Adaptive Window Decoding

Reference simulation code for Adaptive Window Decoding based on Spatiotemporal Complementary Gap by Moeto Mishima et al. (arXiv:2605.14637).

The code evaluates adaptive sliding- and parallel-window minimum-weight perfect matching (MWPM) decoders using the spatiotemporal complementary gap (STCG), distance-shifted STCG, and path-selected STCG.

Installation

Python 3.10 or later is required.

python3 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install -e .

For the exact environment used when preparing this release:

python -m pip install -r requirements-lock.txt
python -m pip install -e . --no-deps

Repository layout

.
├── src/adaptive_window_decoding/
│   ├── repetition_code/
│   │   ├── stcg.py
│   │   ├── distance_shifted_stcg.py
│   │   ├── path_selected_stcg.py
│   │   ├── matching_graph.py
│   │   ├── path_tracing.py
│   │   ├── path_selected_gap.py
│   │   └── diagnostics.py
│   ├── surface_code/
│   │   ├── stcg.py
│   │   ├── path_selected_stcg.py
│   │   ├── single_window_path_selected_stcg.py
│   │   └── conventional_gap_comparison.py
│   ├── parallel_window/
│   │   └── path_selected_stcg.py
│   └── results.py
├── analysis/
│   ├── data/                    # Archived figure CSV files
│   ├── figure_data.py           # Shared CSV loading helpers
│   ├── plot_gap_figure_data.py  # Figs. 10, 12, 14, 15, and 18-20
│   ├── figure_*_*.py            # Figure-specific plotting scripts
│   ├── figure_*.png             # Reproduced paper figures
│   ├── process_results.py       # Shared result-processing helpers
│   └── process_*.py             # Experiment-specific processors
├── tests/
│   ├── test_repetition_code_helpers.py
│   └── test_results_pipeline.py
├── pyproject.toml
├── requirements-lock.txt
├── CITATION.cff
└── LICENSE.txt

The simulation parameters are grouped near the top of each experiment script. Runs use Monte Carlo sample counts up to $10^8$ in the paper; reduce num_shots for a quick local check. Results are written under

results/<experiment>/d<distance>_rounds<rounds>_rcom<commit>_rbuf<buffer>_p<rate>_shots<shots>/

Each dataset contains parameters.json and one summary_expN.json per run. When compute_g_distribution = True, it also contains the raw .npy arrays consumed by the processing scripts. The whole results/ tree is ignored by Git.

Switching-enabled runs also write switching_results_expN.csv. Each row records one gap threshold together with its switching rate, logical error rate, global logical error rate, and run parameters. A separate file is used for each experiment index so concurrent Monte Carlo jobs do not write to the same CSV.

Running experiments

Run modules from the repository root after installation. The path-selected repetition-code script takes an experiment index and a gap threshold:

python -m adaptive_window_decoding.repetition_code.path_selected_stcg 0 8

The surface-code path-selected scripts take an experiment index; their threshold and physical parameters are set in the configuration block at the top of each file:

python -m adaptive_window_decoding.surface_code.path_selected_stcg 0
python -m adaptive_window_decoding.surface_code.single_window_path_selected_stcg 0

The conventional-gap comparison takes the experiment index followed by command-line options:

python -m adaptive_window_decoding.surface_code.conventional_gap_comparison \
    0 --distance 7 --physical-error-rate 0.001 --num-shots 1000000

The STCG, distance-shifted STCG, and parallel-window experiments use their top-of-file configuration blocks:

python -m adaptive_window_decoding.repetition_code.stcg 0
python -m adaptive_window_decoding.repetition_code.distance_shifted_stcg 0
python -m adaptive_window_decoding.surface_code.stcg 0
python -m adaptive_window_decoding.parallel_window.path_selected_stcg 0

In all commands, the first integer argument is the experiment index. Use 1, 2, and so on for additional Monte Carlo runs with the same parameters; the processor combines all available indexed raw arrays.

For gap-distribution and conditioned-error calculations, set compute_g_distribution = True in the selected simulation script before running it. This disables switching for that run and records per-shot gap and logical-error arrays.

Processing results

Pass the dataset directory produced by a simulation to its matching processor. For example:

python analysis/process_surface_path_selected_stcg.py \
    results/surface_path_selected_stcg/d11_rounds55_rcom11_rbuf2_p0-0025_shots1000000

