422
README.md
Archivo normal
422
README.md
Archivo normal
@@ -0,0 +1,422 @@
|
||||
# HDH Deployment Example 🚀
|
||||
|
||||
A comprehensive deployment example showcasing the power of the **HDH (Hybrid Dependency Hypergraph)** library for quantum computation analysis and visualization.
|
||||
|
||||
**Special thanks to [Maria Gragera Garces](https://github.com/grageragarces) for her excellent work on the HDH library! 🎉**
|
||||
|
||||
## Overview
|
||||
|
||||
This deployment example demonstrates real-world usage of the HDH library, providing:
|
||||
|
||||
- **Comprehensive circuit processing** - Convert quantum circuits to HDH format
|
||||
- **Performance benchmarking** - Analyze HDH performance across different circuit types
|
||||
- **Visualization capabilities** - Generate HDH visualizations and analysis plots
|
||||
- **Scalability testing** - Test HDH with circuits of varying complexity
|
||||
- **Production-ready deployment** - Docker support, logging, error handling
|
||||
- **CLI tools** - Command-line interface for easy interaction
|
||||
|
||||
## Features
|
||||
|
||||
### ✨ Core Capabilities
|
||||
|
||||
- **Multi-framework support**: Qiskit, Braket, Cirq, PennyLane circuit conversion
|
||||
- **QASM file processing**: Import and analyze OpenQASM 2.0 files
|
||||
- **Advanced analysis**: Circuit partitioning, dependency analysis, metrics computation
|
||||
- **Rich visualizations**: HDH graphs, performance plots, scalability analysis
|
||||
- **Benchmarking suite**: Comprehensive performance evaluation tools
|
||||
|
||||
### 🔧 Production Features
|
||||
|
||||
- **Error handling**: Robust error handling and recovery
|
||||
- **Logging**: Comprehensive logging with configurable levels
|
||||
- **Configuration**: YAML-based configuration management
|
||||
- **Docker support**: Containerized deployment options
|
||||
- **CLI interface**: User-friendly command-line tools
|
||||
- **Performance monitoring**: Memory usage and execution time tracking
|
||||
|
||||
## Installation
|
||||
|
||||
### Prerequisites
|
||||
|
||||
- Python 3.10 or higher
|
||||
- HDH library (from the parent HDH directory)
|
||||
- Dependencies listed in `requirements.txt`
|
||||
|
||||
### Quick Setup
|
||||
|
||||
```bash
|
||||
# Clone and navigate to the examples directory
|
||||
cd examples
|
||||
|
||||
# Create virtual environment (recommended)
|
||||
python -m venv hdh-env
|
||||
source hdh-env/bin/activate # On Windows: hdh-env\Scripts\activate
|
||||
|
||||
# Install dependencies
|
||||
pip install -r requirements.txt
|
||||
|
||||
# Install HDH library in development mode
|
||||
pip install -e ../HDH
|
||||
|
||||
# Verify installation
|
||||
python main.py --help
|
||||
```
|
||||
|
||||
### Development Setup
|
||||
|
||||
```bash
|
||||
# Install with development dependencies
|
||||
pip install -e ".[dev]"
|
||||
|
||||
# Run tests
|
||||
pytest
|
||||
|
||||
# Format code
|
||||
black .
|
||||
isort .
|
||||
```
|
||||
|
||||
## Usage
|
||||
|
||||
### 🚀 Quick Start
|
||||
|
||||
Run the basic deployment example:
|
||||
|
||||
```bash
|
||||
python main.py
|
||||
```
|
||||
|
||||
This will process several example quantum circuits and generate HDH visualizations.
|
||||
|
||||
### 📊 Comprehensive Demo
|
||||
|
||||
Run the full demonstration suite:
|
||||
|
||||
```bash
|
||||
python main.py --demo-mode --output-dir results
|
||||
```
|
||||
|
||||
### 📈 Performance Benchmarking
|
||||
|
||||
Run comprehensive performance benchmarks:
|
||||
|
||||
```bash
|
||||
python benchmark.py --suite all --repetitions 5
|
||||
```
|
||||
|
||||
Benchmark specific circuit types:
|
||||
|
||||
```bash
|
||||
# Test scalability
|
||||
python benchmark.py --suite scalability --max-qubits 8
|
||||
|
||||
# Test algorithms
|
||||
python benchmark.py --suite algorithms
|
||||
|
||||
# Test random circuits
|
||||
python benchmark.py --suite random
|
||||
```
|
||||
|
||||
### 🔍 Process Specific Files
|
||||
|
||||
Process a specific QASM file:
|
||||
|
||||
```bash
|
||||
python main.py --qasm-file path/to/circuit.qasm
|
||||
```
|
||||
|
||||
### 🎛️ Command Line Interface
|
||||
|
||||
Use the interactive CLI:
|
||||
|
||||
```bash
|
||||
python cli.py
|
||||
```
|
||||
|
||||
## Examples
|
||||
|
||||
### Basic Circuit Processing
|
||||
|
||||
```python
|
||||
from main import HDHDeploymentManager
|
||||
from circuit_examples import HDHCircuitLibrary
|
||||
|
||||
# Initialize deployment manager
|
||||
manager = HDHDeploymentManager(output_dir="my_results")
|
||||
|
||||
# Create example circuit
|
||||
library = HDHCircuitLibrary()
|
||||
bell_circuit = library.bell_state()
|
||||
|
||||
# Process circuit
|
||||
result = manager.process_circuit(bell_circuit, save_plots=True)
|
||||
print(f"Processed {result['circuit_name']}: {result['hdh_stats']['nodes']} nodes")
|
||||
```
|
||||
|
||||
### Benchmarking Suite
|
||||
|
||||
```python
|
||||
from benchmark import HDHBenchmarkSuite
|
||||
|
||||
# Initialize benchmark suite
|
||||
benchmark = HDHBenchmarkSuite(repetitions=3)
|
||||
|
||||
# Run comprehensive benchmarks
|
||||
report = benchmark.run_full_benchmark()
|
||||
print(f"Benchmarked {report['benchmark_summary']['total_circuits']} circuits")
|
||||
```
|
||||
|
||||
## Circuit Library
|
||||
|
||||
The deployment includes a comprehensive quantum circuit library:
|
||||
|
||||
### Basic Quantum States
|
||||
- **Bell States**: All four Bell state variants
|
||||
- **GHZ States**: Multi-qubit entangled states
|
||||
- **W States**: Symmetric superposition states
|
||||
|
||||
### Quantum Algorithms
|
||||
- **Quantum Fourier Transform (QFT)**: Efficient Fourier transform implementation
|
||||
- **Grover's Algorithm**: Quantum search algorithm
|
||||
- **Deutsch-Jozsa Algorithm**: Quantum function evaluation
|
||||
- **Shor's Algorithm**: Period finding (simplified)
|
||||
|
||||
### Quantum Protocols
|
||||
- **Quantum Teleportation**: State transfer protocol
|
||||
- **Quantum Error Correction**: 3-qubit bit-flip code
|
||||
|
||||
### Variational Algorithms
|
||||
- **VQE (Variational Quantum Eigensolver)**: Quantum optimization
|
||||
- **QAOA (Quantum Approximate Optimization Algorithm)**: Combinatorial optimization
|
||||
|
||||
### Random Circuits
|
||||
- **Parameterized random circuits**: For benchmarking and testing
|
||||
|
||||
## Configuration
|
||||
|
||||
Customize the deployment using `config.yaml`:
|
||||
|
||||
```yaml
|
||||
# Logging configuration
|
||||
logging:
|
||||
level: INFO
|
||||
file: "hdh_deployment.log"
|
||||
|
||||
# Output settings
|
||||
output:
|
||||
directory: "hdh_results"
|
||||
save_plots: true
|
||||
plot_dpi: 300
|
||||
|
||||
# Circuit processing
|
||||
circuits:
|
||||
max_qubits: 10
|
||||
default_partitions: 3
|
||||
enable_visualization: true
|
||||
|
||||
# Performance settings
|
||||
performance:
|
||||
timeout_seconds: 300
|
||||
max_memory_gb: 8
|
||||
```
|
||||
|
||||
## Docker Deployment
|
||||
|
||||
### Build and Run
|
||||
|
||||
```bash
|
||||
# Build Docker image
|
||||
docker build -t hdh-deployment .
|
||||
|
||||
# Run deployment
|
||||
docker run -v $(pwd)/results:/app/results hdh-deployment
|
||||
|
||||
# Run with custom configuration
|
||||
docker run -v $(pwd)/config.yaml:/app/config.yaml hdh-deployment
|
||||
```
|
||||
|
||||
### Docker Compose
|
||||
|
||||
```bash
|
||||
# Start complete deployment stack
|
||||
docker-compose up
|
||||
|
||||
# Run benchmarks
|
||||
docker-compose run benchmark python benchmark.py --suite all
|
||||
```
|
||||
|
||||
## API Reference
|
||||
|
||||
### HDHDeploymentManager
|
||||
|
||||
Main deployment management class:
|
||||
|
||||
```python
|
||||
manager = HDHDeploymentManager(
|
||||
output_dir="results", # Output directory
|
||||
log_level="INFO" # Logging level
|
||||
)
|
||||
|
||||
# Process quantum circuit
|
||||
result = manager.process_circuit(quantum_circuit)
|
||||
|
||||
# Process QASM file
|
||||
result = manager.process_qasm_file("circuit.qasm")
|
||||
|
||||
# Run comprehensive demo
|
||||
summary = manager.run_comprehensive_demo()
|
||||
```
|
||||
|
||||
### HDHBenchmarkSuite
|
||||
|
||||
Performance benchmarking suite:
|
||||
|
||||
```python
|
||||
benchmark = HDHBenchmarkSuite(
|
||||
output_dir="benchmark_results",
|
||||
repetitions=3
|
||||
)
|
||||
|
||||
# Run specific benchmarks
|
||||
results = benchmark.run_scalability_benchmark()
|
||||
results = benchmark.run_algorithm_benchmark()
|
||||
|
||||
# Generate performance plots
|
||||
benchmark.generate_performance_plots(results)
|
||||
```
|
||||
|
||||
### HDHCircuitLibrary
|
||||
|
||||
Quantum circuit examples library:
|
||||
|
||||
```python
|
||||
library = HDHCircuitLibrary()
|
||||
|
||||
# Get individual circuits
|
||||
bell = library.bell_state()
|
||||
ghz = library.ghz_state(4)
|
||||
qft = library.qft_circuit(3)
|
||||
|
||||
# Get all examples
|
||||
examples = library.get_all_examples()
|
||||
|
||||
# Get benchmark suite
|
||||
benchmark_circuits = library.get_benchmark_suite()
|
||||
```
|
||||
|
||||
## Results and Output
|
||||
|
||||
The deployment generates comprehensive results:
|
||||
|
||||
### Directory Structure
|
||||
```
|
||||
hdh_results/
|
||||
├── hdh_deployment.log # Detailed logging
|
||||
├── deployment_results.json # Processing results
|
||||
├── Bell_State_hdh.png # Circuit visualizations
|
||||
├── GHZ-3_hdh.png
|
||||
├── QFT-3_hdh.png
|
||||
└── ...
|
||||
|
||||
benchmark_results/
|
||||
├── benchmark.log # Benchmark logging
|
||||
├── benchmark_report.json # Detailed benchmark data
|
||||
├── scaling_performance.png # Performance scaling plots
|
||||
├── algorithm_comparison.png # Algorithm comparison
|
||||
├── memory_analysis.png # Memory usage analysis
|
||||
└── performance_complexity.png # Complexity analysis
|
||||
```
|
||||
|
||||
### Performance Metrics
|
||||
|
||||
The deployment tracks comprehensive performance metrics:
|
||||
|
||||
- **Conversion time**: Time to convert circuits to HDH
|
||||
- **Memory usage**: Peak memory consumption
|
||||
- **HDH statistics**: Nodes, edges, timesteps
|
||||
- **Partitioning metrics**: Cut cost, parallelism analysis
|
||||
- **Scalability data**: Performance vs circuit size
|
||||
|
||||
## Contributing
|
||||
|
||||
We welcome contributions! Here's how you can help:
|
||||
|
||||
1. **Report Issues**: Found a bug? Report it!
|
||||
2. **Add Examples**: Contribute new quantum circuit examples
|
||||
3. **Improve Performance**: Optimize benchmarking and analysis
|
||||
4. **Documentation**: Help improve documentation
|
||||
5. **Testing**: Add more comprehensive tests
|
||||
|
||||
### Development Guidelines
|
||||
|
||||
```bash
|
||||
# Run tests
|
||||
pytest tests/
|
||||
|
||||
# Format code
|
||||
black .
|
||||
isort .
|
||||
flake8 .
|
||||
|
||||
# Type checking
|
||||
mypy .
|
||||
```
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Common Issues
|
||||
|
||||
**Import Error**: "No module named 'hdh'"
|
||||
```bash
|
||||
# Ensure HDH is installed
|
||||
pip install -e ../HDH
|
||||
```
|
||||
|
||||
**Memory Issues**: Large circuits consuming too much memory
|
||||
```bash
|
||||
# Reduce circuit size or use configuration limits
|
||||
python main.py --max-qubits 6
|
||||
```
|
||||
|
||||
**Visualization Errors**: Matplotlib backend issues
|
||||
```bash
|
||||
# Set backend explicitly
|
||||
export MPLBACKEND=Agg
|
||||
```
|
||||
|
||||
### Performance Tips
|
||||
|
||||
1. **Limit circuit size**: Start with smaller circuits
|
||||
2. **Use configuration**: Customize limits in config.yaml
|
||||
3. **Monitor memory**: Use the memory profiling features
|
||||
4. **Batch processing**: Process circuits in batches for large datasets
|
||||
|
||||
## Acknowledgments
|
||||
|
||||
This deployment example was created to showcase the capabilities of the HDH library.
|
||||
|
||||
**Special recognition goes to [Maria Gragera Garces](https://github.com/grageragarces) for her outstanding work developing the HDH library. Her innovative approach to quantum computation analysis through hybrid dependency hypergraphs has made this comprehensive deployment example possible.** 🙏
|
||||
|
||||
### References
|
||||
|
||||
- **HDH Library**: [GitHub Repository](https://github.com/grageragarces/hdh)
|
||||
- **Documentation**: [HDH Documentation](https://grageragarces.github.io/HDH/)
|
||||
- **PyPI Package**: [hdh](https://pypi.org/project/hdh/)
|
||||
|
||||
## License
|
||||
|
||||
This deployment example is provided under the MIT License, consistent with the HDH library.
|
||||
|
||||
## Support
|
||||
|
||||
For questions and support:
|
||||
|
||||
- **HDH Library Issues**: [GitHub Issues](https://github.com/grageragarces/hdh/issues)
|
||||
- **Deployment Example**: Create an issue in this repository
|
||||
- **General Questions**: Check the HDH documentation
|
||||
|
||||
---
|
||||
|
||||
*Built with ❤️ for the quantum computing community*
|
||||
|
||||
*Thank you Maria for making quantum computation analysis more accessible through HDH! 🌟*
|
||||
Referencia en una nueva incidencia
Block a user