QAdapt v1

This repository contains the final QAdapt checkpoint and the exact Ising-fast T0 e100 baseline used for paired evaluation in QAdapt: A Noise-Adaptive Neural Pre-Decoding Framework for Quantum Error Correction.

Release version: v1.

This is a research checkpoint bundle, not a Transformers AutoModel repository. Use it with the pinned NVIDIA/Ising-Decoding revision and the patch supplied here.

Included models

Role	File	Model ID	Architecture	Parameters	RF
QAdapt	Qadapt-r9-v1.safetensors	111	HTNet	650,374	9
Paired baseline	baselines/ising-fast-t0-e100/model.safetensors	1	PreDecoderModelMemory_v1	912,772	9

QAdapt is the primary artifact. The bundled Ising-fast checkpoint was trained only on T0 for 100 epochs and is included so that all reported paired comparisons can be evaluated from one repository. Its exact architecture metadata is stored in baselines/ising-fast-t0-e100/config.json.

Technical overview

detector events [B, 4, T, H, W]
        -> neural local pre-decoder
        -> predicted local correction and residual syndrome
        -> PyMatching global residual decoder
        -> logical prediction

QAdapt workflow: hardware-informed noise modeling, heterogeneous spatiotemporal feature extraction, continual adaptation, and hybrid neural--matching inference.

QAdapt uses a 3-D convolutional stem followed by three HTNet spatiotemporal fusion blocks. Each block combines a spatial branch, a temporal branch, and a grouped joint 3-D branch using input-adaptive fusion, then applies channel, temporal-axis, and spatial-axis gating with a residual connection. The input-conditioned head produces four output channels.

The released HTNet uses 112 hidden channels, 168 expanded channels, six joint convolution groups, eight normalization groups, and an effective receptive field of nine. Full machine-readable parameters are in config.json.

The Ising-fast baseline is a dense four-layer 3-D convolutional pre-decoder with filters [128, 128, 128, 4] and 3x3x3 kernels.

HTNet architecture: a 112-channel 3-D stem, three heterogeneous spatiotemporal fusion blocks, raw-evidence concatenation, and a four-channel correction head.

Training scope

Training samples were generated on demand with Stim from the public 25-parameter circuit-level Pauli configurations under configs/.

• QAdapt: T0 -> T1 -> T2 -> T3 -> T4, 20 epochs per task, 100 epochs total.
• QAdapt training hardware: 4 × NVIDIA A100 GPUs.
• Continual adaptation: Q-EWC coefficient 100 from T1 onward, with 65,536 samples per Fisher estimate.
• Ising-fast baseline: T0 only, 100 epochs.
• Willow: zero-shot evaluation only; no training, fine-tuning, calibration, or model selection used Willow samples.

Training orchestration, optimizer state, Fisher state, intermediate checkpoints, and logs are intentionally not distributed.

Install

git clone https://github.com/NVIDIA/Ising-Decoding.git
cd Ising-Decoding
git checkout 33acb152e403bc189f2effdb07f1a87b34c745f1
git apply /path/to/QAdapt/qadapt-minimal.patch
pip install -r code/requirements_public_inference.txt

The patch adds QAdapt model ID 111, SafeTensors loading, the exact public configs, and the three inference entry points. It contains no training code or intermediate models.

T0--T4 inference

Run QAdapt alone on T0:

PYTHONPATH=code python code/examples/infer_t0_t4.py \
  --tasks T0 --distances 9 \
  --model qadapt:111:/path/to/QAdapt/Qadapt-r9-v1.safetensors

Run the paired release evaluation:

PYTHONPATH=code python code/examples/infer_t0_t4.py \
  --model qadapt:111:/path/to/QAdapt/Qadapt-r9-v1.safetensors \
  --model ising-fast:1:/path/to/QAdapt/baselines/ising-fast-t0-e100/model.safetensors

The default paired command evaluates T0--T4 at d=9/r=9 with 262,144 shots per basis per task and seed 12345. Use --dry-run to inspect all five jobs first.

