Added demutils (#198)

### Add `demutils` Python utilities for DEM manipulation

This PR introduces a new set of Python utilities under
`tesseract_decoder.demutil` to support flexible manipulation of Stim
**`DetectorErrorModel` (DEM)** objects used in decoding workflows. This
PR exposes decomposition and generalization of detector error models.

The changes include:
- Added a new `demutil.py` module providing access to functions such as:
- `decompose_errors(...)` for breaking complex error mechanisms into
simpler component-level errors
- `regeneralize_spatial_dem(...)` for recombining error probabilities
across multiple templates into a scaffold DEM
- Update Python build definitions and test targets to include the new
module
- Extend `src/py/README.md` with documentation describing the new API
and usage patterns

Exposing these utilities enable more expressive and reusable DEM
preprocessing within the Tesseract Python interface, making it easier to
experiment with decoder configurations and integrate Stim-based error
models into downstream decoding pipelines.

Author: LalehB

.gitignore

@@ -14,6 +14,7 @@
 /.idea/
 /.ijwb/
 /.project
+__pycache__/
 /.settings
 /.vscode/
 .eclipse/
@@ -22,6 +23,7 @@
 .project
 eclipse-*bin/
 /bazel.iml
+*.pyc
 # Ignore all bazel-* symlinks. There is no full list since this can change
 # based on the name of the directory bazel is cloned into.
 /bazel-*

MODULE.bazel

@@ -25,6 +25,7 @@ pip.parse(
     hub_name = "pypi",
     python_version = DEFAULT_PYTHON_VERSION,
     requirements_lock = "//src/py:requirements_lock.txt",
+    extra_pip_args = ["--index-url=https://pypi.org/simple"],
 )
 
 use_repo(pip, "pypi")

src/BUILD

@@ -95,6 +95,7 @@ py_library(
     imports=["src"],
     deps=[
         ":tesseract_decoder",
+        "//src/py:demutil",
     ],
 )
 

src/py/BUILD

@@ -27,6 +27,18 @@ py_library(
         "//src:lib_tesseract_decoder",
     ],
 )
+
+py_library(
+    name = "demutil",
+    srcs = ["demutil.py", "generalize_dem.py"],
+    visibility = ["//:__subpackages__"],
+    deps = [
+        ":decompose_errors",
+        "@pypi//stim",
+        "@pypi//numpy",
+    ],
+)
+
 py_test(
     name = "common_test",
     srcs = ["common_test.py"],
@@ -84,6 +96,39 @@ py_test(
     ],
 )
 
