Metadata-Version: 2.4
Name: quantum-debugger
Version: 0.4.0
Summary: Interactive quantum circuit debugger and Quantum Machine Learning library with VQE, QAOA, and parameterized gates
Home-page: https://github.com/Raunakg2005/quantum-debugger
Author: warlord9004
Author-email: your.email@example.com
Project-URL: Bug Reports, https://github.com/Raunakg2005/quantum-debugger/issues
Project-URL: Source, https://github.com/Raunakg2005/quantum-debugger
Project-URL: Documentation, https://github.com/Raunakg2005/quantum-debugger#readme
Keywords: quantum computing debugging profiling quantum-circuit visualization qml vqe qaoa machine-learning
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: Intended Audience :: Developers
Classifier: Topic :: Scientific/Engineering :: Physics
Classifier: Topic :: Software Development :: Debuggers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=1.20.0
Requires-Dist: scipy>=1.7.0
Requires-Dist: matplotlib>=3.5.0
Provides-Extra: qiskit
Requires-Dist: qiskit>=2.0.0; extra == "qiskit"
Provides-Extra: cirq
Requires-Dist: cirq>=1.0.0; extra == "cirq"
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: pytest-cov>=3.0.0; extra == "dev"
Requires-Dist: black>=22.0.0; extra == "dev"
Requires-Dist: flake8>=4.0.0; extra == "dev"
Requires-Dist: mypy>=0.990; extra == "dev"
Dynamic: author
Dynamic: author-email
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: keywords
Dynamic: license-file
Dynamic: project-url
Dynamic: provides-extra
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

# Quantum Debugger

**Interactive debugger, profiler, and quantum machine learning library for quantum circuits**

