Variational Quantum Error Correction Decoder

This repository provides a production-grade Python implementation of a Variational QEC Decoder, focusing on adaptive noise-aware decoding strategies. It integrates classical machine learning (CNNs for noise classification) with parameterized quantum circuits (ansätze) via PennyLane and PyTorch to dynamically adapt to varying physical noise channels.

Project Description

Quantum error correction (QEC) is essential for fault-tolerant quantum computing. Traditional decoders like Minimum Weight Perfect Matching (MWPM) are highly effective but often assume a static, well-characterized noise model (e.g., pure depolarizing noise).

This project explores a novel hybrid approach:

1. Syndrome History Analysis: A classical CNN analyzes the history of syndrome measurements to classify the dominant noise channel (depolarizing, bit-flip, phase-flip, or combined) on the fly.
2. Adaptive Variational Decoding: Once the noise type is identified, the system dynamically swaps to a noise-specific variational ansatz designed to correct that specific error profile optimally.
3. Quantum-Aware Training: The ansätze are trained using the parameter-shift rule directly on the abstract quantum device via PennyLane, using cross-entropy against logical error bounds.

Novel Contributions

• noise_classifier.py: A 1D-CNN tracking syndrome signatures over time.
• adaptive_selector.py: A dynamic decoder bank that switches the underlying decoding strategy mid-operation based on classical heuristics.

Installation

We recommend using a conda or virtual environment for Python 3.10+.

# Clone the repository
git clone https://github.com/variational-qec/variational_qec_decoder.git
cd variational_qec_decoder

# Create and activate environment 
python -m venv vqec_env
source vqec_env/bin/activate

# Install requirements
pip install -r requirements.txt
pip install -e .

*Note: The MWPM baseline requires pymatching>=2.0 and fast stabilizer simulation requires stim>=1.12.*

Usage and Experiments

All experiments are located in the experiments/ directory. Outputs and models are saved to results/data/, results/figures/, and results/models/.

1. Classical Baselines

Train and evaluate MWPM and Lookup Table decoders.

python experiments/run_baseline.py --d 3 --shots 1000 --noise depolarizing

2. Variational Decoder

Train a fixed variational decoder using hardware-efficient or symmetry-preserving ansätze.

python experiments/run_variational.py --d 3 --ansatz hardware_efficient --epochs 50

3. Adaptive Noise-Aware Decoding (Novel Experiment)

Run the full adaptive pipeline in a dynamically changing noise environment. This experiment trains the CNN classifier, initializes the decoder bank, and evaluates logical error rates across fluctuating noise contexts.

python experiments/run_adaptive.py

4. Continuous Noise Estimation

Train a regression-based CNN to estimate continuous noise parameters $(p_X, p_Z, p_{depol})$ and evaluate soft-weight decoder interpolation.

python experiments/run_continuous.py --d 3

5. Online Learning and Adaptation

Evaluate real-time fine-tuning of variational decoders under non-stationary noise (drift, sudden switches, etc.) and calculate adaptation lag.

python experiments/run_online.py --d 3

6. Plotting Results

Generate figures combining data from all completed runs.

python experiments/plot_results.py

7. Advanced Research Features

Run the full suite of novel research contributions (BP Preprocessing, Noise Fingerprinting, Block Decoding, Confidence Calibration, and Syndrome Compression).

python experiments/run_all_features.py

8. High-Precision "Gold Standard" Campaign

Run the full threshold scaling campaign for $d=3, 4$ and baselines up to $d=11$ with high statistics (10,000 shots, 20 $p$-values). Memory-optimized for 6GB RAM.

python experiments/run_large_scale.py

Advanced Research Features

This repository implements several cutting-edge features for next-generation QEC:

• BP Preprocessing: Hybrid Belief Propagation-Variational architecture for soft-prior generation.
• Hardware Fingerprinting: Real-time spatial/temporal noise characterization and personalized initialization.
• Multi-Qubit Block Decoding: Joint inference over logical qubits to exploit shared syndrome correlations.
• Confidence Calibration: Temperature scaling for reliable decoder reliability scores and MWPM fallback.
• Syndrome Compression: Autoencoder-based syndrome reduction for resource-efficient decoding of larger code distances.

Memory Optimization

The codebase is optimized for low-memory environments (6GB RAM):

• Adjoint Differentiation: Memory-efficient gradient calculation via lightning.qubit.
• Batch Size Control: Configurable training batches to manage statevector overhead.
• Thread Management: Restricted OpenMP threading (OMP_NUM_THREADS=1) for stability in high-distance simulations.

Citation

If you use this codebase in your research, please cite the framework:

@misc{VQEC2026,
  author = {Kaivalya Singh},
  title = {Adaptive Noise-Aware Variational Decoding for Quantum Error Correction},
  year = {2026},
  publisher = {GitHub},
  journal = {GitHub repository},
  howpublished = {\url{https://github.com/kaivalya-cyber/variational-qec-decoder}}
}