stochmat 1.0.0__tar.gz

stochmat-1.0.0/.github/workflows/_wheels.yml

@@ -0,0 +1,112 @@
+# Reusable workflow that builds wheels (cibuildwheel matrix) and an sdist.
+#
+# Called by:
+#   * release.yml      -- on tag push, then publishes to PyPI
+#   * test_release.yml -- on workflow_dispatch, then publishes to TestPyPI
+#
+# Artifacts uploaded:
+#   * cibw-wheels-<os>-<arch>   (one per matrix cell)
+#   * cibw-sdist                (single tarball)
+# Callers re-download with actions/download-artifact and a "cibw-*" pattern.
+
+name: Build wheels (reusable)
+
+on:
+  workflow_call:
+    inputs:
+      strip-local-version:
+        description: >-
+          When true, build wheels and the sdist with
+          ``SETUPTOOLS_SCM_LOCAL_SCHEME=no-local-version`` so the
+          ``+gSHA`` local version segment is omitted. Required for
+          uploads to TestPyPI (which rejects PEP 440 local versions per
+          packaging.python.org); the default ``false`` keeps the SHA so
+          local dev installs and PyPI releases (which are tagged anyway,
+          so have no local segment) are unaffected.
+        type: boolean
+        required: false
+        default: false
+
+jobs:
+  build_wheels:
+    name: wheels ${{ matrix.os }} ${{ matrix.arch }}
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          # Linux
+          - os: ubuntu-latest
+            arch: x86_64
+          - os: ubuntu-latest
+            arch: aarch64
+          # macOS: macos-15-intel = Intel runner, macos-14 = Apple Silicon.
+          # Pinning by runner image (rather than cross-compiling from one)
+          # gives native test execution and avoids ARCHFLAGS hacks. The
+          # legacy ``macos-13`` label was deprecated by GitHub; jobs that
+          # request it queue indefinitely.
+          - os: macos-15-intel
+            arch: x86_64
+          - os: macos-14
+            arch: arm64
+          # Windows
+          - os: windows-latest
+            arch: AMD64
+
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          # setuptools_scm needs the full history (or at least tags) to
+          # resolve the version dynamically.
+          fetch-depth: 0
+
+      # QEMU is only needed for cross-arch Linux builds (aarch64 on x86 host).
+      - name: Set up QEMU
+        if: matrix.os == 'ubuntu-latest' && matrix.arch == 'aarch64'
+        uses: docker/setup-qemu-action@v3
+        with:
+          platforms: arm64
+
+      # Strip the setuptools_scm ``+gSHA`` local segment when the caller
+      # asks for it (TestPyPI uploads). Writing to ``$GITHUB_ENV`` makes
+      # the var visible to subsequent steps; ``CIBW_ENVIRONMENT_PASS_LINUX``
+      # is what cibuildwheel uses to forward host env vars across the
+      # manylinux container boundary on Linux runners (no-op on macOS /
+      # Windows where the build runs natively and inherits env directly).
+      - name: Configure local-version stripping
+        if: inputs.strip-local-version
+        shell: bash
+        run: |
+          echo "SETUPTOOLS_SCM_LOCAL_SCHEME=no-local-version" >> "$GITHUB_ENV"
+          echo "CIBW_ENVIRONMENT_PASS_LINUX=SETUPTOOLS_SCM_LOCAL_SCHEME" >> "$GITHUB_ENV"
+
+      - name: Build wheels
+        uses: pypa/cibuildwheel@v2.21
+        env:
+          CIBW_ARCHS: ${{ matrix.arch }}
+
+      - uses: actions/upload-artifact@v4
+        with:
+          name: cibw-wheels-${{ matrix.os }}-${{ matrix.arch }}
+          path: ./wheelhouse/*.whl
+
+  build_sdist:
+    name: sdist
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Build sdist
+        env:
+          # See ``Configure local-version stripping`` in build_wheels;
+          # sdist is built directly on the runner so plain step-level
+          # env is enough (no container boundary to cross).
+          SETUPTOOLS_SCM_LOCAL_SCHEME: ${{ inputs.strip-local-version && 'no-local-version' || '' }}
+        run: pipx run build --sdist
+
+      - uses: actions/upload-artifact@v4
+        with:
+          name: cibw-sdist
+          path: dist/*.tar.gz

stochmat-1.0.0/.github/workflows/development.yml

@@ -0,0 +1,298 @@
+name: Development Workflow
+
+on:
+  pull_request:
+    types: [opened, synchronize, reopened, edited, ready_for_review]
+    branches:
+      - main
+permissions:
+  pull-requests: write
+  contents: write
+
+jobs:
+  determine-python-version:
+    runs-on: ubuntu-latest
+    outputs:
+      version: ${{ steps.pyver.outputs.version }}
+    steps:
+      - uses: actions/checkout@v5
+
+      - name: Determine minimum Python version from pyproject.toml
+        id: pyver
+        run: |
+          py_req=$(sed -n 's/^[[:space:]]*requires-python[[:space:]]*=[[:space:]]*"\(.*\)".*/\1/p' pyproject.toml | head -n1)
+          py_min=$(echo "$py_req" | sed -n 's/.*>=[[:space:]]*\([0-9]\+\.[0-9]\+\).*/\1/p')
+          if [ -z "$py_min" ]; then
+            echo "Could not parse minimum Python version from requires-python='$py_req'" >&2
+            exit 1
+          fi
+          echo "version=$py_min" >> "$GITHUB_OUTPUT"
+          echo "Resolved minimum Python: $py_min"
+
+  setup-and-test:
+    if: github.event.pull_request.draft == false
+    runs-on: ubuntu-latest
+    needs: [determine-python-version]
+    steps:
+      - uses: actions/checkout@v5
+
+      - name: Set up Python ${{ needs.determine-python-version.outputs.version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ needs.determine-python-version.outputs.version }}
+
+      - name: Install Intel MKL
+        run: |
+          sudo apt-get update
+          sudo apt-get -y install intel-mkl
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+          cache-dependency-glob: "pyproject.toml"
+
+      - name: Set up Python
+        run: uv python install ${{ needs.determine-python-version.outputs.version }}
+
+      - name: Sync dependencies
+        # Synchronizes base, mkl extra, and dev groups (testing-mkl/docs).
+        # ``--all-extras`` covers [mkl]; ``--all-groups`` pulls
+        # ``testing-mkl`` (which itself includes ``testing``).
+        run: uv sync --all-extras --all-groups
+
+      - name: Build wheel
+        run: uv build
+
+      - name: Upload wheel
+        uses: actions/upload-artifact@v4
+        with: 
+          name: wheel
+          path: dist
+          retention-days: 1
+
+      - name: Lint with ruff
+        run: uv run ruff check --select=ALL --output-format=github src/
+        continue-on-error: true
+
+      - name: Tests without memory tracking
+        # Exclude memory tests (handled by ``test-memory``) and benchmark
+        # tests (handled by ``mkl-benchmarks``). Parity tests stay in.
+        run: |
+          uv run pytest --junitxml=junit/test-results.xml --cov=stochmat --durations=0 -k 'not _memory' -m 'not benchmark'
+        env:
+          COVERAGE_FILE: ".coverage.no_memory"
+
+      - name: Store coverage file
+        if: always()
+        uses: actions/upload-artifact@v4
+        with:
+          name: coverage-no_memory
+          path: .coverage.no_memory
+          include-hidden-files: true
+
+  test-memory:
+    if: github.event.pull_request.draft == false
+    runs-on: ubuntu-latest
+    needs: [determine-python-version]
+    steps:
+      - uses: actions/checkout@v5
+
+      - name: Set up Python ${{ needs.determine-python-version.outputs.version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ needs.determine-python-version.outputs.version }}
+
+      - name: Install Intel MKL
+        run: |
+          sudo apt-get update
+          sudo apt-get -y install intel-mkl
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+          cache-dependency-glob: "pyproject.toml"
+
+      - name: Set up Python
+        run: uv python install ${{ needs.determine-python-version.outputs.version }}
+
+      - name: Tests with memory tracking
+        # Re-syncing is optimized by uv's global cache. Exclude
+        # ``benchmark``-marked tests; they are handled by the dedicated
+        # ``mkl-benchmarks`` job.
+        run: |
+          uv sync --all-extras --all-groups
+          uv run pytest --junitxml=junit/test-results.xml --cov=stochmat --durations=0 --memray --most-allocations=0 -k '_memory' -m 'not benchmark'
+        env:
+          COVERAGE_FILE: ".coverage.memory"
+
+      - name: Store coverage file
+        if: always()
+        uses: actions/upload-artifact@v4
+        with:
+          name: coverage-memory
+          path: .coverage.memory
+          include-hidden-files: true
+
+  test-pure-python:
+    if: github.event.pull_request.draft == false
+    runs-on: ubuntu-latest
+    needs: [determine-python-version]
+    env:
+      # Disable building the Cython extensions; the package falls back to the
+      # pure-Python implementations in ``_cython_subst`` and ``fast_subst``.
+      STOCHMAT_BUILD_EXTENSIONS: "0"
+      UV_NO_SYNC: "1"  # prevent from fetching dev group
+    steps:
+      - uses: actions/checkout@v5
+
+      - name: Set up Python ${{ needs.determine-python-version.outputs.version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ needs.determine-python-version.outputs.version }}
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+          cache-dependency-glob: "pyproject.toml"
+
+      - name: Set up Python
+        run: uv python install ${{ needs.determine-python-version.outputs.version }}
+
+      - name: Sync dependencies (no Cython extensions, no MKL)
+        # MKL extra is intentionally omitted: the pure-Python build must
+        # not require system MKL or the optional ``sparse_dot_mkl``
+        # package -- the runtime fail-fast in
+        # ``stochmat.sparse_stoch_mat`` would otherwise raise
+        # ``ImportError`` because no MKL libs are installed on this job.
+        # Use the ``testing`` group explicitly (NOT ``testing-mkl``).
+        run: uv sync --no-default-groups --group testing
+
+      - name: Verify compiled extensions are absent
+        run: |
+          uv run python -c "
+          import importlib, sys
+          for mod in ('stochmat._cython_sparse_stoch', 'stochmat.fast'):
+              try:
+                  m = importlib.import_module(mod)
+              except ImportError:
+                  print(f'{mod}: not importable (expected for fast/_cython_sparse_stoch C-extension)')
+                  continue
+              # ``stochmat.fast`` is rebound to the pure-Python fallback when
+              # the compiled extension is missing; check for that.
+              if getattr(m, '__file__', '').endswith('.py'):
+                  print(f'{mod}: pure-Python fallback active ({m.__file__})')
+              else:
+                  print(f'{mod}: compiled extension loaded ({m.__file__})', file=sys.stderr)
+                  sys.exit(1)
+          import stochmat
+          assert not stochmat.backends.fast, 'stochmat.backends.fast should be False without compiled fast extension'
+          print('stochmat.backends.summary() =', stochmat.backends.summary())
+          "
+
+      - name: Tests (pure-Python, parity tests excluded)
+        # Parity tests require both the compiled and the fallback modules to
+        # be importable; tests that depend on the ``fast_modules`` fixture
+        # (e.g. ``test_fast_fallback.py``) auto-skip via the importorskip
+        # guard inside that fixture. Memory tests are handled by the
+        # dedicated ``test-memory`` job; benchmark tests by
+        # ``mkl-benchmarks``.
+        run: |
+          uv run pytest \
+            --junitxml=junit/test-results.xml \
+            --cov=stochmat \
+            --durations=0 \
+            -k 'not parity and not _memory' \
+            -m 'not benchmark'
+        env:
+          COVERAGE_FILE: ".coverage.pure_python"
+
+      - name: Store coverage file
+        if: always()
+        uses: actions/upload-artifact@v4
+        with:
+          name: coverage-pure_python
+          path: .coverage.pure_python
+          include-hidden-files: true
+
+  mkl-benchmarks:
+    # MKL speed/memory parity benchmarks. Non-blocking: this job uploads
+    # benchmark JSON + per-test report sections as artifacts but its
+    # outcome does not gate the PR (continue-on-error: true).
+    if: github.event.pull_request.draft == false
+    runs-on: ubuntu-latest
+    needs: [determine-python-version]
+    continue-on-error: true
+    steps:
+      - uses: actions/checkout@v5
+
+      - name: Set up Python ${{ needs.determine-python-version.outputs.version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ needs.determine-python-version.outputs.version }}
+
+      - name: Install Intel MKL
+        run: |
+          sudo apt-get update
+          sudo apt-get -y install intel-mkl
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+          cache-dependency-glob: "pyproject.toml"
+
+      - name: Set up Python
+        run: uv python install ${{ needs.determine-python-version.outputs.version }}
+
+      - name: Sync dependencies (testing-mkl group, includes pytest-benchmark)
+        run: uv sync --all-extras --all-groups
+
+      - name: Run MKL benchmark + memory parity tests
+        run: |
+          uv run pytest \
+            -m benchmark \
+            --benchmark-json=benchmark.json \
+            --durations=0 \
+            -v
+        # Test-internal asserts (2x speed backstop, 2.5x memory backstop)
+        # may legitimately fail on noisy CI runners; surface those without
+        # failing the PR.
+
+      - name: Upload benchmark results
+        if: always()
+        uses: actions/upload-artifact@v4
+        with:
+          name: mkl-benchmark-results
+          path: benchmark.json
+          if-no-files-found: warn
+
+  coverage:
+    name: combine-coverage
+    runs-on: ubuntu-24.04
+    needs: [setup-and-test, test-memory, test-pure-python]
+    if: always() && github.event.pull_request.draft == false
+    permissions:
+      pull-requests: write
+      contents: write
+    steps:
+      - uses: actions/checkout@v5
+      - uses: actions/download-artifact@v4
+        with:
+          pattern: coverage-*
+          merge-multiple: true
+      - name: Coverage comment
+        id: coverage_comment
+        uses: py-cov-action/python-coverage-comment-action@v3
+        with:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          MERGE_COVERAGE_FILES: true
+
+      - name: Store Pull Request comment
+        uses: actions/upload-artifact@v4
+        if: steps.coverage_comment.outputs.COMMENT_FILE_WRITTEN == 'true'
+        with:
+          name: python-coverage-comment-action
+          path: python-coverage-comment-action.txt

