Use this file to discover all available pages before exploring further.
A .stim file is a UTF-8 encoded, human-readable specification of an annotated stabilizer circuit. It describes the gates applied to qubits, any noise processes to include during simulation, and annotations that enable detection-event sampling, circuit drawing, and spacetime layout hints. The file format is executed top-to-bottom, one instruction at a time.
Stim circuit files are always encoded using UTF-8. Non-ASCII characters may only appear inside comments and inside instruction tags; they are not valid in gate names, arguments, or targets.
A .stim file is a sequence of lines. Each line is one of:
Blank — ignored
Instruction — a gate applied to targets
Block initiator — an instruction followed by { on the same line
Block terminator — a } on its own line
Lines may be indented with spaces or tabs, and may end with a comment beginning with #. Indentation and comments are purely decorative and carry no semantic meaning.
Inside a tag, the following characters must be escaped:
Character
Escape sequence
]
\C
\r (carriage return)
\r
\n (line feed)
\n
\ (backslash)
\B
Tags have no effect on circuit execution. They are intended for use by external tools — for example, a noise-insertion tool might read TICK[100ns] to learn the duration of a time step.
A qubit target is a non-negative integer identifying a qubit by index. Qubits are implicitly allocated; the number of qubits is determined by the largest qubit index referenced in the file.
<QUBIT_TARGET> ::= '!'? <uint>
A ! prefix inverts the recorded measurement result for that qubit. For example, M 0 !1 measures qubit 0 and qubit 1, recording the result for qubit 1 as flipped.
# Measure qubit 0 normally and qubit 1 with inverted resultM 0 !1
A measurement record target references a past measurement result relative to the current end of the measurement record. rec[-1] is the most recent result, rec[-2] is the second most recent, and so on. Negative indices match Python list semantics, which allows loops to reference measurements without knowing absolute positions.
It is an error to reference a result so far back that it would precede the start of the circuit.
# Feed forward: apply CZ conditioned on the most recent measurementM 0CZ rec[-1] 5# Classical correction in quantum teleportationM 0 1CZ rec[-2] 99CNOT rec[-1] 99
A sweep bit target references a column of a per-shot configuration table. It allows the same circuit to behave differently across shots — for example, recording which spin-echo operations were applied.
<SWEEP_BIT_TARGET> ::= "sweep[" <uint> "]"
Sweep bits default to False when no table is provided, and bits beyond the end of the provided table also default to False.
# Apply X to qubit 1 for shots where sweep bit 5 is setCNOT sweep[5] 1
A Pauli target is a qubit index prefixed by X, Y, or Z. Pauli targets are used with instructions like CORRELATED_ERROR and MPP to specify Pauli product operators. Multiple Pauli targets in a product are joined with * combiners. A ! prefix inverts the measurement result for that product group.
When a gate receives more targets than a single application requires, it is broadcast over those targets.
Single-qubit gates — applied to each target in order. H 0 1 2 is equivalent to H 0 then H 1 then H 2.
Two-qubit gates — applied to aligned target pairs in order. CNOT 0 1 2 3 is equivalent to CNOT 0 1 then CNOT 2 3. Giving a two-qubit gate an odd number of targets is an error.
# Broadcast H over three qubitsH 0 1 2# Broadcast CNOT over two pairsCNOT 0 1 2 3# Broadcast depolarizing noise over pairsDEPOLARIZE2(0.001) 0 1 2 3
A Stim simulator executing a circuit tracks three things:
The qubits — all start in the |0⟩ state. The qubit count is inferred from the largest qubit index in the circuit.
The measurement record — an immutable append-only log of all measurement results. Referenced by rec[-n] targets.
The “correlated error occurred” flag — a hidden boolean used by ELSE_CORRELATED_ERROR to condition on whether the preceding CORRELATED_ERROR fired.
An optional coordinate offset, accumulated by SHIFT_COORDS, affects DETECTOR coordinate arguments and QUBIT_COORDS annotations but has no effect on simulation results.
A REPEAT K { ... } block repeats its body exactly K times. K must be a positive integer — REPEAT 0 is a syntax error because it creates ambiguity about whether detectors and observables declared inside the block exist.
This circuit distributes a Bell pair, performs a Bell-basis measurement on the sender’s side, and applies feed-forward corrections to the receiver’s qubit (qubit 99).
# Distribute a Bell Pair.H 0CNOT 0 99# Sender creates an arbitrary qubit state to send.H 1S 1# Sender performs a Bell Basis measurement.CNOT 0 1H 0M 0 1 # Measure both of the sender's qubits.# Receiver performs frame corrections based on measurement results.CZ rec[-2] 99CNOT rec[-1] 99
Repetition code
This circuit measures the parities of adjacent data qubits (0, 2, 4, 6) using measurement qubits (1, 3, 5), then repeats 1000 more rounds. The DETECTOR annotations declare detection events and the OBSERVABLE_INCLUDE annotation declares the logical observable.
# Measure the parities of adjacent data qubits.# Data qubits are 0, 2, 4, 6.# Measurement qubits are 1, 3, 5.CNOT 0 1 2 3 4 5CNOT 2 1 4 3 6 5MR 1 3 5# Annotate that the measurements should be deterministic.DETECTOR rec[-3]DETECTOR rec[-2]DETECTOR rec[-1]# Perform 1000 more rounds of measurements.REPEAT 1000 { CNOT 0 1 2 3 4 5 CNOT 2 1 4 3 6 5 MR 1 3 5 # Annotate that measurements should agree with previous round. DETECTOR rec[-3] rec[-6] DETECTOR rec[-2] rec[-5] DETECTOR rec[-1] rec[-4]}# Measure data qubits.M 0 2 4 6# Annotate final detectors.DETECTOR rec[-3] rec[-4] rec[-7]DETECTOR rec[-2] rec[-3] rec[-6]DETECTOR rec[-1] rec[-2] rec[-5]# Declare logical observable.OBSERVABLE_INCLUDE(0) rec[-1]
Noisy repetition code (annotated)
This is the output of stim --gen repetition_code --task memory --rounds 1000 --distance 3 --after_clifford_depolarization 0.001. It shows noise operations, TICK separators, and coordinate annotations.
