cvmatrix 3.2.2__tar.gz → 3.3.0__tar.gz

{cvmatrix-3.2.2 → cvmatrix-3.3.0}/.github/actions/build/action.yml

@@ -4,12 +4,12 @@ description: Build the package
 runs:
    using: "composite"
    steps:
-    - uses: actions/checkout@v4
+    - uses: actions/checkout@v7
 
     - name: Install uv
-      uses: astral-sh/setup-uv@v5
+      uses: astral-sh/setup-uv@v7
       with:
-        python-version: '3.14'
+        python-version: '3.15'
 
     - name: Lint with ruff
       run: |
@@ -28,7 +28,7 @@ runs:
       shell: bash
 
     - name: Store the distribution packages
-      uses: actions/upload-artifact@v4
+      uses: actions/upload-artifact@v7
       with:
         name: python-package-distributions
         path: dist/

{cvmatrix-3.2.2 → cvmatrix-3.3.0}/.github/actions/release/action.yml

@@ -11,12 +11,12 @@ runs:
           echo "VERSION=$version" >> $GITHUB_ENV
         shell: bash
       - name: Download all the dists
-        uses: actions/download-artifact@v4
+        uses: actions/download-artifact@v8
         with:
           name: python-package-distributions
           path: dist/
       - name: Sign the dists with Sigstore
