gasfir 2.0.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 (143) hide show
  1. gasfir-2.0.0/.flake8 +50 -0
  2. gasfir-2.0.0/.gitattributes +32 -0
  3. gasfir-2.0.0/.gitignore +46 -0
  4. gasfir-2.0.0/.gitlab-ci.yml +369 -0
  5. gasfir-2.0.0/.pre-commit-config.yaml +46 -0
  6. gasfir-2.0.0/.readthedocs.yaml +21 -0
  7. gasfir-2.0.0/CHANGELOG.md +134 -0
  8. gasfir-2.0.0/LICENSE +21 -0
  9. gasfir-2.0.0/Models/SiO2_ulmic_params.txt +12 -0
  10. gasfir-2.0.0/Models/Si_ulmic_params.json +1 -0
  11. gasfir-2.0.0/Models/Si_ulmic_params.txt +0 -0
  12. gasfir-2.0.0/PKG-INFO +294 -0
  13. gasfir-2.0.0/README.md +220 -0
  14. gasfir-2.0.0/benchmarks/HANDOFF.md +185 -0
  15. gasfir-2.0.0/benchmarks/RESULTS_argon_step1.md +301 -0
  16. gasfir-2.0.0/benchmarks/RESULTS_jax_loop_threads.md +40 -0
  17. gasfir-2.0.0/benchmarks/RESULTS_raven.md +21 -0
  18. gasfir-2.0.0/benchmarks/RESULTS_tiptoe_fast.md +46 -0
  19. gasfir-2.0.0/benchmarks/RESULTS_tiptoe_window.md +101 -0
  20. gasfir-2.0.0/benchmarks/RESULTS_v1_speedup.md +87 -0
  21. gasfir-2.0.0/benchmarks/argon_config.py +280 -0
  22. gasfir-2.0.0/benchmarks/argon_step1_jax.py +332 -0
  23. gasfir-2.0.0/benchmarks/argon_step1_legacy.py +179 -0
  24. gasfir-2.0.0/benchmarks/bench_tiptoe_fast.py +166 -0
  25. gasfir-2.0.0/benchmarks/bench_v1_speedup.py +336 -0
  26. gasfir-2.0.0/benchmarks/check_cma_parity.py +99 -0
  27. gasfir-2.0.0/benchmarks/compare_argon_step1.py +187 -0
  28. gasfir-2.0.0/benchmarks/compare_jacobian_modes.py +218 -0
  29. gasfir-2.0.0/benchmarks/probe_base_dT.py +104 -0
  30. gasfir-2.0.0/benchmarks/probe_dT_wavelength_scaling.py +137 -0
  31. gasfir-2.0.0/benchmarks/probe_jax_loop_threads.py +127 -0
  32. gasfir-2.0.0/benchmarks/probe_tiptoe_window.py +223 -0
  33. gasfir-2.0.0/benchmarks/profile_hotpath.py +147 -0
  34. gasfir-2.0.0/benchmarks/raven_bench.py +197 -0
  35. gasfir-2.0.0/benchmarks/raven_cpu.sbatch +27 -0
  36. gasfir-2.0.0/benchmarks/raven_gpu.sbatch +26 -0
  37. gasfir-2.0.0/benchmarks/run_nps_plot.py +138 -0
  38. gasfir-2.0.0/benchmarks/run_orthogonal_pulses_crystal_frame_scan.py +114 -0
  39. gasfir-2.0.0/benchmarks/run_probe_polarization_scan.py +104 -0
  40. gasfir-2.0.0/benchmarks/scan_retrieval.py +1185 -0
  41. gasfir-2.0.0/derivations/anisotropic_gasfir_derivation.pdf +0 -0
  42. gasfir-2.0.0/derivations/anisotropic_gasfir_derivation.tex +449 -0
  43. gasfir-2.0.0/derivations/build_derivation_notebook.py +845 -0
  44. gasfir-2.0.0/derivations/gasfir_solid.pdf +0 -0
  45. gasfir-2.0.0/derivations/gasfir_solid.tex +660 -0
  46. gasfir-2.0.0/derivations/keldysh_derivation.pdf +0 -0
  47. gasfir-2.0.0/derivations/keldysh_derivation.py +1190 -0
  48. gasfir-2.0.0/derivations/keldysh_derivation.tex +628 -0
  49. gasfir-2.0.0/derivations/nonparabolic_band.tex +266 -0
  50. gasfir-2.0.0/derivations/verify_anisotropic_derivation.py +349 -0
  51. gasfir-2.0.0/docs/_static/ar_vs_h_rates.png +0 -0
  52. gasfir-2.0.0/docs/_static/gs_drate_dfield.png +0 -0
  53. gasfir-2.0.0/docs/_static/gs_polarization.png +0 -0
  54. gasfir-2.0.0/docs/_static/gs_rate_vs_field.png +0 -0
  55. gasfir-2.0.0/docs/_static/gs_tiptoe.png +0 -0
  56. gasfir-2.0.0/docs/_static/nps_offdiagonal_mass_tensor.png +0 -0
  57. gasfir-2.0.0/docs/_static/nps_orthogonal_pulses_crystal_tilt.png +0 -0
  58. gasfir-2.0.0/docs/_static/nps_probe_polarization_scan.png +0 -0
  59. gasfir-2.0.0/docs/_static/nps_sumofpulses_delta_p.png +0 -0
  60. gasfir-2.0.0/docs/_static/val_H_bias_heatmap.png +0 -0
  61. gasfir-2.0.0/docs/_static/val_H_rms_heatmap.png +0 -0
  62. gasfir-2.0.0/docs/_static/val_H_rms_worst10_heatmap.png +0 -0
  63. gasfir-2.0.0/docs/api/atomic_data.rst +6 -0
  64. gasfir-2.0.0/docs/api/datasets.rst +6 -0
  65. gasfir-2.0.0/docs/api/grids.rst +6 -0
  66. gasfir-2.0.0/docs/api/index.rst +75 -0
  67. gasfir-2.0.0/docs/api/keldysh.rst +6 -0
  68. gasfir-2.0.0/docs/api/kernel.rst +6 -0
  69. gasfir-2.0.0/docs/api/normalization.rst +6 -0
  70. gasfir-2.0.0/docs/api/observables.rst +6 -0
  71. gasfir-2.0.0/docs/api/parameter_sets.rst +6 -0
  72. gasfir-2.0.0/docs/api/pulses.rst +6 -0
  73. gasfir-2.0.0/docs/api/quadrature.rst +6 -0
  74. gasfir-2.0.0/docs/api/quasistatic.rst +6 -0
  75. gasfir-2.0.0/docs/api/resources.rst +6 -0
  76. gasfir-2.0.0/docs/api/retrieval.rst +6 -0
  77. gasfir-2.0.0/docs/api/units.rst +6 -0
  78. gasfir-2.0.0/docs/changelog.rst +2 -0
  79. gasfir-2.0.0/docs/conf.py +83 -0
  80. gasfir-2.0.0/docs/development/contributing.rst +88 -0
  81. gasfir-2.0.0/docs/development/releasing.rst +45 -0
  82. gasfir-2.0.0/docs/development/testing.rst +106 -0
  83. gasfir-2.0.0/docs/examples/basic_usage.rst +109 -0
  84. gasfir-2.0.0/docs/examples/parameter_fitting.rst +143 -0
  85. gasfir-2.0.0/docs/examples/performance.rst +119 -0
  86. gasfir-2.0.0/docs/index.rst +86 -0
  87. gasfir-2.0.0/docs/installation.rst +125 -0
  88. gasfir-2.0.0/docs/theory/keldysh.rst +412 -0
  89. gasfir-2.0.0/docs/theory/model.rst +465 -0
  90. gasfir-2.0.0/docs/user_guide/getting_started.rst +446 -0
  91. gasfir-2.0.0/docs/user_guide/parameters.rst +109 -0
  92. gasfir-2.0.0/docs/user_guide/pulses.rst +287 -0
  93. gasfir-2.0.0/docs/user_guide/retrieval.rst +213 -0
  94. gasfir-2.0.0/docs/user_guide/validation.rst +252 -0
  95. gasfir-2.0.0/environment.yml +19 -0
  96. gasfir-2.0.0/jupyter_logs/script_init_jupyter.sh +40 -0
  97. gasfir-2.0.0/pyproject.toml +137 -0
  98. gasfir-2.0.0/src/gasfir/__init__.py +187 -0
  99. gasfir-2.0.0/src/gasfir/_compilation_cache.py +237 -0
  100. gasfir-2.0.0/src/gasfir/atomic_data.py +385 -0
  101. gasfir-2.0.0/src/gasfir/datasets.py +234 -0
  102. gasfir-2.0.0/src/gasfir/grids.py +407 -0
  103. gasfir-2.0.0/src/gasfir/keldysh.py +586 -0
  104. gasfir-2.0.0/src/gasfir/kernel.py +328 -0
  105. gasfir-2.0.0/src/gasfir/normalization.py +459 -0
  106. gasfir-2.0.0/src/gasfir/observables.py +679 -0
  107. gasfir-2.0.0/src/gasfir/parameter_sets.py +363 -0
  108. gasfir-2.0.0/src/gasfir/pulses.py +2238 -0
  109. gasfir-2.0.0/src/gasfir/quadrature.py +224 -0
  110. gasfir-2.0.0/src/gasfir/quasistatic.py +573 -0
  111. gasfir-2.0.0/src/gasfir/resources.py +830 -0
  112. gasfir-2.0.0/src/gasfir/retrieval.py +4216 -0
  113. gasfir-2.0.0/src/gasfir/units.py +188 -0
  114. gasfir-2.0.0/tests/__init__.py +1 -0
  115. gasfir-2.0.0/tests/conftest.py +122 -0
  116. gasfir-2.0.0/tests/physics.py +31 -0
  117. gasfir-2.0.0/tests/test_bound_taper.py +234 -0
  118. gasfir-2.0.0/tests/test_cma_restarts.py +216 -0
  119. gasfir-2.0.0/tests/test_compilation_cache.py +165 -0
  120. gasfir-2.0.0/tests/test_datasets.py +249 -0
  121. gasfir-2.0.0/tests/test_gradients.py +219 -0
  122. gasfir-2.0.0/tests/test_grids.py +251 -0
  123. gasfir-2.0.0/tests/test_infrastructure.py +84 -0
  124. gasfir-2.0.0/tests/test_jacobian_modes.py +284 -0
  125. gasfir-2.0.0/tests/test_keldysh.py +331 -0
  126. gasfir-2.0.0/tests/test_mcmc_convergence.py +247 -0
  127. gasfir-2.0.0/tests/test_mcmc_progress.py +304 -0
  128. gasfir-2.0.0/tests/test_normalization.py +379 -0
  129. gasfir-2.0.0/tests/test_parameter_sets.py +215 -0
  130. gasfir-2.0.0/tests/test_points_plot.py +109 -0
  131. gasfir-2.0.0/tests/test_polarization.py +246 -0
  132. gasfir-2.0.0/tests/test_pulses.py +733 -0
  133. gasfir-2.0.0/tests/test_quadrature.py +200 -0
  134. gasfir-2.0.0/tests/test_quasistatic.py +128 -0
  135. gasfir-2.0.0/tests/test_report_plots.py +301 -0
  136. gasfir-2.0.0/tests/test_resources_calibration.py +382 -0
  137. gasfir-2.0.0/tests/test_snap_jointly.py +312 -0
  138. gasfir-2.0.0/tests/test_snap_start.py +197 -0
  139. gasfir-2.0.0/tests/test_stark_consistency.py +110 -0
  140. gasfir-2.0.0/tests/test_units.py +233 -0
  141. gasfir-2.0.0/tests/test_validation_report.py +325 -0
  142. gasfir-2.0.0/tools/import_salmon.py +112 -0
  143. gasfir-2.0.0/tools/push_reminder.sh +18 -0
