ILPDecoder is a Python package for maximum-likelihood quantum error correction decoding using integer linear programming (ILP). It turns parity-check matrices or Stim DetectorErrorModels into an ILP and solves it with a built-in backend out of the box. It is aimed at correctness-focused baselines, solver comparisons, and small-to-medium code studies rather than high-throughput production decoding.

Documentation: https://nzy1997.github.io/ILPDecoder/

What it does well:

• Out-of-the-box decoding with minimal setup.
• Inputs from parity-check matrices or Stim DetectorErrorModel.
• Maximum-likelihood decoding via weights or error probabilities.
• PyMatching-like API for easy experimentation.

When it is not a fit:

• Large code distances or high-shot workloads where ILP scaling dominates; use MWPM/BPOSD for throughput.

# Basic installation
pip install ilpdecoder

# With Stim support
pip install ilpdecoder[stim]

# With SciPy sparse-matrix support
pip install ilpdecoder[scipy]

# Clone the repository
git clone https://github.com/nzy1997/ILPDecoder
cd ILPDecoder

# Create virtual environment (using uv)
uv venv
source .venv/bin/activate

# Install with dev dependencies
uv add highspy numpy scipy stim
uv add pyomo --dev
uv add pytest --dev

# Or using pip
pip install -e ".[dev]"

# Activate virtual environment
source .venv/bin/activate

# Run all tests
pytest tests/ -v

# Run specific test file
pytest tests/test_decoder.py -v

# Run a quick functionality check
python main.py

python examples/basic_usage.py
python examples/surface_code_example.py
benchmark/.venv/bin/python benchmark/benchmark_decoders.py --shots 10000 --distance 3 --rounds 3 --noise 0.01

import numpy as np
from ilpdecoder import Decoder

# Define a simple repetition code parity-check matrix
H = np.array([
    [1, 1, 0, 0, 0],
    [0, 1, 1, 0, 0],
    [0, 0, 1, 1, 0],
    [0, 0, 0, 1, 1],
])

# Create decoder
decoder = Decoder.from_parity_check_matrix(H)

# Decode a syndrome
syndrome = [1, 0, 0, 1]
correction = decoder.decode(syndrome)
print(f"Correction: {correction}")

Note: passing SciPy sparse matrices requires scipy to be installed (e.g., pip install ilpdecoder[scipy]).

import stim
from ilpdecoder import Decoder

# Generate a surface code circuit
circuit = stim.Circuit.generated(
    "surface_code:rotated_memory_x",
    distance=3,
    rounds=3,
    after_clifford_depolarization=0.01
)

# Get detector error model
dem = circuit.detector_error_model(decompose_errors=True)

# Create decoder
decoder = Decoder.from_stim_dem(dem)

# Sample and decode
sampler = circuit.compile_detector_sampler()
detection_events, observables = sampler.sample(shots=100, separate_observables=True)

for i in range(10):
    _, predicted_obs = decoder.decode(detection_events[i])
    print(f"Shot {i}: predicted={predicted_obs}, actual={observables[i]}")

• Only error(p) lines are parsed; tags in error[...] are ignored. detector and logical_observable metadata lines are ignored. shift_detectors offsets are applied. repeat blocks are flattened by default; this can expand large DEMs. detector_separator is unsupported and raises an error.
• The ^ separator is treated as whitespace and does not change parsing.
• If you want to fail fast instead of flattening, pass flatten_dem=False.

import numpy as np
from ilpdecoder import Decoder

H = np.array([[1, 1, 0], [0, 1, 1]])
error_probs = [0.1, 0.01, 0.1]

# Weights are computed automatically from probabilities
decoder = Decoder.from_parity_check_matrix(H, error_probabilities=error_probs)

syndrome = [1, 1]
correction, weight = decoder.decode(syndrome, return_weight=True)
print(f"ML correction: {correction}, weight: {weight}")

Note: error_probabilities must be in (0, 0.5]; pass explicit weights for p > 0.5.

Install optional deps for the benchmarks:

pip install stim pymatching ldpc

Notes:

• BPOSD runs with max_iter=50, osd_order=0, and bp_method=minimum_sum.

benchmark/.venv/bin/python benchmark/benchmark_decoders.py --compare-ilp-solvers --ilp-solvers highs,scip,gurobi,cbc,glpk --shots 10000 --distance 3 --rounds 3 --noise 0.01

Results from a local macOS arm64 run (shots=10000, your numbers will vary):

benchmark/.venv/bin/python benchmark/benchmark_decoders.py --noise-model code_capacity --compare-ilp-solvers --ilp-solvers highs,scip,gurobi,cbc,glpk --shots 10000 --distance 3 --rounds 1 --noise 0.01

Results from a local macOS arm64 run (shots=10000, your numbers will vary):

benchmark/.venv/bin/python benchmark/benchmark_decoders.py --code-task color_code:memory_xyz --compare-ilp-solvers --ilp-solvers highs,scip,gurobi,cbc,glpk --shots 10000 --distance 3 --rounds 3 --noise 0.01

Results from a local macOS arm64 run (shots=10000, your numbers will vary):

Main decoder class.

Class Methods:

• from_parity_check_matrix(H, weights=None, error_probabilities=None, solver=None) - Create from parity-check matrix
• from_stim_dem(dem, solver=None, merge_parallel_edges=True, flatten_dem=True) - Create from Stim DetectorErrorModel

Instance Methods:

• decode(syndrome, return_weight=False) - Decode a single syndrome
• decode_batch(syndromes) - Decode multiple syndromes
• set_solver(name, **options) - Switch solver

Properties:

• num_detectors - Number of parity checks/detectors
• num_errors - Number of error mechanisms
• num_observables - Number of logical observables (for DEM)
• solver_name - Current solver name

Returns a list of available solver names.

from ilpdecoder import get_available_solvers
print(get_available_solvers())  # e.g., ['scip', 'highs', 'cbc']

MIT License