Adaptive Surface-Code Decoding Under Non-Stationary Noise

Code, data, and manuscript for the paper

Hongyi Li (2026), Calibration is Sufficient: A Mechanistic Boundary for Adaptive Surface-Code Decoding. Submission to IEEE Transactions on Quantum Engineering.

Central claim (one paragraph). Adaptive decoding under non-stationary noise can improve logical performance for two distinct reasons: better calibration of the detector error model (DEM), and better decoding once the noise is correctly calibrated. We prove a calibration-sufficiency theorem (a Taylor-expansion of $\log P_L$ in DEM mismatch, bounded by the threshold theorem's exponential decay) and verify it numerically across 52 of 64 empirical $(d, \xi, p)$ cells with fitted constants. Empirically, across the validated noise regimes (burst, close modes, static hot spots, hardware-calibrated profiles, Ornstein–Uhlenbeck drift, biased Pauli; dynamic hot spots are treated as exploratory boundary-search and are not part of the headline evidence stack) at code distances $d = 3$–$17$, classical calibration captures the full adaptive advantage in every tested temporal/global regime (with a bias-aware-DEM caveat at extreme Z-bias), and learned spatial inference adds a measurable advantage only in one narrow extreme static-hot-spot window at $d=3$ — where a true per-qubit DEM oracle still beats the LSTM by 2.3×, showing the gap is calibration-side. A documented coherent-rotation null result reduces to biased Pauli under Pauli twirling.

Layout

src/qec_adaptive/        # importable package
  noise/                 # protected: per-round / per-qubit injection (burst, hotspot, OU, ...)
  baselines/             # classical decoder hierarchy + windowed estimator
  decoders/              # neural decoders (FF, LSTM, GNN, Transformer, RecurrentTransformer)
  theory/                # Route-4 calibration sufficiency + prior failed attempts
  evidence_utils.py      # result-artifact JSON schema (publication gate)
  utils.py               # Wilson CIs, surface-code helpers, DEM construction
experiments/             # entry-point scripts, one per main-text claim
  legacy/                # deprecated iteration scripts (broken imports OK)
results/                 # frozen JSON artifacts (see RESULT_SCHEMA.md)
figures/                 # regenerable PDFs
  legacy/                # pre-Quantum-push figures
manuscript/              # LaTeX (main.tex, supplementary.tex, bibliography.bib, ...)
notebooks/               # Colab/Kaggle drivers for the heavier neural runs
docs/                    # planning, claim ledger, archive
tests/                   # property-based + smoke tests

Quick start

# (Recommended) create a venv with Python 3.10+
uv venv --seed .venv --python 3.13   # or:  python3.13 -m venv .venv
source .venv/bin/activate

# Install the package and pinned dependencies
pip install -r requirements.txt
pip install -e .

# Smoke test (~5 minutes)
bash repro.sh smoke

# Regenerate manuscript figures (Fig. 3 + Fig. 5) from frozen results/
make figures

Reproducing the paper

Claim	Script	Artifact
Calibration-sufficiency theorem + Lemma 2	python -m qec_adaptive.theory.calibration_sufficiency	n/a (analytical; see THEOREM_STATUS.md)
Theorem fit constants from IID data	experiments/exp_iid_subthreshold.py	results/results_iid_subthreshold.json
8-distance R(d) scaling sweep + sub-threshold companions	experiments/exp_scaling.py, exp_scaling_extended.py	results/results_scaling*.json (5 artifacts)
Burst-noise classical adaptive matches oracle	experiments/exp_burst_definitive.py	results/results_experiment2r_definitive.json
FF NN beats MWPM at d=3 i.i.d.	experiments/exp_iid_ceiling.py	results/results_experiment1r_honest.json
Static hot spot: local adaptation helps	experiments/exp_hotspot.py	results/results_hotspot_summary.json
Extreme d=3 hot spot LSTM win	experiments/exp_hotspot_multiseed.py	results/results_hotspot_multiseed_extreme.json
Hardware-profile no-neural-advantage	experiments/exp_hardware_noise.py	results/results_hardware_noise.json
d=5 extended-training transformer	experiments/exp_hotspot_d5.py	results/results_hotspot_d5_large.json
OU drift classical wins	experiments/exp_ou_drift.py, exp_ou_multiseed.py	results/results_ou_drift.json, results_ou_multiseed.json
Biased-Pauli boundary refinement	experiments/exp_biased_pauli.py	results/results_biased_pauli_burst.json
Recurrent-transformer capacity sweep (4 cells) + 5-seed hot-spot v5 + true per-qubit oracle	experiments/exp_recurrent_transformer_sweep.py	results/results_recurrent_transformer_sweep_*.json (multiple)
Bootstrap CIs for every decoder	experiments/exp_bootstrap_ci.py	results/stats_bootstrap_ci.json
Holm–Bonferroni multiplicity correction (8-comparison family)	experiments/exp_holm_bonferroni.py	results/stats_holm_bonferroni.json
Coherent rotations (null result, redundant)	experiments/exp_coherent_rotation.py	results/results_coherent_rotation_burst.json

The full claim ↔ artifact ↔ script mapping lives in CLAIM_LEDGER.md. Post-port result artifacts conform to the schema documented in RESULT_SCHEMA.md; a small number of pre-port legacy files are kept for provenance and listed explicitly in tests/test_results_schema.py::LEGACY_PRE_SCHEMA.

Citation

Bibliography in manuscript/bibliography.bib. Cite with the DOI listed at the top of manuscript/main.tex once accepted.

Code & data availability

The public source repository is https://github.com/Catomakyto/qec-adaptive. Every GitHub release is auto-archived to Zenodo; the concept DOI 10.5281/zenodo.20040186 always resolves to the latest archived snapshot.

License

MIT — see LICENSE.