Simulate and sample circuits

Requires rstim on PATH. If you installed only rustqec with Cargo, add the Stim-style CLI below; the native package already includes it. Run in a scratch directory. The example below provides its complete input.

cargo install --locked rstim --version 0.3.0 --bin rstim --features cli,codegen-css,shot-viewer

This deterministic example resets one qubit, applies an X error with probability 1, then measures a detector and observable. Create the input in your current working directory:

cat > circuit.stim <<'STIM'
R 0
X_ERROR(1) 0
M 0
DETECTOR rec[-1]
OBSERVABLE_INCLUDE(0) rec[-1]
STIM

rstim detect --in circuit.stim --shots 1 --out_format dets

Expected output: shot D0 L0.

cargo run --locked -p rstim --features cli --bin rstim -- detect --in circuit.stim --shots 1 --out_format dets

Save measurements or detector events

sample stores raw measurement bits; detect stores changes relative to the circuit's detector reference. Use a readable format first, then switch to b8 for larger batches.

rstim sample --in circuit.stim --shots 1 --out_format 01 --out measurements.01
cat measurements.01

1

Troubleshooting: if rstim is not found, install it with the command above and check your Cargo bin directory is on PATH. If the output differs, check that the input still contains X_ERROR(1).

Five surface-code sampling paths

One-time precompilation is shown separately. Sample + output is the worker-local Sample phase plus b8 output and excludes both precompilation and pipe transport. Precompiled rows reuse a sampler; direct rows include their per-batch setup in the Sample column. Samples/s is calculated from Sample + output.

All rows use the surface d=11, r=100 fixture with 1,024 shots. Each phase is the breakdown of the same median-total call selected from 7 calls after 2 warmups; precompile is one observed setup. Stim produces an already bit-packed array inside sample, so its packing work appears under “Sample” and its b8 step is only byte serialization. In this recorded run, rstim is 3.60× faster in the precompiled comparison. The precompiled atom-loss path is in the same 4 ms range as rstim precompiled; its small lead is within run-to-run variation and is not treated as an atom-loss speedup claim.

For the atom-loss case, one depolarization event and two independent per-atom loss events after each two-qubit gate all use p = 1 - 0.999^(1/3) ≈ 0.0003334445062, keeping the probability of at least one error at 0.001.