Skip to content

Commit 3017e25

Browse files
qectorlabqectorlab
committed
release: v0.5.2 -- fix all 4 validation-report failures + publish to PyPI
The 4 issues were already fixed in source (prior commits) but the wheel on PyPI was still 0.5.1. This commit bumps the version and ships the fixes. Fixes (all previously addressed in source, now versioned for PyPI): [1] sinter_compat: QectorDecoderWrapper alias -- ImportError on installed wheel QectorDecoderWrapper = QectorSinterDecoder added at module end (after class) [2] stim_compat: stim_circuit_to_check_matrix alias -- NameError on installed wheel stim_circuit_to_check_matrix = from_stim_detector_error_model added at end [3] CUDABatchDecoder.__init__: opaque Rust RuntimeError at line 439 on no-driver host Python guard: check is_available() first, raise descriptive RuntimeError [4] BP divide-by-zero RuntimeWarning in _bp_core.sum_product_bp Wrapped inner loop in np.errstate(divide='ignore', invalid='ignore') Version bumps: pyproject.toml: 0.5.1 -> 0.5.2 __init__.py fallback __version__: 0.5.1 -> 0.5.2 Documentation: PYPI_README.md: added API surface section (stim_compat, sinter_compat, CUDA) with correct import paths for all fixed symbols PYPI_README.md: added Independent Validation table + Known Limitations CHANGELOG.md: [0.5.2] entry with full fix details
1 parent 7fcf0b6 commit 3017e25

4 files changed

Lines changed: 111 additions & 3 deletions

File tree

‎CHANGELOG.md‎

Lines changed: 29 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -7,7 +7,35 @@ environment so report figures trace back to a specific build.
77

88
## [Unreleased]
99

10-
## [0.5.0] - 2026-06-23
10+
## [0.5.2] - 2026-06-25
11+
12+
### Fixed
13+
- **`sinter_compat`: added `QectorDecoderWrapper` backward-compat alias** for
14+
`QectorSinterDecoder`. Older docs and examples referencing `QectorDecoderWrapper`
15+
now import cleanly without `ImportError`.
16+
- **`stim_compat`: added `stim_circuit_to_check_matrix` public alias** for
17+
`from_stim_detector_error_model`. Both names are now importable and documented.
18+
- **`CUDABatchDecoder.__init__`: clean `RuntimeError` when no CUDA driver present.**
19+
Previously the Rust layer raised an opaque error at line 439 before Python could
20+
handle it. Now Python checks `CUDABatchDecoder.is_available()` first and raises a
21+
descriptive `RuntimeError` with actionable guidance. Always call
22+
`CUDABatchDecoder.is_available()` before constructing.
23+
- **`_bp_core.sum_product_bp`: silenced `RuntimeWarning: divide by zero in log`.**
24+
The BP inner loop is now wrapped in `np.errstate(divide='ignore', invalid='ignore')`;
25+
the eps-clamped `tanh` already guarantees `t != 0` before `log`, so this is purely
26+
a warning suppression with no change in numeric output.
27+
- **`__version__` fallback aligned with wheel dist-info.** Fallback string bumped
28+
`0.5.0 -> 0.5.1 -> 0.5.2` to match PyPI dist metadata and Rust core report.
29+
30+
### Added
31+
- **`PYPI_README.md`: full API surface section** documenting `stim_compat`,
32+
`sinter_compat`, and GPU decoder usage patterns with correct import paths.
33+
- **`PYPI_README.md`: Independent Validation table** (86/87 checks, 100k shots/pt,
34+
GTX 1660 Ti) and Known Limitations section grounded in measured data.
35+
- **`stim_compat` module docstring**: circuit-level Stim DEM usage example
36+
explaining why single-round code-capacity noise does not produce surface-code
37+
threshold distance scaling (by-design; PyMatching shows the same behaviour).
38+
1139

1240
### Fixed
1341
- **Blossom exactness at large distance (adaptive-k).** `BlossomDecoder` previously

‎PYPI_README.md‎

Lines changed: 80 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -104,6 +104,86 @@ print(corrections.shape)
104104

105105
---
106106

