QAdapt v2

Noise-Adaptive Neural Pre-Decoding for Surface-Code Quantum Error Correction

QAdapt is a noise-adaptive neural pre-decoding framework for surface-code quantum error correction. Its HTNet pre-decoder learns local spatiotemporal correlations and predicts corrections, while a matching decoder resolves the residual detector events. Online elastic weight consolidation (EWC) limits forgetting during adaptation across noise environments. The resulting weights are frozen during evaluation on unseen compound noise and native Willow records.

This release provides the HTNet A101 final EWC checkpoint, eight comparison checkpoints, inference code, noise configurations, and the numerical data behind the v2 manuscript figures. It is a PyTorch research model bundle; load it with the supplied inference code rather than Transformers AutoModel.

Versions and paper

Version	Weights and code	Associated manuscript
v2	v2/, primary checkpoint v2/model.safetensors	QAdapt: Noise-Adaptive Neural Pre-Decoding for Surface-Code Quantum Error Correction (v2 revision submitted)
v1	Existing root-level files and the preserved v1 tag	Original arXiv preprint: QAdapt: A Noise-Adaptive Neural Pre-Decoding Framework for Quantum Error Correction

The v2 manuscript was submitted to arXiv on 10 November 2026: 16 pages, 11 figures, and 4 tables, including appendices. The abstract and citation below follow this submission. At the time of this update, the public arXiv page still displayed v1; the paper link above points to the latest public version.

The root config.json, Qadapt-r9-v1.safetensors, qadapt-minimal.patch, and root examples remain v1 for existing users. For v2, use the files under v2/ and the installation instructions below. The previous model card remains available at its original revision.

Paper abstract

Fault-tolerant quantum computing relies on quantum error correction to protect logical information, requiring classical decoders that keep pace with syndrome generation. Heterogeneous, changing hardware noise and the distribution shift from simulation to experiment challenge the accuracy and robustness of fixed neural decoders. We present QAdapt, a noise-adaptive neural pre-decoding framework for surface-code quantum error correction. QAdapt learns local spatiotemporal correlations, continually adapts across noise environments, and passes the residual syndrome to a conventional global decoder. Online elastic weight consolidation limits forgetting as training moves between measurement, idle, CNOT, and Pauli-bias noise regimes. At distance nine, the HTNet pre-decoder reduces equivalent per-round logical error by 15.64% relative to Ising-Fast, with 28.75% fewer parameters and 9.07% less matching-backend time. Online EWC reduces average forgetting by 76.52% relative to sequential fine-tuning. With weights frozen, it reduces equivalent per-round logical error by 5.66% relative to continued base-environment training on a fixed valid domain of 331 unseen compound-noise conditions; whole-sequence failure probability falls by 2.54% over all 396 conditions. On native Willow records, the corresponding per-round reductions are 19.44%, 17.47%, and 17.95% at 10, 30, and 50 rounds, without target-domain fine-tuning. These results show how adaptive neural pre-decoding can improve logical accuracy, preserve performance across noise regimes, and reduce residual matching workload within an established decoding pipeline.

What changes in v2

• Architecture: HTNet A101 retains adaptive spatial, temporal, and joint fusion, grouped post-fusion mixing, channel gating, and the raw-input skip. Axis gating is disabled. The model has 650,332 parameters, compared with 650,374 in v1 and 912,772 in Ising-Fast.
• Adaptation: a common T0 checkpoint is followed by measurement ×4, idle ×4, CNOT ×1.5, and Z-bias ×1.5 environments, in that order. The release distinguishes the initial checkpoint, continued T0-only training, and final adapted weights.
• Evaluation: the updated study covers 396 unseen compound-noise conditions and native Willow sequences of 10, 30, and 50 rounds. Model selection uses separate simulated validation data; Willow records are used only for evaluation.

Results

The table reports relative reductions, not percentage-point differences. LER is equivalent per-round logical error, computed as q = (1 - (1 - 2p)^(1/R)) / 2 from whole-sequence failure probability p and sequence length R.

Experiment	Comparison	Relative LER reduction	Paired 95% interval
Architecture, d = 9, R = 9	HTNet T0-best vs Ising-Fast T0-best	15.64%	15.10–16.18%
Unseen compound noise, R = 9	Final EWC vs continued T0-only	5.66%	4.81–6.51%
Native Willow, R = 10	Final EWC vs continued T0-only	19.44%	19.01–19.86%
Native Willow, R = 30	Final EWC vs continued T0-only	17.47%	17.09–17.86%
Native Willow, R = 50	Final EWC vs continued T0-only	17.95%	17.46–18.44%

Architecture comparisons use separately selected T0 checkpoints: HTNet epoch 97 and Ising-Fast epoch 87. At distance nine, HTNet uses 28.75% fewer parameters, leaves 14.14% fewer active residual detector events, and reduces matching-backend time by 9.07%. Timing measures residual matching only. These architecture results are not attributed to the final EWC checkpoint.

