Skip to content

Commit 79a4a9c

Browse files
qectorlabqectorlab
committed
seo: improve PyPI readable discovery text
1 parent 905f968 commit 79a4a9c

1 file changed

Lines changed: 5 additions & 122 deletions

File tree

‎PYPI_README.md‎

Lines changed: 5 additions & 122 deletions
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,10 @@
11
# QECTOR Decoder v3
22

3-
**Source-available Rust/Python quantum error correction decoding platform.**
3+
**Python and Rust quantum error correction decoder package.**
44

5-
QECTOR Decoder v3 provides a Python package backed by a native Rust extension for quantum error correction research and validation workflows.
5+
QECTOR Decoder v3 helps researchers and developers test quantum error correction decoder workflows from Python, with native Rust performance paths and reproducible benchmark artifacts.
6+
7+
Common search terms: quantum error correction, QEC decoder, quantum decoder Python, Rust quantum error correction, PyMatching-compatible decoder, Stim workflow, Sinter benchmark, BP-OSD, LDPC, qLDPC, surface code decoder, MWPM decoder, union find decoder, belief matching, PyO3, maturin, QECTOR.
68

79
Website: https://www.qector.store
810
PyPI: https://pypi.org/project/qector-decoder-v3/
@@ -40,7 +42,7 @@ pip install "qector-decoder-v3[all]"
4042

4143
Use the `pip` bound to your active standard Python environment. Do not force `py -m pip` unless you have checked which interpreter the Windows launcher selected.
4244

43-
On some systems, `py` can select a free-threaded interpreter such as `python3.13t.exe`. QECTOR v0.5.x publishes standard CPython wheels, not `cp313t` free-threaded wheels. If pip cannot find a matching wheel, it may fall back to a source build and fail because the public repository does not ship the proprietary Rust core.
45+
On some systems, `py` can select a free-threaded interpreter such as `python3.13t.exe`. QECTOR v0.5.x publishes standard CPython wheels, not `cp313t` free-threaded wheels.
4446

4547
Working Windows command:
4648

@@ -68,122 +70,3 @@ py -0p
6870
| CPython free-threaded builds such as `cp313t` | Not published in v0.5.x |
6971

7072
Supported Python classifiers are standard CPython 3.9 to 3.13.
71-
72-
---
73-
74-
## Quick start
75-
76-
```python
77-
import numpy as np
78-
from qector_decoder_v3 import UnionFindDecoder, BlossomDecoder
79-
80-
check_to_qubits = [[0, 1], [1, 2], [2, 3], [3, 4]]
81-
n_qubits = 5
82-
syndrome = np.array([0, 1, 0, 0], dtype=np.uint8)
83-
84-
uf = UnionFindDecoder(check_to_qubits, n_qubits)
85-
print(uf.decode(syndrome))
86-
87-
mwpm = BlossomDecoder(check_to_qubits, n_qubits)
88-
print(mwpm.decode(syndrome))
89-
```
90-
91-
Batch decoding:
92-
93-
```python
94-
import numpy as np
95-
from qector_decoder_v3 import BatchDecoder
96-
97-
checks = [[0, 1], [1, 2], [2, 3], [3, 4]]
98-
syndromes = np.random.randint(0, 2, size=(4096, 4), dtype=np.uint8)
99-
100-
cpu = BatchDecoder(checks, n_qubits=5)
101-
corrections = cpu.parallel_batch_decode(syndromes)
102-
print(corrections.shape)
103-
```
104-
105-
---
106-
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-
187-
## License
188-
189-
Source-available. Commercial use requires written licensing through https://www.qector.store.

0 commit comments

Comments
 (0)