qector-decoder-v3 0.6.6

Source-available Rust/Python QEC R&D platform: PyMatching-compatible validation, belief-matching, BP-OSD (LDPC/qLDPC), CPU/GPU batch decoding, and artifact-hashed benchmark evidence

QECTOR Decoder v3

Source-available Rust/Python quantum error correction decoding platform.

QECTOR Decoder v3 provides a Python package backed by a native Rust extension for quantum error correction research and validation workflows. It includes PyMatching-compatible MWPM validation, Union-Find decoding, belief-matching experiments, BP-OSD/qLDPC workflows, batch decoding, and optional GPU backend checks where the release build and target machine support them.

Companion projects:

• The public package snapshot focuses on the decoder library, Python API, validation suite, and benchmark evidence.
• Additional desktop, automation, and documentation tooling may be distributed separately from this checkout.

Website: https://www.qector.store
Repository: https://github.com/GuillaumeLessard/qector-decoder
Commercial licensing: https://www.qector.store

---

Installation

pip install qector-decoder-v3

Supported package target for the public release workflow:

• Python 3.9 to 3.13
• Linux x86_64 wheels
• Windows x64 wheels
• macOS arm64 wheels
• Source distribution for custom/source builds

Optional research and validation extras:

# Stim, Sinter, PyMatching, LDPC and belief-matching ecosystem
pip install "qector-decoder-v3[stim]"

# Benchmark and plotting harness
pip install "qector-decoder-v3[bench]"

# Full validation environment
pip install "qector-decoder-v3[all]"

---

Quick start

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

Batch decoding:

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)

Stim workflow:

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)

---

Included decoder families

Module	Primary use	Status
UnionFindDecoder	Fast approximate decoding	Stable public API
FastUnionFindDecoder	Optimized Union-Find path	Stable public API
BlossomDecoder	Exact MWPM / PyMatching-parity validation	Stable public API
SparseBlossomDecoder	Faster near-optimal matching	Experimental
BeliefMatching	Correlated-noise accuracy experiments	Research/accuracy mode
BpOsdDecoder	LDPC and qLDPC workflows	Experimental
BatchDecoder / CPUBatchDecoder	CPU 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	Stable public API
get_decoder	Cached decoder factory	Stable public API
decode_mmap	Out-of-core decoding via memmap	Stable public API
DecodeResult	Structured decode result	Stable public API
decode_with_diagnostics	Decode with diagnostics	Stable public API
Workbench	High-level 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 and DEM conversion	Stable utility
sinter_compat	Sinter custom decoder integration	Stable utility
rest_api	Local decoding service	Local/partner review only

---

Evidence-backed positioning

QECTOR Decoder v3 is positioned as a source-available QEC R&D platform, not as a blanket replacement for every mature decoder in every workload.

The repository includes public benchmark artifacts and reproduction scripts for:

• PyMatching-parity logical-error-rate checks on selected surface-code workloads
• belief-matching accuracy experiments on selected workloads
• GPU bit-identity checks against CPU output on a tested NVIDIA machine
• native memory profiling for selected decoder paths

Important boundaries:

• PyMatching remains faster for standard MWPM latency in the checked-in comparison artifacts.
• Belief-matching is an accuracy/research mode and is much slower in the provided experiments.
• GPU availability and performance depend on wheel build features, drivers, hardware, and runtime checks.
• OpenCL support must be confirmed on the target machine or built under the appropriate licensed/custom configuration.
• REST/API surfaces are for local experiments or controlled review unless separately hardened.
• v0.6.4: CPU batch decoder now reaches 1.1M shots/s via AVX2 SIMD transpose. BP-OSD adds decode_timed with convergence cap. Blossom intra-decode Rayon parallelism. DecoderPool auto-Rayon on Windows.

Full methodology, reproducibility notes, and benchmark artifacts are in the GitHub repository:

https://github.com/GuillaumeLessard/qector-decoder

---

GPU availability check

from qector_decoder_v3 import CUDABatchDecoder, OpenCLBatchDecoder

print("CUDA:", CUDABatchDecoder.is_available())
print("OpenCL:", OpenCLBatchDecoder.is_available())

Do this before making any hardware-specific performance claim.

---

v0.6.6 — critical fix, upgrade immediately if on v0.6.5

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; the properly-guarded assignment further down in the file (which already existed) now runs as intended. Verified against a clean install of the exact CI-built wheel.

---

v0.6.5 Highlights

Fix	Description
mypy clean	Resolved all 8 type errors across decode_mmap.py, decoder_pool.py, and belief_matching.py
Test suite fix	Genuine NameError (syndrome → syndromes) in the comprehensive test suite's multiprocessing pool test
PredecodedDecoder fix	Backend validation now accepts "union_find" (with underscore), matching canonical decoder names
ruff clean	Full repo passes ruff format --check and ruff check with zero errors
examples/example_batch.py fix	Was using a weight-4 surface code against Union-Find-only batch decoders (weight ≤2 only); switched to a ring code

---

v0.6.4 Highlights

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

---

Licensing

QECTOR Decoder v3 is source-available.

Personal, academic, educational and non-commercial research use is allowed under the repository license. Company use, funded institutional work, SaaS, hosted API deployment, OEM integration, redistribution, paid consulting, or commercial benchmarking requires a commercial license.

Commercial licensing:

https://www.qector.store

Contact:

[e-mail]

---

Citation

@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.}
}