# Quantum Debugger Documentation

**Version 1.1.0** - Interactive quantum circuit debugger with Quantum Singular Value Transformation (QSVT), Tensor Networks, and Quantum Machine Learning

Welcome to the documentation for Quantum Debugger, a Python library for quantum circuit debugging, performance analysis, quantum machine learning, tensor-network simulation, and modern quantum algorithms.

## What's New in v1.1.0

Theme: **Quantum Singular Value Transformation (QSVT) & Modern Algorithm Primitives** — the unifying framework behind modern quantum algorithms, verified at every level:

- **Quantum Signal Processing (QSP)** (`qsp_unitary`, `qsp_response`, `chebyshev_via_qsp`, `signal_operator`) — one-qubit signal transformation engine producing designable polynomials via interleaved signal and phase rotations. Zero phases recover Chebyshev polynomials $T_d(x)$ to machine precision.
- **Block Encoding & Qubitization** (`block_encode`, `qubitization_walk`, `chebyshev_of_matrix`) — embedding arbitrary non-unitary Hermitian matrices into unitaries ($\langle 0|U|0\rangle = A$), with the qubitization walk generating matrix Chebyshev polynomials $T_d(A) = \langle 0|W^d|0\rangle$.
- **Linear Combination of Unitaries (LCU)** (`lcu_block_encoding`, `lcu_matrix`) — exact PREPARE and SELECT state preparation for Pauli expansions and Hamiltonians ($H = \sum \alpha_k U_k$).
- **Quantum Singular Value Transformation (QSVT)** (`qsvt_transform`, `qsvt_scalar_response`) — the grand unification paradigm, applying polynomial matrix functions eigenvalue-by-eigenvalue ($P(A) = \sum_i P(\lambda_i)|v_i\rangle\langle v_i|$).
- **Quantum Linear Systems via QSVT** (`solve_linear_system_qsvt`, `matrix_inverse_qsvt`) — optimal polynomial inversion solving $A x = b$ without phase estimation, matching exact classical solutions.
- **Matrix Functions & Hamiltonian Simulation** (`matrix_function_chebyshev`, `hamiltonian_simulation_qsvt`, `matrix_exp_qsvt`, `matrix_log_qsvt`, `matrix_sqrt_qsvt`) — smooth matrix functions and real-time unitary evolution $e^{-i H t}$ with geometric Chebyshev convergence.
- **Spectral Filtering & Projectors** (`spectral_projector_qsvt`, `ground_state_projector_qsvt`, `bandpass_filter_qsvt`, `pseudo_inverse_qsvt`) — ground-state projection, sign functions, and regularized inverses.
- **Kernel Polynomial Method (KPM) & Spectral Estimation** (`spectral_moments`, `density_of_states_kpm`, `eigenvalue_count_in_interval`, `trace_of_function`) — Jackson-damped Chebyshev moment estimation of density of states and eigenvalue counting without full diagonalization.
- **Amplitude Amplification as QSVT** (`amplitude_amplification_qsvt`) — generalized Grover search unified under odd Chebyshev polynomials.