gasfir-2.0.0/.flake8 ADDED
@@ -0,0 +1,50 @@
1
+ [flake8]
2
+ # black owns formatting and line length; flake8 is here for what black cannot
3
+ # see -- unused imports, shadowed names, unreachable code.
4
+ #
5
+ # Rewritten for this package. The previous version was legacy's file copied
6
+ # verbatim, with per-file-ignores naming src/gasfir/kernels.py and friends --
7
+ # paths that do not exist here -- so it was silently exempting nothing and
8
+ # checking a source tree that was not ours.
9
+ max-line-length = 88
10
+
11
+ # E203 whitespace before ':' — black inserts it deliberately in slices
12
+ # W503/W504 line break before/after a binary operator — mutually exclusive
13
+ # rules, and black picks one of them
14
+ # E501 line length — black --check already enforces this, and duplicating it
15
+ # only turns one problem into two failures
16
+ extend-ignore = E203,W503,W504,E501
17
+
18
+ exclude =
19
+ .git,
20
+ __pycache__,
21
+ .pytest_cache,
22
+ dist,
23
+ build,
24
+ docs/_build,
25
+ # Regenerates reference data by importing legacy gasfir, which is not
26
+ # installed here; it is documentation of provenance, not live code.
27
+ tests/golden,
28
+ scratch,
29
+ Data,
30
+ Data_to_archive,
31
+
32
+ per-file-ignores =
33
+ # The package __init__ deliberately imports out of order: fast-math flags must
34
+ # reach XLA_FLAGS *before* `import jax`, so enable_fast_math() runs first
35
+ # (E402). Everything else it imports is a re-export forming the public API,
36
+ # which flake8 reads as unused (F401).
37
+ src/gasfir/__init__.py: E402, F401
38
+ # `l` is the angular-momentum quantum number and `m` its projection -- the
39
+ # standard notation, and `l` is part of adk_rate's signature and its
40
+ # static_argnames, so renaming it would change the public API to satisfy a
41
+ # rule about `l` looking like `1`.
42
+ src/gasfir/quasistatic.py: E741
43
+ # Benchmarks put the package on sys.path before importing it, so their
44
+ # imports cannot all sit at the top of the file.
45
+ # `I` is intensity and `E` field amplitude -- physics notation (E741).
46
+ benchmarks/*.py: E402, E741, E731
47
+ # Tests: E402 for the same reason. E731/E741 are allowed because a test
48
+ # that deliberately builds a one-line lambda or indexes with `l` is clearer
49
+ # for it, and renaming to satisfy a style rule would obscure the point.
50
+ tests/*.py: E402, E731, E741
@@ -0,0 +1,32 @@
1
+ # Repository language statistics (GitLab / GitHub linguist).
2
+ #
3
+ # Count the package source, not the data, the plot exports, the notebooks or the
4
+ # scratch work. Measured before this file existed, the language bar read:
5
+ #
6
+ # HTML 94.2 % Python 3.2 % Jupyter 1.7 % rest < 1 %
7
+ #
8
+ # The six plotly exports in Data/withFit are 24.3 MB on their own, against
9
+ # 0.82 MB of Python -- so the bar described the data directory, not the project.
10
+ # (Legacy GASFIR has the same layout and hit the same thing at ~93 % HTML.)
11
+ #
12
+ # CSV and the other data formats are already excluded by linguist as data types;
13
+ # these rules cover what it *does* count.
14
+
15
+ # Input and output data, including the plotly exports and their SVG companions.
16
+ Data/** linguist-vendored
17
+ Data_to_archive/** linguist-vendored
18
+ *.html linguist-generated
19
+
20
+ # Exploratory and reference material: real work, but not the library.
21
+ *.ipynb linguist-documentation
22
+ scratch/** linguist-documentation
23
+ jupyter_logs/** linguist-documentation
24
+
25
+ # Per-material model files. (The per-material fit results now live under
26
+ # Data/results/, which the Data/** rule above already covers.)
27
+ Models/** linguist-documentation
28
+
29
+ # The Keldysh derivation: a LaTeX document and the SymPy script that writes it.
30
+ # Provenance for the theory pages rather than library code, so it should not
31
+ # show up as the project being part TeX.
32
+ derivations/** linguist-documentation
@@ -0,0 +1,46 @@
1
+ __pycache__/
2
+ *.py[cod]
3
+ *.egg-info/
4
+ build/
5
+ dist/
6
+ .venv/
7
+ venv/
8
+ .pytest_cache/
9
+ # CI keeps its pip cache in the project folder (PIP_CACHE_DIR in .gitlab-ci.yml).
10
+ .pip-cache/
11
+ .coverage
12
+ htmlcov/
13
+ .ipynb_checkpoints/
14
+ .vscode/
15
+ .idea/
16
+ .DS_Store
17
+ *.h5
18
+ nohup.out
19
+ *.log
20
+
21
+ # LaTeX build artefacts
22
+ *.aux
23
+ *.fdb_latexmk
24
+ *.fls
25
+ *.log
26
+ *.out
27
+ *.toc
28
+
29
+ # Benchmark output: regenerated by the scripts, and stale the moment the code
30
+ # changes. The written analysis (RESULTS_*.md) is tracked; the JSON is not.
31
+ benchmarks/results_*.json
32
+ *_output.txt
33
+ benchmarks/validation_*/
34
+ tests/golden/*.npz
35
+
36
+ # Built documentation -- sources only in version control. v1 commits its
37
+ # _build/html tree, which is why its docs/ directory looks enormous.
38
+ docs/_build/
39
+
40
+ # CMA-ES driver log directory -- regenerated on every run.
41
+ outcmaes/
42
+
43
+ # Parked exploration material (first-principles basis formulation etc.):
44
+ # archived locally, not part of the v2.0 release.
45
+ Data_to_archive/First_principles_formulation/
46
+ Data_to_archive/outcmaes/
@@ -0,0 +1,369 @@
1
+ # GitLab CI/CD pipeline for GASFIR.
2
+ #
3
+ # Mirrors legacy GASFIR's pipeline stage for stage, with four deliberate
4
+ # differences, each explained where it appears:
5
+ #
6
+ # * no Numba cache anchor -- there is no AOT-cached JIT here, and JAX's own
7
+ # persistent compilation cache is switched OFF (see GASFIR_JAX_CACHE below);
8
+ # * lint covers benchmarks/ as well as src/ and tests/, because the retrieval
9
+ # driver lives there and is the thing users actually run;
10
+ # * the coverage gate is a real floor rather than a badge, and it is measured
11
+ # with branch coverage;
12
+ # * `safety` is gone and `bandit` no longer ends in `|| true`.
13
+
14
+ stages:
15
+ - lint
16
+ - test
17
+ - build
18
+ - publish
19
+
20
+ variables:
21
+ PIP_CACHE_DIR: "$CI_PROJECT_DIR/.pip-cache"
22
+ PYTHON_VERSION: "3.12"
23
+ # Runners have no GPU. Saying so up front skips device discovery and keeps
24
+ # the log free of the "no CUDA devices" warning on every single test.
25
+ JAX_PLATFORMS: "cpu"
26
+ # JAX's persistent compilation cache stays off. It is opt-in in this package
27
+ # for a reason: an unbounded cache under $TMPDIR reached 40 GB / 4608 entries
28
+ # on a development machine and filled the disk. CI containers are ephemeral,
29
+ # so the cache would buy nothing and could only cost.
30
+ GASFIR_JAX_CACHE: "0"
31
+ # The memory planner reads cgroup v1 and v2 limits directly, which is exactly
32
+ # what a CI container exposes, so it sizes its chunks to the runner without
33
+ # being told. Set GASFIR_JAX_MEM_BUDGET (bytes) only if a runner reports a
34
+ # limit it does not actually honour.
35
+
36
+ # ---------------------------------------------------------------------------
37
+ # Reusable cache anchor
38
+ # ---------------------------------------------------------------------------
39
+ .pip-cache: &pip-cache
40
+ cache:
41
+ - key:
42
+ files:
43
+ - pyproject.toml
44
+ paths:
45
+ - .pip-cache/
46
+ policy: pull-push
47
+ - key: pytest-cache-$CI_COMMIT_REF_SLUG
48
+ paths:
49
+ - .pytest_cache/
50
+ policy: pull-push
51
+
52
+ # ---------------------------------------------------------------------------
53
+ # Reusable path triggers
54
+ # ---------------------------------------------------------------------------
55
+ # "source, tests, benchmarks or packaging changed"
56
+ .src-changes: &src-changes
57
+ - src/**/*
58
+ - tests/**/*
59
+ - benchmarks/**/*
60
+ - pyproject.toml
61
+ - .flake8
62
+
63
+ # "documentation source changed". The API reference is generated from
64
+ # docstrings, and CHANGELOG.md is included verbatim by myst-parser, so both are
65
+ # docs inputs.
66
+ .docs-changes: &docs-changes
67
+ - docs/**/*
68
+ - src/**/*
69
+ - CHANGELOG.md
70
+ - pyproject.toml
71
+
72
+ .dep-changes: &dep-changes
73
+ - pyproject.toml
74
+
75
+ .run-on-src: &run-on-src
76
+ rules:
77
+ - if: $CI_PIPELINE_SOURCE == "merge_request_event"
78
+ changes: *src-changes
79
+ - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH
80
+ changes: *src-changes
81
+ - if: $CI_COMMIT_BRANCH =~ /^(feature|hotfix)\/.*/
82
+ changes: *src-changes
83
+
84
+ # ---------------------------------------------------------------------------
85
+ # Lint -- its own stage, so a formatting slip fails in seconds without waiting
86
+ # for the test job to install JAX and run 262 tests.
87
+ # ---------------------------------------------------------------------------
88
+ lint:
89
+ stage: lint
90
+ image: python:${PYTHON_VERSION}-slim
91
+ <<: [*pip-cache, *run-on-src]
92
+ before_script:
93
+ - pip install --upgrade pip
94
+ - pip install -e ".[dev]"
95
+ script:
96
+ # A failure here is a FORMATTING problem, not a broken-code problem, and it
97
+ # is fixable in one command. Say so, rather than leaving a contributor to
98
+ # read a diff and guess.
99
+ - |
100
+ if ! black --check --diff src tests benchmarks docs \
101
+ || ! isort --check-only --diff src tests benchmarks docs; then
102
+ echo ""
103
+ echo "=================================================================="
104
+ echo " Code formatting check failed -- this is NOT a test failure."
105
+ echo " Fix it with:"
106
+ echo " black src tests benchmarks docs && isort src tests benchmarks docs"
107
+ echo " Or install the hook once so it cannot happen again:"
108
+ echo " pip install -e \".[dev]\" && pre-commit install"
109
+ echo "=================================================================="
110
+ exit 1
111
+ fi
112
+ - flake8 src tests benchmarks
113
+ # mypy takes its file list from [tool.mypy] in pyproject.toml, so passing
114
+ # paths here would silently override it.
115
+ - mypy
116
+
117
+ # ---------------------------------------------------------------------------
118
+ # Test + coverage
119
+ # ---------------------------------------------------------------------------
120
+ test:
121
+ stage: test
122
+ image: python:${PYTHON_VERSION}-slim
123
+ <<: [*pip-cache, *run-on-src]
124
+ before_script:
125
+ - pip install --upgrade pip
126
+ - pip install -e ".[dev]"
127
+ # The lazy-import branches (cma, h5py, matplotlib, corner) must be exercised
128
+ # rather than skipped, so fail loudly if the dev extra stopped pulling them.
129
+ - python -c "import cma, h5py, matplotlib, corner, psutil, pandas, scipy"
130
+ script:
131
+ - pytest tests/ -m "not slow"
132
+ --cov --cov-report=xml --cov-report=term-missing
133
+ --cov-fail-under=70
134
+ --junitxml=report.xml
135
+ --tb=short
136
+ # Branch coverage, not statement coverage -- see [tool.coverage.run]. The
137
+ # floor is set below the current figure on purpose: it is a ratchet against
138
+ # regression, not a target to game. Raise it when the number rises.
139
+ coverage: '/TOTAL.*\s+(\d+%)$/'
140
+ artifacts:
141
+ when: always
142
+ reports:
143
+ junit: report.xml
144
+ coverage_report:
145
+ coverage_format: cobertura
146
+ path: coverage.xml
147
+ paths:
148
+ - report.xml
149
+ expire_in: 1 week
150
+
151
+ # ---------------------------------------------------------------------------
152
+ # Python version matrix. 3.11 is the floor declared by requires-python; there
153
+ # is no 3.10 entry because the codebase uses 3.11 syntax.
154
+ # ---------------------------------------------------------------------------
155
+ test-matrix:
156
+ stage: test
157
+ needs: [test]
158
+ image: python:${PYTHON_VERSION}-slim
159
+ <<: *pip-cache
160
+ parallel:
161
+ matrix:
162
+ - PYTHON_VERSION: ["3.11", "3.12"]
163
+ before_script:
164
+ - pip install --upgrade pip
165
+ - pip install -e ".[dev]"
166
+ script:
167
+ - pytest tests/ -m "not slow" -q --junitxml=report.xml
168
+ artifacts:
169
+ when: always
170
+ reports:
171
+ junit: report.xml
172
+ expire_in: 1 week
173
+ rules:
174
+ - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH
175
+ changes: *src-changes
176
+
177
+ # ---------------------------------------------------------------------------
178
+ # The slow tests, which the main job excludes. These are the ones that compile
179
+ # real kernels over real grids -- the polarization-equivalence sweep in
180
+ # particular -- so they belong on main rather than in every push's feedback loop.
181
+ # ---------------------------------------------------------------------------
182
+ test-slow:
183
+ stage: test
184
+ needs: [test]
185
+ image: python:${PYTHON_VERSION}-slim
186
+ <<: *pip-cache
187
+ before_script:
188
+ - pip install --upgrade pip
189
+ - pip install -e ".[dev]"
190
+ script:
191
+ - pytest tests/ -m "slow" -v --junitxml=report.xml
192
+ artifacts:
193
+ when: always
194
+ reports:
195
+ junit: report.xml
196
+ expire_in: 1 week
197
+ rules:
198
+ - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH
199
+ changes: *src-changes
200
+
201
+ # ---------------------------------------------------------------------------
202
+ # Security scan.
203
+ #
204
+ # Legacy ran `safety check ... || true` and `bandit ... || true`, which means
205
+ # neither could ever fail the pipeline: the reports were artifacts nobody had a
206
+ # reason to open. Here bandit actually gates, at medium severity and medium
207
+ # confidence, so a finding stops the pipeline and gets triaged (with `# nosec`
208
+ # and a reason if it is a false positive).
209
+ #
210
+ # `safety` is not used: its `check` subcommand is deprecated in favour of `scan`,
211
+ # which requires an authenticated account, and an unauthenticated job would fail
212
+ # for reasons unrelated to this package's dependencies. pip-audit needs no
213
+ # account and reads the same advisory data, so it takes that slot -- non-gating
214
+ # for now, because it reports on transitive pins we do not control.
215
+ # ---------------------------------------------------------------------------
216
+ security-scan:
217
+ stage: test
218
+ image: python:${PYTHON_VERSION}-slim
219
+ before_script:
220
+ - pip install --upgrade pip bandit pip-audit
221
+ - pip install -e "."
222
+ script:
223
+ - bandit -r src/ -ll -f screen
224
+ - bandit -r src/ -f json -o bandit-report.json || true
225
+ - pip-audit --desc --format json --output pip-audit-report.json || true
226
+ artifacts:
227
+ when: always
228
+ paths:
229
+ - bandit-report.json
230
+ - pip-audit-report.json
231
+ expire_in: 1 week
232
+ rules:
233
+ - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH
234
+ changes: *dep-changes
235
+ - if: $CI_PIPELINE_SOURCE == "merge_request_event"
236
+ changes: *dep-changes
237
+
238
+ # ---------------------------------------------------------------------------
239
+ # Build wheel
240
+ # ---------------------------------------------------------------------------
241
+ build:
242
+ stage: build
243
+ image: python:${PYTHON_VERSION}-slim
244
+ before_script:
245
+ - pip install --upgrade pip build twine
246
+ script:
247
+ - python -m build
248
+ - ls -la dist/
249
+ # Catches a malformed README before PyPI does, which is the one packaging
250
+ # error that only shows up at upload time.
251
+ - python -m twine check dist/*
252
+ artifacts:
253
+ paths:
254
+ - dist/
255
+ expire_in: 1 week
256
+ rules:
257
+ - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH
258
+ changes: *src-changes
259
+ - if: $CI_COMMIT_TAG
260
+
261
+ # ---------------------------------------------------------------------------
262
+ # Docs. Built with -W, so a warning is a failure -- the same setting as
263
+ # .readthedocs.yaml's fail_on_warning, so a build that passes here cannot then
264
+ # break on Read the Docs.
265
+ # ---------------------------------------------------------------------------
266
+ build-docs:
267
+ stage: build
268
+ image: python:${PYTHON_VERSION}-slim
269
+ before_script:
270
+ - pip install --upgrade pip
271
+ - pip install -e ".[docs]"
272
+ script:
273
+ - sphinx-build -b html -W --keep-going docs docs/_build/html
274
+ # A broken cross-reference is invisible in rendered HTML; this is the only
275
+ # thing that finds one. Non-gating, because it also probes external URLs.
276
+ - sphinx-build -b linkcheck docs docs/_build/linkcheck || true
277
+ artifacts:
278
+ paths:
279
+ - docs/_build/html/
280
+ - docs/_build/linkcheck/
281
+ expire_in: 1 week
282
+ rules:
283
+ - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH
284
+ changes: *docs-changes
285
+ - if: $CI_PIPELINE_SOURCE == "merge_request_event"
286
+ changes: *docs-changes
287
+ - if: $CI_COMMIT_TAG
288
+
289
+ # ---------------------------------------------------------------------------
290
+ # Trigger a Read the Docs build over the API. RTD's webhook is unreliable
291
+ # against self-hosted GitLab, which is why legacy does the same. Requires an
292
+ # RTD_TOKEN CI variable; the job is skipped rather than failed without one.
293
+ # ---------------------------------------------------------------------------
294
+ trigger-rtd:
295
+ stage: build
296
+ image: alpine:latest
297
+ before_script:
298
+ - apk add --no-cache curl
299
+ script:
300
+ - |
301
+ curl -sf -X POST \
302
+ -H "Authorization: Token ${RTD_TOKEN}" \
303
+ -H "Content-Type: application/json" \
304
+ https://readthedocs.org/api/v3/projects/gasfir/versions/latest/builds/ \
305
+ || echo "RTD trigger failed; the docs artifact from build-docs still stands"
306
+ rules:
307
+ - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH && $RTD_TOKEN
308
+ changes: *docs-changes
309
+ - if: $CI_COMMIT_TAG && $RTD_TOKEN
310
+
311
+ # ---------------------------------------------------------------------------
312
+ # Publish.
313
+ #
314
+ # Both jobs are inert until the corresponding token is set as a CI variable --
315
+ # `&& $..._TOKEN` in the rule, so an unconfigured project skips them rather than
316
+ # failing every pipeline on a missing credential.
317
+ # ---------------------------------------------------------------------------
318
+ publish-testpypi:
319
+ stage: publish
320
+ # An upload can drop mid-file (2.0.0rc1: SSL EOF at 59% of the sdist).
321
+ # Retrying is safe: --skip-existing skips files that already went up.
322
+ retry:
323
+ max: 2
324
+ when: script_failure
325
+ image: python:${PYTHON_VERSION}-slim
326
+ needs:
327
+ - job: build
328
+ optional: true # build is skipped on docs-only pushes; so is this
329
+ variables:
330
+ TWINE_USERNAME: __token__
331
+ TWINE_PASSWORD: $TEST_PYPI_TOKEN
332
+ before_script:
333
+ - pip install --upgrade pip twine
334
+ script:
335
+ - ls -la dist/
336
+ - python -m twine upload --repository testpypi dist/* --skip-existing --verbose
337
+ rules:
338
+ - if: $CI_COMMIT_TAG =~ /^v.*-(rc|alpha|beta).*$/ && $TEST_PYPI_TOKEN
339
+ environment:
340
+ name: test-pypi
341
+ url: https://test.pypi.org/project/gasfir/
342
+
343
+ publish-pypi:
344
+ stage: publish
345
+ # An upload can drop mid-file (2.0.0rc1: SSL EOF at 59% of the sdist).
346
+ # Retrying is safe: --skip-existing skips files that already went up.
347
+ retry:
348
+ max: 2
349
+ when: script_failure
350
+ image: python:${PYTHON_VERSION}-slim
351
+ needs:
352
+ - job: build
353
+ optional: true
354
+ variables:
355
+ TWINE_USERNAME: __token__
356
+ TWINE_PASSWORD: $PYPI_TOKEN
357
+ before_script:
358
+ - pip install --upgrade pip twine
359
+ script:
360
+ - ls -la dist/
361
+ - python -m twine upload dist/* --skip-existing --verbose
362
+ rules:
363
+ # Manual even on a release tag: publishing to PyPI is irreversible, and a
364
+ # version number cannot be reused.
365
+ - if: $CI_COMMIT_TAG =~ /^v\d+\.\d+\.\d+$/ && $PYPI_TOKEN
366
+ when: manual
367
+ environment:
368
+ name: production
369
+ url: https://pypi.org/project/gasfir/
@@ -0,0 +1,46 @@
1
+ # Auto-format/lint on `git commit`, and nudge to run tests on `git push`.
2
+ #
3
+ # One-time setup (per clone):
4
+ # pip install -e ".[dev]"
5
+ # pre-commit install --hook-type pre-commit --hook-type pre-push
6
+ #
7
+ # On `git commit`:
8
+ # * black — auto-reformat changed Python files
9
+ # * isort — auto-sort imports
10
+ # * flake8 — report style violations
11
+ # black/isort modify files in place; if they change anything the commit is
12
+ # aborted so you can re-stage (`git add -u`) and commit again. This uses the
13
+ # project's own black/isort/flake8 (the versions installed by `[dev]`), so a
14
+ # clean local commit is guaranteed to pass the CI lint stage.
15
+ #
16
+ # On `git push`:
17
+ # * a non-blocking reminder to run the local checks before CI runs them.
18
+ repos:
19
+ - repo: local
20
+ hooks:
21
+ - id: black
22
+ name: black (auto-format)
23
+ entry: black
24
+ language: system
25
+ types: [python]
26
+ stages: [pre-commit]
27
+ - id: isort
28
+ name: isort (auto-sort imports)
29
+ entry: isort
30
+ language: system
31
+ types: [python]
32
+ stages: [pre-commit]
33
+ - id: flake8
34
+ name: flake8
35
+ entry: flake8
36
+ language: system
37
+ types: [python]
38
+ stages: [pre-commit]
39
+ - id: push-reminder
40
+ name: nudge — run tests locally before pushing
41
+ entry: tools/push_reminder.sh
42
+ language: script
43
+ stages: [pre-push]
44
+ always_run: true
45
+ pass_filenames: false
46
+ verbose: true
@@ -0,0 +1,21 @@
1
+ # Read the Docs configuration.
2
+ # https://docs.readthedocs.io/en/stable/config-file/v2.html
3
+ version: 2
4
+
5
+ build:
6
+ os: ubuntu-24.04
7
+ tools:
8
+ python: "3.12"
9
+
10
+ sphinx:
11
+ configuration: docs/conf.py
12
+ # Warnings are errors: a docs build that "succeeds" with a dangling reference
13
+ # or an unparsed docstring has not checked anything.
14
+ fail_on_warning: true
15
+
16
+ python:
17
+ install:
18
+ - method: pip
19
+ path: .
20
+ extra_requirements:
21
+ - docs