Versions and migration

Select a documentation version

dev follows the development branch. A numbered edition is the frozen documentation for that coordinated software release. The version menu lists published editions; development pages may describe behavior that is newer than the latest stable archive. Keep the edition, binary version and dataset provenance together when reproducing results.

A RustQEC tag identifies a coordinated source release. Individual crates can receive independent patch updates within the same major/minor line. The API index lists the versions built from this checkout; rstim --version and rstim capabilities --format json describe your installed binary.

Upgrade deliberately

For an installed CLI, record capabilities before upgrading, retain original input files, then rerun a small known case. For Rust, update the intended dependency versions and commit Cargo.lock in your application. A native decoder feature is a build choice, not a new dataset schema or an expanded support promise.

The migration notes below come from the same canonical support contract, so code examples and compatibility rules have one maintained source. Historical release details are in GitHub releases.

Mid-SWAP configuration migration

The pre-1.0 Mid-SWAP API no longer accepts the old catch-all pauli_probability field. Replace it with the four named Pauli channels and initialize before_round_data_loss_probability explicitly:

use rstim::codegen::MidSwapConfig;

// Old API: this does not compile against the current release line.
let config = MidSwapConfig {
    distance: 3,
    rounds: 2,
    before_round_data_depolarization: 0.001,
    before_round_data_loss_probability: 0.0,
    after_clifford_depolarization: 0.001,
    before_measure_flip_probability: 0.001,
    after_reset_flip_probability: 0.001,
    operation_loss_probability: 0.0,
    measurement_loss_probability: 0.0,
    pauli_probability: 0.001,
};

use rstim::codegen::{MidSwapConfig, rotated_memory_z_midswap};

let config = MidSwapConfig {
    distance: 3,
    rounds: 2,
    before_round_data_depolarization: 0.001,
    before_round_data_loss_probability: 0.0,
    after_clifford_depolarization: 0.001,
    before_measure_flip_probability: 0.001,
    after_reset_flip_probability: 0.001,
    operation_loss_probability: 0.0,
    measurement_loss_probability: 0.0,
};
let circuit = rotated_memory_z_midswap(config).unwrap();
assert!(!circuit.is_empty());

The valid form is compiled by the MidSwapConfig rustdoc test. The obsolete form is intentionally marked compile_fail; it documents a migration rather than a compatibility shim.

Compatibility and deprecation policy

RustQEC is pre-1.0. Public Rust APIs, JSON schemas, CLI arguments, defaults, and generated formats can change between release lines. A compatibility promise exists only where a format reference, a version field, or a structured CLI contract says so. In particular, QP101-ZY is governed by rstim/doc/QP101-ZY.md; other experimental exports should be treated as release-line specific unless they state a versioned compatibility policy.

Deprecations are documented in the affected API or command reference with a migration path when one exists. The Mid-SWAP field rename above is an example: the removed field remains a compile-time error so callers must choose the four separate channels rather than receive an implicit mapping.

The repository tag identifies a coordinated RustQEC source release. Published workspace crates share its major/minor release line, while package-only patch releases can advance independently. Inspect each crate's Cargo.toml and Cargo metadata when reproducing an exact package version.

Cargo features in the 0.3 release line

The 0.3 source package defaults keep native solver dependencies optional. rstim needs --features ilp for envelope-mle; default builds advertise only the available decoder choices. Official native archives retain ILP support. rsinter needs explicit runner/plotting features, or full for the previous complete research setup. These changes do not alter immutable v0.2.1 archives. See the crate guide for installation and migration commands.

rmatching::Matching::try_decode_shots_bit_packed returns a typed error for incorrect dimensions, buffer lengths, or batch-size overflow. It counts declared unused detectors/observables as part of the graph. The older infallible method remains available and documents its panic conditions. The DEM importer supports probabilities 0 <= p < 1; probability-1 errors require a different representation and are rejected explicitly. This restriction does not apply to rstim sampling or DEM generation, including the probability-1 installed quickstart.

Library defaults now omit compatibility CLI parsing, CSS generation, the local viewer, and native ILP backends. Enable rstim features cli, codegen-css, and shot-viewer where needed; qec-code/cli enables its executable and qec-ilp-core/highs enables its open-source solver. Full native archives retain the viewer. rmatching benchmark binaries moved to the unpublished rmatching-bench-tools workspace member. See the feature migration guide.