Adding GARI

[arshpreetmaan]

Key Changes

• Introduction: This PR introduces the GARI (Graph Augmentation and Rewiring for Inference) framework based on https://arxiv.org/pdf/2510.14060 (see Eqs. 1, 3, and 5). GARI sparsifies the Detector Error Model (DEM) by splitting multi-connected errors (Y-type errors) into independent components (X-type, Z-type) coupled through virtual detectors.
• Prior Weights: Due to the new DEM structure, assigning new prior weights is a strict necessity. While the methods to assign weights in the paper were suited for Belief Propagation (BP), they are not suitable for Tesseract. This PR introduces various prior weight methods based on Eq3 in the paper (with added scalings), as well as Linear Programming (LP) based modes to mathematically infer weights that are admissible for Tesseract. Users can add their own modes of prior weights.
• Detector Ordering: Various det_orders are introduced as an efficiency feature. These allow Tesseract to process the new GARI-DEM detectors in an optimal chronological manner (for example, real then virtual detectors) to improve speed and efficiency. New and improved orderings can be added based on the circuit under consideration.

1. Core Python Utility (src/py/)

This PR introduces a Python interface for GARI (gari_dem_utils.py), which does the following:

• gari_transform(H, L, det_types): Transforms physical matrices defining the dem ($H, L$) into the GARI representation, returning a structured gari_structure dictionary (GARI matrices, virtual maps, and other data).
• assign_prior_weights(gari_structure, method, original_priors): Implements various modes to assign weights. Optimizations are solved on-demand for the requested method, preventing redundant execution of all LP algorithms.
• get_detector_orderings(gari_structure, det_types, ordering_name): Computes custom stabilizer order sequences to prioritize A* search expansion.

2. Core C++ Changes & CLI Configuration

Both tesseract_main.cc and simplex_main.cc accept the --dem and --det-mapping-file CLI arguments:

• --dem: Path to the Stim detector error model (DEM) file (accepts GARI dem as well).
• --det-mapping-file: Path to a JSON file containing the mapping between the original physical detector indices and detector indices in GARI dem.

Tesseract-Only Configuration: --custom-order

In tesseract_main.cc, --custom-order specifies a custom detector ordering key to load from det_orders in the JSON mapping file (e.g. --custom-order order10). The orderings guide A* search branching priorities. Simplex does not support stabilizer orderings.

3. Simulation Loop & Shot Data Mapping

Incoming physical detector shot data ($N$ original detectors) is translated to the GARI detector space ($M$ GARI detectors) on-the-fly during decoding.

Mapping C++ Loop

• Simulated Shots: Remaps active physical detectors to GARI space using det_mapping[d].
• File-Loaded Shots: Remaps sparse shot records: Directly updates each hit to its GARI mapped equivalent.

Virtual Stabilizers and Parity Bounds

Since GARI adds virtual check stabilizers ($M > N$), any unmapped virtual checks are initialized with 0 (even parity).

What Happens if the Mapping File is Omitted?

• Reading from File (Parsing Failures): If --det-mapping-file is omitted, the reader expects $M$ detectors. Reading records of size $N$ triggers parsing failures:
  • 01 Format: Early newline character triggers: 01 data ended in middle of record... and throws.
  • B8 Format: Causes byte alignment phase-shift, reading data from subsequent shots and causing silent corruption.
• Simulation Mode (Layout Mismatch): The simulator samples physical checks $[0, N-1]$ from the circuit. The decoder maps physical stabilizers directly to GARI indices without translation. Because GARI reorganizes detectors into blocks ([Real X, Real Z, ...]), this layout mismatch causes invalid logical error rates. A possible workaround would be to reorder the real detectors in GARI dem to be same as in original circuit/dem.

Safety & Bounds Warnings

• Out of Bounds Mapping Index: Accessing det_mapping[hit] using [] performs no bounds checking. If a physical shot contains a stabilizer index higher than the mapping size, it leads to undefined behavior/segmentation fault.
• Out-of-Bounds Custom Order Index: The C++ code doesn't check if the indices within the JSON order list are within [0, count_detectors - 1]. If an invalid index is included in JSON, it causes an out-of-bounds vector access inside tesseract.cc and crashes.

4. Sparsification Compatibility

Tesseract's --sparsify-errors features are fully compatible with GARI. The sparsifier operates directly on the symptom error degree extracted from the loaded stim::DetectorErrorModel. Because the incoming shots are remapped to GARI space prior to decoding, the GARI indices in both the DEM and the mapped hits align perfectly.

5. Testing & Verification

• Verified C++ compiles and tests pass: bazel test //src/py/...
• Verified GARI DEMs generated correctly via CLI: bazel run //src/py/_tesseract_py_util:gari_dem_utils -- "testdata/surfacecodes/"
• Verified simulation test executing properly: bazel run //src/py:gari_simulation_test

6. Simulation results

Initial benchmarking shows that running Tesseract on the GARI dem can yield up to a 35x speedup. Additional tuning of prior weights, det_orders, and beam parameters suited for the GARI dem's structure is expected to increase performance further.

• Superdense Color codes:

• BB code:

• BB code with LP based prior weight:

[noajshu]

any reason to leave this comment here?

[noajshu]

This seems to be the central idea from the gari paper? Maybe good to add a comment with some reference to that paper and the specific eq / figure?