PyStormTracker 0.4.2__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 (148) hide show
  1. pystormtracker-0.5.0/.gitattributes +17 -0
  2. {pystormtracker-0.4.2 → pystormtracker-0.5.0}/.github/workflows/ci.yml +70 -82
  3. pystormtracker-0.5.0/.github/workflows/docker-publish.yml +158 -0
  4. {pystormtracker-0.4.2 → pystormtracker-0.5.0}/.github/workflows/python-publish.yml +46 -19
  5. {pystormtracker-0.4.2 → pystormtracker-0.5.0}/.gitignore +1 -0
  6. pystormtracker-0.5.0/AGENTS.md +20 -0
  7. {pystormtracker-0.4.2 → pystormtracker-0.5.0}/CITATION.cff +3 -3
  8. pystormtracker-0.5.0/CONTRIBUTING.md +51 -0
  9. {pystormtracker-0.4.2 → pystormtracker-0.5.0}/Dockerfile +10 -3
  10. {pystormtracker-0.4.2 → pystormtracker-0.5.0}/PKG-INFO +106 -53
  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.2/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.2/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.2/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.2 → 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.2 → 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.2 → pystormtracker-0.5.0}/pyproject.toml +27 -17
  51. {pystormtracker-0.4.2 → 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.2 → 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.2 → 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.4.2 → pystormtracker-0.5.0}/src/pystormtracker/simple/concurrent.py +50 -10
  78. {pystormtracker-0.4.2 → pystormtracker-0.5.0}/src/pystormtracker/simple/detector.py +69 -25
  79. {pystormtracker-0.4.2 → 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.2 → 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.2/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.2/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.2/tests/test_simple_linker.py → pystormtracker-0.5.0/tests/unit/simple/test_linker.py +11 -2
  112. {pystormtracker-0.4.2/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.2/.github/workflows/docker-publish.yml +0 -123
  117. pystormtracker-0.4.2/README.md +0 -226
  118. pystormtracker-0.4.2/ROADMAP.md +0 -45
  119. pystormtracker-0.4.2/docs/architecture.md +0 -2
  120. pystormtracker-0.4.2/docs/benchmark.md +0 -2
  121. pystormtracker-0.4.2/docs/index.md +0 -27
  122. pystormtracker-0.4.2/docs/roadmap.md +0 -2
  123. pystormtracker-0.4.2/src/pystormtracker/cli.py +0 -160
  124. pystormtracker-0.4.2/src/pystormtracker/hodges/tracker.py +0 -33
  125. pystormtracker-0.4.2/src/pystormtracker/io/loader.py +0 -72
  126. pystormtracker-0.4.2/src/pystormtracker/models/tracker.py +0 -27
  127. pystormtracker-0.4.2/src/pystormtracker/simple/tracker.py +0 -132
  128. pystormtracker-0.4.2/src/pystormtracker/utils/benchmark.py +0 -52
  129. pystormtracker-0.4.2/src/pystormtracker/utils/data_utils.py +0 -88
  130. pystormtracker-0.4.2/tests/__init__.py +0 -1
  131. pystormtracker-0.4.2/tests/test_simple_detector.py +0 -52
  132. pystormtracker-0.4.2/uv.lock +0 -2189
  133. {pystormtracker-0.4.2 → pystormtracker-0.5.0}/.dockerignore +0 -0
  134. {pystormtracker-0.4.2 → pystormtracker-0.5.0}/.github/dependabot.yml +0 -0
  135. {pystormtracker-0.4.2 → pystormtracker-0.5.0}/.python-version +0 -0
  136. {pystormtracker-0.4.2 → pystormtracker-0.5.0}/.readthedocs.yaml +0 -0
  137. {pystormtracker-0.4.2 → pystormtracker-0.5.0}/LICENSE +0 -0
  138. {pystormtracker-0.4.2 → pystormtracker-0.5.0}/codecov.yml +0 -0
  139. {pystormtracker-0.4.2/docs → pystormtracker-0.5.0/docs/_static}/IntercomparisonProtocol.pdf +0 -0
  140. {pystormtracker-0.4.2 → pystormtracker-0.5.0}/src/pystormtracker/hodges/__init__.py +0 -0
  141. {pystormtracker-0.4.2 → pystormtracker-0.5.0}/src/pystormtracker/models/__init__.py +0 -0
  142. {pystormtracker-0.4.2 → pystormtracker-0.5.0}/src/pystormtracker/models/center.py +0 -0
  143. /pystormtracker-0.4.2/src/pystormtracker/io/__init__.py → /pystormtracker-0.5.0/src/pystormtracker/py.typed +0 -0
  144. {pystormtracker-0.4.2 → pystormtracker-0.5.0}/src/pystormtracker/simple/__init__.py +0 -0
  145. {pystormtracker-0.4.2 → pystormtracker-0.5.0}/src/pystormtracker/simple/kernels.py +0 -0
  146. {pystormtracker-0.4.2/src/pystormtracker/utils → pystormtracker-0.5.0/tests/integration}/__init__.py +0 -0
  147. {pystormtracker-0.4.2/tests → pystormtracker-0.5.0/tests/unit/models}/test_center.py +0 -0
  148. /pystormtracker-0.4.2/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,10 +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*.*'
19
+ tags:
20
+ - 'v*.*'
16
21
  paths:
17
22
  - 'src/**'
18
23
  - 'tests/**'
@@ -20,8 +25,8 @@ on:
20
25
  - 'uv.lock'
21
26
  - 'Dockerfile'
22
27
  - '.github/workflows/ci.yml'
23
- release:
24
- types: [published]
28
+ - 'docs/**'
29
+ - 'README.md'
25
30
  workflow_dispatch:
26
31
 
27
32
  concurrency:
@@ -36,47 +41,31 @@ jobs:
36
41
  runs-on: ubuntu-24.04
37
42
  steps:
38
43
  - uses: actions/checkout@v6
39
- with:
40
- ref: ${{ github.ref }}
41
- fetch-depth: 0
42
- - name: Set up uv
43
- uses: astral-sh/setup-uv@v7
44
- with:
45
- enable-cache: true
46
- - name: Lint with Ruff
47
- run: uv run ruff check .
44
+ - uses: astral-sh/ruff-action@v3
48
45
 
49
46
  ruff-format:
50
47
  runs-on: ubuntu-24.04
51
48
  steps:
52
49
  - uses: actions/checkout@v6
50
+ - uses: astral-sh/ruff-action@v3
53
51
  with:
54
- ref: ${{ github.ref }}
55
- fetch-depth: 0
56
- - name: Set up uv
57
- uses: astral-sh/setup-uv@v7
58
- with:
59
- enable-cache: true
60
- - name: Check formatting with Ruff
61
- run: uv run ruff format --check .
52
+ args: format --check
62
53
 
63
54
  mypy-typecheck:
64
55
  runs-on: ubuntu-24.04
65
56
  steps:
66
57
  - uses: actions/checkout@v6
67
58
  with:
68
- ref: ${{ github.ref }}
69
59
  fetch-depth: 0
70
60
  - name: Set up uv
71
61
  uses: astral-sh/setup-uv@v7
72
62
  with:
73
63
  enable-cache: true
74
- - name: Install system dependencies
75
- run: sudo apt-get update && sudo apt-get install -y libopenmpi-dev
64
+
76
65
  - name: Install dependencies
77
66
  run: uv sync --frozen --group dev
78
67
  - name: Type check with Mypy
79
- run: uv run mypy src/ tests/
68
+ run: uv run mypy .
80
69
 
81
70
  unit-tests:
82
71
  name: unit-tests (Python ${{ matrix.python-version }}${{ matrix.min-deps && ', min-deps' || '' }})
@@ -84,7 +73,7 @@ jobs:
84
73
  strategy:
85
74
  fail-fast: false
86
75
  matrix:
87
- python-version: ["3.11", "3.12", "3.13", "3.14"]
76
+ python-version: ['3.11', '3.12', '3.13', '3.14']
88
77
  min-deps: [false]
89
78
  include:
90
79
  - python-version: "3.11"
@@ -92,15 +81,13 @@ jobs:
92
81
  steps:
93
82
  - uses: actions/checkout@v6
94
83
  with:
95
- ref: ${{ github.ref }}
96
84
  fetch-depth: 0
97
85
  - name: Set up uv
98
86
  uses: astral-sh/setup-uv@v7
99
87
  with:
100
88
  enable-cache: true
101
89
  python-version: ${{ matrix.python-version }}
102
- - name: Install system dependencies
103
- run: sudo apt-get update && sudo apt-get install -y libopenmpi-dev
90
+
104
91
  - name: Install dependencies
105
92
  if: ${{ !matrix.min-deps }}
106
93
  run: uv sync --frozen --group dev
@@ -117,14 +104,14 @@ jobs:
117
104
 
118
105
  - name: Upload coverage reports to Codecov
119
106
  if: matrix.python-version == '3.13' && !matrix.min-deps
120
- uses: codecov/codecov-action@v5
107
+ uses: codecov/codecov-action@v6
121
108
  with:
122
109
  files: ./coverage.xml
123
110
  flags: unit
124
111
  token: ${{ secrets.CODECOV_TOKEN }}
125
112
 
126
113
  integration-tests:
127
- name: integration-tests (Python ${{ matrix.python-version }}, ${{ matrix.arch }})
114
+ name: integration-tests (${{ matrix.os }})
128
115
  runs-on: ${{ matrix.os }}
129
116
  strategy:
130
117
  fail-fast: false
@@ -132,57 +119,82 @@ jobs:
132
119
  include:
133
120
  - arch: amd64
134
121
  os: ubuntu-24.04
135
- python-version: "3.13"
122
+ python-version: '3.13'
136
123
  - arch: arm64
137
124
  os: ubuntu-24.04-arm
138
- 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'
139
132
  steps:
140
133
  - uses: actions/checkout@v6
141
134
  with:
142
- ref: ${{ github.ref }}
143
135
  fetch-depth: 0
144
136
  - name: Set up uv
145
137
  uses: astral-sh/setup-uv@v7
146
138
  with:
147
139
  enable-cache: true
148
140
  python-version: ${{ matrix.python-version }}
149
- - name: Install system dependencies
150
- 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
+
151
148
  - name: Install dependencies
152
149
  run: uv sync --frozen --group dev
153
150
  - name: Run Integration Tests
154
- if: matrix.arch != 'amd64'
155
- 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
156
153
 
157
154
  - name: Run Integration Tests with Coverage
158
- if: matrix.arch == 'amd64'
159
- 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
160
157
 
161
158
  - name: Upload coverage reports to Codecov
162
- if: matrix.arch == 'amd64'
163
- uses: codecov/codecov-action@v5
159
+ if: matrix.os == 'ubuntu-24.04' && matrix.arch == 'amd64'
160
+ uses: codecov/codecov-action@v6
164
161
  with:
165
162
  files: ./coverage.xml
166
163
  flags: integration
167
164
  token: ${{ secrets.CODECOV_TOKEN }}
168
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
+
169
182
  docker-build:
170
- name: docker-build
183
+ name: docker-build (${{ matrix.arch }})
171
184
  needs: [ruff-lint, ruff-format, mypy-typecheck, unit-tests, integration-tests]
172
- # Only run on merges to main, release branches, tags, releases, or manual dispatch
173
- if: |
174
- github.event_name != 'pull_request' &&
175
- (github.ref == 'refs/heads/main' ||
176
- startsWith(github.ref, 'refs/heads/release/') ||
177
- startsWith(github.ref, 'refs/tags/v') ||
178
- github.event_name == 'release' ||
179
- github.event_name == 'workflow_dispatch')
180
- 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 }}
181
194
  steps:
