Implement 2025/2026 QEC strategic roadmap in v0.5.7 and align all versioning

Author: qectorlab

CHANGELOG.md

@@ -6,8 +6,8 @@ authors:
   - family-names: Lessard
     given-names: Guillaume
     affiliation: iD01t Productions
-version: 0.5.6
-date-released: 2026-06-28
+version: 0.5.7
+date-released: 2026-06-29
 url: https://www.qector.store
 repository-code: https://github.com/GuillaumeLessard/qector-decoder
 identifiers:

CITATION.cff

@@ -1,6 +1,6 @@
 [package]
 name = "qector_decoder_v3"
-version = "0.5.6"
+version = "0.5.7"
 edition = "2021"
 authors = ["Guillaume Lessard / iD01t Productions <guiliguili2705@gmail.com>"]
 description = "Source-available Rust QEC decoder core (Union-Find, exact polynomial MWPM/Blossom, Sparse Blossom, BP-OSD) with CPU/CUDA/OpenCL batch decoding and PyO3 bindings"

Cargo.lock

@@ -1,4 +1,4 @@
-# Installation Guide — QECTOR Decoder v3 (v0.5.6)
+# Installation Guide — QECTOR Decoder v3 (v0.5.7)
 
 The fastest path is a direct PyPI wheel install. Source builds are only needed
 when you want to develop against the Rust core or target a platform without a
@@ -65,7 +65,7 @@ $env:PYO3_PYTHON = (Resolve-Path .\.venv\Scripts\python.exe).Path
 Expected output ending:
 
 ```
-Installed qector-decoder-v3-0.5.6
+Installed qector-decoder-v3-0.5.7
 QECTOR OK
 ```
 

Cargo.toml

@@ -1,6 +1,6 @@
 # QECTOR Decoder v3
 
-**Python and Rust quantum error correction decoder package — v0.5.6**
+**Python and Rust quantum error correction decoder package — v0.5.7**
 
 QECTOR Decoder v3 helps researchers and developers build and benchmark quantum error correction decoder workflows from Python, with native Rust performance paths, GPU acceleration, and artifact-backed reproducible evidence.
 
