Package: beliefmatching
BeliefMatchingAn implementation of thebelief-matchingdecoder, usingpymatchingfor the minimum-weight perfect matching (MWPM) subroutine and
theldpclibrary for the belief propagation (BP) subroutine.
Belief-matching is more accurate than the MWPM decoder alone when hyperedge error mechanisms are present in the error
model.
Belief-matching has the same worst-case complexity as minimum-weight perfect matching, and the expected running time is roughly linear in the size of the decoding problem (Tanner graph).
See thepaperfor more details.However, note that this implementation is much (>100x) slower than just using the pymatching (v2)
decoder alone, since it has not been optimised for performance.
For example, for each shot, belief propagation is run on the full Tanner graph (stimDetectorErrorModel) with
the output used to construct a new instance of a pymatchingMatchingobject.
This implementation uses theldpclibrary for BP, which uses a
parallel BP schedule, and does not support the serial BP schedule shown to have slightly improved accuracy
for belief-matching in the appendix ofthis paper.InstallationTo install beliefmatching, run:pipinstallbeliefmatchingTo install from source, run:pipinstall-e.from the root directory.UsageHere is an example of how the decoder can be used directly with Stim:importstimimportnumpyasnpfrombeliefmatchingimportBeliefMatchingnum_shots=100d=5p=0.007circuit=stim.Circuit.generated("surface_code:rotated_memory_x",rounds=d,distance=d,before_round_data_depolarization=p,before_measure_flip_probability=p,after_reset_flip_probability=p,after_clifford_depolarization=p)sampler=circuit.compile_detector_sampler()shots,observables=sampler.sample(num_shots,separate_observables=True)bm=BeliefMatching(circuit,max_bp_iters=20)predicted_observables=bm.decode_batch(shots)num_mistakes=np.sum(np.any(predicted_observables!=observables,axis=1))print(f"{num_mistakes}/{num_shots}")# prints 4/100Note that, as well as loading directly from astim.Circuitas above, you can also
load from astim.DetectorErrorModel. When using this option it is important thatdecompose_errors=Trueis set when callingcircuit.detector_error_model. E.g.:dem=circuit.detector_error_model(decompose_errors=True)bm=BeliefMatching(dem,max_bp_iters=20)Sinter integrationTo integrate withsinter, you can use thesinter.BeliefMatchingSinterDecoderclass, which inherits fromsinter.Decoder.
To use it, you can use thecustom_decodersargument when usingsinter.collect:importsinterfrombeliefmatchingimportBeliefMatchingSinterDecodersamples=sinter.collect(num_workers=4,max_shots=1_000_000,max_errors=1000,tasks=generate_example_tasks(),decoders=['beliefmatching'],custom_decoders={'beliefmatching':BeliefMatchingSinterDecoder()})A complete example using sinter to compare beliefmatching with pymatching
can be found in theexamples/surface_code_threshold.pyfile (this file also
includes a definition ofgenerate_example_tasks()used above).TestsTests can be run by installing pytest withpipinstallpytestand runningpytesttestsAttributionWhen using thisbeliefmatchingfor research, please cite
thepaper:@article{PhysRevX.13.031007,
  title = {Improved Decoding of Circuit Noise and Fragile Boundaries of Tailored Surface Codes},
  author = {Higgott, Oscar and Bohdanowicz, Thomas C. and Kubica, Aleksander and Flammia, Steven T. and Campbell, Earl T.},
  journal = {Phys. Rev. X},
  volume = {13},
  issue = {3},
  pages = {031007},
  numpages = {20},
  year = {2023},
  month = {Jul},
  publisher = {American Physical Society},
  doi = {10.1103/PhysRevX.13.031007},
  url = {https://link.aps.org/doi/10.1103/PhysRevX.13.031007}
}