Stim: Quantum Stabilizer Circuits

1.15.0 · active · verified Thu Apr 16

Stim is a fast Python library for high-performance simulation and analysis of quantum stabilizer circuits, particularly those used in quantum error correction (QEC). It focuses on providing low-level, fast building blocks for simulating circuits with thousands of qubits and millions of operations, enabling rapid Monte Carlo sampling. The library maintains a regular release cadence, with minor versions typically released every few months, ensuring active development and improvements.

Common errors

```
ModuleNotFoundError: No module named 'stim'
```
cause The Stim library is not installed in the current Python environment, or the environment is not active.

fix Install Stim using pip: `pip install stim`
```
ValueError: shot_count must be a multiple of 64 for 'ptb64' format.
```
cause When reading or writing measurement results using the 'ptb64' format (e.g., with `Circuit.compile_sampler().sample(..., format='ptb64')`), the number of shots provided is not a multiple of 64.

fix Adjust the `shots` parameter to be a multiple of 64. For example, `sampler.sample(shots=128, format='ptb64')`.
```
TypeError: Cannot apply H to qubit 0 1: expected a single qubit target or a list of single qubit targets, not a list of 2 targets
```
cause An incorrect number or type of targets was provided for a gate. For example, applying a single-qubit gate like 'H' to multiple qubits in a single instruction when it expects a list of individual qubit targets.

fix Consult the Stim documentation for the specific gate's target format. For single-qubit gates, pass qubits individually (e.g., `circuit.append("H", [0]); circuit.append("H", [1])`) or as separate entries. For multi-qubit gates, ensure the list format matches (e.g., `circuit.append("CNOT", [0, 1])`).

Warnings

breaking The default value for `ignore_ungraphlike_errors` in `stim.DetectorErrorModel.shortest_graphlike_error` changed from `False` to `True` in v1.11.0. This means the method will now ignore ungraphlike errors by default, which may change behavior for existing code.
Fix: Explicitly set `ignore_ungraphlike_errors=False` if you require the old behavior, or review your logic to account for the new default.
breaking When reading or writing data using the `"ptb64"` format, the shot count is strictly required to be a multiple of 64 since v1.9.0. Previously, missing shots might have been padded.
Fix: Ensure all operations involving `"ptb64"` format data handle shot counts that are exact multiples of 64.
gotcha Stim's C++ API makes no compatibility guarantees and may change arbitrarily and catastrophically between minor versions. Only the Python API and command-line API promise backwards compatibility within major versions.
Fix: When interacting with Stim's C++ components directly, always pin to a specific Stim version and be prepared for API changes with updates. For stability, use the Python API.
gotcha The `HERALDED_PAULI_CHANNEL_1` gate had a bug prior to v1.12.1 where it targeted fixed indices instead of the given qubits. This could lead to incorrect simulation results without explicit error messages.
Fix: Upgrade to Stim v1.12.1 or newer to ensure correct behavior of `HERALDED_PAULI_CHANNEL_1`. If using older versions, thoroughly validate circuits involving this gate. [cite: -Github release v1.12.1]
gotcha Stim's `Circuit` class primarily supports Pauli noise channels and single-control Pauli feedback. For more complex noise models (e.g., amplitude decay) or multi-control feedback, you must manually drive a `stim.TableauSimulator`.
Fix: For advanced noise or feedback scenarios, use `stim.TableauSimulator` and implement custom logic for state evolution.

Install

pip install stim Install Stim

Imports

Circuit
```
from stim import Circuit
```
TableauSimulator
```
from stim import TableauSimulator
```
PauliString
```
from stim import PauliString
```
DetectorErrorModel
```
from stim import DetectorErrorModel
```

Quickstart

This quickstart demonstrates how to create a basic quantum circuit, add gates, compile a sampler for efficient measurement shot generation, and extract a detector error model from a noisy circuit. The example includes fundamental operations and a simple noise model.

import stim

# Create a quantum circuit
circuit = stim.Circuit()
circuit.append("H", [0])
circuit.append("CNOT", [0, 1])
circuit.append("M", [0, 1])

# Compile a sampler for the circuit
sampler = circuit.compile_sampler()

# Sample measurement shots
shots = sampler.sample(shots=10)

print("Circuit:\n", circuit)
print("Sampled shots (first 5):\n", shots[:5])

# Example of adding noise and extracting a detector error model
noisy_circuit = stim.Circuit()
noisy_circuit.append("H", [0])
noisy_circuit.append("DEPOLARIZE1(0.001)", [0])
noisy_circuit.append("CNOT", [0, 1])
noisy_circuit.append("DEPOLARIZE2(0.002)", [0, 1])
noisy_circuit.append("M", [0, 1])
noisy_circuit.append("DETECTOR", [0]) # Add a simple detector at qubit 0

dem = noisy_circuit.detector_error_model()
print("\nDetector Error Model (first few lines):\n", str(dem).splitlines()[0:5])

view raw JSON →