Add Python GARI transformation

[arshpreetmaan]

Summary

This PR replaces the Python portion of #269 with a focused implementation of graph augmentation and rewiring for inference (GARI).

PR #269 combined the Python transformation, C++ runtime integration, detector remapping, ordering experiments, and benchmarking in one change. This PR separates the Python foundation so it can be reviewed independently. C++ CLI integration is handled in a separate PR.

This PR adds:

• a conversion of supported correlated CSS stim circuits into the GARI decoding representation;
• the public Python API from tesseract_decoder import demutil, with GARI available as demutil.gari;
• paper, xor, and lp-max-barred-cost prior policies;
• one-circuit conversion through a dedicated GARI command-line utility;
• paired GARI matrix .dem and tesseract.gari_layout.v1 files;
• compact core tests.

Usage

From Python:

import stim
from tesseract_decoder import demutil
gari = demutil.gari

circuit = stim.Circuit.from_file("circuit_file.stim")
gari_dem, gari_layout = gari.circuit_to_gari(
    circuit,
    prior_function=gari.tesseract_xor_prior_probabilities,
)

The gari.py CLI converts one Stim circuit and derives both output filenames from the original circuit name and selected prior policy. With a python environment with NumPy, SciPy, and Stim installed, run:

python src/py/_tesseract_py_util/gari.py \
    --circuit d5r5colorcode_p001.stim \
    --prior xor \
    --out-dir gari_output

This writes gari_output/d5r5colorcode_p001_gari_xor.dem and gari_output/d5r5colorcode_p001_gari_xor_layout.json. Run python src/py/_tesseract_py_util/gari.py --help to see the conversion arguments.

Input and output GARI matrix

Circuit conversion generates an undecomposed source DEM with decompose_errors=False and flattened loops. dem_to_matrices also flattens repeat blocks and detector shifts before treating each resulting Stim error instruction as one source matrix column. Instructions containing Stim’s ^ decomposition separator are rejected.

The currently supported X/Z partition follows the color-code-style fourth-coordinate convention used by repository test circuits: values 0–2 identify X detectors and 3–5 identify Z detectors.

GARI emits columns in:

[e_Z, e_X, e_Y, bar(e)_Z, bar(e)_X]

and rows in the physical_then_virtual layout:

[physical X, physical Z, virtual Z, virtual X]

The decoder syndrome is [s_X, s_Z, 0, 0], and generic logical observables remain on the original physical variables.

Pure columns without an e_Y projection still receive barred counterparts. This deliberate redundancy preserves the uniform block structure and keeps the physical top-left blocks zero.

Missing or ambiguous projections, duplicate pure columns, and decomposed Stim instructions are rejected.

The generated .dem is matrix storage for decoding, not a physical detector error model, and must not be sampled.

Prior policies

• paper implements the published auxiliary initialization.
• xor assigns the auxiliary XOR parity marginal.
• lp-max-barred-cost first maximizes a common nonnegative cost floor across the physical residual and barred variables, then maximizes the total barred-variable cost while preserving that floor.

The latter two policies are experimental Tesseract search-cost policies and make no claim of decoding optimality.

Historical motivation

This plot reuses exploratory color-code data from the predecessor implementation in PR #269. Its GARI config corresponds to the policy now named xor. It is included as motivation, not as a benchmark of this Python-only change.

Reference

A. S. Maan, F. M. Garcia Herrero, A. Paler, and V. Savin, "Decoding correlated errors in quantum LDPC codes", Nature Communications 17, 3965 (2026).

[noajshu]

Thanks @arshpreetmaan , this is getting a lot simpler. I think this could be simplified even further by replacing the scripts in src/py/ that call gari (gari_convert.py and gari_example.py) with one small example in the docs folder (you can update the jupytext and re-gen the docs using the script) WDYT?

[review-notebook-app]

Check out this pull request on 

See visual diffs & provide feedback on Jupyter Notebooks.

---

Powered by ReviewNB

[arshpreetmaan]

Thanks for the feedback, @noajshu! I’ve incorporated the suggested changes and updated the PR accordingly.