Stim MPP import¶

Install the optional Stim integration before importing this module:

uv add "graphqomb[stim]"

The importer converts unsigned Stim MPP products into a graphqomb.qec.qeccode.StabilizerCode. It does not retain stabilizer signs. Consequently, signed products written with an inverted Pauli target, such as MPP !X0*Z1, raise ValueError instead of silently losing the sign.

The result also provides dense-column mappings for sparse Stim qubit ids and can map selected DETECTOR and OBSERVABLE_INCLUDE records to graph-state ancilla nodes.

Set coord_dims to the number of leading QUBIT_COORDS components to retain. The importer does not restrict this value to two or three dimensions; each referenced qubit’s final accumulated coordinate must contain at least the requested number of components. Repeated declarations are combined according to Stim’s coordinate semantics.

from graphqomb.qec.qeccode import build_graph_state
from graphqomb.qec.stim_mpp import stabilizer_code_from_stim_text

extraction = stabilizer_code_from_stim_text("MPP X0*Z2")
graph_result = build_graph_state(extraction.code)
detector_groups = extraction.detector_groups(graph_result.ancilla_nodes)

API reference¶

class graphqomb.qec.stim_mpp.StimMppExtraction[source]¶

Bases: object

Stabilizer-code data extracted from Stim MPP products.

code¶

Dense-column stabilizer code using the [Hx | Hz] convention.

Type:: StabilizerCode

stim_to_column¶

Mapping from original Stim qubit ids to dense matrix columns.

Type:: dict[int, int]

column_to_stim¶

Inverse dense-column mapping.

Type:: dict[int, int]

supports¶

Original Stim Pauli supports, one support per stabilizer row.

Type:: tuple[PauliSupport, …]

detector_rows¶

Detector groups as selected-MPP stabilizer row indices.

Type:: tuple[frozenset[int], …]

logical_observable_rows¶

Logical observables as selected-MPP stabilizer row indices.

Type:: dict[int, frozenset[int]]

detector_record_indices¶

Absolute Stim measurement-record indices for selected detectors.

Type:: tuple[frozenset[int], …]

logical_observable_record_indices¶

Absolute Stim record indices for selected logical observables.

Type:: dict[int, frozenset[int]]

detector_groups(ancilla_nodes)[source]¶

Return detector groups mapped to graph node ids for qompile.

Returns:: Detector groups suitable for qompile.
Return type:: list[set[int]]

logical_observables(ancilla_nodes)[source]¶

Return logical observables mapped to graph node ids for qompile.

Returns:: Logical-observable node groups keyed by Stim observable index.
Return type:: dict[int, set[int]]

__init__(code, stim_to_column, column_to_stim, supports, detector_rows, logical_observable_rows, detector_record_indices=(), logical_observable_record_indices=<factory>)¶

Build stabilizer-code inputs from Stim MPP layers.

graphqomb.qec.stim_mpp.stabilizer_code_from_stim_file(path, *, mpp_layer=0, coord_dims=2)[source]¶

Build a stabilizer code from MPP products in a Stim file.

Signed MPP products are not supported. A Stim target inversion such as !X0 raises ValueError because stabilizer signs are not retained.

Returns:: Extracted stabilizer code, qubit mapping, and Pauli supports.
Return type:: StimMppExtraction

graphqomb.qec.stim_mpp.stabilizer_code_from_stim_text(text, *, mpp_layer=0, coord_dims=2)[source]¶

Build a stabilizer code from MPP products in Stim text.

The selected MPP products are interpreted as a parity-check matrix using the [Hx | Hz] convention. X and Y targets set entries in Hx; Z and Y targets set entries in Hz. By default, mpp_layer=0 selects the first contiguous MPP layer. Pass mpp_layer=None to select all MPP products in the flattened Stim file. Signed MPP products are not supported because StabilizerCode does not retain stabilizer signs. A Stim target inversion such as !X0 is therefore rejected instead of being silently discarded.

Returns:: Extracted stabilizer code, qubit mapping, and Pauli supports.
Return type:: StimMppExtraction
Raises:: ValueError – If the requested MPP layer or coordinate format is invalid, or if an MPP product is signed using an inverted Pauli target.