fastscipy 0.1.0a1__tar.gz

fastscipy-0.1.0a1/.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,24 @@
+---
+name: Bug report
+about: A result that differs from SciPy, a crash, or a slowdown
+labels: bug
+---
+
+**What happened**
+
+<!-- A minimal script. If a result differs, show it with and without fastscipy:
+
+import numpy as np, scipy.ndimage, fastscipy
+fastscipy.patch()
+x = ...
+with fastscipy.disabled():
+    expected = scipy.ndimage.gaussian_filter(x, 2)
+got = scipy.ndimage.gaussian_filter(x, 2)
+print(np.array_equal(expected, got))
+-->
+
+**Environment**
+
+<!-- Output of:
+python -c "import fastscipy, scipy, numpy, platform, sys; print(fastscipy.__version__, scipy.__version__, numpy.__version__, platform.platform(), sys.version); print(fastscipy.patch())"
+-->

fastscipy-0.1.0a1/.github/workflows/ci.yml

@@ -0,0 +1,81 @@
+name: CI
+
+on:
+  push:
+  pull_request:
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+env:
+  CARGO_TERM_COLOR: always
+  SCIPY_VERSION: "1.18.1"
+
+jobs:
+  lint:
+    name: Lint
+    runs-on: ubuntu-24.04
+    timeout-minutes: 15
+    steps:
+      - uses: actions/checkout@v5
+      - uses: actions/setup-python@v6
+        with:
+          python-version: "3.13"
+      - uses: dtolnay/rust-toolchain@1.97.1
+        with:
+          components: clippy, rustfmt
+      - uses: Swatinem/rust-cache@v2
+      - run: pip install ruff
+      - run: ruff check python tests bench tools examples
+      - run: ruff format --check python tests bench tools examples
+      - run: cargo fmt --check
+      - run: cargo clippy --profile dev-release --all-targets -- -D warnings
+
+  test:
+    name: Tests (macOS arm64, Python ${{ matrix.python }})
+    runs-on: macos-15
+    timeout-minutes: 30
+    strategy:
+      fail-fast: false
+      matrix:
+        python: ["3.12", "3.13", "3.14"]
+    steps:
+      - uses: actions/checkout@v5
+      - uses: actions/setup-python@v6
+        with:
+          python-version: ${{ matrix.python }}
+      - uses: dtolnay/rust-toolchain@1.97.1
+      - uses: Swatinem/rust-cache@v2
+      - name: Build
+        run: |
+          python -m venv .venv
+          source .venv/bin/activate
+          pip install maturin "scipy==$SCIPY_VERSION" pytest pytest-xdist hypothesis
+          maturin develop --profile dev-release
+      - name: Identity tests
+        run: .venv/bin/python -m pytest tests -n auto -q
+
+  scipy-suite:
+    name: SciPy's test suite, with and without fastscipy
+    runs-on: macos-15
+    timeout-minutes: 60
+    steps:
+      - uses: actions/checkout@v5
+      - uses: actions/setup-python@v6
+        with:
+          python-version: "3.13"
+      - uses: dtolnay/rust-toolchain@1.97.1
+      - uses: Swatinem/rust-cache@v2
+      - name: Build
+        run: |
+          python -m venv .venv
+          source .venv/bin/activate
+          pip install maturin "scipy==$SCIPY_VERSION" pytest pytest-xdist hypothesis pooch
+          maturin develop --profile dev-release
+      - name: Compare every test's outcome
+        run: .venv/bin/python tools/scipy_suite.py --pyargs scipy -n auto

fastscipy-0.1.0a1/.github/workflows/linux.yml

@@ -0,0 +1,42 @@
+# Linux is not supported yet: SciPy's Linux wheels are built with a different
+# compiler and BLAS, so some fast paths may not reproduce their last bit.
+# This workflow runs the identity tests there anyway to find out which.
+name: Linux (experimental)
+
+on:
+  push:
+    branches: [main]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+env:
+  CARGO_TERM_COLOR: always
+  FASTSCIPY_ANY_PLATFORM: "1"
+
+jobs:
+  test:
+    name: Identity tests (${{ matrix.os }})
+    runs-on: ${{ matrix.os }}
+    continue-on-error: true
+    timeout-minutes: 60   # the x86-64 build alone takes over 30 minutes on hosted runners
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-24.04, ubuntu-24.04-arm]
+    steps:
+      - uses: actions/checkout@v5
+      - uses: actions/setup-python@v6
+        with:
+          python-version: "3.13"
+      - uses: dtolnay/rust-toolchain@1.97.1
+      - uses: Swatinem/rust-cache@v2
+      - name: Build
+        run: |
+          python -m venv .venv
+          source .venv/bin/activate
+          pip install maturin "scipy==1.18.1" pytest pytest-xdist hypothesis
+          maturin develop --profile dev-release
+      - name: Identity tests
+        run: .venv/bin/python -m pytest tests -n auto -q -rf --tb=no

