RustQEC 0.3 · Development

Why atom loss needs its own decoder

Atom loss. In a neutral-atom quantum computer, each physical qubit is stored in an atom held in a trap. An atom-loss error occurs when that atom escapes: its quantum state is no longer available to the computation, and later gates involving it cannot run as intended.

Why it matters. Atom loss is a major error source in neutral-atom hardware. A missing atom can disrupt repeated error-correction checks until it is replaced. Detecting which atom is missing also gives the decoder useful information about the error location, helping it recover the logical information encoded across the remaining atoms.

The decoding challenge. Ordinary measurement (M) records only a value bit; loss-aware measurement (ML) also records whether the atom is missing. A loss flag at readout tells us which atom is missing, but may not tell us when it disappeared. Loss before a gate and loss after it can affect different checks; one missing atom can disrupt several later interactions. The decoder must use the surviving measurements while accounting for these possible histories and ordinary Pauli errors. With multiple losses, the number of possible histories grows rapidly. See the delayed loss detection framework for background.

The four steps below generate a Mid-SWAP memory-Z circuit, sample 64 shots, decode them with Envelope matching and check the predictions. With rstim installed and on your PATH, copy and run the commands in order in the same empty working directory.

1. Generate the circuit

Create a distance-3, two-round Mid-SWAP memory circuit. Mid-SWAP exchanges data/check roles during the checks so readout can reveal loss.

rstim circuit gen \
  --code surface_code --task rotated_memory_z_midswap \
  --distance 3 --rounds 2 --after-clifford-depolarization 0.002 \
  --operation-loss-probability 0.002 \
  --measurement-loss-probability 0.003 \
  --out circuit.stim

--after-clifford-depolarization sets Pauli noise after Clifford gates. --operation-loss-probability sets loss on gate targets; --measurement-loss-probability sets loss at readout.

Circuit crop on q2: H, D1 with probability 0.002, then LOSS with probability 0.002
Operation loss. LOSS(0.002) follows the H gate on q2. D1 is the separate Pauli depolarization channel.
Circuit crop on q2: LOSS with probability 0.003 immediately before the final ML readout, which produces loss flag and value records
Measurement loss. LOSS(0.003) appears immediately before ML, which records a loss flag and measurement value.

2. Sample 64 shots

The decoder reads the circuit and measurements (shots.b8) from data/public/; data/private/ holds the answers (answers.b8) and input masks for scoring only.

mkdir -p data
rstim dataset export \
  --circuit circuit.stim --shots 64 --seed 7 \
  --public-out data/public --private-out data/private

The generated circuit records the logical-input insertion point and logical-X qubits for its layout. The exporter reads this metadata automatically, privately randomizes the input bit and exports the loss flag/value measurements.

3. Decode public records

Envelope matching builds a graph conditioned on the observed loss pattern, then predicts one logical flip per shot from the public records.

rstim decode --decoder envelope-matching \
  --dataset data/public \
  --out predictions.b8 --stats-out decode-stats.json

predictions.b8 contains one predicted bit per shot, stored in one byte for this one-observable circuit. decode-stats.json records shot counts, compilation and decoding time, and failures.

4. Check the predictions

Compare the predictions with the matching private answer bundle:

rstim dataset score \
  --dataset data/public --private data/private \
  --predictions predictions.b8 --decode-stats decode-stats.json
Scored shots: 64
Logical errors: 0 / 64

Each shot with a disagreement between a prediction and its private answer counts as one logical error. Compare predictions directly with answers.b8, which already accounts for the hidden input masks. Add --format json for a structured result including the logical error rate.

The loss model and stored record

LOSS(p) removes each present target independently with probability p. A lost atom stays absent until reset. Single-qubit gates skip it; a two-qubit gate is skipped when either partner is absent.

ML stores two bits per target: loss flag first, then value. A flag of 0 means the value is a measurement outcome. A flag of 1 means the stored value is a placeholder; it must not become ordinary syndrome evidence. MRL reports the same pair and then resets, restoring the atom.

cat > loss-record.stim <<'STIM'
R 0
LOSS(1) 0
ML 0
R 0
ML 0
STIM
rstim circuit sample --in loss-record.stim --shots 1 --seed 7 \
  --out-format 01 --out loss-record.01 > /dev/null
cat loss-record.01
1100

The first 11 is a lost flag plus placeholder. After reset, 00 is a present atom measured in |0⟩. See the instruction reference for the full readout rules.

What the Mid-SWAP gadget changes

The generator alternates the order of four CX layers. After the first physical layer in each round it exchanges the logical data/check roles of the participating wires; later gates and readout use the updated mapping. Reading and resetting the current check roles helps expose losses that would otherwise remain on a data role.

Mid-SWAP round schedule: first CX layer, role exchange, remaining CX layers, and check-role loss-visible measurement and reset
Physical wire identities stay fixed while data/check roles change.

Physical loss stays attached to its wire until reset; changing a logical role does not restore a lost atom. Inspect the circuit with rstim render_svg or Shot Lab to see gates and paired flag/value records.

Decoder choices and method sources

envelope-matching, used in this tutorial, is included in the default CLI and uses matching on a loss-conditioned graph. envelope-mle requires the optional ilp build and finds the most likely fault configuration within the envelope model.

See the support table for release status.

The methods follow Liu et al., Pauli Envelope (v2), the pinned reproduction reference. For background on delayed loss detection, see Baranes et al.

Troubleshooting & support

The decoder reports unsupported_circuit

The input falls outside the compiler’s acceptance rules. Start with the exact circuit above, then compare your changes with the support contract.

The output differs from the example

Check the CLI version, seed 7, 64 shots, circuit parameters and decoder choice. Use a fresh directory and rerun all four steps.

The check reports mismatched datasets or incomplete rows

Regenerate the public and private bundles together, then rerun decoding. Both manifests must share a dataset_id, and prediction, answer and statistics counts must agree. Do not combine files from different runs.

Should I apply the private input masks again?

No. Compare predictions directly with answers.b8 as in step 4.

Take the next step

Inspect a circuit visually →