Benchmarking

.github/workflows/asv-benchmarks.yml

@@ -0,0 +1,212 @@
+name: Benchmark Availability Checks
+
+on:
+  # This workflow checks whether the benchmark code can be installed and
+  # started on the supported GitHub-hosted runners. It is a smoke check, not a
+  # performance benchmark suite.
+  pull_request:
+    branches:
+      - "main"
+    paths:
+      - ".github/workflows/asv-benchmarks.yml"
+      - "asv*.json"
+      - "benchmarks/**"
+      - "pyproject.toml"
+  push:
+    branches:
+      - "main"
+    paths:
+      - ".github/workflows/asv-benchmarks.yml"
+      - "asv*.json"
+      - "benchmarks/**"
+      - "pyproject.toml"
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  benchmark_asv_existing_env:
+    # Use the same dependency combinations as main.yml, but run only one
+    # lightweight benchmark method in the already-created Python environment.
+    # That avoids ASV's conda environment management in CI while still proving
+    # that users can start the benchmark suite on each runner family.
+    name: ASV smoke on ${{ matrix.os }} py${{ matrix.ver.py }}
+    runs-on: ${{ matrix.os }}
+    timeout-minutes: 30
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - case-id: ubuntu-py311
+            os: ubuntu-latest
+            ver: { py: "3.11", np: "==1.23.2", sp: "==1.9.2" }
+          - case-id: ubuntu-py312
+            os: ubuntu-latest
+            ver: { py: "3.12", np: "==1.26.2", sp: "==1.11.2" }
+          - case-id: ubuntu-py313
+            os: ubuntu-latest
+            ver: { py: "3.13", np: "==2.1.0", sp: "==1.14.1" }
+          - case-id: ubuntu-py314
+            os: ubuntu-latest
+            ver: { py: "3.14", np: "==2.3.2", sp: "==1.16.1" }
+            asv_backends: "cython_fallback"
+          - case-id: windows-py311
+            os: windows-latest
+            ver: { py: "3.11", np: "==1.23.2", sp: "==1.9.2" }
+          - case-id: windows-py312
+            os: windows-latest
+            ver: { py: "3.12", np: "==1.26.2", sp: "==1.11.2" }
+          - case-id: windows-py313
+            os: windows-latest
+            ver: { py: "3.13", np: "==2.1.0", sp: "==1.14.1" }
+          - case-id: windows-py314
+            os: windows-latest
+            ver: { py: "3.14", np: "==2.3.2", sp: "==1.16.1" }
+            asv_backends: "cython_fallback"
+          - case-id: macos-latest-py311
+            os: macos-latest
+            ver: { py: "3.11", np: "==1.23.2", sp: "==1.9.2" }
+          - case-id: macos-latest-py312
+            os: macos-latest
+            ver: { py: "3.12", np: "==1.26.2", sp: "==1.11.2" }
+          - case-id: macos-latest-py313
+            os: macos-latest
+            ver: { py: "3.13", np: "==2.1.0", sp: "==1.14.1" }
+          - case-id: macos-latest-py314
+            os: macos-latest
+            ver: { py: "3.14", np: "==2.3.2", sp: "==1.16.1" }
+            asv_backends: "cython_fallback"
+          - case-id: macos15-intel-py311
+            os: macos-15-intel
+            ver: { py: "3.11", np: "==1.23.2", sp: "==1.9.2" }
+          - case-id: macos15-intel-py312
+            os: macos-15-intel
+            ver: { py: "3.12", np: "==1.26.2", sp: "==1.11.2" }
+          - case-id: macos15-intel-py313
+            os: macos-15-intel
+            ver: { py: "3.13", np: "==2.1.0", sp: "==1.14.1" }
+          - case-id: macos15-intel-py314
+            os: macos-15-intel
+            ver: { py: "3.14", np: "==2.3.2", sp: "==1.16.1" }
+            asv_backends: "cython_fallback"
+
+    defaults:
+      run:
+        # Use one shell syntax for Linux, Windows, and macOS smoke commands.
+        shell: bash
+
+    steps:
+      - uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5.0.0
+        with:
+          fetch-depth: 0
+
+      - uses: actions/setup-python@e797f83bcb11b83ae66e0230d6156d7c80228e7c # v6.0.0
+        with:
+          python-version: ${{ matrix.ver.py }}
+
+      - name: Install benchmark smoke dependencies
+        run: |
+          python -m pip install --upgrade pip
+          python -m pip install \
+            asv \
+            emcee \
+            "gstools-cython>=1,<2" \
+            "gstools_core>=1.0.0" \
+            hankel \
+            meshio \
+            "numpy${{ matrix.ver.np }}" \
+            pyevtk \
+            "scipy${{ matrix.ver.sp }}"
+          python -m pip install --no-deps --editable .
+
+      - name: Configure ASV machine
+        run: |
+          # existing environments still need a machine profile for ASV result
+          # metadata. --yes keeps the command non-interactive in CI.
+          asv machine --yes
+
+      - name: Write ASV smoke config for checked-out commit
+        run: |
+          # With -E existing, ASV cannot receive a range like HEAD^!. If no
+          # range is supplied, ASV resolves the configured branches. PR
+          # checkouts do not necessarily have a local "main" branch, so this
+          # temporary config points ASV at the exact checked-out commit.
+          python - <<'PY'
+          import json
+          import os
+          from pathlib import Path
+
+          config = json.loads(Path("asv.conf.json").read_text())
+          config["branches"] = [os.environ["GITHUB_SHA"]]
+          Path("asv.ci-existing.json").write_text(json.dumps(config, indent=2))
+          PY
+
+      - name: Run ASV smoke check in existing environment
+        env:
+          GSTOOLS_BENCHMARK_THREADS: "1"
+          GSTOOLS_BENCHMARK_BACKENDS: ${{ matrix.asv_backends || '' }}
+        run: |
+          # -E existing uses the Python environment prepared above. Python 3.14
+          # is currently Cython-only because gstools_core 1.2.0 can fail during
+          # the Rust variogram smoke case. Existing environments cannot accept
+          # a commit range, so the checked-out commit is recorded explicitly.
+          asv run \
+            --config asv.ci-existing.json \
+            -E existing \
+            --set-commit-hash "$GITHUB_SHA" \
+            --no-pull \
+            --quick \
+            --bench benchmark_backends.VariogramWorkflowBenchmarks.time_variogram_estimate \
+            --show-stderr
+
+  benchmark_parallel_readiness:
+    # Keep this separate from the ASV smoke job. It checks the smallest useful
+    # runtime proof for parallel backends without running a full ASV benchmark
+    # and without building gstools-cython from the PyPI source distribution.
+    name: Parallel readiness on ${{ matrix.os }} py3.13
+    runs-on: ${{ matrix.os }}
+    timeout-minutes: 30
+    strategy:
+      fail-fast: false
+      matrix:
+        os:
+          - ubuntu-latest
+          - windows-latest
+          - macos-latest
+          - macos-15-intel
+
+    defaults:
+      run:
+        shell: bash -el {0}
+
+    steps:
+      - uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5.0.0
+
+      - uses: conda-incubator/setup-miniconda@fc2d68f6413eb2d87b895e92f8584b5b94a10167 # v3
+        with:
+          activate-environment: gstools-benchmark-readiness
+          python-version: "3.13"
+          channels: conda-forge
+          conda-remove-defaults: true
+
+      - name: Install parallel readiness dependencies
+        run: |
+          conda install -n gstools-benchmark-readiness -y -c conda-forge \
+            emcee \
+            gstools-cython \
+            hankel \
+            meshio \
+            "numpy=2.1.0" \
+            pip \
+            pyevtk \
+            "scipy=1.14.1"
+          conda run -n gstools-benchmark-readiness python -m pip install \
+            "gstools_core>=1.0.0"
+          conda run -n gstools-benchmark-readiness python -m pip install \
+            --no-deps --editable .
+
+      - name: Check Cython OpenMP and Rust backend readiness
+        run: |
+          conda run -n gstools-benchmark-readiness python \
+            benchmarks/tools/check_backend_parallel_ready.py --verbose

