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.