stochmat-1.0.0/.github/workflows/release.yml

@@ -0,0 +1,92 @@
+# Release workflow: builds wheels + sdist for a SemVer tag, creates a GitHub
+# Release with auto-generated notes, and publishes to PyPI via OIDC trusted
+# publishing. The PyPI publish step is gated on the ``pypi`` GitHub
+# environment, which is configured (in repo settings) to require manual
+# reviewer approval.
+#
+# Tag conventions (no ``v`` prefix; SemVer-style):
+#   1.2.3            -- final release
+#   1.2.3-rc1        -- pre-releases (alpha / beta / rc; PEP 440 normalises
+#                       ``1.2.3-rc1`` to ``1.2.3rc1`` for the wheel version)
+#
+# Prerequisites (configured outside this workflow):
+#   * PyPI trusted publisher: workflow=release.yml, environment=pypi
+#   * GitHub environment ``pypi`` with required reviewers
+#   * Tag protection rule for the patterns below
+
+name: Release
+
+on:
+  push:
+    tags:
+      - '[0-9]+.[0-9]+.[0-9]+'
+      - '[0-9]+.[0-9]+.[0-9]+-[abr]*'
+
+permissions:
+  contents: read
+
+jobs:
+  guard_main:
+    # Refuse to release from a tag that does not point at a commit on main.
+    # Prevents accidental releases from feature branches or stale tags.
+    name: Verify tag is on main
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - name: Check tag commit is an ancestor of origin/main
+        run: |
+          git fetch origin main
+          if ! git merge-base --is-ancestor "$GITHUB_SHA" origin/main; then
+            echo "::error::Tag commit $GITHUB_SHA is not on origin/main; refusing to release."
+            exit 1
+          fi
+
+  build:
+    name: Build artifacts
+    needs: guard_main
+    uses: ./.github/workflows/_wheels.yml
+
+  create_github_release:
+    name: Create GitHub Release
+    needs: build
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          pattern: cibw-*
+          path: dist
+          merge-multiple: true
+
+      - name: Create release
+        uses: softprops/action-gh-release@v2
+        with:
+          generate_release_notes: true
+          files: dist/*
+          # Mark pre-releases (anything with a/b/rc/post in the tag)
+          # appropriately so PyPI/users see the right channel.
+          prerelease: ${{ contains(github.ref_name, 'a') || contains(github.ref_name, 'b') || contains(github.ref_name, 'rc') }}
+
+  publish_pypi:
+    name: Publish to PyPI
+    needs: create_github_release
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/stochmat
+    permissions:
+      id-token: write       # OIDC for trusted publishing
+      attestations: write   # sigstore provenance attestations
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          pattern: cibw-*
+          path: dist
+          merge-multiple: true
+
+      - uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          attestations: true

stochmat-1.0.0/.github/workflows/report_coverage.yml

@@ -0,0 +1,29 @@
+name: Post coverage comment
+
+on:
+  workflow_run:
+    workflows: ["Development Workflow"]
+    types:
+      - completed
+
+jobs:
+  test:
+    name: Run tests & display coverage
+    runs-on: ubuntu-24.04
+    # if: github.event.workflow_run.event == 'pull_request' && github.event.workflow_run.conclusion == 'success'
+    if: github.event.workflow_run.event == 'pull_request'
+    permissions:
+      pull-requests: write
+      contents: write
+      actions: read
+    steps:
+      # DO NOT run actions/checkout here, for security reasons
+      # For details, refer to https://securitylab.github.com/research/github-actions-preventing-pwn-requests/
+      - name: Post comment
+        uses: py-cov-action/python-coverage-comment-action@v3
+        with:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          GITHUB_PR_RUN_ID: ${{ github.event.workflow_run.id }}
+          # Update those if you changed the default values:
+          # COMMENT_ARTIFACT_NAME: python-coverage-comment-action
+          # COMMENT_FILENAME: python-coverage-comment-action.txt

stochmat-1.0.0/.github/workflows/status.yml

@@ -0,0 +1,129 @@
+name: Status
+
+on:
+  push:
+    branches:
+      - main
+
+jobs:
+  determine-python-version:
+    runs-on: ubuntu-latest
+    outputs:
+      min-version: ${{ steps.pyver.outputs.version }}
+    steps:
+      - uses: actions/checkout@v5
+
+      - name: Determine minimum Python version from pyproject.toml
+        id: pyver
+        run: |
+          py_req=$(sed -n 's/^[[:space:]]*requires-python[[:space:]]*=[[:space:]]*"\(.*\)".*/\1/p' pyproject.toml | head -n1)
+          py_min=$(echo "$py_req" | sed -n 's/.*>=[[:space:]]*\([0-9]\+\.[0-9]\+\).*/\1/p')
+          if [ -z "$py_min" ]; then
+            echo "Could not parse minimum Python version from requires-python='$py_req'" >&2
+            exit 1
+          fi
+          echo "version=$py_min" >> "$GITHUB_OUTPUT"
+          echo "Resolved minimum Python: $py_min"
+
+  unit-tests:
+    runs-on: ubuntu-24.04
+    needs: [determine-python-version]
+    strategy:
+      matrix:
+        pythonV: ["3.10", "3.11", "3.12", "3.13", "3.14"]
+      fail-fast: false
+    steps:
+      - uses: actions/checkout@v5
+        with:
+          lfs: 'true'
+          submodules: recursive
+
+      - name: Set up Python ${{ matrix.pythonV }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.pythonV }}
+
+      - name: Install Intel MKL
+        run: |
+          sudo apt-get update
+          sudo apt-get -y install intel-mkl
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+          cache-dependency-glob: "pyproject.toml"
+
+      - name: Set up Python
+        run: uv python install ${{ matrix.pythonV }}
+
+      - name: Sync dependencies
+        # Synchronizes base, mkl extra, and dev groups (testing/docs)
+        run: uv sync --all-extras --all-groups
+
+      - name: Lint with ruff
+        run: uv run ruff check --select=ALL --output-format=github src/
+        continue-on-error: true
+
+      - name: Tests without memory tracking
+        run: |
+          uv run pytest --junitxml=junit/test-results.xml --cov=stochmat --durations=0 -k 'not _memory'
+        env:
+          COVERAGE_FILE: ".coverage.no_memory"
+
+      - name: Store coverage file
+        if: matrix.pythonV == needs.determine-python-version.outputs.min-version
+        uses: actions/upload-artifact@v4
+        with:
+          name: coverage-no_memory
+          path: .coverage.no_memory
+          include-hidden-files: true
+
+      - name: Tests with memory tracking
+        # Re-syncing is optimized by uv's global cache
+        run: |
+          uv run pytest --junitxml=junit/test-results.xml --cov=stochmat --durations=0 --memray --most-allocations=0 -k '_memory'
+        env:
+          COVERAGE_FILE: ".coverage.memory"
+
+      - name: Store coverage file
+        if: matrix.pythonV == needs.determine-python-version.outputs.min-version
+        uses: actions/upload-artifact@v4
+        with:
+          name: coverage-memory
+          path: .coverage.memory
+          include-hidden-files: true
+
+      # Update per-version pass/fail badge in gist
+      - name: Update Python ${{ matrix.pythonV }} status badge
+        if: always()
+        # pinned to v1.8.0
+        uses: schneegans/dynamic-badges-action@0e50b8bad39e7e1afd3e4e9c2b7dd145fad07501
+        with:
+          auth: ${{ secrets.GIST_SECRET }}
+          gistID: ${{ vars.STATUS_GIST_ID }}
+          filename: python-${{ matrix.pythonV }}.json
+          label: "Python ${{ matrix.pythonV }}"
+          message: ${{ job.status == 'success' && 'passing' || 'failing' }}
+          color: ${{ job.status == 'success' && 'brightgreen' || 'red' }}
+
+  coverage-badge:
+    name: coverage-badge
+    runs-on: ubuntu-24.04
+    needs: [unit-tests]
+    if: always()
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/checkout@v5
+      - uses: actions/download-artifact@v4
+        id: download
+        with:
+          pattern: coverage-*
+          merge-multiple: true
+  
+      - name: Update coverage badge
+        uses: py-cov-action/python-coverage-comment-action@v3
+        with:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          MERGE_COVERAGE_FILES: true