# `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
| 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.