runtraj 0.1.0a1__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 (206) hide show
  1. runtraj-0.1.0a1/.copier-answers.yml +20 -0
  2. runtraj-0.1.0a1/.git_archival.txt +3 -0
  3. runtraj-0.1.0a1/.gitattributes +5 -0
  4. runtraj-0.1.0a1/.github/ISSUE_TEMPLATE/bug_report.yml +27 -0
  5. runtraj-0.1.0a1/.github/ISSUE_TEMPLATE/config.yml +5 -0
  6. runtraj-0.1.0a1/.github/ISSUE_TEMPLATE/feature_request.yml +17 -0
  7. runtraj-0.1.0a1/.github/dependabot.yml +27 -0
  8. runtraj-0.1.0a1/.github/pull_request_template.md +9 -0
  9. runtraj-0.1.0a1/.github/scripts/docs_versions.py +136 -0
  10. runtraj-0.1.0a1/.github/scripts/install_hysplit.sh +21 -0
  11. runtraj-0.1.0a1/.github/workflows/docs.yml +150 -0
  12. runtraj-0.1.0a1/.github/workflows/lock-upgrade.yml +94 -0
  13. runtraj-0.1.0a1/.github/workflows/publish.yml +103 -0
  14. runtraj-0.1.0a1/.github/workflows/quality.yml +51 -0
  15. runtraj-0.1.0a1/.github/workflows/tests.yml +208 -0
  16. runtraj-0.1.0a1/.github/zizmor.yml +10 -0
  17. runtraj-0.1.0a1/.gitignore +231 -0
  18. runtraj-0.1.0a1/.pre-commit-config.yaml +61 -0
  19. runtraj-0.1.0a1/.zenodo.json +14 -0
  20. runtraj-0.1.0a1/AGENTS.md +289 -0
  21. runtraj-0.1.0a1/CHANGELOG.md +45 -0
  22. runtraj-0.1.0a1/CITATION.cff +21 -0
  23. runtraj-0.1.0a1/CONTRIBUTING.md +549 -0
  24. runtraj-0.1.0a1/LICENSE +21 -0
  25. runtraj-0.1.0a1/PKG-INFO +193 -0
  26. runtraj-0.1.0a1/README.md +147 -0
  27. runtraj-0.1.0a1/cliff.toml +29 -0
  28. runtraj-0.1.0a1/codecov.yml +13 -0
  29. runtraj-0.1.0a1/docs/_ext/api_pages.py +407 -0
  30. runtraj-0.1.0a1/docs/_ext/config_docs.py +265 -0
  31. runtraj-0.1.0a1/docs/_ext/docs_examples.py +220 -0
  32. runtraj-0.1.0a1/docs/_static/custom.css +126 -0
  33. runtraj-0.1.0a1/docs/_static/favicon.ico +0 -0
  34. runtraj-0.1.0a1/docs/_static/logo.svg +1 -0
  35. runtraj-0.1.0a1/docs/_static/logo_dark.svg +1 -0
  36. runtraj-0.1.0a1/docs/_static/release_source_receptor.svg +89 -0
  37. runtraj-0.1.0a1/docs/_static/social-preview.png +0 -0
  38. runtraj-0.1.0a1/docs/_templates/autosummary/class.rst +63 -0
  39. runtraj-0.1.0a1/docs/_templates/autosummary/function.rst +5 -0
  40. runtraj-0.1.0a1/docs/_templates/autosummary/method.rst +6 -0
  41. runtraj-0.1.0a1/docs/_templates/autosummary/module.rst +41 -0
  42. runtraj-0.1.0a1/docs/_templates/layout.html +16 -0
  43. runtraj-0.1.0a1/docs/_tiles/usgs_shaded_relief/8/94/46.jpg +0 -0
  44. runtraj-0.1.0a1/docs/_tiles/usgs_shaded_relief/8/94/47.jpg +0 -0
  45. runtraj-0.1.0a1/docs/_tiles/usgs_shaded_relief/8/94/48.jpg +0 -0
  46. runtraj-0.1.0a1/docs/_tiles/usgs_shaded_relief/8/94/49.jpg +0 -0
  47. runtraj-0.1.0a1/docs/_tiles/usgs_shaded_relief/8/95/46.jpg +0 -0
  48. runtraj-0.1.0a1/docs/_tiles/usgs_shaded_relief/8/95/47.jpg +0 -0
  49. runtraj-0.1.0a1/docs/_tiles/usgs_shaded_relief/8/95/48.jpg +0 -0
  50. runtraj-0.1.0a1/docs/_tiles/usgs_shaded_relief/8/95/49.jpg +0 -0
  51. runtraj-0.1.0a1/docs/_tiles/usgs_shaded_relief/8/96/46.jpg +0 -0
  52. runtraj-0.1.0a1/docs/_tiles/usgs_shaded_relief/8/96/47.jpg +0 -0
  53. runtraj-0.1.0a1/docs/_tiles/usgs_shaded_relief/8/96/48.jpg +0 -0
  54. runtraj-0.1.0a1/docs/_tiles/usgs_shaded_relief/8/96/49.jpg +0 -0
  55. runtraj-0.1.0a1/docs/_tiles/usgs_shaded_relief/8/97/47.jpg +0 -0
  56. runtraj-0.1.0a1/docs/_tiles/usgs_shaded_relief/8/97/48.jpg +0 -0
  57. runtraj-0.1.0a1/docs/_tiles/usgs_shaded_relief/8/97/49.jpg +0 -0
  58. runtraj-0.1.0a1/docs/conf.py +286 -0
  59. runtraj-0.1.0a1/docs/development/architecture.rst +89 -0
  60. runtraj-0.1.0a1/docs/development/index.rst +47 -0
  61. runtraj-0.1.0a1/docs/getting_started/glossary.rst +195 -0
  62. runtraj-0.1.0a1/docs/getting_started/index.rst +23 -0
  63. runtraj-0.1.0a1/docs/getting_started/installation.rst +74 -0
  64. runtraj-0.1.0a1/docs/getting_started/quickstart.rst +269 -0
  65. runtraj-0.1.0a1/docs/guides/checking.rst +273 -0
  66. runtraj-0.1.0a1/docs/guides/choosing_settings.rst +190 -0
  67. runtraj-0.1.0a1/docs/guides/containers.rst +223 -0
  68. runtraj-0.1.0a1/docs/guides/hysplit_build.rst +100 -0
  69. runtraj-0.1.0a1/docs/guides/hysplit_users.rst +229 -0
  70. runtraj-0.1.0a1/docs/guides/index.rst +70 -0
  71. runtraj-0.1.0a1/docs/guides/meteorology.rst +297 -0
  72. runtraj-0.1.0a1/docs/guides/output.rst +80 -0
  73. runtraj-0.1.0a1/docs/guides/particles.rst +301 -0
  74. runtraj-0.1.0a1/docs/guides/projects.rst +310 -0
  75. runtraj-0.1.0a1/docs/guides/releases.rst +374 -0
  76. runtraj-0.1.0a1/docs/guides/running.rst +190 -0
  77. runtraj-0.1.0a1/docs/guides/slurm.rst +262 -0
  78. runtraj-0.1.0a1/docs/index.rst +68 -0
  79. runtraj-0.1.0a1/docs/reference/configuration.rst +180 -0
  80. runtraj-0.1.0a1/docs/reference/core.rst +134 -0
  81. runtraj-0.1.0a1/docs/reference/exceptions.rst +75 -0
  82. runtraj-0.1.0a1/docs/reference/execution.rst +119 -0
  83. runtraj-0.1.0a1/docs/reference/hysplit.rst +189 -0
  84. runtraj-0.1.0a1/docs/reference/index.rst +51 -0
  85. runtraj-0.1.0a1/docs/reference/layout.rst +281 -0
  86. runtraj-0.1.0a1/docs/reference/meteorology.rst +105 -0
  87. runtraj-0.1.0a1/docs/reference/particles.rst +181 -0
  88. runtraj-0.1.0a1/docs/reference/project.rst +23 -0
  89. runtraj-0.1.0a1/docs/reference/transforms.rst +85 -0
  90. runtraj-0.1.0a1/justfile +130 -0
  91. runtraj-0.1.0a1/pyproject.toml +286 -0
  92. runtraj-0.1.0a1/setup.cfg +4 -0
  93. runtraj-0.1.0a1/src/runtraj/__init__.py +56 -0
  94. runtraj-0.1.0a1/src/runtraj/__main__.py +12 -0
  95. runtraj-0.1.0a1/src/runtraj/_paths.py +128 -0
  96. runtraj-0.1.0a1/src/runtraj/_plugins.py +55 -0
  97. runtraj-0.1.0a1/src/runtraj/_transient.py +162 -0
  98. runtraj-0.1.0a1/src/runtraj/check.py +205 -0
  99. runtraj-0.1.0a1/src/runtraj/cli.py +906 -0
  100. runtraj-0.1.0a1/src/runtraj/config.py +1139 -0
  101. runtraj-0.1.0a1/src/runtraj/exceptions.py +106 -0
  102. runtraj-0.1.0a1/src/runtraj/execution/__init__.py +27 -0
  103. runtraj-0.1.0a1/src/runtraj/execution/config.py +360 -0
  104. runtraj-0.1.0a1/src/runtraj/execution/runner.py +917 -0
  105. runtraj-0.1.0a1/src/runtraj/execution/worker.py +970 -0
  106. runtraj-0.1.0a1/src/runtraj/fetch.py +79 -0
  107. runtraj-0.1.0a1/src/runtraj/identity.py +216 -0
  108. runtraj-0.1.0a1/src/runtraj/meteorology.py +284 -0
  109. runtraj-0.1.0a1/src/runtraj/models/__init__.py +601 -0
  110. runtraj-0.1.0a1/src/runtraj/models/hysplit/__init__.py +26 -0
  111. runtraj-0.1.0a1/src/runtraj/models/hysplit/catalog.py +487 -0
  112. runtraj-0.1.0a1/src/runtraj/models/hysplit/config.py +803 -0
  113. runtraj-0.1.0a1/src/runtraj/models/hysplit/control.py +191 -0
  114. runtraj-0.1.0a1/src/runtraj/models/hysplit/driver.py +628 -0
  115. runtraj-0.1.0a1/src/runtraj/models/hysplit/failures.py +77 -0
  116. runtraj-0.1.0a1/src/runtraj/models/hysplit/met.py +983 -0
  117. runtraj-0.1.0a1/src/runtraj/models/hysplit/model.py +346 -0
  118. runtraj-0.1.0a1/src/runtraj/models/hysplit/namelist.py +139 -0
  119. runtraj-0.1.0a1/src/runtraj/output.py +1166 -0
  120. runtraj-0.1.0a1/src/runtraj/particles/__init__.py +30 -0
  121. runtraj-0.1.0a1/src/runtraj/particles/_cf.py +154 -0
  122. runtraj-0.1.0a1/src/runtraj/particles/accessor.py +307 -0
  123. runtraj-0.1.0a1/src/runtraj/particles/table.py +494 -0
  124. runtraj-0.1.0a1/src/runtraj/project.py +1088 -0
  125. runtraj-0.1.0a1/src/runtraj/py.typed +2 -0
  126. runtraj-0.1.0a1/src/runtraj/releases/__init__.py +44 -0
  127. runtraj-0.1.0a1/src/runtraj/releases/models.py +660 -0
  128. runtraj-0.1.0a1/src/runtraj/releases/table.py +580 -0
  129. runtraj-0.1.0a1/src/runtraj/releases/validation.py +87 -0
  130. runtraj-0.1.0a1/src/runtraj/sampling.py +700 -0
  131. runtraj-0.1.0a1/src/runtraj/simulation.py +271 -0
  132. runtraj-0.1.0a1/src/runtraj/spatial.py +238 -0
  133. runtraj-0.1.0a1/src/runtraj/stages.py +350 -0
  134. runtraj-0.1.0a1/src/runtraj/transforms/__init__.py +215 -0
  135. runtraj-0.1.0a1/src/runtraj/transforms/_common.py +93 -0
  136. runtraj-0.1.0a1/src/runtraj/transforms/averaging_kernel.py +356 -0
  137. runtraj-0.1.0a1/src/runtraj/transforms/deposition.py +137 -0
  138. runtraj-0.1.0a1/src/runtraj/transforms/lifetime.py +114 -0
  139. runtraj-0.1.0a1/src/runtraj/transforms/oxidation.py +275 -0
  140. runtraj-0.1.0a1/src/runtraj/transforms/pressure_weighting.py +192 -0
  141. runtraj-0.1.0a1/src/runtraj/visualization.py +453 -0
  142. runtraj-0.1.0a1/src/runtraj.egg-info/PKG-INFO +193 -0
  143. runtraj-0.1.0a1/src/runtraj.egg-info/SOURCES.txt +204 -0
  144. runtraj-0.1.0a1/src/runtraj.egg-info/dependency_links.txt +1 -0
  145. runtraj-0.1.0a1/src/runtraj.egg-info/entry_points.txt +2 -0
  146. runtraj-0.1.0a1/src/runtraj.egg-info/requires.txt +23 -0
  147. runtraj-0.1.0a1/src/runtraj.egg-info/scm_file_list.json +200 -0
  148. runtraj-0.1.0a1/src/runtraj.egg-info/scm_version.json +8 -0
  149. runtraj-0.1.0a1/src/runtraj.egg-info/top_level.txt +1 -0
  150. runtraj-0.1.0a1/tests/__init__.py +1 -0
  151. runtraj-0.1.0a1/tests/conftest.py +240 -0
  152. runtraj-0.1.0a1/tests/execution/__init__.py +1 -0
  153. runtraj-0.1.0a1/tests/execution/test_main_guard.py +157 -0
  154. runtraj-0.1.0a1/tests/execution/test_runner.py +1020 -0
  155. runtraj-0.1.0a1/tests/execution/test_signals.py +235 -0
  156. runtraj-0.1.0a1/tests/execution/test_stages.py +572 -0
  157. runtraj-0.1.0a1/tests/execution/test_worker.py +712 -0
  158. runtraj-0.1.0a1/tests/fixtures/__init__.py +1 -0
  159. runtraj-0.1.0a1/tests/fixtures/factories.py +264 -0
  160. runtraj-0.1.0a1/tests/fixtures/output.py +73 -0
  161. runtraj-0.1.0a1/tests/fixtures/particles.py +66 -0
  162. runtraj-0.1.0a1/tests/fixtures/runs.py +40 -0
  163. runtraj-0.1.0a1/tests/fixtures/stages.py +201 -0
  164. runtraj-0.1.0a1/tests/integration/__init__.py +0 -0
  165. runtraj-0.1.0a1/tests/integration/conftest.py +71 -0
  166. runtraj-0.1.0a1/tests/integration/test_object_store.py +85 -0
  167. runtraj-0.1.0a1/tests/integration/test_runs.py +216 -0
  168. runtraj-0.1.0a1/tests/integration/test_sample_met.py +190 -0
  169. runtraj-0.1.0a1/tests/integration/test_varsiwant.py +39 -0
  170. runtraj-0.1.0a1/tests/models/__init__.py +1 -0
  171. runtraj-0.1.0a1/tests/models/hysplit/__init__.py +1 -0
  172. runtraj-0.1.0a1/tests/models/hysplit/test_catalog.py +293 -0
  173. runtraj-0.1.0a1/tests/models/hysplit/test_config.py +150 -0
  174. runtraj-0.1.0a1/tests/models/hysplit/test_driver.py +1311 -0
  175. runtraj-0.1.0a1/tests/models/hysplit/test_exit_status.py +169 -0
  176. runtraj-0.1.0a1/tests/models/hysplit/test_failures.py +59 -0
  177. runtraj-0.1.0a1/tests/models/hysplit/test_met.py +1525 -0
  178. runtraj-0.1.0a1/tests/models/hysplit/test_met_archives.py +215 -0
  179. runtraj-0.1.0a1/tests/models/hysplit/test_release_assignment.py +226 -0
  180. runtraj-0.1.0a1/tests/models/hysplit/test_timeout.py +66 -0
  181. runtraj-0.1.0a1/tests/models/test_models.py +348 -0
  182. runtraj-0.1.0a1/tests/models/test_transport.py +300 -0
  183. runtraj-0.1.0a1/tests/particles/__init__.py +0 -0
  184. runtraj-0.1.0a1/tests/particles/test_accessor.py +165 -0
  185. runtraj-0.1.0a1/tests/particles/test_cf.py +182 -0
  186. runtraj-0.1.0a1/tests/particles/test_table.py +678 -0
  187. runtraj-0.1.0a1/tests/test_check.py +415 -0
  188. runtraj-0.1.0a1/tests/test_cli.py +1015 -0
  189. runtraj-0.1.0a1/tests/test_config.py +576 -0
  190. runtraj-0.1.0a1/tests/test_docs_examples.py +185 -0
  191. runtraj-0.1.0a1/tests/test_exceptions.py +77 -0
  192. runtraj-0.1.0a1/tests/test_fetch.py +338 -0
  193. runtraj-0.1.0a1/tests/test_fetch_signals.py +57 -0
  194. runtraj-0.1.0a1/tests/test_identity.py +330 -0
  195. runtraj-0.1.0a1/tests/test_output.py +428 -0
  196. runtraj-0.1.0a1/tests/test_pkg.py +23 -0
  197. runtraj-0.1.0a1/tests/test_project.py +728 -0
  198. runtraj-0.1.0a1/tests/test_releases.py +1423 -0
  199. runtraj-0.1.0a1/tests/test_releases_group_dtype.py +58 -0
  200. runtraj-0.1.0a1/tests/test_sampling.py +478 -0
  201. runtraj-0.1.0a1/tests/test_spatial.py +93 -0
  202. runtraj-0.1.0a1/tests/test_stages.py +377 -0
  203. runtraj-0.1.0a1/tests/test_transforms.py +1287 -0
  204. runtraj-0.1.0a1/tests/test_variograms.py +198 -0
  205. runtraj-0.1.0a1/tests/test_visualization.py +372 -0
  206. runtraj-0.1.0a1/uv.lock +5279 -0
