Metadata-Version: 2.4
Name: qector-decoder-v3
Version: 1.0.1
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Programming Language :: Rust
Classifier: Operating System :: Microsoft :: Windows
Classifier: Operating System :: POSIX :: Linux
Classifier: Operating System :: MacOS
Classifier: Topic :: Scientific/Engineering :: Physics
Classifier: Topic :: Scientific/Engineering
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: Development Status :: 5 - Production/Stable
Requires-Dist: numpy>=1.24.0,<3
Requires-Dist: cryptography>=48.0.1
Requires-Dist: stim>=1.12 ; extra == 'all'
Requires-Dist: pymatching>=2.0 ; extra == 'all'
Requires-Dist: sinter>=1.12 ; extra == 'all'
Requires-Dist: ldpc>=2.0 ; extra == 'all'
Requires-Dist: beliefmatching>=0.2,<=2.2.6 ; extra == 'all'
Requires-Dist: psutil>=5.9 ; extra == 'all'
Requires-Dist: matplotlib>=3.7 ; extra == 'all'
Requires-Dist: tabulate>=0.9 ; extra == 'all'
Requires-Dist: scipy>=1.10 ; extra == 'all'
Requires-Dist: cupy-cuda12x>=13 ; extra == 'all'
Requires-Dist: stripe>=5.0 ; extra == 'all'
Requires-Dist: python-dotenv>=1.0 ; extra == 'all'
Requires-Dist: psutil>=5.9 ; extra == 'bench'
Requires-Dist: matplotlib>=3.7 ; extra == 'bench'
Requires-Dist: tabulate>=0.9 ; extra == 'bench'
Requires-Dist: scipy>=1.10 ; extra == 'bench'
Requires-Dist: cupy>=12.3.0 ; extra == 'cupy'
Requires-Dist: cupy-cuda12x>=13 ; extra == 'cupy-cuda12x'
Requires-Dist: pytest>=9.0.3 ; python_full_version >= '3.10' and extra == 'dev'
Requires-Dist: pytest>=8.4.2 ; python_full_version < '3.10' and extra == 'dev'
Requires-Dist: pytest-timeout>=2.1.0 ; extra == 'dev'
Requires-Dist: tomli>=2.0 ; python_full_version < '3.11' and extra == 'dev'
Requires-Dist: hypothesis>=6.0.4 ; extra == 'dev'
Requires-Dist: fastapi>=0.110.0 ; extra == 'dev'
Requires-Dist: uvicorn>=0.29.0 ; extra == 'dev'
Requires-Dist: httpx>=0.27.0 ; extra == 'dev'
Requires-Dist: mypy>=1.0.0 ; extra == 'dev'
Requires-Dist: ruff>=0.1.0 ; extra == 'dev'
Requires-Dist: pytest-cov>=4.0.0 ; extra == 'dev'
Requires-Dist: stripe>=5.0 ; extra == 'dev'
Requires-Dist: python-dotenv>=1.0 ; extra == 'dev'
Requires-Dist: stim>=1.12 ; extra == 'stim'
Requires-Dist: pymatching>=2.0 ; extra == 'stim'
Requires-Dist: sinter>=1.12 ; extra == 'stim'
Requires-Dist: ldpc>=2.0 ; extra == 'stim'
Requires-Dist: beliefmatching>=0.2,<=2.2.6 ; extra == 'stim'
Requires-Dist: stripe>=5.0 ; extra == 'stripe'
Requires-Dist: python-dotenv>=1.0 ; extra == 'stripe'
Provides-Extra: all
Provides-Extra: bench
Provides-Extra: cuda
Provides-Extra: cupy
Provides-Extra: cupy-cuda12x
Provides-Extra: dev
Provides-Extra: opencl
Provides-Extra: stim
Provides-Extra: stripe
License-File: LICENSE
Summary: Quantum error correction decoders for Python with a compiled Rust core: Union-Find, exact MWPM, BP-OSD for qLDPC codes, CPU and GPU batch decoding, Stim and Sinter integration.
Keywords: quantum,error correction,decoder,union-find,QEC,rust,MWPM,Stim,Sinter,PyMatching,qiskit,LDPC,qLDPC,blossom,belief propagation,belief matching,BP-OSD,Relay-BP,colour code,color code,toric code,GPU decoding,CUDA,surface code,syndrome decoding,fault tolerance,quantum computing
Home-Page: https://www.qector.store
Author-email: Guillaume Lessard / iD01t Productions <admin@qector.store>
License-Expression: PolyForm-Noncommercial-1.0.0
Requires-Python: >=3.9
Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
Project-URL: Changelog, https://github.com/GuillaumeLessard/qector-decoder/blob/main/CHANGELOG.md
Project-URL: Commercial Licensing, https://github.com/GuillaumeLessard/qector-decoder/blob/main/COMMERCIAL.md
Project-URL: Documentation, https://github.com/GuillaumeLessard/qector-decoder/tree/main/docs
Project-URL: Funding, https://github.com/sponsors/qectorlab
Project-URL: Homepage, https://qector.store
Project-URL: Issues, https://github.com/GuillaumeLessard/qector-decoder/issues
Project-URL: License, https://qector.store/license/
Project-URL: Pricing, https://qector.store/pricing/
Project-URL: Release Notes, https://github.com/GuillaumeLessard/qector-decoder/blob/main/RELEASE_NOTES.md
Project-URL: Repository, https://github.com/GuillaumeLessard/qector-decoder
Project-URL: Security, https://github.com/GuillaumeLessard/qector-decoder/blob/main/SECURITY.md
Project-URL: Source, https://github.com/GuillaumeLessard/qector-decoder

