Metadata-Version: 2.4
Name: qector-decoder-v3
Version: 0.5.1
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: License :: Other/Proprietary License
Classifier: Programming Language :: Rust
Classifier: Programming Language :: Python :: 3
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: Topic :: Scientific/Engineering :: Physics
Requires-Dist: numpy>=1.24.0
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 ; 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: 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: pytest>=7.0.0 ; extra == 'dev'
Requires-Dist: hypothesis>=6.0.0 ; 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: 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 ; extra == 'stim'
Provides-Extra: all
Provides-Extra: bench
Provides-Extra: cuda
Provides-Extra: dev
Provides-Extra: opencl
Provides-Extra: stim
License-File: LICENSE
Summary: Source-available Rust/Python QEC R&D platform with PyMatching-compatible validation, belief-matching, BP-OSD/qLDPC workflows, CPU/GPU batch decoding, and artifact-backed benchmark evidence
Keywords: quantum,error correction,decoder,union-find,QEC,rust,MWPM,Stim,PyMatching,LDPC,qLDPC
Home-Page: https://www.qector.store
Author-email: Guillaume Lessard / iD01t Productions <admin@qector.store>
Requires-Python: >=3.9, <3.14
Description-Content-Type: text/markdown
Project-URL: Commercial Licensing, https://www.qector.store
Project-URL: Documentation, https://github.com/GuillaumeLessard/qector-decoder#readme
Project-URL: Homepage, https://www.qector.store
Project-URL: Issues, https://github.com/GuillaumeLessard/qector-decoder/issues
Project-URL: PyPI, https://pypi.org/project/qector-decoder-v3/
Project-URL: Repository, https://github.com/GuillaumeLessard/qector-decoder
Project-URL: Source, https://github.com/GuillaumeLessard/qector-decoder
Project-URL: Website, https://www.qector.store

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

Website: https://www.qector.store  
Repository: https://github.com/GuillaumeLessard/qector-decoder  
PyPI: https://pypi.org/project/qector-decoder-v3/  
Commercial licensing: https://www.qector.store

---

## Installation

Recommended command:

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

Verify the install:

```bash
python -c "from qector_decoder_v3 import UnionFindDecoder, BlossomDecoder; print('QECTOR OK')"
```

Optional research and validation extras:

```bash
# 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]"
```

---

## Supported public wheels

QECTOR v0.5.x public releases target standard CPython wheels for:

| Platform | Wheel status |
|---|---|
| Linux x86_64 | Published |
| Windows x64 | Published |
| macOS arm64 / Apple Silicon | Published |
| macOS Intel x86_64 | Not published in v0.5.x public CI |
| CPython free-threaded builds such as `cp313t` | Not published in v0.5.x |

Supported Python classifiers are standard CPython 3.9 to 3.13.

Windows note: do not force `py -m pip` unless you have checked which interpreter the Windows launcher selected. If `py` selects a free-threaded interpreter such as `python3.13t.exe`, pip may fall back to a source build and fail because the public repository does not ship the proprietary Rust core. Use the standard active Python environment instead:

```powershell
pip install qector-decoder-v3
python -c "from qector_decoder_v3 import UnionFindDecoder, BlossomDecoder; print('QECTOR OK')"
```

Check your Python launcher targets with:

```powershell
py -0p
```

---

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

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

```python
import stim
from qector_decoder_v3 import BlossomDecoder
from qector_decoder_v3.stim_compat import stim_circuit_to_check_matrix

circuit = stim.Circuit.generated(
    "surface_code:rotated_memory_z",
    distance=5,
    rounds=5,
    after_clifford_depolarization=0.005,
)

checks, n_qubits = stim_circuit_to_check_matrix(circuit)
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 |
| `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.

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

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

---

## GPU availability check

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

---

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

Website and commercial licensing:

https://www.qector.store

Contact:

admin@qector.store

---

## Citation

```bibtex
@software{lessard2026qector,
  author  = {Guillaume Lessard},
  title   = {{QECTOR Decoder v3}: Rust/Python Quantum Error Correction Decoding Platform},
  year    = {2026},
  version = {0.5.0},
  url     = {https://www.qector.store},
  note    = {Source-available. Commercial license required for commercial use.}
}
```

