Stab

Stab(ilizer) is an agent-native toolkit for quantum error correction (QEC) research: a safe-Rust codebase that researchers and their AI agents can safely modify and extend.

Its first milestone is a drop-in replacement for Stim, the standard simulator and analysis tool for QEC research. Selected implemented Stab surfaces have pinned Stim v1.16.0 compatibility evidence; the generated current state is in docs/qualification-status.md, and the active execution contract is docs/plans/GOAL.md. Stab currently implements selected .stim, .dem, gen, convert, sample, detect, m2d, analyze_errors, sample_dem, and result-format surfaces. Support and qualification are tracked separately in docs/stab-feature-checklist.md; a feature being implemented does not by itself mean its compatibility qualification is complete.

Compatibility: Selected implemented surfaces are checked against the real Stim through pinned parity tests and benchmark comparisons. The pinned Stim v1.16.0 sources are committed in vendor/stim. The generated dashboard and feature checklist distinguish implemented, qualified, reopened, and deferred surfaces. Please report discrepancies so they can be reproduced against the pinned target.

The longer-term vision is composable Rust components for QEC tooling.

The exact implemented scope, including deliberate deferrals such as Python bindings, WASM, diagrams, and explain_errors, is recorded in docs/stab-feature-checklist.md. Rust users moving from the original monolithic facade should follow docs/MIGRATING-0.2.md; Stab 0.2 provides independently consumable model, bits, records, algebra, analysis, engine, and decoder-interoperability crates plus a curated stab-core facade. The analysis crate also exposes an experimental typed circuit-pass seam with pre-lowering output-resource admission, proven by a separate Stable consumer crate.

Quickstart

Download a prebuilt stab binary for Linux AArch64 or macOS AArch64 from the Releases page of this repository, or build from source with the Rust toolchain pinned in rust-toolchain.toml:

cargo install --path crates/stab-cli

On macOS, the unsigned binary needs the quarantine attribute removed after download: xattr -d com.apple.quarantine stab-macos-aarch64.

Then run a complete QEC workflow against the committed sample data in examples/:

# Generate a distance-3 rotated surface code memory experiment (committed as examples/surface_d3.stim).
stab gen --code surface_code --task rotated_memory_z --distance 3 --rounds 3 --after_clifford_depolarization 0.001 --out surface_d3.stim

# Sample 1000 measurement shots from the circuit.
stab sample --shots 1000 --seed 42 --in surface_d3.stim --out shots.01

# Sample detector events directly, or convert measurement shots into detector events.
stab detect --shots 1000 --seed 42 --in surface_d3.stim --out dets.dets --out_format dets --append_observables
stab m2d --circuit surface_d3.stim --in shots.01 --in_format 01 --out dets_from_measurements.dets --out_format dets --append_observables

# Decompose the circuit into a detector error model (committed as examples/surface_d3.dem) and sample it.
stab analyze_errors --in surface_d3.stim --out model.dem
stab sample_dem --shots 1000 --seed 42 --in model.dem --out dem_dets.dets --out_format dets --append_observables

# Convert result data between formats.
stab convert --in shots.01 --in_format 01 --out shots.b8 --out_format b8 --circuit surface_d3.stim --types M

# Discover capabilities, inspect the model, and validate a sampling request without executing it.
stab capabilities --format=json
stab inspect surface_d3.stim --format=json
stab plan sample surface_d3.stim --shots 1000 --seed 42 --out_format b8 --backend=auto --format=json

Every command above finishes in well under a second at distance 3. Larger distances exercise much bigger simulations; Stab enforces documented resource bounds where Stim would attempt unbounded allocation.

Use stab help commands, stab help formats, and stab help gates to explore the supported surface. Human-readable diagnostics remain the default; add --error-format=json to any command when an agent or tool needs one schema-version-1 JSON object per warning or error. The Stab-native capabilities, inspect, and plan sample extensions use --format=json for one successful machine-readable document on stdout; planning validates compilation and explicit backend selection but never executes a shot.

Supported Platforms

Development and all correctness tests and performance benchmarks run on Linux (AArch64, actually my DGX Spark), and they are currently Linux-only, while macOS (Apple Silicon) is supported but not tested.

The prebuilt Linux and macOS AArch64 binaries are convenience artifacts built by GitHub Actions.

Built with Codex and Agent Friendly

Stab is an agent-built codebase: the implementation was developed with OpenAI Codex, and the test, oracle, and benchmark qualification harnesses were developed with GPT-5.6 Sol and previously GPT 5.5.

The working style is plan-first and evidence-first, and the workflow artifacts are committed in this repository: milestone plans and qualification contracts in docs/plans/, agent operating rules in AGENTS.md, the pinned Stim v1.16.0 reference sources in vendor/stim, and the frozen correctness and performance inventories under oracle/ and benchmarks/. For our specialized review skills, see the skill inventory.

Key decisions, including the portable-SIMD bit kernels, the streaming CLI architecture, and the machine-checkable qualification program, are documented in the milestone and progress reports under docs/plans/.

Development

Development setup, the staged pre-commit hook, oracle and compatibility-matrix workflows, correctness and performance qualification commands, and benchmark contracts are documented in CONTRIBUTE.md.