A detector error model (Documentation Index
Fetch the complete documentation index at: https://mintlify.com/quantumlib/Stim/llms.txt
Use this file to discover all available pages before exploring further.
.dem) file is a UTF-8 encoded, human-readable description of the probabilistic error mechanisms in a quantum error-correcting code. The format is designed to be consumed by decoders — algorithms that predict the logical observable frame from a set of detected symptoms. Each error mechanism in the model has a probability, a set of syndrome detectors it flips (symptoms), and a set of logical observables it flips (frame changes). Error mechanisms may also suggest a decomposition into simpler sub-mechanisms.
Encoding
Detector error model files are always encoded using UTF-8. Non-ASCII characters may only appear inside comments.Syntax
A.dem file is a sequence of lines, each of which is blank, an instruction, a block initiator, or a block terminator. Lines may be indented and may end with a # comment. Instruction names are case-insensitive.
Instructions
error
error
The The
error instruction adds an error mechanism to the model. It takes one probability argument and a list of targets that specify the symptoms (detector targets) and frame changes (observable targets) caused by the error. Targets may include a ^ separator to suggest a decomposition.Syntax: error(p) <targets>When two error mechanisms have identical targets, they are typically fused using the combination formula
p_combined = p1(1 − p2) + p2(1 − p1). An error mechanism may have frame changes with no symptoms, which implies code distance ≤ 1.^ separator is used to suggest decompositions, not to define independent error mechanisms. For example, in a surface code, a Y error can be decomposed into correlated X and Z parts.detector
detector
The
detector instruction declares a detection event and optionally annotates it with coordinates. Detectors are implicitly declared by being mentioned in error instructions, but an explicit declaration is the only way to attach coordinate hints.Syntax: detector(<coords...>) D<index>The detector index is relative to the current detector offset (accumulated by shift_detectors). Coordinate arguments are relative to the current coordinate offset.logical_observable
logical_observable
The
logical_observable instruction ensures a frame change is included in the model even if no error mechanism references it.Syntax: logical_observable L<index>shift_detectors
shift_detectors
The
shift_detectors instruction increments the current detector index offset and optionally the coordinate offset. This is essential inside repeat blocks, where each iteration would otherwise declare detectors with the same indices.Syntax: shift_detectors(<coord_offsets...>) <detector_offset>The detector offset argument is a non-negative integer; it can only increase, never decrease. Coordinate offset arguments are floating-point.repeat
repeat
The
repeat K { ... } block repeats its body exactly K times. It is used to compactly express error models for repetitive circuits such as syndrome extraction rounds.Target types
| Target | Format | Description |
|---|---|---|
| Relative detector | D<uint> | A detection event. The absolute index is D_value + current_detector_offset. |
| Logical observable | L<uint> | A logical frame change that an error can flip. |
| Numeric | <uint> | A bare integer used by shift_detectors (detector shift) and repeat (repetition count). |
| Separator | ^ | Splits the targets of an error instruction into a suggested decomposition. |
State space
Interpreting a.dem file requires tracking:
- Offsets — the current relative detector index and coordinate offset, modified by
shift_detectors. - Nodes — the set of all declared detectors and logical observables. The total count equals
max_detector_index + 1andmax_observable_index + 1respectively. - Edges — the list of error mechanisms and their probabilities, symptoms, and frame changes.
Relationship to circuits
A.stim circuit with DETECTOR and OBSERVABLE_INCLUDE annotations can be converted to a .dem file by analyzing how physical errors propagate through the circuit. In Stim’s Python API:
Examples
Circular error model
Circular error model
Ten detectors arranged in a ring, with one error mechanism that also carries a logical observable frame change.The same model using a
repeat block:Repetition code error model (excerpt)
Repetition code error model (excerpt)
This is an excerpt from the output of
stim --gen repetition_code --task memory --rounds 1000 --distance 4 --after_clifford_depolarization 0.001 | stim --analyze_errors --fold_loops. The repeat block encodes all 998 middle rounds compactly.