<p align="center">
  <img src="https://raw.githubusercontent.com/GuillaumeLessard/qector-decoder/main/assets/logo_banner.png" alt="QECTOR" width="80%" />
</p>

<h1 align="center">QECTOR Decoder v3</h1>

<p align="center">
  <strong>Quantum error correction decoding for Python, with a compiled Rust core.</strong><br/>
  Union-Find, exact MWPM, BP-OSD for LDPC/qLDPC codes, CPU and GPU batch decoding, Stim and Sinter integration.
</p>

<p align="center">
  <a href="https://pypi.org/project/qector-decoder-v3/"><img src="https://img.shields.io/pypi/v/qector-decoder-v3?label=PyPI" alt="PyPI version"/></a>
  <a href="https://pypi.org/project/qector-decoder-v3/"><img src="https://img.shields.io/pypi/pyversions/qector-decoder-v3" alt="Python versions"/></a>
  <a href="https://github.com/GuillaumeLessard/qector-decoder/actions/workflows/tests.yml"><img src="https://github.com/GuillaumeLessard/qector-decoder/actions/workflows/tests.yml/badge.svg" alt="Tests"/></a>
  <a href="https://github.com/GuillaumeLessard/qector-decoder/blob/main/LICENSE"><img src="https://img.shields.io/badge/license-PolyForm%20Noncommercial%201.0.0-blue" alt="License"/></a>
</p>

<p align="center">
  <a href="https://qector.store/">Website</a> ·
  <a href="https://qector.store/pricing/">Pricing</a> ·
  <a href="https://github.com/GuillaumeLessard/qector-decoder/blob/main/CHANGELOG.md">Changelog</a> ·
  <a href="https://github.com/GuillaumeLessard/qector-decoder/releases">Releases</a> ·
  <a href="mailto:admin@qector.store">Contact</a>
</p>

---

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

```bash
pip install qector-decoder-v3
```

Binary wheels are published for **CPython 3.9 to 3.14** on:

| Platform | Wheel tag |
| --- | --- |
| Linux x86_64 | `manylinux_2_17_x86_64` |
| Windows x64 | `win_amd64` |
| macOS Apple silicon | `macosx_11_0_arm64` |

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:

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