[![PyPI version](https://badge.fury.io/py/quantum-debugger.svg)](https://pypi.org/project/quantum-debugger/)
[![Tests](https://img.shields.io/badge/tests-316%2F316%20passing-brightgreen)]()
[![Python](https://img.shields.io/badge/python-3.9%2B-blue)]()
[![License](https://img.shields.io/badge/license-MIT-green)]()

A powerful Python library for quantum circuit debugging, state inspection, performance analysis, and **quantum machine learning**. Now with VQE, QAOA, and parameterized quantum circuits!

## ✨ What's New in v0.4.0

**Quantum Machine Learning Module** 🚀

```python
from quantum_debugger.qml import VQE, h2_hamiltonian, hardware_efficient_ansatz

# Find H2 molecule ground state
H = h2_hamiltonian()
vqe = VQE(H, hardware_efficient_ansatz, num_qubits=2)
result = vqe.run(initial_params)
print(f"Ground state energy: {result['ground_state_energy']:.6f} Hartree")
# Accuracy: < 1% error from exact solution
```

**New Features:**
- ✅ **Parameterized Gates** (RX, RY, RZ with trainable parameters)
- ✅ **VQE** (Variational Quantum Eigensolver for chemistry)
- ✅ **QAOA** (Quantum optimization for MaxCut problems)
- ✅ **Training Framework** (Adam, SGD, SPSA, RMSprop optimizers)
- ✅ **Gradient Computation** (Parameter shift rule, finite differences)
- ✅ **316 comprehensive tests** (100% passing)

See full [QML Documentation](#quantum-machine-learning-v040) below.

## Features

### Core Debugging
- **Step-through Debugging** - Execute circuits gate-by-gate with breakpoints
- **State Inspection** - Analyze quantum states at any point
- **Circuit Profiling** - Depth analysis, gate statistics, optimization suggestions  
- **Visualization** - State vectors, Bloch spheres, and more
- **Noise Simulation** - Realistic hardware noise models
- **Qiskit Integration** - Import/export circuits from Qiskit

### Quantum Machine Learning (NEW v0.4.0)
- **Parameterized Circuits** - Trainable quantum gates
- **VQE** - Molecular ground state finding
- **QAOA** - Combinatorial optimization
- **Training & Optimization** - 4 classical optimizers
- **Ansatz Library** - 4 pre-built quantum circuit templates

## Quick Start

### Installation

```bash
pip install quantum-debugger
```

### Basic Circuit Debugging

```python
from quantum_debugger import QuantumCircuit, QuantumDebugger

# Create a Bell state
qc = QuantumCircuit(2)
qc.h(0)
qc.cnot(0, 1)

# Debug step-by-step
debugger = QuantumDebugger(qc)
debugger.step()  # Execute first gate
print(debugger.get_current_state())
debugger.step()  # Execute second gate
print(debugger.get_current_state())
```

### Quantum Machine Learning

```python
from quantum_debugger.qml import RXGate, RYGate, RZGate

# Parameterized quantum gate
rx = RXGate(target=0, parameter=0.5, trainable=True)
matrix = rx.matrix()  # 2x2 unitary matrix

# Update parameter during training
rx.parameter = 0.7
new_matrix = rx.matrix()  # Automatically cached for performance
```

## Quantum Machine Learning (v0.4.0)

### 1. Parameterized Gates

**Rotation gates with trainable parameters:**

```python
from quantum_debugger.qml import RXGate, RYGate, RZGate

# Three rotation gate types
rx = RXGate(0, theta=0.5, trainable=True)   # Rotation about X-axis
ry = RYGate(0, theta=0.3, trainable=True)   # Rotation about Y-axis  
rz = RZGate(0, theta=0.7, trainable=True)   # Rotation about Z-axis

# Get unitary matrix
U = rx.matrix()  # 2x2 complex array
```

**Features:**
- Matrix caching (100-1000x speedup)
- Thread-safe operations
- Parameter validation
- Gradient tracking

### 2. VQE (Variational Quantum Eigensolver)

**Find ground state energy of molecules:**

```python
from quantum_debugger.qml import VQE, h2_hamiltonian, hardware_efficient_ansatz
import numpy as np

# Setup H2 molecule Hamiltonian
H = h2_hamiltonian()  # 2 qubits, chemistry-accurate

# Create VQE instance
vqe = VQE(
    hamiltonian=H,
    ansatz_builder=hardware_efficient_ansatz,
    num_qubits=2,
    optimizer='COBYLA',
    max_iterations=100
)

# Run optimization
initial_params = np.random.rand(2)
result = vqe.run(initial_params)

print(f"Ground state energy: {result['ground_state_energy']:.6f} Hartree")
print(f"Optimal parameters: {result['optimal_params']}")
print(f"Iterations: {result['iterations']}")

# Compare with exact solution
exact = vqe.exact_ground_state()
error = abs(result['ground_state_energy'] - exact)
print(f"Error from exact: {error:.6f} Hartree")
```

**Available Ansätze:**
- `hardware_efficient_ansatz` - RY rotations with CNOTs
- `real_amplitudes_ansatz` - Real-valued states
- `ucc_singlet_ansatz` - Chemistry-inspired
- `alternating_layered_ansatz` - RX and RY layers

### 3. QAOA (Quantum Approximate Optimization)

**Solve MaxCut on graphs:**

```python
from quantum_debugger.qml import QAOA

# Define graph (list of edges)
graph = [(0, 1), (1, 2), (2, 3), (3, 0)]  # Square graph

# Create QAOA instance
qaoa = QAOA(
    graph=graph,
    p=2,                    # 2 QAOA layers
    optimizer='COBYLA',
    max_iterations=50
)

# Run optimization
result = qaoa.run()

print(f"Best cut value: {result['best_value']:.2f}")
print(f"Optimal parameters: {result['optimal_params']}")
print(f"Approximation ratio: {result['best_value']/4:.1%}")  # 4 is optimal for square
```

**Supported graph topologies:**
- Complete graphs, Cycles, Stars
- Line graphs, Custom graphs
- Disconnected graphs

### 4. Training & Optimization

**Classical optimizers for quantum circuits:**

```python
from quantum_debugger.qml.optimizers import Adam, GradientDescent, SPSA
from quantum_debugger.qml.utils.gradients import parameter_shift_gradient

# Adam optimizer
optimizer = Adam(learning_rate=0.01)

# Training loop
params = np.array([0.5, 0.3])
for epoch in range(100):
    # Compute gradients
    grad = parameter_shift_gradient(circuit_builder, cost_function, params, 0)
    
    # Update parameters
    params = optimizer.step(params, grad)
```

**Available optimizers:**
- **Adam** - Adaptive learning rates (recommended)
- **SGD** - Stochastic gradient descent
- **SPSA** - Gradient-free, noise-tolerant
- **RMSprop** - Adaptive learning

**Gradient methods:**
- **Parameter shift rule** - Exact for quantum gates
- **Finite differences** - General purpose

### 5. Training Framework

**Complete training workflow:**

```python
from quantum_debugger.qml.training import QuantumTrainer

def circuit_builder(params):
    gates = []
    gates.append(RYGate(0, params[0]))
    gates.append(RXGate(1, params[1]))
    return gates

def cost_function(circuit):
    # Your cost calculation
    return energy

# Create trainer
trainer = QuantumTrainer(
    circuit_builder=circuit_builder,
    cost_function=cost_function,
    optimizer='adam',
    learning_rate=0.01,
    gradient_method='parameter_shift'
)

# Train
result = trainer.train(
    initial_params=np.random.rand(2),
    epochs=100,
    verbose=True
)

print(f"Final loss: {result['final_loss']:.6f}")
print(f"Training history: {len(result['history'])} epochs")
```

## 📚 Core Features

### Supported Gates

**Single-qubit:** H, X, Y, Z, S, T, RX, RY, RZ, PHASE  
**Two-qubit:** CNOT, CZ, CP (controlled-phase), SWAP  
**Three-qubit:** Toffoli (CCNOT)

### Debugging Features

- ✅ Forward/backward stepping
- ✅ Breakpoints (gate-based & conditional)
- ✅ Execution history tracking
- ✅ State comparison
- ✅ Circuit profiling

### Noise Simulation (v0.3.0)

```python
from quantum_debugger import QuantumCircuit
from quantum_debugger.noise import IBM_PERTH_2025

# Simulate on IBM hardware
qc = QuantumCircuit(2, noise_model=IBM_PERTH_2025.noise_model)
qc.h(0).cnot(0, 1)
results = qc.run(shots=1000)
print(f"Fidelity: {results['fidelity']:.4f}")
```

**Available noise models:**
- Depolarizing, Amplitude/Phase Damping, Thermal Relaxation
- Hardware profiles: IBM, Google, IonQ, Rigetti

## 🧪 Testing & Quality

- **316/316 tests passing** (100%)
- Core logic, integration, regression, property-based tests
- Validated up to **12 qubits** (4,096-D state space)
- Numerical precision < 1e-10
- Cross-platform (Windows/Linux/macOS)
- Python 3.9-3.12 compatible

See [test files](.) for details.

## 🔧 Requirements

- Python 3.9+
- NumPy >= 1.20.0
- SciPy >= 1.7.0
- Matplotlib >= 3.5.0 (optional, for visualization)
- Qiskit >= 2.0 (optional, for integration)

## 📖 Documentation

- **Tutorials:**
  - [Parameterized Gates Tutorial](tutorials/parameterized_gates_tutorial.md)
  - [VQE Preparation Guide](tutorials/vqe_preparation.md)
  - [QAOA Tutorial](tutorials/qaoa_tutorial.md)

- **Examples:**
  - [VQE H2 Molecule](examples/vqe_h2_example.py)
  - [QAOA MaxCut](examples/qaoa_maxcut_example.py)
  - [Performance Benchmarks](examples/benchmarks.py)

## 📈 Version History

**v0.4.0** (December 2024) - Quantum Machine Learning
- ✅ Parameterized gates (RX, RY, RZ)
- ✅ VQE algorithm for molecular chemistry
- ✅ QAOA for combinatorial optimization
- ✅ Training framework with 4 optimizers
- ✅ Gradient computation (parameter shift, finite differences)
- ✅ 316 comprehensive tests
- ✅ 3 tutorials, 4 example scripts

**v0.3.0** (December 2024) - Noise Simulation
- Realistic noise models (4 types)
- Hardware profiles (IBM, Google, IonQ, Rigetti)
- Qiskit Aer validation
- 89 new tests

**v0.2.0** - Qiskit Integration
- Bidirectional circuit conversion
- CP gate support
- 12-qubit support

**v0.1.0** - Foundation
- Core quantum simulation
- Basic debugging features

## 🗺️ Roadmap

**v0.5.0** (Q1 2025) - Advanced QML
- [ ] Quantum Neural Networks (QNN)
- [ ] More molecular Hamiltonians (LiH, H2O)
- [ ] Error mitigation integration
- [ ] GPU acceleration

**v1.0.0** (Future)
- [ ] Real hardware backend support
- [ ] Advanced visualization dashboards
- [ ] Quantum error correction tools
- [ ] Production deployment tools

## 🤝 Contributing

Contributions welcome! Please ensure tests pass:

```bash
pytest test_*.py -v
```

## 📄 License

MIT License - see [LICENSE](LICENSE) file.

---

**PyPI:** https://pypi.org/project/quantum-debugger/  
**Author:** warlord9004  
**Version:** 0.4.0  
**Python:** 3.9+
