QECTOR Decoder v3 — Verification Artifacts

Verification artifacts for the qector-decoder-v3 v1.0.0 Python wheel, frozen against the v1.0.0 Reference Manual (DOI 10.5281/zenodo.21941046). Every number in this repository comes from a real run on real hardware; the scripts and JSON are deterministic and re-runnable.

---

Contents

Path	What it is
scripts/final_benchmark.py	Monte-Carlo LER benchmark (Stim → Sinter → Wilson CI).
scripts/make_report.py	Renders the PDF report from results/benchmark.json.
scripts/investigations/debug_autorouter.py	Investigation log: the AutoRouter end-to-end "fix".
results/benchmark.json	Raw data behind every number in the PDF.
results/QECTOR_Decoder_v3_Benchmark_Report.pdf	10-page PDF, 6 charts.
results/charts/	PNGs embedded in the PDF.
reference-proof/certified_proof.json	SHA-256-pinned theorem-level certificate.
reference-proof/certified_report.pdf	78/78 proof report (independent run).
reference-proof/charts/	syndrome-faithfulness / Wilson / workspace charts.
local/license.key	Ed25519-signed Pro token (gitignored).
CHANGELOG.md / CITATION.cff / SECURITY.md	Repository metadata.
LICENSE	PolyForm-Noncommercial 1.0.0.

Headline numbers (last run on this host)

• License: Ed25519-verified, tier Pro, exp 2026-10-07T04:25:13Z.
• Reference proof suite: 78/78 PASS in 1.7 s.
• Distance sweep d ∈ {3, 5, 7}, blossom, p=1e-3, 2000 shots each: LER 0.05% / 0% / 0%.
• Decoder-kind comparison at d=5, p=1e-3: blossom / unionfind / belief all 0% LER (1 Monte-Carlo hit on unionfind at d=5 in a separate seed).
• Noise sweep d=5, blossom, p ∈ {3e-4, 1e-3, 3e-3, 1e-2}: LER 0% / 0% / 0.4% / 7.7%.
• AutoRouter end-to-end: H·c == s (mod 2) holds for 50 / 50 syndromes fed through AutoRouter.decode(code, syndromes).

The PDF report carries the same numbers with full Wilson 95% confidence intervals, compile-vs-decode breakdown, decoder architecture overview, and package surface appendix.

Quick start

# 1. Fresh venv + install the wheel
python -m venv .venv
.\.venv\Scripts\python.exe -m pip install "qector-decoder-v3[all]==1.0.0"

# 2. (Optional) drop your license key into local/license.key
#    The benchmark also reads QECTOR_LICENSE_KEY if you prefer.
#    The reference suite has its own activation path.

# 3. Re-run the benchmark
.\.venv\Scripts\python.exe -P scripts/final_benchmark.py

# 4. Re-render the PDF
.\.venv\Scripts\python.exe -P scripts/make_report.py

# 5. (Optional) re-run the 78-proof reference suite
#    (uses the same venv; --no-bootstrap skips re-install)
.\.venv\Scripts\python.exe -P "<path-to>/test_qector_decoder_v3_proofs.py" --no-bootstrap --no-banner

How the numbers are produced

1. License activation. The Ed25519 token in local/license.key (or the QECTOR_LICENSE_KEY env var) is loaded by scripts/final_benchmark.py. Both verify_license_token() and activate_license() are called and the tier / signature are persisted in results/benchmark.json.

2. Distance sweep. d ∈ {3, 5, 7}, blossom decoder, p=1e-3, 2000 shots per distance. Sampled via stim.Circuit.generated and compile_detector_sampler; decoded via the official QectorSinterDecoder(kind="blossom") adapter; compared to ground- truth observables with Wilson 95% CIs.

3. Decoder-kind comparison. d=5, p=1e-3: blossom and unionfind at 1000 shots, belief at 200 shots (belief is the throughput bottleneck on this CPU-only host).

4. Noise sweep. d=5, blossom, p ∈ {3e-4, 1e-3, 3e-3, 1e-2}, 2000 shots each. Feeds the d=5-only 1% LER crossover estimate in §7 of the PDF.

5. AutoRouter end-to-end. Per Reference Manual §16.5, the canonical entry point is codes.rotated_surface_code(d). The legacy generate_surface_code_checks(d) is "explicitly not graphlike" (§16.1) and would trip the structural guard. The benchmark calls AutoRouter.decode(code, syndromes) and verifies the foundational contract H·c == s (mod 2) for every row.

6. Reference proof suite. 78 theorems / worked examples from the manual, executed by test_qector_decoder_v3_proofs.py in the same venv with --no-bootstrap. The certified report in reference-proof/ is the artifact.

Repository metadata

• Topics: quantum-error-correction, qec, decoder, surface-code, mwpm, union-find, belief-matching, bp-osd, stim, sinter, rust, pyo3, python, benchmark, verification, reproducible-research, ed25519.
• Homepage: https://www.qector.store
• License: PolyForm-Noncommercial 1.0.0 — see LICENSE.
• Cite this: see CITATION.cff.

Provenance

• The wheel installed during the recorded run is qector-decoder-v3==1.0.0 from PyPI, with the [all] extra (matplotlib, cupy-cuda12x, sinter, pymatching, ldpc, beliefmatching, stripe, cryptography).
• The reference manual frozen against is QectorDecoder_v3_Reference_Manual_v1.0.0.pdf (DOI 10.5281/zenodo.21941046, deposited 2026-08).
• The hardware-specific numbers in results/benchmark.json are anchored to a single Windows 11 / Python 3.12 / CPU-only host and are not portable scientific claims. Hardware-independent claims (license activation, AutoRouter routing, H·c == s contract, reference proofs) are portable and are the actual point of this repository.