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 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

# 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

# Install with development dependencies
pip install -e ".[dev]"

# Run tests
pytest

# Format code
black .
isort .

Usage

🚀 Quick Start

Run the basic deployment example:

python main.py

This will process several example quantum circuits and generate HDH visualizations.

📊 Comprehensive Demo

Run the full demonstration suite:

python main.py --demo-mode --output-dir results

📈 Performance Benchmarking

Run comprehensive performance benchmarks:

python benchmark.py --suite all --repetitions 5

Benchmark specific circuit types:

# 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:

python main.py --qasm-file path/to/circuit.qasm

🎛️ Command Line Interface

Use the interactive CLI:

python cli.py

Examples

Basic Circuit Processing

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

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:

# 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

# 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

# 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:

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:

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:

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

# Run tests
pytest tests/

# Format code
black .
isort .
flake8 .

# Type checking
mypy .

Troubleshooting

Common Issues

Import Error: "No module named 'hdh'"

# Ensure HDH is installed
pip install -e ../HDH

Memory Issues: Large circuits consuming too much memory

# Reduce circuit size or use configuration limits
python main.py --max-qubits 6

Visualization Errors: Matplotlib backend issues

# 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 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
• Documentation: HDH Documentation
• PyPI Package: 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
• 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! 🌟