Skip to content

Overview

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 decoders. Some need optional solver or helper dependencies:

  • MWPF - through bloqade.decoders.MWPFDecoder (MWPF)
  • Tesseract - through bloqade.decoders.TesseractDecoder (Tesseract)
  • MLE (Gurobi) - through bloqade.decoders.GurobiDecoder, finds the most likely error pattern via mixed-integer programming; the class is included, but constructing it requires gurobipy
  • MLD (Table Lookup) - through bloqade.decoders.TableDecoder, builds a lookup table from sampled data; its class is included in the base package

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.

Installation

Section titled “Installation”

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

Terminal window
pip install bloqade-decoders

To add the tesseract decoder you can do:

Terminal window
pip install bloqade-decoders[tesseract]

Or for MWPF do:

Terminal window
pip install bloqade-decoders[mwpf]

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

Terminal window
pip install bloqade-decoders[mle]

For MLD helpers (tqdm for from_stim_circuit and polars for det_obs_dataframe):

Terminal window
pip install bloqade-decoders[mld]

You can combine multiple extras:

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

Usage

Section titled “Usage”

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]])

MLE / MLD Decoders

Section titled “MLE / MLD Decoders”

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

from bloqade.decoders import GurobiDecoder


decoder = GurobiDecoder(dem)
corrections = decoder.decode(syndromes)

With the pinned bloqade-decoders 0.6.1 API, sample the DEM and pass the detector and observable shots to TableDecoder.from_det_obs_shots:

from bloqade.decoders import TableDecoder


num_shots = 100_000
detector_shots, observable_shots, _ = dem.compile_sampler().sample(num_shots)
detector_observable_shots = np.concatenate(
    [detector_shots, observable_shots], axis=1
)
decoder = TableDecoder.from_det_obs_shots(dem, detector_observable_shots)


corrections = decoder.decode(syndromes)

Quick Start

Section titled “Quick Start”

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