PyStormTracker 0.4.0__tar.gz → 0.4.2__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (56) hide show
  1. {pystormtracker-0.4.0 → pystormtracker-0.4.2}/.github/workflows/ci.yml +0 -2
  2. {pystormtracker-0.4.0 → pystormtracker-0.4.2}/.github/workflows/docker-publish.yml +14 -10
  3. {pystormtracker-0.4.0 → pystormtracker-0.4.2}/.github/workflows/python-publish.yml +2 -0
  4. {pystormtracker-0.4.0 → pystormtracker-0.4.2}/CITATION.cff +2 -2
  5. {pystormtracker-0.4.0 → pystormtracker-0.4.2}/PKG-INFO +35 -17
  6. {pystormtracker-0.4.0 → pystormtracker-0.4.2}/README.md +34 -13
  7. {pystormtracker-0.4.0 → pystormtracker-0.4.2}/ROADMAP.md +4 -0
  8. {pystormtracker-0.4.0 → pystormtracker-0.4.2}/pyproject.toml +4 -7
  9. {pystormtracker-0.4.0 → pystormtracker-0.4.2}/src/pystormtracker/__init__.py +1 -1
  10. {pystormtracker-0.4.0 → pystormtracker-0.4.2}/src/pystormtracker/cli.py +13 -1
  11. {pystormtracker-0.4.0 → pystormtracker-0.4.2}/src/pystormtracker/simple/concurrent.py +39 -38
  12. {pystormtracker-0.4.0 → pystormtracker-0.4.2}/src/pystormtracker/simple/tracker.py +2 -0
  13. {pystormtracker-0.4.0 → pystormtracker-0.4.2}/tests/conftest.py +8 -0
  14. {pystormtracker-0.4.0 → pystormtracker-0.4.2}/uv.lock +275 -412
  15. {pystormtracker-0.4.0 → pystormtracker-0.4.2}/.dockerignore +0 -0
  16. {pystormtracker-0.4.0 → pystormtracker-0.4.2}/.github/dependabot.yml +0 -0
  17. {pystormtracker-0.4.0 → pystormtracker-0.4.2}/.gitignore +0 -0
  18. {pystormtracker-0.4.0 → pystormtracker-0.4.2}/.python-version +0 -0
  19. {pystormtracker-0.4.0 → pystormtracker-0.4.2}/.readthedocs.yaml +0 -0
  20. {pystormtracker-0.4.0 → pystormtracker-0.4.2}/ARCHITECTURE.md +0 -0
  21. {pystormtracker-0.4.0 → pystormtracker-0.4.2}/Dockerfile +0 -0
  22. {pystormtracker-0.4.0 → pystormtracker-0.4.2}/LICENSE +0 -0
  23. {pystormtracker-0.4.0 → pystormtracker-0.4.2}/codecov.yml +0 -0
  24. {pystormtracker-0.4.0 → pystormtracker-0.4.2}/data/test/tracks/era5_msl_2.5x2.5_v0.0.2_imilast.txt +0 -0
  25. {pystormtracker-0.4.0 → pystormtracker-0.4.2}/data/test/tracks/era5_vo_2.5x2.5_1e-4_v0.0.2_imilast.txt +0 -0
  26. {pystormtracker-0.4.0 → pystormtracker-0.4.2}/docs/IntercomparisonProtocol.pdf +0 -0
  27. {pystormtracker-0.4.0 → pystormtracker-0.4.2}/docs/architecture.md +0 -0
  28. {pystormtracker-0.4.0 → pystormtracker-0.4.2}/docs/benchmark.md +0 -0
  29. {pystormtracker-0.4.0 → pystormtracker-0.4.2}/docs/conf.py +0 -0
  30. {pystormtracker-0.4.0 → pystormtracker-0.4.2}/docs/index.md +0 -0
  31. {pystormtracker-0.4.0 → pystormtracker-0.4.2}/docs/readme.md +0 -0
  32. {pystormtracker-0.4.0 → pystormtracker-0.4.2}/docs/roadmap.md +0 -0
  33. {pystormtracker-0.4.0 → pystormtracker-0.4.2}/src/pystormtracker/hodges/__init__.py +0 -0
  34. {pystormtracker-0.4.0 → pystormtracker-0.4.2}/src/pystormtracker/hodges/tracker.py +0 -0
  35. {pystormtracker-0.4.0 → pystormtracker-0.4.2}/src/pystormtracker/io/__init__.py +0 -0
  36. {pystormtracker-0.4.0 → pystormtracker-0.4.2}/src/pystormtracker/io/imilast.py +0 -0
  37. {pystormtracker-0.4.0 → pystormtracker-0.4.2}/src/pystormtracker/io/loader.py +0 -0
  38. {pystormtracker-0.4.0 → pystormtracker-0.4.2}/src/pystormtracker/models/__init__.py +0 -0
  39. {pystormtracker-0.4.0 → pystormtracker-0.4.2}/src/pystormtracker/models/center.py +0 -0
  40. {pystormtracker-0.4.0 → pystormtracker-0.4.2}/src/pystormtracker/models/tracker.py +0 -0
  41. {pystormtracker-0.4.0 → pystormtracker-0.4.2}/src/pystormtracker/models/tracks.py +0 -0
  42. {pystormtracker-0.4.0 → pystormtracker-0.4.2}/src/pystormtracker/simple/__init__.py +0 -0
  43. {pystormtracker-0.4.0 → pystormtracker-0.4.2}/src/pystormtracker/simple/detector.py +0 -0
  44. {pystormtracker-0.4.0 → pystormtracker-0.4.2}/src/pystormtracker/simple/kernels.py +0 -0
  45. {pystormtracker-0.4.0 → pystormtracker-0.4.2}/src/pystormtracker/simple/linker.py +0 -0
  46. {pystormtracker-0.4.0 → pystormtracker-0.4.2}/src/pystormtracker/utils/__init__.py +0 -0
  47. {pystormtracker-0.4.0 → pystormtracker-0.4.2}/src/pystormtracker/utils/benchmark.py +0 -0
  48. {pystormtracker-0.4.0 → pystormtracker-0.4.2}/src/pystormtracker/utils/data_utils.py +0 -0
  49. {pystormtracker-0.4.0 → pystormtracker-0.4.2}/tests/__init__.py +0 -0
  50. {pystormtracker-0.4.0 → pystormtracker-0.4.2}/tests/test_center.py +0 -0
  51. {pystormtracker-0.4.0 → pystormtracker-0.4.2}/tests/test_cli.py +0 -0
  52. {pystormtracker-0.4.0 → pystormtracker-0.4.2}/tests/test_integration.py +0 -0
  53. {pystormtracker-0.4.0 → pystormtracker-0.4.2}/tests/test_simple_detector.py +0 -0
  54. {pystormtracker-0.4.0 → pystormtracker-0.4.2}/tests/test_simple_linker.py +0 -0
  55. {pystormtracker-0.4.0 → pystormtracker-0.4.2}/tests/test_simple_tracker.py +0 -0
  56. {pystormtracker-0.4.0 → pystormtracker-0.4.2}/tests/test_tracks.py +0 -0