fastscipy-0.1.0a1/.github/workflows/release.yml

@@ -0,0 +1,112 @@
+name: Release
+
+on:
+  push:
+    tags: ["v*"]
+  workflow_dispatch:
+    inputs:
+      publish:
+        description: "Destination (none only builds and verifies artifacts)"
+        type: choice
+        options: [none, testpypi, pypi]
+        default: none
+
+permissions:
+  contents: read
+
+concurrency:
+  group: release-${{ github.ref }}
+  cancel-in-progress: false
+
+env:
+  CARGO_BUILD_JOBS: "2"
+  MACOSX_DEPLOYMENT_TARGET: "14.0"
+  FASTSCIPY_NUM_THREADS: "2"
+  OPENBLAS_NUM_THREADS: "1"
+  OMP_NUM_THREADS: "1"
+  VECLIB_MAXIMUM_THREADS: "1"
+  RUSTFLAGS: ""
+  RELEASE_TARGET: ${{ inputs.publish || 'pypi' }}
+
+jobs:
+  wheels:
+    name: Wheel / Python ${{ matrix.python }}
+    runs-on: macos-15
+    timeout-minutes: 35
+    strategy:
+      fail-fast: false
+      max-parallel: 2
+      matrix:
+        python: ["3.12", "3.13", "3.14"]
+    steps:
+      - uses: actions/checkout@v5
+      - uses: actions/setup-python@v6
+        with:
+          python-version: ${{ matrix.python }}
+      - uses: dtolnay/rust-toolchain@1.97.1
+      - uses: Swatinem/rust-cache@v2
+      - name: Install build tools
+        run: python -m pip install "maturin>=1.9,<2" twine pytest hypothesis
+      - name: Check versions and architecture
+        run: |
+          python tools/check_release.py
+          python -c "import platform; assert platform.machine() == 'arm64'"
+      - name: Build release wheel from source distribution
+        run: maturin build --release --locked --sdist --out dist --interpreter python
+      - name: Check package contents and PyPI metadata
+        run: |
+          python tools/check_release.py --dist dist
+          python -m twine check --strict dist/*
+      - name: Install the wheel
+        run: |
+          python -m pip install --only-binary=:all: dist/*.whl
+      - name: Verify installed wheel
+        run: python -I tools/check_release.py --installed
+      - name: Identity suite against installed wheel
+        run: python -m pytest tests -q --tb=short
+      - name: Upstream comparison
+        if: matrix.python == '3.13'
+        run: |
+          python -m pip install pytest-xdist pooch
+          python tools/scipy_suite.py --pyargs scipy -n 2
+      - name: Keep one source distribution
+        if: matrix.python != '3.13'
+        run: rm dist/*.tar.gz
+      - uses: actions/upload-artifact@v4
+        with:
+          name: release-${{ matrix.python }}
+          path: dist/*
+          if-no-files-found: error
+          retention-days: 14
+
+  testpypi:
+    needs: wheels
+    if: github.event_name == 'workflow_dispatch' && inputs.publish == 'testpypi'
+    runs-on: ubuntu-24.04
+    environment: testpypi
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          pattern: release-*
+          merge-multiple: true
+          path: dist
+      - uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          repository-url: https://test.pypi.org/legacy/
+
+  pypi:
+    needs: wheels
+    if: startsWith(github.ref, 'refs/tags/v') && (github.event_name == 'push' || inputs.publish == 'pypi')
+    runs-on: ubuntu-24.04
+    environment: pypi
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          pattern: release-*
+          merge-multiple: true
+          path: dist
+      - uses: pypa/gh-action-pypi-publish@release/v1

fastscipy-0.1.0a1/.gitignore

@@ -0,0 +1,8 @@
+/target
+.venv/
+__pycache__/
+*.so
+*.egg-info/
+.pytest_cache/
+
+/dist/

fastscipy-0.1.0a1/CONTRIBUTING.md

@@ -0,0 +1,98 @@
+# Contributing
+
+Contributions are welcome: new fast paths, ports to other platforms, bug
+reports with a reproducer, and benchmark results from other machines.
+
+## Setup
+
+You need Rust (stable) and Python 3.12 to 3.14.
+
+```sh
+python -m venv .venv && source .venv/bin/activate
+pip install maturin "scipy==1.18.1" pytest pytest-xdist hypothesis ruff
+maturin develop --profile dev-release     # rebuild after every Rust change
+```
+
+## Checks
+
+```sh
+pytest tests -n auto                                   # identity tests
+python tools/scipy_suite.py --pyargs scipy.ndimage -n auto   # SciPy's suite, with vs without
+python bench/run.py ndimage --check                    # benchmarks
+ruff check python tests bench tools examples && ruff format --check python tests bench tools examples
+cargo fmt --check && cargo clippy --profile dev-release --all-targets -- -D warnings
+```
+
+CI runs all of these on macOS arm64. A separate workflow runs the identity
+tests on Linux to track that port.
+
+## Adding a fast path
+
+Each SciPy area is one component, `python/fastscipy/_<area>.py`, with
+Rust kernels in `src/<area>/` exposed as `fastscipy._native.<area>`.
+A component defines:
+
+- `patch()`, which starts with `_patch.require_validated("1.18.")` and
+  installs fast paths with `_patch.wrap`, `_patch.replace` and
+  `_patch.rebind` (never by assigning to SciPy directly, or `unpatch()`
+  cannot restore it);
+- `smoke()`, a few small calls that reach every fast path, used by the fork
+  test.
+
+A fast path takes the same arguments as the function it replaces, and either
+returns SciPy's exact result or `NotImplemented` to hand the call to SciPy.
+The rules that keep results identical:
+
+1. **Decline anything you have not matched.** Check dtype, layout, options
+   and sizes up front, and leave every warning and error to SciPy. Never
+   write into a caller's `out=` array and then decline.
+2. **Reproduce SciPy's arithmetic, not just its algorithm.** Keep the
+   summation order, and use `mul_add` where SciPy's compiled code fuses a
+   multiply and add (see [docs/design.md](docs/design.md)).
+3. **Parallel work goes through the shared pools**:
+   `crate::pool::pool().install(...)` in Rust, inside `py.detach(...)`, and
+   `fastscipy._threads.parallel_map` in Python. Never create another pool.
+   Only go parallel above a measured size.
+4. **Test against SciPy, not against expected values.** Add randomized
+   cases to `tests/test_<area>.py` with `fastscipy.testing.check`, which
+   compares bytes and asserts the fast path ran, on 1 and several threads.
+   Include declined cases and edge cases (empty, NaN, inf, ties, strided).
+5. **Show it is faster.** Add cases to `bench/bench_<area>.py`, and make
+   sure `bench/run.py <area> --check` passes.
+
+Before opening a pull request, run SciPy's suite for the area with
+`tools/scipy_suite.py`; no test may change outcome.
+
+## License
+
+By contributing you agree that your contributions are licensed under the
+BSD-3-Clause license of this project.
+
+## Releases
+
+The `Release` workflow builds macOS 14+ arm64 wheels for Python 3.12–3.14,
+installs the wheels, and runs the project checks plus a paired upstream SciPy
+comparison. Builds use two Cargo jobs and bounded numerical thread budgets.
+
+To rehearse, run the workflow manually with `publish: none`. Download the three
+wheel artifacts and source archive from that run. `publish: testpypi` exercises
+an upload to TestPyPI. Publishing to PyPI requires a matching `v<version>` tag;
+version declarations in Python, Cargo and the lockfile must agree.
+
+Before the first upload, sign into PyPI and configure a pending Trusted Publisher:
+
+| Field | Value |
+|---|---|
+| Project | `fastscipy` |
+| Owner | `michael-L-i` |
+| Repository | `fastscipy` |
+| Workflow | `release.yml` |
+| Environment | `pypi` |
+
+Use a separate `testpypi` environment and publisher on TestPyPI for rehearsals.
+No API token is needed. The workflow publishes only after the wheel checks pass.
+A pending publisher does not reserve the package name until the first upload.
+
+Update the README's installation instructions in the release commit before
+creating and pushing the version tag: PyPI renders the README from that archive.
+Push the tag only when ready to publish.

fastscipy-0.1.0a1/Cargo.lock

@@ -0,0 +1,280 @@
+# This file is automatically @generated by Cargo.
+# It is not intended for manual editing.
+version = 4
+
+[[package]]
+name = "autocfg"
+version = "1.5.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "f2032f911046de80f0a198e0901378627c33f59ea0ac00e363d481118bd70a53"
+
+[[package]]
+name = "crossbeam-deque"
+version = "0.8.8"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "622f3fc73690be383c7214310406f28a90e6edeadc3cea882f9d71e495b9711a"
+dependencies = [
+ "crossbeam-epoch",
+ "crossbeam-utils",
+]
+
+[[package]]
+name = "crossbeam-epoch"
+version = "0.9.21"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "dc74980687109a3b14c72fd458107bf0baa1da1a1a805e178d15501ba9b86d9d"
+dependencies = [
+ "crossbeam-utils",
+]
+
+[[package]]
+name = "crossbeam-utils"
+version = "0.8.23"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "a31eee39dddec8330830986fcd7625edb5a24ec90ea038215273bbc3adb08ac6"
+
+[[package]]
+name = "either"
+version = "1.19.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "0e9c71c2167ca323c882b99918929403426e2373ea17242ff5653e0d5e1058be"
+
+[[package]]
+name = "fastscipy"
+version = "0.1.0-alpha.1"
+dependencies = [
+ "numpy",
+ "pyo3",
+ "rayon",
+]
+
+[[package]]
+name = "heck"
+version = "0.5.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "2304e00983f87ffb38b55b444b5e3b60a884b5d30c0fca7d82fe33449bbe55ea"
+
+[[package]]
+name = "libc"
+version = "0.2.190"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "ce5d3ddc6d3fa000eb1536d85e147bfe31aacaba692ed6a876f95cb7c855be78"
+
+[[package]]
+name = "matrixmultiply"
+version = "0.3.11"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "3f607c237553f086e7043417a51df26b2eb899d3caff94e6a67592ff992fedc7"
+dependencies = [
+ "autocfg",
+ "rawpointer",
+]
+
+[[package]]
+name = "ndarray"
+version = "0.17.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "520080814a7a6b4a6e9070823bb24b4531daac8c4627e08ba5de8c5ef2f2752d"
+dependencies = [
+ "matrixmultiply",
+ "num-complex",
+ "num-integer",
+ "num-traits",
+ "portable-atomic",
+ "portable-atomic-util",
+ "rawpointer",
+]
+
+[[package]]
+name = "num-complex"
+version = "0.4.6"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "73f88a1307638156682bada9d7604135552957b7818057dcef22705b4d509495"
+dependencies = [
+ "num-traits",
+]
+
+[[package]]
+name = "num-integer"
+version = "0.1.47"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "7ce2d95d4b3734dc35aa2f45e1aa22cd416814592a4f9d9205e11affd5b8e10b"
+dependencies = [
+ "num-traits",
+]
+
+[[package]]
+name = "num-traits"
+version = "0.2.19"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "071dfc062690e90b734c0b2273ce72ad0ffa95f0c74596bc250dcfd960262841"
+dependencies = [
+ "autocfg",
+]
+
+[[package]]
+name = "numpy"
+version = "0.30.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "aa0b9111761885449e894981fa8051dcf69e0bd114aecbd4bcdd830b6be4ed92"
+dependencies = [
+ "libc",
+ "ndarray",
+ "num-complex",
+ "num-integer",
+ "num-traits",
+ "pyo3",
+ "pyo3-build-config",
+ "rustc-hash",
+]
+
+[[package]]
+name = "once_cell"
+version = "1.21.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "9f7c3e4beb33f85d45ae3e3a1792185706c8e16d043238c593331cc7cd313b50"
+
+[[package]]
+name = "portable-atomic"
+version = "1.15.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "05c8b63e8d9609db387f0324918f81d68fe27748f084ef092fb35954d0539a85"
+
+[[package]]
+name = "portable-atomic-util"
+version = "0.2.8"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "10ab3eb7f3becc3a1cbc4f2c6f20267996cfc1a6467a873763411b136a122715"
+dependencies = [
+ "portable-atomic",
+]
+
+[[package]]
+name = "proc-macro2"
+version = "1.0.107"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "985e7ec9bb745e6ce6535b544d84d6cd6f7ad8bd711c398938ae983b91a766d9"
+dependencies = [
+ "unicode-ident",
+]
+
+[[package]]
+name = "pyo3"
+version = "0.30.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "229ca13b8a15bb0d1487b81ab975bfcd97513416499a8312011b6036e42e0de4"
+dependencies = [
+ "libc",
+ "once_cell",
+ "portable-atomic",
+ "pyo3-build-config",
+ "pyo3-ffi",
+ "pyo3-macros",
+]
+
+[[package]]
+name = "pyo3-build-config"
+version = "0.30.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "70130e2b6dd1ee589a8788026a429561ca5c40fa7a2fa7914c2282eddae24700"
+dependencies = [
+ "target-lexicon",
+]
+
+[[package]]
+name = "pyo3-ffi"
+version = "0.30.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "5e7ff73c555c286d212d4ce7e5fbda845a973c4f61bd5f160f5f2c3c2a04d1c4"
+dependencies = [
+ "libc",
+ "pyo3-build-config",
+]
+
+[[package]]
+name = "pyo3-macros"
+version = "0.30.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "c46d2e5862c7bb8207e3b639f713dda3c499933444784154c11d013c5a691b60"
+dependencies = [
+ "proc-macro2",
+ "pyo3-macros-backend",
+ "quote",
+ "syn",
+]
+
+[[package]]
+name = "pyo3-macros-backend"
+version = "0.30.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "38b89f066f2ae72a2aef52d1537ca2fcd104440ebfadee06e97aa90738a25b9b"
+dependencies = [
+ "heck",
+ "proc-macro2",
+ "quote",
+ "syn",
+]
+
+[[package]]
+name = "quote"
+version = "1.0.47"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "1fbf4db142a473a8d80c26bbf18454ed458bf8d26c8219c331daecfdbd079001"
+dependencies = [
+ "proc-macro2",
+]
+
+[[package]]
+name = "rawpointer"
+version = "0.2.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "60a357793950651c4ed0f3f52338f53b2f809f32d83a07f72909fa13e4c6c1e3"
+
+[[package]]
+name = "rayon"
+version = "1.12.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "fb39b166781f92d482534ef4b4b1b2568f42613b53e5b6c160e24cfbfa30926d"
+dependencies = [
+ "either",
+ "rayon-core",
+]
+
+[[package]]
+name = "rayon-core"
+version = "1.13.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "22e18b0f0062d30d4230b2e85ff77fdfe4326feb054b9783a3460d8435c8ab91"
+dependencies = [
+ "crossbeam-deque",
+ "crossbeam-utils",
+]
+
+[[package]]
+name = "rustc-hash"
+version = "2.1.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "6b1e7f9a428571be2dc5bc0505c13fb6bf936822b894ec87abf8a08a4e51742d"
+
+[[package]]
+name = "syn"
+version = "3.0.9"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "d78c8dee4c7bf0e14673097256fed6142ce9d3b85a408189d07482442145823b"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "unicode-ident",
+]
+
+[[package]]
+name = "target-lexicon"
+version = "0.13.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "adb6935a6f5c20170eeceb1a3835a49e12e19d792f6dd344ccc76a985ca5a6ca"
+
+[[package]]
+name = "unicode-ident"
+version = "1.0.27"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "a2c754d6c33795a1c324727428e5a7dedb5b06195f9890bdbcba760d3e246563"

fastscipy-0.1.0a1/Cargo.toml

@@ -0,0 +1,33 @@
+[package]
+name = "fastscipy"
+version = "0.1.0-alpha.1"
+edition = "2024"
+license = "BSD-3-Clause"
+description = "Rust kernels for fastscipy, a drop-in accelerator for SciPy"
+repository = "https://github.com/michael-L-i/fastscipy"
+publish = false
+readme = "README.md"
+
+[lib]
+name = "_native"
+crate-type = ["cdylib"]
+
+[dependencies]
+numpy = "0.30.0"
+pyo3 = { version = "0.30.1", features = ["extension-module"] }
+rayon = "1.12.0"
+
+[profile.release]
+opt-level = 3
+lto = "thin"          # fat LTO with one codegen unit needs more than 6 GB to link
+codegen-units = 8
+panic = "abort"
+strip = "symbols"
+
+# Fast rebuilds while developing: `maturin develop --profile dev-release`.
+[profile.dev-release]
+inherits = "release"
+lto = false
+codegen-units = 16
+incremental = true
+strip = false