Skip to main content

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.

This guide walks you through Stim’s core workflow: installing the package, defining a circuit, compiling a sampler, collecting measurement shots, annotating the circuit with detectors, and sampling detection events. All examples use Python and real Stim API calls. By the end you will have a working foundation for exploring quantum error correction simulations.
1

Install Stim

Install Stim from PyPI. Stim requires Python 3.6 or later and pulls in NumPy automatically.
pip install stim
Verify the installation:
import stim
print(stim.__version__)
2

Create a circuit

Circuits in Stim are instances of stim.Circuit. You can build one programmatically by calling circuit.append(gate_name, targets), or you can pass the entire circuit as a string using Stim’s circuit file syntax.The example below prepares a Bell pair and then measures both qubits in the Z basis:
import stim

circuit = stim.Circuit()

# Initialize a Bell pair.
circuit.append("H", [0])
circuit.append("CNOT", [0, 1])

# Measure both qubits.
circuit.append("M", [0, 1])
Printing the circuit’s repr shows it in Stim’s circuit file syntax:
print(repr(circuit))
# stim.Circuit('''
#     H 0
#     CX 0 1
#     M 0 1
# ''')
You can also visualize the circuit as an ASCII diagram:
print(circuit.diagram())
# q0: -H-@-M:rec[0]-
#        |
# q1: ---X-M:rec[1]-
3

Compile a sampler and collect shots

Call circuit.compile_sampler() to produce a compiled sampler object, then call .sample(shots=N) to collect N measurement shots. The returned array has shape (shots, num_measurements) with bool values.
sampler = circuit.compile_sampler()
results = sampler.sample(shots=10)
print(results)
# [[False False]
#  [ True  True]
#  [False False]
#  [False False]
#  [ True  True]
#  [False False]
#  [ True  True]
#  [False False]
#  [False False]
#  [ True  True]]
Notice that each row’s two values always agree — the Bell state measurement results are perfectly correlated, as expected.
4

Add detector annotations

A DETECTOR annotation asserts that a particular parity of measurements is consistent from shot to shot under noiseless execution. You reference past measurements using stim.target_rec(offset), where rec[-1] is the most recent measurement.The Bell circuit’s two measurements should always have the same value, so you can annotate their parity as a detector:
circuit.append("DETECTOR", [stim.target_rec(-1), stim.target_rec(-2)])
print(repr(circuit))
# stim.Circuit('''
#     H 0
#     CX 0 1
#     M 0 1
#     DETECTOR rec[-1] rec[-2]
# ''')
5

Compile a detector sampler and sample detection events

Use circuit.compile_detector_sampler() to create a detector sampler. Calling .sample(shots=N) returns an array of shape (shots, num_detectors) — True means the detector fired (a detection event occurred), False means it did not.Without noise, detectors never fire:
det_sampler = circuit.compile_detector_sampler()
print(det_sampler.sample(shots=5))
# [[False]
#  [False]
#  [False]
#  [False]
#  [False]]
Now rebuild the circuit with Pauli noise inserted using Stim’s circuit string syntax, and watch detectors fire:
noisy_circuit = stim.Circuit("""
    H 0
    TICK

    CX 0 1
    X_ERROR(0.2) 0 1
    TICK

    M 0 1
    DETECTOR rec[-1] rec[-2]
""")

noisy_sampler = noisy_circuit.compile_detector_sampler()
print(noisy_sampler.sample(shots=10))
# [[False]
#  [False]
#  [ True]
#  [ True]
#  [False]
#  [False]
#  [ True]
#  [ True]
#  [ True]
#  [False]]
True values appear because the X_ERROR(0.2) channel flips each qubit independently with 20% probability, causing the two measurements to disagree roughly 32% of the time. You can estimate the detection fraction over many shots:
import numpy as np

shots = noisy_sampler.sample(shots=10**6)
print(np.sum(shots) / 10**6)
# ~0.32

​
Next steps

Circuits in depth

Learn how Stim circuits are structured, how detectors and observables work, and how to use REPEAT blocks.

Sampling guide

Explore measurement sampling, detector sampling, and bulk data collection workflows in detail.

Detector error models

Convert annotated noisy circuits into Tanner graphs for configuring matching decoders.

Python API — Circuit

Full reference for stim.Circuit, including all sampler methods and circuit-level operations.

Build docs developers (and LLMs) love

Get started for freeTalk to us