@@ -13,8 +13,6 @@ on:
13
13
  branches:
14
14
  - main
15
15
  - release/**
16
- tags:
17
- - v*
18
16
  paths:
19
17
  - 'src/**'
20
18
  - 'tests/**'
@@ -4,16 +4,19 @@ on:
4
4
  workflow_run:
5
5
  workflows: ["CI"]
6
6
  types: [completed]
7
+ branches:
8
+ - main
9
+ - 'v*'
7
10
  workflow_dispatch:
8
11
 
9
12
  concurrency:
10
13
  group: ${{ github.workflow }}-${{ github.ref }}
11
- cancel-in-progress: false
14
+ cancel-in-progress: ${{ !(github.event.workflow_run.event == 'release' || github.ref_type == 'tag') }}
12
15
 
13
16
  env:
14
- # Publish to ORG on release, else to OWNER (personal) for merge to main/manual
15
- DOCKER_HUB_REPO: docker.io/${{ (github.event_name == 'release' || (github.event_name == 'workflow_run' && github.event.workflow_run.event == 'release')) && vars.DOCKER_ORG_NAME || github.repository_owner }}/${{ vars.DOCKER_IMAGE_NAME }}
16
- GHCR_REPO: ghcr.io/${{ (github.event_name == 'release' || (github.event_name == 'workflow_run' && github.event.workflow_run.event == 'release')) && vars.DOCKER_ORG_NAME || github.repository_owner }}/${{ vars.DOCKER_IMAGE_NAME }}
17
+ # Publish to ORG on release or dispatch from tag, else to OWNER (personal) for merge to main/manual
18
+ DOCKER_HUB_REPO: docker.io/${{ ((github.event_name == 'workflow_run' && github.event.workflow_run.event == 'release') || (github.event_name == 'workflow_dispatch' && github.ref_type == 'tag')) && vars.DOCKER_ORG_NAME || github.repository_owner }}/${{ vars.DOCKER_IMAGE_NAME }}
19
+ GHCR_REPO: ghcr.io/${{ ((github.event_name == 'workflow_run' && github.event.workflow_run.event == 'release') || (github.event_name == 'workflow_dispatch' && github.ref_type == 'tag')) && vars.DOCKER_ORG_NAME || github.repository_owner }}/${{ vars.DOCKER_IMAGE_NAME }}
17
20
 
18
21
  jobs:
19
22
  build-and-push:
@@ -23,8 +26,7 @@ jobs:
23
26
  if: |
24
27
  (github.event_name == 'workflow_run' &&
25
28
  github.event.workflow_run.conclusion == 'success' &&
26
- github.event.workflow_run.head_repository.full_name == github.repository &&
27
- (github.event.workflow_run.head_branch == 'main' || github.event.workflow_run.event == 'release')) ||
29
+ github.event.workflow_run.head_repository.full_name == github.repository) ||
28
30
  github.event_name == 'workflow_dispatch'
29
31
  permissions:
30
32
  actions: read
@@ -69,13 +71,15 @@ jobs:
69
71
  # Fix: Tell the metadata action the real ref, otherwise it defaults to 'main'
70
72
  ref: ${{ github.event.workflow_run.head_branch || github.ref }}
71
73
  tags: |
74
+ # Tag with 'latest' for main branch (used for personal repo/edge)
75
+ type=raw,value=latest,enable=${{ github.event.workflow_run.head_branch == 'main' || github.ref == 'refs/heads/main' }},priority=1000
72
76
  # Tag with 'edge' only for main branch builds
73
- type=edge,branch=main,priority=700
77
+ type=edge,branch=main,priority=900
74
78
  # Semver tags for releases (includes 'latest')
75
79
  type=semver,pattern=latest,priority=1000
76
- type=semver,pattern={{version}},priority=900
77
- type=semver,pattern={{major}}.{{minor}},priority=900
78
- type=semver,pattern={{major}},enable=${{ !startsWith(github.ref_name, 'v0') }},priority=900
80
+ type=semver,pattern={{version}},priority=800
81
+ type=semver,pattern={{major}}.{{minor}},priority=700
82
+ type=semver,pattern={{major}},enable=${{ !startsWith(github.ref_name, 'v0') }},priority=700
79
83
  # Branch tag for all branches except main
80
84
  type=ref,event=branch,enable=${{ github.ref_name != 'main' }},priority=600
81
85
  # Always tag with short SHA
@@ -7,6 +7,8 @@ on:
7
7
  workflow_run:
8
8
  workflows: ["CI"]
9
9
  types: [completed]
10
+ branches:
11
+ - 'v*'
10
12
 
11
13
  concurrency:
12
14
  group: ${{ github.workflow }}-${{ github.ref }}
@@ -1,5 +1,5 @@
1
1
  cff-version: 1.2.0
2
- title: mwyau/PyStormTracker
2
+ title: "mwyau/PyStormTracker: v0.4.2"
3
3
  message: "If you use this software, please cite it as below."
4
4
  type: software
5
5
  authors:
@@ -19,7 +19,7 @@ keywords:
19
19
  - dask
20
20
  - mpi
21
21
  license: BSD-3-Clause
22
- version: 0.4.0
22
+ version: 0.4.2
23
23
  date-released: '2026-03-10'
24
24
  preferred-citation:
25
25
  type: article
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: PyStormTracker
3
- Version: 0.4.0
3
+ Version: 0.4.2
4
4
  Summary: A High-Performance Cyclone Tracker in Python
5
5
  Project-URL: Homepage, https://pypi.org/project/PyStormTracker/
6
6
  Project-URL: Repository, https://github.com/mwyau/PyStormTracker.git
@@ -19,13 +19,10 @@ Classifier: Programming Language :: Python :: 3.14
19
19
  Classifier: Topic :: Scientific/Engineering :: Atmospheric Science
20
20
  Requires-Python: >=3.11
21
21
  Requires-Dist: dask>=2024.1.0
22
- Requires-Dist: distributed>=2024.1.0
23
22
  Requires-Dist: h5netcdf>=1.0.0
24
23
  Requires-Dist: h5py>=3.8.0
25
- Requires-Dist: matplotlib>=3.10.8
26
24
  Requires-Dist: numba>=0.60.0
27
25
  Requires-Dist: numpy>=1.24.0
28
- Requires-Dist: pandas>=3.0.1
29
26
  Requires-Dist: xarray>=2024.9.0
30
27
  Provides-Extra: all
31
28
  Requires-Dist: cfgrib>=0.9.15.1; extra == 'all'
@@ -53,15 +50,15 @@ Description-Content-Type: text/markdown
53
50
  [![Documentation Status](https://readthedocs.org/projects/pystormtracker/badge/?version=latest)](https://pystormtracker.readthedocs.io/en/latest/?badge=latest)
54
51
  [![codecov](https://codecov.io/github/mwyau/PyStormTracker/graph/badge.svg?token=JmTabGA3cq)](https://codecov.io/github/mwyau/PyStormTracker)
55
52
  [![PyPI version](https://img.shields.io/pypi/v/PyStormTracker)](https://pypi.org/project/PyStormTracker/)
56
- ![Python versions](https://img.shields.io/pypi/pyversions/PyStormTracker)
57
- ![License](https://img.shields.io/pypi/l/PyStormTracker)
53
+ [![Conda Version](https://img.shields.io/conda/vn/conda-forge/pystormtracker)](https://anaconda.org/channels/conda-forge/packages/pystormtracker/overview)
54
+ [![GitHub License](https://img.shields.io/github/license/mwyau/PyStormTracker)](https://github.com/mwyau/PyStormTracker/blob/main/LICENSE)
58
55
  [![Docker](https://img.shields.io/badge/docker-xddd%2Fpystormtracker-blue?logo=docker)](https://hub.docker.com/r/xddd/pystormtracker)
59
56
  [![GHCR](https://img.shields.io/badge/ghcr.io-xddd%2Fpystormtracker-blue?logo=github)](https://github.com/orgs/xddd/packages/container/package/pystormtracker)
60
57
  [![DOI](https://zenodo.org/badge/36328800.svg)](https://doi.org/10.5281/zenodo.18764813)
61
58
 
62
- **PyStormTracker** is a high-performance Python package for cyclone trajectory analysis. It implements the "Simple Tracker" algorithm and provides a scalable framework for processing large-scale climate datasets like ERA5.
59
+ **PyStormTracker** is a high-performance Python package for cyclone trajectory analysis. It implements the "Simple Tracker" algorithm described in **Yau and Chang (2020)** and provides a scalable framework for processing large-scale climate datasets like ERA5.
63
60
 
64
- The project is currently being expanded to include a Python port of the adaptive constraints tracking algorithm from **Hodges (1999)** and Accumulated Track Activity metrics.
61
+ The project is currently being expanded to include a Python port of the adaptive constraints tracking algorithm from **Hodges (1999)** (originally in C) and the Accumulated Track Activity metrics from **Yau and Chang (2020)** (originally in Matlab).
65
62
 
66
63
  Initially developed at the **National Center for Atmospheric Research (NCAR)** as part of the **2015 SIParCS** program, PyStormTracker leverages task-parallel strategies and tree reduction algorithms to efficiently process large-scale climate datasets.
67
64
 
@@ -78,7 +75,7 @@ Initially developed at the **National Center for Atmospheric Research (NCAR)** a
78
75
  - **Interoperable**: Full support for the standard **IMILAST** intercomparison format (`.txt`) with human-readable datetime strings.
79
76
 
80
77
  <p align="center">
81
- <img src="benchmark/benchmark_0_25x0_25_breakdown.png" width="600" alt="v0.4.0 Performance Improvements">
78
+ <img src="https://raw.githubusercontent.com/mwyau/PyStormTracker/main/benchmark/benchmark_0_25x0_25_breakdown.png" width="600" alt="v0.4.0 Performance Improvements">
82
79
  <br>
83
80
  <i>Significant performance gains in v0.4.0+ compared to the legacy v0.3.3 architecture on high-resolution ERA5 data.</i>
84
81
  </p>
@@ -100,17 +97,17 @@ Full documentation, including API references and advanced usage examples, is ava
100
97
  ### Prerequisites
101
98
  - Python 3.11+
102
99
  - (Optional) OpenMPI for MPI support.
103
- - **Windows Users**: the `eccodeslib` GRIB helper library is only required on Linux/macOS. (Note: GRIB/ecCodes support on Windows is currently experimental and untested).
100
+ - **Windows**: GRIB support is experimental and untested.
104
101
 
105
- ### From PyPI (Recommended)
102
+ ### From PyPI
106
103
  You can install the latest stable version of PyStormTracker directly from PyPI:
107
104
 
108
- Using `pip` (standard):
105
+ Using `pip`:
109
106
  ```bash
110
107
  pip install PyStormTracker
111
108
  ```
112
109
 
113
- Using `uv` (recommended):
110
+ Using `uv`:
114
111
  ```bash
115
112
  # For use as a CLI tool
116
113
  uv tool install PyStormTracker
@@ -119,8 +116,21 @@ uv tool install PyStormTracker
119
116
  uv add PyStormTracker
120
117
  ```
121
118
 
119
+ ### From Conda-Forge
120
+ You can also install PyStormTracker from `conda-forge`:
121
+
122
+ Using `mamba`:
123
+ ```bash
124
+ mamba install -c conda-forge pystormtracker
125
+ ```
126
+
127
+ Using `conda`:
128
+ ```bash
129
+ conda install -c conda-forge pystormtracker
130
+ ```
131
+
122
132
  ### From Source
123
- Install with `uv` (Recommended):
133
+ Install with `uv`:
124
134
  ```bash
125
135
  git clone https://github.com/mwyau/PyStormTracker.git
126
136
  cd PyStormTracker
@@ -188,7 +198,7 @@ Sample datasets for testing and benchmarking are hosted in the [PyStormTracker-D
188
198
  ## Development
189
199
 
190
200
  ### Setup
191
- Using `uv` is the recommended way to set up your environment:
201
+ Using `uv` to set up your development environment:
192
202
  ```bash
193
203
  # Install dependencies and sync virtual environment
194
204
  uv sync
@@ -208,6 +218,14 @@ uv run ruff format .
208
218
  uv run mypy src/
209
219
  ```
210
220
 
221
+ ### Git Hooks (Recommended)
222
+ You can set up a pre-push git hook to automatically run `ruff` linting and formatting checks before every `git push`. This ensures all code adheres to the project's quality standards before being shared.
223
+
224
+ To install the pre-push hook:
225
+ ```bash
226
+ printf '#!/bin/bash\nuv run ruff check . && uv run ruff format --check .' > .git/hooks/pre-push && chmod +x .git/hooks/pre-push
227
+ ```
228
+
211
229
  ### Tiered Testing
212
230
  To keep development cycles fast, testing is tiered:
213
231
  - **Fast Tests**: Default local runs (skips integration tests).
@@ -244,8 +262,8 @@ If you use this software in your research, please cite the following:
244
262
  - **Yau, A. M. W., K. Paul and J. Dennis**, 2016: PyStormTracker: A Parallel Object-Oriented Cyclone Tracker in Python. *96th American Meteorological Society Annual Meeting*, New Orleans, LA. *Zenodo*, [https://doi.org/10.5281/zenodo.18868625](https://doi.org/10.5281/zenodo.18868625).
245
263
 
246
264
  - **Neu, U., et al.**, 2013: IMILAST: A Community Effort to Intercompare Extratropical Cyclone Detection and Tracking Algorithms. *Bull. Amer. Meteor. Soc.*, **94**, 529–547, [https://doi.org/10.1175/BAMS-D-11-00154.1](https://doi.org/10.1175/BAMS-D-11-00154.1).
247
- - **IMILAST Intercomparison Protocol**: [https://proclim.scnat.ch/en/activities/project_imilast/intercomparison](https://proclim.scnat.ch/en/activities/project_imilast/intercomparison)
248
- - **IMILAST Data Download**: [https://proclim.scnat.ch/en/activities/project_imilast/data_download](https://proclim.scnat.ch/en/activities/project_imilast/data_download)
265
+ - IMILAST Intercomparison Protocol: [https://proclim.scnat.ch/en/activities/project_imilast/intercomparison](https://proclim.scnat.ch/en/activities/project_imilast/intercomparison)
266
+ - IMILAST Data Download: [https://proclim.scnat.ch/en/activities/project_imilast/data_download](https://proclim.scnat.ch/en/activities/project_imilast/data_download)
249
267
 
250
268
  - **Hodges, K. I.**, 1999: Adaptive Constraints for Feature Tracking. *Mon. Wea. Rev.*, **127**, 1362–1373, [https://doi.org/10.1175/1520-0493(1999)127<1362:ACFFT>2.0.CO;2](https://doi.org/10.1175/1520-0493(1999)127<1362:ACFFT>2.0.CO;2).
251
269
 
@@ -4,15 +4,15 @@
4
4
  [![Documentation Status](https://readthedocs.org/projects/pystormtracker/badge/?version=latest)](https://pystormtracker.readthedocs.io/en/latest/?badge=latest)
5
5
  [![codecov](https://codecov.io/github/mwyau/PyStormTracker/graph/badge.svg?token=JmTabGA3cq)](https://codecov.io/github/mwyau/PyStormTracker)
6
6
  [![PyPI version](https://img.shields.io/pypi/v/PyStormTracker)](https://pypi.org/project/PyStormTracker/)
7
- ![Python versions](https://img.shields.io/pypi/pyversions/PyStormTracker)
8
- ![License](https://img.shields.io/pypi/l/PyStormTracker)
7
+ [![Conda Version](https://img.shields.io/conda/vn/conda-forge/pystormtracker)](https://anaconda.org/channels/conda-forge/packages/pystormtracker/overview)
8
+ [![GitHub License](https://img.shields.io/github/license/mwyau/PyStormTracker)](https://github.com/mwyau/PyStormTracker/blob/main/LICENSE)
9
9
  [![Docker](https://img.shields.io/badge/docker-xddd%2Fpystormtracker-blue?logo=docker)](https://hub.docker.com/r/xddd/pystormtracker)
10
10
  [![GHCR](https://img.shields.io/badge/ghcr.io-xddd%2Fpystormtracker-blue?logo=github)](https://github.com/orgs/xddd/packages/container/package/pystormtracker)
11
11
  [![DOI](https://zenodo.org/badge/36328800.svg)](https://doi.org/10.5281/zenodo.18764813)
12
12
 
13
- **PyStormTracker** is a high-performance Python package for cyclone trajectory analysis. It implements the "Simple Tracker" algorithm and provides a scalable framework for processing large-scale climate datasets like ERA5.
13
+ **PyStormTracker** is a high-performance Python package for cyclone trajectory analysis. It implements the "Simple Tracker" algorithm described in **Yau and Chang (2020)** and provides a scalable framework for processing large-scale climate datasets like ERA5.
14
14
 
15
- The project is currently being expanded to include a Python port of the adaptive constraints tracking algorithm from **Hodges (1999)** and Accumulated Track Activity metrics.
15
+ The project is currently being expanded to include a Python port of the adaptive constraints tracking algorithm from **Hodges (1999)** (originally in C) and the Accumulated Track Activity metrics from **Yau and Chang (2020)** (originally in Matlab).
16
16
 
17
17
  Initially developed at the **National Center for Atmospheric Research (NCAR)** as part of the **2015 SIParCS** program, PyStormTracker leverages task-parallel strategies and tree reduction algorithms to efficiently process large-scale climate datasets.
18
18
 
@@ -29,7 +29,7 @@ Initially developed at the **National Center for Atmospheric Research (NCAR)** a
29
29
  - **Interoperable**: Full support for the standard **IMILAST** intercomparison format (`.txt`) with human-readable datetime strings.
30
30
 
31
31
  <p align="center">
32
- <img src="benchmark/benchmark_0_25x0_25_breakdown.png" width="600" alt="v0.4.0 Performance Improvements">
32
+ <img src="https://raw.githubusercontent.com/mwyau/PyStormTracker/main/benchmark/benchmark_0_25x0_25_breakdown.png" width="600" alt="v0.4.0 Performance Improvements">
33
33
  <br>
34
34
  <i>Significant performance gains in v0.4.0+ compared to the legacy v0.3.3 architecture on high-resolution ERA5 data.</i>
35
35
  </p>
@@ -51,17 +51,17 @@ Full documentation, including API references and advanced usage examples, is ava
51
51
  ### Prerequisites
52
52
  - Python 3.11+
53
53
  - (Optional) OpenMPI for MPI support.
54
- - **Windows Users**: the `eccodeslib` GRIB helper library is only required on Linux/macOS. (Note: GRIB/ecCodes support on Windows is currently experimental and untested).
54
+ - **Windows**: GRIB support is experimental and untested.
55
55
 
56
- ### From PyPI (Recommended)
56
+ ### From PyPI
57
57
  You can install the latest stable version of PyStormTracker directly from PyPI:
58
58
 
59
- Using `pip` (standard):
59
+ Using `pip`:
60
60
  ```bash
61
61
  pip install PyStormTracker
62
62
  ```
63
63
 
64
- Using `uv` (recommended):
64
+ Using `uv`:
65
65
  ```bash
66
66
  # For use as a CLI tool
67
67
  uv tool install PyStormTracker
@@ -70,8 +70,21 @@ uv tool install PyStormTracker
70
70
  uv add PyStormTracker
71
71
  ```
72
72
 
73
+ ### From Conda-Forge
74
+ You can also install PyStormTracker from `conda-forge`:
75
+
76
+ Using `mamba`:
77
+ ```bash
78
+ mamba install -c conda-forge pystormtracker
79
+ ```
80
+
81
+ Using `conda`:
82
+ ```bash
83
+ conda install -c conda-forge pystormtracker
84
+ ```
85
+
73
86
  ### From Source
74
- Install with `uv` (Recommended):
87
+ Install with `uv`:
75
88
  ```bash
76
89
  git clone https://github.com/mwyau/PyStormTracker.git
77
90
  cd PyStormTracker
@@ -139,7 +152,7 @@ Sample datasets for testing and benchmarking are hosted in the [PyStormTracker-D
139
152
  ## Development
140
153
 
141
154
  ### Setup
142
- Using `uv` is the recommended way to set up your environment:
155
+ Using `uv` to set up your development environment:
143
156
  ```bash
144
157
  # Install dependencies and sync virtual environment
145
158
  uv sync
@@ -159,6 +172,14 @@ uv run ruff format .
159
172
  uv run mypy src/
160
173
  ```
161
174
 
175
+ ### Git Hooks (Recommended)
176
+ You can set up a pre-push git hook to automatically run `ruff` linting and formatting checks before every `git push`. This ensures all code adheres to the project's quality standards before being shared.
177
+
178
+ To install the pre-push hook:
179
+ ```bash
180
+ printf '#!/bin/bash\nuv run ruff check . && uv run ruff format --check .' > .git/hooks/pre-push && chmod +x .git/hooks/pre-push
181
+ ```
182
+
162
183
  ### Tiered Testing
163
184
  To keep development cycles fast, testing is tiered:
164
185
  - **Fast Tests**: Default local runs (skips integration tests).
@@ -195,8 +216,8 @@ If you use this software in your research, please cite the following:
195
216
  - **Yau, A. M. W., K. Paul and J. Dennis**, 2016: PyStormTracker: A Parallel Object-Oriented Cyclone Tracker in Python. *96th American Meteorological Society Annual Meeting*, New Orleans, LA. *Zenodo*, [https://doi.org/10.5281/zenodo.18868625](https://doi.org/10.5281/zenodo.18868625).
196
217
 
197
218
  - **Neu, U., et al.**, 2013: IMILAST: A Community Effort to Intercompare Extratropical Cyclone Detection and Tracking Algorithms. *Bull. Amer. Meteor. Soc.*, **94**, 529–547, [https://doi.org/10.1175/BAMS-D-11-00154.1](https://doi.org/10.1175/BAMS-D-11-00154.1).
198
- - **IMILAST Intercomparison Protocol**: [https://proclim.scnat.ch/en/activities/project_imilast/intercomparison](https://proclim.scnat.ch/en/activities/project_imilast/intercomparison)
199
- - **IMILAST Data Download**: [https://proclim.scnat.ch/en/activities/project_imilast/data_download](https://proclim.scnat.ch/en/activities/project_imilast/data_download)
219
+ - IMILAST Intercomparison Protocol: [https://proclim.scnat.ch/en/activities/project_imilast/intercomparison](https://proclim.scnat.ch/en/activities/project_imilast/intercomparison)
220
+ - IMILAST Data Download: [https://proclim.scnat.ch/en/activities/project_imilast/data_download](https://proclim.scnat.ch/en/activities/project_imilast/data_download)
200
221
 
201
222
  - **Hodges, K. I.**, 1999: Adaptive Constraints for Feature Tracking. *Mon. Wea. Rev.*, **127**, 1362–1373, [https://doi.org/10.1175/1520-0493(1999)127<1362:ACFFT>2.0.CO;2](https://doi.org/10.1175/1520-0493(1999)127<1362:ACFFT>2.0.CO;2).
202
223
 
@@ -39,3 +39,7 @@ This document outlines the strategic plan for improving PyStormTracker's perform
39
39
  * **Complete `HodgesTracker`:**
40
40
  * *Current State:* Scaffolding added.
41
41
  * *Action:* Integrate spherical distance math (e.g., `haversine` or Numba-compiled Vincenty formula). For track optimization (cost function minimization), port the original C logic using `scipy.optimize.linear_sum_assignment` which perfectly maps to the tracking assignment problem.
42
+ * **Preprocessing (Spherical Harmonics Filtering):**
43
+ * *Action:* Add support for spectral filtering (e.g., T42/T63 truncation) using `pyshtools` to remove small-scale noise from high-resolution fields before tracking.
44
+ * **Postprocessing (Track Metrics):**
45
+ * *Action:* Implement Accumulated Track Activity (ATA) and other storm track metrics from **Yau and Chang (2020)** to provide physically meaningful analysis of detected trajectories.
@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
4
4
 
5
5
  [project]
6
6
  name = "PyStormTracker"
7
- version = "0.4.0"
7
+ version = "0.4.2"
8
8
  description = "A High-Performance Cyclone Tracker in Python"
9
9
  readme = "README.md"
10
10
  license = {text = "BSD-3-Clause"}
@@ -25,14 +25,12 @@ classifiers = [
25
25
  ]
26
26
  dependencies = [
27
27
  "dask>=2024.1.0",
28
- "distributed>=2024.1.0",
28
+
29
29
  "h5netcdf>=1.0.0",
30
30
  "h5py>=3.8.0",
31
31
  "numpy>=1.24.0",
32
32
  "numba>=0.60.0",
33
33
  "xarray>=2024.9.0",
34
- "matplotlib>=3.10.8",
35
- "pandas>=3.0.1",
36
34
  ]
37
35
 
38
36
  [project.scripts]
@@ -84,6 +82,8 @@ dev = [
84
82
  "pytest>=9.0.2",
85
83
  "pytest-cov>=7.0.0",
86
84
  "ruff>=0.15.5",
85
+ "matplotlib>=3.10.8",
86
+ "pandas>=3.0.1",
87
87
  ]
88
88
 
89
89
  [tool.ruff]
@@ -122,9 +122,6 @@ addopts = "-ra -q --durations=0"
122
122
  testpaths = [
123
123
  "tests",
124
124
  ]
125
- markers = [
126
- "integration: marks tests as integration (skipped by default, run with --run-integration)",
127
- ]
128
125
  filterwarnings = [
129
126
  "ignore:numpy.ndarray size changed:RuntimeWarning",
130
127
  ]
@@ -7,7 +7,7 @@ from .simple import SimpleDetector, SimpleLinker, SimpleTracker
7
7
  try:
8
8
  __version__ = version("pystormtracker")
9
9
  except PackageNotFoundError:
10
- __version__ = "0.4.0"
10
+ __version__ = "0.4.2"
11
11
 
12
12
  __all__ = [
13
13
  "Center",
@@ -22,6 +22,7 @@ def run_tracker(
22
22
  mode: Literal["min", "max"] = "min",
23
23
  backend: Backend = "serial",
24
24
  n_workers: int | None = None,
25
+ max_chunk_size: int | None = None,
25
26
  threshold: float | None = None,
26
27
  engine: str | None = None,
27
28
  ) -> None:
@@ -49,6 +50,7 @@ def run_tracker(
49
50
  mode=mode,
50
51
  backend=backend,
51
52
  n_workers=n_workers,
53
+ max_chunk_size=max_chunk_size,
52
54
  threshold=threshold,
53
55
  engine=engine,
54
56
  )
@@ -77,7 +79,9 @@ def run_tracker(
77
79
 
78
80
  def parse_args() -> Namespace:
79
81
  """Parses command line arguments."""
80
- parser = ArgumentParser(description="PyStormTracker: A tool for tracking storms.")
82
+ parser = ArgumentParser(
83
+ description="PyStormTracker: A High-Performance Cyclone Tracker in Python"
84
+ )
81
85
  parser.add_argument("-i", "--input", required=True, help="Input NetCDF file.")
82
86
  parser.add_argument("-v", "--var", required=True, help="Variable to track.")
83
87
  parser.add_argument(
@@ -104,6 +108,13 @@ def parse_args() -> Namespace:
104
108
  default=None,
105
109
  help="Number of workers for Dask. Defaults to number of CPU cores.",
106
110
  )
111
+ parser.add_argument(
112
+ "-c",
113
+ "--chunk-size",
114
+ type=int,
115
+ default=60,
116
+ help="Maximum time steps per chunk for Dask. Defaults to 60.",
117
+ )
107
118
  parser.add_argument(
108
119
  "-e",
109
120
  "--engine",
@@ -139,6 +150,7 @@ def main() -> None:
139
150
  mode=args.mode,
140
151
  backend=args.backend,
141
152
  n_workers=args.workers,
153
+ max_chunk_size=args.chunk_size,
142
154
  threshold=args.threshold,
143
155
  engine=args.engine,
144
156
  )
@@ -18,56 +18,57 @@ def run_simple_dask(
18
18
  time_range: TimeRange | None,
19
19
  mode: Literal["min", "max"],
20
20
  n_workers: int | None,
21
+ max_chunk_size: int | None = None,
21
22
  threshold: float | None = None,
22
23
  engine: str | None = None,
23
24
  ) -> Tracks:
24
- from dask.distributed import Client, LocalCluster
25
+ import dask
25
26
 
26
27
  if n_workers is None or n_workers <= 0:
27
- n_workers = os.cpu_count() or 4
28
+ n_workers = min(os.cpu_count() or 1, 4)
28
29
 
29
30
  detector_obj = SimpleDetector(
30
31
  pathname=infile, varname=varname, time_range=time_range, engine=engine
31
32
  )
32
- detectors = detector_obj.split(n_workers)
33
+
34
+ # Decouple task chunks from worker count to prevent OOM on high-res data.
35
+ # We aim to split the total dataset evenly among the workers.
36
+ times = detector_obj.get_time()
37
+ total_steps = len(times) if times is not None else 1
38
+
39
+ if max_chunk_size is None or max_chunk_size <= 0:
40
+ max_chunk_size = 60
41
+ else:
42
+ max_chunk_size = max(1, max_chunk_size)
43
+
44
+ # Ensure we at least split into n_workers tasks
45
+ n_splits = max(n_workers, (total_steps + max_chunk_size - 1) // max_chunk_size)
46
+
47
+ detectors = detector_obj.split(n_splits)
33
48
 
34
49
  t0 = timeit.default_timer()
35
- # Use processes=True to ensure Xarray/HDF5 locking doesn't serialize I/O
36
- with (
37
- LocalCluster(
38
- n_workers=n_workers,
39
- threads_per_worker=1,
40
- processes=True,
41
- dashboard_address=None,
42
- ) as cluster,
43
- Client(cluster) as client,
44
- ):
45
- t1 = timeit.default_timer()
46
- print(f" [Dask] Cluster setup time: {t1 - t0:.4f}s")
47
-
48
- futures = []
49
- for d in detectors:
50
- futures.append(
51
- client.submit(
52
- _detect_and_link,
53
- d,
54
- 5,
55
- threshold,
56
- mode,
57
- )
58
- )
59
-
60
- # Gather results from all workers
61
- all_raw_chunks: list[list[RawDetectionStep]] = client.gather(futures)
62
-
63
- # Flatten chunks into a single sequence of steps
64
- # They are gathered in the order of the futures list (sorted by split)
65
- all_raw_steps: list[RawDetectionStep] = [
66
- step for chunk in all_raw_chunks for step in chunk
67
- ]
50
+ t1 = timeit.default_timer()
51
+ print(f" [Dask] Setup time: {t1 - t0:.4f}s")
52
+ print(
53
+ f" [Dask] Splitting {total_steps} steps into {n_splits} "
54
+ f"tasks (across {n_workers} threads)"
55
+ )
56
+
57
+ tasks = [
58
+ dask.delayed(_detect_and_link)(d, 5, threshold, mode) # type: ignore[attr-defined]
59
+ for d in detectors
60
+ ]
61
+
62
+ all_raw_chunks = dask.compute(*tasks, scheduler="threads", num_workers=n_workers) # type: ignore[attr-defined]
63
+
64
+ # Flatten chunks into a single sequence of steps
65
+ # They are gathered in the order of the futures list (sorted by split)
66
+ all_raw_steps: list[RawDetectionStep] = [
67
+ step for chunk in all_raw_chunks for step in chunk
68
+ ]
68
69
 
69
- t2 = timeit.default_timer()
70
- print(f" [Dask] Task execution & gather time: {t2 - t1:.4f}s")
70
+ t2 = timeit.default_timer()
71
+ print(f" [Dask] Task execution & gather time: {t2 - t1:.4f}s")
71
72
 
72
73
  # Centralized linking guarantees bit-wise identity with Serial
73
74
  t3 = timeit.default_timer()
@@ -75,6 +75,7 @@ class SimpleTracker:
75
75
  mode: Literal["min", "max"] = "min",
76
76
  backend: Literal["serial", "mpi", "dask"] = "serial",
77
77
  n_workers: int | None = None,
78
+ max_chunk_size: int | None = None,
78
79
  threshold: float | None = None,
79
80
  engine: str | None = None,
80
81
  ) -> Tracks:
@@ -109,6 +110,7 @@ class SimpleTracker:
109
110
  time_range,
110
111
  mode,
111
112
  n_workers,
113
+ max_chunk_size=max_chunk_size,
112
114
  threshold=threshold,
113
115
  engine=engine,
114
116
  )
@@ -15,6 +15,14 @@ def pytest_addoption(parser: pytest.Parser) -> None:
15
15
  )
16
16
 
17
17
 
18
+ def pytest_configure(config: pytest.Config) -> None:
19
+ config.addinivalue_line(
20
+ "markers",
21
+ "integration: marks tests as integration "
22
+ "(skipped by default, run with --run-integration)",
23
+ )
24
+
25
+
18
26
  def pytest_collection_modifyitems(
19
27
  config: pytest.Config, items: list[pytest.Item]
20
28
  ) -> None: