T gates, arbitrary rotations, and
other non-Clifford instructions.
A detailed description of Tsim is given in arXiv:2604.01059.
Quick Start
An introductory tutorial is available here. For many existing scripts, replacingstim with tsim should just work. Tsim mirrors the Stim API and supports all Stim instructions, plus the non-Clifford instructions listed below.
Installation
Sampling Strategies
Tsim offers two ways to simulate the non-Clifford parts of a circuit. Both start from the same ZX diagram. Choose a strategy with thestrategy argument of compile_sampler and compile_detector_sampler.
Architecture
- Active state vector. Each component is read off the reduced ZX diagram, without circuit extraction, as a sequence of Pauli rotations and measurements on . Tsim then simulates it on a dense state vector over its active qubits, an approach that follows Clifft (Chase and Labib, 2026) and SymFT (Fang, Lou and Li, 2026).
- Stabilizer rank. Each component is decomposed into a sum of Clifford terms, following Sutcliffe and Kissinger (2024), and compiled into binary JAX tensors . JIT-compiled XLA kernels contract with batched noise configurations to evaluate marginal probabilities and autoregressively sample detector and observable bits.
Differences from Stim
Tsim supports non-deterministic detectors and observables. An important consequence is that Tsim will simulate actual detector samples, whereas Stim only reports detection flips (i.e. detection samples XORed with a noiseless reference sample). Concretely,True values, whereas the same circuit would result in False values in Stim. To reproduce the behavior of Stim, you can use the following:
True, a noiseless reference sample is computed and XORed with the
results, so that output values represent deviations from the noiseless baseline.
Note that this feature should be used carefully. If detectors or observables are not deterministic, this may lead to incorrect statistics.
Supported Instructions
Tsim supports all Stim instructions. In addition, Tsim defines the following non-Clifford instructions. Angles are given in units of π (half-turns).Postselected simulations
For postselected QEC experiments, pass a boolean mask toCompiledDetectorSampler.sample. The mask has length num_detectors; a shot is
discarded when any masked detector fires, and only the other shots are
returned.
sample returns at most shots rows, possibly none; without one,
exactly shots rows. With separate_observables, both arrays hold the same
shots. Shots discarded by a direct postselected detector (one that is a
single error bit or a constant) skip the remaining component sampling. With
strategy="active_statevector", a shot discarded by a component detector also
stops being simulated, while stabilizer-rank components are computed in full.
The mask tests the values that sample returns: with
use_detector_reference_sample, a shot is kept when its masked detectors match
the noiseless reference sample, and otherwise when their raw parities are 0. A
masked detector that is a constant 1, such as one of a noiseless circuit whose
measurements have parity 1, discards every shot; sample warns about it.
API stability
Tsim follows semantic versioning for its public API:tsim.Circuit, tsim.CompiledMeasurementSampler and tsim.CompiledDetectorSampler. tsim.experimental holds helpers that may change in any release. Every other module is internal, even where it is importable. The stabilizer rank sampling strategies ("cat5", "bss", "cutting") are provisional: they may be removed in a minor release, after at least one minor release in which they emit a DeprecationWarning. See the API reference.
A seed reproduces its samples only with the same versions of Tsim and its dependencies (such as NumPy and JAX) and the same backend (CPU or GPU). With a stabilizer-rank strategy, pass the same explicit batch_size as well, since the default batch size depends on the free memory.