bloqade-decoders

The QEC user interface providing integration with popular open-source decoders for the Bloqade SDK.

By default, the following decoders from the ldpc package and their corresponding interfaces are immediately available for decoding use upon installation of this package:

• BP+OSD - through bloqade.decoders.BpOsdDecoder
• BP+LSD - through bloqade.decoders.BpLsdDecoder
• Belief Find - through bloqade.decoders.BeliefFindDecoder

Interfaces also exist for the following optional decoders, which are not included as dependencies by default:

• MWPF - through bloqade.decoders.MWPFDecoder (MWPF)
• Tesseract - through bloqade.decoders.TesseractDecoder (Tesseract)
• MLE (MILP) - through bloqade.decoders.MILPDecoder, finds the most likely error pattern via mixed-integer programming (PuLP; HiGHS works out of the box, CPLEX/COPT/Gurobi backends optional)
• MLE (Gurobi, deprecated) - through bloqade.decoders.GurobiDecoder; use MILPDecoder instead
• MLD (Table Lookup) - through bloqade.decoders.TableDecoder, builds a lookup table from sampled data

Sinter-compatible adapters for MLE and MLD are also available through bloqade.decoders.sinter_interface.

You can install them separately or specify you would like them included with the bloqade-decoders installation through the additional instructions below.

For access to the ldpc-package originating decoders and their respective interfaces, just do the following:

pip install bloqade-decoders

To add the tesseract decoder you can do:

pip install bloqade-decoders[tesseract]

Or for MWPF do:

pip install bloqade-decoders[mwpf]

For MLE via PuLP (HiGHS is bundled; CPLEX, COPT, and Gurobi are also supported as solver backends):

pip install bloqade-decoders[milp]

For the deprecated Gurobi-based MLE decoder (a full Gurobi license is needed for larger problems, but small models work with the size-limited license bundled with gurobipy):

pip install bloqade-decoders[mle]

For MLD:

pip install bloqade-decoders[mld]

You can combine multiple extras:

pip install bloqade-decoders[mwpf, tesseract, milp, mle, mld, sinter]

The decoding interfaces are designed to align as closely as possible with the decoders themselves in terms of arguments. The only major difference is you're expected to pass in a Detector Error Model (DEM) to instantiate the interface.

Furthermore, all decoder interfaces are designed to accept the detector results of a single shot OR a batch of shots as a numpy ndarray of booleans, with the result being the observable correction (also as an ndarray of booleans).

from bloqade.decoders import BpOsdDecoder
import numpy as np
import stim

dem = stim.DetectorErrorModel("""
    error(0.1) D0
    error(0.1) D0 D1
    error(0.1) D1 L0
""")
# Pretend that circuit was executed twice,
# with two sets of detector results.
syndromes = np.array([[False, False], [False, True]])

# instantiate decoder, passing in desired arguments as you would
# the original decoder interface.
decoder = BpOsdDecoder(dem, bp_method="product_sum")

decoded_observable = decoder.decode(syndromes)
# decoded_observable should give you
# np.array([[False], [True]])

The MILPDecoder takes a DEM directly (note: must use decompose_errors=False):

from bloqade.decoders import MILPDecoder

decoder = MILPDecoder(dem)  # HiGHS backend by default
# or pick another PuLP solver backend
decoder = MILPDecoder(dem, solver="COPT", RelGap=0.0, AbsGap=0.0)

corrections = decoder.decode(syndromes)

To see different solver options, as per the PuLP documentation, you can run

import pulp as pl
solver_list = pl.listSolvers()
print(solver_list)
# ['GLPK_CMD', 'PYGLPK', 'CPLEX_CMD', 'CPLEX_PY', 'CPLEX_DLL', 'GUROBI', 'GUROBI_CMD', 'MOSEK', 'XPRESS', 'COIN_CMD', 'COINMP_DLL', 'CHOCO_CMD', 'MIPCL_CMD', 'SCIP_CMD', 'CPSAT', ...]

The GurobiDecoder is deprecated; use MILPDecoder(dem, solver="GUROBI") instead.

The TableDecoder takes a DEM directly and trains by sampling from that DEM:

from bloqade.decoders import TableDecoder

decoder = TableDecoder(dem)
# or choose a training sample count
decoder = TableDecoder(dem, num_shots=100_000)

corrections = decoder.decode(syndromes)

For a short demonstration of using the TableDecoder and GurobiDecoder, you can refer to this script.