Crate stabilizer_qec

Expand description

§stabilizer_qec

A quantum error-correction simulator and decoder: circuits and detector error models in Stim’s formats, a bit-parallel sampler, exact and correlated matching, belief-matching, BP and BP+OSD, window decoding, IBM’s bivariate bicycle codes and lattice surgery. It is the engine behind the stabilizer-qec Python package and the interactive explainer, and it agrees with Stim, PyMatching, ldpc and beliefmatching on every check in its test suite.

use stabilizer_qec::{memory_circuit, Basis, DemOptions, Matching, Noise, SurfaceCode};

// A distance-5 surface-code memory under circuit noise, sampled and decoded.
let circuit = memory_circuit(SurfaceCode::Rotated, 5, 5, Noise::Sd6 { p: 0.004 }, Basis::Z)?;
let samples = circuit.detector_sampler(7)?.sample(10_000, 0); // 0 threads: every core
let dem = circuit.detector_error_model(&DemOptions::new().decompose_errors(true))?;
let predictions = Matching::with_correlations(&dem)?.decode_batch(&samples.detectors, 0)?;
let failures = (0..10_000).filter(|&s| predictions[s].flips(0) != samples.observables.get(s, 0)).count();
assert!(failures < 1_000);

Circuits: Circuit reads Stim’s circuit language (every Clifford gate, all three bases, Pauli products, every noise channel, measurement feedback, REPEAT, tags, Pauli observables) and prints it back, or is built in code (Circuit::append with Targets, +, *); Circuit::detector_error_model builds the error model Stim’s analyzer builds, fault for fault, its loops folded as Stim folds them (a d = 11 memory of 10,000 rounds in a tenth of a second); DetectorSampler samples 64 shots to a word, reproducibly from a seed on any number of threads; MeasurementConverter turns raw records into detection events.
Decoders on an error model: Matching (exact, sparse blossom; plain or correlated, as fast as PyMatching), BeliefMatching, BpOsd, WindowMatching. On a check matrix: BpDecoder and BpOsdDecoder, equal to ldpc’s. All Send + Sync.
Codes: memory_circuit (rotated and XZZX surface codes), stream_memory and stream_circuit (a million rounds of a memory, or of any circuit with a loop, window-decoded as they stream), BivariateBicycleCode (the gross code, its automorphisms’ logical action, and the gauging measurement of its logicals), lattice_surgery (Z⊗Z and X⊗X merges, a logical CNOT).

Shots are BitTables, bit-packed as Stim’s b8 format. Every fallible call returns Error; none panics on bad input.

§Stability

Semantic versioning from 1.0: the items in this documentation keep compiling, with the same meaning, through every 1.x release (checked by cargo-semver-checks in CI). The engine’s own modules are public so the Python bindings, the site and the tools can reach them, but they are hidden from this documentation and carry no such promise. The Python bindings sit behind the python feature, off by default. The minimum supported Rust is 1.87.

Modules§

lattice_surgery: Lattice surgery on rotated surface-code patches (Horsman, Fowler, Devitt and Van Meter 2012), each operation one circuit with SD6 noise at p: patches prepared, held, merged across a seam for merged rounds, split, held and read out. Distances are odd, at least 3.

Structs§

