Feature: Add utility to decompose Stim Detector Error Models

[oscarhiggott]

Summary

This PR introduces a new module src/py/decomposer/decompose_errors.py that provides functionality to decompose stim.DetectorErrorModel (DEM) error instructions into independent components (e.g., separating X-basis and Z-basis errors in surface code simulations). It also includes the inverse operation (undecompose_errors) to flatten decomposed errors back into their atomic representation. While stim has a generic inbuilt decomposer that does not require detector annotations, it is often suboptimal. The purpose of this PR is to provide a more robust implementation, that requires detector annotations.

This utility allows users to:

1. Define components based on detector coordinates or IDs.
2. Automatically split composite errors into component-specific parts using the ^ separator (e.g., converting error(p) D0 D1 into error(p) D0 ^ D1).
3. Ensure logical observables are correctly assigned to the appropriate component during splitting.

Key Changes

src/py/decomposer/decompose_errors.py

• decompose_errors_using_detector_assignment: Core logic that iterates through a flattened DEM. It identifies "atomic" errors (those affecting only one component) and uses them to reconstruct valid decompositions for "composite" errors.
• decompose_errors_for_stim_surface_code_coords: A specialized helper that decomposes errors based on standard surface code checkerboard coordinates (separating X and Z parity checks).
• undecompose_errors: A utility to merge separated error components back into a single instruction, useful for verification and round-tripping.
• Helper functions: reduce_symmetric_difference and get_component_obs_matching_undecomposed_obs to handle the constraint satisfaction required to assign observables to the correct component.

src/py/decomposer/decompose_errors_test.py

• Added unit tests for helper functions.
• Added integration tests for 2-component and 3-component decomposition scenarios.
• Added negative tests ensuring ValueError is raised if an error cannot be validly decomposed (e.g., missing atomic components or inconsistent observables).
• Added a round-trip test (decompose -> undecompose) using a generated surface_code:rotated_memory_x circuit to ensure data integrity.

Example Usage

import stim
from src.py.decomposer.decompose_errors import decompose_errors_using_last_coordinate_index

# A DEM where D0 (coord 0) and D1 (coord 1) are triggered by a single error
dem = stim.DetectorErrorModel("""
    detector(0) D0
    detector(1) D1
    error(0.1) D0 D1 L0
""")

# Decompose based on the last coordinate
# This splits the error into parts while maintaining the total logical effect
result = decompose_errors_using_last_coordinate_index(dem)
# Output: error(0.1) D0 ^ D1 L0

[noajshu]

Thank you Oscar for the corrected implementation! This will be very helpful.