Metadata-Version: 2.5
Name: bloqade-decoders
Version: 0.7.0
Summary: Decoder related statements and interfaces for Bloqade.
Author-email: johnzl-777 <jlong@quera.com>, rafaelha <rhaenel@quera.com>
License-File: LICENSE
Requires-Python: >=3.10
Requires-Dist: beliefmatching>=0.2.0
Requires-Dist: kirin-toolchain~=0.22.2
Requires-Dist: ldpc>=2.4.1
Requires-Dist: numpy>=1.26.4
Requires-Dist: stim>=1.15.0
Provides-Extra: milp
Requires-Dist: highspy>=1.11.0; extra == 'milp'
Requires-Dist: pulp>=2.9.0; extra == 'milp'
Provides-Extra: mld
Requires-Dist: polars>=1.38.1; extra == 'mld'
Requires-Dist: tqdm>=4.67.0; extra == 'mld'
Provides-Extra: mle
Requires-Dist: gurobipy>=13.0.1; extra == 'mle'
Requires-Dist: scipy>=1.14.0; extra == 'mle'
Provides-Extra: mwpf
Requires-Dist: mwpf[stim]>=0.2.12; extra == 'mwpf'
Provides-Extra: sinter
Requires-Dist: sinter>=1.16.0.dev; extra == 'sinter'
Provides-Extra: tesseract
Requires-Dist: tesseract-decoder>=0.1.1.dev20260109233451; extra == 'tesseract'
Description-Content-Type: text/markdown

# bloqade-decoders

The QEC user interface providing integration with popular open-source decoders for the [Bloqade SDK](https://github.com/QuEraComputing/bloqade).

By default, the following decoders from the [`ldpc`](https://github.com/quantumgizmos/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](https://github.com/yuewuo/mwpf))
- Tesseract - through `bloqade.decoders.TesseractDecoder` ([Tesseract](https://github.com/quantumlib/tesseract-decoder))
- 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.

## Installation

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

```bash
pip install bloqade-decoders
```

To add the tesseract decoder you can do:

```bash
pip install bloqade-decoders[tesseract]
```

Or for MWPF do:

```bash
pip install bloqade-decoders[mwpf]
```

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

```bash
pip install bloqade-decoders[milp]
```

For the deprecated Gurobi-based MLE decoder (a full [Gurobi license](https://www.gurobi.com/academia/academic-program-and-licenses/) is needed for larger problems, but small models work with the [size-limited license](https://support.gurobi.com/hc/en-us/articles/360051597492-How-do-I-resolve-a-Model-too-large-for-size-limited-Gurobi-license-error) bundled with `gurobipy`):

```bash
pip install bloqade-decoders[mle]
```

For MLD:

```bash
pip install bloqade-decoders[mld]
```

You can combine multiple extras:

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

## 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).

```python
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

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

```python
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](https://coin-or.github.io/pulp/guides/how_to_configure_solvers.html), you can run

```python
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:

```python
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)
```

## Quick Start
For a short demonstration of using the `TableDecoder` and `GurobiDecoder`, you can refer to [this script](demo/decoders_api_demo.py).