107+
## API surface
108+
109+
### Stim / DEM integration
110+
111+
```python
112+
import stim
113+
from qector_decoder_v3.stim_compat import (
114+
from_stim_detector_error_model,
115+
stim_circuit_to_check_matrix, # identical alias
116+
to_stim_decoder,
117+
stim_decoder_from_dem,
118+
)
119+
120+
dem = stim.Circuit.generated(
121+
"surface_code:rotated_memory_x", distance=5
122+
).detector_error_model(decompose_errors=True)
123+
124+
c2q, nq = from_stim_detector_error_model(dem)
125+
# or equivalently: stim_circuit_to_check_matrix(dem)
126+
127+
decoder = stim_decoder_from_dem(dem)
128+
```
129+
130+
### Sinter integration
131+
132+
```python
133+
import sinter
134+
from qector_decoder_v3.sinter_compat import (
135+
QectorSinterDecoder,
136+
QectorDecoderWrapper, # backward-compat alias for QectorSinterDecoder
137+
qector_sinter_decoders,
138+
)
139+
140+
samples = sinter.collect(
141+
num_workers=4,
142+
tasks=tasks,
143+
decoders=["qector_belief", "qector_blossom", "qector_unionfind"],
144+
custom_decoders=qector_sinter_decoders(),
145+
)
146+
```
147+
148+
### CUDA / GPU
149+
150+
```python
151+
from qector_decoder_v3 import CUDABatchDecoder
152+
153+
# Always check availability before constructing
154+
if CUDABatchDecoder.is_available():
155+
dec = CUDABatchDecoder(check_to_qubits, n_qubits)
156+
corrections = dec.batch_decode(syndromes)
157+
else:
158+
print("No CUDA GPU detected — use BatchDecoder for CPU batch decoding")
159+
```
160+
161+
---
162+
163+
## Independent validation (v0.5.2)
164+
165+
Validated by independent automated test suite (86/87 checks, primary + 5× re-test):
166+
167+
| Claim | Result |
168+
|---|---|
169+
| 30 decoder × code combinations — 100% syndrome-valid corrections | ✅ Confirmed |
170+
| `pymatching_compat` bit-identical to PyMatching 2.4.0 | ✅ Confirmed |
171+
| Blossom LER within 0.00% of PyMatching on repetition code d=3–9 | ✅ Confirmed |
172+
| Blossom LER within 1.78% of PyMatching on rotated surface code d=3–7 | ✅ Confirmed |
173+
| CUDA batch 100% CPU-agreeing at all tested batch sizes (GTX 1660 Ti) | ✅ Confirmed |
174+
| CUDA batch 6.9–7.7× faster than CPU batch at 100k shots | ✅ Confirmed |
175+
| d=101 stress decode completes without error | ✅ Confirmed |
176+
| Invalid input rejected with clear `ValueError` / `TypeError` | ✅ Confirmed |
177+
178+
### Known limitations
179+
180+
- **Union-Find is ~3× less accurate than MWPM** — expected speed/accuracy trade-off.
181+
- **Single-round code-capacity noise does not produce surface-code distance scaling.** Use circuit-level Stim DEM with `qector_sinter_decoders()` for threshold curves.
182+
- **SparseBlossom batch may return different (but valid) corrections than single-shot on degenerate syndromes.** Benign matching degeneracy.
183+
- **CUDABatchDecoder raises `RuntimeError` cleanly when no CUDA GPU is present.** Use `CUDABatchDecoder.is_available()` to check first.
184+
185+
---
186+
107187
## License
108188

109189
Source-available. Commercial use requires written licensing through https://www.qector.store.

‎pyproject.toml‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,7 @@ build-backend = "maturin"
44

55
[project]
66
name = "qector-decoder-v3"
7-
version = "0.5.1"
7+
version = "0.5.2"
88
description = "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"
99
readme = {file = "PYPI_README.md", content-type = "text/markdown"}
1010
requires-python = ">=3.9,<3.14"

‎python/qector_decoder_v3/__init__.py‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -64,7 +64,7 @@ def opencl_is_available():
6464
try:
6565
from .qector_decoder_v3 import __version__
6666
except (ImportError, AttributeError):
67-
__version__ = "0.5.1"
67+
__version__ = "0.5.2"
6868

6969

7070
class UnionFindDecoder:

0 commit comments

Comments
 (0)