Across the four historical tasks, Online EWC reduces average forgetting from 0.0455 to 0.0107 percentage points: a 76.52% reduction relative to sequential fine-tuning. This is a point estimate from one training realization. EWC improves retention and transfer; SEQ retains a slightly lower final in-distribution task average.

For compound noise, the per-round comparison uses a fixed common-valid mask of 331 out of 396 conditions. The whole-sequence failure comparison uses all 396 conditions and gives a 2.54% reduction. The grid combines 11 noise families, nine strength multipliers, and distances 3, 5, 7, and 9, with 10,000 shots per basis and condition. The aggregate gain is distance dependent; the distance-nine interval includes zero.

Input syndrome density (Figure S6). The heatmaps cover all 396 compound-noise conditions at distances 3, 5, 7, and 9, using nine rounds and 10,000 shots per logical basis. Density is the fraction of active detector entries before pre-decoding, averaged over the X and Z bases. At distance nine, it spans 10.26–32.17%; at the same 5× multiplier, measurement + idle noise gives 17.12%, compared with 32.17% when measurement, CNOT, idle, and Z-bias parameters are changed together. The four panels share a linear 0–35% color scale. Download the condition-level density data.

On Willow, EWC also reduces per-round LER relative to SEQ by 3.83%, 3.73%, and 4.08% at 10, 30, and 50 rounds. EWC and Mix-Total are statistically comparable at the two longer lengths. Each length contains 28 native patch/basis cases at distances 3, 5, and 7, using 50,000 shots per case. Patches are averaged within each distance before distances are weighted equally.

Intervals describe paired evaluation-shot uncertainty for fixed trained weights. They do not measure variability across training seeds. Exact values and condition-level data, with standalone PyMatching results omitted, are supplied in v2/evaluation.json and v2/data/.

Checkpoints

All weights are FP32 SafeTensors. Paths below are relative to v2/; HTNet files use model_id=111, while Ising-Fast uses model_id=1.

Role	File	Intended comparison
QAdapt / final Online EWC	model.safetensors	Primary frozen-transfer model
Continued T0-only	baselines/t0-only/model.safetensors	Matched-update transfer baseline
SEQ	baselines/seq/model.safetensors	Sequential fine-tuning without EWC
Mix-Total	baselines/mix-total/model.safetensors	Mixed tasks, matched update budget
Mix-Exposure	baselines/mix-exposure/model.safetensors	Mixed tasks, matched per-task exposure
Replay	baselines/replay/model.safetensors	Replay control
Initial C0	baselines/initial-c0/model.safetensors	Common epoch-100 starting point
HTNet T0-best	baselines/htnet-t0-best/model.safetensors	Architecture accuracy comparison
Ising-Fast T0-best	baselines/ising-fast-t0-best/model.safetensors	Architecture accuracy comparison

Continued T0-only is not C0. It receives 61,440 additional optimizer updates on T0, matching the sequential adaptation budget. The best-validation architecture checkpoints are also distinct from C0 and the final adapted checkpoints.

v2/weights_manifest.json records the original checkpoint hashes, exported hashes, model roles, and parameter counts. Exported tensors are checked against the source training checkpoints without quantization.

Install and load

Use Python 3.11 or later and a PyTorch build appropriate for your CPU or GPU. Download this model bundle, then apply the v2 patch to a fresh checkout of the pinned NVIDIA upstream revision:

python -m pip install huggingface_hub
hf download Qhub-AI/QAdapt --local-dir QAdapt

git clone https://github.com/NVIDIA/Ising-Decoding.git Ising-Decoding-v2
cd Ising-Decoding-v2
git checkout 33acb152e403bc189f2effdb07f1a87b34c745f1
git apply ../QAdapt/v2/qadapt-v2-inference.patch
python -m pip install -r code/requirements_public_inference.txt

Apply only the v2 patch to that fresh checkout; it includes the required public inference support. It reconstructs A101 from checkpoint metadata and also accepts the legacy v1 checkpoint. Verify the downloaded release from the QAdapt directory with sha256sum -c v2/SHA256SUMS.

To inspect network outputs from the Ising-Decoding-v2 directory:

import sys
import torch
sys.path.insert(0, 'code')
from export.safetensors_utils import load_safetensors

model, metadata = load_safetensors('../QAdapt/v2/model.safetensors', device='cpu')
model.eval()
x = torch.zeros(1, 4, 9, 9, 9)  # B, channels, rounds, d, d
with torch.inference_mode():
    logits = model(x)
print(logits.shape)  # torch.Size([1, 4, 9, 9, 9])

