README.md

---
license: apache-2.0
library_name: pytorch
tags:
- quantum-error-correction
- surface-code
- neural-decoder
- pre-decoding
- continual-learning
---

# 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

```text
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 from the paper](assets/figure2_qadapt_pipeline.png)

*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 from the paper](assets/figure3_htnet_architecture.png)

*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

```bash
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:

```bash
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:

```bash
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

```bash
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.

```bash
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 from the paper](assets/figure5_synthetic_ood.png)

*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% |

![Willow results from the paper](assets/figure6_willow_results.png)

*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:

```bash
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](https://arxiv.org/abs/2607.28422).

## Citation

If you find this work useful, please cite:
```bibtex
@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}
}
```