Synthetic OOD inference

PYTHONPATH=code python code/examples/infer_ood.py \
  --model qadapt:111:/path/to/QAdapt/Qadapt-r9-v1.safetensors \
  --model ising-fast:1:/path/to/QAdapt/baselines/ising-fast-t0-e100/model.safetensors

Defaults run the retained paper grid: 11 axis combinations, multipliers 1.2/1.5/2.0/2.5/3.0, d=7 and d=9, for 110 jobs total.

Willow zero-shot inference

The Willow archive is third-party data and is not redistributed here.

PYTHONPATH=code python code/scripts/download_google_qec_benchmark.py --extract
PYTHONPATH=code python code/examples/infer_willow.py \
  --model qadapt:111:/path/to/QAdapt/Qadapt-r9-v1.safetensors \
  --model ising-fast:1:/path/to/QAdapt/baselines/ising-fast-t0-e100/model.safetensors

Defaults are d=5/d=7, ten rounds, and all available shots: 400,000 at d=5 and 100,000 at d=7, without fine-tuning.

Results

T0--T4 terminal model results

The final e100 checkpoints were evaluated at d=9/r=9 with 262,144 shots per logical basis per task and seed 12345.

Task	PyMatching LER	Ising-fast LER	QAdapt LER
T0	0.04503	0.04094	0.03612
T1	0.05489	0.05207	0.04619
T2	0.15404	0.14017	0.13012
T3	0.04997	0.04532	0.04053
T4	0.09811	0.09135	0.08282
Mean	0.08041	0.07397	0.06716

QAdapt lowers mean LER by 9.22% relative to the Ising-fast T0 e100 baseline.

Synthetic OOD

Each distance aggregates 55 configurations and logical X/Z bases. QAdapt wins all 110 configuration-level LER comparisons.

Distance	Ising-fast LER	QAdapt LER	LER reduction	Ising-fast latency	QAdapt latency
d=7	0.23447	0.22701	3.18%	2.329	2.195
d=9	0.24444	0.23653	3.23%	4.884	4.608

Synthetic OOD results over the five retained noise multipliers. Latency is in microseconds per round.

Willow zero-shot transfer

Setting	Metric	Ising-fast	QAdapt	Reduction
d=5/r=10	LER	0.09963	0.09386	5.79%
d=5/r=10	Backend latency	0.704	0.694	1.43%
d=7/r=10	LER	0.08412	0.08201	2.51%
d=7/r=10	Backend latency	1.405	1.274	9.32%

Zero-shot transfer to Willow at ten rounds. Latency is in microseconds per round.

Full-precision values and protocol metadata are provided in evaluation.json. The paper's mapped-T0 architecture table used Ising-fast e53 and a T0-only HTNet e89; those separate ablation values are not attributed to the final e100 artifacts distributed here.

Backend latency measures only residual PyMatching decoding. It excludes neural inference, device/host transfer, and residual construction and will vary by hardware and software environment.

Integrity

Run from this downloaded model repository:

sha256sum -c SHA256SUMS

The two SafeTensors artifacts were compared tensor-by-tensor with their final source checkpoints. All tensors match exactly.

Limitations

These checkpoints target rotated surface-code memory experiments with the input layout and noise semantics implemented by the pinned repository. They are not standalone end-to-end fault-tolerant systems and have not been validated for arbitrary code families, detector layouts, or hardware control stacks.

License and attribution

Apache-2.0. Retain LICENSE, NOTICE, and the modification notices when redistributing the code or patch. Google Willow data remains under its own upstream terms and is downloaded separately.

Paper

Our paper is now available on arXiv: arXiv:2607.28422.

Citation

If you find this work useful, please cite:

@article{miao2026qadapt,
  title={QAdapt:A Noise-Adaptive Neural Pre-Decoding Framework for Quantum Error Correction},
  author={Miao, Ran and Luo, Rui and Shan, Xiaohan  and Sun, Xiaoming },
  journal = {arXiv preprint arXiv:2607.28422},
  year={2026}
}