Stim Clifford parser

Install the optional Stim integration before importing this module:

uv add "graphqomb[stim]"

The parser normalizes Stim Clifford circuits to GraphQOMB’s unitary basis: the four Clifford J(angle) gates plus CZ. Each single-qubit basis gate is one graphqomb.gates.J primitive, i.e. one XY-plane Pauli measurement in MBQC (gate names use algebraic matrix order):

Basis gate	Definition	Measurement	Stim name
H	J(0)	X+	H
HS	H S = J(pi/2)	Y+	C_XNYZ
HZ	H Z = J(pi)	X-	SQRT_Y
HS_DAG	H S† = J(-pi/2)	Y-	C_XYZ

from graphqomb.stim_parser import transpile

normalized = transpile("S_DAG 0\nCX 0 1", optimize=True)

The parser supports all fixed one- and two-qubit Clifford gates exposed by Stim, arbitrary-length SPP and SPP_DAG rotations, nested REPEAT blocks, Pauli reset and measurement boundaries, and coordinate/TICK annotations. DETECTOR, OBSERVABLE_INCLUDE, and MPAD are preserved verbatim as optimization barriers; the standalone parser does not interpret their measurement-record targets. Noise, non-Clifford instructions, measurement-reset instructions, MPP measurements, and classically controlled targets are rejected.

Hermitian SPP products may contain the same qubit more than once. Their ordered Pauli factors and target inversions retain Stim’s product semantics.

With optimize=True, every maximal single-qubit gate run is replaced by the shortest equivalent word over the four J gates, so any single-qubit Clifford costs at most three J primitives (three graph nodes in the compiled pattern). Optimization repeatedly scans a barrier-free block, so very large circuits without TICK or annotation barriers can take superlinear time. The importer normalizes each unitary TICK block independently, so TICK-partitioned inputs bound this cost.

The Stim importer resolves the preserved detector and observable records, handles MPP operations, and applies GraphQOMB’s circuit-level noise policy.

API reference

Transpile Stim Clifford circuits into GraphQOMB’s Clifford J/CZ basis.

exception graphqomb.stim_parser.UnsupportedInstructionError

Bases: ValueError

Raised when an instruction cannot be represented by the supported basis.

graphqomb.stim_parser.optimize_j_cz(circuit)

Remove redundant Clifford J and CZ gates.

Every maximal run of single-qubit basis gates on one qubit is replaced by the shortest word over the four Clifford J gates (H, HS, HZ, HS_DAG) with the same Clifford action; any single-qubit Clifford needs at most three J gates. CZ pairs cancel across commuting operations on other qubits. Single-qubit gates at R/RX/RY and M/MX/MY boundaries are folded into Pauli preparations or measurements when safe. TICK, coordinate annotations, DETECTOR, OBSERVABLE_INCLUDE, and MPAD are preserved verbatim and treated as optimization barriers. The repeated simplification passes are intended for TICK-bounded blocks; unusually large barrier-free inputs can take superlinear time.

Returns:

The optimized circuit.

Return type:

stim.Circuit

graphqomb.stim_parser.transpile(circuit, *, optimize=False)

Transpile a Stim Clifford circuit into the Clifford J/CZ gate basis.

The single-qubit basis gates are the four Clifford J(angle) gates, i.e. the XY-plane Pauli measurements: H = J(0) (X+), HS = J(pi/2) (Y+, Stim’s C_XNYZ), HZ = J(pi) (X-, Stim’s SQRT_Y), and HS_DAG = J(-pi/2) (Y-, Stim’s C_XYZ).

Parameters:

• circuit (stim.Circuit | str) – A Stim circuit or Stim circuit text. REPEAT blocks are handled recursively. TICK, QUBIT_COORDS, SHIFT_COORDS, DETECTOR, OBSERVABLE_INCLUDE, and MPAD instructions are preserved verbatim because they do not affect the quantum operation. Measurement-record targets are not interpreted by this standalone parser.

• optimize (bool, optional) – Remove redundant basis gates and simplify gates adjacent to R/RX/RY and M/MX/MY boundaries after transpilation.

Returns:

A new circuit containing only Clifford J gates, CZ, supported boundaries, and preserved instructions.

Return type:

stim.Circuit