RustQEC

RustQEC is a Rust workspace for quantum error correction. It brings together the rstim Stim-like circuit simulator and CLI, code-construction tools, decoder experiments, and reproducible benchmark evidence.

Benchmarked Documentation Site

The benchmarked documentation site is the broad repository reference: workspace walkthroughs, benchmark evidence, checked results, methodology and claims limits, plus the QP101 schema browser and gallery that used to be the whole Pages surface.

Build and check the same Pages tree locally:

make build-site
python3 tools/check_site_build.py _site

Generated evidence bundles, documentation test reports and other large site artifacts live in the companion rust-qec-docs repository. make build-site and the evidence workflow fetch the pinned artifact revision automatically; use make fetch-doc-artifacts when running those checks directly.

The site follows master; Get started pins the native CLI examples to v0.3.3. make build-site stages the canonical QP101 and support contracts into ignored site/generated/ before Zola renders them. Edit rstim/doc/QP101-ZY.md or docs/support-compatibility.md to update those pages; do not edit the generated copies.

What You Can Do

With RustQEC you can:

• Trace a circuit through stats, detector events, detector-error-model extraction, and DEM sampling.
• Render circuit diagrams as SVG, including seeded atom-loss sample-shot overlays.
• Construct CSS code matrices and run small exact-distance checks.
• Inspect benchmark and reproduction evidence, including the checked-in surface-code decoder comparison plot.
• Browse the full showcase index for runnable workflow categories and verification commands.

Workspace Map

Path	Role
rustqec-cli/	Unified automation-ready rustqec CLI and capability discovery
rstim/	Simulator crate and rstim CLI for circuit parsing, sampling, DEM extraction, SVG rendering, and QP101 export
rstim/doc/	Simulator getting-started guide, CLI reference, QP101 notes, and parity documentation
docs/showcases/	Stable index for runnable workspace showcases
rsinter/	Parallel collection and benchmark harness for decoder experiments
rmatching/	Rust MWPM decoder for detector-error-model workflows
renvelope/	Reference decoders for explicit atom-loss Pauli envelopes (exact MLE and matching)
rbposd/, rilpqec/	Additional decoder components used by benchmark and comparison flows
qec-code/, qec-ilp-core/	Code construction helpers and ILP-backed checks
benchmarks/surface_decoder_compare/	Cross-decoder comparison harness and benchmark artifacts
qp101-viz/	Optional legacy/prototype Typst renderer and committed QP101 fixtures

Quick Start

If Rust and Cargo are already installed, use the crates.io CLI as the default entry point:

cargo install --locked rustqec-cli --version 0.3.3

If Rust is not installed, get it from the official rustup installation guide, or run:

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

The native installer is the alternative when you want a self-contained binary with the complete native rustqec/rstim CLI feature set, including ILP and the full Shot Lab viewer. It requires no Rust or source checkout:

curl -fsSL https://nzy1997.github.io/rust-qec/install.sh | sh
export PATH="$HOME/.local/bin:$PATH"

The native archive path is validated on Ubuntu 24.04 x86_64 and macOS 15 Apple silicon. Windows, Intel macOS, and other platforms are outside its supported matrix. The installer verifies the archive's pinned checksum and does not edit shell profiles. Inspect the installer or follow the manual download instructions.

The complete introductory workflow uses only rustqec:

rustqec capabilities --format json
cat > pipeline.stim <<'STIM'
R 0
X_ERROR(1) 0
M 0
DETECTOR rec[-1]
OBSERVABLE_INCLUDE(0) rec[-1]
STIM
rustqec circuit stats --format json --in pipeline.stim
rustqec circuit detect --in pipeline.stim --shots 1 --out-format dets --append-observables --out events.dets
rustqec circuit dem --in pipeline.stim --out pipeline.dem
cat events.dets pipeline.dem

The final two lines are shot D0 L0 and error(1) D0 L0. Stats reports one qubit, measurement, detector, and observable, with five instructions. Those commands verify either installation path using only the installed rustqec binary. From a source checkout, automate the same checks plus malformed-input rejection with:

python3 tools/check_installed_quickstart.py --bin-dir "$(dirname "$(command -v rustqec)")"

Cargo and Rust library users

The library crates remain at 0.3.0, while rustqec-cli 0.3.3 is the current verified Envelope release; see the release notes. Install the basic CLI without the ILP solver:

cargo install --locked rustqec-cli --version 0.3.3

This installs rustqec, sufficient for the full example above. Add --features ilp for exact envelope MLE; the official native archives include ILP in rustqec and the full browser viewer in rstim. Stim-style compatibility commands remain available through cargo install --locked rstim --version 0.3.0 --bin rstim --features cli,codegen-css,shot-viewer.

For Rust integration, start with the independent consumer example that samples a circuit and decodes it with MWPM. The crate guide explains package boundaries, features, and the checks required before registry publication.