@@ -248,6 +248,7 @@ LookupTableDecoder is the fastest single-shot decoder on rep d=5 (precomputed ta
 
 | Version | Date | Key change |
 |---|---|---|
+| **0.5.7** | 2026-06-29 | Advanced strategic QEC decoders: Fusion/Sparse Blossom, EBP, Restart Belief, KAT/QCT, Astra GNN, GPU pipelines |
 | **0.5.6** | 2026-06-28 | `stim_compat` doc fix: `stim_circuit_to_check_matrix` documented as parallel impl, not alias |
 | 0.5.5 | 2026-06-28 | `PredecodedDecoder.batch_decode()` wheel sync; PYTHONPATH guard; 775 tests pass |
 | 0.5.4 | 2026-06-27 | `NeuralPredecoder.train()` clear error on numpy>=2.0; 125/125 validation |

INSTALL.md

@@ -6,7 +6,7 @@
 [![GitHub stars](https://img.shields.io/github/stars/GuillaumeLessard/qector-decoder.svg)](https://github.com/GuillaumeLessard/qector-decoder/stargazers)
 [![GitHub last commit](https://img.shields.io/github/last-commit/GuillaumeLessard/qector-decoder)](https://github.com/GuillaumeLessard/qector-decoder/commits/main)
 
-Source-available Rust/Python QEC decoder package — v0.5.6
+Source-available Rust/Python QEC decoder package — v0.5.7
 
 PyMatching-compatible MWPM validation, belief-matching accuracy mode, BP-OSD for LDPC/qLDPC, CPU/GPU batch decoding, Stim/Sinter integration, and artifact-backed benchmark evidence.
 
@@ -216,6 +216,7 @@ Full artifact: `benchmark_results/results_v053_retest.json`
 
 | Version | Date | Key change |
 |---|---|---|
+| 0.5.7 | 2026-06-29 | Advanced strategic QEC decoders: Fusion/Sparse Blossom, EBP, Restart Belief, KAT/QCT, Astra GNN, GPU pipelines |
 | 0.5.6 | 2026-06-28 | `stim_compat` doc fix: `stim_circuit_to_check_matrix` is parallel impl, not alias |
 | 0.5.5 | 2026-06-28 | `PredecodedDecoder.batch_decode()` wheel fix; PYTHONPATH guard; 775 tests pass |
 | 0.5.4 | 2026-06-27 | `NeuralPredecoder.train()` clear error on numpy>=2.0; 125/125 validation |

PYPI_README.md

@@ -1 +1 @@
-{"@context":"https://doi.org/10.5063/schema/codemeta-2.0","@type":"SoftwareSourceCode","name":"QECTOR Decoder v3","version":"0.5.6","description":"Source-available Rust and Python quantum error correction decoder package for QEC research, PyMatching-compatible validation, belief-matching, BP-OSD and qLDPC workflows, CPU/GPU batch decoding, and reproducible benchmark evidence.","codeRepository":"https://github.com/GuillaumeLessard/qector-decoder","url":"https://www.qector.store","downloadUrl":"https://pypi.org/project/qector-decoder-v3/","identifier":"https://doi.org/10.5281/zenodo.20825980","license":"https://www.qector.store/license.html","programmingLanguage":["Python","Rust"],"runtimePlatform":["CPython 3.9","CPython 3.10","CPython 3.11","CPython 3.12","CPython 3.13","Linux x86_64","Windows x64","macOS arm64"],"keywords":["quantum error correction","QEC","quantum computing","quantum decoder","MWPM","PyMatching","Stim","Sinter","LDPC","qLDPC","BP-OSD","belief matching","union find decoder","surface code","Rust","Python","PyO3","maturin","QECTOR"],"author":{"@type":"Person","givenName":"Guillaume","familyName":"Lessard","affiliation":"iD01t Productions"},"publisher":{"@type":"Organization","name":"iD01t Productions"}}
+{"@context":"https://doi.org/10.5063/schema/codemeta-2.0","@type":"SoftwareSourceCode","name":"QECTOR Decoder v3","version":"0.5.7","description":"Source-available Rust and Python quantum error correction decoder package for QEC research, PyMatching-compatible validation, belief-matching, BP-OSD and qLDPC workflows, CPU/GPU batch decoding, and reproducible benchmark evidence.","codeRepository":"https://github.com/GuillaumeLessard/qector-decoder","url":"https://www.qector.store","downloadUrl":"https://pypi.org/project/qector-decoder-v3/","identifier":"https://doi.org/10.5281/zenodo.20825980","license":"https://www.qector.store/license.html","programmingLanguage":["Python","Rust"],"runtimePlatform":["CPython 3.9","CPython 3.10","CPython 3.11","CPython 3.12","CPython 3.13","Linux x86_64","Windows x64","macOS arm64"],"keywords":["quantum error correction","QEC","quantum computing","quantum decoder","MWPM","PyMatching","Stim","Sinter","LDPC","qLDPC","BP-OSD","belief matching","union find decoder","surface code","Rust","Python","PyO3","maturin","QECTOR"],"author":{"@type":"Person","givenName":"Guillaume","familyName":"Lessard","affiliation":"iD01t Productions"},"publisher":{"@type":"Organization","name":"iD01t Productions"}}

README.md

@@ -1,15 +1,17 @@
-# QECTOR API Stability Guide
+# QECTOR API Stability Guide — v0.5.7
 
-QECTOR Decoder v3 is a source-available research and commercial-evaluation platform. This file separates the APIs that are intended to be stable for normal local use from experimental surfaces that require extra caution.
+QECTOR Decoder v3 is a source-available research and commercial-evaluation platform.
+This file separates the APIs that are stable for normal local use from experimental
+surfaces that require extra caution.
 
 ## Stability levels
 
 | Level | Meaning | Examples |
 |---|---|---|
-| Stable local API | Expected to remain usable across compatible `0.5.x` releases, with bug-fix-level changes only | Core Python decoders, code generators, local source build, benchmark artifact format basics |
+| Stable local API | Expected to remain usable across compatible `0.5.x` releases with bug-fix-level changes only | Core Python decoders, code generators, local source build, benchmark artifact format |
 | Supported but workload-sensitive | Supported, but claims must be regenerated for the local code family, hardware, batch size, and dependency set | Stim/PyMatching comparisons, BP-OSD/LDPC experiments, CPU/GPU batch workflows |
-| Experimental / preview | Available for research, demos, or partner review, but not a compatibility promise | REST service, gRPC, MCP, metrics, hybrid/GNN paths, hosted API, OEM embedding |
-| Internal implementation detail | May change without notice | Rust module internals, fallback heuristics, private helper functions, benchmark script internals not documented here |
+| Experimental / preview | Available for research, demos, or partner review but not a compatibility promise | REST service, gRPC, MCP, metrics, hybrid/GNN paths, hosted API, OEM embedding |
+| Internal implementation detail | May change without notice | Rust module internals, fallback heuristics, private helper functions |
 
 ## Stable local Python APIs
 
@@ -25,6 +27,8 @@ from qector_decoder_v3 import (
     BpOsdDecoder,
     CPUBatchDecoder,
     BatchDecoder,
+    LookupTableDecoder,
+    PredecodedDecoder,          # v0.5.5+ — constructor: (check_to_qubits, n_qubits, backend)
     generate_ring_code_checks,
     generate_repetition_code_checks,
     generate_surface_code_checks,
@@ -35,22 +39,68 @@ Expected input/output model:
 
 ```text
 check_to_qubits: list[list[int]] or compatible Python sequence
-n_qubits: optional integer when not inferable
-syndrome: one-dimensional NumPy-compatible uint8/int/bool vector
-correction: NumPy-compatible binary vector of length n_qubits
+n_qubits:        optional integer when not inferable
+syndrome:        one-dimensional NumPy-compatible uint8/int/bool vector
+correction:      NumPy-compatible binary vector of length n_qubits
 ```
 
-The core correctness contract for a syndrome-faithful decoder is:
+The core correctness contract for a syndrome-faithful decoder:
 
 ```text
-H · correction == syndrome (mod 2)
+H · correction == syndrome  (mod 2)
 ```
 
-Use `docs/CORRECTNESS_AUDIT.md` for the exact decoder-by-decoder claim boundary.
+See `docs/CORRECTNESS_AUDIT.md` for the decoder-by-decoder claim boundary.
+
+## Stable stim_compat entry points (v0.5.7 clarification)
+
+`stim_compat` exposes two parallel entry points. As of v0.5.7 they are correctly
+documented as **parallel implementations**, not a Python alias:
+
+| Function | Accepts | Notes |
+|---|---|---|
+| `from_stim_detector_error_model` | `DetectorErrorModel` or `str` | Core entry point |
+| `stim_circuit_to_check_matrix` | `DetectorErrorModel`, `str`, or `stim.Circuit` | Superset — converts `stim.Circuit` via `.detector_error_model(decompose_errors=True)` internally |
+
+Both return `(check_to_qubits, n_qubits)` and produce identical results for
+`DetectorErrorModel` input. The prior erroneous `# alias` comment has been
+corrected in v0.5.7.
+
+```python
+from qector_decoder_v3.stim_compat import (
+    from_stim_detector_error_model,   # accepts DetectorErrorModel or str
+    stim_circuit_to_check_matrix,     # superset: also accepts stim.Circuit
+    to_stim_decoder,
+    stim_decoder_from_dem,
+)
+```
+
+## Stable sinter_compat entry points
+
+```python
+from qector_decoder_v3.sinter_compat import (
+    QectorSinterDecoder,              # primary Sinter-compatible decoder wrapper
+    QectorDecoderWrapper,             # backward-compat alias for QectorSinterDecoder
+    qector_sinter_decoders,           # returns dict of named sinter.Decoder instances
+)
+
+# standalone single-syndrome decode (v0.5.3+, no Sinter required)
+dec = QectorSinterDecoder("blossom")
+obs = dec.decode(syndrome, dem=dem)
+```
+
+## Stable single-shot additions (v0.5.3+)
+
+| API | Added in | Notes |
+|---|---|---|
+| `BatchDecoder.decode(syndrome)` | v0.5.3 | 1-row batch wrapper, matches dtype/shape contract of all other decoders |
+| `BeliefMatching(H, p=...)` | v0.5.3 | Raw numpy check matrix constructor with uniform prior |
+| `QectorSinterDecoder.decode(syndrome, dem)` | v0.5.3 | Standalone decode, DEM cached on first call |
 
 ## Supported but workload-sensitive APIs
 
-These APIs are valid, but their performance and scientific claims depend strongly on local context:
+These APIs are valid but their performance and scientific claims depend on local
+context:
 
 ```text
 BeliefMatching
@@ -72,9 +122,22 @@ Regenerate benchmark artifacts on the target workload and target hardware.
 Record git commit, OS, Python, Rust, dependencies, seeds, batch size, and raw JSON/CSV outputs.
 ```
 
+## NeuralPredecoder limitation (v0.5.4+)
+
+`NeuralPredecoder.train()` raises a clear `RuntimeError` on numpy>=2.0. This is a
+known Rust binding issue; `predict()` and `decode()` are unaffected. To train a
+model, use an environment with `numpy<2.0` installed until the binding is updated.
+
+## OpenCL false-negative (documented v0.5.5)
+
+`OpenCLBatchDecoder.is_available()` returns `False` on the AMD OCL SDK Light legacy
+runtime even though `OpenCL.dll` loads. Root cause: the `ocl` crate's
+`Device::list()` fails silently on that runtime. A ctypes-based fallback is
+scheduled for a future release.
+
 ## Experimental / preview surfaces
 
-The following are not enterprise-stable APIs in the public `0.5.x` release:
+Not enterprise-stable in the public `0.5.x` release:
 
 ```text
 REST service
@@ -88,32 +151,26 @@ hosted API
 OEM / embedded integration
 ```
 
-These surfaces are useful for demos, research, and partner evaluation, but they require a deployment review before customer-facing use. See:
-
-```text
-docs/SERVICE_API_SCHEMA.md
-docs/SECURITY_DEPLOYMENT.md
-COMMERCIAL.md
-```
+See `docs/SERVICE_API_SCHEMA.md`, `docs/SECURITY_DEPLOYMENT.md`, `COMMERCIAL.md`.
 
 ## Versioning policy for 0.5.x
 
-During the `0.5.x` line:
-
 ```text
-Patch releases may fix decoder behavior, docs, build issues, or benchmark scripts.
-Public local Python classes should not be renamed without a compatibility note.
-Experimental service surfaces may change schema or behavior.
+Patch releases may fix decoder behaviour, docs, build issues, or benchmark scripts.
+Public local Python classes will not be renamed without a compatibility note.
+Experimental service surfaces may change schema or behaviour.
 Benchmark numbers may be replaced only with regenerated artifacts and clear environment metadata.
-Commercial rights remain governed by LICENSE and COMMERCIAL.md, not by API availability.
+Commercial rights remain governed by LICENSE and COMMERCIAL.md.
 ```
 
 ## Safe public wording
 
 Safe:
 
 ```text
-QECTOR exposes a stable local Python API for source-built decoder experiments and reproducible benchmark workflows.
+QECTOR exposes a stable local Python API for source-built decoder experiments
+and reproducible benchmark workflows. PyPI wheels are available for CPython 3.9–3.13
+on Linux x86_64, Windows x64, and macOS arm64.
 ```
 
 Unsafe: