{"id":10110,"library":"pymatching","title":"PyMatching","description":"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.","status":"active","version":"2.3.1","language":"en","source_language":"en","source_url":"https://github.com/oscarhiggott/PyMatching","tags":["quantum-error-correction","decoding","matching","graph-algorithms","quantum-computing"],"install":[{"cmd":"pip install pymatching","lang":"bash","label":"Install stable version"}],"dependencies":[{"reason":"Fundamental numerical computing library, used internally and for data structures.","package":"numpy","optional":false},{"reason":"Commonly used for creating sparse matrices (e.g., `scipy.sparse.csc_matrix`) which are a primary input format for `pymatching.Matching` graph construction.","package":"scipy","optional":true},{"reason":"Can be used for graph construction and conversion; replaced `retworkx` in v2.2.0.","package":"rustworkx","optional":true}],"imports":[{"symbol":"Matching","correct":"from pymatching import Matching"}],"quickstart":{"code":"import pymatching\nimport numpy as np\nimport scipy.sparse\n\n# Example: Parity check matrix (H) for a simple [3,1,2] repetition code\n# This H matrix represents two stabilizers: qubit0^qubit1 and qubit1^qubit2\nH = scipy.sparse.csc_matrix(np.array([\n    [1, 1, 0],\n    [0, 1, 1]\n]))\n\n# Initialize the Matching object from the parity check matrix\nmatching = pymatching.Matching(H)\n\n# Simulate a syndrome measurement (e.g., after an error on qubit 1)\n# An error on qubit 1 flips both stabilizers (syndrome = [1, 1])\nsyndrome = np.array([1, 1])\n\n# Decode the syndrome to find the most likely error pattern\n# The result 'correction' is a binary vector indicating the predicted error locations\ncorrection = matching.decode(syndrome)\n\nprint(f\"Input syndrome: {syndrome}\")\nprint(f\"Predicted error pattern: {correction}\")\n# Expected output for syndrome [1,1]: [0, 1, 0] (error on qubit 1)","lang":"python","description":"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."},"warnings":[{"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.","message":"PyMatching 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.","severity":"breaking","affected_versions":"<2.0.0"},{"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`).","message":"The `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.","severity":"deprecated","affected_versions":">=2.2.0"},{"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.","message":"PyMatching 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.","severity":"gotcha","affected_versions":"==2.2.1"},{"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)`.","message":"For 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.","severity":"gotcha","affected_versions":">=2.1.0"},{"fix":"If using correlated matching, ensure you upgrade to PyMatching v2.3.1 or later to avoid potential segmentation faults and incorrect behavior.","message":"The 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.","severity":"gotcha","affected_versions":"==2.3.0"}],"env_vars":null,"last_verified":"2026-04-17T00:00:00.000Z","next_check":"2026-07-16T00:00:00.000Z","problems":[{"fix":"Install the package using pip: `pip install pymatching`","cause":"The pymatching package is not installed or not accessible in the current Python environment.","error":"ModuleNotFoundError: No module named 'pymatching'"},{"fix":"Change your code to use `matching.load_from_rustworkx()` or `matching.to_rustworkx()`. Ensure `rustworkx` is installed (`pip install rustworkx`).","cause":"You are using a PyMatching version (>=2.2.0) where `retworkx` methods have been deprecated/removed, and replaced by `rustworkx` methods.","error":"AttributeError: 'Matching' object has no attribute 'load_from_retworkx'"},{"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.","cause":"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).","error":"TypeError: Input matrix must be a scipy.sparse matrix, a networkx.Graph, or rustworkx.PyGraph."},{"fix":"Upgrade PyMatching to v2.3.1 or later. This bug was specifically addressed and fixed in that release.","cause":"When using the correlated matching feature, a bug in PyMatching v2.3.0 could lead to a segfault for specific circuits.","error":"Segmentation fault (core dumped)"}]}