qector-decoder-v3 0.5.0__tar.gz

qector_decoder_v3-0.5.0/.gitattributes

@@ -0,0 +1,20 @@
+# Normalize line endings -- enforce LF for all text files regardless of OS
+* text=auto eol=lf
+
+# Binaries
+*.whl binary
+*.pyd binary
+*.so binary
+*.dll binary
+*.dylib binary
+*.lib binary
+*.exp binary
+*.a binary
+*.gz binary
+*.zip binary
+*.png binary
+*.jpg binary
+*.jpeg binary
+*.gif binary
+*.ico binary
+*.pdf binary

qector_decoder_v3-0.5.0/.github/workflows/CI.yml

@@ -0,0 +1,236 @@
+# CI -- Build wheels on Linux/Windows/macOS ARM, publish to PyPI on tag.
+#
+# Rust source is injected at build time from three GitHub Actions secrets
+# (RUST_SRC_B64_1 + RUST_SRC_B64_2 + RUST_SRC_B64_3) to keep the proprietary
+# core private. Secrets are base64 chunks that reassemble to src.tar.gz.
+# On forks / external PRs the secrets will be empty and wheel builds are skipped.
+#
+# Trigger: push to main/master, any tag v*, pull_request, manual dispatch.
+
+name: CI
+
+on:
+  push:
+    branches: [main, master]
+    tags: ["v*"]
+  pull_request:
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+env:
+  # Build without OpenCL (SDK not on runners). CUDA is runtime-loaded via
+  # libloading so no CUDA toolkit is needed at build time.
+  MATURIN_ARGS: --release --no-default-features --features cuda --out dist
+
+jobs:
+  # ------------------------------------------------------------------
+  # Linux x86_64 manylinux wheels
+  # ------------------------------------------------------------------
+  linux-x86_64:
+    name: linux-x86_64-py${{ matrix.python-version }}
+    runs-on: ubuntu-22.04
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.9", "3.10", "3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Inject Rust source
+        env:
+          PART1: ${{ secrets.RUST_SRC_B64_1 }}
+          PART2: ${{ secrets.RUST_SRC_B64_2 }}
+          PART3: ${{ secrets.RUST_SRC_B64_3 }}
+        run: |
+          if [ -z "$PART1" ]; then
+            echo "::warning::RUST_SRC_B64_1 secret not set -- skipping wheel build"
+            echo "SKIP_BUILD=1" >> "$GITHUB_ENV"
+          else
+            echo "${PART1}${PART2}${PART3}" | base64 -d | tar -xzf - -C .
+            echo "SKIP_BUILD=0" >> "$GITHUB_ENV"
+          fi
+
+      - uses: actions/setup-python@v5
+        if: env.SKIP_BUILD == '0'
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Build manylinux wheel
+        if: env.SKIP_BUILD == '0'
+        uses: PyO3/maturin-action@v1
+        with:
+          target: x86_64
+          manylinux: auto
+          args: ${{ env.MATURIN_ARGS }} -i python${{ matrix.python-version }}
+          sccache: ${{ !startsWith(github.ref, 'refs/tags/') }}
+
+      - uses: actions/upload-artifact@v4
+        if: env.SKIP_BUILD == '0'
+        with:
+          name: wheels-linux-x86_64-py${{ matrix.python-version }}
+          path: dist
+
+  # ------------------------------------------------------------------
+  # Windows x64 wheels
+  # ------------------------------------------------------------------
+  windows-x64:
+    name: windows-x64-py${{ matrix.python-version }}
+    runs-on: windows-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.9", "3.10", "3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Inject Rust source
+        env:
+          PART1: ${{ secrets.RUST_SRC_B64_1 }}
+          PART2: ${{ secrets.RUST_SRC_B64_2 }}
+          PART3: ${{ secrets.RUST_SRC_B64_3 }}
+        shell: bash
+        run: |
+          if [ -z "$PART1" ]; then
+            echo "::warning::RUST_SRC_B64_1 secret not set -- skipping wheel build"
+            echo "SKIP_BUILD=1" >> "$GITHUB_ENV"
+          else
+            echo "${PART1}${PART2}${PART3}" | base64 -d | tar -xzf - -C .
+            echo "SKIP_BUILD=0" >> "$GITHUB_ENV"
+          fi
+
+      - uses: actions/setup-python@v5
+        if: env.SKIP_BUILD == '0'
+        with:
+          python-version: ${{ matrix.python-version }}
+          architecture: x64
+
+      - name: Build Windows wheel
+        if: env.SKIP_BUILD == '0'
+        uses: PyO3/maturin-action@v1
+        with:
+          target: x64
+          args: ${{ env.MATURIN_ARGS }} -i python
+          sccache: ${{ !startsWith(github.ref, 'refs/tags/') }}
+
+      - uses: actions/upload-artifact@v4
+        if: env.SKIP_BUILD == '0'
+        with:
+          name: wheels-windows-x64-py${{ matrix.python-version }}
+          path: dist
+
+  # ------------------------------------------------------------------
+  # macOS Apple Silicon (aarch64) wheels
+  # ------------------------------------------------------------------
+  macos-arm:
+    name: macos-aarch64-py${{ matrix.python-version }}
+    runs-on: macos-14
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.9", "3.10", "3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Inject Rust source
+        env:
+          PART1: ${{ secrets.RUST_SRC_B64_1 }}
+          PART2: ${{ secrets.RUST_SRC_B64_2 }}
+          PART3: ${{ secrets.RUST_SRC_B64_3 }}
+        run: |
+          if [ -z "$PART1" ]; then
+            echo "::warning::RUST_SRC_B64_1 secret not set -- skipping wheel build"
+            echo "SKIP_BUILD=1" >> "$GITHUB_ENV"
+          else
+            echo "${PART1}${PART2}${PART3}" | base64 -d | tar -xzf - -C .
+            echo "SKIP_BUILD=0" >> "$GITHUB_ENV"
+          fi
+
+      - uses: actions/setup-python@v5
+        if: env.SKIP_BUILD == '0'
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Build macOS ARM wheel
+        if: env.SKIP_BUILD == '0'
+        uses: PyO3/maturin-action@v1
+        with:
+          target: aarch64
+          args: ${{ env.MATURIN_ARGS }} -i python
+          sccache: ${{ !startsWith(github.ref, 'refs/tags/') }}
+
+      - uses: actions/upload-artifact@v4
+        if: env.SKIP_BUILD == '0'
+        with:
+          name: wheels-macos-aarch64-py${{ matrix.python-version }}
+          path: dist
+
+  # ------------------------------------------------------------------
+  # Source distribution (sdist) -- pure Python, no Rust needed
+  # ------------------------------------------------------------------
+  sdist:
+    name: sdist
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Inject Rust source (needed by maturin sdist to embed Cargo.toml)
+        env:
+          PART1: ${{ secrets.RUST_SRC_B64_1 }}
+          PART2: ${{ secrets.RUST_SRC_B64_2 }}
+          PART3: ${{ secrets.RUST_SRC_B64_3 }}
+        run: |
+          if [ -z "$PART1" ]; then
+            echo "SKIP_BUILD=1" >> "$GITHUB_ENV"
+          else
+            echo "${PART1}${PART2}${PART3}" | base64 -d | tar -xzf - -C .
+            echo "SKIP_BUILD=0" >> "$GITHUB_ENV"
+          fi
+
+      - name: Build sdist
+        if: env.SKIP_BUILD == '0'
+        uses: PyO3/maturin-action@v1
+        with:
+          command: sdist
+          args: --out dist
+
+      - uses: actions/upload-artifact@v4
+        if: env.SKIP_BUILD == '0'
+        with:
+          name: wheels-sdist
+          path: dist
+
+  # ------------------------------------------------------------------
+  # Publish to PyPI via OIDC Trusted Publisher (no token required)
+  # Runs only on version tags pushed to the main repo (not forks)
+  # ------------------------------------------------------------------
+  release:
+    name: publish-to-pypi
+    runs-on: ubuntu-latest
+    if: >
+      startsWith(github.ref, 'refs/tags/v') &&
+      github.repository == 'GuillaumeLessard/qector-decoder' &&
+      github.event_name != 'pull_request'
+    needs: [linux-x86_64, windows-x64, macos-arm, sdist]
+    environment: pypi
+    permissions:
+      id-token: write
+      contents: write
+      attestations: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          path: dist
+          merge-multiple: true
+
+      - name: Generate artifact attestations
+        uses: actions/attest-build-provenance@v2
+        with:
+          subject-path: "dist/*"
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          packages-dir: dist/
+          skip-existing: true

