Your first detector event

1. Install with Cargo

Rust and Cargo required. No repository checkout needed. Install Rust or use the native package without Rust.

cargo install --locked rustqec-cli --version 0.3.0

Cargo installs rustqec into ~/.cargo/bin by default. Open a new terminal after installing Rust so this directory is on PATH. This command runs the entire tutorial below.

rustqec capabilities --format json

Success: the capability JSON includes circuit.stats. Continue to create your circuit.

curl -fsSL https://nzy1997.github.io/rust-qec/install.sh | sh

export PATH="$HOME/.local/bin:$PATH"

set -eu
case "$(uname -s)-$(uname -m)" in
  Linux-x86_64) target=x86_64-unknown-linux-gnu ;;
  Darwin-arm64) target=aarch64-apple-darwin ;;
  *) echo "No validated native archive for this platform" >&2; exit 1 ;;
esac
base=https://github.com/nzy1997/rust-qec/releases/download/v0.3.0
archive="rustqec-v0.3.0-${target}.tar.gz"
curl -fLO "$base/$archive" -O "$base/SHA256SUMS" -O "$base/release-manifest.json"
awk -v archive="$archive" '$2 == archive { n++; record=$0 } END { if(n != 1) exit 1; print record }' SHA256SUMS > "$archive.sha256"
if command -v sha256sum >/dev/null; then
  sha256sum -c "$archive.sha256"
else
  shasum -a 256 -c "$archive.sha256"
fi
tar -xzf "$archive"
export PATH="$(pwd)/${archive%.tar.gz}/bin:$PATH"
rustqec capabilities --format json

rustqec capabilities --format json

2. Create and inspect a circuit

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

rustqec circuit stats --format json --in circuit.stim

Expected fields in result: instruction_count: 5, num_qubits: 1, num_measurements: 1, num_detectors: 1, num_observables: 1.

3. Sample and verify a detector event

rustqec circuit detect --in circuit.stim --shots 1 --out-format dets --append-observables --out events.dets
rustqec circuit dem --in circuit.stim --out model.dem
cat events.dets model.dem

shot D0 L0
error(1) D0 L0

The X error has probability 1. The detector stream therefore contains D0 and logical observable L0; the DEM records the same probability-1 event. This small example verifies installation and the command path; it is not a numerical-performance benchmark.

Which command should I use?

Add optional CLI features

cargo install --locked rustqec-cli --version 0.3.0 --features ilp

The default install already includes circuit and dataset tools plus envelope matching. Use this optional reinstall for exact envelope MLE, after installing the native solver build prerequisites. Official native archives include ILP and the viewer. Use rustqec capabilities --format json to inspect your binary.

For the complete Stim-style compatibility command, install rstim separately with cargo install --locked rstim --version 0.3.0 --bin rstim --features cli,codegen-css,shot-viewer. Internal benchmark workers are not installed by default. rilpqec always includes HiGHS; enabling its Gurobi feature adds a separately configured backend. See the crate publishing and feature guide.

Build the development version from source

Guides that require a repository checkout use the source below. To reproduce a published release, use the v0.3.0 source instructions instead. Current development builds are tested with Rust 1.88.0 (MSRV) and stable on the two native targets above. Install Rust and the platform's native build dependencies before building.

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

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

git clone --branch master --depth 1 https://github.com/nzy1997/rust-qec.git
cd rust-qec
cargo build --locked --workspace --features rstim/cli,rstim/codegen-css,rstim/shot-viewer,rustqec-cli/ilp
export PATH="$(pwd)/target/debug:$PATH"

git clone --branch v0.3.0 --depth 1 https://github.com/nzy1997/rust-qec.git rust-qec-v0.3.0
cd rust-qec-v0.3.0
cargo build --locked --workspace --features rstim/cli,rstim/codegen-css,rstim/shot-viewer,rustqec-cli/ilp
export PATH="$(pwd)/target/debug:$PATH"

You can now run the same circuit example. Benchmark workflows may additionally need Python dependencies; use the setup guide linked from each workflow. The development build guide describes test prerequisites.

Version and support boundaries

This documentation follows master and may include features not yet released. A stable documentation edition is not yet available. Installation examples and external Rust API links use published v0.3.0 packages; guides that need newer features explicitly require a source checkout.

Atom-loss envelope decoding is beta; experimental benchmark workflows do not establish universal performance or publication readiness. Read the support and migration contract and evidence guide before applying results to another circuit.