Stim circuit import

Install the optional Stim integration before importing this module:

uv add "graphqomb[stim]"

The circuit importer converts supported Stim circuits into GraphQOMB measurement patterns. It accepts Clifford unitary blocks and Pauli measurement blocks separated by TICK. The supported Pauli measurement instructions are M/MZ, MX, MY, MXX, MYY, MZZ, and MPP.

Single-qubit measurements assign an AxisMeasBasis directly to the measured graph node. They do not create an MPP extraction or an ancillary parity measurement node. Inverted single-qubit measurement targets select the minus sign of that node’s basis. A direct single-qubit measurement terminates that qubit’s lifetime: a later quantum operation on the same qubit is rejected, while operations on other qubits may continue. Reset and qubit reuse are not supported.

Two-qubit measurements are parity measurements and are lowered to equivalent unsigned MPP products. Inverted targets in MXX, MYY, MZZ, and MPP are rejected because GraphQOMB does not currently retain the corresponding parity offset.

All MPP instructions within one TICK block are represented by one combined extraction and are validated to commute. Anticommuting products in the same block are rejected. The importer uses one compact stabilizer-measurement unit when its correction flow is causal. If the compact unit has a cyclic Pauli flow, the commuting products are lowered to equivalent sequential units instead. Non-commuting measurements must be separated by TICK in the source circuit. Each unit has a distinct unmeasured output layer, which is composed with the next unitary or measurement fragment by qubit index. Pass y_foliation=YFoliation.TYPE_II to any of the three import entry points to use the three-layer Y-measurement construction; Type I is the default.

The flattened ideal circuit is analyzed once for measurement records. Records from single-qubit measurements, pair measurements, MPP, and ideal-zero MPAD replacements share one absolute index space. DETECTOR and OBSERVABLE_INCLUDE targets are resolved against that whole-circuit index space, and each StimMppExtraction retains the corresponding absolute record sets even when an annotation also references records outside that MPP unit.

Noise policy

Circuit-level Stim noise is intentionally not imported. GraphQOMB applies noise to the compiled MBQC pattern through its own noise-model API, where preparation, entanglement, measurement, and idle events differ from the source circuit operations.

Pure noise instructions are omitted during import. Error probabilities attached to Pauli measurements are also omitted while retaining the ideal measurement. Heralded noise records are retained as ideal zero-valued record positions so that later DETECTOR and OBSERVABLE_INCLUDE references remain aligned.

Reset instructions (R/RZ, RX, and RY) and combined measurement-reset instructions (MR/MRZ, MRX, and MRY) are not handled by this importer. Consequently, a directly measured qubit cannot begin a new lifetime later in the circuit.

from graphqomb.qec.qeccode import YFoliation
from graphqomb.stim_importer import stim_text_to_pattern

result = stim_text_to_pattern(
    """
    MX 0
    MYY 1 2
    DETECTOR rec[-2] rec[-1]
    """,
    y_foliation=YFoliation.TYPE_II,
)
pattern = result.pattern

API reference

Import supported Stim circuits into GraphQOMB patterns.

class graphqomb.stim_importer.StimImportResult

Bases: object

Result of importing a supported Stim circuit.

__init__(pattern, stim_to_qubit, qubit_to_stim, mpp_extractions)

graphqomb.stim_importer.stim_file_to_pattern(path, *, coord_dims=2, schedule_strategy=CircuitScheduleStrategy.PARALLEL, y_foliation=YFoliation.TYPE_I)

Import a supported Stim file into a GraphQOMB pattern.

Returns:

Imported pattern, qubit mapping, and MPP extraction metadata.

Return type:

StimImportResult

graphqomb.stim_importer.stim_text_to_pattern(text, *, coord_dims=2, schedule_strategy=CircuitScheduleStrategy.PARALLEL, y_foliation=YFoliation.TYPE_I)

Import supported Stim text into a GraphQOMB pattern.

Returns:

Imported pattern, qubit mapping, and MPP extraction metadata.

Return type:

StimImportResult

graphqomb.stim_importer.stim_circuit_to_pattern(circuit, *, coord_dims=2, schedule_strategy=CircuitScheduleStrategy.PARALLEL, y_foliation=YFoliation.TYPE_I)

Import a supported Stim circuit into a GraphQOMB pattern.

The importer supports Clifford unitary blocks and Pauli measurement blocks. Stim noise instructions and measurement-error probabilities are omitted because circuit-level noise is outside the GraphQOMB import model. Pauli measurement blocks must be separated from unitary blocks by TICK. A direct single-qubit measurement terminates that qubit’s lifetime; other qubits may continue, but the measured qubit cannot be used by a later operation.

Returns:

Imported pattern, qubit mapping, and MPP extraction metadata.

Return type:

StimImportResult

Raises:

ValueError – If the circuit uses unsupported instructions or invalid coordinates.