qector_decoder_v3-0.5.0/.github/workflows/tests.yml

@@ -0,0 +1,84 @@
+# Lint and static analysis -- runs on every push/PR, no Rust build needed.
+# Uses the installed wheel from PyPI (or a local sdist) to run the Python layer.
+
+name: tests
+
+on:
+  push:
+    branches: [main, master]
+  pull_request:
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  # ------------------------------------------------------------------
+  # Ruff lint + MyPy type-check
+  # ------------------------------------------------------------------
+  lint:
+    name: ruff-and-mypy
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: Install linting tools
+        # numpy is intentionally omitted: numpy 2.x stubs use `type` syntax
+        # (Python 3.12+) which mypy rejects in py3.9 mode. --ignore-missing-imports
+        # in pyproject.toml handles the missing stubs gracefully.
+        run: pip install ruff mypy
+      - name: Ruff lint
+        run: ruff check python/
+      - name: Ruff format check
+        run: ruff format --check python/
+      - name: MyPy
+        # continue-on-error: pre-existing type inconsistencies in the Python layer
+        # (no-any-return, valid-type, attr-defined, operator, assignment) will be
+        # addressed in a follow-up typing PR. Lint and format checks are hard failures.
+        continue-on-error: true
+        run: mypy python/qector_decoder_v3/ --ignore-missing-imports
+
+  # ------------------------------------------------------------------
+  # Docker image build smoke test
+  # Dockerfile runs maturin build --release which requires the real Rust
+  # source (injected at CI build time via secrets). In the tests workflow
+  # the source is a stub, so the build is expected to fail -- mark
+  # continue-on-error so this job is informational only.
+  # ------------------------------------------------------------------
+  docker:
+    name: docker-build
+    runs-on: ubuntu-latest
+    continue-on-error: true
+    steps:
+      - uses: actions/checkout@v4
+      - name: Build Docker image (Rust source stub -- expected failure)
+        run: docker build -t qector-decoder-test:ci . || echo "::warning::Docker build failed (stub src -- expected)"
+
+  # ------------------------------------------------------------------
+  # Python layer import smoke test (installs from PyPI)
+  # ------------------------------------------------------------------
+  smoke-import:
+    name: smoke-import-py${{ matrix.python-version }}
+    runs-on: ubuntu-22.04
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.9", "3.10", "3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - name: Install from PyPI
+        run: pip install qector-decoder-v3 --pre || echo "PyPI package not yet available -- skipping import test"
+      - name: Import smoke test
+        run: |
+          python -c "
+          try:
+              import qector_decoder_v3
+              print(f'qector_decoder_v3 {getattr(qector_decoder_v3, \"__version__\", \"unknown\")} imported OK')
+          except ImportError as e:
+              print(f'ImportError (expected if not on PyPI yet): {e}')
+          "

