Add GARI support via file-specified detector orders to decoder CLI

[arshpreetmaan]

Summary

This connects the existing Python GARI transform to the Tesseract CLI. It also introduces DetectorOrder, so we can specify how to construct an order before the decoding DEM is known. This is useful here and for the component decoders in #256.

Detector orders

One DetectorOrder represents one permutation. It either contains a literal permutation (Method::Literal) or a method (BFS, Index, or Coordinate) and seed. resolve(dem) fills in the order in place; for literal orders it validates the supplied permutation. Callers do not need separate handling for the two cases.

TesseractConfig holds a vector of these objects. Generated orders are resolved against the actual decoding DEM, with graph/coordinate preparation shared across the batch. Order k uses seed + k, rather than depending on a shared random-number stream. Every order must be a complete permutation of the DEM's detector IDs.

The Tesseract CLI can combine generated methods and JSON order files, in command-line order:

./tesseract --circuit source.stim --dem transformed.dem \
    --num-det-orders 3 --det-order-bfs \
    --detector-orders gari-orders.json --det-order-coordinate

Each generated source contributes --num-det-orders orders, using --det-order-seed as its base seed. --detector-orders FILE can be repeated and contributes every permutation in that file. The format is a JSON list of lists, just like Python's det_orders.

With no source flags, the default is Index. A file-only invocation stays file-only; add --det-order-index to combine it with Index orders. Count/seed flags with files but no generated method are rejected. The bookkeeping for these CLI sources stays local to the CLI, not in the library API.

GARI workflow

GARI transformation and GARI-aware order construction stay in Python. demutil.gari.circuit_to_gari(...) returns the transformed DEM directly, with source detector IDs first and virtual detectors appended. No layout sidecar is needed.

demutil.gari.build_detector_orders(...) constructs orders from the source DEM, appends virtual detector IDs, and checks that the decoding DEM has the expected GARI check and logical matrices. Probability-only reweighting is allowed.

When given both a circuit and a larger decoding DEM, the Tesseract and Simplex CLIs read/sample the circuit-width syndrome and leave the extra DEM detectors zero. The observable counts must agree. The order-file option is specific to the Tesseract CLI.

Python keeps the list-of-lists interface and existing detector-order aliases. Ordinary TesseractSinterDecoder construction and registry names are unchanged; generated orders resolve when the compilation DEM is available. This does not add a GARI-specific Sinter frontend.

GARI requires undecomposed source errors: ^ groups and logical-only errors are rejected. Its basis convention here is fourth coordinate 0/1/2 for X and 3/4/5 for Z. GARI-aware orders require the default source-aligned layout; row_order="block" remains available for matrix work. The transformed DEM is for decoding, not sampling.

Tests

Coverage includes generated/literal resolution, per-order seeds, permutation and file validation, Python compatibility, deferred Sinter orders, GARI layouts and matrix checks, and source-width shots decoded against a larger DEM. The full bazel test --jobs=1 src/... suite passed during implementation.

[LalehB]

can you also make sure that you update the README with examples as well please?

[arshpreetmaan]

The CI failure appears unrelated to the GARI changes. It seems to come from Bazel reusing cached binaries built on a different CPU. A possible fix is to disable only the Bazel disk cache:
In [.github/workflows/ci.yml (line 67)]

with:
  bazelisk-cache: true
  disk-cache: false
  repository-cache: true

This keeps the other caches enabled while ensuring native binaries are rebuilt on each runner.

[mhucka]

The CI failure appears unrelated to the GARI changes. It seems to come from Bazel reusing cached binaries built on a different CPU.

@arshpreetmaan Can you provide more info about the "different CPU" part? Since the GitHub workflows always run on the same type of runner, one would expect the CPU to be the same. Do you suspect a difference in the CPU feature sets?

[mhucka]

One thing I do see, though, is that the disk-cache should be further parametrized by the matrix OS. I'll do a quick PR.

[arshpreetmaan]

One thing I do see, though, is that the disk-cache should be further parametrized by the matrix OS. I'll do a quick PR.

Thanks, PR #295 might fix the issue. By “different CPU,” I meant that separate GitHub-hosted ubuntu-latest VMs may expose different CPU instruction features, even though they are all Linux x64 runners. Since the build uses -march=native, cached binaries can depend on those exact features.
The new per-OS cache name should clear the existing cache and likely fix the current failure in #277. We can rerun #277 after #295 is merged; if the Illegal instruction failure returns later, we may need to consider other options (perhaps making -march=native optional or using -march=x86-64 for CI).

[LalehB]

Thanks Arshpreet!

[noajshu]

Hi @arshpreetmaan @LalehB , WDYT about this alternative API:
just like how tesseract accepts detector orders via its python module API, we could accept one or more detector orders via the CLI. And the GARI code in demutil code can generate the gari-aware detector orders too.

[review-notebook-app]

Check out this pull request on 

See visual diffs & provide feedback on Jupyter Notebooks.

---

Powered by ReviewNB

[LalehB]

Hi @arshpreetmaan @LalehB , WDYT about this alternative API: just like how tesseract accepts detector orders via its python module API, we could accept one or more detector orders via the CLI. And the GARI code in demutil code can generate the gari-aware detector orders too.

@noajshu I think your proposed alternative API would be a good addition. I dunno if @arshpreetmaan addressed that.

[arshpreetmaan]

Hi @arshpreetmaan @LalehB , WDYT about this alternative API: just like how tesseract accepts detector orders via its python module API, we could accept one or more detector orders via the CLI. And the GARI code in demutil code can generate the gari-aware detector orders too.

@noajshu I think your proposed alternative API would be a good addition. I dunno if @arshpreetmaan addressed that.

Hi @LalehB @noajshu , I have applied the suggested API changes. Can you PTAL?

[noajshu]

I think this is becoming more complicated than necessary. In particular, I don't think detector remapping and detector ordering need to be coupled into a new detector_layout schema.

For GARI, can we instead have the generated DEM preserve the original detector IDs for the physical detectors and append the virtual detectors as a suffix? Then shots from the source circuit need no remapping at all: the first circuit.num_detectors entries are the physical syndrome and the remaining DEM detectors are implicitly zero. The C++ CLI would only need to support this source-prefix/augmented-DEM case when reading or sampling shots, rather than introducing a general mapping format.

Separately, if we want the C++ CLI to support explicit detector orders, I think that should just be a detector-orders file mirroring TesseractConfig.det_orders in the Python API.

Also, there is currently an inconsistency in what a “detector order” means between build_det_orders, the C++ decoder, and the Python-facing API. I think we should fix that first and use one representation everywhere (matching the current python API.)