@@ -0,0 +1,20 @@
1
+ # Changes here will be overwritten by Copier; NEVER EDIT MANUALLY
2
+ _commit: v1.4.0
3
+ _src_path: gh:jmineau/python-template
4
+ affiliation: University of Utah
5
+ copyright_year: '2025'
6
+ distribution_name: runtraj
7
+ docs_notebooks: false
8
+ email: jameskmineau@gmail.com
9
+ full_name: James Mineau
10
+ github_username: jmineau
11
+ orcid: 0000-0002-2289-2252
12
+ package_name: runtraj
13
+ project_name: runtraj
14
+ project_short_description: Run particle dispersion models at scale.
15
+ publish_to_pypi: true
16
+ python_min: '3.11'
17
+ repository_name: runtraj
18
+ test_os:
19
+ - ubuntu-latest
20
+ - macos-latest
@@ -0,0 +1,3 @@
1
+ node: $Format:%H$
2
+ node-date: $Format:%cI$
3
+ describe-name: $Format:%(describe:tags=true,match=v[0-9]*)$
@@ -0,0 +1,5 @@
1
+ # Ignore .ASC files for GitHub Linguist
2
+ *.ASC linguist-vendored
3
+
4
+ # setuptools-scm reads the version of a GitHub or Zenodo archive from this file
5
+ .git_archival.txt export-subst
@@ -0,0 +1,27 @@
1
+ name: Bug report
2
+ description: Something in runtraj raises, crashes, or gives wrong results
3
+ labels: ["bug"]
4
+ body:
5
+ - type: textarea
6
+ id: what
7
+ attributes:
8
+ label: What happened?
9
+ description: What you did, what you expected, and what happened instead.
10
+ validations:
11
+ required: true
12
+ - type: textarea
13
+ id: repro
14
+ attributes:
15
+ label: Minimal example
16
+ description: The shortest code that shows the problem. Include the full traceback if there is one.
17
+ render: python
18
+ validations:
19
+ required: true
20
+ - type: textarea
21
+ id: versions
22
+ attributes:
23
+ label: Versions
24
+ description: Output of `python -c "import runtraj, sys; print(runtraj.__version__, sys.version)"` and your OS.
25
+ render: text
26
+ validations:
27
+ required: true
@@ -0,0 +1,5 @@
1
+ blank_issues_enabled: true
2
+ contact_links:
3
+ - name: Documentation
4
+ url: https://jmineau.github.io/runtraj/
5
+ about: User guides and the API reference.
@@ -0,0 +1,17 @@
1
+ name: Feature request
2
+ description: Suggest a new capability or an API improvement
3
+ labels: ["enhancement"]
4
+ body:
5
+ - type: textarea
6
+ id: problem
7
+ attributes:
8
+ label: What are you trying to do?
9
+ description: The workflow or analysis this would support, and what gets in the way today.
10
+ validations:
11
+ required: true
12
+ - type: textarea
13
+ id: proposal
14
+ attributes:
15
+ label: Proposed API or behavior
16
+ description: What you would like to be able to write. Sketches are welcome.
17
+ render: python
@@ -0,0 +1,27 @@
1
+ # Dependabot opens pull requests that update pinned versions. Each ecosystem
2
+ # gets one grouped PR a month, and skips releases younger than a week
3
+ # (supply-chain safety). CI runs on each PR; merge it or close it. uv.lock is
4
+ # not here: the Upgrade lock workflow (.github/workflows/lock-upgrade.yml) does it.
5
+ version: 2
6
+ updates:
7
+ # Actions used by the workflows (actions/checkout@v7, ...)
8
+ - package-ecosystem: github-actions
9
+ directory: /
10
+ schedule:
11
+ interval: monthly
12
+ cooldown:
13
+ default-days: 7
14
+ groups:
15
+ actions:
16
+ patterns: ["*"]
17
+
18
+ # Hook revs in .pre-commit-config.yaml (ruff and pyrefly come from uv.lock)
19
+ - package-ecosystem: pre-commit
20
+ directory: /
21
+ schedule:
22
+ interval: monthly
23
+ cooldown:
24
+ default-days: 7
25
+ groups:
26
+ pre-commit:
27
+ patterns: ["*"]
@@ -0,0 +1,9 @@
1
+ ## Summary
2
+
3
+ <!-- What does this change, and why? Link the issue it addresses (e.g. "Fixes #123"). -->
4
+
5
+ ## Checklist
6
+
7
+ - [ ] Tests added or updated
8
+ - [ ] `just quality-check` passes (lint, type check, docstrings, tests)
9
+ - [ ] Docs updated for any public API change (`just build-docs` has no warnings)
@@ -0,0 +1,136 @@
1
+ """
2
+ Publish one docs build into the versioned GitHub Pages site.
3
+
4
+ The site (the gh-pages branch) holds one folder per published version::
5
+
6
+ dev/ the main branch
7
+ 0.2.0/ each release, by version
8
+ stable/ a copy of the newest final release
9
+ switcher.json the version dropdown's entries
10
+ index.html redirects to stable/ (or dev/ before the first release)
11
+ 404.html sends links from before versioning to the same page in stable/
12
+ .nojekyll makes GitHub Pages serve the branch as it is
13
+
14
+ GitHub Pages serves the branch (Settings > Pages > Source: Deploy from a
15
+ branch), so a push to it publishes the site.
16
+
17
+ Run by the Documentation workflow: ``python docs_versions.py SITE HTML TARGET``,
18
+ where TARGET is ``dev`` or a version such as ``0.2.0``.
19
+ """
20
+
21
+ import argparse
22
+ import json
23
+ import shutil
24
+ from pathlib import Path
25
+
26
+ from packaging.version import InvalidVersion, Version
27
+
28
+
29
+ def _version(name: str) -> Version | None:
30
+ try:
31
+ return Version(name)
32
+ except InvalidVersion:
33
+ return None
34
+
35
+
36
+ def main() -> None:
37
+ """Copy the build into place, then rewrite the switcher and redirects."""
38
+ parser = argparse.ArgumentParser(description=__doc__.split("\n\n")[0])
39
+ parser.add_argument("site", type=Path, help="checkout of the gh-pages branch")
40
+ parser.add_argument("html", type=Path, help="the new HTML build")
41
+ parser.add_argument("target", help='"dev" or the release version')
42
+ parser.add_argument("--base-url", required=True, help="the site's URL, ending in /")
43
+ parser.add_argument(
44
+ "--prereleases",
45
+ choices=["upcoming", "all", "none"],
46
+ default="upcoming",
47
+ help=(
48
+ "upcoming: list pre-releases newer than the latest final release and "
49
+ "delete older ones; all: list every pre-release; none: list none"
50
+ ),
51
+ )
52
+ args = parser.parse_args()
53
+ site, base = args.site, args.base_url
54
+
55
+ if args.target != "dev" and _version(args.target) is None:
56
+ parser.error(f"{args.target!r} is neither 'dev' nor a PEP 440 version")
57
+ shutil.rmtree(site / args.target, ignore_errors=True)
58
+ shutil.copytree(args.html, site / args.target)
59
+
60
+ # Every version folder, newest first. Folder names are the tags without "v".
61
+ versions = sorted(
62
+ ((d.name, v) for d in site.iterdir() if d.is_dir() and (v := _version(d.name))),
63
+ key=lambda item: item[1],
64
+ reverse=True,
65
+ )
66
+ finals = [name for name, v in versions if not v.is_prerelease]
67
+ latest_final = _version(finals[0]) if finals else None
68
+
69
+ def listed(v: Version) -> bool:
70
+ if not v.is_prerelease or args.prereleases == "all":
71
+ return True
72
+ if args.prereleases == "none":
73
+ return False
74
+ return latest_final is None or v > latest_final # "upcoming"
75
+
76
+ if args.prereleases == "upcoming":
77
+ for name, v in versions:
78
+ if not listed(v):
79
+ shutil.rmtree(site / name) # superseded by a final release
80
+ versions = [(name, v) for name, v in versions if listed(v)]
81
+ shown = [name for name, v in versions if listed(v)]
82
+
83
+ # stable/ is the newest final release; before the first one, the newest of any.
84
+ stable = finals[0] if finals else (versions[0][0] if versions else None)
85
+ shutil.rmtree(site / "stable", ignore_errors=True)
86
+ if stable:
87
+ shutil.copytree(site / stable, site / "stable")
88
+
89
+ entries = []
90
+ if (site / "dev").is_dir():
91
+ entries.append({"name": "dev", "version": "dev", "url": f"{base}dev/"})
92
+ for name in shown:
93
+ if name == stable:
94
+ label = "latest" if Version(name).is_prerelease else "stable"
95
+ entries.append(
96
+ {
97
+ "name": f"{name} ({label})",
98
+ "version": name,
99
+ "url": f"{base}stable/",
100
+ "preferred": True,
101
+ }
102
+ )
103
+ else:
104
+ entries.append({"name": name, "version": name, "url": f"{base}{name}/"})
105
+ (site / "switcher.json").write_text(json.dumps(entries, indent=2) + "\n")
106
+
107
+ # Without this file GitHub Pages runs Jekyll on the branch, which drops
108
+ # every _static/ and _sources/ folder.
109
+ (site / ".nojekyll").touch()
110
+
111
+ home = "stable" if stable else "dev"
112
+ (site / "index.html").write_text(
113
+ f'<!doctype html>\n<meta charset="utf-8">\n<title>Redirecting</title>\n'
114
+ f'<meta http-equiv="refresh" content="0; url={home}/">\n'
115
+ f'<link rel="canonical" href="{base}{home}/">\n<a href="{home}/">Go to the documentation</a>\n'
116
+ )
117
+ known = json.dumps(["dev", "stable", *(name for name, _ in versions)])
118
+ (site / "404.html").write_text(
119
+ f"""<!doctype html>
120
+ <meta charset="utf-8">
121
+ <title>Page not found</title>
122
+ <script>
123
+ // A link from before the docs were versioned (e.g. .../api.html): retry it in {home}/.
124
+ const root = new URL("{base}").pathname;
125
+ const rest = location.pathname.startsWith(root) ? location.pathname.slice(root.length) : "";
126
+ if (rest && !{known}.includes(rest.split("/")[0])) {{
127
+ location.replace(root + "{home}/" + rest + location.search + location.hash);
128
+ }}
129
+ </script>
130
+ <p>Page not found. <a href="{base}">Go to the documentation</a>.</p>
131
+ """
132
+ )
133
+
134
+
135
+ if __name__ == "__main__":
136
+ main()
@@ -0,0 +1,21 @@
1
+ #!/usr/bin/env bash
2
+ # Install a Linux HYSPLIT as a HYSPLIT folder: /opt/hysplit/exec/hycs_std and
3
+ # the four data tables in /opt/hysplit/bdyfiles/, with hycs_std on PATH.
4
+ # runtraj includes no HYSPLIT, so the jobs that run it take the v5.1.0 build
5
+ # that the repository below publishes, at the commit below.
6
+ set -euo pipefail
7
+ sha="278b1ef6d542efd21c6ccab2a85b796acd9812a6"
8
+ repo="uataq/stilt"
9
+ base="https://raw.githubusercontent.com/$repo/$sha"
10
+ tmp="$(mktemp -d)"
11
+ mkdir -p "$tmp/exec" "$tmp/bdyfiles"
12
+ curl -fsSL --retry 3 -o "$tmp/exec/hycs_std" "$base/bin/linux_x64/hycs_std"
13
+ for table in ASCDATA.CFG LANDUSE.ASC ROUGLEN.ASC TERRAIN.ASC; do
14
+ curl -fsSL --retry 3 -o "$tmp/bdyfiles/$table" "$base/exe/$table"
15
+ done
16
+ chmod +x "$tmp/exec/hycs_std"
17
+ sudo mkdir -p /opt
18
+ sudo mv "$tmp" /opt/hysplit
19
+ sudo ln -sf /opt/hysplit/exec/hycs_std /usr/local/bin/hycs_std
20
+ echo "HYSPLIT of $repo@$sha in /opt/hysplit:"
21
+ (cd /opt/hysplit && sha256sum exec/hycs_std bdyfiles/*)
@@ -0,0 +1,150 @@
1
+ name: Documentation
2
+
3
+ # Pull requests build the docs (warnings fail the build). Pushes to main publish
4
+ # them as dev/, release tags as <version>/ (final releases also as stable/), with
5
+ # a version dropdown. The gh-pages branch is the site: .github/scripts/
6
+ # docs_versions.py adds each build to it, and GitHub Pages serves the branch
7
+ # (Settings > Pages > Source: Deploy from a branch), rebuilding after each push.
8
+ on:
9
+ push:
10
+ branches: [main]
11
+ tags: ["v*"]
12
+ pull_request:
13
+ branches: [main]
14
+ workflow_dispatch:
15
+
16
+ permissions:
17
+ contents: read
18
+
19
+ concurrency:
20
+ group: docs-${{ github.ref }}
21
+ cancel-in-progress: ${{ github.event_name == 'pull_request' }}
22
+
23
+ env:
24
+ # Which pre-releases (a, b, rc) the dropdown lists:
25
+ # upcoming: those newer than the latest final release; older ones are deleted
26
+ # from the site once their final release is out
27
+ # all: every pre-release ever published
28
+ # none: no pre-releases (their folders are kept but not listed)
29
+ DOCS_PRERELEASES: upcoming
30
+
31
+ jobs:
32
+ build:
33
+ runs-on: ubuntu-latest
34
+ env:
35
+ UV_NO_SYNC: "1" # `just` recipes run in the environment synced below
36
+
37
+ steps:
38
+ - uses: actions/checkout@v7
39
+ with:
40
+ persist-credentials: false
41
+ fetch-depth: 0 # setuptools-scm reads the version from tags
42
+
43
+ - uses: astral-sh/setup-uv@v10.3.3
44
+ with:
45
+ version: "0.12.23"
46
+ python-version: "3.14"
47
+
48
+ - name: Install
49
+ run: uv sync --locked
50
+
51
+ # The pages that run a simulation need a hycs_std.
52
+ - name: Install HYSPLIT
53
+ run: .github/scripts/install_hysplit.sh
54
+
55
+ # The Getting Started page runs a real simulation on the met files the
56
+ # tests cache: the same cache and key as tests.yml.
57
+ - name: Restore HRRR met cache
58
+ id: met-cache
59
+ uses: actions/cache/restore@v6
60
+ with:
61
+ path: tests/met_cache
62
+ key: met-hrrr-2021-v1
63
+
64
+ - name: Prewarm HRRR met cache
65
+ if: steps.met-cache.outputs.cache-hit != 'true'
66
+ env:
67
+ RUNTRAJ_TEST_FETCH_MET: "1"
68
+ run: |
69
+ uv run pytest \
70
+ tests/models/hysplit/test_release_assignment.py::test_hysplit_multipoint_release_points_follow_control_order \
71
+ --setup-only -q
72
+
73
+ - name: Save HRRR met cache
74
+ if: steps.met-cache.outputs.cache-hit != 'true'
75
+ uses: actions/cache/save@v6
76
+ with:
77
+ path: tests/met_cache
78
+ key: ${{ steps.met-cache.outputs.cache-primary-key }}
79
+
80
+ - name: Build
81
+ env:
82
+ RUNTRAJ_TEST_MET_DIR: ${{ github.workspace }}/tests/met_cache
83
+ run: uv run just build-docs
84
+
85
+ - uses: actions/upload-artifact@v7
86
+ if: github.event_name != 'pull_request'
87
+ with:
88
+ name: docs-html
89
+ path: docs/_build/html
90
+
91
+ deploy:
92
+ if: github.event_name != 'pull_request' && (github.ref == 'refs/heads/main' || startsWith(github.ref, 'refs/tags/v'))
93
+ needs: build
94
+ runs-on: ubuntu-latest
95
+ concurrency:
96
+ group: docs-deploy # one update of the gh-pages branch at a time
97
+ cancel-in-progress: false
98
+ permissions:
99
+ contents: write # push the gh-pages branch
100
+
101
+ steps:
102
+ - uses: actions/checkout@v7
103
+ with:
104
+ persist-credentials: false
105
+ path: src
106
+
107
+ - uses: actions/download-artifact@v8
108
+ with:
109
+ name: docs-html
110
+ path: html
111
+
112
+ - uses: astral-sh/setup-uv@v10.3.3
113
+ with:
114
+ version: "0.12.23"
115
+
116
+ - name: Check out the gh-pages branch
117
+ env:
118
+ GH_TOKEN: ${{ github.token }}
119
+ run: |
120
+ gh auth setup-git
121
+ if git ls-remote --exit-code --heads "https://github.com/$GITHUB_REPOSITORY" gh-pages > /dev/null; then
122
+ git clone --quiet --single-branch --branch gh-pages "https://github.com/$GITHUB_REPOSITORY" site
123
+ else
124
+ git init --quiet site
125
+ git -C site checkout --quiet --orphan gh-pages
126
+ fi
127
+
128
+ - name: Add this build to the site
129
+ run: |
130
+ if [ "$GITHUB_REF_TYPE" = tag ]; then target="${GITHUB_REF_NAME#v}"; else target=dev; fi
131
+ echo "target=$target" >> "$GITHUB_ENV"
132
+ uv run --no-project --with packaging python src/.github/scripts/docs_versions.py \
133
+ site html "$target" \
134
+ --base-url "https://jmineau.github.io/runtraj/" \
135
+ --prereleases "$DOCS_PRERELEASES"
136
+
137
+ # GitHub Pages serves the branch, so this push publishes the site: its
138
+ # "pages build and deployment" run (in the Actions tab) finishes within a
139
+ # minute. A push by the workflow's own token does trigger that run.
140
+ - name: Push the gh-pages branch
141
+ env:
142
+ GH_TOKEN: ${{ github.token }}
143
+ run: |
144
+ cd site
145
+ git add --all
146
+ if git diff --cached --quiet; then echo "No changes."; exit 0; fi
147
+ git -c user.name="github-actions[bot]" -c user.email="41898282+github-actions[bot]@users.noreply.github.com" \
148
+ commit --quiet -m "docs: publish $target"
149
+ if ! git remote | grep -q origin; then git remote add origin "https://github.com/$GITHUB_REPOSITORY"; fi
150
+ git push --quiet origin gh-pages
@@ -0,0 +1,94 @@
1
+ name: Upgrade lock
2
+
3
+ # Once a month, re-lock every dependency to its newest release and open one pull
4
+ # request when uv.lock changes (`uv lock --upgrade`). It is the only thing that
5
+ # updates uv.lock (Dependabot does actions and pre-commit hooks). Dependabot's uv
6
+ # updates would leave a package whose newest release needs a newer Python than the
7
+ # oldest one this project supports at its old version, so CI would test a release
8
+ # that users on a newer Python no longer get. `uv lock --upgrade` locks the newest
9
+ # release for each Python (a fork in uv.lock).
10
+ #
11
+ # Setup, once: Settings > Actions > General > Workflow permissions > tick "Allow
12
+ # GitHub Actions to create and approve pull requests".
13
+ #
14
+ # A pull request opened with the workflow's own token does not start the other
15
+ # workflows, so this one starts Tests, Code Quality and Documentation
16
+ # on the branch itself (workflow_dispatch is the one event the token may trigger); their
17
+ # results show on the pull request.
18
+ on:
19
+ schedule:
20
+ - cron: "0 6 1 * *" # 06:00 UTC on the 1st of each month
21
+ workflow_dispatch:
22
+
23
+ permissions:
24
+ contents: read
25
+
26
+ concurrency:
27
+ group: lock-upgrade
28
+ cancel-in-progress: false
29
+
30
+ env:
31
+ BRANCH: chore/lock-upgrade
32
+
33
+ jobs:
34
+ upgrade:
35
+ runs-on: ubuntu-latest
36
+ permissions:
37
+ contents: write # push the branch
38
+ pull-requests: write # open or update the pull request
39
+ actions: write # start the other workflows on the branch
40
+
41
+ steps:
42
+ - uses: actions/checkout@v7
43
+ with:
44
+ persist-credentials: false
45
+ fetch-depth: 0 # setuptools-scm reads the version from tags
46
+
47
+ - uses: astral-sh/setup-uv@v10.3.3
48
+ with:
49
+ version: "0.12.23"
50
+ python-version: "3.14"
51
+
52
+ - name: Upgrade uv.lock
53
+ id: upgrade
54
+ run: |
55
+ set -euo pipefail
56
+ uv lock --upgrade 2>&1 | tee "$RUNNER_TEMP/lock.log"
57
+ if git diff --quiet -- uv.lock; then
58
+ echo "uv.lock is already up to date."
59
+ exit 0
60
+ fi
61
+ {
62
+ echo "Monthly \`uv lock --upgrade\`: the newest release of every dependency, for each supported Python."
63
+ echo
64
+ echo '```'
65
+ grep -E '^(Added|Removed|Updated) ' "$RUNNER_TEMP/lock.log" || true
66
+ echo '```'
67
+ echo
68
+ echo "Tests, Code Quality and Documentation were started on this branch by the workflow run: $GITHUB_SERVER_URL/$GITHUB_REPOSITORY/actions/runs/$GITHUB_RUN_ID"
69
+ echo "Merge it when they pass."
70
+ } > "$RUNNER_TEMP/body.md"
71
+ echo "changed=true" >> "$GITHUB_OUTPUT"
72
+
73
+ - name: Push the branch, open or update the pull request, start the checks
74
+ if: steps.upgrade.outputs.changed == 'true'
75
+ env:
76
+ GH_TOKEN: ${{ github.token }}
77
+ run: |
78
+ set -euo pipefail
79
+ gh auth setup-git
80
+ git checkout --quiet -b "$BRANCH"
81
+ git add uv.lock
82
+ git -c user.name="github-actions[bot]" -c user.email="41898282+github-actions[bot]@users.noreply.github.com" \
83
+ commit --quiet -m "chore(deps): upgrade uv.lock"
84
+ git push --quiet --force origin "$BRANCH" # the branch belongs to this workflow
85
+ number="$(gh pr list --head "$BRANCH" --state open --json number --jq '.[0].number // empty')"
86
+ if [ -n "$number" ]; then
87
+ gh pr edit "$number" --body-file "$RUNNER_TEMP/body.md"
88
+ else
89
+ gh pr create --base main --head "$BRANCH" --title "chore(deps): upgrade uv.lock" \
90
+ --body-file "$RUNNER_TEMP/body.md"
91
+ fi
92
+ for workflow in tests.yml quality.yml docs.yml; do
93
+ gh workflow run "$workflow" --ref "$BRANCH"
94
+ done
@@ -0,0 +1,103 @@
1
+ name: Publish
2
+
3
+ # Pushing a vX.Y.Z tag (see `just release`) builds the package from that tag,
4
+ # publishes it to PyPI with trusted publishing, and creates a GitHub Release
5
+ # from the tag's CHANGELOG.md section. Zenodo archives each GitHub Release.
6
+ #
7
+ # Keep this file's name: the PyPI trusted publisher is registered for it.
8
+ on:
9
+ push:
10
+ tags: ["v*"]
11
+
12
+ permissions:
13
+ contents: read
14
+
15
+ jobs:
16
+ build:
17
+ runs-on: ubuntu-latest
18
+ env:
19
+ UV_NO_SYNC: "1" # `just` recipes run in the environment synced below
20
+ steps:
21
+ - uses: actions/checkout@v7
22
+ with:
23
+ persist-credentials: false
24
+ fetch-depth: 0 # setuptools-scm reads the version from tags
25
+
26
+ - uses: astral-sh/setup-uv@v10.3.3
27
+ with:
28
+ version: "0.12.23"
29
+ python-version: "3.14"
30
+
31
+ - name: Install
32
+ run: uv sync --locked
33
+
34
+ - name: Build and check
35
+ run: uv run just dist
36
+
37
+ - name: Check the version matches the tag
38
+ run: |
39
+ version="$(uv run python -m setuptools_scm)"
40
+ if [ "v$version" != "$GITHUB_REF_NAME" ]; then
41
+ echo "::error::setuptools-scm computed $version, but the tag is $GITHUB_REF_NAME"
42
+ exit 1
43
+ fi
44
+
45
+ - uses: actions/upload-artifact@v7
46
+ with:
47
+ name: dist
48
+ path: dist/
49
+
50
+ publish-pypi:
51
+ needs: build
52
+ runs-on: ubuntu-latest
53
+ environment:
54
+ name: pypi
55
+ url: https://pypi.org/p/runtraj
56
+ permissions:
57
+ id-token: write # trusted publishing (OIDC); also signs attestations
58
+ steps:
59
+ - uses: actions/download-artifact@v8
60
+ with:
61
+ name: dist
62
+ path: dist/
63
+
64
+ - uses: pypa/gh-action-pypi-publish@release/v1
65
+ with:
66
+ # Re-running a tag (a retried job) must not fail on a version PyPI
67
+ # already has.
68
+ skip-existing: true
69
+
70
+ github-release:
71
+ needs: publish-pypi
72
+ runs-on: ubuntu-latest
73
+ permissions:
74
+ contents: write
75
+ steps:
76
+ - uses: actions/checkout@v7
77
+ with:
78
+ persist-credentials: false
79
+
80
+ - uses: actions/download-artifact@v8
81
+ with:
82
+ name: dist
83
+ path: dist/
84
+
85
+ - name: Extract the CHANGELOG section
86
+ run: |
87
+ version="${GITHUB_REF_NAME#v}"
88
+ awk -v v="$version" '
89
+ index($0, "## [" v "]") == 1 { found = 1; next }
90
+ /^## \[/ { if (found) exit }
91
+ found { print }
92
+ ' CHANGELOG.md > release-notes.md
93
+ test -s release-notes.md || { echo "::error::CHANGELOG.md has no '## [$version]' section"; exit 1; }
94
+
95
+ - name: Create the GitHub Release
96
+ env:
97
+ GH_TOKEN: ${{ github.token }}
98
+ run: |
99
+ prerelease=()
100
+ # PEP 440 pre-releases (a, b, rc) and dev releases
101
+ if [[ "$GITHUB_REF_NAME" =~ (a|b|rc)[0-9]+$|\.dev[0-9]+$ ]]; then prerelease=(--prerelease); fi
102
+ gh release create "$GITHUB_REF_NAME" dist/* --verify-tag \
103
+ --title "$GITHUB_REF_NAME" --notes-file release-notes.md "${prerelease[@]}"
@@ -0,0 +1,51 @@
1
+ name: Code Quality
2
+
3
+ on:
4
+ push:
5
+ branches: [main]
6
+ pull_request:
7
+ branches: [main]
8
+ workflow_dispatch:
9
+
10
+ permissions:
11
+ contents: read
12
+
13
+ concurrency:
14
+ group: ${{ github.workflow }}-${{ github.ref }}
15
+ cancel-in-progress: true
16
+
17
+ jobs:
18
+ quality:
19
+ runs-on: ubuntu-latest
20
+ env:
21
+ UV_NO_SYNC: "1" # `just` recipes run in the environment synced below
22
+ RUFF_OUTPUT_FORMAT: github # annotate the PR diff
23
+
24
+ steps:
25
+ - uses: actions/checkout@v7
26
+ with:
27
+ persist-credentials: false
28
+ fetch-depth: 0 # setuptools-scm reads the version from tags
29
+
30
+ - uses: astral-sh/setup-uv@v10.3.3
31
+ with:
32
+ version: "0.12.23"
33
+ python-version: "3.11"
34
+
35
+ - name: Install
36
+ run: uv sync --locked
37
+
38
+ - name: Lint and format check
39
+ run: uv run just lint
40
+
41
+ - name: Type check
42
+ if: ${{ !cancelled() }}
43
+ run: uv run just type-check
44
+
45
+ - name: Import contracts
46
+ if: ${{ !cancelled() }}
47
+ run: uv run just imports
48
+
49
+ - name: Docstring coverage
50
+ if: ${{ !cancelled() }}
51
+ run: uv run just docstr