qector_decoder_v3-0.5.0/.gitignore

@@ -0,0 +1,80 @@
+# QECTOR Decoder v3 -- .gitignore
+# =================================
+
+# --- Build artifacts ---
+/target/
+/dist/
+*.whl
+*.tar.gz
+*.pyd
+*.so
+*.dll
+*.dylib
+
+# --- Python ---
+__pycache__/
+*.py[cod]
+*$py.class
+*.egg-info/
+*.egg
+.eggs/
+build/
+develop-eggs/
+downloads/
+eggs/
+.installed.cfg
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.spec
+pip-wheel-metadata/
+share/python-wheels/
+MANIFEST
+
+# --- Virtual environments ---
+.venv/
+venv/
+env/
+ENV/
+env.bak/
+venv.bak/
+
+# --- IDE ---
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+
+# --- Rust ---
+Cargo.lock.bak
+
+# --- Generated lib artifacts (only OpenCL.def is tracked) ---
+lib/OpenCL.lib
+lib/OpenCL.exp
+
+# --- Local build/dev directories ---
+actions-runner/
+artifacts/
+
+# --- OS ---
+.DS_Store
+Thumbs.db
+desktop.ini
+
+# --- Benchmark outputs (tracked selectively) ---
+# benchmark_results/ is tracked intentionally for reproducibility evidence
+
+# --- Testing ---
+.pytest_cache/
+.coverage
+htmlcov/
+.mypy_cache/
+.ruff_cache/
+
+# --- Temporary ---
+*.tmp
+*.bak
+*.orig

qector_decoder_v3-0.5.0/CHANGELOG.md