182
195
  - name: Checkout repository
183
196
  uses: actions/checkout@v6
184
197
  with:
185
- ref: ${{ github.ref }}
186
198
  fetch-depth: 0
187
199
 
188
200
  - name: Set up Docker Buildx
@@ -194,48 +206,24 @@ jobs:
194
206
  context: .
195
207
  push: false
196
208
  load: true
197
- platforms: linux/amd64
198
- tags: "${{ github.repository_owner }}/${{ vars.DOCKER_IMAGE_NAME }}:${{ github.sha }}"
199
- cache-from: type=gha,scope=docker-build
200
- 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 }}
201
213
 
202
214
  - name: Smoke test Docker image
203
215
  run: |
204
216
  # Test CLI help
205
- 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
206
218
  # Test library import
207
- 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')"
208
220
 
209
221
  - name: Run Trivy vulnerability scanner
210
222
  uses: aquasecurity/trivy-action@0.35.0
211
223
  with:
212
- 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 }}"
213
225
  format: "table"
214
226
  exit-code: "0"
215
227
  ignore-unfixed: true
216
228
  vuln-type: "os,library"
217
229
  severity: "CRITICAL,HIGH"
218
-
219
- pypi-build:
220
- name: pypi-build
221
- needs: [ruff-lint, ruff-format, mypy-typecheck, unit-tests, integration-tests]
222
- # Only run on merges to main, release branches, tags, releases, or manual dispatch
223
- if: |
224
- github.event_name != 'pull_request' &&
225
- (github.ref == 'refs/heads/main' ||
226
- startsWith(github.ref, 'refs/heads/release/') ||
227
- startsWith(github.ref, 'refs/tags/v') ||
228
- github.event_name == 'release' ||
229
- github.event_name == 'workflow_dispatch')
230
- runs-on: ubuntu-latest
231
- steps:
232
- - uses: actions/checkout@v6
233
- with:
234
- ref: ${{ github.ref }}
235
- fetch-depth: 0
236
- - name: Set up uv
237
- uses: astral-sh/setup-uv@v7
238
- with:
239
- enable-cache: true
240
- - name: Build release distributions
241
- 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
@@ -8,10 +8,10 @@ on:
8
8
  workflows: ["CI"]
