GPU-accelerated Relay-BP decoder for qLDPC codes, implemented in Triton.
Pelagos implements min-sum belief propagation with disordered memory
strengths (Relay-BP-S), batched across syndromes and executed as fused
Triton kernels. It is interface-compatible with (and cross-validated
against) the relay-bp Rust reference implementation, available on PyPI.
Pelagos is vendor-neutral: the kernels are written in Triton, which targets both NVIDIA (CUDA), AMD (ROCm/HIP) and Intel (SPIR-V) GPUs. The decoder detects the active backend at construction time and adapts launch parameters accordingly.
pip install pelagos-decoder[gpu] # decoder + torch/triton
pip install pelagos-decoder[gpu,rust] # + the Rust CPU reference, side by side
pip install pelagos-decoder[gpu,stim] # + stim / DEM supportDevelopment uses uv:
uv sync --extra all
uv run pytestA GPU is required to decode; there is no CPU fallback (see Known limitations). The package imports and its structural tests run anywhere.
import numpy as np
import torch
from scipy.sparse import csr_matrix
from pelagos import RelayBPDecoder
# A tiny code: 3 checks over 3 variables.
H = csr_matrix(np.array([[1, 1, 0],
[0, 1, 1],
[1, 0, 1]], dtype=np.uint8))
priors = np.full(3, 0.05)
decoder = RelayBPDecoder(
H_csr=H,
error_priors=priors,
pre_iter=80, # T0: ordered-memory iterations
num_sets=100, # R: relay legs
set_max_iter=60, # Tr: iterations per leg
gamma0=0.65, # ordered memory strength
gamma_dist_interval=(-0.24, 0.66),
stop_nconv=5, # stop after 5 valid solutions
data_type="float32",
algo="relay", # required: "relay" or "plain"
)
# decode() takes a torch GPU tensor, not a numpy array.
syndrome = np.array([[1, 0, 1]], dtype=np.uint8)
syndrome_gpu = torch.from_numpy(syndrome).to("cuda:0")
result = decoder.decode(syndrome_gpu)
# The decoded error pattern is under the "errors" key.
e_hat = result["errors"].cpu().numpy()
print(e_hat)Three details that are easy to get wrong (all enforced by
tests/test_smoke.py):
algomust be passed explicitly —algo="relay"oralgo="plain". Omitting it raisesValueError: Unknown algo 'None'.decode()requires a torch tensor already on the GPU (torch.from_numpy(...).to("cuda:0")— PyTorch uses the"cuda"device type for ROCm builds as well, so the same call works on AMD), not a numpy array.- The result dict's error-pattern key is
"errors", not"e_hat".
import stim
from pelagos.stim.sinter.check_matrices import CheckMatrices
from pelagos import RelayBPDecoder
dem = stim.Circuit.generated(
"surface_code:rotated_memory_x", distance=3, rounds=3,
after_clifford_depolarization=0.001,
).detector_error_model(decompose_errors=False)
cm = CheckMatrices.from_dem(dem)
decoder = RelayBPDecoder(H_csr=cm.check_matrix, error_priors=cm.error_priors, algo="relay")Note the field is cm.error_priors, not cm.priors. This path requires
the stim extra (pip install pelagos-decoder[stim]), which pulls in
beliefmatching.
Step-by-step Jupyter notebooks live in tutorials/. Start with
Tutorial 1: single-GPU quickstart. It goes
from a stim circuit to a logical error rate on the [[72,12,6]] bivariate bicycle code,
compares plain BP with Relay-BP, and measures throughput:
uv sync --extra tutorials # or: pip install -e ".[tutorials]"
uv run jupyter lab tutorials/Continue with Tutorial 2: multi-GPU quickstart to decode on up to eight GPUs using the process backend, check decoding quality, and compare GPU counts with 1,024 shots per GPU.
pelagos_benchmark.py is a full-featured benchmark CLI. Run
python pelagos_benchmark.py --help for the complete flag list; the
important ones are --backend {rust,triton}, --circuit, --basis,
--distance, --rounds, --error-rate, --data-type, and --gpus. It
needs pandas, which ships in the bench extra:
pip install "pelagos-decoder[gpu,bench]" # or: uv sync --extra gpu --extra benchpython pelagos_benchmark.py --backend triton \
--circuit bicycle_bivariate_144_12_12_memory_X --basis x \
--distance 12 --rounds 12 --error-rate 0.003 --data-type float32There is no single --compare-rust flag; to cross-check against the Rust
reference, run the same command twice with --backend rust and
--backend triton (the rust extra must be installed for the former).
tests/testdata/bicycle_bivariate/ ships gzipped stim circuits for the
bivariate bicycle codes [[18,4,3]], [[72,12,6]], [[144,12,12]], and
[[288,12,18]], in X and choi_XZ bases, at physical error rates 0.002,
0.003, and 0.005 (24 files, 2.4 MB total).
stim.Circuit.from_file does not transparently decompress gzip, so the
bundled loader in tests/testdata/circuits.py handles both forms:
import sys; sys.path.insert(0, "tests")
from testdata import get_test_circuit
circuit = get_test_circuit(
"bicycle_bivariate_144_12_12_memory_X", 0.003, distance=12, rounds=12
)
dem = circuit.detector_error_model(decompose_errors=False)Continuous integration runs on GitHub-hosted runners, which have no GPU. On every pull request, CI checks packaging, imports, lint (syntax errors and undefined names), the CPU-side code (input validation, bit packing, the conversion from a stim DEM to check matrices) and the well-formedness of the tutorial notebooks. The decoder tests, including the bit-exact comparison against the Rust reference, are skipped in CI.
Before each release, and for any pull request that touches the kernels or the decoder, a maintainer runs the full suite on a GPU:
uv sync --extra gpu --extra rust --extra stim --extra test
uv run pytest tests/ -v -rs # nothing should be reported as skipped- A GPU is required. There is no CPU fallback; use the Rust
implementation (
relay-bpon PyPI) for CPU decoding. - Multi-GPU support is limited to one node. The default multi-device path
(
device=[0, 1, ...],--gpus) runs one thread per GPU in a single process and does not scale linearly with the number of GPUs. The opt-in process-per-GPU backend runs one worker process per GPU instead; its smoke test checks results against the single-GPU decoder on two GPUs. Scaling across nodes is not supported.
Contributions are welcome! See CONTRIBUTING.md for the development setup, testing, and sign-off requirements. Everyone taking part is expected to follow the Code of Conduct. Please report security issues privately, as described in SECURITY.md. Release notes are in CHANGELOG.md.
Pelagos is maintained by contributors from IBM and AMD under a lightweight, maintainer-led model. See GOVERNANCE.md for how decisions are made and MAINTAINERS.md for the current maintainers.
If you use Pelagos in your research, please cite:
D. Diamantopoulos, L. von Niederhäusern, A. S. Anghel, A. Kayi, R. Pletka, T. Müller, N. Papandreou, J. Blanusa, S. Sarafijanovic, N. M. Gonzalez, F. Abel, C. Hagleitner, S. Seelam, B. Johnson, R. Haas, and H. Pozidis, "Pêlagos: An Adaptive GPU Decoder for Error Correction Simulations of Quantum LDPC Codes," in 2026 IEEE International Conference on Quantum Software (QSW), 2026, pp. 152–165. IEEE Xplore
@INPROCEEDINGS{11662198,
author={Diamantopoulos, Dionysios and von Niederhäusern, Luc and Anghel, Andreea Simona and Pletka, Roman and Kayi, Apo and Müller, Tristan and Papandreou, Nikolaos and Blanusa, Jovan and Sarafijanovic, Slavisa and Gonzalez, Nelson Mimura and Abel, Francois and Hagleitner, Christoph and Seelam, Seetharami and Johnson, Blake and Haas, Robert and Pozidis, Haralampos},
booktitle={2026 IEEE International Conference on Quantum Software (QSW)},
title={Pêlαγos: An Adaptive GPU Decoder for Error Correction Simulations of Quantum LDPC Codes},
year={2026},
pages={152-165},
doi={10.1109/QSW72780.2026.00025}}
Pelagos is jointly owned by IBM and AMD.
Licensed under the Apache License, Version 2.0. See LICENSE.