-        uses: sigstore/gh-action-sigstore-python@v3.0.0
+        uses: sigstore/gh-action-sigstore-python@v3.5.0
         with:
           inputs: >-
             ./dist/*.tar.gz

{cvmatrix-3.2.2 → cvmatrix-3.3.0}/.github/actions/test/action.yml

@@ -14,7 +14,7 @@ runs:
   using: "composite"
   steps:
     - name: Install uv
-      uses: astral-sh/setup-uv@v5
+      uses: astral-sh/setup-uv@v7
       with:
         python-version: ${{ inputs.PYTHON_VERSION }}
 
@@ -28,6 +28,26 @@ runs:
       run: uv sync --group dev
       shell: bash
 
+    # On free-threaded Python (e.g. 3.15t), importing an extension module that does not
+    # support free threading silently re-enables the GIL, and the tests would then pass
+    # without exercising free threading. Fail if any test dependency re-enables it.
+    - name: Check that the GIL stays disabled (free-threaded Python only)
+      if: ${{ endsWith(inputs.PYTHON_VERSION, 't') }}
+      run: |
+        uv run python - <<'EOF'
+        import importlib.util
+        import sys
+
+        import coverage, cvmatrix, numpy, pandas, pytest, typeguard  # noqa: E401, F401
+
+        if importlib.util.find_spec("jax") is not None:
+            import jax.numpy  # noqa: F401
+        if sys._is_gil_enabled():
+            sys.exit("The GIL was re-enabled by an imported extension module.")
+        print("The GIL stays disabled with all test dependencies imported.")
+        EOF
+      shell: bash
+
     # The same test suite runs in both modes. With the JAX backend installed it also
     # exercises the parametrized backend="jax" tests; without JAX those parametrizations
     # are skipped (pytest.importorskip), verifying the numpy-only path.

{cvmatrix-3.2.2 → cvmatrix-3.3.0}/.github/workflows/package_workflow.yml

@@ -10,7 +10,7 @@ jobs:
     build_package:
         runs-on: ubuntu-latest
         steps:
-            - uses: actions/checkout@v4
+            - uses: actions/checkout@v7
             - uses: ./.github/actions/build
 
     publish_package:
@@ -18,8 +18,8 @@ jobs:
         runs-on: ubuntu-latest
         if: ${{ github.event.workflow_run.conclusion == 'success' }}
         steps:  
-            - uses: actions/checkout@v4
-            - uses: actions/download-artifact@v4
+            - uses: actions/checkout@v7
+            - uses: actions/download-artifact@v8
               with:
                 name: python-package-distributions
                 path: dist/
@@ -41,5 +41,5 @@ jobs:
             contents: write
             id-token: write
         steps:
-            - uses: actions/checkout@v4
+            - uses: actions/checkout@v7
             - uses: ./.github/actions/release

{cvmatrix-3.2.2 → cvmatrix-3.3.0}/.github/workflows/pull_request_package_workflow.yml

@@ -14,5 +14,5 @@ jobs:
     build_package:
         runs-on: ubuntu-latest
         steps:
-            - uses: actions/checkout@v4
+            - uses: actions/checkout@v7
             - uses: ./.github/actions/build

{cvmatrix-3.2.2 → cvmatrix-3.3.0}/.github/workflows/pull_request_test_workflow.yml

@@ -18,9 +18,14 @@ jobs:
       fail-fast: false
       matrix:
         os: [ubuntu-latest, windows-latest, macos-latest]
-        python-version: ["3.10", "3.11", "3.12", "3.13", "3.14"]
+        python-version: ["3.10", "3.11", "3.12", "3.13", "3.14", "3.15", "3.15t"]
+        # jaxlib publishes no free-threaded (cp315t) wheel for Windows, and no sdist.
+        # Windows x 3.15t is still tested by the numpy-only job below.
+        exclude:
+          - os: windows-latest
+            python-version: "3.15t"
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v7
       - uses: ./.github/actions/test
         with:
           PYTHON_VERSION: ${{ matrix.python-version }}
@@ -42,9 +47,9 @@ jobs:
       fail-fast: false
       matrix:
         os: [ubuntu-latest, windows-latest, macos-latest]
-        python-version: ["3.10", "3.11", "3.12", "3.13", "3.14"]
+        python-version: ["3.10", "3.11", "3.12", "3.13", "3.14", "3.15", "3.15t"]
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v7
       - uses: ./.github/actions/test
         with:
           PYTHON_VERSION: ${{ matrix.python-version }}

{cvmatrix-3.2.2 → cvmatrix-3.3.0}/.github/workflows/test_workflow.yml

@@ -18,9 +18,14 @@ jobs:
             fail-fast: false
             matrix:
                 os: [ubuntu-latest, windows-latest, macos-latest]
-                python-version: ["3.10", "3.11", "3.12", "3.13", "3.14"]
+                python-version: ["3.10", "3.11", "3.12", "3.13", "3.14", "3.15", "3.15t"]
+                # jaxlib publishes no free-threaded (cp315t) wheel for Windows, and no sdist.
+                # Windows x 3.15t is still tested by the numpy-only job below.
+                exclude:
+                    - os: windows-latest
+                      python-version: "3.15t"
         steps:
-            - uses: actions/checkout@v4
+            - uses: actions/checkout@v7
             - uses: ./.github/actions/test
               with:
                     PYTHON_VERSION: ${{ matrix.python-version }}
@@ -42,9 +47,9 @@ jobs:
             fail-fast: false
             matrix:
                 os: [ubuntu-latest, windows-latest, macos-latest]
-                python-version: ["3.10", "3.11", "3.12", "3.13", "3.14"]
+                python-version: ["3.10", "3.11", "3.12", "3.13", "3.14", "3.15", "3.15t"]
         steps:
-            - uses: actions/checkout@v4
+            - uses: actions/checkout@v7
             - uses: ./.github/actions/test
               with:
                     PYTHON_VERSION: ${{ matrix.python-version }}

{cvmatrix-3.2.2 → cvmatrix-3.3.0}/CHANGELOG.md

@@ -5,6 +5,23 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [3.3.0] - 2026-10-30
+
+### Added
+- `compute_XTX` and `compute_XTY` constructor parameters (both default `True`, the previous behavior) that control whether `fit` computes the dataset-wide `XTX` (`X^T W X`) and `XTY` (`X^T W Y`). A product that is never used can now be skipped: e.g., `compute_XTX=False` avoids the O(NK²) time and K² memory of `XTX` when only `training_XTY` and/or `training_statistics` are used, which can dominate `fit` for wide `X`. A product that is not computed is `None`, and the training methods that need it raise a `ValueError`. The products are still computed in `fit`, so they are pickled along with a fitted `CVMatrix` and are not recomputed per task when cross-validating in parallel worker processes (e.g., with `joblib`).
+- Support for free-threaded Python. The CI test matrices now include free-threaded Python 3.15 (`3.15t`) on Linux, macOS, and Windows, with a check that no dependency re-enables the GIL. The JAX backend is tested on `3.15t` on Linux and macOS only, as jaxlib publishes no free-threaded wheel for Windows. The package declares the `Programming Language :: Python :: Free Threading :: 3 - Stable` classifier. A fitted `CVMatrix` can be shared by multiple threads, as the per-fold training methods only read it.
+
+### Changed
+- The CI test workflow for pushes to `main` now also tests Python 3.15, matching the pull-request workflow.
+- The per-fold training methods now gather only the validation set rows they use. Previously, the unweighted validation set rows of `X` were gathered, but not used, by `training_XTY` and `training_statistics`. With `weights` on the numpy backend, this makes `training_XTY` ~20% faster and `training_statistics` ~25-45% faster. Results are unchanged. Unweighted computations and computations traced by `jax.jit` were not affected.
+
+### Fixed
+- A fitted `CVMatrix` can be pickled with the standard library again. Since 3.2.0, the instance held the array namespace `xp` (the `numpy` or `jax.numpy` module), which cannot be pickled, so `pickle`, `copy.deepcopy`, `multiprocessing`, and `concurrent.futures.ProcessPoolExecutor` failed with `TypeError: cannot pickle 'module' object` (`joblib`'s default `loky` backend was not affected, as it pickles with `cloudpickle`). The module is now left out of the pickled state and resolved again from `backend` when unpickling. With `backend="jax"`, JAX's 64-bit mode is enabled before the arrays are restored, so float64 data stays float64 in fresh worker processes, where it would otherwise silently become float32.
+- Re-fitting a `CVMatrix` now replaces all state derived from `Y` instead of keeping it from the previous fit. Re-fitting without `Y` resets `XTY`, `WY`, `sum_Y`, `sq_Y`, and `sum_sq_Y` to `None`, and re-fitting with weights that do not require `WY` (no `center_X`, `center_Y`, or `scale_Y`) resets `WY` to `None`; likewise, `sq_X` is reset to `None` when `scale_X` is `False`. Results were not affected, but the stale arrays were kept in memory and pickled along with the fitted model (e.g., to parallel worker processes).
+
+## [3.2.3] - 2026-10-30
+- Increased the maximum supported Python version from 3.14 to 3.15. Python 3.15 is now included in the CI test matrices. No functional changes.
+
 ## [3.2.2] - 2026-07-06
 
 ### Changed

{cvmatrix-3.2.2 → cvmatrix-3.3.0}/CONTRIBUTING.md

@@ -30,18 +30,28 @@ The sections below outline the steps in each case.
 1. (**Important**) Announce your plan to the rest of the community *before you start working*. This announcement should be in the form of a (new) issue;
 2. (**Important**) Wait until some kind of consensus is reached about your idea being a good idea;
 3. If needed, fork the repository to your own Github profile and create your own feature branch off of the latest main commit. While working on your feature branch, make sure to stay up to date with the main branch by pulling in changes, possibly from the 'upstream' repository (follow the instructions [here](https://help.github.com/articles/configuring-a-remote-for-a-fork/) and [here](https://help.github.com/articles/syncing-a-fork/));
-4. Make sure the existing tests still work by following the instructions in [Run the test suite](#run-the-test-suite);
-5. Add your own tests (if necessary);
-6. If you added your own tests, make sure they pass by following the instructions in [Run the test suite](#run-the-test-suite);
-7. If your contribution is a performance enhancement, make sure to include benchmarks. See [Benchmarking](#benchmarking) for more information;
-8. Update or expand the documentation;
-9. Make sure the documentation builds without errors by following the instructions in [Build the documentation](#build-the-documentation);
-10. Check that you can build the package locally and that it passes twine check. See [Build from source](#build-from-source) for more information;
-11. [Push](http://rogerdudler.github.io/git-guide/) your feature branch to (your fork of) the CVMatrix repository on GitHub;
-12. Create the pull request, e.g. following the instructions [here](https://help.github.com/articles/creating-a-pull-request/).
+4. Follow the [Design guidelines](#design-guidelines) when changing `CVMatrix`;
+5. Make sure the existing tests still work by following the instructions in [Run the test suite](#run-the-test-suite);
+6. Add your own tests (if necessary);
+7. If you added your own tests, make sure they pass by following the instructions in [Run the test suite](#run-the-test-suite);
+8. If your contribution is a performance enhancement, make sure to include benchmarks. See [Benchmarking](#benchmarking) for more information;
+9. Update or expand the documentation;
+10. Make sure the documentation builds without errors by following the instructions in [Build the documentation](#build-the-documentation);
+11. Check that you can build the package locally and that it passes twine check. See [Build from source](#build-from-source) for more information;
+12. [Push](http://rogerdudler.github.io/git-guide/) your feature branch to (your fork of) the CVMatrix repository on GitHub;
+13. Create the pull request, e.g. following the instructions [here](https://help.github.com/articles/creating-a-pull-request/).
 
 If you feel like you've made a valuable contribution, but you don't know how to write or run tests for it or generate the documentation, don't let this discourage you from making the pull request; we can help you! Just submit the pull request, but remember that you might be asked to append additional commits to your pull request.
 
+## Design guidelines
+
+`CVMatrix` is used in several execution settings: traced by `jax.jit`/`jax.vmap` with `backend="jax"`, called concurrently from multiple threads (including on free-threaded Python, which has no GIL), and pickled to worker processes (e.g., with `joblib`, `multiprocessing`, or `concurrent.futures.ProcessPoolExecutor`). To keep it correct and fast in all of them:
+
+- **The per-fold methods only read the fitted state.** `training_XTX`, `training_XTY`, `training_XTX_XTY`, and `training_statistics` must not modify the instance, e.g., by caching results on it. Compute anything dataset-wide in `fit`. A cache written during a per-fold call would leak tracers under `jax.jit`, race between threads, and, in worker processes, be filled in a throwaway copy, i.e., recomputed for every task.
+- **Route array operations through `self.xp`**, not `np`, so that the NumPy and JAX backends share one implementation and the per-fold methods stay traceable. Data-dependent checks that cannot run under tracing are skipped for tracer inputs (see `_TRACER_TYPES`). The NumPy backend's results must not change.
+- **Keep instances picklable with the standard library's `pickle`.** Do not store modules, locks, open files, or other unpicklable objects on the instance. If one is unavoidable, leave it out in `__reduce__` and restore it in `_reconstruct`, as is done for the array namespace `xp`. `test_pickle` and `test_process_pool` check this.
+- **Test both backends.** Every test runs with both `backend="numpy"` and `backend="jax"` through the `_set_backend` fixture in `tests/test_cvmatrix.py`; JAX-only tests skip themselves under the NumPy parametrization.
+
 ## Build from source
 
 CVMatrix uses [uv](https://docs.astral.sh/uv/) to manage its dependencies and packaging. To build the package from source, follow these steps:
@@ -101,9 +111,25 @@ To run the test suite, follow these steps:
 3. Now, the tests can be run with the following command:
 
     ```shell
-    uv run pytest tests --doctest-modules --junitxml=junit/test-results.xml --cov=cvmatrix/ --cov-report=xml --cov-report=html --typeguard-packages=cvmatrix/
+    uv run pytest tests --doctest-modules
     ```
 
+    The pytest options in `pyproject.toml` enable runtime type checking with [typeguard](https://typeguard.readthedocs.io/) (`--typeguard-packages=cvmatrix`) and coverage reports. Note that `--typeguard-packages` takes the package name `cvmatrix`, not a path: `cvmatrix/` silently instruments nothing.
+
+### Test on free-threaded Python
+
+CVMatrix also runs on free-threaded builds of Python (e.g., `3.15t`), which have no GIL. To run the test suite on one without touching your default environment, let uv create a temporary, isolated environment:
+
+```shell
+uv run --isolated --python 3.15t --extra jax --group dev pytest tests --doctest-modules
+```
+
+A free-threaded interpreter silently re-enables the GIL if it imports an extension module that does not support free threading. Check that the GIL stays disabled with all dependencies imported; this must print `False`:
+
+```shell
+uv run --isolated --python 3.15t --extra jax python -c "import sys, cvmatrix, jax; print(sys._is_gil_enabled())"
+```
+
 ## Build the documentation
 
 1. Install sphinx, the sphinx-rtd-theme, and the MyST-Parser:
@@ -126,4 +152,12 @@ To run the test suite, follow these steps:
 
 ## Benchmarking
 
-To run benchmarks, follow the instructions [here](https://github.com/Sm00thix/CVMatrix/blob/main/benchmarks/README.md).
+To run benchmarks, follow the instructions [here](https://github.com/Sm00thix/CVMatrix/blob/main/benchmarks/README.md).
+
+`benchmarks/benchmark.py` can be configured with environment variables, e.g., `BENCH_CONFIGS=plot` (only the three preprocessing combinations in the plots), `BENCH_PS=3,100,10000` (the numbers of folds), `BENCH_N`/`BENCH_K`/`BENCH_M` (the data size), and `BENCH_CSV` (the output file):
+
+```shell
+OPENBLAS_NUM_THREADS=1 BENCH_CONFIGS=plot BENCH_PS=3,100,10000 BENCH_CSV=my_results.csv uv run python benchmarks/benchmark.py
+```
+
+When you compare the performance of your change against `main`, run both versions on the same machine with a single BLAS thread, as above, and alternate between them over several rounds, also with the order reversed. The per-fold timings depend on the memory allocation history of the process, so identical code can differ by several percent between runs, and a fixed run order can look like a consistent difference.

{cvmatrix-3.2.2 → cvmatrix-3.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: cvmatrix
-Version: 3.2.2
+Version: 3.3.0
 Summary: Fast computation of possibly weighted and possibly centered/scaled training set kernel matrices in a cross-validation setting.
 Project-URL: Homepage, https://cvmatrix.readthedocs.io/en/latest/
 Project-URL: Repository, https://github.com/Sm00thix/CVMatrix
@@ -13,7 +13,9 @@ Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
 Classifier: Programming Language :: Python :: 3.14
-Requires-Python: <3.15,>=3.10
+Classifier: Programming Language :: Python :: 3.15
+Classifier: Programming Language :: Python :: Free Threading :: 3 - Stable
+Requires-Python: <3.16,>=3.10
 Requires-Dist: numpy<3.0.0,>=2.0.0
 Provides-Extra: jax
 Requires-Dist: jax>=0.4.0; extra == 'jax'
@@ -47,6 +49,10 @@ For an implementation of the fast cross-validation algorithms combined with Impr
 
 The `cvmatrix` software package now also features **weigthed matrix produts** $\mathbf{X}^{\mathbf{T}}\mathbf{W}\mathbf{Y}$ **without increasing time or space complexity compared to the unweighted case**. This is due to a generalization of the algorithms by Engstrøm and Jensen [[1]](#references). A new article formally describing the generalization is to be announced.
 
+## Citation
+- If you use the `cvmatrix` software package for your work, please cite  [this Journal of Chemometrics article](https://analyticalsciencejournals.onlinelibrary.wiley.com/doi/full/10.1002/cem.70008).
+- If you use the sample weighted option, please also cite [this PhD thesis](https://arxiv.org/abs/2510.13452).
+
 ## Installation
 
 - Install the package for Python3 using the following command:

{cvmatrix-3.2.2 → cvmatrix-3.3.0}/README.md

@@ -26,6 +26,10 @@ For an implementation of the fast cross-validation algorithms combined with Impr
 
 The `cvmatrix` software package now also features **weigthed matrix produts** $\mathbf{X}^{\mathbf{T}}\mathbf{W}\mathbf{Y}$ **without increasing time or space complexity compared to the unweighted case**. This is due to a generalization of the algorithms by Engstrøm and Jensen [[1]](#references). A new article formally describing the generalization is to be announced.
 
+## Citation
+- If you use the `cvmatrix` software package for your work, please cite  [this Journal of Chemometrics article](https://analyticalsciencejournals.onlinelibrary.wiley.com/doi/full/10.1002/cem.70008).
+- If you use the sample weighted option, please also cite [this PhD thesis](https://arxiv.org/abs/2510.13452).
+
 ## Installation
 
 - Install the package for Python3 using the following command:

{cvmatrix-3.2.2 → cvmatrix-3.3.0}/cvmatrix/__init__.py

@@ -1,4 +1,4 @@
-__version__ = "3.2.2"
+__version__ = "3.3.0"
 __all__ = ["CVMatrix", "Partitioner"]
 from .cvmatrix import CVMatrix
 from .partitioner import Partitioner