9
9
  types: [completed]
10
10
  branches:
11
- - 'v*'
11
+ - 'v[0-9]*'
12
12
 
13
13
  concurrency:
14
- group: ${{ github.workflow }}-${{ github.ref }}
14
+ group: ${{ github.workflow }}-${{ github.event.workflow_run.head_branch || github.ref_name }}
15
15
  cancel-in-progress: false
16
16
 
17
17
  permissions:
@@ -20,17 +20,22 @@ permissions:
20
20
  jobs:
21
21
  release-build:
22
22
  runs-on: ubuntu-latest
23
- # Only run if CI succeeded AND it was a release event.
24
- # 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.
25
25
  if: |
26
26
  github.event_name == 'workflow_run' &&
27
27
  github.event.workflow_run.conclusion == 'success' &&
28
- 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') &&
29
31
  github.event.workflow_run.head_repository.full_name == github.repository
30
32
  permissions:
31
33
  contents: read
32
34
  id-token: write
33
35
  attestations: write
36
+ outputs:
37
+ is_stable: ${{ steps.check_version.outputs.is_stable }}
38
+ version: ${{ steps.check_version.outputs.version }}
34
39
 
35
40
  steps:
36
41
  - uses: actions/checkout@v6
@@ -38,6 +43,18 @@ jobs:
38
43
  ref: ${{ github.event.workflow_run.head_sha }}
