Registry / ai-ml / pymatching

pymatching

JSON →
library2.4.0pypypi✓ verified 87d ago

PyMatching is a high-performance Python package for decoding quantum error correcting codes using minimum-weight perfect matching algorithms. It provides an efficient C++ implementation of the blossom algorithm, significantly speeding up decoding for large codes. The library is actively maintained with frequent minor releases for bug fixes and feature additions, and major updates approximately every 1-2 years introducing significant architectural changes or performance improvements. The current version is 2.3.1.

pip install pymatching
INSTALL
IMPORT
SIG · PYMATCHING
P
pymatching
ai-mlpythonv2.4.0
Install
12.4s avg
Import
1652ms
Disk
333MB
Pass rate
5/ 10
Env Coverage5 / 10
glibc
3.93.13
musl
3.93.13
Install & Compatibility
Where this runs
tested against v2.4.0 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
py 3.103.910 runs
build_error
glibc
py 3.103.910 runs
installs and imports cleanly · install 12.4s · import 1.652s · 322MB
333MB installed
● package 333MB
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

Matching
from pymatching import Matching

This quickstart demonstrates how to create a `Matching` object from a `scipy.sparse` matrix representing a parity check matrix, simulate a syndrome, and decode it to find the most likely error pattern.

import pymatching import numpy as np import scipy.sparse # Example: Parity check matrix (H) for a simple [3,1,2] repetition code # This H matrix represents two stabilizers: qubit0^qubit1 and qubit1^qubit2 H = scipy.sparse.csc_matrix(np.array([ [1, 1, 0], [0, 1, 1] ])) # Initialize the Matching object from the parity check matrix matching = pymatching.Matching(H) # Simulate a syndrome measurement (e.g., after an error on qubit 1) # An error on qubit 1 flips both stabilizers (syndrome = [1, 1]) syndrome = np.array([1, 1]) # Decode the syndrome to find the most likely error pattern # The result 'correction' is a binary vector indicating the predicted error locations correction = matching.decode(syndrome) print(f"Input syndrome: {syndrome}") print(f"Predicted error pattern: {correction}") # Expected output for syndrome [1,1]: [0, 1, 0] (error on qubit 1)
Debug
Known issues
breakingPyMatching v2.0.0 introduced a complete rewrite of the C++ extension, including a new implementation of the blossom algorithm. This resulted in significant performance improvements (100-1000x faster) and the decoding is now exact, unlike the 'local matching' approximation used in v0.7 and earlier. Code written for v0.x might need adjustments if it relied on internal approximations or specific performance characteristics.
fix
Upgrade to v2.0.0+ and verify decoding logic and performance. The public API generally remained stable, but internal behavior for large codes changed significantly.
affects: <2.0.0
deprecatedThe `retworkx` package and its related methods (`Matching.load_from_retworkx`, `Matching.to_retworkx`) were deprecated in v2.2.0 due to `retworkx` being renamed to `rustworkx`. While they may still function for a time, they will eventually be removed.
fix
Migrate to `rustworkx` and use `Matching.load_from_rustworkx` and `Matching.to_rustworkx` methods instead. `rustworkx` is not a direct dependency, so install it explicitly if needed (`pip install rustworkx`).
affects: >=2.2.0
gotchaPyMatching v2.2.1 temporarily pinned the `numpy` dependency to `numpy==1.*` due to incompatibility with `numpy` v2.0.0. Full support for `numpy` v2 was re-added in PyMatching v2.2.2. Users attempting to install PyMatching with `numpy` v2.0.0 or later on PyMatching versions between 2.2.1 and 2.2.2 might encounter installation errors or runtime issues.
fix
Ensure you are using PyMatching v2.2.2 or later if you wish to use `numpy` v2.0.0+. Alternatively, downgrade `numpy` to a v1.x version for older PyMatching releases.
affects: ==2.2.1
gotchaFor decoding multiple shots (batches of syndromes), `Matching.decode_batch` is significantly faster than iterating in Python and calling `Matching.decode` for each individual shot. This is especially true for smaller/easier decoding problems.
fix
When processing multiple syndrome measurements, use `matching.decode_batch(syndromes_batch)` where `syndromes_batch` is a 2D array of syndromes, typically `(num_shots, num_stabilizers)`.
affects: >=2.1.0
gotchaThe correlated matching feature, introduced in PyMatching v2.3.0, had a couple of minor bugs that could lead to a segmentation fault for certain circuits or incorrect reweights in rare cases. These were fixed in v2.3.1.
fix
If using correlated matching, ensure you upgrade to PyMatching v2.3.1 or later to avoid potential segmentation faults and incorrect behavior.
affects: ==2.3.0
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'pymatching'
The pymatching package is not installed or not accessible in the current Python environment.
fix
Install the package using pip: `pip install pymatching`
AttributeError: 'Matching' object has no attribute 'load_from_retworkx'
You are using a PyMatching version (>=2.2.0) where `retworkx` methods have been deprecated/removed, and replaced by `rustworkx` methods.
fix
Change your code to use `matching.load_from_rustworkx()` or `matching.to_rustworkx()`. Ensure `rustworkx` is installed (`pip install rustworkx`).
TypeError: Input matrix must be a scipy.sparse matrix, a networkx.Graph, or rustworkx.PyGraph.
The input provided when constructing `pymatching.Matching(graph)` is not in a supported format (e.g., a dense NumPy array or an incorrect object type).
fix
Convert your graph representation to a `scipy.sparse` matrix (e.g., `scipy.sparse.csc_matrix`), `networkx.Graph`, or `rustworkx.PyGraph` before passing it to the `Matching` constructor.
Segmentation fault (core dumped)
When using the correlated matching feature, a bug in PyMatching v2.3.0 could lead to a segfault for specific circuits.
fix
Upgrade PyMatching to v2.3.1 or later. This bug was specifically addressed and fixed in that release.
Upgrade
Version history
2.4.0latest on PyPI · released May 22, 2026
Audit
Dependencies
numpyrequiredFundamental numerical computing library, used internally and for data structures.
scipyoptionalCommonly used for creating sparse matrices (e.g., `scipy.sparse.csc_matrix`) which are a primary input format for `pymatching.Matching` graph construction.
rustworkxoptionalCan be used for graph construction and conversion; replaced `retworkx` in v2.2.0.
Agent activity
7 hits · last 30 days
node
4
OpenAI (training)
1
Resources
pymatching — pip install pymatching · libregistry