stim

Stim is a high-performance simulator and analysis tool for quantum stabilizer circuits, specifically designed for quantum error correction (QEC).

Key Features

• Fast Simulation: Uses stim.Circuit.compile_sampler() to produce objects capable of sampling shots at kilohertz rates after an initial analysis.
• Decoder Configuration: stim.Circuit.detector_error_model() converts noisy circuits into a detector error model (Tanner graph) for configuring decoders. Using decompose_operations=True helps decompose hyper errors into graphlike errors for matching-based decoders.
• Stabilizer Building Blocks: Provides utilities like stim.PauliString, stim.Tableau, and stim.TableauSimulator.

Limitations

• No non-Clifford gates: Only stabilizer operations are supported (no T gates or Toffoli gates).
• Pauli noise only in stim.Circuit: stim.Circuit does not support non-Pauli noise (like amplitude decay). For complex noise, you must use stim.TableauSimulator manually.
• Feedback constraints: stim.Circuit only supports single-control Pauli feedback. Multi-control or non-Pauli feedback requires manual driving of a stim.TableauSimulator.

A stim.Tableau represents a stabilizer tableau, which explicitly stores how a Clifford operation conjugates Pauli group generators.

Common ways to create a Tableau:

• stim.Tableau(num_qubits): Creates an identity tableau for the specified number of qubits.
• stim.Tableau.from_named_gate(name): Creates a tableau from a standard gate (e.g., "H", "S", "CNOT", "CZ").
• stim.Tableau.from_circuit(circuit): Converts a stim.Circuit into an equivalent stabilizer tableau.
• stim.Tableau.random(num_qubits): Creates a random Clifford tableau.

Key operations:

• Conjugation: Calling a tableau on a PauliString (e.g., t(p)) returns the conjugated Pauli string $Q = C P C^{-1}$.
• Multiplication: t1 * t2 represents the composition of two Clifford operations (applying t2 then t1).
• Power: t**n raises the tableau to an integer power $n$ (efficiently handles large powers via repeated squaring; negative powers invert the tableau).
• Direct Sum: t1 + t2 performs a diagonal concatenation of two tableaus.

import stim

# Create a CNOT tableau
t = stim.Tableau.from_named_gate("CNOT")
p = stim.PauliString("XX")

# Conjugate the Pauli string
result = t(p)
print(result)  # Output: +X_

# Multiply tableaus (composition)
t1 = stim.Tableau.random(4)
t2 = stim.Tableau.random(4)
t3 = t2 * t1

When compiling chunks, ChunkCompiler normally requires that the output flows of one chunk match the input flows of the next. If a mismatch is intentional (e.g., a transversal preparation that produces X stabilizers when the next chunk expects Z), you must explicitly declare these as discarded flows to prevent compilation errors.

• Use add_discarded_flow_output(flow) to annotate that an output stabilizer will not be used.
• Use add_discarded_flow_input(flow) to annotate that an input stabilizer is expected but will be ignored.

import stimflow as sf

# Example: A chunk that produces X stabilizers that are intentionally not used by the next chunk
xx = sf.PauliMap.from_xs([0, 1])
zz = sf.PauliMap.from_zs([0, 1])

init_builder = sf.ChunkBuilder()
init_builder.append("R", [0, 1])
init_builder.add_flow(end=zz)
# Explicitly mark X stabilizers as discarded so the compiler doesn't error when the next chunk starts with Z
init_builder.add_discarded_flow_output(xx)
init_chunk = init_builder.finish_chunk()

The CompiledMeasurementsToDetectionEventsConverter is a tool for converting raw measurement data into detection events (and optionally observable flip data) based on a specific circuit's logic.

Initialization: When initialized, the converter uses a noiseless reference sample (collected via Stim's Tableau simulator) as a baseline to determine expected detector values.

• Use skip_reference_sample=True if you want to initialize the reference sample to all-zeroes instead of collecting it (only if all-zeroes is a known valid noiseless result).

The convert method: Converts a numpy array of measurements into detection events.

• measurements: A numpy array. Its dtype determines if it is bit-packed (uint8) or unpacked (bool_).
• separate_observables: If True, returns a tuple (detection_events, observable_flips). If False, returns only the detection events.
• append_observables: If True, treats circuit observables as additional detectors and appends them to the end of the detection event data.
• sweep_bits: Optional array containing sweep data for sweep[k] controls.

import stim
import numpy as np

# Create a converter using the circuit's built-in method
converter = stim.Circuit('''
   X 0
   M 0 1
   DETECTOR rec[-1]
   DETECTOR rec[-2]
   OBSERVABLE_INCLUDE(0) rec[-2]
 ''').compile_m2d_converter()

# Convert measurements
dets, obs = converter.convert(
    measurements=np.array([[1, 0], [1, 0], [1, 0], [0, 0], [1, 0]], dtype=np.bool_), 
    separate_observables=True
)