Skip to main content

Crate pymatching

Crate pymatching 

Source
Expand description

Safe Rust bindings for the vendored PyMatching decoder.

The crate exposes the current Rust surface of the workspace’s pymatching-cxx bridge, with explicit support types for graph construction, decoding options, and optional ecosystem adapters.

§Quick start

use ndarray::array;
use pymatching::{CheckMatrixOptions, Matching};

let check_matrix = array![[1_u8, 1, 0], [0, 1, 1]];
let matching = Matching::from_check_matrix(
    check_matrix.view(),
    CheckMatrixOptions::new(),
)?;

let prediction = matching.decode(array![1_u8, 0].view())?;
assert_eq!(prediction.len(), 3);

§Building graphs directly

use pymatching::{EdgeData, Matching};

let mut matching = Matching::default();
matching.add_edge(0, 1, EdgeData::new(vec![0]).with_weight(2.0))?;
matching.add_boundary_edge(1, EdgeData::new(vec![1]))?;

assert!(matching.has_edge(0, 1));
assert!(matching.has_boundary_edge(1));
assert_eq!(matching.num_edges(), 2);

§Decoder modes

ModeConstructionSingle syndromeBatch
Raw matchingAny graphMatching::decodeMatching::decode_batch
Correlated matchingStim model with correlations enabledMatching::decode_with_optionsMatching::decode_batch_with_options
Raw GAPStim model, correlations disabledMatching::decode_gapMatching::decode_gap_batch
Correlated GAPStim model, correlations enabledMatching::decode_gapMatching::decode_gap_batch

Native correlated hard decoding is selected with DecodeOptions::with_enable_correlations. GAP follows the construction setting automatically and remains basis agnostic: logical cuts are inferred from graph fault ids.

§Stim interop

Stim-backed constructors accept the safe Rust stim::Circuit and stim::DetectorErrorModel types directly. Their C++ representation stays private to the FFI boundary.

Modules§

bit_packing
Little-endian bit packing used by batch decoding.

Structs§

BatchDecodeResult
Predictions and optional matching weights for a batch of syndromes.
CheckMatrixOptions
Controls construction of a matching graph from a binary check matrix.
DecodeOptions
Options shared by single-shot and batch matching decoders.
DecodeResult
Prediction and optional matching weight for one syndrome.
EdgeData
Attributes attached to an edge in a Matching graph.
EdgeRecord
An edge and its endpoints returned by Matching::edges.
GapBatchPrediction
GAP results for a batch of syndromes.
GapPrediction
GAP result for one syndrome.
Matching
A minimum-weight perfect matching decoder and its decoding graph.
NoiseSample
A sampled physical-fault vector and its resulting syndrome.

Enums§

MatchingError
Error returned by safe matching-graph and decoder operations.
MergeStrategy
Policy used when an edge already exists between two endpoints.

Functions§

upstream_commit
Returns the pinned upstream PyMatching Git commit used by the C++ bridge.

Type Aliases§

MatchedDetectors
Detection-event matches keyed by detector index.
Result
Result type used by the safe pymatching API.