Decode with three solver families

Decode your first detector rows

Rust and Cargo required. The example pins its dependency in Cargo.toml. This standalone example needs no repository checkout, Python, or native solver.

Use a graphlike model with two detectors and one logical observable. For syndrome 11, one joint error is more likely than two independent boundary errors, so matching predicts L0=1. The control row 00 predicts L0=0.

The probability-1 DEM from the installation check is not supported by rmatching. Use this separate probability-0.1 model to learn decoding; detector inputs contain no observable answers.

1. Create a standalone Rust project

mkdir qec-first-decode
cd qec-first-decode
mkdir src

Save as Cargo.toml:

[package]
name = "qec-first-decode"
version = "0.1.0"
edition = "2024"

[dependencies]
rmatching = "=0.3.0"

[workspace]

2. Save the model and detector rows

cat > model.dem <<'DEM'
error(0.1) D0 D1 L0
error(0.1) D0
error(0.1) D1
DEM
cat > detectors.01 <<'SHOTS'
11
00
SHOTS

Each character in detectors.01 is a detector bit, ordered D0 then D1. These are two explicit test cases, not a sampled logical-error-rate estimate.

3. Decode and inspect the prediction

Save as src/main.rs:

use rmatching::Matching;
use std::{error::Error, fs};

fn main() -> Result<(), Box<dyn Error>> {
    let dem = fs::read_to_string("model.dem")?;
    let mut matching = Matching::from_dem(&dem)?;
    let rows = fs::read_to_string("detectors.01")?;
    for (index, row) in rows.lines().enumerate() {
        // This example's model has exactly two detectors, D0 and D1.
        if row.len() != 2 || !row.bytes().all(|bit| matches!(bit, b'0' | b'1')) {
            return Err(format!("row {}: expected two detector bits, e.g. 11", index + 1).into());
        }
        let syndrome: Vec<u8> = row.bytes().map(|bit| bit - b'0').collect();
        let prediction = matching.decode(&syndrome);
        println!("row {}: predicted L0={}", index + 1, prediction[0]);
    }
    Ok(())
}

cargo run --quiet

row 1: predicted L0=1
row 2: predicted L0=0

For these constructed cases, the predicted bits match the chosen error events. With real samples, compare predictions to held-out observable flips to count logical failures; the decoder must only receive detector bits.

4. Use your own model

Replace the DEM and input rows together. The row width must equal the model's detector count, and rmatching supports graphlike error components with at most two detectors and probabilities 0 ≤ p < 1. Adapt this example's two-bit validation to your model; do not simply truncate rows. Under atom loss, first construct loss-aware detector inputs.

Run from a configured repository checkout. These commands are not included in the two-binary native archive. Install the surface comparison Python environment or follow the BB comparison setup before its matching command. Successful smoke runs produce local result files; they check wiring, not decoder ranking.

make surface-decoder-compare-smoke
make bb-circuit-bposd-compare-smoke