PyStormTracker 0.4.1__tar.gz → 0.5.0__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 (150) hide show
  1. pystormtracker-0.5.0/.gitattributes +17 -0
  2. {pystormtracker-0.4.1 → pystormtracker-0.5.0}/.github/workflows/ci.yml +69 -83
  3. pystormtracker-0.5.0/.github/workflows/docker-publish.yml +158 -0
  4. {pystormtracker-0.4.1 → pystormtracker-0.5.0}/.github/workflows/python-publish.yml +47 -18
  5. {pystormtracker-0.4.1 → pystormtracker-0.5.0}/.gitignore +1 -0
  6. pystormtracker-0.5.0/AGENTS.md +20 -0
  7. {pystormtracker-0.4.1 → pystormtracker-0.5.0}/CITATION.cff +3 -3
  8. pystormtracker-0.5.0/CONTRIBUTING.md +51 -0
  9. {pystormtracker-0.4.1 → pystormtracker-0.5.0}/Dockerfile +10 -3
  10. pystormtracker-0.5.0/PKG-INFO +325 -0
  11. pystormtracker-0.5.0/README.md +266 -0
  12. pystormtracker-0.5.0/data/adapt.dat +2 -0
  13. pystormtracker-0.5.0/data/test/era5/era5_msl_2025120100_0.25x0.25.nc +0 -0
  14. pystormtracker-0.5.0/data/test/era5/era5_msl_2025120100_0.25x0.25_t0-42_ncl.nc +0 -0
  15. pystormtracker-0.5.0/data/test/era5/era5_msl_2025120100_0.25x0.25_t5-42_ncl.nc +0 -0
  16. pystormtracker-0.5.0/data/test/era5/era5_msl_2025120100_2.5x2.5.nc +0 -0
  17. pystormtracker-0.5.0/data/test/era5/era5_msl_2025120100_2.5x2.5_t0-42_ncl.nc +0 -0
  18. pystormtracker-0.5.0/data/test/era5/era5_msl_2025120100_2.5x2.5_t5-42_ncl.nc +0 -0
  19. pystormtracker-0.5.0/data/test/era5/era5_sfvp850_2025120100_0.25x0.25_ncl.nc +0 -0
  20. pystormtracker-0.5.0/data/test/era5/era5_sfvp850_2025120100_2.5x2.5_ncl.nc +0 -0
  21. pystormtracker-0.5.0/data/test/era5/era5_uv850_2025120100_0.25x0.25.nc +0 -0
  22. pystormtracker-0.5.0/data/test/era5/era5_uv850_2025120100_2.5x2.5.nc +0 -0
  23. pystormtracker-0.5.0/data/test/era5/era5_vo850_2025120100_0.25x0.25.nc +0 -0
  24. pystormtracker-0.5.0/data/test/era5/era5_vo850_2025120100_2.5x2.5.nc +0 -0
  25. pystormtracker-0.5.0/data/test/era5/era5_vodv850_2025120100_0.25x0.25_ncl.nc +0 -0
  26. pystormtracker-0.5.0/data/test/era5/era5_vodv850_2025120100_2.5x2.5_ncl.nc +0 -0
  27. pystormtracker-0.5.0/data/test/era5/process_era5.ncl +230 -0
  28. pystormtracker-0.5.0/data/test/tracks/era5_msl_2025-2026_djf_2.5x2.5_hodges.txt +28904 -0
  29. pystormtracker-0.5.0/data/test/tracks/era5_msl_2025-2026_djf_2.5x2.5_hodges_imilast.txt +25968 -0
  30. pystormtracker-0.4.1/data/test/tracks/era5_msl_2.5x2.5_v0.0.2_imilast.txt → pystormtracker-0.5.0/data/test/tracks/era5_msl_2025-2026_djf_2.5x2.5_v0.0.2_imilast.txt +1 -1
  31. pystormtracker-0.4.1/data/test/tracks/era5_vo_2.5x2.5_1e-4_v0.0.2_imilast.txt → pystormtracker-0.5.0/data/test/tracks/era5_vo_2025-2026_djf_2.5x2.5_1e-4_v0.0.2_imilast.txt +1 -1
  32. pystormtracker-0.5.0/data/zone.dat +4 -0
  33. pystormtracker-0.5.0/docs/_static/benchmark_0_25x0_25_breakdown.png +0 -0
  34. pystormtracker-0.5.0/docs/_static/benchmark_2_5x2_5_breakdown.png +0 -0
  35. pystormtracker-0.5.0/docs/_static/era5_msl_nh.png +0 -0
  36. pystormtracker-0.5.0/docs/_static/explorer.html +1377 -0
  37. pystormtracker-0.5.0/docs/_static/explorer.tracks.js +1 -0
  38. pystormtracker-0.4.1/ARCHITECTURE.md → pystormtracker-0.5.0/docs/architecture.md +29 -18
  39. pystormtracker-0.5.0/docs/benchmark.md +50 -0
  40. pystormtracker-0.5.0/docs/changelog.md +152 -0
  41. {pystormtracker-0.4.1 → pystormtracker-0.5.0}/docs/conf.py +2 -1
  42. pystormtracker-0.5.0/docs/healpix.md +62 -0
  43. pystormtracker-0.5.0/docs/hodges.md +124 -0
  44. pystormtracker-0.5.0/docs/index.md +37 -0
  45. pystormtracker-0.5.0/docs/interactive.md +17 -0
  46. {pystormtracker-0.4.1 → pystormtracker-0.5.0}/docs/readme.md +1 -0
  47. pystormtracker-0.5.0/docs/roadmap.md +63 -0
  48. pystormtracker-0.5.0/docs/spectral_accuracy.md +71 -0
  49. pystormtracker-0.5.0/notebooks/interactive_tracks.ipynb +1448 -0
  50. {pystormtracker-0.4.1 → pystormtracker-0.5.0}/pyproject.toml +27 -17
  51. {pystormtracker-0.4.1 → pystormtracker-0.5.0}/src/pystormtracker/__init__.py +7 -2
  52. pystormtracker-0.5.0/src/pystormtracker/cli.py +532 -0
  53. pystormtracker-0.5.0/src/pystormtracker/convert.py +146 -0
  54. pystormtracker-0.5.0/src/pystormtracker/healpix/__init__.py +6 -0
  55. pystormtracker-0.5.0/src/pystormtracker/healpix/detector.py +305 -0
  56. pystormtracker-0.5.0/src/pystormtracker/healpix/kernels.py +250 -0
  57. pystormtracker-0.5.0/src/pystormtracker/healpix/tracker.py +231 -0
  58. pystormtracker-0.5.0/src/pystormtracker/hodges/constants.py +41 -0
  59. pystormtracker-0.5.0/src/pystormtracker/hodges/detector.py +222 -0
  60. pystormtracker-0.5.0/src/pystormtracker/hodges/kernels.py +837 -0
  61. pystormtracker-0.5.0/src/pystormtracker/hodges/linker.py +304 -0
  62. pystormtracker-0.5.0/src/pystormtracker/hodges/tracker.py +385 -0
  63. pystormtracker-0.5.0/src/pystormtracker/io/__init__.py +3 -0
  64. pystormtracker-0.5.0/src/pystormtracker/io/data_loader.py +171 -0
  65. pystormtracker-0.5.0/src/pystormtracker/io/hodges.py +41 -0
  66. {pystormtracker-0.4.1 → pystormtracker-0.5.0}/src/pystormtracker/io/imilast.py +49 -7
  67. pystormtracker-0.5.0/src/pystormtracker/io/json.py +220 -0
  68. pystormtracker-0.5.0/src/pystormtracker/models/constants.py +20 -0
  69. pystormtracker-0.5.0/src/pystormtracker/models/geo.py +74 -0
  70. pystormtracker-0.5.0/src/pystormtracker/models/tracker.py +51 -0
  71. {pystormtracker-0.4.1 → pystormtracker-0.5.0}/src/pystormtracker/models/tracks.py +11 -1
  72. pystormtracker-0.5.0/src/pystormtracker/preprocessing/__init__.py +14 -0
  73. pystormtracker-0.5.0/src/pystormtracker/preprocessing/kinematics.py +284 -0
  74. pystormtracker-0.5.0/src/pystormtracker/preprocessing/regrid.py +266 -0
  75. pystormtracker-0.5.0/src/pystormtracker/preprocessing/spectral.py +306 -0
  76. pystormtracker-0.5.0/src/pystormtracker/preprocessing/taper.py +118 -0
  77. pystormtracker-0.5.0/src/pystormtracker/simple/concurrent.py +172 -0
  78. {pystormtracker-0.4.1 → pystormtracker-0.5.0}/src/pystormtracker/simple/detector.py +69 -25
  79. {pystormtracker-0.4.1 → pystormtracker-0.5.0}/src/pystormtracker/simple/linker.py +7 -3
  80. pystormtracker-0.5.0/src/pystormtracker/simple/tracker.py +306 -0
  81. pystormtracker-0.5.0/src/pystormtracker/templates/explorer.html +1377 -0
  82. {pystormtracker-0.4.1 → pystormtracker-0.5.0}/tests/conftest.py +6 -0
  83. pystormtracker-0.5.0/tests/integration/test_hodges.py +118 -0
  84. pystormtracker-0.4.1/tests/test_integration.py → pystormtracker-0.5.0/tests/integration/test_simple.py +24 -7
  85. pystormtracker-0.5.0/tests/integration/test_spectral.py +134 -0
  86. pystormtracker-0.5.0/tests/integration/test_vorticity.py +49 -0
  87. pystormtracker-0.5.0/tests/testing_utils.py +174 -0
  88. pystormtracker-0.5.0/tests/unit/__init__.py +0 -0
  89. pystormtracker-0.5.0/tests/unit/healpix/__init__.py +0 -0
  90. pystormtracker-0.5.0/tests/unit/healpix/test_detector.py +75 -0
  91. pystormtracker-0.5.0/tests/unit/healpix/test_kernels.py +109 -0
  92. pystormtracker-0.5.0/tests/unit/healpix/test_tracker.py +26 -0
  93. pystormtracker-0.5.0/tests/unit/hodges/__init__.py +0 -0
  94. pystormtracker-0.5.0/tests/unit/hodges/test_detector.py +67 -0
  95. pystormtracker-0.5.0/tests/unit/hodges/test_kernels.py +88 -0
  96. pystormtracker-0.5.0/tests/unit/hodges/test_linker.py +119 -0
  97. pystormtracker-0.5.0/tests/unit/hodges/test_tracker.py +101 -0
  98. pystormtracker-0.5.0/tests/unit/io/__init__.py +0 -0
  99. pystormtracker-0.5.0/tests/unit/io/test_data_loader.py +142 -0
  100. pystormtracker-0.5.0/tests/unit/io/test_imilast.py +108 -0
  101. pystormtracker-0.5.0/tests/unit/models/__init__.py +0 -0
  102. pystormtracker-0.5.0/tests/unit/models/test_geo.py +44 -0
  103. {pystormtracker-0.4.1/tests → pystormtracker-0.5.0/tests/unit/models}/test_tracks.py +28 -19
  104. pystormtracker-0.5.0/tests/unit/preprocessing/__init__.py +0 -0
  105. pystormtracker-0.5.0/tests/unit/preprocessing/test_kinematics.py +140 -0
  106. pystormtracker-0.5.0/tests/unit/preprocessing/test_regrid.py +147 -0
  107. pystormtracker-0.5.0/tests/unit/preprocessing/test_spectral.py +109 -0
  108. pystormtracker-0.5.0/tests/unit/simple/__init__.py +0 -0
  109. pystormtracker-0.5.0/tests/unit/simple/test_detector.py +61 -0
  110. pystormtracker-0.5.0/tests/unit/simple/test_kernels.py +86 -0
  111. pystormtracker-0.4.1/tests/test_simple_linker.py → pystormtracker-0.5.0/tests/unit/simple/test_linker.py +11 -2
  112. {pystormtracker-0.4.1/tests → pystormtracker-0.5.0/tests/unit}/test_cli.py +2 -1
  113. pystormtracker-0.5.0/tests/unit/test_cli_dat_files.py +98 -0
  114. pystormtracker-0.5.0/tests/unit/test_testing_utils.py +73 -0
  115. pystormtracker-0.5.0/uv.lock +4495 -0
  116. pystormtracker-0.4.1/.github/workflows/docker-publish.yml +0 -119
  117. pystormtracker-0.4.1/PKG-INFO +0 -252
  118. pystormtracker-0.4.1/README.md +0 -205
  119. pystormtracker-0.4.1/ROADMAP.md +0 -45
  120. pystormtracker-0.4.1/docs/architecture.md +0 -2
  121. pystormtracker-0.4.1/docs/benchmark.md +0 -2
  122. pystormtracker-0.4.1/docs/index.md +0 -27
  123. pystormtracker-0.4.1/docs/roadmap.md +0 -2
  124. pystormtracker-0.4.1/src/pystormtracker/cli.py +0 -148
  125. pystormtracker-0.4.1/src/pystormtracker/hodges/tracker.py +0 -33
  126. pystormtracker-0.4.1/src/pystormtracker/io/loader.py +0 -72
  127. pystormtracker-0.4.1/src/pystormtracker/models/tracker.py +0 -27
  128. pystormtracker-0.4.1/src/pystormtracker/simple/concurrent.py +0 -131
  129. pystormtracker-0.4.1/src/pystormtracker/simple/tracker.py +0 -130
  130. pystormtracker-0.4.1/src/pystormtracker/utils/benchmark.py +0 -52
  131. pystormtracker-0.4.1/src/pystormtracker/utils/data_utils.py +0 -88
  132. pystormtracker-0.4.1/tests/__init__.py +0 -1
  133. pystormtracker-0.4.1/tests/test_simple_detector.py +0 -52
  134. pystormtracker-0.4.1/uv.lock +0 -2342
  135. {pystormtracker-0.4.1 → pystormtracker-0.5.0}/.dockerignore +0 -0
  136. {pystormtracker-0.4.1 → pystormtracker-0.5.0}/.github/dependabot.yml +0 -0
  137. {pystormtracker-0.4.1 → pystormtracker-0.5.0}/.python-version +0 -0
  138. {pystormtracker-0.4.1 → pystormtracker-0.5.0}/.readthedocs.yaml +0 -0
  139. {pystormtracker-0.4.1 → pystormtracker-0.5.0}/LICENSE +0 -0
  140. {pystormtracker-0.4.1 → pystormtracker-0.5.0}/codecov.yml +0 -0
  141. {pystormtracker-0.4.1/docs → pystormtracker-0.5.0/docs/_static}/IntercomparisonProtocol.pdf +0 -0
  142. {pystormtracker-0.4.1 → pystormtracker-0.5.0}/src/pystormtracker/hodges/__init__.py +0 -0
  143. {pystormtracker-0.4.1 → pystormtracker-0.5.0}/src/pystormtracker/models/__init__.py +0 -0
  144. {pystormtracker-0.4.1 → pystormtracker-0.5.0}/src/pystormtracker/models/center.py +0 -0
  145. /pystormtracker-0.4.1/src/pystormtracker/io/__init__.py → /pystormtracker-0.5.0/src/pystormtracker/py.typed +0 -0
  146. {pystormtracker-0.4.1 → pystormtracker-0.5.0}/src/pystormtracker/simple/__init__.py +0 -0
  147. {pystormtracker-0.4.1 → pystormtracker-0.5.0}/src/pystormtracker/simple/kernels.py +0 -0
  148. {pystormtracker-0.4.1/src/pystormtracker/utils → pystormtracker-0.5.0/tests/integration}/__init__.py +0 -0
  149. {pystormtracker-0.4.1/tests → pystormtracker-0.5.0/tests/unit/models}/test_center.py +0 -0
  150. /pystormtracker-0.4.1/tests/test_simple_tracker.py → /pystormtracker-0.5.0/tests/unit/simple/test_tracker.py +0 -0