Automorphism: An automorphism of a bivariate bicycle code: the shift x^a y^b of both halves of the data, with or without the ZX-duality, and what it does to the logical qubits.
BeliefMatching: Belief-matching (Higgott et al. 2023), as the beliefmatching package decodes: BP on the model’s hypergraph; where BP’s own correction explains the shot it is used, otherwise matching on weights −ln p from BP’s posteriors. The model must be decomposed.
BitTable: A table of bits, one row per shot, bit-packed as Stim packs them: each row a whole number of bytes, bit k of a row in byte k / 8 at position k % 8 (numpy’s packbits(..., bitorder="little"), Stim’s b8 format).
BivariateBicycleCode: One of IBM’s bivariate bicycle codes (Bravyi et al., Nature 627, 778, 2024), with the paper’s depth-8 syndrome cycle.
BpDecoder: Belief propagation on a check matrix given by its columns (the checks each column touches), flooding schedule, its arithmetic reproducing ldpc’s BpDecoder bit for bit.
BpOptions: Belief-propagation settings.
BpOsd: BP+OSD on a detector error model (Roffe et al.): each fault a column with its prior, corrections equal to ldpc’s BpOsdDecoder but for ties among equally likely columns. For codes whose faults flip three or more detectors, such as the bivariate bicycle codes: give it the undecomposed model.
BpOsdDecoder: BP+OSD on a check matrix given by its columns, as ldpc’s BpOsdDecoder.
BpOsdOutcome: A BP+OSD run’s result.
BpOutcome: A BP run’s result.
Circuit: A stabilizer circuit in Stim’s circuit language.
CssCode: A CSS code given by its checks, with a memory experiment correct for any of them: every X check measured and then every Z check, each in layers no qubit is used twice in. Built from check matrices, as the hypergraph product of two classical codes, or as the triangular colour code.
DemOptions: How Circuit::detector_error_model builds a model.
DetectorErrorModel: A detector error model in Stim’s format: independent faults, each with a probability, the detectors it flips and the observables it flips. Parse one from Stim’s text, or build one with Circuit::detector_error_model.
DetectorSampler: Detection events and observable flips, 64 shots to a machine word. Made by Circuit::detector_sampler.
Error: Why a call failed: the input was not something the engine can take, with a message saying what and where.
Gauging: The gauging ancilla system that measures a gross-code logical X (see BivariateBicycleCode::gauging).
GeneratedNoise: The noise of Circuit::generated: Stim’s four strengths, each zero (left out) unless set.
Matching: Exact minimum-weight perfect matching on a decomposed detector error model, by sparse blossom, as PyMatching decodes: edges weighted ln((1 − p)/p), the observables of the lightest correction returned. Correlated matching adds PyMatching 2.4’s second pass.
MeasurementConverter: Raw measurement records to detection events and observable flips, as stim m2d: each detector and observable compared with a noiseless reference run. Made by Circuit::measurement_converter.
Prediction: A decoder’s answer for one shot.
Samples: Shots of detection events and of observable flips, one row per shot.
StreamResult: A streamed memory’s outcome (see stream_memory).
UnionFind: Weighted union-find decoding (Delfosse and Nickerson, with Huang, Newman and Brown’s weighted growth) on the same graph matching uses: clusters around the detection events grow edge weight by edge weight until their events can pair inside them, and a spanning tree of each is peeled for the correction. Linear time in practice, its logical error rate a little above matching’s; the standard baseline (this engine’s matcher, near-linear too, is about twice as fast). The model’s faults must flip at most two detectors each, or be decomposed.
Window: A window of a window decoder: it decodes rounds first_layer..end_layer and commits the corrections in commit_start..commit_end.
WindowMatching: Window decoding (Skoric et al.; Tan et al.): the model cut into overlapping windows of rounds, each matched alone and committing only its middle. The model’s detectors need a time coordinate (their last), as Stim’s generated circuits give them.
WindowOptions: A window decoder’s schedule.

Enums§

Basis: A measurement or preparation basis.
BpMethod: How belief propagation updates its messages.
DiagramKind: A kind of Circuit::diagram, after Stim’s.
GrossOperator: A weight-12 logical X of the gross code whose measurement is built (see BivariateBicycleCode::logical_measurement_circuit).
Noise: Circuit noise.
OsdMethod: How BP+OSD’s ordered-statistics step searches when BP does not converge.
Pauli: A single-qubit Pauli.
SurfaceCode: A surface code.
Target: A target of an instruction, for Circuit::append.
WindowMode: The order a window decoder runs its windows in.

Functions§

memory_circuit: A surface-code memory experiment: a patch of distance distance (2 to 11) prepared in basis, held for rounds rounds of syndrome extraction (at most 10,000), and read out; detectors on every check and one observable.
stream_circuit: Any circuit with a loop, sampled round by round and window-decoded as it streams, its windows’ graphs from a template of its folded error model: the middle windows of a short version of the loop serve every window of the long one. As stream_memory, for circuits of your own (Stim’s generated ones among them): their detectors need a time coordinate.
stream_memory: A memory too long to model whole, sampled round by round and window-decoded as it streams: an SD6 memory at strength p of rounds rounds (a million is fine), Z basis, its windows’ graphs built once from a short template. shots is rounded up to a multiple of 64; the same seed gives the same failures on any number of threads (0 is every core).

Type Aliases§

Result: The crate’s result type.