QuantumDGM 0.1.0
# QuantumDGM: Quantum Circuits for Discrete Graphical Models
License: MIT License
Requires Python: >=3.8
Keywords: quantum computing, graphical models, quantum circuits, sampling, qiskit

# QuantumDGM: Quantum Circuits for Discrete Graphical Models

[![Python 3.8+](https://img.shields.io/badge/python-3.8+-blue.svg)](https://www.python.org/downloads/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Research](https://img.shields.io/badge/Research-Active-green.svg)](docs/RESEARCH_PLAN.md)

A Python library for sampling from discrete graphical models using quantum circuits, based on ["On Quantum Circuits for Discrete Graphical Models"](https://arxiv.org/abs/2206.00398) by Nico Piatkowski and Christa Zoufal (2022).

---

## 🌟 Key Features

- **✅ Unbiased Quantum Sampling**: No burn-in or mixing time required (unlike MCMC)
- **🚀 Variational Training**: Scale to 10-20+ variables via circuit compression
- **🎯 Honest Benchmarking**: Fair quantum vs classical comparisons  
- **⚡ Memory Optimized**: Sparse diagonal Hamiltonian with 1000x+ speedup from caching
- **📊 Production Ready**: Comprehensive tests, documentation, and examples

---

## 📋 Table of Contents

- [Installation](#-installation)
- [Quick Start](#-quick-start)
- [Core Capabilities](#-core-capabilities)
- [Documentation](#-documentation)
- [Examples](#-examples)
- [Research & Development](#-research--development)
- [Citation](#-citation)
- [License](#-license)

---

## 🚀 Installation

### From PyPI (Recommended)

```bash
pip install QuantumDGM
```

### From Source

```bash
# Clone the repository
git clone https://github.com/arulrhikm/QuantumDGM.git
cd QuantumDGM

# Install dependencies
pip install -r requirements.txt

# Install the package in development mode
pip install -e .
```

### Requirements

- Python 3.8+
- numpy >= 1.20.0
- qiskit >= 0.39.0
- qiskit-aer >= 0.11.0
- scipy >= 1.7.0
- matplotlib >= 3.3.0 (optional, for visualization)

---

## ⚡ Quick Start

### Basic Usage (n ≤ 10 variables)

```python
from QuantumDGM import DiscreteGraphicalModel, QCGMSampler

# Create a graphical model (chain structure)
model = DiscreteGraphicalModel(n_vars=4, cliques=[{0,1}, {1,2}, {2,3}])
model.set_random_parameters(low=-2.0, high=-0.5)

# Sample using quantum circuit
sampler = QCGMSampler(model)
samples, success_rate = sampler.sample(n_samples=1000)

print(f"Generated {len(samples)} samples")
print(f"Success rate: {success_rate:.4f}")
```

### Large Models (n > 10 variables) - Variational Training

```python
from QuantumDGM import DiscreteGraphicalModel, ApproximateCircuitBuilder

# Create a larger model
model = DiscreteGraphicalModel(12, [{i, i+1} for i in range(11)])
model.set_random_parameters()

# Train variational circuit
builder = ApproximateCircuitBuilder(depth=3, entanglement='linear')
circuit, params, info = builder.build_circuit_with_target(
    model,
    n_optimization_steps=100,
    verbose=True
)

print(f"Final fidelity: {info['final_fidelity']:.4f}")
```

### Automatic Method Selection

```python
from QuantumDGM import smart_circuit_builder

# Automatically chooses exact (n≤10) or approximate (n>10)
circuit, info = smart_circuit_builder(
    model,
    optimize_approx=True,  # Train if approximate
    verbose=True
)

print(f"Method used: {info['method']}")
```

---

## 🎯 Core Capabilities

### 1. Exact Quantum Circuits (n ≤ 10)

- **Amplitude encoding** for efficient state preparation
- **Unbiased samples** from the first measurement
- **100% success rate** with simplified circuits
- **No burn-in period** (unlike MCMC)

### 2. Variational Compression (n > 10)

- **Fixed-depth parameterized circuits** (hardware-efficient ansatz)
- **Multiple loss functions**: KL divergence, fidelity, L2
- **O(n × depth) parameters** instead of O(2^n)
- **Tunable accuracy** via depth and optimization steps

### 3. Performance Optimizations

- **Sparse Diagonal Hamiltonian**: O(2^n) memory instead of O(4^n)
- **Intelligent Caching**: 1000x+ speedup for repeated calls
- **Smart Circuit Selection**: Auto-switch between exact and approximate

### 4. Honest Research Framework

- **Honest comparisons**: Quantum vs classical with equal information
- **Transparent limitations**: Pedagogical vs full QCGM implementation
- **Reproducible results**: All tests passing, comprehensive documentation

---

## 📚 Documentation

| Document | Description |
|----------|-------------|
| [API Reference](docs/VARIATIONAL_TRAINING.md) | Complete API documentation for variational training |
| [Research Plan](docs/RESEARCH_PLAN.md) | Project vision, roadmap, and collaboration opportunities |
| [Examples Guide](examples/README.md) | Organized demonstrations with research direction |
| [Implementation Summary](examples/tests/IMPLEMENTATION_SUMMARY.md) | Technical details and test results |

### Key Classes

**`DiscreteGraphicalModel`** - Core model representation
```python
model = DiscreteGraphicalModel(n_vars=3, cliques=[{0,1}, {1,2}])
model.set_random_parameters(low=-2.0, high=-0.5, seed=42)
probs = model.compute_probabilities()
```

**`QCGMSampler`** - Quantum sampling interface
```python
sampler = QCGMSampler(model)
samples, rate = sampler.sample(n_samples=1000)
```

**`ApproximateCircuitBuilder`** - Variational circuits for large models
```python
builder = ApproximateCircuitBuilder(depth=3)
circuit, params, info = builder.build_circuit_with_target(model)
```

**Utility Functions**
```python
from QuantumDGM import compute_fidelity, estimate_distribution, generate_state_labels
from QuantumDGM import create_chain_model, create_star_model  # Convenience functions
```

---

## 📖 Examples

### Run Demonstrations

```bash
# Basic functionality demo
python examples/demo_script.py

# Honest quantum vs classical comparison (research demo)
python examples/quantum_vs_classical_demo.py

# Variational training for large models
python examples/variational_training_demo.py

# Interactive tutorial
jupyter notebook examples/demo_notebook.ipynb
```

### Run Tests

```bash
# Variational training validation (7 comprehensive tests)
python examples/tests/test_variational_training.py

# Optimization verification (sparse Hamiltonian, caching, etc.)
python examples/tests/test_optimizations.py
```

**Expected Output:**
```
✅ All tests passing (14/14)
✅ No warnings
✅ Production ready
```

---

## 🔬 Research & Development

### Implementation Status

| Research Objective | Status | Documentation |
|-------------------|--------|---------------|
| **R1:** Low-Ancilla Circuits | ⚠️ Partial (Simplified) | [Research Plan](docs/RESEARCH_PLAN.md#r1) |
| **R2:** Hybrid Inference | ❌ Planned | [Research Plan](docs/RESEARCH_PLAN.md#r2) |
| **R3:** Variational Compression | ✅ **Complete** | [API Docs](docs/VARIATIONAL_TRAINING.md) |
| **R4:** Quantitative Benchmarks | ✅ **Complete** | [Demo](examples/quantum_vs_classical_demo.py) |

**Progress: 50-62% complete** (2/4 objectives fully implemented)

### Performance Metrics

**Training Speed** (standard laptop):
- n=6:  ~10 seconds (50 optimization steps)
- n=10: ~20 seconds
- n=12: ~30 seconds

**Parameter Reduction** (vs exact methods):
- n=10: **17x** fewer parameters
- n=15: **364x** reduction
- n=20: **8,738x** reduction

**Fidelity Achieved**:
- Simple models: F = 0.81-0.99
- Complex models: F = 0.45-0.77

### Roadmap

**Phase 1 - Quick Wins (1 week):**
1. ✅ Variational training (DONE)
2. Readout error mitigation (1-2 hours, high utility)
3. Clique-based entanglement (3-4 hours)

**Phase 2 - Enhanced Capabilities (2 weeks):**
4. Hybrid rejection sampling
5. Zero-noise extrapolation
6. Hardware benchmarking suite

**Phase 3 - Major Research (1+ months):**
7. Full ancilla-based QCGM (foundational contribution)
8. Hamiltonian gadgets
9. Scalability studies

See [docs/RESEARCH_PLAN.md](docs/RESEARCH_PLAN.md) for complete details.

---

## 🎓 Theory Background

### Discrete Graphical Models

A discrete graphical model over binary variables:

```
P_θ(X = x) = (1/Z(θ)) exp(Σ_{C∈𝒞} Σ_{y∈𝒳_C} θ_{C,y} φ_{C,y}(x))
```

where:
- `𝒞` = maximal cliques
- `θ` = canonical parameters
- `φ` = sufficient statistics
- `Z(θ)` = partition function

### Quantum Circuit Approach

1. **Hamiltonian Construction**: Encode model as diagonal matrix H_θ
2. **State Preparation**: Create quantum state |ψ⟩ with |⟨x|ψ⟩|² = P_θ(x)
3. **Measurement**: Each measurement yields an unbiased sample

### Key Advantages

- **No burn-in**: Quantum samples are immediately valid
- **Independence**: Each measurement is independent
- **Exact distribution**: Perfect for statistical analysis

---

## 📊 Benchmarking & Validation

### Honest Comparison Framework

Our [quantum vs classical demo](examples/quantum_vs_classical_demo.py) provides:

1. **Equal-Information Comparison**: When all methods know P(x), quantum ≈ classical
2. **Quantum Properties**: Independence, no burn-in, high effective sample size
3. **Gibbs Comparison Explained**: Why comparing to Gibbs is misleading
4. **When Quantum Matters**: Real use cases where properties help

**Key Insight:** The simplified amplitude encoding doesn't give computational advantage,
but quantum sampling **properties** (independence, no burn-in) are valuable for:
- Monte Carlo integration
- Real-time applications
- Statistical analysis
- Parallel sampling

---

## 📝 Citation

If you use this library in your research, please cite:

```bibtex
@article{piatkowski2022quantum,
  title={On Quantum Circuits for Discrete Graphical Models},
  author={Piatkowski, Nico and Zoufal, Christa},
  journal={arXiv preprint arXiv:2206.00398},
  year={2022}
}

@software{quantumdgm2025,
  title={QuantumDGM: Quantum Circuits for Discrete Graphical Models},
  author={Arul Rhik Mazumder, Bryan Zhang},
  year={2025},
  url={https://github.com/arulrhikm/QuantumDGM},
  note={Includes variational compression and honest benchmarking}
}
```

---

## 🤝 Contributing

Contributions are welcome! See our [research plan](docs/RESEARCH_PLAN.md) for priority areas:

**High-Impact Additions:**
- Readout error mitigation (easy, 1-2 hours)
- Hybrid rejection sampling (medium, 4-6 hours)
- Full ancilla-based QCGM (hard, 2-4 weeks, major contribution)

**Development Setup:**
```bash
git clone https://github.com/arulrhikm/QuantumDGM.git
cd QuantumDGM
pip install -e ".[dev]"

# Run tests
python examples/tests/test_variational_training.py
python examples/tests/test_optimizations.py
```

---

## 📄 License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

---

## 🙏 Acknowledgments

- **Original Research**: Piatkowski, N., & Zoufal, C. (2022). "On Quantum Circuits for Discrete Graphical Models"
- **Quantum Framework**: Built with Qiskit and Qiskit Aer
- **Optimization Methods**: Inspired by VQE and hardware-efficient ansatz designs

---

## 📞 Contact

- **Issues**: [GitHub Issues](https://github.com/arulrhikm/QuantumDGM/issues)
- **Email**: arulm@andrew.cmu.edu

---

**Status:** ✅ Production Ready (R3 & R4 complete, R1 & R2 planned)  
**Version:** 0.1.0  
**Last Updated:** December 2025