.github/workflows/main.yml

@@ -55,7 +55,7 @@ jobs:
       fail-fast: false
       matrix:
         os:
-          [ubuntu-latest, ubuntu-24.04-arm, windows-latest, macos-13, macos-14]
+          [ubuntu-latest, ubuntu-24.04-arm, windows-latest, macos-15-intel, macos-latest]
         # https://github.com/scipy/oldest-supported-numpy/blob/main/setup.cfg
         ver:
           - { py: "3.8", np: "==1.20.0", sp: "==1.5.4" }
@@ -64,15 +64,16 @@ jobs:
           - { py: "3.11", np: "==1.23.2", sp: "==1.9.2" }
           - { py: "3.12", np: "==1.26.2", sp: "==1.11.2" }
           - { py: "3.13", np: "==2.1.0", sp: "==1.14.1" }
-          - { py: "3.13", np: ">=2.1.0", sp: ">=1.14.1" }
+          - { py: "3.14", np: "==2.3.2", sp: "==1.16.1" }
+          - { py: "3.14", np: ">=2.3.2", sp: ">=1.16.1" }
         exclude:
           - os: ubuntu-24.04-arm
             ver: { py: "3.8", np: "==1.20.0", sp: "==1.5.4" }
-          - os: macos-14
+          - os: macos-latest
             ver: { py: "3.8", np: "==1.20.0", sp: "==1.5.4" }
