QECTOR Decoder v3

Quantum error correction decoding for Python, with a compiled Rust core.
Union-Find, exact MWPM, BP-OSD for LDPC/qLDPC codes, CPU and GPU batch decoding, Stim and Sinter integration.

Website · Pricing · Changelog · Releases · Contact

Overview

QECTOR Decoder v3 decodes syndromes from quantum error-correcting codes. Every decoder returns a correction c that reproduces the syndrome, H c = s (mod 2), and the same graph can be handed to several decoder families so they can be compared on identical input.

• Decoder families: Union-Find, exact Blossom (MWPM), sparse Blossom, BP-OSD and Relay-BP for LDPC/qLDPC, belief matching, ambiguity clustering, two-stage X/Z decoding, lookup tables and hybrid cascades.
• Batch decoding on CPU (Rayon) and, with a commercial licence, on CUDA or OpenCL GPUs, plus an AutoDecoder that falls back across backends.
• Ecosystem: Stim detector error models, Sinter custom decoders, a PyMatching-compatible Matching shim and a qiskit-qec plugin.
• Tooling: the qector CLI, the qector-doctor environment diagnostic, and a local MCP server for AI assistants.

Installation

pip install qector-decoder-v3

Binary wheels are published for CPython 3.9 to 3.14 on:

There is no source distribution: the Rust core is distributed as compiled wheels only, so other platforms (Linux aarch64, musllinux, macOS x86_64) are not supported by pip install.

Optional extras:

pip install "qector-decoder-v3[stim]"   # Stim, Sinter, PyMatching and LDPC ecosystem
pip install "qector-decoder-v3[all]"    # full validation environment

Quick start

import numpy as np
from qector_decoder_v3 import UnionFindDecoder, BlossomDecoder

check_to_qubits = [[0, 1], [1, 2], [2, 3], [3, 4]]   # repetition code, 5 qubits
syndrome = np.array([0, 1, 0, 0], dtype=np.uint8)

print(UnionFindDecoder(check_to_qubits, 5).decode(syndrome))   # fast, approximate
print(BlossomDecoder(check_to_qubits, 5).decode(syndrome))     # exact MWPM

Batch decoding

from qector_decoder_v3 import BatchDecoder, CUDABatchDecoder

syndromes = np.random.default_rng(0).integers(0, 2, size=(4096, 4), dtype=np.uint8)
corrections = BatchDecoder(check_to_qubits, n_qubits=5).parallel_batch_decode(syndromes)

if CUDABatchDecoder.is_available():                 # requires a paid licence and a CUDA driver
    corrections = CUDABatchDecoder(check_to_qubits, 5).batch_decode(syndromes)

AutoDecoder picks the best available backend and falls back automatically if one fails:

from qector_decoder_v3 import AutoDecoder

auto = AutoDecoder(check_to_qubits, n_qubits=5)
corrections = auto.batch_decode(syndromes)
print(auto.available_backends(), auto.last_backend)

From a Stim circuit

import stim
from qector_decoder_v3 import dem

circuit = stim.Circuit.generated(
    "surface_code:rotated_memory_z", distance=5, rounds=5,
    after_clifford_depolarization=0.005,
)
graph = dem.from_stim(circuit.detector_error_model(decompose_errors=True)).collapse_to_graph()

decoder = graph.make_decoder("blossom")   # carries the DEM's weights
# also: "union_find", "fast_union_find", "sparse_blossom", "bp_osd",
#       "lookup_table", "hybrid_cascade", "ambiguity_cluster"

When decoding circuit-level noise on a GPU, pass the weights (graph.weights()) as edge_weights: unweighted cluster growth cannot tell a rare error mechanism from a common one.

BP-OSD for qLDPC codes

from qector_decoder_v3 import codes
from qector_decoder_v3.bposd import BpOsdDecoder

