PyMatching-compatible MWPM validation - Belief-matching accuracy mode - BP-OSD for LDPC/qLDPC - CPU/GPU batch decoding - Artifact-backed benchmark evidence
Companion tooling: the public package snapshot focuses on the decoder library, Python API, validation suite, and benchmark evidence. Companion desktop and automation surfaces are distributed separately from this checkout.
Website - PyPI - Commercial licensing
pip install qector-decoder-v3Supported public wheel target: Python 3.9 to 3.13 on Linux, Windows, and macOS where wheels are published for the release.
# Stim, Sinter, PyMatching, LDPC and belief-matching ecosystem
pip install "qector-decoder-v3[stim]"
# Benchmark harness: psutil, matplotlib, scipy, tabulate
pip install "qector-decoder-v3[bench]"
# Everything needed for validation and benchmark scripts
pip install "qector-decoder-v3[all]"GPU support is runtime and build dependent. The public CI wheel workflow currently builds the CUDA feature path; OpenCL-capable builds are validated in checked-in benchmark artifacts but may require a licensed/custom build. Always detect support on the target machine before quoting performance.
from qector_decoder_v3 import CUDABatchDecoder, OpenCLBatchDecoder
print("CUDA:", CUDABatchDecoder.is_available())
print("OpenCL:", OpenCLBatchDecoder.is_available())The public repository contains the Python layer and a Rust source stub. The proprietary Rust core is injected during trusted CI/release builds or provided under commercial license.
git clone https://github.com/GuillaumeLessard/qector-decoder.git
cd qector-decoder
python -m venv .venv
source .venv/bin/activate # Windows PowerShell: .\.venv\Scripts\Activate.ps1
python -m pip install --upgrade pip maturin
python -m pip install -e "[stim,bench]"For a full native Rust extension build, use the licensed Rust source bundle alongside the packaging metadata in pyproject.toml and the checked-in Rust sources in src.
import numpy as np
from qector_decoder_v3 import UnionFindDecoder, BlossomDecoder
check_to_qubits = [[0, 1], [1, 2], [2, 3], [3, 4]]
n_qubits = 5
syndrome = np.array([0, 1, 0, 0], dtype=np.uint8)
fast = UnionFindDecoder(check_to_qubits, n_qubits)
print(fast.decode(syndrome))
mwpm = BlossomDecoder(check_to_qubits, n_qubits)
print(mwpm.decode(syndrome))import numpy as np
from qector_decoder_v3 import BatchDecoder, CUDABatchDecoder
checks = [[0, 1], [1, 2], [2, 3], [3, 4]]
syndromes = np.random.randint(0, 2, size=(4096, 4), dtype=np.uint8)
cpu = BatchDecoder(checks, n_qubits=5)
corrections = cpu.parallel_batch_decode(syndromes)
if CUDABatchDecoder.is_available():
gpu = CUDABatchDecoder(checks, n_qubits=5)
corrections = gpu.batch_decode(syndromes)import stim
from qector_decoder_v3 import BlossomDecoder
from qector_decoder_v3.stim_compat import from_stim_detector_error_model
circuit = stim.Circuit.generated(
"surface_code:rotated_memory_z",
distance=5,
rounds=5,
after_clifford_depolarization=0.005,
)
dem = circuit.detector_error_model(decompose_errors=True)
checks, n_qubits = from_stim_detector_error_model(dem)
decoder = BlossomDecoder(checks, n_qubits)import stim
from qector_decoder_v3.belief_matching import BeliefMatching
circuit = stim.Circuit.generated(
"surface_code:rotated_memory_z",
distance=5,
rounds=5,
after_clifford_depolarization=0.005,
)
bm = BeliefMatching.from_stim_circuit(circuit)
sampler = circuit.compile_detector_sampler()
(syndrome,) = sampler.sample(shots=1)
correction = bm.decode(syndrome.astype("uint8"))from qector_decoder_v3 import codes
from qector_decoder_v3.bposd import BpOsdDecoder
cx, cz = codes.bivariate_bicycle_code(
6,
6,
[("x", 3), ("y", 1), ("y", 2)],
[("y", 3), ("x", 1), ("x", 2)],
)
decoder = BpOsdDecoder(cx.parity_check_matrix(), error_rate=0.05, osd_order=0)
correction = decoder.decode(syndrome)| Decoder / module | Best use | Status |
|---|---|---|
UnionFindDecoder |
Low-latency approximate decoding | Stable public API |
FastUnionFindDecoder |
Optimized Union-Find hot path | Stable public API |
BlossomDecoder |
Exact MWPM / PyMatching-parity validation | Stable public API |
SparseBlossomDecoder |
Faster near-optimal matching | Experimental correctness envelope |
BeliefMatching |
Correlated-noise accuracy experiments | Accuracy mode, not latency mode |
BpOsdDecoder |
LDPC / qLDPC decoding workflows | Experimental / research |
BatchDecoder / CPUBatchDecoder |
CPU batch Monte Carlo sweeps | Stable public API |
CUDABatchDecoder |
CUDA batch decoding | Runtime/build dependent |
OpenCLBatchDecoder |
OpenCL batch decoding | Runtime/build dependent |
AutoDecoder |
CPU/GPU backend calibration | Experimental |
PredecodedDecoder |
Easy-syndrome prefiltering | Experimental |
DecoderPool |
Multi-process batch decoding (auto-Rayon on Windows) | Stable public API |
get_decoder |
Cached decoder factory (zero construction cost after first call) | Stable public API |
clear_decoder_cache |
Clear the decoder cache | Stable public API |
get_decoder_pool |
Cached DecoderPool factory | Stable public API |
decode_mmap |
Out-of-core decoding via memory-mapped arrays | Stable public API |
DecodeResult |
Structured decode result with diagnostics | Stable public API |
decode_with_diagnostics |
Decode with detailed diagnostic info | Stable public API |
Workbench |
High-level workbench orchestration | Stable public API |
SlidingWindowDecoder |
Multi-round streaming workflows | Experimental |
StreamingDecoder |
Continuous streaming decode session | Experimental |
HybridDecoder |
Combined Union-Find + Blossom fallback routing | Experimental |
LookupTableDecoder |
Precomputed small-code lookup decoding | Experimental |
NeuralPredecoder |
Learned predecoder front-end | Research/experimental |
GNNPredecoder |
Graph neural network predecoder | Research/experimental |
GNNTrainer |
Training harness for GNNPredecoder |
Research/experimental |
LERBenchmark |
Logical error rate benchmarking harness | Experimental |
stim_compat |
Stim circuit / DEM conversion | Stable utility |
sinter_compat |
Sinter custom decoder integration | Stable utility |
rest_api |
Local service endpoint | Local/partner review only |
See the public API regression coverage in python/tests before building production code on experimental modules.
v0.6.5 fails to import at all (AttributeError on OpenCLBatchDecoder) on every published wheel, because the release build (--no-default-features --features cuda) never compiles in OpenCL support, and __init__.py had a leftover unguarded reference to it. Fixed in v0.6.6 by removing the dead line. Verified against a clean install of the exact CI-built wheel.
| Fix | Description |
|---|---|
| mypy clean | Resolved all 8 type errors across decode_mmap.py, decoder_pool.py, and belief_matching.py — strict type checking passes on the full Python layer |
| Test suite fix | Genuine NameError (syndrome → syndromes) in test_comprehensive_suite.py::_run_pool_test fixed — was a live crash risk on any machine where Windows spawn multiprocessing succeeds |
PredecodedDecoder fix |
Backend validation now accepts "union_find" (with underscore), matching the canonical decoder names |
| ruff clean | Full repo passes ruff format --check and ruff check with zero errors; .venv/.venv_clean_test/target/dist/lib/proto excluded from lint scope |
examples/example_batch.py fix |
Was constructing CPUBatchDecoder/OpenCLBatchDecoder/CUDABatchDecoder (Union-Find-based, weight ≤2 only) against a weight-4 surface code; switched to generate_ring_code_checks(), the correct weight-2 code family for this decoder class |
| CI reliability | Verified full 15-platform wheel build (Linux/Windows/macOS × Python 3.9–3.13) and full test suite (1005 passed, 83 skipped) against the release build |
| Feature | Description |
|---|---|
BP-OSD decode_timed |
Wall-clock deadline for BP iterations; falls back to hard-decision on timeout |
| AVX2 runtime dispatch | CPU batch decoder auto-detects AVX2 support and uses SIMD transpose for 1.1M shots/s |
| Blossom intra-decode parallelism | Rayon-parallelized Blossom matching for multi-shot batches |
| DecoderPool Windows fix | Auto-Rayon fallback on Windows when multi-process pool is unavailable |
DecoderPool |
Multi-process batch decoding with automatic worker management |
get_decoder / clear_decoder_cache / get_decoder_pool |
Cached decoder factory — zero construction cost after first call |
decode_mmap |
Out-of-core decoding via memory-mapped NumPy arrays |
DecodeResult / decode_with_diagnostics |
Structured decode results with per-shot diagnostic metadata |
Workbench |
High-level orchestration for multi-decoder comparison and benchmarking |
The public repository snapshot focuses on the decoder package, its Python API, validation suite, and reproducible benchmark evidence. Companion desktop, automation, and documentation tooling may be provided separately through partner or commercial distribution channels and are not bundled in this checkout.
If you need the full desktop GUI, hosted automation stack, or additional documentation-generation tooling, contact the project team through the commercial site listed above.
All public claims should cite an artifact, commit, command, machine, and version. The current package release is v0.6.5; checked-in evidence below was generated under v0.6.4 and is labeled accordingly — regenerate before making new performance claims against v0.6.5.
v0.6.4 additions: AVX2 SIMD transpose (CPU batch 1.1M shots/s), BP-OSD convergence cap (
decode_timed), Blossom intra-decode Rayon parallelism, DecoderPool auto-Rayon on Windows.
Artifact: benchmark_results/stim_ler_d13_d15.json
Environment: Windows 10/11 class x64 machine, Python 3.11+, QECTOR v0.6.4 + v3.3 Workbench, PyMatching 2.4+, Stim 1.16+, 20,000 shots per distance.
| Distance | QECTOR Blossom LER | PyMatching LER | QECTOR us/shot | PyMatching us/shot |
|---|---|---|---|---|
| 13 | 0.00075 | 0.00075 | 820.46 | 81.12 |
| 15 | 0.00050 | 0.00050 | 1965.15 | 203.20 |
Interpretation: QECTOR Blossom matched PyMatching logical-error counts on this artifact. PyMatching remains much faster for standard MWPM latency on these workloads.
Artifact: benchmark_results/competitive_belief.json
Environment: Windows x64, Python 3.11, QECTOR 0.5.7, PyMatching 2.4.0, Stim 1.16.0, 3,000 shots per distance.
| Distance | PyMatching LER | QECTOR MWPM LER | QECTOR Belief LER | Belief us/shot |
|---|---|---|---|---|
| 3 | 0.01167 | 0.01167 | 0.01233 | 2331.07 |
| 5 | 0.00767 | 0.00767 | 0.00500 | 12125.38 |
| 7 | 0.00600 | 0.00600 | 0.00300 | 54323.56 |
Interpretation: belief-matching improved observed LER at d=5 and d=7 in this artifact but was dramatically slower. It should be positioned as an accuracy/research mode, not a production latency path.
Artifact: benchmark_results/gpu_extensive.json
Environment: NVIDIA GeForce GTX 1660 Ti, Python 3.11, CUDA and OpenCL available, distances 3 to 13, batch sizes 1 to 65,536.
| Claim | Artifact result |
|---|---|
| Number of tested configurations | 36 |
| CUDA bit-identical to CPU | true |
| OpenCL bit-identical to CPU | true |
| All tested GPU paths faithful | true |
Interpretation: this is a correctness and reproducibility artifact for one machine. It is not a universal GPU speed claim.
Artifact: benchmark_results/native_memory.json
Distance 13, batch 16,384:
| Decoder | RSS base MiB | RSS peak MiB | Native delta MiB |
|---|---|---|---|
cpu_batch |
120.98 | 130.39 | 9.41 |
blossom |
123.64 | 129.52 | 5.88 |
fast_union_find |
121.98 | 122.00 | 0.02 |
cuda_batch |
211.57 | 214.24 | 2.67 |
# MWPM / PyMatching comparison
python scripts/competitive_stim_ler.py --distances 3 5 7 9 11 13 15 --shots 40000
# Belief-matching comparison
python scripts/competitive_belief_matching.py --distances 3 5 7 --shots 3000 --no-ref
# GPU correctness and crossover checks
python scripts/gpu_extensive_test.py --distances 3 5 7 9 11 13 --batches 1 64 1024 4096 16384 65536 --error-rate 0.05
# Native memory profile
python scripts/native_memory_profile.py --distances 5 9 13 --batch 16384 --out benchmark_results/native_memory
# Full due-diligence bundle
python scripts/run_due_diligence_bundle.py --out qector_evidence_bundleBenchmark results are hardware, driver, compiler, seed, and workload dependent. Regenerate before quoting throughput, latency, GPU speedup, or buyer-facing performance numbers.
qector_decoder_v3/
+-- Rust core, proprietary
| +-- Union-Find / Blossom / SparseBlossom engines
| +-- CPU batch engine
| +-- CUDA / OpenCL batch paths where enabled
| +-- DEM collapse and Stim integration support
| +-- Native Python extension
|
+-- Python layer, public in this repository
+-- __init__.py
+-- belief_matching.py
+-- bposd.py
+-- predecoder.py
+-- backend.py
+-- dem.py
+-- stim_compat.py
+-- sinter_compat.py
+-- qiskit_plugin.py
+-- rest_api.py
+-- workbench.py
+-- codes.py
The Rust core is built into the native extension during local development and packaging. The checked-in sources in src are the implementation used for this workspace build, while release-wheel packaging relies on the project’s selected build environment.
import sinter
from qector_decoder_v3.sinter_compat import qector_sinter_decoders
tasks = [...] # list[sinter.Task]
samples = sinter.collect(
num_workers=4,
tasks=tasks,
decoders=["qector_belief", "qector_blossom", "qector_unionfind"],
custom_decoders=qector_sinter_decoders(),
)pip install "qector-decoder-v3[stim]" fastapi uvicorn
python -m qector_decoder_v3.rest_apicurl -X POST http://localhost:8000/decode \
-H "Content-Type: application/json" \
-d '{"check_to_qubits":[[0,1],[1,2],[2,3],[3,4]],"syndrome":[0,1,0,0]}'The REST API is for local experiments, partner review, or controlled internal deployments. Do not expose it publicly without authentication, TLS, authorization, logging, input limits, and rate limiting.
| Area | Boundary |
|---|---|
| MWPM latency | PyMatching remains the speed leader on standard surface-code MWPM workloads in the provided artifacts. |
| Belief-matching | Accuracy/research mode. It can improve observed LER on selected workloads but is much slower. |
| GPU performance | Correctness is artifact-backed for tested machines. Speedup is not universal. |
| OpenCL wheels | OpenCL support depends on build configuration and target environment. Confirm locally. |
| SparseBlossom | Near-optimal, not exact MWPM. Use BlossomDecoder for exact minimum-weight matching. |
| UnionFind | Fast approximate path; not a universal decoder for arbitrary graphs. |
| REST/gRPC/MCP surfaces | Not hardened as public SaaS without a separate deployment/security review. |
The public checkout currently includes the following primary reference material:
- README.md — package overview, install steps, and quick-start usage
- PYPI_README.md — PyPI-facing package summary
- AGENTS.md — repository-specific development and validation notes
- LICENSE — repository license terms
- pyproject.toml — packaging metadata and optional dependency groups
- python/tests — public API and regression tests that validate the current behavior
The current checkout is validated through the Python regression suite under python/tests and the packaging metadata in pyproject.toml. Release automation and wheel publication are managed through the upstream project workflow outside this local snapshot.
The public checkout now emphasizes the package sources, Python API, regression tests, packaging metadata, and the validated evidence captured in the repository history and release metadata.
QECTOR Decoder v3 is source-available.
| Use | License required |
|---|---|
| Personal, academic, educational, non-commercial research | Free under the repository license |
| Company use, commercial R&D, institutional funded work | Paid commercial license |
| SaaS, hosted API, OEM embedding, product integration, redistribution | Paid commercial license |
| Commercial benchmarking, paid consulting, revenue-linked work | Paid commercial license |
Commercial contact: admin@qector.store
Website: https://www.qector.store
See LICENSE for the repository terms and contact the commercial team above for separate licensing.
@software{lessard2026qector,
author = {Guillaume Lessard},
title = {{QECTOR Decoder v3}: Rust/Python Quantum Error Correction Decoding Platform},
year = {2026},
version = {0.6.6},
url = {https://www.qector.store},
note = {Source-available. Commercial license required for commercial use.}
}Copyright (c) 2026 Guillaume Lessard / iD01t Productions. All rights reserved.