docs(v0.5.6): rebuild README, PYPI_README, INSTALL, RELEASE_NOTES -- stim_compat parallel-impl note, changelog table, API surface, latency table, verified platforms

Author: qectorlab

INSTALL.md

@@ -1,10 +1,53 @@
-# Installation Guide — QECTOR Decoder v0.5.4
+# Installation Guide — QECTOR Decoder v3 (v0.5.6)
 
-The current repository does **not** include `install.py`. Use the source build path below.
+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
+published wheel.
 
-## Windows PowerShell
+---
 
-Install Rust first from rustup, then run:
+## PyPI wheel install (recommended)
+
+```bash
+pip install qector-decoder-v3
+python -c "from qector_decoder_v3 import UnionFindDecoder, BlossomDecoder; print('QECTOR OK')"
+```
+
+Optional extras:
+
+```bash
+pip install "qector-decoder-v3[stim]"
+pip install "qector-decoder-v3[bench]"
+pip install "qector-decoder-v3[all]"
+```
+
+---
+
+## Windows note
+
+Use the `pip` bound to your active standard CPython environment. Do not force
+`py -m pip` unless you have verified which interpreter the Windows launcher selected.
+On some systems `py` selects the free-threaded interpreter (`python3.13t.exe`).
+QECTOR v0.5.x publishes standard CPython wheels only — not `cp313t`.
+
+Check launcher targets:
+
+```powershell
+py -0p
+```
+
+Working PowerShell install:
+
+```powershell
+pip install qector-decoder-v3
+python -c "from qector_decoder_v3 import UnionFindDecoder, BlossomDecoder; print('QECTOR OK')"
+```
+
+---
+
+## Source build (Windows PowerShell)
+
+Install Rust from https://rustup.rs first, then:
 
 ```powershell
 git clone https://github.com/GuillaumeLessard/qector-decoder.git
@@ -19,18 +62,20 @@ $env:PYO3_PYTHON = (Resolve-Path .\.venv\Scripts\python.exe).Path
 .\.venv\Scripts\python.exe -c "from qector_decoder_v3 import UnionFindDecoder; print('QECTOR OK')"
 ```
 
-### Verified Windows result
+Expected output ending:
 
-This command has been verified from a fresh clone on a second Windows PC with Python 3.11. The expected successful ending is:
-
-```text
-Installed qector-decoder-v3-0.5.4
+```
+Installed qector-decoder-v3-0.5.6
 QECTOR OK
 ```
 
-During the base install, pip may print ignored optional-extra messages for packages such as pytest, stim, pymatching, sinter, and ldpc. That is normal because the public command installs the minimal CPU-safe runtime build. Install optional test and benchmark dependencies only when needed.
+pip may print ignored optional-extra messages for pytest, stim, pymatching, sinter,
+and ldpc during install. That is expected — the base command installs the minimal
+CPU-safe runtime only.
 
-## Git Bash on Windows
+---
+
+## Source build (Git Bash on Windows)
 
 ```bash
 git clone https://github.com/GuillaumeLessard/qector-decoder.git
@@ -46,40 +91,59 @@ python -m maturin develop --release --no-default-features
 python -c "from qector_decoder_v3 import UnionFindDecoder; print('QECTOR OK')"
 ```
 
-## Optional test dependencies
+---
 
-```powershell
-.\.venv\Scripts\python.exe -m pip install "pytest>=7" "hypothesis>=6" "fastapi>=0.110" "uvicorn>=0.29" "httpx>=0.27" stim pymatching sinter ldpc beliefmatching psutil matplotlib tabulate scipy
-.\.venv\Scripts\python.exe -m pytest python/tests -q --tb=short
+## Source build (Linux / macOS)
+
+```bash
+git clone https://github.com/GuillaumeLessard/qector-decoder.git
+cd qector-decoder
+
+python3 -m venv .venv
+source .venv/bin/activate
+pip install --upgrade pip maturin
+
+maturin develop --release --no-default-features
+
+python -c "from qector_decoder_v3 import UnionFindDecoder; print('QECTOR OK')"
 ```
 
-## Optional feature builds
+---
 
-The first install uses `--no-default-features` because it is the safest public CPU path.
+## Optional test dependencies
 
 ```powershell
-# CUDA only
-.\.venv\Scripts\python.exe -m maturin develop --release --no-default-features --features cuda
-
-# OpenCL only
-.\.venv\Scripts\python.exe -m maturin develop --release --no-default-features --features opencl
+.\.venv\Scripts\python.exe -m pip install `
+    "pytest>=7" "hypothesis>=6" "fastapi>=0.110" "uvicorn>=0.29" "httpx>=0.27" `
+    stim pymatching sinter ldpc beliefmatching psutil matplotlib tabulate scipy
 
-# Full infrastructure build
-.\.venv\Scripts\python.exe -m maturin develop --release --features full
+.\.venv\Scripts\python.exe -m pytest python/tests -q --tb=short
 ```
 
-## Common fixes
+---
+
+## Optional feature builds
 
-If `maturin` is missing, install it with the venv Python:
+The default install uses `--no-default-features` for the safest public CPU path.
+
+To build with CUDA and OpenCL support:
 
 ```powershell
-.\.venv\Scripts\python.exe -m pip install --upgrade pip maturin
+.\.venv\Scripts\python.exe -m maturin develop --release
 ```
 
-If Rust is missing, install Rust and restart the shell.
+CUDA requires the NVCC toolchain and CUDA driver >= 7.5.
+OpenCL requires a valid ICD loader and GPU driver. See `docs/PLATFORM_ARTIFACT_ROADMAP.md`
+for the known AMD OCL SDK Light false-negative on `is_available()`.
 
-If GPU feature builds fail, build the CPU-safe path first:
+---
 
-```powershell
-.\.venv\Scripts\python.exe -m maturin develop --release --no-default-features
-```
+## Verified platforms
+
+| Platform | Python | Wheel | Notes |
+|---|---|---|---|
+| Windows 10 x64 | 3.11, 3.13 | Published | GTX 1660 Ti CUDA 7.5 validated |
+| Linux x86\_64 | 3.9 – 3.13 | Published | CI-built, not locally validated |
+| macOS arm64 | 3.9 – 3.13 | Published | CI-built |
+| macOS x86\_64 | 3.9 – 3.13 | Not published | Source build required |
+| cp313t (free-threaded) | — | Not published | Standard CPython only in v0.5.x |