# [[144,12,12]] bivariate bicycle code: A = x^3 + y + y^2, B = y^3 + x + x^2
cx, cz = codes.bivariate_bicycle_code(
    12, 6, [("x", 3), ("y", 1), ("y", 2)], [("y", 3), ("x", 1), ("x", 2)]
)
H = cx.parity_check_matrix()
decoder = BpOsdDecoder(H, error_rate=0.01, osd_order=0)

Sinter

import sinter
from qector_decoder_v3.sinter_compat import qector_sinter_decoders

samples = sinter.collect(
    num_workers=4, tasks=tasks,
    decoders=["qector_blossom", "qector_unionfind"],
    custom_decoders=qector_sinter_decoders(),
)

Available decoders: qector_blossom, qector_unionfind, qector_unionfind_unweighted, qector_bposd, qector_belief.

Decoder families

Command line and MCP server

qector --help          # decode, bench, serve
qector-doctor          # explains why a backend is or is not available

The package includes a Model Context Protocol server (JSON-RPC 2.0 over stdio) that exposes 13 decoding tools to MCP clients such as Claude Code:

python -c "import qector_decoder_v3; qector_decoder_v3.run_mcp_server()"

A ready-made client configuration is in mcp.json. The MCP, REST and gRPC servers are intended for local and controlled use; they are not hardened for public exposure.

Licensing

QECTOR Decoder v3 is source-available under the PolyForm Noncommercial License 1.0.0 (SPDX PolyForm-Noncommercial-1.0.0).

• Free: personal, academic and other non-commercial use. Universities, public research organisations, charities and government institutions may use it free whatever their source of funding.
• Commercial licence required: use by or for a company, including company work under a research contract, hosted or SaaS deployment, OEM integration and redistribution. Plans start at $79/month, with a free 14-day trial: qector.store/pricing.

Activating a licence

Tokens are Ed25519-signed and verified offline against a public key compiled into the package: no licence server and no network access, so they work on air-gapped machines.

export QECTOR_LICENSE_KEY="<token>"
export QECTOR_LICENSE="<token>"
python -c "import qector_decoder_v3 as q; print(q.get_license_info()['tier'])"   # Pro or Enterprise

A key file also works: QECTOR_LICENSE_FILE=/path/to/license.key, or ~/.qector/license.key.

CPU decoding is never blocked. Distance tiers are advisory unless QECTOR_ENFORCE=1 is set.

Limitations

• For standard surface-code MWPM, PyMatching is faster than the exact BlossomDecoder; QECTOR's focus is decoder breadth and qLDPC coverage.
• SparseBlossomDecoder is near-optimal, not exact; use BlossomDecoder when exactness matters.
• GPU speed-ups depend on hardware and workload, and unweighted GPU kernels trade accuracy for throughput.
• No performance figures are published: throughput and logical error rates depend on your hardware, code, distance and noise model.

Release integrity

Wheels are built, tested on Linux, Windows and macOS, and published to PyPI by GitHub Actions using Trusted Publishing. Each GitHub Release lists the wheels' SHA-256 digests, and every wheel carries Sigstore build provenance:

gh attestation verify qector_decoder_v3-<version>-<tag>.whl --repo GuillaumeLessard/qector-decoder

Security reports: see SECURITY.md.

Citation

@software{lessard2026qector,
  author  = {Guillaume Lessard},
  title   = {{QECTOR Decoder v3}: Quantum Error Correction Decoding for Python},
  year    = {2026},
  version = {1.0.1},
  url     = {https://qector.store/},
  note    = {Source-available under PolyForm Noncommercial 1.0.0}
}

Related records on Zenodo: architecture and foundations · verification bundle · user manual · Workbench.

Related projects

• QECTOR Workbench: free desktop application (Windows, Linux, macOS)
• QECTOR Claude plugin: QEC tools for Claude Code and Claude Desktop

Contact

• Commercial licensing and support: admin@qector.store
• Bugs and questions: GitHub Issues
• Sponsor development: GitHub Sponsors

© 2026 Guillaume Lessard / iD01t Productions. Licensed under PolyForm Noncommercial 1.0.0.