pymatching 0.1.0

Safe Rust bindings for the PyMatching quantum error-correction decoder
Documentation
//! 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);
//! # Ok::<(), pymatching::MatchingError>(())
//! ```
//!
//! # 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);
//! # Ok::<(), pymatching::MatchingError>(())
//! ```
//!
//! # Decoder modes
//!
//! | Mode | Construction | Single syndrome | Batch |
//! | --- | --- | --- | --- |
//! | Raw matching | Any graph | [`Matching::decode`] | [`Matching::decode_batch`] |
//! | Correlated matching | Stim model with correlations enabled | [`Matching::decode_with_options`] | [`Matching::decode_batch_with_options`] |
//! | Raw GAP | Stim model, correlations disabled | [`Matching::decode_gap`] | [`Matching::decode_gap_batch`] |
//! | Correlated GAP | Stim model, correlations enabled | [`Matching::decode_gap`] | [`Matching::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.

#![warn(missing_docs, rustdoc::broken_intra_doc_links)]

pub mod bit_packing;

mod adapters;
mod check_matrix;
mod decode;
mod error;
mod export;
mod matching;
mod types;

pub use error::{MatchingError, Result};
pub use matching::Matching;
pub use types::{
    BatchDecodeResult, CheckMatrixOptions, DecodeOptions, DecodeResult, EdgeData, EdgeRecord,
    GapBatchPrediction, GapPrediction, MatchedDetectors, MergeStrategy, NoiseSample,
};

/// Returns the pinned upstream PyMatching Git commit used by the C++ bridge.
#[must_use]
pub fn upstream_commit() -> &'static str {
    pymatching_cxx::pinned_pymatching_commit()
}