The processor reads parameters.json, discovers every run index for which raw arrays exist, combines those runs, and writes distributions, conditioned logical-error counts, a summary, and gap_statistics.png under the dataset's processed/ directory. Available entry points are:

analysis/process_repetition_stcg.py
analysis/process_repetition_distance_shifted_stcg.py
analysis/process_repetition_path_selected_stcg.py
analysis/process_surface_stcg.py
analysis/process_surface_path_selected_stcg.py
analysis/process_surface_single_window_path_selected_stcg.py
analysis/process_parallel_path_selected_stcg.py

Paper-to-code map

Paper result	Implementation
Figs. 10, 18, 19: repetition-code gap properties	repetition_code/{stcg,distance_shifted_stcg,path_selected_stcg}.py with gap-distribution mode
Fig. 11: adaptive repetition-code switching	the same three repetition-code scripts with switching enabled
Figs. 12, 20: surface-code gap properties	surface_code/{stcg,path_selected_stcg}.py with gap-distribution mode
Fig. 13: adaptive surface-code switching	surface_code/{stcg,path_selected_stcg}.py with switching enabled
Figs. 14-17: single-window data and extrapolation inputs	surface_code/single_window_path_selected_stcg.py and surface_code/path_selected_stcg.py
Fig. 22: parallel-window gap properties	parallel_window/path_selected_stcg.py
Figs. 24-25: conventional complementary gap under sliding/global decoding	surface_code/conventional_gap_comparison.py

The plotting and extrapolation in Figs. 10-22 were performed from the generated arrays. Large raw Monte Carlo arrays are intentionally not included in this source release; the final plotted data are archived as CSV files.

The final binned values for Figs. 10, 12, 14, 15, 18, 19, and 20 are archived as analysis/data/figure_N.csv. Each row contains the bin boundaries and plotted x coordinate, raw count or numerator/denominator where applicable, plotted y value, binomial standard error, and simulation parameters. Figure 14 also records its semilog fits. Figure 15 records both measured single/multiple-window data and the independence-model predictions.

The archived CSV files are sufficient to redraw all seven figures without .npy files:

python analysis/plot_gap_figure_data.py
python analysis/plot_gap_figure_data.py 10 15

The remaining paper figures are also rendered entirely from checked-in CSV files:

python analysis/figure_11_repetition_switching.py
python analysis/figure_13_surface_average_buffer.py
python analysis/figure_16_prediction_verification.py
python analysis/figure_17_low_error_extrapolation.py
python analysis/figure_22_parallel_property.py
python analysis/figure_24_conventional_gap_comparison.py
python analysis/figure_25_conventional_gap_distribution.py

Appendix C: conventional complementary gap

The simulation used for Figs. 24 and 25 is preserved as surface_code/conventional_gap_comparison.py. It computes the conventional complementary gap under both global and sliding-window decoding. New runs are stored under results/surface_conventional_gap_comparison/ and can be processed with:

python analysis/process_conventional_gap_comparison.py \
    results/surface_conventional_gap_comparison/d7_rounds70_rcom7_rbuf7_p0-001_shots1000000

The processor writes the disagreement summary, the per-shot global/window gap pairs, and the binned distributions and conditional logical-error rates under processed/ as CSV files.

The data plotted in Figs. 24 and 25 are archived as analysis/data/figure_24.csv, figure_24_scatter.csv.gz, and figure_25.csv. Figure 24(a) contains the 12 plotted combinations of $d\in{5,7,9}$ and $p\in{0.001,0.002,0.003,0.004}$; panel (b) contains all $10^6$ shot-level pairs for $d=7$, $p=0.001$. Two gap values are regarded as different when their relative difference with respect to the global gap is at least 1%. Figure 25 uses the same $d=7$, $p=0.001$ arrays and unit-width bins. In Fig. 25(b), the global and window curves use the logical-error events of the global and sliding-window decoders, respectively.

The figures are drawn from these archived files without access to any .npy files:

python analysis/figure_24_conventional_gap_comparison.py
python analysis/figure_25_conventional_gap_distribution.py

Validation

python -m compileall -q src
python -m unittest discover -s tests

License

This project is distributed under the BSD 3-Clause Clear License. See LICENSE.txt for the full terms, including the explicit patent-rights disclaimer.