@@ -0,0 +1,17 @@
1
+ # Mark notebooks as generated so they don't count towards language statistics
2
+ notebooks/*.ipynb linguist-generated
3
+
4
+ # Mark benchmarking code and data as documentation to focus on core logic
5
+ benchmark/* linguist-documentation
6
+
7
+ # Mark the JOSS paper and all documentation files (including static HTML) as documentation
8
+ docs/* linguist-documentation
9
+ paper/* linguist-documentation
10
+
11
+ # Mark example/test data files as documentation/vendored
12
+ data/* linguist-vendored
13
+
14
+ # Ensure lockfiles are marked as generated
15
+ uv.lock linguist-generated
16
+
17
+ # (Note: src/pystormtracker/templates/*.html are NOT marked, so they WILL count as source)
@@ -9,12 +9,15 @@ on:
9
9
  - 'uv.lock'
10
10
  - 'Dockerfile'
11
11
  - '.github/workflows/ci.yml'
12
+ - 'docs/**'
13
+ - 'README.md'
12
14
  push:
13
15
  branches:
14
16
  - main
15
17
  - release/**
18
+ - 'v*.*'
16
19
  tags:
17
- - v*
20
+ - 'v*.*'
18
21
  paths:
19
22
  - 'src/**'
20
23
  - 'tests/**'
@@ -22,8 +25,8 @@ on:
22
25
  - 'uv.lock'
23
26
  - 'Dockerfile'
24
27
  - '.github/workflows/ci.yml'
25
- release:
26
- types: [published]
28
+ - 'docs/**'
29
+ - 'README.md'
27
30
  workflow_dispatch:
28
31
 
29
32
  concurrency:
@@ -38,47 +41,31 @@ jobs:
38
41
  runs-on: ubuntu-24.04
39
42
  steps:
40
43
  - uses: actions/checkout@v6
41
- with:
42
- ref: ${{ github.ref }}
43
- fetch-depth: 0
44
- - name: Set up uv
45
- uses: astral-sh/setup-uv@v7
46
- with:
47
- enable-cache: true
48
- - name: Lint with Ruff
49
- run: uv run ruff check .
44
+ - uses: astral-sh/ruff-action@v3
50
45
 
51
46
  ruff-format:
52
47
  runs-on: ubuntu-24.04
53
48
  steps:
54
49
  - uses: actions/checkout@v6
50
+ - uses: astral-sh/ruff-action@v3
55
51
  with:
56
- ref: ${{ github.ref }}
57
- fetch-depth: 0
58
- - name: Set up uv
59
- uses: astral-sh/setup-uv@v7
60
- with:
61
- enable-cache: true
62
- - name: Check formatting with Ruff
63
- run: uv run ruff format --check .
52
+ args: format --check
64
53
 
65
54
  mypy-typecheck:
66
55
  runs-on: ubuntu-24.04
67
56
  steps:
68
57
  - uses: actions/checkout@v6
69
58
  with:
70
- ref: ${{ github.ref }}
71
59
  fetch-depth: 0
72
60
  - name: Set up uv
73
61
  uses: astral-sh/setup-uv@v7
74
62
  with:
75
63
  enable-cache: true
76
- - name: Install system dependencies
77
- run: sudo apt-get update && sudo apt-get install -y libopenmpi-dev
64
+
78
65
  - name: Install dependencies
79
66
  run: uv sync --frozen --group dev
80
67
  - name: Type check with Mypy
81
- run: uv run mypy src/ tests/
68
+ run: uv run mypy .
82
69
 
83
70
  unit-tests:
84
71
  name: unit-tests (Python ${{ matrix.python-version }}${{ matrix.min-deps && ', min-deps' || '' }})
@@ -86,7 +73,7 @@ jobs:
86
73
  strategy:
87
74
  fail-fast: false
88
75
  matrix:
89
- python-version: ["3.11", "3.12", "3.13", "3.14"]
76
+ python-version: ['3.11', '3.12', '3.13', '3.14']
90
77
  min-deps: [false]
91
78
  include:
92
79
  - python-version: "3.11"
@@ -94,15 +81,13 @@ jobs:
94
81
  steps:
95
82
  - uses: actions/checkout@v6
96
83
  with:
97
- ref: ${{ github.ref }}
98
84
  fetch-depth: 0
99
85
  - name: Set up uv
100
86
  uses: astral-sh/setup-uv@v7
101
87
  with:
102
88
  enable-cache: true
103
89
  python-version: ${{ matrix.python-version }}
104
- - name: Install system dependencies
105
- run: sudo apt-get update && sudo apt-get install -y libopenmpi-dev
90
+
106
91
  - name: Install dependencies
107
92
  if: ${{ !matrix.min-deps }}
108
93
  run: uv sync --frozen --group dev
@@ -119,14 +104,14 @@ jobs:
119
104
 
120
105
  - name: Upload coverage reports to Codecov
121
106
  if: matrix.python-version == '3.13' && !matrix.min-deps
122
- uses: codecov/codecov-action@v5
107
+ uses: codecov/codecov-action@v6
123
108
  with:
124
109
  files: ./coverage.xml
125
110
  flags: unit
126
111
  token: ${{ secrets.CODECOV_TOKEN }}
127
112
 
128
113
  integration-tests:
129
- name: integration-tests (Python ${{ matrix.python-version }}, ${{ matrix.arch }})
114
+ name: integration-tests (${{ matrix.os }})
130
115
  runs-on: ${{ matrix.os }}
131
116
  strategy:
132
117
  fail-fast: false
@@ -134,57 +119,82 @@ jobs:
134
119
  include:
135
120
  - arch: amd64
136
121
  os: ubuntu-24.04
137
- python-version: "3.13"
122
+ python-version: '3.13'
138
123
  - arch: arm64
139
124
  os: ubuntu-24.04-arm
140
- python-version: "3.13"
125
+ python-version: '3.13'
126
+ - arch: amd64
127
+ os: windows-2025
128
+ python-version: '3.13'
129
+ - arch: arm64
130
+ os: macos-26
131
+ python-version: '3.13'
141
132
  steps:
142
133
  - uses: actions/checkout@v6
143
134
  with:
144
- ref: ${{ github.ref }}
145
135
  fetch-depth: 0
146
136
  - name: Set up uv
147
137
  uses: astral-sh/setup-uv@v7
148
138
  with:
149
139
  enable-cache: true
150
140
  python-version: ${{ matrix.python-version }}
151
- - name: Install system dependencies
152
- run: sudo apt-get update && sudo apt-get install -y openmpi-bin libopenmpi-dev
141
+
142
+ - name: Install MPI (Windows)
143
+ if: runner.os == 'Windows'
144
+ run: |
145
+ winget install -e --id Microsoft.msmpi --accept-source-agreements --accept-package-agreements
146
+ "C:\Program Files\Microsoft MPI\Bin" | Out-File -FilePath $env:GITHUB_PATH -Encoding utf8 -Append
147
+
153
148
  - name: Install dependencies
154
149
  run: uv sync --frozen --group dev
155
150
  - name: Run Integration Tests
156
- if: matrix.arch != 'amd64'
157
- run: uv run pytest -vv tests/test_integration.py --run-integration
151
+ if: matrix.os != 'ubuntu-24.04' || matrix.arch != 'amd64'
152
+ run: uv run pytest -vv tests/integration/ --run-integration
158
153
 
159
154
  - name: Run Integration Tests with Coverage
160
- if: matrix.arch == 'amd64'
161
- run: uv run pytest -vv --cov=pystormtracker --cov-report=term-missing --cov-report=xml tests/test_integration.py --run-integration
155
+ if: matrix.os == 'ubuntu-24.04' && matrix.arch == 'amd64'
156
+ run: uv run pytest -vv --cov=pystormtracker --cov-report=term-missing --cov-report=xml tests/integration/ --run-integration
162
157
 
163
158
  - name: Upload coverage reports to Codecov
164
- if: matrix.arch == 'amd64'
165
- uses: codecov/codecov-action@v5
159
+ if: matrix.os == 'ubuntu-24.04' && matrix.arch == 'amd64'
160
+ uses: codecov/codecov-action@v6
166
161
  with:
167
162
  files: ./coverage.xml
168
163
  flags: integration
169
164
  token: ${{ secrets.CODECOV_TOKEN }}
170
165
 
166
+ docs-build:
167
+ name: docs-build
168
+ needs: [ruff-lint, ruff-format]
169
+ runs-on: ubuntu-24.04
170
+ steps:
171
+ - uses: actions/checkout@v6
172
+ with:
173
+ fetch-depth: 0
174
+ - name: Set up uv
175
+ uses: astral-sh/setup-uv@v7
176
+ with:
177
+ enable-cache: true
178
+ python-version: '3.13'
179
+ - name: Build documentation
180
+ run: uv run --extra docs --no-dev sphinx-build -b html docs docs/_build/html
181
+
171
182
  docker-build:
172
- name: docker-build
183
+ name: docker-build (${{ matrix.arch }})
173
184
  needs: [ruff-lint, ruff-format, mypy-typecheck, unit-tests, integration-tests]
174
- # Only run on merges to main, release branches, tags, releases, or manual dispatch
175
- if: |
176
- github.event_name != 'pull_request' &&
177
- (github.ref == 'refs/heads/main' ||
178
- startsWith(github.ref, 'refs/heads/release/') ||
179
- startsWith(github.ref, 'refs/tags/v') ||
180
- github.event_name == 'release' ||
181
- github.event_name == 'workflow_dispatch')
182
- runs-on: ubuntu-latest
185
+ strategy:
186
+ fail-fast: false
187
+ matrix:
188
+ include:
189
+ - arch: amd64
190
+ os: ubuntu-24.04
191
+ - arch: arm64
192
+ os: ubuntu-24.04-arm
193
+ runs-on: ${{ matrix.os }}
183
194
  steps:
184
195
  - name: Checkout repository
185
196
  uses: actions/checkout@v6
186
197
  with:
187
- ref: ${{ github.ref }}
188
198
  fetch-depth: 0
189
199
 
190
200
  - name: Set up Docker Buildx
@@ -196,48 +206,24 @@ jobs:
196
206
  context: .
197
207
  push: false
198
208
  load: true
199
- platforms: linux/amd64
200
- tags: "${{ github.repository_owner }}/${{ vars.DOCKER_IMAGE_NAME }}:${{ github.sha }}"
201
- cache-from: type=gha,scope=docker-build
202
- cache-to: type=gha,mode=max,scope=docker-build
209
+ platforms: linux/${{ matrix.arch }}
210
+ tags: '${{ github.repository_owner }}/${{ vars.DOCKER_IMAGE_NAME }}:${{ github.sha }}-${{ matrix.arch }}'
211
+ cache-from: type=gha,scope=docker-build-${{ matrix.arch }}
212
+ cache-to: type=gha,mode=max,scope=docker-build-${{ matrix.arch }}
203
213
 
204
214
  - name: Smoke test Docker image
205
215
  run: |
206
216
  # Test CLI help
207
- docker run --rm ${{ github.repository_owner }}/${{ vars.DOCKER_IMAGE_NAME }}:${{ github.sha }} --help
217
+ docker run --rm ${{ github.repository_owner }}/${{ vars.DOCKER_IMAGE_NAME }}:${{ github.sha }}-${{ matrix.arch }} --help
208
218
  # Test library import
209
- docker run --rm --entrypoint python ${{ github.repository_owner }}/${{ vars.DOCKER_IMAGE_NAME }}:${{ github.sha }} -c "import pystormtracker as pst; print('Import success')"
219
+ docker run --rm --entrypoint python ${{ github.repository_owner }}/${{ vars.DOCKER_IMAGE_NAME }}:${{ github.sha }}-${{ matrix.arch }} -c "import pystormtracker as pst; print('Import success')"
210
220
 
211
221
  - name: Run Trivy vulnerability scanner
212
222
  uses: aquasecurity/trivy-action@0.35.0
213
223
  with:
214
- image-ref: "${{ github.repository_owner }}/${{ vars.DOCKER_IMAGE_NAME }}:${{ github.sha }}"
224
+ image-ref: "${{ github.repository_owner }}/${{ vars.DOCKER_IMAGE_NAME }}:${{ github.sha }}-${{ matrix.arch }}"
215
225
  format: "table"
216
226
  exit-code: "0"
217
227
  ignore-unfixed: true
218
228
  vuln-type: "os,library"
219
229
  severity: "CRITICAL,HIGH"
220
-
221
- pypi-build:
222
- name: pypi-build
223
- needs: [ruff-lint, ruff-format, mypy-typecheck, unit-tests, integration-tests]
224
- # Only run on merges to main, release branches, tags, releases, or manual dispatch
225
- if: |
226
- github.event_name != 'pull_request' &&
227
- (github.ref == 'refs/heads/main' ||
228
- startsWith(github.ref, 'refs/heads/release/') ||
229
- startsWith(github.ref, 'refs/tags/v') ||
230
- github.event_name == 'release' ||
231
- github.event_name == 'workflow_dispatch')
232
- runs-on: ubuntu-latest
233
- steps:
234
- - uses: actions/checkout@v6
235
- with:
236
- ref: ${{ github.ref }}
237
- fetch-depth: 0
238
- - name: Set up uv
239
- uses: astral-sh/setup-uv@v7
240
- with:
241
- enable-cache: true
242
- - name: Build release distributions
243
- run: uv build --wheel --sdist
@@ -0,0 +1,158 @@
1
+ name: Docker Publish
2
+
3
+ on:
4
+ workflow_run:
5
+ workflows: ["CI"]
6
+ types: [completed]
7
+ branches:
8
+ - main
9
+ - 'v*.*'
10
+ - 'release/**'
11
+ workflow_dispatch:
12
+
13
+ concurrency:
14
+ group: ${{ github.workflow }}-${{ github.ref }}
15
+ cancel-in-progress: true
16
+
17
+ jobs:
18
+ build-and-push-platform:
19
+ strategy:
20
+ fail-fast: false
21
+ matrix:
22
+ include:
23
+ - arch: amd64
24
+ os: ubuntu-24.04
25
+ - arch: arm64
26
+ os: ubuntu-24.04-arm
27
+ runs-on: ${{ matrix.os }}
28
+ if: |
29
+ (github.event_name == 'workflow_run' &&
30
+ github.event.workflow_run.conclusion == 'success' &&
31
+ github.event.workflow_run.event != 'pull_request' &&
32
+ github.event.workflow_run.head_repository.full_name == github.repository) ||
33
+ github.event_name == 'workflow_dispatch'
34
+ permissions:
35
+ contents: read
36
+ packages: write
37
+ env:
38
+ DOCKER_HUB_IMAGE: docker.io/${{ (startsWith(github.event.workflow_run.head_branch || github.ref_name, 'v*.*')) && vars.DOCKER_ORG_NAME || github.repository_owner }}/${{ vars.DOCKER_IMAGE_NAME }}
39
+ GHCR_IMAGE: ghcr.io/${{ (startsWith(github.event.workflow_run.head_branch || github.ref_name, 'v*.*')) && vars.DOCKER_ORG_NAME || github.repository_owner }}/${{ vars.DOCKER_IMAGE_NAME }}
40
+ steps:
41
+ - name: Checkout repository
42
+ uses: actions/checkout@v6
43
+ with:
44
+ ref: ${{ github.event.workflow_run.head_sha || github.sha }}
45
+ fetch-depth: 0
46
+
47
+ - name: Set up Docker Buildx
48
+ uses: docker/setup-buildx-action@v4
49
+
50
+ - name: Log in to Docker Hub
51
+ uses: docker/login-action@v4
52
+ with:
53
+ username: ${{ vars.DOCKER_HUB_USERNAME }}
54
+ password: ${{ secrets.DOCKER_HUB_ACCESS_TOKEN }}
55
+
56
+ - name: Log in to GHCR
57
+ uses: docker/login-action@v4
58
+ with:
59
+ registry: ghcr.io
60
+ username: ${{ github.repository_owner }}
61
+ password: ${{ secrets.GHCR_PAT }}
62
+
63
+ - name: Build and push Docker image with SHA tag
64
+ id: push
65
+ uses: docker/build-push-action@v7
66
+ with:
67
+ context: .
68
+ push: true
69
+ provenance: false
70
+ sbom: false
71
+ platforms: linux/${{ matrix.arch }}
72
+ tags: |
73
+ ${{ env.DOCKER_HUB_IMAGE }}:${{ github.event.workflow_run.head_sha || github.sha }}-${{ matrix.arch }}
74
+ ${{ env.GHCR_IMAGE }}:${{ github.event.workflow_run.head_sha || github.sha }}-${{ matrix.arch }}
75
+ cache-from: type=gha,scope=docker-build-${{ matrix.arch }}
76
+ cache-to: type=gha,mode=max,scope=docker-build-${{ matrix.arch }}
77
+
78
+ create-manifest:
79
+ needs: build-and-push-platform
80
+ runs-on: ubuntu-24.04
81
+ permissions:
82
+ contents: read
83
+ packages: write
84
+ id-token: write
85
+ attestations: write
86
+ env:
87
+ DOCKER_HUB_IMAGE: docker.io/${{ (startsWith(github.event.workflow_run.head_branch || github.ref_name, 'v*.*')) && vars.DOCKER_ORG_NAME || github.repository_owner }}/${{ vars.DOCKER_IMAGE_NAME }}
88
+ GHCR_IMAGE: ghcr.io/${{ (startsWith(github.event.workflow_run.head_branch || github.ref_name, 'v*.*')) && vars.DOCKER_ORG_NAME || github.repository_owner }}/${{ vars.DOCKER_IMAGE_NAME }}
89
+ steps:
90
+ - name: Log in to Docker Hub
91
+ uses: docker/login-action@v4
92
+ with:
93
+ username: ${{ vars.DOCKER_HUB_USERNAME }}
94
+ password: ${{ secrets.DOCKER_HUB_ACCESS_TOKEN }}
95
+
96
+ - name: Log in to GHCR
97
+ uses: docker/login-action@v4
98
+ with:
99
+ registry: ghcr.io
100
+ username: ${{ github.repository_owner }}
101
+ password: ${{ secrets.GHCR_PAT }}
102
+
103
+ - name: Extract Docker metadata
104
+ id: meta
105
+ uses: docker/metadata-action@v6
106
+ with:
107
+ images: |
108
+ ${{ env.DOCKER_HUB_IMAGE }}
109
+ ${{ env.GHCR_IMAGE }}
110
+ tags: |
111
+ type=raw,value=latest,enable=${{ github.ref == 'refs/heads/main' || github.event.workflow_run.head_branch == 'main' }}
112
+ type=semver,pattern={{version}}
113
+ type=semver,pattern={{major}}.{{minor}}
114
+ type=sha,format=short,prefix=
115
+
116
+ - name: Create and push manifest
117
+ id: manifest
118
+ run: |
119
+ tags_with_commas="${{ steps.meta.outputs.csv_tags }}"
120
+ tags_with_spaces=$(echo "$tags_with_commas" | tr ',' ' ')
121
+ manifest_digest=""
122
+
123
+ for tag in $tags_with_spaces; do
124
+ base_image=$(echo "$tag" | cut -d: -f1)
125
+ echo "Creating manifest for $tag"
126
+ docker buildx imagetools create -t "$tag" \
127
+ "${base_image}:${{ github.event.workflow_run.head_sha || github.sha }}-amd64" \
128
+ "${base_image}:${{ github.event.workflow_run.head_sha || github.sha }}-arm64"
129
+ if [[ "$tag" == *":latest" ]]; then
130
+ manifest_digest=$(docker buildx imagetools inspect "$tag" --format '{{json .Manifest.Digest}}' | tr -d '"')
131
+ fi
132
+ done
133
+ echo "digest=$manifest_digest" >> $GITHUB_OUTPUT
134
+
135
+ - name: Attest Provenance (Docker Hub)
136
+ if: steps.manifest.outputs.digest != ''
137
+ uses: actions/attest@v4
138
+ with:
139
+ subject-name: ${{ env.DOCKER_HUB_IMAGE }}
140
+ subject-digest: ${{ steps.manifest.outputs.digest }}
141
+ push-to-registry: true
142
+
143
+ - name: Generate SBOM
144
+ uses: anchore/sbom-action@v0
145
+ with:
146
+ path: ./
147
+ artifact-name: sbom.cyclonedx.json
148
+ output-file: sbom.cyclonedx.json
149
+ format: cyclonedx-json
150
+
151
+ - name: Attest SBOM (Docker Hub)
152
+ if: steps.manifest.outputs.digest != ''
153
+ uses: actions/attest@v4
154
+ with:
155
+ subject-name: ${{ env.DOCKER_HUB_IMAGE }}
156
+ subject-digest: ${{ steps.manifest.outputs.digest }}
157
+ sbom-path: 'sbom.cyclonedx.json'
158
+ push-to-registry: true
@@ -7,9 +7,11 @@ on:
7
7
  workflow_run:
8
8
  workflows: ["CI"]
9
9
  types: [completed]
10
+ branches:
11
+ - 'v[0-9]*'
10
12
 
11
13
  concurrency:
12
- group: ${{ github.workflow }}-${{ github.ref }}
14
+ group: ${{ github.workflow }}-${{ github.event.workflow_run.head_branch || github.ref_name }}
13
15
  cancel-in-progress: false
14
16
 
15
17
  permissions:
@@ -18,17 +20,22 @@ permissions:
18
20
  jobs:
19
21
  release-build:
20
22
  runs-on: ubuntu-latest
21
- # Only run if CI succeeded AND it was a release event.
22
- # Added head_repository check for security.
23
+ # Only run if CI succeeded AND it was a tag push.
24
+ # Exclude PRs to avoid accidental triggers/publishing.
23
25
  if: |
24
26
  github.event_name == 'workflow_run' &&
25
27
  github.event.workflow_run.conclusion == 'success' &&
26
- github.event.workflow_run.event == 'release' &&
28
+ github.event.workflow_run.event != 'pull_request' &&
29
+ github.event.workflow_run.event == 'push' &&
30
+ startsWith(github.event.workflow_run.head_branch, 'v') &&
27
31
  github.event.workflow_run.head_repository.full_name == github.repository
28
32
  permissions:
29
33
  contents: read
30
34
  id-token: write
31
35
  attestations: write
36
+ outputs:
37
+ is_stable: ${{ steps.check_version.outputs.is_stable }}
38
+ version: ${{ steps.check_version.outputs.version }}
32
39
 
33
40
  steps:
34
41
  - uses: actions/checkout@v6
@@ -36,6 +43,18 @@ jobs:
36
43
  ref: ${{ github.event.workflow_run.head_sha }}
37
44
  fetch-depth: 0
38
45
 
46
+ - name: Check version type
47
+ id: check_version
48
+ run: |
49
+ VERSION=${{ github.event.workflow_run.head_branch }}
50
+ echo "version=${VERSION#v}" >> $GITHUB_OUTPUT
51
+ # Regex for stable release: vX.Y.Z
52
+ if [[ $VERSION =~ ^v[0-9]+\.[0-9]+\.[0-9]+$ ]]; then
53
+ echo "is_stable=true" >> $GITHUB_OUTPUT
54
+ else
55
+ echo "is_stable=false" >> $GITHUB_OUTPUT
56
+ fi
57
+
39
58
  - name: Set up uv
40
59
  uses: astral-sh/setup-uv@v7
41
60
  with:
@@ -59,31 +78,41 @@ jobs:
59
78
  runs-on: ubuntu-latest
60
79
  needs:
61
80
  - release-build
81
+ if: needs.release-build.outputs.is_stable == 'true'
62
82
  permissions:
63
- # IMPORTANT: this permission is mandatory for trusted publishing
64
83
  id-token: write
65
-
66
- # Dedicated environments with protections for publishing are strongly recommended.
67
84
  environment:
68
85
  name: pypi
69
- url: https://pypi.org/project/PyStormTracker/${{ steps.get_version.outputs.version }}
70
-
86
+ url: https://pypi.org/project/PyStormTracker/${{ needs.release-build.outputs.version }}
71
87
  steps:
72
- - name: Get version from tag
73
- id: get_version
74
- run: |
75
- # Strips 'v' prefix from tag_name (e.g. v0.2.1 -> 0.2.1)
76
- # In workflow_run for a release, head_branch contains the tag name.
77
- VERSION=${{ github.event.workflow_run.head_branch }}
78
- echo "version=${VERSION#v}" >> $GITHUB_OUTPUT
79
-
80
88
  - name: Retrieve release distributions
81
89
  uses: actions/download-artifact@v8
82
90
  with:
83
91
  name: release-dists
84
92
  path: dist/
85
-
86
93
  - name: Publish release distributions to PyPI
87
94
  uses: pypa/gh-action-pypi-publish@release/v1
88
95
  with:
89
96
  packages-dir: dist/
97
+
98
+ test-pypi-publish:
99
+ runs-on: ubuntu-latest
100
+ needs:
101
+ - release-build
102
+ if: needs.release-build.outputs.is_stable == 'false'
103
+ permissions:
104
+ id-token: write
105
+ environment:
106
+ name: testpypi
107
+ url: https://test.pypi.org/project/PyStormTracker/${{ needs.release-build.outputs.version }}
108
+ steps:
109
+ - name: Retrieve release distributions
110
+ uses: actions/download-artifact@v8
111
+ with:
112
+ name: release-dists
113
+ path: dist/
114
+ - name: Publish release distributions to TestPyPI
115
+ uses: pypa/gh-action-pypi-publish@release/v1
116
+ with:
117
+ repository-url: https://test.pypi.org/legacy/
118
+ packages-dir: dist/
@@ -31,6 +31,7 @@ docs/_build/
31
31
 
32
32
  # Data and Track files
33
33
  *.nc
34
+ !data/test/era5/*.nc
34
35
  *.txt
35
36
  !data/test/tracks/*.txt
36
37
  *.pickle
@@ -0,0 +1,20 @@
1
+ # PyStormTracker Repository Instructions
2
+
3
+ Foundational mandates and engineering standards for `PyStormTracker`. These take precedence over general defaults.
4
+
5
+ ## 1. Core Mandates
6
+
7
+ - **Hodges Parity**: MUST maintain algorithmic parity with TRACK (Hodges 1994, 1995, 1999) as detailed in `docs/HODGES.md`. Core kernels MUST use Numba.
8
+ - **Vectorized Architecture**: MUST use the array-backed data model and JIT-optimized kernels described in `docs/ARCHITECTURE.md`.
9
+ - **Validation**: Parallel results MUST be bit-wise identical to serial execution. Use Gather-then-Link orchestration.
10
+ - **Geometry**: All distance calculations MUST use the great-circle dot product formula with precision clamping.
11
+
12
+ ## 2. Engineering Standards
13
+
14
+ - **Flexible APIs**: All `track()` implementations MUST accept `**kwargs` for cross-algorithm compatibility.
15
+ - **I/O**: MUST use coordinate-aware Xarray NetCDF/GRIB handling via `DataLoader`. Centralize remote data fetching for tests in `tests/testing_utils.py`.
16
+ - **Typing**: MUST NOT use `Any` typing. Provide explicit type annotations for all declarations.
17
+ - **Plain Language**: Use objective, scientific language in documentation. Avoid superlatives and subjective terms.
18
+ - **No Auto-Commit**: NEVER stage or commit changes unless specifically and explicitly requested by the user.
19
+ - **Tooling**: MUST use `uv` for package management, environment handling, and running tools (e.g., `uv run ruff`, `uv run pytest`).
20
+ - **Documentation Persistence**: Preserve existing technical documentation and design rationale unless explicitly obsoleted.
@@ -1,5 +1,5 @@
1
1
  cff-version: 1.2.0
2
- title: "mwyau/PyStormTracker: v0.4.1"
2
+ title: "mwyau/PyStormTracker: v0.5.0"
3
3
  message: "If you use this software, please cite it as below."
4
4
  type: software
5
5
  authors:
@@ -19,8 +19,8 @@ keywords:
19
19
  - dask
20
20
  - mpi
21
21
  license: BSD-3-Clause
22
- version: 0.4.1
23
- date-released: '2026-03-10'
22
+ version: 0.5.0
23
+ date-released: '2026-04-08'
24
24
  preferred-citation:
25
25
  type: article
26
26
  authors:
@@ -0,0 +1,51 @@
1
+ # Contributing to PyStormTracker
2
+
3
+ Thank you for your interest in contributing to PyStormTracker! We welcome contributions from the community to help improve this cyclone tracking framework.
4
+
5
+ ## How to Contribute
6
+
7
+ ### Reporting Bugs
8
+ If you find a bug, please [open an issue](https://github.com/mwyau/PyStormTracker/issues) on GitHub. Include:
9
+ - A clear description of the issue.
10
+ - Steps to reproduce the bug.
11
+ - Any relevant logs or error messages.
12
+ - Information about your environment (OS, Python version, PyStormTracker version).
13
+
14
+ ### Suggesting Enhancements
15
+ We welcome ideas for new features or improvements. Please [open an issue](https://github.com/mwyau/PyStormTracker/issues) to discuss your proposal before starting implementation.
16
+
17
+ ### Submitting Pull Requests
18
+ 1. **Fork the repository** and create your branch from `main`.
19
+ 2. **Install development dependencies**:
20
+ ```bash
21
+ uv sync
22
+ ```
23
+ 3. **Make your changes**:
24
+ - Ensure your code follows the project's style (use `ruff` for formatting and linting).
25
+ - Add or update tests for your changes.
26
+ - Ensure all tests pass.
27
+ 4. **Run Quality Control Checks**:
28
+ ```bash
29
+ uv run ruff check . --fix
30
+ uv run ruff format .
31
+ uv run mypy src/
32
+ uv run pytest
33
+ ```
34
+ 5. **Submit the Pull Request**:
35
+ - Provide a clear description of the changes.
36
+ - Reference any related issues.
37
+
38
+ ## Development Standards
39
+
40
+ - **Code Style**: We use `ruff` for linting and formatting.
41
+ - **Type Safety**: All new code should be type-hinted and pass `mypy` strict checks.
42
+ - **Testing**: We use `pytest`. Ensure that your changes are covered by unit tests and, if applicable, integration tests.
43
+ - **Documentation**: Update the documentation in `docs/` if you introduce new features or change existing behavior.
44
+
45
+ ## Governance
46
+
47
+ This project is currently maintained by [Albert M. W. Yau](https://github.com/mwyau). Decisions regarding pull requests and the project's roadmap are made by the maintainer in consultation with the community.
48
+
49
+ ## Conduct
50
+
51
+ Please be respectful and professional in all interactions within the PyStormTracker community.