-          - os: macos-14
+          - os: macos-latest
             ver: { py: "3.9", np: "==1.20.0", sp: "==1.5.4" }
-          - os: macos-14
+          - os: macos-latest
             ver: { py: "3.10", np: "==1.21.6", sp: "==1.7.2" }
     steps:
       - uses: actions/checkout@v4

.gitignore

@@ -41,6 +41,10 @@ htmlcov/
 .coverage
 .coverage.*
 .cache
+.asv/*
+.asv-openmp/*
+.asv-ci/*
+asv.ci.*.json
 nosetests.xml
 coverage.xml
 *.cover

README.md

@@ -54,8 +54,8 @@ Install the package by typing the following command in a command terminal:
 
     conda install gstools
 
-In case conda forge is not set up for your system yet, see the easy to follow
-instructions on [conda forge][conda_forge_link]. Using conda, the parallelized
+In case conda-forge is not set up for your system yet, see the easy to follow
+instructions on [conda-forge][conda_forge_link]. Using conda, the parallelized
 version of GSTools should be installed.
 
 

asv.conf.json

@@ -0,0 +1,30 @@
+{
+  "version": 1,
+  "project": "GSTools",
+  "project_url": "https://github.com/jeilealr/GSTools",
+  "repo": ".",
+  "branches": ["main"],
+  "benchmark_dir": "benchmarks",
+  "env_dir": ".asv/env",
+  "results_dir": ".asv/results",
+  "html_dir": ".asv/html",
+  "show_commit_url": "https://github.com/jeilealr/GSTools/commit/",
+  "environment_type": "conda",
+  "conda_channels": ["conda-forge"],
+  "pythons": ["3.12"],
+  "matrix": {
+    "req": {
+      "emcee": [""],
+      "hankel": [""],
+      "meshio": [""],
+      "numpy": [""],
+      "pyevtk": [""],
+      "scipy": [""],
+      "gstools-cython": [""]
+    }
+  },
+  "install_command": [
+    "in-dir={env_dir} python -m pip install gstools_core>=1.0.0",
+    "in-dir={env_dir} python -m pip install --no-deps {build_dir}"
+  ]
+}

asv.openmp.conf.json

@@ -0,0 +1,37 @@
+{
+  "version": 1,
+  "project": "GSTools",
+  "project_url": "https://github.com/jeilealr/GSTools",
+  "repo": ".",
+  "branches": ["main"],
+  "benchmark_dir": "benchmarks",
+  "env_dir": ".asv-openmp/env",
+  "results_dir": ".asv-openmp/results",
+  "html_dir": ".asv-openmp/html",
+  "show_commit_url": "https://github.com/jeilealr/GSTools/commit/",
+  "environment_type": "conda",
+  "conda_channels": ["conda-forge"],
+  "pythons": ["3.12"],
+  "matrix": {
+    "req": {
+      "c-compiler": [""],
+      "cxx-compiler": [""],
+      "cython": [""],
+      "emcee": [""],
+      "extension-helpers": [""],
+      "hankel": [""],
+      "meshio": [""],
+      "numpy": [""],
+      "pyevtk": [""],
+      "scipy": [""],
+      "setuptools>=77": [""],
+      "wheel": [""]
+    }
+  },
+  "install_command": [
+    "in-dir={env_dir} python -m pip install gstools_core>=1.0.0",
+    "in-dir={env_dir} python {conf_dir}/benchmarks/tools/install_openmp_cython.py {env_dir}",
+    "in-dir={env_dir} python -m pip install --no-deps {build_dir}",
+    "in-dir={env_dir} python {conf_dir}/benchmarks/tools/check_backend_parallel_ready.py --verbose"
+  ]
+}