## Quick start

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

```python
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:

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

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

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

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

| Decoder | Use | Status |
| --- | --- | --- |
| `UnionFindDecoder`, `FastUnionFindDecoder` | Low-latency approximate decoding | Stable |
| `BlossomDecoder` | Exact minimum-weight perfect matching | Stable |
| `SparseBlossomDecoder` | Near-optimal matching on large graphs | Experimental |
| `BpOsdDecoder` (BP-OSD, Relay-BP) | LDPC / qLDPC codes | Experimental |
| `BeliefMatching` | Correlated noise, accuracy over speed | Research |
| `AmbiguityClusterDecoder`, `TwoStageDecoder` | qLDPC clusters; X/Z sectors decoded separately | Experimental |
| `ColourCodeDecoder` | Colour codes (BP-OSD on the hypergraph) | Experimental |
| `BatchDecoder`, `DecoderPool` | CPU batch and multi-process decoding | Stable |
| `CUDABatchDecoder`, `OpenCLBatchDecoder`, `CUDABpOsdDecoder` | GPU batch decoding (paid licence) | Hardware dependent |
| `AutoDecoder` | Backend selection with automatic fallback | Stable |
| `SpaceTimeDecoder`, `SlidingWindowDecoder`, `StreamingDecoder` | Multi-round and streaming decoding | Experimental |
| `HybridDecoder`, `LookupTableDecoder` | Union-Find/Blossom routing; small codes | Experimental |
| `NeuralPredecoder`, `GNNPredecoder` | Learned predecoders | Research |

## Command line and MCP server

```bash
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:

```bash
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](https://github.com/GuillaumeLessard/qector-decoder/blob/main/LICENSE)
(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](https://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.

```bash
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`.

| Tier | Plans | GPU batch decoders | Code-distance tier |
| --- | --- | --- | --- |
| Community | no token | not available | 7 |
| Pro | Trial, Pro, Pro Perpetual, Team, Pilot | available | 19 |
| Enterprise | Lab, Enterprise | available | 63 |

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

| Variable | Effect |
| --- | --- |
| `QECTOR_SILENT=1` | Hides the licensing notice printed on import |
| `QECTOR_ENFORCE=1` | Turns distance tiers into hard errors |
| `QECTOR_OFFLINE=1` | Refuses every outbound billing call (decoding never uses the network) |
| `QECTOR_CUDA_DEVICE_ID` | CUDA device to use (default `0`) |
| `QECTOR_OPENCL_DEVICE_ALLOW` | Comma-separated substrings selecting OpenCL devices |
| `QECTOR_BLOSSOM_K_MULT` | Sparse-MWPM candidate multiplier (default `2.0`); lowering it can reduce matching quality |

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

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

Security reports: see [SECURITY.md](https://github.com/GuillaumeLessard/qector-decoder/blob/main/SECURITY.md).

## Citation

```bibtex
@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](https://doi.org/10.5281/zenodo.21941046) ·
[verification bundle](https://doi.org/10.5281/zenodo.22046403) ·
[user manual](https://doi.org/10.5281/zenodo.21363016) ·
[Workbench](https://doi.org/10.5281/zenodo.21360433).

## Related projects

- [QECTOR Workbench](https://github.com/qectorlab/qector-decoder-workbench-windows/releases/latest): free desktop application (Windows, Linux, macOS)
- [QECTOR Claude plugin](https://github.com/GuillaumeLessard/qector-claude-plugin): QEC tools for Claude Code and Claude Desktop

## Contact

- Commercial licensing and support: [admin@qector.store](mailto:admin@qector.store)
- Bugs and questions: [GitHub Issues](https://github.com/GuillaumeLessard/qector-decoder/issues)
- Sponsor development: [GitHub Sponsors](https://github.com/sponsors/qectorlab)

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

