Add Python GARI transformation

BUILD

@@ -26,6 +26,8 @@ py_wheel(
     ],
     version = "$(VERSION)",
     requires=[
+        "numpy",
+        "scipy",
         "stim",
     ],
     python_tag="$(TARGET_VERSION)",

docs/tutorial.ipynb

@@ -906,6 +906,99 @@
         "print_results(results)"
       ]
     },
+    {
+      "cell_type": "markdown",
+      "id": "2b9319e5",
+      "metadata": {
+        "id": "gari-correlated-decoding"
+      },
+      "source": [
+        "# Faster Methods of Decoding Correlated Errors with Tesseract\n",
+        "\n",
+        "## GARI\n",
+        "\n",
+        "Graph augmentation and rewiring for inference (GARI) transforms a correlated\n",
+        "CSS detector matrix into a block form for Tesseract; see [Decoding correlated\n",
+        "errors in quantum LDPC codes](https://doi.org/10.1038/s41467-026-70556-3).\n",
+        "This example reuses the superdense color-code memory-Z circuit and sampled\n",
+        "data from above, and applies the XOR prior policy."
+      ]
+    },
+    {
+      "cell_type": "code",
+      "execution_count": null,
+      "id": "fd1644de",
+      "metadata": {
+        "id": "gari-transform-example"
+      },
+      "outputs": [],
+      "source": [
+        "gari = tesseract_decoder.demutil.gari\n",
+        "\n",
+        "gari_dem, gari_layout = gari.circuit_to_gari(\n",
+        "    circuit,\n",
+        "    prior_function=gari.tesseract_xor_prior_probabilities,\n",
+        ")"
+      ]
+    },
+    {
+      "cell_type": "markdown",
+      "id": "34e07e3a",
+      "metadata": {
+        "id": "gari-syndrome-layout"
+      },
+      "source": [
+        "Sample detection events only from the original circuit. The GARI matrix DEM\n",
+        "stores the transformed matrices for decoding and is not sampled. Copy the\n",
+        "source syndrome into its physical rows; the added virtual entries stay zero."
+      ]
+    },
+    {
+      "cell_type": "code",
+      "execution_count": null,
+      "id": "d22c7d2c",
+      "metadata": {
+        "id": "gari-sample-example"
+      },
+      "outputs": [],
+      "source": [
+        "num_shots = 10\n",
+        "gari_dets = np.zeros((num_shots, gari_dem.num_detectors), dtype=bool)\n",
+        "gari_dets[:, gari_layout[\"source_to_gari\"]] = dets[:num_shots]"
+      ]
+    },
+    {
+      "cell_type": "markdown",
+      "id": "abc39564",
+      "metadata": {
+        "id": "gari-detector-order"
+      },
+      "source": [
+        "The layout is physical-then-virtual. Setting `num_det_orders=0` selects one\n",
+        "ascending detector order, so Tesseract processes the rows in that order."
+      ]
+    },
+    {
+      "cell_type": "code",
+      "execution_count": null,
+      "id": "bc0c802c",
+      "metadata": {
+        "id": "gari-decode-example"
+      },
+      "outputs": [],
+      "source": [
+        "short_beam = tesseract_decoder.make_tesseract_sinter_decoders_dict()[\n",
+        "    \"tesseract-short-beam\"\n",
+        "]\n",
+        "short_beam.num_det_orders = 0\n",
+        "gari_decoder = short_beam.compile_decoder_for_dem(dem=gari_dem).decoder\n",
+        "predicted_observables = gari_decoder.decode_batch(gari_dets)\n",
+        "logical_failures = np.count_nonzero(\n",
+        "    np.any(predicted_observables != obs[:num_shots], axis=1)\n",
+        ")\n",
+        "print(f\"Logical failures: {logical_failures}/{num_shots}\")"
+      ]
+    },
     {
       "cell_type": "markdown",
       "metadata": {

docs/tutorial.py

@@ -344,6 +344,51 @@ def run_tesseract_decoder(decoder, dets, obs):
 results = run_tesseract_decoder(tesseract_config2.compile_decoder(), dets, obs)
 print_results(results)
 
+# %% [markdown] id="gari-correlated-decoding"
+# # Faster Methods of Decoding Correlated Errors with Tesseract
+#
+# ## GARI
+#
+# Graph augmentation and rewiring for inference (GARI) transforms a correlated
+# CSS detector matrix into a block form for Tesseract; see [Decoding correlated
+# errors in quantum LDPC codes](https://doi.org/10.1038/s41467-026-70556-3).
+# This example reuses the superdense color-code memory-Z circuit and sampled
+# data from above, and applies the XOR prior policy.
+
+# %% id="gari-transform-example"
+gari = tesseract_decoder.demutil.gari
+
+gari_dem, gari_layout = gari.circuit_to_gari(
+    circuit,
+    prior_function=gari.tesseract_xor_prior_probabilities,
+)
+
+# %% [markdown] id="gari-syndrome-layout"
+# Sample detection events only from the original circuit. The GARI matrix DEM
+# stores the transformed matrices for decoding and is not sampled. Copy the
+# source syndrome into its physical rows; the added virtual entries stay zero.
+
+# %% id="gari-sample-example"
+num_shots = 10
+gari_dets = np.zeros((num_shots, gari_dem.num_detectors), dtype=bool)
+gari_dets[:, gari_layout["source_to_gari"]] = dets[:num_shots]
+
+# %% [markdown] id="gari-detector-order"
+# The layout is physical-then-virtual. Setting `num_det_orders=0` selects one
+# ascending detector order, so Tesseract processes the rows in that order.
+
+# %% id="gari-decode-example"
+short_beam = tesseract_decoder.make_tesseract_sinter_decoders_dict()[
+    "tesseract-short-beam"
+]
+short_beam.num_det_orders = 0
+gari_decoder = short_beam.compile_decoder_for_dem(dem=gari_dem).decoder
+predicted_observables = gari_decoder.decode_batch(gari_dets)
+logical_failures = np.count_nonzero(
+    np.any(predicted_observables != obs[:num_shots], axis=1)
+)
+print(f"Logical failures: {logical_failures}/{num_shots}")
+
 # %% [markdown] id="BoEALeo3OYGp"
 # # Decoding Wild Stabilizer Codes under Code Capacity Noise with Tesseract
 #

src/py/README.md

@@ -678,3 +678,48 @@ nice_calibrated_dem = demutil.regeneralize_spatial_dem(
 )
 # Result will have error probability (0.1 + 0.2) / 2 = 0.15
 ```
+
+#### GARI transformed matrices
+
+`demutil.gari.circuit_to_gari` converts a supported correlated CSS Stim
+circuit into a GARI matrix DEM and companion layout for Tesseract. It
+generates a flattened source DEM with `decompose_errors=False`. Detectors must
+follow the repository's fourth-coordinate convention: values `0`–`2` identify
+X detectors and `3`–`5` identify Z detectors.
+
+```python
+import stim
+from tesseract_decoder import demutil
+
+circuit = stim.Circuit.from_file("circuitFile.stim")
+gari_dem, gari_layout = demutil.gari.circuit_to_gari(
+    circuit,
+    prior_function=demutil.gari.tesseract_xor_prior_probabilities,
+)
+```
+
+`circuit_to_gari` returns:
+
+* `gari_dem`: the augmented detector and logical matrices stored using Stim
+  DEM syntax.
+* `gari_layout`: a `tesseract.gari_layout.v1` dictionary containing the source
+  and GARI detector counts, the `source_to_gari` detector mapping, and the
+  `physical_then_virtual` detector order.
+
+Related public APIs:
+
+* `demutil.gari.dem_to_matrices(dem)` returns the sparse detector matrix,
+  sparse logical matrix, and one probability per source error column.
+* `demutil.gari.GariTransform` is passed to prior-policy callbacks. It exposes
+  the transformed detector and logical matrices, the `U` and `V` projection
+  matrices, the source `e_Z`, `e_X`, and `e_Y` column indices, and the source
+  detector mapping.
+* `paper_prior_probabilities`, `tesseract_xor_prior_probabilities`, and
+  `tesseract_lp_max_barred_cost_prior_probabilities` return one probability for
+  each transformed GARI column. A user-defined prior can follow the same
+  callable interface.
+
+The returned GARI matrix DEM stores transformed matrices for decoding and must
+not be sampled. Sample from the original circuit and use the companion layout
+to place its physical syndrome. See the
+[GARI tutorial](../../docs/tutorial.ipynb) for a complete decoding example.

src/py/_tesseract_py_util/BUILD

@@ -8,6 +8,21 @@ py_library(
     deps = [
         "@pypi//stim",
         "@pypi//numpy",
+        "@pypi//scipy",
+    ],
+)
+
+py_test(
+    name = "gari_test",
+    srcs = ["gari_test.py"],
+    imports = ["..", ".", "../.."],
+    visibility = ["//:__subpackages__"],
+    deps = [
+        ":_tesseract_py_util",
+        "@pypi//numpy",
+        "@pypi//pytest",
+        "@pypi//stim",
+        "//src:lib_tesseract_decoder",
     ],
 )
 

src/py/_tesseract_py_util/__init__.py

@@ -17,6 +17,7 @@
 and related utilities, in `decompose_errors.py` and `generalize_dem.py`.
 """
 
+from _tesseract_py_util import gari as gari
 from _tesseract_py_util.demutil import decompose_errors
 from _tesseract_py_util.generalize_dem import \
     generalize as regeneralize_spatial_dem

src/py/_tesseract_py_util/demutil_test.py

@@ -32,6 +32,7 @@ def test_import_exposes_demutil_submodule():
     assert hasattr(tesseract_decoder, "demutil")
     assert hasattr(demutil, "regeneralize_spatial_dem")
     assert hasattr(demutil, "decompose_errors")
+    assert hasattr(demutil.gari, "circuit_to_gari")
 
 
 def test_decompose_errors_rejects_unknown_method():