Skip to main content
If you have been using Stim, using Tsim should feel very similar. In many cases, replacing stim with tsim should just work. If you’re not yet familiar with Stim, there are lots of resources out there: For example, Stim’s getting_started notebook, Craig Gidney’s Stim tutorial on YouTube, Google’s course on QEC, or this Stim 101 tutorial.

Non-Clifford instructions

Tsim extends the Stim text format with non-Clifford instructions:
  • T and T_DAG on qubits, and TPP and TPP_DAG on Pauli products,
  • the rotations R_X, R_Y, R_Z, the general single-qubit unitary U3, the two-qubit rotations R_XX, R_YY, R_ZZ, and R_PAULI on Pauli products,
  • CS and CS_DAG on qubit pairs, and CCZ and CCX on qubit triples, which expand to a Clifford+T decomposition.
Rotation angles are specified in units of π.

Detector Reference Samples

There are a few differences between the two packages. For example, Stim’s detector sampler will output results relative to a noiseless reference sample. For example, in the following circuit, detector and observable bits will always be False:
Output
By default, Tsim reports actual detector and observable bits. To match Stim’s behavior, set use_detector_reference_sample=True and use_observable_reference_sample=True. This computes a noiseless reference sample and XORs it with the results.
Output

Batch size and just-in-time compilation

Tsim’s samplers also have a batch_size argument, which does not exist in Stim. This parameter controls the number of shots sampled in parallel. When batch_size is not specified, it is automatically chosen based on available device memory (GPU VRAM or system RAM). To achieve maximum performance on a GPU, you can also set batch_size explicitly.
Output
Tsim uses jax just-in-time compilation, which is triggered upon first execution of the sample function. This means that subsequent calls to sample with the same parameters will be faster. Note that recompilation is triggered whenever the batch_size is changed.

Sampling strategies

By default ("active_statevector"), Tsim simulates each connected component of the circuit’s ZX diagram on a dense state vector over its active qubits. Tsim also supports three stabilizer rank decomposition strategies: "cat5", "bss", and "cutting". The strategy can be passed to compile_sampler or compile_detector_sampler:
Output
Different strategies can yield different performance depending on the circuit structure. If sampling is slow, it can be worth trying an alternative strategy.

Postselection

Stim has no built-in postselection. In Tsim, pass a boolean postselection_mask over the detectors to sample. Only the shots in which every masked detector reads 0 are returned, so the result can have fewer than shots rows. Tsim stops simulating a shot as soon as a masked detector fires.
Output

Visualization methods

Tsim supports a subset of Stim’s visualization methods. Since Tsim is based on ZX diagrams, it also provides visualization via zxparam.
It can be interesting to look at the ZX diagram of more advanced Stim programs. For example, the following program measures a qubit and records the flipped measurement outcome. Based on this outcome, an X gate is applied to a different qubit:

REPEAT instructions are flattened

Tsim does not support REPEAT instructions. Any REPEAT instructions will be flattened.