# 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! 🌟*