+
+py_library(
+    name = "decompose_errors",
+    srcs = ["decompose_errors.py"],
+    visibility = ["//:__subpackages__"],
+    deps = [
+        "@pypi//stim",
+    ],
+)
+
+py_test(
+    name = "decompose_errors_test",
+    srcs = ["decompose_errors_test.py"],
+    visibility = ["//:__subpackages__"],
+    deps = [
+        ":decompose_errors",
+        "@pypi//pytest",
+        "@pypi//stim",
+    ],
+)
+
+
+py_test(
+    name = "demutil_test",
+    srcs = ["demutil_test.py"],
+    visibility = ["//:__subpackages__"],
+    deps = [
+        "@pypi//pytest",
+        "@pypi//stim",
+        "//src:lib_tesseract_decoder",
+    ],
+)
+
 compile_pip_requirements(
     name = "requirements",
     src = "requirements.in",

src/py/README.md

@@ -569,4 +569,68 @@ print("Basic sample_decode Results:")
 print(f"Shots run: {result.shots}")
 print(f"Observed errors: {result.errors}")
 print(f"Logical error rate: {result.errors / result.shots}")
-```
+```
+### `tesseract_decoder.demutil` Module
+The `tesseract_decoder.demutil` module provides utilities for manipulating `stim.DetectorErrorModel` objects, specifically for decomposing complex error mechanisms into simpler components and regeneralizing spatial error models.
+
+#### Functions
+* `demutil.decompose_errors(dem: stim.DetectorErrorModel, method: str) -> stim.DetectorErrorModel`
+  * Decomposes error mechanisms in a DEM into simpler components based on the specified method.
+  * Supported methods:
+    * `"stim-surfacecode-coords"`: Decomposes errors based on the spatial coordinates of detectors, assuming a surface code layout where coordinates indicate X or Z basis.
+    * `"last-coordinate-index"`: Decomposes errors using the last coordinate of the detector as the component identifier.
+  * **Note:** For decomposition to work, the DEM must contain "atomic" errors (errors involving only one component) that explain the components of the complex errors.
+
+**Example Usage**:
+
+```python
+import tesseract_decoder.demutil as demutil
+import stim
+
+dem = stim.DetectorErrorModel("""
+    detector(0, 0, 0) D0
+    detector(0, 0, 1) D1
+    # Atomic errors for decomposition reference
+    error(0.01) D0
+    error(0.01) D1
+    # Complex error to decompose
+    error(0.1) D0 D1
+""")
+
+# Re-decompose the errors assuming Stim surface code coordinate convention
+nice_matchable_dem = demutil.decompose_errors(dem, method='stim-surfacecode-coords')
+
+# Re-decompose the errors assuming the last-coordinate index indicates the component:
+nice_matchable_dem2 = demutil.decompose_errors(dem, method='last-coordinate-index')
+```
+
+* `demutil.regeneralize_spatial_dem(templates: list[stim.DetectorErrorModel], scaffold: stim.DetectorErrorModel, verbose: bool = False) -> stim.DetectorErrorModel`
+  * Updates the error probabilities in a `scaffold` DEM by averaging probabilities from matching errors in a list of `template` DEMs. Errors are matched based on their spatial geometry (relative coordinates of detectors).
+  * **Important:** The scaffold errors must have the same structure and **same absolute coordinates** (for the first detector) as the template errors to be matched.
+
+**Example Usage**:
+
+```python
+import tesseract_decoder.demutil as demutil
+import stim
+
+# Take one or more DEMs **with detector coordinates**, aggregate the error probabilities
+template1 = stim.DetectorErrorModel("""
+    detector(0, 0) D0
+    error(0.1) D0
+""")
+template2 = stim.DetectorErrorModel("""
+    detector(0, 0) D0
+    error(0.2) D0
+""")
+scaffold = stim.DetectorErrorModel("""
+    detector(0, 0) D1
+    error(0.99) D1
+""")
+
+nice_calibrated_dem = demutil.regeneralize_spatial_dem(
+    templates=[template1, template2],
+    scaffold=scaffold
+)
+# Result will have error probability (0.1 + 0.2) / 2 = 0.15
+```

src/py/decompose_errors.py

@@ -1,3 +1,17 @@
+# Copyright 2025 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http:#www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
 import stim
 from functools import reduce
 import itertools

src/py/decompose_errors_test.py

@@ -2,7 +2,7 @@
 from collections.abc import Iterable
 import stim
 
-from decompose_errors import (
+from src.py.decompose_errors import (
     reduce_symmetric_difference,
     reduce_set_symmetric_difference,
     get_component_obs_matching_undecomposed_obs,

src/py/demutil.py

@@ -0,0 +1,65 @@
+# Copyright 2025 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http:#www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""
+This module is a dispatcher for DEMfunctionality such as decomposition and re-generalization,
+and related utilities, in `decompose_errors.py` and `generalize_dem.py`.
+"""
+
+
+import stim
+
+from .decompose_errors import (
+    reduce_symmetric_difference as reduce_symmetric_difference,
+    reduce_set_symmetric_difference as reduce_set_symmetric_difference,
+    undecomposed_error_detectors_and_observables as undecomposed_error_detectors_and_observables,
+    get_component_obs_matching_undecomposed_obs as get_component_obs_matching_undecomposed_obs,
+    decompose_errors_using_detector_assignment as decompose_errors_using_detector_assignment,
+    decompose_errors_using_detector_coordinate_assignment as decompose_errors_using_detector_coordinate_assignment,
+    detector_coord_to_basis_for_stim_surface_code_convention as detector_coord_to_basis_for_stim_surface_code_convention,
+    decompose_errors_using_last_coordinate_index as decompose_errors_using_last_coordinate_index,
+    decompose_errors_for_stim_surface_code_coords as decompose_errors_for_stim_surface_code_coords,
+    undecompose_errors as undecompose_errors,
+)
+from .generalize_dem import generalize as regeneralize_spatial_dem
+
+
+__all__ = [
+    "decompose_errors",
+    "regeneralize_spatial_dem",
+    "reduce_symmetric_difference",
+    "reduce_set_symmetric_difference",
+    "undecomposed_error_detectors_and_observables",
+    "get_component_obs_matching_undecomposed_obs",
+    "decompose_errors_using_detector_assignment",
+    "decompose_errors_using_detector_coordinate_assignment",
+    "detector_coord_to_basis_for_stim_surface_code_convention",
+    "decompose_errors_using_last_coordinate_index",
+    "decompose_errors_for_stim_surface_code_coords",
+    "undecompose_errors",
+]
+
+
+def decompose_errors(
+    dem: stim.DetectorErrorModel, method: str = "stim-surfacecode-coords"
+) -> stim.DetectorErrorModel:
+    """Dispatch decomposition strategy by method name."""
+    if method == "stim-surfacecode-coords":
+        return decompose_errors_for_stim_surface_code_coords(dem)
+    if method == "last-coordinate-index":
+        return decompose_errors_using_last_coordinate_index(dem)
+    raise ValueError(
+        "Unknown decomposition method "
+        f"{method!r}. Expected 'stim-surfacecode-coords' or 'last-coordinate-index'."
+    )