qslib-quantum 0.1.0__tar.gz

qslib_quantum-0.1.0/.gitattributes

@@ -0,0 +1,3 @@
+# Conformance fixtures are checksummed as exact UTF-8 bytes. Keep their
+# canonical LF representation independent of a contributor's platform.
+fixtures/conformance/v1/** text eol=lf

qslib_quantum-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,189 @@
+name: CI
+
+on:
+  push:
+  pull_request:
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+env:
+  CARGO_INCREMENTAL: "0"
+  CARGO_TERM_COLOR: always
+
+jobs:
+  test:
+    name: Test (${{ matrix.os }}, Rust ${{ matrix.rust }})
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, macos-latest, windows-latest]
+        rust: [stable, "1.85.0"]
+    runs-on: ${{ matrix.os }}
+    steps:
+      - name: Checkout
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        with:
+          persist-credentials: false
+      - name: Install Rust
+        run: rustup toolchain install ${{ matrix.rust }} --profile minimal
+      - name: Check Rust workspace (Python cdylib excluded)
+        run: cargo +${{ matrix.rust }} check --locked --workspace --exclude qslib-quantum-python --all-targets --all-features
+      - name: Test Rust workspace (Python cdylib excluded)
+        run: cargo +${{ matrix.rust }} test --locked --workspace --exclude qslib-quantum-python --all-targets --all-features
+
+  quality:
+    name: Formatting, lint, docs, and policy
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        with:
+          persist-credentials: false
+      - name: Install stable Rust
+        run: rustup toolchain install stable --profile minimal --component rustfmt,clippy
+      - name: Install MSRV Rust
+        run: rustup toolchain install 1.85.0 --profile minimal
+      - name: Check formatting
+        run: cargo +stable fmt --all --check
+      - name: Run Clippy with warnings denied (Python cdylib excluded)
+        run: cargo +stable clippy --locked --workspace --exclude qslib-quantum-python --all-targets --all-features -- -D warnings
+      - name: Build documentation with warnings denied
+        env:
+          RUSTDOCFLAGS: -D warnings
+        run: cargo +stable doc --locked --workspace --exclude qslib-quantum-python --no-deps --all-features
+      - name: Install mdBook
+        run: cargo +stable install mdbook --version 0.5.4 --locked
+      - name: Build combined Markdown and Rust API site
+        run: python3 tools/build_docs_site.py "$RUNNER_TEMP/qslib-site"
+      - name: Test neutral conformance harness
+        run: cargo +stable test --locked -p qslib-test-support --test conventions --test workspace
+      - name: Check Markdown links
+        run: python3 tools/check_markdown_links.py
+      - name: Test third-party distribution contracts
+        run: |
+          PYTHONPATH=tools python3 tools/test_distribution_contract.py
+          PYTHONPATH=tools python3 tools/test_package_cli_release.py
+      - name: Run bounded structured CLI fuzz smoke
+        run: cargo +stable test --locked -p qslib-quantum-cli --lib structured_config_fuzz_never_panics_during_resolution
+      - name: Install cargo-deny
+        run: cargo +stable install cargo-deny --version 0.20.2 --locked
+      - name: Check dependency policy
+        run: cargo +stable deny check advisories licenses sources
+      - name: Install independent artifact readers
+        run: python3 -m pip install --disable-pip-version-check pyarrow blake3
+      - name: Verify generated IO artifacts through Python
+        run: |
+          fixture="${{ runner.temp }}/qslib-io-fixture"
+          cargo +stable run --locked -p qslib-quantum-io --example io_artifacts -- "$fixture"
+          python3 tools/verify_io_artifacts.py --checkpoint "$fixture/checkpoint" --dataset "$fixture/dataset"
+      - name: Build and test the local Python wheel
+        env:
+          RUSTUP_TOOLCHAIN: 1.85.0
+        run: |
+          python3 -m pip install --disable-pip-version-check maturin pytest numpy
+          maturin build --locked --manifest-path crates/qslib-python/Cargo.toml --out "$RUNNER_TEMP/qslib-wheel"
+          python3 -m venv "$RUNNER_TEMP/qslib-venv"
+          "$RUNNER_TEMP/qslib-venv/bin/pip" install --disable-pip-version-check "$RUNNER_TEMP"/qslib-wheel/*.whl pytest numpy
+          "$RUNNER_TEMP/qslib-venv/bin/pytest" -q crates/qslib-python/tests/python_contract.py
+          "$RUNNER_TEMP/qslib-venv/bin/python" examples/python_exact_ground_state.py
+
+  python-wheels:
+    name: Python wheel (${{ matrix.os }}, Python ${{ matrix.python }})
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, macos-latest, windows-latest]
+        python: ["3.12", "3.13"]
+    runs-on: ${{ matrix.os }}
+    steps:
+      - name: Checkout
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        with:
+          persist-credentials: false
+      - name: Set up Python
+        uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 # v6.1.0
+        with:
+          python-version: ${{ matrix.python }}
+      - name: Install Rust
+        run: rustup toolchain install 1.85.0 --profile minimal
+      - name: Build ABI3 wheel
+        env:
+          RUSTUP_TOOLCHAIN: 1.85.0
+        run: |
+          python -m pip install --disable-pip-version-check maturin pytest numpy
+          maturin build --locked --manifest-path crates/qslib-python/Cargo.toml --out wheelhouse
+      - name: Install and exercise wheel
+        run: |
+          python -m pip install --disable-pip-version-check --find-links wheelhouse qslib-quantum pytest numpy
+          python -m pytest -q crates/qslib-python/tests/python_contract.py
+          python examples/python_exact_ground_state.py
+
+  features:
+    name: Facade feature boundaries
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        with:
+          persist-credentials: false
+      - name: Install stable Rust
+        run: rustup toolchain install stable --profile minimal
+      - name: Check core-only facade
+        run: cargo +stable check --locked -p qslib-quantum --no-default-features
+      - name: Check exact facade
+        run: cargo +stable check --locked -p qslib-quantum --no-default-features --features exact
+      - name: Check variational facade
+        run: cargo +stable check --locked -p qslib-quantum --no-default-features --features variational
+      - name: Check SSE facade
+        run: cargo +stable check --locked -p qslib-quantum --no-default-features --features sse
+      - name: Check IO facade
+        run: cargo +stable check --locked -p qslib-quantum --no-default-features --features io
+      - name: Check full Rust facade
+        run: cargo +stable check --locked -p qslib-quantum --no-default-features --features full
+      - name: Audit workspace graph and feature metadata
+        run: cargo +stable test --locked -p qslib-test-support --test workspace
+
+  fuzz-state-conversion:
+    name: Bounded state-conversion fuzz
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        with:
+          persist-credentials: false
+      - name: Install stable Rust
+        run: rustup toolchain install stable --profile minimal
+      - name: Install cargo-fuzz
+        run: cargo +stable install cargo-fuzz --version 0.13.2 --locked
+      - name: Run bounded state-conversion fuzz target
+        run: cargo fuzz run state_conversion --sanitizer none -- -runs=1000
+
+  coverage:
+    name: Branch coverage
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        with:
+          persist-credentials: false
+      - name: Install nightly coverage toolchain
+        run: rustup toolchain install nightly --profile minimal --component llvm-tools-preview --component rust-src
+      - name: Install cargo-llvm-cov
+        run: cargo +stable install cargo-llvm-cov --version 0.6.21 --locked
+      - name: Run branch-enabled workspace coverage (Python cdylib excluded)
+        run: cargo +nightly llvm-cov --locked --workspace --exclude qslib-quantum-python --all-features --branch --summary-only
+
+  miri-core:
+    name: Miri core safety checks
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        with:
+          persist-credentials: false
+      - name: Install nightly Miri
+        run: rustup toolchain install nightly --profile minimal --component miri --component rust-src
+      - name: Run core tests under Miri
+        run: cargo +nightly miri test --locked -p qslib-quantum-core --all-targets

qslib_quantum-0.1.0/.github/workflows/docs.yml

@@ -0,0 +1,55 @@
+name: Documentation site
+
+on:
+  push:
+    branches:
+      - main
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: pages
+  cancel-in-progress: false
+
+env:
+  CARGO_INCREMENTAL: "0"
+  CARGO_TERM_COLOR: always
+
+jobs:
+  build:
+    name: Build combined documentation site
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        with:
+          persist-credentials: false
+      - name: Install stable Rust
+        run: rustup toolchain install stable --profile minimal
+      - name: Install pinned mdBook
+        run: cargo +stable install mdbook --version 0.5.4 --locked
+      - name: Build the combined Markdown and Rust API site
+        run: python3 tools/build_docs_site.py "$RUNNER_TEMP/qslib-site"
+      - name: Upload Pages artifact
+        uses: actions/upload-pages-artifact@fc324d3547104276b827a68afc52ff2a11cc49c9 # v5.0.0
+        with:
+          path: ${{ runner.temp }}/qslib-site
+
+  deploy:
+    name: Deploy to GitHub Pages
+    needs: build
+    runs-on: ubuntu-latest
+    permissions:
+      pages: write
+      id-token: write
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - name: Configure GitHub Pages
+        uses: actions/configure-pages@983d7736d9b0ae728b81ab479565c72886d7745b # v5.0.0
+      - name: Deploy the built site
+        id: deployment
+        uses: actions/deploy-pages@cd2ce8fcbc39b97be8ca5fce6e763baed58fa128 # v5.0.0

qslib_quantum-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,223 @@
+name: Release preparation
+
+on:
+  push:
+    tags:
+      - "v*"
+  workflow_dispatch:
+    inputs:
+      publish:
+        description: Create the GitHub release for this checked-out version
+        required: true
+        default: false
+        type: boolean
+      publish_pypi:
+        description: Publish Python wheel and source distributions to PyPI
+        required: true
+        default: false
+        type: boolean
+      publish_crates:
+        description: Publish the Rust workspace crates to crates.io
+        required: true
+        default: false
+        type: boolean
+
+permissions:
+  contents: read
+
+env:
+  CARGO_INCREMENTAL: "0"
+  CARGO_TERM_COLOR: always
+
+jobs:
+  prepare:
+    name: Build publication artifacts
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout full repository history
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        with:
+          fetch-depth: 0
+          persist-credentials: false
+      - name: Install stable Rust
+        run: rustup toolchain install stable --profile minimal
+      - name: Install MSRV Rust
+        run: rustup toolchain install 1.85.0 --profile minimal
+      - name: Set up Python
+        uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 # v6.1.0
+        with:
+          python-version: "3.12"
+      - name: Build and verify release artifacts
+        shell: bash
+        run: |
+          set -euo pipefail
+          version="$(cargo +stable metadata --locked --no-deps --format-version 1 | python3 -c 'import json, sys; packages=json.load(sys.stdin)["packages"]; print(next(p["version"] for p in packages if p["name"] == "qslib-quantum"))')"
+          if [[ "$GITHUB_REF_TYPE" == "tag" && "$GITHUB_REF_NAME" != "v$version" ]]; then
+            echo "tag $GITHUB_REF_NAME does not match workspace version v$version" >&2
+            exit 1
+          fi
+          rm -rf dist
+          cargo +stable package --locked -p qslib-quantum-core
+          mkdir -p dist/bin dist/rust-source dist/wheels
+          python3 tools/test_distribution_contract.py
+          python3 tools/test_package_cli_release.py
+          cargo +stable test --locked --workspace --exclude qslib-quantum-python --all-targets --all-features
+          cargo +stable build --locked --release -p qslib-quantum-cli
+          cp target/release/qslib dist/bin/qslib
+          cp target/package/qslib-quantum-core-*.crate dist/rust-source/
+          git archive --format=tar.gz --prefix="qslib-$version/" HEAD > "dist/rust-source/qslib-$version-source.tar.gz"
+          python3 -m pip install --disable-pip-version-check maturin pytest numpy
+          RUSTUP_TOOLCHAIN=1.85.0 maturin build --locked --manifest-path crates/qslib-python/Cargo.toml --out dist/wheels
+          RUSTUP_TOOLCHAIN=1.85.0 maturin sdist --manifest-path crates/qslib-python/Cargo.toml --out dist/wheels
+          python3 -m venv "$RUNNER_TEMP/qslib-wheel-venv"
+          "$RUNNER_TEMP/qslib-wheel-venv/bin/pip" install --disable-pip-version-check \
+            dist/wheels/*.whl pytest numpy
+          "$RUNNER_TEMP/qslib-wheel-venv/bin/pytest" -q crates/qslib-python/tests/python_contract.py
+          "$RUNNER_TEMP/qslib-wheel-venv/bin/python" examples/python_exact_ground_state.py
+          python3 -m venv "$RUNNER_TEMP/qslib-sdist-venv"
+          "$RUNNER_TEMP/qslib-sdist-venv/bin/pip" install --disable-pip-version-check \
+            dist/wheels/*.tar.gz pytest numpy
+          "$RUNNER_TEMP/qslib-sdist-venv/bin/pytest" -q crates/qslib-python/tests/python_contract.py
+          "$RUNNER_TEMP/qslib-sdist-venv/bin/python" examples/python_exact_ground_state.py
+          dist/bin/qslib --help
+          cargo +stable install mdbook --version 0.5.4 --locked
+          python3 tools/build_docs_site.py dist/qslib-site
+          cp README.md LICENSE dist/
+          cp docs/release-evidence.md dist/
+          tar -C dist -czf "dist/qslib-$version-artifacts.tar.gz" \
+            bin rust-source wheels qslib-site LICENSE README.md release-evidence.md
+          printf 'qslib version: %s\ncommit: %s\n' "$version" "$(git rev-parse HEAD)" > dist/BUILD_METADATA.txt
+          (cd dist && find . -type f ! -name SHA256SUMS -print0 | sort -z | xargs -0 shasum -a 256 > SHA256SUMS)
+          (cd dist && shasum -a 256 -c SHA256SUMS)
+      - name: Upload release candidate for review
+        uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4.6.2
+        with:
+          name: qslib-release-${{ github.run_id }}
+          path: dist
+          if-no-files-found: error
+
+  cli-binaries:
+    name: CLI archive (${{ matrix.platform }})
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - os: ubuntu-latest
+            platform: linux-x86_64
+            binary: target/release/qslib
+          - os: macos-latest
+            platform: macos
+            binary: target/release/qslib
+          - os: windows-latest
+            platform: windows-x86_64
+            binary: target/release/qslib.exe
+    runs-on: ${{ matrix.os }}
+    steps:
+      - name: Checkout full repository history
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        with:
+          fetch-depth: 0
+          persist-credentials: false
+      - name: Install stable Rust
+        run: rustup toolchain install stable --profile minimal
+      - name: Build optimized CLI
+        run: cargo +stable build --locked --release -p qslib-quantum-cli
+      - name: Package CLI archive
+        shell: bash
+        run: |
+          set -euo pipefail
+          version="$(cargo +stable metadata --locked --no-deps --format-version 1 | python3 -c 'import json, sys; packages=json.load(sys.stdin)["packages"]; print(next(p["version"] for p in packages if p["name"] == "qslib-quantum"))')"
+          python3 tools/package_cli_release.py \
+            --binary "${{ matrix.binary }}" \
+            --version "$version" \
+            --platform "${{ matrix.platform }}" \
+            --output dist/cli
+      - name: Upload CLI archive
+        uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4.6.2
+        with:
+          name: qslib-cli-${{ matrix.platform }}-${{ github.run_id }}
+          path: dist/cli/*
+          if-no-files-found: error
+
+  publish:
+    name: Create GitHub release (manual)
+    needs: [prepare, cli-binaries]
+    if: ${{ github.event_name == 'workflow_dispatch' && inputs.publish && startsWith(github.ref, 'refs/tags/v') }}
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - name: Checkout tag history for gh verification
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        with:
+          fetch-depth: 0
+          persist-credentials: false
+      - name: Download reviewed release candidate
+        uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093 # v4.3.0
+        with:
+          name: qslib-release-${{ github.run_id }}
+          path: dist
+      - name: Download reviewed CLI archives
+        uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093 # v4.3.0
+        with:
+          pattern: qslib-cli-*-${{ github.run_id }}
+          path: dist/cli
+          merge-multiple: true
+      - name: Create GitHub release from the checked-out tag
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: gh release create "$GITHUB_REF_NAME" dist/qslib-*-artifacts.tar.gz dist/SHA256SUMS dist/BUILD_METADATA.txt dist/cli/* --verify-tag --generate-notes
+
+  publish-crates:
+    name: Publish Rust crates (manual)
+    needs: prepare
+    if: ${{ github.event_name == 'workflow_dispatch' && inputs.publish_crates && startsWith(github.ref, 'refs/tags/v') }}
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout the release tag
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        with:
+          persist-credentials: false
+      - name: Install stable Rust
+        run: rustup toolchain install stable --profile minimal
+      - name: Publish crates in dependency order
+        env:
+          CARGO_REGISTRY_TOKEN: ${{ secrets.CARGO_REGISTRY_TOKEN }}
+        run: |
+          set -euo pipefail
+          if [[ -z "$CARGO_REGISTRY_TOKEN" ]]; then
+            echo "the CARGO_REGISTRY_TOKEN repository secret is not configured" >&2
+            exit 1
+          fi
+          for package in \
+            qslib-quantum-core \
+            qslib-quantum-exact \
+            qslib-quantum-io \
+            qslib-quantum-sse \
+            qslib-quantum-variational \
+            qslib-quantum \
+            qslib-quantum-cli; do
+            cargo +stable publish --locked -p "$package"
+          done
+
+  publish-pypi:
+    name: Publish Python distributions (manual)
+    needs: prepare
+    if: ${{ github.event_name == 'workflow_dispatch' && inputs.publish_pypi && startsWith(github.ref, 'refs/tags/v') }}
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/qslib-quantum
+    permissions:
+      id-token: write
+    steps:
+      - name: Download reviewed release candidate
+        uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093 # v4.3.0
+        with:
+          name: qslib-release-${{ github.run_id }}
+          path: dist
+      - name: Publish Python distributions with trusted publishing
+        uses: pypa/gh-action-pypi-publish@ba38be9e461d3875417946c167d0b5f3d385a247 # release/v1
+        with:
+          packages-dir: dist/wheels/
+          skip-existing: true

qslib_quantum-0.1.0/.gitignore

@@ -0,0 +1,48 @@
+
+# Generated by Cargo
+# will have compiled files and executables
+debug
+target
+
+# These are backup files generated by rustfmt
+**/*.rs.bk
+
+# MSVC Windows builds of rustc generate these, which store debugging information
+*.pdb
+
+# Generated by cargo mutants
+# Contains mutation testing data
+**/mutants.out*/
+
+# RustRover
+#  JetBrains specific template is maintained in a separate JetBrains.gitignore that can
+#  be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
+#  and can be added to the global gitignore or merged into this file.  For a more nuclear
+#  option (not recommended) you can uncomment the following to ignore the entire idea folder.
+#.idea/
+
+AGENTS.md
+PLANS.md
+SECURITY.md
+.agents/
+.codex/
+docs/plans
+docs/governance/target/
+
+/target/
+/fuzz/target/
+
+# Local-only agent, governance, and planning metadata.
+.DS_Store
+.agents/
+.codex/
+docs/governance/
+docs/plans
+AGENTS.md
+SECURITY.md
+PLANS.md
+CONTRIBUTING.md
+__pycache__/
+*.pyc
+CHANGELOG.md
+RELEASE_NOTES.md