prism-q 0.21.1__tar.gz

prism_q-0.21.1/.github/ISSUE_TEMPLATE/BUG-REPORT.yml

@@ -0,0 +1,109 @@
+name: Bug report
+description: Report incorrect behavior, performance regressions, panics, or build failures.
+title: "[Bug]: "
+labels: ["bug"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thanks for reporting a bug. Include enough detail to reproduce the issue and assess performance impact.
+
+  - type: textarea
+    id: summary
+    attributes:
+      label: Summary
+      description: Describe the problem and why it matters.
+      placeholder: "Example: Applying a controlled gate with adjacent qubits returns an incorrect amplitude."
+    validations:
+      required: true
+
+  - type: dropdown
+    id: bug-type
+    attributes:
+      label: Bug category
+      description: Select the primary category.
+      options:
+        - Incorrect simulation result
+        - Performance regression
+        - Panic or crash
+        - Build, CI, or tooling failure
+        - Documentation mismatch
+        - Other
+    validations:
+      required: true
+
+  - type: textarea
+    id: reproduction
+    attributes:
+      label: Reproduction steps
+      description: Provide a minimal command, circuit, test case, or code snippet that triggers the issue.
+      placeholder: |
+        1. Run `cargo test ...`
+        2. Execute this circuit:
+           ...
+        3. Observe ...
+    validations:
+      required: true
+
+  - type: textarea
+    id: expected
+    attributes:
+      label: Expected behavior
+      description: State the correct result, timing, output, or error handling.
+    validations:
+      required: true
+
+  - type: textarea
+    id: actual
+    attributes:
+      label: Actual behavior
+      description: Paste the observed result, error output, panic, or benchmark regression.
+      render: shell
+    validations:
+      required: true
+
+  - type: textarea
+    id: affected-area
+    attributes:
+      label: Affected area
+      description: List the backend, gate, parser, fusion pass, benchmark, or public API involved.
+      placeholder: "Example: statevector backend, controlled-X kernel, benches/circuits.rs"
+    validations:
+      required: true
+
+  - type: textarea
+    id: environment
+    attributes:
+      label: Environment
+      description: Include enough system detail to reproduce correctness or performance issues.
+      value: |
+        - OS:
+        - CPU model:
+        - Rust version:
+        - PRISM-Q commit:
+        - Feature flags:
+        - Compiler flags:
+    validations:
+      required: true
+
+  - type: textarea
+    id: benchmarks
+    attributes:
+      label: Benchmark or profiling data
+      description: Required for performance regressions. Include before and after numbers if available.
+      placeholder: |
+        | Benchmark | Before | After | Change |
+        | --- | --- | --- | --- |
+        |  |  |  |  |
+
+        Regression verdict: PASS / FAIL / WAIVER
+    validations:
+      required: false
+
+  - type: textarea
+    id: additional-context
+    attributes:
+      label: Additional context
+      description: Add links, related issues, screenshots, logs, or proposed fixes.
+    validations:
+      required: false

prism_q-0.21.1/.github/ISSUE_TEMPLATE/FEATURE-REQUEST.yml

@@ -0,0 +1,99 @@
+name: Feature request
+description: Propose a new capability, backend, gate, optimization, or developer workflow.
+title: "[Feature]: "
+labels: ["enhancement"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thanks for proposing an improvement. Ground the request in performance, correctness, and maintainability impact.
+
+  - type: textarea
+    id: summary
+    attributes:
+      label: Summary
+      description: Describe the requested feature and the problem it solves.
+      placeholder: "Example: Add a sparse state backend for circuits with limited basis support."
+    validations:
+      required: true
+
+  - type: dropdown
+    id: feature-type
+    attributes:
+      label: Feature category
+      description: Select the primary category.
+      options:
+        - Simulation backend
+        - Gate or circuit operation
+        - Performance optimization
+        - Parser or input format
+        - Benchmarking or profiling
+        - Developer tooling
+        - Documentation
+        - Other
+    validations:
+      required: true
+
+  - type: textarea
+    id: motivation
+    attributes:
+      label: Motivation
+      description: Explain the use case, target workload, or limitation in the current implementation.
+    validations:
+      required: true
+
+  - type: textarea
+    id: proposed-solution
+    attributes:
+      label: Proposed solution
+      description: Describe the desired behavior, API, backend contract, or workflow.
+    validations:
+      required: true
+
+  - type: textarea
+    id: alternatives
+    attributes:
+      label: Alternatives considered
+      description: List other approaches and why this proposal is preferred.
+    validations:
+      required: false
+
+  - type: textarea
+    id: performance-impact
+    attributes:
+      label: Performance impact
+      description: Describe expected throughput, latency, memory, allocation, or benchmark impact.
+      placeholder: |
+        - Affected benchmark or workload:
+        - Expected speedup or tradeoff:
+        - Measurement plan:
+    validations:
+      required: true
+
+  - type: textarea
+    id: correctness-impact
+    attributes:
+      label: Correctness and testing plan
+      description: List the tests, golden comparisons, seeds, or numerical tolerances needed.
+      placeholder: |
+        - Unit tests:
+        - Golden tests:
+        - Fixed RNG seed:
+    validations:
+      required: true
+
+  - type: textarea
+    id: docs-impact
+    attributes:
+      label: Documentation impact
+      description: Note public API docs, architecture documentation, or benchmark notes that need updates.
+    validations:
+      required: false
+
+  - type: textarea
+    id: additional-context
+    attributes:
+      label: Additional context
+      description: Add links, examples, related issues, or implementation notes.
+    validations:
+      required: false

prism_q-0.21.1/.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,69 @@
+<!--
+Review this template before deleting sections that do not apply. Keep the headings that
+match the PR so reviewers know what was considered and skipped.
+-->
+
+## Summary
+
+Describe what changed and why in two or three sentences. Focus on the motivation, not the
+diff. Link any related issue or discussion.
+
+## Scope
+
+- [ ] Bug fix
+- [ ] New feature
+- [ ] Performance improvement
+- [ ] Refactor or cleanup
+- [ ] Documentation
+- [ ] Build, CI, or tooling
+
+## Benchmarks (required for any change that touches a hot path)
+
+Run from a quiet machine with `--features parallel` and paste the numbers below. If this
+PR only changes documentation or non-performance code, write "N/A, no hot-path changes"
+and skip the table.
+
+| Benchmark | Before | After | Change | Within 5% threshold? |
+| --- | --- | --- | --- | --- |
+|  |  |  |  |  |
+
+Regression verdict: PASS / FAIL / WAIVER
+
+If WAIVER, explain why the regression is acceptable and what future work will recover it.
+
+## Correctness
+
+- [ ] `cargo test --all-features` passes locally
+- [ ] `cargo clippy --all-targets --all-features -- -D warnings -D clippy::undocumented_unsafe_blocks` passes
+- [ ] `cargo fmt --check` passes
+- [ ] `cargo doc --no-deps --all-features` passes
+- [ ] New public API has docstrings
+- [ ] New gate, backend, or fusion pass has golden tests against the statevector backend
+- [ ] GPU-affecting change runs `cargo test --features "parallel gpu" --test golden_gpu`
+
+## Hotspot notes
+
+If the change touches a hot path, list the functions affected and attach profiler or
+flamegraph output showing where time went. If no hot paths were touched, write "N/A".
+
+## Architecture or design changes
+
+- [ ] `docs/architecture/` updated if the change is structural
+- [ ] Design or research notes added where required for new subsystems
+
+## Breaking changes
+
+List any public API breakage, config format changes, or behavioral differences a user
+might hit after upgrading. Write "None" if there are none.
+
+## Risks and rollback
+
+Describe the blast radius if this lands and turns out wrong. Note any feature flags or
+dispatch guards that let the change be rolled back without reverting the commit.
+
+## Pre-merge checklist
+
+- [ ] Commit messages follow the style rules
+- [ ] No secrets, credentials, or local config added
+- [ ] No new dependencies without a rationale
+- [ ] CI is green

prism_q-0.21.1/.github/labeler.yml

@@ -0,0 +1,57 @@
+backend:
+  - changed-files:
+    - any-glob-to-any-file: 'src/backend/**/*'
+
+simd:
+  - changed-files:
+    - any-glob-to-any-file: 'src/backend/simd.rs'
+
+statevector:
+  - changed-files:
+    - any-glob-to-any-file: 'src/backend/statevector/**/*'
+
+stabilizer:
+  - changed-files:
+    - any-glob-to-any-file: 'src/backend/stabilizer.rs'
+
+mps:
+  - changed-files:
+    - any-glob-to-any-file: 'src/backend/mps.rs'
+
+parser:
+  - changed-files:
+    - any-glob-to-any-file: 'src/circuit/openqasm.rs'
+
+circuit:
+  - changed-files:
+    - any-glob-to-any-file: 'src/circuit/**/*'
+
+fusion:
+  - changed-files:
+    - any-glob-to-any-file: 'src/circuit/fusion.rs'
+
+gates:
+  - changed-files:
+    - any-glob-to-any-file: 'src/gates/**/*'
+
+sim:
+  - changed-files:
+    - any-glob-to-any-file: 'src/sim/**/*'
+
+benchmarks:
+  - changed-files:
+    - any-glob-to-any-file: 'benches/**/*'
+
+tests:
+  - changed-files:
+    - any-glob-to-any-file: 'tests/**/*'
+
+ci:
+  - changed-files:
+    - any-glob-to-any-file: '.github/**/*'
+
+docs:
+  - changed-files:
+    - any-glob-to-any-file:
+      - '**/*.md'
+      - 'LICENSE*'

prism_q-0.21.1/.github/workflows/ci.yml

@@ -0,0 +1,302 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+env:
+  CARGO_TERM_COLOR: always
+  # Features exercised on runners without CUDA. The `gpu` feature links against CUDA via
+  # cudarc's dynamic-linking mode and can't build on hosts that don't have the NVIDIA
+  # toolkit installed, so CI enumerates features instead of using --all-features.
+  CI_FEATURES: parallel,serialization
+  CI_BENCH_FEATURES: parallel,bench-fast
+  REGRESSION_THRESHOLD: ${{ vars.REGRESSION_THRESHOLD || '5.0' }}
+
+jobs:
+  check:
+    name: Lint & Test
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+      - uses: dtolnay/rust-toolchain@stable
+        with:
+          components: rustfmt, clippy
+      - uses: Swatinem/rust-cache@v2
+        with:
+          cache-bin: false
+      - uses: taiki-e/install-action@cargo-nextest
+
+      - name: Formatting
+        run: cargo fmt --all -- --check
+
+      - name: Clippy
+        run: cargo clippy --all-targets --features "$CI_FEATURES" -- -D warnings -D clippy::undocumented_unsafe_blocks
+
+      - name: Tests
+        run: cargo nextest run --features "$CI_FEATURES"
+
+      - name: Doc tests
+        run: cargo test --doc --features "$CI_FEATURES"
+
+      - name: Doc build
+        run: cargo doc --no-deps --features "$CI_FEATURES"
+        env:
+          RUSTDOCFLAGS: -D warnings
+
+  check-no-default-features:
+    name: Lint & Test (no default features)
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+      - uses: dtolnay/rust-toolchain@stable
+        with:
+          components: clippy
+      - uses: Swatinem/rust-cache@v2
+        with:
+          cache-bin: false
+      - uses: taiki-e/install-action@cargo-nextest
+
+      - name: Clippy
+        run: cargo clippy --all-targets --no-default-features -- -D warnings -D clippy::undocumented_unsafe_blocks
+
+      - name: Tests
+        run: cargo nextest run --no-default-features
+
+      - name: Doc tests
+        run: cargo test --doc --no-default-features
+
+  benchmark-regression:
+    name: Benchmark Regression
+    runs-on: ubuntu-latest
+    needs: check
+    if: github.event_name == 'pull_request'
+    timeout-minutes: 45
+    permissions:
+      contents: read
+    steps:
+      - name: Checkout base
+        uses: actions/checkout@v7
+        with:
+          ref: ${{ github.event.pull_request.base.sha }}
+          path: base
+          fetch-depth: 1
+
+      - name: Checkout head
+        uses: actions/checkout@v7
+        with:
+          repository: ${{ github.event.pull_request.head.repo.full_name }}
+          ref: ${{ github.event.pull_request.head.sha }}
+          path: head
+          fetch-depth: 1
+
+      - uses: dtolnay/rust-toolchain@stable
+
+      - uses: Swatinem/rust-cache@v2
+        with:
+          cache-bin: false
+          workspaces: |
+            base -> target
+            head -> target
+
+      - name: Install benchmark tools
+        run: sudo apt-get update && sudo apt-get install -y bc jq
+
+      - name: Benchmark base
+        working-directory: base
+        run: bash ../head/scripts/bench_ci.sh
+        env:
+          PRISM_BENCH_PROJECT_DIR: ${{ github.workspace }}/base
+
+      - name: Save base baseline
+        working-directory: base
+        run: bash scripts/bench_check.sh save --name ci-base
+
+      - name: Copy base baseline
+        run: |
+          mkdir -p head/bench_results/baselines
+          cp base/bench_results/baselines/ci-base.json head/bench_results/baselines/ci-base.json
+
+      - name: Benchmark head
+        working-directory: head
+        run: bash scripts/bench_ci.sh
+
+      - name: Compare benchmark results
+        working-directory: head
+        run: |
+          set +e
+          bash scripts/bench_check.sh table --baseline ci-base | tee ../benchmark-summary.md
+          table_status=${PIPESTATUS[0]}
+          bash scripts/bench_check.sh compare --baseline ci-base | tee ../benchmark-compare.txt
+          compare_status=${PIPESTATUS[0]}
+
+          {
+            echo "## Benchmark Regression Gate"
+            echo ""
+            cat ../benchmark-summary.md
+            echo ""
+            echo '```text'
+            cat ../benchmark-compare.txt
+            echo '```'
+          } >> "$GITHUB_STEP_SUMMARY"
+
+          if [[ "$table_status" -ne 0 ]]; then
+            exit "$table_status"
+          fi
+          exit "$compare_status"
+
+      - name: Upload benchmark artifacts
+        if: always()
+        uses: actions/upload-artifact@v7
+        with:
+          name: benchmark-regression
+          if-no-files-found: ignore
+          path: |
+            benchmark-summary.md
+            benchmark-compare.txt
+            base/bench_results/baselines/ci-base.json
+            head/bench_results/baselines/ci-base.json
+            head/target/criterion/**/benchmark.json
+            head/target/criterion/**/new/estimates.json
+
+  coverage:
+    name: Coverage
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+      - uses: dtolnay/rust-toolchain@stable
+        with:
+          components: llvm-tools-preview
+      - uses: Swatinem/rust-cache@v2
+        with:
+          cache-bin: false
+      - uses: taiki-e/install-action@cargo-llvm-cov
+      - name: Generate coverage
+        run: cargo llvm-cov --features "$CI_FEATURES" --lcov --output-path lcov.info
+      - name: Extract coverage percentage
+        id: cov
+        run: |
+          LF=$(grep '^LF:' lcov.info | awk -F: '{s+=$2} END {print s+0}')
+          LH=$(grep '^LH:' lcov.info | awk -F: '{s+=$2} END {print s+0}')
+          COVERAGE=$(awk "BEGIN {if ($LF>0) printf \"%.1f\", ($LH/$LF)*100; else print \"0\"}")
+          echo "percentage=$COVERAGE" >> "$GITHUB_OUTPUT"
+          echo "### Coverage: ${COVERAGE}%" >> "$GITHUB_STEP_SUMMARY"
+      - name: Update coverage badge
+        if: github.ref == 'refs/heads/main' && github.event_name == 'push'
+        uses: schneegans/dynamic-badges-action@v1.9.0
+        with:
+          auth: ${{ secrets.GIST_TOKEN }}
+          gistID: ${{ vars.COVERAGE_GIST_ID }}
+          filename: coverage.json
+          label: coverage
+          message: ${{ steps.cov.outputs.percentage }}%
+          valColorRange: ${{ steps.cov.outputs.percentage }}
+          minColorRange: 50
+          maxColorRange: 90
+
+  check-aarch64:
+    name: Cross-compile aarch64
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+      - uses: dtolnay/rust-toolchain@stable
+        with:
+          targets: aarch64-unknown-linux-gnu
+      - uses: Swatinem/rust-cache@v2
+        with:
+          cache-bin: false
+      - name: Install cross-compilation toolchain
+        run: sudo apt-get update && sudo apt-get install -y gcc-aarch64-linux-gnu
+      - name: Check (no default features)
+        run: cargo check --target aarch64-unknown-linux-gnu --no-default-features
+        env:
+          CARGO_TARGET_AARCH64_UNKNOWN_LINUX_GNU_LINKER: aarch64-linux-gnu-gcc
+      - name: Check (CI features)
+        run: cargo check --target aarch64-unknown-linux-gnu --features "$CI_FEATURES"
+        env:
+          CARGO_TARGET_AARCH64_UNKNOWN_LINUX_GNU_LINKER: aarch64-linux-gnu-gcc
+
+  # Execute the NEON fallbacks under emulation. check-aarch64 above only compiles,
+  # so without this the NEON kernels are never run against their scalar reference on
+  # Linux. Scoped to the SIMD-relevant tests to bound QEMU wall-clock.
+  test-aarch64-qemu:
+    name: Test aarch64 (QEMU)
+    runs-on: ubuntu-latest
+    timeout-minutes: 40
+    steps:
+      - uses: actions/checkout@v7
+      - uses: dtolnay/rust-toolchain@stable
+        with:
+          targets: aarch64-unknown-linux-gnu
+      - uses: Swatinem/rust-cache@v2
+        with:
+          cache-bin: false
+      - uses: taiki-e/install-action@v2
+        with:
+          tool: cross
+      - name: SIMD kernel unit tests (NEON vs scalar)
+        run: cross test --target aarch64-unknown-linux-gnu --features "$CI_FEATURES" --lib backend::simd::tests
+      - name: word_ops unit tests (NEON vs scalar)
+        run: cross test --target aarch64-unknown-linux-gnu --features "$CI_FEATURES" --lib backend::word_ops::tests
+      - name: Batched diagonal phase reference (NEON path)
+        run: cross test --target aarch64-unknown-linux-gnu --features "$CI_FEATURES" --lib backend::statevector::tests::batch_phase_matches_independent_reference
+      - name: Cross-backend correctness matrix
+        run: cross test --target aarch64-unknown-linux-gnu --features "$CI_FEATURES" --test backend_matrix
+
+  # Compile-check the GPU paths with the CUDA toolkit but no device. The job only
+  # compiles and runs the device-free KERNEL_NAMES test (nothing opens a device),
+  # enforcing the exhaustive GPU dispatch matches and the golden_gpu registry at
+  # compile time. Pinned to ubuntu-22.04: CUDA 12.4 (matching cudarc's cuda-12040
+  # bindings) has no package for the ubuntu2404 repo on ubuntu-latest.
+  gpu-check:
+    name: GPU compile-check (no device)
+    runs-on: ubuntu-22.04
+    steps:
+      - uses: actions/checkout@v7
+      - uses: Jimver/cuda-toolkit@v0.2.35
+        with:
+          cuda: '12.4.0'
+          method: network
+      - uses: dtolnay/rust-toolchain@stable
+        with:
+          components: clippy
+      - uses: Swatinem/rust-cache@v2
+        with:
+          cache-bin: false
+      - uses: taiki-e/install-action@cargo-nextest
+      - name: Compile-check GPU dispatch + golden_gpu coverage
+        run: cargo check --all-targets --features "parallel gpu"
+      - name: Clippy GPU paths
+        run: cargo clippy --all-targets --features "parallel gpu" -- -D warnings -D clippy::undocumented_unsafe_blocks
+      - name: KERNEL_NAMES consistency (device-free)
+        run: cargo nextest run --features "parallel gpu" -E 'test(kernel_names_match_source_entry_points)'
+
+  test-macos-arm:
+    name: Test macOS ARM64
+    runs-on: macos-latest
+    steps:
+      - uses: actions/checkout@v7
+      - uses: dtolnay/rust-toolchain@stable
+        with:
+          components: clippy
+      - uses: Swatinem/rust-cache@v2
+        with:
+          cache-bin: false
+      - uses: taiki-e/install-action@cargo-nextest
+      - name: Clippy
+        run: cargo clippy --all-targets --features "$CI_FEATURES" -- -D warnings -D clippy::undocumented_unsafe_blocks
+      - name: Tests
+        run: cargo nextest run --features "$CI_FEATURES"
+      - name: Doc tests
+        run: cargo test --doc --features "$CI_FEATURES"
+
+  security:
+    name: Security & Licenses
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+      - uses: EmbarkStudios/cargo-deny-action@v2
+        with:
+          command: check

prism_q-0.21.1/.github/workflows/docs.yml

@@ -0,0 +1,49 @@
+name: Docs
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - 'docs/**'
+      - '.github/workflows/docs.yml'
+  pull_request:
+    paths:
+      - 'docs/**'
+      - '.github/workflows/docs.yml'
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: pages
+  cancel-in-progress: true
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+      - uses: taiki-e/install-action@v2
+        with:
+          tool: mdbook@0.4.52
+      - name: Install mdBook preprocessors
+        run: cargo install --locked mdbook-admonish@1.20.0 mdbook-mermaid@0.14.0 mdbook-katex@0.9.4
+      - name: Build book
+        run: mdbook build docs
+      - uses: actions/upload-pages-artifact@v5
+        with:
+          path: docs/book
+
+  deploy:
+    needs: build
+    if: github.ref == 'refs/heads/main' && github.event_name != 'pull_request'
+    runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - id: deployment
+        uses: actions/deploy-pages@v5

prism_q-0.21.1/.github/workflows/label.yml

@@ -0,0 +1,12 @@
+name: Labeler
+on: [pull_request_target]
+
+jobs:
+  label:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      pull-requests: write
+
+    steps:
+    - uses: actions/labeler@v6