PyMatching v2.3.1

PyMatching v2.3.1

Changes made for v2.3.1

This release contains a couple of minor bug fixes for correlated pymatching:

• Fixes a bug (issue #175) where certain circuits could lead to a seg fault when using correlations
• Fixes a bug where reweights were not full undone for correlations in rare cases (see PR #169)

PyMatching v2.3.0

Changes made for v2.3.0

Features and improvements

• PyMatching now has correlations! Thank you to Sid Madhuk (@smadhuk), who was the main contributor for this new feature (PR #156). The method used is from this paper: https://arxiv.org/abs/1310.0863. Correlated matching has better accuracy than standard (uncorrelated) matching for many decoding problems where hyperedge errors are present. When these hyperedge errors are decomposed into edges (graphlike errors), they amount to correlations between these edges in the matching graph. A common example of such a hyperedge error is a $Y$ error in the surface code. The "two-pass" correlated matching decoder implemented in pymatching works by running sparse blossom twice. The first pass is a standard (uncorrelated) run of sparse blossom, to predict a set of edges in the matching graph. Correlated matching then assumes these errors (edges) occurred and reweights edges that are correlated with it based on this assumption. Matching is then run for the second time on this reweighted graph.
• The pymatching.Matching object can be configured for correlations by setting enable_correlations=True when using:
  • The constructor pymatching.Matching.__init__ with a stim circuit/dem
  • The static method pymatching.Matching.from_detector_error_model
  • The static method pymatching.Matching.from_stim_circuit
• Correlations can be used when decoding by setting enable_correlations=True when using the methods:
  • pymatching.Matching.decode
  • pymatching.Matching.decode_batch
  • pymatching.Matching.decode_to_edges_array
• The command line interface for pymatching can also have correlations enabled using the --enable_correlations argument

Here's a plot showing the improved accuracy from enabling correlations (which runs around 2x-3x slower than uncorrelated matching):

Minor breaking changes to the API

• The legacy positional arguments _legacy_num_neighbours and _legacy_return_weight for pymatching.Matching.decode, which previously resulted in a warning when used (since pymatching v2.0.0) have now been removed entirely. They were introduced in pymatching v2.0.0 to (1) convert the conditional argument return_weight to be a keyword-only argument without breaking changes and (2) remove the positional argument num_neighbours that is not used in pymatching v2.

PyMatching v2.2.2

Changes made for v2.2.2

• Adds support for Numpy v2
• Add pre-built binaries for Python 3.13
• Add support for stim circuit/DEM tags (update C++ stim dependency)
• Remove pre-built binaries for Python 3.7

PyMatching v2.2.1

Changes made for v2.2.1

Support added for PowerPC architecture (#92 and #94)

The numpy python dependency is now pinned to major version 1 (numpy==1.*) since the recent v2 release is not yet supported.

PyMatching v2.2.0

Changes made for v2.2.0

Support added for using pymatching as a C++ dependency (see changes in #77)

Renamed retworkx to rustworkx (since the retworkx package name has been deprecated):

• Added methods Matching.load_from_rustworkx and Matching.to_rustworkx
• DeprecationWarning added to Matching.load_from_retworkx and Matching.to_retworkx
• retworkx dependency removed. rustworkx has not been added as a dependency, and instead an ImportError is raised if Matching.load_from_rustworkx or Matching.to_rustworkx are used without rustworkx installed.

PyMatching now requires Python>=3.7 (rather than Python>=3.6)

Fixes an issue where multiple boundary nodes could sometimes lead to boundary edges being merged incorrectly (issue #81, fixed in #86)

PyMatching v2.1.0

Features and improvements

Added the following methods to pymatching.Matching:

• pymatching.Matching.decode_batch: decodes a batch of (optionally bit-packed) shots to decode, instead of just a single shot (as done by pymatching.Matching.decode). For smaller/easier problems, Matching.decode_batch is much faster than iterating over the shots in python and calling Matching.decode for each one. E.g. When decoding d=11,rounds=11, p=0.1% surface code circuits, looping over Matching.decode in python is 1us per round vs 0.37us per round using Matching.decode_batch. For d=5,rounds=5, p=0.01%, looping Matching.decode in python is 0.8us per round vs 0.02us per round with Matching.decode_batch.
• pymatching.Matching.decode_to_edges_array: returns the solution as an array of edges (given as pairs of detector node indices).
• pymatching.Matching.from_detector_error_model_file
• pymatching.Matching.from_stim_circuit
• pymatching.Matching.from_stim_circuit_file

Adds pymatching.cli, which provides access to the pymatching command line tool via the Python API.

Adds the pymatching console script entry point to the setup.py. Makes the pymatching command line tool available when pip installing.

Bug fixes

Fixes a bug in the command line tool where b8-formatted stim dets files couldn't be read on windows machines (also causing issues with sinter, which uses the command line tool).

PyMatching v2.0.1

This patch release fixes an issue where placing a detection event on a node marked as a boundary node in the Python API would lead to an exception being raised (issue #41).

PyMatching v2.0.0

Changes made for v2.0

Flagship changes:

• The C++ extension has been completely rewritten, and includes a new implementation of the blossom algorithm
• PyMatching v2.0 is now around 100-1000x faster than PyMatching v0.7 for decoding surface codes with circuit-level noise
• The new implementation is also exact. It does not make the "local matching" approximation used in v0.7 and earlier,
  which resulted in a reduction in accuracy for very large surface code circuits
• The runtime of the new version is approximately linear in the size of the graph, and can process between 1 and 10
  million detection events per second

Features and improvements

• Decoding speeds improved 100-1000x

• pymatching.Matching.load_from_check_matrix is around 30x faster

• Added methods to pymatching.Matching:

  • pymatching.Matching.add_boundary_edge
  • pymatching.Matching.decode_to_matched_dets_array
  • pymatching.Matching.decode_to_matched_dets_dict
  • pymatching.Matching.has_edge
  • pymatching.Matching.get_edge_data
  • pymatching.Matching.set_min_num_fault_ids

• Added static methods to pymatching.Matching:

  • pymatching.Matching.from_detector_error_model
  • pymatching.Matching.from_check_matrix (static method equivalent to constructing a new pymatching.Matching and
    then calling pymatching.Matching.load_from_check_matrix)

• merge_strategy argument added to pymatching.Matching.add_edge, pymatching.Matching.add_boundary_edge and
  pymatching.Matching.load_from_check_matrix. When an attempt is made to
  add an edge already present in the graph, the following strategies are available:

  • disallow: raises a ValueError if a parallel edge is added
  • independent: edge weights and error probabilities updated treating the parallel edges as independent error mechanisms
  • smallest-weight: The edge with the smallest weight is kept
  • keep-original: The existing edge is kept and the new edge is silently ignored
  • replace: Only the edge being added is kept

• faults_matrix argument added to pymatching.Matching.from_check_matrix. faults_matrix is an array that can be used to set
  the fault_ids attribute of edges in a graph loaded from a check matrix. For example, faults_matrix can be used to specify the
  logical observables whose outcome should be predicted by the decoder.

Minor changes to the API

• spacelike_weights renamed to weights in pymatching.Matching.load_from_check_matrix. But spacelike_weights
  still accepted for backward compatibility.
• H renamed to graph in the constructor for pymatching.Matching. H still accepted for backward compatibility.
• precompute_shortest_paths argument removed from constructor (won't break if supplied)
• Both a virtual boundary node (via pymatching.Matching.add_boundary_edge) and a regular boundary node are supported.
  These are treated equivalently by the decoder, but are treated differently by pymatching.Matching.edges,
  pymatching.Matching.to_networkx and pymatching.Matching.to_retworkx

Minor breaking changes to the API

• pymatching.Matching.matching_graph renamed to pymatching.Matching._matching_graph (since this property is only
  intended to be used internally to access the C++ extension)
• pymatching.Matching.decode arguments after the first argument are now keyword-only, and num_neighbours has been
  removed as an argument. Users' code won't break or raise a warning if they already used keyword arguments (and num_neighbours is
  silently ignored when provided). If users provide num_neighbours or return_weight as a positional argument, a deprecation warning is raised.
• pymatching.Matching.compute_all_pairs_shortest_paths method removed

Bug fixes

• Fixed a bug where timelike error probabilities were set incorrectly if provided as a scalar

PyMatching v0.7.0

Adds support for creating Matching objects from retworkx graphs

PyMatching v0.6.1

Improves the error message for parallel edges.