422 líneas
10 KiB
Markdown
422 líneas
10 KiB
Markdown
# 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! 🌟* |