See the [QSVT Guide](qsvt_guide) and the [CHANGELOG](https://github.com/Raunakg2005/quantum-debugger/blob/main/CHANGELOG.md).

## What's New in v1.0.0

Scale & tensor networks — **breaking the exponential state-vector wall**:

- **Matrix Product State Simulator (`MPS`)** — `O(n·χ²)` memory instead of `2ⁿ`. Represents large, lightly-entangled quantum systems (e.g. **100-qubit GHZ states**, area-law ground states) with exact single-qubit gates, SVD-truncated two-qubit gates, and long-range connectivity via SWAP networks.
- **Matrix Product Operators (`MPO`)** — compact tensor chains for TFIM (`tfim_mpo`) and Heisenberg (`heisenberg_mpo`) models; evaluate `<ψ|H|ψ>` in `O(n·χ²·D²)` time without dense matrices.
- **TEBD Real-Time Dynamics** (`tebd_tfim`, `tebd_magnetization`) — Trotterized time evolution on the MPS engine with automatic SVD bond truncation.
- **Imaginary-Time DMRG-Style Ground States** (`imaginary_tebd_ground_state`) — cool MPS into true ground states on 24+ qubit chains unreachable by dense diagonalizers.
- **Arbitrary Pauli & Energy Readout** — `MPS.expectation_pauli` and `MPS.energy` evaluate arbitrary Pauli strings and Hamiltonians by tensor contraction.
- **Born-Rule Measurement Sampling** (`MPS.sample`) — sequential conditional sampling with precomputed environments, drawing shots directly from the MPS.
- **Circuit-to-MPS Converter** (`MPS.from_circuit`) — execute `QuantumCircuit` instances directly on the tensor-network engine.

See the [Matrix Product States Guide](mps_guide) and the
[CHANGELOG](https://github.com/Raunakg2005/quantum-debugger/blob/main/CHANGELOG.md) for the full list.

## What's New in v0.9.1

Correctness patch: `DepolarizingNoise.get_kraus_operators()` now implements the same
channel as `apply()` and the class docstring (the Pauli-error convention
`ρ → (1−p)ρ + (p/3)(XρX + YρY + ZρZ)`). The old `√(p/4)` weighting made
`StochasticNoiseSampler`'s sampled depolarizing noise `4/3×` too strong for a given `p`;
trace preservation is unchanged. See the
[CHANGELOG](https://github.com/Raunakg2005/quantum-debugger/blob/main/CHANGELOG.md).

## What's New in v0.9.0

Quantum chemistry, many-body physics & advanced simulation: fermionic systems
(Jordan-Wigner, Fermi-Hubbard, the Kitaev chain), ground/excited-state solvers
(chemistry-via-VQE, imaginary-time cooling, Krylov/Lanczos, adiabatic evolution),
finite-temperature physics (Gibbs states & thermodynamics), quantum dynamics (Trotter
error scaling, Loschmidt echo & DQPTs, OTOC scrambling, entanglement growth), quantum
chaos (level statistics), metrology (spin squeezing, mixed-state QFI), and the modern
measurement/tensor-network toolkit (classical shadows, Schmidt decomposition & the area
law). Open systems, noise, and fault tolerance shipped in v0.8.0.

See the [Algorithms guide](quantum_algorithms_guide) and the
[CHANGELOG](https://github.com/Raunakg2005/quantum-debugger/blob/main/CHANGELOG.md)
for the full list.

## What's New in v0.6.1

- **Faster simulator** - gate application is O(2ⁿ) per gate (was O(4ⁿ)), plus
  optional **GPU state-vector simulation** (`get_statevector(use_gpu=True)`).
- **Genuinely quantum QML** - the quantum kernel/QSVM, hybrid PyTorch/TensorFlow
  layers, Quantum GAN, Quantum RL, and error mitigation (PEC, CDR, QNG, ZNE) are
  now real circuit-based implementations with real gradients (each verified).
- **Robust imports** - a broken optional dependency no longer breaks
  `import quantum_debugger`.

See the [CHANGELOG](https://github.com/Raunakg2005/quantum-debugger/blob/main/CHANGELOG.md) for the full list.

## Features

- 🐛 Step-through debugging
- 🔍 State inspection
- 📊 Circuit profiling
- 🚀 GPU-accelerated state-vector simulation (CuPy)
- 🔗 Qiskit / PennyLane / Cirq integration
- 🧠 Quantum Machine Learning (QNN, AutoML, quantum kernels, hybrid models)
- ⚗️ VQE for molecular chemistry
- 🎯 QAOA for optimization (with a MaxCut solver)
- 📚 Quantum algorithms library (Shor, Grover, QPE, HHL, QEC, Trotter, ...)
- 🧮 Clifford / stabilizer simulator (hundreds of qubits)

## Quick Start

### Installation

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

### Basic 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()
print(debugger.get_current_state())
```

### Quantum Machine Learning

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

# VQE for H2 molecule
H = h2_hamiltonian()
vqe = VQE(H, hardware_efficient_ansatz, num_qubits=2)
result = vqe.run(initial_params)
print(f"Ground state: {result['ground_state_energy']:.6f} Hartree")
```

### GPU-Accelerated Simulation

```python
from quantum_debugger import QuantumCircuit

qc = QuantumCircuit(20)
for q in range(20):
    qc.h(q)
for q in range(19):
    qc.cnot(q, q + 1)

# Run the whole circuit on the GPU (requires CuPy + a CUDA GPU).
# precision='single' (complex64) is dramatically faster on consumer GPUs;
# 'double' (complex128, default) is bit-identical to the CPU result.
state = qc.get_statevector(use_gpu=True, precision="single")
```

## Contents

```{toctree}
:maxdepth: 2
:caption: User Guide

quickstart
examples
```

```{toctree}
:maxdepth: 2
:caption: Algorithms & Advanced QML

algorithms_overview
quantum_algorithms_guide
qsvt_guide
advanced_qml_guide
quantum_rl_guide
advanced_algorithms_guide
stabilizer_guide
density_matrix_guide
qec_noise_guide
mps_guide
```

```{toctree}
:maxdepth: 2
:caption: Quantum Machine Learning

qnn_guide
hybrid_models_guide
quantum_kernels_guide
ansatz_guide
optimizers_guide
dataset_guide
hamiltonians_guide
transfer_learning_guide
```

```{toctree}
:maxdepth: 2
:caption: Error Mitigation & Noise

error_mitigation_guide
zne_guide
hardware_profiles
```

```{toctree}
:maxdepth: 2
:caption: Hardware & Performance

gpu_guide
hardware_backends_guide
circuit_optimization_guide
```

```{toctree}
:maxdepth: 2
:caption: API Reference

modules
api
api_reference
qml_api
```

## Indices and tables

* {ref}`genindex`
* {ref}`modindex`
* {ref}`search`