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.
- {pystormtracker-0.4.0 → pystormtracker-0.4.2}/.github/workflows/ci.yml +0 -2
- {pystormtracker-0.4.0 → pystormtracker-0.4.2}/.github/workflows/docker-publish.yml +14 -10
- {pystormtracker-0.4.0 → pystormtracker-0.4.2}/.github/workflows/python-publish.yml +2 -0
- {pystormtracker-0.4.0 → pystormtracker-0.4.2}/CITATION.cff +2 -2
- {pystormtracker-0.4.0 → pystormtracker-0.4.2}/PKG-INFO +35 -17
- {pystormtracker-0.4.0 → pystormtracker-0.4.2}/README.md +34 -13
- {pystormtracker-0.4.0 → pystormtracker-0.4.2}/ROADMAP.md +4 -0
- {pystormtracker-0.4.0 → pystormtracker-0.4.2}/pyproject.toml +4 -7
- {pystormtracker-0.4.0 → pystormtracker-0.4.2}/src/pystormtracker/__init__.py +1 -1
- {pystormtracker-0.4.0 → pystormtracker-0.4.2}/src/pystormtracker/cli.py +13 -1
- {pystormtracker-0.4.0 → pystormtracker-0.4.2}/src/pystormtracker/simple/concurrent.py +39 -38
- {pystormtracker-0.4.0 → pystormtracker-0.4.2}/src/pystormtracker/simple/tracker.py +2 -0
- {pystormtracker-0.4.0 → pystormtracker-0.4.2}/tests/conftest.py +8 -0
- {pystormtracker-0.4.0 → pystormtracker-0.4.2}/uv.lock +275 -412
- {pystormtracker-0.4.0 → pystormtracker-0.4.2}/.dockerignore +0 -0
- {pystormtracker-0.4.0 → pystormtracker-0.4.2}/.github/dependabot.yml +0 -0
- {pystormtracker-0.4.0 → pystormtracker-0.4.2}/.gitignore +0 -0
- {pystormtracker-0.4.0 → pystormtracker-0.4.2}/.python-version +0 -0
- {pystormtracker-0.4.0 → pystormtracker-0.4.2}/.readthedocs.yaml +0 -0
- {pystormtracker-0.4.0 → pystormtracker-0.4.2}/ARCHITECTURE.md +0 -0
- {pystormtracker-0.4.0 → pystormtracker-0.4.2}/Dockerfile +0 -0
- {pystormtracker-0.4.0 → pystormtracker-0.4.2}/LICENSE +0 -0
- {pystormtracker-0.4.0 → pystormtracker-0.4.2}/codecov.yml +0 -0
- {pystormtracker-0.4.0 → pystormtracker-0.4.2}/data/test/tracks/era5_msl_2.5x2.5_v0.0.2_imilast.txt +0 -0
- {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
- {pystormtracker-0.4.0 → pystormtracker-0.4.2}/docs/IntercomparisonProtocol.pdf +0 -0
- {pystormtracker-0.4.0 → pystormtracker-0.4.2}/docs/architecture.md +0 -0
- {pystormtracker-0.4.0 → pystormtracker-0.4.2}/docs/benchmark.md +0 -0
- {pystormtracker-0.4.0 → pystormtracker-0.4.2}/docs/conf.py +0 -0
- {pystormtracker-0.4.0 → pystormtracker-0.4.2}/docs/index.md +0 -0
- {pystormtracker-0.4.0 → pystormtracker-0.4.2}/docs/readme.md +0 -0
- {pystormtracker-0.4.0 → pystormtracker-0.4.2}/docs/roadmap.md +0 -0
- {pystormtracker-0.4.0 → pystormtracker-0.4.2}/src/pystormtracker/hodges/__init__.py +0 -0
- {pystormtracker-0.4.0 → pystormtracker-0.4.2}/src/pystormtracker/hodges/tracker.py +0 -0
- {pystormtracker-0.4.0 → pystormtracker-0.4.2}/src/pystormtracker/io/__init__.py +0 -0
- {pystormtracker-0.4.0 → pystormtracker-0.4.2}/src/pystormtracker/io/imilast.py +0 -0
- {pystormtracker-0.4.0 → pystormtracker-0.4.2}/src/pystormtracker/io/loader.py +0 -0
- {pystormtracker-0.4.0 → pystormtracker-0.4.2}/src/pystormtracker/models/__init__.py +0 -0
- {pystormtracker-0.4.0 → pystormtracker-0.4.2}/src/pystormtracker/models/center.py +0 -0
- {pystormtracker-0.4.0 → pystormtracker-0.4.2}/src/pystormtracker/models/tracker.py +0 -0
- {pystormtracker-0.4.0 → pystormtracker-0.4.2}/src/pystormtracker/models/tracks.py +0 -0
- {pystormtracker-0.4.0 → pystormtracker-0.4.2}/src/pystormtracker/simple/__init__.py +0 -0
- {pystormtracker-0.4.0 → pystormtracker-0.4.2}/src/pystormtracker/simple/detector.py +0 -0
- {pystormtracker-0.4.0 → pystormtracker-0.4.2}/src/pystormtracker/simple/kernels.py +0 -0
- {pystormtracker-0.4.0 → pystormtracker-0.4.2}/src/pystormtracker/simple/linker.py +0 -0
- {pystormtracker-0.4.0 → pystormtracker-0.4.2}/src/pystormtracker/utils/__init__.py +0 -0
- {pystormtracker-0.4.0 → pystormtracker-0.4.2}/src/pystormtracker/utils/benchmark.py +0 -0
- {pystormtracker-0.4.0 → pystormtracker-0.4.2}/src/pystormtracker/utils/data_utils.py +0 -0
- {pystormtracker-0.4.0 → pystormtracker-0.4.2}/tests/__init__.py +0 -0
- {pystormtracker-0.4.0 → pystormtracker-0.4.2}/tests/test_center.py +0 -0
- {pystormtracker-0.4.0 → pystormtracker-0.4.2}/tests/test_cli.py +0 -0
- {pystormtracker-0.4.0 → pystormtracker-0.4.2}/tests/test_integration.py +0 -0
- {pystormtracker-0.4.0 → pystormtracker-0.4.2}/tests/test_simple_detector.py +0 -0
- {pystormtracker-0.4.0 → pystormtracker-0.4.2}/tests/test_simple_linker.py +0 -0
- {pystormtracker-0.4.0 → pystormtracker-0.4.2}/tests/test_simple_tracker.py +0 -0
- {pystormtracker-0.4.0 → pystormtracker-0.4.2}/tests/test_tracks.py +0 -0
|
@@ -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:
|
|
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 == '
|
|
16
|
-
GHCR_REPO: ghcr.io/${{ (github.event_name == 'release' || (github.event_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=
|
|
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=
|
|
77
|
-
type=semver,pattern={{major}}.{{minor}},priority=
|
|
78
|
-
type=semver,pattern={{major}},enable=${{ !startsWith(github.ref_name, 'v0') }},priority=
|
|
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
|
|
@@ -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.
|
|
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.
|
|
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
|
[](https://pystormtracker.readthedocs.io/en/latest/?badge=latest)
|
|
54
51
|
[](https://codecov.io/github/mwyau/PyStormTracker)
|
|
55
52
|
[](https://pypi.org/project/PyStormTracker/)
|
|
56
|
-
](https://anaconda.org/channels/conda-forge/packages/pystormtracker/overview)
|
|
54
|
+
[](https://github.com/mwyau/PyStormTracker/blob/main/LICENSE)
|
|
58
55
|
[](https://hub.docker.com/r/xddd/pystormtracker)
|
|
59
56
|
[](https://github.com/orgs/xddd/packages/container/package/pystormtracker)
|
|
60
57
|
[](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
|
|
100
|
+
- **Windows**: GRIB support is experimental and untested.
|
|
104
101
|
|
|
105
|
-
### From PyPI
|
|
102
|
+
### From PyPI
|
|
106
103
|
You can install the latest stable version of PyStormTracker directly from PyPI:
|
|
107
104
|
|
|
108
|
-
Using `pip
|
|
105
|
+
Using `pip`:
|
|
109
106
|
```bash
|
|
110
107
|
pip install PyStormTracker
|
|
111
108
|
```
|
|
112
109
|
|
|
113
|
-
Using `uv
|
|
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
|
|
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`
|
|
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
|
-
-
|
|
248
|
-
-
|
|
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
|
[](https://pystormtracker.readthedocs.io/en/latest/?badge=latest)
|
|
5
5
|
[](https://codecov.io/github/mwyau/PyStormTracker)
|
|
6
6
|
[](https://pypi.org/project/PyStormTracker/)
|
|
7
|
-
](https://anaconda.org/channels/conda-forge/packages/pystormtracker/overview)
|
|
8
|
+
[](https://github.com/mwyau/PyStormTracker/blob/main/LICENSE)
|
|
9
9
|
[](https://hub.docker.com/r/xddd/pystormtracker)
|
|
10
10
|
[](https://github.com/orgs/xddd/packages/container/package/pystormtracker)
|
|
11
11
|
[](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
|
|
54
|
+
- **Windows**: GRIB support is experimental and untested.
|
|
55
55
|
|
|
56
|
-
### From PyPI
|
|
56
|
+
### From PyPI
|
|
57
57
|
You can install the latest stable version of PyStormTracker directly from PyPI:
|
|
58
58
|
|
|
59
|
-
Using `pip
|
|
59
|
+
Using `pip`:
|
|
60
60
|
```bash
|
|
61
61
|
pip install PyStormTracker
|
|
62
62
|
```
|
|
63
63
|
|
|
64
|
-
Using `uv
|
|
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
|
|
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`
|
|
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
|
-
-
|
|
199
|
-
-
|
|
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.
|
|
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
|
-
|
|
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
|
]
|
|
@@ -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(
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
36
|
-
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
|
|
45
|
-
|
|
46
|
-
|
|
47
|
-
|
|
48
|
-
|
|
49
|
-
|
|
50
|
-
|
|
51
|
-
|
|
52
|
-
|
|
53
|
-
|
|
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
|
-
|
|
70
|
-
|
|
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:
|