@@ -0,0 +1,64 @@
+# Changelog
+
+All notable changes to QECTOR Decoder v3 are documented here. The format is based
+on [Keep a Changelog](https://keepachangelog.com/), and the project aims to follow
+semantic versioning. Every benchmark artifact is stamped with the git commit and
+environment so report figures trace back to a specific build.
+
+## [Unreleased]
+
+## [0.5.0] - 2026-06-23
+
+### Fixed
+- **Blossom exactness at large distance (adaptive-k).** `BlossomDecoder` previously
+  used a fixed `k=12` candidate cap, which undershot the optimum on large dense
+  circuit-level graphs (d ≥ 13–15), producing heavier matchings and a markedly
+  worse logical error rate than PyMatching at d=15. The candidate set is now
+  **adaptive**, `k = max(12, 4·√n_defects)`, restoring exact-MWPM LER parity with
+  PyMatching through **d=15** (`memory_x` and `memory_z`). Locked permanently by
+  `test_blossom_adaptive_k_regression.py`, `test_blossom_d15_no_gap.py`,
+  `test_blossom_candidate_set_contains_optimal.py`, `test_weight_gap_histogram.py`,
+  and `test_defect_count_vs_weight_gap.py`.
+
+### Added
+- **QECTOR Workbench** (`qector_decoder_v3.workbench.Workbench`): headless,
+  fully-tested controller to load `.stim`/`.dem` files, run cancelable benchmark
+  jobs through a FIFO queue, and export JSON/CSV/PDF reports (charts built from
+  real artifacts, no fabricated data). Backend detection + environment snapshot.
+- **Evidence & reproduction scripts**: `run_due_diligence_bundle.py` (one-command
+  evidence bundle with hashes + git commit), `belief_reference_compare.py`,
+  `gpu_memory_profile.py`, `auto_backend_calibrate.py`, `leak_test.py`.
+- **Provenance**: `benchmarking.capture_environment()` now records `git_commit`, so
+  every JSON artifact and report figure points to the exact build it came from
+  (replaces "Git commit: unknown").
+- **Expanded validation suite** covering: exact-MWPM parity (memory_x/z, p-sweep,
+  rounds-sweep), DEM-collapse mathematical equivalence + d=11/d=15 regression
+  fixtures (50,484→6,718 and 132,426→17,862), logical-observable / stabilizer-coset
+  correctness, belief-matching seed×p grid + reference cross-check, BP-OSD on
+  BB[[72,12]]/BB[[144,12,12]]/HGP/bicycle, GPU CPU-bit-identity + fallback +
+  calibration, latency percentiles + tail, and memory/leak profiling.
+- **Documentation**: README "Validated scope", "When to use which decoder" decision
+  matrix, and a permanent "Known limitations" section with honest latency ratios.
+
+### Build
+- Refreshed Rust dependencies (`rayon` 1.12, `fastrand` 2.4) and migrated the
+  optional `grpc`/`full` stack to `tonic` 0.14 / `prost` 0.14 with a vendored
+  `protoc` (`protoc-bin-vendored`), so gRPC builds need no system `protoc`. The
+  default wheel features (`opencl`, `cuda` with CPU fallback) are unchanged.
+
+## [0.4.0]
+
+### Added
+- `SparseBlossomDecoder` (region-growing, RadixHeap, exact DP for n ≤ 20 with
+  Edmonds primal-dual fallback), bit-validated against `BlossomDecoder`.
+- Ecosystem layer: `codes`, `dem`, `result`, `backend`, `pymatching_compat`,
+  `benchmarking`; belief-matching and BP-OSD decoders; Stim/Sinter compatibility.
+- Native CUDA (NVRTC + Driver API) and OpenCL batch decoders with CPU fallback.
+
+### Fixed
+- Stim DEM loading uses the correct detector graph (mechanisms = columns,
+  detectors = rows), replacing the earlier `stim_compat` heuristic.
+
+## [0.2.0]
+
+- Python + Numba baseline decoder core (pre-Rust rewrite).

qector_decoder_v3-0.5.0/COMMERCIAL.md

@@ -0,0 +1,133 @@
+# Commercial Licensing
+
+QECTOR Decoder v3 is source-available for personal, academic, educational, and
+non-commercial research use.
+
+Commercial use requires a paid commercial license.
+
+Commercial use includes, but is not limited to:
+
+- company use
+- startup use
+- commercial R&D
+- government use
+- institutional or funded use
+- paid consulting
+- SaaS use
+- hosted API use
+- OEM embedding
+- product integration
+- redistribution
+- internal business operations
+- commercial benchmarking
+- revenue-generating use
+- fundraising or investor validation
+
+## Current commercial pricing position
+
+QECTOR is priced as a source-available Rust/Python QEC R&D platform, not as a
+mature real-time hardware QEC stack.
+
+The defendable value is decoder diversity, reproducible benchmark packaging,
+BP-OSD / LDPC workflows, CPU/GPU batch paths, source access, and commercial legal
+clarity.
+
+QECTOR should not be sold as the universal fastest MWPM decoder. PyMatching
+remains the latency leader for exact MWPM on the tested workloads. QECTOR's
+commercial value must come from broader workflow packaging, differentiated R&D
+use cases, reproducible artifacts, and selected accuracy-mode gains.
+
+## Why pay when PyMatching and Stim are free?
+
+PyMatching and Stim are excellent free baselines. A buyer should not license
+QECTOR only to get exact-MWPM surface-code latency.
+
+QECTOR is a paid commercial option when a team needs:
+
+| Need | QECTOR value |
+|---|---|
+| Multi-decoder experiments | Union-Find, Blossom, Sparse Blossom, BP-OSD, streaming, batch, and hybrid workflows in one source-available platform |
+| LDPC/qLDPC coverage | BP-OSD and LDPC workflows beyond plain graphlike MWPM |
+| Reproducible evidence | Benchmark artifacts, environment snapshots, reproducibility scripts, and Workbench report bundles |
+| Commercial permission | Written license terms for company, lab, funded, product, hosted, or revenue-linked use |
+| Support path | Paid support, validation package, and advisory options for commercial R&D users |
+
+The correct commercial pitch is workflow/time-saving value, reproducible proof,
+legal clarity, and decoder breadth. Do not pitch QECTOR as a universal PyMatching
+replacement.
+
+## Public pricing tiers
+
+| Tier | Price | Scope |
+|---|---:|---|
+| Personal / Academic | Free | Personal, academic, educational, and non-commercial research use |
+| Commercial Evaluation Pilot | $1,500 / 90 days | Internal commercial evaluation, up to 2 named users, creditable toward annual license |
+| Startup Commercial | $3,500 / year | Early commercial R&D, internal prototype use, up to 5 named users |
+| Professional / Lab | $15,000 / year | Funded lab or commercial R&D use, benchmark workflows, up to 20 named users |
+| Enterprise R&D | $35,000+ / year | Internal enterprise evaluation and commercial QEC research workflows |
+| SaaS / Hosted API | Contact only | Beta review only until production hosted infrastructure, support scope, and hosted-value proof exist |
+| OEM / Embedded | Contact only | Partner validation only until hardware/platform scope and redistribution terms exist |
+| Strategic Partnership | Custom | No public exclusive-price floor; requires validation, IP, or partnership scope |
+
+Hosted API and OEM prices are intentionally not listed publicly at this stage.
+QECTOR's hosted layer is not yet enterprise SaaS infrastructure, and OEM rights
+require a serious hardware or platform partner before pricing can be responsible.
+
+## Optional support and advisory pricing
+
+| Service | Price | Scope |
+|---|---:|---|
+| Priority Support | $5,000 / year | Private email support and priority bug review for licensed users |
+| Integration Support | $10,000 / year | Benchmark review, install support, and integration guidance |
+| Validation Report Package | $5,000 one-time | Review of customer benchmark setup and reproducibility package |
+| Custom Engineering | $150 / hour | Private fixes, special reports, scripts, or workflow adaptation |
+| Technical Advisory | $2,000 / day | Architecture review and QEC workflow consulting |
+
+## Pilot success criteria
+
+A commercial pilot should be judged on measurable workflow value, not vague
+interest.
+
+Recommended pilot proof points:
+
+- install success on the buyer's target machines
+- one reproduced benchmark artifact bundle
+- one QECTOR vs PyMatching comparison run
+- one BP-OSD / LDPC workflow if relevant
+- one artifact manifest with hashes and environment snapshot
+- documented time saved versus the buyer's existing PyMatching / Stim / custom-script workflow
+
+## Next proof asset
+
+The next commercially important public artifact is a reproducible GPU/batch
+benchmark campaign against a strong PyMatching + Stim baseline.
+
+Do not claim universal GPU throughput superiority, RTX 4090 speedups, SaaS
+readiness, OEM readiness, or real-time hardware decoding until the repository
+includes reproducible artifacts with hardware, driver/runtime versions, batch
+size, circuit/DEM, seeds, wall time, memory, output hashes, and environment
+snapshots.
+
+## Rights not included by default
+
+Unless explicitly granted in a written commercial agreement, no license tier
+includes:
+
+- redistribution rights
+- sublicensing rights
+- OEM rights
+- hosted API rights
+- SaaS rights
+- trademark rights
+- patent rights
+- exclusivity
+- warranty or indemnification
+- government or defense rights
+
+## Official licensing portal
+
+https://www.qector.store
+
+## Commercial contact
+
+admin@qector.store