39
44
  fetch-depth: 0
40
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
+
41
58
  - name: Set up uv
42
59
  uses: astral-sh/setup-uv@v7
43
60
  with:
@@ -61,31 +78,41 @@ jobs:
61
78
  runs-on: ubuntu-latest
62
79
  needs:
63
80
  - release-build
81
+ if: needs.release-build.outputs.is_stable == 'true'
64
82
  permissions:
65
- # IMPORTANT: this permission is mandatory for trusted publishing
66
83
  id-token: write
67
-
68
- # Dedicated environments with protections for publishing are strongly recommended.
69
84
  environment:
70
85
  name: pypi
71
- url: https://pypi.org/project/PyStormTracker/${{ steps.get_version.outputs.version }}
72
-
86
+ url: https://pypi.org/project/PyStormTracker/${{ needs.release-build.outputs.version }}
73
87
  steps:
74
- - name: Get version from tag
75
- id: get_version
76
- run: |
77
- # Strips 'v' prefix from tag_name (e.g. v0.2.1 -> 0.2.1)
78
- # In workflow_run for a release, head_branch contains the tag name.
79
- VERSION=${{ github.event.workflow_run.head_branch }}
80
- echo "version=${VERSION#v}" >> $GITHUB_OUTPUT
81
-
82
88
  - name: Retrieve release distributions
83
89
  uses: actions/download-artifact@v8
84
90
  with:
85
91
  name: release-dists
86
92
  path: dist/
87
-
88
93
  - name: Publish release distributions to PyPI
89
94
  uses: pypa/gh-action-pypi-publish@release/v1
90
95
  with:
91
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.2"
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.2
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.