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::defaultMatching::add_edgeMatching::add_boundary_edgeMatching::set_boundary_nodesMatching::ensure_num_fault_ids
Graph inspection and queries:
Matching::has_edgeMatching::has_boundary_edgeMatching::num_nodesMatching::num_edgesMatching::num_fault_idsMatching::num_detectorsMatching::boundaryMatching::boundary_nodesMatching::edge_dataMatching::boundary_edge_dataMatching::edges
Decoding:
Matching::decodeMatching::decode_with_optionsMatching::decode_gapMatching::decode_gap_batchMatching::decode_batchMatching::decode_batch_with_optionsMatching::decode_batch_with_weightsMatching::decode_to_edges_arrayMatching::decode_to_edges_array_with_optionsMatching::decode_to_matched_dets_arrayMatching::decode_to_matched_dets_dictMatching::add_noise
Loaders and adapters:
Matching::from_check_matrixMatching::load_check_matrixMatching::from_detector_error_model_with_optionsMatching::from_stim_circuit_with_optionsMatching::from_detector_error_model_fileMatching::from_stim_circuit_fileTryFrom<&stim::DetectorErrorModel> for MatchingTryFrom<stim::DetectorErrorModel> for MatchingTryFrom<&stim::Circuit> for MatchingTryFrom<stim::Circuit> for MatchingMatching::load_rustworkxbehind therustworkxfeatureMatching::to_rustworkxbehind therustworkxfeatureTryFrom<&rustworkx_core::petgraph::graph::UnGraph<bool, EdgeData>> for Matchingbehind therustworkxfeatureTryFrom<rustworkx_core::petgraph::graph::UnGraph<bool, EdgeData>> for Matchingbehind therustworkxfeatureTryFrom<&sprs::CsMat<u8>> for Matchingbehind thesprsfeatureTryFrom<sprs::CsMat<u8>> for Matchingbehind thesprsfeature
Option builders and helpers:
DecodeOptions::newDecodeOptions::with_return_weightDecodeOptions::with_bit_packed_shotsDecodeOptions::with_bit_packed_predictionsDecodeOptions::with_enable_correlationsCheckMatrixOptions::newCheckMatrixOptions::with_weightsCheckMatrixOptions::with_error_probabilitiesCheckMatrixOptions::with_faults_matrixCheckMatrixOptions::with_merge_strategyCheckMatrixOptions::with_repetitionsCheckMatrixOptions::with_timelike_weightsCheckMatrixOptions::with_measurement_error_probabilitiesCheckMatrixOptions::with_virtual_boundary_nodebit_packing::required_packed_bytesbit_packing::pack_bits_lebit_packing::unpack_bits_leupstream_commit
Public support types:
MatchingEdgeDataEdgeData::newEdgeData::with_weightEdgeData::with_error_probabilityEdgeData::{fault_ids, weight, error_probability}EdgeRecordEdgeRecord::newEdgeRecord::{node1, node2, data}DecodeOptionsDecodeResultDecodeResult::{prediction, weight}BatchDecodeResultBatchDecodeResult::{predictions, weights}GapPredictionGapPrediction::{prediction, gaps}GapBatchPredictionGapBatchPrediction::{predictions, gaps}CheckMatrixOptionsNoiseSampleNoiseSample::{errors, syndrome}MergeStrategyMergeStrategy::{Disallow, Independent, SmallestWeight, KeepOriginal, Replace}MatchedDetectorsMatchingErrorMatchingError::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.