pymatching 0.1.0

Safe Rust bindings for the PyMatching quantum error-correction decoder
Documentation

pymatching

pymatching is the safe Rust surface in this workspace. It wraps the vendored PyMatching C++ core through pymatching-cxx and exposes a Rust-first API for constructing matching graphs, loading check matrices, decoding syndromes, and bridging to optional ecosystem adapters.

Current API surface

Core graph construction:

  • Matching::default
  • Matching::add_edge
  • Matching::add_boundary_edge
  • Matching::set_boundary_nodes
  • Matching::ensure_num_fault_ids

Graph inspection and queries:

  • Matching::has_edge
  • Matching::has_boundary_edge
  • Matching::num_nodes
  • Matching::num_edges
  • Matching::num_fault_ids
  • Matching::num_detectors
  • Matching::boundary
  • Matching::boundary_nodes
  • Matching::edge_data
  • Matching::boundary_edge_data
  • Matching::edges

Decoding:

  • Matching::decode
  • Matching::decode_with_options
  • Matching::decode_gap
  • Matching::decode_gap_batch
  • Matching::decode_batch
  • Matching::decode_batch_with_options
  • Matching::decode_batch_with_weights
  • Matching::decode_to_edges_array
  • Matching::decode_to_edges_array_with_options
  • Matching::decode_to_matched_dets_array
  • Matching::decode_to_matched_dets_dict
  • Matching::add_noise

Loaders and adapters:

  • Matching::from_check_matrix
  • Matching::load_check_matrix
  • Matching::from_detector_error_model_with_options
  • Matching::from_stim_circuit_with_options
  • Matching::from_detector_error_model_file
  • Matching::from_stim_circuit_file
  • TryFrom<&stim::DetectorErrorModel> for Matching
  • TryFrom<stim::DetectorErrorModel> for Matching
  • TryFrom<&stim::Circuit> for Matching
  • TryFrom<stim::Circuit> for Matching
  • Matching::load_rustworkx behind the rustworkx feature
  • Matching::to_rustworkx behind the rustworkx feature
  • TryFrom<&rustworkx_core::petgraph::graph::UnGraph<bool, EdgeData>> for Matching behind the rustworkx feature
  • TryFrom<rustworkx_core::petgraph::graph::UnGraph<bool, EdgeData>> for Matching behind the rustworkx feature
  • TryFrom<&sprs::CsMat<u8>> for Matching behind the sprs feature
  • TryFrom<sprs::CsMat<u8>> for Matching behind the sprs feature

Option builders and helpers:

  • DecodeOptions::new
  • DecodeOptions::with_return_weight
  • DecodeOptions::with_bit_packed_shots
  • DecodeOptions::with_bit_packed_predictions
  • DecodeOptions::with_enable_correlations
  • CheckMatrixOptions::new
  • CheckMatrixOptions::with_weights
  • CheckMatrixOptions::with_error_probabilities
  • CheckMatrixOptions::with_faults_matrix
  • CheckMatrixOptions::with_merge_strategy
  • CheckMatrixOptions::with_repetitions
  • CheckMatrixOptions::with_timelike_weights
  • CheckMatrixOptions::with_measurement_error_probabilities
  • CheckMatrixOptions::with_virtual_boundary_node
  • bit_packing::required_packed_bytes
  • bit_packing::pack_bits_le
  • bit_packing::unpack_bits_le
  • upstream_commit

Public support types:

  • Matching
  • EdgeData
  • EdgeData::new
  • EdgeData::with_weight
  • EdgeData::with_error_probability
  • EdgeData::{fault_ids, weight, error_probability}
  • EdgeRecord
  • EdgeRecord::new
  • EdgeRecord::{node1, node2, data}
  • DecodeOptions
  • DecodeResult
  • DecodeResult::{prediction, weight}
  • BatchDecodeResult
  • BatchDecodeResult::{predictions, weights}
  • GapPrediction
  • GapPrediction::{prediction, gaps}
  • GapBatchPrediction
  • GapBatchPrediction::{predictions, gaps}
  • CheckMatrixOptions
  • NoiseSample
  • NoiseSample::{errors, syndrome}
  • MergeStrategy
  • MergeStrategy::{Disallow, Independent, SmallestWeight, KeepOriginal, Replace}
  • MatchedDetectors
  • MatchingError
  • MatchingError::InvalidProbability { probability }
  • MatchingError::MissingEdge { node1, node2 }
  • MatchingError::MissingBoundaryEdge { node }
  • MatchingError::InvalidInput(&'static str)
  • MatchingError::Upstream(String)
  • Result<T>

Batch decoder modes

Mode Construction Batch method
Raw matching Any graph decode_batch
Native correlated matching Stim model loaded with correlations; enable correlations in DecodeOptions decode_batch_with_options
Raw GAP Stim model loaded without correlations decode_gap_batch
Correlated GAP Stim model loaded with correlations decode_gap_batch

GAP returns a hard prediction and an absolute class-weight gap for every (shot, observable) pair. It infers logical cuts from graph fault IDs and does not require a Pauli-basis option.

Native build

The C++ bridge discovers the matching Stim headers from the shared stim-cxx dependency automatically. No include-path environment variable is required.