Circuit and loss instructions
Circuit syntax
A .stim file contains one instruction per line: NAME(arguments) targets. Arguments and targets depend on the instruction. # introduces a comment; REPEAT N { ... } repeats a block. Qubit targets are zero-based integers. Use rstim circuit stats --in circuit.stim to parse a file and inspect its measurement, detector and observable counts.
| Instruction | Role | Example |
|---|---|---|
R, RX, RY | Prepare a qubit in a Pauli basis; restores a lost atom | R 0 1 |
H, S, CX, CZ | Clifford evolution on available qubits | CX 0 1 |
X_ERROR(p), DEPOLARIZE1(p), DEPOLARIZE2(p) | Stochastic Pauli noise | X_ERROR(0.01) 0 |
M, MX, MY, MR | Measure, optionally reset | M 0 1 |
DETECTOR | Declare a measurement parity relative to the noiseless reference | DETECTOR rec[-1] |
OBSERVABLE_INCLUDE(k) | Add measurement parity to logical observable k | OBSERVABLE_INCLUDE(0) rec[-1] |
TICK, coordinates | Timing and drawing annotations | TICK |
A record target rec[-k] refers to the kth most recent stored bit at that point in execution. It is not a qubit index. Each detector and observable computes a parity; these declarations do not perform another measurement. The Get started circuit explains the example step by step.
RustQEC reads Stim-style syntax. Accepted instructions vary by execution, analysis, export and decoder; see the support contract. For shared instructions, consult Stim's gate reference.
OpenQASM 2.0 conversion
Enable the optional qasm feature to import QASM 2.0 into a checked semantic
document or export the supported native instruction subset. Declarations,
register operands, gate definitions and parameter expressions are checked before
lowering. Measurement, reset and single-bit Pauli feedback execute in order;
T gates and general rotations require an explicit near-Clifford backend.
Keep the semantic JSON document for register names and classical destinations. Native Stim text is an execution projection. Noise, loss and unsupported quantum operations are rejected on QASM export; QEC annotation omission is explicit and reported. Follow the QASM round-trip tutorial and its support matrix.
Atom-loss extensions
The simulator uses a gate-cancellation model: LOSS(p) q... independently removes each still-present target with probability p, and loss persists until reset. Ideal single-qubit gates do nothing to absent atoms; a two-qubit interaction is skipped if either partner is absent. DEPOLARIZE2 also skips an incomplete pair.
M and ML both measure in the Z basis when the atom is present. Their stored records differ: M writes one value bit, while ML writes a loss flag followed by a value bit for each target. For plain, uninverted readout in this simulator:
| Instruction | Atom present | Atom absent |
|---|---|---|
M | 0 or 1: measurement outcome | 1: placeholder, with no loss flag |
ML | 00 or 01: flag 0, then measurement outcome | 11: flag 1, then placeholder |
A 1 from M alone cannot distinguish loss from an ordinary measurement outcome. With ML, flag 1 identifies loss and tells the decoder to ignore the accompanying value as measurement evidence; it does not reveal exactly when the atom was lost. Result inversion changes the value bit, not the loss flag.
Experimental readout. An example of the binary information represented by M is state-selective push-out followed by fluorescence imaging: atoms in |1⟩ are expelled, so an atom lost earlier produces the same absence signal as |1⟩. See Levine et al., Phys. Rev. Lett. 123, 170503 (2019), especially the Supplemental Material's “State readout through atom loss” section.
ML represents readout that distinguishes |0⟩, |1⟩ and atom loss. Bluvstein et al., arXiv:2506.20661 (2025) demonstrate spin-to-position conversion: a state-selective one-dimensional optical lattice pins one spin state while optical tweezers move the other to a separate position. Imaging then identifies the state from the atom's position, or detects loss if neither position contains an atom (Fig. 1b, Extended Data Fig. 2 and Methods).
Another implementation uses low-loss fluorescence state detection followed by a state-insensitive presence check; see Chow et al., PRX Quantum 5, 040343 (2024), Sec. I A and Appendix A7.
| Instruction | Stored record | Reset |
|---|---|---|
ML / MZL | loss flag, then Z-value bit for each target | No |
MRL / MRZL | loss flag, then Z-value bit for each target | Yes, after readout |
MXL, MYL | loss flag, then X/Y-value bit | No |
MRXL, MRYL | loss flag, then X/Y-value bit | Yes |
Reset restores the atom after recording the flag. The simulator supports X/Y loss readouts; the native v1 loss decoder accepts Z loss readouts only. Its result must be independent of the lost-value placeholder.
Generated Mid-SWAP circuits keep physical wire identities fixed and exchange data/check roles. MIDSWAP_SHUTTLE comments record the role changes; the generator does not insert a literal SWAP instruction.
Blinded logical input marker
TICK[rstim:logical_flip_point] marks the insertion point for a private logical Pauli in a blinded dataset. It must occur exactly once at top level, after ideal preparation and before positive-probability noise. A comment with similar text is not the marker. The training tutorial explains how the labels and masks relate.
Native loss decoder acceptance
The v1 contract below specifies accepted circuits, resource limits, bundle validation and failure codes. Release support is documented in the support table.
Status: stable contract (versioned). This document is the public
specification of the circuit subset accepted by rstim decode and produced
by rstim dataset export. It exists so that dataset producers outside this
repository can generate decodable datasets without reading the compiler
source.
The reference implementation is
rstim/src/unified_cli/decode/compiler.rs
(compile_circuit and normalize_supported_circuit).
1. Scope and versioning
- Subset version: v1.
- Selected by default, or explicitly with
--circuit-subset v1, onrstim decodeandrstim dataset import. The opt-in v2 subset adds native Clifford pulses and dephasing; it does not change v1 acceptance. - The decoder accepts exactly one circuit per dataset, stored as
circuit.stiminside a public dataset bundle (see §7). - Any circuit meeting every requirement in §2–§6 is accepted, regardless of which software generated it. Acceptance is capability-checked per circuit; there is no allow-list of generator programs or code families.
- Widening the subset (new instructions,
REPEAT, additional loss-visible bases) requires a new subset version. Rejections that v1 specifies must stay rejections within v1.
2. File-level requirements
| Requirement | Error code on violation |
|---|---|
Circuit is valid UTF-8 and parses under rstim::validation::parse_and_validate | invalid_dataset / unsupported_circuit |
Circuit is flat: no REPEAT blocks | unsupported_circuit ("outside the flat native Mid-SWAP subset") |
Measurement/detector/observable/sweep-bit counts match manifest.json | invalid_dataset |
| No sweep bits; between 1 and 64 observables | unsupported_circuit |
3. Instruction subset
Each instruction is classified as kept for analysis (present in the DEM extraction circuit), structural (consumed by the loss compiler itself), or rejected.
| Instruction | Class | Notes |
|---|---|---|
LOSS q... | structural | Declares a loss-opportunity site. Not itself analyzed; it opens the window in which a later loss-visible readout may herald a loss. Targets must be plain qubits. |
ML, MZL | structural → M | Loss-visible Z readout. Emits two measurement records: flag then value (see §4). |
MRL, MRZL | structural → MR | Loss-visible Z readout with reset. Same two-record layout; closes the loss window for that wire. |
MXL, MYL, MRXL, MRYL | rejected | Non-Z loss-visible bases are future work. |
H | kept | Also tracked as a basis-change site for envelope compilation. |
CX, CNOT, ZCX | kept (decomposed to H–CZ–H) | Targets must form complete, pairwise-disjoint qubit pairs within one instruction. |
R, RZ | kept | Closes any open loss window for the targeted wires. |
X_ERROR, DEPOLARIZE1, DEPOLARIZE2 | kept | The only noise channels in v1. All probabilities must be finite and < 0.5 at DEM level. |
QUBIT_COORDS, SHIFT_COORDS, TICK, DETECTOR, OBSERVABLE_INCLUDE | kept | Semantically inert annotations for loss-envelope construction; they remain in the analysis circuit so detector coordinates are preserved. |
anything else (incl. Y_ERROR, Z_ERROR, PAULI_CHANNEL_*, CORRELATED_ERROR, MPP, S, SWAP, …) | rejected | unsupported_circuit naming the instruction. |
Loss-visible readouts with inline noise arguments (ML(p) ...) are rejected.
4. Loss-record layout
For every loss-visible readout the measurement record interleaves:
- flag record — 1 iff the atom was heralded lost at this readout;
- value record — the measurement value bit.
The flag occupies the earlier measurement index. During compilation the flag
position is materialized as an MPAD placeholder so record indices stay
stable. Consequences:
DETECTORandOBSERVABLE_INCLUDEmust reference value records, never flag records (unsupported_circuit, "detectors and observables must reference value bits, not loss flags").- Each readout must have at least one
LOSSsite on that wire since the last reset (unsupported_circuit, "no LOSS opportunity since reset"). - A readout without reset (
ML/MZL) is terminal for its wire: no subsequent instruction may target that wire (unsupported_circuit, "ML must be terminal for each measured physical wire").
5. Detector error model requirements
The kept-for-analysis circuit (loss structure removed, noiseless variant used for reference samples) must yield a DEM satisfying:
- every detector carries at least
x, y, tcoordinates; - every error probability is finite and
< 0.5(zero-probability errors are ignored); - after DEM decomposition, every error component touches at most two
detectors (graphlike). Non-graphlike remnants are rejected
(
unsupported_circuit, "non-graphlike Pauli effect"); - observable-only error components are rejected for the matching backend ("observable-only Pauli effects are unsupported by envelope-matching");
- at least one decodable effect and one graph edge exist.
Edges are classified for diagnostics: same (x, y) → time-like, otherwise
space-like, single-detector → boundary.
6. Resource limits
| Limit | Value | Error on exceed |
|---|---|---|
| Envelope-MLE candidates per loss measurement | 100 000 | unsupported_circuit ("exceeds candidate limit") |
| Unique primitive loss probes | 100 000 | unsupported_circuit ("exceeds primitive probe limit") |
| Primitive detector/observable symptom terms | 10 000 000 | unsupported_circuit ("exceeds primitive symptom-term limit") |
| Measurements / detectors | 10 000 000 each | layout error |
| Observables | min(64, 1 000 000) | unsupported_circuit |
| Parity terms in measurement transforms | 100 000 000 | layout error |
| Transform working memory | 512 MiB transform / 256 MiB block | layout error |
Successful decode stats expose
primitive_probe_count, primitive_symptom_terms, and
loss_envelope_candidate_count. See the compiler implementation
for primitive effect construction.
7. Dataset bundle contract (consumer side)
rstim decode accepts a directory containing exactly:
manifest.json— formatrstim_decoder_datasetschema v1, orqude_decoder_datasetschema v3 (Decoder-Server interchange);circuit.stim— a v1-subset circuit;shots.b8—lsb_firstbit-packed measurement rows, width equal to the circuit's measurement count, zero padding.
SHA-256 hashes of both files, row widths, shot count, file size, and (for the
rstim format) the derived dataset_id are verified before compilation.
Violations report missing_dataset_file, invalid_dataset, or
unsupported_dataset_mode. Decode-time failures report decode_timeout or
decode_infeasible (exit code 3); all other failures exit 2.
8. Relationship to built-in generators
rstim circuit gen --code surface_code --task rotated_memory_z_midswap
emits circuits inside this subset, and the decode regression suite replays
them. Membership in the subset is the contract, not the generator. The
compiler performs no generator identification: any circuit satisfying §2–§6 is
accepted, whether hand-written, generated by this repository, or produced by
third-party tooling.
9. Error-code summary
| Code | Meaning | Exit |
|---|---|---|
unsupported_circuit | circuit violates §2–§6 | 2 |
invalid_dataset | manifest/hash/layout mismatch | 2 |
missing_dataset_file | bundle file absent or unreadable | 2 |
unsupported_dataset_mode | dataset is not measurements_blinded | 2 |
decode_timeout | per-shot time limit hit | 3 |
decode_infeasible | model infeasible for a shot | 3 |