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 initial Pauli resets, 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.

Every unitary block is normalized by graphqomb.stim_parser to the four Clifford J(angle) gates (H = J(0), HS = J(pi/2), HZ = J(pi), HS_DAG = J(-pi/2), corresponding to X+/Y+/X-/Y- measurements) plus CZ before graph conversion. This accepts all fixed one- and two-qubit Clifford gates exposed by Stim as well as SPP and SPP_DAG. Each basis gate becomes one GraphQOMB J primitive.

Initial reset instructions¶

Leading reset instructions determine the positive Pauli eigenstate used for an input: R/RZ initializes Z+, RX initializes X+, and RY initializes Y+. A reset is initial when its target qubit has not previously participated in a unitary or measurement operation. Operations on other qubits do not prevent a later initial reset. Repeated leading resets are accepted, and the last reset on each qubit determines its initialization state.

Leading resets are normalized together with the Clifford gates in their TICK block. When the resulting state is a positive Pauli eigenstate, the gates are absorbed into R, RX, or RY before graph construction. For example, R followed by H becomes RX and does not add a gate node or shift that input to an earlier z layer.

Stim canonicalizes the Z-axis aliases internally, so the importer accepts both M and MZ for Z measurement and both R and RZ for Z reset. Stim export uses MZ for Z measurement and R for Z reset.

Mid-circuit resets are rejected because GraphQOMB patterns do not currently represent multiple lifetimes for one logical qubit. Combined measurement-reset instructions (MR/MRZ, MRX, and MRY) remain unsupported.

Single-qubit measurements assign an AxisMeasBasis directly to the measured data-lane endpoint without replacing that node or its coordinate. 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. A measured qubit cannot begin a new lifetime later in the circuit.

The first two components of QUBIT_COORDS are used as the fixed spatial (x, y) position of each data lane. The importer supplies the temporal z component. Every unitary TICK block is transpiled before placement. Its input layer starts at the preceding block’s output z, and all of its output nodes share the maximum transpiled depth of the block. A shorter data-wire chain is spread across that same interval. A live qubit with no operation in the block remains a single input/output node and is relocated directly to the common output layer; this adds no graph node or edge and does not change the circuit semantics.

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. Within a combined block, local stabilizer interactions are ordered Z -> Y -> X on each shared data qubit. If an odd number of shared-data-qubit pairs reverse the order of the same two stabilizers, the graph-state builder adds the required CZ edge between their ancillas. This rule is applied automatically for both Type I and Type II foliation.

Only data-wire nodes contribute to the X-correction flow; MPP ancilla nodes do not produce X corrections. After composing all graph fragments, the importer derives the Z-correction flow from the odd neighborhood of the complete X-correction flow. Both correction maps are passed directly to qompile() without Pauli simplification or an importer-specific fallback. 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.

An MPP block starts at the preceding gate or MPP output layer and ends two z units later. Live lanes not used by that MPP block are relocated to the same output layer without adding nodes. Consequently, a composed output and the next active fragment input have the same z coordinate, and imported patterns do not mix 2D spatial coordinates with 3D spacetime coordinates.

The flattened ideal circuit is normalized before measurement-record analysis. The original qubit inventory is retained even when a unitary block optimizes to the identity. 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.

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

result = stim_text_to_pattern(
    """
    RY 0
    R 1 2
    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[source]¶

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)[source]¶

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)[source]¶

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)[source]¶

Import a supported Stim circuit into a GraphQOMB pattern.

The importer supports initial Pauli resets, Clifford unitary blocks, and Pauli measurement blocks. Stim R, RX, and RY instructions are imported as positive Z-, X-, and Y-eigenstate input initialization, respectively, when they occur before any other quantum operation on the target qubit. Adjacent Clifford gates are folded into those initial Pauli states when possible. 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.