The four input channels follow the supplied surface-code datapipe. The network returns correction logits, not logical predictions. Use the decoding workflow below for the full logical decision.

Run inference

A small CPU check on T0, using the public paired-decoding entry point:

PYTHONPATH=code python code/scripts/paired_inference_compare.py \
  --config-file ../QAdapt/v2/configs/T0.yaml \
  --model qadapt:111:../QAdapt/v2/model.safetensors \
  --distance 5 --n-rounds 9 --num-samples 1024 \
  --latency-num-samples 128 --batch-size 32 --num-workers 0 \
  --basis both --seed 12345 --device cpu \
  --output outputs/qadapt_v2_t0_smoke.json

For GPU evaluation of the five simulated tasks:

PYTHONPATH=code python code/examples/infer_t0_t4.py \
  --model qadapt:111:../QAdapt/v2/model.safetensors \
  --model t0-only:111:../QAdapt/v2/baselines/t0-only/model.safetensors \
  --distances 9 --tasks T0,T1,T2,T3,T4 --n-rounds 9 \
  --num-samples 65536 --gpus 0 --output-dir outputs/qadapt_v2_tasks

For the 396-condition compound-noise grid:

PYTHONPATH=code python code/examples/infer_ood.py \
  --base-config conf/examples/qadapt_v2/T0.yaml \
  --model qadapt:111:../QAdapt/v2/model.safetensors \
  --model t0-only:111:../QAdapt/v2/baselines/t0-only/model.safetensors \
  --distances 3,5,7,9 --multipliers 1.2,1.5,2,2.5,3,3.5,4,4.5,5 \
  --n-rounds 9 --num-samples 10000 --gpus 0 \
  --output-dir outputs/qadapt_v2_ood

For Willow, obtain and extract the original Google Quantum AI dataset, then point to its google_105Q_surface_code_d3_d5_d7 directory:

PYTHONPATH=code python code/examples/infer_willow.py \
  --benchmark-root /path/to/google_105Q_surface_code_d3_d5_d7 \
  --model qadapt:111:../QAdapt/v2/model.safetensors \
  --model t0-only:111:../QAdapt/v2/baselines/t0-only/model.safetensors \
  --distances 3 5 7 --rounds 10 30 50 --num-samples 50000 \
  --gpus 0 --output-dir outputs/qadapt_v2_willow

The native lengths are evaluated directly, without constructing longer sequences by repeating or concatenating shorter records. Add --dry-run to the three example commands to inspect jobs before evaluation. These commands generate fresh evaluations; the archived numerical results and fixed validity mask in v2/data/ are the evidence for the table above.

Training protocol and scope

The common HTNet A101 starting point is the fixed epoch-100 T0 checkpoint. Adaptation follows T1 → T3 → T2 → T4, with 15,360 optimizer updates per stage, effective batch size 4,096, and 61,440 updates in total. Online EWC uses coefficient 316.227766, Fisher decay factor 1, and 4,096 samples per Fisher estimate. See v2/training_protocol.json for the recorded budget and v2/configs/ for the exact noise probabilities.

The release contains frozen model weights, inference support, and archived evaluation data. It does not include the full training orchestration, optimizer/Fisher states, or intermediate adaptation checkpoints. The forgetting figure summarizes the archived training trajectories. Architecture evaluation covers distances 5, 7, and 9; the OOD and Willow domains are stated separately above. The supplied weights were trained at distance nine and nine rounds. Other devices and noise regimes require separate validation.

Authors and contact

Ran Miao, Rui Luo, Xiaohan Shan, and Xiaoming Sun. Ran Miao and Xiaohan Shan contributed equally. Correspondence: Xiaoming Sun, Institute of Computing Technology, Chinese Academy of Sciences — sunxiaoming@ict.ac.cn.

Acknowledgments

We sincerely thank Fusheng Chen (Hefei National Laboratory, University of Science and Technology of China) and Riling Li (Institute of Software, Chinese Academy of Sciences) for their thoughtful and valuable discussions of this work.

We also acknowledge the NVIDIA Ising-Decoding authors for the open-source foundation and Google Quantum AI for making the Willow quantum error-correction records publicly available.

License and citation

The model bundle and supplied code use Apache-2.0. The upstream notices remain in LICENSE and NOTICE. Willow data are downloaded separately under the dataset's terms.

Citation for the submitted v2 manuscript:

@article{miao2026qadapt,
  title={QAdapt: Noise-Adaptive Neural Pre-Decoding for Surface-Code Quantum Error Correction},
  author={Miao, Ran and Luo, Rui and Shan, Xiaohan and Sun, Xiaoming},
  journal={arXiv preprint arXiv:2607.28422},
  year={2026},
  url={https://arxiv.org/abs/2607.28422}
}

For experiments with this release, also record the Hugging Face repository revision and the v2/ checkpoint used.