Build From Source

RustQEC supports native source builds on these tested environments:

Operating system	Native target	Rust toolchains
Ubuntu 24.04 x86_64	x86_64-unknown-linux-gnu	1.88.0 (MSRV), stable
macOS 15 on Apple silicon	aarch64-apple-darwin	1.88.0 (MSRV), stable

Install the full-workspace native build prerequisites on Ubuntu 24.04:

sudo apt-get update
sudo apt-get install -y build-essential clang cmake libclang-dev pkg-config libfontconfig1-dev python3-venv

On macOS 15, install the Xcode Command Line Tools and the Homebrew packages:

xcode-select --install
brew install cmake fontconfig pkg-config python

Install Rust 1.88.0 with rustup for the minimum-version configuration, or select the current stable toolchain:

rustup toolchain install 1.88.0 --profile minimal
rustup default 1.88.0

These prerequisites cover the full workspace feature selection, including the HiGHS-backed ILP crates and rsinter plotting. A smaller rsinter build avoids both HiGHS and plotting (as well as the other optional decoder runners):

cargo build --locked -p rsinter --no-default-features --features rbposd-runner

The complete test suite also invokes Stim through Python. Install it in an isolated environment before running make test:

python3 -m venv .venv
. .venv/bin/activate
python3 -m pip install stim

The support promise is limited to the two native targets above. Windows and other operating-system, architecture, and toolchain combinations are not part of the validated matrix.

git clone https://github.com/nzy1997/rust-qec.git
cd rust-qec
cargo build --locked --workspace --features rstim/cli,rstim/codegen-css,rstim/shot-viewer,qec-code/cli,rustqec-cli/ilp,rsinter/full,rstim/benchmark-tools

Inspect a small circuit through the unified CLI:

printf 'H 0\nM 0\nDETECTOR rec[-1]\n' | \
  cargo run -p rustqec-cli --bin rustqec -- circuit stats --format json

Discover the currently implemented automation contract:

cargo run -p rustqec-cli --bin rustqec -- capabilities --format json

Automation clients can request structured errors independently of successful output formatting by adding --error-format json. Capability discovery lists the concrete argv path, supported arguments, error codes, and exit codes.

The existing crate-specific CLIs remain available. For example, the same circuit can be inspected with rstim stats:

printf 'H 0\nM 0\nDETECTOR rec[-1]\n' | cargo run -p rstim --features cli --bin rstim -- stats

Run the Rust test suite:

make test

After a native-support workflow completes, validate its four jobs, compiler identities, uploaded CLI evidence, and the checked-out package metadata with:

python3 tools/check_native_support_matrix.py --repo-root . --run-id RUN_ID

Support And Compatibility

The support and compatibility contract states the current supported boundaries, pre-1.0 compatibility policy, and known exclusions for this release line.

Primary Next Steps

• Showcase index: runnable workflow categories and the template used for future examples, including rstim CLI DEM Pipeline, rstim Render SVG Atom-Loss, QEC-Code CSS Construction, and Benchmark Evidence.
• Getting started with rstim: simulator and Rust API orientation.
• rstim CLI reference: stats, sample, detect, analyze_errors, render_svg, export_json, and related commands.
• Local neural-decoder training data: aligned detector/observable b8 streams plus versioned per-shot simulator traces.
• rmatching decoder docs: MWPM decoder entry point for detector-error-model workflows.
• rsinter replay: decode frozen .dem plus b8 detector rows into b8 predictions and a reproducibility report.
• Surface decoder benchmark docs: benchmark setup, smoke commands, and generated artifacts.

CLI And Visualization Notes

The CLI reads from --in <path> or stdin and writes to --out <path> or stdout for most commands. For static circuit diagrams, prefer:

rstim render_svg --in circuit.stim --out circuit.svg

For an interactive single-shot view that can resample the fixed circuit, change the realized outcome of existing noise instructions, and export SVG/PDF, run:

rstim shot_viewer

The hosted Shot Lab shows one repository-configured circuit. Its local-file entry starts blank and processes a selected .stim file entirely in WebAssembly.

Use export_json when you need QP101 structured data for downstream tools, fixtures, or the optional qp101-viz workflow:

rstim export_json --in circuit.stim --out circuit.json

Benchmark smoke runs are documented in benchmarks/surface_decoder_compare/README.md; the README intentionally leaves algorithm details and benchmark implementation notes to those dedicated docs.

License

All tracked content in this repository, including the Rust workspace crates and qp101-viz, is licensed under Apache-2.0. See LICENSE for the full license text. Ignored or untracked drafts are outside this repository license declaration.

Portions of rstim compatibility tests are adapted from Stim, and rmatching is ported from PyMatching. Both upstream projects are Apache-2.0, and existing source-level provenance comments are preserved.