diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index a183af091..a396640b1 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -27,12 +27,15 @@ env: jobs: # Which lanes to run. A change confined to docs/ and Markdown files runs the static # checks, the documentation build and the tests that read the documentation - # (docs-tests), not the test lanes; one confined to the front end (gui/, with docs/ - # and Markdown) runs the static checks, the documentation build and the front end's - # own job; anything else, or a push whose base is unknown, runs everything, the front - # end's job included, so a change to solprop is checked against the front end. A push to main that merges a pull request runs nothing when the - # pushed tree is the pull request head's tree and CI passed on that head: the pull - # request was up to date with main, so its run already tested exactly this tree. + # (docs-tests), not the test lanes. Otherwise, one confined to gui/, docs/ and + # Markdown files runs those and the front end's own job; so does a documentation + # change to the front end's chapter of the user guide (docs/guide/front-end/), which + # its tests read. Anything else, gui/pyproject.toml included (solprop's release tests + # read it), or a push whose base is unknown, runs everything, the front end's job + # included, so a change to solprop is checked against the front end. A push to main + # that merges a pull request runs nothing when the pushed tree is the pull request + # head's tree and CI passed on that head: the pull request was up to date with main, + # so its run already tested exactly this tree. changes: runs-on: ubuntu-latest timeout-minutes: 5 @@ -65,9 +68,11 @@ jobs: if [ -n "$BASE" ] && git cat-file -e "$BASE^{commit}" 2>/dev/null; then git diff --name-only "$BASE" HEAD > changed.txt cat changed.txt - if ! grep -qvE '^docs/|\.md$' changed.txt; then + # The front end's tests read its chapter of the user guide, and solprop's + # release tests read gui/pyproject.toml. + if ! grep -qvE '^docs/|\.md$' changed.txt && ! grep -q '^docs/guide/front-end/' changed.txt; then lanes=docs - elif ! grep -qvE '^gui/|^docs/|\.md$' changed.txt; then + elif ! grep -qvE '^gui/|^docs/|\.md$' changed.txt && ! grep -qx 'gui/pyproject.toml' changed.txt; then lanes=gui fi fi @@ -96,7 +101,7 @@ jobs: docs-tests: needs: [changes, native-wheel] - if: needs.changes.outputs.lanes == 'docs' + if: needs.changes.outputs.lanes == 'docs' || needs.changes.outputs.lanes == 'gui' runs-on: ubuntu-24.04 timeout-minutes: 30 steps: @@ -123,6 +128,11 @@ jobs: - name: The tests that read the documentation run: | uv run --no-sync pytest -n 4 $(grep -lE '"docs"|"docs/|"(CHANGELOG|README|AGENTS)\.md"|\.md"\)|/ "[a-z0-9-]+\.md"' tests/test_*.py tests/*/test_*.py) + # Every python block of docs/guide/ runs (AGENTS.md): the slow-tier test that + # executes them, in the slow lane's configuration, so a documentation-only change + # cannot merge a broken snippet. + - name: The guide's snippets + run: uv run --no-sync poe test-slow tests/test_guide_snippets.py # The definition-of-done gate of AGENTS.md (`poe check`), split into jobs that run in # parallel: the static checks, the documentation, and the default lane, sharded, with @@ -150,6 +160,9 @@ jobs: - run: uv run poe reuse - run: uv run poe changelog-check - run: uv run poe size-check + # solprop's sdist, whose include list and readme the root pyproject.toml sets: the + # wheels workflow builds it only weekly and on a release tag. + - run: uv build --package solprop --sdist --out-dir dist docs: needs: [changes, native-wheel] @@ -368,7 +381,10 @@ jobs: - run: uv python install 3.14 - run: uv sync --locked --no-install-package solprop-native - run: uv pip install --no-deps wheelhouse/*.whl - - run: uv run --no-sync poe test-slow + - run: uv run --no-sync poe test-slow --junitxml=junit.xml + - name: No unexpected skips + if: ${{ !cancelled() }} + run: uv run --no-sync python -I native/ci/check_skips.py junit.xml # The slow lane on macOS, with the native wheel installed. slow-macos: @@ -393,7 +409,10 @@ jobs: - run: uv python install 3.14 - run: uv sync --locked --no-install-package solprop-native - run: uv pip install --no-deps wheelhouse/*.whl - - run: uv run --no-sync poe test-slow + - run: uv run --no-sync poe test-slow --junitxml=junit.xml + - name: No unexpected skips + if: ${{ !cancelled() }} + run: uv run --no-sync python -I native/ci/check_skips.py junit.xml # The coverage lane (`poe cov`) as parallel jobs, on Linux with the native wheel # installed and the driver tests on it (solprop's native paths are part of the 100 %): diff --git a/.github/workflows/cuda.yml b/.github/workflows/cuda.yml index b756e2129..258cf47b5 100644 --- a/.github/workflows/cuda.yml +++ b/.github/workflows/cuda.yml @@ -11,6 +11,9 @@ name: NVIDIA CUDA validation # architecture (for example AMPERE80, ADA89 or HOPPER90); HOPPER90 is used when unset. # The repository is public: keep this workflow dispatch-only and never let the # self-hosted runner pick up pull_request jobs, which would run code from forks on it. +# It is part of no gate: GPU qualification is `poe test-gpu`, run by hand on a device. +# The build passes the `cuda` preset's options (native/CMakePresets.json), without +# the C++ tests. on: workflow_dispatch: @@ -21,6 +24,7 @@ permissions: jobs: cuda: runs-on: [self-hosted, linux, x64, nvidia-gpu] + timeout-minutes: 180 env: CXX: g++-14 NVCC_WRAPPER_DEFAULT_COMPILER: g++-14 @@ -32,7 +36,6 @@ jobs: fetch-depth: 0 - uses: astral-sh/setup-uv@68559e99cc807c1eb7e9238fd43a15bba460eec2 # v10.3.3 with: - version: 0.12.7 enable-cache: true - name: Check CUDA toolchain run: | @@ -45,9 +48,13 @@ jobs: -DSOLPROP_NATIVE_ENABLE_CUDA=ON -DSOLPROP_NATIVE_ENABLE_OPENMP=OFF -DSOLPROP_NATIVE_CUDA_ARCH=${{ vars.SOLPROP_NATIVE_CUDA_ARCH || 'HOPPER90' }} + -DSOLPROP_NATIVE_ENABLE_TPL_BLAS=ON + -DSOLPROP_NATIVE_DEVICE_TEAM_SIZE=512 + -DSOLPROP_NATIVE_ENABLE_IPO=OFF + -DSOLPROP_NATIVE_HOST_ARCH=OFF -DBUILD_TESTING=OFF run: | - uv sync --python 3.14 --no-install-package solprop-native + uv sync --locked --python 3.14 --no-install-package solprop-native uv pip install --no-deps --no-build-isolation -e native - name: Run CUDA correctness tests working-directory: native diff --git a/.github/workflows/native-deep.yml b/.github/workflows/native-deep.yml index 5795b3a64..5ca3052e1 100644 --- a/.github/workflows/native-deep.yml +++ b/.github/workflows/native-deep.yml @@ -37,7 +37,8 @@ concurrency: jobs: coverage: runs-on: ubuntu-24.04 - timeout-minutes: 240 + # The instrumented suite outgrew 240 minutes; 360 is GitHub's hosted-runner limit. + timeout-minutes: 360 env: CC: clang-18 CXX: clang++-18 @@ -190,12 +191,18 @@ jobs: build=native/build/presets/cpu-tidy # The pinned clang-tidy and the arguments the build gives it. mapfile -t tidy < "$build/clang_tidy_command.txt" + units=$(git ls-files -- 'native/src/*.cpp' 'native/tests/native/*.cpp' | wc -l) git ls-files -z -- 'native/src/*.cpp' 'native/tests/native/*.cpp' | xargs -0 -n 1 -P "$(nproc)" "${tidy[@]}" --quiet -p "$build" \ --checks='-*,misc-include-cleaner' --warnings-as-errors='' \ > include-cleaner.txt 2>&1 || true findings=$(grep -c 'misc-include-cleaner' include-cleaner.txt || true) - echo "## misc-include-cleaner: ${findings} findings" >> "$GITHUB_STEP_SUMMARY" + echo "## misc-include-cleaner: ${findings} findings in ${units} units" \ + >> "$GITHUB_STEP_SUMMARY" + # Report only: clang-tidy's exit status is non-zero whenever it has a finding, + # and one unit (the Accelerate transform) does not parse on Linux. + unparsed=$(grep -c 'clang-diagnostic-error' include-cleaner.txt || true) + echo "Units with a compile error: ${unparsed}" >> "$GITHUB_STEP_SUMMARY" - uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2 if: always() with: diff --git a/.github/workflows/wheels.yml b/.github/workflows/wheels.yml index 5c89d578e..823a486a2 100644 --- a/.github/workflows/wheels.yml +++ b/.github/workflows/wheels.yml @@ -4,7 +4,7 @@ # The release wheels of solprop-native, built, repaired and qualified, and the pure # Python distributions of solprop and solprop-gui, built and installed; on a release -# tag, once enabled, published. +# tag, published. # The recipe is docs/dev/releasing.md; cibuildwheel's configuration is in # native/pyproject.toml and the dependency scripts in native/ci/. name: Wheels @@ -167,7 +167,7 @@ jobs: uv run --no-project --python ../coexist python -I native/ci/coexistence.py # The default lane's peak memory with four test workers is at the edge of a 16 GB # runner (the aarch64 runner shut down mid-suite, as CI's did): swap on Linux and - # three workers, as in CI's native-suite job. + # three workers, as in CI's coverage job. # A safeguard only: with three workers no lane used any swap when measured. Keep it # small, because some runners have 13 GB of free disk and 12 GB of swap filled them, # which kills the job with its log. @@ -524,11 +524,10 @@ jobs: # building from source). solprop's sdist and wheel follow from `pypi` once every # native wheel is up: the `native` extra pins solprop-native at this version # (hatch_build.py), so a failed native upload leaves no solprop release behind. - # Guarded until the PyPI projects, their trusted publishers and both environments - # exist and the repository variable PUBLISH is set to "true" (the pre-flight - # checklist in docs/dev/releasing.md). The front end, solprop-gui, is published from - # its own environment `pypi-gui` once PUBLISH_GUI is "true" too; until then - # `solprop[gui]` resolves only in the repository's workspace. + # Guarded by the repository variable PUBLISH, set to "true" once the PyPI projects, + # their trusted publishers and the environments existed (the pre-flight checklist in + # docs/dev/releasing.md). The front end, solprop-gui, is published after solprop from + # its own environment `pypi-gui`, guarded by PUBLISH_GUI as well. publish-native: # cpu-floor runs only when SDE_URL names an emulator, so it may be skipped only then. needs: [test, python-3-15, solprop-dist, cpu-floor, minimum-systems] diff --git a/.gitignore b/.gitignore index 41cac8745..16064abee 100644 --- a/.gitignore +++ b/.gitignore @@ -36,6 +36,7 @@ docs/introduction/lessons/sg_execution_times.rst # OS and editors .DS_Store .idea/ +.vscode/ # The galleries' generated pages under docs/introduction/lessons/, docs/auto_tutorials/ # and docs/auto_examples/ ARE committed (they are reused, not regenerated, by every diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml index 50e96f42f..4e5dc0a78 100644 --- a/.pre-commit-config.yaml +++ b/.pre-commit-config.yaml @@ -19,7 +19,6 @@ repos: rev: v2.4.3 hooks: - id: codespell - additional_dependencies: [tomli] - repo: https://github.com/astral-sh/uv-pre-commit rev: 0.12.6 hooks: diff --git a/AGENTS.md b/AGENTS.md index 6ae9b4139..8aced508c 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -24,10 +24,10 @@ physics or numerics rather than style, ask rather than guess. | Purpose | Ultrafast nonlinear pulse propagation (UPPE and GNLSE; field and envelope; single-mode, multimode and general modal guides; radial, Cartesian, planar and line free space) | | Python | 3.14 — equal to `requires-python` in `pyproject.toml` | | Platforms | solprop runs where solprop-native installs: wheels for osx-arm64, linux-64, linux-aarch64, win-64 and win-arm64; from source on Linux and macOS (GPU builds on Linux); the Queue and Slurm scan executors POSIX-only | -| Backends | `native` (required; `auto`; CPU and GPU; implements every feature, the TDSE response on CPU builds only) and `numpy_ref` (the numerical reference). No other backend. Binary64 only (ADR-077), with one method set on both: `PIController` is final, and the single-precision code, CF4 sections and `ComparisonMultistep` are retired | +| Backends | `native` (required; `auto`; CPU and GPU; implements every feature, the TDSE response on CPU builds only) and `numpy_ref` (the numerical reference). No other backend. Binary64 only (ADR-077), with one method set on both | | Type checker | `basedpyright`, pinned exactly in the dev group | | Materials | [optmat](https://github.com/LupoLab/optmat), the curated optical-materials package | -| Planned work | [GitHub issues](https://github.com/LupoLab/solprop/issues), not the roadmap, which lists only SEPs (ADR-062); [`CONTRIBUTING.md`](CONTRIBUTING.md) says how to write and label one | +| Planned work | [GitHub issues](https://github.com/LupoLab/solprop/issues) (ADR-062); [`CONTRIBUTING.md`](CONTRIBUTING.md) says how to write and label one | | Enhancement proposals | `docs/dev/seps/` — process in SEP 0 (`sep-0000-process.md`), form in `template.md` | ## Commands @@ -36,7 +36,7 @@ physics or numerics rather than style, ask rather than guess. |---|---| | Sync environment | `uv sync` (builds native editable; needs a C++20 compiler). `--extra gui --group gui-test` adds the front end. No compiler: the lightweight setup and `poe fetch-wheel` ([`docs/dev/contributing.md`](docs/dev/contributing.md)) | | Full gate | `uv run poe check` | -| Native gate | `uv run poe check-native`; `uv run poe check-all` runs the three gates | +| Native gate | `uv run poe check-native`; `uv run poe check-all` runs the three gates (the front end's needs its extra, below) | | Front-end gate | `uv run poe check-gui` (needs `--extra gui --group gui-test`) | | Lint, format, types | `uv run ruff check --fix .`, `uv run ruff format .`, `uv run basedpyright` | | Docstrings, spelling, licences | `uv run poe docstrings`, `uv run codespell`, `uv run poe reuse` | @@ -53,16 +53,16 @@ in `addopts` and selects the slow tier too. Select by path or `-k` instead. ## Definition of done **Documentation-only changes**, SEPs included: `git diff --check` and codespell on the -changed files, `uv run pytest tests/test_seps.py` when proposals, their index or the -roadmap change, and `uv run poe docs` when Sphinx content or links change (`testing.md`). +changed files, `uv run pytest tests/test_seps.py` when proposals or their index +change, and `uv run poe docs` when Sphinx content or links change (`testing.md`). **Other changes:** develop first, test towards the end. Run the fast checks (ruff check with `--fix`, ruff format, ruff check, basedpyright) and the modules that exercise what changed (`uv run pytest -n auto `). The full gate, slow and coverage lanes run in CI on the pull request, not locally; after a CI failure, rerun the failing modules, never the -whole lane. `poe check` and CI run the same steps ([`tooling.md`](docs/dev/tooling.md)): -change both in the same commit. Coverage is 100 % of statements and branches; a -`# pragma: no cover` gives its reason on its line. `gui/` and `native/` add their own gates. +whole lane. CI runs `poe check`'s checks, split across its jobs +([`tooling.md`](docs/dev/tooling.md)): change both in the same commit. Coverage is 100 % +of statements and branches; a `# pragma: no cover` gives its reason on its line. `gui/` and `native/` add their own gates. **Qualification scope:** `numpy_ref` and the native CPU build; GPU builds separately with `poe test-gpu` on a device. **No test, lane or timing runs a full-length propagation** @@ -99,7 +99,7 @@ validity range is cited to its primary source; say what you verified and what yo - **Report failure honestly:** a failed check, an untested path, an invented assumption. - **The public tree stands alone.** No local paths, host names, private notes or links to them, and no development-register identifiers, in code, tests, docs or the changelog. - The hardware a benchmark ran on is part of its ledger entry. + The hardware a benchmark ran on is part of its record. ## Code @@ -215,7 +215,7 @@ The long form is [`backends.md`](docs/dev/backends.md). - **The seam has no version number** (ADR-068). A change to the `PropagationProblem` or `RunRequest` fields or the stage bundles of `translate/stage.py` rewrites the frozen tables in `tests/backends/test_driver.py` in the same commit, with a release-note fragment. -- A hot-path change comes with a benchmark ledger entry ([`benchmarks.md`](docs/dev/benchmarks.md)) +- A hot-path change comes with a benchmark measurement ([`benchmarks.md`](docs/dev/benchmarks.md)) from `python -m benchmarks ab` on about ten steps or a short `--length` window; report the window, never extrapolate it. diff --git a/CHANGELOG.md b/CHANGELOG.md index 98393e72d..c015ac8d8 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -20,12 +20,12 @@ Highlights: as a third distribution at solprop's own version (`pip install "solprop[gui]"`): it sets up, runs, scans and reads simulations without a script. - **Recipes, the command line and design solvers** - ([SEP 41](docs/dev/seps/archive/sep-0041-recipes-and-front-ends.md)): a TOML recipe + ([SEP 41](https://github.com/LupoLab/solprop/blob/main/docs/dev/seps/archive/sep-0041-recipes-and-front-ends.md)): a TOML recipe for every route, the `solprop` command, pins that set a radius or a pressure from a zero-dispersion wavelength, a dispersive-wave wavelength or a soliton order, chosen launch modes, displaced and tilted beams, and parameter metadata for front ends. - **The native backend is required** - ([SEP 43](docs/dev/seps/archive/sep-0043-retire-numba-cpu.md)): `numba_cpu` and the + ([SEP 43](https://github.com/LupoLab/solprop/blob/main/docs/dev/seps/archive/sep-0043-retire-numba-cpu.md)): `numba_cpu` and the numba and pyFFTW dependencies are gone, `pip install solprop` installs `solprop-native`, and new wheels cover Windows on Arm and x86-64 processors without AVX2. @@ -36,11 +36,11 @@ Highlights: keeps its phase, large record arrays are stored beside the record's JSON, and a file no longer grows with the square of its planes. Read a 0.1.0 file with 0.1.0. - **Transverse absorbing boundaries** - ([SEP 40](docs/dev/seps/archive/sep-0040-transverse-absorbing-boundaries.md)): every + ([SEP 40](https://github.com/LupoLab/solprop/blob/main/docs/dev/seps/archive/sep-0040-transverse-absorbing-boundaries.md)): every free-space run carries a safety ramp by default, a designed real-space collar on request, and a boundary monitor that warns or stops when light reaches the edge; that edge is now read where the state lives - ([SEP 44](docs/dev/seps/archive/sep-0044-native-edge-read.md)), so a device run + ([SEP 44](https://github.com/LupoLab/solprop/blob/main/docs/dev/seps/archive/sep-0044-native-edge-read.md)), so a device run copies no state to check it. - **MLX performance**: compiled stages run a trial 1.5 to 2.6 times faster on an Apple GPU, single precision admits the Adams integrator, and single-precision grids are @@ -51,7 +51,7 @@ Highlights: #### The native backend replaces numba - The `numba_cpu` backend, and the `numba` and `pyfftw` dependencies, are removed - ([SEP 43](docs/dev/seps/archive/sep-0043-retire-numba-cpu.md), ADR-064). + ([SEP 43](https://github.com/LupoLab/solprop/blob/main/docs/dev/seps/archive/sep-0043-retire-numba-cpu.md), ADR-064). `backend="numba_cpu"` raises `BackendError`, naming `native` and `numpy_ref`. A file written by 0.1.0 is refused by its output schema, as every file of another schema is: read it with `solprop==0.1.0`, which is also the rollback. To migrate, pass @@ -63,7 +63,7 @@ Highlights: `SOLPROP_FFTW_PLAN`, `SOLPROP_FFTW_WISDOM` and `SOLPROP_BLAS_THREADS` stay. - `solprop-native` is a required dependency, with no extra: `pip install solprop` installs it, and solprop is supported where it installs - ([SEP 43](docs/dev/seps/archive/sep-0043-retire-numba-cpu.md)). On any other platform, + ([SEP 43](https://github.com/LupoLab/solprop/blob/main/docs/dev/seps/archive/sep-0043-retire-numba-cpu.md)). On any other platform, including Intel macOS, ppc64le, musl and macOS before 14, the installer reports that no matching distribution exists; the installation page explains that and how to report a platform. The `native` extra is gone: install `solprop`, not `solprop[native]`. @@ -143,7 +143,7 @@ Highlights: #### Free-space transverse boundaries - A free-space run's transverse boundary is a `SpatialAbsorber` - ([SEP 40](docs/dev/seps/archive/sep-0040-transverse-absorbing-boundaries.md)), given as + ([SEP 40](https://github.com/LupoLab/solprop/blob/main/docs/dev/seps/archive/sep-0040-transverse-absorbing-boundaries.md)), given as `SimulationSettings.spatial_absorber` or the `spatial_absorber` keyword of `prop_radial`, `prop_free`, `prop_planar` and their `Simulation.from_*` builders. By default every radial, Cartesian, line and planar run carries a designed safety ramp on @@ -159,7 +159,7 @@ Highlights: `collar_fraction` that leaves it room. - Every spatial grid takes `collar_fraction` in place of `window_factor`, default 0, and puts the room it asks for **outside** the requested size on every geometry - ([SEP 40](docs/dev/seps/archive/sep-0040-transverse-absorbing-boundaries.md)). + ([SEP 40](https://github.com/LupoLab/solprop/blob/main/docs/dev/seps/archive/sep-0040-transverse-absorbing-boundaries.md)). `RadialGrid`'s `radius` is now the requested aperture, the Dirichlet boundary is at `outer_radius = radius * (1 + collar_fraction)`, and `n_r` counts every sample; the transform, the nodes and the effective area use the outer radius. Fractions of 1 and @@ -170,7 +170,7 @@ Highlights: `collar_fraction=c`. - A free-space run whose light reaches its transverse boundary now warns or stops, where it used to log and carry on - ([SEP 40](docs/dev/seps/archive/sep-0040-transverse-absorbing-boundaries.md)). The + ([SEP 40](https://github.com/LupoLab/solprop/blob/main/docs/dev/seps/archive/sep-0040-transverse-absorbing-boundaries.md)). The boundary monitor reads the outer 5 % of the grid on every backend. It warns above 1e-6 of the launch energy and stops at 1e-4, naming a size and a sample count to try, and `BoundaryCheck.transverse_budget` sets those levels apart from the time window's. The @@ -276,7 +276,7 @@ Highlights: #### Recipes and the command line -- Recipes ([SEP 41](https://solprop.readthedocs.io/en/latest/dev/seps/archive/sep-0041-recipes-and-front-ends.html)): +- Recipes ([SEP 41](https://github.com/LupoLab/solprop/blob/main/docs/dev/seps/archive/sep-0041-recipes-and-front-ends.md)): `solprop.recipe.Recipe` reads a TOML description of a run, with quantities in their units (`"125 um"`, `"1.2 bar"`), checks it (`check()`, each issue at its parameter path), builds and runs it, saves it and exports it as the Python script it stands for @@ -284,7 +284,7 @@ Highlights: and warnings that concern a value carry its `parameter`; writing TOML takes the `tomli-w` dependency. A run built from a recipe records it in a top-level `recipe` group of its output, as written and as resolved (the recipe that rebuilds the run). - See [recipes and the command line](https://solprop.readthedocs.io/en/latest/guide/setup/recipes.html). + See [recipes and the command line](https://solprop.readthedocs.io/en/stable/guide/setup/recipes.html). - Recipes on every route. The `gnlse` and `capillary` recipes came first; `radial`, `free` and `planar` recipes write the grids, medium, responses, beam and settings as tables of registered types (`RadialGrid`, `FreeGrid`, `LineGrid`, `PlanarGrid`, @@ -312,7 +312,7 @@ Highlights: stopped point is not committed and a rerun computes it; Queue and Slurm refuse it. `run_scan(progress=)` accepts a `solprop.log.ScanReporter` (and a `WatchingScanReporter` for each point's run, relayed from Pool workers). -- Design solvers for any guide ([SEP 41](https://solprop.readthedocs.io/en/latest/dev/seps/archive/sep-0041-recipes-and-front-ends.html)): +- Design solvers for any guide ([SEP 41](https://github.com/LupoLab/solprop/blob/main/docs/dev/seps/archive/sep-0041-recipes-and-front-ends.md)): `solprop.tools.solve_parameter` finds every value of a guide or fill parameter (a radius, a pressure, a core size, a wall thickness) that meets a target, `ZDW`, `RDW` or `SolitonOrder`, discarding sign changes through a wall resonance, and @@ -385,7 +385,7 @@ with the plain `prop_*` interface: phase column is unwrapped only where the power is above a noise floor, a phase in the FFT sign convention of a Luna.jl file is read with `phase_convention="fft"`, and a wrapped column sampled too coarsely to unwrap is warned on - ([SEP 41](https://solprop.readthedocs.io/en/latest/dev/seps/archive/sep-0041-recipes-and-front-ends.html)). + ([SEP 41](https://github.com/LupoLab/solprop/blob/main/docs/dev/seps/archive/sep-0041-recipes-and-front-ends.md)). - `prop_capillary`, `prop_waveguide` and their `Simulation` constructors take `launch=`, which puts each pulse into chosen modes with a share and an optional phase: `launch={"HE1,1": 0.9, "HE1,2": {"share": 0.1, "phase": 1.57}}`, or a list with one @@ -394,14 +394,14 @@ with the plain `prop_*` interface: split scaled to the pulse's energy under the flux metric. The run records the launch as `configuration["modal_launch"]`, which a resume compares; a run without one records nothing - ([SEP 41](https://solprop.readthedocs.io/en/latest/dev/seps/archive/sep-0041-recipes-and-front-ends.html)). + ([SEP 41](https://github.com/LupoLab/solprop/blob/main/docs/dev/seps/archive/sep-0041-recipes-and-front-ends.md)). - `SpatialPulse` takes `displacement=(d_x, d_y)` and `tilt=(theta_x, theta_y)`, as `coupling.Alignment` defines them, applied at the launch plane on a Cartesian grid with the energy set after them; a tilt the grid's band, window or time window cannot carry is refused, and so is either on a radial grid, a y component on a line grid, a `PlanarPulse` and a guide's incident beam. A record without them reads as an unmoved beam - ([SEP 41](https://solprop.readthedocs.io/en/latest/dev/seps/archive/sep-0041-recipes-and-front-ends.html)). + ([SEP 41](https://github.com/LupoLab/solprop/blob/main/docs/dev/seps/archive/sep-0041-recipes-and-front-ends.md)). - `pulses.SpatialPulseSum` launches several beams together on the free-space routes, the sum of its `SpatialPulse` members' fields, each built and scaled as it would be alone: two beams crossing at an angle, a pump beside a probe. Recipes hold it @@ -420,7 +420,7 @@ with the plain `prop_*` interface: `polarisation_taper`, as `prop_gnlse` does; `step_planes` defaults to `None` on every interface that takes it, which on `prop_gnlse` behaves as its `0` did. The guide lists the deliberate differences between the routes' keywords - ([SEP 41](https://solprop.readthedocs.io/en/latest/dev/seps/archive/sep-0041-recipes-and-front-ends.html)). + ([SEP 41](https://github.com/LupoLab/solprop/blob/main/docs/dev/seps/archive/sep-0041-recipes-and-front-ends.md)). - `Simulation.from_radial`, `from_free` and `from_planar` take `absorber` and `absorber_scheme`, as `prop_radial`, `prop_free` and `prop_planar` and the modal `from_*` do. @@ -518,7 +518,7 @@ with the plain `prop_*` interface: #### Plotting - Cross-section drawings in the library - ([SEP 41](https://solprop.readthedocs.io/en/latest/dev/seps/archive/sep-0041-recipes-and-front-ends.html)): + ([SEP 41](https://github.com/LupoLab/solprop/blob/main/docs/dev/seps/archive/sep-0041-recipes-and-front-ends.md)): `solprop.plotting.geometry.outline` gives the outline of a capillary, antiresonant, step-index, graded-index, rectangular or planar guide, or of a radial, Cartesian, line or planar grid, as shapes in metres; `draw(ax, guide, palette=...)` paints it in @@ -812,7 +812,7 @@ with the plain `prop_*` interface: numbers cross, so a field-free run on a device copies no state at all, and on the CPU a free-space Kerr beam's check costs less. A resumed run with a requested collar now restores its current, baselines and peaks, so it no longer judges against zero. - ([SEP 44](docs/dev/seps/archive/sep-0044-native-edge-read.md), #385, #512) + ([SEP 44](https://github.com/LupoLab/solprop/blob/main/docs/dev/seps/archive/sep-0044-native-edge-read.md), #385, #512) - The default boundary check no longer does work that nothing uses. A saved plane the step that reached it already read takes no second read, which on a device was a copy of the whole state. A fixed schedule's reads of the transverse edge now follow its next @@ -1044,7 +1044,7 @@ break the API, the output schema or the resume key, and lists every such break u diffraction operator; planar guides can be resolved across their width. Launches, shot noise, energies, fluences and intensities measure the medium's axial Poynting flux at the plane, so a requested energy is the physical energy there - ([SEP 34](https://solprop.readthedocs.io/en/latest/dev/seps/archive/sep-0034-medium-flux.html)). + ([SEP 34](https://github.com/LupoLab/solprop/blob/main/docs/dev/seps/archive/sep-0034-medium-flux.md)). Far-field and aperture statistics. - **Media and responses.** - Gases, gas mixtures, glasses and metals from the [optmat](https://github.com/LupoLab/optmat) @@ -1054,7 +1054,7 @@ break the API, the output schema or the resume key, and lists every such break u envelope grids. - Rotational and vibrational Raman responses, scalar and vector. - Quantum shot noise, on by default - ([SEP 37](https://solprop.readthedocs.io/en/latest/dev/seps/archive/sep-0037-noise-and-stepper-defaults.html)): + ([SEP 37](https://github.com/LupoLab/solprop/blob/main/docs/dev/seps/archive/sep-0037-noise-and-stepper-defaults.md)): one photon per mode with a random phase, added to the input field (`noise="input"`) and recorded with its seed. A resumed run draws the same realisation again, and a scan draws each point's from a seed of its own. @@ -1073,15 +1073,15 @@ break the API, the output schema or the resume key, and lists every such break u measurement: `RungeKutta()` for `prop_gnlse` (`rtol` 1e-7), `prop_waveguide` (1e-5) and `prop_free` (1e-4); `Multistep()` for `prop_capillary` (1e-6), `prop_radial` and `prop_planar` (1e-5). The - [choosing-a-stepper page](https://solprop.readthedocs.io/en/latest/guide/numerics/choosing-a-stepper.html) + [choosing-a-stepper page](https://solprop.readthedocs.io/en/stable/guide/numerics/choosing-a-stepper.html) tabulates them and says when to choose another. - `Multistep(carrier_frame="scalar")`, an opt-in carrier frame for the Adams history that is the fastest method measured on dense, multimode, Raman-active runs such as a comb-to-continuum capillary - ([SEP 35](https://solprop.readthedocs.io/en/latest/dev/seps/archive/sep-0035-carrier-frame-exponential-adams.html)). + ([SEP 35](https://github.com/LupoLab/solprop/blob/main/docs/dev/seps/archive/sep-0035-carrier-frame-exponential-adams.md)). - Backends agree with each other to bounded, rounding-level differences. - **Time-window boundaries** - ([SEP 21](https://solprop.readthedocs.io/en/latest/dev/seps/archive/sep-0021-absorbing-boundaries.html)). + ([SEP 21](https://github.com/LupoLab/solprop/blob/main/docs/dev/seps/archive/sep-0021-absorbing-boundaries.md)). Every interface absorbs at the edges of the time window and of the spectrum. The temporal collar lies outside the requested window: the grid widens to `trange / (1 - 2 collar_fraction)` (`collar_fraction` 0.1), so the whole request is @@ -1092,7 +1092,7 @@ break the API, the output schema or the resume key, and lists every such break u then stops the run (`BoundaryError`) when light above the shot-noise floor reaches the window's edge, and records the energy the collar removed. - **Coupling simulations** - ([SEP 31](https://solprop.readthedocs.io/en/latest/dev/seps/archive/sep-0031-simulation-coupling.html)). + ([SEP 31](https://github.com/LupoLab/solprop/blob/main/docs/dev/seps/archive/sep-0031-simulation-coupling.md)). `solprop.coupling` hands a field from one simulation to the next. A `FieldPlane` holds a coherent field at one plane with its reference and provenance; `couple` maps it into another simulation's `InputPort` under a declared `CouplingModel` and returns @@ -1106,25 +1106,25 @@ break the API, the output schema or the resume key, and lists every such break u within derived error bounds, and `numba_cpu`, compiled with Numba. The backends come in tiers: new features land on `numpy_ref` and `native`; `numba_cpu` is mature and takes a new feature only where its design says so; `mlx` is experimental. - - The optional [native backend](https://solprop.readthedocs.io/en/latest/guide/performance/native.html), + - The optional [native backend](https://solprop.readthedocs.io/en/stable/guide/performance/native.html), the solprop-native distribution: C++20 kernels on Kokkos for multi-core CPUs (OpenMP) and for NVIDIA and AMD GPUs (CUDA, HIP). `pip install "solprop[native]"` installs a precompiled CPU wheel on macOS on Apple silicon, Linux on x86-64 and aarch64, and Windows on x86-64. `backend="auto"` selects it when installed, except on a processor below the wheel's CPU baseline, where it uses `numba_cpu` and warns - once ([SEP 29](https://solprop.readthedocs.io/en/latest/dev/seps/archive/sep-0029-compiled-backend-distribution.html)). + once ([SEP 29](https://github.com/LupoLab/solprop/blob/main/docs/dev/seps/archive/sep-0029-compiled-backend-distribution.md)). On the native backend the exponential Adams march runs in compiled code, many steps per call - ([SEP 39](https://solprop.readthedocs.io/en/latest/dev/seps/archive/sep-0039-native-adams-march.html)). + ([SEP 39](https://github.com/LupoLab/solprop/blob/main/docs/dev/seps/archive/sep-0039-native-adams-march.md)). - One thread budget per process, which every pool of both CPU backends stays within: the smallest of the CPU affinity mask, the physical cores that hold it, the control group's CPU quota and `SOLPROP_THREADS` (ADR-052). - Single precision - ([SEP 33](https://solprop.readthedocs.io/en/latest/dev/seps/archive/sep-0033-single-precision-mlx.html)): + ([SEP 33](https://github.com/LupoLab/solprop/blob/main/docs/dev/seps/archive/sep-0033-single-precision-mlx.md)): `precision="single"` holds the state, the transforms and the responses in binary32, with the controller in binary64. `numpy_ref` runs it as the reference, and the `mlx` backend (`pip install "solprop[mlx]"`) on the Apple GPU. A - [survival record](https://solprop.readthedocs.io/en/latest/guide/performance/single-precision.html) + [survival record](https://github.com/LupoLab/solprop/blob/v0.1.0/docs/guide/performance/single-precision.md) states which problems keep their accuracy. - **Running and recording.** - HDF5 output with periodic snapshots and provenance, and resuming an interrupted @@ -1145,7 +1145,7 @@ break the API, the output schema or the resume key, and lists every such break u - Pulse compressors: Taylor phase, chirped mirrors, materials, gratings and prisms. - An interactive session through `import solprop.sol as sol`. - **Performance tracking** for developers - ([SEP 38](https://solprop.readthedocs.io/en/latest/dev/seps/archive/sep-0038-performance-tracking.html)): + ([SEP 38](https://github.com/LupoLab/solprop/blob/main/docs/dev/seps/archive/sep-0038-performance-tracking.md)): `python -m benchmarks track` times about a dozen representative workloads, with each interface's defaults, at one thread and at the production width, and records them by hardware; `python -m benchmarks ab` compares two builds. @@ -1191,14 +1191,14 @@ Nothing was released before 0.1.0. For scripts and files from a development chec (an absorber given to a spatial run, `Absorber.spatial`) removes only part of the light that reaches it, at a large cost in steps, and the boundary monitor watches the time window only. Size the transverse window so that the light stays clear of its edge. - [SEP 40](https://solprop.readthedocs.io/en/latest/dev/seps/archive/sep-0040-transverse-absorbing-boundaries.html) + [SEP 40](https://github.com/LupoLab/solprop/blob/main/docs/dev/seps/archive/sep-0040-transverse-absorbing-boundaries.md) (a draft) rebuilds these boundaries. - **A run is resumed by the release that wrote it.** A run's configuration hash covers every recorded field, so a release that adds one changes every hash, and within 0.x the output schema may change too: finish a run with the release that started it. - **GPU builds are made from source.** The wheels are for CPUs; CUDA and HIP builds of solprop-native are built from the repository - ([building the native backend](https://solprop.readthedocs.io/en/latest/guide/performance/building-native.html)). + ([building the native backend](https://solprop.readthedocs.io/en/stable/guide/performance/building-native.html)). - **CPython 3.14 only.** solprop-native, pyFFTW and h5py have no wheels for 3.15 yet. - **macOS: import solprop before pyFFTW.** pyFFTW's macOS wheel starts its own OpenMP runtime, so the native backend refuses to load in a process that imported pyFFTW diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 90d3f2432..1a1d14650 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -45,8 +45,8 @@ That is all a report needs. A maintainer fills in the rest. ## Writing an issue -Planned work lives in [GitHub issues](https://github.com/LupoLab/solprop/issues), not on -the roadmap, which lists only SEPs (ADR-062). So an issue for planned work, written by +Planned work lives in [GitHub issues](https://github.com/LupoLab/solprop/issues) +(ADR-062). So an issue for planned work, written by a person or an agent, has to let someone pick up the task from its text alone. [#76](https://github.com/LupoLab/solprop/issues/76) and [#77](https://github.com/LupoLab/solprop/issues/77) are examples. @@ -112,32 +112,12 @@ git clone https://github.com/LupoLab/solprop.git cd solprop uv sync # the package and native/, both editable, with the development tools uv run poe check # the full gate: lint, format, types, docstrings, spelling, tests, docs -uv run poe check-all # solprop's gate, then the native gate (`poe check-native`) ``` -The material models come from [optmat](https://github.com/LupoLab/optmat), installed as -an ordinary dependency. - -The compiled backend, solprop-native, lives in the same repository under -[`native/`](native/README.md). It is a second distribution with the same version and a -required dependency, so a plain `uv sync` builds it, which takes a C++20 compiler, CMake and -FFTW, on Linux or macOS. A Python or documentation change doesn't need that. The lightweight -setup, which also serves Windows, has no native package and no compiler: - -```sh -uv run --no-project tools/setup_light.py -export UV_NO_SYNC=1 # or activate .venv and run the tools directly -SOLPROP_TEST_BACKEND=numpy_ref uv run poe test -``` - -It supports the reference backend and the lint, type, test and documentation checks. uv can't -be told to leave native out for good, so a later plain `uv sync`, or `uv run` without that -setting, builds it. There `backend="auto"` refuses, so scripts name `backend="numpy_ref"`, and -tests that need native skip. [Contributing](docs/dev/contributing.md) has the details, and -`poe fetch-wheel`, which installs the wheel CI built when it fits your tree. - -A change that touches `native/` runs `poe check-all` and follows the native rules in -[`native/AGENTS.md`](native/AGENTS.md). +A plain `uv sync` builds the native backend, which takes a C++20 compiler, CMake and FFTW, +on Linux or macOS. [Contributing](docs/dev/contributing.md#set-up-a-development-environment) +covers the rest: the native and front-end gates, the lightweight setup with no compiler for +Python and documentation changes (which also serves Windows), and `poe fetch-wheel`. ## Making a change diff --git a/README.md b/README.md index e033b8479..2458e87f1 100644 --- a/README.md +++ b/README.md @@ -141,8 +141,7 @@ installs it and solprop uses it automatically; your scripts do not change. `numpy_ref`, the plain NumPy backend that native is tested against, is the numerical reference. It is unthreaded and roughly 6 to 40 times slower than threaded native, so it -is for checking a result and for the few supported features native does not run yet, the -TDSE response among them +is for checking a result, and for a problem a GPU build of native refuses ([which backend to use](https://solprop.readthedocs.io/en/stable/guide/performance/backends.html#which-backend-to-use)). See [The native backend](https://solprop.readthedocs.io/en/stable/guide/performance/native.html) and [Performance tuning](https://solprop.readthedocs.io/en/stable/guide/performance/tuning.html). diff --git a/benchmarks/README.md b/benchmarks/README.md index dcf94ae28..79fa0471b 100644 --- a/benchmarks/README.md +++ b/benchmarks/README.md @@ -12,7 +12,7 @@ uv run python -m benchmarks ab --case CASE --baseline-python OLD/bin/python # f ``` `history/` holds one CSV per hardware set, a few rows per release. Run bundles go to -`.benchmarks/`, which git ignores; the benchmark rules and indicative results are in +`.benchmarks/`, which git ignores; the benchmark rules and current results are in `docs/dev/benchmarks.md`. What has already been tried for CPU performance is in `docs/dev/cpu-performance.md`. Earlier campaign harnesses, the retired standard suite's baselines and their raw data are kept with the project's development records, not in diff --git a/benchmarks/builders.py b/benchmarks/builders.py index c87961160..1b9956add 100644 --- a/benchmarks/builders.py +++ b/benchmarks/builders.py @@ -376,11 +376,11 @@ def spatial_grids( ) if name == "spatial_absorber": # SEP 40: the aperture of three waists with 2.6 radii of room outside it, for - # the requested collar, at the former spacing (64 samples over the aperture). + # the requested collar, at 64 samples over the aperture. return field, RadialGrid(3e-4, size, collar_fraction=2.6) if name.startswith("radial"): - # 1.5 mm since revision 2 (SEP 40): on 1 mm the filament's light reaches the - # wall at 2.9 cm, and the transverse edge stops the run. + # 1.5 mm (SEP 40): on 1 mm the filament's light reaches the wall at 2.9 cm, + # and the transverse edge stops the run. return field, RadialGrid(1.5e-3, size) if name == "line": return field, LineGrid(1e-3, size) @@ -395,6 +395,9 @@ def kerr(name: str, settings: SimulationSettings, fft_size: str = "case") -> Sim The Sellmeier coefficients are inherited from the SEP 28 builder, citing Malitson, JOSA 55, 1205 (1965), doi:10.1364/JOSA.55.001205. This extraction preserves its declared UV extrapolation and records the resulting warning. + + No statistics are collected: the cases time four fixed steps, and the free-space + route's default statistics at the observed plane would cost a quarter of that. """ from solprop.constants import EPS0, MU0, C # noqa: PLC0415 from solprop.driver import Simulation # noqa: PLC0415 @@ -403,6 +406,7 @@ def kerr(name: str, settings: SimulationSettings, fft_size: str = "case") -> Sim from solprop.physdata.glasses import SellmeierGlass # noqa: PLC0415 from solprop.pulses import GaussianPulse, SpatialPulse # noqa: PLC0415 from solprop.spatial import SpatialMedium # noqa: PLC0415 + from solprop.stats import StatsSpec # noqa: PLC0415 grid, space = spatial_grids(name, fft_size) assert isinstance(space, FreeGrid) @@ -422,7 +426,7 @@ def kerr(name: str, settings: SimulationSettings, fft_size: str = "case") -> Sim SpatialMedium(glass), [KerrResponse(chi3=2.2e-22 * MU0 * EPS0 * C**2, thg=False)], launch, - settings=settings, + settings=dataclasses.replace(settings, stats=StatsSpec(names=())), ) diff --git a/benchmarks/native_session.py b/benchmarks/native_session.py index a04ddb10f..de41f53f9 100644 --- a/benchmarks/native_session.py +++ b/benchmarks/native_session.py @@ -8,9 +8,7 @@ (:class:`solprop_native.session.NativeSession`): a ``sep47`` case is built as the worker builds it (``benchmarks.builders.build``) and run to its end through a minimal service loop -- advance, keep each observation's statistics and rows, export a kept -plane's field once, acknowledge -- so that what is measured is the session's own. The -transitional driver session it was first compared with was deleted in SEP 47's phase 5; -the paired timings of Part II are the record of that comparison. +plane's field once, acknowledge -- so that what is measured is the session's own. Each run reports its wall time, the time inside the native session's ``advance`` and ``export`` and the Python time outside them, its returns to Python by cause, the field diff --git a/changelog.d/138-bench-history-build.fixed.md b/changelog.d/138-bench-history-build.fixed.md deleted file mode 100644 index 7cbd01766..000000000 --- a/changelog.d/138-bench-history-build.fixed.md +++ /dev/null @@ -1 +0,0 @@ -The benchmark history no longer reports a change of native build profile (a local build after the release's wheel) as a speed change: rows compare only within one build profile. `python -m benchmarks track --append-history --allow-dirty` now admits a native build stamped `+dirty`, marking its rows dirty, and without the flag refuses it by naming the modified tree instead of asking for a rebuild; a modified `benchmarks/history` file no longer stamps the native build `+dirty` ([#138](https://github.com/LupoLab/solprop/issues/138)). diff --git a/changelog.d/155-on-axis-end-bins.fixed.md b/changelog.d/155-on-axis-end-bins.fixed.md new file mode 100644 index 000000000..b4be3072e --- /dev/null +++ b/changelog.d/155-on-axis-end-bins.fixed.md @@ -0,0 +1 @@ +Fixed the `numpy_ref` definition of `on_axis_spectrum`, `aperture_on_axis_spectrum` and `spatial.node_spectrum` at a field grid's zero-frequency and Nyquist bins: they now weigh those bins as the analytic signal does, a quarter of an interior bin, as the native backend already did, so both backends agree there and the sum times `d_omega` is exactly the fluence ([#155](https://github.com/LupoLab/solprop/issues/155)). diff --git a/changelog.d/157-zdw-sampled-search.fixed.md b/changelog.d/157-zdw-sampled-search.fixed.md new file mode 100644 index 000000000..b06ab136b --- /dev/null +++ b/changelog.d/157-zdw-sampled-search.fixed.md @@ -0,0 +1 @@ +`modes.base.zdw` now searches the sampled sign of `beta_2` and keeps a sign change as a zero only where the analytic group delay has a resolved extremum and `beta_2` keeps each sign for 1.5 % in frequency on either side; a change that is not a zero blocks the search only where the group delay is not finite or not continuous (a gas line), and the fine structure of a narrow feature, such as fused silica's OH absorption bands near 1.38 and 2.7 µm, is passed over. So a gas resonance's poles are no longer read as zeros, a window whose ends agree in sign no longer hides the zeros inside it, and the answer no longer depends on the window: a standard telecom fibre reports its 1.3 µm zero from a 1550 nm reference on any window that holds it. Several zeros in the window raise `ModeError` naming them, where an arbitrary one was returned or `NoZeroDispersionError` raised; the new `near=` reference wavelength picks the nearest zero that no line separates from it. `stats.zdw` takes `near=` too, and the `zdw` run statistic and the recipe's mode preview pass the grid's reference wavelength, so a krypton capillary whose band reaches its 120 nm lines records and previews its 770.5 nm zero instead of `nan` (#157, #527). diff --git a/changelog.d/159-flow-conditioning-cap.changed.md b/changelog.d/159-flow-conditioning-cap.changed.md new file mode 100644 index 000000000..ae8197f85 --- /dev/null +++ b/changelog.d/159-flow-conditioning-cap.changed.md @@ -0,0 +1 @@ +A coupled flow refused by its conditioning guard (the taper coupling of a lossy multimode capillary at the default `dz_max`, for one) now names the largest `dz_max` it admits, read exactly from its `exp(dz_max spread)` bound, instead of leaving the step to be found by trial (#159). diff --git a/changelog.d/160-rosa-radius-coefficient.changed.md b/changelog.d/160-rosa-radius-coefficient.changed.md new file mode 100644 index 000000000..d10b85b61 --- /dev/null +++ b/changelog.d/160-rosa-radius-coefficient.changed.md @@ -0,0 +1 @@ +`VincettiMode`'s effective core radius uses the coefficient Rosa, Melli and Vincetti (2021) print in their Eq. 10, `3 + 20 wavelength / core_radius`, instead of 10, so its index, dispersion and fitted area change while the API and the loss do not. For the tutorial fibre (15 µm core, six 9 µm tubes with 180 nm walls) at 800 nm `beta_2` moves from -479 to -471 fs²/m, and filled with argon its zero-dispersion wavelength moves 1.7 to 3.7 nm longer between 5 and 30 bar. The coefficient is not a parameter: results with the old value of 10 need solprop 0.2 (#160). diff --git a/changelog.d/166-optmat-tracker-ids.fixed.md b/changelog.d/166-optmat-tracker-ids.fixed.md index 44aaf1aa7..df430309f 100644 --- a/changelog.d/166-optmat-tracker-ids.fixed.md +++ b/changelog.d/166-optmat-tracker-ids.fixed.md @@ -1,5 +1,7 @@ -Dropped optmat's internal tracker ids, such as `(TC-688)`, from the optmat warnings -solprop passes on as `MaterialRangeWarning` and from the run's material record; the -rest of each message is unchanged. A Raman response used outside its density or -temperature range, hydrogen at 0.5 bar for example, no longer ends its warning with a -reference users cannot look up ([#166](https://github.com/LupoLab/solprop/issues/166)). +Dropped optmat's internal tracker ids, references users cannot look up, from every +optmat text solprop passes on: its range and absorption warnings (`MaterialRangeWarning`), +the status reason of each material record (`MaterialRecord.status_reason`, and so the +run's material manifest and `solprop.capabilities.species`) and the +`MaterialStatusWarning` built from it, which also no longer doubles the reason's full +stop. The rest of each text is unchanged +([#166](https://github.com/LupoLab/solprop/issues/166)). diff --git a/changelog.d/168-scan-claims-released.fixed.md b/changelog.d/168-scan-claims-released.fixed.md new file mode 100644 index 000000000..c1fd6759c --- /dev/null +++ b/changelog.d/168-scan-claims-released.fixed.md @@ -0,0 +1,5 @@ +A `Local` or `Pool` scan that ends with an exception (an interrupt, a refused worker +admission, a point that conflicts with the file) gives back the points it had claimed, +and a rerun computes any point an earlier scan left `running`, rather than skipping it +for ten minutes and reporting it as running +([#168](https://github.com/LupoLab/solprop/issues/168)). diff --git a/changelog.d/471-simulation-inputs-copy.fixed.md b/changelog.d/471-simulation-inputs-copy.fixed.md index 8c7afa64e..e7dde219c 100644 --- a/changelog.d/471-simulation-inputs-copy.fixed.md +++ b/changelog.d/471-simulation-inputs-copy.fixed.md @@ -5,6 +5,5 @@ recorded configuration or its hash. `PiecewiseLinear`, `PressureGradient`, `FromCallable` (its declared positions) and `SeriesOfPath` keep read-only copies of the arrays and series they are given, so changing a profile's table after passing it to a simulation no longer changes the run or its record. `SimulationSettings` keeps -`components` as a tuple copied from the sequence given. The record and hash of an unchanged -input are the same as before +`components` as a tuple copied from the sequence given ([#471](https://github.com/LupoLab/solprop/issues/471)). diff --git a/changelog.d/533-save-planes-count.fixed.md b/changelog.d/533-save-planes-count.fixed.md deleted file mode 100644 index e76dfa02b..000000000 --- a/changelog.d/533-save-planes-count.fixed.md +++ /dev/null @@ -1,3 +0,0 @@ -A recipe's `save_planes = 80` in an object route's `[build.settings]` is no longer read -as one plane at 80 m, with the run marching until something unrelated stopped it: it is -refused with "write `n_save = 80`", and every run now ends at its grid's length (#533). diff --git a/changelog.d/598.changed.md b/changelog.d/598.changed.md index 3f4cd47c3..951707655 100644 --- a/changelog.d/598.changed.md +++ b/changelog.d/598.changed.md @@ -1 +1 @@ -The native backend's CPU transforms are faster on many threads ([#598](https://github.com/LupoLab/solprop/pull/598); [ADR-075](docs/dev/decisions.md)): a batch of transforms now threads by its shape, about one thread per row and the whole team only for many rows, instead of by its element count, and a multi-mode stage transforms its forward rows (projection, absorber, plasma currents) as one batch, as on a GPU (`SOLPROP_NATIVE_FORWARD_PACK=0` turns that off). The tracking cases ran 0.98 of their time on geometric mean on 18–36 cores of an Intel Xeon Gold 6240 and 16 of an AMD EPYC 7763, the few-mode capillaries and the one-dimensional free-space beam 0.80–0.95. `solprop calibrate` now also tunes the transforms' threading, reaches a decision on FFT plan efforts (it no longer tries `patient` plans, and skips efforts whose plans are slower alone), and takes about 30 s, two minutes or seven minutes (from 20 s, 90 s and five minutes). Existing calibration profiles no longer apply: the next native run on each machine calibrates quickly again by itself, or run `solprop calibrate`. +The native backend's CPU transforms are faster on many threads ([#598](https://github.com/LupoLab/solprop/pull/598); [ADR-075](docs/dev/decisions.md)): a batch of transforms now threads by its shape, about one thread per row and the whole team only for many rows, instead of by its element count, and a multi-mode stage transforms its forward rows (projection, absorber, plasma currents) as one batch, as on a GPU (`SOLPROP_NATIVE_FORWARD_PACK=0` turns that off). The tracking cases ran 0.98 of their time on geometric mean on 18–36 cores of an Intel Xeon Gold 6240 and 16 of an AMD EPYC 7763, the few-mode capillaries and the one-dimensional free-space beam 0.80–0.95. diff --git a/changelog.d/619-simulation-run-request.added.md b/changelog.d/619-simulation-run-request.added.md index 5ff8e140f..7314e326f 100644 --- a/changelog.d/619-simulation-run-request.added.md +++ b/changelog.d/619-simulation-run-request.added.md @@ -1,7 +1,3 @@ -`Simulation.run_request()` returns the run request translation built beside the -problem, translating once, as `Simulation.translate()` does for the problem -([#619](https://github.com/LupoLab/solprop/issues/619)). The problem and the request are -what `solprop.backends.registry.select`, `solprop.translate.problem.validate_run`, -`PropagationProblem.validate_launch` and `solprop.driver.run.field_retention` take when -the outer loop is run by hand; the documented examples no longer reach for the private -`Simulation._run_request()`, which is gone. +`Simulation.run_request()` returns the run request translation built beside the problem, +translating once, as `Simulation.translate()` does for the problem +([#619](https://github.com/LupoLab/solprop/issues/619)). diff --git a/changelog.d/619-with-stepper-fresh-request.breaking.md b/changelog.d/619-with-stepper-fresh-request.breaking.md deleted file mode 100644 index 95233cd8d..000000000 --- a/changelog.d/619-with-stepper-fresh-request.breaking.md +++ /dev/null @@ -1,6 +0,0 @@ -`RunRequest.with_stepper(...)` now takes a fresh request only, and raises -`TranslationError` for one that `RunRequest.for_run(...)` has given a field retention -other than every field, or a start plane beyond the entrance: both are resolved against -the planes the new stepper section replaces, and were copied unchanged before -([#619](https://github.com/LupoLab/solprop/issues/619)). Call `with_stepper` first and -`for_run` after. `Simulation.with_input` already did, and is unchanged. diff --git a/changelog.d/724-record-ending-last.fixed.md b/changelog.d/724-record-ending-last.fixed.md deleted file mode 100644 index f6d445620..000000000 --- a/changelog.d/724-record-ending-last.fixed.md +++ /dev/null @@ -1 +0,0 @@ -Fixed a run's ending being visible before its record was finished: a run now closes its events and writes its end into `job.json` before its summary records the ending, writes nothing to its record after that, and the machine helper relays a run's ending only once it is recorded. Resuming a run the moment it stops no longer fails on Windows because the old run still holds its events file, and a run reported as ended is listed as ended (#724, #825). diff --git a/changelog.d/815-radial-device-gemm.fixed.md b/changelog.d/815-radial-device-gemm.fixed.md index bbcbeee01..fe9e48452 100644 --- a/changelog.d/815-radial-device-gemm.fixed.md +++ b/changelog.d/815-radial-device-gemm.fixed.md @@ -1 +1 @@ -Fixed a segmentation fault in the native session's `advance` on a CUDA build for compute capability 8.6 (`AMPERE86`, such as an NVIDIA A40): every radial run crashed in its first step, envelope or field, with or without a collar or statistics, with every stepper. The device GEMM's kernel is now a named functor; as an extended host-device lambda instantiated alike in several source files, a Release build called a null copy function. Other device targets and the other routes were not affected ([#815](https://github.com/LupoLab/solprop/issues/815)). +Fixed a segmentation fault of the native backend on a CUDA build for compute capability 8.6 (`AMPERE86`, such as an NVIDIA A40): every radial run crashed in its first step, envelope or field, with or without a collar or statistics, with every stepper. The device GEMM's kernel is now a named functor; as an extended host-device lambda instantiated alike in several source files, a Release build called a null copy function. Other device targets and the other routes were not affected ([#815](https://github.com/LupoLab/solprop/issues/815)). diff --git a/changelog.d/856-scaffold-n-save.changed.md b/changelog.d/856-scaffold-n-save.breaking.md similarity index 100% rename from changelog.d/856-scaffold-n-save.changed.md rename to changelog.d/856-scaffold-n-save.breaking.md diff --git a/changelog.d/863-gated-plasma-benchmark.removed.md b/changelog.d/863-gated-plasma-benchmark.removed.md deleted file mode 100644 index 0abfe6ca8..000000000 --- a/changelog.d/863-gated-plasma-benchmark.removed.md +++ /dev/null @@ -1 +0,0 @@ -Removed the private, test-only gated plasma benchmark source, the time-domain plasma integral that SEP 27's held current replaced, from both backends, with the run-metadata entries and the resume refusal it added. The Luna propagation witnesses that ran it are dropped with it: the reduced and full M2 dispersive-wave comparisons, milestone M4's comb-to-continuum bounds under Luna's vibrational Raman amplitude, and the plasma case of the mixture witness ([accuracy](docs/dev/accuracy.md) sections 5 and 6) (#863). diff --git a/changelog.d/874-basis-identity-on-read.breaking.md b/changelog.d/874-basis-identity-on-read.breaking.md index 1361f9da7..ef12491a5 100644 --- a/changelog.d/874-basis-identity-on-read.breaking.md +++ b/changelog.d/874-basis-identity-on-read.breaking.md @@ -1 +1 @@ -A run no longer computes or records its planes' basis identities before its first step ([#874](https://github.com/LupoLab/solprop/issues/874)): a guide that varies along z paid a mode evaluation at every saved plane, about 0.3 s for 201 planes of a gas-filled capillary with a pressure gradient. The output schema is now 4: the plane-reference record (`RunMetadata.reference`) has no `basis` entry, and files of schema 3 are refused; read them with the solprop version that wrote them. A plane's basis is derived when it is read (`PlaneBasis.of_run`): a spatial or general modal plane's from the file, an ordinary mode set's from its modes at the plane's own position, so a plane saved at a natural step has one too. Those modes come from `field_plane(..., source=simulation)` or from the recipe the output records, rebuilt only when coupling first reads the identity; a plane of a run from a script read without `source=` has no basis identity (`plane.basis.identity` is `None`), and `same_basis` refuses to copy it or apply a declared `BasisChange` to it, naming `source=` as the remedy. `PlaneBasis.identity` may be `None`, and `Recipe.from_output` also takes an opened output. +A run no longer computes or records its planes' basis identities before its first step ([#874](https://github.com/LupoLab/solprop/issues/874)): a guide that varies along z paid a mode evaluation at every saved plane, about 0.3 s for 201 planes of a gas-filled capillary with a pressure gradient. A plane's basis is derived when it is read (`PlaneBasis.of_run`; the record change is output schema 3's), an ordinary mode set's from its modes at the plane's own position, which come from `field_plane(..., source=simulation)` or from the recipe the output records. A plane of a run from a script read without `source=` has no basis identity (`PlaneBasis.identity` may now be `None`), and `same_basis` refuses to copy it or apply a declared `BasisChange` to it, naming `source=` as the remedy. `Recipe.from_output` also takes an opened output. diff --git a/changelog.d/adams-interval-cap-recorded.fixed.md b/changelog.d/adams-interval-cap-recorded.fixed.md new file mode 100644 index 000000000..3b624d5d3 --- /dev/null +++ b/changelog.d/adams-interval-cap-recorded.fixed.md @@ -0,0 +1 @@ +An Adams run (`Multistep`, the default of the capillary interfaces) no longer silently ignores `SimulationSettings(interval_cap=...)`: the Adams march caps its steps by `Multistep(interval_cap=...)`, a different explicit `interval_cap` is now refused by name, and the run's stepper record and resume key carry the cap the march applied. A coupled-flow Adams run used to record `interval_cap=True` without being capped; it now records `False`. diff --git a/changelog.d/apply-transfer-order.breaking.md b/changelog.d/apply-transfer-order.breaking.md index 009f3cfe8..0d71254fa 100644 --- a/changelog.d/apply-transfer-order.breaking.md +++ b/changelog.d/apply-transfer-order.breaking.md @@ -1,4 +1,3 @@ `solprop.processing.compression.apply_transfer` takes the output first, like every other processing function: `apply_transfer(output, transfer)` replaces -`apply_transfer(transfer, output)`. It and the compressors also take `z=` to select the -saved plane nearest a position. +`apply_transfer(transfer, output)`. diff --git a/changelog.d/arm-band-filter.changed.md b/changelog.d/arm-band-filter.changed.md deleted file mode 100644 index c03053019..000000000 --- a/changelog.d/arm-band-filter.changed.md +++ /dev/null @@ -1 +0,0 @@ -On Arm and other non-x86-64 hosts, the native plasma column's band filter sums each sample's taps in one unrolled pass over blocks of samples, with the same values: on an Apple M5 Max the plasma cases' windows ran 1-6 % faster (#560). diff --git a/changelog.d/backend-execution.breaking.md b/changelog.d/backend-execution.breaking.md new file mode 100644 index 000000000..ce1450bc8 --- /dev/null +++ b/changelog.d/backend-execution.breaking.md @@ -0,0 +1,31 @@ +A backend (`solprop.backends`, unstable within 0.x under ADR-058) is built for one +problem and request and runs it in a session of its own; 0.2.0's direct stepping +interface and Python step loop are gone +([SEP 47](https://github.com/LupoLab/solprop/blob/main/docs/dev/seps/archive/sep-0047-run-ownership.md)). +`Simulation.run`, `SimulationRunner`, scans and the `prop_*` functions do all of this +themselves, with unchanged interfaces. +`solprop.backends.registry.select(name, problem, request, ...)` and the backend +constructors take the run's request after the problem, check the pair before they +allocate and expose it as `Backend.request`; execution choices such as the node budget +arrive as `solprop.backends.session.ExecutionOptions` (`options=`). A run starts with +`backend.prepare(problem, request).start(start)`, or +`solprop.backends.sessions.start_session`, from a `solprop.backends.session.Start` +(`Start.entrance(problem)` for a fresh run), which also carries a resumed run's call +ledgers and Adams history; `solprop.driver.run.run_problem` takes a required `start=` in +place of `start_plane=`, and a caller no longer calls `set_initial` first. The `Backend` +protocol loses its stepping members (`set_initial`, `propagate_to`, `observe`, +`march_snapshot`, `restore_march` and the rest; `available_device_memory` is the module +function `solprop_native.available_device_memory()`), and `timed_step()` is replaced by +`Backend.timing_probe(start)`, whose `trial(z, dz)` takes one trial step that commits +nothing and whose `field()` reads that trial's end state. Removed with the loop: +`solprop.backends.driver`, `solprop.backends.multistep` (`CallLedger` is now +`solprop.backends.ledger.CallLedger`), `solprop.backends.multistep_general`, +`solprop.backends.low_storage.LowStorageMarch` (the NumPy reference's own marches are in +`solprop.backends.numpy_ref.marches`), `solprop.backends.numpy_ref.admission` and +`solprop.backends.exponential.refuse_formulation` (its one Adams refusal is +`refuse_adams`), with `COUPLED_SECTIONS` and `EXPONENTIAL_REPRESENTATIONS` of that +module, the reference backend's `helpers` attribute, +`solprop.backends.registry.statistics_refusal`, `NativeBackend.far_field_statistics` +and `solprop_native`'s `*_FIELDS` tuples. `reached` and `replay_tolerance` are now in `solprop.stepper.schedule`, +and the general route's node chunk in `solprop.backends.node_chunk` +(`general_node_chunk`). diff --git a/changelog.d/backend-seam-slimmed.removed.md b/changelog.d/backend-seam-slimmed.removed.md deleted file mode 100644 index eedb3138c..000000000 --- a/changelog.d/backend-seam-slimmed.removed.md +++ /dev/null @@ -1 +0,0 @@ -The backend seam keeps only what the run layer reads ([#860](https://github.com/LupoLab/solprop/issues/860), [#861](https://github.com/LupoLab/solprop/issues/861), [#862](https://github.com/LupoLab/solprop/issues/862)). `Backend.reads_transverse_edge` and `march_export_refusal` (on `Backend` and `RunSession`) are gone, every backend having given one answer, and so are `ExecutionOptions.backend_options`, `solprop.backends.session.SessionBackend`, `solprop.backends.numpy_ref.construct` (construct `NumpyRefBackend` directly), the reference's `helpers` and `propagator_default` attributes, and `refuse_formulation`, `COUPLED_SECTIONS` and `EXPONENTIAL_REPRESENTATIONS` of `solprop.backends.exponential`, whose one Adams refusal is now `refuse_adams`. `RunSession` declares `march_refusal`, `in_flight` and `failure_ticket`. The reference's session and marches moved from `solprop.backends.host` into `solprop.backends.numpy_ref` (`session`, `session_parts` and the `marches` package, class names unchanged); `check_preparation`, `foreign_request` and `AttemptListener` are now in `solprop.backends.session`, and `solprop.backends.session_core` is gone. `MAX_N_POL` is `solprop.nonlinear.responses.MAX_N_POL` alone. A hand-built problem whose polarisation count, vector Raman terms or TDSE statistics a backend used to refuse with `BackendError` is now refused by `validate_run` with `TranslationError`. diff --git a/changelog.d/basis-identity-hashing.breaking.md b/changelog.d/basis-identity-hashing.breaking.md index 430ac7f26..9bfc4d84e 100644 --- a/changelog.d/basis-identity-hashing.breaking.md +++ b/changelog.d/basis-identity-hashing.breaking.md @@ -1 +1 @@ -A modal basis identity (`solprop.coupling.modal_basis_identity`) is formed by rounding `aeff` and `neff` to 40 significant bits with exact binary arithmetic and hashing their bytes: it costs about a third of what it did and is the same on every platform. Identities therefore differ from those an earlier version computed. +A modal basis identity (`solprop.coupling.modal_basis_identity`) is formed by rounding `aeff` and `neff` to 40 significant bits with exact binary arithmetic and hashing their bytes: it costs about a third of what it did and is the same on every platform. Identities therefore differ from those 0.2.0 computed. diff --git a/changelog.d/benchmark-ab-standard-calibration.changed.md b/changelog.d/benchmark-ab-standard-calibration.changed.md deleted file mode 100644 index a40303523..000000000 --- a/changelog.d/benchmark-ab-standard-calibration.changed.md +++ /dev/null @@ -1 +0,0 @@ -`python -m benchmarks ab` now calibrates each build at the `standard` level by default instead of `thorough`, so a development A/B no longer spends several minutes per arm calibrating; pass `--calibrate thorough` for release benchmarks. `track` keeps `thorough`. diff --git a/changelog.d/benchmark-backend-default.changed.md b/changelog.d/benchmark-backend-default.changed.md deleted file mode 100644 index 90ca26ed1..000000000 --- a/changelog.d/benchmark-backend-default.changed.md +++ /dev/null @@ -1 +0,0 @@ -The benchmark harness (`python -m benchmarks track` and `ab`) now runs workers with the backend's own OpenMP waiting by default (`--threading backend`), so that a row measures a user's default run; `--threading passive` keeps the previous policy. History rows record the policy, so rows taken from now on start a new series. diff --git a/changelog.d/benchmark-history-0-2-0.added.md b/changelog.d/benchmark-history-0-2-0.added.md deleted file mode 100644 index 80b66264d..000000000 --- a/changelog.d/benchmark-history-0-2-0.added.md +++ /dev/null @@ -1,2 +0,0 @@ -Performance-history rows for 0.2.0 (`benchmarks/history/`) on the same nine hardware sets -as 0.1.0. diff --git a/changelog.d/benchmark-sep47-matrix.added.md b/changelog.d/benchmark-sep47-matrix.added.md deleted file mode 100644 index b0a7ea84c..000000000 --- a/changelog.d/benchmark-sep47-matrix.added.md +++ /dev/null @@ -1 +0,0 @@ -The benchmark harness has a `sep47` set of short windows for SEP 47's performance matrix: statistics rows at every step under `Multistep()` and `RungeKutta()`, snapshot controllers idle, sparse and at every endpoint, repeated `with_input` runs, a four-point scan on `Local`, saved and field-free radial and Cartesian planes in memory and in HDF5, and coupled flows of 4 and 17 channels. `track --counters` and `ab --counters` add one separately reported run per worker with structural counters from the native backend, counted the same way whether the native execution session or the transitional driver session serves the run: its returns to Python by cause, native march calls, attempts, planes, statistics rows, transverse-edge reads, the fields copied to the host and loaded into the native state, and their bytes. diff --git a/changelog.d/binary64-only.breaking.md b/changelog.d/binary64-only.breaking.md new file mode 100644 index 000000000..83967536c --- /dev/null +++ b/changelog.d/binary64-only.breaking.md @@ -0,0 +1 @@ +Single and mixed precision are retired: solprop computes in IEEE 754 binary64 only ([ADR-077](docs/dev/decisions.md)). The `precision` keyword of `SimulationSettings`, the `Simulation.from_*` constructors and the `prop_*` functions, and a recipe's `precision` key, are gone (a recipe that gives it is refused as an unknown key); so are `solprop.translate.precision`, the reference's binary32 path (`NumpySingleBackend`), the run summary's precision row, the `precision` field of `solprop_native.BuildInfo`, the guide's single-precision page and gallery example, and every internal `precision` argument and field. The kernel's `run_options` reply lists the installed backends under `backends`, in place of `double` and `single`. To migrate, drop `precision=` from calls and the `precision` key from recipes. diff --git a/changelog.d/binary64-only.removed.md b/changelog.d/binary64-only.removed.md deleted file mode 100644 index dfa756bf1..000000000 --- a/changelog.d/binary64-only.removed.md +++ /dev/null @@ -1 +0,0 @@ -Single and mixed precision are retired: solprop computes in IEEE 754 binary64 only ([ADR-077](docs/dev/decisions.md)). The `precision` keyword of `SimulationSettings`, the `Simulation.from_*` constructors and the `prop_*` functions, and a recipe's `precision` key, are gone (a recipe that gives it is refused as an unknown key); so are `solprop.translate.precision`, the `precision` field of `PropagationProblem` and the `precision` argument of `assemble`, the reference's binary32 path (`NumpySingleBackend`), `SINGLE_PRECISION_NOISE`, `solprop.driver.defaults.rtol_in_precision`, the `precision` argument of `default_rtol`, `default_controller`, `default_integrator`, `resolve_noise` and `solprop.backends.registry.available`, the run summary's precision row, the `precision` field of `solprop_native.BuildInfo`, and the guide's single-precision page and gallery example. The kernel's `run_options` reply lists the installed backends under `backends`, in place of `double` and `single`. diff --git a/changelog.d/blas-idle-children.changed.md b/changelog.d/blas-idle-children.changed.md index 7fb69c2cf..a0b893611 100644 --- a/changelog.d/blas-idle-children.changed.md +++ b/changelog.d/blas-idle-children.changed.md @@ -1 +1 @@ -Python processes solprop starts (a run from the window, directly or as a Slurm job, the window's kernel, and `Pool` workers) take `OPENBLAS_THREAD_TIMEOUT=20` unless it is set, so NumPy's and SciPy's OpenBLAS pools no longer spin on every CPU for a moment as they load: importing the driver used 13.8 CPU seconds on a 72-CPU Linux machine, and now 0.75 ([#383](https://github.com/LupoLab/solprop/issues/383)). The performance guide says how to set it for your own scripts. +Python processes solprop starts (a run from the window, directly or as a Slurm job, the window's kernel, and `Pool` workers) take `OPENBLAS_THREAD_TIMEOUT=20` unless it is set, as does the batch script of a Slurm scan (`solprop.driver.executors.Slurm`) for its controller, so NumPy's and SciPy's OpenBLAS pools no longer spin on every CPU for a moment as they load: importing the driver used 13.8 CPU seconds on a 72-CPU Linux machine, and now 0.75 ([#383](https://github.com/LupoLab/solprop/issues/383)). The performance guide says how to set it for your own scripts. diff --git a/changelog.d/boundaries-split-step-helpers.breaking.md b/changelog.d/boundaries-split-step-helpers.breaking.md new file mode 100644 index 000000000..7b59223e9 --- /dev/null +++ b/changelog.d/boundaries-split-step-helpers.breaking.md @@ -0,0 +1,4 @@ +Removed `solprop.boundaries.split_step_factor`, `apply_split_step` and `apply_band_mask`, +which no backend ran: the `absorber_scheme="split_step"` path is the backends' own. To +reproduce them, multiply a time-domain field by `numpy.exp(-0.5 * temporal_rate * step)` +and mask a spectrum with `numpy.where(band_mask, spectrum, 0.0)`. diff --git a/changelog.d/bounded-cycle-memos.fixed.md b/changelog.d/bounded-cycle-memos.fixed.md new file mode 100644 index 000000000..03bcde5f8 --- /dev/null +++ b/changelog.d/bounded-cycle-memos.fixed.md @@ -0,0 +1,3 @@ +The TDSE response's per-configuration memos and the envelope plasma's cycle integrals, +which kept one entry for every configuration or field range met, now keep the sixteen +most recent, so a long scan or front-end session no longer grows its memory with them. diff --git a/changelog.d/capillary-envelope-mode-count.fixed.md b/changelog.d/capillary-envelope-mode-count.fixed.md index 9ae4ef379..d52e4549a 100644 --- a/changelog.d/capillary-envelope-mode-count.fixed.md +++ b/changelog.d/capillary-envelope-mode-count.fixed.md @@ -1 +1 @@ -`scalar_paraxial` coupling into a capillary reports the omitted leaky-field physics for the field actually coupled, as the change of power launched into each mode. The recorded capillary envelope was measured only on Gaussian beams and equal-amplitude three-mode exits, so it understated the discrepancy for structured fields about tenfold, even at four modes: at delta = 2.5e-3 (a 75 µm capillary at 800 nm) a structured beam or a capillary exit of a few modes with arbitrary amplitudes changes the launched power by 1e-2 to 2e-2, against the 1.5e-3 the record allowed. The new `FieldEnvelope` `capillary-he1m-scalar-vs-leaky-marcatili-field-2026-11` evaluates it against Marcatili's leaky HE1m field in closed form at every bin, exactly for a capillary exit (zero into an identical capillary) and with a bounded series remainder for a beam, and reports it with scope `field`. Its mode range now bounds the highest HE1m radial order present, up to 24, rather than the channel count, so two polarisations of four modes are no longer counted as eight and a set such as HE1,25 to HE1,33 is refused rather than counted as nine. +`scalar_paraxial` coupling into a capillary reports the omitted leaky-field physics for the field actually coupled, as the change of power launched into each mode. The recorded capillary envelope was measured only on Gaussian beams and equal-amplitude three-mode exits, so it understated the discrepancy for structured fields about tenfold: at delta = 2.5e-3 (a 75 µm capillary at 800 nm) a structured beam or a capillary exit of a few modes with arbitrary amplitudes changes the launched power by 1e-2 to 2e-2, against the 1.5e-3 the record allowed. The new envelope, evaluated against Marcatili's leaky HE1m field, is reported with scope `field`. Its mode range now bounds the highest HE1m radial order present, up to 24, rather than the channel count, so two polarisations of four modes are no longer counted as eight and a set such as HE1,25 to HE1,33 is refused rather than counted as nine. diff --git a/changelog.d/capillary-polarisation-keyword.removed.md b/changelog.d/capillary-polarisation-keyword.breaking.md similarity index 100% rename from changelog.d/capillary-polarisation-keyword.removed.md rename to changelog.d/capillary-polarisation-keyword.breaking.md diff --git a/changelog.d/cf4-coupled-flow.removed.md b/changelog.d/cf4-coupled-flow.breaking.md similarity index 100% rename from changelog.d/cf4-coupled-flow.removed.md rename to changelog.d/cf4-coupled-flow.breaking.md diff --git a/changelog.d/channel-wording.changed.md b/changelog.d/channel-wording.changed.md deleted file mode 100644 index 9ccd03a25..000000000 --- a/changelog.d/channel-wording.changed.md +++ /dev/null @@ -1 +0,0 @@ -Messages and documentation no longer call the channel routes, their responses and their per-channel statistics "legacy": they are first-class beside the general modal basis. The refusals now read "TDSE does not define the rate-model statistics ...", "... and no channel response ..." (a general modal guide beside a channel route's response) and "... neither scalar-only models nor a fraction" (an optmat Raman response), and `RamanResponse(models=...)` is documented as the shorthand for scalar-only `tensor_terms` it is. diff --git a/changelog.d/cli-export-form.breaking.md b/changelog.d/cli-export-form.breaking.md new file mode 100644 index 000000000..f3fe55ad8 --- /dev/null +++ b/changelog.d/cli-export-form.breaking.md @@ -0,0 +1 @@ +`solprop export` no longer takes the required `--python` flag: `solprop export recipe.toml` prints the Python script, and `--form python` names that form explicitly. Drop `--python` from scripts that call it. diff --git a/changelog.d/closed-file-run-readable.changed.md b/changelog.d/closed-file-run-readable.changed.md index 08abbde8f..e0181c2e5 100644 --- a/changelog.d/closed-file-run-readable.changed.md +++ b/changelog.d/closed-file-run-readable.changed.md @@ -2,4 +2,6 @@ A finished file run is readable through the handler it returned: `prop_*(..., output="run.h5")` and `Simulation.run` hand back a closed `HDF5Output` whose reads (`run["field"]`, `fields()`, `plane_field()`, processing functions and plots) open the file read-only for the one read and close it again, so no handle is held between reads. A -suspended writer still refuses, and the refusal now says why. +suspended writer still refuses, and the refusal now says why. Once another run has written or +continued a file at that path, the handler's read is refused, naming the file, and +`open_file` reads what the file now holds. diff --git a/changelog.d/comparison-multistep.removed.md b/changelog.d/comparison-multistep.breaking.md similarity index 60% rename from changelog.d/comparison-multistep.removed.md rename to changelog.d/comparison-multistep.breaking.md index 78a586d56..80fd5d4ab 100644 --- a/changelog.d/comparison-multistep.removed.md +++ b/changelog.d/comparison-multistep.breaking.md @@ -1 +1 @@ -Removed `solprop.stepper.multistep.ComparisonMultistep`, the benchmark-only Adams variants SEP 13 compared and did not select (PECE, explicit Adams–Bashforth, the matched predictor–corrector pairs and their Hermite dense interpolant), with the reference's general Adams path that stepped them, `milne_factor`, `defect_integral`, the `Corrector` and `Interpolant` types, `Multistep.corrector`, `Multistep.corrector_nodes` and `IntegrationSpec.reference_only` (ADR-077). Use `Multistep()`; `Multistep(order=q, variable_order=False, formulation="interaction")` is the one-order-higher PEC variant the comparison family also named. +Removed `solprop.stepper.multistep.ComparisonMultistep`, the benchmark-only Adams variants SEP 13 compared and did not select (PECE, explicit Adams–Bashforth, the matched predictor–corrector pairs and their Hermite dense interpolant), with the reference's general Adams path that stepped them, `milne_factor`, `defect_integral`, the `Corrector` and `Interpolant` types, `Multistep.corrector` and `Multistep.corrector_nodes` (ADR-077). Use `Multistep()`; `Multistep(order=q, variable_order=False, formulation="interaction")` is the one-order-higher PEC variant the comparison family also named. diff --git a/changelog.d/compressor-mode-error.breaking.md b/changelog.d/compressor-mode-error.breaking.md new file mode 100644 index 000000000..9b4d33cc9 --- /dev/null +++ b/changelog.d/compressor-mode-error.breaking.md @@ -0,0 +1 @@ +The compressors and `apply_transfer` refuse a `modes=` selection the run does not have, or an empty one, with `ModeError`, as every other processing reader does, instead of `ProcessingError`: catch `ModeError` (or `ValueError`, which both subclass) around them. diff --git a/changelog.d/dense-admission-revalidated.fixed.md b/changelog.d/dense-admission-revalidated.fixed.md deleted file mode 100644 index 363d15670..000000000 --- a/changelog.d/dense-admission-revalidated.fixed.md +++ /dev/null @@ -1 +0,0 @@ -A run request changed after translation to dense observation (`interpolate_planes`) is now refused where a backend is prepared, as at translation, beside the per-step temporal collar (`absorber_scheme="split_step"`), a coupled linear flow or the `"modified"` noise model: `validate_run` runs dense observation's admission itself, so the refusal comes before any session storage is allocated ([#682](https://github.com/LupoLab/solprop/issues/682)). diff --git a/changelog.d/development-schema-readers.removed.md b/changelog.d/development-schema-readers.removed.md deleted file mode 100644 index 68322ba13..000000000 --- a/changelog.d/development-schema-readers.removed.md +++ /dev/null @@ -1 +0,0 @@ -Output files written by development builds between 0.1.0 and 0.2.0 in forms no release wrote are no longer read specially: a march snapshot without a `history_key` is now ignored with a warning and the Adams history starts afresh, and `MarchSnapshot.history_key` is required. Files written by 0.2.0 read and resume as before; read an older development file with the build that wrote it. diff --git a/changelog.d/driver-session-loop.breaking.md b/changelog.d/driver-session-loop.breaking.md deleted file mode 100644 index d044bc8b4..000000000 --- a/changelog.d/driver-session-loop.breaking.md +++ /dev/null @@ -1,4 +0,0 @@ -`solprop.driver.service`, the loop that services a run's execution session, is renamed -`solprop.driver.session_loop`, apart from the front end's `solprop.service`. -`solprop.driver.run.MARCH_SNAPSHOT_AUTO_BYTES` is gone; the one limit is -`solprop.translate.run_request.MARCH_SNAPSHOT_AUTO_BYTES`. diff --git a/changelog.d/driver-simulation-split.breaking.md b/changelog.d/driver-simulation-split.breaking.md index d69dc0bd3..0c17477c8 100644 --- a/changelog.d/driver-simulation-split.breaking.md +++ b/changelog.d/driver-simulation-split.breaking.md @@ -1,7 +1,6 @@ -`solprop.driver.simulation` now holds the `Simulation` class alone; the rest moved -into modules by concern. Import `SimulationSettings` and `default_collar` from +`solprop.driver.simulation` now holds the `Simulation` class alone; the rest moved into +modules by concern. Import `SimulationSettings` and `default_collar` from `solprop.driver.settings` (or `SimulationSettings` from `solprop.driver`), `SimulationRunner` and `check_derived_problem` from `solprop.driver.runner`, `metadata_for` from `solprop.driver.metadata`, `default_field_range` from -`solprop.driver.inputs` and `default_radial_order` from -`solprop.driver.routes.hollow`; the names `solprop.driver` exports are unchanged. +`solprop.driver.inputs` and `default_radial_order` from `solprop.driver.routes.hollow`. diff --git a/changelog.d/edge-read-backstop.changed.md b/changelog.d/edge-read-backstop.changed.md index 21d26def2..874d21541 100644 --- a/changelog.d/edge-read-backstop.changed.md +++ b/changelog.d/edge-read-backstop.changed.md @@ -1 +1 @@ -The transverse edge's read spacing has a growing backstop: `min(B, 4g/v_q)`, with `B` starting at `L/16` and doubling at each read whose reach has not grown by a tenth since it started, up to `L/4`. A free-space run whose spectrum holds far from its edge no longer takes extra steps for its reads. On the suite's `line` case the edge costs 2.9 % of the run where it cost 12.8 %, with 13 reads where it took 23 ([#396](https://github.com/LupoLab/solprop/issues/396)). A planar run also no longer evaluates its slab modes again at each run to set up the edge. On scaled versions of SEP 40's linear witnesses (414 packets that must stop) and on a self-focusing line beam in narrowed boxes (80 configurations), every run that stopped or warned under the former spacing still does. +The transverse edge's read spacing has a growing backstop: `min(B, 4g/v_q)`, with `B` starting at `L/16` and doubling at each read whose reach has not grown by a tenth since it started, up to `L/4`. A free-space run whose spectrum holds far from its edge no longer takes extra steps for its reads. On the suite's `line` case the edge costs 2.9 % of the run where it cost 12.8 %, with 13 reads where it took 23 ([#396](https://github.com/LupoLab/solprop/issues/396)). A planar run also no longer evaluates its slab modes again at each run to set up the edge. diff --git a/changelog.d/fftw-plans-kept.changed.md b/changelog.d/fftw-plans-kept.changed.md index a86261955..f5785f0d4 100644 --- a/changelog.d/fftw-plans-kept.changed.md +++ b/changelog.d/fftw-plans-kept.changed.md @@ -1 +1 @@ -The native backend now keeps the FFTW plans its runs measure by default, so each transform shape is measured once per machine and build instead of on every run. Plans are kept per transform in `wisdom.json` in the calibration store's directory for the machine and build, and a calibration profile's own plans take precedence. `SOLPROP_FFTW_WISDOM` now only moves this file, and the file it names no longer turns off a profile's FFT planning. `SOLPROP_CALIBRATION=off` keeps no default file, and `solprop calibrate --clear` removes the plans. Plans kept by earlier releases are not read; their files can be deleted. A name that cannot be used now logs a warning and the run plans without stored plans, where it used to raise. The store is keyed by the machine fingerprint, which tells Apple silicon models apart (#136). +The native backend now keeps the FFTW plans its runs measure by default, so each transform shape is measured once per machine and build instead of on every run. Plans are kept per transform in `wisdom.json` in the calibration store's directory for the machine and build, and a calibration profile's own plans take precedence. `SOLPROP_FFTW_WISDOM` now only moves this file. `SOLPROP_CALIBRATION=off` keeps no default file, and `solprop calibrate --clear` removes the plans. Plans kept by earlier releases are not read; their files can be deleted. The store is keyed by the machine fingerprint, which tells Apple silicon models apart (#136). diff --git a/changelog.d/field-grid-ffac-minimum.breaking.md b/changelog.d/field-grid-ffac-minimum.breaking.md new file mode 100644 index 000000000..8eb28b7ff --- /dev/null +++ b/changelog.d/field-grid-ffac-minimum.breaking.md @@ -0,0 +1 @@ +`FieldGrid.from_limits` refuses `ffac` below 2.2, and `TimeGrid.validate` refuses a field grid whose spectral collar is not exactly zero at the zero-frequency or Nyquist bin. With `2 <= ffac < 2.2` the coarse Nyquist bin lay inside the collar and kept field, which broke the energy identities of `fourier.oversample`, `fourier.spectral_density` and `spatial.node_spectrum`. Pass `ffac >= 2.2` (the default, 6, is unchanged). `EnvelopeGrid` still accepts `ffac >= 2`. diff --git a/changelog.d/field-reduction-plane-subset.fixed.md b/changelog.d/field-reduction-plane-subset.fixed.md new file mode 100644 index 000000000..1d76b146d --- /dev/null +++ b/changelog.d/field-reduction-plane-subset.fixed.md @@ -0,0 +1 @@ +The `processing.scans.field_at_plane` reduction reads its own plane with `Output.plane_field`, so it evaluates on a run saved with `fields="planes"` whose chosen plane kept its field, rather than raising `OutputError`. diff --git a/changelog.d/final-pi-controller.breaking.md b/changelog.d/final-pi-controller.breaking.md index c54b23092..0e2117fef 100644 --- a/changelog.d/final-pi-controller.breaking.md +++ b/changelog.d/final-pi-controller.breaking.md @@ -1 +1 @@ -`PIController` is final: defining a subclass raises `StepperError` (ADR-077). Both backends implement its decisions and its norm (`scale`, `accepts`, `propose`, `rejection_factor`, `start_factor`, `equivalent_norm`) themselves, so a subclass that overrode one would have stepped differently on each; it ran on `numpy_ref` alone and native refused it. Set the controller's fields instead. +`PIController` is final: defining a subclass raises `StepperError` (ADR-077). Both backends implement its decisions and its norm (`scale`, `accepts`, `propose`, `rejection_factor`, `start_factor`, `equivalent_norm`) themselves, so a subclass that overrode one would step differently on each (0.2.0 stepped such a run on native with solprop's Python march and a `HostMarchWarning`). Set the controller's fields instead. diff --git a/changelog.d/free-space-vector-propagators.changed.md b/changelog.d/free-space-vector-propagators.changed.md deleted file mode 100644 index 1a4fb1f30..000000000 --- a/changelog.d/free-space-vector-propagators.changed.md +++ /dev/null @@ -1 +0,0 @@ -The native backend forms free space's separable stage propagators a tile at a time through its vector maths (SLEEF on x86-64 and macOS arm64), rather than one libm `sincos` per element, which took 18 % of a one-thread `line` run. `line` takes 0.89 of its time at one thread and 0.93 at 16, and the Cartesian filament 0.93 at 16 ([#338](https://github.com/LupoLab/solprop/issues/338)). diff --git a/changelog.d/front-end-figure-export.fixed.md b/changelog.d/front-end-figure-export.fixed.md new file mode 100644 index 000000000..427aa2a47 --- /dev/null +++ b/changelog.d/front-end-figure-export.fixed.md @@ -0,0 +1,3 @@ +The desktop front end no longer keeps every publication figure it exports in memory: the +analysis process closes each figure once written, so a long session neither grows nor +warns of more than twenty open figures. diff --git a/changelog.d/gas-fill-needs-pressure.breaking.md b/changelog.d/gas-fill-needs-pressure.breaking.md new file mode 100644 index 000000000..180e5f733 --- /dev/null +++ b/changelog.d/gas-fill-needs-pressure.breaking.md @@ -0,0 +1,12 @@ +A gas fill no longer takes a pressure it was not given: the same omitted argument meant +0 bar on the modes and 1 bar on the routes and `SpatialMedium`. Wherever a gas is named, +its pressure must now be passed, in bar, or the call is refused with "a gas fill needs +its pressure" naming `pressure`: on the hollow modes, the `ModeCollection` factories, +`SpatialMedium` and the capillary and waveguide routes (for a built-in gas, `"air"` or a +mapping of fractions). Where no gas is named nothing changes: a mode without a gas is +evacuated, `SpatialMedium()` is vacuum, and a `Mixture` carries its own pressure. To +migrate, add the pressure the call used to take by default: +`MarcatiliMode(125e-6, "He", 0.0)` for a mode or mode set (or drop the gas, which is +what 0 bar meant), and `prop_capillary(r, L, "He", 1.0)` or `SpatialMedium("Ar", 1.0)` +for a route or a medium. A recipe's route no longer resolves an omitted `pressure` to +one bar. diff --git a/changelog.d/gui-gnlse-noise-page.fixed.md b/changelog.d/gui-gnlse-noise-page.fixed.md new file mode 100644 index 000000000..ec5724146 --- /dev/null +++ b/changelog.d/gui-gnlse-noise-page.fixed.md @@ -0,0 +1 @@ +The desktop front end no longer shows a GNLSE fibre's results with a Noise and coherence page that could never be opened: no run is a seeded ensemble the page could read. diff --git a/changelog.d/gui-home-runs-thread.fixed.md b/changelog.d/gui-home-runs-thread.fixed.md new file mode 100644 index 000000000..b72ac9280 --- /dev/null +++ b/changelog.d/gui-home-runs-thread.fixed.md @@ -0,0 +1,3 @@ +The desktop front end's Home lists the workspace's runs on a thread, so a large or +network-mounted workspace no longer blocks the window at each refresh; it lists the runs +that have a results file. diff --git a/changelog.d/gui-kernel-failures-said.fixed.md b/changelog.d/gui-kernel-failures-said.fixed.md new file mode 100644 index 000000000..bf0a80eee --- /dev/null +++ b/changelog.d/gui-kernel-failures-said.fixed.md @@ -0,0 +1 @@ +The desktop front end now says at the foot of its window when solprop's kernel fails to give the examples, the list of gases, the run options, a class's example or a sheet's curve, where Home or the sheet was left empty without a word. diff --git a/changelog.d/gui-pin-roots-button.removed.md b/changelog.d/gui-pin-roots-button.removed.md new file mode 100644 index 000000000..1e7391d13 --- /dev/null +++ b/changelog.d/gui-pin-roots-button.removed.md @@ -0,0 +1 @@ +Removed the Roots button from a pinned value's editor in the desktop front end, which did nothing when pressed; the editor still takes the lowest or the highest root in the search range. diff --git a/changelog.d/gui-workflow-flag.removed.md b/changelog.d/gui-workflow-flag.removed.md new file mode 100644 index 000000000..f1f1c0169 --- /dev/null +++ b/changelog.d/gui-workflow-flag.removed.md @@ -0,0 +1 @@ +Removed the hidden `--workflow` option of `solprop-gui`, which did nothing: the command now refuses it as an unknown argument. diff --git a/changelog.d/hollow-alpha-callable-checked.fixed.md b/changelog.d/hollow-alpha-callable-checked.fixed.md new file mode 100644 index 000000000..2944e44b0 --- /dev/null +++ b/changelog.d/hollow-alpha-callable-checked.fixed.md @@ -0,0 +1 @@ +The hollow modes (`MarcatiliMode`, `VincettiMode`, the tabulated, rectangular and slab modes) now refuse an `alpha` callable that returns a non-finite or negative attenuation, or one of the wrong shape, with `ModeError`, as `StepIndexMode` does, instead of carrying NaN into `neff` or reading a negative value as gain; every family evaluates `alpha` through one helper. diff --git a/changelog.d/host-fixed-cost.changed.md b/changelog.d/host-fixed-cost.changed.md deleted file mode 100644 index f87740f3d..000000000 --- a/changelog.d/host-fixed-cost.changed.md +++ /dev/null @@ -1 +0,0 @@ -A run's fixed host cost is smaller ([#347](https://github.com/LupoLab/solprop/issues/347)): the first statistics no longer import `scipy.signal` (0.7 s), opening a run's output no longer serialises and digests its configuration a second time, and package versions are read once per process. A large free-space launch builds and translates faster, its column energies summed and its admittance copied in threads. diff --git a/changelog.d/host-march-warning.removed.md b/changelog.d/host-march-warning.removed.md new file mode 100644 index 000000000..fa3bea490 --- /dev/null +++ b/changelog.d/host-march-warning.removed.md @@ -0,0 +1,4 @@ +`solprop.exceptions.HostMarchWarning` is removed: the native backend steps every run it +admits in its own session and refuses the rest by name, so no configuration issued it. +Delete any import of it, or warning filter that names it, such as +`ignore::solprop.exceptions.HostMarchWarning`. diff --git a/changelog.d/ideal-gas-non-finite-state.fixed.md b/changelog.d/ideal-gas-non-finite-state.fixed.md new file mode 100644 index 000000000..225eebac3 --- /dev/null +++ b/changelog.d/ideal-gas-non-finite-state.fixed.md @@ -0,0 +1,4 @@ +`solprop.physdata.ideal_gas_density`, and `density` and `pressure` with `ideal=True`, +now refuse a NaN or infinite pressure, number density or temperature with a +`MaterialError`, as the real-gas path already did, rather than returning NaN or +infinity. diff --git a/changelog.d/log-protocols.breaking.md b/changelog.d/log-protocols.breaking.md index c25bc2b97..b38f53078 100644 --- a/changelog.d/log-protocols.breaking.md +++ b/changelog.d/log-protocols.breaking.md @@ -1,12 +1,12 @@ -`solprop.log` has two reporter protocols instead of six. `ProgressReporter` now declares all -six calls (`summary`, `started`, `step`, `plane`, `finished`, `interrupted`), each with a -no-op default that a subclass inherits, and `ScanReporter` declares `point_reporter` -(default `None`). `InterruptibleReporter`, `SummarisingReporter`, `PlaneObserver` and -`WatchingScanReporter` are removed: an `isinstance` test against them becomes one against -`ProgressReporter` or `ScanReporter`, and `observe_plane` stays an optional method that a -reporter may define. A reporter that subclasses `NullReporter` or `NullScanReporter` needs -no change. One written from scratch to the four basic calls must now also define `summary` -and `interrupted`, or subclass `NullReporter` (or `ProgressReporter`) to inherit them; a -run refuses it with a `DriverError` before it starts. Likewise a scan reporter must define -`point_reporter` or subclass `NullScanReporter` (or `ScanReporter`). What scripts, the GUI, -the service, scans and the CLI show is unchanged. +`solprop.log` has two reporter protocols instead of six. `ProgressReporter` now declares +all six calls (`summary`, `started`, `step`, `plane`, `finished`, `interrupted`), each +with a no-op default that a subclass inherits, and `ScanReporter` declares +`point_reporter` (default `None`). `InterruptibleReporter`, `SummarisingReporter`, +`PlaneObserver` and `WatchingScanReporter` are removed: an `isinstance` test against +them becomes one against `ProgressReporter` or `ScanReporter`, and `observe_plane` stays +an optional method that a reporter may define. A reporter that subclasses `NullReporter` +or `NullScanReporter` needs no change. One written from scratch to the four basic calls +must now also define `summary` and `interrupted`, or subclass `NullReporter` (or +`ProgressReporter`) to inherit them; a run refuses it with a `DriverError` before it +starts. Likewise a scan reporter must define `point_reporter` or subclass +`NullScanReporter` (or `ScanReporter`). diff --git a/changelog.d/log-refusals-driver-error.changed.md b/changelog.d/log-refusals-driver-error.changed.md new file mode 100644 index 000000000..51c2d5e2f --- /dev/null +++ b/changelog.d/log-refusals-driver-error.changed.md @@ -0,0 +1,4 @@ +The progress refusals of `solprop.log` (`set_default_progress`, `default_reporter` and +`BarReporter`'s `period`) raise a `DriverError` instead of a bare `ValueError` +(`DriverError` is now a `ValueError`, so `except ValueError` still catches them); and +`configure_logging(file=...)` writes the log file as UTF-8 whatever the locale. diff --git a/changelog.d/loss-vocabulary.breaking.md b/changelog.d/loss-vocabulary.breaking.md index 9b087aa86..8b339ff19 100644 --- a/changelog.d/loss-vocabulary.breaking.md +++ b/changelog.d/loss-vocabulary.breaking.md @@ -9,9 +9,6 @@ hollow modes), the `ModeCollection` factories, `prop_capillary` and `from_table`), whose `loss=` was already an absolute attenuation, take it as `alpha=`. Migrate `loss=False` to `loss_scale=0.0`, `loss=0.5` to `loss_scale=0.5`, a callable `loss=f` to `alpha=f`, drop `loss=True`, and write `loss_scale = 0.0` in a recipe for -`loss = false`. `SpecifiedMode.alpha(omega, z)` is now `SpecifiedMode.attenuation(omega, -z)` and `loss_path` is `alpha_path`, because `alpha` is the declared field. A mode's -printed form says what its loss is (`loss=model`, `loss=none`, `loss=model x 0.5`, -`loss=alpha 0.1 1/m`). A run record names the new keywords, so its configuration hash -differs from one written before, which therefore cannot be resumed; the output schema -is unchanged. +`loss = false`. `SpecifiedMode.alpha(omega, z)` is now +`SpecifiedMode.attenuation(omega, z)` and `loss_path` is `alpha_path`, because `alpha` +is the declared field. diff --git a/changelog.d/memory-to-file-recipe.fixed.md b/changelog.d/memory-to-file-recipe.fixed.md new file mode 100644 index 000000000..505dd2259 --- /dev/null +++ b/changelog.d/memory-to-file-recipe.fixed.md @@ -0,0 +1 @@ +`MemoryOutput.to_file` now writes the recipe a run was built from, so a recipe run kept in memory and written to a file can be resumed (`solprop resume`), read back with `Recipe.from_output`, and give its saved planes their basis identity, as the file an `HDF5Output` writes does. diff --git a/changelog.d/modal-accessors-in-resume-key.breaking.md b/changelog.d/modal-accessors-in-resume-key.breaking.md deleted file mode 100644 index e16780e9d..000000000 --- a/changelog.d/modal-accessors-in-resume-key.breaking.md +++ /dev/null @@ -1 +0,0 @@ -A general modal run's resume key now covers the accessor list its record publishes (`modal["accessors"]`), as it covers the rest of the general modal identity: a file whose list differs from the run's, shorter or longer, is refused on resume as a configuration mismatch naming `modal.accessors`, where a shorter list used to resume. The separate check that refused a file naming an accessor this build lacks is gone. Finish such a file with the solprop version that wrote it, or start a new one. diff --git a/changelog.d/mode-collection-factories.breaking.md b/changelog.d/mode-collection-factories.breaking.md index ceadcbc18..be9067484 100644 --- a/changelog.d/mode-collection-factories.breaking.md +++ b/changelog.d/mode-collection-factories.breaking.md @@ -1,6 +1,7 @@ The `ModeCollection` factories share one layout: the geometry, then `gas` and -`pressure` (optional, as on the modes), then keyword-only options, with `temperature=None` -(room temperature, or the mixture's own) and `mixture=` on all of them. `he1m` and +`pressure` (as on the modes: no gas is an evacuated guide, and a gas needs its +pressure), then keyword-only options, with `temperature=None` (room temperature, or the +mixture's own) and `mixture=` on all of them. `he1m` and `vincetti` take `count=` by keyword (default one), `slab` takes `orders=` by keyword (default `(1,)`) after the fill, and `marcatili` takes `kinds=`, `n=` and `m=` by keyword: write `ModeCollection.slab(63.5e-6, "Ar", 1.0, orders=(1, 3, 5))` for diff --git a/changelog.d/mode-overlap-tolerance.fixed.md b/changelog.d/mode-overlap-tolerance.fixed.md deleted file mode 100644 index 0aaf0cb17..000000000 --- a/changelog.d/mode-overlap-tolerance.fixed.md +++ /dev/null @@ -1 +0,0 @@ -`solprop.modes.collection.overlap` (and so `orthonormality` and the orthonormality check on a mode set given to a waveguide simulation) integrates the normalised product, so the adaptive rule's absolute tolerance no longer stops it unconverged when the mode's normalisation integral is small. A supplied set of high-order capillary modes (from about 16 HE1m of a 75 µm capillary) was wrongly refused as not orthonormal. diff --git a/changelog.d/native-carrier-z-table.changed.md b/changelog.d/native-carrier-z-table.changed.md deleted file mode 100644 index b8b48ca31..000000000 --- a/changelog.d/native-carrier-z-table.changed.md +++ /dev/null @@ -1 +0,0 @@ -On the native backend's CPU build, the Adams carrier frame (`Multistep(carrier_frame="scalar")`) on an operator stored as a z table (a mixture of gases on independent density paths, for example) now steps natively in the native execution session, with no `HostMarchWarning`, and takes the same steps and gives the same fields as before (#255). The carrier approximation is unchanged; device builds still refuse the carrier frame by name. diff --git a/changelog.d/native-construction-closes-workspace.fixed.md b/changelog.d/native-construction-closes-workspace.fixed.md new file mode 100644 index 000000000..0c6da16b6 --- /dev/null +++ b/changelog.d/native-construction-closes-workspace.fixed.md @@ -0,0 +1,3 @@ +A native backend whose construction fails after its native workspace is built, by a +refusal, an error or an interrupt, now closes the workspace before raising, rather than +leaving it, and on a GPU build its device memory, to the garbage collector. diff --git a/changelog.d/native-cpu-openmp-required.fixed.md b/changelog.d/native-cpu-openmp-required.fixed.md new file mode 100644 index 000000000..82fa2ef45 --- /dev/null +++ b/changelog.d/native-cpu-openmp-required.fixed.md @@ -0,0 +1 @@ +A CPU build of solprop-native with `SOLPROP_NATIVE_ENABLE_OPENMP=OFF` is now refused when CMake configures it, with a message naming the options to set; it used to build and then be refused at every backend construction. diff --git a/changelog.d/native-digest-cmake-modules.changed.md b/changelog.d/native-digest-cmake-modules.changed.md deleted file mode 100644 index 7741377d0..000000000 --- a/changelog.d/native-digest-cmake-modules.changed.md +++ /dev/null @@ -1,3 +0,0 @@ -An editable solprop-native build's `source_digest` now also covers the build's CMake -modules (`native/cmake/*.cmake`), so `check_build()` refuses an extension built before a -change to them, as it does for `CMakeLists.txt` and the C++ sources. diff --git a/changelog.d/native-load-settings-backend-error.fixed.md b/changelog.d/native-load-settings-backend-error.fixed.md new file mode 100644 index 000000000..c61c9bf5d --- /dev/null +++ b/changelog.d/native-load-settings-backend-error.fixed.md @@ -0,0 +1,4 @@ +Selecting the native backend with a malformed process-start setting, such as a +non-numeric `SOLPROP_THREADS`, now raises a `BackendError` carrying the setting's +message instead of a bare `ValueError` or `RuntimeError` from the package import, and +`solprop.backends.available()` is documented as listing the installed backends. diff --git a/changelog.d/native-numpy-ref-decoupled.breaking.md b/changelog.d/native-numpy-ref-decoupled.breaking.md deleted file mode 100644 index fa03faf0e..000000000 --- a/changelog.d/native-numpy-ref-decoupled.breaking.md +++ /dev/null @@ -1,13 +0,0 @@ -The general modal route's and the coupled flow's admission is part of the problem's own -validation (`solprop.translate.admission.check_general_route`), raised once as a -`TranslationError` naming solprop rather than as a `BackendError` from each backend; -`solprop.backends.numpy_ref.admission` and `refuse_general_leaves` are removed. The -general route's derivations moved to `solprop.translate.general` (`node_kerr_tensor`, -`node_kerr_form`, `node_delayed_maps`) and its node chunk to `solprop.backends.node_chunk` -(`general_node_chunk`, `general_planned_chunk`); the quadrature alarm is -`solprop.translate.modal.QUADRATURE_ALARM`, logged on the `solprop.translate.modal` -logger; the Adams call ledger is `solprop.backends.ledger.CallLedger`, and the -reference's Adams module is `solprop.backends.numpy_ref.multistep`. -`CompiledResponses.response_order` is derived from the compiled leaves and is no longer a -constructor argument. `solprop_native` no longer exports the `*_FIELDS` seam tuples, and -`check_build` no longer looks seam members up. diff --git a/changelog.d/native-proc-bind-inherited.fixed.md b/changelog.d/native-proc-bind-inherited.fixed.md new file mode 100644 index 000000000..27cf21cd6 --- /dev/null +++ b/changelog.d/native-proc-bind-inherited.fixed.md @@ -0,0 +1 @@ +A process started from one that imported the native backend no longer reports the inherited `OMP_PROC_BIND=false` as the user's choice: its run metadata's `openmp_proc_bind` is `false`, as in the parent, rather than `environment: OMP_PROC_BIND=false`. The import marks the setting with `SOLPROP_NATIVE_PROC_BIND`. diff --git a/changelog.d/native-statistics-plan.changed.md b/changelog.d/native-statistics-plan.changed.md index f7c3fee7a..71de0b1f6 100644 --- a/changelog.d/native-statistics-plan.changed.md +++ b/changelog.d/native-statistics-plan.changed.md @@ -1 +1 @@ -The native backend evaluates and finishes its statistics natively from a plan lowered once (SEP 47 section 6.4): the half-maximum widths, the species reduction, the multi-channel electron density and peak ionisation rate, the plasma integration ratios, the profile statistics and a general modal basis's flux statistics (`omega0`, `physical_energy`, `spectral_flux`, `analytic_flux`, `fwhm_t`, `fwhm_t_outer`) no longer return to Python, and a general modal plane's statistics no longer copy the field to the host. Their z-dependent inputs are read from the problem's own tables. A profile statistic (`density`, `pressure`, `core_radius`) reads the propagation's table of its path where one reproduces the profile, or the profile tabulated once over the run; its measured error, at most 1e-13 of the profile's magnitude (about 1e-15 on a gas-filled capillary), is recorded in the run's execution record under `statistics_tables`. A modal power weight that varies in z is summed in a different order, a rounding-level change. The native execution session takes every periodic-capable statistic as a native periodic row. +The native backend evaluates and finishes its statistics natively from a plan lowered once (SEP 47 section 6.4), so the default statistics of a modal, general modal, radial or free-space run no longer return to Python, and a general modal plane's statistics no longer copy the field to the host. A profile statistic (`density`, `pressure`, `core_radius`) reads a table of its path, and `zdw` a table of each mode's zero-dispersion wavelength along z made once before the run; their measured errors, at most 1e-13 of a profile's magnitude and 1e-6 of a wavelength, are recorded in the run's execution record under `statistics_tables`. A modal power weight that varies in z is summed in another order, a rounding-level change. The native backend records `zdw` as `nan` where the band holds no zero, as `numpy_ref` does, instead of raising, and refuses by name the metric statistics of a general modal basis whose metric varies inside one of its intervals. On every backend, a statistic the problem does not carry is refused by name before the run starts instead of at the first saved plane: a modal statistic such as `omega0` on a spatial run, a spatial statistic such as `beam_radius` or `absorbed_power` on a modal run (where `numpy_ref` used to return the peak ionisation rate as `absorbed_power`), the plasma integration diagnostics without a field-grid plasma column, and the electron density or peak ionisation rate without a plasma response. diff --git a/changelog.d/native-tooling.changed.md b/changelog.d/native-tooling.changed.md deleted file mode 100644 index 7fee63b7c..000000000 --- a/changelog.d/native-tooling.changed.md +++ /dev/null @@ -1 +0,0 @@ -The native C++ checks: every tracked C++ file is formatted, clang-tidy is pinned to LLVM 23.1 and enables whole check families, the sources compile with stronger warnings, the sanitizer build stops at the first report and checks Kokkos view bounds, and `uv run poe fmt-native` and `uv run poe tidy-native` format and tidy native files locally. diff --git a/changelog.d/numpy-ref-structure.changed.md b/changelog.d/numpy-ref-structure.changed.md deleted file mode 100644 index 2c96e15d4..000000000 --- a/changelog.d/numpy-ref-structure.changed.md +++ /dev/null @@ -1,7 +0,0 @@ -The `numpy_ref` backend's internals are reorganised for reading. The passes are now -the `numpy_ref.passes` subpackage (`transforms`, `responses`, `plasma`, `stepping`), -and the workspace's source evaluation, statistics and coupled flow have modules of their -own (`source`, `statistics`, `coupled_flow`). The Adams engine, kernels and tables are -`multistep`, `adams_kernels` and `adams_tables`. The low-storage engine is -`numpy_ref.engines.NumpyLowStorage`. The package no longer re-exports the passes. -Selecting `backend="numpy_ref"` is unchanged. diff --git a/changelog.d/object-route-defaults.changed.md b/changelog.d/object-route-defaults.breaking.md similarity index 100% rename from changelog.d/object-route-defaults.changed.md rename to changelog.d/object-route-defaults.breaking.md diff --git a/changelog.d/observable-tolerances-removed.breaking.md b/changelog.d/observable-tolerances-removed.breaking.md new file mode 100644 index 000000000..e414f176e --- /dev/null +++ b/changelog.d/observable-tolerances-removed.breaking.md @@ -0,0 +1 @@ +`Simulation.from_waveguide` and `prop_waveguide` no longer take `observable_rtol` and `observable_atol`, which accepted only `None` and refused every number. Drop them from calls: a general modal run's observables are bounded by the solver's own `rtol` and `atol`. diff --git a/changelog.d/old-files-refused.breaking.md b/changelog.d/old-files-refused.breaking.md deleted file mode 100644 index 94a401ae7..000000000 --- a/changelog.d/old-files-refused.breaking.md +++ /dev/null @@ -1 +0,0 @@ -Files, records and recipes written by earlier releases or development builds are refused rather than read: a recipe that gives a retired keyword (`precision`, the grid's `transforms`, or `CoherentWall`'s `method`, `growth_limit` and `fallback`) now gets the ordinary unknown-key error, even for `precision = "double"`, which was dropped before; a march snapshot with the leading axis of one that output schema 2 kept, and a call ledger whose predictor orders are one per step, are refused as malformed rather than named as an earlier build's; a resumed run whose file states no method-history retention at the resume position records the retention as `{"state": "unknown", "reason": "not_recorded"}`, never `"legacy"`; and a recorded backend name is no longer promised to load. Remove the retired keys from a recipe, and finish or read an earlier file with the release that wrote it. diff --git a/changelog.d/one-mode-accelerate.changed.md b/changelog.d/one-mode-accelerate.changed.md deleted file mode 100644 index ec11bc7f2..000000000 --- a/changelog.d/one-mode-accelerate.changed.md +++ /dev/null @@ -1 +0,0 @@ -Single-mode problems on the native backend now run their synthesis and projection on the response team with Apple's Accelerate too, as they already did with OpenBLAS: on an Apple M5 Max at six threads the argon blueshift window ran 0.96 of its time. diff --git a/changelog.d/one-mole-fraction-rule.changed.md b/changelog.d/one-mole-fraction-rule.changed.md new file mode 100644 index 000000000..970d73fe0 --- /dev/null +++ b/changelog.d/one-mole-fraction-rule.changed.md @@ -0,0 +1 @@ +The gas-flow functions (`physdata.transport.viscosity`, `molar_mass`, `sound_speed` and the `gasflow` calculations) validate a composition by the rule `Mixture.fill` applies: its fractions must sum to one within the rounding of its entries (two ulps per entry) rather than within 1e-12, so a flow and a fill accept the same compositions. The refusal messages are the fill's. diff --git a/changelog.d/open-run.removed.md b/changelog.d/open-run.breaking.md similarity index 100% rename from changelog.d/open-run.removed.md rename to changelog.d/open-run.breaking.md diff --git a/changelog.d/optmat-0-10.changed.md b/changelog.d/optmat-0-10.breaking.md similarity index 52% rename from changelog.d/optmat-0-10.changed.md rename to changelog.d/optmat-0-10.breaking.md index efd6cbd8c..6921a9f78 100644 --- a/changelog.d/optmat-0-10.changed.md +++ b/changelog.d/optmat-0-10.breaking.md @@ -1 +1 @@ -solprop requires optmat 0.10.0 or later. Its first real-gas density loads CoolProp in about 0.07 s instead of 0.46 s; no density, index or other recommended value changes, but every equation of state's identity does (optmat's `EVALUATION_VERSION` 2), so the configuration hash of a run with a gas fill changes and a run started on an earlier release finishes on it. +solprop requires optmat 0.10.0 or later. Its first real-gas density loads CoolProp in about 0.07 s instead of 0.46 s; no density, index or other recommended value changes, but every equation of state's identity does (optmat's `EVALUATION_VERSION` 2), which a run with a gas fill records. diff --git a/changelog.d/optmat-rate-nan.fixed.md b/changelog.d/optmat-rate-nan.fixed.md new file mode 100644 index 000000000..5f01440f4 --- /dev/null +++ b/changelog.d/optmat-rate-nan.fixed.md @@ -0,0 +1 @@ +`OptmatRate` raises `MaterialError`, naming the species and the field, when optmat returns a NaN ionisation rate, instead of replacing it silently with the model's maximum rate; an infinite rate is still clipped to the maximum. diff --git a/changelog.d/outcome-read-tolerantly.fixed.md b/changelog.d/outcome-read-tolerantly.fixed.md new file mode 100644 index 000000000..e8ca3afb2 --- /dev/null +++ b/changelog.d/outcome-read-tolerantly.fixed.md @@ -0,0 +1 @@ +An output file whose recorded execution status (`meta/outcome`) another build of the same output schema wrote now reads, as its run record does: an entry this build lacks is dropped and an absent one takes its default. A status that cannot be read is refused with an `OutputError` naming the file, where it used to raise a bare `TypeError`, and opening the file no longer leaves its handle open when it is refused. diff --git a/changelog.d/output-request-error.breaking.md b/changelog.d/output-request-error.breaking.md new file mode 100644 index 000000000..46efccfda --- /dev/null +++ b/changelog.d/output-request-error.breaking.md @@ -0,0 +1,7 @@ +A refused argument to `SnapshotController` (`interval_seconds`, `max_snapshots`) or to +`TDSEArchive` (`path`, `outputs`) raises the new +`solprop.exceptions.OutputRequestError`, a `SolpropError` and a `ValueError`, as a +refused `progress` or `resume` raises a `DriverError`. They raised `OutputError` (a +`RuntimeError`) and bare `TypeError` or `ValueError` before. Catch `OutputRequestError` +or `ValueError` in place of `OutputError` or `TypeError` around these constructors; +`OutputError` still reports a file that cannot be written or read. diff --git a/changelog.d/output-schema-3.breaking.md b/changelog.d/output-schema-3.breaking.md new file mode 100644 index 000000000..40b0f70e8 --- /dev/null +++ b/changelog.d/output-schema-3.breaking.md @@ -0,0 +1 @@ +Output files are written in output schema 3. A file's march snapshot (`/march_snapshot`) stores its `state` as `(n_modes, n_pol, n_omega)` and its engine `rows` as `(n_slots, n_modes, n_pol, n_omega)`, without the leading axis of one they kept before, and the plane-reference record (`RunMetadata.reference`) has no `basis` entry: a plane's basis is derived when it is read. Saved fields, statistics and the rest of the run record are laid out as before. A file or scan written by 0.2.0 (output schema 2) is refused wherever it is opened, read or resumed, and the refusal names the file and the release that wrote it: read, resume or continue it with solprop 0.2.x, and a 0.1.0 file (schema 1) with solprop 0.1.x. Every run's configuration hash also differs from 0.2.0's, since the run record names its record types by module (`solprop.output.records.GridRecord`) and holds the keywords renamed in this release, so a run or scan started on 0.2.0 is finished on 0.2.x. diff --git a/changelog.d/output-schema-split.breaking.md b/changelog.d/output-schema-split.breaking.md index a2956c9d0..c5fd1527e 100644 --- a/changelog.d/output-schema-split.breaking.md +++ b/changelog.d/output-schema-split.breaking.md @@ -1,11 +1,8 @@ `solprop.output.schema` is split into five modules: `solprop.output.serialisation` -(`serialise`, `ArrayDigest`, `StatedInput`, `recorded_input`), `solprop.output.provenance` -(`BackendRecord`, `GitProvenance`, `package_versions`), `solprop.output.records` -(`GridRecord`, `ModeRecord`, `StepperRecord`, `SavedPlane`, `RunOutcome` and the other -record types), `solprop.output.metadata` (`RunMetadata`, `SCHEMA_VERSION`, -`resolve_metadata_write`) and `solprop.output.store` (`Output`, `PlaneStore`, -`FieldRetention` and the other save protocols). Import these names from -`solprop.output`, which still exports the public ones, or from their new module. A run -record names its record types by module (`solprop.output.records.GridRecord`), so every -configuration hash differs from the one an earlier version wrote: a file or a scan -written before cannot be resumed or continued, and is read as it was. +(`serialise`, `ArrayDigest`, `StatedInput`, `recorded_input`), +`solprop.output.provenance` (`BackendRecord`, `GitProvenance`, `package_versions`), +`solprop.output.records` (`GridRecord`, `ModeRecord`, `StepperRecord`, `SavedPlane`, +`RunOutcome` and the other record types), `solprop.output.metadata` (`RunMetadata`, +`SCHEMA_VERSION`, `resolve_metadata_write`) and `solprop.output.store` (`Output`, +`PlaneStore`, `FieldRetention` and the other save protocols). Import these names from +`solprop.output`, which still exports the public ones, or from their new module. diff --git a/changelog.d/parallel-rows-budget.changed.md b/changelog.d/parallel-rows-budget.changed.md deleted file mode 100644 index a2921f052..000000000 --- a/changelog.d/parallel-rows-budget.changed.md +++ /dev/null @@ -1 +0,0 @@ -Host passes too small to thread no longer read the CPU topology first, which took up to a sixth of a short window's host statistics on Linux (#556). diff --git a/changelog.d/physdata-pressure-order.breaking.md b/changelog.d/physdata-pressure-order.breaking.md index bd3b9dd2f..424f86eea 100644 --- a/changelog.d/physdata-pressure-order.breaking.md +++ b/changelog.d/physdata-pressure-order.breaking.md @@ -1,12 +1,12 @@ -The gas-property functions take one argument order, `(gas, pressure, temperature)`, -with the pressure in bar named `pressure` and the temperature defaulting to 293.15 K -everywhere. `density`, `ideal_gas_density`, the equations of state's `density`, -`ReferenceState`, `gasflow.mass_flow` and `gasflow.knudsen_number` rename `pressure_bar` -to `pressure` (write `ReferenceState(pressure=1.0, temperature=273.15)`). +The gas-property functions take one argument order, `(gas, pressure, temperature)`, with +the pressure in bar named `pressure` and the temperature defaulting to 293.15 K in every +function; `ReferenceState`, where a source states its own state, and the +`EquationOfState` protocol keep it required. `density`, `ideal_gas_density`, the +equations of state's `density`, `ReferenceState`, `gasflow.mass_flow` and +`gasflow.knudsen_number` rename `pressure_bar` to `pressure` (write +`ReferenceState(pressure=1.0, temperature=273.15)`). `physdata.transport.sound_speed(gas, temperature, pressure_bar=None)` becomes -`sound_speed(gas, pressure=None, temperature=293.15)`: replace -`sound_speed(gas, T)` with `sound_speed(gas, temperature=T)` and -`sound_speed(gas, T, p)` with `sound_speed(gas, p, T)`. `viscosity`, -`heat_capacity_ratio` and `mean_free_path` now default the temperature to 293.15 K. A gas law's -recorded reference state names `pressure`, so a run's configuration hash differs from -one written before. +`sound_speed(gas, pressure=None, temperature=293.15)`: replace `sound_speed(gas, T)` +with `sound_speed(gas, temperature=T)` and `sound_speed(gas, T, p)` with +`sound_speed(gas, p, T)`. `viscosity`, `heat_capacity_ratio` and `mean_free_path` now +default the temperature to 293.15 K. diff --git a/changelog.d/plot-defaults-from-run.breaking.md b/changelog.d/plot-defaults-from-run.breaking.md index 2a4643165..9b8906334 100644 --- a/changelog.d/plot-defaults-from-run.breaking.md +++ b/changelog.d/plot-defaults-from-run.breaking.md @@ -6,5 +6,5 @@ picosecond fibre pulses and mid-infrared spectra: with no `spec_range`, `prop_2d (`plotting.propagation.default_time_range`: 0.05 % to 99.95 % of each trace's energy, widened by a quarter on each side). `prop_2d` defaults to `axis="wavelength"` like every other plot. `spec_1d(log_min=1e-6)` is now `db_min=-60.0`, in dB below the peak, as on -`prop_2d` and `spectrogram`. `DEFAULT_WAVELENGTH_RANGE`, `DEFAULT_SLICE_WAVELENGTH_RANGE` +`prop_2d` (`spectrogram` names its floor `db_min` too, at -40 dB by default). `DEFAULT_WAVELENGTH_RANGE`, `DEFAULT_SLICE_WAVELENGTH_RANGE` and `DEFAULT_TIME_RANGE` are removed. diff --git a/changelog.d/plot-plane-selection.added.md b/changelog.d/plot-plane-selection.added.md new file mode 100644 index 000000000..52d50427c --- /dev/null +++ b/changelog.d/plot-plane-selection.added.md @@ -0,0 +1 @@ +`plotting.spectrogram`, `time_1d` and `spec_1d` take `plane=`, a saved plane's index (negative from the end; a sequence of them for the slices), as the processing readers do; giving both `plane` and `z` raises `ProcessingError`. diff --git a/changelog.d/pool-worker-interrupt-stops.fixed.md b/changelog.d/pool-worker-interrupt-stops.fixed.md new file mode 100644 index 000000000..3f8b83fe4 --- /dev/null +++ b/changelog.d/pool-worker-interrupt-stops.fixed.md @@ -0,0 +1,3 @@ +A `Pool` scan point whose worker is interrupted, by Ctrl-C (which a terminal sends to +every worker) or SIGTERM, is now a stopped point, given back so that a rerun computes +it, instead of being committed as `failed` with a `KeyboardInterrupt` traceback. diff --git a/changelog.d/precision-resume-key.breaking.md b/changelog.d/precision-resume-key.breaking.md deleted file mode 100644 index 823e796a2..000000000 --- a/changelog.d/precision-resume-key.breaking.md +++ /dev/null @@ -1 +0,0 @@ -A run's configuration no longer records a `precision`, which every run recorded since SEP 33, so the resume key of every run changes once ([ADR-077](docs/dev/decisions.md)): a run started on an earlier release is refused a resume on this one, naming the change. Finish in-flight runs, and resume stopped ones, on the release that started them before upgrading; their output still opens. diff --git a/changelog.d/pressure-keywords-without-unit.breaking.md b/changelog.d/pressure-keywords-without-unit.breaking.md new file mode 100644 index 000000000..e16a24433 --- /dev/null +++ b/changelog.d/pressure-keywords-without-unit.breaking.md @@ -0,0 +1,10 @@ +The steady-flow and pressure-profile functions name their pressures without the unit, +as `physdata` does; the pressures stay in bar. `gasflow.throughput` and +`PressureGradient.two_point` rename `start_bar` and `end_bar` to `start_pressure` and +`end_pressure`, `gasflow.choked_pressure` renames `high_bar` to `high_pressure`, +`gasflow.steady_fill` renames `pressures_bar` to `pressures` (as +`PressureGradient.from_stages` already spells it), `StageFlow` renames its fields +`start_bar` and `end_bar` to `start_pressure` and `end_pressure`, and `FlowReport` +renames `choked_start_bar` and `choked_end_bar` to `choked_start_pressure` and +`choked_end_pressure`. A recipe's `PressureGradient.two_point` table takes the new +keys. Positional calls are unchanged; rename the keywords, recipe keys and attributes. diff --git a/changelog.d/project-tooling.changed.md b/changelog.d/project-tooling.changed.md new file mode 100644 index 000000000..0bda56a27 --- /dev/null +++ b/changelog.d/project-tooling.changed.md @@ -0,0 +1,8 @@ +Project and tooling: the benchmark harness gains performance-history rows for 0.2.0 +(`benchmarks/history/`, on the same nine hardware sets as 0.1.0) and `--counters` on +`track` and `ab`, one separately reported run per worker with the native backend's +structural counters (returns to Python by cause, native calls, attempts, planes, +statistics rows, edge reads and host copies). History rows record the OpenMP wait policy +and are compared only within one native build profile, and `track --append-history` +refuses a native build stamped `+dirty` without `--allow-dirty` +([#138](https://github.com/LupoLab/solprop/issues/138)). diff --git a/changelog.d/public-surface-trim.breaking.md b/changelog.d/public-surface-trim.breaking.md index c2059582c..568f583fc 100644 --- a/changelog.d/public-surface-trim.breaking.md +++ b/changelog.d/public-surface-trim.breaking.md @@ -3,10 +3,12 @@ collections, materials and the mode protocol, and now also exports the derived quantities of `solprop.modes.base` (`beta`, `beta1`, `beta2`, `beta3`, `alpha`, `zdw`, `aeff`, `loss_length`, `db_per_m`, `transmission`); its numerical machinery (the wall families and limits, connections, quadrature rules, `GasFillMixin`, tolerances) is -imported from its submodule, for example `from solprop.modes.capillary import -worst_wall_limits`. `solprop.output` no longer re-exports `PlaneStore`, `PlaneLayout`, -`CheckpointOutput`, `RetainingOutput`, `TerminalCheckpoint`, `StatedInput`, -`serialise`, `resolve_metadata_write`, `package_versions` or the layout and convention -constants; `solprop.driver` no longer re-exports `metadata_for`, -`plane_from_observation`, `LogReporter` or `ProgressReporter` (import the reporters -from `solprop.log`). `solprop.nonlinear` exports `OptmatRate`. +imported from its submodule, for example +`from solprop.modes.wall import worst_wall_limits`. `solprop.output` no longer +re-exports `PlaneStore`, `PlaneLayout`, `CheckpointOutput`, `RetainingOutput`, +`TerminalCheckpoint`, `StatedInput`, `serialise`, `resolve_metadata_write`, +`package_versions` or the layout and convention constants; `solprop.driver` no longer +re-exports `metadata_for` or `plane_from_observation` (import the latter from +`solprop.driver.run`), and neither it nor `solprop.driver.run` re-exports `LogReporter` +or `ProgressReporter`: import the reporters from `solprop.log`. `solprop.nonlinear` +exports `OptmatRate`. diff --git a/changelog.d/pulse-family-checks.fixed.md b/changelog.d/pulse-family-checks.fixed.md new file mode 100644 index 000000000..d052ab085 --- /dev/null +++ b/changelog.d/pulse-family-checks.fixed.md @@ -0,0 +1,5 @@ +`GaussianPulse` now refuses a super-Gaussian order `m` that is not an integer of at least +1, as `SpatialPulse` does; `PulseSum` and `SpatialPulse` refuse a beam given as a temporal +pulse with a `PulseError` at construction instead of a `TypeError` at build time; and +`PlanarPulse`'s printed form and the planar-grid refusal of a `SpatialPulse` name the +`waist` keyword, not a `waist_y` that does not exist. diff --git a/changelog.d/pulse-phases-and-m.breaking.md b/changelog.d/pulse-phases-and-m.breaking.md index 64478f7a9..935c1d0e9 100644 --- a/changelog.d/pulse-phases-and-m.breaking.md +++ b/changelog.d/pulse-phases-and-m.breaking.md @@ -3,6 +3,5 @@ phase of `GaussianPulse`, `SechPulse`, `CustomPulse`, `DataPulse` and `TimeDataP (and of `DataPulse.from_spectral_density`) is `phases=`, the name `prop_gnlse`, `prop_capillary` and `prop_waveguide` use, rather than `phase=`; and the super-Gaussian order of `SpatialPulse` and `PlanarPulse` is `m=`, as on `GaussianPulse`, rather than -`order=`. The meaning is unchanged. A recipe's pulse tables take `phases` and `m`, and -a run's record holds the new names, so a file written before cannot be resumed. +`order=`. The meaning is unchanged. A recipe's pulse tables take `phases` and `m`. Migration: rename `phase=` to `phases=` on the pulses and `order=` to `m=` on the beams. diff --git a/changelog.d/queue-scan-recipe.fixed.md b/changelog.d/queue-scan-recipe.fixed.md new file mode 100644 index 000000000..daea651db --- /dev/null +++ b/changelog.d/queue-scan-recipe.fixed.md @@ -0,0 +1,2 @@ +A recipe scan run on `Queue` or `Slurm` now records its recipe in the collected scan +file, as on `Local` and `Pool`, so `Recipe.from_output` reopens it with its setup. diff --git a/changelog.d/radial-edge-gemm.changed.md b/changelog.d/radial-edge-gemm.changed.md deleted file mode 100644 index 1ebcef767..000000000 --- a/changelog.d/radial-edge-gemm.changed.md +++ /dev/null @@ -1 +0,0 @@ -The native backend's transverse-edge reads on radial grids synthesise the rows they use in one matrix product, once for every table, rather than one sum per sample per table: on an Apple M5 Max the 256- and 512-node radial filaments ran 0.83 and 0.75 of their one-thread windows, and 0.92 and 0.87 at six threads, with the same steps. diff --git a/changelog.d/read-resume-state.breaking.md b/changelog.d/read-resume-state.breaking.md new file mode 100644 index 000000000..924fe7a84 --- /dev/null +++ b/changelog.d/read-resume-state.breaking.md @@ -0,0 +1 @@ +`solprop.output.resume` is renamed `solprop.output.read_resume_state` (also in `solprop.output.hdf5`), and `solprop.sol` no longer exports `resume`: the name read a file's resumable state into a `ResumeState` and continued nothing, which `resume=True` on a run or `solprop resume` does. Replace `from solprop.output import resume` or `from solprop.sol import resume`, and `resume(path)`, with `read_resume_state`; the old name is gone. diff --git a/changelog.d/real-gas-sound-speed-range.fixed.md b/changelog.d/real-gas-sound-speed-range.fixed.md new file mode 100644 index 000000000..188b0a5b2 --- /dev/null +++ b/changelog.d/real-gas-sound-speed-range.fixed.md @@ -0,0 +1 @@ +A real-gas speed of sound (`physdata.transport.sound_speed` with a pressure) checks only the equation of state it comes from: it no longer warns that a gas's transport model is provisional (methane's), nor refuses a temperature inside the equation of state's range but outside the transport properties' range. diff --git a/changelog.d/refractive-index-minus-one-precision.fixed.md b/changelog.d/refractive-index-minus-one-precision.fixed.md new file mode 100644 index 000000000..7df7986d9 --- /dev/null +++ b/changelog.d/refractive-index-minus-one-precision.fixed.md @@ -0,0 +1 @@ +`refractive_index_minus_one` no longer loses precision at low pressure. It formed `n - 1` from `1 + chi1`, the cancellation it exists to avoid, so its relative error grew as the gas thinned: about 1e-12 for helium at 1 bar and up to 3e-7 at 1e-6 bar. It now forms it from `chi1` itself, which scales with the density to rounding. diff --git a/changelog.d/regrid-copy-crops-band.fixed.md b/changelog.d/regrid-copy-crops-band.fixed.md new file mode 100644 index 000000000..df83ed469 --- /dev/null +++ b/changelog.d/regrid-copy-crops-band.fixed.md @@ -0,0 +1 @@ +Fixed `coupling.regrid(..., crop_band=True)` between two grids that share a lattice but not an active band (an explicit `dt=`, or limit pairs with the same short-wavelength end): it now removes the light outside the target's band, as its `RegridReport` says, instead of copying it and leaving `couple` to refuse the plane. diff --git a/changelog.d/resume-choice-public.added.md b/changelog.d/resume-choice-public.added.md new file mode 100644 index 000000000..d4e4b64b2 --- /dev/null +++ b/changelog.d/resume-choice-public.added.md @@ -0,0 +1 @@ +Added `solprop.log.ResumeChoice`, the type `resume=` takes on `Simulation.run` and the `prop_*` routes, so their signatures and `help()` show `resume: bool | Literal['interpolated']` under a public name. diff --git a/changelog.d/resume-keeps-caller-noise.fixed.md b/changelog.d/resume-keeps-caller-noise.fixed.md new file mode 100644 index 000000000..8b87192e1 --- /dev/null +++ b/changelog.d/resume-keeps-caller-noise.fixed.md @@ -0,0 +1,4 @@ +`Simulation.run(..., resume=True)` no longer replaces the simulation's own noise +realisation with the one drawn from the resumed file's recorded seed. The redraw now +belongs to the resumed run alone, so a later fresh `run` of the same simulation is no +longer silently the resumed file's realisation; the resumed run itself is unchanged. diff --git a/changelog.d/route-warnings-thread-safe.fixed.md b/changelog.d/route-warnings-thread-safe.fixed.md new file mode 100644 index 000000000..3e372f87f --- /dev/null +++ b/changelog.d/route-warnings-thread-safe.fixed.md @@ -0,0 +1,4 @@ +Keyword routes built on two threads at once no longer leave the process's warning +filters changed: each route's capture of the material warnings it names a keyword for +now waits for another thread's to end, where two overlapping captures restored each +other's filters and left every later warning recorded instead of shown. diff --git a/changelog.d/run-scan-stale-age.breaking.md b/changelog.d/run-scan-stale-age.breaking.md new file mode 100644 index 000000000..264c7490e --- /dev/null +++ b/changelog.d/run-scan-stale-age.breaking.md @@ -0,0 +1,7 @@ +`run_scan` no longer takes `stale_age`: a `Local` or `Pool` scan holds its file's lock +for its whole session, so a `running` point it finds is always taken up again, and the +keyword never reached `Queue` or `Slurm`. Remove it from calls; a durable queue's lease +is `Queue(stale_age=...)`, and now `Slurm(stale_age=...)` for the queue its tasks share. +`python -m solprop.scan --stale-age` now reaches the tasks of `--submit` and +`--emit-slurm`, and is refused without `--queue`, `--chunk` or a Slurm mode, where it +did nothing. diff --git a/changelog.d/saved-plane-copies.changed.md b/changelog.d/saved-plane-copies.changed.md deleted file mode 100644 index 402229e28..000000000 --- a/changelog.d/saved-plane-copies.changed.md +++ /dev/null @@ -1 +0,0 @@ -A saved plane makes fewer field-sized copies, with the same stored bits. A field the backend made for the observation alone (the native backend's host copy) is converted to true-power amplitudes where it is, so a modal plane on `native` makes two field-sized arrays where it made three, and a unit-weight one no longer copies the field at all before storing it. A plane observer and a failure checkpoint at a plane that kept no field now share one fetch of it. This partly addresses [#346](https://github.com/LupoLab/solprop/issues/346), as SEP 47's early copy elisions; a large spatial plane on `native` still makes its host copy and its stored copy. diff --git a/changelog.d/scan-command-errors.fixed.md b/changelog.d/scan-command-errors.fixed.md new file mode 100644 index 000000000..ddd0552f7 --- /dev/null +++ b/changelog.d/scan-command-errors.fixed.md @@ -0,0 +1 @@ +`solprop scan` reports a refused or failed scan as one `solprop:` line and exits with status 2, as the other commands do, instead of printing a traceback and exiting with 1. diff --git a/changelog.d/scan-command-help.added.md b/changelog.d/scan-command-help.added.md new file mode 100644 index 000000000..ca462370d --- /dev/null +++ b/changelog.d/scan-command-help.added.md @@ -0,0 +1 @@ +`solprop scan --help` (and `python -m solprop.scan --help`) now explains every option, with its unit and default. diff --git a/changelog.d/scan-print-axes.fixed.md b/changelog.d/scan-print-axes.fixed.md new file mode 100644 index 000000000..434290315 --- /dev/null +++ b/changelog.d/scan-print-axes.fixed.md @@ -0,0 +1,2 @@ +Printing a `Scan`, or showing it as a notebook cell's result, no longer raises for a +string, object or empty axis. diff --git a/changelog.d/selection-energy-loss.breaking.md b/changelog.d/selection-energy-loss.breaking.md new file mode 100644 index 000000000..eaf39c5ee --- /dev/null +++ b/changelog.d/selection-energy-loss.breaking.md @@ -0,0 +1,7 @@ +`MaterialSelection` no longer has an `energy_loss` field, and +`solprop.physdata.selection.ENERGY_LOSS_POLICIES` is gone: its one value, +`"peak-weighted"`, was validated and recorded but never read, since each optmat rate +applies its own convention, which its `ionisation` entry in the material manifest still +records. Drop `energy_loss=` from `MaterialSelection(...)` and from a recipe's +`MaterialSelection` table; the run is unchanged. A run's material manifest no longer +carries a `policies.energy_loss` entry. diff --git a/changelog.d/sep-0045-native-march.changed.md b/changelog.d/sep-0045-native-march.changed.md deleted file mode 100644 index 6bcb8f311..000000000 --- a/changelog.d/sep-0045-native-march.changed.md +++ /dev/null @@ -1 +0,0 @@ -The native backend's Adams march takes the boundary monitor's checks inside its compiled loop: a run whose monitor is busy, as when light lingers near the time window's edge, no longer returns to Python at every step. The monitor's record, its warning and a stop are unchanged, at the same step ([SEP 45](docs/dev/seps/archive/sep-0045-native-rk-march.md)). The split collar's crossing limit sums its bucket occupancies in one sequential order, so that the compiled march reproduces it exactly (Q7); in a near-tie its bucket can move one place, which changes a split-scheme run's steps at rounding level. The native backend also steps the adaptive Runge–Kutta loop of `RungeKutta()` in compiled code, from the stage tables it already holds, taking each trial's stage rows and its error norm natively: a run's metadata says which loop stepped it (`rk_march`), including interpolated planes, replayed schedules, coupled flows, z tables, the transverse edge and a weighted error norm, on CPU and GPU builds; a controller with its own methods runs solprop's loop with a `HostMarchWarning` naming the reason. The norm, weighted or not, now sums in one sequential order in both loops, which moves native Runge–Kutta runs once at rounding level. diff --git a/changelog.d/sep-0046-machine-calibration.added.md b/changelog.d/sep-0046-machine-calibration.added.md index 8ef828685..03d430d17 100644 --- a/changelog.d/sep-0046-machine-calibration.added.md +++ b/changelog.d/sep-0046-machine-calibration.added.md @@ -1 +1 @@ -`solprop calibrate` fits the native backend to the machine it runs on ([SEP 46](docs/dev/seps/archive/sep-0046-machine-calibration.md); [Calibrating solprop to your machine](docs/guide/performance/calibration.md)): in about 30 s (`--quick`), two minutes, or seven minutes (`--thorough`), child processes pinned to the job's CPUs measure how idle threads should wait, how wide the team should be, where each kind of operation should start to thread and which FFTW plan effort runs fastest inside the step, and a setting replaces the built-in value only if it wins every round by more than the measured noise, slows none of the problems (production-sized ones among them) and validates with the other winners. The profile is kept per user in the platform's cache directory (`SOLPROP_CACHE_DIR` moves it; `SOLPROP_CALIBRATION_PATH` adds shared read-only directories, such as a cluster's per node type), keyed by machine, build and allocation, and every later run applies it and records the settings it applied in its metadata (`calibration`). The first native run with no profile for its machine, build and allocation calibrates quickly by itself after a `CalibrationNotice`, and a scan calibrates its workers' allocation first (unless they run one thread each, which has nothing to choose); `SOLPROP_CALIBRATION=use` never measures and `off` ignores profiles. `Simulation.calibrate()` and `solprop calibrate --recipe` refine the settings for one simulation, reused by every run and scan point of the same execution. `--show`, `--export`, `--import` and `--clear` manage profiles. Benchmark series calibrate each build first and record the profile per row. Without a profile, every run uses exactly the former settings, now a built-in table keyed by operating system; `BuildInfo`'s threshold fields report that table for the process. +`solprop calibrate` fits the native backend to the machine it runs on ([SEP 46](https://github.com/LupoLab/solprop/blob/main/docs/dev/seps/archive/sep-0046-machine-calibration.md); [Calibrating solprop to your machine](docs/guide/performance/calibration.md)): in about 30 s (`--quick`), two minutes, or seven minutes (`--thorough`), it measures how the native backend should thread and plan its transforms here, and keeps a setting only where it reliably beats the built-in value. The profile is kept per user in the platform's cache directory (`SOLPROP_CACHE_DIR` moves it; `SOLPROP_CALIBRATION_PATH` adds shared read-only directories, such as a cluster's per node type), keyed by machine, build and allocation, and every later run applies it and records the settings it applied in its metadata (`calibration`). The first native run with no profile for its machine, build and allocation calibrates quickly by itself after a `CalibrationNotice`, and a scan calibrates its workers' allocation first; `SOLPROP_CALIBRATION=use` never measures and `off` ignores profiles. Without a profile (with `SOLPROP_CALIBRATION=use` or `off`, or on a device build), a run uses the built-in table keyed by operating system, which `BuildInfo`'s threshold fields report. `Simulation.calibrate()` and `solprop calibrate --recipe` refine the settings for one simulation, reused by every run and scan point of the same execution, and `--show`, `--export`, `--import` and `--clear` manage profiles. diff --git a/changelog.d/sep-0046-scan-worker-wait.changed.md b/changelog.d/sep-0046-scan-worker-wait.changed.md index 099791373..75a6beb57 100644 --- a/changelog.d/sep-0046-scan-worker-wait.changed.md +++ b/changelog.d/sep-0046-scan-worker-wait.changed.md @@ -1 +1 @@ -A scan's workers ask for passive waiting instead of setting `OMP_WAIT_POLICY=passive` themselves, so that a user's own `OMP_WAIT_POLICY`, `GOMP_SPINCOUNT` or `KMP_BLOCKTIME` now reaches them, and so does a machine calibration's row for the workers' allocation ([SEP 46](docs/dev/seps/archive/sep-0046-machine-calibration.md)); without either they wait as before. Their recorded `openmp_wait_policy` reads `passive`. +A scan's workers ask for passive waiting instead of setting `OMP_WAIT_POLICY=passive` themselves, so that a user's own `OMP_WAIT_POLICY`, `GOMP_SPINCOUNT` or `KMP_BLOCKTIME` now reaches them, and so does a machine calibration's row for the workers' allocation ([SEP 46](https://github.com/LupoLab/solprop/blob/main/docs/dev/seps/archive/sep-0046-machine-calibration.md)); without either they wait as before. Their recorded `openmp_wait_policy` reads `passive`. diff --git a/changelog.d/sep-0047-dense-snapshots.changed.md b/changelog.d/sep-0047-dense-snapshots.changed.md index 9c19fba1d..2b5aeb55f 100644 --- a/changelog.d/sep-0047-dense-snapshots.changed.md +++ b/changelog.d/sep-0047-dense-snapshots.changed.md @@ -1 +1 @@ -Snapshots now work with interpolated planes (`interpolate_planes=True`), which they refused before: a requested snapshot is taken at the end of the step that crossed the plane being saved, once every plane that step crossed has been saved, or at the next accepted endpoint, so its running checkpoint is a state the march passed through, which `resume=True` continues without `resume="interpolated"`, saving each later plane once. The native execution session (SEP 47's prototype, selected by tests and the benchmark harness) now interpolates planes itself, for Adams and the embedded Runge-Kutta tableau alike, where the state lives: no stage or field crosses to the host but the exported plane. Its Runge-Kutta march evaluates the next step's first stage afresh after an observation, as the native bridge does, so the two take the same steps to the bit and their planes differ only at the last bits. A step plane owed by a step that crossed an interpolated plane and ended on the next one is no longer saved twice at that position ([SEP 47](docs/dev/seps/archive/sep-0047-run-ownership.md)). +Snapshots now work with interpolated planes (`interpolate_planes=True`), which they refused before: a requested snapshot is taken at the end of the step that crossed the plane being saved, once every plane that step crossed has been saved, or at the next accepted endpoint, so its running checkpoint is a state the march passed through, which `resume=True` continues without `resume="interpolated"`, saving each later plane once. A step plane owed by a step that crossed an interpolated plane and ended on the next one is no longer saved twice at that position ([SEP 47](https://github.com/LupoLab/solprop/blob/main/docs/dev/seps/archive/sep-0047-run-ownership.md)). diff --git a/changelog.d/sep-0047-descriptor-contract.breaking.md b/changelog.d/sep-0047-descriptor-contract.breaking.md deleted file mode 100644 index 7b15e5e8b..000000000 --- a/changelog.d/sep-0047-descriptor-contract.breaking.md +++ /dev/null @@ -1,20 +0,0 @@ -The backend seam's problem descriptor is now one trajectory's typed description -([SEP 47](docs/dev/seps/archive/sep-0047-run-ownership.md) sections 6.2 and 6.7). -`solprop.translate.problem.KernelProblem` is renamed `PropagationProblem`, with no -alias. The nominal leading batch axis is gone: `PropagationProblem.shape`, -`initial.field0` and `initial.noise0`, `Backend.set_initial`, `Observation.field` and -`noise_phase`, `Backend.stats()`, the periodic rows of `StepStats` and -`ResponseBudgetError.field` are all `(n_modes, n_pol, n_omega)`-shaped with no batch -axis, `Initial.batch_params`, `Flags.single_batch` and `assemble(batch_params=...)` are -removed, `assemble` refuses a stacked field, and `RunEstimate.shape` has three entries. -`solprop.driver.batch.split_observation` and `plane_from_observation(member=...)` are -removed. A march snapshot's stored state keeps its leading axis of one on disk, and -existing files stay readable. The route-specific optional fields `transform`, `flux`, -`transverse`, `tdse` and `current_numerator` move into a closed union, `problem.route`, -from the new module `solprop.translate.routes`: a `ModalRoute`, a `GeneralRoute` or a -`SpatialRoute` of kind radial, Cartesian, planar or line, each with the fields its -executor needs; the TDSE response is the modal route's reference-only `TDSESource`. -`problem.transform` still reads the route's transform, and `tdse_of`, `flux_of` and -`transverse_of` read a route's own leaves. Both backends refuse a route they do not -execute by name before they allocate. The public `Simulation` and `SimulationSettings` -interfaces are unchanged, and every result is bitwise the same. diff --git a/changelog.d/sep-0047-destination-export.changed.md b/changelog.d/sep-0047-destination-export.changed.md index bc27d1bdd..fee316012 100644 --- a/changelog.d/sep-0047-destination-export.changed.md +++ b/changelog.d/sep-0047-destination-export.changed.md @@ -1 +1 @@ -A kept plane's field is exported once, straight into its stored form, with the same stored bits ([#346](https://github.com/LupoLab/solprop/issues/346), SEP 47). `MemoryOutput` hands the run the block row the plane will occupy, so the field is written once, where it is kept, with no host volume of its own; `HDF5Output` is handed one new array, which h5py writes into the plane's chunk without a copy. A plane observer and a failure checkpoint at the same plane share that export. On a 108 MiB Cartesian plane the native session's saved plane no longer allocates a field into memory and one fewer into a file, and the driver session's file output converts its observation where it is instead of allocating a second field. `PlaneStore` gains `takes_exports`, `field_destination` and `save_exported` for this, with `solprop.output.records.StoredField` beside them; a store subclass that overrides `save` is still given every plane, with its field, through it. Export destinations are refused by what is wrong with them (shape, dtype, layout or a read-only array). +A kept plane's field is exported once, straight into its stored form, with the same stored bits ([#346](https://github.com/LupoLab/solprop/issues/346), SEP 47). `MemoryOutput` hands the run the block row the plane will occupy, so the field is written once, where it is kept, with no host volume of its own; `HDF5Output` is handed one new array, which h5py writes into the plane's chunk without a copy. On a 108 MiB Cartesian plane the native backend's saved plane no longer allocates a field into memory and one fewer into a file, and a modal plane on `native` makes two field-sized arrays where it made three. For a custom store, `PlaneStore` gains `takes_exports`, `field_destination` and `save_exported`, with `solprop.output.records.StoredField` beside them; a store subclass that overrides `save` is still given every plane, with its field, through it. diff --git a/changelog.d/sep-0047-host-march-switches.removed.md b/changelog.d/sep-0047-host-march-switches.removed.md index 413fc8e0c..4a6e6af3a 100644 --- a/changelog.d/sep-0047-host-march-switches.removed.md +++ b/changelog.d/sep-0047-host-march-switches.removed.md @@ -1 +1 @@ -The native backend's private host-march switches are retired as production modes ([SEP 47](docs/dev/seps/archive/sep-0047-run-ownership.md) §6.3): the environment variables `SOLPROP_ADAMS_MARCH`, `SOLPROP_RK_MARCH` and `SOLPROP_RK_ROWS` are no longer read, and `NativeBackend` no longer takes an `adams_march` keyword. They selected solprop's Python march on the native engine for A/B comparisons. The test interface that replaced them is retired too, with `benchmarks.adams_host`'s `--host-march` and `--host-stages` arms: every native run is the native execution session's, and the identical-input decision traces and the comparisons with `numpy_ref` in the test suite serve their diagnostic purpose. A problem whose operator or prefactor representation the native stage tables cannot read, which no built-in configuration produces, is now refused by name when the backend is built instead of being stepped with stage rows formed on the host. +The native backend's private host-march switches are retired as production modes ([SEP 47](https://github.com/LupoLab/solprop/blob/main/docs/dev/seps/archive/sep-0047-run-ownership.md) §6.3): the environment variable `SOLPROP_ADAMS_MARCH` is no longer read, and `NativeBackend` no longer takes an `adams_march` keyword. They selected solprop's Python march on the native engine for A/B comparisons; every native run now steps in the native session. A problem whose operator or prefactor representation the native stage tables cannot read, which no built-in configuration produces, is now refused by name when the backend is built instead of being stepped with stage rows formed on the host. diff --git a/changelog.d/sep-0047-host-stepping.breaking.md b/changelog.d/sep-0047-host-stepping.breaking.md deleted file mode 100644 index d1e6f91ee..000000000 --- a/changelog.d/sep-0047-host-stepping.breaking.md +++ /dev/null @@ -1,9 +0,0 @@ -The `Backend` protocol (`solprop.backends.protocol`) no longer declares the stepping -members a run drives through a session: `set_initial`, `set_progress`, `set_stop`, -`attach_monitor`, `propagate_to`, `observe`, `in_flight`, `stats`, -`restore_call_ledgers`, `march_snapshot`, `march_snapshot_nbytes` and `restore_march` move -to the new `HostStepping` protocol, which the NumPy reference implements and the native -backend does not ([SEP 47](docs/dev/seps/archive/sep-0047-run-ownership.md) section 6.8). Code that -steps a `numpy_ref` backend directly narrows the backend `select` returns with -`solprop.backends.protocol.stepping(backend)`; every backend runs through -`backend.prepare(problem, request).start(start)`. diff --git a/changelog.d/sep-0047-native-low-storage-direct.breaking.md b/changelog.d/sep-0047-native-low-storage-direct.breaking.md deleted file mode 100644 index 50616f5a9..000000000 --- a/changelog.d/sep-0047-native-low-storage-direct.breaking.md +++ /dev/null @@ -1,8 +0,0 @@ -The native backend no longer steps the low-storage march (SEP 24) through its legacy -direct API: `propagate_to` on a native low-storage run raises a `BackendError` that names -the session, which replays the march natively -([SEP 47](docs/dev/seps/archive/sep-0047-run-ownership.md) section 6.8). Start such a run with -`backend.prepare(problem, request).start(start)` or -`solprop.backends.sessions.start_session`, as `Simulation.run` already does. A native -timing probe's low-storage steps are now counted in the backend's `source_evaluations`, -four a step, where they counted none. diff --git a/changelog.d/sep-0047-native-low-storage.changed.md b/changelog.d/sep-0047-native-low-storage.changed.md deleted file mode 100644 index 0cfa91117..000000000 --- a/changelog.d/sep-0047-native-low-storage.changed.md +++ /dev/null @@ -1 +0,0 @@ -The native execution session (SEP 47's prototype, selected by tests and the benchmark harness) now runs the low-storage replay (`LowStorageRungeKutta`) itself: each step is one in-place native step whose stage scalars the native state forms from its tables, so the replay no longer returns to Python once a step, with the same steps, statistics rows and fields as before. A failure partway through a step ends the session poisoned, with no checkpoint of its own, and the run's service loop records it against the latest running checkpoint ([SEP 47](docs/dev/seps/archive/sep-0047-run-ownership.md)). diff --git a/changelog.d/sep-0047-native-monitor.changed.md b/changelog.d/sep-0047-native-monitor.changed.md deleted file mode 100644 index e386e08c7..000000000 --- a/changelog.d/sep-0047-native-monitor.changed.md +++ /dev/null @@ -1 +0,0 @@ -The native execution session (SEP 47's prototype, selected by tests and the benchmark harness) now runs a run's temporal boundary monitor itself: its launch judgement, cadence, quiet collar, split-collar cap, warnings, stops, plane rows, finish and resumed record are native, with the same decisions and record as solprop's monitor. A boundary warning reaches the caller as a `ServiceRequired` warning barrier, which the run's service loop emits; under warning filters that raise it, the run fails at that endpoint with its field available for the checkpoint ([SEP 47](docs/dev/seps/archive/sep-0047-run-ownership.md)). A free-space run's transverse edge now runs on the native session too, no longer refused: its launch judgement, read spacing, reads, a requested collar's current and return, warnings, stops, record and resumed record are native, with the same decisions and record as solprop's edge on the same readings, and a point that raises several warnings serves each as its own barrier. The safety ramp's share in its band at the launch and its removal over each read interval are summed natively in another order, within a rounding bound of solprop's values that accumulates across reads, so their warnings and stops may differ from solprop's for a share within that bound of a threshold. diff --git a/changelog.d/sep-0047-native-session-device.changed.md b/changelog.d/sep-0047-native-session-device.changed.md index 430cded29..50d3d00bb 100644 --- a/changelog.d/sep-0047-native-session-device.changed.md +++ b/changelog.d/sep-0047-native-session-device.changed.md @@ -1 +1,8 @@ -On a GPU build (CUDA or HIP) of the native backend, runs are now admitted to the native execution session as on a CPU build ([SEP 47](docs/dev/seps/archive/sep-0047-run-ownership.md)): Adams and the embedded Runge-Kutta tableaux, adaptive or replayed, the low-storage replay, dense output (`interpolate_planes`), the modal, general and spatial routes (radial, Cartesian, line and planar, with their statistics and fluence widths), saved planes, periodic statistics rows, step planes, the temporal boundary monitor and a free-space run's transverse edge with a requested collar's current, the input and modified noise models and resumed Adams history. A coupled flow wider than 16 channels or with bins off its eigenbasis route to the native Adams march, rather than solprop's Python march with a `HostMarchWarning`, so its fields differ from before at the rounding level; a bin off the route takes its matrix functions from the scaled Taylor series and squaring of the augmented exponential, and a step whose exponent there would need more than 30 squarings is refused by name, as on a CPU build. These have been run on an NVIDIA A40 (CUDA), where the session takes the same steps, statistics and fields as the backend's own march on the same device (dense Runge-Kutta planes and the transverse edge's ramp sums within rounding bounds); HIP and data-centre NVIDIA evidence is to follow, and they are not yet qualified on either vendor. A saved plane's field crosses from the device once, into its destination, with no extra host copy. +On a GPU build (CUDA or HIP) of the native backend, runs take the compiled session of a +CPU build, with its coverage and its refusals +([SEP 47](https://github.com/LupoLab/solprop/blob/main/docs/dev/seps/archive/sep-0047-run-ownership.md)), +and device builds also refuse the Adams carrier frame by name. On an NVIDIA A40 (CUDA) +the session takes the same steps, statistics and fields as the backend's previous march +on the same device (dense Runge–Kutta planes and the transverse edge's ramp sums within +rounding bounds); device builds are not yet qualified on either vendor. A saved plane's +field crosses from the device once, into its destination, with no extra host copy. diff --git a/changelog.d/sep-0047-native-session-production.changed.md b/changelog.d/sep-0047-native-session-production.changed.md index cba910301..bb863662e 100644 --- a/changelog.d/sep-0047-native-session-production.changed.md +++ b/changelog.d/sep-0047-native-session-production.changed.md @@ -1 +1,17 @@ -Runs on the native backend's CPU build now go through the native execution session ([SEP 47](docs/dev/seps/archive/sep-0047-run-ownership.md)), the only native executor once the transitional driver session it replaced was removed, with the same steps, fields, statistics, step records and call ledgers as before. The session also runs resumed runs, carrying the Adams history and the call ledgers, the input and modified noise models (also on a propagator stored as a z table, and the input noise beside a free-space run's transverse edge), the boundary monitor (including a free-space run's transverse edge), dense output and the low-storage replay, and it exports the Adams history beside each saved plane and checkpoint. A signal during a run is still handled once the native call returns, within 256 attempts or 0.1 s; the run's checkpoint then includes every attempt made. Comparison methods, controllers that override `PIController`'s methods and TDSE responses are refused by name on native (see the reference-only entries). The four on-axis plasma statistics (`on_axis_electron_density`, `on_axis_peak_ionisation_rate` and their species forms) no longer send a run to the backend's own march: the session scans the axis row natively, agreeing with the earlier host scan to the node scans' parity tolerance (1e-10 relative). A spatial run's `beam_radius` and `fwhm_r` are now finished natively, so the default statistics of a radial or free-space run no longer leave the native session, and so is `zdw`, read from a table of each mode's zero-dispersion wavelength along z made once before the run (exact for a mode that does not vary along z, otherwise within 1e-6 of the wavelength, with the measured error in the run's execution record under `statistics_tables`); the native backend records `nan` where the band holds no zero, as `numpy_ref` does, instead of raising. The native backend refuses by name the metric statistics of a general modal basis whose metric varies inside one of its intervals. Statistics a problem does not carry are refused by name before the run starts, on every backend, instead of at the first saved plane: a modal statistic such as `omega0` on a spatial run, a spatial statistic such as `beam_radius` or `absorbed_power` on a modal run (where `numpy_ref` used to return the peak ionisation rate as `absorbed_power`), the plasma integration diagnostics without a field-grid plasma column, and the electron density or peak ionisation rate without a plasma response. On a CPU build, a coupled flow wider than 16 channels or with bins off its eigenbasis route now runs on the native Adams march in the session rather than on solprop's Python march: a bin off the route takes its matrix functions from the scaled Taylor series and squaring of the augmented exponential rather than SciPy's `expm`, a difference at the rounding level, and a step whose exponent there would need more than 30 squarings is refused by name. +The native backend runs every run it admits in its own compiled session, with no Python +step loop +([SEP 45](https://github.com/LupoLab/solprop/blob/main/docs/dev/seps/archive/sep-0045-native-rk-march.md), +[SEP 47](https://github.com/LupoLab/solprop/blob/main/docs/dev/seps/archive/sep-0047-run-ownership.md)). +Beside the Adams march it already had, it now steps the adaptive Runge–Kutta loop of +`RungeKutta()` and the low-storage replay (`LowStorageRungeKutta`) natively, and the +session also runs resumed runs, the noise models, dense output (`interpolate_planes`), +the temporal boundary monitor, a free-space run's transverse edge, the Adams carrier +frame on an operator stored as a z table (#255), and coupled flows wider than 16 +channels or with bins off their eigenbasis route, which 0.2.0 stepped with solprop's +Python march; such a flow's step whose exponent would need more than 30 squarings is +refused by name. A run's backend metadata says which loop stepped it (`adams_march`, +`rk_march`). Some results move at the rounding level, because +the Runge–Kutta error norm, the split collar's crossing limit and the transverse edge's +safety-ramp shares are summed in another order: in a near-tie a split-scheme run's +collar bucket can move one place, and an edge warning or stop may differ from +`numpy_ref`'s for a share within a rounding bound of its threshold. diff --git a/changelog.d/sep-0047-reporter-cadence.changed.md b/changelog.d/sep-0047-reporter-cadence.changed.md index d3681ad0c..db9104522 100644 --- a/changelog.d/sep-0047-reporter-cadence.changed.md +++ b/changelog.d/sep-0047-reporter-cadence.changed.md @@ -1 +1 @@ -A progress reporter now hears a run's attempted steps in batches, as the run's session delivers them: once per save plane, and at least every 256 attempts or 0.1 s in between. It no longer hears each step as it is taken ([SEP 47](docs/dev/seps/archive/sep-0047-run-ownership.md) section 5.3). Each attempt is still reported once and in order. As a result, a stop flag that a reporter sets lands up to one batch later, at most 256 attempts or 0.1 s, on every backend, the NumPy reference included. A flag set from outside the run is still polled between batches, as before. +A progress reporter now hears a run's attempted steps in batches, as the run's session delivers them: once per save plane, and at least every 256 attempts or 0.1 s in between. It no longer hears each step as it is taken ([SEP 47](https://github.com/LupoLab/solprop/blob/main/docs/dev/seps/archive/sep-0047-run-ownership.md) section 5.3). Each attempt is still reported once and in order. As a result, a stop flag that a reporter sets lands up to one batch later, at most 256 attempts or 0.1 s, on every backend, the NumPy reference included. A flag set from outside the run is still polled between batches, as before. diff --git a/changelog.d/sep-0047-restart-record.changed.md b/changelog.d/sep-0047-restart-record.changed.md index 24c418e78..f7dc87a42 100644 --- a/changelog.d/sep-0047-restart-record.changed.md +++ b/changelog.d/sep-0047-restart-record.changed.md @@ -1 +1 @@ -Each execution record now states what a restart keeps and restores, under `outcome.execution["restart"]`: whether a plane's or checkpoint's method history was `retained`, `omitted` or is `not_applicable`, with a reason (`explicit_policy`, `automatic_policy`, `automatic_size_limit`, `snapshot_required`, `unavailable_history`, `output_cannot_store`, `write_failed`, `incompatible_representation`, `unsupported_method`, `no_method_history`), and in a resumed execution what it `restored`, `reset` (a Runge–Kutta resume's proposal and norm memory, an Adams history set aside) or found `not_applicable` (low-storage), and that the boundary monitor was reconstructed from its persisted records. A resume now warns once (`SolpropWarning`) when an Adams history it expected was omitted by the automatic 256 MiB limit, was not exportable, or cannot be read back (including a write cut short); `resume_history=False` is recorded without a warning. Files written before the record read as unknown, and resume as before ([SEP 47](docs/dev/seps/archive/sep-0047-run-ownership.md)). +Each execution record now states what a restart keeps and restores, under `outcome.execution["restart"]`: whether a plane's or checkpoint's method history was `retained`, `omitted` or is `not_applicable`, with a reason (`explicit_policy`, `automatic_policy`, `automatic_size_limit`, `snapshot_required`, `unavailable_history`, `output_cannot_store`, `write_failed`, `incompatible_representation`, `unsupported_method`, `no_method_history`), and in a resumed execution what it `restored`, `reset` (a Runge–Kutta resume's proposal and norm memory, an Adams history set aside) or found `not_applicable` (low-storage), and that the boundary monitor was reconstructed from its persisted records. A resume now warns once (`SolpropWarning`) when an Adams history it expected was omitted by the automatic 256 MiB limit, was not exportable, or cannot be read back (including a write cut short); `resume_history=False` is recorded without a warning ([SEP 47](https://github.com/LupoLab/solprop/blob/main/docs/dev/seps/archive/sep-0047-run-ownership.md)). diff --git a/changelog.d/sep-0047-retire-mlx.breaking.md b/changelog.d/sep-0047-retire-mlx.breaking.md new file mode 100644 index 000000000..bd35a5b25 --- /dev/null +++ b/changelog.d/sep-0047-retire-mlx.breaking.md @@ -0,0 +1 @@ +The experimental `mlx` backend for Apple GPUs is retired ([SEP 47](https://github.com/LupoLab/solprop/blob/main/docs/dev/seps/archive/sep-0047-run-ownership.md) §6.6): `backend="mlx"`, in a call or a recipe, raises `BackendError` and never runs on another backend. The `solprop[mlx]` extra, the front end's MLX choice and the `metal` entry of the kernel's run options are gone; the front end shows a recipe's unavailable backend as it is named. With MLX's transform costs gone, the `transforms` keyword of `FieldGrid.from_limits` and `EnvelopeGrid.from_limits` (a recipe grid that gives it is refused as an unknown key), the `library` argument of `solprop.grid.fft_cost`, `solprop.grid.TransformLibrary` and `TRANSFORM_LIBRARIES`, `solprop.backends.registry.metal_available` and `SINGLE_ONLY`, and the `mlx_*` and `single_precision_rows` sizes of `solprop.backends.memory` are removed. diff --git a/changelog.d/sep-0047-retire-mlx.removed.md b/changelog.d/sep-0047-retire-mlx.removed.md deleted file mode 100644 index ddfa868fd..000000000 --- a/changelog.d/sep-0047-retire-mlx.removed.md +++ /dev/null @@ -1 +0,0 @@ -The experimental `mlx` backend for Apple GPUs is retired ([SEP 47](docs/dev/seps/archive/sep-0047-run-ownership.md) §6.6): `backend="mlx"`, in a call or a recipe, raises `BackendError` and never runs on another backend. The `solprop[mlx]` extra, the front end's MLX choice and the `metal` entry of the kernel's run options are gone; the front end shows a recipe's unavailable backend as it is named. With MLX's transform costs gone, the `transforms` keyword of `FieldGrid.from_limits` and `EnvelopeGrid.from_limits` (a recipe grid that gives it is refused as an unknown key), the `library` argument of `solprop.grid.fft_cost`, `solprop.grid.TransformLibrary` and `TRANSFORM_LIBRARIES`, `solprop.backends.registry.metal_available` and `SINGLE_ONLY`, and the `mlx_*` and `single_precision_rows` sizes of `solprop.backends.memory` are removed. diff --git a/changelog.d/sep-0047-run-request.breaking.md b/changelog.d/sep-0047-run-request.breaking.md deleted file mode 100644 index b928e3733..000000000 --- a/changelog.d/sep-0047-run-request.breaking.md +++ /dev/null @@ -1,32 +0,0 @@ -The run's policy has left the backend seam's problem descriptor -([SEP 47](docs/dev/seps/archive/sep-0047-run-ownership.md) sections 5.2 and 6.2). -`PropagationProblem` no longer has `stepper` or `stats_spec`: the tableau, controller, -step limits, schedule, save planes and statistics travel in the immutable -`solprop.translate.run_request.RunRequest`. `solprop.translate.problem.assemble` returns -a `Translation(problem, request)` pair (`problem, request = assemble(...)`), whose -request has the route's step limits resolved, and `RunRequest.stepper` reads the stepper -settings as one `StepperSettings` record. Backends receive the request where they are -built: `solprop.backends.registry.select(name, problem, request, ...)` and the backend -constructors take it after the problem, check the pair with the new -`solprop.translate.problem.validate_run(problem, request)` before they allocate, and -expose it as `Backend.request`. A run starts through the backend's preparation: -`Backend.prepare(problem, request)` returns a `PreparedExecution` whose `start(...)` -opens the backend's own session, the reference's `HostSession`, the native backend's -`NativeSession` where it admits the run and the transitional session otherwise, and -`solprop.backends.sessions.start_session` only starts it; a preparation refuses a -request that is not one run of the backend's own (`RunRequest.for_run` of it). A -`solprop.backends.registry.BackendEntry` row now names its backend's constructor -(`factory`) and policies by import path, so a backend registers with one row. -`PropagationProblem.validate()` now checks what the problem -promises alone; `validate_run` adds the checks that read the run's policy, with the same -refusals and messages, and `validate_launch(request)` takes the request. -`describe_run` now takes a `StepperSettings`; `RunRequest.for_run(...)` gives one run's -start, retention, monitor, history and snapshot policy, and `RunRequest.with_stepper(...)` -replaces the stepper section. `metadata_for(problem, request, grid, ...)`, -`field_retention(request, ...)`, `check_snapshot_request(request, ...)`, -`run_summary(problem, request, metadata, ...)` and -`check_derived_problem(constructed, derived, constructed_request, derived_request)` take -the request; `run_problem` reads it from the backend. The public `Simulation` and -`SimulationSettings` interfaces are unchanged, configuration hashes and resume identity -are unchanged (a file written before this change resumes), and every result is bitwise -the same. diff --git a/changelog.d/sep-0047-running-checkpoints.changed.md b/changelog.d/sep-0047-running-checkpoints.changed.md index cd97ef974..35c666e57 100644 --- a/changelog.d/sep-0047-running-checkpoints.changed.md +++ b/changelog.d/sep-0047-running-checkpoints.changed.md @@ -1 +1 @@ -Snapshots no longer require `step_planes=1`: a requested snapshot is taken at the next accepted endpoint, and where no plane is saved there the run writes a running checkpoint, in the existing terminal-checkpoint record with a matching `running` outcome, from which the snapshot and `resume=True` continue. The attempts and periodic rows since the last plane stay with that plane, once, and a later saved plane supersedes the checkpoint. A low-storage step abandoned in flight now falls back to the latest running checkpoint, or to the checkpoint the run resumed from, rather than to the last saved plane ([SEP 47](docs/dev/seps/archive/sep-0047-run-ownership.md)). +Snapshots no longer require `step_planes=1`: a requested snapshot is taken at the next accepted endpoint, and where no plane is saved there the run writes a running checkpoint, in the existing terminal-checkpoint record with a matching `running` outcome, from which the snapshot and `resume=True` continue. The attempts and periodic rows since the last plane stay with that plane, once, and a later saved plane supersedes the checkpoint. A low-storage step abandoned in flight now falls back to the latest running checkpoint, or to the checkpoint the run resumed from, rather than to the last saved plane ([SEP 47](https://github.com/LupoLab/solprop/blob/main/docs/dev/seps/archive/sep-0047-run-ownership.md)). diff --git a/changelog.d/sep-0047-start-and-group.breaking.md b/changelog.d/sep-0047-start-and-group.breaking.md deleted file mode 100644 index 7285616e2..000000000 --- a/changelog.d/sep-0047-start-and-group.breaking.md +++ /dev/null @@ -1,10 +0,0 @@ -A run now starts from an explicit start rather than from a backend its caller loaded -([SEP 47](docs/dev/seps/archive/sep-0047-run-ownership.md) section 5.2): -`solprop.driver.run.run_problem` takes a required `start=`, a -`solprop.backends.session.Start` (`Start.entrance(problem)` for a fresh run), and loads -it into the backend through the run's session; its `start_plane=` argument is removed, -the start's `plane_index` taking its place. A caller no longer calls -`backend.set_initial` before `run_problem`. `Simulation.run`, `SimulationRunner`, scans -and the benchmark suite start their runs this way, and a resumed run's call ledgers -and Adams history travel in the start, a history the backend cannot install being -warned about and recorded as reset as before. diff --git a/changelog.d/sep-0047-step-driver-removed.removed.md b/changelog.d/sep-0047-step-driver-removed.removed.md deleted file mode 100644 index 6fa2d9f65..000000000 --- a/changelog.d/sep-0047-step-driver-removed.removed.md +++ /dev/null @@ -1,9 +0,0 @@ -The legacy step driver `solprop.backends.driver` (`StepDriver`), the Adams march class -`solprop.backends.multistep.AdamsMarch` and `solprop.backends.low_storage.LowStorageMarch` -are removed ([SEP 47](docs/dev/seps/archive/sep-0047-run-ownership.md) section 6.8): the native -backend runs every run in its native session and inherits no Python step loop, and the -NumPy reference marches with its own `solprop.backends.host` classes. `reached` and -`replay_tolerance` are now in `solprop.stepper.schedule`. A native backend's direct stepping members -(`set_initial`, `propagate_to`, `observe`, `stats`, `attach_monitor` and the rest) are -gone with them: start a run with `backend.prepare(problem, request).start(start)` or -`solprop.backends.sessions.start_session`. diff --git a/changelog.d/sep-0047-timing-probe.breaking.md b/changelog.d/sep-0047-timing-probe.breaking.md deleted file mode 100644 index d977ac325..000000000 --- a/changelog.d/sep-0047-timing-probe.breaking.md +++ /dev/null @@ -1,9 +0,0 @@ -The backend seam's `timed_step()` is replaced by an explicit timing probe -([SEP 47](docs/dev/seps/archive/sep-0047-run-ownership.md) section 6.6): -`Backend.timing_probe(start)` loads a `solprop.backends.session.Start` and returns a -`solprop.backends.protocol.TimingProbe`, whose `trial(z, dz)` takes one trial step that -commits nothing and whose `field()` reads that trial's end state back on the host. -`Simulation.estimate` and the SEP 46 calibration time and compare trials through it, -instead of loading the backend themselves and reaching private driver members; the -calibration's plan comparison on the native backend now compares the trial fields, -where it read the unchanged launch field before. diff --git a/changelog.d/sep-0051-save-planes-front-end.breaking.md b/changelog.d/sep-0051-save-planes-front-end.breaking.md new file mode 100644 index 000000000..0412cf51c --- /dev/null +++ b/changelog.d/sep-0051-save-planes-front-end.breaking.md @@ -0,0 +1,6 @@ +In the desktop front end, every sheet's *Saved planes* row offers *Evenly spaced* +(`n_save`) and *Explicit positions* (`save_planes`), and typing into one form removes +the other in the same undoable edit. A setup opens on the form it holds; the object +sheets no longer turn a count into a list of positions, nor rewrite the positions when +the length changes. An object-sheet count of 80 planes, which left out the entrance, is +`n_save = 81`. diff --git a/changelog.d/sep-0051-save-planes.breaking.md b/changelog.d/sep-0051-save-planes.breaking.md new file mode 100644 index 000000000..2e6668ad1 --- /dev/null +++ b/changelog.d/sep-0051-save-planes.breaking.md @@ -0,0 +1,20 @@ +Every route now follows one rule for the saved planes and the end of a run +([SEP 51](https://github.com/LupoLab/solprop/blob/main/docs/dev/seps/archive/sep-0051-save-planes.md)). +A run marches from `initial_z` to its length, `length` or `grid.length`, and always +records both ends. `n_save=N` gives `N` evenly spaced observations over that interval, +both ends included, and `save_planes=[...]` lists positions inside it. +`SimulationSettings` gains `n_save`, its `save_planes` becomes optional (given neither, +a run records 201), and a recipe's object-route `[build.settings]` takes `n_save` too. +Migration: `save_planes=80` is refused with "pass `n_save=80`" in Python and "write +`n_save = 80`" in a recipe, where 0.2.0 read a recipe's `save_planes = 80` as one plane +at 80 m (#533); `save_planes=0.25` must be `[0.25]`; `n_save` and `save_planes` +together, `n_save` below 2, and positions before the entrance or beyond the end are +refused. Positions short of the length no longer end the run: it continues to the length +and records it, so indices counted from the end (`field_planes=[-1, …]`) may name other +planes, and a short window of a longer setup is now a shorter grid, with +`boundary_length` pinned to keep the absorber. On the keyword routes `length` may be +`None` beside `grid=`, which then supplies it, as in +`prop_capillary(radius, None, "Ar", grid=grid, ...)`; it is still passed, so `gas` stays +required. Given beside `grid=`, the two must agree, and a call with neither is refused; +a recipe may leave `length` out beside a grid. `n_save` beside an interior launch counts +over `[initial_z, length]`. diff --git a/changelog.d/sep-0051-save-planes.changed.md b/changelog.d/sep-0051-save-planes.changed.md deleted file mode 100644 index 8ab3b3a7d..000000000 --- a/changelog.d/sep-0051-save-planes.changed.md +++ /dev/null @@ -1,28 +0,0 @@ -Every route now follows one rule for the saved planes and the end of a run -([SEP 51](docs/dev/seps/archive/sep-0051-save-planes.md)). A run marches from `initial_z` to its -length, `length` or `grid.length`, and always records both ends. `n_save=N` gives `N` -evenly spaced observations over that interval, both ends included, and -`save_planes=[...]` lists positions inside it. `SimulationSettings` gains `n_save`, its -`save_planes` becomes optional (given neither, a run records 201), and a recipe's -object-route `[build.settings]` takes `n_save` too. Migration: -`save_planes=80` is refused with "pass `n_save=80`" in Python and "write `n_save = 80`" -in a recipe; `save_planes=0.25` must be `[0.25]`; `n_save` and `save_planes` together, -`n_save` below 2, and positions before the entrance or beyond the end are refused; a -position within eight ulps of an endpoint is that endpoint. Positions short of the length -no longer end the run: it continues to the length and records it, so indices counted -from the end (`field_planes=[-1, …]`) may name other planes, and a short window of a -longer setup is now a shorter grid, with `boundary_length` pinned to keep the absorber. -On the keyword routes `length` may be `None` beside `grid=`, which then supplies it, as -in `prop_capillary(radius, None, "Ar", grid=grid, ...)`; it is still passed, so `gas` -stays required. Given beside `grid=`, the two must agree, and a call with neither is -refused; a recipe may leave `length` out beside a grid. `n_save` beside an interior -launch counts over -`[initial_z, length]`. A replayed `FixedSchedule` must start at the entrance and end at -the length, within the rounding its step sum accumulates, or it is refused before the -run. The resolved recipe writes the run's positions in `[build.settings]` on an object -route and drops `n_save`. -In the front end, every sheet's *Saved planes* row offers *Evenly spaced* (`n_save`) and -*Explicit positions* (`save_planes`), and typing into one form removes the other in the -same undoable edit. A setup opens on the form it holds; the object sheets no longer turn -a count into a list of positions, nor rewrite the positions when the length changes. An -object-sheet count of 80 planes, which left out the entrance, is `n_save = 81`. diff --git a/changelog.d/sep-0052-batch-executor.breaking.md b/changelog.d/sep-0052-batch-executor.breaking.md new file mode 100644 index 000000000..cccb705e4 --- /dev/null +++ b/changelog.d/sep-0052-batch-executor.breaking.md @@ -0,0 +1,10 @@ +The `Batch` scan executor is removed, with the batch machinery behind it on both +backends (SEP 52): on the native backend it cost `size` times the memory of `Local` for +no gain in speed. A script that imports `Batch` now fails at import: use `Local()` to +run the points one after another on one reused backend, or `Pool()` to run them in +parallel worker processes; `Queue` and `Slurm` spread them over controllers and cluster +jobs. Every executor still replays a fixed schedule. Also removed: +`solprop.driver.batch`, `solprop.backends.batch`, +`solprop.backends.registry.select_batch`, `solprop.backends.BatchBackend`, +`Backend.max_batch`, `StatsSpec.same_tables`, the reference's `NumpyBatchBackend` and +`solprop_native.batch` (`NativeBatchBackend`). diff --git a/changelog.d/sep-0052-batch-executor.removed.md b/changelog.d/sep-0052-batch-executor.removed.md deleted file mode 100644 index 7f030d99e..000000000 --- a/changelog.d/sep-0052-batch-executor.removed.md +++ /dev/null @@ -1,14 +0,0 @@ -The `Batch` scan executor is removed, with the group machinery behind it on both backends -(SEP 52). On the native backend a `Batch` group built a complete backend for every member -and ran one session each, so it cost `size` times the memory of `Local` for no gain in -speed; on `numpy_ref` it fused only the Runge-Kutta stage sums. A script that imports -`Batch` now fails at import: use `Local()` to run the points one after another on one -reused backend, or `Pool()` to run them in parallel worker processes (as many workers as -`Batch` had members hold about what it did, and run their points concurrently); `Queue` -and `Slurm` spread them over controllers and cluster jobs. Every executor still replays a -fixed schedule. Also removed: `solprop.driver.batch`, -`solprop.backends.registry.select_batch`, `solprop.backends.BatchBackend`, -`Backend.max_batch`, `Backend.prepare_group`, the `GroupSession` and `PreparedGroup` -protocols, `check_group`, `start_group`, `solprop.backends.events.GroupBatch`, -`ExportTicket.member`, `StatsSpec.same_tables`, the reference's `HostGroup` and -`NumpyBatchBackend`, `solprop_native.group`, and the benchmark suite's `group_batch` case. diff --git a/changelog.d/sep-0052-native-seam-phase-0.changed.md b/changelog.d/sep-0052-native-seam-phase-0.changed.md deleted file mode 100644 index c57a7bad6..000000000 --- a/changelog.d/sep-0052-native-seam-phase-0.changed.md +++ /dev/null @@ -1 +0,0 @@ -solprop-native's source build pins nanobind 3.1.0 (it took any release from 2.9 on), and the private extension's test-only entry points moved to its `_testing` submodule, which the wheel ships for solprop's own tests (SEP 52). diff --git a/changelog.d/sep-0052-native-workspace.changed.md b/changelog.d/sep-0052-native-workspace.changed.md deleted file mode 100644 index 3ffe3eda1..000000000 --- a/changelog.d/sep-0052-native-workspace.changed.md +++ /dev/null @@ -1 +0,0 @@ -solprop-native's private extension takes one workspace per backend, built from one problem record that carries every set-once table, and starts each run from one run record and each timing probe from the run's start (SEP 52): the per-call configuration of the old native state is gone, records cross by field table and are refused by field path, and both stubs of the extension are generated. A backend whose low-storage timing probe advanced its registers now refuses a further run or probe by name instead of running from the discarded registers. diff --git a/changelog.d/sep-0052-run-records.changed.md b/changelog.d/sep-0052-run-records.changed.md deleted file mode 100644 index 4b973164e..000000000 --- a/changelog.d/sep-0052-run-records.changed.md +++ /dev/null @@ -1 +0,0 @@ -Both backends read each run's records -- the method's policy, the low-storage settings, the schedule, the plane plan and the boundary monitor's configuration and continuation -- formed once by the new `solprop.backends.records` (SEP 52). `RungeKuttaPolicy` moves there from `solprop.backends.rk_core` and carries the march's landings; `rk_policy` becomes `records.runge_kutta_policy`. The engine protocols the marches are to call are declared in the new `solprop.backends.engines`. diff --git a/changelog.d/sep-0052-snapshot-layout.breaking.md b/changelog.d/sep-0052-snapshot-layout.breaking.md deleted file mode 100644 index c0f7650af..000000000 --- a/changelog.d/sep-0052-snapshot-layout.breaking.md +++ /dev/null @@ -1,6 +0,0 @@ -The output schema is 3 (SEP 52): a file's march snapshot (`/march_snapshot`) now stores -its `state` as `(n_modes, n_pol, n_omega)` and its engine `rows` as `(n_slots, n_modes, -n_pol, n_omega)`, without the leading axis of one they kept before. A file of output -schema 2, which 0.2.0 wrote, is refused as any file of another schema is: resume or continue it with -the solprop version that wrote it. Saved fields, statistics and the run record are -otherwise unchanged. diff --git a/changelog.d/sep-0052-unit-axis.changed.md b/changelog.d/sep-0052-unit-axis.changed.md deleted file mode 100644 index 0f88e5e4c..000000000 --- a/changelog.d/sep-0052-unit-axis.changed.md +++ /dev/null @@ -1,9 +0,0 @@ -The arrays of one trajectory carry no leading axis of one anywhere (SEP 52): the -`PropagationProblem` operator's value tables (`LinearOperator.phi_coefficients` is -`(n_intervals, n_deg, n_modes, n_pol, n_omega)`, `phi_constant` and an expansion's -`terms` lose the same axis), the stage terms (`StageTerms.phi`), the separable operator's -`value_shape`, the boundary monitor's and the split collar's readings -(`BoundaryMonitor.power`, `SplitCrossing.occupancy`), the design check's launch, the -carrier frame's chord (a scalar per position) and both backends' private state. No field -is added or removed and no value changes; code that indexed `[0]` into these arrays drops -the index. diff --git a/changelog.d/sep47-backend-node-chunk.breaking.md b/changelog.d/sep47-backend-node-chunk.breaking.md index cdf61976f..31109bd79 100644 --- a/changelog.d/sep47-backend-node-chunk.breaking.md +++ b/changelog.d/sep47-backend-node-chunk.breaking.md @@ -1 +1 @@ -The node chunk is the backend's execution choice, planned when the backend is prepared, not part of the translated problem (SEP 47, #361): `Transform.node_chunk` is gone, and `assemble`, `multimode_transform`, `free_transform`, `planar_transform` and `radial_transform` no longer take `node_budget` (`free_transform` no longer takes the time grid, nor `radial_transform` `n_pol`). `SimulationSettings.node_budget` keeps its meaning and its chunks, is now an execution setting that may change after translation and stays outside the resume key, and reaches the backend through `ExecutionOptions(node_budget=...)` (`select(..., options=...)` or the backend's `options=`); an explicit budget is authoritative. `from_capillary`, `from_waveguide`, `prop_capillary` and `prop_waveguide` now default `node_budget` to `None`, the backend's choice (the same 64 MiB on these modal routes), so a later device default can apply to them; the general-guide refusal of `node_budget` now refuses any value other than `None`. A budget may be any integral value, a NumPy integer included, and one that is not a positive integer is refused when the settings are made (`DriverError`); a budget too small for one node is refused by the backend with a `BackendError`, no longer by the translation. The default budgets and the rule are in `solprop.backends.node_chunk` (`DEFAULT_NODE_BUDGET`, `DEFAULT_SPATIAL_NODE_BUDGET`, `plan_node_chunk`), and every run records its `node_chunk`, `node_budget` and `node_chunk_source` (`"default"`, `"explicit"` or `"forced"`) in its backend metadata. +The node chunk is the backend's execution choice, planned when the backend is prepared, not part of the translated problem (SEP 47, #361): `Transform.node_chunk` is gone, and `assemble`, `multimode_transform`, `free_transform`, `planar_transform` and `radial_transform` no longer take `node_budget` (`free_transform` no longer takes the time grid, nor `radial_transform` `n_pol`). `SimulationSettings.node_budget` keeps its meaning and its chunks, may change after translation, stays outside the resume key and reaches the backend through `ExecutionOptions(node_budget=...)` (`select(..., options=...)` or the backend's `options=`); an explicit budget is authoritative. `from_capillary`, `from_waveguide`, `prop_capillary` and `prop_waveguide` now default `node_budget` to `None`, the backend's choice (the same 64 MiB on a CPU build), and the general-guide refusal of `node_budget` now refuses any value other than `None`. The default budgets and the rule are in `solprop.backends.node_chunk` (`DEFAULT_NODE_BUDGET`, `DEFAULT_SPATIAL_NODE_BUDGET`, `plan_node_chunk`). diff --git a/changelog.d/sep47-device-node-chunk.changed.md b/changelog.d/sep47-device-node-chunk.changed.md index 18526c08e..00225078f 100644 --- a/changelog.d/sep47-device-node-chunk.changed.md +++ b/changelog.d/sep47-device-node-chunk.changed.md @@ -1 +1 @@ -On a CUDA or HIP build, a run with no `node_budget` and no node chunk now plans its node chunk within a quarter of the accelerator's free memory, through the same rule and response admissions as the host's plan, and never takes fewer nodes than the host plan at the route's default budget (#361). Most spatial runs on a data-centre GPU then evaluate their responses in one chunk, which took 0.74-0.92 of the default's time on an AMD Instinct MI300X, at the cost of space-domain buffers for every node at once (about 5 GB more on a 128 x 128 Cartesian filament). An explicit `node_budget` or chunk is unchanged and always wins; the run records `node_chunk_rule = "device"` in its backend metadata. CPU builds are unchanged. +On a CUDA or HIP build, a run with no `node_budget` and no node chunk now plans its node chunk within a quarter of the accelerator's free memory, through the same rule and response admissions as the host's plan, and never takes fewer nodes than the host plan at the route's default budget (#361). Most spatial runs on a data-centre GPU then evaluate their responses in one chunk, which took 0.74-0.92 of the default's time on an AMD Instinct MI300X, at the cost of space-domain buffers for every node at once (about 5 GB more on a 128 x 128 Cartesian filament). The run records `node_chunk_rule = "device"` in its backend metadata. CPU builds are unchanged. diff --git a/changelog.d/service-kernel-budget-agg.fixed.md b/changelog.d/service-kernel-budget-agg.fixed.md new file mode 100644 index 000000000..49e848a15 --- /dev/null +++ b/changelog.d/service-kernel-budget-agg.fixed.md @@ -0,0 +1 @@ +The front end's analysis kernel keeps its own two-thread budget when the window is started with `SOLPROP_THREADS` set (the window's value still goes to its runs), and draws the figures it exports with matplotlib's file-only Agg backend rather than the platform's interactive one. diff --git a/changelog.d/setup-repeated-work.changed.md b/changelog.d/setup-repeated-work.changed.md deleted file mode 100644 index e5741311d..000000000 --- a/changelog.d/setup-repeated-work.changed.md +++ /dev/null @@ -1 +0,0 @@ -Building a graded-index guide and run, and a large free-space launch, take less time: a mode solve evaluates its material once instead of once per finite element, a free-space launch forms each distinct column's admittance once, and neither repeats a table evaluation or a pass over the beam it already made. On the `grin_nonlinear` benchmark the build and translation go from 24 s to 16 s on one core, and on `kerr_beam_384` the launch's build from 12.6 s to 7.1 s. Every number of the translated problem is unchanged. diff --git a/changelog.d/single-gas-absorbing-attribution.fixed.md b/changelog.d/single-gas-absorbing-attribution.fixed.md new file mode 100644 index 000000000..e6bfce962 --- /dev/null +++ b/changelog.d/single-gas-absorbing-attribution.fixed.md @@ -0,0 +1 @@ +`absorption_by_species` of a gas-filled mode raises `ModeError` for a single gas whose `susceptibility=` law is absorbing, instead of reporting zero absorption while the law's loss is in `neff`; declaring the gas as a component of a `Mixture` attributes it. diff --git a/changelog.d/slurm-scan-blas-idle.changed.md b/changelog.d/slurm-scan-blas-idle.changed.md deleted file mode 100644 index 2998e175b..000000000 --- a/changelog.d/slurm-scan-blas-idle.changed.md +++ /dev/null @@ -1,4 +0,0 @@ -The batch script of a Slurm scan (`solprop.driver.executors.Slurm`) now sets -`OPENBLAS_THREAD_TIMEOUT=20` unless the job's environment sets it, as the front end's -Slurm runs already did, so the scan controller's BLAS threads sleep instead of spinning -between calls. diff --git a/changelog.d/smaller-speed-ups.changed.md b/changelog.d/smaller-speed-ups.changed.md new file mode 100644 index 000000000..2ce7e57e9 --- /dev/null +++ b/changelog.d/smaller-speed-ups.changed.md @@ -0,0 +1,15 @@ +Smaller speed-ups, each with the same results. Building a graded-index guide evaluates +its material once per mode solve rather than once per finite element (the +`grin_nonlinear` build and translation from 24 s to 16 s on one core), and a large +free-space launch forms each distinct column's admittance once, in threads (a 384-node +Kerr beam's launch from 12.6 s to 7.1 s). A run's fixed host cost is smaller: the first +statistics no longer import `scipy.signal` (0.7 s), opening a run's output no longer +digests its configuration a second time, and package versions are read once per process +([#347](https://github.com/LupoLab/solprop/issues/347)). Host passes too small to thread +no longer read the CPU topology first (#556). On the native backend, free space's +separable stage propagators go through its vector maths (`line` 0.89 of its time at one +thread; [#338](https://github.com/LupoLab/solprop/issues/338)); radial transverse-edge +reads synthesise their rows in one matrix product (radial filaments down to 0.75 of +their one-thread windows on an Apple M5 Max); single-mode problems use Apple's +Accelerate as they use OpenBLAS; and on Arm hosts the plasma column's band filter sums +its taps in one pass (the plasma cases 1-6 % faster on an Apple M5 Max, #560). diff --git a/changelog.d/sol-stats-spec.added.md b/changelog.d/sol-stats-spec.added.md new file mode 100644 index 000000000..fc6d44aa6 --- /dev/null +++ b/changelog.d/sol-stats-spec.added.md @@ -0,0 +1 @@ +`solprop.sol` exports `StatsSpec`, which a session passes to `stats=`. diff --git a/changelog.d/sol-stats-spec.breaking.md b/changelog.d/sol-stats-spec.breaking.md deleted file mode 100644 index 6d8bd6db0..000000000 --- a/changelog.d/sol-stats-spec.breaking.md +++ /dev/null @@ -1,4 +0,0 @@ -`solprop.sol` exports `StatsSpec`, which a session passes to `stats=`, and no longer -exports `resume`: that name read a file's resumable state and never continued a run, -which is `resume=True` on a run or `solprop resume`. The reader is -`solprop.output.resume`. diff --git a/changelog.d/spectral-responses-leaf.removed.md b/changelog.d/spectral-responses-leaf.removed.md deleted file mode 100644 index c2a6895e5..000000000 --- a/changelog.d/spectral-responses-leaf.removed.md +++ /dev/null @@ -1 +0,0 @@ -Removed `CompiledResponses.spectral_responses` and `Flags.has_spectral_responses` from the kernel contract. The tuple could only repeat `envelope_plasma`, which carries the envelope plasma's post-transform assembly alone, and the refusals that read the flag could not be reached. diff --git a/changelog.d/spectrogram-default-gate.fixed.md b/changelog.d/spectrogram-default-gate.fixed.md new file mode 100644 index 000000000..070e9ac0e --- /dev/null +++ b/changelog.d/spectrogram-default-gate.fixed.md @@ -0,0 +1,4 @@ +The desktop front end's spectrogram reports the gate solprop used: with no gate given it +showed a twentieth of the time range asked for, not of that range within the time window, +so a range wider than the window showed a wider gate than the map's. The default gate is +now given by `solprop.processing.fields.default_gate_fwhm`. diff --git a/changelog.d/stat-definition-fields.removed.md b/changelog.d/stat-definition-fields.breaking.md similarity index 100% rename from changelog.d/stat-definition-fields.removed.md rename to changelog.d/stat-definition-fields.breaking.md diff --git a/changelog.d/stats-spec-processing-error.breaking.md b/changelog.d/stats-spec-processing-error.breaking.md index c0ba29eb4..b6ec3bc48 100644 --- a/changelog.d/stats-spec-processing-error.breaking.md +++ b/changelog.d/stats-spec-processing-error.breaking.md @@ -1,5 +1,10 @@ -A malformed `StatsSpec` (an unknown, repeated or reserved name, a bad window or region, a -periodic subset that is not a subset or names a statistic no backend evaluates between -planes, a period below 1, a missing far-field table) now raises `ProcessingError`, a -`ValueError`, instead of `OutputError`, a `RuntimeError`: it is an argument error. Catch -`ProcessingError` (or `ValueError`) where `OutputError` was caught. +A malformed `StatsSpec` (an unknown, repeated or reserved name, a bad window or region, +a periodic subset that is not a subset or names a statistic no backend evaluates between +planes, a period below 1, a missing far-field table) or `stats.ApertureSet`, an unknown +profile or weighting passed to `stats.check_aperture_choices`, and a spec that does not +fit a line grid (an aperture centred off `y = 0`, a half-plane bounded in y or an +ellipse, or a spectral region whose `kappa_y` interval excludes zero) now raise +`ProcessingError`, a `ValueError`, instead of `OutputError`, a `RuntimeError`: they are +argument errors. Catch `ProcessingError` (or `ValueError`) where `OutputError` was +caught, around building a spec or its apertures and around a line run's statistics +tables. diff --git a/changelog.d/step-index-scalar-basis-orders.fixed.md b/changelog.d/step-index-scalar-basis-orders.fixed.md new file mode 100644 index 000000000..f5cd80290 --- /dev/null +++ b/changelog.d/step-index-scalar-basis-orders.fixed.md @@ -0,0 +1 @@ +`coupling.ScalarModeBasis.from_modes` admits several radial orders of one step-index fibre (HE11 with HE12, as LP01 and LP02), which it refused as modes of different fibres because each channel bounds its cladding at its own radius. diff --git a/changelog.d/stepindex-one-guide-collection.fixed.md b/changelog.d/stepindex-one-guide-collection.fixed.md new file mode 100644 index 000000000..8a461b432 --- /dev/null +++ b/changelog.d/stepindex-one-guide-collection.fixed.md @@ -0,0 +1 @@ +A `ModeCollection` of step-index channels of one fibre, whose outer radii differ, now integrates `orthonormality()` and its mode matrices over the widest channel's disc instead of refusing the set it accepted, and channels built with `StepIndexMode.from_numerical_aperture` for one fibre are recognised as one guide; the new `StepIndexMode.same_guide` says whether two channels share a guide. `modes.collection.overlap` is now the pair's entry of `orthonormality`, integrated to the same 1e-12 and refusing non-convergence with `ModeError`, where it used `dblquad` at its default 1.5e-8 tolerance and only warned. It integrates the normalised product, so a supplied set of high-order capillary modes (from about 16 HE1m of a 75 µm capillary), whose normalisation integral is small, is no longer wrongly refused as not orthonormal. diff --git a/changelog.d/stepper-settings-in-stepper.breaking.md b/changelog.d/stepper-settings-in-stepper.breaking.md index 2d8bf3476..531587734 100644 --- a/changelog.d/stepper-settings-in-stepper.breaking.md +++ b/changelog.d/stepper-settings-in-stepper.breaking.md @@ -1,5 +1,4 @@ `StepperSettings` and `PropagatorMode` moved from `solprop.translate.problem` to `solprop.stepper.settings`, the run-specification layer the run request's stepper -section belongs to: import them from there, or `StepperSettings` from -`solprop.stepper`. `solprop.translate` no longer re-exports `StepperSettings`. A run's -record and configuration hash do not name the class, and are unchanged. +section belongs to: import them from there, or `StepperSettings` from `solprop.stepper`. +`solprop.translate` no longer re-exports `StepperSettings`. diff --git a/changelog.d/stopped-run-close-failure.fixed.md b/changelog.d/stopped-run-close-failure.fixed.md new file mode 100644 index 000000000..7d6fee1a3 --- /dev/null +++ b/changelog.d/stopped-run-close-failure.fixed.md @@ -0,0 +1,2 @@ +A run stopped by its own `stop=` flag now raises a failure to close its output, backend +or TDSE archive, instead of returning as a clean stop with the error lost. diff --git a/changelog.d/tabulated-mode-loss-repr.fixed.md b/changelog.d/tabulated-mode-loss-repr.fixed.md new file mode 100644 index 000000000..fc0fd4546 --- /dev/null +++ b/changelog.d/tabulated-mode-loss-repr.fixed.md @@ -0,0 +1 @@ +The printed form of `TabulatedMode` and `TabulatedHollowMode` now says what their loss is (`loss=model`, `loss=none`, ...) and names the fill as the other hollow modes do (`Ar 1 bar`, `evacuated`), and `IndexTable`'s printed form calls its interpolation rule `loss_interpolation=` rather than `loss=`. diff --git a/changelog.d/tdse-worker-script-path.fixed.md b/changelog.d/tdse-worker-script-path.fixed.md new file mode 100644 index 000000000..00801c6fe --- /dev/null +++ b/changelog.d/tdse-worker-script-path.fixed.md @@ -0,0 +1,3 @@ +The TDSE provider's worker process no longer receives the running script's own +directory on its import path, so a module there named like a standard-library one +(a script's `random.py`, say) is not imported in the worker in its place. diff --git a/changelog.d/translate-problem-request.breaking.md b/changelog.d/translate-problem-request.breaking.md new file mode 100644 index 000000000..7c67edcfa --- /dev/null +++ b/changelog.d/translate-problem-request.breaking.md @@ -0,0 +1,35 @@ +The problem descriptor between translation and the backends (`solprop.translate`, +unstable within 0.x under ADR-058) describes one trajectory and leaves the run's policy +to a separate request +([SEP 47](https://github.com/LupoLab/solprop/blob/main/docs/dev/seps/archive/sep-0047-run-ownership.md), +[SEP 52](https://github.com/LupoLab/solprop/blob/main/docs/dev/seps/archive/sep-0052-backend-shape.md)). +`Simulation`, `SimulationSettings` and the `prop_*` functions take the same arguments as +before. `solprop.translate.problem.KernelProblem` is renamed `PropagationProblem`, with +no alias. Its arrays carry no leading batch axis (the problem's `shape`, +`initial.field0` and `initial.noise0`, the operator's value tables, `StageTerms.phi`, +`Observation.field` and `noise_phase`, the periodic rows of `StepStats`, +`ResponseBudgetError.field`, `RunEstimate.shape` and the fields that +`BoundaryMonitor.power` and `SplitCrossing.occupancy` take), so code that indexed `[0]` +drops the index; `Initial.batch_params`, `Flags.single_batch`, +`assemble(batch_params=...)` and `plane_from_observation(member=...)` are removed. The +route-specific fields `transform`, `flux`, `transverse`, `tdse` and `current_numerator` +move into a closed union, `problem.route`, from the new module +`solprop.translate.routes` (a `ModalRoute`, a `GeneralRoute` or a `SpatialRoute`); +`problem.transform` still reads the route's transform, and `tdse_of`, `flux_of` and +`transverse_of` read a route's own leaves. The problem no longer has `stepper` or +`stats_spec`: the run's policy travels in the immutable +`solprop.translate.run_request.RunRequest`, which `Simulation.run_request()` returns, +and `assemble` returns a `Translation(problem, request)` pair +(`problem, request = assemble(...)`). `PropagationProblem.validate()` checks the problem +alone, the new `solprop.translate.problem.validate_run(problem, request)` adds the +checks that read the run's policy, and `validate_launch`, `metadata_for`, +`field_retention`, `check_snapshot_request`, `run_summary` and `check_derived_problem` +take the request. A hand-built problem whose route, polarisation count, vector Raman +terms or TDSE statistics a backend refused with `BackendError` is now refused with +`TranslationError` (`solprop.translate.admission.check_general_route`). Moved: +`node_kerr_tensor`, `node_kerr_form` and `node_delayed_maps` from +`solprop.backends.numpy_ref` to `solprop.translate.general`, `QUADRATURE_ALARM` to +`solprop.translate.modal`, `MARCH_SNAPSHOT_AUTO_BYTES` from `solprop.driver.run` to +`solprop.translate.run_request`, and `MAX_N_POL` to +`solprop.nonlinear.responses.MAX_N_POL` alone; `CompiledResponses` no longer takes +`response_order`. diff --git a/changelog.d/translate-problem-split.changed.md b/changelog.d/translate-problem-split.changed.md deleted file mode 100644 index f7d90dc3d..000000000 --- a/changelog.d/translate-problem-split.changed.md +++ /dev/null @@ -1,7 +0,0 @@ -`solprop.translate.problem` now holds the kernel contract alone; translation is split -into modules by concern: `solprop.translate.assembly` (`assemble`, -`MAX_GENERAL_FLOW_EXPONENT`), `solprop.translate.walls` (a capillary's coherent wall and -taper coupling) and `solprop.translate.validation` (`validate_coupled_flow`, -`DEFAULT_FLOW_CONDITION_LIMIT`, `MOVING_FLOW_CERTIFICATE`, `TAPER_FLOW_CERTIFICATE`). -Every name `solprop.translate.problem` exported still imports from it, and -`solprop.translate.assemble` is unchanged. diff --git a/changelog.d/transverse-unwatched.breaking.md b/changelog.d/transverse-unwatched.breaking.md new file mode 100644 index 000000000..ba40f28bc --- /dev/null +++ b/changelog.d/transverse-unwatched.breaking.md @@ -0,0 +1 @@ +The transverse edge's `unwatched` status is gone, every backend reading the edge: `TransverseStatus` no longer lists it and `TransverseEdge.launch` no longer takes `reads=`; drop `reads=` from a call. The boundary monitor's `unwatched` stretches, left by an execution run with `boundary_check=None`, are unchanged. diff --git a/changelog.d/transverse-unwatched.removed.md b/changelog.d/transverse-unwatched.removed.md deleted file mode 100644 index 53f6ffd77..000000000 --- a/changelog.d/transverse-unwatched.removed.md +++ /dev/null @@ -1 +0,0 @@ -The transverse edge's `unwatched` status is gone, every backend reading the edge: `TransverseStatus` no longer lists it and `TransverseEdge.launch` no longer takes `reads=`, `solprop.backends.records.EdgeConfig` drops `reads_edge` and `edge_config` its `reads=` argument, and `EdgeNoticeKind` drops `UNWATCHED`. The boundary monitor's `unwatched` stretches, left by an execution run with `boundary_check=None`, are unchanged. diff --git a/changelog.d/two-backends.removed.md b/changelog.d/two-backends.breaking.md similarity index 51% rename from changelog.d/two-backends.removed.md rename to changelog.d/two-backends.breaking.md index 8341035eb..38bb90af9 100644 --- a/changelog.d/two-backends.removed.md +++ b/changelog.d/two-backends.breaking.md @@ -1 +1 @@ -solprop has exactly two backends, `native` and `numpy_ref`, with no tiers and no plugin backends ([ADR-077](docs/dev/decisions.md)). `solprop.backends.registry.BACKENDS`, `BackendEntry`, `REMOVED_BACKENDS` and `FAR_FIELD_BACKENDS` are removed; `BACKEND_NAMES` lists the two. A backend name that is neither, `numba_cpu` and `mlx` included, now raises `BackendError` naming both wherever it is requested, where `select` raised `ValueError` for an unknown one. +solprop has exactly two backends, `native` and `numpy_ref`, with no tiers and no plugin backends ([ADR-077](docs/dev/decisions.md)). `solprop.backends.registry.BACKENDS`, `BackendEntry`, `REMOVED_BACKENDS` and `FAR_FIELD_BACKENDS` are removed; `BACKEND_NAMES` lists the two. A backend name that is neither, `numba_cpu` included, now raises `BackendError` naming both wherever it is requested, where `select` raised `ValueError` for an unknown one; pass `backend="native"`, `"numpy_ref"` or `"auto"`. diff --git a/changelog.d/uniform-refusal-wording.changed.md b/changelog.d/uniform-refusal-wording.breaking.md similarity index 100% rename from changelog.d/uniform-refusal-wording.changed.md rename to changelog.d/uniform-refusal-wording.breaking.md diff --git a/changelog.d/vincetti-mixture-repr.fixed.md b/changelog.d/vincetti-mixture-repr.fixed.md new file mode 100644 index 000000000..009207790 --- /dev/null +++ b/changelog.d/vincetti-mixture-repr.fixed.md @@ -0,0 +1 @@ +The `repr` of a mixture-filled `VincettiMode` names the mixture's gases and pressure (`He+Ar 2 bar`), as the other mode families do, instead of the bare word `mixture`. diff --git a/changelog.d/walkoff-warning-caller.fixed.md b/changelog.d/walkoff-warning-caller.fixed.md new file mode 100644 index 000000000..bc946e701 --- /dev/null +++ b/changelog.d/walkoff-warning-caller.fixed.md @@ -0,0 +1,3 @@ +The walk-off `SolpropWarning` of `solprop.boundaries.warn_walkoff`, raised when a capillary +or hollow-core run builds its absorber, now names the caller's line instead of a line in +solprop's own route code. diff --git a/changelog.d/zdw-default-window.changed.md b/changelog.d/zdw-default-window.changed.md new file mode 100644 index 000000000..b23504eb7 --- /dev/null +++ b/changelog.d/zdw-default-window.changed.md @@ -0,0 +1 @@ +The default search window of `modes.base.zdw` and `stats.zdw` (`stats.DEFAULT_ZDW_RANGE`) now starts at 150 nm instead of 100 nm, above the noble gases' vacuum-ultraviolet lines and fused silica's absorption edge, where a lossless solve takes silica as transparent and finds zeros with no meaning; pass `wavelength_limits` to search below it. diff --git a/coverage-cpu.ini b/coverage-cpu.ini deleted file mode 100644 index 11f8aa59f..000000000 --- a/coverage-cpu.ini +++ /dev/null @@ -1,18 +0,0 @@ -; SPDX-FileCopyrightText: 2026 John C. Travers and contributors -; -; SPDX-License-Identifier: GPL-3.0-or-later - -# Coverage configuration of the CPU lanes (`poe cov`): every line of solprop, which the -# lane requires to 100 %. -[run] -source = solprop -branch = True - -[report] -fail_under = 100 -show_missing = True -exclude_also = - if TYPE_CHECKING: - @overload - raise NotImplementedError - ^\s*\.\.\.$ diff --git a/docs/_templates/autosummary/module.rst b/docs/_templates/autosummary/module.rst index 722c546a6..bfa998da4 100644 --- a/docs/_templates/autosummary/module.rst +++ b/docs/_templates/autosummary/module.rst @@ -4,8 +4,10 @@ documented on the submodule's own page. Documenting them here too would register two objects under one name -- `solprop.physdata.density` is both a module and the function that module exports -- which Sphinx reports as a duplicate object - description and `-W` turns into a build failure. So a package page carries only its - module list; a leaf module documents its members as usual. #} + description and `-W` turns into a build failure. So a package page carries its + module list, and documents only the names no submodule's page can: those defined in + its own `__init__` or in a private module (`package_members`, from + `docs/api_surface.py`). A leaf module documents its members as usual. #} {#- The front end's service is front-end support, not user interface (the front end's design, D20): its package page says what it is, and its modules get no pages, as they change without notice. #} @@ -35,6 +37,9 @@ Its design is the desktop front end's (``docs/dev/gui/design.md``, sections 13.3 {%- elif modules %} .. automodule:: {{ fullname }} :no-members: +{% for directive, name in package_members.get(fullname, []) %} +.. {{ directive }}:: {{ fullname }}.{{ name }} +{% endfor %} .. rubric:: Modules diff --git a/docs/api/index.md b/docs/api/index.md index 817048fc8..ec3e68e52 100644 --- a/docs/api/index.md +++ b/docs/api/index.md @@ -26,9 +26,13 @@ In scripts and library code, import from the home modules listed below. | {mod}`solprop.profiles` | quantities that vary along z: radius, pressure and temperature profiles such as `PiecewiseLinear` and `PressureGradient` | | {mod}`solprop.gasflow` | the steady gas flow of a pressure gradient: `steady_fill`, choked ends, `flow_report` | | {mod}`solprop.boundaries` | absorbing boundaries in time and frequency | +| {mod}`solprop.spatial_absorber` | the transverse boundary of a free-space run: `SpatialAbsorber`, a real-space collar beside the default safety ramp, and the design translation resolves it into ([the transverse boundary](../guide/numerics/boundaries.md#the-transverse-boundary)) | +| {mod}`solprop.monitor`, {mod}`solprop.transverse_monitor` | the boundary monitor: `BoundaryCheck`, the policy every `prop_*` takes as `boundary_check`, the monitor of the time window's edges, and `TransverseEdge`, which watches a free-space grid's outer edge ([watching the window's edges](../guide/numerics/boundaries.md#watching-the-windows-edges)) | | {mod}`solprop.stepper` | the Runge–Kutta tableaux, the low-call Adams methods (`multistep`), the step-size controller, fixed step schedules (`FixedSchedule`) and the stepper section a run request carries (`StepperSettings`) | | {mod}`solprop.noise` | shot-noise realisations | | {mod}`solprop.recipe` | recipes: a run written as TOML (`Recipe`, with `check`, `build`, `run`, `save` and `to_python`), values pinned to a design target (`solprop.recipe.pins`, `Recipe.resolve`, `Recipe.pin_roots`), the parameter metadata a front end reads (`parameters`), and the quantity parser and formatter (`solprop.recipe.quantity`) ([recipes and the command line](../guide/setup/recipes.md)) | +| {mod}`solprop.capabilities` | what solprop can do: `route` (a route's keywords, their values and the combination rules its builder enforces), `species` (a built-in gas's ionisation models and Raman response) and `output` (what a results file can derive) ([what a route and a species admit](../guide/setup/recipes.md#what-a-route-and-a-species-admit)) | +| {mod}`solprop.calibration` | calibrating the native backend to its machine: `calibrate`, and `profile`, `export_profile`, `import_profile` and `clear` for the stored profile ([calibration](../guide/performance/calibration.md)) | | {mod}`solprop.driver.defaults` | the route defaults in one table (`ROUTE_DEFAULTS`): integrators, tolerances, noise and collar schemes, and the functions that resolve them | | {mod}`solprop.driver.scan`, {mod}`solprop.driver.executors` | parameter scans and where their points run ([scans and executors](scans.md)) | diff --git a/docs/api/scans.md b/docs/api/scans.md index db86cfb26..5e7763d84 100644 --- a/docs/api/scans.md +++ b/docs/api/scans.md @@ -11,7 +11,8 @@ modules involved are: `Pool`, a durable `Queue` and `Slurm`; - {mod}`solprop.processing.scans`: the reductions a worker evaluates for each point (energy in a band, a spectrum, mode energies, a custom reduction) and the reader of a - collected scan (`open`, `ScanOutput`); + collected scan ({func}`~solprop.processing.scans.open_scan`, + {class}`~solprop.processing.scans.ScanOutput`); - {mod}`solprop.output.scan`: the scan file, into which the controller commits each completed point; diff --git a/docs/api/transport.md b/docs/api/transport.md index 7b5e2db9f..4571dc0b0 100644 --- a/docs/api/transport.md +++ b/docs/api/transport.md @@ -15,5 +15,5 @@ page. Both names are importable from {mod}`solprop.coupling`. :members: ``` -Transport between planes was proposed and carried out by -[SEP 31](../dev/seps/archive/sep-0031-simulation-coupling.md). +The design of transport between planes is +[SEP 31](https://github.com/LupoLab/solprop/blob/main/docs/dev/seps/archive/sep-0031-simulation-coupling.md). diff --git a/docs/api_surface.py b/docs/api_surface.py new file mode 100644 index 000000000..c16a8e722 --- /dev/null +++ b/docs/api_surface.py @@ -0,0 +1,151 @@ +# SPDX-FileCopyrightText: 2026 John C. Travers and contributors +# +# SPDX-License-Identifier: GPL-3.0-or-later + +"""The public names that only a package page of the API reference can document. + +The reference's module template (``_templates/autosummary/module.rst``) documents a +leaf module's ``__all__`` in full and gives a package page its module list. A package +page leaves out the names its ``__all__`` re-exports from a public submodule, whose own +page documents them. A name whose home is the package's ``__init__`` or a private +module (``solprop.calibration.calibrate``, ``solprop.processing.example_output``) has +no such page, so the template documents it on the package page, from the table +:func:`package_members` gives ``conf.py``. ``tests/test_api_reference.py`` holds the +rendered template to every public module's ``__all__``. +""" + +import importlib +import inspect +import pkgutil +from collections.abc import Iterator +from types import ModuleType + +__all__ = [ + "NAMESPACES", + "UNDOCUMENTED_TREES", + "object_key", + "package_members", + "public_modules", +] + +#: Packages whose modules get no page of their own: the front end's service changes +#: without notice (the template says why). +UNDOCUMENTED_TREES = ("solprop.service",) + +#: Leaf modules that gather names documented on their home pages: their page documents +#: only the functions they define themselves. +NAMESPACES = ("solprop.sol",) + + +def public_modules(root: str = "solprop") -> Iterator[ModuleType]: + """Yield the modules the recursive autosummary gives a page. + + Parameters + ---------- + root : str, optional + The package the reference starts from. + + Yields + ------ + module + ``root``, then every submodule whose name has no leading underscore, depth + first, as autosummary walks them; nothing below :data:`UNDOCUMENTED_TREES`. + """ + module = importlib.import_module(root) + yield module + if hasattr(module, "__path__") and root not in UNDOCUMENTED_TREES: + for _, name, _ in pkgutil.iter_modules(module.__path__): + if not name.startswith("_"): + yield from public_modules(f"{root}.{name}") + + +def object_key(name: str, value: object) -> object: + """Return what identifies a public name's object across the pages that list it. + + A function or class is the same object under every name it is exported by; any + other value (a number, a string) is matched by its name as well, since equal small + values may be one object. + + Parameters + ---------- + name : str + The name a module exports it under. + value : object + The object. + + Returns + ------- + object + A hashable key. + """ + if hasattr(value, "__qualname__") and not isinstance(value, ModuleType): + return id(value) + return (name, id(value)) + + +def _leaf_page_keys(module: ModuleType) -> set[object]: + """Keys of the objects a leaf module's page documents: its ``__all__``.""" + keys = set() + for name in getattr(module, "__all__", ()): + value = getattr(module, name) + home = getattr(value, "__module__", None) + if module.__name__ in NAMESPACES and home != module.__name__: + continue + keys.add(object_key(name, value)) + return keys + + +def _directive(value: object) -> str: + """Name the autodoc directive that documents an object.""" + if inspect.isclass(value): + return "autoexception" if issubclass(value, BaseException) else "autoclass" + return "autofunction" if callable(value) else "autodata" + + +def package_members(root: str = "solprop") -> dict[str, list[tuple[str, str]]]: + """Return, for each package page, the names only that page can document. + + These are the names of a package's ``__all__`` that no leaf module's page + documents: those defined in the package's ``__init__`` or in a private module. A + name two packages export is documented once, on the deeper page. Dunder names + (``__version__``) are package metadata and are left out. + + Parameters + ---------- + root : str, optional + The package the reference starts from. + + Returns + ------- + dict of str to list of (str, str) + Package name to the ``(directive, name)`` pairs its page documents, sorted by + name, with ``directive`` the autodoc directive (``"autoclass"``, + ``"autofunction"``, ...); a package with none is absent. + """ + modules = list(public_modules(root)) + documented = set().union( + *( + _leaf_page_keys(module) + for module in modules + if not hasattr(module, "__path__") + ) + ) + packages = [ + module + for module in modules + if hasattr(module, "__path__") and module.__name__ not in UNDOCUMENTED_TREES + ] + members: dict[str, list[tuple[str, str]]] = {} + for package in sorted(packages, key=lambda module: -module.__name__.count(".")): + for name in sorted(getattr(package, "__all__", ())): + value = getattr(package, name) + key = object_key(name, value) + if ( + name.startswith("__") + or isinstance(value, ModuleType) + or key in documented + ): + continue + documented.add(key) + members.setdefault(package.__name__, []).append((_directive(value), name)) + return members diff --git a/docs/auto_examples/waveguides/images/sphx_glr_plot_05_moving_solid_guide_002.png b/docs/auto_examples/waveguides/images/sphx_glr_plot_05_moving_solid_guide_002.png index 7325b3576..1ff6d3628 100644 Binary files a/docs/auto_examples/waveguides/images/sphx_glr_plot_05_moving_solid_guide_002.png and b/docs/auto_examples/waveguides/images/sphx_glr_plot_05_moving_solid_guide_002.png differ diff --git a/docs/auto_examples/waveguides/images/sphx_glr_plot_05_moving_solid_guide_003.png b/docs/auto_examples/waveguides/images/sphx_glr_plot_05_moving_solid_guide_003.png index b6d8d8e8f..0d41db097 100644 Binary files a/docs/auto_examples/waveguides/images/sphx_glr_plot_05_moving_solid_guide_003.png and b/docs/auto_examples/waveguides/images/sphx_glr_plot_05_moving_solid_guide_003.png differ diff --git a/docs/auto_examples/waveguides/plot_05_moving_solid_guide.codeobj.json b/docs/auto_examples/waveguides/plot_05_moving_solid_guide.codeobj.json index 3c292ff73..6d9788e18 100644 --- a/docs/auto_examples/waveguides/plot_05_moving_solid_guide.codeobj.json +++ b/docs/auto_examples/waveguides/plot_05_moving_solid_guide.codeobj.json @@ -3144,8 +3144,8 @@ { "is_class": false, "is_explicit": false, - "module": "solprop.modes.guide", - "module_short": "solprop.modes.guide", + "module": "solprop.modes.path", + "module_short": "solprop.modes.path", "name": "ModalPath" }, { diff --git a/docs/auto_examples/waveguides/plot_05_moving_solid_guide.ipynb b/docs/auto_examples/waveguides/plot_05_moving_solid_guide.ipynb index 7f5313c85..06474e90f 100644 --- a/docs/auto_examples/waveguides/plot_05_moving_solid_guide.ipynb +++ b/docs/auto_examples/waveguides/plot_05_moving_solid_guide.ipynb @@ -229,7 +229,7 @@ "name": "python", "nbconvert_exporter": "python", "pygments_lexer": "ipython3", - "version": "3.14.7" + "version": "3.14.6" } }, "nbformat": 4, diff --git a/docs/auto_examples/waveguides/plot_05_moving_solid_guide.rst b/docs/auto_examples/waveguides/plot_05_moving_solid_guide.rst index f7c8e316c..e7d162be5 100644 --- a/docs/auto_examples/waveguides/plot_05_moving_solid_guide.rst +++ b/docs/auto_examples/waveguides/plot_05_moving_solid_guide.rst @@ -409,9 +409,9 @@ keep the launched energy to about 1e-6 in every run. .. code-block:: none - L = 0.05 mm: LP_02 holds 6.131e-02 at the exit (first order 6.267e-02); energy lost 6.7e-10 - L = 0.10 mm: LP_02 holds 5.394e-02 at the exit (first order 5.517e-02); energy lost 6.8e-10 - L = 0.20 mm: LP_02 holds 3.112e-02 at the exit (first order 3.192e-02); energy lost 7.7e-10 + L = 0.05 mm: LP_02 holds 6.131e-02 at the exit (first order 6.267e-02); energy lost 6.9e-10 + L = 0.10 mm: LP_02 holds 5.394e-02 at the exit (first order 5.517e-02); energy lost 7.0e-10 + L = 0.20 mm: LP_02 holds 3.112e-02 at the exit (first order 3.192e-02); energy lost 7.8e-10 L = 0.50 mm: LP_02 holds 7.900e-04 at the exit (first order 7.597e-04); energy lost 2.0e-09 L = 1.00 mm: LP_02 holds 6.548e-04 at the exit (first order 6.496e-04); energy lost 7.0e-09 L = 2.00 mm: LP_02 holds 3.271e-04 at the exit (first order 3.272e-04); energy lost 3.1e-08 @@ -917,7 +917,7 @@ Twelve guides, eight linear runs on the moving guide and four nonlinear runs. .. code-block:: none - 433 s; backend native, 16 threads + 413 s; backend native, 32 threads @@ -934,7 +934,7 @@ For a paced introduction to propagation, start with the .. rst-class:: sphx-glr-timing - **Total running time of the script:** (7 minutes 12.609 seconds) + **Total running time of the script:** (6 minutes 52.874 seconds) .. _sphx_glr_download_auto_examples_waveguides_plot_05_moving_solid_guide.py: diff --git a/docs/auto_examples/waveguides/plot_05_moving_solid_guide.zip b/docs/auto_examples/waveguides/plot_05_moving_solid_guide.zip index b0fbc0a01..b2cbfc73e 100644 Binary files a/docs/auto_examples/waveguides/plot_05_moving_solid_guide.zip and b/docs/auto_examples/waveguides/plot_05_moving_solid_guide.zip differ diff --git a/docs/auto_tutorials/basics/images/sphx_glr_plot_02_pulses_001.png b/docs/auto_tutorials/basics/images/sphx_glr_plot_02_pulses_001.png index aabdd2e06..9efcd2301 100644 Binary files a/docs/auto_tutorials/basics/images/sphx_glr_plot_02_pulses_001.png and b/docs/auto_tutorials/basics/images/sphx_glr_plot_02_pulses_001.png differ diff --git a/docs/auto_tutorials/basics/images/sphx_glr_plot_02_pulses_002.png b/docs/auto_tutorials/basics/images/sphx_glr_plot_02_pulses_002.png index 07eb497e1..73b6d3fd5 100644 Binary files a/docs/auto_tutorials/basics/images/sphx_glr_plot_02_pulses_002.png and b/docs/auto_tutorials/basics/images/sphx_glr_plot_02_pulses_002.png differ diff --git a/docs/auto_tutorials/basics/images/sphx_glr_plot_03_analysing_a_run_002.png b/docs/auto_tutorials/basics/images/sphx_glr_plot_03_analysing_a_run_002.png index 39215d6c3..2dddb974d 100644 Binary files a/docs/auto_tutorials/basics/images/sphx_glr_plot_03_analysing_a_run_002.png and b/docs/auto_tutorials/basics/images/sphx_glr_plot_03_analysing_a_run_002.png differ diff --git a/docs/auto_tutorials/basics/images/sphx_glr_plot_07_time_window_001.png b/docs/auto_tutorials/basics/images/sphx_glr_plot_07_time_window_001.png index a8dd174a7..e1f177e6b 100644 Binary files a/docs/auto_tutorials/basics/images/sphx_glr_plot_07_time_window_001.png and b/docs/auto_tutorials/basics/images/sphx_glr_plot_07_time_window_001.png differ diff --git a/docs/auto_tutorials/basics/images/sphx_glr_plot_07_time_window_002.png b/docs/auto_tutorials/basics/images/sphx_glr_plot_07_time_window_002.png index d51f5a752..8759426b1 100644 Binary files a/docs/auto_tutorials/basics/images/sphx_glr_plot_07_time_window_002.png and b/docs/auto_tutorials/basics/images/sphx_glr_plot_07_time_window_002.png differ diff --git a/docs/auto_tutorials/basics/images/thumb/sphx_glr_plot_02_pulses_thumb.png b/docs/auto_tutorials/basics/images/thumb/sphx_glr_plot_02_pulses_thumb.png index 2a1e903d4..3900abadd 100644 Binary files a/docs/auto_tutorials/basics/images/thumb/sphx_glr_plot_02_pulses_thumb.png and b/docs/auto_tutorials/basics/images/thumb/sphx_glr_plot_02_pulses_thumb.png differ diff --git a/docs/auto_tutorials/basics/images/thumb/sphx_glr_plot_07_time_window_thumb.png b/docs/auto_tutorials/basics/images/thumb/sphx_glr_plot_07_time_window_thumb.png index d9a48d1ff..8a49418c3 100644 Binary files a/docs/auto_tutorials/basics/images/thumb/sphx_glr_plot_07_time_window_thumb.png and b/docs/auto_tutorials/basics/images/thumb/sphx_glr_plot_07_time_window_thumb.png differ diff --git a/docs/auto_tutorials/basics/plot_01_package_overview.ipynb b/docs/auto_tutorials/basics/plot_01_package_overview.ipynb index a1f893ed6..ce4f36178 100644 --- a/docs/auto_tutorials/basics/plot_01_package_overview.ipynb +++ b/docs/auto_tutorials/basics/plot_01_package_overview.ipynb @@ -85,7 +85,7 @@ "name": "python", "nbconvert_exporter": "python", "pygments_lexer": "ipython3", - "version": "3.14.7" + "version": "3.14.6" } }, "nbformat": 4, diff --git a/docs/auto_tutorials/basics/plot_01_package_overview.rst b/docs/auto_tutorials/basics/plot_01_package_overview.rst index 0640b6802..49a7a5444 100644 --- a/docs/auto_tutorials/basics/plot_01_package_overview.rst +++ b/docs/auto_tutorials/basics/plot_01_package_overview.rst @@ -61,7 +61,7 @@ warning. .. code-block:: none - solprop 0.1.1.dev200+ga44d5ec24.d20261102 + solprop 0.2.1.dev2062+g9b317f7af installed backends ('numpy_ref', 'native'); auto resolves to native @@ -115,7 +115,7 @@ range at the short end of the window, which it reports; that notice is silenced. plasma_work_defect, pressure, quadrature_error, species_density, ... between planes: none run: RunMetadata(multimode, field grid of 864, 1 modes, native, - 2026-11-02T09:43:29.380614+00:00) + 2026-11-18T12:16:21.678301+00:00) @@ -177,7 +177,7 @@ For a paced propagation lesson, return to .. rst-class:: sphx-glr-timing - **Total running time of the script:** (0 minutes 4.303 seconds) + **Total running time of the script:** (0 minutes 0.244 seconds) .. _sphx_glr_download_auto_tutorials_basics_plot_01_package_overview.py: diff --git a/docs/auto_tutorials/basics/plot_01_package_overview.zip b/docs/auto_tutorials/basics/plot_01_package_overview.zip index 709b54c0c..114edfc6d 100644 Binary files a/docs/auto_tutorials/basics/plot_01_package_overview.zip and b/docs/auto_tutorials/basics/plot_01_package_overview.zip differ diff --git a/docs/auto_tutorials/basics/plot_02_pulses.ipynb b/docs/auto_tutorials/basics/plot_02_pulses.ipynb index 38a93305d..6ce0ffa05 100644 --- a/docs/auto_tutorials/basics/plot_02_pulses.ipynb +++ b/docs/auto_tutorials/basics/plot_02_pulses.ipynb @@ -103,7 +103,7 @@ "name": "python", "nbconvert_exporter": "python", "pygments_lexer": "ipython3", - "version": "3.14.5" + "version": "3.14.6" } }, "nbformat": 4, diff --git a/docs/auto_tutorials/basics/plot_02_pulses.zip b/docs/auto_tutorials/basics/plot_02_pulses.zip index 7439a564a..d448938ef 100644 Binary files a/docs/auto_tutorials/basics/plot_02_pulses.zip and b/docs/auto_tutorials/basics/plot_02_pulses.zip differ diff --git a/docs/auto_tutorials/basics/plot_03_analysing_a_run.rst b/docs/auto_tutorials/basics/plot_03_analysing_a_run.rst index 36c1aafd8..23cdd1c08 100644 --- a/docs/auto_tutorials/basics/plot_03_analysing_a_run.rst +++ b/docs/auto_tutorials/basics/plot_03_analysing_a_run.rst @@ -346,7 +346,7 @@ For a paced propagation lesson, return to .. rst-class:: sphx-glr-timing - **Total running time of the script:** (0 minutes 1.296 seconds) + **Total running time of the script:** (0 minutes 0.435 seconds) .. _sphx_glr_download_auto_tutorials_basics_plot_03_analysing_a_run.py: diff --git a/docs/auto_tutorials/basics/plot_03_analysing_a_run.zip b/docs/auto_tutorials/basics/plot_03_analysing_a_run.zip index 80d0dc9a2..9a1edbdff 100644 Binary files a/docs/auto_tutorials/basics/plot_03_analysing_a_run.zip and b/docs/auto_tutorials/basics/plot_03_analysing_a_run.zip differ diff --git a/docs/auto_tutorials/basics/plot_04_interactive_session.rst b/docs/auto_tutorials/basics/plot_04_interactive_session.rst index d5d70e0e4..f781d554b 100644 --- a/docs/auto_tutorials/basics/plot_04_interactive_session.rst +++ b/docs/auto_tutorials/basics/plot_04_interactive_session.rst @@ -200,8 +200,8 @@ wall resonances can produce several roots; phase matching does not ensure low lo .. code-block:: none - 2026-11-16 16:17:38,476 WARNING solprop.modes.antiresonant: Vincetti geometry outside published validation ranges: wall_thickness/tube_radius=0.0243902 outside [0.05, 0.2] - Vincetti RDW roots (nm): [636.0, 688.2] + 2026-11-18 12:16:23,848 WARNING solprop.modes.antiresonant: Vincetti geometry outside published validation ranges: wall_thickness/tube_radius=0.0243902 outside [0.05, 0.2] + Vincetti RDW roots (nm): [635.9, 688.5] @@ -251,7 +251,7 @@ One call. The pulse is a Gaussian, the default; the run takes a second or two. plasma_work_defect, pressure, quadrature_error, species_density, ... between planes: none run: RunMetadata(multimode, field grid of 1728, 1 modes, native, - 2026-11-16T16:17:39.316305+00:00) + 2026-11-18T12:16:24.129867+00:00) @@ -352,7 +352,7 @@ best it can do is *remove* glass that is not there. duration: 41.92 fs before, 4.944 fs after, 4.21 fs at the transform limit peak power: 2.113 GW before, 13.34 GW after, 17.44 GW at the limit quality: 0.765 of the transform-limited peak power - search: converged: Solution found. (77 evaluations) + search: converged: Solution found. (78 evaluations) @@ -390,7 +390,7 @@ and tunes the insertion for each. duration: 41.92 fs before, 4.96 fs after, 4.21 fs at the transform limit peak power: 2.113 GW before, 13.13 GW after, 17.44 GW at the limit quality: 0.7533 of the transform-limited peak power - search: converged: Solution found. (624 evaluations) + search: converged: Solution found. (626 evaluations) per count: 0: quality 0.1212, 0 m 1: quality 0.7533, 128.3 um 2: quality 0.7391, 1.338 mm @@ -528,7 +528,7 @@ For a paced propagation lesson, return to .. rst-class:: sphx-glr-timing - **Total running time of the script:** (0 minutes 12.055 seconds) + **Total running time of the script:** (0 minutes 2.768 seconds) .. _sphx_glr_download_auto_tutorials_basics_plot_04_interactive_session.py: diff --git a/docs/auto_tutorials/basics/plot_04_interactive_session.zip b/docs/auto_tutorials/basics/plot_04_interactive_session.zip index 7df2f8828..a87fe9ae9 100644 Binary files a/docs/auto_tutorials/basics/plot_04_interactive_session.zip and b/docs/auto_tutorials/basics/plot_04_interactive_session.zip differ diff --git a/docs/auto_tutorials/basics/plot_05_pressure_energy_scan.ipynb b/docs/auto_tutorials/basics/plot_05_pressure_energy_scan.ipynb index f6ff8e8c2..2c6aa2d8d 100644 --- a/docs/auto_tutorials/basics/plot_05_pressure_energy_scan.ipynb +++ b/docs/auto_tutorials/basics/plot_05_pressure_energy_scan.ipynb @@ -60,7 +60,7 @@ "name": "python", "nbconvert_exporter": "python", "pygments_lexer": "ipython3", - "version": "3.14.7" + "version": "3.14.6" } }, "nbformat": 4, diff --git a/docs/auto_tutorials/basics/plot_05_pressure_energy_scan.rst b/docs/auto_tutorials/basics/plot_05_pressure_energy_scan.rst index 636eb5ba5..bf166ce7f 100644 --- a/docs/auto_tutorials/basics/plot_05_pressure_energy_scan.rst +++ b/docs/auto_tutorials/basics/plot_05_pressure_energy_scan.rst @@ -157,7 +157,7 @@ For a paced propagation lesson, return to .. rst-class:: sphx-glr-timing - **Total running time of the script:** (0 minutes 4.584 seconds) + **Total running time of the script:** (0 minutes 0.551 seconds) .. _sphx_glr_download_auto_tutorials_basics_plot_05_pressure_energy_scan.py: diff --git a/docs/auto_tutorials/basics/plot_05_pressure_energy_scan.zip b/docs/auto_tutorials/basics/plot_05_pressure_energy_scan.zip index 4144c2785..a27392146 100644 Binary files a/docs/auto_tutorials/basics/plot_05_pressure_energy_scan.zip and b/docs/auto_tutorials/basics/plot_05_pressure_energy_scan.zip differ diff --git a/docs/auto_tutorials/basics/plot_06_material_choices.codeobj.json b/docs/auto_tutorials/basics/plot_06_material_choices.codeobj.json index 694c2ce57..4c5da334e 100644 --- a/docs/auto_tutorials/basics/plot_06_material_choices.codeobj.json +++ b/docs/auto_tutorials/basics/plot_06_material_choices.codeobj.json @@ -239,7 +239,7 @@ "is_class": true, "is_explicit": false, "module": "solprop.nonlinear.optmat_rates", - "module_short": "solprop.nonlinear.optmat_rates", + "module_short": "solprop.nonlinear", "name": "OptmatRate" }, { @@ -260,7 +260,7 @@ "is_class": false, "is_explicit": false, "module": "solprop.nonlinear.optmat_rates", - "module_short": "solprop.nonlinear.optmat_rates", + "module_short": "solprop.nonlinear", "name": "OptmatRate" } ], @@ -1368,7 +1368,7 @@ "is_class": false, "is_explicit": false, "module": "solprop.output.store", - "module_short": "solprop.output", + "module_short": "solprop.output.store", "name": "PlaneStore.metadata" }, { @@ -1575,7 +1575,7 @@ "is_class": false, "is_explicit": false, "module": "solprop.nonlinear.optmat_rates", - "module_short": "solprop.nonlinear.optmat_rates", + "module_short": "solprop.nonlinear", "name": "OptmatRate" }, { @@ -1598,7 +1598,7 @@ "is_class": false, "is_explicit": false, "module": "solprop.nonlinear.optmat_rates", - "module_short": "solprop.nonlinear.optmat_rates", + "module_short": "solprop.nonlinear", "name": "OptmatRate.maximum_field" }, { @@ -1621,7 +1621,7 @@ "is_class": false, "is_explicit": false, "module": "solprop.nonlinear.optmat_rates", - "module_short": "solprop.nonlinear.optmat_rates", + "module_short": "solprop.nonlinear", "name": "OptmatRate.optmat_model" }, { @@ -1644,7 +1644,7 @@ "is_class": false, "is_explicit": false, "module": "solprop.nonlinear.optmat_rates", - "module_short": "solprop.nonlinear.optmat_rates", + "module_short": "solprop.nonlinear", "name": "OptmatRate.status" }, { @@ -1667,7 +1667,7 @@ "is_class": false, "is_explicit": false, "module": "solprop.nonlinear.optmat_rates", - "module_short": "solprop.nonlinear.optmat_rates", + "module_short": "solprop.nonlinear", "name": "OptmatRate.threshold" }, { @@ -1690,7 +1690,7 @@ "is_class": false, "is_explicit": false, "module": "solprop.nonlinear.optmat_rates", - "module_short": "solprop.nonlinear.optmat_rates", + "module_short": "solprop.nonlinear", "name": "OptmatRate.uncertainty_factor" }, { diff --git a/docs/auto_tutorials/basics/plot_06_material_choices.ipynb b/docs/auto_tutorials/basics/plot_06_material_choices.ipynb index c109bc5c2..d29235416 100644 --- a/docs/auto_tutorials/basics/plot_06_material_choices.ipynb +++ b/docs/auto_tutorials/basics/plot_06_material_choices.ipynb @@ -4,7 +4,7 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "\n# Compare material choices\n\nThe default material data for gases, solids, Raman responses and ionisation\nrates come from the curated library optmat\n([SEP 3](../../dev/seps/archive/sep-0003-optmat-materials.html)): a run\nwith no ``materials=`` takes ``MaterialSelection()``, optmat's recommended model of\neach family. This tutorial shows how to see what a run resolved, how to declare a\ndifferent material, and how to tell which part of the physics a change touches.\n\nIt resolves and inspects optmat's models of argon, their identities, statuses and\nuncertainty; modifies one of them with optmat's own ``with_parameters``; and runs a\nshort, 0.4 mm argon capillary with plasma (ten fixed steps, about a second each) once\non the defaults and once for each of three *declared* changes: another gas index,\na modified ionisation rate and a wall of the caller's own Sellmeier glass. A table\nseparates what each change touched -- dispersion, electronic (Kerr) coefficient, Raman\nresponse, ionisation rate and solid index -- by reading the runs' material manifests.\n\nThe guide is far too short to be a physical prediction; it ranks the changes. See\n:doc:`/guide/media/materials` for the full selection guide.\n" + "\n# Compare material choices\n\nThe default material data for gases, solids, Raman responses and ionisation\nrates come from the curated library optmat\n([SEP 3](https://github.com/LupoLab/solprop/blob/main/docs/dev/seps/archive/sep-0003-optmat-materials.md)):\na run\nwith no ``materials=`` takes ``MaterialSelection()``, optmat's recommended model of\neach family. This tutorial shows how to see what a run resolved, how to declare a\ndifferent material, and how to tell which part of the physics a change touches.\n\nIt resolves and inspects optmat's models of argon, their identities, statuses and\nuncertainty; modifies one of them with optmat's own ``with_parameters``; and runs a\nshort, 0.4 mm argon capillary with plasma (ten fixed steps, about a second each) once\non the defaults and once for each of three *declared* changes: another gas index,\na modified ionisation rate and a wall of the caller's own Sellmeier glass. A table\nseparates what each change touched -- dispersion, electronic (Kerr) coefficient, Raman\nresponse, ionisation rate and solid index -- by reading the runs' material manifests.\n\nThe guide is far too short to be a physical prediction; it ranks the changes. See\n:doc:`/guide/media/materials` for the full selection guide.\n" ] }, { @@ -132,7 +132,7 @@ "name": "python", "nbconvert_exporter": "python", "pygments_lexer": "ipython3", - "version": "3.14.7" + "version": "3.14.6" } }, "nbformat": 4, diff --git a/docs/auto_tutorials/basics/plot_06_material_choices.py b/docs/auto_tutorials/basics/plot_06_material_choices.py index 74d8996c0..69fa1ab29 100644 --- a/docs/auto_tutorials/basics/plot_06_material_choices.py +++ b/docs/auto_tutorials/basics/plot_06_material_choices.py @@ -8,7 +8,8 @@ The default material data for gases, solids, Raman responses and ionisation rates come from the curated library optmat -(`SEP 3 <../../dev/seps/archive/sep-0003-optmat-materials.html>`_): a run +(`SEP 3 `_): +a run with no ``materials=`` takes ``MaterialSelection()``, optmat's recommended model of each family. This tutorial shows how to see what a run resolved, how to declare a different material, and how to tell which part of the physics a change touches. diff --git a/docs/auto_tutorials/basics/plot_06_material_choices.py.md5 b/docs/auto_tutorials/basics/plot_06_material_choices.py.md5 index e9e68ca1b..7a3ad35fa 100644 --- a/docs/auto_tutorials/basics/plot_06_material_choices.py.md5 +++ b/docs/auto_tutorials/basics/plot_06_material_choices.py.md5 @@ -1 +1 @@ -e2f9eb85bce3bbe5d9dc1839dd3b2bca \ No newline at end of file +092057de99e6c7c7e7d6b77e06b9dfa4 \ No newline at end of file diff --git a/docs/auto_tutorials/basics/plot_06_material_choices.rst b/docs/auto_tutorials/basics/plot_06_material_choices.rst index 282bd9fb2..db7e47f18 100644 --- a/docs/auto_tutorials/basics/plot_06_material_choices.rst +++ b/docs/auto_tutorials/basics/plot_06_material_choices.rst @@ -23,7 +23,8 @@ Compare material choices The default material data for gases, solids, Raman responses and ionisation rates come from the curated library optmat -(`SEP 3 <../../dev/seps/archive/sep-0003-optmat-materials.html>`_): a run +(`SEP 3 `_): +a run with no ``materials=`` takes ``MaterialSelection()``, optmat's recommended model of each family. This tutorial shows how to see what a run resolved, how to declare a different material, and how to tell which part of the physics a change touches. @@ -39,7 +40,7 @@ response, ionisation rate and solid index -- by reading the runs' material manif The guide is far too short to be a physical prediction; it ranks the changes. See :doc:`/guide/media/materials` for the full selection guide. -.. GENERATED FROM PYTHON SOURCE LINES 27-47 +.. GENERATED FROM PYTHON SOURCE LINES 28-48 .. code-block:: Python @@ -70,7 +71,7 @@ The guide is far too short to be a physical prediction; it ranks the changes. Se -.. GENERATED FROM PYTHON SOURCE LINES 48-54 +.. GENERATED FROM PYTHON SOURCE LINES 49-55 What optmat resolves -------------------- @@ -79,7 +80,7 @@ and a SHA-256 digest that changes whenever the model's numbers can. The status s how far optmat vouches for it (``validated``, ``provisional``, ``untested``, ``comparison`` for a curated alternative, ``user`` for a caller's override). -.. GENERATED FROM PYTHON SOURCE LINES 54-68 +.. GENERATED FROM PYTHON SOURCE LINES 55-69 .. code-block:: Python @@ -106,8 +107,8 @@ how far optmat vouches for it (``validated``, ``provisional``, ``untested``, .. code-block:: none gas_refractive fit/Ar validated f0efa785e42d - equation_of_state eos/Ar validated 85ee5c2688ac - transport transport/Ar validated 1054ed95ba27 + equation_of_state eos/Ar validated 15a9b124e6ee + transport transport/Ar validated 314ba33bd217 gas_hyperpolarizability hyperpolarizability/Ar validated d15700d61f7a solid fit/SiO2 validated 93e901d77368 @@ -117,7 +118,7 @@ how far optmat vouches for it (``validated``, ``provisional``, ``untested``, -.. GENERATED FROM PYTHON SOURCE LINES 69-75 +.. GENERATED FROM PYTHON SOURCE LINES 70-76 A quick experiment ------------------ @@ -126,7 +127,7 @@ result is status ``user``, lists what changed and keeps the digest of the model started from, so a run's record says exactly what was declared. Here argon's rate with two effective electrons in place of one: twice the rate, at every field. -.. GENERATED FROM PYTHON SOURCE LINES 75-83 +.. GENERATED FROM PYTHON SOURCE LINES 76-84 .. code-block:: Python @@ -152,7 +153,7 @@ with two effective electrons in place of one: twice the rate, at every field. -.. GENERATED FROM PYTHON SOURCE LINES 84-90 +.. GENERATED FROM PYTHON SOURCE LINES 85-91 One short run, four material choices ------------------------------------ @@ -161,7 +162,7 @@ A 50 um-radius, 0.4 mm argon capillary at 1 bar with a 30 fs, 100 uJ pulse at witness. The absorbing collar is lengthened, as the witness's was, because the default collar of so short a guide is too stiff for ten fixed steps. -.. GENERATED FROM PYTHON SOURCE LINES 90-136 +.. GENERATED FROM PYTHON SOURCE LINES 91-137 .. code-block:: Python @@ -218,7 +219,7 @@ default collar of so short a guide is too stiff for ten fixed steps. -.. GENERATED FROM PYTHON SOURCE LINES 137-144 +.. GENERATED FROM PYTHON SOURCE LINES 138-145 Which family each change touched -------------------------------- @@ -228,7 +229,7 @@ kind by kind says which family a change reached, whatever the change was declare as. The other columns are the change of the output: the spectrum's relative change in norm, and the ionised fraction and peak power at the exit. -.. GENERATED FROM PYTHON SOURCE LINES 144-202 +.. GENERATED FROM PYTHON SOURCE LINES 145-203 .. code-block:: Python @@ -312,7 +313,7 @@ in norm, and the ionised fraction and peak power at the exit. -.. GENERATED FROM PYTHON SOURCE LINES 203-210 +.. GENERATED FROM PYTHON SOURCE LINES 204-211 The rate dominates: twice the rate raises the ionised fraction at the exit by three quarters and changes the spectrum by more than ten per cent. Another gas index @@ -322,7 +323,7 @@ reaches the wall of a 50 um core in 0.4 mm. The figure compares the exit spectra. -.. GENERATED FROM PYTHON SOURCE LINES 210-234 +.. GENERATED FROM PYTHON SOURCE LINES 211-235 .. code-block:: Python @@ -363,12 +364,12 @@ The figure compares the exit spectra. .. code-block:: none - run time 5.5 s + run time 0.5 s -.. GENERATED FROM PYTHON SOURCE LINES 235-242 +.. GENERATED FROM PYTHON SOURCE LINES 236-243 Related reading --------------- @@ -381,7 +382,7 @@ For a paced propagation lesson, return to .. rst-class:: sphx-glr-timing - **Total running time of the script:** (0 minutes 5.566 seconds) + **Total running time of the script:** (0 minutes 0.567 seconds) .. _sphx_glr_download_auto_tutorials_basics_plot_06_material_choices.py: diff --git a/docs/auto_tutorials/basics/plot_06_material_choices.zip b/docs/auto_tutorials/basics/plot_06_material_choices.zip index 2f39279ca..21c8724b0 100644 Binary files a/docs/auto_tutorials/basics/plot_06_material_choices.zip and b/docs/auto_tutorials/basics/plot_06_material_choices.zip differ diff --git a/docs/auto_tutorials/basics/plot_07_time_window.codeobj.json b/docs/auto_tutorials/basics/plot_07_time_window.codeobj.json index e812b9f92..e5f741f9b 100644 --- a/docs/auto_tutorials/basics/plot_07_time_window.codeobj.json +++ b/docs/auto_tutorials/basics/plot_07_time_window.codeobj.json @@ -1288,8 +1288,8 @@ { "is_class": false, "is_explicit": false, - "module": "solprop.output.schema", - "module_short": "solprop.output", + "module": "solprop.output.store", + "module_short": "solprop.output.store", "name": "PlaneStore.outcome" }, { diff --git a/docs/auto_tutorials/basics/plot_07_time_window.ipynb b/docs/auto_tutorials/basics/plot_07_time_window.ipynb index 4f20fb037..894035cf2 100644 --- a/docs/auto_tutorials/basics/plot_07_time_window.ipynb +++ b/docs/auto_tutorials/basics/plot_07_time_window.ipynb @@ -157,7 +157,7 @@ "name": "python", "nbconvert_exporter": "python", "pygments_lexer": "ipython3", - "version": "3.14.5" + "version": "3.14.6" } }, "nbformat": 4, diff --git a/docs/auto_tutorials/basics/plot_07_time_window.rst b/docs/auto_tutorials/basics/plot_07_time_window.rst index 4876557a1..324655804 100644 --- a/docs/auto_tutorials/basics/plot_07_time_window.rst +++ b/docs/auto_tutorials/basics/plot_07_time_window.rst @@ -307,11 +307,11 @@ needs 3 ps. .. code-block:: none window points wall (s) removed exit energy against 8 ps - 0.5 ps 384 0.12 8.4e-01 -8.7e-01 - 1.0 ps 768 0.16 2.5e-03 -2.6e-03 - 2.0 ps 1536 0.35 1.6e-03 -1.6e-03 - 3.0 ps 2048 0.36 1.5e-07 -1.6e-07 - 4.0 ps 3072 0.52 3.5e-12 -3.6e-12 + 0.5 ps 384 0.10 8.4e-01 -8.7e-01 + 1.0 ps 768 0.15 2.5e-03 -2.6e-03 + 2.0 ps 1536 0.27 1.6e-03 -1.6e-03 + 3.0 ps 2048 0.24 1.5e-07 -1.6e-07 + 4.0 ps 3072 0.33 3.5e-12 -3.7e-12 @@ -367,7 +367,7 @@ check, ``absorber=False`` the collar. .. rst-class:: sphx-glr-timing - **Total running time of the script:** (0 minutes 3.565 seconds) + **Total running time of the script:** (0 minutes 2.347 seconds) .. _sphx_glr_download_auto_tutorials_basics_plot_07_time_window.py: diff --git a/docs/auto_tutorials/basics/plot_07_time_window.zip b/docs/auto_tutorials/basics/plot_07_time_window.zip index a500f2829..5c51a7a6f 100644 Binary files a/docs/auto_tutorials/basics/plot_07_time_window.zip and b/docs/auto_tutorials/basics/plot_07_time_window.zip differ diff --git a/docs/auto_tutorials/capillaries/images/sphx_glr_plot_03_gas_flow_001.png b/docs/auto_tutorials/capillaries/images/sphx_glr_plot_03_gas_flow_001.png index b150d14c6..eda04b91f 100644 Binary files a/docs/auto_tutorials/capillaries/images/sphx_glr_plot_03_gas_flow_001.png and b/docs/auto_tutorials/capillaries/images/sphx_glr_plot_03_gas_flow_001.png differ diff --git a/docs/auto_tutorials/capillaries/images/sphx_glr_plot_03_gas_flow_002.png b/docs/auto_tutorials/capillaries/images/sphx_glr_plot_03_gas_flow_002.png index b5a4423a1..9d2cbd2a5 100644 Binary files a/docs/auto_tutorials/capillaries/images/sphx_glr_plot_03_gas_flow_002.png and b/docs/auto_tutorials/capillaries/images/sphx_glr_plot_03_gas_flow_002.png differ diff --git a/docs/auto_tutorials/capillaries/images/sphx_glr_plot_03_gas_flow_003.png b/docs/auto_tutorials/capillaries/images/sphx_glr_plot_03_gas_flow_003.png index 0ceaa1683..4738d08ec 100644 Binary files a/docs/auto_tutorials/capillaries/images/sphx_glr_plot_03_gas_flow_003.png and b/docs/auto_tutorials/capillaries/images/sphx_glr_plot_03_gas_flow_003.png differ diff --git a/docs/auto_tutorials/capillaries/images/sphx_glr_plot_04_air_mixture_001.png b/docs/auto_tutorials/capillaries/images/sphx_glr_plot_04_air_mixture_001.png index ddc4df699..3cf99c3a9 100644 Binary files a/docs/auto_tutorials/capillaries/images/sphx_glr_plot_04_air_mixture_001.png and b/docs/auto_tutorials/capillaries/images/sphx_glr_plot_04_air_mixture_001.png differ diff --git a/docs/auto_tutorials/capillaries/images/sphx_glr_plot_05_envelope_plasma_001.png b/docs/auto_tutorials/capillaries/images/sphx_glr_plot_05_envelope_plasma_001.png index 69181b2be..a6ec5403a 100644 Binary files a/docs/auto_tutorials/capillaries/images/sphx_glr_plot_05_envelope_plasma_001.png and b/docs/auto_tutorials/capillaries/images/sphx_glr_plot_05_envelope_plasma_001.png differ diff --git a/docs/auto_tutorials/capillaries/images/sphx_glr_plot_06_vector_raman_001.png b/docs/auto_tutorials/capillaries/images/sphx_glr_plot_06_vector_raman_001.png index 51cbdf429..a43c01162 100644 Binary files a/docs/auto_tutorials/capillaries/images/sphx_glr_plot_06_vector_raman_001.png and b/docs/auto_tutorials/capillaries/images/sphx_glr_plot_06_vector_raman_001.png differ diff --git a/docs/auto_tutorials/capillaries/images/sphx_glr_plot_09_vector_wall_002.png b/docs/auto_tutorials/capillaries/images/sphx_glr_plot_09_vector_wall_002.png index 0a1bef78b..7da60b7c4 100644 Binary files a/docs/auto_tutorials/capillaries/images/sphx_glr_plot_09_vector_wall_002.png and b/docs/auto_tutorials/capillaries/images/sphx_glr_plot_09_vector_wall_002.png differ diff --git a/docs/auto_tutorials/capillaries/images/sphx_glr_plot_10_low_call_stepping_001.png b/docs/auto_tutorials/capillaries/images/sphx_glr_plot_10_low_call_stepping_001.png index 28a1e57f0..3ef5b410d 100644 Binary files a/docs/auto_tutorials/capillaries/images/sphx_glr_plot_10_low_call_stepping_001.png and b/docs/auto_tutorials/capillaries/images/sphx_glr_plot_10_low_call_stepping_001.png differ diff --git a/docs/auto_tutorials/capillaries/images/thumb/sphx_glr_plot_03_gas_flow_thumb.png b/docs/auto_tutorials/capillaries/images/thumb/sphx_glr_plot_03_gas_flow_thumb.png index 909db86b1..c6faa52c9 100644 Binary files a/docs/auto_tutorials/capillaries/images/thumb/sphx_glr_plot_03_gas_flow_thumb.png and b/docs/auto_tutorials/capillaries/images/thumb/sphx_glr_plot_03_gas_flow_thumb.png differ diff --git a/docs/auto_tutorials/capillaries/images/thumb/sphx_glr_plot_04_air_mixture_thumb.png b/docs/auto_tutorials/capillaries/images/thumb/sphx_glr_plot_04_air_mixture_thumb.png index ae7664502..607538a26 100644 Binary files a/docs/auto_tutorials/capillaries/images/thumb/sphx_glr_plot_04_air_mixture_thumb.png and b/docs/auto_tutorials/capillaries/images/thumb/sphx_glr_plot_04_air_mixture_thumb.png differ diff --git a/docs/auto_tutorials/capillaries/images/thumb/sphx_glr_plot_05_envelope_plasma_thumb.png b/docs/auto_tutorials/capillaries/images/thumb/sphx_glr_plot_05_envelope_plasma_thumb.png index 42bc90466..eca812604 100644 Binary files a/docs/auto_tutorials/capillaries/images/thumb/sphx_glr_plot_05_envelope_plasma_thumb.png and b/docs/auto_tutorials/capillaries/images/thumb/sphx_glr_plot_05_envelope_plasma_thumb.png differ diff --git a/docs/auto_tutorials/capillaries/images/thumb/sphx_glr_plot_06_vector_raman_thumb.png b/docs/auto_tutorials/capillaries/images/thumb/sphx_glr_plot_06_vector_raman_thumb.png index 673dde12a..5c8e89f16 100644 Binary files a/docs/auto_tutorials/capillaries/images/thumb/sphx_glr_plot_06_vector_raman_thumb.png and b/docs/auto_tutorials/capillaries/images/thumb/sphx_glr_plot_06_vector_raman_thumb.png differ diff --git a/docs/auto_tutorials/capillaries/images/thumb/sphx_glr_plot_10_low_call_stepping_thumb.png b/docs/auto_tutorials/capillaries/images/thumb/sphx_glr_plot_10_low_call_stepping_thumb.png index ff7f45acd..eb8fda8cb 100644 Binary files a/docs/auto_tutorials/capillaries/images/thumb/sphx_glr_plot_10_low_call_stepping_thumb.png and b/docs/auto_tutorials/capillaries/images/thumb/sphx_glr_plot_10_low_call_stepping_thumb.png differ diff --git a/docs/auto_tutorials/capillaries/plot_03_gas_flow.codeobj.json b/docs/auto_tutorials/capillaries/plot_03_gas_flow.codeobj.json index c7fcbe7e0..5650195b8 100644 --- a/docs/auto_tutorials/capillaries/plot_03_gas_flow.codeobj.json +++ b/docs/auto_tutorials/capillaries/plot_03_gas_flow.codeobj.json @@ -28,6 +28,34 @@ "module_short": "solprop", "name": "Displayed" }, + { + "is_class": true, + "is_explicit": false, + "module": "solprop.profiles", + "module_short": "solprop.profiles", + "name": "ZProfile" + }, + { + "is_class": true, + "is_explicit": false, + "module": "solprop", + "module_short": "solprop", + "name": "ZProfile" + }, + { + "is_class": true, + "is_explicit": false, + "module": "typing", + "module_short": "typing", + "name": "Protocol" + }, + { + "is_class": true, + "is_explicit": false, + "module": "typing", + "module_short": "typing", + "name": "Generic" + }, { "is_class": false, "is_explicit": false, @@ -65,6 +93,34 @@ "module_short": "solprop", "name": "Displayed.from_stages" }, + { + "is_class": true, + "is_explicit": false, + "module": "solprop.profiles", + "module_short": "solprop.profiles", + "name": "ZProfile.from_stages" + }, + { + "is_class": true, + "is_explicit": false, + "module": "solprop", + "module_short": "solprop", + "name": "ZProfile.from_stages" + }, + { + "is_class": true, + "is_explicit": false, + "module": "typing", + "module_short": "typing", + "name": "Protocol.from_stages" + }, + { + "is_class": true, + "is_explicit": false, + "module": "typing", + "module_short": "typing", + "name": "Generic.from_stages" + }, { "is_class": false, "is_explicit": false, diff --git a/docs/auto_tutorials/capillaries/plot_03_gas_flow.ipynb b/docs/auto_tutorials/capillaries/plot_03_gas_flow.ipynb index cc4b71903..c724f5721 100644 --- a/docs/auto_tutorials/capillaries/plot_03_gas_flow.ipynb +++ b/docs/auto_tutorials/capillaries/plot_03_gas_flow.ipynb @@ -85,7 +85,7 @@ "name": "python", "nbconvert_exporter": "python", "pygments_lexer": "ipython3", - "version": "3.14.5" + "version": "3.14.6" } }, "nbformat": 4, diff --git a/docs/auto_tutorials/capillaries/plot_03_gas_flow.rst b/docs/auto_tutorials/capillaries/plot_03_gas_flow.rst index 732478099..3dc743738 100644 --- a/docs/auto_tutorials/capillaries/plot_03_gas_flow.rst +++ b/docs/auto_tutorials/capillaries/plot_03_gas_flow.rst @@ -191,7 +191,7 @@ For a paced propagation lesson, return to .. rst-class:: sphx-glr-timing - **Total running time of the script:** (0 minutes 0.095 seconds) + **Total running time of the script:** (0 minutes 0.111 seconds) .. _sphx_glr_download_auto_tutorials_capillaries_plot_03_gas_flow.py: diff --git a/docs/auto_tutorials/capillaries/plot_03_gas_flow.zip b/docs/auto_tutorials/capillaries/plot_03_gas_flow.zip index f5e284a0a..7f3526303 100644 Binary files a/docs/auto_tutorials/capillaries/plot_03_gas_flow.zip and b/docs/auto_tutorials/capillaries/plot_03_gas_flow.zip differ diff --git a/docs/auto_tutorials/capillaries/plot_04_air_mixture.ipynb b/docs/auto_tutorials/capillaries/plot_04_air_mixture.ipynb index f458c4a38..3862a7954 100644 --- a/docs/auto_tutorials/capillaries/plot_04_air_mixture.ipynb +++ b/docs/auto_tutorials/capillaries/plot_04_air_mixture.ipynb @@ -114,7 +114,7 @@ "name": "python", "nbconvert_exporter": "python", "pygments_lexer": "ipython3", - "version": "3.14.5" + "version": "3.14.6" } }, "nbformat": 4, diff --git a/docs/auto_tutorials/capillaries/plot_04_air_mixture.rst b/docs/auto_tutorials/capillaries/plot_04_air_mixture.rst index 814518a48..d59052271 100644 --- a/docs/auto_tutorials/capillaries/plot_04_air_mixture.rst +++ b/docs/auto_tutorials/capillaries/plot_04_air_mixture.rst @@ -119,7 +119,7 @@ The default fractions are divided by 0.9996 because carbon dioxide is omitted. .. code-block:: none - MaterialRangeWarning: N2+O2+Ar: optmat's Raman response raman_response/N2+O2+Ar@300K,800nm is used outside its validated density range (5.396 to 5.396 amagat). optmat: density above 2.07 amagat, where the lines overlap: their mixing is not modelled (TC-527, TC-688) + MaterialRangeWarning: N2+O2+Ar: optmat's Raman response raman_response/N2+O2+Ar@300K,800nm is used outside its validated density range (5.396 to 5.396 amagat). optmat: density above 2.07 amagat, where the lines overlap: their mixing is not modelled @@ -186,9 +186,9 @@ with_mixture rebuilds those coefficients while sharing rates, geometry and input .. code-block:: none - MaterialRangeWarning: N2+O2+Ar: optmat's Raman response raman_response/N2+O2+Ar@300K,800nm is used outside its validated density range (5.396 to 5.396 amagat). optmat: density above 2.07 amagat, where the lines overlap: their mixing is not modelled (TC-527, TC-688) - MaterialRangeWarning: N2+O2+Ar: optmat's Raman response raman_response/N2+O2+Ar@300K,800nm is used outside its validated density range (5.396 to 5.396 amagat). optmat: density above 2.07 amagat, where the lines overlap: their mixing is not modelled (TC-527, TC-688) - MaterialRangeWarning: N2+O2+Ar: optmat's Raman response raman_response/N2+O2+Ar@300K,800nm is used outside its validated density range (5.396 to 5.396 amagat). optmat: density above 2.07 amagat, where the lines overlap: their mixing is not modelled (TC-527, TC-688) + MaterialRangeWarning: N2+O2+Ar: optmat's Raman response raman_response/N2+O2+Ar@300K,800nm is used outside its validated density range (5.396 to 5.396 amagat). optmat: density above 2.07 amagat, where the lines overlap: their mixing is not modelled + MaterialRangeWarning: N2+O2+Ar: optmat's Raman response raman_response/N2+O2+Ar@300K,800nm is used outside its validated density range (5.396 to 5.396 amagat). optmat: density above 2.07 amagat, where the lines overlap: their mixing is not modelled + MaterialRangeWarning: N2+O2+Ar: optmat's Raman response raman_response/N2+O2+Ar@300K,800nm is used outside its validated density range (5.396 to 5.396 amagat). optmat: density above 2.07 amagat, where the lines overlap: their mixing is not modelled @@ -229,8 +229,8 @@ Its units follow P_R(t) = eps0 rho_N2 E(t) integral h(t-t') E(t')^2 dt'. .. code-block:: none Oxygen Raman omitted by the explicit raman=('N2',) selection. - with_mixture translation times (s): [0.11414074990898371, 0.10931341699324548, 0.11484987498261034] - Complete example and three-point sweep: 2.126 s + with_mixture translation times (s): [0.12389149994123727, 0.11254504101816565, 0.11838695802725852] + Complete example and three-point sweep: 1.813 s @@ -247,7 +247,7 @@ For a paced propagation lesson, return to .. rst-class:: sphx-glr-timing - **Total running time of the script:** (0 minutes 2.202 seconds) + **Total running time of the script:** (0 minutes 1.890 seconds) .. _sphx_glr_download_auto_tutorials_capillaries_plot_04_air_mixture.py: diff --git a/docs/auto_tutorials/capillaries/plot_04_air_mixture.zip b/docs/auto_tutorials/capillaries/plot_04_air_mixture.zip index 83f19d92a..54adce796 100644 Binary files a/docs/auto_tutorials/capillaries/plot_04_air_mixture.zip and b/docs/auto_tutorials/capillaries/plot_04_air_mixture.zip differ diff --git a/docs/auto_tutorials/capillaries/plot_05_envelope_plasma.rst b/docs/auto_tutorials/capillaries/plot_05_envelope_plasma.rst index 41474fa32..ec33e0b85 100644 --- a/docs/auto_tutorials/capillaries/plot_05_envelope_plasma.rst +++ b/docs/auto_tutorials/capillaries/plot_05_envelope_plasma.rst @@ -146,7 +146,7 @@ Fractions are evaluated at the end of each local pulse at every saved plane. .. code-block:: none Final population discrepancy: 0.004% - Complete example: 4.651 s + Complete example: 0.856 s @@ -163,7 +163,7 @@ For a paced propagation lesson, return to .. rst-class:: sphx-glr-timing - **Total running time of the script:** (0 minutes 4.774 seconds) + **Total running time of the script:** (0 minutes 0.888 seconds) .. _sphx_glr_download_auto_tutorials_capillaries_plot_05_envelope_plasma.py: diff --git a/docs/auto_tutorials/capillaries/plot_05_envelope_plasma.zip b/docs/auto_tutorials/capillaries/plot_05_envelope_plasma.zip index 16932e910..870744a65 100644 Binary files a/docs/auto_tutorials/capillaries/plot_05_envelope_plasma.zip and b/docs/auto_tutorials/capillaries/plot_05_envelope_plasma.zip differ diff --git a/docs/auto_tutorials/capillaries/plot_06_vector_raman.ipynb b/docs/auto_tutorials/capillaries/plot_06_vector_raman.ipynb index 262cfebaf..3d18d9821 100644 --- a/docs/auto_tutorials/capillaries/plot_06_vector_raman.ipynb +++ b/docs/auto_tutorials/capillaries/plot_06_vector_raman.ipynb @@ -42,7 +42,7 @@ "name": "python", "nbconvert_exporter": "python", "pygments_lexer": "ipython3", - "version": "3.14.5" + "version": "3.14.6" } }, "nbformat": 4, diff --git a/docs/auto_tutorials/capillaries/plot_06_vector_raman.rst b/docs/auto_tutorials/capillaries/plot_06_vector_raman.rst index bad505c84..c9ce23d92 100644 --- a/docs/auto_tutorials/capillaries/plot_06_vector_raman.rst +++ b/docs/auto_tutorials/capillaries/plot_06_vector_raman.rst @@ -94,7 +94,7 @@ no spontaneous Raman noise or complex modal basis is introduced. .. code-block:: none - MaterialRangeWarning: H2: optmat's Raman response raman_response/H2@293.15K,800nm is used outside its validated density range (0.3722 to 0.3722 amagat). optmat: density below 0.94 amagat, where the motion of the molecules sets the widths: the Dicke terms are capped at the Doppler widths (TC-688) + MaterialRangeWarning: H2: optmat's Raman response raman_response/H2@293.15K,800nm is used outside its validated density range (0.3722 to 0.3722 amagat). optmat: density below 0.94 amagat, where the motion of the molecules sets the widths: the Dicke terms are capped at the Doppler widths @@ -111,7 +111,7 @@ For a paced propagation lesson, return to .. rst-class:: sphx-glr-timing - **Total running time of the script:** (0 minutes 0.163 seconds) + **Total running time of the script:** (0 minutes 0.081 seconds) .. _sphx_glr_download_auto_tutorials_capillaries_plot_06_vector_raman.py: diff --git a/docs/auto_tutorials/capillaries/plot_06_vector_raman.zip b/docs/auto_tutorials/capillaries/plot_06_vector_raman.zip index 92a9d6cd3..314e06d46 100644 Binary files a/docs/auto_tutorials/capillaries/plot_06_vector_raman.zip and b/docs/auto_tutorials/capillaries/plot_06_vector_raman.zip differ diff --git a/docs/auto_tutorials/capillaries/plot_07_coherent_wall.ipynb b/docs/auto_tutorials/capillaries/plot_07_coherent_wall.ipynb index 82a6f093f..4ea0af965 100644 --- a/docs/auto_tutorials/capillaries/plot_07_coherent_wall.ipynb +++ b/docs/auto_tutorials/capillaries/plot_07_coherent_wall.ipynb @@ -96,7 +96,7 @@ "name": "python", "nbconvert_exporter": "python", "pygments_lexer": "ipython3", - "version": "3.14.7" + "version": "3.14.6" } }, "nbformat": 4, diff --git a/docs/auto_tutorials/capillaries/plot_07_coherent_wall.rst b/docs/auto_tutorials/capillaries/plot_07_coherent_wall.rst index 2bf04700f..c98581d32 100644 --- a/docs/auto_tutorials/capillaries/plot_07_coherent_wall.rst +++ b/docs/auto_tutorials/capillaries/plot_07_coherent_wall.rst @@ -305,7 +305,7 @@ For a paced propagation lesson, return to .. rst-class:: sphx-glr-timing - **Total running time of the script:** (0 minutes 5.497 seconds) + **Total running time of the script:** (0 minutes 0.385 seconds) .. _sphx_glr_download_auto_tutorials_capillaries_plot_07_coherent_wall.py: diff --git a/docs/auto_tutorials/capillaries/plot_07_coherent_wall.zip b/docs/auto_tutorials/capillaries/plot_07_coherent_wall.zip index 7122e5cb2..c0969d2e2 100644 Binary files a/docs/auto_tutorials/capillaries/plot_07_coherent_wall.zip and b/docs/auto_tutorials/capillaries/plot_07_coherent_wall.zip differ diff --git a/docs/auto_tutorials/capillaries/plot_08_coherent_wall_taper.codeobj.json b/docs/auto_tutorials/capillaries/plot_08_coherent_wall_taper.codeobj.json index 4aec53fbf..40a5ba461 100644 --- a/docs/auto_tutorials/capillaries/plot_08_coherent_wall_taper.codeobj.json +++ b/docs/auto_tutorials/capillaries/plot_08_coherent_wall_taper.codeobj.json @@ -3,7 +3,7 @@ { "is_class": true, "is_explicit": false, - "module": "solprop.modes.capillary", + "module": "solprop.modes.wall", "module_short": "solprop.modes", "name": "CoherentWall" }, @@ -1217,7 +1217,7 @@ "is_class": false, "is_explicit": false, "module": "solprop.output.store", - "module_short": "solprop.output", + "module_short": "solprop.output.store", "name": "PlaneStore.metadata" }, { diff --git a/docs/auto_tutorials/capillaries/plot_08_coherent_wall_taper.ipynb b/docs/auto_tutorials/capillaries/plot_08_coherent_wall_taper.ipynb index 705bb19c6..657aba445 100644 --- a/docs/auto_tutorials/capillaries/plot_08_coherent_wall_taper.ipynb +++ b/docs/auto_tutorials/capillaries/plot_08_coherent_wall_taper.ipynb @@ -96,7 +96,7 @@ "name": "python", "nbconvert_exporter": "python", "pygments_lexer": "ipython3", - "version": "3.14.7" + "version": "3.14.6" } }, "nbformat": 4, diff --git a/docs/auto_tutorials/capillaries/plot_08_coherent_wall_taper.rst b/docs/auto_tutorials/capillaries/plot_08_coherent_wall_taper.rst index 299f2a4f0..ec9694bcb 100644 --- a/docs/auto_tutorials/capillaries/plot_08_coherent_wall_taper.rst +++ b/docs/auto_tutorials/capillaries/plot_08_coherent_wall_taper.rst @@ -289,7 +289,7 @@ For a paced introduction to propagation, start with the .. rst-class:: sphx-glr-timing - **Total running time of the script:** (0 minutes 8.791 seconds) + **Total running time of the script:** (0 minutes 1.804 seconds) .. _sphx_glr_download_auto_tutorials_capillaries_plot_08_coherent_wall_taper.py: diff --git a/docs/auto_tutorials/capillaries/plot_08_coherent_wall_taper.zip b/docs/auto_tutorials/capillaries/plot_08_coherent_wall_taper.zip index 94889c368..8b4057cdf 100644 Binary files a/docs/auto_tutorials/capillaries/plot_08_coherent_wall_taper.zip and b/docs/auto_tutorials/capillaries/plot_08_coherent_wall_taper.zip differ diff --git a/docs/auto_tutorials/capillaries/plot_09_vector_wall.codeobj.json b/docs/auto_tutorials/capillaries/plot_09_vector_wall.codeobj.json index c8a0c5da5..627c6b0fc 100644 --- a/docs/auto_tutorials/capillaries/plot_09_vector_wall.codeobj.json +++ b/docs/auto_tutorials/capillaries/plot_09_vector_wall.codeobj.json @@ -19,7 +19,7 @@ { "is_class": true, "is_explicit": false, - "module": "solprop.modes.capillary", + "module": "solprop.modes.wall", "module_short": "solprop.modes", "name": "CoherentWall" }, @@ -231,7 +231,7 @@ "is_class": true, "is_explicit": false, "module": "solprop.modes.fill", - "module_short": "solprop.modes", + "module_short": "solprop.modes.fill", "name": "GasFillMixin" }, { @@ -730,8 +730,8 @@ { "is_class": false, "is_explicit": false, - "module": "solprop.modes.capillary", - "module_short": "solprop.modes", + "module": "solprop.modes.wall", + "module_short": "solprop.modes.wall", "name": "VectorWallOperator" }, { @@ -1792,7 +1792,7 @@ "is_class": false, "is_explicit": false, "module": "solprop.output.store", - "module_short": "solprop.output", + "module_short": "solprop.output.store", "name": "PlaneStore.metadata" }, { diff --git a/docs/auto_tutorials/capillaries/plot_09_vector_wall.ipynb b/docs/auto_tutorials/capillaries/plot_09_vector_wall.ipynb index 212a18f77..4c532e68f 100644 --- a/docs/auto_tutorials/capillaries/plot_09_vector_wall.ipynb +++ b/docs/auto_tutorials/capillaries/plot_09_vector_wall.ipynb @@ -96,7 +96,7 @@ "name": "python", "nbconvert_exporter": "python", "pygments_lexer": "ipython3", - "version": "3.14.7" + "version": "3.14.6" } }, "nbformat": 4, diff --git a/docs/auto_tutorials/capillaries/plot_09_vector_wall.rst b/docs/auto_tutorials/capillaries/plot_09_vector_wall.rst index 18048e52e..445266e3f 100644 --- a/docs/auto_tutorials/capillaries/plot_09_vector_wall.rst +++ b/docs/auto_tutorials/capillaries/plot_09_vector_wall.rst @@ -343,7 +343,7 @@ For a paced propagation lesson, return to .. rst-class:: sphx-glr-timing - **Total running time of the script:** (0 minutes 8.775 seconds) + **Total running time of the script:** (0 minutes 0.920 seconds) .. _sphx_glr_download_auto_tutorials_capillaries_plot_09_vector_wall.py: diff --git a/docs/auto_tutorials/capillaries/plot_09_vector_wall.zip b/docs/auto_tutorials/capillaries/plot_09_vector_wall.zip index 32b64ccee..270692476 100644 Binary files a/docs/auto_tutorials/capillaries/plot_09_vector_wall.zip and b/docs/auto_tutorials/capillaries/plot_09_vector_wall.zip differ diff --git a/docs/auto_tutorials/capillaries/plot_10_low_call_stepping.codeobj.json b/docs/auto_tutorials/capillaries/plot_10_low_call_stepping.codeobj.json index 0e93e5ac5..227bc7c17 100644 --- a/docs/auto_tutorials/capillaries/plot_10_low_call_stepping.codeobj.json +++ b/docs/auto_tutorials/capillaries/plot_10_low_call_stepping.codeobj.json @@ -77,8 +77,8 @@ { "is_class": false, "is_explicit": false, - "module": "solprop.output.schema", - "module_short": "solprop.output", + "module": "solprop.output.store", + "module_short": "solprop.output.store", "name": "PlaneStore.fields" }, { @@ -714,8 +714,8 @@ { "is_class": false, "is_explicit": false, - "module": "solprop.output.schema", - "module_short": "solprop.output.schema", + "module": "solprop.output.store", + "module_short": "solprop.output.store", "name": "PlaneStore.planes" }, { @@ -1116,8 +1116,8 @@ { "is_class": false, "is_explicit": false, - "module": "solprop.output.schema", - "module_short": "solprop.output", + "module": "solprop.output.store", + "module_short": "solprop.output.store", "name": "PlaneStore.fields" }, { diff --git a/docs/auto_tutorials/capillaries/plot_10_low_call_stepping.ipynb b/docs/auto_tutorials/capillaries/plot_10_low_call_stepping.ipynb index 50fd9a37a..bf3bb27c6 100644 --- a/docs/auto_tutorials/capillaries/plot_10_low_call_stepping.ipynb +++ b/docs/auto_tutorials/capillaries/plot_10_low_call_stepping.ipynb @@ -85,7 +85,7 @@ "name": "python", "nbconvert_exporter": "python", "pygments_lexer": "ipython3", - "version": "3.14.5" + "version": "3.14.6" } }, "nbformat": 4, diff --git a/docs/auto_tutorials/capillaries/plot_10_low_call_stepping.rst b/docs/auto_tutorials/capillaries/plot_10_low_call_stepping.rst index 0d96b2ee1..478c0190f 100644 --- a/docs/auto_tutorials/capillaries/plot_10_low_call_stepping.rst +++ b/docs/auto_tutorials/capillaries/plot_10_low_call_stepping.rst @@ -186,7 +186,7 @@ For a paced propagation lesson, return to .. rst-class:: sphx-glr-timing - **Total running time of the script:** (0 minutes 3.189 seconds) + **Total running time of the script:** (0 minutes 3.278 seconds) .. _sphx_glr_download_auto_tutorials_capillaries_plot_10_low_call_stepping.py: diff --git a/docs/auto_tutorials/capillaries/plot_10_low_call_stepping.zip b/docs/auto_tutorials/capillaries/plot_10_low_call_stepping.zip index d027f2002..7108031df 100644 Binary files a/docs/auto_tutorials/capillaries/plot_10_low_call_stepping.zip and b/docs/auto_tutorials/capillaries/plot_10_low_call_stepping.zip differ diff --git a/docs/auto_tutorials/capillaries/plot_11_dispersive_kerr.codeobj.json b/docs/auto_tutorials/capillaries/plot_11_dispersive_kerr.codeobj.json index c62d02690..f83605ace 100644 --- a/docs/auto_tutorials/capillaries/plot_11_dispersive_kerr.codeobj.json +++ b/docs/auto_tutorials/capillaries/plot_11_dispersive_kerr.codeobj.json @@ -128,7 +128,7 @@ "is_class": true, "is_explicit": false, "module": "solprop.modes.fill", - "module_short": "solprop.modes", + "module_short": "solprop.modes.fill", "name": "GasFillMixin" }, { diff --git a/docs/auto_tutorials/capillaries/plot_11_dispersive_kerr.ipynb b/docs/auto_tutorials/capillaries/plot_11_dispersive_kerr.ipynb index c71897720..01807f57a 100644 --- a/docs/auto_tutorials/capillaries/plot_11_dispersive_kerr.ipynb +++ b/docs/auto_tutorials/capillaries/plot_11_dispersive_kerr.ipynb @@ -4,7 +4,7 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "\n# A frequency-dependent Kerr response\n\nA gas's electronic third-order response is not one number. Its hyperpolarisability\ndepends on all four frequencies of each mixing quartet, and it rises towards the\nultraviolet: argon's Kerr coefficient at 267 nm is twice its value at 800 nm. The\ndefault ``carrier-kerr`` policy freezes it at the run's carrier and uses that value for\nevery process the cubic drives. Two opt-in policies of\n[SEP 6](../../dev/seps/archive/sep-0006-dispersive-nonlinearity.html) evaluate\noptmat's whole fit instead, at the absolute frequencies of every quartet, in one\nbroadband polarisation (:doc:`/guide/media/dispersive-kerr`):\n\n- ``\"gas-polynomial\"`` evaluates the gas dispersion polynomial itself;\n- ``\"symmetric-kerr\"`` factorises its Kerr diagonal symmetrically over the four legs, a\n cheaper approximation that is exact for self-phase modulation.\n\nThis tutorial compares the three on the two demonstration cases of SEP 6:\n\n1. **Deep-ultraviolet four-wave mixing in argon.** A 400 nm pump and an 800 nm seed\n make 266.7 nm, $\\omega_s = 2\\omega_p - \\omega_i$, in a capillary at its\n linear phase-matching pressure. The declared active band lies inside argon's\n electronic-response band edge, so the dispersive evaluators are supported or\n bounded throughout.\n2. **Resonant dispersive-wave emission in helium**, the case of\n :doc:`/introduction/lessons/plot_01_rdw`. Here the field reaches below\n helium's two-photon resonance at a 120.3 nm fundamental, where no off-resonant\n model is valid. The\n dispersive evaluators still run it, with every leg held at the edge of helium's\n data, and the band beyond the edge labelled *best effort*. The comparison is a\n **sensitivity study of the vacuum-ultraviolet legs, not a qualified prediction**.\n\n**What to look for.** In argon, the dispersive responses make the signal grow faster\nat first -- the generating quartet's coefficient is 4 % above the pump's Kerr value --\nbut saturate earlier and lower, because the signal's cross-phase modulation by the pump\nis 25 % stronger than the carrier model says, which detunes the phase matching. The two\ndispersive evaluators agree to about one per cent. In helium, the soliton's own\nself-phase modulation is identical under all three, so the pump dynamics barely move;\nthe dispersive wave's energy changes by about a tenth and its centre wavelength by\nabout a nanometre.\n\n**What is approximate.** Only the electronic response differs between the runs: the\nlinear operator, the pulse, the grid, the plasma and the backend are the same. Every\nrun here selects ``backend=\"native\"``, the carrier runs too, for a like-for-like\ncomparison: the dispersive responses run on ``numpy_ref`` and the native backend's CPU\nbuild.\n" + "\n# A frequency-dependent Kerr response\n\nA gas's electronic third-order response is not one number. Its hyperpolarisability\ndepends on all four frequencies of each mixing quartet, and it rises towards the\nultraviolet: argon's Kerr coefficient at 267 nm is twice its value at 800 nm. The\ndefault ``carrier-kerr`` policy freezes it at the run's carrier and uses that value for\nevery process the cubic drives. Two opt-in policies of\n[SEP 6](https://github.com/LupoLab/solprop/blob/main/docs/dev/seps/archive/sep-0006-dispersive-nonlinearity.md)\nevaluate optmat's whole fit instead, at the absolute frequencies of every quartet,\nin one broadband polarisation (:doc:`/guide/media/dispersive-kerr`):\n\n- ``\"gas-polynomial\"`` evaluates the gas dispersion polynomial itself;\n- ``\"symmetric-kerr\"`` factorises its Kerr diagonal symmetrically over the four legs, a\n cheaper approximation that is exact for self-phase modulation.\n\nThis tutorial compares the three on the two demonstration cases of SEP 6:\n\n1. **Deep-ultraviolet four-wave mixing in argon.** A 400 nm pump and an 800 nm seed\n make 266.7 nm, $\\omega_s = 2\\omega_p - \\omega_i$, in a capillary at its\n linear phase-matching pressure. The declared active band lies inside argon's\n electronic-response band edge, so the dispersive evaluators are supported or\n bounded throughout.\n2. **Resonant dispersive-wave emission in helium**, the case of\n :doc:`/introduction/lessons/plot_01_rdw`. Here the field reaches below\n helium's two-photon resonance at a 120.3 nm fundamental, where no off-resonant\n model is valid. The\n dispersive evaluators still run it, with every leg held at the edge of helium's\n data, and the band beyond the edge labelled *best effort*. The comparison is a\n **sensitivity study of the vacuum-ultraviolet legs, not a qualified prediction**.\n\n**What to look for.** In argon, the dispersive responses make the signal grow faster\nat first -- the generating quartet's coefficient is 4 % above the pump's Kerr value --\nbut saturate earlier and lower, because the signal's cross-phase modulation by the pump\nis 25 % stronger than the carrier model says, which detunes the phase matching. The two\ndispersive evaluators agree to about one per cent. In helium, the soliton's own\nself-phase modulation is identical under all three, so the pump dynamics barely move;\nthe dispersive wave's energy changes by about a tenth and its centre wavelength by\nabout a nanometre.\n\n**What is approximate.** Only the electronic response differs between the runs: the\nlinear operator, the pulse, the grid, the plasma and the backend are the same. Every\nrun here selects ``backend=\"native\"``, the carrier runs too, for a like-for-like\ncomparison: the dispersive responses run on ``numpy_ref`` and the native backend's CPU\nbuild.\n" ] }, { @@ -218,7 +218,7 @@ "name": "python", "nbconvert_exporter": "python", "pygments_lexer": "ipython3", - "version": "3.14.7" + "version": "3.14.6" } }, "nbformat": 4, diff --git a/docs/auto_tutorials/capillaries/plot_11_dispersive_kerr.py b/docs/auto_tutorials/capillaries/plot_11_dispersive_kerr.py index e3ef6ff3e..b18d2d3a3 100644 --- a/docs/auto_tutorials/capillaries/plot_11_dispersive_kerr.py +++ b/docs/auto_tutorials/capillaries/plot_11_dispersive_kerr.py @@ -11,9 +11,9 @@ ultraviolet: argon's Kerr coefficient at 267 nm is twice its value at 800 nm. The default ``carrier-kerr`` policy freezes it at the run's carrier and uses that value for every process the cubic drives. Two opt-in policies of -`SEP 6 <../../dev/seps/archive/sep-0006-dispersive-nonlinearity.html>`_ evaluate -optmat's whole fit instead, at the absolute frequencies of every quartet, in one -broadband polarisation (:doc:`/guide/media/dispersive-kerr`): +`SEP 6 `_ +evaluate optmat's whole fit instead, at the absolute frequencies of every quartet, +in one broadband polarisation (:doc:`/guide/media/dispersive-kerr`): - ``"gas-polynomial"`` evaluates the gas dispersion polynomial itself; - ``"symmetric-kerr"`` factorises its Kerr diagonal symmetrically over the four legs, a diff --git a/docs/auto_tutorials/capillaries/plot_11_dispersive_kerr.py.md5 b/docs/auto_tutorials/capillaries/plot_11_dispersive_kerr.py.md5 index 391b18273..ff80fce68 100644 --- a/docs/auto_tutorials/capillaries/plot_11_dispersive_kerr.py.md5 +++ b/docs/auto_tutorials/capillaries/plot_11_dispersive_kerr.py.md5 @@ -1 +1 @@ -4c270b02ab1f119833fc0b02f2ce8284 \ No newline at end of file +570e74ed25fcfe5f290202d8978c3d2b \ No newline at end of file diff --git a/docs/auto_tutorials/capillaries/plot_11_dispersive_kerr.rst b/docs/auto_tutorials/capillaries/plot_11_dispersive_kerr.rst index 6a8cbec50..acc11ff41 100644 --- a/docs/auto_tutorials/capillaries/plot_11_dispersive_kerr.rst +++ b/docs/auto_tutorials/capillaries/plot_11_dispersive_kerr.rst @@ -26,9 +26,9 @@ depends on all four frequencies of each mixing quartet, and it rises towards the ultraviolet: argon's Kerr coefficient at 267 nm is twice its value at 800 nm. The default ``carrier-kerr`` policy freezes it at the run's carrier and uses that value for every process the cubic drives. Two opt-in policies of -`SEP 6 <../../dev/seps/archive/sep-0006-dispersive-nonlinearity.html>`_ evaluate -optmat's whole fit instead, at the absolute frequencies of every quartet, in one -broadband polarisation (:doc:`/guide/media/dispersive-kerr`): +`SEP 6 `_ +evaluate optmat's whole fit instead, at the absolute frequencies of every quartet, +in one broadband polarisation (:doc:`/guide/media/dispersive-kerr`): - ``"gas-polynomial"`` evaluates the gas dispersion polynomial itself; - ``"symmetric-kerr"`` factorises its Kerr diagonal symmetrically over the four legs, a @@ -599,7 +599,7 @@ Runtime and reproducibility .. code-block:: none - 33 s on native + 4 s on native @@ -616,7 +616,7 @@ For a paced propagation lesson, return to .. rst-class:: sphx-glr-timing - **Total running time of the script:** (0 minutes 33.218 seconds) + **Total running time of the script:** (0 minutes 4.485 seconds) .. _sphx_glr_download_auto_tutorials_capillaries_plot_11_dispersive_kerr.py: diff --git a/docs/auto_tutorials/capillaries/plot_11_dispersive_kerr.zip b/docs/auto_tutorials/capillaries/plot_11_dispersive_kerr.zip index cb7c7b453..689e218cb 100644 Binary files a/docs/auto_tutorials/capillaries/plot_11_dispersive_kerr.zip and b/docs/auto_tutorials/capillaries/plot_11_dispersive_kerr.zip differ diff --git a/docs/auto_tutorials/free_space/images/sphx_glr_plot_01_radial_001.png b/docs/auto_tutorials/free_space/images/sphx_glr_plot_01_radial_001.png index edb2580d6..a7ebd4463 100644 Binary files a/docs/auto_tutorials/free_space/images/sphx_glr_plot_01_radial_001.png and b/docs/auto_tutorials/free_space/images/sphx_glr_plot_01_radial_001.png differ diff --git a/docs/auto_tutorials/free_space/images/sphx_glr_plot_02_cartesian_001.png b/docs/auto_tutorials/free_space/images/sphx_glr_plot_02_cartesian_001.png index 45584acc7..7ca9fa26a 100644 Binary files a/docs/auto_tutorials/free_space/images/sphx_glr_plot_02_cartesian_001.png and b/docs/auto_tutorials/free_space/images/sphx_glr_plot_02_cartesian_001.png differ diff --git a/docs/auto_tutorials/free_space/images/sphx_glr_plot_05_low_storage_001.png b/docs/auto_tutorials/free_space/images/sphx_glr_plot_05_low_storage_001.png index 4e2f1529c..73c918c8f 100644 Binary files a/docs/auto_tutorials/free_space/images/sphx_glr_plot_05_low_storage_001.png and b/docs/auto_tutorials/free_space/images/sphx_glr_plot_05_low_storage_001.png differ diff --git a/docs/auto_tutorials/free_space/images/sphx_glr_plot_06_four_wave_mixing_scan_001.png b/docs/auto_tutorials/free_space/images/sphx_glr_plot_06_four_wave_mixing_scan_001.png index 368a45db8..a8821f38c 100644 Binary files a/docs/auto_tutorials/free_space/images/sphx_glr_plot_06_four_wave_mixing_scan_001.png and b/docs/auto_tutorials/free_space/images/sphx_glr_plot_06_four_wave_mixing_scan_001.png differ diff --git a/docs/auto_tutorials/free_space/images/sphx_glr_plot_06_four_wave_mixing_scan_002.png b/docs/auto_tutorials/free_space/images/sphx_glr_plot_06_four_wave_mixing_scan_002.png index 7c02eed2b..d43cd156a 100644 Binary files a/docs/auto_tutorials/free_space/images/sphx_glr_plot_06_four_wave_mixing_scan_002.png and b/docs/auto_tutorials/free_space/images/sphx_glr_plot_06_four_wave_mixing_scan_002.png differ diff --git a/docs/auto_tutorials/free_space/images/sphx_glr_plot_06_four_wave_mixing_scan_003.png b/docs/auto_tutorials/free_space/images/sphx_glr_plot_06_four_wave_mixing_scan_003.png index 6761fab27..c678c9700 100644 Binary files a/docs/auto_tutorials/free_space/images/sphx_glr_plot_06_four_wave_mixing_scan_003.png and b/docs/auto_tutorials/free_space/images/sphx_glr_plot_06_four_wave_mixing_scan_003.png differ diff --git a/docs/auto_tutorials/free_space/images/sphx_glr_plot_07_far_field_statistics_001.png b/docs/auto_tutorials/free_space/images/sphx_glr_plot_07_far_field_statistics_001.png index 83a44f555..c5b0cd3bc 100644 Binary files a/docs/auto_tutorials/free_space/images/sphx_glr_plot_07_far_field_statistics_001.png and b/docs/auto_tutorials/free_space/images/sphx_glr_plot_07_far_field_statistics_001.png differ diff --git a/docs/auto_tutorials/free_space/images/sphx_glr_plot_07_far_field_statistics_002.png b/docs/auto_tutorials/free_space/images/sphx_glr_plot_07_far_field_statistics_002.png index 8074efeee..272b6da43 100644 Binary files a/docs/auto_tutorials/free_space/images/sphx_glr_plot_07_far_field_statistics_002.png and b/docs/auto_tutorials/free_space/images/sphx_glr_plot_07_far_field_statistics_002.png differ diff --git a/docs/auto_tutorials/free_space/images/sphx_glr_plot_07_far_field_statistics_003.png b/docs/auto_tutorials/free_space/images/sphx_glr_plot_07_far_field_statistics_003.png index 5dd7cbb0d..cd0a06999 100644 Binary files a/docs/auto_tutorials/free_space/images/sphx_glr_plot_07_far_field_statistics_003.png and b/docs/auto_tutorials/free_space/images/sphx_glr_plot_07_far_field_statistics_003.png differ diff --git a/docs/auto_tutorials/free_space/images/sphx_glr_plot_07_far_field_statistics_004.png b/docs/auto_tutorials/free_space/images/sphx_glr_plot_07_far_field_statistics_004.png index a984c26f3..1a8bc80a4 100644 Binary files a/docs/auto_tutorials/free_space/images/sphx_glr_plot_07_far_field_statistics_004.png and b/docs/auto_tutorials/free_space/images/sphx_glr_plot_07_far_field_statistics_004.png differ diff --git a/docs/auto_tutorials/free_space/images/sphx_glr_plot_08_radial_capillary_coupling_005.png b/docs/auto_tutorials/free_space/images/sphx_glr_plot_08_radial_capillary_coupling_005.png index ac3e579be..452dca4f3 100644 Binary files a/docs/auto_tutorials/free_space/images/sphx_glr_plot_08_radial_capillary_coupling_005.png and b/docs/auto_tutorials/free_space/images/sphx_glr_plot_08_radial_capillary_coupling_005.png differ diff --git a/docs/auto_tutorials/free_space/images/sphx_glr_plot_10_radial_kerr_001.png b/docs/auto_tutorials/free_space/images/sphx_glr_plot_10_radial_kerr_001.png index ae3a86281..d96500f8f 100644 Binary files a/docs/auto_tutorials/free_space/images/sphx_glr_plot_10_radial_kerr_001.png and b/docs/auto_tutorials/free_space/images/sphx_glr_plot_10_radial_kerr_001.png differ diff --git a/docs/auto_tutorials/free_space/images/sphx_glr_plot_11_radial_filament_001.png b/docs/auto_tutorials/free_space/images/sphx_glr_plot_11_radial_filament_001.png index d6458f228..2b63b406f 100644 Binary files a/docs/auto_tutorials/free_space/images/sphx_glr_plot_11_radial_filament_001.png and b/docs/auto_tutorials/free_space/images/sphx_glr_plot_11_radial_filament_001.png differ diff --git a/docs/auto_tutorials/free_space/images/sphx_glr_plot_12_crossing_beams_kerr_001.png b/docs/auto_tutorials/free_space/images/sphx_glr_plot_12_crossing_beams_kerr_001.png index bfeb3c248..1ba1bebed 100644 Binary files a/docs/auto_tutorials/free_space/images/sphx_glr_plot_12_crossing_beams_kerr_001.png and b/docs/auto_tutorials/free_space/images/sphx_glr_plot_12_crossing_beams_kerr_001.png differ diff --git a/docs/auto_tutorials/free_space/images/sphx_glr_plot_12_crossing_beams_kerr_002.png b/docs/auto_tutorials/free_space/images/sphx_glr_plot_12_crossing_beams_kerr_002.png index adf4a0c66..9fc50b142 100644 Binary files a/docs/auto_tutorials/free_space/images/sphx_glr_plot_12_crossing_beams_kerr_002.png and b/docs/auto_tutorials/free_space/images/sphx_glr_plot_12_crossing_beams_kerr_002.png differ diff --git a/docs/auto_tutorials/free_space/images/thumb/sphx_glr_plot_01_radial_thumb.png b/docs/auto_tutorials/free_space/images/thumb/sphx_glr_plot_01_radial_thumb.png index 264e1d2b1..f216c8557 100644 Binary files a/docs/auto_tutorials/free_space/images/thumb/sphx_glr_plot_01_radial_thumb.png and b/docs/auto_tutorials/free_space/images/thumb/sphx_glr_plot_01_radial_thumb.png differ diff --git a/docs/auto_tutorials/free_space/images/thumb/sphx_glr_plot_02_cartesian_thumb.png b/docs/auto_tutorials/free_space/images/thumb/sphx_glr_plot_02_cartesian_thumb.png index 3c9021f6f..6b02c23bb 100644 Binary files a/docs/auto_tutorials/free_space/images/thumb/sphx_glr_plot_02_cartesian_thumb.png and b/docs/auto_tutorials/free_space/images/thumb/sphx_glr_plot_02_cartesian_thumb.png differ diff --git a/docs/auto_tutorials/free_space/images/thumb/sphx_glr_plot_05_low_storage_thumb.png b/docs/auto_tutorials/free_space/images/thumb/sphx_glr_plot_05_low_storage_thumb.png index 7786480c8..180faa5e4 100644 Binary files a/docs/auto_tutorials/free_space/images/thumb/sphx_glr_plot_05_low_storage_thumb.png and b/docs/auto_tutorials/free_space/images/thumb/sphx_glr_plot_05_low_storage_thumb.png differ diff --git a/docs/auto_tutorials/free_space/images/thumb/sphx_glr_plot_06_four_wave_mixing_scan_thumb.png b/docs/auto_tutorials/free_space/images/thumb/sphx_glr_plot_06_four_wave_mixing_scan_thumb.png index b3e7b87e5..97d0deea2 100644 Binary files a/docs/auto_tutorials/free_space/images/thumb/sphx_glr_plot_06_four_wave_mixing_scan_thumb.png and b/docs/auto_tutorials/free_space/images/thumb/sphx_glr_plot_06_four_wave_mixing_scan_thumb.png differ diff --git a/docs/auto_tutorials/free_space/images/thumb/sphx_glr_plot_07_far_field_statistics_thumb.png b/docs/auto_tutorials/free_space/images/thumb/sphx_glr_plot_07_far_field_statistics_thumb.png index abb1ca0d7..417555997 100644 Binary files a/docs/auto_tutorials/free_space/images/thumb/sphx_glr_plot_07_far_field_statistics_thumb.png and b/docs/auto_tutorials/free_space/images/thumb/sphx_glr_plot_07_far_field_statistics_thumb.png differ diff --git a/docs/auto_tutorials/free_space/images/thumb/sphx_glr_plot_10_radial_kerr_thumb.png b/docs/auto_tutorials/free_space/images/thumb/sphx_glr_plot_10_radial_kerr_thumb.png index 6e1927ebd..b61d56b16 100644 Binary files a/docs/auto_tutorials/free_space/images/thumb/sphx_glr_plot_10_radial_kerr_thumb.png and b/docs/auto_tutorials/free_space/images/thumb/sphx_glr_plot_10_radial_kerr_thumb.png differ diff --git a/docs/auto_tutorials/free_space/images/thumb/sphx_glr_plot_11_radial_filament_thumb.png b/docs/auto_tutorials/free_space/images/thumb/sphx_glr_plot_11_radial_filament_thumb.png index 704e8814b..28d67ce01 100644 Binary files a/docs/auto_tutorials/free_space/images/thumb/sphx_glr_plot_11_radial_filament_thumb.png and b/docs/auto_tutorials/free_space/images/thumb/sphx_glr_plot_11_radial_filament_thumb.png differ diff --git a/docs/auto_tutorials/free_space/images/thumb/sphx_glr_plot_12_crossing_beams_kerr_thumb.png b/docs/auto_tutorials/free_space/images/thumb/sphx_glr_plot_12_crossing_beams_kerr_thumb.png index cf2e7f26b..4a77f28f2 100644 Binary files a/docs/auto_tutorials/free_space/images/thumb/sphx_glr_plot_12_crossing_beams_kerr_thumb.png and b/docs/auto_tutorials/free_space/images/thumb/sphx_glr_plot_12_crossing_beams_kerr_thumb.png differ diff --git a/docs/auto_tutorials/free_space/plot_01_radial.ipynb b/docs/auto_tutorials/free_space/plot_01_radial.ipynb index 4b0b7b156..61ef83780 100644 --- a/docs/auto_tutorials/free_space/plot_01_radial.ipynb +++ b/docs/auto_tutorials/free_space/plot_01_radial.ipynb @@ -96,7 +96,7 @@ "name": "python", "nbconvert_exporter": "python", "pygments_lexer": "ipython3", - "version": "3.14.5" + "version": "3.14.6" } }, "nbformat": 4, diff --git a/docs/auto_tutorials/free_space/plot_01_radial.rst b/docs/auto_tutorials/free_space/plot_01_radial.rst index 73f916bfb..545eea803 100644 --- a/docs/auto_tutorials/free_space/plot_01_radial.rst +++ b/docs/auto_tutorials/free_space/plot_01_radial.rst @@ -236,7 +236,7 @@ For a paced propagation lesson, return to .. rst-class:: sphx-glr-timing - **Total running time of the script:** (0 minutes 0.252 seconds) + **Total running time of the script:** (0 minutes 0.269 seconds) .. _sphx_glr_download_auto_tutorials_free_space_plot_01_radial.py: diff --git a/docs/auto_tutorials/free_space/plot_01_radial.zip b/docs/auto_tutorials/free_space/plot_01_radial.zip index 8075d132e..3229bbc92 100644 Binary files a/docs/auto_tutorials/free_space/plot_01_radial.zip and b/docs/auto_tutorials/free_space/plot_01_radial.zip differ diff --git a/docs/auto_tutorials/free_space/plot_02_cartesian.codeobj.json b/docs/auto_tutorials/free_space/plot_02_cartesian.codeobj.json index acdaa5f96..92db8fbe3 100644 --- a/docs/auto_tutorials/free_space/plot_02_cartesian.codeobj.json +++ b/docs/auto_tutorials/free_space/plot_02_cartesian.codeobj.json @@ -202,7 +202,7 @@ { "is_class": true, "is_explicit": false, - "module": "solprop.driver.simulation", + "module": "solprop.driver.settings", "module_short": "solprop.driver", "name": "SimulationSettings" }, @@ -769,8 +769,8 @@ { "is_class": false, "is_explicit": false, - "module": "solprop.output.schema", - "module_short": "solprop.output", + "module": "solprop.output.store", + "module_short": "solprop.output.store", "name": "PlaneStore.fields" }, { @@ -813,7 +813,7 @@ { "is_class": false, "is_explicit": false, - "module": "solprop.driver.simulation", + "module": "solprop.driver.settings", "module_short": "solprop.driver", "name": "SimulationSettings" }, diff --git a/docs/auto_tutorials/free_space/plot_02_cartesian.ipynb b/docs/auto_tutorials/free_space/plot_02_cartesian.ipynb index 80147627e..0c68a0455 100644 --- a/docs/auto_tutorials/free_space/plot_02_cartesian.ipynb +++ b/docs/auto_tutorials/free_space/plot_02_cartesian.ipynb @@ -60,7 +60,7 @@ "name": "python", "nbconvert_exporter": "python", "pygments_lexer": "ipython3", - "version": "3.14.5" + "version": "3.14.6" } }, "nbformat": 4, diff --git a/docs/auto_tutorials/free_space/plot_02_cartesian.rst b/docs/auto_tutorials/free_space/plot_02_cartesian.rst index 2d5be6db8..ef020fec2 100644 --- a/docs/auto_tutorials/free_space/plot_02_cartesian.rst +++ b/docs/auto_tutorials/free_space/plot_02_cartesian.rst @@ -122,7 +122,7 @@ For a paced propagation lesson, return to .. rst-class:: sphx-glr-timing - **Total running time of the script:** (0 minutes 1.017 seconds) + **Total running time of the script:** (0 minutes 0.317 seconds) .. _sphx_glr_download_auto_tutorials_free_space_plot_02_cartesian.py: diff --git a/docs/auto_tutorials/free_space/plot_02_cartesian.zip b/docs/auto_tutorials/free_space/plot_02_cartesian.zip index ed05c578f..13962cae0 100644 Binary files a/docs/auto_tutorials/free_space/plot_02_cartesian.zip and b/docs/auto_tutorials/free_space/plot_02_cartesian.zip differ diff --git a/docs/auto_tutorials/free_space/plot_03_line.codeobj.json b/docs/auto_tutorials/free_space/plot_03_line.codeobj.json index a9b6744a8..47914e09c 100644 --- a/docs/auto_tutorials/free_space/plot_03_line.codeobj.json +++ b/docs/auto_tutorials/free_space/plot_03_line.codeobj.json @@ -304,7 +304,7 @@ { "is_class": true, "is_explicit": false, - "module": "solprop.driver.simulation", + "module": "solprop.driver.settings", "module_short": "solprop.driver", "name": "SimulationSettings" }, @@ -1006,8 +1006,8 @@ { "is_class": false, "is_explicit": false, - "module": "solprop.output.schema", - "module_short": "solprop.output", + "module": "solprop.output.store", + "module_short": "solprop.output.store", "name": "PlaneStore.fields" }, { @@ -1050,7 +1050,7 @@ { "is_class": false, "is_explicit": false, - "module": "solprop.driver.simulation", + "module": "solprop.driver.settings", "module_short": "solprop.driver", "name": "SimulationSettings" }, diff --git a/docs/auto_tutorials/free_space/plot_03_line.ipynb b/docs/auto_tutorials/free_space/plot_03_line.ipynb index 66da43fe6..748e75b14 100644 --- a/docs/auto_tutorials/free_space/plot_03_line.ipynb +++ b/docs/auto_tutorials/free_space/plot_03_line.ipynb @@ -78,7 +78,7 @@ "name": "python", "nbconvert_exporter": "python", "pygments_lexer": "ipython3", - "version": "3.14.7" + "version": "3.14.6" } }, "nbformat": 4, diff --git a/docs/auto_tutorials/free_space/plot_03_line.rst b/docs/auto_tutorials/free_space/plot_03_line.rst index 5e63a3a25..437025a36 100644 --- a/docs/auto_tutorials/free_space/plot_03_line.rst +++ b/docs/auto_tutorials/free_space/plot_03_line.rst @@ -192,7 +192,7 @@ For a paced propagation lesson, return to .. rst-class:: sphx-glr-timing - **Total running time of the script:** (0 minutes 2.086 seconds) + **Total running time of the script:** (0 minutes 0.524 seconds) .. _sphx_glr_download_auto_tutorials_free_space_plot_03_line.py: diff --git a/docs/auto_tutorials/free_space/plot_03_line.zip b/docs/auto_tutorials/free_space/plot_03_line.zip index c467d96ad..52df19bf7 100644 Binary files a/docs/auto_tutorials/free_space/plot_03_line.zip and b/docs/auto_tutorials/free_space/plot_03_line.zip differ diff --git a/docs/auto_tutorials/free_space/plot_04_planar_hybrid.rst b/docs/auto_tutorials/free_space/plot_04_planar_hybrid.rst index 5b056cae8..3fded772a 100644 --- a/docs/auto_tutorials/free_space/plot_04_planar_hybrid.rst +++ b/docs/auto_tutorials/free_space/plot_04_planar_hybrid.rst @@ -218,7 +218,7 @@ and across y after integrating over the gap. The widths in y are the run's .. code-block:: none - ran in 0.8 s + ran in 0.3 s @@ -235,7 +235,7 @@ For a paced propagation lesson, return to .. rst-class:: sphx-glr-timing - **Total running time of the script:** (0 minutes 0.812 seconds) + **Total running time of the script:** (0 minutes 0.330 seconds) .. _sphx_glr_download_auto_tutorials_free_space_plot_04_planar_hybrid.py: diff --git a/docs/auto_tutorials/free_space/plot_04_planar_hybrid.zip b/docs/auto_tutorials/free_space/plot_04_planar_hybrid.zip index 278b60f8a..a09811566 100644 Binary files a/docs/auto_tutorials/free_space/plot_04_planar_hybrid.zip and b/docs/auto_tutorials/free_space/plot_04_planar_hybrid.zip differ diff --git a/docs/auto_tutorials/free_space/plot_05_low_storage.codeobj.json b/docs/auto_tutorials/free_space/plot_05_low_storage.codeobj.json index 3ff720341..1b1f4b21d 100644 --- a/docs/auto_tutorials/free_space/plot_05_low_storage.codeobj.json +++ b/docs/auto_tutorials/free_space/plot_05_low_storage.codeobj.json @@ -292,7 +292,7 @@ { "is_class": true, "is_explicit": false, - "module": "solprop.driver.simulation", + "module": "solprop.driver.settings", "module_short": "solprop.driver", "name": "SimulationSettings" }, diff --git a/docs/auto_tutorials/free_space/plot_05_low_storage.ipynb b/docs/auto_tutorials/free_space/plot_05_low_storage.ipynb index d18627960..fe4940513 100644 --- a/docs/auto_tutorials/free_space/plot_05_low_storage.ipynb +++ b/docs/auto_tutorials/free_space/plot_05_low_storage.ipynb @@ -150,7 +150,7 @@ "name": "python", "nbconvert_exporter": "python", "pygments_lexer": "ipython3", - "version": "3.14.5" + "version": "3.14.6" } }, "nbformat": 4, diff --git a/docs/auto_tutorials/free_space/plot_05_low_storage.rst b/docs/auto_tutorials/free_space/plot_05_low_storage.rst index 6e55a0699..10fb4f9ff 100644 --- a/docs/auto_tutorials/free_space/plot_05_low_storage.rst +++ b/docs/auto_tutorials/free_space/plot_05_low_storage.rst @@ -170,7 +170,7 @@ reused across steps, or the flow formed in every pass -- are those two computati BoundaryWarning: the fixed schedule's longest step, 1.309e-03 m, is longer than the transverse edge's read spacing, 1.227e-03 m: light could cross the edge unseen between two reads; the run is reported as coarse (SEP 40 section 5.3) BoundaryWarning: the fixed schedule's longest step, 1.309e-03 m, is longer than the transverse edge's read spacing, 1.227e-03 m: light could cross the edge unseen between two reads; the run is reported as coarse (SEP 40 section 5.3) BoundaryWarning: the fixed schedule's longest step, 1.309e-03 m, is longer than the transverse edge's read spacing, 1.227e-03 m: light could cross the edge unseen between two reads; the run is reported as coarse (SEP 40 section 5.3) - band fraction 2.123e-04, parity floor 6.8e-19 + band fraction 2.123e-04, parity floor 8.7e-19 @@ -323,7 +323,7 @@ describes calibration and replay. .. rst-class:: sphx-glr-timing - **Total running time of the script:** (0 minutes 1.216 seconds) + **Total running time of the script:** (0 minutes 0.588 seconds) .. _sphx_glr_download_auto_tutorials_free_space_plot_05_low_storage.py: diff --git a/docs/auto_tutorials/free_space/plot_05_low_storage.zip b/docs/auto_tutorials/free_space/plot_05_low_storage.zip index 9538d5b02..ccabfb246 100644 Binary files a/docs/auto_tutorials/free_space/plot_05_low_storage.zip and b/docs/auto_tutorials/free_space/plot_05_low_storage.zip differ diff --git a/docs/auto_tutorials/free_space/plot_06_four_wave_mixing_scan.codeobj.json b/docs/auto_tutorials/free_space/plot_06_four_wave_mixing_scan.codeobj.json index eefeb6184..cffc8b434 100644 --- a/docs/auto_tutorials/free_space/plot_06_four_wave_mixing_scan.codeobj.json +++ b/docs/auto_tutorials/free_space/plot_06_four_wave_mixing_scan.codeobj.json @@ -436,7 +436,7 @@ { "is_class": true, "is_explicit": false, - "module": "solprop.driver.simulation", + "module": "solprop.driver.settings", "module_short": "solprop.driver", "name": "SimulationSettings" }, @@ -1869,8 +1869,8 @@ { "is_class": false, "is_explicit": false, - "module": "solprop.output.schema", - "module_short": "solprop.output", + "module": "solprop.output.store", + "module_short": "solprop.output.store", "name": "PlaneStore.plane_field" }, { @@ -1913,7 +1913,7 @@ { "is_class": false, "is_explicit": false, - "module": "solprop.driver.simulation", + "module": "solprop.driver.runner", "module_short": "solprop.driver", "name": "SimulationRunner" }, @@ -1936,7 +1936,7 @@ { "is_class": false, "is_explicit": false, - "module": "solprop.driver.simulation", + "module": "solprop.driver.runner", "module_short": "solprop.driver", "name": "SimulationRunner.run" }, diff --git a/docs/auto_tutorials/free_space/plot_06_four_wave_mixing_scan.ipynb b/docs/auto_tutorials/free_space/plot_06_four_wave_mixing_scan.ipynb index f578074d5..1b21926ed 100644 --- a/docs/auto_tutorials/free_space/plot_06_four_wave_mixing_scan.ipynb +++ b/docs/auto_tutorials/free_space/plot_06_four_wave_mixing_scan.ipynb @@ -180,7 +180,7 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "## Related reading\n:doc:`/guide/setup/running` describes the runner, :doc:`/guide/results/output` the\nstatistics-only planes, :doc:`/guide/numerics/boundaries` the custom absorber and\nthe two lengths of a collar, and :doc:`/guide/free-space/cartesian` the one-half rule\nand the transverse safety ramp. The design is\n:doc:`SEP 22 `.\n\n" + "## Related reading\n:doc:`/guide/setup/running` describes the runner, :doc:`/guide/results/output` the\nstatistics-only planes, :doc:`/guide/numerics/boundaries` the custom absorber and\nthe two lengths of a collar, and :doc:`/guide/free-space/cartesian` the one-half rule\nand the transverse safety ramp. The design is\n[SEP 22](https://github.com/LupoLab/solprop/blob/main/docs/dev/seps/archive/sep-0022-memory-lean-spatial-execution.md).\n\n" ] } ], @@ -200,7 +200,7 @@ "name": "python", "nbconvert_exporter": "python", "pygments_lexer": "ipython3", - "version": "3.14.5" + "version": "3.14.6" } }, "nbformat": 4, diff --git a/docs/auto_tutorials/free_space/plot_06_four_wave_mixing_scan.py b/docs/auto_tutorials/free_space/plot_06_four_wave_mixing_scan.py index 3e3aa4ae8..01091ba88 100644 --- a/docs/auto_tutorials/free_space/plot_06_four_wave_mixing_scan.py +++ b/docs/auto_tutorials/free_space/plot_06_four_wave_mixing_scan.py @@ -387,4 +387,4 @@ def kx_spectrum(spatial_grid, run): # statistics-only planes, :doc:`/guide/numerics/boundaries` the custom absorber and # the two lengths of a collar, and :doc:`/guide/free-space/cartesian` the one-half rule # and the transverse safety ramp. The design is -# :doc:`SEP 22 `. +# `SEP 22 `_. diff --git a/docs/auto_tutorials/free_space/plot_06_four_wave_mixing_scan.py.md5 b/docs/auto_tutorials/free_space/plot_06_four_wave_mixing_scan.py.md5 index cf1267650..6b7e81dd0 100644 --- a/docs/auto_tutorials/free_space/plot_06_four_wave_mixing_scan.py.md5 +++ b/docs/auto_tutorials/free_space/plot_06_four_wave_mixing_scan.py.md5 @@ -1 +1 @@ -ab8f504cdd56725b5d6cb977c3623614 \ No newline at end of file +ad8956a8377f55ff5e0a6e7a49d8d67c \ No newline at end of file diff --git a/docs/auto_tutorials/free_space/plot_06_four_wave_mixing_scan.rst b/docs/auto_tutorials/free_space/plot_06_four_wave_mixing_scan.rst index d5c6c134a..2311e3732 100644 --- a/docs/auto_tutorials/free_space/plot_06_four_wave_mixing_scan.rst +++ b/docs/auto_tutorials/free_space/plot_06_four_wave_mixing_scan.rst @@ -395,7 +395,7 @@ to change it. The scan's second moment, read as a Gaussian's width, recovers it. correlation FWHM: 61.1 fs (predicted 61.2 fs) - + @@ -509,7 +509,7 @@ A relaxed check lets the coarse runs finish, so that what they hold can be read. BoundaryWarning: the fixed schedule's longest step, 1.250e-04 m, is longer than the transverse edge's read spacing, 6.250e-05 m: light could cross the edge unseen between two reads; the run is reported as coarse (SEP 40 section 5.3) 2 μm, ramp: energy fraction within K0/4 of +-2 K0: 1.37e-05 - + @@ -629,7 +629,7 @@ about a part in a million and shows the rate alone. BoundaryWarning: the fixed schedule's longest step, 1.250e-04 m, is longer than the transverse edge's read spacing, 6.250e-05 m: light could cross the edge unseen between two reads; the run is reported as coarse (SEP 40 section 5.3) BoundaryWarning: light reached the transverse edge on its y- face at z = 6.2500e-04 m: 1.41e-06 of the launch energy above its launch value, which the wall or the wrap returns (SEP 40 section 5.3) largest departure of the transmission from exp(-alpha L): 7.2e-07 - tutorial run time: 12.6 s + tutorial run time: 3.6 s @@ -642,12 +642,12 @@ Related reading statistics-only planes, :doc:`/guide/numerics/boundaries` the custom absorber and the two lengths of a collar, and :doc:`/guide/free-space/cartesian` the one-half rule and the transverse safety ramp. The design is -:doc:`SEP 22 `. +`SEP 22 `_. .. rst-class:: sphx-glr-timing - **Total running time of the script:** (0 minutes 12.755 seconds) + **Total running time of the script:** (0 minutes 3.608 seconds) .. _sphx_glr_download_auto_tutorials_free_space_plot_06_four_wave_mixing_scan.py: diff --git a/docs/auto_tutorials/free_space/plot_06_four_wave_mixing_scan.zip b/docs/auto_tutorials/free_space/plot_06_four_wave_mixing_scan.zip index 6daded39c..8d3b3fae3 100644 Binary files a/docs/auto_tutorials/free_space/plot_06_four_wave_mixing_scan.zip and b/docs/auto_tutorials/free_space/plot_06_four_wave_mixing_scan.zip differ diff --git a/docs/auto_tutorials/free_space/plot_07_far_field_statistics.codeobj.json b/docs/auto_tutorials/free_space/plot_07_far_field_statistics.codeobj.json index 1ad9d534c..028efe007 100644 --- a/docs/auto_tutorials/free_space/plot_07_far_field_statistics.codeobj.json +++ b/docs/auto_tutorials/free_space/plot_07_far_field_statistics.codeobj.json @@ -2462,7 +2462,7 @@ "is_class": false, "is_explicit": false, "module": "solprop.output.store", - "module_short": "solprop.output", + "module_short": "solprop.output.store", "name": "PlaneStore.plane_field" }, { diff --git a/docs/auto_tutorials/free_space/plot_07_far_field_statistics.ipynb b/docs/auto_tutorials/free_space/plot_07_far_field_statistics.ipynb index 7594601d3..3727077b9 100644 --- a/docs/auto_tutorials/free_space/plot_07_far_field_statistics.ipynb +++ b/docs/auto_tutorials/free_space/plot_07_far_field_statistics.ipynb @@ -191,7 +191,7 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "## Related reading\n:doc:`/guide/results/statistics` defines the far-field statistics, their two\nweightings and what each backend computes; :doc:`/guide/free-space/model` gives the\nfar-zone and Fourier-plane conditions and the paraxial error;\n:doc:`/guide/results/output` describes statistics-only planes. The design is\n:doc:`SEP 23 `.\n\n" + "## Related reading\n:doc:`/guide/results/statistics` defines the far-field statistics, their two\nweightings and what each backend computes; :doc:`/guide/free-space/model` gives the\nfar-zone and Fourier-plane conditions and the paraxial error;\n:doc:`/guide/results/output` describes statistics-only planes. The design is\n[SEP 23](https://github.com/LupoLab/solprop/blob/main/docs/dev/seps/archive/sep-0023-far-field-aperture-spectra.md).\n\n" ] } ], @@ -211,7 +211,7 @@ "name": "python", "nbconvert_exporter": "python", "pygments_lexer": "ipython3", - "version": "3.14.5" + "version": "3.14.6" } }, "nbformat": 4, diff --git a/docs/auto_tutorials/free_space/plot_07_far_field_statistics.py b/docs/auto_tutorials/free_space/plot_07_far_field_statistics.py index 2b7225d69..c90b395c1 100644 --- a/docs/auto_tutorials/free_space/plot_07_far_field_statistics.py +++ b/docs/auto_tutorials/free_space/plot_07_far_field_statistics.py @@ -529,4 +529,4 @@ def exact_fraction(profile, weighting): # weightings and what each backend computes; :doc:`/guide/free-space/model` gives the # far-zone and Fourier-plane conditions and the paraxial error; # :doc:`/guide/results/output` describes statistics-only planes. The design is -# :doc:`SEP 23 `. +# `SEP 23 `_. diff --git a/docs/auto_tutorials/free_space/plot_07_far_field_statistics.py.md5 b/docs/auto_tutorials/free_space/plot_07_far_field_statistics.py.md5 index 4a5e354c3..6ba4a448d 100644 --- a/docs/auto_tutorials/free_space/plot_07_far_field_statistics.py.md5 +++ b/docs/auto_tutorials/free_space/plot_07_far_field_statistics.py.md5 @@ -1 +1 @@ -64d54e8f5b9f1c1312a5d2b6af83def0 \ No newline at end of file +1d293d3e8782bd0f82ff88fc348026bf \ No newline at end of file diff --git a/docs/auto_tutorials/free_space/plot_07_far_field_statistics.rst b/docs/auto_tutorials/free_space/plot_07_far_field_statistics.rst index 5fa929968..4e4fde58d 100644 --- a/docs/auto_tutorials/free_space/plot_07_far_field_statistics.rst +++ b/docs/auto_tutorials/free_space/plot_07_far_field_statistics.rst @@ -372,7 +372,7 @@ statistic here weights it. .. code-block:: none - + @@ -423,7 +423,7 @@ peaks near the coherence length :math:`\pi/|\Delta k|` and falls back. coherence length pi/|dk| = 0.69 mm signal peaks at z = 0.750 mm - + @@ -640,7 +640,7 @@ to the beam spectrum needs no further normalisation. .. code-block:: none collect against the run: 6.2e-16 - from the definition against the run, largest difference in collected fraction: 2.2e-16 + from the definition against the run, largest difference in collected fraction: 1.7e-16 @@ -694,7 +694,7 @@ transmission of the exit face into air is not modelled. quadrants against the beam spectrum: 3.2e-16 towards +x 1.3721e-07 J, towards -x 1.3708e-07 J; upper 1.5409e-07 J, lower 1.2020e-07 J - exit energy 2.742885e-07 J; beam spectrum integral 2.742885e-07 J; relative difference 3.9e-15 + exit energy 2.742885e-07 J; beam spectrum integral 2.742885e-07 J; relative difference 3.3e-15 @@ -752,7 +752,7 @@ the evanescent, material and custom channels are exactly zero. energy drop 1.5701e-08 J; absorbed 1.5704e-08 J evanescent, material and custom channels: 0.0 J/m; transverse at the exit 7.6e-10 J/m - tutorial run time: 2.1 s + tutorial run time: 1.7 s @@ -765,12 +765,12 @@ Related reading weightings and what each backend computes; :doc:`/guide/free-space/model` gives the far-zone and Fourier-plane conditions and the paraxial error; :doc:`/guide/results/output` describes statistics-only planes. The design is -:doc:`SEP 23 `. +`SEP 23 `_. .. rst-class:: sphx-glr-timing - **Total running time of the script:** (0 minutes 2.134 seconds) + **Total running time of the script:** (0 minutes 1.713 seconds) .. _sphx_glr_download_auto_tutorials_free_space_plot_07_far_field_statistics.py: diff --git a/docs/auto_tutorials/free_space/plot_07_far_field_statistics.zip b/docs/auto_tutorials/free_space/plot_07_far_field_statistics.zip index 646618a50..24aff1887 100644 Binary files a/docs/auto_tutorials/free_space/plot_07_far_field_statistics.zip and b/docs/auto_tutorials/free_space/plot_07_far_field_statistics.zip differ diff --git a/docs/auto_tutorials/free_space/plot_08_radial_capillary_coupling.codeobj.json b/docs/auto_tutorials/free_space/plot_08_radial_capillary_coupling.codeobj.json index c43cdb427..a024f8f23 100644 --- a/docs/auto_tutorials/free_space/plot_08_radial_capillary_coupling.codeobj.json +++ b/docs/auto_tutorials/free_space/plot_08_radial_capillary_coupling.codeobj.json @@ -271,7 +271,7 @@ "is_class": true, "is_explicit": false, "module": "solprop.modes.fill", - "module_short": "solprop.modes", + "module_short": "solprop.modes.fill", "name": "GasFillMixin" }, { @@ -315,7 +315,7 @@ "is_class": true, "is_explicit": false, "module": "solprop.nonlinear.optmat_rates", - "module_short": "solprop.nonlinear.optmat_rates", + "module_short": "solprop.nonlinear", "name": "OptmatRate" }, { @@ -336,7 +336,7 @@ "is_class": false, "is_explicit": false, "module": "solprop.nonlinear.optmat_rates", - "module_short": "solprop.nonlinear.optmat_rates", + "module_short": "solprop.nonlinear", "name": "OptmatRate" } ], @@ -2301,7 +2301,7 @@ "is_class": false, "is_explicit": false, "module": "solprop.nonlinear.optmat_rates", - "module_short": "solprop.nonlinear.optmat_rates", + "module_short": "solprop.nonlinear", "name": "OptmatRate" }, { @@ -2850,7 +2850,7 @@ "is_class": false, "is_explicit": true, "module": "solprop.nonlinear.optmat_rates", - "module_short": "solprop.nonlinear.optmat_rates", + "module_short": "solprop.nonlinear", "name": "OptmatRate" } ], diff --git a/docs/auto_tutorials/free_space/plot_08_radial_capillary_coupling.ipynb b/docs/auto_tutorials/free_space/plot_08_radial_capillary_coupling.ipynb index d65fd8213..be9a8e8ce 100644 --- a/docs/auto_tutorials/free_space/plot_08_radial_capillary_coupling.ipynb +++ b/docs/auto_tutorials/free_space/plot_08_radial_capillary_coupling.ipynb @@ -227,7 +227,7 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "## Related reading\n:doc:`/guide/workflows/coupling` describes planes, ports, coupling models and\ntheir budgets. :doc:`/guide/free-space/model` and\n:doc:`/guide/waveguides/capillaries` describe the two propagations.\nThe design is\n:doc:`SEP 31 `.\n\n" + "## Related reading\n:doc:`/guide/workflows/coupling` describes planes, ports, coupling models and\ntheir budgets. :doc:`/guide/free-space/model` and\n:doc:`/guide/waveguides/capillaries` describe the two propagations.\nThe design is\n[SEP 31](https://github.com/LupoLab/solprop/blob/main/docs/dev/seps/archive/sep-0031-simulation-coupling.md).\n\n" ] } ], @@ -247,7 +247,7 @@ "name": "python", "nbconvert_exporter": "python", "pygments_lexer": "ipython3", - "version": "3.14.7" + "version": "3.14.6" } }, "nbformat": 4, diff --git a/docs/auto_tutorials/free_space/plot_08_radial_capillary_coupling.py b/docs/auto_tutorials/free_space/plot_08_radial_capillary_coupling.py index 019aee432..5b62231e4 100644 --- a/docs/auto_tutorials/free_space/plot_08_radial_capillary_coupling.py +++ b/docs/auto_tutorials/free_space/plot_08_radial_capillary_coupling.py @@ -516,4 +516,4 @@ # their budgets. :doc:`/guide/free-space/model` and # :doc:`/guide/waveguides/capillaries` describe the two propagations. # The design is -# :doc:`SEP 31 `. +# `SEP 31 `_. diff --git a/docs/auto_tutorials/free_space/plot_08_radial_capillary_coupling.py.md5 b/docs/auto_tutorials/free_space/plot_08_radial_capillary_coupling.py.md5 index 0f168ce8c..02581c7e4 100644 --- a/docs/auto_tutorials/free_space/plot_08_radial_capillary_coupling.py.md5 +++ b/docs/auto_tutorials/free_space/plot_08_radial_capillary_coupling.py.md5 @@ -1 +1 @@ -af0e3d832e983700d7024ab3a450eb75 \ No newline at end of file +7ba9d121a995322b642376f6e5455a4f \ No newline at end of file diff --git a/docs/auto_tutorials/free_space/plot_08_radial_capillary_coupling.rst b/docs/auto_tutorials/free_space/plot_08_radial_capillary_coupling.rst index 903da4a33..42395bb0b 100644 --- a/docs/auto_tutorials/free_space/plot_08_radial_capillary_coupling.rst +++ b/docs/auto_tutorials/free_space/plot_08_radial_capillary_coupling.rst @@ -468,7 +468,7 @@ whole entrance plane in the coupling's common measure. launched: 12.11 uJ launched share: 0.9997 of the incident energy uncaptured: 3.36 nJ - budget: 1.951e-02 of model_error 0.05 + budget: 1.818e-02 of model_error 0.05 angular: 6.250e-03 (field) incident field: cone-rule allocation (1 - cos theta*) = model_error/8 of the cone, not a measured defect, plus the tail @@ -481,12 +481,13 @@ whole entrance plane in the coupling's common measure. source metric: 1.249e-05 (field) common measure M0 against the plane's native metric contrast: n/a (model) not applied: a capillary wall is not a weakly guiding dielectric - envelope: 1.503e-03 (model) capillary-he1m-scalar-vs-leaky-marcatili-2026-10 + envelope: 1.676e-04 (field) + capillary-he1m-scalar-vs-leaky-marcatili-field-2026-11 passivity: 1.295e-08 (map) apparent gain within the model's defects, reported as a model defect exterior: zero - linear: s11 = 0.90618, s12 = 0.09229, s13 = 9.36e-04; launched 0.99953 of 12.114 uJ; budget 0.018 - Kerr: s11 = 0.88235, s12 = 0.11562, s13 = 1.68e-03; launched 0.99971 of 12.114 uJ; budget 0.020 + linear: s11 = 0.90618, s12 = 0.09229, s13 = 9.36e-04; launched 0.99953 of 12.114 uJ; budget 0.016 + Kerr: s11 = 0.88235, s12 = 0.11562, s13 = 1.68e-03; launched 0.99971 of 12.114 uJ; budget 0.018 change: ds11 = -2.383e-02, ds12 = +2.333e-02, ds13 = +7.40e-04 @@ -695,7 +696,7 @@ Both are far below anything that could affect the shares. .. code-block:: none - linear: outer-domain fluence 2.7e-27, spectral-edge content 2.4e-36 + linear: outer-domain fluence 2.7e-27, spectral-edge content 2.7e-36 Kerr: outer-domain fluence 6.1e-27, spectral-edge content 8.9e-28 @@ -782,7 +783,7 @@ through a :class:`~solprop.coupling.elements.PlanarInterface`, before giving it .. code-block:: none - run time 9.6 s + run time 1.7 s @@ -795,12 +796,12 @@ Related reading their budgets. :doc:`/guide/free-space/model` and :doc:`/guide/waveguides/capillaries` describe the two propagations. The design is -:doc:`SEP 31 `. +`SEP 31 `_. .. rst-class:: sphx-glr-timing - **Total running time of the script:** (0 minutes 9.602 seconds) + **Total running time of the script:** (0 minutes 1.664 seconds) .. _sphx_glr_download_auto_tutorials_free_space_plot_08_radial_capillary_coupling.py: diff --git a/docs/auto_tutorials/free_space/plot_08_radial_capillary_coupling.zip b/docs/auto_tutorials/free_space/plot_08_radial_capillary_coupling.zip index 09b3987eb..988e183a5 100644 Binary files a/docs/auto_tutorials/free_space/plot_08_radial_capillary_coupling.zip and b/docs/auto_tutorials/free_space/plot_08_radial_capillary_coupling.zip differ diff --git a/docs/auto_tutorials/free_space/plot_09_transverse_window.ipynb b/docs/auto_tutorials/free_space/plot_09_transverse_window.ipynb index 2f63a3855..63f585657 100644 --- a/docs/auto_tutorials/free_space/plot_09_transverse_window.ipynb +++ b/docs/auto_tutorials/free_space/plot_09_transverse_window.ipynb @@ -121,7 +121,7 @@ "name": "python", "nbconvert_exporter": "python", "pygments_lexer": "ipython3", - "version": "3.14.5" + "version": "3.14.6" } }, "nbformat": 4, diff --git a/docs/auto_tutorials/free_space/plot_09_transverse_window.rst b/docs/auto_tutorials/free_space/plot_09_transverse_window.rst index 91ecba55c..e61e4de9d 100644 --- a/docs/auto_tutorials/free_space/plot_09_transverse_window.rst +++ b/docs/auto_tutorials/free_space/plot_09_transverse_window.rst @@ -259,9 +259,9 @@ requested radius, against a wall at eight times the radius. wall status edge share field error wall time (s) 1 R off nan 1.0e-01 0.11 - 2 R warned 2.4e-05 4.0e-05 0.11 + 2 R warned 2.4e-05 4.0e-05 0.12 3 R clear 3.6e-09 8.9e-09 0.15 - 8 R reference 0.42 + 8 R reference 0.43 @@ -302,7 +302,7 @@ by name. Here it needs 2.6 radii of room: .. code-block:: none - collar in 2.6 R of room: clear, field error 1.7e-06, removed 8.2e-05 of the energy, 1.94 s + collar in 2.6 R of room: clear, field error 1.7e-06, removed 8.2e-05 of the energy, 1.95 s @@ -335,7 +335,7 @@ wider run. ``spatial_absorber=False`` removes the safety ramp, and .. rst-class:: sphx-glr-timing - **Total running time of the script:** (0 minutes 3.279 seconds) + **Total running time of the script:** (0 minutes 3.382 seconds) .. _sphx_glr_download_auto_tutorials_free_space_plot_09_transverse_window.py: diff --git a/docs/auto_tutorials/free_space/plot_09_transverse_window.zip b/docs/auto_tutorials/free_space/plot_09_transverse_window.zip index 45be82975..63cefb061 100644 Binary files a/docs/auto_tutorials/free_space/plot_09_transverse_window.zip and b/docs/auto_tutorials/free_space/plot_09_transverse_window.zip differ diff --git a/docs/auto_tutorials/free_space/plot_10_radial_kerr.codeobj.json b/docs/auto_tutorials/free_space/plot_10_radial_kerr.codeobj.json index ddbe35110..a3e48a2d0 100644 --- a/docs/auto_tutorials/free_space/plot_10_radial_kerr.codeobj.json +++ b/docs/auto_tutorials/free_space/plot_10_radial_kerr.codeobj.json @@ -817,8 +817,8 @@ { "is_class": false, "is_explicit": false, - "module": "solprop.output.schema", - "module_short": "solprop.output", + "module": "solprop.output.store", + "module_short": "solprop.output.store", "name": "PlaneStore.fields" }, { diff --git a/docs/auto_tutorials/free_space/plot_10_radial_kerr.ipynb b/docs/auto_tutorials/free_space/plot_10_radial_kerr.ipynb index d7459cdf5..b390b75df 100644 --- a/docs/auto_tutorials/free_space/plot_10_radial_kerr.ipynb +++ b/docs/auto_tutorials/free_space/plot_10_radial_kerr.ipynb @@ -78,7 +78,7 @@ "name": "python", "nbconvert_exporter": "python", "pygments_lexer": "ipython3", - "version": "3.14.5" + "version": "3.14.6" } }, "nbformat": 4, diff --git a/docs/auto_tutorials/free_space/plot_10_radial_kerr.rst b/docs/auto_tutorials/free_space/plot_10_radial_kerr.rst index 96f56a44f..c799dcc4a 100644 --- a/docs/auto_tutorials/free_space/plot_10_radial_kerr.rst +++ b/docs/auto_tutorials/free_space/plot_10_radial_kerr.rst @@ -138,7 +138,7 @@ The fluence through each plane in the argon, against the radius. .. code-block:: none Second-moment radius: 1.0000 mm -> 1.0045 mm - Complete radial Kerr example: 0.070 s + Complete radial Kerr example: 0.083 s @@ -153,7 +153,7 @@ Related reading .. rst-class:: sphx-glr-timing - **Total running time of the script:** (0 minutes 0.086 seconds) + **Total running time of the script:** (0 minutes 0.098 seconds) .. _sphx_glr_download_auto_tutorials_free_space_plot_10_radial_kerr.py: diff --git a/docs/auto_tutorials/free_space/plot_10_radial_kerr.zip b/docs/auto_tutorials/free_space/plot_10_radial_kerr.zip index 73d591e67..0c62bdcf8 100644 Binary files a/docs/auto_tutorials/free_space/plot_10_radial_kerr.zip and b/docs/auto_tutorials/free_space/plot_10_radial_kerr.zip differ diff --git a/docs/auto_tutorials/free_space/plot_11_line_beam.codeobj.json b/docs/auto_tutorials/free_space/plot_11_line_beam.codeobj.json index f41923c24..4d3b491d8 100644 --- a/docs/auto_tutorials/free_space/plot_11_line_beam.codeobj.json +++ b/docs/auto_tutorials/free_space/plot_11_line_beam.codeobj.json @@ -225,7 +225,7 @@ { "is_class": true, "is_explicit": false, - "module": "solprop.driver.simulation", + "module": "solprop.driver.settings", "module_short": "solprop.driver", "name": "SimulationSettings" }, @@ -981,7 +981,7 @@ { "is_class": false, "is_explicit": false, - "module": "solprop.driver.simulation", + "module": "solprop.driver.settings", "module_short": "solprop.driver", "name": "SimulationSettings" }, diff --git a/docs/auto_tutorials/free_space/plot_11_line_beam.ipynb b/docs/auto_tutorials/free_space/plot_11_line_beam.ipynb index c3a439777..c2b146094 100644 --- a/docs/auto_tutorials/free_space/plot_11_line_beam.ipynb +++ b/docs/auto_tutorials/free_space/plot_11_line_beam.ipynb @@ -89,7 +89,7 @@ "name": "python", "nbconvert_exporter": "python", "pygments_lexer": "ipython3", - "version": "3.14.7" + "version": "3.14.6" } }, "nbformat": 4, diff --git a/docs/auto_tutorials/free_space/plot_11_line_beam.rst b/docs/auto_tutorials/free_space/plot_11_line_beam.rst index ed65cf1b3..37aa7185f 100644 --- a/docs/auto_tutorials/free_space/plot_11_line_beam.rst +++ b/docs/auto_tutorials/free_space/plot_11_line_beam.rst @@ -188,7 +188,7 @@ The fluence across the line at the entrance and after 10 cm, in J/m^2. .. rst-class:: sphx-glr-timing - **Total running time of the script:** (0 minutes 3.240 seconds) + **Total running time of the script:** (0 minutes 0.246 seconds) .. _sphx_glr_download_auto_tutorials_free_space_plot_11_line_beam.py: diff --git a/docs/auto_tutorials/free_space/plot_11_line_beam.zip b/docs/auto_tutorials/free_space/plot_11_line_beam.zip index fc5a5f26c..729a407a6 100644 Binary files a/docs/auto_tutorials/free_space/plot_11_line_beam.zip and b/docs/auto_tutorials/free_space/plot_11_line_beam.zip differ diff --git a/docs/auto_tutorials/free_space/plot_11_radial_filament.codeobj.json b/docs/auto_tutorials/free_space/plot_11_radial_filament.codeobj.json index fceabddcb..c7ab35098 100644 --- a/docs/auto_tutorials/free_space/plot_11_radial_filament.codeobj.json +++ b/docs/auto_tutorials/free_space/plot_11_radial_filament.codeobj.json @@ -166,7 +166,7 @@ "is_class": true, "is_explicit": false, "module": "solprop.nonlinear.optmat_rates", - "module_short": "solprop.nonlinear.optmat_rates", + "module_short": "solprop.nonlinear", "name": "OptmatRate" }, { @@ -187,7 +187,7 @@ "is_class": false, "is_explicit": false, "module": "solprop.nonlinear.optmat_rates", - "module_short": "solprop.nonlinear.optmat_rates", + "module_short": "solprop.nonlinear", "name": "OptmatRate" } ], @@ -404,6 +404,13 @@ } ], "beam": [ + { + "is_class": false, + "is_explicit": false, + "module": "solprop.tools.beam", + "module_short": "solprop.tools", + "name": "BeamParams" + }, { "is_class": false, "is_explicit": false, diff --git a/docs/auto_tutorials/free_space/plot_11_radial_filament.ipynb b/docs/auto_tutorials/free_space/plot_11_radial_filament.ipynb index 620136b0d..b44a13f29 100644 --- a/docs/auto_tutorials/free_space/plot_11_radial_filament.ipynb +++ b/docs/auto_tutorials/free_space/plot_11_radial_filament.ipynb @@ -96,7 +96,7 @@ "name": "python", "nbconvert_exporter": "python", "pygments_lexer": "ipython3", - "version": "3.14.5" + "version": "3.14.6" } }, "nbformat": 4, diff --git a/docs/auto_tutorials/free_space/plot_11_radial_filament.rst b/docs/auto_tutorials/free_space/plot_11_radial_filament.rst index 89f5f3248..d2e1dabdc 100644 --- a/docs/auto_tutorials/free_space/plot_11_radial_filament.rst +++ b/docs/auto_tutorials/free_space/plot_11_radial_filament.rst @@ -193,7 +193,7 @@ conical emission. Each has its own unit; the colours here are in dB of each. .. code-block:: none - Complete filament reader example: 3.2 s + Complete filament reader example: 3.4 s @@ -208,7 +208,7 @@ and :doc:`/guide/setup/recipes` the recipe that builds this run. .. rst-class:: sphx-glr-timing - **Total running time of the script:** (0 minutes 3.213 seconds) + **Total running time of the script:** (0 minutes 3.504 seconds) .. _sphx_glr_download_auto_tutorials_free_space_plot_11_radial_filament.py: diff --git a/docs/auto_tutorials/free_space/plot_11_radial_filament.zip b/docs/auto_tutorials/free_space/plot_11_radial_filament.zip index f0eb67ff9..1dbd79cde 100644 Binary files a/docs/auto_tutorials/free_space/plot_11_radial_filament.zip and b/docs/auto_tutorials/free_space/plot_11_radial_filament.zip differ diff --git a/docs/auto_tutorials/free_space/plot_12_crossing_beams_kerr.codeobj.json b/docs/auto_tutorials/free_space/plot_12_crossing_beams_kerr.codeobj.json index c5c1e5b27..41c308689 100644 --- a/docs/auto_tutorials/free_space/plot_12_crossing_beams_kerr.codeobj.json +++ b/docs/auto_tutorials/free_space/plot_12_crossing_beams_kerr.codeobj.json @@ -202,7 +202,7 @@ { "is_class": true, "is_explicit": false, - "module": "solprop.driver.simulation", + "module": "solprop.driver.settings", "module_short": "solprop.driver", "name": "SimulationSettings" }, @@ -1240,8 +1240,8 @@ { "is_class": false, "is_explicit": false, - "module": "solprop.output.schema", - "module_short": "solprop.output", + "module": "solprop.output.store", + "module_short": "solprop.output.store", "name": "PlaneStore.n_saved" }, { @@ -1284,7 +1284,7 @@ { "is_class": false, "is_explicit": false, - "module": "solprop.driver.simulation", + "module": "solprop.driver.settings", "module_short": "solprop.driver", "name": "SimulationSettings" }, diff --git a/docs/auto_tutorials/free_space/plot_12_crossing_beams_kerr.ipynb b/docs/auto_tutorials/free_space/plot_12_crossing_beams_kerr.ipynb index 26f1691a3..21561c0c2 100644 --- a/docs/auto_tutorials/free_space/plot_12_crossing_beams_kerr.ipynb +++ b/docs/auto_tutorials/free_space/plot_12_crossing_beams_kerr.ipynb @@ -96,7 +96,7 @@ "name": "python", "nbconvert_exporter": "python", "pygments_lexer": "ipython3", - "version": "3.14.5" + "version": "3.14.6" } }, "nbformat": 4, diff --git a/docs/auto_tutorials/free_space/plot_12_crossing_beams_kerr.rst b/docs/auto_tutorials/free_space/plot_12_crossing_beams_kerr.rst index 5cb8116ac..983f4b20f 100644 --- a/docs/auto_tutorials/free_space/plot_12_crossing_beams_kerr.rst +++ b/docs/auto_tutorials/free_space/plot_12_crossing_beams_kerr.rst @@ -126,7 +126,7 @@ meet at 0.4 mm / tan(5 mrad) = 8 cm. .. code-block:: none BoundaryWarning: the safety ramp has removed 1.40e-06 of the launch energy above the input noise's share: content reached the grid's outer wavenumbers; refine the transverse grid (SEP 40 section 5.3) - Both runs in 5.6 s + Both runs in 7.5 s @@ -225,7 +225,7 @@ beams; the linear crossing is :doc:`/introduction/lessons/plot_04_crossing_beams .. rst-class:: sphx-glr-timing - **Total running time of the script:** (0 minutes 8.958 seconds) + **Total running time of the script:** (0 minutes 10.252 seconds) .. _sphx_glr_download_auto_tutorials_free_space_plot_12_crossing_beams_kerr.py: diff --git a/docs/auto_tutorials/free_space/plot_12_crossing_beams_kerr.zip b/docs/auto_tutorials/free_space/plot_12_crossing_beams_kerr.zip index 0e80333e8..4058cfd48 100644 Binary files a/docs/auto_tutorials/free_space/plot_12_crossing_beams_kerr.zip and b/docs/auto_tutorials/free_space/plot_12_crossing_beams_kerr.zip differ diff --git a/docs/auto_tutorials/tools/plot_01_compressor_pairs.rst b/docs/auto_tutorials/tools/plot_01_compressor_pairs.rst index 417dae58b..942b4cdc4 100644 --- a/docs/auto_tutorials/tools/plot_01_compressor_pairs.rst +++ b/docs/auto_tutorials/tools/plot_01_compressor_pairs.rst @@ -170,7 +170,7 @@ For a paced propagation lesson, return to .. rst-class:: sphx-glr-timing - **Total running time of the script:** (0 minutes 0.321 seconds) + **Total running time of the script:** (0 minutes 0.091 seconds) .. _sphx_glr_download_auto_tutorials_tools_plot_01_compressor_pairs.py: diff --git a/docs/auto_tutorials/tools/plot_01_compressor_pairs.zip b/docs/auto_tutorials/tools/plot_01_compressor_pairs.zip index 9b3f5aadc..b15e1147b 100644 Binary files a/docs/auto_tutorials/tools/plot_01_compressor_pairs.zip and b/docs/auto_tutorials/tools/plot_01_compressor_pairs.zip differ diff --git a/docs/auto_tutorials/waveguides/images/sphx_glr_plot_01_antiresonant_fibre_001.png b/docs/auto_tutorials/waveguides/images/sphx_glr_plot_01_antiresonant_fibre_001.png index 38cd55fcf..0f4d4fab5 100644 Binary files a/docs/auto_tutorials/waveguides/images/sphx_glr_plot_01_antiresonant_fibre_001.png and b/docs/auto_tutorials/waveguides/images/sphx_glr_plot_01_antiresonant_fibre_001.png differ diff --git a/docs/auto_tutorials/waveguides/images/sphx_glr_plot_01_antiresonant_fibre_002.png b/docs/auto_tutorials/waveguides/images/sphx_glr_plot_01_antiresonant_fibre_002.png index 08a663f54..8aa73d110 100644 Binary files a/docs/auto_tutorials/waveguides/images/sphx_glr_plot_01_antiresonant_fibre_002.png and b/docs/auto_tutorials/waveguides/images/sphx_glr_plot_01_antiresonant_fibre_002.png differ diff --git a/docs/auto_tutorials/waveguides/images/sphx_glr_plot_01_antiresonant_fibre_003.png b/docs/auto_tutorials/waveguides/images/sphx_glr_plot_01_antiresonant_fibre_003.png index b0820e945..3dbbc8e1a 100644 Binary files a/docs/auto_tutorials/waveguides/images/sphx_glr_plot_01_antiresonant_fibre_003.png and b/docs/auto_tutorials/waveguides/images/sphx_glr_plot_01_antiresonant_fibre_003.png differ diff --git a/docs/auto_tutorials/waveguides/images/sphx_glr_plot_02_tabulated_modes_002.png b/docs/auto_tutorials/waveguides/images/sphx_glr_plot_02_tabulated_modes_002.png index aeb84a554..738683222 100644 Binary files a/docs/auto_tutorials/waveguides/images/sphx_glr_plot_02_tabulated_modes_002.png and b/docs/auto_tutorials/waveguides/images/sphx_glr_plot_02_tabulated_modes_002.png differ diff --git a/docs/auto_tutorials/waveguides/images/sphx_glr_plot_03_stepindex_rectangular_001.png b/docs/auto_tutorials/waveguides/images/sphx_glr_plot_03_stepindex_rectangular_001.png index 5383b60b8..7d286f59c 100644 Binary files a/docs/auto_tutorials/waveguides/images/sphx_glr_plot_03_stepindex_rectangular_001.png and b/docs/auto_tutorials/waveguides/images/sphx_glr_plot_03_stepindex_rectangular_001.png differ diff --git a/docs/auto_tutorials/waveguides/images/sphx_glr_plot_03_stepindex_rectangular_002.png b/docs/auto_tutorials/waveguides/images/sphx_glr_plot_03_stepindex_rectangular_002.png index 7a9a16fd4..20d7e0cdc 100644 Binary files a/docs/auto_tutorials/waveguides/images/sphx_glr_plot_03_stepindex_rectangular_002.png and b/docs/auto_tutorials/waveguides/images/sphx_glr_plot_03_stepindex_rectangular_002.png differ diff --git a/docs/auto_tutorials/waveguides/images/sphx_glr_plot_03_stepindex_rectangular_003.png b/docs/auto_tutorials/waveguides/images/sphx_glr_plot_03_stepindex_rectangular_003.png index 4900d470a..fbc509c03 100644 Binary files a/docs/auto_tutorials/waveguides/images/sphx_glr_plot_03_stepindex_rectangular_003.png and b/docs/auto_tutorials/waveguides/images/sphx_glr_plot_03_stepindex_rectangular_003.png differ diff --git a/docs/auto_tutorials/waveguides/images/sphx_glr_plot_03_stepindex_rectangular_004.png b/docs/auto_tutorials/waveguides/images/sphx_glr_plot_03_stepindex_rectangular_004.png index 5a7df9227..ed9b05284 100644 Binary files a/docs/auto_tutorials/waveguides/images/sphx_glr_plot_03_stepindex_rectangular_004.png and b/docs/auto_tutorials/waveguides/images/sphx_glr_plot_03_stepindex_rectangular_004.png differ diff --git a/docs/auto_tutorials/waveguides/images/sphx_glr_plot_04_vector_mode_providers_001.png b/docs/auto_tutorials/waveguides/images/sphx_glr_plot_04_vector_mode_providers_001.png index 610f10a3a..0a43c8215 100644 Binary files a/docs/auto_tutorials/waveguides/images/sphx_glr_plot_04_vector_mode_providers_001.png and b/docs/auto_tutorials/waveguides/images/sphx_glr_plot_04_vector_mode_providers_001.png differ diff --git a/docs/auto_tutorials/waveguides/images/sphx_glr_plot_05_general_modal_001.png b/docs/auto_tutorials/waveguides/images/sphx_glr_plot_05_general_modal_001.png index bf4abae05..44b56af4a 100644 Binary files a/docs/auto_tutorials/waveguides/images/sphx_glr_plot_05_general_modal_001.png and b/docs/auto_tutorials/waveguides/images/sphx_glr_plot_05_general_modal_001.png differ diff --git a/docs/auto_tutorials/waveguides/images/sphx_glr_plot_09_hollow_rectangular_001.png b/docs/auto_tutorials/waveguides/images/sphx_glr_plot_09_hollow_rectangular_001.png index 88d3cd104..f4b243719 100644 Binary files a/docs/auto_tutorials/waveguides/images/sphx_glr_plot_09_hollow_rectangular_001.png and b/docs/auto_tutorials/waveguides/images/sphx_glr_plot_09_hollow_rectangular_001.png differ diff --git a/docs/auto_tutorials/waveguides/images/sphx_glr_plot_09_hollow_rectangular_002.png b/docs/auto_tutorials/waveguides/images/sphx_glr_plot_09_hollow_rectangular_002.png index fe85d3751..c61853980 100644 Binary files a/docs/auto_tutorials/waveguides/images/sphx_glr_plot_09_hollow_rectangular_002.png and b/docs/auto_tutorials/waveguides/images/sphx_glr_plot_09_hollow_rectangular_002.png differ diff --git a/docs/auto_tutorials/waveguides/images/sphx_glr_plot_10_graded_index_fibre_001.png b/docs/auto_tutorials/waveguides/images/sphx_glr_plot_10_graded_index_fibre_001.png index 9757c6fc4..32fab67ac 100644 Binary files a/docs/auto_tutorials/waveguides/images/sphx_glr_plot_10_graded_index_fibre_001.png and b/docs/auto_tutorials/waveguides/images/sphx_glr_plot_10_graded_index_fibre_001.png differ diff --git a/docs/auto_tutorials/waveguides/images/sphx_glr_plot_10_graded_index_fibre_002.png b/docs/auto_tutorials/waveguides/images/sphx_glr_plot_10_graded_index_fibre_002.png index 9211ed836..307449518 100644 Binary files a/docs/auto_tutorials/waveguides/images/sphx_glr_plot_10_graded_index_fibre_002.png and b/docs/auto_tutorials/waveguides/images/sphx_glr_plot_10_graded_index_fibre_002.png differ diff --git a/docs/auto_tutorials/waveguides/images/thumb/sphx_glr_plot_01_antiresonant_fibre_thumb.png b/docs/auto_tutorials/waveguides/images/thumb/sphx_glr_plot_01_antiresonant_fibre_thumb.png index 122b3e9a2..c920657f5 100644 Binary files a/docs/auto_tutorials/waveguides/images/thumb/sphx_glr_plot_01_antiresonant_fibre_thumb.png and b/docs/auto_tutorials/waveguides/images/thumb/sphx_glr_plot_01_antiresonant_fibre_thumb.png differ diff --git a/docs/auto_tutorials/waveguides/images/thumb/sphx_glr_plot_03_stepindex_rectangular_thumb.png b/docs/auto_tutorials/waveguides/images/thumb/sphx_glr_plot_03_stepindex_rectangular_thumb.png index 6ba94a226..e634d3ea5 100644 Binary files a/docs/auto_tutorials/waveguides/images/thumb/sphx_glr_plot_03_stepindex_rectangular_thumb.png and b/docs/auto_tutorials/waveguides/images/thumb/sphx_glr_plot_03_stepindex_rectangular_thumb.png differ diff --git a/docs/auto_tutorials/waveguides/images/thumb/sphx_glr_plot_04_vector_mode_providers_thumb.png b/docs/auto_tutorials/waveguides/images/thumb/sphx_glr_plot_04_vector_mode_providers_thumb.png index 1cc504fcf..2858dfd6f 100644 Binary files a/docs/auto_tutorials/waveguides/images/thumb/sphx_glr_plot_04_vector_mode_providers_thumb.png and b/docs/auto_tutorials/waveguides/images/thumb/sphx_glr_plot_04_vector_mode_providers_thumb.png differ diff --git a/docs/auto_tutorials/waveguides/images/thumb/sphx_glr_plot_05_general_modal_thumb.png b/docs/auto_tutorials/waveguides/images/thumb/sphx_glr_plot_05_general_modal_thumb.png index 856d8bb76..a83d6792c 100644 Binary files a/docs/auto_tutorials/waveguides/images/thumb/sphx_glr_plot_05_general_modal_thumb.png and b/docs/auto_tutorials/waveguides/images/thumb/sphx_glr_plot_05_general_modal_thumb.png differ diff --git a/docs/auto_tutorials/waveguides/images/thumb/sphx_glr_plot_09_hollow_rectangular_thumb.png b/docs/auto_tutorials/waveguides/images/thumb/sphx_glr_plot_09_hollow_rectangular_thumb.png index dd9e67929..680220bfd 100644 Binary files a/docs/auto_tutorials/waveguides/images/thumb/sphx_glr_plot_09_hollow_rectangular_thumb.png and b/docs/auto_tutorials/waveguides/images/thumb/sphx_glr_plot_09_hollow_rectangular_thumb.png differ diff --git a/docs/auto_tutorials/waveguides/images/thumb/sphx_glr_plot_10_graded_index_fibre_thumb.png b/docs/auto_tutorials/waveguides/images/thumb/sphx_glr_plot_10_graded_index_fibre_thumb.png index 39b712d7b..730bb53f0 100644 Binary files a/docs/auto_tutorials/waveguides/images/thumb/sphx_glr_plot_10_graded_index_fibre_thumb.png and b/docs/auto_tutorials/waveguides/images/thumb/sphx_glr_plot_10_graded_index_fibre_thumb.png differ diff --git a/docs/auto_tutorials/waveguides/plot_01_antiresonant_fibre.codeobj.json b/docs/auto_tutorials/waveguides/plot_01_antiresonant_fibre.codeobj.json index f36e07b16..729bb47d5 100644 --- a/docs/auto_tutorials/waveguides/plot_01_antiresonant_fibre.codeobj.json +++ b/docs/auto_tutorials/waveguides/plot_01_antiresonant_fibre.codeobj.json @@ -41,7 +41,7 @@ "is_class": true, "is_explicit": false, "module": "solprop.modes.fill", - "module_short": "solprop.modes", + "module_short": "solprop.modes.fill", "name": "GasFillMixin" }, { @@ -95,6 +95,34 @@ "module_short": "solprop", "name": "NullReporter" }, + { + "is_class": true, + "is_explicit": false, + "module": "solprop.log", + "module_short": "solprop.log", + "name": "ProgressReporter" + }, + { + "is_class": true, + "is_explicit": false, + "module": "solprop", + "module_short": "solprop", + "name": "ProgressReporter" + }, + { + "is_class": true, + "is_explicit": false, + "module": "typing", + "module_short": "typing", + "name": "Protocol" + }, + { + "is_class": true, + "is_explicit": false, + "module": "typing", + "module_short": "typing", + "name": "Generic" + }, { "is_class": false, "is_explicit": false, @@ -194,7 +222,7 @@ "is_class": true, "is_explicit": false, "module": "solprop.modes.fill", - "module_short": "solprop.modes", + "module_short": "solprop.modes.fill", "name": "GasFillMixin" }, { @@ -808,7 +836,7 @@ "is_class": false, "is_explicit": false, "module": "solprop.modes.base", - "module_short": "solprop.modes.base", + "module_short": "solprop.modes", "name": "beta2" } ], @@ -856,7 +884,7 @@ "is_class": false, "is_explicit": false, "module": "solprop.modes.base", - "module_short": "solprop.modes.base", + "module_short": "solprop.modes", "name": "db_per_m" } ], diff --git a/docs/auto_tutorials/waveguides/plot_01_antiresonant_fibre.ipynb b/docs/auto_tutorials/waveguides/plot_01_antiresonant_fibre.ipynb index cbf9ebe1b..bc8a7e346 100644 --- a/docs/auto_tutorials/waveguides/plot_01_antiresonant_fibre.ipynb +++ b/docs/auto_tutorials/waveguides/plot_01_antiresonant_fibre.ipynb @@ -96,7 +96,7 @@ "name": "python", "nbconvert_exporter": "python", "pygments_lexer": "ipython3", - "version": "3.14.5" + "version": "3.14.6" } }, "nbformat": 4, diff --git a/docs/auto_tutorials/waveguides/plot_01_antiresonant_fibre.rst b/docs/auto_tutorials/waveguides/plot_01_antiresonant_fibre.rst index e58378ea2..de6264024 100644 --- a/docs/auto_tutorials/waveguides/plot_01_antiresonant_fibre.rst +++ b/docs/auto_tutorials/waveguides/plot_01_antiresonant_fibre.rst @@ -225,7 +225,7 @@ per wavelength includes the omega-to-wavelength Jacobian before normalisation. .. code-block:: none BoundaryWarning: the temporal collar removed 1.88e-05 of the launch energy, whose square root is above the 1e-03 budget: what left the window may have mattered; widen trange to keep it - Complete Vincetti example: 3.305 s + Complete Vincetti example: 2.424 s @@ -242,7 +242,7 @@ For a paced propagation lesson, return to .. rst-class:: sphx-glr-timing - **Total running time of the script:** (0 minutes 3.345 seconds) + **Total running time of the script:** (0 minutes 2.468 seconds) .. _sphx_glr_download_auto_tutorials_waveguides_plot_01_antiresonant_fibre.py: diff --git a/docs/auto_tutorials/waveguides/plot_01_antiresonant_fibre.zip b/docs/auto_tutorials/waveguides/plot_01_antiresonant_fibre.zip index efc86edc4..039984076 100644 Binary files a/docs/auto_tutorials/waveguides/plot_01_antiresonant_fibre.zip and b/docs/auto_tutorials/waveguides/plot_01_antiresonant_fibre.zip differ diff --git a/docs/auto_tutorials/waveguides/plot_02_tabulated_modes.codeobj.json b/docs/auto_tutorials/waveguides/plot_02_tabulated_modes.codeobj.json index 2a88865bd..a0e14b9bc 100644 --- a/docs/auto_tutorials/waveguides/plot_02_tabulated_modes.codeobj.json +++ b/docs/auto_tutorials/waveguides/plot_02_tabulated_modes.codeobj.json @@ -184,6 +184,78 @@ "name": "from_wavelength" } ], + "NoZeroDispersionError": [ + { + "is_class": true, + "is_explicit": false, + "module": "solprop.exceptions", + "module_short": "solprop.exceptions", + "name": "NoZeroDispersionError" + }, + { + "is_class": true, + "is_explicit": false, + "module": "solprop", + "module_short": "solprop", + "name": "NoZeroDispersionError" + }, + { + "is_class": true, + "is_explicit": false, + "module": "solprop.exceptions", + "module_short": "solprop.exceptions", + "name": "ModeError" + }, + { + "is_class": true, + "is_explicit": false, + "module": "solprop", + "module_short": "solprop", + "name": "ModeError" + }, + { + "is_class": true, + "is_explicit": false, + "module": "solprop.exceptions", + "module_short": "solprop", + "name": "SolpropError" + }, + { + "is_class": true, + "is_explicit": false, + "module": "solprop", + "module_short": "solprop", + "name": "SolpropError" + }, + { + "is_class": true, + "is_explicit": false, + "module": "builtins", + "module_short": "builtins", + "name": "ValueError" + }, + { + "is_class": true, + "is_explicit": false, + "module": "builtins", + "module_short": "builtins", + "name": "Exception" + }, + { + "is_class": true, + "is_explicit": false, + "module": "builtins", + "module_short": "builtins", + "name": "BaseException" + }, + { + "is_class": false, + "is_explicit": false, + "module": "solprop.exceptions", + "module_short": "solprop.exceptions", + "name": "NoZeroDispersionError" + } + ], "NullReporter": [ { "is_class": true, @@ -1574,6 +1646,15 @@ "name": "prop_gnlse" } ], + "root": [ + { + "is_class": false, + "is_explicit": false, + "module": "builtins", + "module_short": "builtins", + "name": "float" + } + ], "root_pressures": [ { "is_class": false, diff --git a/docs/auto_tutorials/waveguides/plot_02_tabulated_modes.ipynb b/docs/auto_tutorials/waveguides/plot_02_tabulated_modes.ipynb index 896eb85d3..86d4af494 100644 --- a/docs/auto_tutorials/waveguides/plot_02_tabulated_modes.ipynb +++ b/docs/auto_tutorials/waveguides/plot_02_tabulated_modes.ipynb @@ -15,7 +15,7 @@ }, "outputs": [], "source": [ - "import sys\nfrom pathlib import Path\nfrom time import perf_counter\n\nimport matplotlib.pyplot as plt\nimport numpy as np\n\nfrom solprop.constants import C\nfrom solprop.driver import Simulation, prop_gnlse\nfrom solprop.grid import EnvelopeGrid\nfrom solprop.log import NullReporter\nfrom solprop.modes import IndexTable, TabulatedHollowMode, TabulatedMode\nfrom solprop.modes.base import beta2, db_per_m, zdw\nfrom solprop.nonlinear.gnlse import SpecifiedMode, attenuation_from_db\nfrom solprop.stats import StatsSpec\nfrom solprop.stepper import FixedSchedule\n\nstarted = perf_counter()\n# Gallery sets argv[0] to the source script but deliberately omits __file__. The\n# tables are in a ``data`` directory beside the script.\ndata_directory = Path(sys.argv[0]).resolve().parent / \"data\"\nvacuum = np.loadtxt(data_directory / \"fem-vacuum.csv\", delimiter=\",\")\nargon = np.loadtxt(data_directory / \"fem-argon.csv\", delimiter=\",\")\ntable = IndexTable.from_wavelength(\n vacuum[:, 0], vacuum[:, 3] + 1j * vacuum[:, 4], area=vacuum[:, 6]\n)\nfilled_table = IndexTable.from_wavelength(\n argon[:, 0], argon[:, 3] + 1j * argon[:, 4], area=argon[:, 6]\n)\nfilled = TabulatedMode(\n 15e-6,\n \"Ar\",\n 10.0,\n temperature=293.0,\n table=filled_table,\n reference_wavelength=650e-9,\n)" + "import sys\nfrom pathlib import Path\nfrom time import perf_counter\n\nimport matplotlib.pyplot as plt\nimport numpy as np\n\nfrom solprop.constants import C\nfrom solprop.driver import Simulation, prop_gnlse\nfrom solprop.exceptions import NoZeroDispersionError\nfrom solprop.grid import EnvelopeGrid\nfrom solprop.log import NullReporter\nfrom solprop.modes import IndexTable, TabulatedHollowMode, TabulatedMode\nfrom solprop.modes.base import beta2, db_per_m, zdw\nfrom solprop.nonlinear.gnlse import SpecifiedMode, attenuation_from_db\nfrom solprop.stats import StatsSpec\nfrom solprop.stepper import FixedSchedule\n\nstarted = perf_counter()\n# Gallery sets argv[0] to the source script but deliberately omits __file__. The\n# tables are in a ``data`` directory beside the script.\ndata_directory = Path(sys.argv[0]).resolve().parent / \"data\"\nvacuum = np.loadtxt(data_directory / \"fem-vacuum.csv\", delimiter=\",\")\nargon = np.loadtxt(data_directory / \"fem-argon.csv\", delimiter=\",\")\ntable = IndexTable.from_wavelength(\n vacuum[:, 0], vacuum[:, 3] + 1j * vacuum[:, 4], area=vacuum[:, 6]\n)\nfilled_table = IndexTable.from_wavelength(\n argon[:, 0], argon[:, 3] + 1j * argon[:, 4], area=argon[:, 6]\n)\nfilled = TabulatedMode(\n 15e-6,\n \"Ar\",\n 10.0,\n temperature=293.0,\n table=filled_table,\n reference_wavelength=650e-9,\n)" ] }, { @@ -40,7 +40,7 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "Bracket each root locally; broad endpoints can have the same sign even when\ntwo roots lie inside. All probes stay inside the vacuum table and gas fit.\n\n" + "Bracket each root locally; broad endpoints can have the same sign even when\ntwo roots lie inside. All probes stay inside the vacuum table and gas fit.\n``zdw`` returns a zero only where it bounds a dispersion regime at least 1.5 % wide\nin frequency: the evacuated fibre's ``beta_2`` ripples through zero twice within\n3 nm near 455 nm, which is fine structure of the interpolant and no zero-dispersion\nwavelength, so the search refuses it and the loop passes over it.\n\n" ] }, { @@ -51,7 +51,7 @@ }, "outputs": [], "source": [ - "probe_wavelength = np.linspace(450e-9, 990e-9, 200)\nroot_pressures = []\nroot_wavelengths = []\nfor pressure in np.arange(0.0, 31.0, 2.0):\n mode = TabulatedHollowMode(\n 15e-6,\n \"Ar\",\n float(pressure),\n temperature=293.0,\n table=table,\n reference_wavelength=650e-9,\n )\n curvature = beta2(mode, 2 * np.pi * C / probe_wavelength)\n brackets = np.flatnonzero(curvature[:-1] * curvature[1:] < 0)\n for index in brackets:\n root_pressures.append(pressure)\n root_wavelengths.append(\n zdw(\n mode,\n wavelength_limits=(\n float(probe_wavelength[index]),\n float(probe_wavelength[index + 1]),\n ),\n )\n * 1e9\n )\nfigure, axis = plt.subplots(figsize=(6, 3.5))\naxis.scatter(root_pressures, root_wavelengths, s=22)\naxis.set(\n xlabel=\"Argon pressure (bar)\",\n ylabel=\"Zero-dispersion wavelength (nm)\",\n title=\"Bracketed roots of a sparse interpolant, not converged ZDWs\",\n)\naxis.grid(alpha=0.2)\nfigure.tight_layout()" + "probe_wavelength = np.linspace(450e-9, 990e-9, 200)\nroot_pressures = []\nroot_wavelengths = []\nfor pressure in np.arange(0.0, 31.0, 2.0):\n mode = TabulatedHollowMode(\n 15e-6,\n \"Ar\",\n float(pressure),\n temperature=293.0,\n table=table,\n reference_wavelength=650e-9,\n )\n curvature = beta2(mode, 2 * np.pi * C / probe_wavelength)\n brackets = np.flatnonzero(curvature[:-1] * curvature[1:] < 0)\n for index in brackets:\n try:\n root = zdw(\n mode,\n wavelength_limits=(\n float(probe_wavelength[index]),\n float(probe_wavelength[index + 1]),\n ),\n )\n except NoZeroDispersionError:\n continue\n root_pressures.append(pressure)\n root_wavelengths.append(root * 1e9)\nfigure, axis = plt.subplots(figsize=(6, 3.5))\naxis.scatter(root_pressures, root_wavelengths, s=22)\naxis.set(\n xlabel=\"Argon pressure (bar)\",\n ylabel=\"Zero-dispersion wavelength (nm)\",\n title=\"Bracketed roots of a sparse interpolant, not converged ZDWs\",\n)\naxis.grid(alpha=0.2)\nfigure.tight_layout()" ] }, { diff --git a/docs/auto_tutorials/waveguides/plot_02_tabulated_modes.py b/docs/auto_tutorials/waveguides/plot_02_tabulated_modes.py index c36d15e5b..c8ba1684f 100644 --- a/docs/auto_tutorials/waveguides/plot_02_tabulated_modes.py +++ b/docs/auto_tutorials/waveguides/plot_02_tabulated_modes.py @@ -47,6 +47,7 @@ from solprop.constants import C from solprop.driver import Simulation, prop_gnlse +from solprop.exceptions import NoZeroDispersionError from solprop.grid import EnvelopeGrid from solprop.log import NullReporter from solprop.modes import IndexTable, TabulatedHollowMode, TabulatedMode @@ -117,6 +118,10 @@ # %% # Bracket each root locally; broad endpoints can have the same sign even when # two roots lie inside. All probes stay inside the vacuum table and gas fit. +# ``zdw`` returns a zero only where it bounds a dispersion regime at least 1.5 % wide +# in frequency: the evacuated fibre's ``beta_2`` ripples through zero twice within +# 3 nm near 455 nm, which is fine structure of the interpolant and no zero-dispersion +# wavelength, so the search refuses it and the loop passes over it. probe_wavelength = np.linspace(450e-9, 990e-9, 200) root_pressures = [] root_wavelengths = [] @@ -132,17 +137,18 @@ curvature = beta2(mode, 2 * np.pi * C / probe_wavelength) brackets = np.flatnonzero(curvature[:-1] * curvature[1:] < 0) for index in brackets: - root_pressures.append(pressure) - root_wavelengths.append( - zdw( + try: + root = zdw( mode, wavelength_limits=( float(probe_wavelength[index]), float(probe_wavelength[index + 1]), ), ) - * 1e9 - ) + except NoZeroDispersionError: + continue + root_pressures.append(pressure) + root_wavelengths.append(root * 1e9) figure, axis = plt.subplots(figsize=(6, 3.5)) axis.scatter(root_pressures, root_wavelengths, s=22) axis.set( diff --git a/docs/auto_tutorials/waveguides/plot_02_tabulated_modes.py.md5 b/docs/auto_tutorials/waveguides/plot_02_tabulated_modes.py.md5 index 2561a73b8..4836f46de 100644 --- a/docs/auto_tutorials/waveguides/plot_02_tabulated_modes.py.md5 +++ b/docs/auto_tutorials/waveguides/plot_02_tabulated_modes.py.md5 @@ -1 +1 @@ -95e59e6b80e2de9d7a0cb55d2b6d0d16 \ No newline at end of file +4863ef35e629c4a754f7808367878b4b \ No newline at end of file diff --git a/docs/auto_tutorials/waveguides/plot_02_tabulated_modes.rst b/docs/auto_tutorials/waveguides/plot_02_tabulated_modes.rst index 384c866d6..1f53b5969 100644 --- a/docs/auto_tutorials/waveguides/plot_02_tabulated_modes.rst +++ b/docs/auto_tutorials/waveguides/plot_02_tabulated_modes.rst @@ -52,7 +52,7 @@ not a converged broadband prediction. Finally a synthetic 200-knot solid-core table sampled from Taylor dispersion demonstrates the GNLSE n2 route, with unit prefactor index and no gas-material response inferred from the fibre. -.. GENERATED FROM PYTHON SOURCE LINES 40-79 +.. GENERATED FROM PYTHON SOURCE LINES 40-80 .. code-block:: Python @@ -66,6 +66,7 @@ prefactor index and no gas-material response inferred from the fibre. from solprop.constants import C from solprop.driver import Simulation, prop_gnlse + from solprop.exceptions import NoZeroDispersionError from solprop.grid import EnvelopeGrid from solprop.log import NullReporter from solprop.modes import IndexTable, TabulatedHollowMode, TabulatedMode @@ -102,12 +103,12 @@ prefactor index and no gas-material response inferred from the fibre. -.. GENERATED FROM PYTHON SOURCE LINES 80-82 +.. GENERATED FROM PYTHON SOURCE LINES 81-83 Keep derivative probes inside both tables. The filled overlay stops at 940 nm, before its last 946 nm row, and begins after its first row. -.. GENERATED FROM PYTHON SOURCE LINES 82-117 +.. GENERATED FROM PYTHON SOURCE LINES 83-118 .. code-block:: Python @@ -158,12 +159,16 @@ before its last 946 nm row, and begins after its first row. -.. GENERATED FROM PYTHON SOURCE LINES 118-120 +.. GENERATED FROM PYTHON SOURCE LINES 119-125 Bracket each root locally; broad endpoints can have the same sign even when two roots lie inside. All probes stay inside the vacuum table and gas fit. +``zdw`` returns a zero only where it bounds a dispersion regime at least 1.5 % wide +in frequency: the evacuated fibre's ``beta_2`` ripples through zero twice within +3 nm near 455 nm, which is fine structure of the interpolant and no zero-dispersion +wavelength, so the search refuses it and the loop passes over it. -.. GENERATED FROM PYTHON SOURCE LINES 120-156 +.. GENERATED FROM PYTHON SOURCE LINES 125-162 .. code-block:: Python @@ -182,17 +187,18 @@ two roots lie inside. All probes stay inside the vacuum table and gas fit. curvature = beta2(mode, 2 * np.pi * C / probe_wavelength) brackets = np.flatnonzero(curvature[:-1] * curvature[1:] < 0) for index in brackets: - root_pressures.append(pressure) - root_wavelengths.append( - zdw( + try: + root = zdw( mode, wavelength_limits=( float(probe_wavelength[index]), float(probe_wavelength[index + 1]), ), ) - * 1e9 - ) + except NoZeroDispersionError: + continue + root_pressures.append(pressure) + root_wavelengths.append(root * 1e9) figure, axis = plt.subplots(figsize=(6, 3.5)) axis.scatter(root_pressures, root_wavelengths, s=22) axis.set( @@ -215,7 +221,7 @@ two roots lie inside. All probes stay inside the vacuum table and gas fit. -.. GENERATED FROM PYTHON SOURCE LINES 157-164 +.. GENERATED FROM PYTHON SOURCE LINES 163-170 A mode's own fill drives the capillary material responses. Select its constant propagation area at the pulse wavelength, independently of the inherited fields. @@ -225,7 +231,7 @@ the default multistep integrator is stable against it only for steps below 0.7 u so the 64 fixed steps would diverge. The pulse never reaches the collar, where the per-step split's error would lie (:doc:`/guide/numerics/adams`). -.. GENERATED FROM PYTHON SOURCE LINES 164-203 +.. GENERATED FROM PYTHON SOURCE LINES 170-209 .. code-block:: Python @@ -280,12 +286,12 @@ per-step split's error would lie (:doc:`/guide/numerics/adams`). -.. GENERATED FROM PYTHON SOURCE LINES 204-206 +.. GENERATED FROM PYTHON SOURCE LINES 210-212 Synthetic solid-core input: the area gives gamma = n2 omega0 / (c A_eff). This table samples an analytic Taylor model, rather than a FEM solution. -.. GENERATED FROM PYTHON SOURCE LINES 206-237 +.. GENERATED FROM PYTHON SOURCE LINES 212-243 .. code-block:: Python @@ -328,12 +334,12 @@ This table samples an analytic Taylor model, rather than a FEM solution. .. code-block:: none - Tabulated examples completed in 4.19 s + Tabulated examples completed in 0.67 s -.. GENERATED FROM PYTHON SOURCE LINES 238-245 +.. GENERATED FROM PYTHON SOURCE LINES 244-251 Related reading --------------- @@ -346,7 +352,7 @@ For a paced propagation lesson, return to .. rst-class:: sphx-glr-timing - **Total running time of the script:** (0 minutes 4.193 seconds) + **Total running time of the script:** (0 minutes 0.668 seconds) .. _sphx_glr_download_auto_tutorials_waveguides_plot_02_tabulated_modes.py: diff --git a/docs/auto_tutorials/waveguides/plot_02_tabulated_modes.zip b/docs/auto_tutorials/waveguides/plot_02_tabulated_modes.zip index a45cc36fd..bdc43bb96 100644 Binary files a/docs/auto_tutorials/waveguides/plot_02_tabulated_modes.zip and b/docs/auto_tutorials/waveguides/plot_02_tabulated_modes.zip differ diff --git a/docs/auto_tutorials/waveguides/plot_03_stepindex_rectangular.codeobj.json b/docs/auto_tutorials/waveguides/plot_03_stepindex_rectangular.codeobj.json index 46196e2dc..3e0e402d5 100644 --- a/docs/auto_tutorials/waveguides/plot_03_stepindex_rectangular.codeobj.json +++ b/docs/auto_tutorials/waveguides/plot_03_stepindex_rectangular.codeobj.json @@ -62,7 +62,7 @@ "is_class": true, "is_explicit": false, "module": "solprop.modes.fill", - "module_short": "solprop.modes", + "module_short": "solprop.modes.fill", "name": "GasFillMixin" }, { @@ -576,7 +576,7 @@ "is_class": false, "is_explicit": false, "module": "solprop.modes.base", - "module_short": "solprop.modes.base", + "module_short": "solprop.modes", "name": "beta2" } ], @@ -592,7 +592,7 @@ "is_class": false, "is_explicit": false, "module": "solprop.modes.base", - "module_short": "solprop.modes.base", + "module_short": "solprop.modes", "name": "db_per_m" } ], @@ -1200,8 +1200,8 @@ { "is_class": false, "is_explicit": false, - "module": "solprop.output.schema", - "module_short": "solprop.output", + "module": "solprop.output.store", + "module_short": "solprop.output.store", "name": "PlaneStore.fields" }, { @@ -1288,7 +1288,7 @@ "is_class": false, "is_explicit": false, "module": "solprop.modes.base", - "module_short": "solprop.modes.base", + "module_short": "solprop.modes", "name": "zdw" } ], diff --git a/docs/auto_tutorials/waveguides/plot_03_stepindex_rectangular.ipynb b/docs/auto_tutorials/waveguides/plot_03_stepindex_rectangular.ipynb index 7915e04ef..b932eac68 100644 --- a/docs/auto_tutorials/waveguides/plot_03_stepindex_rectangular.ipynb +++ b/docs/auto_tutorials/waveguides/plot_03_stepindex_rectangular.ipynb @@ -96,7 +96,7 @@ "name": "python", "nbconvert_exporter": "python", "pygments_lexer": "ipython3", - "version": "3.14.5" + "version": "3.14.6" } }, "nbformat": 4, diff --git a/docs/auto_tutorials/waveguides/plot_03_stepindex_rectangular.rst b/docs/auto_tutorials/waveguides/plot_03_stepindex_rectangular.rst index 3b74ac17c..ecf1e2fcf 100644 --- a/docs/auto_tutorials/waveguides/plot_03_stepindex_rectangular.rst +++ b/docs/auto_tutorials/waveguides/plot_03_stepindex_rectangular.rst @@ -256,9 +256,9 @@ Rectangular x/y partners have separate propagation constants and losses. .. code-block:: none - GrazingIncidenceWarning: RectMode(x11, 100 um x 20 um, Ar 5 bar, loss=True): the first-order wall-pair model reaches lambda |q| / (2 pi a) = 0.179 at 2332 nm, above the 0.1 it is valid to; its neglected terms are second order in that ratio. Narrow the band towards shorter wavelengths, widen the guide, or keep lower orders + GrazingIncidenceWarning: RectMode(x11, 100 um x 20 um, Ar 5 bar, loss=model): the first-order wall-pair model reaches lambda |q| / (2 pi a) = 0.179 at 2332 nm, above the 0.1 it is valid to; its neglected terms are second order in that ratio. Narrow the band towards shorter wavelengths, widen the guide, or keep lower orders Rectangular transmitted energy: 9.954503e-09 J - Complete step-index/rectangular example: 2.257 s + Complete step-index/rectangular example: 1.968 s @@ -275,7 +275,7 @@ For a paced propagation lesson, return to .. rst-class:: sphx-glr-timing - **Total running time of the script:** (0 minutes 2.286 seconds) + **Total running time of the script:** (0 minutes 1.994 seconds) .. _sphx_glr_download_auto_tutorials_waveguides_plot_03_stepindex_rectangular.py: diff --git a/docs/auto_tutorials/waveguides/plot_03_stepindex_rectangular.zip b/docs/auto_tutorials/waveguides/plot_03_stepindex_rectangular.zip index ed9a57ac3..0ea9855d7 100644 Binary files a/docs/auto_tutorials/waveguides/plot_03_stepindex_rectangular.zip and b/docs/auto_tutorials/waveguides/plot_03_stepindex_rectangular.zip differ diff --git a/docs/auto_tutorials/waveguides/plot_04_vector_mode_providers.codeobj.json b/docs/auto_tutorials/waveguides/plot_04_vector_mode_providers.codeobj.json index c1c93a8f6..af55a029d 100644 --- a/docs/auto_tutorials/waveguides/plot_04_vector_mode_providers.codeobj.json +++ b/docs/auto_tutorials/waveguides/plot_04_vector_mode_providers.codeobj.json @@ -572,7 +572,7 @@ "is_class": false, "is_explicit": false, "module": "solprop.modes.vector", - "module_short": "solprop.modes", + "module_short": "solprop.modes.vector", "name": "ModalNodeRule" }, { @@ -645,7 +645,7 @@ "is_class": false, "is_explicit": false, "module": "solprop.modes.vector", - "module_short": "solprop.modes", + "module_short": "solprop.modes.vector", "name": "ModalNodeRule" }, { @@ -840,7 +840,7 @@ { "is_class": false, "is_explicit": false, - "module": "solprop.modes.guide", + "module": "solprop.modes.stepindex_vector", "module_short": "solprop.modes", "name": "StepIndexProvider" }, @@ -863,7 +863,7 @@ { "is_class": false, "is_explicit": false, - "module": "solprop.modes.guide", + "module": "solprop.modes.stepindex_vector", "module_short": "solprop.modes", "name": "StepIndexProvider.node_rule" }, @@ -900,7 +900,7 @@ { "is_class": false, "is_explicit": false, - "module": "solprop.modes.guide", + "module": "solprop.modes.stepindex_vector", "module_short": "solprop.modes", "name": "StepIndexProvider.solve" }, @@ -961,7 +961,7 @@ "is_class": false, "is_explicit": false, "module": "solprop.modes.vector", - "module_short": "solprop.modes", + "module_short": "solprop.modes.vector", "name": "ModalNodeRule" }, { diff --git a/docs/auto_tutorials/waveguides/plot_04_vector_mode_providers.ipynb b/docs/auto_tutorials/waveguides/plot_04_vector_mode_providers.ipynb index 46941a835..ab6d23cc4 100644 --- a/docs/auto_tutorials/waveguides/plot_04_vector_mode_providers.ipynb +++ b/docs/auto_tutorials/waveguides/plot_04_vector_mode_providers.ipynb @@ -42,7 +42,7 @@ "name": "python", "nbconvert_exporter": "python", "pygments_lexer": "ipython3", - "version": "3.14.5" + "version": "3.14.6" } }, "nbformat": 4, diff --git a/docs/auto_tutorials/waveguides/plot_04_vector_mode_providers.rst b/docs/auto_tutorials/waveguides/plot_04_vector_mode_providers.rst index 3de942735..7ca5e68fb 100644 --- a/docs/auto_tutorials/waveguides/plot_04_vector_mode_providers.rst +++ b/docs/auto_tutorials/waveguides/plot_04_vector_mode_providers.rst @@ -119,7 +119,7 @@ For a paced propagation lesson, return to .. rst-class:: sphx-glr-timing - **Total running time of the script:** (0 minutes 0.093 seconds) + **Total running time of the script:** (0 minutes 0.079 seconds) .. _sphx_glr_download_auto_tutorials_waveguides_plot_04_vector_mode_providers.py: diff --git a/docs/auto_tutorials/waveguides/plot_04_vector_mode_providers.zip b/docs/auto_tutorials/waveguides/plot_04_vector_mode_providers.zip index 5402549b6..1b1aab4d5 100644 Binary files a/docs/auto_tutorials/waveguides/plot_04_vector_mode_providers.zip and b/docs/auto_tutorials/waveguides/plot_04_vector_mode_providers.zip differ diff --git a/docs/auto_tutorials/waveguides/plot_05_general_modal.ipynb b/docs/auto_tutorials/waveguides/plot_05_general_modal.ipynb index 6a07b99f5..0de5cd1a1 100644 --- a/docs/auto_tutorials/waveguides/plot_05_general_modal.ipynb +++ b/docs/auto_tutorials/waveguides/plot_05_general_modal.ipynb @@ -114,7 +114,7 @@ "name": "python", "nbconvert_exporter": "python", "pygments_lexer": "ipython3", - "version": "3.14.7" + "version": "3.14.6" } }, "nbformat": 4, diff --git a/docs/auto_tutorials/waveguides/plot_05_general_modal.rst b/docs/auto_tutorials/waveguides/plot_05_general_modal.rst index 27a894fbb..82d1a7008 100644 --- a/docs/auto_tutorials/waveguides/plot_05_general_modal.rst +++ b/docs/auto_tutorials/waveguides/plot_05_general_modal.rst @@ -351,7 +351,7 @@ For a paced propagation lesson, return to .. rst-class:: sphx-glr-timing - **Total running time of the script:** (0 minutes 10.622 seconds) + **Total running time of the script:** (0 minutes 4.562 seconds) .. _sphx_glr_download_auto_tutorials_waveguides_plot_05_general_modal.py: diff --git a/docs/auto_tutorials/waveguides/plot_05_general_modal.zip b/docs/auto_tutorials/waveguides/plot_05_general_modal.zip index 202a0c661..17e1899f7 100644 Binary files a/docs/auto_tutorials/waveguides/plot_05_general_modal.zip and b/docs/auto_tutorials/waveguides/plot_05_general_modal.zip differ diff --git a/docs/auto_tutorials/waveguides/plot_06_graded_index.ipynb b/docs/auto_tutorials/waveguides/plot_06_graded_index.ipynb index da2899a1a..3e96badc7 100644 --- a/docs/auto_tutorials/waveguides/plot_06_graded_index.ipynb +++ b/docs/auto_tutorials/waveguides/plot_06_graded_index.ipynb @@ -204,7 +204,7 @@ "name": "python", "nbconvert_exporter": "python", "pygments_lexer": "ipython3", - "version": "3.14.7" + "version": "3.14.6" } }, "nbformat": 4, diff --git a/docs/auto_tutorials/waveguides/plot_06_graded_index.rst b/docs/auto_tutorials/waveguides/plot_06_graded_index.rst index 317c53c67..dbbd01925 100644 --- a/docs/auto_tutorials/waveguides/plot_06_graded_index.rst +++ b/docs/auto_tutorials/waveguides/plot_06_graded_index.rst @@ -422,7 +422,7 @@ For a paced propagation lesson, return to .. rst-class:: sphx-glr-timing - **Total running time of the script:** (0 minutes 2.027 seconds) + **Total running time of the script:** (0 minutes 0.617 seconds) .. _sphx_glr_download_auto_tutorials_waveguides_plot_06_graded_index.py: diff --git a/docs/auto_tutorials/waveguides/plot_06_graded_index.zip b/docs/auto_tutorials/waveguides/plot_06_graded_index.zip index 69c025f73..e435fed11 100644 Binary files a/docs/auto_tutorials/waveguides/plot_06_graded_index.zip and b/docs/auto_tutorials/waveguides/plot_06_graded_index.zip differ diff --git a/docs/auto_tutorials/waveguides/plot_07_split_block.codeobj.json b/docs/auto_tutorials/waveguides/plot_07_split_block.codeobj.json index 875037b51..7c0e0492a 100644 --- a/docs/auto_tutorials/waveguides/plot_07_split_block.codeobj.json +++ b/docs/auto_tutorials/waveguides/plot_07_split_block.codeobj.json @@ -19,8 +19,8 @@ { "is_class": true, "is_explicit": false, - "module": "solprop.modes.guide", - "module_short": "solprop.modes.guide", + "module": "solprop.modes.vector", + "module_short": "solprop.modes.vector", "name": "ChannelBasis" }, { @@ -614,8 +614,8 @@ { "is_class": false, "is_explicit": false, - "module": "solprop.modes.guide", - "module_short": "solprop.modes.guide", + "module": "solprop.modes.vector", + "module_short": "solprop.modes.vector", "name": "ChannelBasis" }, { @@ -1085,7 +1085,7 @@ "is_class": false, "is_explicit": false, "module": "solprop.modes.vector", - "module_short": "solprop.modes", + "module_short": "solprop.modes.vector", "name": "ModalNodeRule" }, { @@ -1489,7 +1489,7 @@ { "is_class": false, "is_explicit": false, - "module": "solprop.modes.guide", + "module": "solprop.modes.stepindex_vector", "module_short": "solprop.modes", "name": "StepIndexProvider" }, @@ -1512,7 +1512,7 @@ { "is_class": false, "is_explicit": false, - "module": "solprop.modes.guide", + "module": "solprop.modes.stepindex_vector", "module_short": "solprop.modes", "name": "StepIndexProvider.node_rule" }, @@ -1784,7 +1784,7 @@ "is_class": false, "is_explicit": false, "module": "solprop.output.store", - "module_short": "solprop.output", + "module_short": "solprop.output.store", "name": "PlaneStore.metadata" }, { diff --git a/docs/auto_tutorials/waveguides/plot_07_split_block.ipynb b/docs/auto_tutorials/waveguides/plot_07_split_block.ipynb index 9529db13c..f2e7d8dea 100644 --- a/docs/auto_tutorials/waveguides/plot_07_split_block.ipynb +++ b/docs/auto_tutorials/waveguides/plot_07_split_block.ipynb @@ -96,7 +96,7 @@ "name": "python", "nbconvert_exporter": "python", "pygments_lexer": "ipython3", - "version": "3.14.7" + "version": "3.14.6" } }, "nbformat": 4, diff --git a/docs/auto_tutorials/waveguides/plot_07_split_block.rst b/docs/auto_tutorials/waveguides/plot_07_split_block.rst index 9b28a03eb..8ff645d23 100644 --- a/docs/auto_tutorials/waveguides/plot_07_split_block.rst +++ b/docs/auto_tutorials/waveguides/plot_07_split_block.rst @@ -343,7 +343,7 @@ For a paced propagation lesson, return to .. rst-class:: sphx-glr-timing - **Total running time of the script:** (0 minutes 2.854 seconds) + **Total running time of the script:** (0 minutes 0.882 seconds) .. _sphx_glr_download_auto_tutorials_waveguides_plot_07_split_block.py: diff --git a/docs/auto_tutorials/waveguides/plot_07_split_block.zip b/docs/auto_tutorials/waveguides/plot_07_split_block.zip index 1db315092..bd065d183 100644 Binary files a/docs/auto_tutorials/waveguides/plot_07_split_block.zip and b/docs/auto_tutorials/waveguides/plot_07_split_block.zip differ diff --git a/docs/auto_tutorials/waveguides/plot_08_planar.rst b/docs/auto_tutorials/waveguides/plot_08_planar.rst index 3cd79927d..44e84dc48 100644 --- a/docs/auto_tutorials/waveguides/plot_08_planar.rst +++ b/docs/auto_tutorials/waveguides/plot_08_planar.rst @@ -207,7 +207,7 @@ quadrature diagnostic visible when it has only one recorded value. .. code-block:: none - ran in 2.4 s + ran in 0.6 s @@ -224,7 +224,7 @@ For a paced propagation lesson, return to .. rst-class:: sphx-glr-timing - **Total running time of the script:** (0 minutes 2.387 seconds) + **Total running time of the script:** (0 minutes 0.615 seconds) .. _sphx_glr_download_auto_tutorials_waveguides_plot_08_planar.py: diff --git a/docs/auto_tutorials/waveguides/plot_08_planar.zip b/docs/auto_tutorials/waveguides/plot_08_planar.zip index 978da82bf..3519f8598 100644 Binary files a/docs/auto_tutorials/waveguides/plot_08_planar.zip and b/docs/auto_tutorials/waveguides/plot_08_planar.zip differ diff --git a/docs/auto_tutorials/waveguides/plot_09_hollow_rectangular.codeobj.json b/docs/auto_tutorials/waveguides/plot_09_hollow_rectangular.codeobj.json index 930470bc8..6f1b35472 100644 --- a/docs/auto_tutorials/waveguides/plot_09_hollow_rectangular.codeobj.json +++ b/docs/auto_tutorials/waveguides/plot_09_hollow_rectangular.codeobj.json @@ -62,7 +62,7 @@ "is_class": true, "is_explicit": false, "module": "solprop.modes.fill", - "module_short": "solprop.modes", + "module_short": "solprop.modes.fill", "name": "GasFillMixin" }, { @@ -136,7 +136,7 @@ "is_class": false, "is_explicit": false, "module": "solprop.modes.base", - "module_short": "solprop.modes.base", + "module_short": "solprop.modes", "name": "beta2" } ], @@ -152,7 +152,7 @@ "is_class": false, "is_explicit": false, "module": "solprop.modes.base", - "module_short": "solprop.modes.base", + "module_short": "solprop.modes", "name": "db_per_m" } ], diff --git a/docs/auto_tutorials/waveguides/plot_09_hollow_rectangular.ipynb b/docs/auto_tutorials/waveguides/plot_09_hollow_rectangular.ipynb index c639e71a2..812ed621d 100644 --- a/docs/auto_tutorials/waveguides/plot_09_hollow_rectangular.ipynb +++ b/docs/auto_tutorials/waveguides/plot_09_hollow_rectangular.ipynb @@ -78,7 +78,7 @@ "name": "python", "nbconvert_exporter": "python", "pygments_lexer": "ipython3", - "version": "3.14.5" + "version": "3.14.6" } }, "nbformat": 4, diff --git a/docs/auto_tutorials/waveguides/plot_09_hollow_rectangular.rst b/docs/auto_tutorials/waveguides/plot_09_hollow_rectangular.rst index c6e9d298f..2904d0e36 100644 --- a/docs/auto_tutorials/waveguides/plot_09_hollow_rectangular.rst +++ b/docs/auto_tutorials/waveguides/plot_09_hollow_rectangular.rst @@ -145,7 +145,7 @@ has no Raman response. The transverse quadrature of the nonlinear overlap uses 1 .. code-block:: none Transmitted energy: 17.4235 uJ - Complete hollow rectangular example: 0.760 s + Complete hollow rectangular example: 0.168 s @@ -160,7 +160,7 @@ Related reading .. rst-class:: sphx-glr-timing - **Total running time of the script:** (0 minutes 0.852 seconds) + **Total running time of the script:** (0 minutes 0.213 seconds) .. _sphx_glr_download_auto_tutorials_waveguides_plot_09_hollow_rectangular.py: diff --git a/docs/auto_tutorials/waveguides/plot_09_hollow_rectangular.zip b/docs/auto_tutorials/waveguides/plot_09_hollow_rectangular.zip index 63588ab1a..f2a2b6185 100644 Binary files a/docs/auto_tutorials/waveguides/plot_09_hollow_rectangular.zip and b/docs/auto_tutorials/waveguides/plot_09_hollow_rectangular.zip differ diff --git a/docs/auto_tutorials/waveguides/plot_10_graded_index_fibre.codeobj.json b/docs/auto_tutorials/waveguides/plot_10_graded_index_fibre.codeobj.json index 4d3c09204..4701e0742 100644 --- a/docs/auto_tutorials/waveguides/plot_10_graded_index_fibre.codeobj.json +++ b/docs/auto_tutorials/waveguides/plot_10_graded_index_fibre.codeobj.json @@ -1095,8 +1095,8 @@ { "is_class": false, "is_explicit": false, - "module": "solprop.output.schema", - "module_short": "solprop.output", + "module": "solprop.output.store", + "module_short": "solprop.output.store", "name": "PlaneStore.fields" }, { diff --git a/docs/auto_tutorials/waveguides/plot_10_graded_index_fibre.ipynb b/docs/auto_tutorials/waveguides/plot_10_graded_index_fibre.ipynb index 9b989a4b7..48383f987 100644 --- a/docs/auto_tutorials/waveguides/plot_10_graded_index_fibre.ipynb +++ b/docs/auto_tutorials/waveguides/plot_10_graded_index_fibre.ipynb @@ -125,7 +125,7 @@ "name": "python", "nbconvert_exporter": "python", "pygments_lexer": "ipython3", - "version": "3.14.5" + "version": "3.14.6" } }, "nbformat": 4, diff --git a/docs/auto_tutorials/waveguides/plot_10_graded_index_fibre.rst b/docs/auto_tutorials/waveguides/plot_10_graded_index_fibre.rst index 8063503fb..1b292aee8 100644 --- a/docs/auto_tutorials/waveguides/plot_10_graded_index_fibre.rst +++ b/docs/auto_tutorials/waveguides/plot_10_graded_index_fibre.rst @@ -256,7 +256,7 @@ channel. .. rst-class:: sphx-glr-timing - **Total running time of the script:** (0 minutes 12.315 seconds) + **Total running time of the script:** (0 minutes 8.035 seconds) .. _sphx_glr_download_auto_tutorials_waveguides_plot_10_graded_index_fibre.py: diff --git a/docs/auto_tutorials/waveguides/plot_10_graded_index_fibre.zip b/docs/auto_tutorials/waveguides/plot_10_graded_index_fibre.zip index 51e7d4713..2508bbff0 100644 Binary files a/docs/auto_tutorials/waveguides/plot_10_graded_index_fibre.zip and b/docs/auto_tutorials/waveguides/plot_10_graded_index_fibre.zip differ diff --git a/docs/conf.py b/docs/conf.py index 04b388ce2..fda995f43 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -25,6 +25,9 @@ from sphinx_gallery.sorting import ExplicitOrder from sphinx_gallery.utils import get_md5sum +_DOCS = Path(__file__).parent +sys.path.insert(0, str(_DOCS)) # api_surface and gallery_session, named below + # Read the Docs discards the log of a build it stops at its time limit. There # `docs/build-on-read-the-docs.sh` sets SOLPROP_DOCS_WATCHDOG to a delay in seconds # after which every thread's stack is written to the log, before the build is stopped. @@ -41,11 +44,6 @@ if importlib.util.find_spec("solprop_native") is not None: importlib.import_module("solprop_native") -# Initialise the reference backend through its package entry point before -# autosummary visits its implementation modules in an arbitrary order. Importing -# populations first encounters the package's existing circular initialisation. -importlib.import_module("solprop.backends.numpy_ref") - project = "solprop" author = "John C. Travers and contributors" copyright = "2026, John C. Travers and contributors" @@ -78,6 +76,9 @@ "tutorials/*/README.rst", "examples/README.rst", "examples/*/README.rst", + # Archived enhancement proposals are kept in the repository as records, not built + # into the manual; pages link each one's file on GitHub (SEP 0, section 4). + "dev/seps/archive/**", ] # --- myst @@ -95,6 +96,11 @@ # --------------------------------------------------------------------- autosummary_generate = True autosummary_imported_members = False +# A package page documents the public names that no submodule's page can (the module +# template says why); `tests/test_api_reference.py` holds the result to `__all__`. +autosummary_context = { + "package_members": importlib.import_module("api_surface").package_members() +} # Source links belong to the defining module. Following re-exported aliases makes # viewcode reuse one alias prefix with another page's anchors, breaking backlinks. # The complete API still documents aliases; their home modules retain source links. @@ -137,8 +143,6 @@ nitpicky = True nitpick_ignore = [ ("py:class", "logging.Logger"), - # Removed with numba_cpu (SEP 43); the Final SEP 18 keeps its reference as history. - ("py:mod", "solprop.backends.bodies"), # The private base of the two tabulated hollow modes. `show-inheritance` # emits it under "Bases:" for both subclasses; documenting it to satisfy the # reference would publish an underscore name in the API reference and its @@ -185,13 +189,13 @@ # Three galleries, each with committed output: the introductory lessons # (`introduction/tutorials/` → `introduction/lessons/`), which run developed physical # problems; the focused tutorials (`tutorials/` → `auto_tutorials/`); and the worked -# examples (`examples/` → `auto_examples/`), full-size runs of minutes to half an hour -# each. A normal build executes none of them: their generated pages, figures and -# sphinx-gallery checksums are committed, and sphinx-gallery reuses a script's stored -# output unchanged whenever the source's checksum matches the stored one. The build -# that publishes the manual therefore runs no gallery (Read the Docs' builders stalled -# on the lessons and tutorials from 2026-10-29); its only propagations are three short -# `.. plot::` blocks on `numpy_ref` in `guide/waveguides/` (`vector-wall.md`, and +# examples (`examples/` → `auto_examples/`), full-size runs of a few seconds to about +# ten minutes each. A normal build executes none of them: their generated pages, figures +# and sphinx-gallery checksums are committed, and sphinx-gallery reuses a script's +# stored output unchanged whenever the source's checksum matches the stored one. The +# build that publishes the manual therefore runs no gallery (Read the Docs' builders +# stalled on the lessons and tutorials from 2026-10-29); its only propagations are three +# short `.. plot::` blocks on `numpy_ref` in `guide/waveguides/` (`vector-wall.md`, and # `coherent-wall.md` twice). # # `SOLPROP_RUN_EXAMPLES` executes them. "stale" (`poe docs-examples`) runs every @@ -206,8 +210,6 @@ # code and figures disagree, with nothing on it to say so, and rendering it without # output would overwrite the committed page in the working tree. The refusal names the # command that refreshes it (`_check_committed_galleries` below). -_DOCS = Path(__file__).parent -sys.path.insert(0, str(_DOCS)) # gallery_session, named below _GALLERIES = ( (_DOCS / "introduction" / "tutorials", _DOCS / "introduction" / "lessons"), (_DOCS / "tutorials", _DOCS / "auto_tutorials"), diff --git a/docs/dev/accuracy.md b/docs/dev/accuracy.md index 7fbcaed0b..706ea57b3 100644 --- a/docs/dev/accuracy.md +++ b/docs/dev/accuracy.md @@ -28,10 +28,10 @@ reduced CtC archive's own plane zero to 1.2e-11. term at first order in the window factor, whatever the boundary does: Kerr-generated content at the band's low-frequency edge, where the spectral collar and the mask are sampled on bins that move with the bin spacing. [SEP 21's phase -0a](seps/archive/sep-0021-absorbing-boundaries.md#phase-0a--decisions-and-interim-findings) measured it, and no test holds it: +0a](https://github.com/LupoLab/solprop/blob/main/docs/dev/seps/archive/sep-0021-absorbing-boundaries.md#phase-0a--decisions-and-interim-findings) measured it, and no test holds it: widening the band from 1.6 to 3.2 µm cut the edge energy from 2.5e-3 to 1.4e-6 and the term about threefold; it floors every requested-window comparison at order 1e-5 (1.9e-5 -on the canonical case, [findings](seps/archive/sep-0021-absorbing-boundaries.md#phase-0a-report--2026-10-25) item 1); and +on the canonical case, [findings](https://github.com/LupoLab/solprop/blob/main/docs/dev/seps/archive/sep-0021-absorbing-boundaries.md#phase-0a-report--2026-10-25) item 1); and field errors near 1e-4 on smooth windows are this term, not the boundary (item 13). A boundary is therefore measured with and without temporal absorption at equal window, or against references extrapolated as $2F(2M) - F(M)$, whose uncertainty there was 4e-6 @@ -48,7 +48,7 @@ to 5e-5 per case ([the boundaries guide](../guide/numerics/boundaries.md#watchin | the parameter expansion against the z table | 9.8e-10 on the RDW capillary and 4.9e-9 on the reduced M2 case, each two orders inside the tolerance both are built to | `tests/translate/test_linop.py` | | ionisation rate tables | relative error falls at fourth order as the knots double; 1e-6 relative at 257 knots for optmat's PPT form of every noble gas | `tests/translate/test_ionisation_tables.py` | | the plasma column's cumulative trapezoid | second order in the sample spacing on a constant field: 9.9e-5 at 8193 samples, falling by four at each doubling; a pre-ionised tone has the Drude susceptibility times the two integrals' multiplier, $((\theta/2)\cot(\theta/2))^2$, to round-off — 3.7e-8 short of it at $\theta = 4.7\times10^{-4}$, 0.8225 of it at the default grid's $\omega_{\max}$ and 0.7866 at $1.1\,\omega_{\max}$ (below) | `tests/nonlinear/test_plasma.py` | -| the plasma column's band rule ([SEP 18](seps/archive/sep-0018-band-exact-plasma-integrals.md)) | the composite multiplier within a certified $10^{-5}$ of one across the active band; on ionising fields $\le 6.5\times10^{-6}$ per band against an independent reference, and over ten propagation steps $\le 4.2\times10^{-6}$ (below) | `tests/nonlinear/test_plasma_band*.py`, `tests/driver/test_plasma_band_propagation.py` | +| the plasma column's band rule ([SEP 18](https://github.com/LupoLab/solprop/blob/main/docs/dev/seps/archive/sep-0018-band-exact-plasma-integrals.md)) | the composite multiplier within a certified $10^{-5}$ of one across the active band; on ionising fields $\le 6.5\times10^{-6}$ per band against an independent reference, and over ten propagation steps $\le 4.2\times10^{-6}$ (below) | `tests/nonlinear/test_plasma_band*.py`, `tests/driver/test_plasma_band_propagation.py` | | the Raman kernel's normalisation | analytic against quadrature; the dephasing-capped decay exponent; the window residual reported at debug level | `tests/nonlinear/test_raman.py` | ```{eval-rst} .. plot:: @@ -105,7 +105,7 @@ the default `ffac = 6`. A physical-polarisation evaluation applies the rule thre $\int fE$ gives $J_{\rm free}$, and $\int(J_{\rm free} + J_{\rm loss})$ gives $P$. The loss current goes through one integral and the Drude term through two. The production column stops at the current and forms the held source in frequency -([SEP 27](seps/archive/sep-0027-held-plasma-current.md)): its interior Drude multiplier +([SEP 27](https://github.com/LupoLab/solprop/blob/main/docs/dev/seps/archive/sep-0027-held-plasma-current.md)): its interior Drude multiplier has one integration factor, and its loss current has none. The two-integral values below qualify the direct physical response: @@ -119,7 +119,7 @@ below qualify the direct physical response: The two-integral identity on a pre-ionised tone is exact to round-off and held by `tests/nonlinear/test_plasma.py`. That is the trapezoid rule, `integration="trapezoid"`, which the comparisons with Luna use. The band rule of -[SEP 18](seps/archive/sep-0018-band-exact-plasma-integrals.md) filters each integrand with taps +[SEP 18](https://github.com/LupoLab/solprop/blob/main/docs/dev/seps/archive/sep-0018-band-exact-plasma-integrals.md) filters each integrand with taps designed for the grid ([field plasma](../guide/media/field-plasma.md#how-the-current-integrals-are-formed)). It brings the composite multiplier to within a certified $10^{-5}$ of one across the active band: $K = 4$ and $4.92\times10^{-6}$ at `ffac = 6`, $K = 7$ at `ffac = 4`. It is @@ -286,7 +286,7 @@ were of the reduced case (two modes, 1 m: the fundamental's shape and content, t 100–140 nm band and its arrival, the second mode's energy) and the full case (four modes, 1.5 m, against production Luna at `rtol = 1e-6` and a converged Luna at `rtol = 1e-9`), and each ran a private, test-only copy of the time-domain gated plasma -source that Luna steps. Since [SEP 27](seps/archive/sep-0027-held-plasma-current.md) +source that Luna steps. Since [SEP 27](https://github.com/LupoLab/solprop/blob/main/docs/dev/seps/archive/sep-0027-held-plasma-current.md) solprop's plasma is the held current, which no stored Luna run computes, so with that gated source removed nothing compares like with like, and the comparisons and their field archives went with it. What stays compared with Luna is what such a comparison @@ -318,7 +318,7 @@ was the boundary's (SEP 21, D2). The installed native backend against `numpy_ref`, bounds derived from summation lengths and then measured; the measured values are the native CPU build's unless a row names another. No comparison is bitwise -([SEP 25](seps/archive/sep-0025-rounding-level-reproducibility.md)): independent +([SEP 25](https://github.com/LupoLab/solprop/blob/main/docs/dev/seps/archive/sep-0025-rounding-level-reproducibility.md)): independent floating-point computations are compared by numerical error — numpy's complex multiply can contract into a fused multiply-add where a compiled kernel's does not — so every round-off bound is a multiple of ε. The ladder has two kinds of row, and the criterion @@ -471,7 +471,7 @@ field's contraction pragma removed - **Accepted-step counts.** Luna's are not reproducible across machines (4856 against 4851 on one case); solprop's were identical on both when measured, an observation rather - than a requirement ([SEP 25](seps/archive/sep-0025-rounding-level-reproducibility.md)). + than a requirement ([SEP 25](https://github.com/LupoLab/solprop/blob/main/docs/dev/seps/archive/sep-0025-rounding-level-reproducibility.md)). solprop takes 58 % fewer steps than Luna on the M2 case at the same nominal tolerance, because the two norms mean different things. On the reduced CtC case (one mode, 2 ps) it takes 3163 accepted steps to Luna's 205; that gap is recorded and not yet explained. @@ -573,9 +573,9 @@ SOLPROP_WRITE_RECORDS=1 SOLPROP_NATIVE_THREADS=1 OMP_PROC_BIND=false \ **A write run is not a green run**: it says at the end which files it wrote, and those are what is committed. And because a stored number is a regression witness, a genuine *improvement* fails its comparison — the order is to commit the code with the records -red, regenerate, and commit the records. `uv run poe docs-clean` before `poe docs` if a -figure looks stale: the plot directive decides from the page's own timestamp, not the -record's. +red, regenerate, and commit the records. `uv run poe docs-clean`, which removes the build +output under `docs/_build`, before `poe docs` if a figure looks stale: the plot directive +decides from the page's own timestamp, not the record's. ## 10. Free space, tabulated, step-index and rectangular modes @@ -753,7 +753,7 @@ that comparison, not a general estimate for a changing basis. ## 12. Coupling between simulations -A coupling ([SEP 31](seps/archive/sep-0031-simulation-coupling.md), +A coupling ([SEP 31](https://github.com/LupoLab/solprop/blob/main/docs/dev/seps/archive/sep-0031-simulation-coupling.md), [the manual's chapter](../guide/workflows/coupling.md)) joins two runs that each have their own accuracy envelope; the coupling adds its own, and the three are kept apart rather than folded into one number. diff --git a/docs/dev/algorithms.md b/docs/dev/algorithms.md index 8451837de..4e30939e5 100644 --- a/docs/dev/algorithms.md +++ b/docs/dev/algorithms.md @@ -151,6 +151,14 @@ with $\beta_1 = 3/25$ and $\beta_2 = -1/25$ — Söderlind's $0.6$ and $-0.2$ di $k = q+1 = 5$, the **estimator's** order, not the scheme's — safety $S = 0.8$, growth cap $f_{\max} = 1.1$, and a lag of one step by default. +That is the Runge–Kutta march's controller (`RungeKutta()`). The Adams march +(`Multistep()`, the default on the capillary, radial and planar routes) scores its +predictor–corrector defect, scaled by the state before the step, and takes the elementary +factor $\operatorname{clip}\!\big(S\,e_n^{-1/(k+1)}, f_{\min}, f_{\max}\big)$ of the order +$k$ it chose, with $S = 0.8$, $f_{\min} = 0.2$ and its own growth cap $f_{\max} = 2$ +(`factor` in `backends/adams_core.py`; [stepper.md §2](stepper.md), *Low-call Adams +methods*). + **Where.** {py:func}`solprop.stepper.controller.weak_norm_scale` and {py:func}`solprop.stepper.controller.weighted_norm_scale`; {py:class}`solprop.stepper.controller.PIController`; @@ -190,7 +198,7 @@ reproducible, because {py:class}`solprop.stepper.controller.PIController` is fro `propose` is a pure function of the norm history; the replayed run is required to meet the overall accuracy target, not to reproduce the original run's bits or every adaptive decision ([stepper.md §8](stepper.md); -[SEP 25](seps/archive/sep-0025-rounding-level-reproducibility.md)). +[SEP 25](https://github.com/LupoLab/solprop/blob/main/docs/dev/seps/archive/sep-0025-rounding-level-reproducibility.md)). **Order and accuracy.** The controller chooses $h$; it does not change the order. The calibration gate refuses an observed order above $p + 3$ @@ -430,8 +438,8 @@ the product $E_jE_kE_l$ is symmetric in $(j, k, l)$, so the sum is evaluated as $\sum_m C_{im}\,(E_jE_k)E_l$ over the ten monomials $j \le k \le l$, with $C_{im}$ the sum of $A_{ijkl}$ over the orderings of monomial $m$ — an identity for any tensor — formed once per node and evaluation: 3 + 10 products a component a sample in place of -the dense 81 + 3, 2.5 times faster in the kernel of the since-retired `numba_cpu` -([benchmarks.md](benchmarks.md#general-route-symmetric-contraction)). The +the dense 81 + 3, which ran a two-channel step-index window 1.35 times faster at one +thread ([benchmarks.md](benchmarks.md#general-route-symmetric-contraction)). The order is fixed: the orderings in lexicographic order, the monomials likewise, every sum from zero; `numpy_ref` defines it and the native backend runs it. Its rounding is within $\gamma_{17}$ of $\sum_{jkl}|A_{ijkl}||E_j||E_k||E_l|$, against $\gamma_{14}$ for @@ -456,7 +464,7 @@ Final ionised inventory includes pre-ionisation; work done during the pulse coun $f_c-f_{0,c}$. **The rate.** solprop keeps no rate formula of its own -([SEP 3](seps/archive/sep-0003-optmat-materials.md), D1): every built-in rate is one of optmat's +([SEP 3](https://github.com/LupoLab/solprop/blob/main/docs/dev/seps/archive/sep-0003-optmat-materials.md), D1): every built-in rate is one of optmat's curated models — short-range PPT forms with Tong and Lin's barrier-suppression correction for the atoms, orientation-averaged molecular models for the molecules — adapted to the rate protocol by {py:class}`solprop.nonlinear.optmat_rates.OptmatRate`, @@ -502,14 +510,14 @@ $-i(\delta t/2)\cot(\omega\,\delta t/2)$, compared with the exact $-i/\omega$: the ratio is $(\theta/2)\cot(\theta/2)$ with $\theta=\omega\,\delta t_{\rm fine}$. The default field grid reaches $\theta=\pi/3$ at $\omega_{\max}$, giving 0.907. The production source does not integrate the current into a polarisation in time -([SEP 27](seps/archive/sep-0027-held-plasma-current.md)): it uses +([SEP 27](https://github.com/LupoLab/solprop/blob/main/docs/dev/seps/archive/sep-0027-held-plasma-current.md)): it uses $A_J=\operatorname{DFT}[gJ]/(i\omega)-\operatorname{DFT}[g'J]/(i\omega)^2$ on active bins, with exact zeros elsewhere, so the free-current dispersion has one running-integral multiplier and converting the loss current to its source has none. The physical `PlasmaResponse.evaluate` oracle integrates the current to an ungated polarisation. The band rule (`integration="band"`, -[SEP 18](seps/archive/sep-0018-band-exact-plasma-integrals.md)) keeps the running sums and filters +[SEP 18](https://github.com/LupoLab/solprop/blob/main/docs/dev/seps/archive/sep-0018-band-exact-plasma-integrals.md)) keeps the running sums and filters each integrand first. The filter has $2K+1$ symmetric taps designed in translation for the grid, so that the composite multiplier is within a certified $10^{-5}$ of one up to $1.1\,\omega_{\max}$. It uses $K = 4$ on the default grid and is refused below @@ -583,9 +591,10 @@ mask stays a 0/1 mask, idempotent, and never had the problem. **Where.** {py:func}`solprop.boundaries.collar_rate`, {py:func}`solprop.boundaries.temporal_collar_rate` and {py:func}`solprop.boundaries.absorber`; -{py:func}`solprop.boundaries.nonlinear_absorber_term` and -{py:func}`solprop.boundaries.split_step_factor` are the two temporal applications; -{py:func}`solprop.boundaries.stable_step`; {py:func}`solprop.boundaries.apply_band_mask`. +{py:func}`solprop.boundaries.nonlinear_absorber_term` is the in-stage temporal +application, and the reference backend's `apply_temporal_rate` +(`backends/numpy_ref/passes/stepping.py`) the split-step one; +{py:func}`solprop.boundaries.stable_step`. **Why a rate.** A per-step multiplicative window gives total absorption $W^n$ for however many steps the controller happened to take, so the physics becomes a function of `rtol`: @@ -608,7 +617,7 @@ problem, so an explicit method needs $h\alpha/2$ inside its stability region, an exactly and is unconditionally stable, which is the one thing it is better at; both stay implemented behind `absorber_scheme`, and the measured orders are in ADR-025. On the radial, Cartesian and planar routes the split is the default unless planes are -interpolated ([SEP 21](seps/archive/sep-0021-absorbing-boundaries.md)): there the +interpolated ([SEP 21](https://github.com/LupoLab/solprop/blob/main/docs/dev/seps/archive/sep-0021-absorbing-boundaries.md)): there the in-stage term took 1.2 to 4.6 times the split's steps at equal or worse accuracy. **Cost.** The spectral rate is free. The in-stage term costs one extra modal transform per @@ -633,7 +642,7 @@ ever cost stability. **The transverse collar's design check.** A free-space run's collar ({py:class}`solprop.spatial_absorber.SpatialAbsorber`) is checked at translation for what it sends back ({py:func}`solprop.translate.collar_check.design_check`, -[SEP 40](seps/archive/sep-0040-transverse-absorbing-boundaries.md) §4.4). A product of +[SEP 40](https://github.com/LupoLab/solprop/blob/main/docs/dev/seps/archive/sep-0040-transverse-absorbing-boundaries.md) §4.4). A product of plane-wave reflection and a ray share cannot say how much of a launch a collar returns: evaluated on the phase-0 witnesses it was wrong by up to nine decades, because the return lives in diffraction tails. So the check computes it. The launch is propagated linearly on @@ -707,7 +716,7 @@ evaluated every $N$ accepted steps through the same `stats` a plane uses, so a r the plane's own number to the statistic's rounding bound ([backends.md §1](backends.md)). **The reductions are two-stage**: a kernel writes one partial per column and the driver combines them. Their order is free -([SEP 25](seps/archive/sep-0025-rounding-level-reproducibility.md)): repeats and thread counts are +([SEP 25](https://github.com/LupoLab/solprop/blob/main/docs/dev/seps/archive/sep-0025-rounding-level-reproducibility.md)): repeats and thread counts are asserted against the reduction's rounding bound, not for identical bits, and a norm that moves in its last bit may fork an adaptive trajectory, which the accuracy envelopes of adaptive comparisons allow for. diff --git a/docs/dev/architecture.md b/docs/dev/architecture.md index 7a6f38d02..b4f170c90 100644 --- a/docs/dev/architecture.md +++ b/docs/dev/architecture.md @@ -71,19 +71,20 @@ Envelope plasma with THG is refused. The native CPU/CUDA/HIP paths have their own qualification. The [running guide](../guide/setup/running.md) and [backends.md](backends.md) record the qualified scope. -**Optional atomic response** ([SEP 12](seps/archive/sep-0012-tdse-nonlinear-response.md)). +**Optional atomic response** ([SEP 12](https://github.com/LupoLab/solprop/blob/main/docs/dev/seps/archive/sep-0012-tdse-nonlinear-response.md)). A scalar helium `TDSEGasResponse` owns the gas nonlinearity. Its immutable specification becomes a `TDSEDescriptor`; the driver lazily owns native plans and stable radial chunks and passes a narrow host binding explicitly to NumPy. The optical march uses Adams. Atomic device -execution is independent of the optical backend. The native backend refuses this -response by name. The kernel schema includes separate polarisation and current +execution is independent of the optical backend. The native CPU build executes this +response ([SEP 49](https://github.com/LupoLab/solprop/blob/main/docs/dev/seps/archive/sep-0049-tdse-on-native.md)); native device builds +refuse it by name. The kernel schema includes separate polarisation and current factors: current enters with `-1/(2 epsilon_0 c Re(n_eff))`, without division by frequency. The provider's raw discrete shadows are subtracted before density and calibration. Native retention subtracts only the first-order current and applies its explicitly declared positive scale to the whole nonlinear current; its polarisation contribution is zero. Its source is always gated and edge-free -([SEP 26](seps/archive/sep-0026-edge-free-tdse-source.md)): the backend multiplies the already subtracted remainder by its gate, +([SEP 26](https://github.com/LupoLab/solprop/blob/main/docs/dev/seps/archive/sep-0026-edge-free-tdse-source.md)): the backend multiplies the already subtracted remainder by its gate, `grids.t_window_fine` or the atomic window's, before source projection/FFT, and subtracts the gate's edge term `F[g' S]/(i omega)` on the active bins. The raw provider result, atomic drive and separate in-stage field absorber are unchanged. This is a recorded @@ -101,7 +102,7 @@ the window and the atomic cut error are unresolved saved output has a schema version and the kernel contract has none ([kernel contract](kernel-contract.md), ADR-068). -**haCC helium** ([SEP 20](seps/archive/sep-0020-hacc-helium-tdse.md)). The same route carries a second atomic model, the +**haCC helium** ([SEP 20](https://github.com/LupoLab/solprop/blob/main/docs/dev/seps/archive/sep-0020-hacc-helium-tdse.md)). The same route carries a second atomic model, the two-electron haCC atom (`TDSEGasResponse.model="hacc"` with a `HaccBasis`), at a fixed current scale of one. Its descriptor may carry an atomic window whose gate replaces the grid collar as the source gate; the binding slices and @@ -122,7 +123,7 @@ belong to the driver/binding, which runs the provider in a worker process of its provider's adapter): framed pipes, no pickle, cancellation while waiting; modal synthesis to the nodes, the assembly of the macroscopic sources and their projection belong to `backends/tdse_source.py`, which imports neither backend and which a backend calls from its source evaluation -([SEP 49](seps/archive/sep-0049-tdse-on-native.md)). See the [TDSE manual](../guide/media/tdse.md). +([SEP 49](https://github.com/LupoLab/solprop/blob/main/docs/dev/seps/archive/sep-0049-tdse-on-native.md)). See the [TDSE manual](../guide/media/tdse.md). Geometry: mode-averaged propagation is the single-node case of multimode propagation (the effective-area normalisation replaces the quadrature); the GNLSE is the mode-averaged @@ -156,7 +157,7 @@ request itself is T (`translate.run_request`), built from these records. **Rules are built in P.** `modes/quadrature.py` constructs its transverse rules numerically -- Laurie's Kronrod recursion, and the field-scale rules of -[SEP 19](seps/archive/sep-0019-field-scale-quadrature.md) by the Lanczos +[SEP 19](https://github.com/LupoLab/solprop/blob/main/docs/dev/seps/archive/sep-0019-field-scale-quadrature.md) by the Lanczos process and the Golub–Welsch eigenvalue method, certified on construction -- once per problem, and caches them, and it holds the Chebyshev–Lobatto points and coefficients that both a guide's sampling and T's tables are built on. A guide samples its provider @@ -181,6 +182,14 @@ native backend's own BLAS and does not import a backend; an already loaded nativ package supplies its library identity through `build_info`. See the [BLAS guide](../guide/performance/tuning.md#blas-and-vendor-libraries). +**Threaded passes over large arrays.** One performance measure is allowed in P: a NumPy +pass over an array of 64 MiB or more (`_process.PARALLEL_BYTES`) may split its rows over +threads within the thread budget through `_process.parallel_rows`, the pass's rows being +independent and NumPy's ufuncs releasing the GIL. `SpatialPulse.build` uses it for a large +beam launch (with its first touch per thread and its column norms reused), and so do the +host reduction of a state's energy into the boundary's split-rate buckets (`boundaries.py`) and the plane measure's admittance +(`spatial.py`). Smaller arrays run in one call, and nothing in P threads per step. + **Deliberate upward edges.** A handful of imports climb a layer, each for a reason recorded here and in the allowlist of `tests/test_layers.py`, which checks every import of the package -- at module level, inside a function or for typing -- and fails on any @@ -248,7 +257,7 @@ NumPy/SciPy/h5py/matplotlib. A value type in P may carry what T designed and apply it with NumPy alone: the plasma column's `nonlinear.ionisation.RunningIntegral` holds taps that `translate.plasma_integration` fits and certifies, and filters and sums with them -([SEP 18](seps/archive/sep-0018-band-exact-plasma-integrals.md)). +([SEP 18](https://github.com/LupoLab/solprop/blob/main/docs/dev/seps/archive/sep-0018-band-exact-plasma-integrals.md)). ## 4. Package layout @@ -267,18 +276,18 @@ against `src/solprop` by `tests/test_structure_figures.py`. | `linear.py`, `boundaries.py`, `spatial_absorber.py`, `monitor.py`, `transverse_monitor.py`, `nonlinear/` | Linear assembly; absorbing rates, in time and at a spatial grid's edge, and the monitors that read what a boundary absorbs (the time window's and the transverse edge's, under one `BoundaryCheck` policy); response definitions, ionisation, Raman, normalisation and the GNLSE mapping | P | | `translate/` | Validated `PropagationProblem` (`translate/problem.py`) and its route union (`translate/routes.py`), assembled by `assemble` (`translate/assembly.py`), with a capillary's coherent wall and taper coupling in `translate/walls.py` and the refusals and advisories assembly applies in `translate/validation.py`; parameter expansions and z tables; modal/radial/Cartesian transforms and the hybrid planar one (slab modes in x × FFT in y, `translate/planar.py`); dense tracked modal tables, the general modal route and the coupled-flow and metric records (`translate/general.py`, `translate/coupled.py`); the spatial plane measure (`translate/flux.py`, the `FluxPlan` of schema 35); the persisted frame integral and the filled input port of a problem's entrance (`translate/coupling.py`); what the general route and the coupled flow execute, checked once (`translate/admission.py`); response tables, masks and stage bundles | T | | `backends/` | Registry and protocols (`registry.py`, `protocol.py`); the session contract, its events and the run layer's one door to a backend's sessions (`session.py`, `events.py`, `sessions.py`), and export into a destination (`export.py`); the run records both backends read (`records.py`, SEP 52); the engine protocols the marches call (`engines.py`) and the march controllers native is traced against (`rk_core.py`, `adams_core.py`, `low_storage.py`); the exponential Adams weights (`exponential.py`); the Adams call ledger both backends keep (`ledger.py`); node chunks and the byte counts of the memory ledgers (`node_chunk.py`, `memory.py`); spatial and population statistics (`spatial.py`, `populations.py`); and the TDSE response's host source assembly (`tdse_source.py`) | B | -| `backends/numpy_ref/` | Reference execution: the passes (`passes/`), the workspace with its stage source, statistics and coupled flow, the engines, the Adams engine, kernels and tables, and the reference's own run session (`session.py`, composed of `session_parts.py`) with its Runge-Kutta, Adams and low-storage marches (`marches/`, [SEP 47](seps/archive/sep-0047-run-ownership.md) phase 2) | B | +| `backends/numpy_ref/` | Reference execution: the passes (`passes/`), the workspace with its stage source, statistics and coupled flow, the engines, the Adams engine, kernels and tables, and the reference's own run session (`session.py`, composed of `session_parts.py`) with its Runge-Kutta, Adams and low-storage marches (`marches/`, [SEP 47](https://github.com/LupoLab/solprop/blob/main/docs/dev/seps/archive/sep-0047-run-ownership.md) phase 2) | B | | `stepper/`, `stats/`, and in `output/`: `records.py`, `serialisation.py`, `provenance.py`, `metadata.py`, `store.py`, `capability.py` | The run specification: tableaux, controllers and schedules, and the stepper section of a run request (`stepper/settings.py`); the statistics definitions, catalogue, specification and their collection; and the run record: serialising configuration objects, what executed a run, the record types of a saved run and its planes, `RunMetadata` and the resume key, the save protocol with `PlaneStore` and field retention, and what a saved basis can be asked for | S | | `driver/`, `driver/routes/`, `driver/executors/`, `scan.py` | The `Simulation` object (`simulation.py`) with its settings and their admission (`settings.py`), its input, launch, noise and peak field (`inputs.py`), its run record (`metadata.py`), resume (`resume.py`), many-input runner (`runner.py`) and TDSE run glue (`tdse_run.py`), with the TDSE response's binding and diagnostics (`tdse.py`) and its consistency check (`tdse_consistency.py`); the run loop over save planes and the service loop that serves a session's events (`run.py`, `session_loop.py`), a run's fill and its material records (`mixtures.py`, `material_output.py`), the printed summary, cost estimate and defaults (`summary.py`, `estimate.py`, `defaults.py`) and the view of an observed plane (`plane_view.py`); the keyword routes behind its constructors, one module per family (`routes/`: GNLSE, hollow guides, general modal guides, spatial grids, and the material selection and keyword attribution they share); the convenience interfaces, scan orchestration, Local/Pool/Queue/Slurm execution and the scan command line | D | | `recipe/`, `cli.py` | A run written as a TOML recipe: its document format and upgrades, quantities with units, parameter paths and pins, the registry that decodes configuration objects, the route and type metadata a front end shows (`metadata.py`, `type_metadata.py`), previews, provenance and export to Python; and the `solprop` command line (`run`, `check`, `resume`, `calibrate`) | D | -| `calibration/` | The native backend's machine calibration ([SEP 46](seps/archive/sep-0046-machine-calibration.md)): reading, showing, exporting, importing and clearing profiles in the per-user store, through solprop-native's standard-library modules loaded by path so that the native runtime never starts (`calibration/_native.py`), the measuring controller, its child processes, the synthetic problems they time, the operation-grain candidates and the selection rule (`calibration/controller.py`, `child.py`, `problems.py`, `grain.py`, `selection.py`), the refinement of one simulation (`calibration/refine.py`, stage 2, which `Simulation.calibrate` runs), the first-use check that a native run has a profile (`calibration/first_use.py`), and the `solprop calibrate` command (`calibration/command.py`). It imports `solprop_native` directly, below the seam (section 3) | D | +| `calibration/` | The native backend's machine calibration ([SEP 46](https://github.com/LupoLab/solprop/blob/main/docs/dev/seps/archive/sep-0046-machine-calibration.md)): reading, showing, exporting, importing and clearing profiles in the per-user store, through solprop-native's standard-library modules loaded by path so that the native runtime never starts (`calibration/_native.py`), the measuring controller, its child processes, the synthetic problems they time, the operation-grain candidates and the selection rule (`calibration/controller.py`, `child.py`, `problems.py`, `grain.py`, `selection.py`), the refinement of one simulation (`calibration/refine.py`, stage 2, which `Simulation.calibrate` runs), the first-use check that a native run has a profile (`calibration/first_use.py`), and the `solprop calibrate` command (`calibration/command.py`). It imports `solprop_native` directly, below the seam (section 3) | D | | `output/` (the handlers) | Memory, HDF5 and callback outputs (`memory.py`, `hdf5.py`, `callback.py`), the TDSE archive, snapshots and resumability (`tdse_archive.py`, `snapshots.py`, `resumable.py`), scan storage and per-point artifacts (`scan.py`, `scan_artifacts.py`) and the writer and scan locks; the record types they write are S, above | D | | `processing/`, `plotting/`, `sol.py`, `capabilities.py` | Field, spectrum, time, coherence, compression, mixture and scan analysis; a saved plane read back as a field plane or a fluence map (`processing/planes.py`), and a field plane's file form (`processing/plane_file.py`); propagation/statistics plots and spectrograms; the interactive session namespace, the one module whose import has side effects; and the capability report of what a route, species or saved output supports (`capabilities.py`) | X | | `service/` | Front-end support, above every other layer: the messages between a front end and solprop, the kernel process that answers a front end's checks, previews and readings of a results file as plain data, each run as a job that keeps its record in its folder, and the helper and connection that reach a machine's runs over SSH ([the front end's design](gui/design.md), sections 13.3 and 13.4). Not part of the user API and outside the stability promise; nothing else in solprop imports it | X | `solprop-native` is the backend's second distribution, built from `native/` in this repository at solprop's own version, and a required dependency of solprop pinned to that -version ([SEP 43](seps/archive/sep-0043-retire-numba-cpu.md)). It depends on the seam, +version ([SEP 43](https://github.com/LupoLab/solprop/blob/main/docs/dev/seps/archive/sep-0043-retire-numba-cpu.md)). It depends on the seam, which has no version number: the pin and `check_build` guard it (ADR-068). `solprop-gui`, the desktop front end, is the third, built from `gui/` at solprop's @@ -369,7 +378,8 @@ driver does not do is as much a part of the design as what it does: - It **never conjugates a spectrum**. The backend works in the FFT convention, the output layer's recipe converts on the way to disk -- applied by the session as it exports a kept field into the store ([backends.md §1](backends.md#1-the-seam), "Export into a - destination") -- and those are the only two places a sign changes. + destination"). Where the sign changes is listed once, in + [conventions.md §2](conventions.md#2-fourier-transform-and-the-sign-of-propagation-adr-017). - It **never touches the state between planes**. Everything between two save planes happens inside the backend's march. - It **never computes physics**. The mapping from `gamma` to a susceptibility is @@ -393,9 +403,9 @@ ModalProvider -> DenseModalTable -> ModalTransformTables -> PropagationPro `FieldGrid` and `EnvelopeGrid` implement one protocol: time axis `t` (`n_t` points, spacing `δt`), coarse frequency axis `omega` (`n_omega`: `n_t/2+1` for the field grid, `n_t` for the -envelope grid in FFT order), the oversampled fine axes `t_fine`/`omega_fine` (factor `ffac`: -6 for a cubic field response with third-harmonic content, 4 for `|E|²E`, 1 or 2 for -envelopes), the in-band mask (physical frequencies inside the wavelength limits), the +envelope grid in FFT order), the oversampled fine axes `t_fine`/`omega_fine` (factor `ffac`, +at least 2: by default 6 on the field grid, and on the envelope grid 6 with third-harmonic +content and 2 without), the in-band mask (physical frequencies inside the wavelength limits), the spectral and temporal collar profiles, and the reference frequency `ω₀`. The temporal collar lies outside the requested window: the realised window is at least `trange / (1 − 2 collar_fraction)`, `collar_fraction` 0.1 by default (ADR-057). Sizes are even @@ -414,7 +424,8 @@ model allows; a validated finite-difference fallback otherwise, ADR-006), `field (transverse field components at points), `dimlimits(z)`, `aeff(z)`, and the traits `z_constant`, `scale_invariant`, `azimuthal_order`. Derived quantities (β, α, β₁, β₂, ZDW, loss length) are protocol-level functions. `MarcatiliMode` (hollow capillary, full and reduced -models, loss as a Boolean, scale factor or callable of ω) shares gas-fill machinery +models, the model's loss scaled by `loss_scale` or replaced by an absolute `alpha`, a number or +callable of ω) shares gas-fill machinery with the tabulated and rectangular hollow modes; the core index is a `ZProfile`-aware object so gradients and tapers are ordinary cases. `n_eff − 1` is computed directly, never as `(1 + x) − 1`. @@ -428,8 +439,9 @@ exact on pieces certified monotone. An arbitrary callable must declare its turni points to have one; sampling is not an enclosure. The adiabatic certificate (`adiabatic.py`, SEP 34 §4.5) builds on it. Pressure gradients use the steady-flow profile `p(z) = sqrt(p₀² + (z/L)(p₁² − p₀²))`; fills must not start or end at exactly zero -pressure (a vacuum-terminated fill caps every scheme at order ~3, [stepper.md](stepper.md) -§10; the interface substitutes a small floor and logs it). A steady-flow fill of a +pressure (a vacuum-terminated fill caps every scheme at low order, 1.4 to 1.6 measured, +[accuracy.md §5](accuracy.md#5-milestone-m2-the-rdw-example-four-modes-15-m-gradient) and +[stepper.md](stepper.md) §10; the interface substitutes a small floor and logs it). A steady-flow fill of a hollow fibre (`gasflow.py`) follows the bore and chokes at its vacuum end (ADR-032). `modes/quadrature.py` builds the fixed transverse rules (Gauss–Legendre radial with Kronrod @@ -444,7 +456,7 @@ transform, and only `mode_averaged_transform` makes `Transform.kind == "mode_ave ### 6.3 Materials (`physdata/`) -solprop keeps no material database of its own ([SEP 3](seps/archive/sep-0003-optmat-materials.md)). +solprop keeps no material database of its own ([SEP 3](https://github.com/LupoLab/solprop/blob/main/docs/dev/seps/archive/sep-0003-optmat-materials.md)). Every built-in material is optmat's, adapted at the boundary: a gas's polarizability (`OptmatSusceptibility`), equation of state and transport (`OptmatGas`) and electronic Kerr model at the carrier (`OptmatKerr`), its first ionisation energy, and the solids' @@ -546,7 +558,7 @@ shared groups are common to every route; what differs between routes is one vari closed union, `problem.route` (`translate/routes.py`: `ModalRoute`, `GeneralRoute` or `SpatialRoute` of kind radial, Cartesian, planar or line), each with the fields its executor needs, which every backend visits explicitly and refuses by name before it -allocates ([SEP 47](seps/archive/sep-0047-run-ownership.md) §6.2). Beside the problem it +allocates ([SEP 47](https://github.com/LupoLab/solprop/blob/main/docs/dev/seps/archive/sep-0047-run-ownership.md) §6.2). Beside the problem it returns the run's `RunRequest` (`translate/run_request.py`): the stepper settings with the route's defaults filled and the collars' limits applied, the save planes and the statistics, which are how the problem is run and not what it means (SEP 47 §5.2; @@ -579,7 +591,14 @@ changes. ## 8. The solver, in one page -Details and evidence are in [stepper.md](stepper.md). The anatomy of one stage `i` of the +Details and evidence are in [stepper.md](stepper.md). There are three integrators +([stepper.md §2](stepper.md)): `Multistep()`, the exponential Adams method, one source +evaluation per accepted step, the default on the capillary, radial and planar routes and +for settings built by hand; `RungeKutta()`, interaction-picture DOPRI5, the default on the +GNLSE, waveguide, slab and Cartesian and line free-space routes +(`solprop.driver.defaults.ROUTE_DEFAULTS`); and the replay-only `LowStorageRungeKutta()`. +Every one evaluates the same source passes (2 to 6 below); the Adams and low-storage +engines evaluate them at a lab-frame field. The anatomy of one stage `i` of the interaction-picture DOPRI5 step from anchor `z_n`, for a multimode field-grid problem, as the backend executes it (each numbered line is one pass over its data; the FFT counts are the cost metric): @@ -597,11 +616,11 @@ two temporal transforms to that modal route. Radial propagation instead transfor combines the three streams per node, crops, then projects once in frequency. Cartesian and line propagation combine before the transverse FFT; planar propagation projects in x before the temporal transforms and combines before the y transform. These orders -and their buffer budgets are part of [SEP 27](seps/archive/sep-0027-held-plasma-current.md). +and their buffer budgets are part of [SEP 27](https://github.com/LupoLab/solprop/blob/main/docs/dev/seps/archive/sep-0027-held-plasma-current.md). These are passes over data, not launches. -Per step: six new nonlinear evaluations with FSAL (seven without it), with the modal +Per Runge–Kutta step: six new nonlinear evaluations with FSAL (seven without it), with the modal batched transforms above plus the doubled-grid pairs for Raman, 6 `exp(ΔΦ_i)` evaluations (or 5 with FSAL and memoisation), one controller decision (lagged, with rejection allowed by default; `reject_free` is explicit), one accept pass (`y ← exp(ΔΦ)·(y + h·acc_sol)` — the stages live in the interaction variable anchored at the step start, so the whole sum is carried by one exponential, and the embedded difference takes the same factor — rebase the FSAL stage, apply @@ -628,7 +647,7 @@ are counted separately in the backend ledger. Examples: | RDW VUV: n_t 4096, 4 modes | 0.13 MB | ~2 MB | ~3 MB | ~8 MB | | CtC: n_t 32768, 6 modes, Raman | 1.6 MB | ~20 MB | ~45 MB | ~210 MB | -**The low-storage march** ([SEP 24](seps/archive/sep-0024-low-storage-interaction-picture-runge-kutta.md), +**The low-storage march** ([SEP 24](https://github.com/LupoLab/solprop/blob/main/docs/dev/seps/archive/sep-0024-low-storage-interaction-picture-runge-kutta.md), ADR-050) is RK4 in the midpoint interaction picture, replay-only and accepted in place: each slope is folded into a running sum as it is produced, so a step holds the state, an accumulator and a stage register beside the evaluation's scratch, plus the half-step flow @@ -649,12 +668,16 @@ propagated state*, never at the array-namespace level class Backend(Protocol): name: str + @property + def request(self) -> RunRequest: ... # the run request it was built for def prepare(self, problem, request) -> PreparedExecution: ... # a run's session - def timing_probe(self, start) -> TimingProbe: ... # an estimate's trial def metadata(self) -> dict[str, object]: ... # what the execution was - def available_device_memory(self) -> int | None: ... + def edge_memory(self, space) -> int: ... + def timing_probe(self, start) -> TimingProbe: ... # an estimate's trial def memory_ledger(self) -> dict[str, int]: ... def close(self) -> None: ... + @property + def closed(self) -> bool: ... # Nothing else: a run is its session's on both backends (SEP 52). Behind the # protocol each backend has a lowering, a workspace, engines, marches and a @@ -667,20 +690,21 @@ class Backend(Protocol): - `native` (the `solprop-native` distribution, `native/`): C++20/Kokkos kernels and persistent Kokkos-FFT plans behind nanobind. It runs mode-averaged and multimode scalar/two-component problems, Kerr, plasma and declared tensor Raman, weighted control, embedded quadrature and - backend-owned statistics with one native call per trial, and on its CPU build also the - general modal route and the coupled flow. Raman uses doubled-grid plans, actual-width + backend-owned statistics with one native call per trial, and also the general modal + route and the coupled flow, on its CPU and device builds + ([backends.md §9](backends.md#9-what-runs-where)). Raman uses doubled-grid plans, actual-width tails and memoisation by decay rates and mixture amplitude densities. KokkosKernels supplies the portable GEMM seam; measured local builds may dispatch eligible whole transforms to Accelerate, OpenBLAS or cuBLAS. The CUDA build uses time-parallel response teams, deterministic plasma scans and device reductions and is qualified on - data-centre NVIDIA GPUs; the HIP build is qualified on AMD Instinct GPUs, with the HIP - sanitizer run still outstanding. The private state is read only by the backend's own + data-centre NVIDIA GPUs, with the CUDA sanitizers clean; the HIP build is qualified on AMD + Instinct GPUs, for which ROCm ships no device sanitizer. The private state is read only by the backend's own session and timing probe. The binding is small (SEP 52, ADR-079): a `_core.Workspace` built from one `_core.Problem`, a run started from one run record (`start(run)`), the probe (`probe(start)`) and one `diagnostics()` record; every record crosses by its field table, the binding only marshals, and test-only entry points live in the private `_core._testing`. Its floating-point licence is - [SEP 25](seps/archive/sep-0025-rounding-level-reproducibility.md)'s: contraction by default, + [SEP 25](https://github.com/LupoLab/solprop/blob/main/docs/dev/seps/archive/sep-0025-rounding-level-reproducibility.md)'s: contraction by default, strict opt-outs for the protected helpers (stable increments, small-argument functions, defects, compensated sums), reassociation only on the loops of a kernel that asks for it, and no other fast-math flag ([backends.md §3.2](backends.md)). @@ -707,7 +731,7 @@ A TDSE run may also write its raw provider evaluations to a separate archive (`output/tdse_archive.py`, schema `solprop.tdse-archive.v1`), which the optical record references and never needs ([the archive page](../guide/media/tdse.md)). -A kept field reaches a store once, already converted ([SEP 47](seps/archive/sep-0047-run-ownership.md) +A kept field reaches a store once, already converted ([SEP 47](https://github.com/LupoLab/solprop/blob/main/docs/dev/seps/archive/sep-0047-run-ownership.md) §5.4): the run's session exports it in the stored form straight into the room the store gives (`PlaneStore.field_destination`) -- `MemoryOutput`'s own block row, or a new array that `HDF5Output` writes as it is -- and `PlaneStore.save_exported` stores the plane. The @@ -803,7 +827,7 @@ its execution space. `HDF5Output` ([backends.md §1](backends.md#1-the-seam), "Export into a destination"). - A run keeps its fields on every plane, the named planes or none (`FieldRetention`, - [SEP 22](seps/archive/sep-0022-memory-lean-spatial-execution.md)): a plane without its field is not copied, converted or + [SEP 22](https://github.com/LupoLab/solprop/blob/main/docs/dev/seps/archive/sep-0022-memory-lean-spatial-execution.md)): a plane without its field is not copied, converted or stored, the stores allocate field storage for the kept planes only, and the admission charges those alone (its `output` group). The backend is asked for the field only on the kept planes: a field-free observation transfers nothing from a device, @@ -823,7 +847,7 @@ its execution space. its load. A caller that identifies its input states that instead (`StatedInput`), and nothing digests it. - Φ tables are shared where possible; the constant-D fast path stores one array. -- Fine-grid buffers use the smallest `ffac` the declared responses need. +- Fine-grid buffers are sized by the grid's `ffac` (§6.1), not by the declared responses. ## 14. Logging and progress @@ -902,8 +926,8 @@ section of the operator table's breakpoints, in one of two ways: the generator — its z variation and the connection — as an explicit residual that the Runge–Kutta source carries, so the embedded pair sees its error. -The coupled flow runs on `numpy_ref` and the native CPU build, which forms -the per-bin flow actions in its own kernels and agrees with the reference to a derived +The coupled flow runs on `numpy_ref` and on native, whose CPU and device builds form +the per-bin flow actions in their own kernels and agree with the reference to a derived rounding bound; a certificate records each flow's conditioning. A multimode capillary taper carries the taper coupling by default; `taper_coupling=False` is the explicit opt-out to the adiabatic route diff --git a/docs/dev/backends.md b/docs/dev/backends.md index da1bc2598..1dc257986 100644 --- a/docs/dev/backends.md +++ b/docs/dev/backends.md @@ -15,7 +15,7 @@ Public simulation settings default to `backend="auto"`. `resolve_name` probes th native package without importing it, resolves to `"native"` if it is installed and the processor is at or above a build's baseline, and otherwise raises `BackendError`, saying what to do; it stores that name before execution or worker transfer. `auto` has no fallback. -Native being installed is a packaging policy ([SEP 43](seps/archive/sep-0043-retire-numba-cpu.md) §5), +Native being installed is a packaging policy ([SEP 43](https://github.com/LupoLab/solprop/blob/main/docs/dev/seps/archive/sep-0043-retire-numba-cpu.md) §5), so a run does not have to prove that native could execute here, and nothing loads a runtime to enforce it. A TDSE response's `auto` resolves to `native` like every other run (SEP 49, ADR-078). Explicit names are preserved, so `backend="numpy_ref"` runs where @@ -39,17 +39,16 @@ class Backend(Protocol): @property def request(self) -> RunRequest: ... # the run request it was built for def prepare(self, problem, request) -> PreparedExecution: ... # a run's session - def timing_probe(self, start: Start) -> TimingProbe: ... # commits nothing - def edge_memory(self, space: object) -> int: ... def metadata(self) -> dict[str, object]: ... # what the execution was + def edge_memory(self, space: object) -> int: ... + def timing_probe(self, start: Start) -> TimingProbe: ... # commits nothing def memory_ledger(self) -> dict[str, int]: ... - def available_device_memory(self) -> int | None: ... def close(self) -> None: ... # idempotent @property def closed(self) -> bool: ... # a failure can close a backend ``` -That is the whole protocol ([SEP 52](seps/archive/sep-0052-backend-shape.md) §5.1): a run goes through the backend's session +That is the whole protocol ([SEP 52](https://github.com/LupoLab/solprop/blob/main/docs/dev/seps/archive/sep-0052-backend-shape.md) §5.1): a run goes through the backend's session (`prepare(...).start(...)`, SEP 47 §5.2), which loads the start, schedules the run, reports its events and exports its fields, on both backends. Each backend has the same five parts behind it: a lowering, a workspace that holds the state and does every @@ -70,11 +69,12 @@ are traced against, and the exponential coefficients and the preparation refusal once per run by shared code; native's cross the seam by field table (§4). The listing is abbreviated; `solprop/backends/protocol.py` holds the exact signatures and -docstrings, in the order of [architecture.md §9](architecture.md#9-backends-in-one-page). +docstrings, in this order, which [architecture.md §9](architecture.md#9-backends-in-one-page) +follows. Rules: a backend is constructed from a validated `PropagationProblem` ([kernel-contract.md](kernel-contract.md)), the `RunRequest` that carries the run's -policy ([SEP 47](seps/archive/sep-0047-run-ownership.md) §5.2; it checks the two with +policy ([SEP 47](https://github.com/LupoLab/solprop/blob/main/docs/dev/seps/archive/sep-0047-run-ownership.md) §5.2; it checks the two with `validate_run` before it allocates) and host arrays, and returns host arrays; its buffers, layout and plans are private; the state is never a parameter of anything a session is asked; the numbers are the contract — a backend is correct when it reproduces the @@ -92,11 +92,10 @@ the reference as `solprop.backends.numpy_ref.NumpyRefBackend` and the native bac as `solprop_native.NativeBackend`, each called as `factory(problem, request, *, grid, modes, profiles, tdse_binding, options)`, importing each only when -it is selected. Before a native construction it runs SEP 46's first-use calibration; -`SOLPROP_REQUIRE_DEVICE` reads the installed native build's `build_info()` (the -reference is refused a required device by name); and `statistics_refusal` reads the -far-field statistics `NativeBackend.far_field_statistics` declares. `auto` is -`registry.AUTO`, `native`, with no fallback. +it is selected. `SOLPROP_REQUIRE_DEVICE` is checked first, against the installed +native build's `build_info()` (the reference is refused a required device by name); +only then, before a native construction, does it run SEP 46's first-use calibration. +`auto` is `registry.AUTO`, `native`, with no fallback. **Periodic statistics are the session's.** Each session decides which accepted steps produce rows and keeps them between events: the reference's in a host buffer it drains at @@ -117,15 +116,13 @@ through `warnings.warn` as before. Both sessions report their execution facts th interface. A fixed-schedule `Batch` executor and its groups (`GroupSession`, `prepare_group`, the reference's lockstep `HostGroup` and `NumpyBatchBackend`, and the native group session) were removed by SEP 52: on native a group built a complete backend -per member and fused nothing. `available_device_memory()` returns free device bytes or -`None` on hosts, so that a scan's admission needs no backend-specific array library in -the driver. +per member and fused nothing. **Three things every backend owes, beyond the protocol's members.** **1. Reductions to the error bound.** The error norm and every statistic a backend reduces are compared by numerical error, not bits -([SEP 25](seps/archive/sep-0025-rounding-level-reproducibility.md)): a reduction may be ordered, +([SEP 25](https://github.com/LupoLab/solprop/blob/main/docs/dev/seps/archive/sep-0025-rounding-level-reproducibility.md)): a reduction may be ordered, chunked and threaded however measures fastest, provided its rounding bound, `γ_n` of the sum of the magnitudes for a reduction of length `n`, is the one its tests assume. The norm is *control flow*: it decides whether a step is accepted and what the next proposal is, so @@ -148,7 +145,7 @@ thread against many on a fixed schedule within the step's rounding bound. small bundle of host scalars (`translate.stage.scalars`) against a fixed set of arrays uploaded once (`translate.stage.terms`); `ΔΦ` is one linear combination of the terms over the bundle's floats and nothing about the representation reaches the backend -([kernel-contract.md §3](kernel-contract.md)). The contract's z-table fallback has no such +([kernel-contract.md §1](kernel-contract.md#1-identity-and-validation)). The contract's z-table fallback has no such split, so `PropagationProblem.device_ready` is false for it. NumPy evaluates the general representation directly. The native CPU build gives the table the split itself (SEP 29 section 6.6): its coefficients cross once, in the workspace's `Problem` (its `z_tables`, uploaded where the workspace is @@ -214,7 +211,7 @@ operation (SEP 52 §5.1). The backend builds a fresh march and engines for each | `HostAdamsMarch._replay_to` | Adams on a fixed schedule | the same engine | | `HostLowStorageMarch.replay_to`, in `backends/numpy_ref/marches/low_storage.py` | low-storage, always on a schedule | a `RungeKuttaEngine` with a destructive trial: `NumpyLowStorage` | | the native session's Adams march, `native/src/march/adams_march.cpp` | Adams, adaptive and replayed, compiled (ADR-060) | the resident engine (`engines::ResidentEngine`, a `march::Engine`), the march's state from the run record (`_NativeAdamsMarch.start_state`) | -| the native session's Runge-Kutta march, `native/src/march/rk_march.cpp` | Runge-Kutta, adaptive and replayed, compiled (ADR-069, [SEP 45](seps/archive/sep-0045-native-rk-march.md)) | the staged trial and native norm | +| the native session's Runge-Kutta march, `native/src/march/rk_march.cpp` | Runge-Kutta, adaptive and replayed, compiled (ADR-069, [SEP 45](https://github.com/LupoLab/solprop/blob/main/docs/dev/seps/archive/sep-0045-native-rk-march.md)) | the staged trial and native norm | | the native session's low-storage replay | low-storage, always on a schedule | one in-place native step a schedule step | The reference's Runge-Kutta march is the reference for the compiled Runge-Kutta march, @@ -308,7 +305,7 @@ reads the state's energy per walk-off bucket at each check, in the same reductio histogram per thread and no atomics, which is why its bucket count has a compiled limit. The input-noise floor is read on the host, once, at the launch. -**Export into a destination** ([SEP 47](seps/archive/sep-0047-run-ownership.md) §5.4) is how a +**Export into a destination** ([SEP 47](https://github.com/LupoLab/solprop/blob/main/docs/dev/seps/archive/sep-0047-run-ownership.md) §5.4) is how a session's field reaches the output. A session's `export(ticket, recipe, out=None)` fills a host destination with the pending observation's field converted by an `ExportRecipe` (`backends/export.py`): the true-power weight's square root on a modal route (a spatial @@ -347,8 +344,10 @@ array crosses it. ## 2. `numpy_ref`: the oracle -Plain NumPy and `scipy.fft`, one function per pass, no fusion, no in-place tricks, no -threading beyond what `scipy.fft` does with `workers=1`. It exists to be read and to be right: +Plain NumPy and `scipy.fft`, one function per pass, no fusion, no threading beyond what +`scipy.fft` does with `workers=1`, and in-place updates only where the algorithm is defined +by them: the low-storage engine's registers and the Adams history's transport +(`AdamsKernels.transport`), which multiplies the stored rows in place. It exists to be read and to be right: every step of the anatomy in [architecture.md §8](architecture.md) is a named function with a docstring stating the formula. It is slow (tens of separate array operations per stage) and that is acceptable; it is the reference against which every other backend is validated, and @@ -366,7 +365,7 @@ stages, with `raman_spectrum` beside them), `plasma.py` (`ionisation_rate`, `plasma_scan` and the plasma currents, cycle-averaged on an envelope grid) and `stepping.py` (the step around the stage). Field plasma returns ungated current separately; `held_plasma_spectrum` assembles its two products with the analytic collar -derivative ([SEP 27](seps/archive/sep-0027-held-plasma-current.md)), while the +derivative ([SEP 27](https://github.com/LupoLab/solprop/blob/main/docs/dev/seps/archive/sep-0027-held-plasma-current.md)), while the physical-polarisation helpers retain their independent oracle role. The transform and response passes serve every march, the interaction-picture trial and the Adams, exponential and low-storage engines alike. The backend also owns the once-per-step @@ -467,9 +466,10 @@ It consumes the contract only through `linop.delta_phi`, `linop.unitary_phase`, `responses.prefactor_at` and the scalar tables `responses.density`, `transform.taper_scale`, `transform.aeff`, the plasma group's `preionisation` and the Raman decay rates, so a change of the operator's representation cannot reach it. It refuses, by -name and with `BackendError`: a spectral response other than -the compiled envelope-plasma assembly; scalar-only Raman on a two-component -problem; general z-dependent response data; and a transform and a state that +name and with `BackendError`, only a route variant it does not know and what an Adams march +does not step (`_refuse_unsupported`, `refuse_adams`). The problem's own validation refuses +the rest with `TranslationError` before any backend sees it: scalar-only Raman on a +two-component problem (`PropagationProblem._check_raman`), and a transform and a state that would both carry the transverse components. Measured on the verification ladder: P0 exact to 4.8e-16 for a constant operator and @@ -500,7 +500,7 @@ the shock term and Raman on is conserved exactly while the energy falls by 7.2e- **Selection.** `backends/registry.py`: `available()` detects with `importlib.util.find_spec` and never caches; `select(name, problem, request, *, grid, -modes, profiles)` builds one, for the problem and the request it is run with: the +modes, profiles, tdse_binding, options)` builds one, for the problem and the request it is run with: the request's method, error control, itinerary and planes are lowered once, here (the native session lowers its statistics as it starts, from profile tables cached per problem), and a run's session serves that request adapted to one run (`RunRequest.for_run`); a @@ -545,9 +545,9 @@ reads the polarisation ellipse, so on a one-component transform whose modes have axis the two rows go to a row of their own, which the envelope scan reads as a node of two components (`numpy_ref.passes.plasma.envelope_populations` on the host's row). The native row agrees with the host's scan to the node scans' parity tolerance (`1e-10`), and is the same bits where -both read a Radau rule's axis node. The three keyword arguments of `select` (`grid`, `modes`, `profiles`) are what the statistics need and the kernel contract does not carry. +both read a Radau rule's axis node. Three keyword arguments of `select` (`grid`, `modes`, `profiles`) are what the statistics need and the kernel contract does not carry; the other two are a TDSE run's binding (`tdse_binding`) and the execution options (`options`). -**Spatial statistics measure the medium's flux** ([SEP 34](seps/archive/sep-0034-medium-flux.md)). +**Spatial statistics measure the medium's flux** ([SEP 34](https://github.com/LupoLab/solprop/blob/main/docs/dev/seps/archive/sep-0034-medium-flux.md)). The shared spatial statistics, `backends.spatial.collect_spatial`, read the plane's coefficients through `problem.route.flux.at(z)` (the spatial route's plane measure) (kernel schema 35): energy and the far-field spectra weight each column and bin by the real admittance `c Re k_z/omega` of that root, @@ -558,12 +558,14 @@ refuse a fluence negative beyond its rounding budget. The helper as one; its end-of-plane log is retired, and the boundary monitor's transverse edge (SEP 40) judges the boundary instead. A backend whose own statistics do not apply this measure refuses the problem. -**The transverse edge is read where the state lives** ([SEP 40](seps/archive/sep-0040-transverse-absorbing-boundaries.md), [SEP 44](seps/archive/sep-0044-native-edge-read.md)). -Every backend reads the edge: it hands the monitor's `TransverseEdge` an `_EdgeReading` from `NumpyWorkspace.edge_reading` at the edge's reads, at saved planes, and with a -requested collar at every committed step. The reading is numbers and never the field: region sums, each +**The transverse edge is read where the state lives** ([SEP 40](https://github.com/LupoLab/solprop/blob/main/docs/dev/seps/archive/sep-0040-transverse-absorbing-boundaries.md), [SEP 44](https://github.com/LupoLab/solprop/blob/main/docs/dev/seps/archive/sep-0044-native-edge-read.md)). +Every backend reads the edge at the edge's reads, at saved planes, and with a requested +collar at every committed step; the reference's session hands the monitor's `TransverseEdge` +an `_EdgeReading` from `NumpyWorkspace.edge_reading`. The reading is numbers and never the field: region sums, each column's energy and any collar's strip and current. The default forms them with `_HostEdgeReduction` on a host copy, the reference, which `numpy_ref` uses. `native` forms them on its own state against -the edge's `_EdgeTables`, four regions' weights on the nodes, so it holds no face, mask or judgement, and a +the edge's tables (`_EdgeTables`, four regions' weights on the nodes, packed once when the run +starts), and its session judges them natively (below), and a field-free run crosses no state (`tests/backends/test_native_edge_reading.py`). A requested collar's lines are described once, as `_edge_lines`, for both reductions (`tests/backends/test_native_edge_collar.py`): native takes each strip's padded transform in batches of planes under `_STRIP_BATCH_BYTES`, on buffers listed in the `transverse_edge` ledger row, and the @@ -577,12 +579,13 @@ reads stay at most a spacing apart without shortening the steps between them (la each read cost 10-35 % more steps on the suite's line and planar cases). `numpy_ref` keeps its state on the host and steps from there, under the session's ceiling. The native Adams march takes the next read and the spacing as the call's `read_at` and `read_spacing` bounds: -an adaptive step is capped at the spacing, and the call returns at the committed -position from which the next step would pass the read, so the host reads the state -there. With a collar the host step is one, so the march returns at every committed step. +an adaptive step is capped at the spacing, and the call returns to the native session at +the committed position from which the next step would pass the read, so the session reads +the state there. With a collar the edge is read at every committed step, so the march +returns to the session at each one. A saved plane reads the edge unless the step that reached it already did (`TransverseEdge.wants_read`), as a second read at one position records nothing. -**Under the native execution session the judgement is native too** ([SEP 47](seps/archive/sep-0047-run-ownership.md) §6.4). +**Under the native execution session the judgement is native too** ([SEP 47](https://github.com/LupoLab/solprop/blob/main/docs/dev/seps/archive/sep-0047-run-ownership.md) §6.4). `NativeSession` hands no reading to a Python edge: `transverse::Edge` (`native/include/solprop_native/session/transverse.hpp`, a strict translation unit) owns the edge's every decision and record -- the launch's judgements, the spacing and its ceiling, each read's ledgers and verdict, a collar's current and return, @@ -678,11 +681,11 @@ rule (§3.12), the statistics column's fraction and peak rate, two runs of `nati thread against many, a same-backend resume — is a rounding bound fixed from its operation counts (the running sums by the prefix bound of their signed increments; [kernel-contract.md](kernel-contract.md)), and a resume of an adaptive run is held to its -accuracy envelope ([SEP 25](seps/archive/sep-0025-rounding-level-reproducibility.md)). With +accuracy envelope ([SEP 25](https://github.com/LupoLab/solprop/blob/main/docs/dev/seps/archive/sep-0025-rounding-level-reproducibility.md)). With the kernels contracting (§3.2), native's products round once where the reference's may round twice, and that is within the bound. -**Held field current** ([SEP 27](seps/archive/sep-0027-held-plasma-current.md)). The +**Held field current** ([SEP 27](https://github.com/LupoLab/solprop/blob/main/docs/dev/seps/archive/sep-0027-held-plasma-current.md)). The trapezoid column writes non-plasma polarisation and total physical current separately. The band column writes current after its second running integral. The engine owns the current, its two collared products, the projected rows, the spectra and all forward plans at @@ -714,7 +717,7 @@ inside a step loop: re-synthesising every node into a buffer of megabytes evicts own working set. Measured on the retired `numba_cpu` backend, on the reduced M2 case at `period = 1`, the electron density alone cost 14 % of a step through that path and 1.3 % through the stash, and the whole default subset went from 15.8 % to 2.5 %. The predicate for -reading it (`stash_plasma` in the adapter) is `first_same_as_last` — the seventh stage's +reading it (`_stash_plasma` in `_lowering.py`) is `first_same_as_last` — the seventh stage's *input* is the accept pass's own result, so the last column evaluation of an accepted step scanned exactly the state the run adopted — which is also false for the `split_step` absorber, where the finish changes the state after the stages have run, and beside a @@ -796,7 +799,7 @@ mask and the in-stage absorber preserve it, and the measured saving are already apply. - Reductions (error norm, statistics) are two-stage: per-column partials, then a sum over the columns. Their order is free - ([SEP 25](seps/archive/sep-0025-rounding-level-reproducibility.md)), and repeats and thread + ([SEP 25](https://github.com/LupoLab/solprop/blob/main/docs/dev/seps/archive/sep-0025-rounding-level-reproducibility.md)), and repeats and thread counts are tested against the reduction's rounding bound, not for identical bits. - No allocation, planning, logging, Python call or unplanned fence in a trial step; every persistent buffer is allocated at construction and named by `memory_ledger()`. No @@ -833,7 +836,8 @@ measured planning may write over both its buffers, so plans must be built before is filled. Threads are a property of the plan, chosen at construction: a plan of fewer real-side samples -than `default_threaded_fft_min_samples` runs on one thread (§4), and the others take their +than the execution record's `fft_threshold` (`BuildInfo.threaded_fft_min_samples`) runs on +one thread (§4), and the others take their width from the size rules of §3.4, within the process's thread budget (ADR-052: the affinity mask, the cgroup CPU quota on the process's own path rounded down, and `SOLPROP_THREADS`; never `os.cpu_count()`). The plans runs measure are kept by default, per machine and @@ -846,9 +850,11 @@ build (ADR-076, §4). | compact problem | one column on one node, fewer than 65 536 fine samples | kernels on a team of at most eight threads, transforms on that team, products on one BLAS thread | independent scans: Local, or spawned processes through Pool | | sized problem | the rest | each operation's width chosen from its own element count at construction: stage, response, dense product, FFT, Raman, copy, flow, modal and Adams | one process per problem | -The widths are constants of `include/solprop_native/runtime/cpu_execution.hpp` (`operation_threads`, with -their calibration in -[benchmarks.md](benchmarks.md#kokkos-cpu-operation-size-threading)), and `SOLPROP_NATIVE_*_THREADS` +The widths come from the built-in table (`builtin()` in +`native/src/solprop_native/_execution.py`, with the measurements behind it in +[benchmarks.md](benchmarks.md#kokkos-cpu-operation-size-threading)) or a machine +calibration (§3.4a); native code holds no values for them +(`include/solprop_native/runtime/cpu_execution.hpp`), and `SOLPROP_NATIVE_*_THREADS` overrides a pool ([Performance tuning](../guide/performance/tuning.md)). The stage boundary and the threaded-FFT boundary differ on macOS (§4). Three things motivate the policy. They say the regime cannot be inherited from the environment, and that a few settings matter more @@ -996,7 +1002,7 @@ absorber's transform pair for a state that is thrown away. Under Runge–Kutta the reference's march is the reference, and on `native` one call executes all seven stages of a trial (§4), its rows formed natively from the uploaded stage tables and its -norm reduced natively ([SEP 45](seps/archive/sep-0045-native-rk-march.md) phase 2). An earlier +norm reduced natively ([SEP 45](https://github.com/LupoLab/solprop/blob/main/docs/dev/seps/archive/sep-0045-native-rk-march.md) phase 2). An earlier measurement on the retired `numba_cpu` backend found the loop's Python cheap (about 50 calls a step cost 1.69 % of a step at 1024 bins on the GNLSE soliton), but the host's whole per-step work, the stage scalars and the packing with the loop, came to about 200 µs a step on an Intel @@ -1019,8 +1025,8 @@ The native backend's host kernels form these exponentials, the exponential Adams method's flows, phi-function exponentials and compensation factors, and the plasma's rates and fractions in passes over blocks of elements through one vector-maths layer (`native/include/solprop_native/runtime/vmath.hpp`): SLEEF's 1.0 ulp vector functions on x86-64 -builds, the system libm, with each element's own calls, on Arm and on devices -([ADR-059](decisions.md)). +and macOS arm64 builds, the system libm, with each element's own calls, on Linux aarch64 and +on devices (`native/cmake/VectorMath.cmake`; [ADR-059, ADR-072](decisions.md)). **In a fused backend the answer is a property of the fusion.** Both signs are consumed by the stage that formed them — the forward in pass 1 and the inverse in pass 7 — so @@ -1059,17 +1065,19 @@ the low-storage march holds flows (§8). `native` executes the general modal route — `transform.modal_tables`, `linear.modal_metric` and `responses.regional_responses` — in the combinations solprop's problem validation admits (`solprop.translate.admission.check_general_route`), which it runs where it is -built, so a refusal there is a refusal on both backends, raised once. It adds one limit of its own: a delayed response must be the -six channels of the silica tensor Raman model on three components (§4, -`_refuse_native_route`). `linear.coupled_flow` is §3.9. The route is a **second execution +built, so a refusal there is a refusal on both backends, raised once. The delayed response's +limit is part of the same translation for both backends: it must be the two delayed +channels of the silica tensor Raman model on three Cartesian components +(`solprop.translate.responses.DELAYED_TERMS`, `MAX_N_COMPONENTS`), refused otherwise with a +`TranslationError`. `linear.coupled_flow` is §3.9. The route is a **second execution path** (`src/response/general_modal.cpp`, `GeneralModalSource`) beside the fused pipeline and not an extension of it, for the reason §3.1a's three families make plain: those are one real transverse matrix in the time domain, and this route's synthesis is a complex frequency-dependent map of three Cartesian components. -- **Maps.** Derived by the reference's own functions in - `solprop.backends.numpy_ref.general_modal`, so the two backends cannot read a record - differently: the per-node `chi3 T`, the form from `model_id`, and the delayed response's +- **Maps.** Derived by the shared functions of `solprop.translate.general` + (`node_kerr_tensor`, `node_kerr_form`, `node_delayed_maps`), which the reference uses + too, so the two backends cannot read a record differently: the per-node `chi3 T`, the form from `model_id`, and the delayed response's owners, tensors and weighted kernel spectra. - **Plans.** Per node chunk, a complex inverse of the doubled one-sided spectrum (the analytic signal) and a real forward of the polarisation; on the host the real form reads its field @@ -1078,7 +1086,7 @@ frequency-dependent map of three Cartesian components. histories. A partial last chunk has its own plans on views of the same buffers. Built once; nothing is planned or allocated inside a stage. - **Kernels.** Team kernels with every sum in a fixed order, held to their rounding bounds - ([SEP 25](seps/archive/sep-0025-rounding-level-reproducibility.md)): the synthesis over + ([SEP 25](https://github.com/LupoLab/solprop/blob/main/docs/dev/seps/archive/sep-0025-rounding-level-reproducibility.md)): the synthesis over channels, the real cubic's symmetric contraction (its coefficients formed once per node, then ten monomials a sample), the analytic form's dense contraction, the delayed contraction, and the projection over nodes and components into the source. Each is diagonal in the bin or @@ -1221,7 +1229,7 @@ modified noise draw, and every statistic. ### 3.11 The dispersive electronic response -`native` executes [SEP 6](seps/archive/sep-0006-dispersive-nonlinearity.md)'s +`native` executes [SEP 6](https://github.com/LupoLab/solprop/blob/main/docs/dev/seps/archive/sep-0006-dispersive-nonlinearity.md)'s `responses.dispersive_kerr` on every route `numpy_ref` runs it -- the fused node path (mode-averaged, multimode and radial), Cartesian free space and the line, the hybrid planar route and the general modal route -- on field and envelope grids, with both @@ -1272,7 +1280,7 @@ Everywhere the multipliers move off the nodes, to wherever the route already hol - **Mixtures.** The symmetric evaluator forms one product per mixture -- per region on the general route -- under the filter of the mixture's own Kerr diagonal, `g_mix = [Σ_s f_s g_s⁴ / Σ_s f_s]^(1/4)` with `f_s = ε₀ γ₀,s ρ_s` - ([SEP 6](seps/archive/sep-0006-dispersive-nonlinearity.md)). `DispersiveWeights` rebuilds a + ([SEP 6](https://github.com/LupoLab/solprop/blob/main/docs/dev/seps/archive/sep-0006-dispersive-nonlinearity.md)). `DispersiveWeights` rebuilds a mixture's filter (`O(n_omega × n_species)` and two square roots per bin) only when the densities differ from the last rebuild's: a fill of constant composition builds it once, a composition varying along z at every stage. Its arithmetic is `mixture_filter`'s, so the two backends' filters @@ -1309,7 +1317,7 @@ Everywhere the multipliers move off the nodes, to wherever the route already hol ### 3.12 The plasma column's band rule -[SEP 18](seps/archive/sep-0018-band-exact-plasma-integrals.md)'s band rule filters each of the +[SEP 18](https://github.com/LupoLab/solprop/blob/main/docs/dev/seps/archive/sep-0018-band-exact-plasma-integrals.md)'s band rule filters each of the column's population and free-current integrands with the problem's $2K+1$ taps before its running sum, reading $K$ samples ahead, so the fused one-sample traversal cannot carry it. @@ -1341,7 +1349,7 @@ sum, reading $K$ samples ahead, so the fused one-sample traversal cannot carry i **Verification.** - **Against the reference.** The column agrees with `plasma_scan` and `plasma_current` within an absolute budget carried through the whole chain - ([SEP 25](seps/archive/sep-0025-rounding-level-reproducibility.md)): the stencil's $\gamma_{2K+2}$ + ([SEP 25](https://github.com/LupoLab/solprop/blob/main/docs/dev/seps/archive/sep-0025-rounding-level-reproducibility.md)): the stencil's $\gamma_{2K+2}$ bound, the prefix bound of each scan's signed increments, and the fraction, guard, currents and density between them (`native/tests/plasma_bounds.py`). The stress set (`native/tests/test_band_stress.py`) is a preionised field whose rate is identically zero, a field @@ -1370,7 +1378,7 @@ build defaults to its own: direct reads on CUDA, staging on HIP ### 3.13 The far-field statistics' banded pass -[SEP 23](seps/archive/sep-0023-far-field-aperture-spectra.md)'s six far-field statistics and +[SEP 23](https://github.com/LupoLab/solprop/blob/main/docs/dev/seps/archive/sep-0023-far-field-aperture-spectra.md)'s six far-field statistics and `on_axis_spectrum` are one native pass over the stored state on the Cartesian and line kinds (`GeneralState::aperture_statistics`, `native/include/solprop_native/response/far_field.hpp`, `FarFieldPass`), in place of the shared host pass `spatial.aperture_statistics` that `numpy_ref` @@ -1417,13 +1425,11 @@ image's distance from the origin (and the radius too when they share a centre). and the shared radius are gated on the layout's aperture slot: apertures declared in the spec but no aperture statistic asked for (a periodic `beam_spectrum` sample) evaluate no weight. -The native `Problem` carries the stored axes `spatial_k_x` and `spatial_k_y` and the slot count of -the problem's own request (`spatial_far_field_slots`), which sizes the band partials at construction +The native `Problem` carries the stored axes `spatial.k_x` and `spatial.k_y` and the slot count of +the problem's own request (`spatial.far_field_slots`), which sizes the band partials at construction (`far_field_partials` in the ledger). The call carries the tables, `(n_apertures, 11 + n_omega)` rows of the host-formed constants and scale row and `(n_regions, 4)` boxes, which the native -`far_field_tables` row holds with the axes and the packed output. A build declares the names it -forms in `NativeBackend.far_field_statistics`; solprop's registry admits them by it and refuses them -by name on an older build, before it is built (`registry.statistics_refusal`). The device path +`far_field_tables` row holds with the axes and the packed output. The device path compiles but is not qualified: its partials live in global memory, not in registers. Measured cost: about 2.3–2.6 % of one Runge–Kutta step at the sizes of [benchmarks.md](benchmarks.md#far-field-statistics-pass), paid at save planes and periodic rows only. @@ -1432,15 +1438,15 @@ about 2.3–2.6 % of one Runge–Kutta step at the sizes of statistic by the medium's axial flux, as `collect_spatial` defines it, and reads the admittance `c k_z / omega` from the root the operator uses, per element, with no column-by-frequency table. A Cartesian, line or planar run's plane measure is its own separable operator (the adapter refuses -another); a radial run packs the entrance's material and transverse squares (`flux_k_squared`, -`flux_kperp_sq` and their residuals) and, for a medium that varies along z, uploads the material +another); a radial run packs the entrance's material and transverse squares (the `Problem.flux` +record's `k_squared` and `kperp_sq`, and their residuals `k_squared_low` and `kperp_sq_low`) and, for a medium that varies along z, uploads the material square as a `"flux"` z table of `n_omega` values, which `spatial_statistics(flags, factor, z)` evaluates at the statistic's plane. Energy weighs each column and bin by `Re eta`; the on-axis spectrum pairs the coherent axis amplitude with its closure; the on-axis intensity, peak intensity and fluence synthesise the closure `G` beside `E` -- on the radial kind through the dense synthesis of a closure time volume (`statistics_weighted_time`), on the separable kinds through a second -transverse volume (`flux_closure_transverse`, one state's bytes, the estimate's -`flux_closure_memory`) and, for the intensities, the chunk's closure time rows. The largest magnitude +transverse volume (`flux_closure_transverse`, one state's bytes, a row of +`memory_ledger()`) and, for the intensities, the chunk's closure time rows. The largest magnitude over the nodes fixes the width refusal's normwise budget (`backends.spatial.fluence_budget`). The closure buffers are allocated at construction when the problem's own request has a local statistic and, outside any step, when a later request first needs one. @@ -1464,7 +1470,7 @@ per ring cross, and solprop keeps the rule: `solprop.spatial._fluence_rings` fix and its angles, which depend on the axes alone, are formed once at lowering (`solprop.spatial._ring_angles`). -**The widths are finished natively** ([SEP 47](seps/archive/sep-0047-run-ownership.md) §6.4). +**The widths are finished natively** ([SEP 47](https://github.com/LupoLab/solprop/blob/main/docs/dev/seps/archive/sep-0047-run-ownership.md) §6.4). `beam_radius` and `fwhm_r` are statistics of the native plan (`Stat::beam_radius`, `Stat::fwhm_r`), so the native session takes them with no Python finishing, at planes (neither is periodic-capable). The plan runs the same fluence passes the host finishing @@ -1495,8 +1501,8 @@ The backend depends on solprop's seam: the `PropagationProblem` and `RunRequest` the stage bundles and the march policy, all frozen by `tests/backends/test_driver.py`. A change to any of them rewrites those tables in the same commit and adds a release-note fragment. The two packages are released together, and solprop's metadata pins this one to its own version. -`check_build` looks the descriptor and bundle fields and contract tuples the adapter relies on -up by name. Since SEP 47 phase 5 the native backend is a resource holder: it lowers the problem, +`check_build` checks the build's facts and, in an editable checkout, its source digest; it +looks no seam member up, and the binding reads each record through its field table. Since SEP 47 phase 5 the native backend is a resource holder: it lowers the problem, loads a start (`solprop_native._load`), keeps its Adams march's record and times its trials (`timing_probe`, `solprop_native._probe`) itself, inherits no step driver, and serves every run through its session. @@ -1522,7 +1528,7 @@ ctest reaches them. Test-only entry points are in the private `_core._testing` s which promises nothing; `_testing.engines(workspace)` exposes the workspace's engines, which the tests wrap in solprop's engine protocols (`tests/engine_pairs.py`). The whole stub, `_core.pyi` with `_core_testing.pyi`, is generated by nanobind's `stubgen` -(`native/scripts/problem_stub.py`, checked by the native gate). +(`native/scripts/stubs.py`, checked by the native gate). In an editable checkout it also recomputes the digest of `native/CMakeLists.txt`, its modules in `native/cmake` @@ -1537,8 +1543,8 @@ coupled flow, the moving guide and the others) are executed by both backends in combinations, and the problem's own validation refuses every other by name ({py:func}`~solprop.translate.admission.check_general_route`), so neither backend repeats the list. A change that -touches `native/` is complete only when the gates (`poe check-all`) and solprop's lanes -are green with the current build installed. +touches `native/` is complete only when the gates (`poe check`, `poe check-native`) and +solprop's lanes are green with the current build installed. **The fused route.** The backend runs the three field families, the Kerr variants, both noise and absorber schemes, adaptive/replay/resume, FSAL and hard masking, multimode scalar @@ -1575,7 +1581,7 @@ alone, in `wisdom.json` in the calibration store's directory of the machine and in memory for its later workspaces either way. A run's own planning (the policy's, or the profile's) is offered the stored plans (`FftPlanning::stored`) and asked to keep what it measures (`keep`). In `begin_seed` a key the profile holds is planned from the -profile's wisdom, as before; any other seeded above estimate plans *alone*: the +profile's wisdom; any other seeded above estimate plans *alone*: the workspace's accumulated wisdom is exported and forgotten, only that key's known wisdom imported (stored, or measured earlier in this workspace, so a key seeded twice is measured once; a key to measure starts from what the workspace measured so far, whose @@ -1602,7 +1608,8 @@ Contiguous Raman transforms use the same planning policy, including long doubled rows and partial chunks. On macOS, NEON FFTW handles serial and long Raman rows; short parallel power-of-two rows (at most 16384 samples) retain Accelerate. Selection uses the linked FFTW's codelet family and the plan's dimensions and thread width at -construction. A local FFTW without NEON retains the previous short-serial FFTW rule. +construction. With a local FFTW without NEON, FFTW takes only serial rows of at most 16384 +samples and Accelerate the other power-of-two rows (`transforms/raman_fft.hpp`). The full-chunk Raman provider and task counts, planning seconds, and plan heap growth remain in execution metadata. General-modal tail views add no field buffers. These choices preserve explicit transform scaling and the device paths. See the multimode CPU measurements @@ -1642,8 +1649,8 @@ field, independently of the field-plasma accepted-state stash. The the ordering and memory ownership. KokkosKernels 5.2.0 supplies ordinary GEMM—not Batched GEMM—for the skinny-by-wide node -transforms. The backend keeps custom, TPL-free KokkosBlas, vendor-TPL and measured hybrid -build variants. Hybrid builds use Accelerate for eligible real transforms on macOS; +transforms. Every build uses the hybrid GEMM provider (`build_info().gemm_provider` is +`"HYBRID"`). Hybrid builds use Accelerate for eligible real transforms on macOS; OpenBLAS builds additionally use persistent preconverted complex matrices for eligible envelope transforms. Vendor and Kokkos/FFTW pools are recorded separately and are never changed inside the extension. @@ -1738,7 +1745,7 @@ Adams trial's rate weights) live in one packed buffer of two slots and cross in trial from a ring of eight pinned host buffers (`Kokkos::SharedHostPinnedSpace`), the ring's reuse waiting for the space to drain; an Adams trial's step scalars fill slot 0 and its sample's slot 1, and the stage views turn to slot 1 for the source -([SEP 39](seps/archive/sep-0039-native-adams-march.md) §6.7). A radial analytic field's node +([SEP 39](https://github.com/LupoLab/solprop/blob/main/docs/dev/seps/archive/sep-0039-native-adams-march.md) §6.7). A radial analytic field's node chunks take the interleaved real GEMM on a device as on the host, and a square radial analytic map synthesises its retained spectrum there too (the gather and the pad a thread per element, the chunk's padded rows zeroed first): the product covers `n_omega` complex @@ -1758,9 +1765,10 @@ that order for the stage too. The state crosses the seam once at a load and once at an observation, straight between the memory space and the NumPy buffer. -The backend refuses scalar-only declarations on vector Raman problems, spectral responses other than -the compiled envelope-plasma assembly, and, on a device build, z-tabulated operators or -prefactors, before field-sized allocation (the CPU build runs them, §1). Supported mixture density, pre-ionisation and Raman decay paths +Scalar-only declarations on vector Raman problems are refused by the problem's own +validation (`TranslationError`) before any backend sees them. The backend refuses, on a +device build, z-tabulated operators or prefactors and the TDSE response, before field-sized +allocation (the CPU build runs them, §1). Supported mixture density, pre-ionisation and Raman decay paths cross as stage scalars; z dependence alone is not a refusal. **The general modal route** is a second execution path beside the node pipeline @@ -1816,8 +1824,8 @@ stage's nonzero `flow_weights` over the held terms, minus the step's frozen bloc the drive back by the inverse action and accumulates; the accepted update takes `U(h)` of the state, the solution and the error sum, the old norm on the unmixed state. A zero stage fraction is flagged and not applied; FSAL is off on a flow. The `flow_*` rows join -`memory_ledger()`, zero on every other route. Admission is solprop's shared list under the -name `native` plus one native limit (the delayed response's three components). +`memory_ledger()`, zero on every other route. Admission is solprop's shared translation +check, the delayed response's limit included; native adds none of its own. **The hybrid planar kind** runs on the same engine: columns `(p, k_y)` go to `(p, y)` rows by a one-axis y FFT, a node chunk holds whole y rows, and the slab rule synthesises and @@ -1827,7 +1835,7 @@ subtracts its channel's `kappa_sq` last. Ten fixed steps agree with `numpy_ref` those bounds. **The dispersive electronic response** (`src/response/dispersive.cpp`, `DispersiveResponse`; -[SEP 6](seps/archive/sep-0006-dispersive-nonlinearity.md)) runs on every route +[SEP 6](https://github.com/LupoLab/solprop/blob/main/docs/dev/seps/archive/sep-0006-dispersive-nonlinearity.md)) runs on every route `numpy_ref` runs it, with the structure of §3.11 route by route: the fused node path (one or two components), `SeparableDispersive` on the Cartesian free-space, line and planar routes, and `GeneralDispersive`, held by `GeneralModalSource`, on the general modal @@ -1883,8 +1891,10 @@ at most: the thread count (a two-column 256-point inverse took radix 4 with 64-point leaves at three and four threads and radix 8 with 32-point leaves at others), which moves ten realistic steps by at most 8 u: within the transform's rounding bound, so it constrains - nothing. This threshold and the stage threshold switch only on `__APPLE__` - (`include/solprop_native/runtime/cpu_execution.hpp`): Windows and linux-aarch64 builds take the values + nothing. This threshold and the stage threshold switch only on the operating system + (`builtin()` in `native/src/solprop_native/_execution.py`, keyed on `platform.system()` + being `"Darwin"`, where a spinning team of at most `SPIN_MAX_TEAM` threads divides them by + `SPIN_DIVISOR`, ADR-073): Windows and linux-aarch64 builds take the values measured on x86-64 Linux (Cascade Lake and Zen 3), which have not been measured on those platforms ([#328](https://github.com/LupoLab/solprop/issues/328)). - **One stage phase.** `sum_t dPhi_t Phi_t` is needed three times per stage (the @@ -1932,17 +1942,17 @@ machine-specific code) is the gate's tidy and sanitizer build. `build_info()` re and a CPU target may contract multiply-adds, so the builds' answers agree to rounding, not bitwise, and every build is held to the same parity bounds against `numpy_ref` and the same rounding bounds between repeats and thread counts. No build carries numerical pins -([SEP 25](seps/archive/sep-0025-rounding-level-reproducibility.md)): `REFERENCE` keeps its name for +([SEP 25](https://github.com/LupoLab/solprop/blob/main/docs/dev/seps/archive/sep-0025-rounding-level-reproducibility.md)): `REFERENCE` keeps its name for its tidy and sanitizer role only. A rename of a seam member the adapter reads is caught by solprop's frozen tables (`tests/backends/test_driver.py`), which move with the seam. ## 4a. `mlx`: retired -[SEP 33](seps/archive/sep-0033-single-precision-mlx.md)'s experimental single-precision +[SEP 33](https://github.com/LupoLab/solprop/blob/main/docs/dev/seps/archive/sep-0033-single-precision-mlx.md)'s experimental single-precision backend for Apple GPUs was retired, unused, by -[SEP 47](seps/archive/sep-0047-run-ownership.md) §6.6, before the driver hierarchy it inherited +[SEP 47](https://github.com/LupoLab/solprop/blob/main/docs/dev/seps/archive/sep-0047-run-ownership.md) §6.6, before the driver hierarchy it inherited was restructured. `backend="mlx"` raises `BackendError`, as any name that is neither -backend does. Single precision went with it (ADR-077): every backend computes in binary64. SEP 33 and the benchmark ledger keep what it measured. +backend does. Single precision went with it (ADR-077): every backend computes in binary64. SEP 33 keeps what it measured. ## 5. JAX: evaluated, not adopted @@ -1977,16 +1987,16 @@ Every backend reports `memory_ledger()`: buffer name → bytes, including transf A test asserts which entries are field-sized, that everything is named even when empty, and that the total is within the documented budget for the standard cases. -**The native Adams march** (ADR-060, [SEP 39](seps/archive/sep-0039-native-adams-march.md)). +**The native Adams march** (ADR-060, [SEP 39](https://github.com/LupoLab/solprop/blob/main/docs/dev/seps/archive/sep-0039-native-adams-march.md)). `native` steps `Multistep()` itself, in either formulation, and replayed schedules: the record `_NativeAdamsMarch` hands the native state solprop's `MarchPolicy` (and a replay's schedule) once, and the session's native march runs attempts on the resident engine -- stage scalars and tables evaluated natively from the run's uploaded expansions, the trial, the decision, the accept, and the boundary monitor's checks -([SEP 45](seps/archive/sep-0045-native-rk-march.md) §4.8) -- to each event, the session +([SEP 45](https://github.com/LupoLab/solprop/blob/main/docs/dev/seps/archive/sep-0045-native-rk-march.md) §4.8) -- to each event, the session holding the march's state natively (SEP 47). The decisions are compiled without contraction in their own translation unit, so that they round as solprop's do; within one build the two marches take the same -steps. The host marches are no longer execution modes ([SEP 47](seps/archive/sep-0047-run-ownership.md) +steps. The host marches are no longer execution modes ([SEP 47](https://github.com/LupoLab/solprop/blob/main/docs/dev/seps/archive/sep-0047-run-ownership.md) §6.3): the environment variables `SOLPROP_ADAMS_MARCH`, `SOLPROP_RK_MARCH` and `SOLPROP_RK_ROWS`, the backend's `adams_march` keyword and, in phase 5, the test interface that replaced them (`_ADAMS_MARCH`, `_RK_MARCH`, `_RK_ROWS`) and the @@ -2020,7 +2030,7 @@ maps on a constant guide on every backend (`native` holds two natively; the othe are the Python-owned record). The user-facing account is [Execution resources](../guide/performance/resources.md#memory). -**The low-storage march** ([SEP 24](seps/archive/sep-0024-low-storage-interaction-picture-runge-kutta.md)) +**The low-storage march** ([SEP 24](https://github.com/LupoLab/solprop/blob/main/docs/dev/seps/archive/sep-0024-low-storage-interaction-picture-runge-kutta.md)) holds no stage, accumulator or propagator-pair row: `numpy_ref`'s ledger (`reference_base_memory`, method-aware) names the state, `register_accumulator` and `register_stage`, the transverse scratch on the free kinds and, tabulating, the flow @@ -2044,7 +2054,8 @@ constant operator's table it has not built since the field was loaded (solprop's never ask for any of them). **The far-field pass** (§3.13) holds `far_field_partials` on the native backend, the band -partials, `8 n_bands n_slots n_omega` bytes; the estimate counts them to the byte in `base`. +partials, `8 n_bands n_slots n_omega` bytes, which its `memory_ledger()` counts and so +`Simulation.estimate` with it. `numpy_ref`'s reference pass allocates per call. **Statistics.** The modal power weight enters the statistics alone: `numpy_ref` evaluates @@ -2063,9 +2074,10 @@ that execution space. | fibre: mode-averaged and multimode, field and envelope grids, Kerr, scalar and tensor Raman, field and envelope plasma, noise, both absorber schemes | yes | yes | qualified | | an operator or prefactor that took the z table (not `device_ready`) | yes | yes: the coefficients resident, evaluated natively into term slots | refused, naming the table's size | | radial and Cartesian free space (including a line, `n_y = 1`) | yes | yes | qualified (CUDA) | -| the hybrid planar kind (`"slab"`) | yes | yes | held field-plasma source qualified on HIP (under CUDA, below); one short planar Kerr case run on an NVIDIA H100 NVL and an AMD MI325X ([SEP 34](seps/archive/sep-0034-medium-flux.md#device-qualification-report--cuda-and-hip), 2026-10-23); other combinations not qualified | -| general modal route (modal tables, metric, regional responses) | yes | yes; a delayed response only as the six silica tensor channels on three components | qualified | +| the hybrid planar kind (`"slab"`) | yes | yes | held field-plasma source qualified on HIP (under CUDA, below); one short planar Kerr case run on an NVIDIA H100 NVL and an AMD MI325X ([SEP 34](https://github.com/LupoLab/solprop/blob/main/docs/dev/seps/archive/sep-0034-medium-flux.md#device-qualification-report--cuda-and-hip), 2026-10-23); other combinations not qualified | +| general modal route (modal tables, metric, regional responses; a delayed response only as the silica tensor model's two channels on three components, refused at translation) | yes | yes | qualified | | coupled flow: constant-Schur and frozen-residual sections | yes | yes | qualified | +| the TDSE response (`ModalRoute.tdse`, SEP 49) | yes | yes | refused by name | | the dispersive electronic response (`responses.dispersive_kerr`) | every route | every route | qualified on one AMD Instinct device (HIP) and one NVIDIA Hopper device (CUDA) | | the low-call Adams integrator (`StepperSettings.integrator`), both formulations | yes | every route, the history resident; beside a coupled flow the exponential formulation alone, on constant-Schur and frozen-residual sections, the history resident at any width and on either route of each bin (the eigenbasis or the augmented exponential), in the native session | beside a coupled flow the history resident at any width and on either route of each bin, in the native session (past 16 channels or off the eigenbasis route: run on an NVIDIA A40, not yet qualified); qualified | | the Adams carrier frame (`Multistep(carrier_frame="scalar")`, SEP 35) | every guided route; free space refused | CPU builds, resident, on every representation of the operator (a z table's chord carried as its own scalar table, #255); device builds refused | refused by name | @@ -2078,7 +2090,7 @@ that execution space. | materials from optmat: gas Raman leaves of many rows on gradients, rate tables, optmat walls, the silica bundles | yes | yes | not qualified | | coupling between runs (`field_plane`, `regrid`, `couple`, `Outcouple`, `transport`, `with_input`; SEP 31) | host-side: any source and receiving backend | host-side | receiving runs not qualified | -**Materials from optmat** ([SEP 3](seps/archive/sep-0003-optmat-materials.md), a run under +**Materials from optmat** ([SEP 3](https://github.com/LupoLab/solprop/blob/main/docs/dev/seps/archive/sep-0003-optmat-materials.md), a run under `MaterialSelection`) reach the backends as the arrays any other run carries: index and wall tables, carrier Kerr coefficients, rate tables, and Raman rows with their decay paths. No backend reads optmat. The native CPU build is qualified on them against @@ -2096,7 +2108,7 @@ views sized from the problem. A fill whose populations follow independent densit paths takes the z table, which `numpy_ref` and native's CPU build run; a shared pressure path does not. Device builds are not qualified on these runs. -**Coupling between runs** ([SEP 31](seps/archive/sep-0031-simulation-coupling.md)) never crosses +**Coupling between runs** ([SEP 31](https://github.com/LupoLab/solprop/blob/main/docs/dev/seps/archive/sep-0031-simulation-coupling.md)) never crosses the seam: a field plane is read from a run's stored output and its record, coupled and transported in NumPy and SciPy on the host, and installed in the receiving run as its initial state through `with_input`. A source and a receiver may therefore run on @@ -2111,23 +2123,21 @@ dependencies. The native backend's device builds are qualified on a data-centre NVIDIA GPU (CUDA 13) and an AMD Instinct GPU (a ROCm 7 prerelease stack): the native tests, the native pytest suite, solprop's device lane and its slow lane on `native` pass, repeats agree within -[SEP 25](seps/archive/sep-0025-rounding-level-reproducibility.md)'s rounding bounds, and the +[SEP 25](https://github.com/LupoLab/solprop/blob/main/docs/dev/seps/archive/sep-0025-rounding-level-reproducibility.md)'s rounding bounds, and the CUDA sanitizers (memcheck, racecheck, initcheck, synccheck) are clean. Thread-count probes are the only tests skipped on a device, which has no thread count to vary. **Field plasma on a device.** The held field-plasma source -([SEP 27](seps/archive/sep-0027-held-plasma-current.md)) is qualified under HIP — native +([SEP 27](https://github.com/LupoLab/solprop/blob/main/docs/dev/seps/archive/sep-0027-held-plasma-current.md)) is qualified under HIP — native execution, the native and solprop GPU lanes, the held-current ladders and bounded timings on modal, radial, Cartesian, line and planar routes under both integration rules, on an AMD -MI325X (2026-10-19). The committed records hold no `native_hip` rows for its Cartesian -ladder and statistics, and a missing row is a `RecordError`, so the record-comparing -tests of `tests/backends/test_free_ladders.py` under field plasma cannot pass on a HIP -build until those rows are written. Under CUDA it +MI325X (2026-10-19); the committed records hold its `native_hip` rows for the Cartesian +ladder and statistics (`tests/data/convergence/spatial_accuracy.json`). Under CUDA it has run without that pass: its Cartesian ladder on an NVIDIA H200 (2026-10-20), whose `native_cuda` rows are in the records -([SEP 28](seps/archive/sep-0028-free-space-evaluation.md#phases-1-and-2-report--the-separable-core-on-both-cpu-backends)); +([SEP 28](https://github.com/LupoLab/solprop/blob/main/docs/dev/seps/archive/sep-0028-free-space-evaluation.md#phases-1-and-2-report--the-separable-core-on-both-cpu-backends)); solprop's device lane on an NVIDIA A40 and an H200 (2026-10-29, 63 passed, -[SEP 39](seps/archive/sep-0039-native-adams-march.md#phase-5--report-cuda-on-nvidia-a40s-hip-to-come)), +[SEP 39](https://github.com/LupoLab/solprop/blob/main/docs/dev/seps/archive/sep-0039-native-adams-march.md#phase-5--report-cuda-on-nvidia-a40s-hip-to-come)), which by reading holds a one-evaluation held-current parity test on every route under both rules; and the `argon_blueshift` capillary benchmark on both, timed only. The held-current ladders on the other routes and the bounded timings have not run under CUDA. @@ -2179,7 +2189,7 @@ Which backend and build to choose for a run is the user guide's - A device answer on the general route agrees with the CPU build's to rounding (the device projection's summation order), and the local and distribution native builds' answers agree with the reference build's to rounding: which is all any comparison requires - ([SEP 25](seps/archive/sep-0025-rounding-level-reproducibility.md)). + ([SEP 25](https://github.com/LupoLab/solprop/blob/main/docs/dev/seps/archive/sep-0025-rounding-level-reproducibility.md)). - No native build runs on Intel macOS, ppc64le, Arm below Neoverse N1 or Windows before 10 version 2004, nor on x86-64 below x86-64-v2, and solprop doesn't support them. With no wheel the installer refuses; where a wheel installs, `auto` and `native` refuse on the diff --git a/docs/dev/benchmarking.md b/docs/dev/benchmarking.md index 4c501be20..64b546cdb 100644 --- a/docs/dev/benchmarking.md +++ b/docs/dev/benchmarking.md @@ -3,8 +3,8 @@ `benchmarks/` times **complete runs** of a small set of representative workloads. Each release adds a few lines per case to a history file kept per hardware set, so that regressions and improvements show from one release to the next. The design is -[SEP 38](seps/archive/sep-0038-performance-tracking.md), which replaced SEP 30's standard -suite. The rules for a performance claim and the indicative results are in +[SEP 38](https://github.com/LupoLab/solprop/blob/main/docs/dev/seps/archive/sep-0038-performance-tracking.md), which replaced SEP 30's standard +suite. The rules for a performance claim and the current results are in [Benchmarks](benchmarks.md); this page is the manual. ```sh @@ -69,7 +69,7 @@ same steps; the summary says so when they do not. **Library defaults.** A case is the interface call a user would write. It passes no tolerance or integrator, so it runs with its interface's defaults -([SEP 37](seps/archive/sep-0037-noise-and-stepper-defaults.md)). A changed default therefore +([SEP 37](https://github.com/LupoLab/solprop/blob/main/docs/dev/seps/archive/sep-0037-noise-and-stepper-defaults.md)). A changed default therefore shows in the history as a new integrator or tolerance on that row. Every noisy launch fixes the same seed, so its repeats and its releases are comparable. The N = 3 soliton is the one noiseless case: a soliton-recurrence study runs without noise, and SEP 37 @@ -101,7 +101,7 @@ spin before sleeping), `active` (idle threads spin), `bound` (threads pinned to neighbouring cores) or `bound-active`. The policy is recorded with each row, and rows compare only within one policy. Binding also confines SciPy's transforms on the host to the main thread's core, so a free-space row's edge reads cost more under a bound policy than -under `passive` ([the edge against 0.1.0](benchmarks.md#the-transverse-edge-against-010)). +under `passive` ([the edge against 0.1.0](benchmarks.md#the-transverse-edge)). ## On a GPU @@ -128,7 +128,7 @@ uv run python -m benchmarks track --append-history ``` A series measures a user's default run, so it runs calibrated -([SEP 46](seps/archive/sep-0046-machine-calibration.md) section 6.13): before the first +([SEP 46](https://github.com/LupoLab/solprop/blob/main/docs/dev/seps/archive/sep-0046-machine-calibration.md) section 6.13): before the first configuration, `track` runs `solprop calibrate --thorough` (`--calibrate` chooses another level, or `none` to keep the profiles there are), and its workers apply the profile (`SOLPROP_CALIBRATION=use`) without measuring inside a timed window. Each history row @@ -147,7 +147,7 @@ bundle to a directory outside the repository. `--append-history` adds one row per configuration to `benchmarks/history/.csv`, which is committed. Each row names its backend, and rows compare only with rows of the same backend, so the `numba_cpu` rows recorded at -0.1.0, before [SEP 43](seps/archive/sep-0043-retire-numba-cpu.md) retired that backend, keep their own series beside the native one. It records only the whole default plan +0.1.0, before [SEP 43](https://github.com/LupoLab/solprop/blob/main/docs/dev/seps/archive/sep-0043-retire-numba-cpu.md) retired that backend, keep their own series beside the native one. It records only the whole default plan with at least three repeats, and only when: - every configuration finished, and its repeats took the same steps and reached the @@ -291,7 +291,7 @@ adoption verdict; the [rules](benchmarks.md#rules) say how a claim is judged. ## SEP 47's matrix and the structural counters -[SEP 47](seps/archive/sep-0047-run-ownership.md) section 7.2 compares builds on a predeclared +[SEP 47](https://github.com/LupoLab/solprop/blob/main/docs/dev/seps/archive/sep-0047-run-ownership.md) section 7.2 compares builds on a predeclared matrix of short windows, each holding the events it measures, with structural counters beside the timings (section 7.3). `--set sep47` selects the windows added for it; each finishes in seconds at its full declared length, so run it without `--length`: @@ -311,9 +311,10 @@ uv run python -m benchmarks ab --set sep47 --threads 1 --counters \ | `cartesian_filament_128_{saved,free}_{memory,hdf5}` | the Cartesian filament's first 1 mm, likewise | the same on a 128² grid | | `taper_flow_4`, `taper_flow_17` | 40 µm of a He capillary tapering from 50 to 48 µm with taper coupling, 4 or 17 modes | a coupled flow on the native Adams march, and one wider than 16 channels, whose host passes hold each bin's channel vectors in a row of their own (a device build's passes hold none) | -Today a snapshot controller needs `step_planes=1` and HDF5 output, so the snapshot cases -save a plane at every step; their variant without step planes becomes possible with SEP -47's independent snapshot scheduling, and the cases will be extended then. Every case uses +The snapshot cases save a plane at every step (`step_planes=1`) to HDF5; the harness +requires HDF5 output of a snapshot case (`benchmarks/registry.py`). A snapshot itself no longer needs +step planes: SEP 47 takes it at the next accepted endpoint and writes a running checkpoint +where no plane is saved; no case measures that yet. Every case uses only public interfaces of the current code; one whose interface changes is updated with it, and the harness copied into each A/B run keeps both arms on one definition. diff --git a/docs/dev/benchmarks.md b/docs/dev/benchmarks.md index f3d9755d7..6f0b5ba69 100644 --- a/docs/dev/benchmarks.md +++ b/docs/dev/benchmarks.md @@ -1,30 +1,25 @@ # Benchmarks -How solprop's performance is measured and judged, and what the measurements so far -indicate. A performance claim names what it measured, the build, the machine and the -result; the rules below say how to take it. The numbers in the indicative sections are -indicative: each was measured once, on one machine, for one change. Re-measure before -relying on any of them. Rows naming `numba_cpu` record a backend that -[SEP 43](seps/archive/sep-0043-retire-numba-cpu.md) retired; they can no longer be re-measured, and -stay as what was measured. +How solprop's performance is measured and judged, what the current release takes on the +recorded hardware, and the standing results a contributor needs before changing a hot +path. [Running the benchmarks](benchmarking.md) is the manual for the harness. Each +result below names its date (the day it was recorded) and the processor or device it ran +on; a few older records name only a class of machine, and say so. Every result was +measured once, on one machine, for one change: re-measure before relying on one. The +per-change campaign records kept until 0.3, each A/B with its full table, are in the +repository's history +([this page at commit `ec3eb8f`](https://github.com/LupoLab/solprop/blob/ec3eb8fc9353a30d9d7d43e82762c6ff8c18c70c/docs/dev/benchmarks.md)); +much of that ledger measured code that no longer exists. ## Where things are - **The benchmarks** are `benchmarks/` - ([SEP 38](seps/archive/sep-0038-performance-tracking.md)), run with `uv run poe bench` - (`python -m benchmarks`). `track` times complete runs of the tracking set (about a - dozen representative workloads, with each interface's default integrator and - tolerances) at one thread and the production width, in about an hour per machine; - `ab` compares two builds while a change is made. [Running the benchmarks](benchmarking.md) - is the manual. -- **The history** is `benchmarks/history/`: one CSV per hardware set, named by its CPU - model and core count, with a few rows per release. `python -m benchmarks history` - summarises it. Full run bundles stay in the ignored `.benchmarks/` directory. -- **[CPU performance: what was tried](cpu-performance.md)** records the compiled CPU - backend's performance experiments: what was adopted, measured and rejected, and what - remains open. Read it before repeating an experiment. -- **[backends.md](backends.md)** describes each backend's execution design and the - performance policies it adopts. + ([SEP 38](https://github.com/LupoLab/solprop/blob/main/docs/dev/seps/archive/sep-0038-performance-tracking.md)): `track` times complete runs of the + tracking set at one thread and the production width, `ab` compares two builds, and + `benchmarks/history/` holds a few rows per release for each hardware set. +- **[CPU performance: what was tried](cpu-performance.md)** records what was adopted, + measured and rejected on the compiled CPU backend. Read it before repeating an + experiment. [backends.md](backends.md) describes each backend's execution design. (benchmark-rules)= ## Rules @@ -49,63 +44,21 @@ stay as what was measured. (benchmark-windows)= ## What is timed -- **Release tracking times complete runs.** The tracking set's cases are complete - guides at production sizes, with the library's defaults, so the history says how long - the usual simulations take now. Construction, translation and backend construction - are timed separately; an untimed warm-up builds plans first +- **Release tracking times complete runs** of guides at production sizes with the + library's defaults; construction is timed separately, after an untimed warm-up ([what is timed](benchmarking.md#what-is-timed)). -- **A change in progress may time less.** `ab --length` runs part of each guide from - the entrance, which is fine for comparing two builds on the same work. Report the - fraction run, and do not extrapolate an entrance window to a complete-run cost: the +- **A change in progress may time less.** `ab --length` runs part of each guide from the + entrance. Report the fraction, and do not extrapolate it to a complete run: the expensive part of a propagation (compression, ionisation, the Raman shift) often comes - late. -- **A later state of a long propagation** is timed by replaying a saved witness into a - short run, not by regenerating the propagation. -- **An event's cost is timed on a window that holds it.** The `sep47` set's windows - each contain the rows, snapshots, planes, members or flows they measure, and - `--counters` reports the native run's returns to Python by cause, its crossings and - its bytes beside the timings, counted under the same keys before and after SEP 47 - phase 5 deleted the transitional bridge, so that two builds can be checked to do the - same work - ([SEP 47's matrix](benchmarking.md#sep-47s-matrix-and-the-structural-counters)). An observation-free window cannot - qualify an observation change. + late. A later state is timed by replaying a saved witness into a short run. +- **An event's cost is timed on a window that holds it.** The `sep47` set's windows hold + the rows, snapshots, planes or flows they measure, and `--counters` reports the native + run's returns to Python, crossings and bytes, so that two builds can be checked to do the + same work ([SEP 47's matrix](benchmarking.md#sep-47s-matrix-and-the-structural-counters)). - **Compare two source trees with alternating pairs** (A/B/A/B…), and report the A/A spread beside the ratio; a difference inside the spread is not a result. (benchmark-reporting)= -## Graded-index and free-space launch setup - -Two setups that are rebuilt for every scan point spent most of their time on repeated work: -the graded-index mode solve evaluated its material once per finite element, and the -free-space launch formed the admittance of every column although a Cartesian grid repeats -each column's transverse squares about eight times. - -Measured on an Intel Xeon Gold 6240, one core of a shared machine (load 5 to 13, another -benchmark running on the same socket), every pool at one thread, two builds in one process, -`4b22e5c9` against the branch's head; build and translation as the benchmark harness forms -them (`benchmarks.builders.build`, then `Simulation.translate`): - -| case | | first build (s) | second build (s) | -|---|---|---:|---:| -| `grin_nonlinear`, build and translation | before | 24.75 | 23.90 | -| | after | 16.82 | 15.92 | -| `kerr_beam_384`, build | before | 12.74 | 12.63 | -| | after | 7.19 | 7.09 | -| `kerr_beam_384`, translation | before | 4.15 | 4.12 | -| | after | 4.10 | 4.04 | - -The translated problems are bitwise unchanged: a SHA-256 over every array of the -`PropagationProblem`, the general route's modal tables and the launch field included, is the -same before and after. Not measured: the production width, where the launch's passes -already run in threads and the saving is smaller. - -What is left on `grin_nonlinear` is the launch's coupling (about 6 s, 4 s of it the -angular admittance check's phase matrix), the knot solves (about 3 s) and the modal -tables (about 4 s); a translation still solves the guide's knots again, since reusing the -guide's solve would hide the run's material record of the loss a transparent index drops. -On `kerr_beam_384` it is the launch's volume passes, the transverse ramp's column power and -the split collar's occupancy, each a pass or two over a 1.8 GB spectrum. - ## Reporting a performance claim **The machine record.** Every measurement carries the CPU (or device) model, core count, @@ -126,3339 +79,471 @@ its verdict, and any case that regressed. Concise evidence belongs in the change description; raw runs stay local. (benchmark-results)= -## Indicative results - -Indicative ratios, not absolute times. Each is a short window (see above) on one -machine; the rows' cases, grids and step lengths differ, so rows share no scale. They say -which backend or method to expect to win, and by roughly how much. - -### Backends and builds - -**Speed-up over `numpy_ref`, one thread**, ten-step windows on an 18-core AVX-512 server -(one socket, one NUMA node) with a local Kokkos build (vendor BLAS, native architecture). -The capillary cases have 3 or 4 channels on a 513-bin grid; the general-route cases are a -two-channel step-index pair and a graded-index guide at 2304 quadrature nodes. - -| case | `numba_cpu` | Kokkos CPU | -|---|---:|---:| -| M1 soliton (GNLSE), reduced | 2.6× | 2.1× | -| GNLSE soliton with Raman | 2.6× | 2.6× | -| M2 (RDW capillary), reduced | 4.9× | 5.9× | -| M2 (RDW capillary), full | 7.1× | 8.6× | -| capillary, no wall | 2.5× | 3.9× | -| capillary, scalar coherent wall | 2.1× | 3.5× | -| capillary, TE/TM coherent wall | 4.2× | 8.8× | -| capillary taper with wall (coupled flow) | 2.4× | 2.8× | -| general route, step-index pair | 2.7× | 5.5× | -| general route, graded index | 2.9× | 4.7× | - -**Threads.** `numpy_ref` does not thread. At four threads Kokkos CPU ran the general route -2 to 6 times faster than `numba_cpu` and the capillary cases 1.5 to 3 times faster. On -larger general-route and coherent-wall workloads (2 to 32 channels, up to 16 384 fine -samples) at 18 threads it was 1.2 to 4 times faster than `numba_cpu` at 18 threads and 6 to -40 times faster than single-threaded `numpy_ref`. Small capillary grids stop scaling beyond -a few threads on every backend. - -**Kokkos build profiles**, same server, seven ten-step capillary and general-route cases. -The vendor BLAS and the instruction set are separate gains. Against the reference build -(no vendor BLAS, generic x86-64), linking OpenBLAS alone made the straight capillaries 2.6 -to 3.8 times faster at one thread (the tapers 1.7) and left the general route unchanged; -compiling for `x86-64-v3` alone made the general route 1.4 to 1.5 times faster and left -the capillaries unchanged. A distribution-style build (`x86-64-v3` and the -`scipy-openblas32` OpenBLAS, ADR-034) ran within about 5 % of the local build -(`-march=native`, the system OpenBLAS) on every case at one and four threads and beat -`numba_cpu` on all seven; `x86-64-v4` added 7 to 14 % on the general route only. The -distribution wheels now target a lower baseline ([CPU performance](cpu-performance.md)). -At one thread, in milliseconds per ten steps: - -| case | reference | distribution-style | local | `numba_cpu` | -|---|---:|---:|---:|---:| -| scalar wall | 61.4 | 21.8 | 22.8 | 35.0 | -| TE/TM wall | 1547 | 390 | 402 | 480 | -| taper wall | 90.3 | 54.6 | 56.6 | 64.7 | -| general pair | 188 | 118 | 120 | 241 | -| general GRIN | 358 | 245 | 244 | 454 | - -On the same server MKL was 1.4 to 1.8 times faster than OpenBLAS on the TE/TM wall, where -the MKL build keeps the custom complex kernel, and level elsewhere. - -**GPU against a whole CPU socket.** On the same seven cases, the Kokkos CUDA build on a -data-centre NVIDIA GPU and the HIP build on an AMD Instinct GPU ran 2.7 to 18 times faster -than the Kokkos OpenMP build on all 18 cores of the server, the graded-index general route -most. These grids are small for a device; the ratios say nothing about large grids. - -### The tracking set on the release wheel, without Numba - -[SEP 43](seps/archive/sep-0043-retire-numba-cpu.md)'s final tree against the history's 0.1.0 rows: -`python -m benchmarks track` with CI's `cp314-abi3` wheel at its x86-64-v3 build, three repeats, -passive threading, an exclusively allocated AMD EPYC 7763 node at 1 and 16 threads. The rows -aren't appended, because the history holds releases. - -| case | threads | now, s | 0.1.0 native, s | ratio | 0.1.0 `numba_cpu` over now | -|---|---:|---:|---:|---:|---:| -| `gnlse_raman_shock` | 1 | 43.57 | 44.16 | 0.987 | 1.24 | -| `gnlse_soliton` | 1 | 0.583 | 0.578 | 1.009 | 1.60 | -| `rdw` | 1 | 11.71 | 11.63 | 1.007 | 1.80 | -| `he_rdw_averaged` | 1 | 1.075 | 1.058 | 1.016 | 2.63 | -| `argon_blueshift` | 1 | 26.50 | 26.44 | 1.002 | 1.86 | -| `argon_blueshift_averaged` | 1 | 3.941 | 3.920 | 1.005 | 2.79 | -| `argon_blueshift_envelope` | 1 | 1.250 | 1.240 | 1.008 | 1.98 | -| `h2_raman_averaged` | 1 | 6.101 | 6.119 | 0.997 | 2.40 | -| `kerr_beam_192` | 1 | 13.34 | 12.07 | 1.105 | 1.45 | -| `gnlse_raman_shock` | 16 | 39.05 | 37.84 | 1.032 | 1.37 | -| `gnlse_soliton` | 16 | 0.587 | 0.582 | 1.007 | 1.62 | -| `rdw` | 16 | 5.112 | 5.148 | 0.993 | 3.18 | -| `he_rdw_averaged` | 16 | 0.770 | 0.785 | 0.980 | 3.70 | -| `argon_blueshift` | 16 | 9.852 | 9.861 | 0.999 | 2.30 | -| `argon_blueshift_averaged` | 16 | 3.271 | 3.261 | 1.003 | 3.37 | -| `argon_blueshift_envelope` | 16 | 1.123 | 1.322 | 0.850 | 2.22 | -| `h2_raman_averaged` | 16 | 5.163 | 5.250 | 0.983 | 2.82 | -| `ctc` | 16 | 108.4 | 111.5 | 0.972 | 2.44 | -| `grin_nonlinear` | 16 | 20.50 | 21.17 | 0.969 | 1.79 | -| `kerr_beam_384` | 16 | 29.10 | 25.26 | 1.152 | 1.24 | - -The geometric mean is 1.002, with the same steps on all twenty, and Numba's rows are 2.08 times -slower. These are runs on different days, so a few per cent is not a result. `radial_filament_256` -is left out, since its guide changed at revision 2. - -- **`kerr_beam`:** the rise isn't the removal. The branch against the `main` it came from gave 0.9956 - and 0.9994 on these rows, with identical fields. Its size matches - [the transverse edge's read cost](#the-transverse-edge-and-a-requested-collar), +10.5 % on the - Cartesian case there, though this comparison didn't bisect it. -- **The same work on the Xeon Gold 6240:** at one thread, the same steps and ratios of 0.99 to 1.04 - in two runs, apart from `kerr_beam_192` at 1.18 to 1.20 and `rdw` at 0.99 to 1.09. At 36 threads - the two runs of one wheel differ from each other by 0.84 to 1.57 per configuration, unpinned across two - sockets, so the 36-thread column gives no verdict. +## Current performance -### Kokkos CPU operation-size threading - -The Kokkos CPU backend chooses each operation's thread width from its dimensions at -construction ([tuning](../guide/performance/tuning.md); the thresholds are under -[reference tables](#kokkos-cpu-sizing-thresholds)). It was calibrated on an 18-core arm64 -laptop and a two-socket, 36-core AVX-512 server, against one thread on the small cases and -against the previous default build on the large windows (best of complete paired rounds): - -| window | arm64 laptop | two-socket server, all 72 logical CPUs | -|---|---|---| -| small cases (eight case/track configurations), geometric mean | 2.00× faster | 2.06× faster | -| averaged helium RDW | same within noise | same within noise | -| resolved blueshift | 2.0–2.6× faster | 1.8–2.4× faster | -| reduced comb-to-continuum (revision 1, 1 ps) | 2.8–3.1× faster | 2.4–3.6× faster | -| RDW ten-step window | 1.81× faster | 2.33× faster | -| reduced comb-to-continuum ten-step window (revision 1, 1 ps) | 3.18× faster | 3.85× faster | -| full comb-to-continuum ten-step window | 7.9 % faster | 2.7 % faster, noisy | -| general modal | 4–11 % faster | same, noisy | -| Cartesian and radial filaments | same within noise | within 5 %, noisy | -| scalar / TE-TM walls | 44 % / 17 % faster | TE-TM same | - -Separate thresholds for copies and arithmetic matter: an 8,192-element temporal copy is -slower threaded, while arithmetic stages of the same size gain from the full pool. A wide -response chunk followed by a full-width FFT needs both at full width, and a serialised -coupled-flow matrix function on the scalar wall took about 20 times its threaded kernel's -time; both were corrected before the comparison above. "Noisy" rows did not meet the -predeclared stability check; taper, short-line and planar controls were not requalified. - -The exponential Adams trial without a coupled flow is two passes around its source -evaluation, a prediction and a correction that also reduces the defects' norms. An -element of them costs about ten stage entries, so they take a class of their own, its -work the field's elements times the history's rows (seven at the default fifth order). -Forced to 1-16 threads of a 16-thread process whose idle threads sleep, over -single-column capillaries of 401 to 10,241 elements, on 16 cores of a dual AMD EPYC -7643: four threads lost at 4,487 (0.8×) and gained 1.1-2.1× (median of two rounds) -from 5,607 to 71,687, while sixteen beat four on argon from 11,207 but lost to them on -helium up to 17,927 and lost to one thread at 8,967 (0.7×), a fork and join of sixteen -sleeping threads costing 100-200 µs. The first round had the node to itself; in the -second, with other jobs on it, the serial times held within 5 % while the threaded ones -slowed by up to 2.3×, the sixteen-thread ones most, yet four threads stayed at least as -fast as one from 5,607 up. On a loaded Apple M5 Max (indicative) four gained 1.0-1.6× -at 4,487-8,967 and sixteen beat four only at 71,687 (4.7× against 2.8×). The class -therefore threads at four from 8,192 and takes the pool from 65,536 on both platforms. - -(stable-kernel-team)= -### A stable kernel team +### The tracking set at 0.2.0 -GNU OpenMP keeps one pool of threads for the main thread's parallel regions. When a region -asks for fewer threads than the last, the surplus threads end; the next wider region -starts them again. A four-thread kernel between full-width ones therefore costs a thread -creation per surplus thread each time: alternating 16- and 4-thread regions took about -490 us a pair, against 40 us for two 16-thread regions and 23 us for 16 and 1 (one socket -of a Xeon Gold 6240, idle threads sleeping; twelve `clone3` calls a pair). FFTW's threaded -loops run on the runtime's whole team and only hand out fewer iterations, so a -four-thread FFT plan costs no resize. At 16 threads, `h2_raman_averaged` (an exponential -Adams trial pass and a response at four threads beside a full-width stage) re-created -twelve threads every source evaluation, and was slower than at one thread. - -A kernel pool that already holds a full-width instance now hands it to medium-width -kernels too; a pool without one keeps four threads (averaged helium, whose other kernels -are serial, took 14 % longer on a Xeon Gold 6240 with its Adams passes at full width). Workspaces ask for their stage -instance first. Interleaved `benchmarks ab` at 16 threads against the parent, 3 rounds, -`--length 0.1`, passive-bound placement, the same steps and fields to rounding (at most -1e-13 relative): - -| case | Xeon Gold 6240 (socket 1) | AMD EPYC 7763 (16 cores) | -|---|---:|---:| -| `h2_raman_averaged` | 0.526 [0.521, 0.531] | 0.483 [0.483, 0.510] | -| `argon_blueshift` | 0.717 [0.700, 1.070] | 0.806 [0.800, 0.850] | -| `ctc` | 1.001 | 0.979 | -| `gnlse_raman_shock`, `gnlse_soliton`, `rdw`, `he_rdw_averaged`, `argon_blueshift_averaged`, `argon_blueshift_envelope`, `radial_filament_256`, `grin_nonlinear`, `kerr_beam_384` | 0.984-1.036 | 0.983-1.106 (node noise) | -| geometric mean (12 cases) | 0.924 | 0.938 | - -The unchanged cases have no medium-width kernel or none beside a full-width one; their -spread is the A/A spread (about 2 % on a Xeon Gold 6240, up to 10 % on the shared EPYC nodes). On -a Xeon Gold 6240 `h2_raman_averaged` now takes 0.79 s at 16 threads against 1.06-1.12 s at one. -Every medium width serial instead lost 2.8 times on averaged helium (EPYC geometric mean -1.08); every medium width full, the FFTs included, gained on resolved cases but lost on the -averaged ones (EPYC 0.94, Xeon 0.90 with averaged helium 1.22). - -The promotion applies everywhere but macOS (`stable_kernel_team` in `cpu_execution.hpp`). On an -18-core Apple M5 Max, whose cores are of two kinds, the 11207-element Adams passes of -`argon_blueshift` at 18 threads instead of four took the window from 3.0 to 3.2 s, and -`h2_raman_averaged` at 18 threads ran 0.86 of `main`'s time without the promotion -against 0.94 with it. The Windows wheel also runs on LLVM's libomp, which keeps a -narrower region's threads, but there the promotion still gained: on eight cores of a -Google Cloud C4D (AMD EPYC 9B45) `h2_raman_averaged` took 0.906 [0.899, 0.914] of its time -with it at eight threads, every other modal case within 1 % (5 rounds, `--length 0.2`). - -(compact-cpu-teams)= -### Compact CPU teams +The newest release rows of `benchmarks/history/`, recorded on 2026-11-07: the native +backend from the release wheel on the CPUs, a build of the tag on the GPUs +([recorded hardware](benchmarking.md#recorded-hardware)), passive threading, the median +of three complete runs in seconds. The production width is 18 threads on the Apple M5 +Max, 36 on the two Intel Xeon Gold 6240, and 16 on the AMD EPYC 7763 node, the Google +Cloud C4D (AMD EPYC 9B45, Linux and Windows) and the Google Cloud C4A (Arm Neoverse V2). -A problem of one column on one node (the GNLSE, the mode-averaged capillary) has few -operations large enough to thread, and between them serial transforms and products. At -16 threads `gnlse_raman_shock` (16384 bins, 6289 source evaluations a `--length 0.1` -window) ran its stage entry on all sixteen threads and its responses on all of them too, -its FFTs on four threads within the runtime's whole team, and gained nothing over one -thread (5.86 against 6.02 s on one socket of a Xeon Gold 6240). Its serial kernels each -ran 1.2-2.5 times slower than in a one-thread process; with every pool forced serial in -the same 16-thread process they ran at their one-thread times, so the idle pool costs -nothing and the wide regions do. A per-thread `perf stat` of the timed window shows both -parts: the main thread ran at about 2.7 GHz instead of 3.5 (waking fifteen cores every -0.9 ms evaluation holds the socket in its many-core turbo bin), and its loads found -16 million lines modified in another core's cache, against 60 thousand. - -Such a problem (`compact_problem`: one column, one node, one transform polarisation, no -general modal route, coupled flow or separable geometry, fewer than 65536 fine samples) -now runs on a compact team: its kernels at most eight threads wide, medium widths -promoted to that team as in [a stable kernel team](#stable-kernel-team), and its FFT and -Raman plans at most eight (see the end of this section for their sizing). FFTW's threaded loop normally opens the runtime's whole team -(sixteen threads for a four-thread plan); beside an eight-thread kernel team that made -GNU OpenMP end and restart threads at every pair, and a whole run took 2.6 times as long. -The native backend therefore installs FFTW's loop callback (FFTW 3.3.9 and later, the -OpenMP FFTW only): outside a scope it runs the jobs on the runtime's team, as FFTW's own -loop does, and inside the scope that every native call of a compact problem opens it runs -them on the problem's team. A build without the callback keeps a compact problem's -transforms serial. An observation now copies the field on the stage's instance rather -than the default one, which would also widen the team. - -Sweeps of the whole native pool on the same 16-thread process (`SOLPROP_NATIVE_THREADS`, -2 rounds, wall s) chose the team: `gnlse_raman_shock` 5.84 at 16, 4.72 at 4, 4.64 at 6, -4.76 at 8, 5.42 at 12; `h2_raman_averaged` 0.71 at 16, 0.61 at 4 and at 8; the 33-node -cases lose at 4 (`argon_blueshift` 1.77 against 1.48 s, `rdw` 0.90 against 0.75 s) and -stay with their own sizing. Interleaved `benchmarks ab` against the parent on a Xeon Gold 6240, -3 rounds, `--length 0.1`, passive-bound placement, the same steps and fields to the -measured-plan floor (at most 6e-14 relative): - -| case | 1 thread | 16 threads | -|---|---:|---:| -| `gnlse_raman_shock` | 0.995 | 0.801 [0.794, 0.831] | -| `h2_raman_averaged` | 0.992 | 0.888 [0.883, 0.891] | -| `he_rdw_averaged` | 1.027 [0.971, 1.055] | 0.979 | -| `gnlse_soliton`, `argon_blueshift_averaged` | 0.983-0.985 | 0.995-1.017 | -| `argon_blueshift_envelope`, `rdw` (not compact) | 0.988-1.009 | 0.999-1.009 | - -`gnlse_raman_shock` now runs 1.25 times faster at 16 threads than at one (4.76 against -5.94 s), where it ran at the same speed. - -On the compact team the transforms kept a 16-thread sizing: the four-thread plans of the -16384-sample transform left half the team idle. A compact problem's threaded transform now -takes its whole team. Three refinements were measured on both machines, interleaved -`benchmarks ab` at 16 threads, 3 rounds, `--length 0.1`, the same steps (AMD EPYC 7763: 16 -cores of a quiet shared node): - -| change | Xeon Gold 6240 | AMD EPYC 7763 | -|---|---:|---:| -| threaded transforms at the team width: `gnlse_raman_shock` | 0.943 | 0.981 | -| the same: `h2_raman_averaged` | 1.003 | 0.995 | -| Raman transforms from the modal FFT's start (not kept): `gnlse_raman_shock` | 0.946 | 1.056 | -| the same: `h2_raman_averaged` | 0.978 | 1.17 [1.08, 1.21] | -| one-node products as the one-mode kernel on the team (not kept): `gnlse_raman_shock` | 0.973 | 1.045 | - -The Raman transforms therefore keep their own start (65536 samples), and the GNLSE's -1 × 1 synthesis and projection stay with the vendor GEMM. Threading every compact kernel -of at least 4096 elements at the team width gained nothing either (`h2_raman_averaged` 3 % -slower on a Xeon Gold 6240), nor did threading compact transforms from 4096 or 8192 samples -(averaged argon 1.6 times slower at 4096). - -The final rule against the parent of the compact-team commit, 3 rounds, `--length 0.1`, -the same steps (fields within 9e-14), 16 threads; one thread moved by 0.98-1.02: - -| case | Xeon Gold 6240 | AMD EPYC 7763 (16 cores of a quiet shared node) | -|---|---:|---:| -| `gnlse_raman_shock` | 0.774 [0.763, 0.800] | 0.965 [0.960, 0.970] | -| `h2_raman_averaged` | 0.895 [0.872, 0.905] | 0.965 [0.957, 0.980] | -| `gnlse_soliton`, `he_rdw_averaged`, `argon_blueshift_averaged` | 0.98-1.05 | 0.97-1.04 | - -With the package's own plan mode (threaded rows planned at `FFTW_ESTIMATE`, where the -suite measures every plan) the Intel Xeon Gold 6240 rows were 0.780 and 0.905. On the EPYC the 16 -allocated cores lay in three CCXs; its 16-thread `gnlse_raman_shock` window ran 1.04 -times faster than one thread before and 1.08 times after (Xeon: 1.02 and 1.29). - -**The products of a compact problem run on one OpenBLAS thread.** On 16 cores of a Google -Cloud C4A (Neoverse V2) the compact team made `gnlse_raman_shock` slower at 16 threads -than `main` (1.13) and than itself at eight (29.6 against 19.5 s in a window, with the same -sizing). Its 1 × 1 synthesis and projection reach an OpenMP OpenBLAS, which on aarch64 -sends them to its threaded GEMV at the process width; between the team's eight-thread -regions, GNU OpenMP ended and re-created eight threads at every call: a short window made -100,836 `clone3` calls, against 72 for `main` and 28 at eight threads. Every native call of -a compact problem already opens a team scope (`CpuTeamScope`); for an OpenMP OpenBLAS the -scope now also sets the calling thread's OpenMP default width to one, which OpenBLAS reads -before it threads a call. `openblas_set_num_threads` is not used for this: it frees the -per-thread buffers above the new count and allocates them again when the count returns, -which cost `h2_raman_averaged` 3 % at 16 threads on an Intel Xeon Gold 6240. The library is recognised at -import whatever width the environment gave it (the suite's workers set -`OMP_NUM_THREADS`, which skips `fit_blas_threads`). On the C4A `gnlse_raman_shock` now -takes 17.6 s at 16 threads, against 25.8 s for `main`; on an Intel Xeon Gold 6240 the change is within -1 % of the A/A spread on every case. - -(one-mode-products)= -### One-mode products on the response team +| case, production width | M5 Max | Xeon Gold 6240 | EPYC 7763 | EPYC 9B45 | EPYC 9B45, Windows | Neoverse V2 | +|---|---:|---:|---:|---:|---:|---:| +| `gnlse_raman_shock` | 21.0 | 41.8 | 38.6 | 23.5 | 24.0 | 39.3 | +| `gnlse_soliton` | 0.291 | 0.627 | 0.574 | 0.270 | 0.328 | 0.717 | +| `rdw` | 3.19 | 7.53 | 4.78 | 3.26 | 3.73 | 4.31 | +| `he_rdw_averaged` | 0.423 | 1.16 | 0.731 | 0.407 | 0.581 | 0.894 | +| `argon_blueshift` | 6.21 | 14.7 | 9.75 | 7.07 | 7.20 | 9.24 | +| `argon_blueshift_averaged` | 1.94 | 3.60 | 3.38 | 1.86 | 2.30 | 3.90 | +| `argon_blueshift_envelope` | 0.340 | 1.65 | 1.16 | 0.351 | 0.554 | 1.76 | +| `h2_raman_averaged` | 3.00 | 5.74 | 5.18 | 2.85 | 3.22 | 6.19 | +| `ctc` | 65.5 | 176 | 112 | 65.6 | 80.2 | 104 | +| `radial_filament_256` | 0.957 | 1.61 | 1.76 | 0.846 | 1.09 | 1.17 | +| `grin_nonlinear` | 11.8 | 23.5 | 21.5 | 11.9 | 12.2 | 14.8 | +| `kerr_beam_384` | 7.28 | 11.0 | 23.5 | 7.86 | 9.17 | 7.93 | + +The same rows' device runs, a whole case each, seconds: + +| case | NVIDIA A40 | NVIDIA H200 | AMD Instinct MI325X | +|---|---:|---:|---:| +| `gnlse_raman_shock` | 18.1 | 9.77 | 5.00 | +| `rdw` | 1.18 | 0.537 | 0.476 | +| `argon_blueshift` | 4.85 | 2.38 | 2.23 | +| `h2_raman_averaged` | 6.13 | 2.11 | 1.83 | +| `ctc` | 34.1 | 9.41 | 7.88 | +| `radial_filament_256` | 0.552 | 0.162 | 0.152 | +| `grin_nonlinear` | 15.1 | 4.80 | 3.34 | +| `kerr_beam_384` | 3.30 | 0.421 | 0.461 | + +Against the 0.1.0 rows of 2026-11-01 (geometric means of the per-case ratios), 0.2.0 took +1.05 to 1.11 of the time at one thread and 0.93 to 1.06 at the production width on the +CPUs, 0.72 on the H200 and 0.80 on the MI325X. The A40's 0.2.0 rows start a new series +(its job spanned fewer memory domains), so they do not compare with its 0.1.0 rows. + +### Since 0.2.0 + +Changes after the 0.2.0 rows, each measured with `benchmarks ab` against its parent (the +sections below give each one): transforms threaded by their shape and a modal stage's +forward rows in one transform (2026-11-09; geometric mean 0.977 on an Intel Xeon Gold +6240 and 0.981 on an AMD EPYC 7763, `argon_blueshift` 0.80 to 0.87 at full width); +free space's separable propagators as vector maths (2026-11-08; `line` 0.893 at one +thread on a Xeon Gold 6240); a run's fixed host cost (2026-11-08; 0.3 s less to build +every case, and 1.8 s and 2.4 s less to build and translate `kerr_beam_384`); and SEP +52's native workspace seam (2026-11-16; every round within 0.98 to 1.04 on an AMD EPYC +7763). A machine calibration (SEP 46) moved the tracking set by 0.965 on a Google Cloud +C4A and 0.989 on an Intel Xeon Platinum 8581C, and chose the built-in table, or nearly, on +the AMD EPYC 7763, the AMD EPYC 9B45 and the Intel Xeon Gold 6240 (2026-11-08). + +### Against `numpy_ref` + +`numpy_ref` is the reference, not a production backend: it does not thread. Over ten-step +windows of capillary, coherent-wall and general-route cases on one 18-core socket of an +AVX-512 server (recorded by 2026-10-23; the record does not name the model), the native +backend at one thread ran 2.1 to 8.6 times faster than `numpy_ref`. At 18 threads, on +larger general-route and coherent-wall workloads (2 to 32 channels, up to 16 384 fine +samples), it ran 6 to 40 times faster than single-threaded `numpy_ref`. + +## Where a run's time goes + +- **A source evaluation's transforms, response and dense products dominate the steps.** + In a one-thread `grin_nonlinear` window on an Intel Xeon Gold 6240 (2026-10-30), after + the changes of [band column passes](#band-column-passes-and-the-general-routes-real-signal), + the complex inverse transform took 1.21 s, the projection 1.17 s and the synthesis 1.31 s; + the synthesis and projection each stream a 122 MB map per evaluation at 8–9 GB/s, about + what one core draws from memory. In a one-thread `ctc` window the band plasma column + took 1.00 s of the 1.99 s spent in native kernels before those changes, and 0.49 s + after. +- **On free-space grids the separable fold and the transforms share the step.** In a + one-thread `kerr_beam_384` window on an Intel Xeon Gold 6240 the separable fold took + 27.7 s of 69.8 s before its layout change, which took the window to 54.2 s; at sixteen + threads the 384² fold is bound by memory bandwidth, about 52 GB/s (2026-10-29). +- **Host work outside the steps is a fixed cost per run.** On complete runs (Intel Xeon + Gold 6240, 2026-10-30) it is 0.1–0.3 s on the capillary and radial cases and about 6 s on + `kerr_beam_384`: 2–9 % of a one-thread capillary run, and up to a third of the complete + `radial_filament_256` and `kerr_beam_384` runs at sixteen threads. The cost that repeats is a saved plane of a large Cartesian field: about + 3 s for `kerr_beam_384`'s 1.77 GB field (the saved plane's copy 1.1 s, the conversion to + the optics convention 1.0 s, the store's copy 0.6 s, the native observation 0.35 s), + against 7–25 ms for a capillary or radial plane. +- **Construction is mostly FFTW planning and imports.** Without stored wisdom, measured + planning is most of a short run's backend construction (about 1.3 s for averaged + helium's 6400-sample real pair; [persistent wisdom](#persistent-fftw-wisdom)). On an + Intel Xeon Gold 6240 (2026-11-08) CoolProp's import, through optmat's transport model, + is 2.3–2.7 s of every capillary build and the driver's own import 0.75 s. +- **The step loop runs in native code.** The native marches spend 0.4 to 8 µs of host + time a trial where solprop's own march took 11 to 210 µs (AMD EPYC 7763 and Apple M5 + Max, 2026-10-29), so returns to Python are host events (planes, statistics rows, monitor + checks), not steps. A statistics row at every step costs about 290 µs a step on the EPYC + 7763 and 75 µs on the M5 Max; a native call's return at its bound 29 to 91 µs, at most + 0.21 % of a run (Intel Xeon Gold 6240, 2026-11-04). + +### Builds and libraries + +On one 18-core socket of an AVX-512 server (recorded by 2026-10-23; model not recorded), +seven ten-step capillary and general-route cases: against a build with no vendor BLAS +for generic x86-64, linking OpenBLAS alone made the straight capillaries 2.6 to 3.8 times +faster at one thread (the tapers 1.7) and left the general route unchanged; compiling for +`x86-64-v3` alone made the general route 1.4 to 1.5 times faster. A distribution-style +build (`x86-64-v3` and `scipy-openblas32`, ADR-034) ran within about 5 % of a local +`-march=native` build. MKL was 1.4 to 1.8 times faster than OpenBLAS on the TE/TM wall and +level elsewhere. Later, with identical libraries (2026-11-08), `x86-64-v4` against v3 gave +a geometric mean of 0.984 over the tracking set on an Intel Xeon Gold 6240 and +`-march=znver5` 0.963 on an AMD EPYC 9B45, no case reaching the 10 % that run-time +dispatch would need ([#337](https://github.com/LupoLab/solprop/issues/337)). -A one-mode capillary with a field plasma column (`argon_blueshift`: 33 radial nodes, -6400 fine samples) synthesises its node fields as an outer product (33 × 1 by 1 × 6400) -and projects three node drives a source evaluation as a stacked 2 × 33 by 33 × 6400 -product. The product sizing keeps them serial on the engine's side (211200 work, below -the dense threshold), so the vendor GEMM threaded each call over its own pool: at 16 -threads on a Xeon Gold 6240 the 4212 calls of a `--length 0.1` window took 0.46 s, 108 us -each, against 0.29 s at one thread; the band column, which writes the node rows, runs on -the full-width response team. Plain loops tried earlier ran on the product's -serial instance and lost to the threaded library. On a host build with a vendor BLAS, -one real mode at several nodes in one chunk now synthesises and projects through two -small kernels on the response team: the projection one contiguous share of the samples -per thread, both stacked rows from one read of the node rows, written straight into the -fine and coarse rows (no stacked copy); the synthesis one node row per item. Each element -sums the nodes in order from zero (within the GEMM rounding bound; a native test holds -both kernels to `KokkosBlas::gemm`). Label timer at 16 threads: projection 40 us a call -instead of 112, synthesis 26 instead of about 100; the band column and the held products -that read the synthesised rows also ran faster (0.35 to 0.29 s, 0.10 to 0.06 s). -Interleaved `benchmarks ab` against the compact-team commit, Xeon, 3 rounds, `--length -0.1`, the same steps, fields within 4.4e-15: - -| case | 1 thread | 16 threads | -|---|---:|---:| -| `argon_blueshift` | 0.999 [0.993, 1.000] | 0.679 [0.672, 0.688] | -| `rdw` (four modes, unchanged path) | 1.000 | 1.000 | - -`argon_blueshift` now runs 4.1 times faster at 16 threads than at one (1.01 against -4.13 s), where it was 2.8 times. On one thread the kernels are left to the vendor GEMM's -serial ones: in two tracking-set runs the one-thread window was 1.8 % slower with them, -and without them it took 0.963 [0.948, 0.969] of the time with them (the four-mode `rdw`, -whose code is unchanged, also moved by 0.964 in that A/B: code-layout noise of this size -is present at one thread). - -The kernels apply with OpenBLAS only. Apple's Accelerate runs these small calls well, and -on an 18-core Apple M5 Max the kernels on the 18-thread response team took the -`argon_blueshift` window from 3.0 to 3.8 s (1.31 of `main` at 18 threads in the -tracking-set A/B; a bisection of the push found this commit). - -(stacked-projection-splits)= -### Stacked projection splits +### Host vector maths -A real projection that also forms the embedded rule's coarse rows projects both in one -stacked product and then copies the halves into the fine and coarse rows. The copy ran -on the temporal copy's instance, which the copy sizing keeps serial below 65536 samples: -on the four-mode capillary (`rdw`, 4 × 10240 samples) each took about 90 us at 16 threads -on a Xeon Gold 6240, 43 ms of a `--length 0.1` window, beside full-width kernels; on `ctc` -159 us. It now runs on the stage's instance (full width there, serial where the stage -is). Interleaved `benchmarks ab` against the one-mode commit, 3 rounds, `--length 0.05`, -the same steps, fields within 6.1e-15: - -| case | 1 thread | 16 threads | -|---|---:|---:| -| `ctc` | 0.990 | 0.977 [0.976, 0.980] | -| `rdw` | 0.987 | 0.992 [0.962, 0.994] | -| `argon_blueshift_envelope` | 1.004 | 1.012 (no stacked real split) | - -(host-blas-pool)= -### NumPy's BLAS beside a native run +The native CPU kernels' transcendentals through SLEEF's vector functions (ADR-059), complete +runs or long entrance windows of the tracking cases at one thread (2026-10-28): geometric +mean −11.1 % on an AMD EPYC 7763 (AVX2 functions; `gnlse_raman_shock` −19.4 %) and −6.8 % +on an AMD EPYC 9B45, where the opt-in AVX-512F functions gave −11.4 %. On an Intel Xeon of +the Ice Lake generation the AVX2 functions gained 3.7 % and the AVX-512F ones lost 2.9 %, +so AVX2 is the default. On an Apple M5 Max the system libm stays: SLEEF's AdvSIMD functions +forced on were 11.6 % slower (`gnlse_raman_shock` 56 %). -NumPy's OpenBLAS is a pthreads library with a pool of its own, sized from -`OPENBLAS_NUM_THREADS` or every CPU (the benchmark suite sets the variable to the run's -width). During a native run the host calls it only for small products: the power -weights' expansion at each saved plane is a 3 × 2561 `dgemv` on averaged helium, 24 of -them in a `--length 0.5` window. After each call OpenBLAS's workers spin before they -sleep, and the planes come often enough that they never do: at 16 threads on a Xeon Gold 6240 -Gold 6240, its 15 workers took 1.09 s of CPU each in a 1.24 s window, and the -four-thread Adams passes ran three times as slowly (0.74 s against 0.22 s, label timer). -The native backend now holds every BLAS but its own to one thread while it lives, as -`numba_cpu` holds its BLAS pool. Interleaved `benchmarks ab` against the parent, 3 rounds, -`--length 0.1`, passive-bound placement, the same steps and fields to rounding: - -| case | Xeon Gold 6240, 1 thread | 16 threads | AMD EPYC 7763, 1 thread | 16 threads | -|---|---:|---:|---:|---:| -| `rdw` | 0.996 | 0.462 [0.456, 0.465] | 1.012 | 0.762 [0.749, 0.780] | -| `he_rdw_averaged` | 1.011 | 0.693 [0.670, 0.773] | 0.997 | 0.343 [0.326, 0.816] | -| `radial_filament_256` | 0.996 | 0.725 [0.718, 0.726] | 0.992 | 0.610 [0.603, 0.791] | -| the other nine tracking cases | 0.984-1.019 | 0.979-1.010 | 0.988-1.020 | 0.972-1.017 | -| geometric mean (12 cases) | 1.000 | 0.886 | 1.001 | 0.855 | - -The EPYC rows are 16 cores of a shared node (its averaged-helium spread is the node's). - -The four-mode capillary now runs 3.1 times faster at 16 threads than at one (0.77 s -against 2.40 s), where it was 1.4 times. - -(smooth-size-cliffs)= -### Smooth grid sizes +## Threads -`python -m benchmarks.size_cliffs` times the four-mode RDW capillary per source -evaluation (short and long capped Runge-Kutta windows, their difference) on 2-3-5-smooth -and power-of-two grids, and flags a size whose cost per sample exceeds its nearest power -of two's by more than 25 %. Two size boundaries made cliffs: the stage threshold (8192 -elements, just above n_t 4000's 8004-element stage, whose entry kernel then took 708 us -serially against 59 us at full width) with the FFT threshold (32,768 samples, above its -32,000-sample batch), and a node budget that left 33 nodes as a 32-node pass and a serial -one-node tail at n_t 8640. With the thresholds at 4096 and 16,384 and the nodes spread -evenly over the passes, on one 18-core socket of a Xeon Gold 6240 (GCC 16, FFTW 3.3.11, -ms per evaluation, two rounds each): - -| n_t | 4000 | 4096 | 4500 | 5000 | 6000 | 7200 | 8000 | 8192 | 8640 | -|---|---:|---:|---:|---:|---:|---:|---:|---:|---:| -| before | 2.45–2.47 | 1.24–1.36 | 1.49–1.56 | 1.54–1.57 | 1.86–1.87 | 2.21–2.26 | 2.38–2.39 | 2.29–2.30 | 3.52–3.55 | -| after | 1.32 | 1.27–1.36 | 1.53–1.54 | 1.57–1.61 | 1.83–1.87 | 2.17–2.26 | 2.38–2.40 | 2.28–2.31 | 2.54–2.58 | - -At a stage threshold of 1024 a 1351-element SSFS stage regressed (1.2 to 1.7 ms); the -reduced comb-to-continuum and SSFS cases did not move at 4096. On a dual EPYC 7643 (Zen 3, -idle node, pinned) the same change made n_t 4000 24-27 % faster at 12 and 24 threads -(2.36-2.42 to 1.74-1.82 ms), and the even chunks made n_t 8640 4-13 % faster; other sizes -moved within 5 %. On an 18-core Apple arm64 laptop, in contrast, n_t 4000 went from 0.88 -to 1.04 ms (level with 4096), and even 4096's threaded stage is dearer than 4000's serial -one: the crossover there lies above 8192. macOS therefore keeps the stage and FFT -starts at 8192 and 32,768; its own crossover still needs a sweep on a quiet machine. Its -node-chunk gain stands (n_t 8640: 2.35 to 1.73 ms). - -(radial-chunk-dispatch)= -### Radial analytic chunk dispatch +### Kokkos CPU operation-size threading -Admitting partial analytic radial node chunks to the interleaved real GEMM, instead of a -scalar contraction that took about 94 % of the source time, made the radial filament's -adaptive Adams window (256 and 512 nodes, 12 accepted steps, construction excluded) 2.8 -to 8.8 times faster on Kokkos CPU, on an exclusively allocated two-socket AVX-512 server. -At one thread Kokkos then took 0.91 (256 nodes) and 0.95 (512) times `numba_cpu`'s time, -at 36 threads 0.10 and 0.12 times. +The native CPU backend chooses each operation's thread width from its dimensions at +construction ([tuning](../guide/performance/tuning.md)); a machine calibration may replace +the table below (SEP 46). On an 18-core arm64 laptop and a two-socket, 36-core AVX-512 +server (recorded by 2026-10-23; models not recorded) the sizing ran the small cases 2.00 +and 2.06 times faster than one thread. Copies and arithmetic need separate thresholds: an +8,192-element temporal copy is slower threaded, an arithmetic stage of that size is not. The exponential Adams +trial's two passes, about ten stage entries an element, thread at four from 8,192 elements +and take the pool from 65,536: a fork and join of sixteen sleeping threads costs 100–200 µs +(16 cores of a dual AMD EPYC 7643, 2026-10-28). -(multimode-cpu-step)= -### Multimode CPU step costs +The built-in table counts elements or product work, never bytes (the counts are defined +in `native/src/solprop_native/_execution.py`): -Sharing real cubic monomials across output components, planning general-modal tail -transforms over active rows only and seeding serial transforms with measured FFTW wisdom -brought Kokkos CPU to 1.00–1.07 times `numba_cpu`'s best time at one thread on an arm64 -laptop, over 1–2 mm entrance windows of the general modal and reduced -comb-to-continuum cases with both adaptive methods. In ten-step profiles the general -route's tensor work fell from 0.44 to 0.15 s and its ordinary FFTs from 1.00 to 0.84 s. -Measured FFTW planning adds about 18 ms (general modal) and 120 ms (reduced -comb-to-continuum) of construction. A direct FFTW execution adapter, a pooled allocator -and vector transcendental functions were measured and not needed -([CPU performance](cpu-performance.md)). - -(multimode-threaded-planning)= -### Threaded FFT plan selection +| Operation | Serial below | Full pool from | Between the two | +|---|---:|---:|---| +| Stage, update, reduction | 4,096 (macOS 8,192) | the same | none | +| Packing, temporal copy | 65,536 | 65,536 | none | +| Response | 32,768 | 196,608 | four threads; 40 columns or 65,536 fine samples a column also take the pool | +| Native or custom GEMM | 1,048,576 | 1,048,576 | none | +| General-modal synthesis, projection, maps | 65,536 | 65,536 | none | +| Coupled matrix functions | 32,768 | 32,768 | none | +| Exponential Adams trial passes | 8,192 | 65,536 | four threads | +| Modal and spatial FFT | 8,192 (macOS 32,768) | 4,194,304 | by shape ([transforms by shape](#transforms-by-shape-and-one-forward-pack)) | +| Raman FFT | 65,536 | 262,144 | four threads | -FFTW's measured planning sometimes chose a slower threaded plan: on a 32-core AVX-512 -server, for 204 rows of 2048 complex samples at 32 threads, a 64 × 32 decomposition -instead of 32 × 64 made the warm general-modal RK window about 12 % slower, almost all of -it in complex transforms. Measured wisdom is now seeded only for serial transforms; -threaded ones default to estimate planning. Against the previous build, the general modal -case's window then took about 0.80 times as long at one thread and the same at 32 -threads; reduced comb-to-continuum stayed within its repeatability. +Every width is capped by the process's thread budget, and on Apple silicon's spinning top +tier every threshold is divided by sixteen (ADR-073). Backend metadata records the +effective widths. -### Low-storage interaction-picture RK +### A stable kernel team -The low-storage march (four evaluations a step) against the IP-DOPRI5 replay (six, with -first-same-as-last) on a Cartesian envelope Kerr beam with no collar, fixed 0.5 µm steps, -ten timed steps after one untimed one, same-process comparisons on an 18-core arm64 -workstation. Shape A is 192 × 192 × 300 (one state 177 MB), shape B 384 × 384 × 600 -(1.42 GB). Ratios are how many times less time the march takes than the replay on the -same backend: - -| backend | shape, threads | per step | per evaluation | field volumes held, march / replay | -|---|---|---:|---:|---:| -| `numba_cpu` | A, 1 | 1.83× | 1.22× | 4 / 16 | -| `numba_cpu` | A, all | 1.77× | 1.18× | 4 / 16 | -| `numba_cpu` | B, all | 1.73× | 1.15× | 4 / 16 | -| Kokkos CPU | A, 1 | 2.02× | 1.35× | 4 / 15 | -| Kokkos CPU | A, all | 1.81× | 1.21× | 4 / 15 | -| Kokkos CPU | B, all | 1.85× | 1.24× | 4 / 15 | - -Recomputing the flow factors instead of tabulating them holds three volumes and costs -3–13 % more. Most of a march step is now the source evaluation's core (transforms, the -Kerr column, packing): 69 % on `numba_cpu` at one thread, the fused finish 27 %. At all -threads the Kokkos march was 1.6 (shape A) to 2.1 (shape B) times faster than -`numba_cpu`'s. +GNU OpenMP ends a team's surplus threads when a region asks for fewer and starts them +again for the next wider one: alternating 16- and 4-thread regions took about 490 µs a pair +against 40 µs for two 16-thread regions (one socket of an Intel Xeon Gold 6240, +2026-10-29). A pool that already holds a full-width instance therefore hands it to +medium-width kernels too. At 16 threads the tracking set's geometric mean was 0.924 on a +Xeon Gold 6240 and 0.938 on an AMD EPYC 7763, `h2_raman_averaged` 0.526 and 0.483. The +promotion applies everywhere but macOS, where the Apple M5 Max's two kinds of core made it +lose; on Windows (LLVM's libomp) it still gained (`h2_raman_averaged` 0.906 on eight cores +of an AMD EPYC 9B45). -### Band-rule plasma integration +### Compact CPU teams -The band-exact plasma integrals -([SEP 18](seps/archive/sep-0018-band-exact-plasma-integrals.md)) against the trapezoid, on -the four-mode RDW window (33 nodes, 8192 fine samples, ten fixed steps from the launch), -for the band column as first built: - -| backend | threads | band / trapezoid window | -|---|---|---:| -| `numba_cpu` (arm64 laptop) | default | 1.51–1.58 | -| `numba_cpu` (arm64 laptop, or the AVX-512 server, where this column ran serially) | 1 | 2.4–2.5 | -| Kokkos CPU (arm64 laptop) | 18 / 4 / 1 | 1.3 / 1.9 / 2.7 | -| Kokkos CUDA (data-centre NVIDIA GPU), direct halo reads | — | 1.10 | -| Kokkos HIP (AMD Instinct GPU), halo staged in team scratch | — | 1.25 | - -On a CPU each integral is a nine-tap filter inside a serial traversal; on a device the -filters are parallel maps over the row, so the band rule costs about a tenth more than -the trapezoid there. Staging the halo in team scratch loses on the NVIDIA device (1.21) -and wins on the AMD one (1.36 with direct reads), so each build defaults to its winner. -`numba_cpu`'s column has since been rewritten as whole-row passes, 1.7 times faster than -the traversal measured here ([algorithms.md](algorithms.md)). A finer grid, the -alternative SEP 18 rejects, costs about twice the whole nonlinear term for a quarter of -the error. +A problem of one column on one node (the GNLSE, the mode-averaged capillary) has few +operations large enough to thread. At 16 threads `gnlse_raman_shock` ran its serial +kernels 1.2–2.5 times slower than in a one-thread process: waking fifteen cores each 0.9 ms +evaluation held the main thread at about 2.7 GHz instead of 3.5, and its loads found lines +modified in other cores' caches (Intel Xeon Gold 6240, 2026-10-29). Such a problem now runs +on a team of at most eight threads, its FFT plans on that team through FFTW's loop +callback, and its products on one OpenBLAS thread. `gnlse_raman_shock` then ran 1.25 times +faster at 16 threads than at one, where it had run at the same speed; on a Google Cloud C4A +(Neoverse V2) the single BLAS thread took it from 25.8 to 17.6 s at 16 threads. -### Dispersive electronic response +### Stacked projection splits -The dispersive Kerr response ([SEP 6](seps/archive/sep-0006-dispersive-nonlinearity.md), -[backends.md §3.11](backends.md#311-the-dispersive-electronic-response)) is judged by its -nonlinear stage time against the constant cubic's on the same route: the symmetric -evaluator's target is 1.3, the polynomial's 4. Same-process medians of ten-step windows -from the launch, on the RDW grid and on Cartesian, line, planar and general-route -problems: - -| evaluator | `numba_cpu` | Kokkos CPU | GPUs (NVIDIA and AMD) | -|---|---|---|---| -| symmetric, one species | 0.92–1.23 (1.31–1.35 on one averaged node, analytic sector) | 0.81–1.21 at one thread | 0.86–1.30 | -| symmetric, mixture (one filter from the mixture's Kerr diagonal) | 0.90–1.11 | 0.97–1.21 at one thread | 0.86–1.30 | -| polynomial, one species or equal leg bounds | 1.16–3.72 | 1.52–3.65 at one thread; 4.2–5.0 on the general route | 1.01–3.53 | -| polynomial, mixture of distinct leg bounds | 4.1–7.6 (3.3–3.7 for helium and argon in the default pools) | 3.2–8.3 at one thread, at most 2.2 in the default pools | within 4 (air 1.5–2.1) | - -Ten-step windows, which carry the integrator's own work, move less than the stage. A -rebuild of the mixture filter when the densities change costs about 2 % of a symmetric -stage. A polynomial mixture is one group per distinct leg bound, which is why mixtures -such as air miss its target on the CPUs. +A stacked fine-and-coarse projection's split ran on the temporal copy's serial instance, +about 90 µs a copy at 16 threads on `rdw` beside full-width kernels (Intel Xeon Gold 6240, +2026-10-29); on the stage's instance `ctc` took 0.977 of its time. -### Far-field statistics pass +### Smooth grid sizes -The banded far-field pass (six aperture statistics and the on-axis spectrum, 30 slots) -on the last state of a Cartesian envelope Kerr run (192 × 192 × 256 and 384 × 384 × 512), -same-process comparisons: about 2.3–2.6 % of one Runge–Kutta step on both `numba_cpu` -and Kokkos CPU, paid at save planes and periodic rows only. On `numba_cpu` it costs about -as much as the `energy` statistic and is 30 to 37 times faster than the host pass it -replaced (which cost 77–84 % of a step). On Kokkos CPU it is compute-bound (square roots -and saturated `tanh` weights), 15–16 times `energy`. - -The per-row profile and shape of kernel schema 45 (#446) left a set of circles' path alone. -Measured on the pass alone, `NativeBackend.stats` of `aperture_spectrum` and `beam_spectrum` -called seven times per process on a held 192 × 192 × 192-bin state of a Cartesian grid, -interleaved old and new builds in four rounds, native CPU at 8 threads on an Intel Xeon Gold -6240, GCC 16.2. The machine was shared and each round's numbers moved by up to 60 % -between runs, so the fastest round of each arm is the figure (ms per call, before → after): -three hard holes 31.75 → 32.16 (+1.3 %), three hard holes on one centre, with the radius -shared, 32.26 → 32.69 (+1.3 %), three `tanh` holes 79.42 → 76.74 (−3.4 %), sixteen `rcos` -holes 103.4 → 89.7 (−13 %). The results of both backends on these sets were identical to the -bit. A shape other than a circle forms its offsets and takes one more branch per row and -element. That comparison is indicative; the far-field pass runs at save planes and periodic -rows only. The whole-run check is `python -m benchmarks ab --case rdw --case far_field_stats ---threads 1,16 --length 0.1 --rounds 5 --repeats 1`, an exclusive AMD EPYC 7763 node, GCC 16.2, -base f004a662: candidate/baseline `far_field_stats` 0.994 at one thread (21.48 → 21.38 s) and -0.994 at 16 (4.699 → 4.696 s), `rdw` 0.997 at both, geometric mean 0.995, the fields agreeing -to 6e-15 and the same work on every row. Those holes are circles; the new shapes were not timed -there. - -On a device (#364): one `stats` call of `aperture_spectrum` on the marched field, `rcos` edges -and quadrature weighting, the median of six in one process, against one low-storage RK4IP step -of the same process. NVIDIA H200 with CUDA 13.1 and AMD Instinct MI325X with ROCm 10, 2026-11-04. - -| Grid | Holes | H200 call / ms | of a step | MI325X call / ms | of a step | -|---|---:|---:|---:|---:|---:| -| 384² × 600 | 4 circles | 6.2 | 11.6 % | 6.1 | 9.9 % | -| 384² × 600 | 16 circles | 13.6 | 25.3 % | 14.6 | 23.9 % | -| 768² × 600 | 4 circles | 15.4 | 6.5 % | 14.4 | 6.5 % | -| 768² × 600 | 16 circles | 33.3 | 14.1 % | 33.8 | 15.2 % | -| 768² × 600 | 4 mixed shapes | 16.0 | 6.7 % | 16.7 | 7.5 % | -| 768² × 600 | 16 mixed shapes | 36.9 | 15.6 % | 44.7 | 20.0 % | - -A step takes 53.9 and 236 ms on the H200, 61.0 and 223 ms on the MI325X. So at a few steps per -saved plane the pass is under 5 % of the plane, and SEP 23 §6's registers and groups have -little left to win: the pass costs about 1.5 ms per hole on top of the 9 ms `beam_spectrum` -takes, and even sixteen holes cost less than the 54 ms (H200) and 80 ms (MI325X) of `energy` on -the same field. +`python -m benchmarks.size_cliffs` flags a 2-3-5-smooth grid size whose cost per sample +exceeds its nearest power of two's by more than 25 %. Two boundaries made cliffs: the +stage threshold just above n_t 4000's 8004-element stage, and a node budget that left a +serial one-node tail at n_t 8640. With the thresholds lowered to 4096 and 16,384 and the +nodes spread evenly, n_t 4000 went from 2.45 to 1.32 ms per evaluation and n_t 8640 from +3.52 to 2.54 ms on an 18-core socket of an Intel Xeon Gold 6240 (2026-10-25). On an 18-core +arm64 laptop (model not recorded) the threaded stage is dearer than the serial one up to +8192, so macOS keeps the higher thresholds. -### Raman kernel rebuild +### Thread scaling -On a density gradient the Raman kernel is rebuilt at every stage, and its cost scales with -the response's rows. `numpy_ref`'s rebuild at $2^{14}$ fine samples (median of 35, -same-process, a loaded laptop) took 0.31 ms for a two-term N₂ model (rotation and -vibration), 0.47 ms for optmat's H₂ (4 rows), 6.0 ms for optmat's N₂ (72 rows) and -10.2 ms for dry air (126 rows), against 0.25 ms for one convolution. With tens of rows -the rebuild dominates the step; Kokkos's native rebuild is slower than the host's at one -thread and overtakes it at four. [SEP 10](seps/sep-0010-low-rank-raman.md)'s low-rank -representation is what removes it. +One-thread time over production-width time in the 0.2.0 rows of the +[tracking set](#the-tracking-set-at-020) (2026-11-07): -### General-route symmetric contraction +| case | M5 Max, 18 | Xeon Gold 6240, 36 | EPYC 7763, 16 | EPYC 9B45, 16 | Neoverse V2, 16 | +|---|---:|---:|---:|---:|---:| +| `gnlse_soliton` | 0.99 | 0.98 | 1.01 | 1.00 | 1.01 | +| `gnlse_raman_shock` | 1.18 | 1.14 | 1.14 | 0.92 | 1.47 | +| `argon_blueshift_averaged` | 1.21 | 1.24 | 1.15 | 1.09 | 1.32 | +| `argon_blueshift_envelope` | 1.37 | 0.71 | 1.06 | 1.39 | 0.76 | +| `rdw` | 2.04 | 2.21 | 2.42 | 1.99 | 3.34 | +| `argon_blueshift` | 2.74 | 2.03 | 2.71 | 1.97 | 3.58 | +| `radial_filament_256` | 3.22 | 4.94 | 3.95 | 4.85 | 7.05 | + +- **One column gains little.** A GNLSE or a mode-averaged capillary gains at most about + 1.5 times from a whole machine, and can lose; resolved multimode and radial problems gain + 2 to 7 times. +- **Keep a run in one memory domain.** Two runs of one wheel at 36 threads, unpinned across + the two sockets of a Xeon Gold 6240, differed by 0.84 to 1.57 per configuration + (2026-11-03). On an exclusive AMD EPYC 7763 allocation, binding (`OMP_PROC_BIND=close + OMP_PLACES=cores`) was worth about 11 % on average and neutral on the Xeon Gold 6240, so + it is not the default (2026-10-30). +- **Idle threads spin briefly.** Every machine's calibration refused passive waiting + (2026-11-08): 1.10 to 1.94 times slower, from a Google Cloud C4A to an Intel Xeon Platinum + 8581C. Concurrent scan workers ran the same spinning or passive on an AMD EPYC 7763 node + (2026-11-09). + +## FFT -Summing the general route's real cubic over its ten symmetric monomials instead of the -dense 81 + 3 products ([algorithms.md](algorithms.md)), on a two-channel step-index pair -(288 nodes, 256 samples) at one thread: the respond kernel alone 2.5 times faster on -`numba_cpu`; a ten-step window 1.45 times faster on `numba_cpu` and 1.35 times on Kokkos -CPU. The gain shrinks as channels are added. +### Transforms by shape and one forward pack -### Adams carrier frame per step +A batched forward transform's best width depends on its rows (Intel Xeon Gold 6240, AMD +EPYC 7763 and Apple M5 Max, 2026-11-09): a few rows ran best at about a thread a row; many +rows of a few thousand samples wanted 8 to 18 threads, where four were two to three times +slower; one row gained from being split only from about 16384 samples on the two Linux +machines (4608 on the M5 Max's top tier). Hence the rule: from the FFT threshold a thread +per 4096 samples, at most one a row, or up to the medium width for rows of 16384 samples +(macOS 32768 and 65536). Estimate plans of a prime length at more than four threads ran 15 +to 47 times slower than at four; measured ones did not. A modal stage's forward rows now go +through one plan (`rdw` transforms 28 rows of 10240 at once): `argon_blueshift` 0.88, `rdw` +0.90 and `ctc` 0.92 on 18 cores of a Xeon Gold 6240. One-column problems keep separate +transforms, which the pack made 1.35 times slower there. -The scalar carrier frame ([SEP 35](seps/archive/sep-0035-carrier-frame-exponential-adams.md)) -adds, per trial, a shifted argument and one complex product per element in the moments -pass and one complex product per history row read. Ten replayed steps of a 2 mm, -40 bar hydrogen capillary (16 µm, 515 nm, 2 ps window, 4097 bins, one mode, a weak -collar), the stepping alone timed, one thread, median ratio of nine same-process -interleaved pairs on an Apple M5 Max, a machine in ordinary use (labelled A/B, not an -absolute timing): - -| source | `numba_cpu` off → scalar | ratio | native CPU off → scalar | ratio | -|---|---|---|---|---| -| Kerr only | 11.9 → 12.4 ms | 1.042 [1.019, 1.096] | 9.2 → 9.7 ms | 1.057 [1.036, 1.066] | -| Kerr and Raman | 121.5 → 121.9 ms | 1.007 [0.995, 1.017] | 95.4 → 95.8 ms | 1.006 [0.997, 1.009] | - -Forming `exp(x - sigma)` as `exp(x) exp(-sigma)` instead of a second exponential took -native's Kerr-only ratio from 1.076 to 1.057. The per-step cost is a few per cent where -the source is cheap and negligible where it is not; the policy's case rests on the calls -it saves, which SEP 35's phase 4 measures at matched error. - -(resident-adams-memory)= -### Resident Adams storage +### Threaded FFT plan selection -At maximum order five the Kokkos resident Adams engine held 29 complex field volumes, -eleven of them dense-output slopes and saved fields allocated even when planes are landed -on. Allocating those only for `interpolate_planes=True` reduces it to 18 -([backends.md §8](backends.md#8-memory-ledger)). Peak RSS of a reduced-resolution -`kerr_beam_384` (same box, 600 temporal bins, ten accepted steps, four threads, median of -three fresh processes on an 18-core arm64 laptop), in GiB; the 384² row is a projection -from the other two (constant plus transverse area), not a measurement: - -| grid | `numba_cpu` | Kokkos, 29 volumes | Kokkos, 18 volumes | 18 volumes / `numba_cpu` | -|---|---:|---:|---:|---:| -| 128² | 4.31 | 7.53 | 5.92 | 1.37 | -| 256² | 15.7 | 28.2 | 21.8 | 1.38 | -| 384², projected | 34.8 | 62.7 | 48.2 | 1.39 | - -Field export adds a further host copy (up to 1.43 times `numba_cpu`'s peak). No -field-sized workspace scales with the thread count. The allocations are itemised under -[reference tables](#resident-adams-allocations). - -### Free-space cases at the package defaults - -Per-step time of the free-space cases at the package's defaults, production thread -policy, on a 64-core AVX-512 cloud server (seconds per step, medians of two repeats): - -| case | stepper | Kokkos CPU | `numba_cpu` | -|---|---|---:|---:| -| Kerr beam 384² | march | 0.348 | 0.796 | -| Kerr beam 384² | IP-DOPRI5 | 0.998 | 2.49 | -| Kerr beam 768² | march | 1.51 | 3.34 | -| Kerr beam 768² | IP-DOPRI5 | 4.09 | 10.1 | -| Cartesian filament 128² | default | 0.076 | 0.300 | -| Cartesian filament 256² | default | 0.296 | 1.19 | - -The march scales from 384² to 768² as 4.33 (Kokkos) and 4.20 (`numba_cpu`) against -$N \log N$'s 4.30. Against a per-evaluation reference built from the cost of its parts -(transforms and response), the march's evaluations take 0.94–1.37 times the reference and -IP-DOPRI5's 1.21 (Kokkos) and 1.80 (`numba_cpu`) -([SEP 28](seps/archive/sep-0028-free-space-evaluation.md)). - -### The boundary monitor's reading - -Each backend reduces the boundary monitor's five numbers where its state lives, instead -of copying the field to the host to be transformed there (ADR-057). The benchmark -harness runs without a monitor, so the monitor's cost is measured by its own same-process -comparison: each case built by the harness's builder and run through `Simulation.run` -with the default check and with `boundary_check=None`, alternated, five times each -after a warm-up of each, the shortest of each arm compared. - -**Monitored over unmonitored run time**, native CPU, one thread, on a two-socket AMD -EPYC 7763 node (GCC 16.2, FFTW 3.3.11, Kokkos 5.2.1 OpenMP); before is the parent -revision, after is this change: - -| case, window | accepted steps | before | after | -|---|---:|---:|---:| -| Kerr beam 192², the whole 2 µm guide | 4 | +7.8 % | +4.0 % | -| radial filament 256, 3 mm | 68 | +0.9 % | +0.6 % | -| GNLSE soliton, a fifth of the guide | 81 | +5.5 % | +1.5 % | +FFTW's measured planning sometimes chose a slower threaded plan: for 204 rows of 2048 +complex samples at 32 threads on a 32-core AVX-512 server (recorded by 2026-10-23; model not +recorded), a 64 × 32 decomposition instead of 32 × 64 made a general-modal window about +12 % slower. Measured wisdom is seeded only for serial transforms; threaded ones default to +estimate planning. -The Kerr beam's guide is shorter than its steps times the monitor's 256 checks, so every -step is checked. A check now costs one inverse transform of the state where it lives -and a pass that sums it; it was three host copies and a single-threaded host transform. -**One check** of the launched state, the backend's reading against that host path, same -process, shortest of seven: +### Persistent FFTW wisdom -| case | EPYC 7763, one thread | NVIDIA A40 | NVIDIA L4 | -|---|---:|---:|---:| -| Kerr beam 192² (36,864 columns × 384) | 100 ms / 218 ms | 3.4 ms / 214 ms | 5.0 ms / 511 ms | -| radial filament 256 (256 × 864, field) | 1.08 ms / 1.22 ms | 0.13 ms / 1.03 ms | 0.14 ms / 4.3 ms | -| GNLSE soliton (one column × 3072) | 0.027 ms / 0.071 ms | 0.082 ms / 0.085 ms | 0.072 ms / 0.095 ms | - -The GPU columns are CUDA 12.8 builds (an A40 on its node's host, an L4 on an 8-vCPU -cloud host, whose host path is the slower). On a field grid under the split scheme the -native reading uses the collar's inverse real transform, half the analytic signal's -work; through the analytic signal the radial filament's check took 1.83 ms against the -host path's 1.13 ms at one thread. The L4's column was measured before that change. On `mlx` -(Apple M5 Max, a busy laptop: ratios only, same process), monitored over unmonitored on -the spatial cases of 60 fixed steps: radial 256 1.36 → 1.01, Cartesian 64² 1.21 → 1.05, -Cartesian 128² 1.28 → 1.06. The unmonitored path is unchanged: -`python -m benchmarks ab` at one thread on the same node gives 1.000 (GNLSE soliton), -1.005 (radial filament) and 1.005 (Kerr beam) for the three cases above. - -**What the split finds** (the guards judged on the power each step's split finds, -halfway through its factor, and the split collar's crossing limit, #127 and #149). The -finish's removal pass sums four more numbers of the samples it already holds, on every -accepted step under the split scheme while a monitor is attached. Only a check reads -them, but a saved plane is checked whatever the cadence said of its step, and the -native marches decide their own steps; forming them only on the steps that end at a -check would save a few multiply-adds per sample already in hand, at the cost of telling -every march which steps those are. They are formed on every step. Measured on an Apple M5 Max (Homebrew Clang 23, NEON FFTW -3.3.11, one thread, a shared machine: ratios only), a tenth of each guide, before the -change (its parent on `main`) and after: - -| case, a tenth of the guide | backend | monitored / unmonitored, before | after | `ab`, unmonitored | -|---|---|---:|---:|---:| -| radial filament 256 | native | 1.028 | 1.030 | 1.018 | -| line | native | 1.666 | 1.660 | 1.001 | -| planar | native | 1.469 | 1.470 | 1.001 | - -The first two columns are the same-process comparison above (shortest of five after a -warm-up, alternated); the last is `python -m benchmarks ab --length 0.1 --rounds 3`, -the median ratio of candidate to baseline over paired rounds. Within the machine's -spread both ways; the line and planar cases' monitored cost is the transverse edge's -reads (#396). The steps are the same: on these cases the crossing limit does not bind. - -**The crossing cap read at every check** (#440). Under the split scheme each check also -sums the state's energy per walk-off bucket, one more pass over the state where it lives -(a histogram of 128 buckets: NumPy's `bincount` on the host, a Kokkos `ScatterView` in -native, a scatter-add on the `mlx` device). Measured as above, the same machine and -window, before (the previous head of this branch) and after: - -| case, a tenth of the guide | backend | monitored / unmonitored, before | after | -|---|---|---:|---:| -| radial filament 256 | native | 1.031 | 1.039 | -| line | native | 1.658 | 1.698 | -| planar | native | 1.470 | 1.484 | - -One to two and a half per cent of the run on the shared machine, about a third of a check's own -cost. The Cartesian filament 128² takes 1.158 monitored over unmonitored before; its -after was not timed, at fifteen minutes a pair at one thread. The steps are unchanged -on every case: the cap never fell below a step these runs took. - -### The transverse edge and a requested collar - -[SEP 40](seps/archive/sep-0040-transverse-absorbing-boundaries.md) puts a k⊥ safety ramp -and reads of the transverse edge on every free-space run by default, and builds a real-space -collar on request. The default's cost was measured as the monitor's was above, with each case -built by the harness's builder and run four ways in the same process: - -- with neither the ramp nor reads; -- with the ramp alone; -- with reads alone; -- with both. - -The four were interleaved, six rounds each. The setup: a Xeon Gold 6240, one socket, -18 threads, GCC 16. - -| case | steps (no reads → reads) | both, native | both, `numba_cpu` | -|---|---:|---:|---:| -| line | 27 → 28 | +14.0 % | +6.4 % | -| planar | 40 → 40 | 0.0 % | −1.1 % | -| radial filament 256 | 127 → 127 | +2.2 % | −0.1 % | -| Cartesian filament 128, half length (its light reaches the edge) | 40 → 41 | +10.5 % | +2.6 % | +At one thread the default plans every row transform with FFTW's measured search. +`SOLPROP_FFTW_WISDOM` keeps those plans for the next process +([tuning](../guide/performance/tuning.md)). On one core of an Intel Xeon Gold 6240 +(2026-10-29) it took the backend's construction from 1.4 to 0.033 s on `he_rdw_averaged`, +from 4.0 to 0.029 s on `h2_raman_averaged` and from 5.0 to 0.056 s on `ctc`, with windows +as fast as cold ones; an AMD EPYC 7763 gave the same picture. What remains of a warm +construction is allocation and setup: tens of milliseconds, a few tenths of a second for a +free-space Kerr beam's 1.4 GB of state. -The ramp alone costs nothing measurable. Reading costs in two ways. The read ceiling, -`min(L/16, 4g/v_q)`, adds a step on the line and Cartesian cases. Each read also has a -host cost: about 1 ms on the line case's 0.2 s run, and about 180 ms on the native -Cartesian filament. Both are open in [#396](https://github.com/LupoLab/solprop/issues/396); -[the edge against 0.1.0](#the-transverse-edge-against-010) has the later measurements. +### Native CPU FFT and diagnostic scheduling -A requested collar was measured on the suite's `spatial_absorber` case, a 0.9 P_cr argon -beam over 8 cm with 64 samples across its 3e-4 m aperture. The table gives the field error -on the aperture against a bare wall at 8 R: +Ten-step windows on an Apple M5 Max and two Intel Xeon Gold 6240 (2026-10-24). FFTW's NEON +codelets made an eight-case screen 0.933 on the M5 Max, where vDSP stays for short parallel +power-of-two rows. Tuned Kokkos-FFT Raman plans took `ctc` to 0.698 and `h2_raman_averaged` +to 0.480 at one thread, for more measured planning (`ctc`'s serial construction 3.0 → 22.8 s). +Deferring a step's coarse projections to accepted scoring cut `rdw`'s forward transforms +from 427 to 274 a window (`rdw` 0.82 at 18 threads on the Xeon Gold 6240). The M5 Max's +retained combination: 0.792 at one thread, 0.865 at 18. -| transverse room | wall | error | translate | run, native | run, `numba_cpu` | -|---|---|---:|---:|---:|---:| -| 3 R | bare | 1.2e-7 | — | 0.22 s | 1.24 s | -| 3.6 R | collar, f = 2.6 | 2.3e-6 | 6.4 s | 0.74 s | 2.27 s | -| 4.5 R | collar, f = 3.5 | 5.0e-7 | 8.2 s | 1.08 s | 2.24 s | +## BLAS -Most of a collar's cost is its design check at translation. That check also raised the -process's peak memory from 0.45 to 0.68 GB. The SEP's phase 3 report has the full tables. +### NumPy's BLAS beside a native run -### The native read of the transverse edge +NumPy's OpenBLAS is a pthreads library with a pool of its own. During a native run the host +calls it only for small products, often enough that its workers never sleep: at 16 threads +on an Intel Xeon Gold 6240 its 15 workers took 1.09 s of CPU each in a 1.24 s window, and +the Adams passes ran three times as slowly (2026-10-29). The native backend holds every +BLAS but its own to one thread while it lives: `rdw` 0.462 at 16 threads on the Xeon Gold +6240 and 0.762 on an AMD EPYC 7763, geometric means 0.886 and 0.855. A fresh process pays +the same pools at import (0.75 s of wall time and 13.8 s of CPU unpinned on 72 logical CPUs +of the Xeon Gold 6240, 2026-11-08); processes solprop starts set `OPENBLAS_THREAD_TIMEOUT`. -[SEP 44](seps/archive/sep-0044-native-edge-read.md) reads the edge on the state's own memory, with only numbers returning. Its Part II holds the measurements phase by phase, and [the next section](#the-native-read-on-the-data-centre-cards) those on an NVIDIA H200 and an AMD Instinct MI325X. +### One-mode products on the response team -Against itself, SEP 40's four-way control, `python -m benchmarks.edge_overhead`, native at 18 threads of an Intel Xeon Gold 6240, 5 rounds, default check against no ramp and no reads: +A one-mode capillary with a field-plasma column synthesises and projects its node fields +through products the sizing keeps serial on the engine's side, which the vendor GEMM then +threaded over its own pool (0.46 s of a short window at 16 threads against 0.29 s at one, +Intel Xeon Gold 6240, 2026-10-29). Two small kernels on the response team took `argon_blueshift` to +0.679 at 16 threads. They apply with OpenBLAS only: Apple's Accelerate runs these calls +well, and on an Apple M5 Max the kernels made the window 1.31 times slower. The vendor GEMM +also beat native GEMMs for products of at most 256 left-matrix entries and plain row loops +for one-mode products on an AMD EPYC 7763. -| case | neither (s) | default (s) | added | reads | -|---|---:|---:|---:|---:| -| `line` | 0.227 | 0.263 | +15.8 % | 23 | -| `planar` | 0.126 | 0.136 | +7.6 % | 23 | -| `radial_filament_256` | 1.335 | 1.389 | +4.1 % | 21 | -| `kerr_beam_192` | 1.837 | 1.989 | +8.3 % | 4 | +## Kernels -`line` takes 224 calls where it took 196, which is the read ceiling on the step and not a read's cost. SEP 40 section 7.7's 2 % limit is retired: the cost is to be as small as possible, and reported. +### The Adams passes on x86-64 lanes -Against the code before it, `python -m benchmarks ab`, `e49925d1` to this stack, 3 rounds, passive threads, 18 cores available, the same work and fields within 4.2e-15: +The exponential Adams trial's predict and correct passes on blocks of 32 elements held as +lanes, against element-by-element strict code (2026-10-29): one thread on an AMD EPYC 7763, +−30 to −37 % on the averaged capillaries and −16 % on `rdw` and `radial_filament_256`; on +an Intel Xeon Gold 6240 a geometric mean of 0.867 over one and sixteen threads. The rest of +the predict pass is about a third SLEEF's complex exponentials, a sixth the memory-bound +phase and rate sum. -| case | 1 thread | 16 threads | -|---|---:|---:| -| `kerr_beam_192` | 0.903 | 0.483 | -| `radial_filament_256` | 0.987 | 0.796 | -| `line` | 0.996 | 0.938 | -| `planar` | 0.994 | 0.835 | +### Host stage entry, free-space crossings and statistics -The geometric mean is 0.85. A requested collar's read, at 384 x 384 x 600 on those 18 cores, one state: the current at each commit 116 ms against the host's 7.36 s, and a read with its strip 0.94 s against 41.9 s, against a step of 2.97 s. On an NVIDIA A40 with 16 host threads, 36 ms against 1.54 s, and 204 ms against 7.98 s, against 0.70 s. +On an Intel Xeon Gold 6240 at one thread (2026-10-29): the modal stage entry as 64-bin real +and imaginary lanes, `gnlse_raman_shock` 0.836; the separable low-storage fold in the +scratch's layout, `kerr_beam_384` 0.789; crossings without run-time divisions, the +monitor's runs and the radial statistics' GEMMs, `radial_filament_256` 0.834 and +`kerr_beam_384` 0.830 again. Together `kerr_beam_192` took 0.635 of its time at one thread. +On an AMD EPYC 7763, whose divisions and strided streams are far cheaper, the free-space +cases took about 0.95 at one thread. -### The native read on the data-centre cards +### Band column passes and the general route's real signal -An NVIDIA H200 (driver 580.196.07, `nvcc` 13.1, an Intel Xeon Platinum 8592+ host, 24 cores) and an AMD Instinct MI325X (ROCm 10.0.0, `gfx942`, an AMD EPYC 9575F host, 20 cores), one rented machine each. The H200's figures are at `8cd170e2`, on 2026-11-05. The MI325X's are at `9a5d2346`, which still took a device's split collar [a whole state at a time](#a-device-step-beyond-its-transforms): by that section's control the node chunk adds 2.2 % to its step, and it hasn't the threaded finiteness pass, which took 0.17 s of each point. "Start" is the same probe on [the default check's section](#the-default-check-on-a-device-reads-occupancy-and-sums)'s base, with no work from these changes. +The band plasma column's passes as block loops, its filter a tap pair at a time on x86-64, +and a real-form cubic's field through a complex-to-real transform (Intel Xeon Gold 6240, +2026-10-30): `ctc` 0.703, `argon_blueshift` 0.641 and `grin_nonlinear` 0.701 at one thread, +0.80 to 0.85 at sixteen; on an AMD EPYC 7763 0.72 to 0.76 at one thread. -`python -m benchmarks.device_split`, field-free, a stated input identity, `held_plane=False`, the first of a runner's points set apart: +### Band-rule plasma integration -| | H200, start | H200, now | MI325X, start | MI325X, now | Aim | -|---|---:|---:|---:|---:|---| -| 768 x 768 x 600, 8 steps, 4 planes: check on, s | 70 | 2.58 | 29 | 2.68 | under 8, under 6 | -| The same, check off, s | 5.9 | 1.98 | 4.2 | 2.00 | | -| On against off | x11.9 | x1.30 | x6.9 | x1.34 | under x2 | -| 384 x 384 x 600, 51 steps, 17 planes: on against off | x12.6 | x1.23 | not run | x1.20 | under x1.25 | -| State crossings of the 8-step point | 13 | 0 | 13 | 0 | 0 | -| A step at 768, ms | 239 | 223 | 224 | 208 | | -| An edge read, ms | about 4,300 | 25 | about 1,000 | 31 | under half a step | -| The temporal monitor's sums, each step, ms | | 24 | | 32 | | -| `field_to_host`, 5.27 GiB, ms | 2,929 | 159 | 506 | 106 | under 300 | -| `energy`, ms | 55 | 2.3 | 80 | 6.7 | under 10 | -| `on_axis_intensity`, ms | | 11.7 | | 14.1 | | -| `beam_radius`, `fwhm_r`, ms | about 1,000 | 43 | about 1,000 | 44 | | -| `peak_intensity`, ms | 134 | 75 | 164 | 74 | | +The band-exact plasma integrals (SEP 18) against the trapezoid on the four-mode RDW window +(recorded by 2026-10-23): 1.3, 1.9 and 2.7 times the time at 18, 4 and 1 threads on an +18-core arm64 laptop (model not recorded), before the block loops +[above](#band-column-passes-and-the-general-routes-real-signal) halved the column; 1.10 +on CUDA (direct halo reads) and 1.25 on HIP (halo staged in team scratch). -The crossings are native's own byte count in `tests/backends/test_native_edge_reading.py`, which ran on both cards, and the point's profile, which lists no crossing. No separate Kokkos trace was taken on these cards. At 51 steps the temporal monitor's sums take most of what the check still costs: on the H200 0.38 s of 0.58 s, and the edge's 18 reads 0.11 s. +### Retained radial synthesis and Raman modal products -**At the head, on an AMD Instinct MI300X** ([#541](https://github.com/LupoLab/solprop/issues/541)). This ran the later commits the MI325X above did not: ROCm 10.0.0, `gfx942`, an Intel Xeon Platinum 8568Y+ host, 20 cores, at `c0bd23f2`, on 2026-11-06. `pytest -m gpu` passed over `tests`, 251 with 1 skipped, and over `native/tests`, 31. The modules of the edge, the collar, the split rows, the transverse backends, the scans, the runner and the stop passed too, 270 with 3 skipped. The same probe at 768 x 768 x 600, 8 steps, 4 planes, takes 2.87 s with the check on and 2.13 s with it off, x1.35. At 384 x 384 x 600, 51 steps, 17 planes, the check costs x1.19. At 768 a step takes 241 ms and an edge read 32 ms. `field_to_host` takes 168 ms, `energy` 6.7, `on_axis_intensity` 14.5, `beam_radius` and `fwhm_r` 48, and `peak_intensity` 78. Every aim holds. These figures are the MI300X's own, not the MI325X's at a later commit. A whole `Local` scan of 5 points through `with_input`, check on, ran two rounds each way, and every point finished. Keeping the backend took 768 x 768 x 600, 8 steps, from 37.4 and 36.2 s to 29.2 and 28.9 s, x0.79, and 384 x 384 x 600, 51 steps, from 27.7 and 27.0 s to 23.7 and 23.7 s, x0.87. With the far field's `clang fp contract(off)` removed, as on #497's base, 31 of the hard-edge fuzz's 120 cases fail (12 of the circle's 40 seeds, 19 of the ellipse's, none of the half-plane's), and so does the older hard-edge test. So the fuzz sees that bug on HIP too. +On an Intel Xeon Gold 6240 (2026-10-29), a square radial map synthesising the retained +spectrum only: `radial_filament_256` 0.928 at one thread, 0.954 at 16; the Raman response +over three-mode `ctc`'s modal products rather than its node drives: 0.884 at 16, at the cost +of more FFT plans (a `ctc` worker's wall time, construction included, 16.3 → 17.7 s). -`python -m benchmarks ab --device` against `main` at `8ed26dd7`, 3 rounds, the same work: +### Radial analytic chunk dispatch -| | H200 | Fields | MI325X | Fields | -|---|---:|---:|---:|---:| -| `kerr_beam_384` | 12.491 s to 0.640 s, x0.051 | 6.2e-16 | 5.101 s to 0.606 s, x0.117 | 6.1e-16 | -| `kerr_beam_192` | 1.535 s to 0.219 s, x0.141 | 5.2e-16 | 0.807 s to 0.111 s, x0.138 | 5.8e-16 | +Partial radial node chunks through the interleaved real GEMM, instead of a scalar +contraction (94 % of the source time), made the radial filament's Adams window 2.8 to 8.8 +times faster on a two-socket AVX-512 server (recorded by 2026-10-23; model not recorded). -A requested collar at 384 x 384 x 600, one state, field-free, native against the host's reduction of a host copy, with a step of 72 ms on both: +### Multimode CPU step costs -| | Current, each commit | Read with its strip and regions | -|---|---:|---:| -| H200 | 4.5 ms against 2,719 ms | 18.7 ms against 12,936 ms | -| MI325X | 3.9 ms against 1,218 ms | 14.1 ms against 6,205 ms | +Real cubic monomials shared across output components, general-modal tail transforms planned +over active rows only and serial transforms seeded with measured wisdom: in ten-step +profiles on an 18-core arm64 laptop (recorded by 2026-10-23; model not recorded) the general +route's tensor work fell from 0.44 to 0.15 s and its FFTs from 1.00 to 0.84 s. Measured +planning adds about 18 ms (general modal) and 120 ms (reduced comb-to-continuum) of +construction. -**On an AMD EPYC 7763,** 16 cores of an exclusive two-socket node, `SOLPROP_FFTW_PLAN=measure`, `--threading passive`, at `ccd701d5` against 0.1.0, interleaved over three rounds. Both arms used this branch's harness, with the local change [described below](#the-transverse-edge-against-010) giving 0.1.0 the same grids. Every row took the same steps. Medians of the per-round pairs: +### General-route symmetric contraction -| Row | Threads | 0.1.0 (s) | This branch (s) | Ratio | Range | Final field | -|---|---:|---:|---:|---:|---:|---:| -| `kerr_beam_192` | 1 | 12.05 | 12.75 | 1.059 | 1.052–1.067 | 1.8e-7 | -| `kerr_beam_192` | 16 | 3.19 | 2.88 | 0.902 | 0.899–0.911 | 1.8e-7 | -| `kerr_beam_384` | 1 | 100.53 | 108.60 | 1.080 | 1.080–1.081 | 1.2e-15 | -| `kerr_beam_384` | 16 | 25.35 | 23.79 | 0.941 | 0.938–0.943 | 1.2e-15 | - -The aim was under x1.08, from x1.07 to x1.18. Three rows meet it, and `kerr_beam_384` at one thread doesn't quite, at x1.0803, which the maintainer accepted. That's the row the removal of `READ_RESOLUTION` was expected to cost, and it was x1.067 with it, though these runs don't separate that from the branch's other changes. `kerr_beam_192`'s 1.8e-7 is SEP 40's safety ramp, which 0.1.0 doesn't have: at 16 threads, with `spatial_absorber=False`, this branch's final field is within 5.4e-16 of 0.1.0's, and with the ramp on it reproduces the 1.8e-7. - -**What a run holds.** After three runs at 768 x 768 x 600 the ledger totals 38.96 GiB on the H200 and 39.64 GiB on the MI325X, for a state of 5.27 GiB. FFT plans are the largest row, 21.09 GiB and 22.02 GiB. The state, the register and the scratch are 5.27 GiB each, and the ring 1.5 GiB and 1.25 GiB. Each plan's own work area is why ([#529](https://github.com/LupoLab/solprop/issues/529)). - -**What a march costs in Python** ([#110](https://github.com/LupoLab/solprop/issues/110)), the wall time outside native calls, on the same harness, 600 fixed calls at most: - -| Route, grid, march | H200 | MI325X | -|---|---:|---:| -| Cartesian 32, 64, 128, 256, low-storage | 26, 21, 6.8, 1.2 % | 13, 8.4, 4.0, 0.7 % | -| Cartesian 32, 64, 128, Runge-Kutta | 21, 13, 4.8 % | 13, 7.9, 2.1 % | -| Radial 64, 256, Runge-Kutta | 17, 11 % | 10, 2.4 % | -| Cartesian 64, radial 64, native Adams | 0.6, 1.1 % | 0.6, 0.6 % | - -**A lockstep batch's observation** ([#299](https://github.com/LupoLab/solprop/issues/299)), `Batch(8)` of a fibre on native, 8 steps a plane: with a member's field an observation took 5.2 to 6.6 ms of a plane interval of 23 to 28 ms on the H200, 22 to 23 %, and 2.6 to 2.8 ms of 13 to 18 ms on the MI325X, 13 to 16 %, for `n_omega` from 768 to 32,768. On the CPU it was 1 to 4 %. A plane no one reads now takes 0.23 ms on the H200, about 1 %, and its interval falls to 18 to 21 ms. The statistics at each plane, 0.8 to 2.1 ms, are unchanged. - -**A scan worker's backend** ([#298](https://github.com/LupoLab/solprop/issues/298)), in a warm process on the H200, default check, the median of 3: - -| | Build the simulation | Translate | Point, new backend | Point, kept | -|---|---:|---:|---:|---:| -| 768 x 768 x 600, 8 steps, 4 planes | 4.80 s | 3.68 s | 4.69 s | 2.59 s | -| 384 x 384 x 600, 51 steps, 17 planes | 1.39 s | 0.93 s | 4.24 s | 3.26 s | - -So a `Local` scan on a device now keeps the backend while each point is the last but for its input, which is what `Simulation.with_input` gives. On those two windows that saves 45 % and 23 % of a point's own time, and a builder that shares its base skips the first two columns too. A whole scan has only been timed on an NVIDIA A40, whose binary64 step is slow beside what it saves: 5 points through `with_input`, default check, 8 steps, two rounds of each, 37.3 s to 32.7 s at 384 x 384 x 600, x0.88, and 153.9 s to 141.7 s at 768 x 768 x 600, x0.92. - -**The transverse size** ([#529](https://github.com/LupoLab/solprop/issues/529)). Each plan takes a work area, one state's each for the rank-3 pair and, at some sizes only, for the rank-2 pair. So the plans hold two or four states, and the point's memory and its seconds per GiB depend on the size. On the H200, 8 steps, check off: - -| N x N x 600 | State, GiB | Plans, GiB | Total, GiB | Point, s | Seconds per GiB of state | -|---:|---:|---:|---:|---:|---:| -| 720 | 4.64 | 18.56 | 34.49 | 1.905 | 0.411 | -| 750 | 5.03 | 10.06 | 27.18 | 1.774 | 0.353 | -| 768 | 5.27 | 21.09 | 38.96 | 1.987 | 0.377 | -| 800 | 5.72 | 11.45 | 30.67 | 2.078 | 0.363 | -| 864 | 6.67 | 26.70 | 48.80 | 2.515 | 0.377 | -| 900 | 7.24 | 14.48 | 38.30 | 2.373 | 0.328 | - -**One work area.** A device's plans of the scratch now share one, as cuFFT's guide allows for plans launched one after another, so the table's Plans column is what each size held before. On an NVIDIA A40, CUDA 12.8.1, 8 steps, check off, two interleaved rounds of three runs each, against the commit before: - -| N x N x 600 | Plans, GiB | Total, GiB | Point, s | -|---:|---:|---:|---:| -| 384 | 2.64 to 1.32 | 8.04 to 6.73 | 4.84, 4.94 to 4.86, 4.79 | -| 750 | 10.06 to 5.03 | 26.68 to 21.66 | 20.24, 20.19 to 20.28, 20.10 | -| 768 | 21.09 to 5.28 | 38.46 to 22.64 | 21.37, 21.41 to 21.37, 21.46 | -| 900 | 14.48 to 7.24 | 37.80 to 30.56 | 28.74, 28.61 to 28.64, 28.50 | - -`python -m benchmarks ab --device --length 0.3`, 3 rounds, the same steps and final fields with no difference: `kerr_beam_384` x0.994 (0.984–1.048), `kerr_beam_192` x1.030 (1.001–1.035, a window of two steps). So a size no longer costs more memory for its rank-2 pair, and 768 x 768 x 600 now holds less than 900 x 900 x 600. The size still sets the seconds per GiB. - -rocFFT's plans share it as well. On an AMD Instinct MI300X (ROCm 10.0.0, `gfx942`) at `c0bd23f2`, 8 steps, check off, the plans grow by 1.35, 5.07, 5.76 and 7.28 GiB at 384, 750, 768 and 900 x 900 x 600, and a run holds 7.01, 21.95, 23.37 and 30.85 GiB. Asked of rocFFT directly, in place, Z2Z, a rank-3 plan with the frequency innermost (rocFFT lengths `{T, N, N}`, which rocFFT lists innermost first) has a work area of one state at every N from 320 to 1200 and every T from 512 to 1024. With x innermost, an AMD Instinct MI325X's plans need one state too, at N = 384, 750, 768, 800 and 900 with T = 600. A rank-2 plan batched over T takes one state at 192 and 384, none at 256 and 512, and 1.10, 1.08 and 1.06 states at 640, 768 and 1024. A rank-1 plan takes none. So at 768 x 768 x 600 four areas of their own would hold 22.0 GiB, as the MI325X's 22.02 GiB at `9a5d2346` did, and the shared one holds the largest of them. - -### The transverse edge against 0.1.0 - -[#453](https://github.com/LupoLab/solprop/issues/453) found the tracking set's `kerr_beam` -rows slower than at 0.1.0, and `ctc`'s construction three times longer. These runs compare -0.1.0 with `main` at `00d83454` and with the changes this section describes. - -The setup: `python -m benchmarks ab` on 16 cores of one NUMA domain of an exclusively -allocated two-socket AMD EPYC 7763, `SOLPROP_FFTW_PLAN=measure`, with `main`'s harness on -both arms. A small local change to `benchmarks/builders.py`, not merged, gave 0.1.0 the same -grids, because it calls `collar_fraction` `window_factor`. The builds are GCC 16.2 from -source for every 0.1.0 and fix comparison; the first sweep used the published 0.1.0 wheel -and CI's wheel, and agrees with them on the Kerr rows. Every row took the same steps in -both arms and no sample was taken on a busy machine. - -**`ctc`'s construction is not a regression.** Both wheels take about 5.5 s without the -planning flag and about 15.5 s with `SOLPROP_FFTW_PLAN=measure`, `construction_s` including -the backend's construction, where FFTW plans. The 15.01 s #453 compared had the flag, and the -5.21 s row in the history is close to a run without it, so the two differ in planning, not -in code. In the first sweep, with the flag on both arms, the -`ctc` window's ratio is 1.010. Limiting host BLAS during construction -([#382](https://github.com/LupoLab/solprop/issues/382)) is not the cause: -`SOLPROP_BLAS_THREADS=16` made no improvement. `--append-history` now refuses -`SOLPROP_FFTW_PLAN`, so the history's rows stay comparable. - -**The Kerr rows' cost is the transverse edge, with a smaller part from the split collar's -occupancy.** With the monitor off, a Kerr run takes the same time in both arms, so the -kernels are unchanged. Two first-parent boundaries account for the rise, with threads -bound (`--threading passive-bound`, below): SEP 40 (`05ee1f32` to `39ee3335`) is ×1.110 -on `kerr_beam_192` at one thread and ×1.406 on `kerr_beam_384` at 16; -[#439](https://github.com/LupoLab/solprop/issues/439) (`6083d63a` to `3e13360e`) is ×1.060 -and ×1.015. - -Two changes reduce it, neither moving a field by more than rounding: - -- **A read leaves out what cannot reach its resolution** (`READ_RESOLUTION`, - `transverse_monitor.py`; removed by [SEP 44](seps/archive/sep-0044-native-edge-read.md), since a - read on the state's own memory has no copy to save). Each read synthesised every frequency plane, and a run's light - occupies from a fifth to a third of them at this level on the filaments and Kerr beams. - A read now leaves out the planes whose energy together is at most 1e-3 of the warning. By - Parseval a plane cannot put more on a face than it holds, so a face's share reads low by - at most 1e-9 of the launch energy at the default budget, against a warning at 1e-6. -- **The occupancy takes its host scatter per row.** `scatter.access()` finds its thread's - copy, and it dominated the loop when taken per element. - -Complete runs, passive unbound threads as the history uses, three rounds, medians of the -per-round pairs with the fix's range. Each ratio is from its own comparison; the 0.1.0 times -shown are from the comparison with `main`, and the fix's comparison's were within 1 % of them. - -| row | threads | 0.1.0 (s) | `main` (s) | fix (s) | `main` / 0.1.0 | fix / 0.1.0 | range | -|---|---:|---:|---:|---:|---:|---:|---:| -| `kerr_beam_192` | 1 | 12.05 | 14.24 | 13.02 | 1.182 | 1.080 | 1.078–1.090 | -| `kerr_beam_192` | 16 | 3.17 | 3.75 | 3.75 | 1.185 | 1.184 | 1.179–1.184 | -| `kerr_beam_384` | 1 | 101.13 | 117.06 | 106.48 | 1.157 | 1.067 | 1.060–1.067 | -| `kerr_beam_384` | 16 | 25.33 | 29.91 | 28.83 | 1.180 | 1.136 | 1.129–1.140 | - -Against `main`, the free-space set with threads bound, three rounds, same steps, final fields -equal to 2e-15 or better except the Cartesian filament's 8e-13 at 16 threads. Complete runs -unless stated: - -| case | threads | `main` (s) | fix (s) | fix / `main` | range | -|---|---:|---:|---:|---:|---:| -| `kerr_beam_192` | 1 | 14.13 | 12.99 | 0.918 | 0.917–0.919 | -| `kerr_beam_192` | 16 | 4.56 | 3.95 | 0.871 | 0.868–0.980 | -| `kerr_beam_384` | 1 | 117.18 | 106.81 | 0.911 | 0.905–0.915 | -| `kerr_beam_384` | 16 | 35.77 | 29.73 | 0.831 | 0.830–0.832 | -| `radial_filament_256` | 1 | 6.85 | 6.78 | 0.990 | 0.979–0.992 | -| `radial_filament_256` | 16 | 1.88 | 1.89 | 1.003 | 0.992–1.007 | -| `line` | 1 | 0.905 | 0.889 | 0.982 | 0.978–1.000 | -| `line` | 16 | 0.275 | 0.267 | 0.980 | 0.962–0.987 | -| `planar` | 1 | 0.450 | 0.436 | 0.969 | 0.960–0.983 | -| `planar` | 16 | 0.148 | 0.149 | 1.012 | 1.006–1.047 | -| `cartesian_filament_128`, half length | 1 | 346.2 | 342.4 | 0.990 | 0.976–0.992 | -| `cartesian_filament_128`, half length | 16 | 97.3 | 96.3 | 0.990 | 0.986–0.995 | - -Bound threads overstate the transverse edge. SciPy's transforms take a bound main thread's -single core (0.48 s with 16 workers against 0.11 s unbound, on a 384² × 256 array), so -`main`'s `kerr_beam_384` at 16 threads is ×1.425 against 0.1.0 when bound and ×1.180 unbound. -#453 measured ×1.152 unbound, from runs on different days. - -**What remains, proposed as an accepted cost.** Each of these is a known part of the -default's work, and reducing it further means moving work rather than removing it: - -- **`kerr_beam_192` at 16 threads does not improve.** The monitor takes 0.77 s of 3.70 s - against 0.20 s of 3.13 s at 0.1.0. Of the 0.57 s more, five reads are 0.31 s, of which the - plane scan is 0.21 s, about what the left-out planes save at this width; six more host - copies of the state are 0.12 s; the other 0.14 s, which includes the launch's transform, was - not broken down. Reducing the faces and the plane energies in native would remove most of - this, which is the seam change in [#396](https://github.com/LupoLab/solprop/issues/396). -- **These rows read at every step.** A four-step run reads five times, its launch and each - step, because `L/16` is shorter than a step. `radial_filament_256` took 19 reads over - 127 steps in #396. How far the share falls on a longer Kerr run has not been measured. -- **Construction.** `kerr_beam_192` goes from 1.63 s to 1.95 s and `kerr_beam_384` from - 11.25 s to 13.52 s, one-off work per translation. At 384² the launch's occupancy is about - 1.0 s, the walk-off buckets 0.6 s and the edge's design 0.7 s. -- **Memory.** Peak resident memory rises by about 1 %: 2.51 to 2.54 GiB and 15.60 to - 15.81 GiB. -- **`radial_filament_256`, 3 to 5 % against 0.1.0.** Five rounds, one and 16 threads: - -| boundary | t1 | t16 | -|---|---:|---:| -| 0.1.0 to SEP 40's parent | 0.992 | 0.997 | -| SEP 40 | 1.016 | 1.035 | -| SEP 40 to #439's parent | 1.002 | 1.002 | -| #439 | 1.028 | 1.016 | -| #439 to `main` | 1.003 | 1.006 | -| `main` to the fix | 0.990 | 1.003 | -| 0.1.0 to the fix | 1.030 (1.018–1.035) | 1.048 (1.019–1.070) | - -SEP 40 moves the final field by 1.2e-7 through its ramp. #439 takes no step more and leaves -the field exact; its accepted steps now form five sums instead of one, so that the guards -are judged on the symmetric splitting's state. That the sums are its whole cost is read -from the code, not profiled. - -**The rest of the tracking set.** The 22 configurations, a quarter of each guide from the -entrance, three rounds, 0.1.0 against the fix, threads bound: geometric mean 1.021. Apart from -the Kerr and radial rows, the largest are `argon_blueshift_envelope` at 16 threads at 1.025 -(0.12 s; 1.006 and 1.010 for a complete run on `main`) and `grin_nonlinear` at 1.017, whose -range (0.999–1.020) overlaps its A/A control's (0.979–1.015). The windows say nothing about -what a run does past them. `rdw` at 16 threads, 1.048 in the first such window, was 1.001 at -full length. +The real cubic over its ten symmetric monomials instead of 81 + 3 dense products +([algorithms.md](algorithms.md)): a two-channel step-index window 1.35 times faster at one +thread (recorded by 2026-10-23; machine not recorded), less with more channels. -### Host vector maths +### Separable stage propagators as vector maths -The native CPU kernels' transcendentals in vector passes (ADR-059) against the parent -revision, complete runs of the tracking cases from the entrance (the fraction of the -guide in brackets where it is not the whole), the default stepper and `RungeKutta()`, -three rounds of interleaved fresh processes, medians with their median absolute -deviations. Every arm took the same steps; final fields differ from the parent's by -4e-15 to 6e-11 relative, the run-to-run spread of FFTW's measured plans (a candidate -with this change's arithmetic on the libm route differs as much). - -**Two-socket AMD EPYC 7763** (Zen 3, AVX2; 16 cores of a shared node, glibc 2.34, GCC -16.2, FFTW 3.3.11, OpenBLAS 0.3.34, Kokkos 5.2.1 OpenMP, a local build, so SLEEF's AVX2 -functions), one thread, this change's final revision, two rounds: - -| case | stepper | before (s) | vector maths | -|---|---|---:|---:| -| `gnlse_raman_shock` (0.3) | RK | 18.84 ± 0.02 | −19.4 % | -| `argon_blueshift_averaged` | RK | 2.947 ± 0.015 | −17.2 % | -| `argon_blueshift_averaged` | default | 8.235 ± 0.003 | −6.2 % | -| `he_rdw_averaged` | RK | 1.365 ± 0.003 | −12.4 % | -| `he_rdw_averaged` | default | 2.338 ± 0.009 | −10.5 % | -| `h2_raman_averaged` (0.5) | RK | 2.866 ± 0.002 | −10.1 % | -| `rdw` (0.3) | RK | 7.679 ± 0.012 | −14.4 % | -| `rdw` (0.3) | default | 5.313 ± 0.012 | −11.4 % | -| `radial_filament_256` (0.3) | RK | 8.915 ± 0.010 | −7.8 % | -| `radial_filament_256` (0.3) | default | 6.261 ± 0.025 | −5.9 % | -| `argon_blueshift_envelope` | RK | 1.665 ± 0.006 | −5.7 % | -| geometric mean | | | **−11.1 %** (conservative 0.896) | - -An earlier revision, three rounds, with a third arm built with -`SOLPROP_NATIVE_VECTOR_MATH=SCALAR` (this change's arithmetic on the libm route, an -A/A-like control): that arm's geometric mean was +0.7 % and its cases −1.2 to +2.2 %. - -The free-space routes, the same machine and protocol, one thread, with the low-storage -flows and the split factor: `spatial_absorber` (0.5) −12.2 %, `radial_filament_256` -(0.3) RK −5.3 % and default −1.8 %, `planar` (0.5) −1.5 %, `line` (0.5) −1.1 %, -`kerr_beam_192` (0.5) −0.9 % (inside its spread); geometric mean −3.9 %. Sixteen-thread -runs on that node, which other jobs shared, scattered by more than the effect (one -case's arms spread by 30 %), and are not reported. - -**AMD EPYC 9B45** (Zen 5, AVX-512; a cloud instance of 16 cores without SMT, glibc -2.39, GCC 14.2, Ubuntu's FFTW 3.3.10 and OpenMP OpenBLAS 0.3.26), local builds at -`-march=native`; the AVX2 rows with `-mno-avx512f` too, so the AVX2 base is the -reference. One thread, three rounds: - -| case | stepper | before, AVX2 (s) | vector maths, AVX2 | AVX-512F (opt-in) | -|---|---|---:|---:|---:| -| `gnlse_raman_shock` (0.3) | RK | 10.42 ± 0.03 | −21.3 % | −29.2 % | -| `argon_blueshift_averaged` | RK | 1.581 ± 0.003 | −10.9 % | −15.8 % | -| `argon_blueshift_averaged` | default | 4.424 ± 0.004 | −6.2 % | −13.1 % | -| `he_rdw_averaged` | RK | 0.765 ± 0.011 | −6.2 % | −8.7 % | -| `he_rdw_averaged` | default | 1.295 ± 0.014 | −10.8 % | −18.1 % | -| `h2_raman_averaged` (0.5) | RK | 1.546 ± 0.003 | −10.3 % | −14.7 % | -| `rdw` (0.3) | RK | 3.873 ± 0.012 | +4.9 % | +2.2 % | -| `rdw` (0.3) | default | 3.123 ± 0.001 | −2.5 % | −6.6 % | -| `radial_filament_256` (0.3) | RK | 5.026 ± 0.012 | −4.3 % | −6.1 % | -| `kerr_beam_192` (0.5) | default | 5.071 ± 0.036 | +2.0 % | +0.5 % | -| geometric mean | | | **−6.8 %** (conservative 0.945) | −11.4 % (0.900) | - -The AVX-512 base was itself 2.0 % faster than the AVX2 base, so AVX-512F's functions -save 9.8 % against it. At sixteen threads, the AVX2 builds, two rounds, six cases: -geometric mean −5.3 % (conservative 0.983), `argon_blueshift_averaged` −10.9 % (RK) and -−11.3 % (default), `he_rdw_averaged` −6.9 % (RK) and −1.5 % (default), `rdw` −0.9 % -(RK) and +0.2 % (default). **An Intel Xeon of the Ice Lake generation** (a cloud instance of -16 cores without SMT, the same software), one to two rounds and noisier: the AVX2 -functions −3.7 %, the AVX-512F functions +2.9 % (`he_rdw_averaged` with RK +21 %, -`rdw` with RK +12 %). The AVX2 functions are therefore the default, AVX-512F an opt-in. - -`rdw` with RK lost 3 to 5 % on both cloud machines, against a 7 % gain on the EPYC -7763, whose glibc (2.34) is older and slower. The label timer put it in the band plasma -column (1.92 s → 2.21 s), whose block passes staged every sample's magnitude, rate and -fraction: most of the pulse's samples lie outside the rate table and cost about a -nanosecond each, as much as the staging. Writing the rows as the classifying loop goes -and gathering only the live samples for the vector calls took the Zen 5 machine's -`rdw` with RK to −4.7 % (from +4.4 %), `argon_blueshift_averaged` to −14.1 % (RK) and -−6.8 % (default) and `he_rdw_averaged` with RK to −11.4 %, three rounds; the tables -above predate that change. - -**Apple M5 Max**, a machine in ordinary use (labelled A/B), one thread: this change's -default (the system libm, each element's own calls) against the parent, geometric mean -+0.4 % over eight of the cases above, every case within its spread; SLEEF's AdvSIMD -functions forced on (`SOLPROP_NATIVE_VECTOR_MATH=SLEEF`) +11.6 %, `gnlse_raman_shock` -+56 %. - -### Exponential Adams host cost: the SEP 39 baseline - -The host side of an exponential `Multistep()` trial on the native CPU backend, before -[SEP 39](seps/archive/sep-0039-native-adams-march.md)'s native march, at the head of the vector -maths change (a500d2d). The SEP's §3.3 reads these figures. - -**Method.** - -- Complete runs of the tracking cases, with the fraction of the guide in brackets - where it is not the whole, timed by the suite's worker after its warm-up. -- The default stepper and `RungeKutta()` interleaved over three rounds of fresh - processes, the order reversed every round; medians reported. -- Host time per trial: `python -m benchmarks.adams_host CASE [--length F]` (SEP 39; removed by SEP 52), - the march's wall time less its native `adams_*` calls, with no other wrappers. -- The per-piece split comes from one run with `perf_counter` wrappers on about - twenty-five host functions, which inflate the total by about half, so it gives the - shares, not the sum. -- Steps and calls are counted. - -**AMD EPYC 7763** (Zen 3, 16 cores of one NUMA domain of a shared node, GCC 16.2, -SLEEF's AVX2 functions, FFTW 3.3.11, OpenBLAS 0.3.34), one thread: - -| case | `Multistep()` (s) | `RungeKutta()` (s) | host / native per trial (µs) | steps (acc/rej), calls: MS · RK | -|---|---:|---:|---:|---| -| `he_rdw_averaged` | 2.126 | 1.528 | 212 / 1 182 | 1 434/3, 1 438 · 480/1, 2 887 | -| `argon_blueshift_averaged` | 9.17 (7.83–9.47) | 2.460 | 177 / 632 | 11 166/2, 11 169 · 1 684/0, 10 105 | -| `h2_raman_averaged` (0.4) | 4.820 | 2.146 | 173 / 695 | 5 417/2, 5 420 · 1 308/0, 7 849 | -| `rdw` (0.25) | 4.157 | 5.440 | 372 / 9 245 | 393/1, 395 · 175/0, 1 051 | - -The node's sixteen-thread runs, which other jobs shared, were slower than one thread on -several cases and are not reported. - -**Apple M5 Max** (Homebrew Clang 23.1.3, FFTW 3.3.11 with NEON codelets, the system -libm, an otherwise idle machine): - -| case | threads | `Multistep()` (s) | `RungeKutta()` (s) | host / native per trial (µs) | -|---|---:|---:|---:|---:| -| `he_rdw_averaged` | 1 | 0.815 | 0.650 | 51 / 448 | -| `argon_blueshift_averaged` | 1 | 2.920 | 1.419 | 38 / 213 | -| `h2_raman_averaged` (0.4) | 1 | 1.755 | 1.311 | 40 / 263 | -| `rdw` (0.25) | 1 | 1.711 | 2.736 | 129 / 3 730 | -| `he_rdw_averaged` | 16 | 0.636 | 0.650 | 53 / 282 | -| `argon_blueshift_averaged` | 16 | 2.474 | 1.381 | 36 / 175 | -| `h2_raman_averaged` (0.4) | 16 | 1.697 | 1.652 | 44 / 254 | -| `rdw` (0.25) | 16 | 0.862 | 1.256 | 205 / 1 555 | - -The step and call counts are the EPYC's on both machines. - -**Host pieces, helium, one thread** (µs per trial, instrumented): - -| piece | EPYC 7763 | M5 Max | -|---|---:|---:| -| stage arrays (bundle, packing, sample) | 113 | 21 | -| … of which the bundle's Clenshaw reads | 73 | 14 | -| the decision, less the native accept | 48 | 7 | -| rate weights (uncached Clenshaw) | 26 | 4 | -| landing and approach | 30 | 5 | -| the tables call (one native helper) | 18 | 4 | -| order choice and stencil | 17 | 3 | -| sample, hoist, record and the rest | 22 | 4 | - -On the four-mode `rdw` the step history's record costs 67 µs a trial on the EPYC: its -backend hook scores the quadrature alarm natively. - -**Native time per trial** (µs, host-only Kokkos label timer, one thread): - -| case | machine | predict pass | correct pass | the source and the rest | -|---|---|---:|---:|---:| -| `he_rdw_averaged` | EPYC 7763 | 557 | 287 | ≈290 | -| `argon_blueshift_averaged` | EPYC 7763 | 192 | 112 | ≈200 | -| `he_rdw_averaged` | M5 Max | 169 | 100 | ≈155 | -| `argon_blueshift_averaged` | M5 Max | 51 | 34 | ≈110 | - -On the EPYC the two passes cost 1.5–2.9 source evaluations a trial, against 0.6–0.9 for -the host. Their per-element cost is 2.9–3.8 times the M5's, against about 1.9 times for -the source. - -### The native Adams march - -[SEP 39](seps/archive/sep-0039-native-adams-march.md)'s native march against solprop's Python -march on the same build (`benchmarks.adams_host --host-march`), and against the march -with the host packing the stage rows, as before the SEP's phase 1 (`--host-stages`). -Interleaved fresh processes, the arm order reversed every round, medians; every arm -took the same steps and calls (the counts above). Host time per trial as in the -baseline above. - -**Exponential formulation** (the default `Multistep()`): - -| machine, threads | case | host µs/trial: packed → staged → native | wall, native vs staged | wall, native vs packed | -|---|---|---|---:|---:| -| M5 Max, 1 | `he_rdw_averaged` | 43 → 13 → 0.6 | −3.3 % | −7.6 % | -| | `argon_blueshift_averaged` | 30 → 11 → 0.4 | −6.0 % | −13.6 % | -| | `h2_raman_averaged` (0.4) | 37 → 11 → 0.5 | −3.9 % | −11.6 % | -| | `rdw` (0.25) | 91 → 47 → 2.7 | −0.6 % | +0.4 % | -| M5 Max, 16 | `he_rdw_averaged` | 47 → 13 → 0.6 | −4.2 % | −13.2 % | -| | `argon_blueshift_averaged` | 32 → 12 → 0.4 | −9.2 % | −17.2 % | -| | `h2_raman_averaged` (0.4) | 39 → 12 → 0.6 | −6.2 % | −16.2 % | -| | `rdw` (0.25) | 171 → 122 → 1.9 | −2.2 % | −4.5 % | -| EPYC 7763, 1 | `he_rdw_averaged` | 208 → 65 → 1.7 | −6.1 % | −14.0 % | -| | `argon_blueshift_averaged` | 148 → 58 → 1.1 | −11.5 % | −24.2 % | -| | `h2_raman_averaged` (0.4) | 168 → 58 → 1.2 | −9.5 % | −22.7 % | -| | `rdw` (0.25) | 168 → 8 (staged → native) | −1.7 % | — | - -The EPYC's first three rows are from a shared node (load 80–97), whose one-thread -walls were consistent; its `rdw` row is from a quiet node, nine rounds, where the -sixteen-thread median read +2.7 % and the minimum −3.3 % inside a ±6 % spread. - -**Interaction formulation** (`Multistep(formulation="interaction")`, M5 Max): - -| threads | case | host µs/trial: packed → staged → native | wall, native vs staged | wall, native vs packed | -|---|---|---|---:|---:| -| 1 | `he_rdw_averaged` | 41 → 12 → 0.5 | −4.0 % | −11.8 % | -| | `argon_blueshift_averaged` | 33 → 11 → 0.5 | −5.4 % | −16.7 % | -| | `h2_raman_averaged` (0.4) | 40 → 11 → 0.5 | −5.6 % | −18.3 % | -| | `rdw` (0.25) | 85 → 43 → 1.5 | −1.3 % | −2.9 % | -| 16 | `he_rdw_averaged` | 41 → 12 → 0.5 | −3.9 % | −12.9 % | -| | `argon_blueshift_averaged` | 33 → 11 → 0.4 | −8.6 % | −18.2 % | -| | `h2_raman_averaged` (0.4) | 42 → 11 → 0.5 | −34.1 % | −15.0 % | -| | `rdw` (0.25) | 165 → 119 → 1.5 | −2.1 % | −4.7 % | - -The staged Python march's sixteen-thread `h2_raman_averaged` (2.24 s, slower than the -packed march's 1.74 s, in every round) is unexplained; see SEP 39's phase 3 report. - -**The frequent-event cases** (SEP 39 §7.6, measured after its `Final`; #273). The native -march against the Python march, `benchmarks.adams_host` with and without `--host-march`, -on an idle AMD EPYC 7763 node (exclusive, commit `f5bd1937`, after SEP 45), five -interleaved rounds, complete runs unless a fraction is given. `--step-planes 1` stops at -every step and `--row-period 1` takes an energy row at every step, so each makes every -step a host event; `argon_blueshift_envelope`'s monitor is busy for most of the run. -Both arms took the same steps. - -| threads | case | host µs/trial: Python → native | wall, native vs Python | -|---|---|---|---:| -| 1 | `he_rdw_averaged` | 68 → 1.5 | −11.6 % | -| | `he_rdw_averaged`, `step_planes = 1` | 160 → 58 | −3.1 % | -| | `he_rdw_averaged`, `row_period = 1` | 326 → 290 | −2.9 % | -| | `argon_blueshift_envelope` (busy monitor) | 71 → 1.4 | −14.1 % | -| | `ctc` (0.2) | 209 → 18 | −1.0 % | -| 16 | `he_rdw_averaged` | 69 → 1.5 | −14.4 % | -| | `he_rdw_averaged`, `step_planes = 1` | 162 → 58 | −9.6 % | -| | `he_rdw_averaged`, `row_period = 1` | 330 → 291 | −9.5 % | -| | `argon_blueshift_envelope` (busy monitor) | 77 → 1.5 | about −30 % | -| | `ctc` (0.2) | 198 → 9 | −4.2 % | - -The one-thread walls varied by under 1 % between rounds. At sixteen threads `ctc`'s -varied by ±20 %, so its row is inside the spread. In every round the first -sixteen-thread run, `argon_blueshift_envelope` in whichever arm went first, took 3 to -3.8 s against 0.7 to 1.3 s otherwise, a cold start that reverses with the arm order; its -row compares the runs that were not first (native 0.74 and 0.95 s, Python 1.17 to -1.28 s), while the medians of all five read +27 %. No case is slower than the spread, -as SEP 39's acceptance rule requires. A statistics row at every step costs about 290 µs -a step in either march, the row itself rather than the return; a natural stop at every -step about 58 µs. - -On an 18-core Apple M5 Max (macOS, the distribution wheel's `apple-m1` baseline, main -after #577, the same five interleaved rounds and the same steps in both arms): - -| threads | case | host µs/trial: Python → native | wall, native vs Python | -|---|---|---|---:| -| 1 | `he_rdw_averaged` | 13.8 → 0.9 | −3.3 % | -| | `he_rdw_averaged`, `step_planes = 1` | 39.5 → 15.2 | −2.2 % | -| | `he_rdw_averaged`, `row_period = 1` | 85.7 → 74.8 | −1.7 % | -| | `argon_blueshift_envelope` (busy monitor) | 14.2 → 0.7 | −7.6 % | -| | `ctc` (0.2) | 65.0 → 7.2 | −0.8 % | -| 16 | `he_rdw_averaged` | 14.2 → 0.9 | −4.6 % | -| | `he_rdw_averaged`, `step_planes = 1` | 40.4 → 15.4 | −2.6 % | -| | `he_rdw_averaged`, `row_period = 1` | 87.8 → 75.8 | −3.9 % | -| | `argon_blueshift_envelope` (busy monitor) | 15.7 → 0.7 | −7.7 % | -| | `ctc` (0.2) | 140.3 → 3.4 | −1.6 % | - -The native march was faster in 47 of the 50 paired rounds and within 0.4 % in the other -three; walls varied by 1 to 7 % between rounds, and no first run stood out. Python's -march takes about a fifth as much host time a trial here as on the EPYC, so the gains are -smaller in proportion. As there, a statistics row at every step costs about the same in -either march (about 75 µs a step), and a natural stop about 15 µs. - -**On an NVIDIA A40** (CUDA 12.8.1; exponential formulation, short windows; the same -steps in both arms): host time per trial 64 → 2.2 µs (`he_rdw_averaged`, 0.3), 61 → 1.6 -(`argon_blueshift_averaged`, 0.1) and 83 → 5.0 (`rdw`, 0.1), walls −6.7 %, −10.6 % and -−1.8 %. A trial costs about a millisecond on this FP64-weak device. - -**On an AMD Instinct MI325X** (HIP 7.14 prerelease, `AMD_GFX942`; the same build, -`--host-march` against the native march, five rounds, the same steps): host time per trial -21.7 → 1.5 µs (`he_rdw_averaged`, 0.3), 17.3 → 0.8 (`argon_blueshift_averaged`, 0.1), 40.5 → -3.0 (`rdw`, 0.1), 14.9 → 0.5 (`h2_raman_averaged`, 0.4) and 30.2 → 2.9 -(`radial_filament_256`, 0.1); walls (`ab --device`, three rounds) −2.9 %, −3.4 %, −2.0 %, -−3.0 % and −0.8 %, fields bitwise equal. A trial there is 160 to 550 µs of device time in 25 -to 70 kernels, most of it launch-bound -([device launches on an MI325X](#device-launches-and-the-adams-passes-on-an-amd-instinct-mi325x)). -**On an NVIDIA H200** (CUDA 13.1, `HOPPER90`, three rounds, the same steps): 49 → 2.2 µs -(`he_rdw_averaged`), 44 → 1.2 (`argon_blueshift_averaged`), 70 → 5.2 (`rdw`), 41 → 0.8 -(`h2_raman_averaged`) and 65 → 4.7 (`radial_filament_256`, 0.1); walls −15 %, −21 %, −4 %, -−23 % and −3 %. - - -### A native Adams call's return and the stop flag - -A native call returns at a host event or at its bound, 256 attempts or 0.1 s -([SEP 39](seps/archive/sep-0039-native-adams-march.md), Q3), and a run's stop flag is polled -before each call ([#519](https://github.com/LupoLab/solprop/issues/519)). That adds no -return, only a Python call: 56 ns with no flag and 82 ns with a `threading.Event` -(`timeit`). Everything here is on an Intel Xeon Gold 6240 pinned to CPUs of one socket on a -shared machine, load average 4 to 16, GCC 16.2, `-march=cascadelake`, no wisdom file: read -the ratios, not the times. - -**The poll.** Interleaved pairs in one process, 21 rounds, one thread, with a -`threading.Event` as the flag, where returns are most frequent: an N = 8 soliton on 576 -bins, 1 m at `rtol = 1e-8`, whose busy monitor returns at 4780 of its 4783 attempts, 0.90 s. - -| | median | range | -|---|---:|---:| -| poll / no poll | 1.0027 | 0.983–1.058 | -| no poll / no poll | 1.0010 | 0.990–1.020 | - -The difference is inside the control's range; 4780 polls at 82 ns are 0.04 % of the run. - -**Against the parent.** `benchmarks ab`, `--stepper multistep`, `--length 0.2`, nine logical -CPUs, 3 rounds, the same steps and fields to rounding (at most 1.3e-13), median ratio and -range, with an A/A control of the parent against itself: - -| threads | case | candidate / parent | A/A | -|---|---|---:|---:| -| 1 | `gnlse_soliton` | 0.997 [0.957, 1.031] | 1.022 [0.993, 1.025] | -| | `he_rdw_averaged` | 1.025 [0.951, 1.087] | 0.994 [0.887, 1.098] | -| | `argon_blueshift_averaged` | 0.992 [0.817, 1.004] | 1.006 [0.889, 1.011] | -| | `rdw_one_mode` | 1.116 [0.981, 1.355] | 0.995 [0.978, 1.059] | -| 8 | `gnlse_soliton` | 0.990 [0.930, 1.125] | 1.052 [0.885, 1.089] | -| | `he_rdw_averaged` | 1.060 [0.998, 1.263] | 0.982 [0.818, 1.018] | -| | `argon_blueshift_averaged` | 1.025 [1.021, 1.033] | 1.029 [0.995, 1.087] | -| | `rdw_one_mode` | 0.995 [0.869, 1.315] | 1.032 [1.008, 1.065] | -| | geometric mean | 1.024 | 1.014 | - -This machine could not resolve the change. Five rounds of the two highest rows read 0.966 -[0.732, 1.019] (`rdw_one_mode`, 1 thread) and 0.982 [0.820, 1.149] (`he_rdw_averaged`, 8 -threads). - -**What a return costs**, as it has since SEP 39: this change makes none of them. One plane -and no boundary monitor, so nothing but the bound returns the march; a bound of none, the -production bound and a bound of one attempt interleaved in one process, medians of 3 to 5 -rounds of the run's wall time, setup included. One return is the excess of the bound of one -over none, per return: - -| case, threads | bins | attempts | wall, no bound | returns at the bound | one return | their share | -|---|---:|---:|---:|---:|---:|---:| -| N = 2 soliton, 0.3 m, 1 | 512 | 946 | 0.085 s | 4 | 44 µs | 0.21 % | -| N = 8 soliton, 0.1 m, 1 | 576 | 974 | 0.105 s | 4 | 47 µs | 0.18 % | -| the same, interaction form, 1 | 576 | 2046 | 0.186 s | 8 | 29 µs | 0.13 % | -| `gnlse_soliton` (0.3), 1 | 3072 | 285 | 0.143 s | 2 | 63 µs | 0.09 % | -| `he_rdw_averaged` (0.3), 1 | 2561 | 483 | 0.464 s | 4 | 62 µs | 0.05 % | -| `he_rdw_averaged` (0.3), 8 | 2561 | 483 | 0.291 s | 3 | 91 µs | 0.09 % | - -The share is read from the return's cost: comparing the production bound with none directly -reads −2.7 to +1.8 %, which is noise. Where 256 attempts take less than 0.1 s the share -grows as an attempt gets cheaper, and it is above 0.1 % on the two smallest grids here. -### The Adams passes on x86-64 lanes +Free space's separable propagators through one `vmath::sincos` pass per 32 × 16 tile instead +of a libm call per element (18 % of `line`): `line` 0.893 at one thread and 0.927 at 16 on +an Intel Xeon Gold 6240 (2026-11-08). -The exponential Adams trial's predict and correct passes on a host block of 32 elements -held as lanes (`include/solprop_native/march/adams_phi.hpp`, `adams_lanes_*` in -`src/general/trial.cpp`) against the element-by-element form, at 740b24d. Before the change -the passes ran each element through latency-bound scalar strict code (the -phi-functions' series, Horner pass and squarings, the compensation and the defects), -GCC calling every strict helper out of line from the contracting kernels; per element -they cost 2.9–3.8 times the Apple M5 Max's on the AMD EPYC 7763 (§ "Exponential Adams -host cost" above). Now every lane loop vectorises on x86-64-v3, Zen 3 and Cascade Lake -(checked with GCC 16.2's vectoriser report): the selections are bitwise, the -comparisons quiet, and the corrector's endpoint rate is formed beside the step's -phase, in one pass over the operator's terms. The strict parts keep each element's -operations and their rounding (a native test holds the lanes' phi-functions to -`adams_phi`'s bits); the predictor's and corrector's sums may contract differently, so -the first step whose inputs differ differs by about 2e-16 in its norm. Every case -below took the same steps and trials in both arms; final fields differ by 2e-15 to -5e-12 relative (`he_rdw_averaged` at 0.3 of its length: 4.6e-12, the step sizes -apart by up to 5e-5 relative after the pulse's compression amplifies the rounding). - -**AMD EPYC 7763** (16 cores of a shared node, GCC 16.2, SLEEF's AVX2 functions, -OpenMP OpenBLAS), one thread, three interleaved rounds, medians; the passes in µs per -call (host-only Kokkos label timer), the wall of the timed window: - -| case (fraction) | predict | correct | wall | -|---|---:|---:|---:| -| `he_rdw_averaged` (0.3) | 562 → 273 | 293 → 109 | −32 % | -| `argon_blueshift_averaged` (0.1) | 190 → 82 | 112 → 45 | −30 % | -| `h2_raman_averaged` (0.2) | 269 → 115 | 164 → 65 | −37 % | -| `rdw` (0.1) | 2430 → 1373 | 1222 → 530 | −16 % | -| `radial_filament_256` (0.05) | 13 470 → 7 050 | 9 890 → 4 430 | −16 % | -| `argon_blueshift` (0.05) | 189 → 83 | 111 → 48 | −7 % | - -Per element the predict pass now costs about 1.6 times the M5 Max's figure of § 3.3 -of SEP 39, and the correct pass about 1.1 times. A stage clock (rdtsc around each lane -step, a profiling build) puts the rest of `he_rdw_averaged`'s predict pass at about a -third in SLEEF's six complex exponentials an element (the flow, the series argument and -four spans), a sixth in the 18-term phase and rate sum, which is memory-bound, an eighth -in the phi-functions and the rest in the history sums and stores. That node's -sixteen-thread runs scattered by more than the effect and are not reported. - -**Intel Xeon Gold 6240** (18 physical cores of one socket, the other socket in use, GCC -16.2 `-march=cascadelake`, SLEEF's AVX2 functions, OpenMP OpenBLAS), complete windows at -0.1 of each case's length, `python -m benchmarks ab` with passive bound threads, three -rounds, medians of the paired ratios (range over rounds); every pair did the same work, -final fields within 6.2e-15: - -| case | one thread | sixteen threads | -|---|---:|---:| -| `he_rdw_averaged` | 0.786 (0.779–0.809) | 0.879 (0.775–0.885) | -| `argon_blueshift_averaged` | 0.752 (0.747–0.759) | 0.946 (0.920–1.057) | -| `h2_raman_averaged` | 0.697 (0.696–0.710) | 0.936 (0.921–0.952) | -| `rdw` | 0.827 (0.816–0.829) | 0.974 (0.961–0.974) | -| `radial_filament_256` | 0.839 (0.836–0.849) | 0.937 (0.932–0.945) | -| `argon_blueshift` | 0.936 (0.934–0.963) | 0.953 (0.946–0.975) | - -The geometric mean of the twelve ratios is 0.867. At sixteen threads the single-column -passes run on four threads (the size class above), so less of the gain shows. - -SLEEF's AVX-512F functions (`SOLPROP_NATIVE_VECTOR_MATH_AVX512`, opt-in) took a further -5–8 % off these windows at one thread on a Xeon Gold 6240, and were 6 % slower on -`he_rdw_averaged` at sixteen threads (one round); they stay opt-in. - -Tried and not adopted: blocks of 16 elements (5–15 % slower on the EPYC) and of 64 -(within 2 % of 32 on single columns, 5 % faster on `rdw`). - -### Device transfers and the free-space Kerr stage - -On an NVIDIA A40 (CUDA 12.8.1, `AMPERE86`, binary64 at about a sixty-fourth of the -single-precision rate), `python -m benchmarks ab --device`, three rounds of interleaved -fresh processes, half of `kerr_beam_384` (two fixed RK4IP steps, 384² × 750): - -| change | wall, s | ratio (range) | field difference | -|---|---|---:|---:| -| one copy at a load and an observation, the free-space split on the stored columns | 4.775 → 3.878 | 0.812 (0.812–0.815) | 1.0e-15 | -| the split factor per sample, the pinned single upload | 4.686 → 3.892 (with the above) | 0.830 (0.829–0.832) | 1.0e-15 | -| the rank-3 Kerr stage | 3.913 → 3.764 | 0.963 (0.957–0.964) | 1.3e-16 | -| all, against the baseline | 4.732 → 3.747 | 0.792 (0.789–0.798) | 1.0e-15 | - -Kernel time fell from 827 to 651 ms a step: the split's transverse pair and transposes -(about 100 ms) and the chunks' pack, crop and pointwise passes (about 75 ms). An -observation of the 1.77 GB state took 0.85 s of host time through three fresh buffers. -On an Intel Xeon Gold 6240 at one thread `kerr_beam_192` (half) took 0.920 of the time -(0.917–0.922, fields to 6e-16). `radial_filament_256` is unchanged on the A40 (0.3 and 0.5 -of its length, within ±2 %): its trial, 3.3 ms of kernels, is bound by binary64 -arithmetic (the synthesis and projection GEMMs near the device's binary64 peak, the -φ-functions), so neither the single upload, the GEMM for its node chunks nor one chunk -in place of two (48 → 31 kernels a trial, not adopted) moved it. The retained-spectrum -synthesis does, by halving the synthesis's product: on the A40, half the run, three -rounds of three repeats, 0.569 → 0.512 s, ratio 0.902 (0.898–0.903), fields to 3.2e-15, -kernel time 238 → 200 ms over a 71-trial window. -The device prefactor with one reciprocal in place of two divisions took the separable -fold from 29.5 to 21.6 ms (`kerr_beam_384`, kernels 651 → 620 ms a step, wall 0.981, -0.936–0.984, fields to 2.4e-17). - -### Device launches and the Adams passes on an AMD Instinct MI325X - -On an AMD Instinct MI325X (HIP 7.14 prerelease, AMD Clang 23, `AMD_GFX942`, band staging -on), `rocprofv3 --kernel-trace` over a timed window showed the device busy for a third of -an Adams run. A single-mode trial was 30 to 70 kernels of 2 to 9 µs, launched one by one, -and between them Kokkos's constant-memory launches: a functor of 512 B to 32 kB (most of -a trial's) is copied by a blit kernel behind an event wait on the previous such launch, -4 to 10 a trial, 13 to 18 % of the kernel time. Each change below, `ab --device`, -interleaved fresh processes, three rounds, the same steps: - -| change | case | ratio (range) | field difference | -|---|---|---:|---:| -| functors under 3840 B passed as the launch argument (a light-weight hint) | `he_rdw_averaged` (0.3) | 0.900 (0.885–0.935) | 1.4e-11 | -| | `argon_blueshift_averaged` (0.1) | 0.829 (0.823–0.849) | 3.7e-15 | -| | `radial_filament_256` (0.5) | 0.938 (0.935–0.947) | 3.4e-15 | -| HIP range reductions back to 256-thread blocks with the hint | `he_rdw_averaged` | 0.944 (0.931–0.953) | 0 (against no hint) | -| predict pass's phi-functions in registers (order dispatched, one to eight) | `he_rdw_averaged` | 0.971 (0.949–0.984) | 1.0e-12 | -| correct pass's history read once into registers | `he_rdw_averaged` | 0.979 (0.973–0.995) | 1.3e-11 | -| | `radial_filament_256` | 1.000 (0.983–1.002) | 3.8e-15 | -| no fence after an accepted step on a device | `he_rdw_averaged` | 0.959 (0.955–1.005) | 0 | -| | `argon_blueshift_averaged` | 0.966 (0.900–0.971) | 0 | -| the held currents' transforms in one plan | `he_rdw_averaged` | 0.964 (0.957–0.967) | 0 | -| | `argon_blueshift` (0.1) | 0.903 (0.890–0.938) | 0 | - -The light-weight hint first took the range reductions to Kokkos's largest HIP block (1024 -threads), which put a single-mode trial's predict and correct passes on three compute -units, 40 → 56 µs; their reduction order moved the norms, hence the 1.4e-11 over 411 steps. -The predict pass held its phi-functions in scratch memory (560 B a thread) because their -loops ran to a run-time order: 38.9 → 28.8 µs a trial on `he_rdw_averaged` and 64.6 → 32.7 µs -on `radial_filament_256`. The correct pass's register copy is 31.9 → 27.5 µs on the former -and 54.2 → 57.7 µs on the latter (its registers doubled); it is kept for the small runs. -The unrolled device arithmetic contracts differently, so fields move at rounding level, -which the adaptive steps carry to the 1e-12 and 1e-11 above with the same steps. - -All of them, against the HIP build with the native march alone (five rounds; radial three -repeats): - -| case | wall, s | ratio (range) | field difference | -|---|---|---:|---:| -| `he_rdw_averaged` (0.3) | 0.196 → 0.145 | 0.744 (0.697–0.814) | 1.3e-11 | -| `argon_blueshift_averaged` (0.1) | 0.346 → 0.237 | 0.686 (0.683–0.688) | 2.9e-15 | -| `h2_raman_averaged` (0.4) | 1.344 → 0.994 | 0.740 (0.715–0.791) | 1.3e-13 | -| `rdw` (0.1) | 0.196 → 0.171 | 0.875 (0.861–0.901) | 8.1e-15 | -| `radial_filament_256` (0.5) | 0.182 → 0.165 | 0.901 (0.889–0.907) | 3.7e-15 | - -A trial's native time (`benchmarks.adams_host`, medians of five) went 323 → 206 µs, 279 → -178, 224 → 160, 446 → 291 and 547 → 399 µs. Against the previous HIP build, which stepped -the runs with the Python march: `he_rdw_averaged` 0.463 (0.405–0.666; that build's walls -are bimodal on this device, 0.20 or 0.37 s), `argon_blueshift_averaged` 0.629, `h2_raman_averaged` -0.624, `rdw` 0.605, `radial_filament_256` 0.843, `kerr_beam_384` (half) 0.650 and -`kerr_beam_192` (half) 0.702 (both from the free-space work above), and at a tenth of their -length (two rounds) `gnlse_raman_shock` 0.843, `argon_blueshift` 0.657, `ctc` 0.780. -What remains is mostly the host's launch rate: a trial's kernels take 2 to 4 µs each, and -rocFFT runs each of these transforms as four kernels. - -**On an NVIDIA H200** (CUDA 13.1, `HOPPER90`) the same changes, of which the light-weight -hint is a no-op there (grid-constant arguments), against the build without them (three -rounds, the same steps): `he_rdw_averaged` 0.920 (0.904–0.936, fields to 1.2e-11), -`argon_blueshift_averaged` 0.902 (0.880–0.912), `h2_raman_averaged` 0.918 (0.916–0.920), -`rdw` 0.969 (0.962–1.035), `radial_filament_256` 0.989 (0.962–1.134). Over a 411-trial window -of the first the correct pass went 21.4 → 14.1 µs and the predict pass 24.7 → 22.2 µs, the -transforms 4 → 3 a trial (cuFFT's one kernel each). Against the previous main build: -`he_rdw_averaged` 0.790, `argon_blueshift_averaged` 0.882, `h2_raman_averaged` 0.788, `rdw` -0.841, `radial_filament_256` 0.868, `kerr_beam_384` (half) 0.722, `kerr_beam_192` (half) 0.776. - -### Pinned trial norms and batched forward rows on a device - -On a device, an Adams trial's defect norms are reduced into pinned host memory. The -reduction's last block writes them there directly, so the device-to-host copy is gone (on -HIP it was a blit kernel: 2.16 → 1.16 copies a trial), and the trial keeps its one fence. -A modal stage's in-stage absorber, projection and held-current rows are carved from one -buffer and transformed with one batched plan after the absorber is formed. This does not -apply to dispersive responses, the general route or coarse rows. The radial route's three -held streams also take one plan. - -All A/Bs use `ab --device`, three rounds, against the tree before the change. Every case -took the same steps, and the fields were bitwise equal. - -| device | case | ratio (range) | -|---|---|---:| -| AMD Instinct MI325X | `he_rdw_averaged` (0.3) | 0.903 (0.856–0.906) | -| | `argon_blueshift_averaged` (0.1) | 0.858 (0.854–0.929) | -| | `h2_raman_averaged` (0.4) | 0.888 (0.836–0.893) | -| | `rdw` (0.1, coarse rows, not packed) | 0.994 (0.959–1.001) | -| | `radial_filament_256` (0.5) | 0.969 (0.963–0.977) | -| | `kerr_beam_192` (0.5, unaffected) | 1.004 (0.984–1.024) | -| NVIDIA A40 (batched rows and pinned norms) | `he_rdw_averaged` | 0.784 | -| | `argon_blueshift_averaged` | 0.755 | -| | `h2_raman_averaged` | 0.878 | - -The pinned norms alone were within noise on the MI325X. When the pack is forced on a CPU -build, the fields are bitwise equal. - -### Device graph replay of an Adams trial's source - -On a CUDA or HIP build, an elementwise Adams trial's source evaluation runs in a graph -region (`graph::Region`). The first trial captures its kernels, device copies and -transforms. Each later trial whose operations repeat, in order and with equal keys, -launches the instantiated graph instead. In a microbenchmark, thirty dependent tiny -kernels cost 3.36 µs each back to back and 2.18 µs as a replayed graph on an AMD Instinct -MI325X, and 2.41 and 1.67 µs on an NVIDIA A40. Capturing every trial and updating the -instantiated graph cost more than plain launches (4.04 µs on the MI325X). - -All A/Bs below use `ab --device`, three rounds, against the build without the region. -Every case took the same steps, and the fields were bitwise equal. - -| case | MI325X | NVIDIA H200 | NVIDIA A40 | -|---|---:|---:|---:| -| `he_rdw_averaged` (0.3) | 0.915 (0.902–0.995) | 0.991 (0.937–1.003) | 0.972 (0.944–0.976) | -| `argon_blueshift_averaged` (0.1) | 0.893 (0.880–0.897) | 0.918 (0.917–0.962) | 0.962 (0.959–0.965) | -| `h2_raman_averaged` (0.4) | 0.885 (0.864–0.889) | 0.964 (0.948–0.976) | 0.978 (0.976–0.981) | -| `rdw` (0.1) | 1.029 (0.978–1.031) | 0.987 (0.968–1.039) | 0.999 (0.997–1.000) | -| `radial_filament_256` (0.5) | 0.990 (0.986–0.994) | 1.022 (0.992–1.114) | 0.999 (0.997–1.004) | -| `kerr_beam_384` (0.5) | 1.001 (0.981–1.003) | 1.001 (0.993–1.023) | 0.987 (0.986–1.005) | - -The three mode-averaged runs replay all but their first trial: 410, 1048 and 5418 replays -to one capture. The sources of `rdw` and `radial_filament_256` hold a vendor GEMM or a -reduction. Their region stops at its second operation and the run continues with ordinary -launches; its one capture is the 3 % on the MI325X's short `rdw` window. The Kerr cases do -not use the region. A first version on the H200, whose trial is bound by the host, was -slower (`he_rdw_averaged` 1.10, `argon_blueshift_averaged` 1.25). A verifying trial walks -the whole source before its one launch, and that walk copied every operation it skipped. -Comparing keys in place and copying an operation only when it is recorded removed that -cost. - -### Device transforms of the four-mode capillary and the radial filament - -`rdw` and `radial_filament_256` gained least on devices from the batched rows and the graph -replay. An NVIDIA A40 trace of one `rdw` trial (34 kernels, 1.30 ms of kernels, gaps of -about 0.9 µs) showed why: the trial is bound by its transform shapes, not by its launches. - -- **Coarse rows in the forward pack.** Each of the stage's four real transforms (fine and - coarse projection, absorber, held currents) took about 96 µs on 16 of the A40's 84 - multiprocessors, whatever its rows: the held pack's 16 rows cost the same as the - projection's 4. The coarse projection's rows now join the device forward pack, so the - stage's 28 rows are one transform (`packs_forward`). A device never defers the coarse - quadrature, so those rows are projected at every stage. -- **Few-mode transforms through the custom kernels.** cuBLAS took 71 µs for the stacked - projection (8 rows, 36 nodes, 10240 samples; about 84 GFLOP/s) and 27 µs for the - synthesis. Below eight modes the device's hybrid guard now keeps the custom kernels, - which form the fine and coarse rows in one pass: 19 µs and 8 µs. With no vendor GEMM - left, the whole source replays as a graph (158 replays to one capture). -- **CUDA trial reductions in blocks of 128.** Kokkos's CUDA range reduction gave the - prediction and correction 256-thread blocks of one element each: `rdw`'s 10496 elements - were 41 blocks. Blocks of 128 occupy every multiprocessor. On the A40 the prediction went - from 92.5 to 55.4 µs and the correction from 49.3 to 41.0 µs. The reductions' order - changes, so the trial norms move by rounding. -- **An AMPERE86 build's real GEMMs.** cuBLAS runs a compute capability 8.6 device's DGEMM - with the FP64 tensor-op kernels of 8.0. A probe on the A40 measured 316 GFLOP/s for the - radial filament's 128 × 256 × 866 synthesis, about 54 % of the FP64 peak, at any row - pitch. `device_dense_gemm` gives a thread four rows of one column and takes 132 µs where - cuBLAS took 180. Eight rows a thread were 5 % slower. The radial source then replays as a - graph too (70 replays to one capture). - -All A/Bs use `ab --device`, three rounds, against the build before these changes. - -| case | NVIDIA A40 | AMD Instinct MI325X | -|---|---:|---:| -| `rdw` (0.1) | 0.799 (0.795–0.810) | 0.962 (0.912–0.974) | -| `radial_filament_256` (0.5) | 0.930 (0.928–0.934) | 1.000 (0.995–1.005) | -| `he_rdw_averaged` (0.3) | 0.934 (0.927–0.937) | 0.996 (0.990–1.004) | -| `argon_blueshift_averaged` (0.1) | 0.940 (0.938–0.956) | 0.994 (0.990–1.007) | -| `h2_raman_averaged` (0.4) | 0.952 (0.947–0.954) | 0.999 (0.989–1.025) | - -Every case took the same steps. Measured one change at a time on the A40, the coarse rows -gave `rdw` 0.892 and the custom transforms 0.923, both bitwise. The CUDA reductions gave -`rdw` 0.981 (0.968–1.008), and they are the whole of the single-mode runs' gain. The -AMPERE86 GEMM gave `radial_filament_256` 0.933, bitwise. The reductions' order moves the -norms by rounding, and through the step sizes it moves the final fields: by 2e-15 to -6e-14, and by 1.0e-11 on `he_rdw_averaged` (410 steps). The HIP reduction's block did the -same before (1.4e-11). On the MI325X only the first two changes apply. There, `rdw`'s -field moves by 2.5e-15 (the custom transforms against rocBLAS) and the others are bitwise. -The MI325X's `rdw` source replays as a graph after four captures, while its radial source -still holds rocBLAS. - -Three leads were dropped. Eight rows a thread in the AMPERE86 GEMM ran at 1.054 against -four. Padding the radial GEMM's row pitch changed nothing: cuBLAS ran at 316 GFLOP/s with -866, 872, 896 and 1024 doubles. Recording vendor GEMMs in the graph was not tried. The -trace puts its saving at about 1 % of a radial trial, and KokkosBlas sets cuBLAS's stream -at every call, which resets cuBLAS's workspace to its default pool. - -What is left on the A40's `rdw` trial (0.77 ms of kernels): the inverse transform (96 µs -on 4 multiprocessors, one block a row), the packed forward transform (96 µs), the band -column's four kernels (235 µs), the three projections (57 µs), the prediction (55 µs), -the correction (41 µs) and the quadrature partials (39 µs on 4 teams). A timed run is -also one long host gap at the first saved plane, in solprop's output layer. - -### Split real-row transforms on compute capability 8.6 - -After the device transforms of the four-mode capillary, an NVIDIA A40 trace of one `rdw` -trial still spent a quarter of its 0.77 ms of kernels in two cuFFT kernels: the inverse -transform of the fine spectrum (4 rows of 10240 samples, 96 µs) and the packed forward -transform (28 rows, 96 µs). cuFFT gives a real row of a few thousand samples one thread -block, and a GA10x device (compute capability 8.6) runs FP64 at a sixty-fourth of its -FP32 rate, so each block is FP64-bound on its multiprocessor while the rest of the -device waits. A single-mode run's one-row transforms used one multiprocessor of 84. - -An AMPERE86 build now transforms up to 64 contiguous real rows of n = 2m samples as -m-point complex rows (sample pairs as one point, the standard half-length real -transform) by the four-step method (`RealRowPlan`, `fft_plan.hpp`): m = n1 n2, with n2 -the largest power of two up to 512 that divides m. Our kernels pack the rows into n2 × n1 -columns, cuFFT transforms n1 points per column, a kernel applies the twiddle -exp(∓2πi j2 k1 / m) and transposes, cuFFT transforms n2 points per row, and a last kernel -forms the real spectrum (or unpacks the samples). The roots are rounded once from long -double. The inverse drops the imaginary parts of the DC and Nyquist bins, as cuFFT's and -FFTW's do. A probe on the A40 timed 4 × 10240 at 20 µs against cuFFT's 102, and 28 rows -at 60 against 114, both agreeing with cuFFT to 2e-15 relative. Of the splits of 5120 -points, 10 × 512 and 40 × 128 were fastest; those with an 80-point pass took half as -long again. In the engine the two transforms of an `rdw` trial take about 78 µs where -they took 193. - -An NVIDIA H200 runs the same cuFFT kernels in 12 to 13 µs, faster than the split (12.5 -µs for 4 rows and 17.8 for 28), and on it the single-mode mode-averaged runs lost 4 to -5 % with the split, so only AMPERE86 builds split their rows, as they form their own real -GEMMs. - -| case | NVIDIA A40 | -|---|---:| -| `rdw` (0.1) | 0.932 (0.924–0.939) | -| `he_rdw_averaged` (0.3) | 0.751 (0.750–0.752) | -| `argon_blueshift_averaged` (0.1) | 0.757 (0.756–0.758) | -| `h2_raman_averaged` (0.4) | 0.770 (0.768–0.771) | -| `radial_filament_256` (0.5) | 0.996 (0.985–0.997) | - -`ab --device`, three rounds, against the build before the change. Every case took the -same steps; the radial filament's rows are too many to split and its field is bitwise. -The fields agree to 1.2e-13, except `he_rdw_averaged` (1.1e-11): the split moves each -transform by rounding, the trial norms follow, and through the step sizes the final -field, as the CUDA reductions' order did (1.0e-11). On the H200 the build with the split -off agrees with the build before bit for bit and takes 0.99 to 1.01 of its time. - -Two other levers were measured and dropped. A team per 128-bin chunk of a column's -quadrature partials took them from 39 to 7.8 µs, but the score's sum over the chunks took -most of that back, by one thread (2.5 to 7.9 µs) or by a team: 0.989 on `rdw`, 0.994 and -1.005 on the single-mode runs. The band column's four tiled kernels (235 µs of the `rdw` -trial) moved neither with teams of half a tile (0.985 on `rdw`, 1.002 on -`he_rdw_averaged`) nor with 512-sample tiles (1.010, 1.019). The A40 we measured on -gave no access to its performance counters, so what bounds them is not known. A -single-mode trial's prediction and correction (84 of its 205 µs of kernels) ran on 21 -blocks of 128 threads; blocks of 64 gave 0.985, 0.980 and 0.987 on the mode-averaged -runs and 1.000 on `rdw`, and blocks of 32 regressed the radial filament (1.029). +### Dispersive electronic response -### Retained radial synthesis and Raman modal products +The dispersive Kerr response (SEP 6) is judged by its nonlinear stage time against the +constant cubic's on the same route, the symmetric evaluator's target 1.3 and the +polynomial's 4 (recorded by 2026-10-23; machines not recorded). On the native CPU backend at +one thread the symmetric evaluator took 0.81–1.21 (one species) and 0.97–1.21 (a mixture); +the polynomial 1.52–3.65 for one species (4.2–5.0 on the general route) and 3.2–8.3 for a +mixture of distinct leg bounds, at most 2.2 in the default pools. On NVIDIA and AMD GPUs the +symmetric evaluator took 0.86–1.30 and the polynomial 1.01–3.53 for one species. A polynomial mixture is +one group per distinct leg bound, which is why mixtures such as air miss its target on CPUs. -Two work reductions from the CPU experiment's handoff, each measured with -`python -m benchmarks ab` (fresh interleaved processes, passive-bound threads, -`SOLPROP_FFTW_PLAN=measure`, three rounds, one repeat; medians of the per-round pairs, -range over rounds). Each case exercises one of them: the radial filament has no Raman -term, and the capillary is not a square radial map. Work counts are equal in every pair -and the final fields agree to 4–10 × 10⁻¹⁵ relative. - -- **Retained-spectrum radial synthesis** (square radial analytic maps, - [backends.md](backends.md)): the synthesis product covers `2 n_omega` real columns - instead of `2 n_to`. `radial_filament_256`, complete guide: on an Intel Xeon Gold 6240 - (one socket, 18 cores) 0.928 [0.925, 0.945] at one thread and 0.954 [0.936, 0.968] at - 16; on 16 cores of an AMD EPYC 7763, 0.869 [0.868, 0.891] at one thread, and at - `--length 0.05` 0.866 [0.850, 0.868] at one thread and 0.825 [0.653, 0.894] at 16. The - EPYC's 16-thread ratios moved by about ±15 % between allocations on a shared node (a - complete-guide repeat gave 0.999 [0.735, 1.020]); the Intel Xeon Gold 6240's are the resolved ones. - A 16-thread label profile on the EPYC put the synthesis GEMMs at 0.20 s against - 0.38 s, of which the gather and pad, as first written per chunk and over every fine - bin, took back 0.14 s; they now gather once per evaluation and write only the retained - bins. -- **Raman modal products** (three-mode `ctc`, 6 product rows against 33 node drives): - `--length 0.05` at 16 threads 0.884 [0.881, 0.899] on a Xeon Gold 6240; on the EPYC 0.833 - [0.823, 0.837] at one thread and 0.921 [0.861, 0.928] at 16 (`--length 0.02`: 0.850 - and 0.884). The first reconstruction looped over the products per sample and cost ten - times the node path's finish (0.46 s against 0.046 s in a one-thread window); it now - accumulates each product over contiguous blocks of 512 samples. - -Both add FFT plans (the node transforms; the product rows), measured at construction: -on a Xeon Gold 6240 a CTC worker's wall time, construction included, rose from 16.3 s to 17.7 s. - -Not adopted, on the same EPYC allocation: -- Routing every real product with a left matrix of at most 256 entries through - `native_order_gemm` instead of the vendor BLAS: RDW 1.012 / 0.881, argon 1.057 / - 1.099, CTC 1.070 / 1.377 at one / 16 threads (`--length 0.05`). The vendor library - wins on the serial transform spaces the operation-size policy gives these shapes. -- Plain row-block loops for one-mode synthesis and projection: argon 0.996 at one - thread; at 16 the loops took 0.65–0.69 s of a short window where the vendor GEMMs took - 0.55 s. The vendor pool still costs 0.55 s against 0.23 s at one thread there. -- Planning the product rows at the full Raman chunk's width rather than their own: - CTC 1.001 / 0.980 [0.952, 1.012]. +### Raman kernel rebuild -### Host stage entry, free-space crossings and statistics +On a density gradient the Raman kernel is rebuilt at every stage, and its cost scales with +the response's rows. `numpy_ref`'s rebuild at $2^{14}$ fine samples (a loaded laptop, +recorded by 2026-10-23, model not recorded) took 0.31 ms for a two-term N₂ model, 0.47 ms for +optmat's H₂ (4 rows), 6.0 ms for optmat's N₂ (72 rows) and 10.2 ms for dry air (126 rows), +against 0.25 ms for one convolution; the native rebuild is slower than the host's at one +thread and overtakes it at four. With tens of rows the rebuild dominates the step; +[SEP 10](seps/sep-0010-low-rank-raman.md)'s low-rank representation is what removes it. -Host-only changes found by profiling the tracking set at one and sixteen threads (Kokkos -label timer and `perf`, Intel Xeon Gold 6240, GCC 16.2 `-march=cascadelake`, SLEEF's AVX2 -functions, OpenMP OpenBLAS). Each was measured with `python -m benchmarks ab` (fresh -interleaved processes on 18 cores of one socket, passive bound threads, -`SOLPROP_FFTW_PLAN=measure`, three rounds of one repeat at 0.1 of each case's length; -medians of the per-round pairs, range over rounds). Every pair did the same work. - -- **The stage entry's finish and combination as lanes** (the modal routes' host entry - kernel). The deferred finish and the combination ran each bin through scalar - `Kokkos::complex` code: on `gnlse_raman_shock` (16384 bins, DOPRI5, noise, Raman, a - temporal collar) the entry took 2.8 s of a 7.1 s one-thread window, 21 % of it in the - lambda's own scalar code. A 64-bin block now runs as real and imaginary lanes, each bin - the same operations in the same order (only the crop's gathers stay per bin, and an - identity crop reads and writes contiguously), and a lossy problem's block whose phases - all have zero real parts takes both magnitudes as exactly one without the two `exp` - passes (only 42 of the 256 blocks of `gnlse_raman_shock` carry loss). One trial step - from identical input differs by at most 3.4e-18 of the field's peak. - - | case | one thread | sixteen threads | - |---|---:|---:| - | `gnlse_raman_shock` | 0.836 (0.826–0.840) | 0.962 (0.960–0.987) | - | `gnlse_soliton` | 0.955 (0.937–1.042) | 0.939 (0.934–0.959) | - | `argon_blueshift_envelope` | 1.011 (0.968–1.019) | 0.984 (0.981–1.013) | - | `ctc` | 1.012 (0.982–1.012) | 1.022 (1.001–1.027) | - - Both arms of these sixteen-thread runs predate the hold of - [NumPy's BLAS](#numpys-blas-beside-a-native-run). -- **The separable low-storage fold in the scratch's layout.** The fold read the - column-major state, accumulator, stage register and flow table 32 columns apart at each - bin beside the transverse scratch, divided each column by the polarisation count and - called the element's full spatial value out of line: 63 ns an element at one thread, - 27.7 s of `kerr_beam_384`'s 69.8 s window. The host's registers now sit at the scratch - cell's own position; a work item takes 32 adjacent columns over every bin, loads each - 16-bin tile of their state a contiguous run at a time and folds it in the scratch's - order; a tabulated fold reads only the prefactor. The flow table is formed in the same - order. Fields are bitwise equal. - - | case | one thread | sixteen threads | - |---|---:|---:| - | `kerr_beam_384` | 0.789 (0.788–0.790): 68.6 → 54.2 s | 0.899 (0.895–0.903) | - | `kerr_beam_192` | 0.742 (0.732–0.746) | 0.902 (0.900–0.918) | - -- **Crossings without divisions, the monitor's runs, the radial statistics' GEMMs.** Every - host crossing between state columns and the transverse scratch located its cell with a - run-time `% n_pol` and `/ n_pol`; in a microbenchmark of `kerr_beam_384`'s chunk (4468 - rows of 750 bins) at one thread they doubled the crop's time (17 to 35 ms), and visiting - the pack's tile rows outermost took it from 36 to 22 ms. The boundary monitor's reading - divided each sample's flat index by the row length (1.76 s of `kerr_beam_384`'s - one-thread window); a host work item now sums a run of 512 samples of one row. A radial - run's local flux statistics synthesised each node's field and closure with a scalar - 256-mode sum inside the pointwise kernel (0.57 s of `radial_filament_256`'s 3.65 s - window, five planes); they are now two GEMMs over the time fields' interleaved real - columns into buffers the statistics already hold, bitwise equal on the host. Against - the fold above: - - | case | one thread | sixteen threads | - |---|---:|---:| - | `radial_filament_256` | 0.834 (0.827–0.840) | 0.945 (0.933–0.954) | - | `kerr_beam_384` | 0.830 (0.826–0.856): 53.7 → 44.9 s | 0.943 (0.943–1.190) | - | `kerr_beam_192` | 0.855 (0.849–0.861) | 0.951 (0.946–0.973) | - - Together with the fold, `kerr_beam_192` takes 0.635 of its time at one thread (8.04 → - 5.11 s) and `kerr_beam_384` 0.847 at sixteen (9.36 → 7.93 s); at sixteen threads the - 384² fold is now bound by memory bandwidth (about 52 GB/s), and about 5 s of that - window is solprop's own host work at the saved plane. - -On 16 cores of an AMD EPYC 7763 (GCC 16.2 `-march=znver3`, the three changes together, -same protocol), one / sixteen threads: `gnlse_raman_shock` 0.841 (0.836–0.842) / 0.972, -`gnlse_soliton` 0.941 / 0.942, `radial_filament_256` 0.838 (0.837–0.850) / 0.938, -`kerr_beam_384` 0.953 (0.947–0.958) / 1.003, `kerr_beam_192` 0.956 / 0.995, `ctc` -0.994 / 0.977, `argon_blueshift_envelope` 0.981 / 1.001. The free-space gains are small -there: Zen 3 ran the 384² window in 30 s at one thread where a Xeon Gold 6240 took 69 s, its -64-bit divisions and strided streams far cheaper. - -Not adopted: -- The Kerr-only free-space stage through one rank-3 FFTW transform, as a device takes it: - for 384 × 192² at one thread an estimated plan took 1.03 s a transform and a measured - one 0.31 s, the same as the batched planes and a strided temporal transform, after - 17 s of planning; native's transform pair with the chunks' pack and crop is no slower. -- The pack and crop through a 32 × 32 tile buffer (as the fold's state): 0.55 → 0.68 s - and 0.52 → 0.56 s on `kerr_beam_192` at one thread. -- A one-element GEMM (one mode, one node) as an elementwise product: no faster than - OpenBLAS's small kernel; both are memory-bound. -- Transparent huge pages through glibc's `glibc.malloc.hugetlb=1` (the workstation's - setting is `madvise`): within ±3 % on `kerr_beam_192` at one thread. - -(persistent-fftw-wisdom)= -### Persistent FFTW wisdom +### Adams carrier frame per step -At one thread, the default plans every row transform with FFTW's measured search, which -is most of a short run's backend construction: about 1.3 s for averaged helium's -6400-sample real pair alone. `SOLPROP_FFTW_WISDOM` now keeps those plans for the next -process ([tuning](../guide/performance/tuning.md)). Fresh processes at one thread, -`SOLPROP_FFTW_PLAN=measure`, passive-bound, through the benchmark worker's own -`timed_run` (`--length 0.1`; `ctc`, `kerr_beam_192` and `grin_nonlinear` on the EPYC -and `ctc` on a Xeon Gold 6240 `--length 0.05`). For each case one process stores the wisdom, -then three rounds alternate a process without the variable (cold) and one with it -(warm): medians of the backend's construction, cold → warm, and the warm/cold window -ratio's median and range over the rounds. Step counts are equal in every pair. One core -of an Intel Xeon Gold 6240 (an otherwise idle socket) and of a 16-core allocation of an -AMD EPYC 7763: - -| case | Xeon construction | Xeon window | EPYC construction | EPYC window | -|---|---:|---:|---:|---:| -| `he_rdw_averaged` | 1.398 → 0.033 s | 0.985 [0.945, 0.988] | 1.777 → 0.049 s | 1.002 [0.973, 1.004] | -| `argon_blueshift_averaged` | 1.330 → 0.032 s | 1.006 [0.987, 1.009] | 1.708 → 0.040 s | 0.987 [0.961, 1.001] | -| `h2_raman_averaged` | 4.003 → 0.029 s | 1.003 [0.996, 1.025] | 5.224 → 0.040 s | 0.999 [0.987, 1.009] | -| `gnlse_raman_shock` | 2.097 → 0.033 s | 1.002 [0.926, 1.010] | 2.801 → 0.048 s | 1.004 [0.987, 1.005] | -| `gnlse_soliton` | 0.453 → 0.022 s | 0.999 [0.995, 1.005] | 0.636 → 0.035 s | 0.995 [0.990, 1.019] | -| `rdw` | 1.405 → 0.051 s | 0.992 [0.985, 1.003] | 1.827 → 0.068 s | 0.993 [0.990, 1.005] | -| `argon_blueshift` | 1.321 → 0.035 s | 0.995 [0.985, 0.999] | 1.735 → 0.048 s | 0.998 [0.996, 1.002] | -| `argon_blueshift_envelope` | 0.473 → 0.024 s | 0.989 [0.976, 1.021] | 0.678 → 0.038 s | 1.007 [0.995, 1.016] | -| `radial_filament_256` | 0.613 → 0.093 s | 0.994 [0.986, 1.022] | 0.820 → 0.107 s | 1.008 [1.004, 1.011] | -| `ctc` | 5.033 → 0.056 s | 0.985 [0.983, 1.016] | 6.565 → 0.068 s | 1.002 [1.001, 1.004] | -| `kerr_beam_192` | 1.248 → 0.657 s | 0.993 [0.972, 1.006] | 1.079 → 0.255 s | 0.995 [0.973, 1.126] | -| `grin_nonlinear` | | | 1.984 → 0.309 s | 1.015 [1.000, 1.040] | - -Warm windows run as fast as cold ones: the plans are those a measurement chose, in this -process or an earlier one. A warm process given the seeding process's wisdom reproduced -its final field bit for bit (averaged helium), where two cold processes differ by -measured plans (5.8 × 10⁻¹⁵ relative). What remains of a warm construction is allocation -and setup: tens of milliseconds, a few tenths of a second for the free-space Kerr beam's -1.4 GB of state. A job of a one-thread scan still pays solprop's own import, case -construction and translation (0.7 s and 3.0 s for averaged helium on a Xeon Gold 6240), which -the native backend does not own. +The scalar carrier frame (SEP 35) on ten replayed steps of a hydrogen capillary at one +thread, Apple M5 Max (2026-10-25, a machine in use: ratios only): 1.057 with a Kerr-only +source and 1.006 with Raman. Its case rests on the calls it saves. -### Band column passes and the general route's real signal +### Low-storage interaction-picture RK -Host-only changes found by profiling `ctc` and `grin_nonlinear` (Kokkos label timer and -`perf`, Intel Xeon Gold 6240, GCC 16.2 `-march=cascadelake`, SLEEF's AVX2 functions). -In a one-thread `ctc` window (0.01 of the guide) the band plasma column took 1.00 of -1.99 s inside Kokkos, 25 ns a sample, and the band statistics another 0.29 s; in a -`grin_nonlinear` window (0.05) the complex inverse transform took 2.53 of 8.02 s, the -projection 1.81 s and the synthesis 1.57 s. - -- **The band column's passes as block loops.** In the column's own code a third of the - samples went to the integrand pass (an out-of-line strict call per sample for the - ionised fraction, a scalar division in the loss guard, a live-window note per - sample), two fifths to the scans (Kokkos' host team scan runs each closure twice, the - second time from the same zero), and a fifth to the rates' classification and - scatter. A rate block of 256 samples that is mostly live now takes every sample - through the vector-maths passes, a quiet one's magnitude replaced by the table's lower - limit, and selects the limits after; a mostly quiet block gathers as before. The - fractions come from one strict block loop, the guard's branch is a selection that - divides by one where it is not taken, the live window is searched from a block's - ends, and a one-thread team scans in one pass. Every value is unchanged to the bit. - Label timer, column: 1.00 → 0.69 s at one thread, 0.147 → 0.100 s at sixteen. -- **The filter one tap pair at a time, on x86-64.** GCC had vectorised each sample's - nine-tap sum across the taps, a serial chain of additions per sample. A thread now - takes blocks of 512 samples and runs the interior as one loop per tap pair; each - sample keeps its order of terms, and only the contraction of its multiply-adds can - move it (one `ctc` step: 2.2 × 10⁻¹⁶ of the field's peak). Column: 0.69 → 0.54 s at - one thread, 0.100 → 0.082 s at sixteen. Other hosts keep the per-sample traversal: the - earlier tap-first filter slowed an Apple M-series argon window (see the rejected - leads below). -- **The rate table's cubic vectorised out of line.** Called from the blocks, the table's - cubic ran scalar, a division per sample: the compiled-out-of-line loop stored through - the pointer it read while it gathered from the table, which GCC could not prove - apart. It now writes a local block. Bitwise; column 0.54 → 0.51 s. -- **The quiet-block skip.** A rate block with no live sample takes only the table's - limits, without the gather, and the single gas's density is read once per node, not - after each store of the current (which the compiler had to assume might alias it). - Bitwise; `argon_blueshift` column 0.72 → 0.64 s of a 0.05 window at one thread, `ctc` - 0.51 → 0.49 s. -- **The band statistics in the same blocks.** The statistics scan took each sample's - rate and diagnostic fraction through the system libm and its whole-row prefix through - Kokkos' two-pass scan; it now uses the column's rate blocks, block fractions and the - one-pass scan. `ctc`: 22.8 → 14.0 ms a call at one thread. The statistics' rates now - carry the vector maths' rounding: the peak ionisation rate moves by 3.6 × 10⁻¹⁴ - relative (a one-ulp change of `log |E|` through the cubic's slope), every other - statistic not at all. -- **The real form's field through a complex-to-real transform.** A real-form cubic - reads only the real part of the analytic signal, which is the c2r transform of the - one-sided spectrum with its doubled bins halved (exactly) and the imaginary parts of - the zero and Nyquist bins dropped. The host now synthesises that half spectrum and - transforms it c2r; the buffers are the complex transform's, aliased, so the ledger - and solprop's memory estimate are unchanged. Not with SEP 6's dispersive response, - and not on devices. One `grin_nonlinear` step: 4.7 × 10⁻¹⁷ of the field's peak. - Inverse transform 2.53 → 1.21 s, respond 0.68 → 0.50 s at one thread. -- **The projection's block of bins up to the whole row.** A host projection team walked - the chunk's rows over at most 64 bins, 1 KiB of each map row in turn; the block now - widens to 2048 bins and to the first power of two covering the bins, so at one thread - a team streams a mode's map rows contiguously. No bin's sum changes order. Project - 1.81 → 1.17 s at one thread (2048 bins), 0.20 → 0.17 s at sixteen (512 bins). -- **The synthesis summed in local blocks.** The host synthesis zeroed each row and - added every mode's products into it in memory; it now zeroes only the bins outside - the crop and sums blocks of 256 bins in two local arrays before one store, each bin's - sum in the same order. Synthesise 1.47 → 1.31 s at one thread. At one thread the - synthesis and the projection each stream a 122 MB map per evaluation at 8–9 GB/s, - about what one core of this socket draws from memory. - -Each case measured with `python -m benchmarks ab` against the parent of these changes -(fresh interleaved processes on 18 cores of one socket of a Xeon Gold 6240, passive bound -threads, `SOLPROP_FFTW_PLAN=measure`, `--length 0.05`, three rounds of one repeat; -medians of the per-round pairs, range over rounds). Every pair did the same work, and -the final fields agree within the measured-plan floor (2 × 10⁻¹⁵ to 3 × 10⁻¹⁴): - -| case | one thread | sixteen threads | -|---|---:|---:| -| `ctc` | 0.703 (0.694–0.705): 7.74 → 5.46 s | 0.846 (0.829–0.868) | -| `argon_blueshift` | 0.641 (0.627–0.649) | 0.853 (0.844–0.868) | -| `rdw` | 0.865 (0.859–0.886) | 0.982 (0.949–0.984) | -| `grin_nonlinear` | 0.701 (0.687–0.705): 8.04 → 5.67 s | 0.802 (0.800–0.805) | -| `argon_blueshift_averaged` | 0.913 (0.911–0.947) | 0.919 (0.901–0.922) | -| `he_rdw_averaged` | 0.945 (0.773–0.951) | 0.958 (0.947–1.019) | - -The two averaged cases were measured without the quiet-block skip, which affects the -resolved cases only (a separate run). - -On 16 cores of an AMD EPYC 7763 (GCC 16.2 `-march=znver3`, the same protocol on a -fragmented allocation; all but the quiet-block skip), one / sixteen threads: - -| case | one thread | sixteen threads | -|---|---:|---:| -| `ctc` | 0.760 (0.754–0.770): 6.37 → 4.84 s | 0.927 (0.924–0.929) | -| `argon_blueshift` | 0.755 (0.744–0.765) | 0.937 (0.904–0.940) | -| `rdw` | 0.884 (0.874–0.885) | 0.975 (0.963–1.020) | -| `grin_nonlinear` | 0.750 (0.750–0.766): 5.53 → 4.16 s | 0.872 (0.845–0.881) | -| `argon_blueshift_averaged` | 0.918 (0.912–0.927) | 0.922 (0.906–0.929) | -| `he_rdw_averaged` | 0.985 (0.943–1.056) | 0.967 (0.941–0.975) | - -With the quiet-block skip as well (another allocation, the same CPUs): `argon_blueshift` -0.720 (0.715–0.724) / 0.937, `ctc` 0.754 (0.751–0.755) / 0.907, `rdw` 0.883 / 0.989, -`grin_nonlinear` 0.749 / 0.918 (0.835–0.918). - -Not adopted: summing each block of eight scan increments locally before the running -prefix, so that only block totals form a dependent chain (`ctc` column 0.538 → 0.534 s, -within noise, for a change of association). - -### The native performance push: `main` at `740b24d` against its result - -The native performance push started from `main` at `740b24d`, the merge of SEP 39's -native Adams march, and changed only the native backend and its build. It left the -benchmark cases and stepper settings unchanged. The sections above record each adopted -change with its own A/B. This section compares the two ends. - -**Complete runs** (`ab --length 1.0`, three interleaved rounds, fresh processes) on a -dual Intel Xeon Gold 6240, timed on the 18 physical cores of one socket. Every case took the same steps. - -| Case | One thread (field difference) | Sixteen threads (field difference) | -|---|---|---| -| `gnlse_raman_shock` | 0.841 ($3.6\times10^{-13}$) | 0.765 ($1.0\times10^{-12}$) | -| `gnlse_soliton` | 0.802 ($9.4\times10^{-14}$) | 0.796 ($7.9\times10^{-14}$) | -| `rdw` | 0.659 ($7.9\times10^{-14}$) | 0.704 ($1.7\times10^{-13}$) | -| `he_rdw_averaged` | 0.608 ($2.4\times10^{-10}$) | 0.505 ($2.1\times10^{-10}$) | -| `argon_blueshift` | 0.563 ($5.4\times10^{-14}$) | 0.366 ($1.1\times10^{-13}$) | -| `argon_blueshift_averaged` | 0.605 ($5.3\times10^{-14}$) | 0.697 ($1.3\times10^{-13}$) | -| `argon_blueshift_envelope` | 0.724 ($2.0\times10^{-12}$) | 0.818 ($1.7\times10^{-12}$) | -| `h2_raman_averaged` | 0.645 ($1.4\times10^{-13}$) | 0.387 ($9.5\times10^{-14}$) | -| `radial_filament_256` | 0.623 ($4.7\times10^{-15}$) | 0.627 ($4.5\times10^{-15}$) | -| `grin_nonlinear` | 0.684 ($1.7\times10^{-12}$) | 0.792 ($6.9\times10^{-13}$) | -| `kerr_beam_384` | 0.559 ($1.1\times10^{-15}$) | 0.640 ($1.1\times10^{-15}$) | -| `kerr_beam_192` | 0.545 ($9.4\times10^{-16}$) | 0.659 ($9.5\times10^{-16}$) | -| `ctc` | not run (hours) | 0.679 ($2.0\times10^{-10}$) | -| geometric mean | 0.649 | 0.627 (without `ctc`) | - -The geometric means are 0.649 at one thread and 0.627 at sixteen. Short windows -(`--length 0.1`) gave 0.663 and 0.613, but individual cases differ. `rdw` at sixteen -threads is 0.337 in a window and 0.704 over a complete run, because the window's -baseline is dominated by per-run costs that the push removed (an idle NumPy BLAS pool -spinning beside the native team). - -**Short windows on an exclusive AMD EPYC 7763 node** (`--length 0.1`, three rounds, 128 -cores, timing at one and sixteen threads). Every case took the same steps, with fields -within $2\times10^{-13}$. - -| Case | One thread | Sixteen threads | -|---|---|---| -| `gnlse_raman_shock` | 0.839 | 0.784 | -| `gnlse_soliton` | 0.886 | 0.882 | -| `rdw` | 0.685 | 0.934 | -| `he_rdw_averaged` | 0.663 | 0.785 | -| `argon_blueshift` | 0.662 | 0.448 | -| `argon_blueshift_averaged` | 0.595 | 0.718 | -| `argon_blueshift_envelope` | 0.863 | 0.928 | -| `h2_raman_averaged` | 0.618 | 0.351 | -| `ctc` | 0.574 | 0.748 | -| `radial_filament_256` | 0.528 | 0.751 | -| `grin_nonlinear` | 0.763 | 0.811 | -| `kerr_beam_384` | 0.817 | 0.858 | -| `kerr_beam_192` | 0.824 | 0.875 | -| geometric mean | 0.707 | 0.735 | - -**Complete runs on an NVIDIA A40** (`ab --device --length 1.0`, three rounds). Every case -took the same steps. - -| Case | `main` s | branch s | Ratio | Field difference | -|---|---|---|---|---| -| `he_rdw_averaged` | 1.330 | 0.476 | 0.358 | $1.2\times10^{-10}$ | -| `argon_blueshift_averaged` | 6.691 | 2.731 | 0.408 | $1.7\times10^{-13}$ | -| `h2_raman_averaged` | 10.119 | 6.171 | 0.610 | $1.1\times10^{-13}$ | -| `rdw` | 3.302 | 1.377 | 0.417 | $7.9\times10^{-14}$ | -| `radial_filament_256` | 0.701 | 0.528 | 0.753 | $3.6\times10^{-15}$ | -| `kerr_beam_384` | 6.455 | 5.036 | 0.791 | $1.7\times10^{-15}$ | - -On this card `main` runs some cases at one of two speeds from process to process. For -`rdw` and `radial_filament_256`, the `main` column is therefore the faster of two -complete-run jobs, and the ratio is the branch's median over it, which makes it -conservative. The final tree's own job measured 0.403 and 0.392 directly. The other -ratios are that job's direct medians of paired rounds. - -On the A40 the complete-run gains are larger than the short windows'. A window spends -a larger share of its time in solprop's per-run host work, which both arms share. - -**The other wheel platforms** (`ab --length 0.2`, three interleaved rounds, each case at -one thread and at the machine's physical cores; the same steps everywhere, fields within -$2.1\times10^{-12}$). The push was tuned on Linux x86-64; a first pass on these platforms -found two regressions at full width, both on one-column problems: `argon_blueshift` 1.31 -on macOS and `gnlse_raman_shock` 1.13 on Linux aarch64. Their causes and fixes are in -[a stable kernel team](#stable-kernel-team), [compact CPU teams](#compact-cpu-teams) and -[one-mode products](#one-mode-products). The table compares `main` with the branch with -those fixes: the CI wheels of both on macOS and Windows; on aarch64 `main`'s CI wheel -against a local DISTRIBUTION build of the same commit. - -| Case | macOS arm64, Apple M5 Max, 1 / 18 threads | Linux aarch64, Google Cloud C4A (Neoverse V2), 1 / 16 | Windows x86-64, Google Cloud C4D (AMD EPYC 9B45), 1 / 8 | -|---|---|---|---| -| `gnlse_raman_shock` | 0.969 / 0.769 | 0.982 / 0.704 | 0.773 / 0.941 | -| `gnlse_soliton` | 0.983 / 0.979 | 0.978 / 0.982 | 0.889 / 0.893 | -| `rdw` | 0.952 / 0.995 | 0.973 / 0.518 | 0.795 / 0.858 | -| `he_rdw_averaged` | 0.989 / 1.010 | 1.005 / 0.569 | 0.774 / 0.877 | -| `argon_blueshift` | 0.874 / 0.975 | 0.880 / 0.619 | 0.861 / 0.648 | -| `argon_blueshift_averaged` | 0.954 / 0.974 | 0.968 / 0.953 | 0.714 / 0.826 | -| `argon_blueshift_envelope` | 0.981 / 1.004 | 1.004 / 1.014 | 0.925 / 0.970 | -| `h2_raman_averaged` | 1.010 / 0.858 | 0.991 / 0.593 | 0.686 / 0.770 | -| `ctc` | – / 0.754 | – / 0.878 | – / 0.717 | -| `radial_filament_256` | 0.715 / 0.846 | 0.722 / 0.586 | 0.564 / 0.764 | -| `grin_nonlinear` | – / 0.872 | – / 0.896 | – / 0.764 | -| `kerr_beam_384` | – / 0.954 | – / 0.726 | – / 0.827 | -| `kerr_beam_192` | 0.902 / – | 0.820 / – | 0.725 / – | -| geometric mean | 0.929 / 0.911 | 0.928 / 0.733 | 0.764 / 0.816 | - -The first-pass tables before the fixes, the bisection and the sizing -records are kept with the project's development records. The M5 Max ran with about 1.5 -cores of background load (each round's ranges stay within a few per cent); on an Intel Xeon -Gold 6240 the fixes leave every case within the A/A spread (geometric mean 0.999 against the -unfixed branch; `main` against the fixed branch 0.646 over both widths). - -**Accuracy.** Every A/B took the same steps. -- On a Xeon Gold 6240, complete runs of `he_rdw_averaged` and `ctc` moved the final field by - about $2\times10^{-10}$, against $10^{-13}$ in short windows. `main` against itself, over - the same complete runs, gives $6\times10^{-11}$ to $2\times10^{-10}$: measured FFTW plans - differ between processes at about $10^{-16}$, and the adaptive controller amplifies the - difference over a long run. The branch's differences are at that floor. -- On the A40, fields are reproducible bitwise between processes. The device's contraction of the - Adams passes, its reduction order and the split transforms each change a step by - rounding. Together they move `he_rdw_averaged` by $10^{-11}$ in a window and by - $1.2\times10^{-10}$ over a complete run, with the same steps: the adaptive controller - amplifies the rounding, as on the CPU. -- Every other case agrees to within about $2\times10^{-12}$. - -**Measured and not adopted.** -- Compiler options: `-fno-math-errno -fno-trapping-math -fcx-fortran-rules`, `-O2`, - IPO off, 512-bit vectors, SLEEF's AVX-512 functions on a Xeon Gold 6240, branch padding. -- Threading: spinning OpenMP waits, binding threads by default (on an exclusive EPYC - allocation, `OMP_PROC_BIND=close OMP_PLACES=cores` is worth about 11 % on average; it - was neutral on a Xeon Gold 6240), a BLAS width per product, serial or full-width medium - operations. -- Sixteen-thread Raman and one-column team kernels: they gained on one CPU and lost on - the other. -- Hand-written skinny products, Adams lane blocks of 16 and 64, band statistics through - vector maths. -- On devices: a whole-transform node chunk, eight rows a thread in the compute - capability 8.6 GEMM, other device reduction block sizes, band column tilings, and - quadrature partials in chunks. - -**Outside the native backend.** On complete runs, solprop's host work outside the steps -is a fixed cost per run, not per step: 0.1–0.3 s on the capillary and radial cases, -about 6 s on `kerr_beam_384`. That is 2–9 % of a complete one-thread capillary run, and -up to a third of the complete `radial_filament_256` (sixteen threads) and -`kerr_beam_384` runs, which take one to twenty seconds. The configuration hash is -computed once, at the first output write: 0.07–0.27 s, or 1.7 s for `kerr_beam_384`'s -configuration. The cost that repeats is a saved field plane of a large Cartesian field. -For `kerr_beam_384`'s 1.77 GB field that is about 3 s per plane: -- the saved plane's copy, 1.1 s; -- the conversion to the optics convention, 1.0 s; -- the output store's copy, 0.6 s; -- the native observation, 0.35 s. - -A capillary or radial plane costs 7–25 ms. - -### The run record per plane - -[#427](https://github.com/LupoLab/solprop/pull/427) bounds the controller's norm history -(a `deque` of the controller's lag plus two, on the per-step Runge–Kutta and batch path) -and makes the per-plane run record incremental: one `RunOutcome` and one validation of -its record per plane, `CallLedger.orders` run-length encoded as it grows, and -`/meta/outcome` rewritten in place. Before: `main` at `76eb2e57`; after: the same with -the pull request merged. One thread, `numba_cpu`, on an Apple M5 Max (18 cores, 128 GB, -macOS 27.0.1, Python 3.14.5, NumPy 2.5.2, numba 0.67.0, h5py 3.16.0), a machine in -ordinary use (load 4–10): a labelled A/B, to be read as ratios, not times. - -`python -m benchmarks ab --length 0.02 --rounds 4 --repeats 7` (the harness's -`MemoryOutput`, its 11 planes inside the window, so a plane every one to four steps): - -| case | stepper | steps (rejected) | before → after | ratio | A/A | -|---|---|---:|---:|---:|---:| -| `gnlse_soliton` | `rk` | 12 (0) | 14 → 14 ms | 0.962 [0.906, 1.127] | 1.009 [0.994, 1.057] | -| `gnlse_soliton` | `multistep` | 18 (1) | 16 → 15 ms | 0.955 [0.887, 0.987] | 0.991 [0.982, 1.034] | -| `he_rdw_averaged` | `rk` | 12 (0) | 46 → 46 ms | 1.002 [0.992, 1.012] | 0.990 [0.924, 1.036] | -| `he_rdw_averaged` | `multistep` | 37 (1) | 54 → 54 ms | 0.990 [0.882, 1.026] | 0.992 [0.986, 1.034] | - -Geometric mean 0.977 (A/A 0.996); the same steps and final fields in both builds. The -harness writes no file, so the in-place `/meta/outcome` was timed by a hand script with -the same alternation (fresh processes, four rounds of five repeats after a warm-up): the -first centimetre of `gnlse_soliton`'s fibre (1536 bins) with 40 save planes, through -`run_problem` into an `HDF5Output`: - -| stepper | steps | before → after | ratio | A/A | file | -|---|---:|---:|---:|---:|---:| -| `Multistep()` | 243 | 101.2 → 95.0 ms | 0.947 [0.930, 0.968] | 0.988 [0.837, 1.012] | 1.50 → 1.35 MB | -| `RungeKutta()` | 48 | 48.6 → 48.2 ms | 0.987 [0.903, 1.001] | 0.955 [0.714, 1.025] | 1.21 → 1.13 MB | +The low-storage march (four evaluations a step) against the IP-DOPRI5 replay (six) on a +Cartesian envelope Kerr beam with fixed steps, on an 18-core arm64 workstation (recorded by +2026-10-23; model not recorded): the native CPU march took 2.02 times less time per step +at one thread on 192 × 192 × 300, and 1.81 and 1.85 times less at all threads on that grid +and on 384 × 384 × 600; per evaluation 1.35, 1.21 and 1.24 times. It holds 4 field volumes +against 15. -Nothing measured is slower. The Multistep file run, a plane every six steps, is 5 % -faster, outside its A/A range; the others sit inside theirs. The record's old cost grew -with the steps times the planes, so these windows show only its start. +### Far-field statistics pass -### A run's planes without a copy +The banded far-field pass costs about 2.3–2.6 % of one Runge–Kutta step on the native CPU +backend (192² and 384² Kerr runs, recorded by 2026-10-23; machine not recorded), paid at save +planes and periodic rows only; a whole-run check on an AMD EPYC 7763 moved +`far_field_stats` by 0.994. On an NVIDIA H200 and an AMD Instinct MI325X (2026-11-04) one +`aperture_spectrum` call at 768² × 600 took 15.4 and 14.4 ms with four circular holes and +33.3 and 33.8 ms with sixteen, about 1.5 ms a hole on top of the 9 ms `beam_spectrum` takes: +under 5 % of a saved plane at a few steps a plane. -The fix of [#448](https://github.com/LupoLab/solprop/issues/448) hands an output each plane -without copying its field, by adopting the observation's arrays, and adds one branch to -`StepDriver.observe` for the held plane of -[#345](https://github.com/LupoLab/solprop/issues/345). Before: `f004a662`; after: -`643db910` on the pull request's branch. An exclusive node, AMD EPYC 7763, 16 cores in one -NUMA domain, `--threading passive-bound`, `SOLPROP_FFTW_PLAN=measure`. +## Memory -`python -m benchmarks ab --length 0.1 --rounds 5 --repeats 1`, as the median of the -per-round paired medians (after / before), with its range over the rounds: +### Resident Adams storage -| case | threads | ratio | range | -|---|---:|---:|---:| -| `rdw` | 1 | 0.9911 | 0.980 to 0.998 | -| `rdw` | 16 | 0.9982 | 0.990 to 1.007 | -| `far_field_stats` | 1 | 1.0017 | 0.995 to 1.012 | -| `far_field_stats` | 16 | 0.9980 | 0.544 to 0.999 | - -Geometric mean 0.9972, the fields within 3.6e-15 and the same work in both builds. The -range of `far_field_stats` at 16 threads has one outlier round, in which the baseline took -16.2 s. This shows **no regression**. It does not measure the saving at large fields: these -cases save few planes at a field size where the copy is small. - -The saving is in memory, and is measured separately, on a loaded machine and so as field -volumes rather than times. A delay scan through `SimulationRunner` with a handler that -reduces each plane, against a hand loop over the backend protocol, on native CPU: a -low-storage Kerr beam at 128 x 128 x 80 (20 MiB a volume), a window of 6 steps and 3 planes -per input, the peak above the level before each input after a warm first one, on an Intel -Xeon Gold 6240. The change is this fix together with -[#435](https://github.com/LupoLab/solprop/issues/435) and -[#447](https://github.com/LupoLab/solprop/issues/447), which release the input: - -| measure | hand loop | runner, before | runner, after | -|---|---:|---:|---:| -| peak by `tracemalloc`, volumes | 1.006 | 3.003 | 1.063 | -| peak resident, volumes | 0.94 to 0.99 | 2.86 to 2.94 | 0.93 to 1.00 | - -`numpy_ref`, whose stages allocate per pass, went from 14.50 to 12.50 volumes by -`tracemalloc`, the hand loop's figure. Not measured at full size, and not extrapolated to it. - -### A kept plane exported into its store - -SEP 47 phase 3's destination export ([#346](https://github.com/LupoLab/solprop/issues/346), -[backends.md §1](backends.md#1-the-seam), "Export into a destination"): a kept field is -exported once, in the stored form, into `MemoryOutput`'s own block row, or into one new -array that `HDF5Output` writes as it is. Before: the integration branch at `1037ea88`; -after: this change. An Intel Xeon Gold 6240, pinned to 18 logical CPUs, `SOLPROP_THREADS=4`, on a -shared machine (load averages between 6 and 210 during the runs), so times are indicative -and the structural counts are the result. - -**What a kept plane makes.** Field-sized host arrays made per kept plane, and the passes -that write them, by session and store (the driver session's observation is the native -backend's host copy, which every kept plane makes): - -| session, store | before | after | -|---|---|---| -| native session, memory | a new consumer array (live until the batch is acknowledged), then the optics conversion into the row | one native pass into the row; no array | -| native session, file | the consumer array and a new stored array | one new stored array | -| driver session, memory | the observation; the conversion into the row | the same | -| driver session, file | the observation and a new stored array | the observation, converted where it is | - -**Through the service loop.** Each `sep47` saved case run to its end through -`solprop.driver.session_loop.serve` (a warm-up, three timed runs, one under `tracemalloc`), -timing each kept plane from its export to the end of its store, and tracing the bytes -allocated in that window above its start (NumPy's allocations; the native observation is -outside the tracer's sight). The median over planes 2 to 5; the first allocates the -store. Milliseconds, then MiB: - -| case | session | plane, before (median / min) | after | transient, before | after | -|---|---|---:|---:|---:|---:| -| radial, memory | driver | 2.7 / 2.0 | 1.6 / 1.3 | 0.14 | 0.13 | -| radial, memory | native | 3.1 / 1.7 | 0.9 / 0.5 | 2.67 | 0.00 | -| radial, file | driver | 6.7 / 6.1 | 5.6 / 4.9 | 2.67 | 0.13 | -| radial, file | native | 7.7 / 6.2 | 5.7 / 4.4 | 5.21 | 2.54 | -| Cartesian, memory | driver | 72.2 / 33.2 | 16.3 / 14.8 | 0.29 | 0.42 | -| Cartesian, memory | native | 393.7 / 92.2 | 33.8 / 32.6 | 108.47 | 0.00 | -| Cartesian, file | driver | 212.9 / 158.8 | 138.5 / 134.4 | 108.54 | 0.55 | -| Cartesian, file | native | 398.8 / 213.9 | 158.5 / 153.2 | 216.92 | 108.25 | - -The radial field is 2.5 MiB a plane, the Cartesian 108 MiB. The native session's file -case still holds one field for h5py; its memory case holds none. Each kept plane is one -native export (`status().exports`) in both builds. The machine's load fell from 100 to -210 during the baseline to 6 to 65 after, so part of the times' fall is the load's; the -transient bytes do not depend on it. The run's peak traced memory with the native -session fell from 650 to 542 MiB in memory (one field fewer) and stayed -217 MiB into a file, where a peak outside the planes sets it. - -**The conversion alone.** At the launch plane, each variant into a fresh zeroed row -(first touch included, as in a run), 15 interleaved repeats, milliseconds median / min: - -| case | native, two steps | native, one export | host, two steps | host, one pass | -|---|---:|---:|---:|---:| -| radial (2.5 MiB) | 0.76 / 0.68 | 0.28 / 0.24 | 0.47 / 0.44 | 0.47 / 0.44 | -| Cartesian (108 MiB) | 76.49 / 50.18 | 64.65 / 36.34 | 35.33 / 14.68 | 29.64 / 14.46 | - -The native fused pass took an integer division per element for `(-1)^k` until this -change; row by row it is 6.5 times faster on the radial plane and beats the two steps on -both. It is single-threaded: on the 108 MiB plane the host's threaded pass (36 ms -against 14.5 ms at the minimum) is faster, so threading the native pass is the next -step there. On the host the one pass and the two steps cost the same. - -### Single-precision collar and batches - -[#428](https://github.com/LupoLab/solprop/pull/428) keeps the reference backend's split -collar (`apply_temporal_rate`) in binary32 under single precision, as the correction -`a + F(F^-1(a)(f - 1))`; before, the product promoted to binary64 and was narrowed. Its -single-precision batches now run through the plain `LockstepRunner`, each member its own -binary32 trial; before, `NumpyBatchBackend` computed them in binary64 and narrowed the -result, so the before column is the wrong arithmetic's cost and the fields are not -compared. `ab` selects neither a precision nor a batch, so both were timed by the hand -script above, same machine and builds (`main` at `76eb2e57`, then #428 merged), one -thread, `numpy_ref`, on the same soliton. - -**The collar**, 5 mm of `RungeKutta()` (43 accepted steps, one collar pass each), -`absorber_scheme="split_step"`, four rounds of five repeats: - -| bins | before → after | ratio | A/A | -|---:|---:|---:|---:| -| 1536 | 34.0 → 34.0 ms | 1.003 [0.999, 1.169] | 0.993 [0.957, 1.003] | -| 16384 (8 ps, 300 nm–4 µm) | 183.1 → 180.2 ms | 0.989 [0.971, 1.019] | 0.992 [0.960, 1.020] | - -The pass alone, same process (best of seven times 200 calls): 18.3 → 15.9 µs at 1536 -bins and 191 → 125 µs at 16384, 2–5 % of a step, which the runs do not resolve. - -**Batches**, ten fixed steps over 2 cm with no collar, members 1 % apart in peak power, -the stepping alone timed (`propagate_to`; the members' construction is not): - -| bins | members | rounds | before → after | ratio | A/A | -|---:|---:|---:|---:|---:|---:| -| 1536 | 4 | 4 | 29.8 → 30.1 ms | 1.003 [0.963, 1.029] | 1.025 [1.011, 1.059] | -| 1536 | 16 | 4 | 116.5 → 122.3 ms | 1.048 [1.036, 1.075] | 1.028 [0.958, 1.072] | -| 1536 | 16 | 8 | 136.5 → 141.5 ms | 1.059 [0.984, 1.119] | 0.981 [0.930, 1.030] | -| 16384 | 8 | 8 | 496.6 → 389.7 ms | 0.779 [0.676, 0.852] | 0.971 [0.890, 1.017] | - -On a small grid with many members the member-by-member trials cost 3–6 %, at the edge of -the A/A spread; on a 16384-bin grid they are 22 % faster, binary32 transforms replacing -the binary64 ones. What vectorising over the members is worth was read from the binary64 -batch, `NumpyBatchBackend` against `LockstepRunner` on the same members (unpaired medians -of the same runs): 108.7 against 117.5 ms (16 members, 1536 bins) and 469 against 491 ms -(8 members, 16384 bins), 4–8 %. A vectorised binary32 batch would recover at most that, -so the reference keeps the plain runner. +At maximum order five the native resident Adams engine held 29 complex field volumes, +eleven of them dense-output slopes and saved fields; allocating those only for +`interpolate_planes=True` reduces it to 18 ([backends.md §8](backends.md#8-memory-ledger)). +Peak resident memory of a reduced-resolution `kerr_beam_384` (600 temporal bins, four +threads, an 18-core arm64 laptop, recorded by 2026-10-23, model not recorded) fell from 7.53 to +5.92 GiB at 128² and from 28.2 to 21.8 GiB at 256², and is projected from 62.7 to 48.2 GiB +at 384². Field export adds a further host copy; no field-sized workspace scales with the +thread count. + +## Boundaries + +### The transverse edge + +Each backend reduces the boundary monitor's numbers where its state lives: one check costs +an inverse transform of the state and a pass that sums it. After SEP 44's native read and +the growing backstop (`L/16` doubling to `L/4`), the default check added 2.6–3.6 % to +`line`, 9.1 % to `planar` and 3.9 % to `radial_filament_256` against no ramp and no reads, +at 18 threads of an Intel Xeon Gold 6240 (2026-11-08). On a device, a 768 × 768 × 600 Kerr +point with the check on took 1.30 times its time with it off on an NVIDIA H200 and 1.34 on +an AMD Instinct MI325X, an edge read 25 and 31 ms (2026-11-05). Bound threads overstate the +host's share: SciPy's transforms then take the main thread's single core (0.48 s with 16 +workers against 0.11 s unbound on a 384² × 256 array, AMD EPYC 7763, 2026-11-04). ### A spectral walk-off absorber against the temporal collar What the [spectral walk-off absorber](../guide/numerics/boundaries.md#a-spectral-walk-off-absorber) -saves is the temporal pass, which a zero temporal rate compiles away; this entry says what -that is worth, in place of a figure measured on a backend since retired. A hand script, on the -one grid, one backend and one build: a field grid over 40 µm of fused silica, 143 nm to 2 µm, -`trange` 250 fs at the default `collar_fraction`, so a 326 fs window of 2048 samples; envelope -Kerr, an 800 nm 30 fs launch; ten fixed `RungeKutta()` steps of 1 µm, each case translated once -beforehand and the runs alone timed. The cases are the default collar under each scheme, and -`custom_absorber(grid, rate, collar=absorber(grid, temporal=False))`. Native CPU, eight threads -bound to eight cores of a dual Intel Xeon Gold 6240 (18 cores a socket), built for -`-march=cascadelake`. The machine was shared and in use (load 16–58 of 72), so these are to be -read as ratios of medians, and each is given over its separate sessions, cycling the three cases -within a session: - -| grid | sessions (repeats) | spectral / `split_step` | spectral / in-stage | -|---|---:|---:|---:| -| line, 256 columns | 2 (5, 9) | 0.92, 0.90 | 0.58, 0.53 | -| Cartesian, 64 × 64 | 2 (5, 5) | 0.91, 0.89 | 0.47, 0.53 | - -Single runs carried outliers of up to three times the median, which the median sets aside. The -ratio against the split repeats to within 3 %; the one against the in-stage term less well, -between 0.47 and 0.58. Over these ten steps the three runs' fields agree to 1e-15 of the on-axis -column's norm inside the request, because no light has reached a collar: the entry times the pass -and compares no absorption. It is a window, and the temporal pass's share of a step moves with -the response's: a heavier response gives a smaller saving. - -### The default check on a device: reads, occupancy and sums - -A field-free point of a free-space Kerr beam at 768 x 768 x 600 (5.27 GiB), eight fixed low-storage -RK4IP steps and four planes, with a stated input identity, took 12 to 7 times as long -with the default `boundary_check` as without it. `python -m benchmarks.device_split 768`, the second point -of one `SimulationRunner`, on an NVIDIA H200 (CUDA 13.1) and an AMD Instinct MI325X (ROCm 10). Before is -`7a224ea5`, measured the same way that morning with the probe that became this module, on another machine -of the same type; after is this entry's commit, both cards the same day: - -| | H200, before | H200, after | MI325X, before | MI325X, after | -|---|---:|---:|---:|---:| -| Point, `boundary_check=None`, s | 5.9 | 5.7 | 4.2 | 3.8 | -| Point, default check, s | 70 | 51 | 29 | 14 | -| State crossings in a point | 13 | 9 | 13 | 9 | -| `monitor.occupancy`, one reading, ms | 184 | 10 | 1,240 | 13 | -| `energy` statistic, ms | 55 | 2.3 | 80 | 6.6 | -| `peak_intensity` statistic, ms | 134 | 77 | 164 | 86 | - -What changed: a saved plane that the step reaching it already read takes no second read, which was a whole -state's copy thrown away; a replay decides its reads by its next step, not by `dz_init`; the occupancy is -a reduction per column, without an atomic per element; `energy`, the peak and a low-storage step's norm are real -reductions, not sums on one thread of a device; a runner's points share the occupancy's table; an -Adams run past its snapshot limit takes no snapshot to learn its size. - -HIP's smallest block is 64 threads, and a reduction's value has to fit `(64 + 2) * sizeof(value)` of 64 KiB -with the kernel's own static memory beside it, which Kokkos's check doesn't count. So a reading there holds 64 -buckets a pass and takes two passes of 6.4 ms, not one of 128: 124 passed Kokkos's check and the dispatch then faulted -("Illegal opcode in command stream"). On a CPU, `python -m benchmarks ab` against `main` on an Intel Xeon Gold 6240 -at 1 and 16 threads, three rounds, on `kerr_beam_192`, `line` and `planar`: geometric mean 1.002, each case -within 4 %, fields to 1.5e-15, the same work. - -The check still reads a host copy of the state, on the host, which is what is left of its cost above: the -entries that follow take that. - -### The state's crossing: a ring of pinned chunks - -A state crossing to the host was slow for one reason: a fresh pageable buffer takes its first touch inside the -driver's copy, 1.38 million page faults at 768 x 768 x 600. A bare copy of 5.27 GiB, in GiB/s: - -| | NVIDIA H200 | AMD Instinct MI325X | -|---|---:|---:| -| Fresh pageable buffer, as it was | 1.8 | 7.9 | -| Reused pageable buffer | 16.5 | 52 | -| Pinned, which is the link | 51.5 | 52.6 | -| 64 MiB pinned ring, a worker per host thread, fresh huge-page destination | 33 | 50 | -| The same ring, no huge pages | 25 | 33 | - -Every state-sized crossing now takes that ring, both ways. `python -m benchmarks.device_split`, against the previous -entry's commit, the same day, on the same cards and window: - -| | H200, before | H200, after | MI325X, before | MI325X, after | -|---|---:|---:|---:|---:| -| `field_to_host`, 5.27 GiB, ms | 2,929 | 175 | 506 | 107 | -| Its page faults | 1,382,401 | 2,758 | 1,382,401 | 2,755 | -| The point's crossings together, s | 26.5 | 1.6 | 4.3 | 0.96 | -| Point, default check, s | 51 | 25 | 14 | 9.7 | - -Against `main`, with the previous entry, `python -m benchmarks ab --device` on `kerr_beam_384`, three rounds of one repeat, -which saves its fields: H200 13.451 → 4.672 s, ratio 0.347 (0.347–0.349); MI325X 5.700 → 2.033 s, ratio 0.359 -(0.338–0.362). Fields identical and the same work on both. On a longer window, 384 x 384 x 600 with 51 steps and 17 planes, -the point with the check takes 14.2 s against 3.9 s without on the H200 (49.8 s before these two entries), and 7.1 s against 3.7 s on -the MI325X. The NVIDIA A40 sees less (PCIe Gen 4): 183 → 147 ms at 384 x 384. - -A kept plane's conversion and its finiteness check take threads too, above `PARALLEL_BYTES`, and a plane converts straight -into the store's block rather than through a copy. A state under `ring_threshold`, 256 MiB, takes no ring, and -`memory_ledger`'s `host_crossing_ring` stays zero, which a device test holds. A larger state's load allocates it, even in a run -that keeps no field: 64 MiB of pinned host memory per host thread, 1.5 GiB on 24. - -On a CPU a crossing is a plain copy and takes no ring. `python -m benchmarks ab` against `main`, with the previous entry, on an Intel -Xeon Gold 6240 (18 cores of one socket, passive threads, three rounds of one repeat, a shared machine): `kerr_beam_192` 0.976 -at one thread and 0.882 at sixteen, `radial_filament_256` 0.999 and 0.994, `line` 0.983 and 0.990, `planar` 0.997 and 0.980; geometric -mean 0.975, fields to 4.2e-15, the same work. - -### A plane's widths and its axis where the field lives - -`beam_radius` was the costliest statistic on a device by far: about 1.0 s a call on an NVIDIA H200 and 0.9 s on an -AMD Instinct MI325X at 768 x 768 x 600 (`python -m benchmarks.device_split`), against 77 and 86 ms for `peak_intensity` -and about 230 ms for a step. A width ran `peak_intensity`'s kernels and copied 9.4 MiB, so most of that second lay in what -else it did, and it did two things: - -- **A sum per bin over every column.** A separable width formed the axis's fluence, which only a radial width reads, - through the kernel `on_axis_intensity` uses: for each of the 600 bins, twice, one work item walking all 589,824 columns - in turn. It has the shape of the `energy` kernel an earlier entry replaced, a single thread's walk across the plane. -- **The azimuthal average in Python, on one host thread.** About 3.7 million bilinear samples, 0.23 s on an Intel Xeon - Gold 6240. - -On that CPU the two make up about 80 to 90 % of what a width took beyond `peak_intensity` (the table's "before" columns: -the axis's row plus 64 or 240 ms). Both are gone. A width no longer forms the axis's fluence, and `on_axis_intensity`, -which the default spec asks for, reads the same sums from the far-field pass's team-local bands, the slots -`on_axis_spectrum` reads. A separable fluence takes no time transform: by Parseval's theorem it is a sum over the bins -that the transverse volumes already hold. On a Cartesian plane the centroid, the second moment and the rings are -kernels too, so that about 780 values cross at 768 x 768, not 1.18 million. The on-axis plasma statistics read their row -natively, not a copy of the state, and `species_statistics` lost a Python loop over the nodes that took 0.2 s per -species at 768 x 768, with its additions unchanged. - -**None of this is measured on a device.** That these two make up the devices' second is inferred from the CPU's split -and the kernels' shape. `python -m benchmarks.device_split` now reports `on_axis_intensity`, `fwhm_r`, the default spec, a -width's native moments and the same azimuthal average on the host, which will settle it. - -On a CPU: one call, the median of at least three after a warm one, of the launch of that module's Kerr beam, against -`facf2b23`, on an Intel Xeon Gold 6240 shared with other work, in ms: - -| | 768 x 768 x 600, 9 threads, before | after | 384 x 384 x 600, 9 threads, before | after | 192 x 192 x 600, 1 thread, before | after | -|---|---:|---:|---:|---:|---:|---:| -| `energy` | 226 | 208 | 55 | 54 | 114 | 111 | -| `beam_spectrum` | 657 | 600 | 162 | 150 | 307 | 315 | -| `on_axis_spectrum` | 873 | 743 | 193 | 184 | 381 | 388 | -| `absorbed_power` | 741 | 733 | 186 | 181 | 373 | 378 | -| `on_axis_intensity` | 3,224 | 746 | 686 | 194 | 818 | 429 | -| `peak_intensity` | 6,567 | 6,467 | 1,688 | 1,556 | 2,037 | 1,992 | -| `beam_radius` | 10,863 | 3,507 | 2,528 | 788 | 2,861 | 804 | -| `fwhm_r` | 11,119 | 3,532 | 2,501 | 784 | 2,858 | 803 | -| The default spec | 11,341 | 8,437 | 2,606 | 2,061 | 3,448 | 3,040 | - -The two builds' widths of that state agree to 7e-15 at 768 x 768. A whole run moves little, since these take one plane. -`python -m benchmarks ab` against `facf2b23` on the same machine, complete runs, passive threads, one repeat, median and -range over the rounds, the same work and identical fields in every row: - -| case | 1 thread, three rounds | 9 threads | -|---|---:|---:| -| `kerr_beam_192` | 0.969 (0.891–0.988) | 1.004 (0.997–1.019), five rounds | -| `kerr_beam_384` | | 1.015 (0.970–1.193), three rounds | -| `line` | 0.913 (0.879–1.047) | 1.005 (0.948–1.065), five rounds | -| `planar` | 1.022 (0.972–1.028) | 1.030 (0.833–1.084), three rounds | -| `radial_filament_256` | 1.024 (1.000–1.041) | 1.056 (1.014–1.106), three rounds | - -Other work shared the machine during the three-round rows, which is their spread. The five-round rows repeat two of them -when it was quieter, 1.076 and 1.077 before. `planar`'s and `radial_filament_256`'s statistics took only the small change -to their packed output and fluence, and the same comparison before the on-axis change gave 1.003 and 0.999 at 9 threads. - -### A device step beyond its transforms - -A low-storage step of the Kerr beam of `python -m benchmarks.device_split` at 768 x 768 x 600 with no boundary check, as `LowStorageRungeKutta` runs it on the Cartesian -route, was 239 ms on an NVIDIA H200 and 224 ms on an AMD Instinct MI325X, 112 to 144 ms of it in its eight rank-3 transforms. These changes take what lies beside them. -**No data-centre card was run for this entry.** Its numbers are launch counts, which do not depend on the card, and times on an NVIDIA A40 (CUDA 12.8.1, `AMPERE86`, an -AMD EPYC 7543 host, 16 threads), whose binary64 rate is a sixty-fourth of its binary32 rate, so its share of each kernel says little about an H200. They were taken at -`cb2cb068` against the merge base `43ddefab`, by a Kokkos Tools trace of that one case with a fence around each kernel. - -| Per step, 768 x 768 x 600 | Before | Collar in place | A whole state, tried and dropped | -|---|---:|---:|---:| -| Kernels | 330 | 119 | 14 | -| Transforms | 220 | 220 | 10 | - -| NVIDIA A40, ms per step | Before | After | -|---|---:|---:| -| Eight rank-3 transforms | 1,840 | 1,840 | -| The collar's transforms | 142 | 136 | -| The collar's copies in and out | 41.4 | none | -| The collar's factor and band mask | 21.0 | 22.0 | -| Fold, passes 1 to 4 | 134, 64, 129, 123 | 121, 62, 115, 109 | -| Kerr | 118 | 118 | -| Input | 42.5 | 24.9 | -| Whole step, no fences | 2,660 | 2,557 | - -The whole step takes 0.961 of its time at 768 x 768 x 600 and 0.956 at 384 x 384 x 600 (589 to 563 ms): three interleaved rounds of fresh processes, whose medians spread by -0.1 %. `python -m benchmarks ab --device --length 0.3` against the merge base, three rounds, the same steps: `kerr_beam_384` 0.974 (0.972–0.995), `kerr_beam_192` 1.030 -(0.954–1.036, a window of two steps, inside its spread), fields to 3.3e-16; `rdw` 1.000, `he_rdw_averaged` 1.002, `radial_filament_256` 1.000, fields bitwise. - -**The collar** depends on time alone, so its transform pair runs in place on the state's own rows, with the normalisation on the factor. Most of the A40's gain is the two -copies gone at the node chunk: 2,578.6 ms a step, against 2,574.6 for a whole state on the same build. The "After" column and the `python -m benchmarks ab` figures above were -taken with a whole state, which a device took by default until the cards were measured. - -**A whole state was dropped.** It saves launches, and #361 asks 10 % of a default-memory change. At 768 x 768 x 600, 8 steps, at `9a5d2346`, the median of three runs on one runner in one process, whole -state first and not interleaved, against the node chunk: NVIDIA H200 2.661 s against 2.671 s, x0.996; AMD Instinct MI325X 2.023 s against 2.068 s, x0.978. So a device keeps the -node chunk, and `Transform` needs no field to tell a stated budget from the default. It wouldn't have cost memory either: the plans' device growth was the same to 6 MiB on both -cards, and cuFFT's work area is small (at 589,824 rows of 600 points each plan holds 9 MiB, in place or not, 0.1 MiB at the node chunk). A CPU keeps the -chunk for its own reason: on an Intel Xeon Gold 6240, nine cores, at 384 x 384 x 600, FFTW's threaded plan of a whole state took 2.5 s a step in transforms against 1.5 s. - -**A whole state again.** #361's 10 % is asked of a change that costs default memory, and this one costs none, so the maintainer asked for it back if an interleaved run on an AMD card shows a consistent gain. A device now takes every row at once whatever the node budget, with no seam field: in place, the block's only memory is its plans' work area. On an NVIDIA A40, CUDA 12.8.1, `python -m benchmarks ab --device --length 0.3`, 3 rounds, against the same tree at the node chunk, the same steps and final fields with no difference: `kerr_beam_384` x0.989 (0.958–0.994), `kerr_beam_192` x0.971 (0.951–1.065), and every route without the collar between x0.998 and x1.004. On an AMD Instinct MI300X, ROCm 10.0.0, at `c0bd23f2` against the same tree at the node chunk: a field-free point of 8 steps with the check off, the median of a runner's second and third runs, three interleaved rounds of fresh processes. At 384 x 384 x 600 the rounds give x0.990, x0.988 and x0.990 (0.576 to 0.569 s), and at 768 x 768 x 600 x0.984, x0.983 and x0.986 (2.172 to 2.138 s), with the plans' memory the same. `ab --device --length 0.3`, 3 rounds, gives `kerr_beam_384` x0.952 (0.912–0.999), with the final fields identical. Every round gained, so it stays, though at about 1.5 % of a point it is far from #361's 10 %. - -**The fold.** A flow's magnitude on a lossless bin is `exp(+-0)`, exactly one, and took a binary64 `exp` per element: 13.4 ms a pass on the A40, whose reduced binary64 rate -overstates it. Runge-Kutta's `stage_input` and `finish_transform` fall by 13 % the same way. The flowless pass forms no exponent (64.3 to 61.5 ms). The first input crosses the -plane's stride through tiles of team scratch (42.5 to 24.9 ms). On a host the branch is out of line: inlined there, it took the tabulated fold's kernel past GCC's inlining limit, -though a tabulated fold never takes it, every pass 40 % slower and `kerr_beam_384` 1.056. - -**Dropped, for no gain on the A40.** Pass 3's dead read of register A: the fourth pass took 13.5 ms less against 13.4 for the other flows' `exp`, so the read is worth 0.1 ms. -Folding `finish` into the step: the mask it would fold is 1.5 ms of a step on the A40, and a collar's kernels cannot fold. A Kerr pass over a two-dimensional range instead of a division per element: -117.9 ms either way. The modal routes' two accumulator stores in an Adams trial: 0.997 to 1.000, inside the spread. `weighted_error`'s mirrors: 0.114 to 0.099 ms a call at -32 x 32 and 10.8 to 10.7 at 384 x 384, on the rare controller that has one. - -**The Adams trial.** A Cartesian route's source no longer accumulates its stage (3.4 of 199 ms a trial at 256 x 256 x 600, 186 ms with the collar and the flows), and the -interaction formulation's fused trial swaps the state aside rather than copying it twice: `ab --device --stepper multistep-interaction`, three rounds, `rdw` 0.994 (0.979–0.994), `he_rdw_averaged` 0.988 (0.878–0.989), -`argon_blueshift_averaged` 0.978 (0.975–0.979), `radial_filament_256` 0.993 (0.990–0.995), fields bitwise. - -**A Runge-Kutta trial.** The accept is one reduction on a device as on the host (26.4 to 23.4 µs a trial on `he_rdw_averaged`, 71.8 to 60.8 on `radial_filament_256`), and its -partials cross through a persistent pinned mirror (16.8 to 8.8 µs a trial), the ledger's `trial_norms` row, 13.5 MiB at 768 x 768 on the host's pinned memory, outside a low-storage run. `ab --device --stepper rk`, five rounds, -against the build before them: `he_rdw_averaged` 0.988 (0.986–1.007), `rdw` 0.996 (0.988–0.996), `radial_filament_256` 1.001 (0.999–1.036), fields bitwise. - -**The Adams read-back** (#362) is about 2.8 µs a trial from its last kernel's end to the host's return, by an `nsys` trace with graph nodes on the A40: 1.2 % of a 237 µs `he_rdw_averaged` trial, 0.5 % of -`rdw`'s 586 µs, 0.1 % of `radial_filament_256`'s 3.3 ms, at most 14 µs at the 90th percentile. That is well below #362's 20 %. - -**Scratch-order registers on the volume route**, tried on the A40 and not adopted, take the fold from 407 to 387 ms and the step to 2,538 ms, with the fold's tile staging the state rather than the scratch. A layout change needs its own issue. - -**The scratch in the registers' order** ([#365](https://github.com/LupoLab/solprop/issues/365)), on a device. A stage of the volume route views the scratch as `(y, x, omega)`, the state's and the -registers' order, so its rank-3 pair is cuFFT's frequency-fastest `{N,N,T}`, and its input and fold stream instead of crossing. A probe of the two orders on an NVIDIA H200, CUDA 13.1, -T = 600, took `{N,N,T}` 2.49, 11.08, 14.71, 17.62 and 13.81 ms a transform at N = 384, 750, 768, 800 and 900, against 3.74, 14.97, 17.63, 17.97 and 18.96 ms for `{T,N,N}`, and `{N,N,T}` -needs no work area at those sizes but 768. A step, from a field-free point with the check off, (24 steps - 8 steps) / 16, three interleaved rounds against the build before it -(`c0bd23f2` against `8e9b4e76`): - -| N x N x 600, NVIDIA H200 | Before, ms | After, ms | Ratio | A run's memory, GiB | -|---:|---:|---:|---:|---:| -| 384 | 50.96–51.17 | 36.22–36.49 | 0.713 | 7.23 → 5.91 | -| 768 | 225.21–225.78 | 203.88–204.13 | 0.905 | 23.14 → 23.14 | - -At 768 the transforms account for it: eight of them are 23.4 ms apart in the probe, and the step gains 21.6 ms. `python -m benchmarks ab --device --length 0.3`, 3 rounds: -`kerr_beam_384` x0.971 (0.928–1.003), fields to 3.2e-17. On the NVIDIA A40, CUDA 12.8.1, where the orders are within 1 % at 768, two rounds against `29e9e156`, whose native code is -the same: 2,535 and 2,578 ms a step before, 2,556 and 2,597 after, at 768; 559 and 560 ms before, 513 and 513 after, at 384; `ab --device` geometric mean 0.998, with `kerr_beam_384` -x1.010 (0.997–1.042) and `kerr_beam_192` x0.977 (0.950–1.070). The device tests pass on both cards. With the stage's window read in the old order, nine of them fail across the three -marches, and with the fold reading the old order, three low-storage ones do. - -**On HIP too.** On an AMD Instinct MI325X, ROCm 10.0.0, `gfx942`, rocFFT's two orders take the same time. In place, Z2Z, T = 600, frequency innermost (rocFFT lengths -`{T,N,N}`, cuFFT's `{N,N,T}`) took 4.07, 15.66, 15.31, 16.72 and 20.94 ms a transform at N = 384, 750, 768, 800 and 900, against 4.10, 16.20, 15.31, 16.69 and 20.35 ms with x innermost. Both -need one state of work area at every one of those sizes. The step gains all the same, from the input and fold that no longer cross layouts. Three interleaved rounds, the same method, -against #542's head (`931ac0dc`): - -| N x N x 600, AMD Instinct MI325X | Before, ms | After, ms | Ratio | A run's memory, GiB | -|---:|---:|---:|---:|---:| -| 384 | 57.30–58.02 | 51.80–52.20 | 0.902 | 7.009 → 7.013 | -| 768 | 210.00–211.22 | 198.87–199.73 | 0.946 | 23.37 → 23.37 | - -At 768 eight transforms are the same in the probe, so all of the step's 11.8 ms is in the passes beside them. `python -m benchmarks ab --device --length 0.3`, 3 rounds: `kerr_beam_384` -x0.978 (0.974–0.982), fields to 1.8e-17. `pytest -m gpu` (251 passed, 1 skipped), the native device tests (31 passed) and the affected modules (172 passed, 3 skipped) pass on that -card in the new order. - -On a CPU, `python -m benchmarks ab` against the merge base on an Intel Xeon Gold 6240 (nine cores of one socket, bound passive threads, on a machine others shared; three rounds, the same steps): `kerr_beam_192` 0.982 (0.978–0.996) at one thread and 0.974 (0.973–0.987) at nine; `kerr_beam_384` 0.981 (0.981–0.982) at nine, fields to 6.4e-16. -`rdw` under `rk` and `multistep-interaction`, one and nine threads, without the host's fold fix, which they do not reach: 1.011, 0.974, 0.996 and 0.999. -Before the fold's fix, `radial_filament_256` 0.993 and `planar` 0.980 at nine threads, five rounds, took neither path. - -The H200 has since measured the step in the scratch's order, above. An AMD Instinct MI300X has measured what rocFFT's plans hold and what a whole state's collar is worth, and an MI325X the step and the device tests with HIP in the scratch's new order, above. - -### `mlx` against `native` on an Apple M5 Max - -Single precision on `mlx` was slower than binary64 `native` on the helium RDW capillary, -by 3.7 times as each backend runs it by default and 4.7 mode-averaged. Four causes, -each measured on an Apple M5 Max (MLX 0.32.4) shared with other work, so ratios only, -interleaved: - -- **Grid sizes.** `fft_size="auto"` took FFTW's 2-3-5-smooth sizes; MLX's GPU FFT is - direct at every smooth size up to 4096 and at powers of two, and takes Bluestein's - algorithm elsewhere: an rfft and irfft pair at 10240 took 715 µs, at 16384 63 µs. The - keyword interfaces now size a single-precision `mlx` run's grid with MLX's costs - (`grid.fft_cost(n, "mlx")`); one mode-averaged RDW trial went from 18.6 to 4.66 ms. -- **Launches.** A DOPRI5 trial was about 2000 graph nodes, half of them launches of - about 10 µs. Each stage is now one `mx.compile` graph, bitwise the eager one; one - trial, op by op against compiled: `he_rdw_averaged` 5.30 against 2.91 ms, `rdw` 7.76 - against 4.76, `radial_filament_256` 14.1 against 6.88, `spatial_absorber` 3.69 against - 2.38, `kerr_beam_192` 246 against 131, `cartesian_filament_128` 806 against 316. - Starting each stage as it is built took another 7 to 12 %. -- **The integrator.** Single precision refused Adams, so `mlx` stepped DOPRI5 where - `native` stepped Adams. Adams is admitted now (#342) and runs on the device - (`MlxAdams`): warm, a four-mode `rdw` step is 1.48 ms. -- **Host statistics.** A plane's field-grid plasma statistics scanned every node on the - host in binary64: 37.7 s of a 50.6 s tenth of `cartesian_filament_128`. On the device - with the stage's kernels the run took 21.5 s, and an RK trial there is 223 ms on - `mlx` against 511 ms on `native` at all cores. - -`python -m benchmarks ab --baseline-backend native --candidate-backend mlx`, a third -of each case, two rounds, the ratio `mlx`/`native` (below one, `mlx` faster): - -| case | before, each default | after, each default | after, Adams on both | -|---|---:|---:|---:| -| `rdw` | 3.72 | 1.24 | 0.84 | -| `he_rdw_averaged` | 4.72 | 2.40 | 1.68 | -| `radial_filament_256` | 1.10 | 0.45 | 0.42 | -| `spatial_absorber` | 0.71 | 0.80 | 0.27 | -| `cartesian_filament_128` | 2.50 | 0.79 | | - -The single-precision default is still Runge-Kutta, so on the capillaries the middle -column sets `mlx`'s DOPRI5 against `native`'s Adams. Whole runs, RK at `rtol = 1e-4`: -`radial_filament_256` 0.67 s on `mlx` against 2.07 s on `native`, `spatial_absorber` -1.98 against 5.54. The short runs' ratios carry the planes' shared host statistics -(12 planes) as a fixed cost. `kerr_beam_*` was refused on `mlx` past a tenth of its -length: over its 0.5–0.6 µm steps the spectral collar reaches `|Re ΔΦ|` of 150–180, -past binary32's 88.7. Its low-storage march applies forward flows only, which a damped -bin underflows harmlessly, so binary32 now holds it to growth alone; with the edge read -on the device and the operator built once, whole runs take 1.05 s on `mlx` against -2.64 s on `native` (192²) and 7.72 against 9.43 s (384²), the fields 2e-7 apart. - -### Machine calibration against the built-in table (SEP 46) - -[SEP 46](seps/archive/sep-0046-machine-calibration.md) section 7 items 1–4. On each machine a -thorough calibration, then the tracking set calibrated against the built-in table -(`benchmarks ab`, a fifth of each case, three rounds of one run, both arms as default -runs: no thread count of their own, `SOLPROP_CALIBRATION=off` against `use`), an A/A -control of the same command, and a second calibration. Sixteen cores of each machine -unless stated; fields equal to rounding in every row. - -The first rules failed. A candidate was scored by the geometric mean of five small -problems, and the FFT stage's fallback published stored wisdom untested: -- **Google Axion (C4A):** a team of 8 won the small problems by 16 % and ran the large - cases slower (`kerr_beam_384` 1.82, `kerr_beam_192` 1.73, `radial_filament_256` - 1.35, `grin_nonlinear` 1.28, `ctc` 1.07); geometric mean 1.094. -- **AMD EPYC 9B45 (C4D):** the stored FFT wisdom ran `h2_raman_averaged` 1.18 times - slower (1.17 with the wisdom alone, 0.99 with the efforts alone): a 4608-point plan - chosen alone in the capture ran slower in the step than one measured in place. A full - width from 98304 elements (`fft_full`) ran `grin_nonlinear` 1.08–1.10 slower, and on - an AMD EPYC 7763 1.087. - -Revised rules: no problem may be slower than its noise plus 5 % (the run below used -2 %), four production-sized problems join the standard and thorough levels, FFT -planning is compared with the plan policy and published only when an effort wins, and -the transforms' thresholds stay at the table (#587). With them: - -| machine | calibration chose | geometric mean | A/A | slower than A/A + 2 % | -|---|---|---:|---:|---| -| Google Axion (C4A), three runs | medium width 8, Raman and copy thresholds | 0.965, 0.964, 0.968 | 1.000 | none | -| AMD EPYC 7763, exclusive node, one NUMA domain | the table (no grain move won) | 1.003 | 0.991 | none | -| AMD EPYC 9B45 (C4D), Windows Server 2025, the CI wheel | the table, twice | — | — | — | -| AMD EPYC 9B45 (C4D), Linux (5 % bar) | the table; a copy threshold in the second | — | — | — | -| Intel Xeon Gold 6240, one socket (18 cores) | the table, twice | — | — | — | -| Intel Xeon Platinum 8581C (Emerald Rapids, C4), 12 cores (5 % bar) | medium width 8, Raman and copy thresholds, twice | 0.989 | 0.996 | none | -| the same, at the quick level (first use) | medium width 8 | 0.999 | 0.996 | none | -| Apple M5 Max, six top-tier threads (5 % bar) | a Raman threshold of 8193, twice | 1.012 | 1.000 | none that the profile changes | - -On the Axion the gains are on the few-mode and Raman cases: `gnlse_raman_shock` -0.85–0.86, `he_rdw_averaged` 0.90–0.91, `argon_blueshift_envelope` 0.91–0.92, `ctc` -0.93–0.94, `argon_blueshift_averaged` 0.94–0.95; the large cases stay within -0.99–1.01. The team of 8 was refused on the production-sized radial problem -(1.17–1.18). The last run's two calibrations chose the same settings; earlier second -calibrations found the grain inconclusive and kept the table. - -Where the calibration chose the table, the A/B would compare the table with itself and -was not run (or, on the Xeon, measured only the shared machine's noise). - -The two machines the table was never tuned on, the Axion and the Emerald Rapids, chose -the same grain; on the Emerald Rapids `ctc` ran 0.87 and `gnlse_raman_shock` 0.94 (the -quick level, the medium width alone: `ctc` 0.90). Its second calibration also admitted -`threaded_rows measure`, under the FFT stage's earlier base (every plan at estimate), -since corrected; it was not A/B'd. - -Every machine refused passive waiting: 1.94 (Emerald Rapids), 1.10–1.11 (Axion), 1.16–1.23 (EPYC 7763), -1.25–1.27 (EPYC 9B45 Linux), 1.18 (Windows), 1.25 (Xeon), 1.74–1.78 (Apple M5 Max). On -the Apple M5 Max, under the first rules, two calibrations kept six top-tier threads and -admitted a Raman threshold of 8193; the A/B was 1.002 and 1.008 (`h2_raman_averaged` -1.04, the stored wisdom). Under the revised rules it chose the Raman threshold again, -twice, and no planning. The Raman cases did not move (`gnlse_raman_shock` 1.011, -`h2_raman_averaged` 1.001); `argon_blueshift_averaged` 1.155 and -`argon_blueshift_envelope` 1.088 ran the same computation in both arms (fields equal), -within the M5 Max's A/A range on those cases (0.89–1.12). ADR-073's table already fits -this chip. Inconclusive sessions published nothing: the EPYC 9B45 at -16 cores on two earlier VMs (A/A 35 % and 15 %; a third VM's session was conclusive at -2 %, and its table-against-table A/B spread 0.60–1.52 per case), the shared Xeon (23 %), the EPYC 7763's second session -(31 %). - -### Scan workers calibrated on an AMD EPYC 7763 node (SEP 46) - -[SEP 46](seps/archive/sep-0046-machine-calibration.md) section 7 item 14, a scan's workers. One -whole node of two AMD EPYC 7763 (128 cores, 8 NUMA domains), exclusive, GCC 16, commit -`ad1df42e` of #582. The workload is an RDW tuning scan: a four-mode helium capillary -(125 µm core radius, 5 cm, 7.5 fs at 800 nm, plasma) over pressure (0.6–1.2 bar) and -energy (150–275 µJ), run by `run_scan` on `Pool`. Each arm is one scan, in three rounds -of shuffled order: `table` (`SOLPROP_CALIBRATION=off`: workers wait passively), `spin` -(the table with `GOMP_SPINCOUNT=10000`, so workers spin) and `calibrated` (`auto`, after -one warm-up scan that calibrated the workers' allocation). Wall seconds: - -| config | table | spin | calibrated | warm-up (calibrating) | -|---|---|---|---|---:| -| A: 128 workers × 1 thread, 20 × 20 points | 464, 690, 415 | — | 505, 496, 459 | 577 | -| B: 4 workers × 4 threads on one NUMA domain, 4 × 4 points | 21.6, 25.9, 20.3 | 22.1, 20.4, 21.9 | 24.9, 23.0, 20.6 | 111.8 | -| C: 8 workers × 16 threads, 4 × 4 points | 25.9, 27.9, 26.2 | 25.8, 37.5, 25.9 | 29.0, 29.2, 30.6 | 114.6 | - -- **What the calibration chose.** The 4- and 16-core rows kept the table's waiting and - team (passive 1.13 and 1.18 times slower in the calibration's children, half the team - 1.46 and 1.08), found the grain inconclusive and planned nothing. A calibrated worker - therefore differs from the table's only in spinning, which is the `spin` arm. -- **Config C's calibrated arm** ran 1.05–1.17 times the table's in its rounds, but a - second job on the same node, nine shuffled scans, did not repeat it: `off` 27.4, 26.6, - 24.9, 24.9, 31.1; `use` (the same profile, no first-use check) 25.7, 25.9, 26.5, 27.6, - 31.0; `auto` 25.8, 25.4, 25.8. Scans of every arm land near 31 s at times. The - first-use check costs the scan's parent 0.4 s (0.2 s the second time). -- **Workers spinning or passive** (B and C): the same within the node's spread. The - calibration's lone-process verdict against passive waiting does not carry to - concurrent workers here, and does not cost them either. -- **Single-threaded workers** (A): the one-core class's standard calibration ran out of - its 90 s before three rounds of its problems in series and published nothing, to try - again a day later. One CPU has no team, waiting or grain to choose, so a one-CPU - allocation is now never measured. No setting differed between A's arms; the first - scan of each round ran slowest whichever arm it was (505, 690, 459 against 464, 496, - 415). -- **The one-off cost** is the warm-up's extra time: about 90 s a worker class, once per - machine, allocation class and release. - -### Device settings and the node chunk on an NVIDIA H200 (SEP 46 phase 6) - -SEP 46 phase 6 measures which device settings move a run beyond its noise (section -6.14). Builds of one commit, each changing one compiled setting, against the default -build (`benchmarks ab --device`, a fifth of each case, three rounds, CUDA 13.1); the -node chunk with one build and `SOLPROP_BENCH_NODE_BUDGET` in the candidate arm (#361). -A/A: geometric mean 0.996, each case within about ±3 % (`kerr_beam_192` to 1.05). - -| setting | geometric mean | beyond the noise | -|---|---:|---| -| graph replay off | 1.012 | `ctc` 1.08, `h2_raman_averaged` 1.07 slower | -| team 128, reduction 256 (from 256, 512) | 0.994 | `he_rdw_averaged` 0.94 (one round 0.996), `argon_blueshift` 0.965 | -| team 512, reduction 1024 | 1.009 | `ctc` 1.09 slower | - -The node chunk, against the 1 GiB default (Runge-Kutta, Multistep): - -| case | one chunk (64 GiB) | 8 GiB | -|---|---|---| -| `radial_filament_512` | 0.748, 0.924 | 0.749, 0.880 | -| `cartesian_filament_256` | 0.862, 0.888 | 0.877, 0.908 | -| `cartesian_filament_128` | 0.904, 0.935 | 0.911, 0.944 | -| `kerr_beam_384`, `kerr_beam_768` (fixed-step RK4IP) | 0.974, 0.996 | | - -Graph replay pays and stays on; neither width pays. The chunk pays 6–25 % on the -spatial routes, and 8 GiB takes nearly all of it. The device tests passed on the same -build (211 targeted, 31 native, 253 `-m gpu`, 92 radial). - -### A run's fixed host cost and a fresh process's BLAS - -[#347](https://github.com/LupoLab/solprop/issues/347) asked what a complete run costs -outside its steps; [#383](https://github.com/LupoLab/solprop/issues/383) and -[#76](https://github.com/LupoLab/solprop/issues/76) what a fresh process costs in CPU. -Measured on an Intel Xeon Gold 6240 in an exclusive allocation, pinned to the second -socket's 18 cores, FFTW wisdom warmed for every shape first so that neither arm plans. -`main` at `f7d1a736` against the branch, alternating, three rounds, medians; each -process builds, translates and runs twice into an HDF5 file: - -| case (length, threads) | build (s) | translation (s) | second run (s) | of it, the march (s) | -|---|---:|---:|---:|---:| -| `he_rdw_averaged` (5 %, 1) | 3.47 → 3.17 | 0.18 → 0.18 | 0.28 → 0.28 | 0.07 | -| `radial_filament_256` (5 %, 8) | 3.57 → 3.27 | 0.11 → 0.11 | 0.88 → 0.89 | 0.56 | -| `kerr_beam_384` (whole, 8) | 6.48 → 4.68 | 5.20 → 2.83 | 35.7 → 35.9 | 24.1 | - -- **Build, every case, 0.3 s:** the analytic signal (a capillary's input peak, a plane's - statistics) no longer imports `scipy.signal`, 0.7 s of imports in a profile. -- **`kerr_beam_384`'s build, another 1.5 s:** the admittance's copy to the columns that - share it runs in threads. -- **Its translation, 2.4 s:** the transverse ramp's column energies are summed in threads. -- The resume key is carried into the opened run rather than computed again, and the - package versions are read once per process: each is milliseconds on these cases and - grows with the launch's arrays. - -What is left, from profiles of the same runs: - -- **FFTW planning.** Without `SOLPROP_FFTW_WISDOM`, constructing the native backend - plans every transform again in each process: 1.34 s of `he_rdw_averaged`'s run at 5 %, - against its 0.07 s march and about 0.2 s of other host work. SEP 46's wisdom store is - the remedy. -- **CoolProp's import.** A capillary's fill imports it through optmat's transport model: - 2.3–2.7 s of every capillary build. -- **`kerr_beam_384`'s 11.6 s of run outside the march:** the planes' saves 2.9 s - ([#346](https://github.com/LupoLab/solprop/issues/346)), the edge's reads 1.65 s and the - temporal checks 1.5 s. -- **Smaller:** a plane's modal basis identity about 1 ms per plane and mode (the index, - its quantisation and its JSON in about equal shares), and the peak-field report about - 0.1 s per run. The driver's 0.75 s import is spread over many modules, so deferring - them was not worth it. - -**A fresh process's BLAS.** NumPy's and SciPy's wheels each load a pthreads OpenBLAS, -which starts a thread per CPU at load and spins it for OpenBLAS's thread timeout before it -sleeps. Importing the driver in a fresh process, then building `rdw`, wall against CPU -time, unpinned in the same exclusive allocation (so each pool starts 72 threads), two -repeats: - -| setting | import (s) | `rdw` build (s) | -|---|---:|---:| -| nothing set | 0.75 / 13.8 | 3.46 / 6.77 | -| `OPENBLAS_THREAD_TIMEOUT=20` | 0.67 / 0.73 | 3.44 / 3.46 | -| `OPENBLAS_NUM_THREADS=1` | 0.66 / 0.66 | 3.43 / 3.43 | - -`grin_nonlinear`'s build took 16.2–19.1 s and `moving_solid_guide`'s 79–98 s under every -setting, CPU equal to wall (the construction lease of -[#382](https://github.com/LupoLab/solprop/pull/382)); the spread is between repeats, not -settings. The timeout changes no width, so it is safe where a load-time width is not -(Windows on Arm), and processes solprop starts now take it: service runs, the GUI's -kernel and pool workers. A script that imports NumPy itself still pays it, unless it sets -the variable. - -### The edge's growing backstop - -[#396](https://github.com/LupoLab/solprop/issues/396): after SEP 44's native read, what -`line` paid for its edge was the read ceiling on its steps, not the reads (above: 224 calls -where it took 196). The spacing's backstop now starts at `L/16` and doubles at each read -whose reach has not grown by a tenth since it started, up to `L/4`; growth or a spectrum -without reach starts it again. SEP 40's four-way control, `python -m benchmarks.edge_overhead`, -native at 18 threads of an Intel Xeon Gold 6240 in an exclusive allocation, six rounds, -`main` at `f7d1a736` against the branch, the default check against no ramp and no reads: - -| case | before: added, reads | after: added, reads | -|---|---:|---:| -| `line` | +14.3 %, 23 (224 calls) | +2.6 to 3.6 %, 13 (196 calls) | -| `planar` | +12.5 %, 23 | +9.1 %, 16 | -| `radial_filament_256` | +4.4 %, 21 | +3.9 %, 15 | - -The reads alone (`edge`) on `line` went from +12.8 % to +2.9 %. On `planar` about 3 ms of -each run was the edge's setup evaluating every slab mode's index again, now kept by run -length; its reads alone went from +9.8 % to +6.6 %. What remains there is the reads' -own cost, about 0.4 ms each on a 0.1 s run. - -Qualification, before any timing: - -- **SEP 40's linear witnesses, scaled.** 432 packets on the line route under Multistep - (the integrator that commits long steps) and each rule, 414 whose exact flow passes the - stop before the end: none missed under either rule. In 28 that cross half the box the - new rule stops without having warned first. -- **A nonlinear witness.** A self-focusing line Kerr beam in argon (300 to 10000 critical - powers, 60 and 100 µm waists, half-widths 0.25 to 1 mm, two lengths: 80 configurations) - under a dense spacing (`L/256`), the former rule and the new one: the same outcome for - every configuration under all three (57 stop, 12 warn, 11 clear). The new rule stops at - most 2 % of the length after the dense one, and warns at most 8.5 % after it (the former - rule 2.3 %). One such case is the slow-tier test - `test_a_self_focusing_beam_is_stopped_as_dense_reads_stop_it`. - -### Separable stage propagators as vector maths - -[#338](https://github.com/LupoLab/solprop/issues/338): free space's separable stage input -and finish formed each element's propagator with one libm `sincos` (and an `exp` where it -carries loss) inside the crossing's visit. At one thread that was 18 % of `line`. Each -host crossing tile (32 columns by 16 bins) now forms its 512 propagators in one -`vmath::sincos` pass, and one `vmath::exp` pass only where a real part is non-zero, before -the tile is visited in its former order. Devices keep the per-element path. - -`python -m benchmarks ab`, `main` at `f7d1a736` against the branch, an Intel Xeon Gold 6240 -(18 cores of one socket, exclusive), a quarter of each case's length, three rounds of three -repeats (the Cartesian filament one), the same steps, and fields within 1.2e-12: - -| case | 1 thread | 16 threads | -|---|---:|---:| -| `line` | 0.893 [0.882, 0.893] | 0.927 [0.901, 0.929] | -| `cartesian_filament_128` | | 0.931 [0.852, 0.932] | -| `planar` | 0.995 | 0.994 | -| `kerr_beam_192` (control: tabulated low-storage path) | 0.996 | 1.009 | -| `argon_blueshift` (control) | 1.004 | 1.002 | - -`planar`'s remaining libm time is `hypot`, in the complex square root of its lossy -medium's longitudinal wavenumber (`SpatialCoefficients::root_of`), in these same two -kernels: about 7 % of its one-thread march (`perf` with LBR call stacks). The other -per-element kernels #338 lists (the envelope cycle moments, the two-component -magnitudes, the trapezoid column and dense observation) were negligible in one-thread -profiles of the tracked cases, so they were left. A profile on a second x86 processor -was not taken: the code and glibc are the same, so the ranking would not change. - -### x86-64-v4 against v3 on an AVX-512 Xeon - -[#334](https://github.com/LupoLab/solprop/issues/334): the branch above built with -`-march=cascadelake` (x86-64-v4 with VNNI) against x86-64-v3, GCC 16.2, FFTW 3.3.11, -OpenBLAS 0.3.34 and SLEEF's AVX2 route in both. `python -m benchmarks ab --set tracking`, -an Intel Xeon Gold 6240 (18 cores of one socket, exclusive), a quarter length, three -rounds; the ratio v4/v3, the same steps and fields to rounding: - -| case | 1 thread | 16 threads | -|---|---:|---:| -| `argon_blueshift` | 0.909 | 0.962 | -| `ctc` | 0.924 | 0.964 | -| `grin_nonlinear` | 0.943 | 0.968 | -| `rdw` | 0.978 | 0.976 | -| `he_rdw_averaged` | 1.036 | 1.004 | -| the other eight | 0.972–1.034 | 0.976–1.013 | - -The geometric mean over all 26 rows is 0.984. `kerr_beam_384` at one thread had a round -twice as slow; its median, 1.034, is that noise. - -The same tree on an AMD EPYC 9B45 (Zen 5, whose AVX-512 runs at full width without -lowering the clock; Google Cloud C4D, 16 cores without SMT, Ubuntu 26.04), built with -`-march=znver5` against x86-64-v3: GCC 15.2, the distribution's FFTW 3.3.10 and OpenMP -OpenBLAS 0.3.32, and SLEEF's AVX2 route in both. The same command and rounds; the ratio -znver5/v3, the same steps and fields to rounding: - -| case | 1 thread | 16 threads | -|---|---:|---:| -| `gnlse_soliton` | 0.911 | 0.910 | -| `argon_blueshift_envelope` | 0.918 | 0.980 | -| `argon_blueshift_averaged` | 0.932 | 0.943 | -| `grin_nonlinear` | 0.934 | 0.960 | -| `argon_blueshift` | 0.937 | 0.996 | -| the other eight | 0.938–1.003 | 0.949–1.014 | - -The geometric mean over all 26 rows is 0.963. `gnlse_soliton` is a 0.07 s run whose -time does not change with the thread count, so its two columns are one result. Neither -machine has a case that reaches the 10 % at the default width that -[#337](https://github.com/LupoLab/solprop/issues/337) asks of run-time dispatch. - -### Transforms by shape and one forward pack - -Issues [#587](https://github.com/LupoLab/solprop/issues/587) and -[#584](https://github.com/LupoLab/solprop/issues/584), November 2026. The transforms' -width was one element count (serial below 16384, four threads below 131072, the full -pool above), and a modal stage ran each forward transform as its own threaded call over -the modes' rows only. - -**Width by shape, timed alone.** A batched real-to-complex forward transform of each -shape the tracking set runs, at FFTW's estimate and measure, on 1 to 36 threads, with -native's OpenMP loop callback and spinning waits (an Intel Xeon Gold 6240 node, 16 -cores of an AMD EPYC 7763 on one NUMA domain, an Apple M5 Max). Microseconds a -transform, measured plans; the table's width in brackets: - -| rows × length | Xeon 1 | 4 | 8 | 18 | EPYC 1 | 4 | 8 | 16 | -|---|---:|---:|---:|---:|---:|---:|---:|---:| -| 4 × 3072 | [20.5] | 15.5 | 8.5 | 16.0 | [16.7] | 5.8 | 7.8 | 9.3 | -| 4 × 10240 | 73.5 | [21.8] | 24.5 | 29.1 | 66.5 | [17.7] | 19.9 | 20.9 | -| 1 × 32768 | 70.2 | [47.6] | 50.5 | 62.7 | 71.1 | [34.2] | 29.0 | 38.8 | -| 7 × 6400 | 77.7 | [38.5] | 16.9 | 18.8 | 67.0 | [20.6] | 13.6 | 14.2 | -| 289 × 128 | 46.5 | [16.2] | 22.7 | 9.8 | 40.4 | [12.2] | 7.5 | 7.7 | -| 128 × 576 | 119.5 | [30.4] | 16.4 | 28.4 | 89.7 | [23.5] | 13.0 | 9.5 | -| 16 × 6144 | 198.9 | [46.9] | 29.5 | 45.1 | 149.8 | [38.9] | 19.8 | 13.3 | -| 12 × 10240 | 279.1 | [61.7] | 44.4 | 31.5 | 205.0 | [52.5] | 37.6 | 23.9 | - -A few rows ran best at about a thread a row, more threads splitting rows at a loss; -many rows of a few thousand samples wanted 8 to 18 threads, where four were two to three -times slower. One row gained from being split only from about 16384 samples on these -two Linux machines (from 4608 on the M5 Max's top tier, at four threads). Hence the rule -(`operation_threads`): from `fft_threshold`, a thread per `fft_thread_elements` -samples, at most one a row, or up to the medium width for rows of `fft_long_row` -samples; Linux 8192, 4096 and 16384, macOS 32768, 32768 and 65536 (a sixteenth on a -spinning top tier). Estimate plans of a prime length (4096 × 193) at more than four -threads ran 15 to 47 times slower than at four; measured ones did not. - -**One forward pack.** A modal stage's forward rows -- the projection's fine and coarse, -the in-stage absorber's, the two held plasma currents' fine and coarse -- now go -through one plan, as on a device: `rdw` transforms 28 rows of 10240 at once where it -transformed seven batches of four. The host keeps the coarse rows after the fine ones, -so that a deferred quadrature transforms the fine block in its stages and the coarse -block once at its finish. Pack on against off, one build (5 % windows, three rounds, -fields within 1e-14): - -| case | Xeon Gold 6240, 18 | 36 | EPYC 7763, 16 | M5 Max, 6 (contended) | -|---|---:|---:|---:|---:| -| `argon_blueshift` | 0.88 | 0.90 | 0.88 | 0.92 | -| `rdw` | 0.90 | 0.94 | 0.95 | 0.90 | -| `ctc` | 0.92 | 0.94 | 0.94 | 0.97 | -| `he_rdw_averaged` (one column) | 1.35 | 1.32 | 1.11 | 0.97 | - -On the one-column case the pack's four rows, threaded on the compact team, took 152 µs -a stage against 90 µs for its three serial transforms (Kokkos section timer, Xeon, 18 -threads), though the same transform alone took 25 µs on eight threads; measured plans -did not change it (1.34). One-column problems keep their separate transforms. - -**Against the previous build** (both together; one-column problems unpacked; 5 % -windows, three rounds, fields within 1e-12): - -| case | Xeon 18 | Xeon 36 | EPYC 16 | M5 Max 6 (contended) | -|---|---:|---:|---:|---:| -| `argon_blueshift` | 0.87 | 0.80 | 0.86 | 0.92 | -| `ctc` | 0.89 | 0.91 | 0.92 | 0.98 | -| `rdw` | 0.91 | 0.95 | 0.95 | 0.95 | -| `line` | 0.93 | 0.87 | 0.88 | 1.00 | -| `radial_filament_256` | 0.97 | 1.01 | 0.99 | 1.00 | -| `gnlse_raman_shock` | 0.94 | 0.99 | 0.98 | 1.00 | -| `grin_nonlinear` | 1.01 | 0.93 | 1.01 | 1.00 | -| `kerr_beam_192` | 1.02 | 1.04 | 1.01 | 0.99 | -| geometric mean, with the one-thread rows | 0.977 | | 0.981 | 0.993 | - -The shape rule alone (pack off) gave `line` 0.91 and 0.90 (Xeon 18 and 36) and 0.89 -(EPYC), and `grin_nonlinear` 0.95 on the EPYC; the one-thread rows stay within -0.98-1.02. `he_rdw_averaged` and `h2_raman_averaged`, whose code is unchanged, ranged -0.92-1.12 on the Xeon between runs of either arm: the per-process modes of #81. - -### The native workspace seam (SEP 52) - -[SEP 52](seps/archive/sep-0052-backend-shape.md)'s phase 4 replaced the native binding's -configuration calls with one `Problem` and one run record per start, and the per-step -probe paths with the workspace's own probe; the marches did not change. Measured on an -exclusive node of two AMD EPYC 7763 (32 cores), `--threading bound`, `--calibrate none`, -three rounds of three repeats, the milestone's base against the branch, ratios of the -per-round medians (below one is faster): - -| case | default window, `--length 0.05` | whole run (`SOLPROP_BENCHMARK_WINDOW=run`) | -|---|---|---| -| `gnlse_soliton` | 1.042 / 1.008 / 1.014 | 1.020 / 1.004 / 1.027 | -| `rdw` | 0.996 / 0.983 / 0.991 | 0.992 / 0.989 / 0.994 | -| `radial_filament_256` | 1.004 / 1.004 / 0.995 | 1.022 / 1.001 / 1.029 | -| `kerr_beam_192` | 1.007 | | - -Each cell lists the three rounds' ratios. Every arm took the same -steps. The default window starts after the load, which the branch moved into the -session's start, so the whole-run window (from before the load; [benchmarking.md](benchmarking.md#comparing-two-builds-while-iterating)) -is the like-for-like reading. Timed from a built backend, a whole run cost 1.9 % more -under Runge–Kutta, 2.1 % under low-storage and 1.9 % under Adams, the start's one -converted record; a scan's preparation 0.5–1 % more. The probe's open, trial and read -cost 3.4 % more under Runge–Kutta and 2.5 % under Adams and 8 % less under low-storage; -a trial alone is unchanged under Runge–Kutta and Adams and 16 % faster under -low-storage. Peak resident memory moved by at most 1 MB. Two costs were removed on the -way: a run's initial field is read where it is rather than copied into the record -(`kerr_beam_192`'s low-storage window had been 4.6 % slower), and a run reads the -workspace's live counters, not its whole diagnostics record, at its start, close and -planes. No device build was run (the device targets were compiled only). - -The host-trial timer of the earlier Adams entries, `benchmarks.adams_host`, was removed -with it: it reached the deleted per-step adapter, and the native march leaves it nothing -to time. Those entries stand as recorded. - -## Reference tables - -These tables back the indicative results above. - -### Kokkos CPU sizing thresholds - -Counts are elements or scalar product work, never allocated bytes. Stages and reductions -use the field's element count; batch updates use the fused batch's total. Packing uses -matrix entries and temporal copies use output samples, without multiplying by the dense -transform's inner dimension. Responses use active columns × components × fine-grid -samples. Dense products use output rows × inner dimension × samples; coupled matrix -functions instead use active spectral bins × modes³, and the exponential Adams trial's -passes the field's elements × history rows. FFT and Raman choices use each -plan's actual real-side batch dimensions, including a kernel transform and the last -partial chunk. - -| Operation | Serial below | Full pool from | Intermediate rule | -|---|---:|---:|---| -| Stage/update/reduction | 8,192 | 8,192 | none | -| Packing/temporal copy | 65,536 | 65,536 | none | -| Response | 32,768 | 196,608 | up to four threads; at least 40 component columns or 65,536 fine samples per column also enables the full pool | -| Native/custom GEMM | 1,048,576 | 1,048,576 | none | -| General-modal synthesis/projection/maps | 65,536 | 65,536 | none | -| Coupled matrix functions | 32,768 | 32,768 | none | -| Exponential Adams trial passes | 8,192 | 65,536 | up to four threads | -| Modal/spatial FFT | 8,192 (macOS 32,768) | 4,194,304 | by shape: a thread per 4,096 samples (macOS 32,768), at most one a row; rows of 16,384 samples (macOS 65,536) or more split up to four threads ([transforms by shape](#transforms-by-shape-and-one-forward-pack)) | -| Raman FFT | 65,536 | 262,144 | up to four threads | - -A response column is one active node and one component. Every width is capped by the -global thread setting. A kernel pool that already holds a full-width instance gives it to -the medium-width kernels too ([a stable kernel team](#stable-kernel-team)); the FFT pools -keep their medium widths. A problem of one column on one node takes at most eight -threads in every pool, its transforms on its kernels' team -([compact CPU teams](#compact-cpu-teams)). Explicit per-pool requests bypass this table, including the -short-FFT rule. `build_info()` exposes the constants and override mask; backend metadata -exposes effective widths and sizing inputs. Non-OpenMP host builds report that -per-operation sizing is unsupported and keep their existing execution policy. - -### Resident Adams allocations - -`F = N² × 600 × 16` bytes is one complex128 field of the reduced `kerr_beam_384` above -and `C = 5592 × 600 × 16` bytes one node chunk (a 1 GiB node budget). Each pair is -**`numba_cpu` / Kokkos** capacity in GiB; arrows show the 29 → 18 volume change. The -384² capacities are calculated. These are owned allocations, not resident pages. - -| Allocation | Field count, `numba_cpu` / Kokkos | 128² | 256² | 384² | -|---|---|---:|---:|---:| -| Adams history ring | 7 / 7 | 1.025 / 1.025 | 4.102 / 4.102 | 9.229 / 9.229 | -| Adams moments | 8 / 7 | 1.172 / 1.025 | 4.688 / 4.102 | 10.547 / 9.229 | -| Adams flow / propagator | 1 / 1 | 0.146 / 0.146 | 0.586 / 0.586 | 1.318 / 1.318 | -| Native Adams source, exponent, saved state | 0 / 3 | 0 / 0.439 | 0 / 1.758 | 0 / 3.955 | -| Dense slopes | 0 / 7 → 0 | 0 / 1.025 → 0 | 0 / 4.102 → 0 | 0 / 9.229 → 0 | -| Dense start, end, exponent, held observation | 0 / 4 → 0 | 0 / 0.586 → 0 | 0 / 2.344 → 0 | 0 / 5.273 → 0 | -| Current state | 1 / 1 | 0.146 / 0.146 | 0.586 / 0.586 | 1.318 / 1.318 | -| RK stages | 7 / 7 | 1.025 / 1.025 | 4.102 / 4.102 | 9.229 / 9.229 | -| Solution, error, advanced, recycled stage | 4 / 4 | 0.586 / 0.586 | 2.344 / 2.344 | 5.273 / 5.273 | -| RK exponent / weighted residual | 1 / 1 | 0.146 / 0.146 | 0.586 / 0.586 | 1.318 / 1.318 | -| RK propagators | 2 / 1 | 0.293 / 0.146 | 1.172 / 0.586 | 2.637 / 1.318 | -| Transverse FFT scratch | 1 / 1 | 0.146 / 0.146 | 0.586 / 0.586 | 1.318 / 1.318 | -| **Field-volume subtotal** | **32 / 44 → 33** | **4.688 / 6.445 → 4.834** | **18.750 / 25.781 → 19.336** | **42.188 / 58.008 → 43.506** | -| Temporal FFT buffers (`4C` each) | fixed chunk | 0.200 / 0.200 | 0.200 / 0.200 | 0.200 / 0.200 | -| Absorber scratch (`0 / 2C`) | fixed chunk | 0 / 0.100 | 0 / 0.100 | 0 / 0.100 | -| Statistics spectrum, time, power (`0 / 2.5C`) | fixed chunk | 0 / 0.125 | 0 / 0.125 | 0 / 0.125 | - -The remaining ledger entries (reduction partials, axes, spatial coefficients, statistics -outputs, host problem tables, masks, weights and plan heap) total a few MiB. Outside the -ledgers, the input field adds one `F`; Kokkos keeps another `F` of host state, and field -export passes through two more `F` at the Python boundary. Host Adams trials form about -`4F` of temporary arrays. Capacities and transients do not all become resident at once, -so their sum overstates the measured peak. - -## Native CPU FFT and diagnostic scheduling - -This campaign uses the frozen `benchmarks ab` harness and unchanged registry recipes, -under an approved exception to standard-run and whole-suite performance reporting. -These are **lightweight measurements**, not a standard-run adoption verdict. Every -reported propagation window contains ten prescribed steps: `fixed-rk` for modal and -radial cases, `fixed-rk4ip` for Cartesian Kerr. Construction, first-window cost and -observations are recorded separately; no window is extrapolated to a full run. - -The baseline is `9521a88`; the retained implementation is `b3bdd0f`. Each arm has a -separate source/environment/native wheel. On the Apple M5 Max (18 cores, 128 GiB, -macOS 27.0.1), Homebrew Clang 23.1.3 uses Accelerate BLAS and one LLVM OpenMP runtime. -The source-built FFTW 3.3.11 control and NEON library have identical M1 flags, -deployment target 14.0 and cycle-counter support, with both precisions and coherent -threading libraries. The two-socket Xeon Gold 6240 uses exclusive 72-logical-CPU -allocations and one hardware thread per selected physical core. Its independent -bundles are GCC 16.2/OpenBLAS 0.3.34/FFTW 3.3.11 with GNU OpenMP, and IntelLLVM -2026.1.1/MKL 2026.1 (including MKL FFT) with Intel OpenMP. Timed arms run sequentially, -without concurrent builds. Python is 3.14.5 on an Apple M5 Max and 3.14.7 on a Xeon Gold 6240; -NumPy is 2.5.2, Kokkos 5.2.1, Kokkos Kernels 5.2.0 and Kokkos-FFT 2.0.0. - -### NEON codelets and Raman plans - -A same-source control with matched compiler flags changes only FFTW's explicit NEON -codelets. Its eight-case screen at budgets 1 and 18 has geometric mean ratio 0.933; -this one-round/two-repetition screen isolates the library effect but is not a -confirmation. Full and tail microchecks include H₂'s 65536×21/12 and CtC's 131072×3/1 -rows at serial and parallel widths, raw FFT normalization and exact padding zeros. -ESTIMATE and MEASURE both retain short parallel shapes where vDSP is faster, so -complete vDSP removal is rejected. - -With NEON in both arms, replacing the previous Raman choice with tuned Kokkos-FFT -has the following three-round/five-repetition warmed-window ratios. The rest of the -source is held fixed for this provider/planning comparison. - -| Case | 1 thread | 18 threads | -|---|---:|---:| -| CtC | 0.698 [0.694, 0.699] | 0.966 [0.961, 0.971] | -| H₂ Raman | 0.480 [0.459, 0.485] | 0.788 [0.767, 0.795] | -| GNLSE Raman shock | 0.828 [0.817, 0.830] | 0.839 [0.839, 0.846] | - -Measured planning has a real setup cost. In this ordered Raman comparison, median -serial CtC construction changes from 3.00 to 22.83 s, while a warmed ten-step window -changes from 6.00 to 4.18 s. H₂ construction changes from 1.09 to 1.81 s and its -window from 1.28 to 0.62 s. Wisdom is process-local and previous constructions affect -these costs; they are not universal constants. Explicit `SOLPROP_FFTW_PLAN=estimate` -trades this measured setup for cheaper construction. Parallel default planning stays -ESTIMATE. No full-propagation payback is inferred from these ten-step windows. - -### Retained Mac combination - -The fresh current-library baseline and retained NEON/provider/scheduling candidate -use three alternating rounds and five repetitions at each budget. Ratios are the -median of paired round medians, with the range across rounds in brackets. - -| Case | 1 thread | 18 threads | -|---|---:|---:| -| RDW | 0.888 [0.877, 0.901] | 0.831 [0.810, 0.835] | -| CtC | 0.595 [0.577, 0.604] | 0.859 [0.858, 0.878] | -| Radial 256 | 0.893 [0.853, 0.912] | 0.962 [0.934, 0.967] | -| Resolved argon | 0.954 [0.950, 0.961] | 0.886 [0.879, 0.898] | -| H₂ Raman | 0.472 [0.457, 0.474] | 0.718 [0.712, 0.718] | -| Averaged helium RDW | 0.891 [0.880, 0.901] | 0.902 [0.891, 0.916] | -| Averaged argon | 0.918 [0.909, 0.922] | 0.915 [0.905, 0.920] | -| GNLSE soliton | 0.889 [0.882, 0.893] | 0.870 [0.867, 0.871] | - -The geometric mean is 0.792 at one thread and 0.865 at the production budget of 18 -(0.828 across both budgets). Using each fresh process's warmed median as one sample, -the conservative aggregate `(candidate median + 2 MAD) / (baseline median − 2 MAD)` -is 0.805 and 0.878 respectively. All denominators are positive. These spread checks -support the retained change within the lightweight scope. All fixed windows retain -ten accepted steps, no rejected steps and 61 source evaluations; field differences -are at most 2.1e-16 in relative L2 norm. A one-round/two-repetition guard screen at budget 18 gives radial -512 1.012, Cartesian plasma 128² 0.894, line 0.976, general modal 0.892, scalar wall -0.936 and vector wall 0.990. The 1.2% radial variation does not exceed the A/A spread. - -The retained library also passes the Cartesian Kerr confirmation (three rounds, -two repetitions, ten `fixed-rk4ip` steps). No Cartesian traversal change is included: - -| Case | 1 thread | 18 threads | -|---|---:|---:| -| Kerr 192² | 0.843 [0.832, 0.849] | 0.869 [0.718, 0.924] | -| Kerr 384² | 0.837 [0.834, 0.860] | 0.880 [0.880, 0.895] | - -The geometric mean is 0.840 at one thread and 0.874 at 18 (0.857 combined); -the corresponding conservative aggregates are 0.860 and 0.919. Fields differ by at most 1.4e-18 and work -matches. The 192² parallel spread is wider, so its precise gain is less certain; -all three paired rounds still favour the candidate. These results measure the -library change with the original traversal. - -### Diagnostic scheduling - -The affected set is ordinary DOPRI5 modal CtC, RDW, resolved argon and H₂ Raman. -The implementation defers coarse projections to the final source and their FFTs and -held-current assembly to accepted scoring. General-modal, dispersive, low-storage, -Adams and envelope-plasma scheduling remains eager. A serial full-source profile -reduced RDW's forward real FFT calls from 427 to 274 per ten-step window; CtC's -fell from 1464 to 1311. Persistent field-buffer ledgers are unchanged. FFT plan heap -estimates can vary with planning and allocator state. - -These confirmations use three alternating rounds and five repetitions. Each ratio -is the median of the per-round paired medians; brackets give the range over rounds. -A ratio below one favours the candidate. - -| Case | M5 Max, 18 threads | GCC Xeon, 1 thread | GCC Xeon, 18 threads | Intel Xeon, 1 thread | Intel Xeon, 18 threads | -|---|---:|---:|---:|---:|---:| -| RDW | 0.803 [0.755, 0.845] | 0.930 [0.925, 0.946] | 0.823 [0.820, 0.843] | 0.900 [0.887, 0.916] | 0.822 [0.813, 0.828] | -| CtC | 0.906 [0.888, 0.917] | 0.897 [0.894, 0.901] | 0.946 [0.945, 0.949] | 0.904 [0.893, 0.910] | 0.937 [0.933, 0.937] | -| Resolved argon | — | 0.998 [0.984, 1.002] | 0.949 [0.941, 0.953] | 0.966 [0.963, 0.976] | 0.966 [0.956, 0.972] | -| H₂ Raman | 0.933 [0.914, 0.967] | 1.007 [0.986, 1.082] | 0.982 [0.981, 0.988] | 0.985 [0.976, 1.044] | 0.973 [0.957, 0.977] | - -At one thread the GCC affected-set geometric mean is 0.957 and Intel's is 0.938; -at 18 threads they are 0.923 and 0.922. The corresponding conservative aggregates -from fresh-process medians are 0.972/0.931 for GCC and 0.951/0.929 for Intel, with -positive denominators. Both production-budget gains exceed 5% and satisfy the -conservative spread criterion. Mac's isolated 18-thread ratio is 0.879, with a -conservative aggregate of 0.950. Across both budgets, GCC is 0.940 and Intel 0.930. -The matched fixed windows retain ten accepted steps, no rejections and 61 source evaluations; their -field differences are at rounding level (at most 1.9e-16 in these confirmations). -The M5 Max's first 18-thread screen and one A/A round showed large host timing -variation and remain inconclusive. The runner's busy-at-launch flag does not establish its cause; load averages also include prior -owned work. A subsequent three-round A/A control gave RDW 1.010 [1.008, 1.054] -and H₂ 1.015 [0.995, 1.040]. -Those controls do not justify interpreting a few-percent change as a gain. - -### Retained Xeon combination - -Each compiler bundle also compares the complete retained candidate with its frozen -baseline. Raman cases use three alternating rounds/five repetitions at budgets 1 -and 18; other main cases and geometry guards use one round/two repetitions. The -Raman confirmations are: - -| Case | GCC, 1 thread | GCC, 18 threads | Intel, 1 thread | Intel, 18 threads | -|---|---:|---:|---:|---:| -| CtC | 0.790 [0.789, 0.792] | 0.963 [0.953, 0.966] | 0.912 [0.908, 0.914] | 0.939 [0.934, 0.942] | -| H₂ Raman | 0.824 [0.817, 0.841] | 1.003 [0.988, 1.030] | 0.977 [0.966, 0.986] | 0.976 [0.974, 0.977] | - -The geometric means at budgets 1/18 are 0.807/0.983 for GCC and 0.944/0.957 for -Intel (combined 0.890 and 0.951). GCC's parallel Raman-only conservative aggregate -is 1.004, so that subset does not establish a gain beyond spread; the confirmed -shared scheduling gain is assessed over its complete affected set above. The -serial GCC improvement includes measured FFTW planning; Intel uses MKL FFT, whose -FFTW compatibility layer ignores planning flags. No benefit is inferred for -unmeasured Linux Arm codelets. - -Main-case guard screens, followed by A/A controls for the small averaged and GNLSE -windows, are reported separately from the confirmed affected-set gains: - -| Case | GCC, 1 thread | GCC, 18 threads | Intel, 1 thread | Intel, 18 threads | -|---|---:|---:|---:|---:| -| RDW | 0.928 | 0.834 | 0.929 | 0.827 | -| Radial 256 | 1.002 | 0.962 | 1.012 | 0.991 | -| Resolved argon | 1.000 | 0.947 | 0.988 | 0.965 | -| Averaged helium RDW | 1.014 | 1.051 | 1.011 | 1.001 | -| Averaged argon | 1.004 | 1.025 | 0.994 | 1.017 | -| GNLSE soliton | 1.008 | 1.005 | 1.019 | 1.039 | - -The initial GCC averaged-helium 18-thread ratio of 1.051 and Intel GNLSE ratio of -1.039 triggered separate three-round/five-repetition A/A and A/B controls: - -| Control case | A/A, 1 thread | A/B, 1 thread | A/A, 18 threads | A/B, 18 threads | -|---|---:|---:|---:|---:| -| GCC averaged helium | 0.997 [0.989, 0.998] | 1.014 [1.005, 1.016] | 1.016 [0.998, 1.128] | 1.012 [1.012, 1.014] | -| GCC averaged argon | 0.987 [0.984, 0.994] | 1.014 [1.009, 1.031] | 1.001 [1.000, 1.001] | 1.010 [0.983, 1.017] | -| GCC GNLSE | 0.991 [0.818, 0.997] | 1.005 [1.003, 1.016] | 0.999 [0.995, 0.999] | 1.010 [0.992, 1.017] | -| Intel GNLSE | 0.981 [0.746, 0.993] | 1.005 [0.996, 1.008] | 1.018 [0.985, 1.061] | 0.999 [0.991, 1.018] | - -The initial 4–5% slowdowns do not repeat. GCC's small-window confirmation aggregate -is 1.011, a roughly 1% cost that remains visible; this does not justify additional -specialisation. Large A/A outliers make those controls inconclusive at fine -resolution. No improvement is claimed for these unchanged small-window routes. - -At budget 18, GCC's six geometry guards span 0.977–1.018 (aggregate 1.000), and -Intel's span 0.998–1.017 (aggregate 1.007). These cover radial 512, Cartesian plasma -128², line, general modal and scalar/vector walls. Cartesian Kerr 192²/384² guards -are 0.997/0.999 for GCC and 1.001/1.004 for Intel, with ten steps and matched work. -They support the absence of a large regression; they do not establish percent-level -improvements on routes whose implementation is unchanged. - -### Verification scope - -Focused checks cover raw FFT normalization, full/tail shapes, threaded execution, -provider selection, planning overrides, coherent library coexistence, repeated -construction/closure, source/step parity, held-plasma diagnostics after discarded -trials, FSAL, reset, accepted values and peaks, and band-filter boundaries and high -dynamic range. Native suites passed on both Xeon bundles: GCC has 137 C++ tests and -378 Python tests passing; Intel has 133 and 376. Provider/platform/device skips -remain explicit. Mac final focused Python checks have 118 passes plus 13 lifetime -and import checks. Independent bounded smooth-law adaptive fixtures pass on both -arms and all three builds against accuracy envelopes fixed from tighter NumPy -references; these small fixtures do not certify full production trajectories. - -The macOS distribution helper was exercised with freshly built dependencies and -wheel repair. A clean installation discovers both bundled FFTW precisions as NEON, -one bundled OpenMP runtime and the required third-party licences, with the Apple M1 -baseline and macOS 14 target. No workflow edit is needed: the existing macOS wheel -job calls this dependency recipe. Full gates, slow and coverage lanes are deferred -to CI at the maintainer's request; GPU/device checks were unavailable on these CPU -hosts. Focused formatting, lint, spelling and diff checks passed. Supplemental -CPU/wall, observation, load and memory receipts are collected outside A/B timing; -no additional speed claim is taken from those resource measurements. - -### Rejected leads - -| Lead | Bounded evidence | Decision | -|---|---|---| -| Remove vDSP completely | NEON FFTW still loses on short parallel rows, including 8192×1 and 16384×1, under both ESTIMATE and MEASURE | Keep vDSP for short parallel power-of-two rows; use FFTW for serial and long rows with NEON | -| Tap-first band filter, preserving each sample's tap order | Mac serial RDW 0.973 [0.970, 0.982], argon 1.079 [1.061, 1.090]; GCC/Intel RDW/argon aggregates 0.911/0.900 across 1/18 threads | Reject the shared traversal and avoid an architecture-specific fork; retain the new boundary/dynamic-range tests | -| Cartesian 8×32 tile plus unused-load elimination | 192² Kerr: serial 0.980 [0.939, 0.997], 18 threads 0.980 [0.959, 1.005], three rounds/two repetitions | Reject the approximately 2% gain; keep 32×16 and the existing loads | -| Force one Accelerate BLAS thread | Five-case confirmation at budget 18: geometric mean 1.000, three rounds/five repetitions | Keep the existing provider-managed startup policy | - -The post-FFTW 192² serial profile assigns 4.62 s to the separable fold, 4.72 s to -complex FFTs and 2.11 s to temporal pack/crop within a 12.16 s instrumented window. -A separate non-IPO compiler diagnostic reports control-flow and call barriers in the -crossing and final reduction loops; the measured production binaries retain IPO. -The tile experiment changes locality without changing stored layouts or per-column -summation order, but its complete-window gain does not meet the greater-than-5% -threshold. Instrumented profiles are diagnostic evidence, not timings used for -retaining a change. - -Independent startup-only pool screens at budget 18 varied kernel, ordinary FFT, -Raman full, Raman tail and BLAS widths separately to 1 or 4. Both Xeon bundles -showed aggregate slowdowns for every reduced-width screen (the smallest was 1.095 -for Intel's four-thread Raman tail). Mac responses were mixed, including opposite -RDW and argon directions. No shared dimension threshold or pool policy is changed; -explicit overrides and global caps retain their existing semantics. A 36-core -sizing confirmation is unnecessary because no sizing change is retained. - -## The run record's cost - -[#309](https://github.com/LupoLab/solprop/issues/309) measured how a run's record grows with -its grid. Moving the record's large arrays beside its text (`RECORD_ARRAY_LIMIT`) takes the -hash from the record's text to its arrays' bytes. - -Measured on an Intel Xeon Gold 6240, pinned to one socket with 16 threads, on a shared -machine with a load average of about 17, so treat small differences as noise. One run each, -built and not stepped, on `numpy_ref`, with `#309`'s Cartesian problem of 96 frequency bins. -The figures are for the record alone, not for a run. - -| Grid | | First hash, s | `to_json`, s | `HDF5Output.open`, s | Reading the file's record, s | Hashing a read record, s | JSON, MB | File, MB | -|---|---|---:|---:|---:|---:|---:|---:|---:| -| 256² | before | 0.442 | 0.163 | 0.171 | 0.177 | 0.174 | 5.61 | 5.62 | -| | after | 0.010 | 0.001 | 0.006 | 0.021 | 0.001 | 0.03 | 3.19 | -| 512² | before | 1.763 | 0.652 | 0.711 | 0.755 | 0.777 | 22.66 | 22.67 | -| | after | 0.032 | 0.001 | 0.011 | 0.065 | 0.001 | 0.05 | 12.64 | -| 768² | before | 4.250 | 1.588 | 1.711 | 2.155 | 1.735 | 55.59 | 55.60 | -| | after | 0.075 | 0.002 | 0.017 | 0.144 | 0.002 | 0.07 | 28.40 | - -A default radial run of 256 nodes and 8192 frequency bins, which carries input noise, holds -83.21 MB of JSON before and 0.04 MB after, and its first hash goes from 2.603 s to 0.077 s. -A 64-node grid is about the same before and after, since its arrays sit close to the limit. -A run into `MemoryOutput` computes no hash at all. - -## A free-space point's setup - -Building and translating a large free-space launch took longer than the steps of a short point: -the passes over a beam's elements ran on one thread, its admittance ran twice, and the transverse -residual took a Python `Fraction` per node. - -Measured on an Intel Xeon Gold 6240, one socket's 18 cores, 18 threads, on a shared machine, twice each, unprofiled: -a 768 × 768 × 600 envelope launch through a Sellmeier glass with a Kerr response, `e49925d1` against `ece75dd7`. - -| | before (s) | after (s) | -|---|---:|---:| -| `Simulation.from_free` | 169, 179 | 14.9, 14.9 | -| `translate` | 30.3, 27.5 | 7.2, 7.8 | -| `runner` | 3.8, 3.0 | 3.5, 3.3 | - -A launch's bits don't change, which `tests/test_pulses.py` and `tests/test_cartesian_precision.py` hold across -thread counts. The sum that scales the field stays one sum in one order for that reason, so it stays on one thread. - +saves is the temporal pass. Ten fixed `RungeKutta()` steps of an envelope Kerr launch in +fused silica on a field grid, eight threads of an Intel Xeon Gold 6240 on a shared machine +(2026-11-03, ratios of medians): the spectral absorber took 0.90–0.92 of the `split_step` +collar's time and 0.47–0.58 of the in-stage term's, on a 256-column line and a 64 × 64 +Cartesian grid. A heavier response gives a smaller saving. + +## Devices + +The [tracking set](#the-tracking-set-at-020) shows where a GPU pays. Large Cartesian grids +gain most: `kerr_beam_384` takes 0.42–0.46 s on an NVIDIA H200 or an AMD Instinct MI325X +against 7.3–23.5 s on the CPUs. Modal problems are bound by kernel launches rather than +arithmetic: on an MI325X an Adams trial was 30 to 70 kernels of 2 to 9 µs launched one by +one, the device busy for a third of the run (2026-10-30; +[#357](https://github.com/LupoLab/solprop/issues/357)). The NVIDIA A40's binary64 rate is +a sixty-fourth of its binary32 rate, and its rows take two to eight times the H200's. + +- **A Cartesian step.** A low-storage step at 768 × 768 × 600 took 239 ms on an H200 and + 224 ms on an MI325X, 112 to 144 ms of it in its eight rank-3 transforms (2026-11-04); + changes to the passes beside them took it to 223 and 208 ms (2026-11-05). +- **Plans share one work area.** A device's plans of the scratch now share a work area: a + 768 × 768 × 600 run on an A40 fell from 38.5 to 22.6 GiB, the plans from 21.1 to 5.3 GiB, + with the same time (2026-11-05). +- **Settings** (SEP 46, NVIDIA H200, 2026-11-08). Graph replay of an Adams trial's source + pays (`ctc` 1.08 times slower without it); neither other team width does. An 8 GiB node + chunk instead of 1 GiB takes 6 to 25 % off the spatial routes. + + diff --git a/docs/dev/contributing.md b/docs/dev/contributing.md index 80d5d1c87..413e9cf31 100644 --- a/docs/dev/contributing.md +++ b/docs/dev/contributing.md @@ -19,8 +19,8 @@ uv sync The native backend lives in `native/` in the same repository and is a second distribution, solprop-native, at the same version and a required dependency. A plain `uv sync` therefore builds it and installs it editable into the same environment, which needs its C++ -toolchain, and `uv run poe check-all` runs solprop's gate and then the native gate; a change -that touches `native/` runs both and follows `native/AGENTS.md`. +toolchain. A change that touches `native/` runs solprop's gate and the native gate, +`uv run poe check` and `uv run poe check-native`, and follows `native/AGENTS.md`. [Building the native backend](../guide/performance/building-native.md) covers its builds; the [architecture](architecture.md) and [kernel contract](kernel-contract.md) describe the boundary between the two packages. @@ -69,9 +69,10 @@ history only if the difference between that artifact's commit and the working tr uncommitted changes, touches neither `native/` nor the solprop modules that `solprop_native` imports. Anything else is refused, and so is an expired artifact; each refusal names `uv sync` and the lightweight setup. A later plain `uv sync` or `uv run` builds native in its place, so -run with `uv run --no-sync`. The wheel keeps the commit it was built from, and `check_build`'s -lookup of the seam's names remains the guard at run time; the comparison of source digests is -for an editable checkout, and a wheel has no sources beside it to compare. +run with `uv run --no-sync`. The wheel keeps the commit it was built from, and that commit, +checked by `poe fetch-wheel`, is the guard: `check_build` compares source digests only in an +editable checkout, and a wheel has no sources beside it to compare, so nothing at import +catches a fetched wheel that is stale beside a newer solprop. ## Agree and implement a change @@ -114,9 +115,11 @@ its committed output. There are three galleries: rendered into `docs/auto_tutorials/`. Both are deterministic and large enough to show the physics, and may run their real problem at full length when that is what they demonstrate. CI's docs job runs every one again on each change - (`SOLPROP_RUN_EXAMPLES=tutorials`). -- **Worked examples**, `docs/examples/**/plot_*.py`: full-size problems of minutes to half - an hour, rendered into `docs/auto_examples/` and run only by hand. + (`SOLPROP_RUN_EXAMPLES=tutorials`) and keeps none of what they write; the published + pages are the committed output. +- **Worked examples**, `docs/examples/**/plot_*.py`: full-size problems that take from a + few seconds to about ten minutes each, rendered into `docs/auto_examples/` and run only + by hand; each page shows the stored result of its last run. After changing a gallery script, including its prose, regenerate its output with `uv run poe docs-examples ` (or with no name, every stale script) on an idle machine diff --git a/docs/dev/conventions.md b/docs/dev/conventions.md index 2ede8f5b3..7e6722006 100644 --- a/docs/dev/conventions.md +++ b/docs/dev/conventions.md @@ -92,7 +92,7 @@ for time-domain arrays and wherever only the sign matters. A Taylor phase about pure delay commutes with the origin shift and may be applied to a stored spectrum directly (Luna's `prop_taylor!`); an *absolute* spectral phase — measured data, a group delay read as an arrival time — must go through the spectrum helpers. The shift is `(−1)^k` on the -storage index for both layouts and nothing else: a pulse's `phase[0]` is therefore its +storage index for both layouts and nothing else: a pulse's `phases[0]` is therefore its carrier-envelope phase at its own peak on either grid, independent of the window length (Luna's envelope-grid constant `exp(−iω₀ n_t δt/2)` is not carried). No other module conjugates anything. Energies, spectral densities, masks and windows are @@ -100,6 +100,24 @@ convention-free (`|Ẽ|²`). A round-trip test guards the sign: build a pulse wi group-delay dispersion, read the spectral phase back, delay it by τ and check that it arrives later. +**Transverse axes and their signs** (`FreeGrid` and `LineGrid`; a `RadialGrid`'s Hankel +transform has no direction). The stored transverse spectrum is the raw forward DFT of the +samples taken in the order of `FreeGrid.x` and `FreeGrid.y`, +`Ẽ(k_x, k_y) = Σ E(x, y) e^{−i(k_x x + k_y y)}` (NumPy's `fft2` over `(y, x)`, x fastest +in the node index), with `k_x` and `k_y` in unshifted FFT order. It has the time +transform's sign, and the boundary does not conjugate it. A beam travelling towards +x +with physical transverse wave number `κ_x > 0` carries `e^{+iκ_x x}` in the optics +convention and so `e^{−iκ_x x}` on the internal samples: it is stored at **negative** +`k_x`, and a stored column's axis is `k^{(s)} = −κ` (`spatial.mask_plane_offsets`, +[SEP 23](https://github.com/LupoLab/solprop/blob/main/docs/dev/seps/archive/sep-0023-far-field-aperture-spectra.md) §4.1). A **positive +displacement** `d_x` moves the beam towards +x, `E(x) → E(x − d_x)`, which multiplies the +stored spectrum by `e^{−i k_x d_x}`. A **positive tilt** `θ_x` makes the beam propagate +towards +x: the screen `e^{+i k x sin θ_x}` in the optics convention +(`coupling.elements.Alignment`, which converts it with `fourier.to_internal`), which is +`e^{−i k x sin θ_x}` on the internal samples (`pulses.SpatialPulse`), `k` the medium's real +wave number. The same holds for y. `tests/test_beam_alignment.py` and +`tests/coupling/test_transport.py` hold both signs. + The amplitude conversion is a separate, named boundary beside these Fourier helpers: `fourier.power_amplitude` maps internal `a` to saved `b`, and its inverse maps a resumed plane back. A session applies it on export (`backends.export.ExportRecipe` with @@ -123,7 +141,10 @@ from the wavelength limits `(λ_min, λ_max)` and the requested window `trange` - `ω_min = 2πc/λ_max`, `ω_max = 2πc/λ_min`, `ω_max_win = 1.1 ω_max`; - the **fine** grid is sampled at `ffac × f_max` (`δt_fine = 1/(ffac f_max)`, or the user's `δt` if finer); `ffac = 6` by default so that a cubic response (`E³`, reaching `3ω_max`) - is resolved; `ffac = 4` suffices for a response without third harmonic; `ffac ≥ 2`; + is resolved; `ffac = 4` suffices for a response without third harmonic; `ffac ≥ 2.2`, + so that the fine Nyquist frequency `ffac ω_max/2` reaches `ω_max_win` and the coarse + Nyquist bin lies at or past it (where rounding leaves it an ulp short at the minimum, + `ω_max_win` is moved onto it); - `n_to` = the transform size ≥ `trange/((1 − 2 collar_fraction) δt_fine)`, room for the temporal collar outside the request (`collar_fraction = 0.1` by default; `trange/δt_fine` under `collar_placement="inside"`); the realised window is `trange_even = n_to δt_fine` and @@ -131,8 +152,9 @@ from the wavelength limits `(λ_min, λ_max)` and the requested window `trange` - the coarse grid keeps the fine bins up to the first `ω > ω_max_win`, its size `n_t` rounded up to the smallest even divisor of `n_to` (so `2^k + 1` bins on a power-of-two grid; clamped to the fine grid); `δt = π/ω[−1]`, `n_t = 2 (n_omega − 1)`; -- invariants (asserted): `δt/δt_fine = n_to/n_t = ω_fine[−1]/ω[−1]`, and the coarse time - samples coincide with fine samples. +- invariants (asserted): `δt/δt_fine = n_to/n_t = ω_fine[−1]/ω[−1]`, the coarse time + samples coincide with fine samples, and the spectral window is exactly zero at the + zero-frequency and Nyquist bins, which the analytic signal does not double. Note that `ffac` changes the whole grid (δω, window length, `n_omega`), not only the fine one. @@ -226,7 +248,7 @@ mode per active bin, fixed modulus and random phase. Its field-grid modulus is `sqrt(hbar omega/domega) sqrt(2 pi)/dt`. The internal draw is divided by the entrance square root. It is not a circular-Gaussian draw. -**Spatial geometry** ([SEP 34](seps/archive/sep-0034-medium-flux.md)). Radial, Cartesian and +**Spatial geometry** ([SEP 34](https://github.com/LupoLab/solprop/blob/main/docs/dev/seps/archive/sep-0034-medium-flux.md)). Radial, Cartesian and line states retain physical V/m or V m units and have no modal power-weight row. They are measured with the scalar axial admittance of the medium at the plane, `Y_c = eps0 c² k_z/omega` per transverse column and bin, zero on nonpropagating, @@ -251,7 +273,7 @@ admitted only when every propagating column meets the adiabatic certificate: `delta* = expm1(Lambda tanh Lambda)` within `AdiabaticAccuracy` (default 1e-4 each; `solprop.adiabatic`). -**Field planes and coupling** ([SEP 31](seps/archive/sep-0031-simulation-coupling.md)). A +**Field planes and coupling** ([SEP 31](https://github.com/LupoLab/solprop/blob/main/docs/dev/seps/archive/sep-0031-simulation-coupling.md)). A `FieldPlane` holds a stored spectrum exactly as the output does: the optics-convention raw DFT of each column, referenced to the window centre, in √W (ordinary and general modal coordinates), V m (the Hankel spectrum of a radial field) or V/m (the DFT of a diff --git a/docs/dev/cpu-performance.md b/docs/dev/cpu-performance.md index 9795d87a2..480023359 100644 --- a/docs/dev/cpu-performance.md +++ b/docs/dev/cpu-performance.md @@ -4,15 +4,15 @@ This page records the CPU performance work on the compiled backend. It lists wha adopted, what was measured and rejected, and what remains open. The aim is that nobody repeats an experiment without knowing its result. Each entry gives the result in one or two lines and, where they are summarised, links to its measurements in -[benchmarks](benchmarks.md#indicative-results) or to -[SEP 29](seps/archive/sep-0029-compiled-backend-distribution.md). The open items are in the +[benchmarks](benchmarks.md#current-performance) or to +[SEP 29](https://github.com/LupoLab/solprop/blob/main/docs/dev/seps/archive/sep-0029-compiled-backend-distribution.md). The open items are in the [issues](https://github.com/LupoLab/solprop/issues?q=is%3Aopen+label%3Aperformance+label%3A%22area%3A+native%22). Timings follow the [benchmark rules](benchmarks.md#rules). They are short, bounded windows: fresh processes, same machine, interleaved arms. Results are compared within SEP 25's rounding bounds, never bitwise. A ratio "against `numba_cpu`" is that backend's time divided by the native backend's: above 1, the native backend is faster. `numba_cpu` -was retired by [SEP 43](seps/archive/sep-0043-retire-numba-cpu.md); such ratios record what was +was retired by [SEP 43](https://github.com/LupoLab/solprop/blob/main/docs/dev/seps/archive/sep-0043-retire-numba-cpu.md); such ratios record what was measured while it existed. ## Build and libraries @@ -24,7 +24,7 @@ measured while it existed. coupled-wall and modal capillary cases 10 to 75 times slower on a 32-core AVX-512 x86-64 server, and similarly on Windows and aarch64. With one runtime the backend is 2 to 7 times faster than `numba_cpu` on those cases at full width, and level with it at - one thread ([SEP 29](seps/archive/sep-0029-compiled-backend-distribution.md)). + one thread ([SEP 29](https://github.com/LupoLab/solprop/blob/main/docs/dev/seps/archive/sep-0029-compiled-backend-distribution.md)). - At start-up the backend fits a host OpenBLAS to its own pool, unless the user sets `OPENBLAS_NUM_THREADS`, `GOTO_NUM_THREADS` or `OMP_NUM_THREADS`. - A pthreads OpenBLAS is held to one thread. This covers a local build against a @@ -34,16 +34,16 @@ measured while it existed. to every logical CPU. - **Accelerate on macOS.** It matched or beat both OpenBLAS variants and native GEMM, except at one thread on the TE/TM wall, where it is the fastest option. -- **NEON FFTW on both Arm wheels**, in both precisions, with the Arm cycle counter. +- **NEON FFTW on both Arm wheels**, in double precision (a wheel carrying a single-precision + FFTW fails `native/ci/smoke.py`), with the Arm cycle counter. On Apple silicon it keeps the M1 baseline and deployment target, and FFTW and Kokkos share one OpenMP runtime. This enables FFTW's explicit codelets; compiler vectorisation alone does not select them ([build recipe](../guide/performance/building-native.md)). - Linux aarch64 (the manylinux wheel, Neoverse N1 baseline), measured on 16-core Google Axion (Neoverse V2) and Ampere Altra (Neoverse N1) machines. FFTW's own - benchmark, 1 thread: 1.16–1.18× faster in double precision and 1.9× in single - (geometric means over 22 one- and two-dimensional problems); at 16 threads - 1.07× and 1.2×. + benchmark, 1 thread: 1.16–1.18× faster in double precision (geometric means over 22 + one- and two-dimensional problems); at 16 threads 1.07×. - solprop A/B, same wheels otherwise, five FFT-heavy cases with both steppers: no case slower beyond its round-to-round range, and a geometric-mean time of 0.95 (V2) and 0.96 (N1) at 1 thread, 0.96 and 0.98 at 16 threads. The Raman and RK @@ -62,7 +62,7 @@ measured while it existed. ([#334](https://github.com/LupoLab/solprop/issues/334)). The same tree built both ways, with the same FFTW, OpenBLAS and SLEEF's AVX2 route in each; `benchmarks ab`, the tracking set at a quarter length, three rounds; the same steps and fields to rounding - ([ledger](benchmarks.md)). + ([measurements](benchmarks.md#builds-and-libraries)). - On an Intel Xeon Gold 6240 (18 cores of one socket, exclusive), `-march=cascadelake` (v4 with VNNI): geometric mean 0.984. The largest gains are at one thread (`argon_blueshift` 0.909, `ctc` 0.924, `grin_nonlinear` 0.943); at 16 threads none @@ -108,7 +108,7 @@ measured while it existed. threshold runs serially; a medium one runs on four threads; a large one runs at full width. The thresholds are a per-workspace record (`CpuExecution`), filled from the built-in table in `native/src/solprop_native/_execution.py`, which holds their reasons, - or from a machine calibration ([SEP 46](seps/archive/sep-0046-machine-calibration.md)). The + or from a machine calibration ([SEP 46](https://github.com/LupoLab/solprop/blob/main/docs/dev/seps/archive/sep-0046-machine-calibration.md)). The global thread setting is a cap, and explicitly set pools force their (clamped) widths. The small cases became 2.0 times faster than one thread (geometric mean) on an 18-core arm64 laptop and on a two-socket, 36-core AVX-512 server. @@ -213,7 +213,7 @@ measured while it existed. transform planned within the stage's share), and so still does this one without patient plans: the stage needs more of the levels' time than it gets. Timed alone, the measured threaded plans ran 0.53–1.05 of estimate's time - (medians 0.74 on the EPYC 7763, 0.91 on the Xeon, about 0.95 on the M5 Max), and + (medians 0.74 on the EPYC 7763, 0.91 on the Xeon Gold 6240, about 0.95 on the M5 Max), and estimate's serial plans 1.06–2.8 of measure's. Those timings ran outside the native wait scope, so LLVM's runtime woke its idle threads at each loop; the timing alone now runs inside it, as a step's transforms do (on the M5 Max a 4 × 10240 plan took @@ -346,7 +346,7 @@ measured while it existed. the per-element form. The other per-element transcendentals [#338](https://github.com/LupoLab/solprop/issues/338) listed (the envelope and trapezoid plasma columns, two-component magnitudes, the Adams corrector and dense - observation) were negligible in one-thread profiles of the tracked cases on the Xeon. + observation) were negligible in one-thread profiles of the tracked cases on the Xeon Gold 6240. The largest left is the lossy planar medium's complex square root (`hypot`), about 7 % of `planar`'s one-thread march. - **A pooled allocator.** Allocation service in the warmed propagation window is below @@ -406,8 +406,11 @@ Each has an issue: comparison is done (v4 against v3, above): wider vectors gained at most 9 % on an AVX-512 Xeon and on Zen 5, so it gives no case for explicit SIMD on its own. - A broad conversion to SIMD types is not justified. -- **A subnormal count on long runs** ([#340](https://github.com/LupoLab/solprop/issues/340)) and **reduced precision** ([#342](https://github.com/LupoLab/solprop/issues/342)). +- **A subnormal count on long runs** ([#340](https://github.com/LupoLab/solprop/issues/340)). + Reduced precision is not pursued: solprop is binary64 only (ADR-077). The value-safe flags (`-fno-math-errno`, `-fno-trapping-math`) were measured together in [#59](https://github.com/LupoLab/solprop/pull/59), with no net gain; [#334](https://github.com/LupoLab/solprop/issues/334) keeps that record. -- **SLEEF on Linux aarch64, and AVX-512 against AVX2**, unmeasured end to end - ([#339](https://github.com/LupoLab/solprop/issues/339)). +- **SLEEF's AVX-512 against its AVX2 variant**, unmeasured end to end + ([#339](https://github.com/LupoLab/solprop/issues/339)). SLEEF on Linux aarch64 was + measured level (1.00 on a Neoverse V2), so AUTO keeps the system libm there + (`native/cmake/VectorMath.cmake`, ADR-072). diff --git a/docs/dev/decisions.md b/docs/dev/decisions.md index 97241aa88..8cf955afb 100644 --- a/docs/dev/decisions.md +++ b/docs/dev/decisions.md @@ -67,15 +67,21 @@ it is qualified, [backends.md](backends.md); for the current seam, throughput. JAX therefore wins on neither problem in practice, and `numba_cpu` is the CPU backend either way; its per-element bodies are shared with a device family as this record intends. See [backends.md](backends.md) §5. +- **Now:** the `numba_cpu` backend and its numba and pyfftw dependencies are gone + (ADR-064); `native` is built from this repository's `native/`, released with solprop + and required ([SEP 43](https://github.com/LupoLab/solprop/blob/main/docs/dev/seps/archive/sep-0043-retire-numba-cpu.md)), and the two + backends are `native` and `numpy_ref` (ADR-077). The seam has no version number + (ADR-068) and no driver surface: each backend runs its own session ([SEP + 47](https://github.com/LupoLab/solprop/blob/main/docs/dev/seps/archive/sep-0047-run-ownership.md), ADR-079). ## ADR-003 — Kernel state layout `(n_batch, n_modes, n_pol, n_omega)` -- **Status:** accepted; amended by [SEP 47](seps/archive/sep-0047-run-ownership.md) §6.2, which +- **Status:** accepted; amended by [SEP 47](https://github.com/LupoLab/solprop/blob/main/docs/dev/seps/archive/sep-0047-run-ownership.md) §6.2, which removes the nominal `n_batch` from the single-trajectory seam: the state is `(n_modes, n_pol, n_omega)` and a group is a sequence of member problems; and by - [SEP 52](seps/archive/sep-0052-backend-shape.md) §5.4, which removes the remaining leading axis + [SEP 52](https://github.com/LupoLab/solprop/blob/main/docs/dev/seps/archive/sep-0052-backend-shape.md) §5.4, which removes the remaining leading axis of one everywhere: the backends' state, the operator's value tables, the memory ledgers - and a march snapshot's stored state + and a march snapshot's stored state (ADR-079) - **Context:** Luna has different array shapes per geometry and special code paths for scalar vs vector polarisation and for mode-averaged vs modal propagation. Polarisation support must not slow single-polarisation runs; batch mode must be a first-class leading axis. @@ -192,6 +198,8 @@ it is qualified, [backends.md](backends.md); for the current seam, three registers. Stepping across planes and interpolating them is ADR-039's opt-in. - **Consequences:** Saved fields are exact step endpoints. A run with many save planes takes slightly shorter steps near them (negligible at the usual ratios). +- **Now:** `numba_cpu` is retired (ADR-064); `native`'s Runge–Kutta march holds the + stage rows as described. ## ADR-010 — Fixed-quadrature multimode transform only @@ -206,7 +214,7 @@ it is qualified, [backends.md](backends.md); for the current seam, coarse-rule error estimate as an *alarm*, never a controller. Mode-averaged propagation is the `n_nodes = 1` case of the same pipeline with the effective-area normalisation. - **Consequences:** The ionisation rates, PPT among them, come from optmat - ([SEP 3](seps/archive/sep-0003-optmat-materials.md)); the quadrature order is a validated + ([SEP 3](https://github.com/LupoLab/solprop/blob/main/docs/dev/seps/archive/sep-0003-optmat-materials.md)); the quadrature order is a validated default with a convergence test in the manual. ## ADR-011 — Response definitions with declared traits, compiled into one fused pass @@ -239,7 +247,10 @@ it is qualified, [backends.md](backends.md); for the current seam, ## ADR-013 — Batch mode: lockstep with fixed schedules, or independent adaptive runs -- **Status:** accepted; batch agreement is held to ADR-049's rounding bound +- **Status:** superseded in part by ADR-079, which removed lockstep execution, its batch + axis and the `Batch` executor's groups; the independent half (`Local` and `Pool`, + spawned processes) stands ([scans.md](scans.md)). Batch agreement was held to ADR-049's + rounding bound - **Context:** Many small problems must run in a highly parallel way; several large ones in separate processes. Adaptive stepping in a vectorised batch forces every member onto the stiffest member's step; ensembles must use identical steps so the numerical error is a @@ -257,7 +268,11 @@ it is qualified, [backends.md](backends.md); for the current seam, ## ADR-014 — Stateful `Simulation` object -- **Status:** accepted +- **Status:** superseded in fact, by no single record: `Simulation` has no `reset()` or + `propagate_to(z)` (a run goes through the backend's session, SEP 47), its inputs are + read-only properties from which `with_input` and `with_mixture` derive new simulations + (the public API review, PR #872), and there is no batch mode (ADR-079). It still owns + translation and backend selection, and `prop_capillary` and `prop_gnlse` still build one - **Context:** Luna's free-function `run` cannot be re-run, reset or vectorised; the `LunaSim` branch showed a callable, re-runnable object is a better fit. - **Decision:** `Simulation` holds the physics objects, owns translation and backend selection, @@ -322,7 +337,7 @@ it is qualified, [backends.md](backends.md); for the current seam, order gate calibrates it; production runs (every ensemble member, every scan point where the schedule transfers) replay the scaled schedule. Dithering a schedule to decorrelate round-off is an unimplemented idea, and whether it would help at all is an open question - ([open questions](open-questions.md), "Round-off growth with varying operators"). + ([#262](https://github.com/LupoLab/solprop/issues/262)). - **Consequences:** Step schedules are first-class, saved with the output and re-loadable. ## ADR-020 — Priorities: accuracy and reliability, then CPU performance, then GPU @@ -352,6 +367,9 @@ it is qualified, [backends.md](backends.md); for the current seam, `benchmark`. Reference problems: linear-only (P0), N-soliton with phase (P1), analytic z-varying loss and dispersion (P2), cross-scheme Richardson with order gate (P3), and stored Luna results for the two target simulations. See [testing.md](testing.md). +- **Now:** the `NUMBA_DISABLE_JIT` lane and the identity-decorated kernel bodies went + with `numba_cpu` (ADR-064); the coverage lane measures solprop's Python with the + native wheel installed ([tooling.md](tooling.md)). ## ADR-023 — numba and pyfftw are core dependencies @@ -478,8 +496,10 @@ Withdrawn (development-process record, not a design decision). ## ADR-029 — Prefer the installed native backend when no backend is specified -- **Status:** accepted; sets the default selection that ADR-002 leaves open; its fallback - is ADR-064's +- **Status:** superseded by ADR-064 and ADR-077: native is a required dependency and + `backend="auto"` is `native`, with no fallback + ([SEP 43](https://github.com/LupoLab/solprop/blob/main/docs/dev/seps/archive/sep-0043-retire-numba-cpu.md)). It set the default selection that + ADR-002 left open - **Context:** the optional native backend has measured CPU and GPU improvements, and installing its target-specific build should make ordinary propagation use it. Numba CPU remains a core dependency and the portable fallback. This is an installation policy, @@ -528,7 +548,7 @@ Withdrawn (development-process record, not a design decision). 20 bar gradient. The rejected alternative, carrying the true-power amplitude as the internal state, would have changed the first stage pass and the on-axis synthesis in every backend for the same result. The first approximation was removed by - [SEP 34](seps/archive/sep-0034-medium-flux.md) (2026-10-23): the spatial functionals, launches + [SEP 34](https://github.com/LupoLab/solprop/blob/main/docs/dev/seps/archive/sep-0034-medium-flux.md) (2026-10-23): the spatial functionals, launches and noise now use the medium's axial admittance, and a radial gas gradient carries the matching endpoint term. @@ -592,7 +612,7 @@ Withdrawn (development-process record, not a design decision). when the full gate (`poe check`, see [tooling.md](tooling.md)) and continuous integration are green. Design documents under `docs/dev/` describe the code as it is, and a change that alters the design updates them in the same pull request: a new or - reversed decision as a new record here, open work on the [roadmap](roadmap.md), and a + reversed decision as a new record here, open work in an issue, and a deliberate difference from Luna.jl's behaviour on the [differences from Luna](../guide/workflows/luna.md) page. Luna functionality is added when a use case needs it. Numerical claims need an analytic or independent reference and @@ -605,7 +625,7 @@ Withdrawn (development-process record, not a design decision). - **Context:** A portable `solprop-native` build — no vendor BLAS, generic x86-64 — lost to `numba_cpu` on every measured case at one thread: Numba compiles for the processor it runs on and uses NumPy's OpenBLAS, which selects its kernels at run time. Builds compared - on an 18-core-per-socket AVX-512 server ([benchmarks.md](benchmarks.md#backends-and-builds)) + on an 18-core-per-socket AVX-512 server ([benchmarks.md](benchmarks.md#builds-and-libraries)) separated the local build's gain: the vendor BLAS is all of it on capillary problems (2.6–3.8× on straight capillaries), and the instruction set most of it on the general route. Against `x86-64-v3`, an `x86-64-v2` build's median cost on the benchmark core is @@ -635,11 +655,14 @@ Withdrawn (development-process record, not a design decision). from source. The reference build is the gate's tidy and sanitizer build; the gate builds and smoke-tests the distribution wheel. MKL, 1.4–1.8× faster than OpenBLAS on TE/TM walls, remains a local-build choice. +- **Now:** the `numba_cpu` fallback of `backend="auto"` was removed by ADR-064: below a + wheel's baseline `auto` refuses. The x86-64 wheels are built for `x86-64-v3` and, as a + second variant, `x86-64-v2` (`.github/workflows/wheels.yml`). ## ADR-035 — Enhancement proposals for major changes - **Status:** accepted; amends ADR-033. Its implementation order is amended by ADR-061, - [SEP 43](seps/archive/sep-0043-retire-numba-cpu.md) (which retired `numba_cpu`), + [SEP 43](https://github.com/LupoLab/solprop/blob/main/docs/dev/seps/archive/sep-0043-retire-numba-cpu.md) (which retired `numba_cpu`), ADR-068 and ADR-077: a feature now lands on `native` and `numpy_ref`, in either order - **Context:** Under ADR-033 every change is an ordinary branch and pull request. That suits fixes and small additions, but not a new model, route or numerical scheme: such @@ -653,8 +676,8 @@ Withdrawn (development-process record, not a design decision). form. A SEP is standalone — it cites solprop's own documentation and code, the literature and public reports, never another code's source (optmat excepted, SEP 0 §7) or private notes — and carries the motivation, the theory with its references, the - implementation options and the verification plan. Accepted SEPs are listed on the - [roadmap](roadmap.md). They are implemented in phases on branches, `numpy_ref` first, + implementation options and the verification plan. Accepted SEPs are listed in the + [SEP index](seps/index.md). They are implemented in phases on branches, `numpy_ref` first, then `numba_cpu`, then the native CPU build, until the backends agree; each phase appends a report of its deviations, decisions, verification and open questions to the SEP. A finished SEP is archived under `docs/dev/seps/archive/` and linked from the manual @@ -664,7 +687,7 @@ Withdrawn (development-process record, not a design decision). - **Consequences:** SEPs are public design records in the developer documentation. ADRs still record durable decisions and are what code cites; the manual and design pages describe the code as it is, and a final SEP is not updated to follow them. - `tests/test_seps.py` keeps the SEP files, their index and the roadmap consistent with + `tests/test_seps.py` keeps the SEP files and their index consistent with each SEP's status. ## ADR-036 — Dense observation for the low-call Adams march @@ -679,12 +702,12 @@ Withdrawn (development-process record, not a design decision). ## ADR-037 — The low-call Adams method: one-call PEC, variable order -- **Status:** accepted; made the default integrator by ADR-045; amended by ADR-057 (the spatial routes' default collar scheme, and an opt-in quiet collar) +- **Status:** accepted; made the default integrator by ADR-045; amended by ADR-057 (the spatial routes' default collar scheme, and an opt-in quiet collar); its comparison variants removed by ADR-077 - **Context:** SEP 13 compared interaction-picture Adams methods for responses that dominate a run's cost: explicit Adams-Bashforth, PEC and PECE, matched and one-order-higher correctors, fixed and variable order. It ran them at full length on a gas-flow capillary at 1 and 2 mJ, and on RDW, CtC, GNLSE and soliton cases - ([SEP 14](seps/archive/sep-0014-stepper-efficiency.md)). + ([SEP 14](https://github.com/LupoLab/solprop/blob/main/docs/dev/seps/archive/sep-0014-stepper-efficiency.md)). - **Decision:** `solprop.stepper.multistep.Multistep` is one-call PEC: an Adams-Bashforth predictor of order *q*, one source call at the predicted field, and an Adams-Moulton corrector one order higher through it. The step is controlled on the @@ -708,12 +731,14 @@ Withdrawn (development-process record, not a design decision). - **Consequences:** `numpy_ref`, `numba_cpu` and `native` implement it, in both formulations of ADR-041 and, beside a coupled flow, as ADR-044 describes; a backend that does not refuses `Multistep()` by name. `RungeKutta()` names IP-DOPRI5 (ADR-045). +- **Now:** `ComparisonMultistep` and the comparison variants were removed by ADR-077, + and `numba_cpu` by ADR-064; `numpy_ref` and `native` implement the method. ## ADR-038 — Step limits by route: no interval cap on diagonal flows, a start-up rule - **Status:** accepted; supersedes the interval cap of ADR-004 on the diagonal-flow routes - **Context:** On gas-flow capillaries - ([SEP 14](seps/archive/sep-0014-stepper-efficiency.md)), steps were limited by things + ([SEP 14](https://github.com/LupoLab/solprop/blob/main/docs/dev/seps/archive/sep-0014-stepper-efficiency.md)), steps were limited by things other than the error estimate. ADR-004 capped every step at the width of the Chebyshev interval containing it, and a choked end's table bisects to its width floor, so the runs took hundreds of µm-scale steps there. From `dz_init = 1e-4 L` the growth cap of @@ -756,7 +781,8 @@ Withdrawn (development-process record, not a design decision). ## ADR-039 — Opt-in dense output and natural-step saving -- **Status:** accepted; amends ADR-009 for `interpolate_planes` and `step_planes`; +- **Status:** accepted; its bitwise `numpy_ref` resume superseded by ADR-049 (agreement to + a rounding bound); amends ADR-009 for `interpolate_planes` and `step_planes`; supersedes ADR-036 - **Context:** ADR-009 lands every step on a save plane. With many planes that caps the steps at the plane spacing: on SEP 13's canonical capillary at `rtol=1e-3`, 501 planes @@ -777,7 +803,7 @@ Withdrawn (development-process record, not a design decision). grows exponentially across the step and no polynomial follows it. The same guard applies to the Adams interpolant. - **Landed still:** the end of the run and every hard kink. - - **Refused** ([SEP 14](seps/archive/sep-0014-stepper-efficiency.md) §5): the per-step + - **Refused** ([SEP 14](https://github.com/LupoLab/solprop/blob/main/docs/dev/seps/archive/sep-0014-stepper-efficiency.md) §5): the per-step temporal collar, a coupled flow, the `modified` noise model and a fixed schedule. - **Resume.** A file whose last plane was interpolated is refused for `resume=True`, for both steppers; `resume="interpolated"` continues afresh from it and records the @@ -811,6 +837,11 @@ Withdrawn (development-process record, not a design decision). uninterrupted one to rounding (ADR-049). - The host keeps five field-sized coefficient buffers while a step that crosses a plane is held; `native` copies the seven stages to the host once per such step. +- **Now:** `numba_cpu` is retired (ADR-064) and `ComparisonMultistep` removed (ADR-077). + The continuous extension is `solprop.stepper.tableau.extension_coefficients`, applied + by the Runge–Kutta engine's `extend` (`backends/engines.py`), and the run's session + observes the plane; there is no `_dense_stages` hook and no `propagate_to` ([SEP + 47](https://github.com/LupoLab/solprop/blob/main/docs/dev/seps/archive/sep-0047-run-ownership.md)). ## ADR-040 — Tables accept a tail at the sampling-noise floor of their positions @@ -843,7 +874,7 @@ Withdrawn (development-process record, not a design decision). controller) take longer steps near a choked end. ## ADR-041 — One Adams family, two formulations: interaction and exponential -- **Status:** accepted ([SEP 16](seps/archive/sep-0016-unified-multistep.md)); the default +- **Status:** accepted ([SEP 16](https://github.com/LupoLab/solprop/blob/main/docs/dev/seps/archive/sep-0016-unified-multistep.md)); the default formulation is ADR-045's - **Context:** SEP 15 found that interpolating the interaction picture's transported source limits the linear phase an Adams step can take in a driven bin to about one, @@ -869,9 +900,15 @@ Withdrawn (development-process record, not a design decision). - **Consequences:** a backend without `_adams_lab_source` refuses the exponential formulation by name. Switching formulation mid-run is not defined; a resume restarts the history under the run's own formulation. +- **Now:** the reference march is `HostAdamsMarch` + (`backends/numpy_ref/marches/adams.py`) and the lab-frame source the workspace's + `lab_source` (`NumpyWorkspace.lab_source`); native's compiled march evaluates its own. + `StepDriver` and its hooks were removed by [SEP + 47](https://github.com/LupoLab/solprop/blob/main/docs/dev/seps/archive/sep-0047-run-ownership.md), and the CF4 sections and comparison + variants by ADR-077. ## ADR-042 — The compensated reference for varying operators: the transported treatment -- **Status:** accepted ([SEP 16](seps/archive/sep-0016-unified-multistep.md)) +- **Status:** accepted ([SEP 16](https://github.com/LupoLab/solprop/blob/main/docs/dev/seps/archive/sep-0016-unified-multistep.md)) - **Context:** the exponential formulation integrates its source exactly against a constant operator's flow. Along a varying operator the exact flow $U = e^{\Phi(z_2)-\Phi(z_1)}$ is available, but the source's polynomial is integrated @@ -902,9 +939,12 @@ Withdrawn (development-process record, not a design decision). (SEP 16 §4.2) was built opt-in, measured slower on `numba_cpu` (4 % on the canonical run, 13 to 15 % on the M2/RDW run, with the same calls and fields) and removed at review (SEP 16, phase 3b report and D26); the exponential form stays the transport. +- **Now:** the untransported witness is selected by a test hook of the reference backend + (`NumpyRefBackend._use_adams(..., compensation="untransported")`); `numba_cpu` is + retired (ADR-064). ## ADR-043 — The Adams march hands its state-sized work to an engine -- **Status:** accepted ([SEP 16](seps/archive/sep-0016-unified-multistep.md)); amended by +- **Status:** accepted ([SEP 16](https://github.com/LupoLab/solprop/blob/main/docs/dev/seps/archive/sep-0016-unified-multistep.md)); amended by ADR-060, under which `native` executes the exponential march's controller itself - **Context:** a march that does its field arithmetic on host arrays and asks a backend only for a source and an adoption makes `native` copy the state, the predicted field and @@ -929,9 +969,14 @@ Withdrawn (development-process record, not a design decision). - **Consequences:** an engine must reproduce `HostHistory` within the parity bounds of the compiled backends. A varying operator's per-sample rate is formed on the host (`translate.linop.phi_rate`) and handed to the engine, one row per accepted step. +- **Now:** the engine protocol is `solprop.backends.engines.AdamsEngine` and the + reference's engine `HostHistory` (`backends/numpy_ref/multistep.py`); native's + compiled march has its own resident engine (ADR-060). `StepDriver` and its + `_adams_engine` hook (SEP 47), lockstep (ADR-079) and the PECE path are gone, and the + dense hold and observation are the session's (`backends/engines.py`). ## ADR-044 — The exponential formulation beside a coupled flow -- **Status:** accepted ([SEP 16](seps/archive/sep-0016-unified-multistep.md)) +- **Status:** accepted ([SEP 16](https://github.com/LupoLab/solprop/blob/main/docs/dev/seps/archive/sep-0016-unified-multistep.md)) - **Context:** a coupled flow (a coherent capillary wall, a split block, a moving guide) is not a diagonal exponential. The interaction formulation would transport its history through the flow's inverse actions, whose conditioning grows with loss. Beside a @@ -957,12 +1002,17 @@ Withdrawn (development-process record, not a design decision). section edge is not a kink unless declared; a declared kink restarts the history. *Amended 2026-11-10 (SEP 47 phase 4):* `native` keeps them resident at any width and whichever route each bin takes, on a CPU and a device build alike. +- **Now:** `coupled_moments` is in `backends/numpy_ref/adams_kernels.py`, and the frozen + block comes from the workspace's `coupled_block`; `StepDriver._adams_block` ([SEP + 47](https://github.com/LupoLab/solprop/blob/main/docs/dev/seps/archive/sep-0047-run-ownership.md)), the CF4 sections (ADR-077) and + `numba_cpu` (ADR-064) are gone. ## ADR-045 — `Multistep()` is a default integrator, chosen per interface by ADR-055; `RungeKutta()` names the march -- **Status:** accepted ([SEP 16](seps/archive/sep-0016-unified-multistep.md)); amended by +- **Status:** accepted ([SEP 16](https://github.com/LupoLab/solprop/blob/main/docs/dev/seps/archive/sep-0016-unified-multistep.md)); amended by ADR-055, which chooses each interface's default: `RungeKutta()` on `prop_gnlse`, `prop_waveguide` and `prop_free`, `Multistep()` on `prop_capillary` (an override of - its rule), `prop_radial` and `prop_planar` + its rule), `prop_radial` and `prop_planar`; its memory refusal naming `RungeKutta()` + removed by ADR-065 (no memory admission) - **Context:** the exponential formulation runs on every route and backend, devices included, and took the fewest calls on every case SEP 16 measured. With the error norm over the whole active band it was, at matched error on one CPU thread, @@ -990,6 +1040,7 @@ Withdrawn (development-process record, not a design decision). Adams method's smaller negative-real stability interval under the in-stage collar; a few fixed steps start at order one. Tests whose subject is the interaction formulation or the Runge–Kutta march name it. +- **Now:** `prop_radial` is `prop_free` on a `RadialGrid`. ## ADR-046 — A resume continues the Adams history - **Status:** accepted; agreement to a rounding bound (ADR-049) @@ -1014,6 +1065,7 @@ Withdrawn (development-process record, not a design decision). afresh (roadmap). Superseded in part by SEP 29 §6.6: `native` exports and installs its resident rows, and continues too. A file holds one snapshot, of the history's size (7 to about 60 copies of the state), rewritten at every save. +- **Now:** `numba_cpu` is retired (ADR-064), and open work is in issues (ADR-062). ## ADR-047 — Signals reach a run between its commits - **Status:** accepted; "bit for bit on the host engines" is restated by ADR-049 as @@ -1070,7 +1122,7 @@ Withdrawn (development-process record, not a design decision). ## ADR-049 — Reproducibility to the error bound - **Status:** accepted - ([SEP 25](seps/archive/sep-0025-rounding-level-reproducibility.md)); supersedes the bitwise + ([SEP 25](https://github.com/LupoLab/solprop/blob/main/docs/dev/seps/archive/sep-0025-rounding-level-reproducibility.md)); supersedes the bitwise clauses of ADR-013 (batches bit-identical to sequential runs), ADR-022 (bitwise repeatability and thread-count invariance tests), ADR-034 (pins for the reference build) and ADR-039 (`numpy_ref` resumes bitwise), and restates the "bit for bit" @@ -1130,7 +1182,7 @@ Withdrawn (development-process record, not a design decision). ## ADR-050 — A replay-only low-storage march, accepted in place, with no estimate - **Status:** accepted - ([SEP 24](seps/archive/sep-0024-low-storage-interaction-picture-runge-kutta.md)); + ([SEP 24](https://github.com/LupoLab/solprop/blob/main/docs/dev/seps/archive/sep-0024-low-storage-interaction-picture-runge-kutta.md)); amends ADR-009's stage clause and, for this march only, ADR-047's premise that a step in flight holds nothing committed - **Context:** a Cartesian free-space state can take gigabytes, and the Runge–Kutta march @@ -1171,12 +1223,17 @@ Withdrawn (development-process record, not a design decision). replay of the Runge–Kutta march catches before it writes the state. A resume rebuilds the half-step flow table from its own first step and agrees with the uninterrupted run to rounding. The kernel contract and the output schema carry the kind. +- **Now:** the reference march is `HostLowStorageMarch` + (`backends/numpy_ref/marches/low_storage.py`) over the engine `NumpyLowStorage` + (`backends/numpy_ref/engines.py`); native's is its compiled march's resident engine + (`native/src/march/low_storage.cpp`). `StepDriver`, `propagate_to` and the lockstep + runner were removed ([SEP 47](https://github.com/LupoLab/solprop/blob/main/docs/dev/seps/archive/sep-0047-run-ownership.md), ADR-079). ## ADR-051 — No compatibility with earlier configurations, and one TDSE source form - **Status:** accepted; withdraws the source filter of - [SEP 12](seps/archive/sep-0012-tdse-nonlinear-response.md) and - [SEP 26](seps/archive/sep-0026-edge-free-tdse-source.md); one exception added on + [SEP 12](https://github.com/LupoLab/solprop/blob/main/docs/dev/seps/archive/sep-0012-tdse-nonlinear-response.md) and + [SEP 26](https://github.com/LupoLab/solprop/blob/main/docs/dev/seps/archive/sep-0026-edge-free-tdse-source.md); one exception added on 2026-10-28 (`collar_placement="inside"`); its rules on resuming and on recorded fields narrowed by ADR-063, and restored by ADR-066 - **Context:** before a first release there are no external output files to keep. An @@ -1192,7 +1249,7 @@ Withdrawn (development-process record, not a design decision). `ComparisonMultistep`, both Raman spellings, the Luna witnesses (`LEGACY_CONVENTIONS`, the trapezoid plasma rule) and `vacuum_end="floor"`. - **The exception: `collar_placement="inside"`** (maintainer, 2026-10-28). It rebuilds - the time-window geometry of before [SEP 21](seps/archive/sep-0021-absorbing-boundaries.md), + the time-window geometry of before [SEP 21](https://github.com/LupoLab/solprop/blob/main/docs/dev/seps/archive/sep-0021-absorbing-boundaries.md), the collar inside the request, bin for bin. It stays public because the Luna witnesses and the frozen cross-backend comparisons were measured on that geometry, and re-measuring them is work of its own. Tests pin it, through `tests/legacy_geometry.py`, @@ -1205,10 +1262,12 @@ Withdrawn (development-process record, not a design decision). change that moves an identity bumps the version it moves and adds no compatibility layer. ADR-066 sets the resume policy: a file of another output schema is never resumed, by that precondition, and a field added to a record refuses every earlier file. +- **Now:** `ComparisonMultistep` was removed by ADR-077. ## ADR-052 — One thread budget per process, which every pool stays within -- **Status:** accepted; amended by ADR-056 (one thread per core) +- **Status:** accepted; amended by ADR-056 (one thread per core) and ADR-070 (the budget + on a chip with cores of several kinds) - **Context:** each piece sized its threads its own way. `numba_cpu` read the affinity mask and the root control group's `cpu.max`, rounded to nearest, but not `NUMBA_NUM_THREADS`, so a large problem failed at construction when that was below the @@ -1257,6 +1316,8 @@ Withdrawn (development-process record, not a design decision). `SOLPROP_THREADS` to its share; `Pool` already shares its budget among its workers. Virtual machines (cloud instances included) and Slurm jobs set no quota by default; their limit is the mask. +- **Now:** `numba_cpu` and `NUMBA_NUM_THREADS` went with ADR-064; `SOLPROP_THREADS` and + the budget are as decided. ## ADR-053 — Runtime type checks in one CI lane; the CI lanes sharded @@ -1297,7 +1358,7 @@ Withdrawn (development-process record, not a design decision). - **Status:** superseded by ADR-077 (binary64 only). It amended [architecture.md §1](architecture.md) ("Double precision throughout") and recorded an exception to ADR-020 for the `mlx` route - ([SEP 33](seps/archive/sep-0033-single-precision-mlx.md)) + ([SEP 33](https://github.com/LupoLab/solprop/blob/main/docs/dev/seps/archive/sep-0033-single-precision-mlx.md)) - **Context:** Apple-silicon GPUs have several times the CPU's single-precision throughput and no binary64 arithmetic, and Kokkos has no Metal backend. Whether a problem survives binary32 depends on the problem, so it has to be measured, against @@ -1321,7 +1382,7 @@ Withdrawn (development-process record, not a design decision). ## ADR-055 — Noise on by default, and defaults chosen for each interface -- **Status:** accepted ([SEP 37](seps/archive/sep-0037-noise-and-stepper-defaults.md)); amends +- **Status:** accepted ([SEP 37](https://github.com/LupoLab/solprop/blob/main/docs/dev/seps/archive/sep-0037-noise-and-stepper-defaults.md)); amends ADR-045 and ADR-008; the capillary's override of the selection rule requalified on 2026-10-28 and re-timed on 2026-10-31 - **Context:** every run was noiseless unless it asked, every interface stepped with @@ -1399,10 +1460,14 @@ Withdrawn (development-process record, not a design decision). (the maintainers' ruling of 2026-10-28; `docs/guide/results/resuming.md`). - Low-energy GNLSE runs take more steps with noise (the seed's dynamics are resolved). Replayed schedules for noisy ensembles must be calibrated with noise on. +- **Now:** single precision was removed by ADR-077, and `prop_radial` is `prop_free` on + a `RadialGrid`. ## ADR-056 — One thread per core, and idle native threads sleep at once -- **Status:** accepted; amends ADR-052 +- **Status:** superseded in part by ADR-071 (idle threads spin briefly within native work + rather than sleep at once); amends ADR-052; amended by ADR-070 (the budget on a chip with + cores of several kinds) - **Context:** the thread budget counted CPUs, so on a machine with two hardware threads per core a default run took two threads per core. The native backend left OpenMP's waiting to the runtime, whose idle threads spin between parallel regions, and it runs @@ -1437,7 +1502,7 @@ Withdrawn (development-process record, not a design decision). ## ADR-057 — Temporal boundaries: the collar outside the window, a watched edge, a quiet collar on request - **Status:** accepted; amends ADR-025 and ADR-037 -- **Context:** [SEP 21](seps/archive/sep-0021-absorbing-boundaries.md) changed the +- **Context:** [SEP 21](https://github.com/LupoLab/solprop/blob/main/docs/dev/seps/archive/sep-0021-absorbing-boundaries.md) changed the temporal boundaries' defaults: - the collar lies outside the requested window (the grid widens to `trange / (1 - 2 collar_fraction)`, `collar_fraction` 0.1); @@ -1533,10 +1598,12 @@ Withdrawn (development-process record, not a design decision). exponential Adams march, the cap removes the gain. A per-step check that would lift the cap is [#224](https://github.com/LupoLab/solprop/issues/224). - The monitor's record counts `collar_left_out_checks`. +- **Now:** single precision was removed by ADR-077, and `numba_cpu` by ADR-064. ## ADR-058 — The 0.x releases are unstable; the first output schema is 1 -- **Status:** accepted (maintainer, 2026-10-28) +- **Status:** accepted (maintainer, 2026-10-28); `KERNEL_SCHEMA_VERSION` removed by ADR-068, + and the reserved batch axis by ADR-079 - **Context:** ADR-021 promised nothing about stability until a first release, and nothing said what the first release promises. The exported surface is large (`solprop.translate` alone exports 61 names), and some internal seams are known to be @@ -1558,11 +1625,16 @@ Withdrawn (development-process record, not a design decision). made now would freeze seams already known to need work. - **Consequences:** a released version cannot read a development output file; keep an older install for those. ADR-066 sets the resume policy. +- **Now:** the seam has no version number (ADR-068). Of the reserved seams, the batch + axis was removed by [SEP 52](https://github.com/LupoLab/solprop/blob/main/docs/dev/seps/archive/sep-0052-backend-shape.md) (ADR-079), and + the step loops are each backend's session and marches ([SEP + 47](https://github.com/LupoLab/solprop/blob/main/docs/dev/seps/archive/sep-0047-run-ownership.md), ADR-079). ## ADR-059 — Host vector maths on SLEEF for the native CPU kernels on x86-64 - **Status:** accepted 2026-11-01, having shipped in the 0.1.0 wheels; the maintainers - asked for SLEEF to be evaluated and adopted if it paid (2026-10-28) + asked for SLEEF to be evaluated and adopted if it paid (2026-10-28); amended by ADR-072 + (SLEEF on macOS arm64 too) - **Context:** a profile of the native exponential Adams trial found glibc's scalar `exp`, `cos` and `sin` about two thirds of its predict pass on a pressure-gradient helium case on an AMD EPYC 7763. A survey of the native CPU backend with Valgrind's @@ -1631,7 +1703,9 @@ Withdrawn (development-process record, not a design decision). corrector and dense observation, the separable stage propagators). ## ADR-060 — The exponential Adams march executes natively; solprop's is the reference -- **Status:** accepted ([SEP 39](seps/archive/sep-0039-native-adams-march.md)); amends ADR-043 +- **Status:** accepted ([SEP 39](https://github.com/LupoLab/solprop/blob/main/docs/dev/seps/archive/sep-0039-native-adams-march.md)); amends ADR-043; + extended by ADR-069; its host march for configurations the native march did not cover + removed by [SEP 47](https://github.com/LupoLab/solprop/blob/main/docs/dev/seps/archive/sep-0047-run-ownership.md) phase 5 - **Context:** ADR-043 keeps the Adams controller in solprop and hands the state-sized work to an engine, so each trial of a native run crosses the seam several times and runs Python on the host: 150 to 210 µs per trial on an AMD EPYC 7763 before SEP 39, @@ -1664,6 +1738,13 @@ Withdrawn (development-process record, not a design decision). - Within one build the two marches read the same tables and norms and take the same steps; across builds they differ by rounding, as any two builds do. - A native run's metadata records which march stepped it (`adams_march`). +- **Now:** the reference march is `HostAdamsMarch` + (`backends/numpy_ref/marches/adams.py`), which `numpy_ref` runs. Native has no Python + march and refuses by name what its march does not step ([SEP + 47](https://github.com/LupoLab/solprop/blob/main/docs/dev/seps/archive/sep-0047-run-ownership.md) phase 5), so no configuration issues + `HostMarchWarning`, and the class was removed in 0.3. The native session books a call's attempts + (`native/src/session/session.cpp`, as the reference's `HostSession.record` does); + `StepDriver` was removed. ## ADR-061 — Backend tiers: where features land first @@ -1737,7 +1818,7 @@ Withdrawn (development-process record, not a design decision). - **Status:** superseded by ADR-066, except its amendment on how often the schema is bumped, which stands. Accepted (maintainer, 2026-11-01, with - [SEP 42](seps/archive/sep-0042-tolerant-resume.md)); narrowed ADR-051 and set the policy + [SEP 42](https://github.com/LupoLab/solprop/blob/main/docs/dev/seps/archive/sep-0042-tolerant-resume.md)); narrowed ADR-051 and set the policy ADR-058 left open; amended 2026-11-02 for how often the schema is bumped (the last bullet) - **Context:** a file resumed only when the rebuilt run's configuration hash equalled @@ -1776,7 +1857,7 @@ Withdrawn (development-process record, not a design decision). table of classes and one table of neutral values rather than versioned hashers. - **Consequences:** a new recorded field needs a decision, which the frozen records of `tests/output/test_record_stability.py` enforce; each release adds its frozen records - from its tag (`docs/dev/releasing.md`). 0.2.0, the first release of output schema 2, + from its tag (`docs/dev/releasing.md`); both were removed with ADR-066. 0.2.0, the first release of output schema 2, is tagged after SEP 42, so that every released reader of schema 2 knows these rules; a later change to what force records bumps the schema. - **Amendment, how often the schema is bumped** (maintainer, 2026-11-02): the bump rule @@ -1786,13 +1867,17 @@ Withdrawn (development-process record, not a design decision). are not compatible with one another, and a known difference between them is refused by name rather than read two ways (#80, the Multistep ledger's run-length encoded orders, folded into schema 2). +- **Now:** the comparison table (`solprop.output.compatibility`), `NEUTRAL_VALUES` and + `resume="force"` were removed with ADR-066, which compares the configuration hash + exactly. ## ADR-064 — `numba_cpu` is retired: no Tier 2, and the documentation lane runs on the wheel -- **Status:** accepted, with [SEP 43](seps/archive/sep-0043-retire-numba-cpu.md); supersedes +- **Status:** accepted, with [SEP 43](https://github.com/LupoLab/solprop/blob/main/docs/dev/seps/archive/sep-0043-retire-numba-cpu.md); supersedes ADR-061's Tier 2 and its statement that the documentation build installs no native backend, removes the fallback of ADR-029, and ends ADR-023; its single-precision clause - for `backend="auto"` is amended by ADR-077 (binary64 only) + for `backend="auto"` and Tier 3 (`mlx`) are amended by ADR-077 (binary64 only, two + backends), and its TDSE clause by ADR-078 (a TDSE response runs on `native`) - **Context:** every test, route and kernel of `numba_cpu` was a second copy of what `native` does. In the 0.1.0 history it took 1.5 to 2.8 times as long as native by geometric mean, with no winning configuration among the 22 measured on three machines, @@ -1840,13 +1925,15 @@ Withdrawn (development-process record, not a design decision). - An exact pin means a new release replaces a source or GPU build with that release's CPU wheel. Released source builds take a local version label, and a GPU job can set `SOLPROP_REQUIRE_DEVICE`, which reads the actual build. - - Records keep the rows `numba_cpu` wrote, as evidence of what it measured. Records of - decisions that name it, this log's included, stay as written. + - Records keep the rows `numba_cpu` wrote, as evidence of what it measured. The SEPs + that name it stay as written; the decisions in this log that name it say so. +- **Now:** `backend="auto"` resolves a TDSE response to `native` like every other run + (ADR-078), and `mlx` and single precision are retired (ADR-077). ## ADR-065 — No memory admission: a run that doesn't fit fails with an out-of-memory error - **Status:** accepted, 2026-11-04. Supersedes the memory admission of SEP 22, SEP 41 and - earlier decisions. Those records stay as written. + earlier decisions (ADR-045's refusal). The SEPs stay as written; ADR-045 says so. - **Decision:** solprop no longer estimates a run's memory before allocating or compares it with a budget. `estimate_memory`, `estimate_guide_memory`, `solprop.driver.memory`, `memory_budget=`, `SOLPROP_MEMORY_BUDGET`, `--memory-budget`, `MemoryBudgetError`, @@ -1872,11 +1959,12 @@ Withdrawn (development-process record, not a design decision). - A run keeping its planes in memory can run out partway through, and a general modal guide fails while its tables are built. Both were previously refused or warned about before they started. +- **Now:** there are no batch groups (ADR-079); scan workers stay bounded as described. ## ADR-066 — A resume continues on an exact configuration hash - **Status:** accepted, 2026-11-04. Supersedes ADR-063 and the design of - [SEP 42](seps/archive/sep-0042-tolerant-resume.md), except ADR-063's amendment on how often + [SEP 42](https://github.com/LupoLab/solprop/blob/main/docs/dev/seps/archive/sep-0042-tolerant-resume.md), except ADR-063's amendment on how often the schema is bumped. Restores ADR-051's rule that every field is recorded. - **Context:** restarting a run is rare, and restarting from an earlier version essentially never happens. SEP 42's path-by-path comparison cost a classification for each new recorded @@ -1894,8 +1982,9 @@ Withdrawn (development-process record, not a design decision). `RunOutcome.resumes` and `forced_positions` are removed. So are `record_none` and the refusal of four-column `absorbed_power`: every field is recorded at its default, and development builds are not compatible with one another. - - Reading is unchanged. A file of output schema 2 written by another build still reads, - with an absent field taking its default. + - Reading is unchanged. A file of the current output schema written by another build + still reads, with an absent field taking its default; one of any other schema is + refused (ADR-058). - `source=` in `field_plane` and a scan's reuse of a finished point use the same hash. - Nothing is carved out of the key for rounding, and provenance stays in it. A carve-out was tried for a band rule's taps and dropped, as the measurement below shows it can't @@ -1914,8 +2003,8 @@ Withdrawn (development-process record, not a design decision). apart from 2 recipes with unseeded noise, which a resume redraws from the file's seed. All 31 differed between those and an Intel Xeon Gold 6240, which also had another glibc and Python patch version, in the launch, absorber rates, quadrature weights, effective areas - and noise spectra. Forcing other OpenBLAS kernels on the Xeon moved 23 to 27 of 34 recipes. - So a long job has to stay on one CPU family to resume. + and noise spectra. Forcing other OpenBLAS kernels on the Xeon Gold 6240 moved 23 to 27 of + 34 recipes. So a long job has to stay on one CPU family to resume. - **Why not a SEP:** SEP 42 stays `Final` as the record of what it did, with a note pointing here. The maintainer judged a decision record enough for removing a mechanism, and the same goes for ADR-067. @@ -1940,8 +2029,8 @@ Withdrawn (development-process record, not a design decision). ## ADR-068 — Native is the primary backend; `numpy_ref` stays the oracle for numbers - **Status:** accepted (maintainer), 2026-11-04. Amends ADR-061 and - [SEP 0](seps/sep-0000-process.md)'s implementation rules. Those records, and the SEPs - implemented under them, stay as written. + [SEP 0](seps/sep-0000-process.md)'s implementation rules, which say so. The SEPs + implemented under them stay as written. - **Context:** production runs on `native`, and the costs of the split between Python and native decide what those runs can do. The written rules still steered work as if the reference came first: a SEP was implemented on `numpy_ref` and then on native, the kernel @@ -1984,11 +2073,15 @@ Withdrawn (development-process record, not a design decision). - A wheel skips the comparison, and has only the pin and the name lookup between it and a mismatched solprop. `poe fetch-wheel` keeps its own check on the tree. - "Kernel schema N" in the code and the documents is history: the number a change took. +- **Now:** `StepDriver` and its protected surface were removed by [SEP + 47](https://github.com/LupoLab/solprop/blob/main/docs/dev/seps/archive/sep-0047-run-ownership.md): the crossings are the kernel contract + (the problem, the run request and the stage bundles) and the `Backend` protocol, + frozen in `tests/backends/test_driver.py`. `mlx` was retired by ADR-077. ## ADR-069 — The Runge–Kutta march and the boundary checks run natively, solprop's as reference - **Status:** accepted (maintainer), 2026-11-07, with - [SEP 45](seps/archive/sep-0045-native-rk-march.md). Extends ADR-060 to the adaptive Runge–Kutta march + [SEP 45](https://github.com/LupoLab/solprop/blob/main/docs/dev/seps/archive/sep-0045-native-rk-march.md). Extends ADR-060 to the adaptive Runge–Kutta march and to the boundary monitor's checks. - **Context:** after SEP 39 the native Adams march still returned to Python at every check of a busy boundary monitor, 100–250 µs each, and the Runge–Kutta march, the default of the fibre @@ -2011,6 +2104,10 @@ Withdrawn (development-process record, not a design decision). - **Consequences:** native Runge–Kutta trajectories moved once at rounding level (phase 2); the split collar's crossing limit sums in one sequential order (Q7); the driver's protected surface gained `_account_step`, `_statistics_step` and `_watched_step` for `_skip_step`. +- **Now:** `RungeKuttaPolicy` is in `solprop.backends.records`, and the reference march + is `RungeKuttaMarch` (`backends/numpy_ref/marches/runge_kutta.py`); `StepDriver` and + its hooks were removed ([SEP 47](https://github.com/LupoLab/solprop/blob/main/docs/dev/seps/archive/sep-0047-run-ownership.md)), and nothing + issues `HostMarchWarning`: the class was removed in 0.3. ## ADR-070 — On a chip with cores of several kinds, the budget is the fastest kind's cores @@ -2109,10 +2206,15 @@ Withdrawn (development-process record, not a design decision). thresholds; Linux, Windows and wider teams are unchanged. A grain calibrated per machine at start-up (from the measured region cost and a small-pass probe) is the general form and a lead; this decision measures one platform and keeps to it. +- **Now:** the thresholds are the built-in table of + `native/src/solprop_native/_execution.py` ([SEP + 46](https://github.com/LupoLab/solprop/blob/main/docs/dev/seps/archive/sep-0046-machine-calibration.md)), not `core.hpp`; the divisor and + the team cap are its `SPIN_DIVISOR` and `SPIN_MAX_TEAM`, and a machine calibration + (ADR-074) may replace the table. ## ADR-074 — A per-user calibration store, calibrated on first use, below explicit settings -- **Status:** proposed with SEP 46's implementation (PR #582), for the maintainer. +- **Status:** accepted (maintainer), 2026-11-09, with SEP 46's implementation (PR #582). - **Context:** the native backend's CPU execution settings (operation thresholds, medium and compact widths, the stable team, the waiting policy and team width, FFT plan efforts) were constants chosen on two or three machines; PR #576 found them not to transfer (ADR-073). @@ -2192,7 +2294,7 @@ Withdrawn (development-process record, not a design decision). ## ADR-076 — Runs keep the FFTW plans they measure, by transform, by default -- **Status:** proposed with PR #602 (issue #136), for the maintainer. +- **Status:** accepted (maintainer), 2026-11-09, with PR #602 (issue #136). - **Context:** measured plans for threaded rows win in the step (0.94–0.97, ADR-075), but planning them costs up to 12 s of a run's construction (`ctc` on 16 cores of an AMD EPYC 7763: 13.8 s against 1.6 s), so the policy left them at estimate. Wisdom outlived the @@ -2241,10 +2343,10 @@ Withdrawn (development-process record, not a design decision). across four comparisons on the EPYC (same build and against #598, two independent stored measurements), no slower than plans measured in place; `ctc` 1.003–1.017, its range spanning 1 with a second stored measurement, so the plan a single measurement - picks; `rdw` 1.00; the Xeon's geometric mean 1.015, every range spanning 1. Fields agree - to rounding. A first attempt that planned each transform from nothing measured a key - seeded twice twice and lost shared sub-plans (`rdw` 6.7 s cold on the Xeon against 1.4 s); - a transform to measure now starts from the workspace's own measurements. The store + picks; `rdw` 1.00; the Xeon Gold 6240's geometric mean 1.015, every range spanning 1. + Fields agree to rounding. A first attempt that planned each transform from nothing measured + a key seeded twice twice and lost shared sub-plans (`rdw` 6.7 s cold on the Xeon Gold 6240 + against 1.4 s); a transform to measure now starts from the workspace's own measurements. The store holds about 20 kB a case at one width (80 kB for four cases on the EPYC) and grows with the shapes a user runs; nothing evicts a plan, and `--clear` empties it. Plans kept by the earlier opt-in file are not read. Measured threaded rows stay off by default: a @@ -2255,12 +2357,12 @@ Withdrawn (development-process record, not a design decision). - **Status:** accepted (maintainer), 2026-11-11. Supersedes ADR-054 and ADR-061; amends ADR-064 (single precision under `backend="auto"`); withdraws - [SEP 48](seps/archive/sep-0048-julia-backend.md). Those records, and the SEPs - implemented under them, stay as written. Amended by ADR-078: native runs the TDSE + [SEP 48](https://github.com/LupoLab/solprop/blob/main/docs/dev/seps/archive/sep-0048-julia-backend.md). The SEPs implemented under them stay + as written; the earlier records here say so. Amended by ADR-078: native runs the TDSE response too. - **Context:** single precision runs on `numpy_ref` alone since `mlx` was retired (SEP 47): no installed backend runs it quickly, and `backend="auto"` refuses it. - [SEP 36](seps/archive/sep-0036-native-reduced-precision.md) measured single and mixed + [SEP 36](https://github.com/LupoLab/solprop/blob/main/docs/dev/seps/archive/sep-0036-native-reduced-precision.md) measured single and mixed precision on the native engine and was withdrawn, because the gains on the target hardware do not repay a precision-templated engine. The tiers of ADR-061 rank two backends whose roles are fixed: Tier 2 has been empty since ADR-064 and Tier 3 since @@ -2298,7 +2400,7 @@ Withdrawn (development-process record, not a design decision). ## ADR-078 — The TDSE response runs on native through a host source; its provider in a worker - **Status:** accepted (maintainer), 2026-11-12, with - [SEP 49](seps/archive/sep-0049-tdse-on-native.md) (PR #771). Amends ADR-077's "every feature + [SEP 49](https://github.com/LupoLab/solprop/blob/main/docs/dev/seps/archive/sep-0049-tdse-on-native.md) (PR #771). Amends ADR-077's "every feature except the TDSE response, for now": native implements every feature. - **Context:** the TDSE response ran on `numpy_ref` alone, and native refused it by name. Its source is a complete atomic calculation at every radial node, from 93 s to over @@ -2351,13 +2453,13 @@ Withdrawn (development-process record, not a design decision). fastest recorded atomic call. Native runs without a host source are unchanged bit for bit. The hook's two rows are listed as `host_source` in the memory ledger. CI tests the hook and the worker with manufactured providers; compatibility with an installed - Pyroraptor is checked by hand ([SEP 49](seps/archive/sep-0049-tdse-on-native.md), section 7.4), + Pyroraptor is checked by hand ([SEP 49](https://github.com/LupoLab/solprop/blob/main/docs/dev/seps/archive/sep-0049-tdse-on-native.md), section 7.4), and the worker's handshake refuses a mismatched protocol or execution space. ## ADR-079 — One backend shape; no groups or unit axis; a native seam that only marshals - **Status:** accepted (maintainer), 2026-11-16, with - [SEP 52](seps/archive/sep-0052-backend-shape.md) (accepted 2026-11-15 in PR #850, + [SEP 52](https://github.com/LupoLab/solprop/blob/main/docs/dev/seps/archive/sep-0052-backend-shape.md) (accepted 2026-11-15 in PR #850, implemented in PRs #853, #854, #858 and #859). Amends ADR-003 (the state has no leading axis of one). - **Context:** after SEP 47 both backends kept one external contract, but behind it they @@ -2436,7 +2538,7 @@ Withdrawn (development-process record, not a design decision). ## ADR-081 — A coupling envelope may be evaluated for each field; the capillary one measures launched modal power - **Status:** accepted (maintainer), 2026-11-17, with PR #878. Applies - [SEP 31](seps/archive/sep-0031-simulation-coupling.md) section 4.3 (benchmark + [SEP 31](https://github.com/LupoLab/solprop/blob/main/docs/dev/seps/archive/sep-0031-simulation-coupling.md) section 4.3 (benchmark envelopes for an approximate coupling model's omitted physics) without changing its rule; replaces the capillary envelope recorded in SEP 31's phase 5 report (`capillary-he1m-scalar-vs-leaky-marcatili-2026-10`). diff --git a/docs/dev/dependencies.md b/docs/dev/dependencies.md index 70916a258..cd08814ab 100644 --- a/docs/dev/dependencies.md +++ b/docs/dev/dependencies.md @@ -18,23 +18,23 @@ need no exception for them. | package | purpose | notes | |---|---|---| -| solprop-native, at solprop's own version | the backend solprop runs on ([SEP 43](seps/archive/sep-0043-retire-numba-cpu.md)) | [below](#the-native-backend-package); no environment markers, so solprop's supported platforms are the ones it installs on | +| solprop-native, at solprop's own version | the backend solprop runs on ([SEP 43](https://github.com/LupoLab/solprop/blob/main/docs/dev/seps/archive/sep-0043-retire-numba-cpu.md)) | [below](#the-native-backend-package); no environment markers, so solprop's supported platforms are the ones it installs on | | numpy ≥ 2.5 | arrays | the array type at every layer; the APIs used are NumPy 2.0's (`concat`, `trapezoid`, `copy=`) and 2.3.2 is the first release with 3.14 wheels on all three platforms, but under 2.3 and 2.4 the free-space reference runs produce NaN and about 200 free-space and dispersive tests fail; the cause is not yet identified, so the floor stays at 2.5 until it is | | scipy ≥ 1.18 | `scipy.fft` (reference backend), `special`, `optimize`, `interpolate`, `integrate.quad_vec`, `signal`, `constants` | root finding, special functions, interpolation and adaptive quadrature throughout; the newest API used is `signal.ShortTimeFFT` (1.12), but optmat requires 1.18, the release its stored fits reproduce from | | matplotlib ≥ 3.10.7 | plotting | earlier 3.10 releases call pyparsing APIs that current pyparsing deprecates, which the test suite's warnings-as-errors refuses | | h5py ≥ 3.15 | HDF5 output | first release with 3.14 wheels on all three platforms | -| optmat[gas] ≥ 0.10.0 | built-in material models: gas dispersion, Kerr, equation of state and transport; solids; gas and silica Raman responses; gas ionisation rates ([SEP 3](seps/archive/sep-0003-optmat-materials.md)) | the same maintainers' curated-data package; never imported at `import solprop`, since its registries take about a second to import; 0.9 reads only the data a model needs and says which gases each rate model covers; 0.10 loads CoolProp without its superancillaries, so the first real-gas density takes 0.07 s rather than 0.46 s, and versions its equations of state (`EVALUATION_VERSION` 2) | +| optmat[gas] ≥ 0.10.0 | built-in material models: gas dispersion, Kerr, equation of state and transport; solids; gas and silica Raman responses; gas ionisation rates ([SEP 3](https://github.com/LupoLab/solprop/blob/main/docs/dev/seps/archive/sep-0003-optmat-materials.md)) | the same maintainers' curated-data package; never imported at `import solprop`, since its registries take about a second to import; 0.9 reads only the data a model needs and says which gases each rate model covers; 0.10 loads CoolProp without its superancillaries, so the first real-gas density takes 0.07 s rather than 0.46 s, and versions its equations of state (`EVALUATION_VERSION` 2) | | threadpoolctl ≥ 3.1 | inspect and control the backend-owned BLAS pool | pool provenance and limits are recorded per run | | jaxtyping ≥ 0.3.11 | array annotations, evaluated at import time in every module | pure Python; the checker (beartype) is dev-only; the floor dates from the removed `numba_cpu` backend, whose compiled kernels earlier releases' import hook wrapped; it has not been re-tested lower since | | tqdm ≥ 4.67 | the progress bar (`solprop.log.BarReporter`) | pure Python; imported when the first bar is drawn, never at `import solprop`; `ipywidgets` is optional for the notebook widget and is not a dependency | -| tomli-w ≥ 1.0 | writes recipes as TOML (`solprop.recipe`; [SEP 41](seps/archive/sep-0041-recipes-and-front-ends.md), Q6) | pure Python, MIT-licensed, no dependencies of its own; `tomllib` (standard library) reads them; it writes no comments, so an edited recipe loses its own; 1.0 already writes every form a recipe uses | +| tomli-w ≥ 1.0 | writes recipes as TOML (`solprop.recipe`; [SEP 41](https://github.com/LupoLab/solprop/blob/main/docs/dev/seps/archive/sep-0041-recipes-and-front-ends.md), Q6) | pure Python, MIT-licensed, no dependencies of its own; `tomllib` (standard library) reads them; it writes no comments, so an edited recipe loses its own; 1.0 already writes every form a recipe uses | ## Optional atomic-response engine Pyroraptor (`pyroraptor`) provides the helium atomic responses of the [TDSE response](../guide/media/tdse.md): the single-active-electron model of -[SEP 12](seps/archive/sep-0012-tdse-nonlinear-response.md) and the haCC models of -[SEP 20](seps/archive/sep-0020-hacc-helium-tdse.md). It is not yet publicly available, so +[SEP 12](https://github.com/LupoLab/solprop/blob/main/docs/dev/seps/archive/sep-0012-tdse-nonlinear-response.md) and the haCC models of +[SEP 20](https://github.com/LupoLab/solprop/blob/main/docs/dev/seps/archive/sep-0020-hacc-helium-tdse.md). It is not yet publicly available, so solprop declares no dependency or extra for it, and imports it only when a TDSE response is prepared; ordinary imports and non-TDSE runs never initialise its runtime. A missing provider, an unsupported interpreter (the provider supports Python 3.14 only) or a @@ -42,7 +42,7 @@ missing capability is refused with a `BackendError`. solprop pins no provider revision: until Pyroraptor has a release, it uses whatever provider is installed, by default the latest `main` -([SEP 49](seps/archive/sep-0049-tdse-on-native.md), ADR-078). The provider runs in a worker +([SEP 49](https://github.com/LupoLab/solprop/blob/main/docs/dev/seps/archive/sep-0049-tdse-on-native.md), ADR-078). The provider runs in a worker process, whose handshake refuses another protocol version; the revision, build and execution space it reports are recorded with every run, and a preset's source names that revision. A device build (CUDA or HIP) is selected explicitly through @@ -73,15 +73,15 @@ device libraries. Both distributions resolve in the root workspace's one `uv.loc solprop-native has no runtime dependency on solprop. **SLEEF 3.9.0** ([sleef.org](https://sleef.org), Boost Software License 1.0) is the -native CPU build's host vector maths on x86-64 (ADR-059): vector `exp`, `log` and +native CPU build's host vector maths on x86-64 and macOS arm64 (ADR-059, ADR-072): vector `exp`, `log` and `sincos`, its u10 functions (1.0 ulp over each function's domain), called over blocks by `native/include/solprop_native/runtime/vmath.hpp`. It is fetched at its release tag like Kokkos (`FETCHCONTENT_SOURCE_DIR_SLEEF` names a local copy for an offline build), built static as its own CMake project with only `libsleef` and the variants the layer calls (SSE2, AVX2, AVX-512F on request; AdvSIMD on aarch64), and compiled into the extension, whose wheel -carries its licence as `LICENSE-sleef.txt`. Arm builds (Apple silicon, Linux aarch64) -and GPU builds use the system libm and do not fetch it; `SOLPROP_NATIVE_VECTOR_MATH` -overrides the choice. Its floor is the pinned release: it is never resolved from a +carries its licence as `LICENSE-sleef.txt`. Linux aarch64 builds and GPU builds use the +system libm and do not fetch it (`native/cmake/VectorMath.cmake`); +`SOLPROP_NATIVE_VECTOR_MATH` overrides the choice. Its floor is the pinned release: it is never resolved from a package index. Evaluated against glibc's `libmvec` (2 ulp, and reachable from GCC only through fast-math or hand-written vector declarations) and Intel's MKL (faster on Intel only, by at most 1.5 times, and a large dependency); see ADR-059. @@ -132,7 +132,6 @@ Windows on Arm, where a sync would build LLVM from source. | package | for | status | |---|---|---| -| rocket-fft | transforms callable inside `@njit`, if a measured need for a compiled march emerges | not needed; the shared march is Python ([backends.md §3.5](backends.md)) | | mkl_fft | Intel FFT on Linux nodes | no evaluation planned | | jax | array-compiler backend | evaluated; not selected (ADR-002, [backends.md §5](backends.md)) | | sphinx-design, sphinx-copybutton | docs presentation | no evaluation planned | diff --git a/docs/dev/figures/backends.svg b/docs/dev/figures/backends.svg index 8ae89f3cf..1afbb7d77 100644 --- a/docs/dev/figures/backends.svg +++ b/docs/dev/figures/backends.svg @@ -1,6 +1,6 @@ + width="1200" height="702.0" viewBox="0 0 1200 702.0"> - + One seam, a session, and the backends behind them backends.md §1: the protocol is drawn at the level of operations on the propagated state, never at the array-namespace level. A backend is constructed from a validated PropagationProblem and host arrays and returns host arrays; its buffers, layout and plans are private. - + the seam · backends.protocol.Backend prepare -bind a problem and its run request; each start opens a session +bind a problem and its run request; each start opens a session edge_memory -what reading a grid's edge will hold, for an estimate +what reading a grid's edge will hold, for an estimate timing_probe -single trials from a start, committing nothing, for timing +single trials from a start, committing nothing, for timing metadata -what the execution was: pools, plans, digests, propagator mode +what the execution was: pools, plans, digests, propagator mode memory_ledger -every named buffer and its size -available_device_memory -free device bytes for scan admission; None on hosts -close -idempotent - - -backends.registry.select(name, problem, grid=, modes=, profiles=) - -HostSession (the reference's schedule) -the planes and the halts -advance · natural_stop · request_snapshot -the load and the cursor -_load · _restore_march -the history -record · _observe -the dense observation -_after_march · _here -the statistics channel -_account_step · _observation -the boundary monitor -_attach · absorb · _energies · _warning -the caps a march asks for -cap · collar_quiet -the march, driven -_propagate · stepped - -the stepper it drives -stepper.tableau -DOPRI5, Tsit5, the order-condition checks -stepper.controller -PIController: propose, accepts, rejection_factor, -equivalent_norm -stepper.schedule -landing, discover, calibrate, replay -the quadrature alarm -record · _propagate - - - -numpy_ref · the oracle -plain NumPy and scipy.fft -one named function per pass -the general representation, the z table included -propagator_mode auto → tabulate -NumpyWorkspace · engines · marches · dense output - - - -native · what auto selects -solprop-native distribution, native/ -C++20 Kokkos + persistent Kokkos-FFT plans -one native call per seven-stage trial -OpenMP on CPUs; CUDA and HIP on GPUs -NumpyWorkspace · engines · marches · dense output -Three things every backend owes beyond the methods: deterministic reductions, the device form of the stage, and the session's bookkeeping. The error norm is control flow, -so a sum whose association depends on the thread count forks the trajectory. +every named buffer and its size +close +idempotent + + +backends.registry.select(name, problem, grid=, modes=, profiles=) + +HostSession (the reference's schedule) +the planes and the halts +advance · natural_stop · request_snapshot +the load and the cursor +_load · _restore_march +the history +record · _observe +the dense observation +_after_march · _here +the statistics channel +_account_step · _observation +the boundary monitor +_attach · absorb · _energies · _warning +the caps a march asks for +cap · collar_quiet +the march, driven +_propagate · stepped + +the stepper it drives +stepper.tableau +DOPRI5, Tsit5, the order-condition checks +stepper.controller +PIController: propose, accepts, rejection_factor, +equivalent_norm +stepper.schedule +landing, discover, calibrate, replay +the quadrature alarm +record · _propagate + + + +numpy_ref · the oracle +plain NumPy and scipy.fft +one named function per pass +the general representation, the z table included +propagator_mode auto → tabulate +NumpyWorkspace · engines · marches · dense output + + + +native · what auto selects +solprop-native distribution, native/ +C++20 Kokkos + persistent Kokkos-FFT plans +one native call per seven-stage trial +OpenMP on CPUs; CUDA and HIP on GPUs +NumpyWorkspace · engines · marches · dense output +Three things every backend owes beyond the methods: deterministic reductions, the device form of the stage, and the session's bookkeeping. The error norm is control flow, +so a sum whose association depends on the thread count forks the trajectory. \ No newline at end of file diff --git a/docs/dev/figures/build.py b/docs/dev/figures/build.py index bb1807089..693477205 100644 --- a/docs/dev/figures/build.py +++ b/docs/dev/figures/build.py @@ -1272,7 +1272,6 @@ class Pass(NamedTuple): ("timing_probe", "single trials from a start, committing nothing, for timing"), ("metadata", "what the execution was: pools, plans, digests, propagator mode"), ("memory_ledger", "every named buffer and its size"), - ("available_device_memory", "free device bytes for scan admission; None on hosts"), ("close", "idempotent"), ) """The methods of `backends.protocol.Backend`: a run is its session's, on every diff --git a/docs/dev/gui/design.md b/docs/dev/gui/design.md index f5952f8b7..c1f59ea3d 100644 --- a/docs/dev/gui/design.md +++ b/docs/dev/gui/design.md @@ -1,7 +1,7 @@ # solprop GUI: design -Status: **the design of the front end being built**, in solprop's repository as the `gui/` -distribution `solprop-gui` (decision D2). First drafted on 2026-10-31 in a separate +Status: **the design of the front end**, in solprop's repository as the `gui/` +distribution `solprop-gui` (decision D2), published with solprop from 0.2.0. First drafted on 2026-10-31 in a separate repository, revised the same day after the design review of section 18 (response in section 19), and on 2026-11-01 after the solprop proposals it rests on were accepted. Moved here on 2026-11-02, when those proposals had been delivered; section 21 records where what @@ -11,9 +11,9 @@ preceded it; they are not kept in the repository. Planned work is in GitHub issu tracking issue for the front end and one issue per milestone of section 16. **Revised on 2026-11-05 to a workflow per problem class** (D14), and Qt reaffirmed after a fairer -comparison with the web (D1). Section 22 records why. Sections 5 to 11 now describe the front end -being built, not the stepper in draft PR #484, whose code remains the starting point for the -layers without Qt. Sections 18 to 21 are records, and their section numbers still resolve. +comparison with the web (D1). Section 22 records why. Sections 5 to 11 describe the front end, +which replaced the stepper of draft PR #484. Sections 18 to 21 are records, and their section +numbers still resolve. **Starting work on the GUI? Read section 0, then section 22, then section 21.** Much of this design depends on solprop's recipes and front-end hooks, and what solprop delivers takes precedence over @@ -174,7 +174,7 @@ general plotting package; replacing scripts for production campaigns. | D8 | The recipe lives in solprop (`solprop.recipe`, change S1): its format, builders, Python export and `solprop run`; the GUI adds only presentation. Q1 closed. | 2026-10-31 | | D9 | This design is a living page under `docs/dev/gui/`, not a SEP; the work is a tracking issue and one issue and branch per milestone of section 16. A change to solprop the GUI needs follows solprop's own rules (an issue, or a SEP for a major change) and is merged on its own. | 2026-11-02 | | D10 | Questions Q3–Q12 of section 14 are decided as recommended there. | 2026-11-02 | -| D11 | The quality bar is split by layer: `model`, `registry`, `service` and `help` meet solprop's standard in full, 100 % coverage included; `ui` and `views` are typed, documented and linted the same way and tested by `pytest-qt` smoke tests and offscreen screenshots, outside the coverage measure. | 2026-11-02 | +| D11 | The quality bar is split by layer: `model`, `registry`, `service` and `help` meet solprop's standard in full, 100 % coverage included; `ui` and `views` are typed, documented and linted the same way and tested by `pytest-qt` smoke tests and offscreen screenshots, outside the coverage measure. **Amended by D20:** the service is `solprop.service`, and the layers without Qt are `model`, `registry`, `classes` and `help` (`gui/tests/test_layers.py`). | 2026-11-02 | | D12 | The GUI is built out and tested locally, milestone on milestone, and iterated on by hand before any of it is merged: the milestone branches stack locally and are not pushed while that goes on, and the local gate (`poe check-gui`) stands in for CI. The solprop changes the GUI needs still go to main as their own pull requests. | 2026-11-02 | | D13 | The first hands-on review (2026-11-03) reshaped the front end. The start page is a gallery of the geometry classes, each a simple cross-section, grouped and titled; Cartesian and line free space, and rectangular and slab waveguides, are classes of their own, and planar guides are hidden for now. One set of plot options (spectral axis, typed limits, scale, a bandpass for the time domain) sits at the bottom left of Propagate and Results. Results show one run, with a 2 by 2 statistics grid of up to two quantities a panel and an interactive spectrogram (`processing.get_spectrogram`). Compression moves to a Post-process step after Results: a chain of solprop.optics elements, each fixed or searched by solprop's compressor of its kind, one at a time. **Replaced in part by D14:** the gallery, the shared plot options and the steps go; the spectrogram and the compressor chain stay, as pages. | 2026-11-03 | | D14 | A workflow per problem class replaces the stepper: Home, then Setup, Run and Analyse. A class is a definition held as data (6.1). The first are capillary, radial filament, solid-core fibre and antiresonant fibre; everything else is under Other geometry on the generic form. | 2026-11-04 | @@ -226,13 +226,13 @@ serves. pins, so it follows new defaults. The *resolved* recipe that solprop stores beside it in every results file freezes what rebuilds the run: what the user set, every solved pin, the noise seed, the data files and the defaults solprop can write back and still get the same - run. "Open setup from this run" shows the resolved values; adopting the current defaults or - re-solving the pins is a separate, explicit action ("Update to current solprop"), which lists - what would change. A frozen setup can still be refused at resume if the materials data or the + run. Opening a results file restores its setup from the resolved values. Adopting the + current defaults or re-solving the pins is to be a separate, explicit action that lists what + would change ("Update to current solprop"); it is not built yet. A frozen setup can still be refused at resume if the materials data or the physics differ; solprop names the fields that changed (ADR-066). - **Run.** One execution of a recipe revision: a results file (solprop HDF5) with both recipes embedded, a log, and two separate states. The *execution state* is the GUI's: - queued, starting, running, stopping, stopped, complete, failed, worker lost. The + queued, starting, running, stopping, stopped, complete, failed, lost. The *outcome* is solprop's `RunOutcome.status` (running, complete, budget exhausted, failed), which has no "stopped". Whether a run can be resumed is never assumed from either: it is asked of solprop (`resumability`, SEP 41 S17), which gives the mode @@ -241,13 +241,15 @@ serves. writer still alive), and whether the file can be rebuilt from itself. A changed grid, a wider time window included, is always a new run. - **Workspace.** A folder the user picks (default `~/solprop-runs`), holding one folder - per run: `-/` with `run.h5`, `recipe.toml`, `run.log` and a thumbnail, and - for a run with a record (13.4) `job.json`, its live rows and events, and its stop file. The - GUI keeps an index for fast browsing but the folder is the truth: copying a run folder + per run: `<date>-<title>/` with `run.h5`, `recipe.toml` and `run.log`, and the run's + record (13.4, `solprop.service.record`): `spec.json`, `job.json`, its events + (`events.bin`), its summary (`status.json`) and, when a stop is asked, its stop file. The + GUI keeps no index: the list of runs is read from the disk each time + (`solprop_gui.model.workspace`), and the folder is the truth, so copying a run folder elsewhere loses nothing. Each machine (13.4) has a workspace of its own. - **Project file.** Just a recipe saved by the user wherever they like ("Save setup - as…"). Opening a results file offers "Open setup from this run", which loads its - embedded recipe as a new, unsaved project. + as…"). Opening a results file loads its resolved recipe into the sheet, when the open + setup may be discarded. ## 5. The window and the route through it @@ -262,7 +264,7 @@ Home ─┬─ New simulation ──► Setup ──► Run ──► Analyse │ (a class) ◄── edit and rerun ──┘ ├─ Design a waveguide ──► "Simulate this" ──► Setup ├─ Open results ──► Analyse - └─ Scans (later, a mode of its own, started from a sheet) + └─ Scans (a mode of its own, started from a sheet) ``` ``` @@ -279,8 +281,8 @@ Capillary, helium Setup Run Analyse [▶ Run] ⋯ by itself, and editing a finished run's setup goes back to Setup without losing the results. - **One primary action.** The button at the top right is what comes next: Run, Stop or Rerun. Run, Stop and Resume appear nowhere else. -- **One overflow menu** (⋯) holds Save, Save as, Export recipe, Export Python and Open setup - from this run. The platform's menu bar repeats these, with the keyboard shortcuts. +- **One overflow menu** (⋯) holds Save, Save as, Show the recipe and Show as Python. The + platform's menu bar repeats the first two, with the keyboard shortcuts. - **No permanent console.** The log moves to the Run health page (11.3). A warning appears beside what it concerns and only when something is wrong. The recipe and its Python equivalent open in a drawer on request. @@ -299,7 +301,7 @@ Shown when nothing is open. It asks what you want to do: - **Design a waveguide** (7.4), for questions that need no pulse or run. - **Open results**: a file, or one of the recent runs listed here with its state. - **Open a setup**, and the recent setups. -- **Scans**, later (12.7). +- **Scans** are not here: a scan starts from a sheet (12.7). A class's examples (`Recipe.examples()`) are a short list on its sheet, not a dialog. @@ -311,8 +313,8 @@ projector (S5). - A sheet is one column of sections beside its plot. On a narrow window the plot moves below. - An analysis page shows one large view at a time, and the rail can shrink to icons. -- Fonts and plot line widths follow the system scale; a "Presentation" toggle enlarges - everything for S5. +- Fonts and plot line widths follow the system scale. A "Presentation" toggle to enlarge + everything for S5 is not built yet. ## 6. Setup: one sheet per problem class @@ -333,7 +335,10 @@ A class is a definition, held as data in the layer that imports no Qt (13.5): | Its starting point: a solprop example recipe | `rdw` | This replaces about 30 branches on the route in the views (22.1): a new class is a new -definition, and no view asks which class it is drawing. The first four classes: +definition, and no view asks which class it is drawing. The first four classes are below; +the catalog (`solprop_gui.classes.catalog.CLASSES`) now holds nine, adding Cartesian beams, +a Cartesian beam and a line beam (free space), and GNLSE, step-index and graded-index +fibres: | Class | solprop route | Notes | |---|---|---| @@ -653,8 +658,8 @@ doesn't fit is visible before the run. - **Modal routes**: today the keyword routes put the pulse in the lowest mode, or in the mode `channel=` names. The design has a launch table, per pulse (a pump and a seed may go into different modes): a share and a phase per mode, labelled as solprop labels the - modes (`HE1,1`, with the parity where both polarisations exist). It needs solprop - change S5; until then it shows "fundamental mode" and explains. On Marcatili-type bases + modes (`HE1,1`, with the parity where both polarisations exist): the recipe's `launch` + (solprop change S5). On Marcatili-type bases the shares are energy fractions. On a general modal basis the modes are not flux-orthogonal, so solprop normalises the total energy through the flux metric and the table labels the shares "coordinate shares, not an energy split". @@ -663,8 +668,9 @@ doesn't fit is visible before the run. - **Free space**: beam waist (1/e² intensity radius), super-Gaussian order, focus position as a distance before or after the waist (`propz`), polarisation (`jones`). A lens (focal length and beam on it) is an optional way to give the waist and focus (21.2). - Cartesian: displacement and tilt (today only through `coupling.Alignment`; S6 puts them - on the beam, with `Alignment`'s names; the tilt is a pure angle at every frequency). + Cartesian: displacement and tilt, on the beam with `Alignment`'s names + (`SpatialPulse.displacement` and `tilt`, solprop change S6; the tilt is a pure angle at + every frequency). Planar: `waist_x`, `offset_x`. A preview shows the beam cross-section on the transverse grid (`Recipe.preview_input`, S18). @@ -732,21 +738,24 @@ Capillary, helium Setup Run Analyse [■ Stop] ⋯ - **On completion** the strip goes, the rail appears and you are in Analyse. - **On failure** an advice card states the fix and keeps the planes reached, which stay open for analysis. -- **Stop** sends a stop request on the worker's control pipe; the worker sets solprop's - stop flag (S17), which takes effect within one step or trial on every platform (on Windows - a signal would terminate the worker outright). The run writes its state and `run` returns - normally. The execution state is *stopping* until the worker reports, then *stopped*, and - Resume follows `resumability`. If the worker hasn't stopped after a grace period the - GUI offers to kill it; afterwards it asks `resumability` before calling the file - resumable, since a killed run may have no restart state. -- **Detach** (with the service, 13.3) lets the run continue after the window closes; reopening - the run re-attaches. +- **Stop** writes the run's stop file in its folder (`solprop.service.record.request_stop`), + which the run looks for every 0.25 s (`STOP_PERIOD`) and which sets solprop's stop flag + (S17); the flag takes effect within one step or trial on every platform. The run writes its + state and `run` returns normally. The execution state is *stopping* until the record says + otherwise, then *stopped*, and Resume follows `resumability`. A run that does not stop can + be ended (the helper's `cancel`, `SIGTERM` or `scancel`, or with `force` `SIGKILL`); the GUI + then asks `resumability` before calling the file resumable, since a killed run may have no + restart state. +- **Every run outlives its window** (D21): reopening the window follows a run still going. + Closing a window over a run asks Keep, Stop or Kill, and a run tied to its window (the Run + menu's "Tie runs to this window") stops itself, resumably, when the window's process + goes. ### 10.3 Several runs The usual work is one run at a time, so the window shows one. Home lists the workspace's runs with -their state, and opening one shows it. Starting a second while one runs is allowed, with a warning -before oversubscribing the machine's thread budget. Campaigns are scans (12.7). +their state, and opening one shows it. Starting a second while one runs is allowed; a warning +before it oversubscribes the machine's thread budget is not built yet. Campaigns are scans (12.7). ## 11. Analyse @@ -980,25 +989,26 @@ shows unsaved changes; autosave keeps a recovery copy. Window layout, last works units and recent files persist with `QSettings`. The first look is light (D18); a dark theme can follow the system later. -### 12.7 Scans (designed now, built later) - -Scans are a mode of their own (D16), started from a sheet, not a section of the Run stage. - -- **Setup**: any numeric field, nested ones included (a second pulse's energy, a - profile knot), gets a "scan" toggle in its context menu that turns it into a list or - range (linear, log, explicit) over its parameter path. Pins re-solve at every point. The scan's setup shows - the variables, the grid shape and the total cost, the retention choice (`fields`: - none, chosen planes, all) and reductions (energy in a band, spectrum in a band, peak - power, …, from `processing.scans`). -- **Run**: `Recipe.scan()` gives the `Scan`, a picklable builder (passing each point's seed) - and the keywords for `run_scan(..., executor=Local() | Pool(workers))`, the retention choice - among them. Live progress - needs solprop change S4 (today the scan reports finished points only). -- **Results**: a scan browser shows any reduction as a map over two scan variables (or - lines over one), with the others as sliders; clicking a point opens that point's run - in Analyse (when its fields were retained). -- **Data model**: a scan is a recipe plus a `[scan]` table of variables, so the recipe - format must allow it from format 1. +### 12.7 Scans + +Scans are a stage of their own (D16), started from a sheet, not a section of the Run stage +(`ui/scan_stage.py`, `ui/scan_editor.py`). + +- **Setup**: a numeric field's context menu offers "Scan this…", which adds its parameter + path, nested ones included (`pulses[0].energy`), to the recipe's `[scan]` table. The Scan + stage edits that table: each variable a list of values or a range + (`{start, stop, num, spacing}`) in the keyword's unit, and a `name` that names the scan's + files and seeds its points. Pins are solved again at every point. Beyond its statistics a + scan can record the energy and peak power within a band, each point's spectrum and each + point's pulse. +- **Run**: the run helper runs `Recipe.scan()` through `run_scan(..., executor=Pool())` + into the scan's folder (`solprop.service.run`); a run from the sheet leaves the table + out and runs the setup once. The stage shows a bar for each variable and one for the + whole scan, advanced as points finish. +- **Results**: one recorded quantity at a time, over the first variable with a line for + each value of the second, or, for a recorded spectrum or pulse, as a map over the first + variable; failed points are marked, and a point's context menu opens it as a setup. +- **Data model**: a scan is a recipe plus a `[scan]` table of variables (recipe format 1). ### 12.8 View specifications @@ -1034,12 +1044,14 @@ filtering, and the reduction used for display. waits for the commit to finish), and the run then writes its state. The handlers are installed only in a main thread, and on Windows `os.kill` with SIGINT terminates the process outright. So the run needs its own process, and the GUI stops it through - solprop's portable stop flag (S17) set from the worker's control thread. + solprop's portable stop flag (S17), which the run's own thread sets when the run's stop + file appears (`solprop.service.record.watch_stop`). - Results files have no SWMR: a writer holds a lock sidecar, and another process can't - safely read a file being written. Live data must therefore be **streamed** from the + safely read a file being written. Live data must therefore be **reduced** in the process that runs the simulation, through solprop's plane observer (S3), which gives - read-only, lazy access to each committed plane. An observer that raises is detached - by solprop and the run continues, but the worker still catches its own pipe errors. + read-only, lazy access to each committed plane, and written to the run's record + (`events.bin`), which the window follows (13.4, D21). An observer that raises is detached + by solprop and the run continues. - Resume needs a `Simulation` rebuilt in Python with the file's configuration hash (ADR-066): solprop rebuilds it from the resolved recipe in the file (S2), so the GUI needs no state of its own to resume. `resumability(file, gate=True)` shows what differs before one is tried. @@ -1098,7 +1110,6 @@ Messages (sketch): | `validate(recipe)` | errors and warnings with parameter paths | | `summarise(recipe)` | a sheet's numbers, on a route with no lighter call | | `explore(geometry, medium, quantities, axis, sweep)` | arrays | -| `solve_pin(recipe, pin)` | every root and the chosen value, or the attainable range (`Recipe.pin_roots`) | | `preview_input(recipe)` | pulse and beam arrays on the grid | | `estimate(recipe)` | sizes, memory, rough time | | `start_run(recipe, folder)` | `started`, `progress`, `plane`, `stats`, `warning` (the boundary lamp's among them), `log`, then `finished` / `stopped` / `failed` (with traceback) | @@ -1212,8 +1223,8 @@ a list of runs, a resume setting the record aside) goes by that summary, so it f complete and let go (Windows refuses to rename a file another process holds open). The terminal event can be read from `events.bin` a moment before the summary says it, so a reader acting on the run's end waits for the summary. Re-attaching reads the rows and events from the start and then follows them, -which works for a scan as well as a run. On this computer the run also keeps its pipe to the -window, so the live view does not wait on a file. +which works for a scan as well as a run. On this computer too the window follows the record, +through this computer's helper (D21); no run keeps a pipe to the window. **Starting a run.** Directly, as a detached process that outlives the SSH session, with the thread count of the Runs on line; or through Slurm, as a job from the machine's template, @@ -1289,8 +1300,8 @@ for every change to `gui/` or to solprop itself. First `pip install "solprop[gui]"` (or `pip install solprop-gui`, or `uv tool install solprop-gui`), giving a `solprop-gui` command; it pulls PySide6 (its Essentials distribution) and pyqtgraph, and solprop at the same version; add `native` for the native -backend. It is released with solprop from the same tag; its publication to PyPI waits for -a first usable milestone. +backend. It is released with solprop from the same tag, and is published to PyPI with +solprop from 0.2.0. The PySide6 wheels carry Qt itself, so Windows and macOS should need nothing more (Windows is untried by hand). Linux needs a few system libraries the wheels leave out. A desktop @@ -1387,9 +1398,9 @@ table, scan editor, compressor chain) and the pyqtgraph views. | W1 Frame (built locally) | The `classes` layer. The controller moved out of `MainWindow`. Home, the three stages, the sheet frame, the rail and the z scrubber. Built as: `classes/` holds the four classes as data, a test holding every row to its class's example; `ui/document.py` (`SetupDocument`) owns the recipe, undo, checks and files for both windows; `solprop-gui --workflow` opens the new window beside the step window, which Other geometry still opens. Setup edits and checks a real recipe with solprop's numbers; Run and Analyse host the existing views under the new frame, with their sliders replaced by the scrubber. Left to W2: the live sheet (preview plot, typed targets, fast numbers), plain-language rows, and the pages not built, which say so on the rail. | | W2 Capillary (built locally) | End to end: the live sheet with typed targets, the Run stage and every page of 11.3. Checked by walking S1 and S4 by hand. Built as: `service/sheet.py` gives the numbers (about 120 ms, `tools.capillary_params` on the resolved recipe), the curve and dispersive wave (about 170 ms) and the output's size; a number with a target is a button that writes `[pins]`, and the row it moves shows what it solved. Run and Analyse are one widget (`ui/analyse.py`), the Overview under a progress strip or beside the rail, and the pages are `ui/analysis_pages.py` over a shared `ui/analysis.py`, drawing only while on screen. Not built: a rough time on the Ready line, the step-size sparkline on the strip, and a choice among several roots of a target. A ZDW target takes about 290 ms to solve, over the sheet's 150 ms (P8). | | W3 Radial filament (built locally) | Its sheet and pages, with the spatial readers and beam numbers of 21.2. Checked by walking S6. Built as: rows that move several paths, because the object routes write a gas or wavelength several times (`Field.also`); a saved-planes row of two forms, a count (`n_save`) or explicit positions (`save_planes`), one replacing the other in one edit (`Field.positions`, SEP 51); switches for Kerr and plasma, whose entries come back from the class's example; a lens as an option on the beam. The live numbers come from `tools.beam_params`. The Overview grows from each plane's fluence and the beam's spectrum, and reads the on-axis spectrum from the file when the run ends. Not built: a far field or spectrogram while a run goes. | -| W4 Fibres (built locally) | Solid-core and antiresonant, as classes. Checked by running both through every page. Built as: the solid-core sheet reads its mode and `tools`, with no targets, since pins cover the capillary only; the antiresonant sheet uses `tools.soliton_params` on its own mode, and only the soliton order is a target, because a fibre has many zeros and resonances. Its zero is read from the curve inside the run's window, where the tool's nearest in frequency can lie far beyond it. Its loss curve and cross-section sit below the dispersion curve. A sheet edit costs about 280 ms on the antiresonant route against the 150 ms of the capillary. Not built: Noise and coherence, which stays disabled as no run is a seeded ensemble until scans exist. | +| W4 Fibres (built locally) | Solid-core and antiresonant, as classes. Checked by running both through every page. Built as: the solid-core sheet reads its mode and `tools`, with no targets, since pins cover the capillary only; the antiresonant sheet uses `tools.soliton_params` on its own mode, and only the soliton order is a target, because a fibre has many zeros and resonances. Its zero is read from the curve inside the run's window, where the tool's nearest in frequency can lie far beyond it. Its loss curve and cross-section sit below the dispersion curve. A sheet edit costs about 280 ms on the antiresonant route against the 150 ms of the capillary. Not built: Noise and coherence, which is not offered until a run can be a seeded ensemble. | | W5 Design a waveguide (built locally) | The workflow of 7.4, reusing the explorer's quantities and sweeps. Checked by walking S2 by script. Built as: a stage of the workflow window, opened from Home, that never touches the open setup. A design is always a class's example with the design's values set, so what it shows is what that recipe builds, and *Simulate this* opens it as a new sheet. It covers capillary and antiresonant fibre, with pages Curves (β₂, D, β₃, n_eff − 1, group index), ZDW map (pressure against radius per zero, capillary only), Phase matching and Loss. It has a sweep of pressure, radius or gas, where a click takes a curve's value or a map point's radius and pressure. It solves the pressure for a ZDW, and the energy too for an order. A curve costs about 90 ms, a sweep of four about 250 ms, and a map about 2 s. Not built: a sweep of the mode order, the solid-core fibre, a figure export (CSV only), and Copy as Python. | -| W6 Other geometry (built locally) | Every other route on the generic form. The step window is deleted. Checked by running each example of those routes (hollow rectangular, graded-index, Cartesian and line beams, both planar) from Home through every page. Built as: Home's Other geometry tile lists those examples. A recipe on a route with no class gets a class made from solprop's metadata: its sections are the metadata groups, holding the keywords the recipe sets, with the rest under Advanced. Its numbers are the summary's energy and peak power, and its rail is Overview, At this plane, Along z and Run health. A planar run has no Overview, since its planes are slab amplitudes no map reads yet. A beam's plane is summed across the beam. A general modal guide's energy is its physical energy. `solprop-gui` opens the workflow window, and `--workflow` is accepted and ignored. A service run re-attaches in the new window. Removed with the step window: `ui/main_window`, `ui/start`, `ui/design_tool`, `ui/scan_editor`, `views/explorer`, `views/zdw_chart` and their tests. Not built: scans, which wait for their own mode (12.7); a cross-section on the generic form; per-width labels (J/m) for line and planar beams; a fluence map page for Cartesian and line beams (#455 gives the reader). | +| W6 Other geometry (built locally) | Every other route on the generic form. The step window is deleted. Checked by running each example of those routes (hollow rectangular, graded-index, Cartesian and line beams, both planar) from Home through every page. Built as: Home's Other geometry tile lists those examples. A recipe on a route with no class gets a class made from solprop's metadata: its sections are the metadata groups, holding the keywords the recipe sets, with the rest under Advanced. Its numbers are the summary's energy and peak power, and its rail is Overview, At this plane, Along z and Run health. A planar run has no Overview, since its planes are slab amplitudes no map reads yet. A beam's plane is summed across the beam. A general modal guide's energy is its physical energy. `solprop-gui` opens the workflow window, its only window. A service run re-attaches in the new window. Removed with the step window: `ui/main_window`, `ui/start`, `ui/design_tool`, `views/explorer`, `views/zdw_chart`, the Results step (`ui/results`, `ui/plot_options`, `views/plane`, `views/statistics`, `views/compare`, `views/scan_browser`), the step pages (`ParameterPage`, the step registry) and the start page's gallery pictures, with their tests. Not built: scans, which wait for their own mode (12.7); a cross-section on the generic form; per-width labels (J/m) for line and planar beams; a fluence map page for Cartesian and line beams (#455 gives the reader). | | After W6 (built) | From the first hand review. Opening a class's sheet takes 0.06 to 0.18 s and is ready in 0.3 to 0.5 s, down from 0.7 to 1.9 s and 2 s. The cost was the window's widgets, so an object field now makes a type's form when it is picked, and Advanced rows are made when the section is opened, searched or holds an error. The kernel describes the classes' routes and makes a first check of the slow ones as the window opens. Opening another setup, example or file while a run is going asks first, and a run stopped that way no longer takes the stage when it ends. A "Runs on" line under the Ready line chooses the backend (the recipe's keyword, where the route has one; MLX writes single precision and is shown disabled with the reason where it cannot run) and the thread count (the window's, kept between sessions; the default is solprop's `thread_budget`, which `solprop.backends` exports for this, #540). Home's tiles carry a drawing of each geometry. There are two classes more: a Cartesian beam (`space.type=FreeGrid`), with the beam numbers and a page of the fluence across x and y, and a line beam (`space.type=LineGrid`), with values per metre of y and a map of the fluence across x along z. Not built: a rectangular guide class, a plasma switch on the Cartesian sheet (its example has none to copy), and P/P_cr for a line beam, which has no collapse of its own. | | Fibres (built) | From the hand review. The solid-core class is the GNLSE fibre, given by its γ and Taylor coefficients alone; its Raman row says silica, the GNLSE's default. A step-index fibre (`fibre.type=StepIndexMode`, from `step_index_fibre`) has its mode solved: its γ from the mode and n₂, its dispersion curve and its cross-section, and rows that say an empty core is fused silica and an empty cladding air. A graded-index fibre (`provider.provider.type=GradedIndexProvider`, from `graded_index_fibre`) is read from its recipe's profile without solving it, for its numerical aperture, V number and the modes a power-law core holds (about V² p / (2 (p + 2))), and draws its index across the core; its Modes page says why it has no energy per mode (its modes are not orthogonal). Not built: per-material Raman models, which belong in solprop. | | Plots (built) | From the hand review. A Home button starts the stage bar. Every plot zooms with the wheel, on the plot or on one axis, and pans by dragging (on a map with a z line a drag moves the plane, so an axis drag pans it); a double-click, or Reset the zoom, goes back, and a zoomed plot keeps its view while the scrubber or a live run redraws it. The readout on a line plot follows the nearest curve. A right-click opens a plot's own menu: Save this plot (PNG, or SVG drawn through Qt, since pyqtgraph's exporter fails on a legend), Copy this plot as an image, and, on a line plot, Width at half maximum here (−3 dB on a dB axis), which draws the width on the curve with its value, Copy the data as CSV and Clear the widths; on a map with a z line, Go to the peak. The export menu adds This page as an image, and offers the publication figure only where `solprop.plotting` draws one (not on spatial runs); a figure that fails says why. Every map reads out its position and value under the pointer, unless its page says more (the on-axis spectrogram, the beam's maps and the fluence maps had none). Pulses are drawn four times finer than the run's grid (`oversampling=4`, as solprop's plots and Luna do): on the modal routes through `get_power` (the plane, the Overview, the live rows, Compress and the scans' pulse and peak power), and on a beam through `spatial_power`, `spatial_intensity` and `on_axis_power`, whose `oversampling` came with #535, on `processing.time_axis`. The publication figure's maps are rasterized in solprop (#546). The run strip has the step-size sparkline W2 left out: the accepted step against z on a log scale, from the run's progress reports, with the latest and the range in its tooltip. | diff --git a/docs/dev/index.md b/docs/dev/index.md index 90f5c7dcd..7122bfcbe 100644 --- a/docs/dev/index.md +++ b/docs/dev/index.md @@ -54,10 +54,8 @@ gui/design ```{toctree} :maxdepth: 1 -:caption: Decisions, proposals, and ongoing work +:caption: Decisions and proposals decisions seps/index -roadmap -open-questions ``` diff --git a/docs/dev/kernel-contract.md b/docs/dev/kernel-contract.md index ea27a62cb..d472b40a0 100644 --- a/docs/dev/kernel-contract.md +++ b/docs/dev/kernel-contract.md @@ -33,7 +33,7 @@ polarisation component. **Agreement is a rounding bound.** The contract fixes quantities, not operation order. A backend reproduces the reference's results within a rounding bound fixed from its operation and reduction counts, never bit for bit -([SEP 25](seps/archive/sep-0025-rounding-level-reproducibility.md)). That includes the plasma +([SEP 25](https://github.com/LupoLab/solprop/blob/main/docs/dev/seps/archive/sep-0025-rounding-level-reproducibility.md)). That includes the plasma column's running sums against `plasma_scan` and `plasma_current`, under either running-integral rule (§5); the Raman pass against `RamanResponse.evaluate` and `raman_spectrum` against `RamanKernels.spectrum`; and the statistics evaluated on one @@ -46,7 +46,7 @@ hard-mask zeros, and explicitly exact zeros and no-ops. |---|---|---| | `grid_kind` | `"field" \| "envelope"` | selects r2c/c2r vs c2c transforms and the response formulas | | `shape` | `(n_modes, n_pol, n_omega)` | canonical state shape of the one trajectory the problem describes | -| `flags` | frozen dataclass of static flags and counts | `single_mode`, `scalar_pol`, `has_plasma`, `has_raman`, `has_noise`, `has_temporal_absorber`, `constant_linop`, `mode_averaged`, `n_channels`, `n_raman` — kernels specialise on these at compile time. Derived from the content, never passed in | +| `flags` | frozen dataclass of static flags and counts | `single_mode`, `scalar_pol`, `has_plasma`, `has_raman`, `has_noise`, `has_temporal_absorber`, `constant_linop`, `mode_averaged`, `n_channels`, `n_raman` — kernels specialise on these at compile time. Derived from the content by `Flags.from_content` (`kernel-problem.md`) | | `grids` | frozen dataclass | section 2 (`translate.masks.Grids`) | | `linear` | frozen dataclass | section 3 (`translate.linop.LinearOperator`) | | `responses` | frozen dataclass | section 5 (`translate.responses.CompiledResponses`) | @@ -58,7 +58,7 @@ above: `transform`, the route's transform, and `device_ready`, true when Φ (§3 of a fixed set of arrays, and false when either took the z table. The problem is the run's numerical meaning and nothing of how it is run -([SEP 47](seps/archive/sep-0047-run-ownership.md) §5.2). The stepper settings of §7 and the +([SEP 47](https://github.com/LupoLab/solprop/blob/main/docs/dev/seps/archive/sep-0047-run-ownership.md) §5.2). The stepper settings of §7 and the statistics request of §8 are run policy: they travel in the immutable `translate.run_request.RunRequest` that `translate.assembly.assemble` returns beside the problem (`Translation(problem, request)`), and a backend receives both where it is built @@ -73,7 +73,7 @@ route, the statistics the route admits and dense observation's admission (§7's ### The route union `route` is one of three frozen variants from `translate.routes`, a closed union -([SEP 47](seps/archive/sep-0047-run-ownership.md) §6.2). The grid, operator, response and source +([SEP 47](https://github.com/LupoLab/solprop/blob/main/docs/dev/seps/archive/sep-0047-run-ownership.md) §6.2). The grid, operator, response and source groups above are shared by every route; a variant carries exactly the fields its executor needs, and checks them on construction. `validate()` visits the variant with a `match` statement for what spans groups, and every backend admits a problem the same @@ -112,8 +112,8 @@ resource, the atomic binding, is the driver's and crosses explicitly (§6). |---|---|---| | `kind` | `"radial" \| "cartesian" \| "planar" \| "line"` | the transverse grid: Hankel, two-dimensional Cartesian, the hybrid planar slab transform, or a Cartesian grid one sample wide in y (`grid.LineGrid`); equal to `translate.routes.spatial_kind` of the geometry | | `transform` | frozen dataclass | §4, with a spatial `geometry` (`"radial"`, `"free"` or `"slab"`) | -| `flux` | `FluxPlan` | the plane measure ([SEP 34](seps/archive/sep-0034-medium-flux.md), `translate.spatial.FluxPlan`): `base`, the separable coefficients with the entrance material square, whose principal root gives the dimensionless axial admittance `c k_z/omega` of every column and bin (zero on nonpropagating, inactive and nonpositive-frequency bins); `material`, the z table of the complex material square `(omega n/c)²` for a varying radial medium, `None` for a uniform one; and `admission`, the varying path's adiabatic certificate. `at(z)` gives a plane's coefficients. Every spatial statistic weights its columns by the real admittance at its plane (energy, spectra, absorbed powers) or synthesises the closure `G` with the complex one (fluence, intensities, on-axis spectrum). Its active mask equals `grids.active_mask` | -| `transverse` | `SpatialAbsorberDesign` or `None` | the resolved transverse boundary ([SEP 40](seps/archive/sep-0040-transverse-absorbing-boundaries.md), `spatial_absorber.SpatialAbsorberDesign`), host-side: the safety ramp's rate per column, which the separable operator carries as `kperp_rate` (the dense operator radially), and a requested collar's rate on the nodes, which the geometry carries as `absorber_rate`, with its band, strength, crossing step and design check. A backend meets it only through those fields and the stepper's `dz_max`, held to the collar's crossing limit and to the ramp's exponent budget. `None` for no transverse boundary | +| `flux` | `FluxPlan` | the plane measure ([SEP 34](https://github.com/LupoLab/solprop/blob/main/docs/dev/seps/archive/sep-0034-medium-flux.md), `translate.spatial.FluxPlan`): `base`, the separable coefficients with the entrance material square, whose principal root gives the dimensionless axial admittance `c k_z/omega` of every column and bin (zero on nonpropagating, inactive and nonpositive-frequency bins); `material`, the z table of the complex material square `(omega n/c)²` for a varying radial medium, `None` for a uniform one; and `admission`, the varying path's adiabatic certificate. `at(z)` gives a plane's coefficients. Every spatial statistic weights its columns by the real admittance at its plane (energy, spectra, absorbed powers) or synthesises the closure `G` with the complex one (fluence, intensities, on-axis spectrum). Its active mask equals `grids.active_mask` | +| `transverse` | `SpatialAbsorberDesign` or `None` | the resolved transverse boundary ([SEP 40](https://github.com/LupoLab/solprop/blob/main/docs/dev/seps/archive/sep-0040-transverse-absorbing-boundaries.md), `spatial_absorber.SpatialAbsorberDesign`), host-side: the safety ramp's rate per column, which the separable operator carries as `kperp_rate` (the dense operator radially), and a requested collar's rate on the nodes, which the geometry carries as `absorber_rate`, with its band, strength, crossing step and design check. A backend meets it only through those fields and the stepper's `dz_max`, held to the collar's crossing limit and to the ramp's exponent budget. `None` for no transverse boundary | **How a stage is evaluated, and why `device_ready` exists.** Three of the quantities a stage needs are *arrays* that depend on z — the propagator's exponent ΔΦ, the response @@ -153,15 +153,14 @@ took, as history. The tables of this document describe the contract as it stands change to it, to the descriptors or to the stage bundles of `translate/stage.py` rewrites the frozen tables in `tests/backends/test_driver.py` in the same commit and adds a release-note fragment. solprop and solprop-native are released -together and pinned to one version; `check_build` looks up every member the native adapter -relies on by name, and in an editable checkout compares the extension with its `native/` -sources by digest (`BuildInfo.source_digest`). An added optional field leaves every problem +together and pinned to one version (solprop requires solprop-native at exactly its own); +`check_build` compares, in an editable checkout only, the extension with its `native/` +sources by digest (`BuildInfo.source_digest`), and nothing about the solprop beside it. An added optional field leaves every problem that does not use it unchanged. -**Device memory.** `Backend.available_device_memory()` returns current free device bytes, -excluding live allocations and allocator reserves, or `None` for host execution; -a host backend returns `None` and a device backend answers for itself. A scan's memory -admission reads it with the backend's complete memory ledger. +**Device memory.** The protocol carries no device-memory query: a native device build reads +its free device bytes itself when it plans its node chunk +(`solprop_native.available_device_memory()`). **The general-modal leaves.** `linear.coupled_flow` and `linear.modal_metric` (§3), `transform.modal_tables` (§4) and `responses.regional_responses` (§5) are optional. Each @@ -229,9 +228,12 @@ maps of one coefficient — reports `None`. Moving maps are admitted only beside `"frozen_residual"` flow that carries their connection. **The frozen literals.** `tests/backends/test_driver.py` freezes -`LINEAR_OPERATOR_FIELDS` (`dataclasses.fields(LinearOperator)`), the descriptor's and the -request's fields, `STAGE_TERMS_FIELDS`, `STAGE_SCALARS_FIELDS`, -`SEPARABLE_OPERATOR_FIELDS` and `MARCH_POLICY_FIELDS`; a change to the seam rewrites the +`PROPAGATION_PROBLEM_FIELDS`, `RUN_REQUEST_FIELDS`, `ROUTE_VARIANT_FIELDS`, +`TDSE_SOURCE_FIELDS` and `SPATIAL_KINDS` (the descriptor, the request and the route union), +the `LinearOperator` fields (inline in +`test_linear_operator_fields_are_frozen_with_the_driver_seam`), `STAGE_TERMS_FIELDS`, +`STAGE_SCALARS_FIELDS`, `SEPARABLE_OPERATOR_FIELDS`, `MARCH_POLICY_FIELDS` and +`BACKEND_MEMBERS` (the reference's backend surface); a change to the seam rewrites the literal it changes, and `native` and solprop are changed together in the same commit. The dataclass tree is exactly `PropagationProblem` and the five array groups `grids`, @@ -246,7 +248,7 @@ in both directions; a second test checks the flags and counts named in the `flag against the fields of `Flags`. **The transverse edge.** `NumpyWorkspace.edge_reading(edge, *, faces, current, full)` -(native's `GeneralResident::edge_reading` in C++, `native/src/march/engines.cpp`) returns an `_EdgeReading` ([SEP 44](seps/archive/sep-0044-native-edge-read.md)): region sums, each column's unweighted energy, each +(native's `GeneralResident::edge_reading` in C++, `native/src/march/engines.cpp`) returns an `_EdgeReading` ([SEP 44](https://github.com/LupoLab/solprop/blob/main/docs/dev/seps/archive/sep-0044-native-edge-read.md)): region sums, each column's unweighted energy, each line's `(inward, windowed)` strip and the summed rectified current, never the field. The reference forms them with the edge's host reduction (`_HostEdgeReduction`) on its host state. Native's takes the edge's `_EdgeTables` and `_EdgeLine`s, whose weights, strides, windows and onsets say all there is to know about the geometry, so a backend holds no face, mask or judgement of its own. It @@ -274,7 +276,7 @@ either backend. at a lab-frame field and position -- the `modified` noise draw advanced to that position's absolute phase, the in-stage absorbers and the TDSE adapter with its labels -- returned in the lab frame, with no propagator applied. The exponential Adams formulation -([SEP 16](seps/archive/sep-0016-unified-multistep.md)) stores these untransported +([SEP 16](https://github.com/LupoLab/solprop/blob/main/docs/dev/seps/archive/sep-0016-unified-multistep.md)) stores these untransported samples and integrates their polynomial against the linear flow, and the low-storage step's passes evaluate it too. `Multistep.formulation` is `"interaction"` or `"exponential"`. @@ -309,12 +311,14 @@ meets the fit's rounding. `validate()` checks: all arrays finite, read-only, C-contiguous (but `initial.field0`, which may be a broadcast view: section 6), and of the stated dtype -(float64, complex128, bool and intp everywhere, and `int32` at exactly three declared +(float64, complex128, bool and intp everywhere, `int32` at exactly four declared index leaves — `transform.modal_tables.region_index`, -`responses.regional_responses.response_region` and -`responses.regional_responses.kernel_valid_samples`, named in -`translate.problem._INT32_LEAVES`; the dtype rule applies to every leaf the tree walk -reaches, so `int32` is admitted by name and not globally) +`responses.regional_responses.response_region`, +`responses.regional_responses.kernel_valid_samples` and +`responses.dispersive_kerr.regions`, named in `translate.problem._INT32_LEAVES` — and +`uint8` at `split_crossing.buckets` alone (`_UINT8_LEAVES`); the dtype rule applies to +every leaf the tree walk reaches, so `int32` and `uint8` are admitted by name and not +globally) and shape; masks Boolean; breakpoints strictly increasing and covering `[0, z_max]`; hard kinks are breakpoints; every `ZProfile` table covers the same z range as `Phi`; every general-modal leaf tabulated along z covers `[0, z_max]` and carries `grids.omega` @@ -417,7 +421,7 @@ imaginary part. Compiled backends evaluate these formulas per element. `PropagationProblem.validate` holds a step the run cannot shrink -- a replayed schedule's longest step, or the floor `dz_min` -- to the propagator's exponent budget -([SEP 22](seps/archive/sep-0022-memory-lean-spatial-execution.md) §4.5): with `λ₋` and `λ₊` bounds on `max(-Re D)` and `max(Re D)` from +([SEP 22](https://github.com/LupoLab/solprop/blob/main/docs/dev/seps/archive/sep-0022-memory-lean-spatial-execution.md) §4.5): with `λ₋` and `λ₊` bounds on `max(-Re D)` and `max(Re D)` from `translate.spatial.rate_bounds` (a sorted search over the columns, `O(n_omega log n_modes)`), a step `h` with `h max(λ₋, σλ₊) > ln(DBL_MAX)` is refused naming the binding term and the admissible step and rate, and one past nine tenths of it warns @@ -440,7 +444,7 @@ for a constant fill and for the GNLSE unit-index override. Statistics evaluate weights only through `translate.linop.power_weight_at(problem, z)`. Radial Φ in a varying gas carries the spatial counterpart, `-1/2 ln[Y_z(ω,k_r,z)/Y_z(ω,k_r,0)]` with `Y_z ∝ Re k_z/ω`, evaluated from endpoint admittances in both the table and the -parameter-expansion representations ([SEP 34](seps/archive/sep-0034-medium-flux.md) §4.4); it +parameter-expansion representations ([SEP 34](https://github.com/LupoLab/solprop/blob/main/docs/dev/seps/archive/sep-0034-medium-flux.md) §4.4); it is exactly zero in a uniform medium, and a radial statistic reads the admittance at its plane through `flux.at(z)`. @@ -502,7 +506,7 @@ the **measured** round-off floor of `D`: the frame subtracts `β₀ + β₁(ω that reaches 8·10⁷ m⁻¹ at the top of a wide field grid's active band, so `D` is only known to about 1e-11 relative and no interpolant can resolve it below its own noise. The floor is a property of one evaluation of `D` and serves both representations. See -[`docs/guide/numerics/linear-operator.md`](../guide/numerics/linear-operator.md), "The table". +[`docs/guide/numerics/linear-tables.md`](../guide/numerics/linear-tables.md#the-table), "The table". ### The coupled-flow leaf @@ -616,7 +620,7 @@ execute every admitted combination. The transform carries **no node chunk**. How many nodes a response pass holds at once is an execution choice, not part of the scientific problem -([SEP 47](seps/archive/sep-0047-run-ownership.md) sections 4.3 and 6.5): each backend plans it when +([SEP 47](https://github.com/LupoLab/solprop/blob/main/docs/dev/seps/archive/sep-0047-run-ownership.md) sections 4.3 and 6.5): each backend plans it when it is prepared, from the problem and its `ExecutionOptions` -- an explicit `node_budget`, which is authoritative, or the automatic choice (`solprop.backends.node_chunk.plan_node_chunk`) -- records it in its execution metadata, @@ -784,7 +788,7 @@ integrand $\tilde y_n = c_0 y_n + \sum_{k=1}^K c_k (y_{n-k} + y_{n+k})$. The ref sums it centre first, then each pair added before it is weighted; a backend may sum the stencil and the running integrals in any order, held to the stencil's $\gamma_{2K+2} A_n$ bound and the absolute prefix bounds of the scans' signed increments -([SEP 25](seps/archive/sep-0025-rounding-level-reproducibility.md) §4.6). The $K$ samples past +([SEP 25](https://github.com/LupoLab/solprop/blob/main/docs/dev/seps/archive/sep-0025-rounding-level-reproducibility.md) §4.6). The $K$ samples past each end are $y_{-m} = 2y_0 - y_m$ and $y_{N-1+m} = 2y_{N-1} - y_{N-1-m}$. The exposure is floored at zero pointwise, $X_n = \max(S_n, 0)$, before the fraction is formed; the loss current keeps the raw rate. So `plasma_scan` finalises the fraction at sample $n$ @@ -793,7 +797,7 @@ the production column stops at the total current. The physical oracle `PlasmaResponse.evaluate` also integrates that current to polarisation, from samples up to $n+3K$. The `"trapezoid"` rule has no filter, no boundary and no floor. -**The held field-plasma source** ([SEP 27](seps/archive/sep-0027-held-plasma-current.md)). +**The held field-plasma source** ([SEP 27](https://github.com/LupoLab/solprop/blob/main/docs/dev/seps/archive/sep-0027-held-plasma-current.md)). The field-plasma column writes three complete streams: the collared non-plasma polarisation `P`, the collared current `X = gJ` and its collar-derivative companion `Z = g'J`, with `g'` the analytic `grids.t_window_fine_derivative` (§2). On active bins @@ -889,7 +893,7 @@ pass. **`dispersive_kerr` is a leaf** (`translate.responses.DispersiveKerrTerms`), so its fields are not rows of this document. It is the frequency-dependent electronic -response of [SEP 6](seps/archive/sep-0006-dispersive-nonlinearity.md) reduced to arrays, sampled by the translation layer on the problem's own fine +response of [SEP 6](https://github.com/LupoLab/solprop/blob/main/docs/dev/seps/archive/sep-0006-dispersive-nonlinearity.md) reduced to arrays, sampled by the translation layer on the problem's own fine spectral layout at **absolute** angular frequency: the one-sided `(n_to // 2 + 1,)` layout on a field grid, the full FFT-order `(n_to,)` layout on an envelope grid. Its fields are `evaluator` (`"symmetric"` or `"polynomial"`), `sector` (`"full"`, every @@ -961,11 +965,12 @@ those exist to recover from the eight digits the co-moving frame cancels out of the tolerance it is asked for. Why the prefactor follows z, and what carrying it costs, is in [the kernel problem](kernel-problem.md#where-the-normalisations-live). -A backend evaluates the prefactor only through `translate.responses.prefactor_at`, as it -evaluates the linear flow only through `translate.linop.delta_phi` and `unitary_phase`, -never by reading the coefficient arrays. That is what lets the representation change — -a z table, an expansion in the scalar parameters, a constant — without a backend -noticing. +The NumPy reference evaluates the prefactor through `translate.responses.prefactor_at`, +as it evaluates the linear flow through `translate.linop.delta_phi` and `unitary_phase`; +a compiled backend combines the same coefficient arrays through the stage bundle +(`stage.terms` and `stage.scalars`, §1), which is the same arithmetic rearranged. That is +what lets the representation change — a z table, an expansion in the scalar parameters, a +constant — without a backend's stage code changing. Each plasma channel also carries `label`, `density` and `electrons_per_event=1.0`. Dissociation and multiple electrons per event are unsupported. Channel labels select species metadata by name, and rates are identity-checked per channel. @@ -1019,7 +1024,7 @@ it changes no step, charge or reservation. None of this is part of the descripto or the kernel problem, which compiled backends see, so it is outside the kernel schema. -**The native host source hook** ([SEP 49](seps/archive/sep-0049-tdse-on-native.md), +**The native host source hook** ([SEP 49](https://github.com/LupoLab/solprop/blob/main/docs/dev/seps/archive/sep-0049-tdse-on-native.md), ADR-078). On the native CPU build the binding reaches the resident Adams march as a host source: a session binding outside the kernel problem, whose three entry points the march calls from the thread that called `advance`, outside every parallel region, holding the @@ -1130,7 +1135,7 @@ already holds, or one the translation built for it, is taken without a second co These settings, and the statistics request of §8, are run policy rather than the problem's numerical meaning, so they are not fields of `PropagationProblem`: they live in the immutable `translate.run_request.RunRequest` -([SEP 47](seps/archive/sep-0047-run-ownership.md) §§5.2, 6.3), resolved by translation — +([SEP 47](https://github.com/LupoLab/solprop/blob/main/docs/dev/seps/archive/sep-0047-run-ownership.md) §§5.2, 6.3), resolved by translation — `assemble` fills the route's defaults and holds `dz_max` and `dz_init` to the collars' limits — and handed to a backend where it is built. The request structures them as its integration, error-control, replay and observation specifications; `RunRequest.stepper` @@ -1150,9 +1155,9 @@ launch's remaining planes). | `schedule` | `(n_steps,) float64` or `None` | fixed schedule to replay; its edges must contain every save plane and hard kink, which `FixedSchedule.uniform` guarantees for a plain fixed-step run | | `save_planes` | `(n_z,) float64` | z positions the driver will ask for; steps land on them unless `interpolate_planes` is set | | `propagator_mode` | `"auto" \| "tabulate" \| "recompute"` | ADR-004 and [backends.md §3.6](backends.md). `"auto"` is the default and is the backend's own choice, resolved at construction and written into the run's `backend` metadata group: `tabulate` for `numpy_ref` and `recompute` for `native` on a modal problem; `recompute` on every backend for a separable free-space operator, whose increment `D (z₂ − z₁)` is exact. Under the low-storage march `tabulate` is one volume of `exp(h D / 2)` reused while the step holds (a varying operator's `P` and `Q` for the step), admitted on the free and planar kinds too, and `"auto"` resolves to `tabulate` for a constant operator and `recompute` for a varying one (SEP 24 §4.3), and to `recompute` on a native device build, where an extra field read costs more than the exponential | -| `integrator` | `Multistep \| LowStorageRungeKutta \| None` | The method stepping the problem instead of the tableau, or `None` for the Runge-Kutta march. `Multistep` ([SEP 13](seps/archive/sep-0013-expensive-response-steppers.md), [SEP 16](seps/archive/sep-0016-unified-multistep.md)) is the Adams march in its exponential or interaction formulation, with an optional carrier frame (`carrier_frame`, [SEP 35](seps/archive/sep-0035-carrier-frame-exponential-adams.md), added in version 37: `"off"` or `"scalar"`, the latter on `numpy_ref` and native CPU builds and refused by name elsewhere); it runs on `numpy_ref` and Kokkos on every diagonal-flow route, and beside the constant-Schur and frozen-residual coupled flows in the exponential formulation; with a `schedule` it replays the schedule's steps (`HostAdamsMarch._replay_to`); the TDSE response runs adaptive, on `numpy_ref` and the native CPU build (SEP 49). `LowStorageRungeKutta` ([SEP 24](seps/archive/sep-0024-low-storage-interaction-picture-runge-kutta.md)) is RK4 in the midpoint interaction picture in three registers: it replays a `schedule` and nothing else, records the norm 0.0 ("not estimated"), refuses a coupled flow, the TDSE response, interpolated planes and a step past RK4's negative-real interval 2.785, and runs on `numpy_ref` and solprop-native (a resident engine whose step is one native call) | -| `interval_cap` | bool | whether a step is capped at the width of the operator-table interval it starts in. `assemble` turns it off on the diagonal-flow routes and on for a coupled flow or a reject-free controller, unless set ([SEP 14](seps/archive/sep-0014-stepper-efficiency.md) §4.1) | -| `auto_init` | bool | whether the start-up rule takes the step after the first from the first step's own scaled norm (`PIController.start_factor`, at most 100 times `dz_init`). Set by the convenience interfaces when no `dz_init` is given; off for a coupled flow or a reject-free controller ([SEP 14](seps/archive/sep-0014-stepper-efficiency.md) §4.2) | +| `integrator` | `Multistep \| LowStorageRungeKutta \| None` | The method stepping the problem instead of the tableau, or `None` for the Runge-Kutta march. `Multistep` ([SEP 13](https://github.com/LupoLab/solprop/blob/main/docs/dev/seps/archive/sep-0013-expensive-response-steppers.md), [SEP 16](https://github.com/LupoLab/solprop/blob/main/docs/dev/seps/archive/sep-0016-unified-multistep.md)) is the Adams march in its exponential or interaction formulation, with an optional carrier frame (`carrier_frame`, [SEP 35](https://github.com/LupoLab/solprop/blob/main/docs/dev/seps/archive/sep-0035-carrier-frame-exponential-adams.md), added in version 37: `"off"` or `"scalar"`, the latter on `numpy_ref` and native CPU builds and refused by name elsewhere); it runs on `numpy_ref` and Kokkos on every diagonal-flow route, and beside the constant-Schur and frozen-residual coupled flows in the exponential formulation; with a `schedule` it replays the schedule's steps (`HostAdamsMarch._replay_to`); the TDSE response runs adaptive, on `numpy_ref` and the native CPU build (SEP 49). `LowStorageRungeKutta` ([SEP 24](https://github.com/LupoLab/solprop/blob/main/docs/dev/seps/archive/sep-0024-low-storage-interaction-picture-runge-kutta.md)) is RK4 in the midpoint interaction picture in three registers: it replays a `schedule` and nothing else, records the norm 0.0 ("not estimated"), refuses a coupled flow, the TDSE response, interpolated planes and a step past RK4's negative-real interval 2.785, and runs on `numpy_ref` and solprop-native (a resident engine whose step is one native call) | +| `interval_cap` | bool | whether a step is capped at the width of the operator-table interval it starts in. `assemble` turns it off on the diagonal-flow routes and on for a coupled flow or a reject-free controller, unless set ([SEP 14](https://github.com/LupoLab/solprop/blob/main/docs/dev/seps/archive/sep-0014-stepper-efficiency.md) §4.1) | +| `auto_init` | bool | whether the start-up rule takes the step after the first from the first step's own scaled norm (`PIController.start_factor`, at most 100 times `dz_init`). Set by the convenience interfaces when no `dz_init` is given; off for a coupled flow or a reject-free controller ([SEP 14](https://github.com/LupoLab/solprop/blob/main/docs/dev/seps/archive/sep-0014-stepper-efficiency.md) §4.2) | | `interpolate_planes` | bool | steps across the save planes and observes each inside its accepted step, through DOPRI5's continuous extension or, with an `integrator`, the Adams march's own polynomial (ADR-039); the end of the run and the hard kinks are still landed on. Refused with a schedule, a Runge-Kutta tableau without an extension, the per-step collar, a coupled flow and the `modified` noise | | `step_planes` | int | a positive `k` also saves the end of every `k`-th accepted step since the load: the march returns to its session there, short of its target, and the session observes the plane and marches on to the target (ADR-039). `0` never stops short | @@ -1169,7 +1174,7 @@ the problem. | field | type | meaning | |---|---|---| -| `stats` | frozen dataclass | `solprop.stats.StatsSpec`: which statistics, energy windows (`(n_windows, 2)` in ω), periodic subset and period, validated against the catalogue at construction; and the far-field tables of [SEP 23](seps/archive/sep-0023-far-field-aperture-spectra.md), `apertures` (an `ApertureSet`: centres, diameters, distances, edges, profile, weighting, labels, and from schema 45 the optional shapes, profiles and extents, which a record leaves out while they are unset) and `spectral_regions` (`(n_regions, 4)` boxes of physical transverse wavevector in rad/m, the one leaf whose entries may be infinite), read only when a name that uses them is requested, so a backend that does not know a name refuses it rather than misreading a table. Fields of the leaf, not rows of the contract | +| `stats` | frozen dataclass | `solprop.stats.StatsSpec`: which statistics, energy windows (`(n_windows, 2)` in ω), periodic subset and period, validated against the catalogue at construction; and the far-field tables of [SEP 23](https://github.com/LupoLab/solprop/blob/main/docs/dev/seps/archive/sep-0023-far-field-aperture-spectra.md), `apertures` (an `ApertureSet`: centres, diameters, distances, edges, profile, weighting, labels, and from schema 45 the optional shapes, profiles and extents, which a record leaves out while they are unset) and `spectral_regions` (`(n_regions, 4)` boxes of physical transverse wavevector in rad/m, the one leaf whose entries may be infinite), read only when a name that uses them is requested, so a backend that does not know a name refuses it rather than misreading a table. Fields of the leaf, not rows of the contract | The `periodic` subset and its `period` are read **when the backend is built**, not when a run is started: the session arms the between-planes channel from the statistics @@ -1218,11 +1223,11 @@ the step history and over the same interval, and a row may not index past it. The descriptor is a typed contract, extended by changing its types and their tests in both distributions, never through an untyped optional field -([SEP 47](seps/archive/sep-0047-run-ownership.md) §6.2): +([SEP 47](https://github.com/LupoLab/solprop/blob/main/docs/dev/seps/archive/sep-0047-run-ownership.md) §6.2): | Addition | Contract, admission and qualification | |---|---| -| Route | Add a variant to the union in `translate.routes`, with its scientific validation in its own `__post_init__` and in `PropagationProblem.validate`'s visit of the route (and in `validate_run`'s, for a check that reads the run's policy). Each backend visits it (`numpy_ref`'s `refuse_route`, `native`'s `_refuse_native_route`) and either prepares it or refuses it by name before workspace allocation. Qualify the route's transforms, flow, source and export against independent references. | +| Route | Add a variant to the union in `translate.routes`, with its scientific validation in its own `__post_init__` and in `PropagationProblem.validate`'s visit of the route (and in `validate_run`'s, for a check that reads the run's policy). Each backend visits it (each backend's `_refuse_unsupported`) and either prepares it or refuses it by name before workspace allocation. Qualify the route's transforms, flow, source and export against independent references. | | Response/operator | Add a typed component within the finite representation vocabulary (§3, §5), its units, shape, validity and error contract, and its validation. Extend reference evaluation, native lowering and the capability tests; never pass it through an untyped optional field. | | Statistic | Add its typed specification, dependencies, units and sampling rules to the statistics request (§8); qualify periodic and plane equivalence and reference and native reductions, including field-free execution. | | Auxiliary evolving state | Add a typed physical-state component, separate from method history. Its own physics SEP specifies initialisation, evolution and stage coupling, rejection rollback, error control, observations, checkpoint and reset, and group ownership before admission. The present set is empty. | @@ -1230,7 +1235,7 @@ both distributions, never through an untyped optional field Every addition updates the rows of this document (which `tests/translate/test_problem.py` checks against the dataclasses in both directions), the frozen descriptor tables in `tests/backends/test_driver.py`, the capability and refusal -tests, the memory ledger ([architecture.md §8](architecture.md)), the manual and the +tests, the memory ledger ([backends.md §8](backends.md)), the manual and the source and error-budget evidence, and adds a release-note fragment. It lands on `numpy_ref` and native CPU, in either order (ADR-068), unless its accepted SEP records an exception. There is no version counter to bump (ADR-068). @@ -1244,16 +1249,16 @@ reference. ## 11. The Adams march -*Normative since kernel schema 39 ([SEP 39](seps/archive/sep-0039-native-adams-march.md), -ADR-060). The native backend executes it on its CPU build for `Multistep()` in either -formulation, adaptive or replayed; every other configuration and backend runs the -reference.* +*Normative since kernel schema 39 ([SEP 39](https://github.com/LupoLab/solprop/blob/main/docs/dev/seps/archive/sep-0039-native-adams-march.md), +ADR-060). The native backend executes it for `Multistep()` in either formulation, +adaptive or replayed, and has no Python march (its Runge–Kutta and low-storage marches are +native too, §12); `numpy_ref` runs the reference.* The step loop of `Multistep()` is one algorithm with one reference implementation, solprop's `HostAdamsMarch` and the controller core it calls (`solprop.backends.adams_core`). A backend may execute the same algorithm natively. It then receives every number the algorithm reads in one record, and holds no default and no constant of its own -(`native/AGENTS.md`). [SEP 39](seps/archive/sep-0039-native-adams-march.md) §4 is the algorithm +(`native/AGENTS.md`). [SEP 39](https://github.com/LupoLab/solprop/blob/main/docs/dev/seps/archive/sep-0039-native-adams-march.md) §4 is the algorithm in full; this section is its interface. **The policy record** (`solprop.stepper.multistep.MarchPolicy`, formed once per run by @@ -1328,7 +1333,7 @@ one attempt, of seven and of none to one set of bits. (convergence, value, backend) and message; - the state above, every step before the event committed. -**The boundary checks inside the march** ([SEP 45](seps/archive/sep-0045-native-rk-march.md) +**The boundary checks inside the march** ([SEP 45](https://github.com/LupoLab/solprop/blob/main/docs/dev/seps/archive/sep-0045-native-rk-march.md) §4.8, normative since its phase 1). Unless the run's monitor reads a transverse edge, a call also takes the monitor's checks: the bounds carry the monitor's watch policy (`BoundaryMonitor.watch_policy`: the scaled floor @@ -1370,7 +1375,7 @@ stripped extension labels only exported functions). The boundary checks above an ## 12. The Runge–Kutta march -*Normative from [SEP 45](seps/archive/sep-0045-native-rk-march.md) phase 3. `native` executes it +*Normative from [SEP 45](https://github.com/LupoLab/solprop/blob/main/docs/dev/seps/archive/sep-0045-native-rk-march.md) phase 3. `native` executes it (`native/src/march/rk_march.cpp`), adaptive or replayed, with `PIController`'s norm, weighted or not, on CPU and device builds. `PIController` is final (ADR-077), so its decisions are the only ones either backend takes.* @@ -1380,7 +1385,7 @@ reference implementation, solprop's `RungeKuttaMarch.march_to` and the controlle calls (`solprop.backends.rk_core`). A backend may execute the same algorithm natively, as §11's Adams march is executed. It then receives every number the algorithm reads in one record and holds no default and no constant of its own (`native/AGENTS.md`). -[SEP 45](seps/archive/sep-0045-native-rk-march.md) §4 is the algorithm in full; this section is +[SEP 45](https://github.com/LupoLab/solprop/blob/main/docs/dev/seps/archive/sep-0045-native-rk-march.md) §4 is the algorithm in full; this section is its interface. **The policy record** (`solprop.backends.records.RungeKuttaPolicy`, formed once per run @@ -1390,18 +1395,20 @@ backends read): | field | meaning | |---|---| | the controller's `safety`, `beta1`, `beta2`, `min_factor`, `max_factor`, `lag`, `reject_free`, `estimator_order` | `PIController`'s gains, factors and acceptance rule (§7) | -| `START_GROWTH` | the start-up rule's cap on the second proposal (100) | +| `RungeKuttaPolicy.start_growth` | the start-up rule's cap on the second proposal (`START_GROWTH`, 100) | | `RungeKuttaPolicy.auto_init` | whether the first accepted step takes the start-up rule | | `RungeKuttaPolicy.dz_min`, `RungeKuttaPolicy.dz_max` | the floor and the cap on a proposal, m | +| `RungeKuttaPolicy.interpolate` | whether the planes are interpolated rather than landed on (`save_planes` is then empty) | | the landings: `stretch`, `z_end`, `save_planes`, `hard_kinks`, `breakpoints`, `landing_ulps` | as §11's, shared with the Adams march | | the tableau's nodes | the stage positions $z + c_i\,\Delta z$, with the whole step at $z + \Delta z$ | -| the norm's scale | `rtol`, `atol` and the region of §7, applied by the engine's scorer; a weighted norm keeps the reference march | +| the norm's scale | `rtol`, `atol` and the region of §7, applied by the engine's scorer, weighted or not | | the quiet collar's interval | the monitor's, or none | **The state**: the position; the controller's proposal; the accepted-norm history, at most `lag + 2` values, oldest first; the accepted count; the replay cursor. It is a continuation between the calls of one march only. A load resets it (the native -backend's `_load`), on a fresh launch and on a resume alike, and `march_snapshot()` is `None` for this march. +backend's `_load`), on a fresh launch and on a resume alike, and +`RunSession.march_snapshot(ticket)` is `None` for this march. **One attempt**, in order (SEP 45 §4.3): diff --git a/docs/dev/kernel-problem.md b/docs/dev/kernel-problem.md index 9b6cdafbd..18eb72371 100644 --- a/docs/dev/kernel-problem.md +++ b/docs/dev/kernel-problem.md @@ -49,9 +49,8 @@ away beforehand. ## What crosses {class}`solprop.translate.problem.PropagationProblem` is built by -{func}`solprop.translate.assembly.assemble`. It describes one trajectory: a group of them, -as a batched scan runs, is a sequence of problems. It carries the groups every route -shares, one per section of the contract, and a `route`: +{func}`solprop.translate.assembly.assemble`. It describes one trajectory. It carries the +groups every route shares, one per section of the contract, and a `route`: | group | holds | |---|---| @@ -60,14 +59,14 @@ shares, one per section of the contract, and a `route`: | `linear` | the cumulative operator $\Phi(\omega, z)$ as a Chebyshev expansion in the mode set's scalar paths, or as a table along z where that is not available, plus its hard kinks and the frame quantities | | `responses` | the compiled nonlinear term: the Kerr coefficients, the ionisation table, the plasma and Raman leaves, the density path, the prefactor, the temporal absorber | | `initial` | the initial state and the noise realisation of the one trajectory the problem describes | -| `route` | what differs between routes, as exactly one variant of a closed union ({mod}`solprop.translate.routes`): a {class}`~solprop.translate.routes.ModalRoute` (mode-averaged or resolved modes, with the TDSE response as its reference-only extension), a {class}`~solprop.translate.routes.GeneralRoute` (a general modal guide) or a {class}`~solprop.translate.routes.SpatialRoute` (radial, Cartesian, planar or line free space, with its plane measure and transverse boundary). Each carries the transform — synthesis and projection between modal amplitudes and the field at quadrature nodes, and their rescaling along z — which `problem.transform` reads | +| `route` | what differs between routes, as exactly one variant of a closed union ({mod}`solprop.translate.routes`): a {class}`~solprop.translate.routes.ModalRoute` (mode-averaged or resolved modes, with the TDSE response as its extension, which the native CPU build and the reference execute and native device builds refuse), a {class}`~solprop.translate.routes.GeneralRoute` (a general modal guide) or a {class}`~solprop.translate.routes.SpatialRoute` (radial, Cartesian, planar or line free space, with its plane measure and transverse boundary). Each carries the transform — synthesis and projection between modal amplitudes and the field at quadrature nodes, and their rescaling along z — which `problem.transform` reads | How the problem is *run* is not part of it. The tableau, the controller, the step caps, the save planes, any fixed schedule and the statistics to collect are the run's policy, held by an immutable {class}`~solprop.translate.run_request.RunRequest` that {func}`~solprop.translate.assembly.assemble` returns beside the problem ({class}`~solprop.translate.problem.Translation`); a backend is built from the two -together ([SEP 47](seps/archive/sep-0047-run-ownership.md) §5.2; the +together ([SEP 47](https://github.com/LupoLab/solprop/blob/main/docs/dev/seps/archive/sep-0047-run-ownership.md) §5.2; the [kernel contract](kernel-contract.md), §§7 and 8). So the same problem can be run with another request -- an interior launch's remaining planes, another start or retention -- without being translated again, and a run's configuration record reads its stepper @@ -77,10 +76,11 @@ Each variant has exactly the fields its executor needs and checks them when it i A backend visits the variant explicitly and refuses one it does not execute by name, before it allocates anything: extending a route changes this typed contract and its tests, never a bag of optional fields -([SEP 47](seps/archive/sep-0047-run-ownership.md) §6.2; the contract's extension procedure, +([SEP 47](https://github.com/LupoLab/solprop/blob/main/docs/dev/seps/archive/sep-0047-run-ownership.md) §6.2; the contract's extension procedure, [kernel contract](kernel-contract.md) §10). -Every array is `float64`, `complex128`, `bool` or `intp` (and `int32` at three named index -leaves of the general modal route); C-contiguous; read-only; and in +Every array is `float64`, `complex128`, `bool` or `intp` (and `int32` at four named index +leaves, three of the general modal route and the dispersive Kerr regions, and `uint8` at the +split collar's buckets); C-contiguous; read-only; and in the **FFT convention** with the phase origin at the first time sample ([the conventions](conventions.md), §2). The user's optics-convention inputs were converted by the pulse builders and the observations are converted back by the output @@ -116,7 +116,10 @@ agree where they coincide, is folded into `transform.synthesis` — not into a r coefficient. A coefficient can absorb a field scale only when the response is homogeneous in the field. The Kerr term is; an ionisation rate, which is a table looked up at the physical field amplitude in volts per metre, emphatically is not. Folding the pad into the synthesis -means every response sees the physical field, whatever its degree. +means every response sees the physical field, whatever its degree. Two transforms carry no +synthesis to fold it into: on the Cartesian and line grids the backends multiply by +`grids.pad_scale` after their inverse transverse DFT, and the general modal route's source +takes it as a factor of its own (`backends/numpy_ref/source.py`, `general_modal.py`). The **crop scale** on the way back has no such condition, so it is folded into `responses.prefactor`, which is applied in the same pass as the crop. The prefactor is the @@ -158,11 +161,15 @@ the operator. ## The flags are derived, never declared -The nine booleans of section 1 — `single_mode`, `has_raman`, `constant_linop` and the rest — -are computed by {meth}`solprop.translate.problem.Flags.from_content` from the arrays that -were actually built. A caller cannot set them, so a flag cannot disagree with what it -describes, which is the failure mode a kernel specialising on them would find hardest to -debug. +The eight booleans and two counts of section 1 — `single_mode`, `has_raman`, +`constant_linop` and the rest — are computed by +{meth}`solprop.translate.problem.Flags.from_content` from the arrays that were actually +built: by `assemble`, and again wherever solprop changes a problem's content (the +driver's noise redraw), so a flag does not disagree with what it describes, which is the +failure mode a kernel specialising on them would find hardest to debug. The problem's +constructor and `validate` do not re-derive them, so a problem built by hand keeps them +consistent itself; the backend tests use that to declare content no compiler builds yet, +which a backend must refuse. ## Validation is the backend's defence @@ -279,10 +286,10 @@ kernel has to do: the operator does not propagate what is not there, and the pre not create it. Between the two, the assembled problem reports ``` -shape (1, 1, 4096) +shape (1, 1, 3072) grid_kind 'envelope' flags single_mode, scalar_pol, constant_linop, mode_averaged -Phi table 1 interval of degree 1, 128 kB +Phi table 1 interval of degree 1, 96 kB save planes [0.5, 1.0] ``` diff --git a/docs/dev/open-questions.md b/docs/dev/open-questions.md deleted file mode 100644 index 8bd65b7fc..000000000 --- a/docs/dev/open-questions.md +++ /dev/null @@ -1,138 +0,0 @@ -# Open questions - -These are open, unscheduled questions about solprop as it is, not planned work: a check -not yet made, a choice deferred, or a known limitation accepted for now. Each entry stands -alone: what the question is, where it lives in the code or the documentation, what is -known, and why it is open. - -This page is not a list of planned work. Missing functionality and known defects that are -to be fixed are in the [issues](https://github.com/LupoLab/solprop/issues); a major change starts as an -[enhancement proposal](seps/index.md). An entry here moves to an issue if it becomes work -to do, and is removed when it is settled. - -Contributions are welcome: an independent check of any entry below — a derivation, a -comparison with a reference, a measurement — settles it. - -<!-- Entries are grouped by area; each is a short paragraph with its file or page. --> - -## Spatial propagation - -**The on-axis spectrum's end bins on the native backend.** The `on_axis_spectrum` -statistic is computed natively on the native backend -(`GeneralWorkspace::spatial_statistics` in `native/src/general/statistics.cpp`) and in -Python on the others (`solprop/backends/spatial.py`, through -{func}`~solprop.fourier.spectral_density`). On a field grid the two agree at every -interior bin and differ at the zero-frequency and Nyquist bins: the native kernel does -not double those two in the analytic signal, so that $\delta\omega\sum_k S_k$ is the -axial fluence exactly, while `spectral_density` applies the interior factor at every -bin and, as its docstring states, overcounts those two by a factor of four. Every grid -that `solprop.grid` builds apodises both bins to zero, so no run built through the -public interfaces sees the difference. Open: which definition the statistic should have, -so that the backends also agree on a hand-built grid. - -**Transverse components resolved at the entrance only.** With a transverse quadrature and -`components=None`, {func}`~solprop.translate.assembly.assemble` decides which Cartesian -field components (x, y or both) the transform carries from each mode's -`principal_component(0.0)`, and refuses an explicitly requested component that is zero -for every mode by the same z = 0 reading (`_components` and `_transform` in -`solprop/translate/assembly.py`). The mode protocol's `principal_component(z)` takes a -position, so a mode whose polarisation changed along the guide would gain a component the -transform does not carry. Every mode class today ignores `z`, so no run is affected. Open: -whether the resolution should take the union over the run's length, or the protocol -should declare the component independent of z. - -**Thread-count invariance of the transverse FFT plans.** On the native backend the -Cartesian transverse FFTs are planned at their own width, sized by the FFT size rule or -`SOLPROP_NATIVE_FFT_THREADS`; the backend metadata records it. An FFTW -plan, and so its rounding, can depend on the thread count, as the temporal pool's does. -The tests pin this width to one thread or check only that the setting is recorded; none -compares a Cartesian run at two transverse thread counts. Open: the rounding bound that -holds between two sizes of this pool, and a test of it (bitwise independence is not -required, [SEP 25](seps/archive/sep-0025-rounding-level-reproducibility.md)). - -**GPU capacity at the largest Cartesian grids.** A Cartesian run's memory is set by its -$n_x n_y$ columns per time sample ([free space](../guide/free-space/model.md), *Memory*). The -backend ledger counts the retained arrays exactly, and `native` also records the device's -free-memory decrease while its FFT plans are built, but cuFFT and rocFFT plan workspace is -opaque and these measurements are not upper bounds. The largest Cartesian grid recorded -on a data-centre GPU is 768 × 768 × 600, with statistics-only planes -([SEP 24](seps/archive/sep-0024-low-storage-interaction-picture-runge-kutta.md#closing-report--the-native-guards-the-follow-ups-and-phase-4-not-started), -2026-10-19): the low-storage march took 610 ms a step on an AMD MI325X and 674 ms on an -NVIDIA H200, at a device high-water of 46 and 34 GB with the transform workspace, and the -IP-DOPRI5 replay 1077 and 1092 ms. A grid of 512 × 512 transverse samples on 2000 to 4000 -time samples is 1.5 to 3 times as many points and has not run, no record gives the Adams -march at such a size, and the largest grid a given device holds is not known. Open: a -measurement of plan usage and peak device memory at the largest intended grid on each -qualified device. - -## Translation and materials - -**`with_mixture` and the operator's representation.** -{meth}`Simulation.with_mixture <solprop.driver.simulation.Simulation.with_mixture>` -reuses the existing pressure expansion when the new densities fall within its parameter -ranges. Updated to a constant fill inside those ranges, the run keeps the -`"expansion"` representation of the linear operator, where a fresh build of the same -mixture gives `"constant"`; the two agree to the expansion's tolerance, not bitwise. -Open: whether an update to a constant fill should always rebuild the constant operator, -trading the reuse for bitwise agreement with a fresh build. - -**A reserved electrons-per-event weight.** The compiled plasma channels -(`PlasmaChannel` in `solprop/translate/responses.py`, `EnvelopePlasmaChannel` in -`solprop/translate/envelope_plasma.py`) carry `electrons_per_event`, and the reference -backend's field-plasma current multiplies by it, but `native` does not carry -it. Validation pins it to 1, so the backends agree. Open: remove the field, or carry it -through the native backend with a test, for a model that releases more than one -electron per event. - -## Numerical methods - -Each of these has a measurable question behind it; none blocks the current solver. The -section numbers refer to the [solver design](stepper.md). - -**Error norms for observables far below the pump.** The weak norm of the step controller -(`stepper.md` §3) scores total content, so a weak spectral band — a dispersive wave, a -harmonic — can be under-resolved while the norm is met. The weighted norm is a tool, not -an answer. Open: which weighting controls the error of such an observable, and at what -cost. - -**Reject-free efficiency at matched global error.** `reject_free` takes more steps and -buys a smaller error (§3). Open: whether it wins at *matched global* error, and on which -problems. - -**Schedule transfer outside the measured ranges.** A calibrated fixed schedule transfers -across the scan cases measured so far (§8). Open: how far it transfers in pressure, -energy and length beyond them, and whether a schedule calibrated on a coarser transverse -grid transfers to the production grid. - -**Round-off growth with varying operators.** Open: whether the round-off floor of a long -replayed run grows linearly with the step count when the linear operator varies along z, -and whether dithering the schedule would decorrelate it. - -**Save-plane density versus cost.** Every save plane is a step landing (ADR-009). Open: -the cost of dense plane sets, measured against dense output. - -**FSAL through a coupled flow.** The first-same-as-last identity and its saving are known -for a coupled flow (§2). Open: whether to enable it, and with which parity statement -between backends. - -## Validation - -**Systematic differences against Luna's mixture witness.** -`tests/backends/test_luna_mixture_propagation.py` propagates a single gas and the same -gas split into two populations over 64 fixed steps from Luna's own inputs and compares -the exit field with Luna.jl's (`tests/data/luna_mixture_propagation.json`). The relative -L2 differences are 5.25e-9, the same on every run. The test admits them under a -predeclared rounding budget, $64\,n_{to}\cdot 7\cdot{\rm steps}\cdot\varepsilon$ -(1.30e-8), which is an allowance rather than a count of operations, so the margin is -2.5. (The witness's two-channel plasma case ran the gated plasma source and was dropped -with it; its arrays stay in the archive.) Open: what the systematic difference is — -summation order, an input conversion or a small model difference — so that the bound can -be derived rather than budgeted. - -**NaN in free-space reference runs under NumPy 2.3 and 2.4.** With every other -dependency at its floor, NumPy 2.3.2, 2.3.5 and 2.4.0 make the `numpy_ref` free-space -runs (line, planar and radial) return NaN fields and fail about 200 tests, among them -`tests/backends/test_line_free.py` and `tests/backends/test_free_nonlinear.py`, with -overflow warnings on the way; NumPy 2.5.0 passes them. The NumPy floor is held at 2.5 ([dependencies](dependencies.md)) until the -cause is found. Open: which operation's behaviour changed between 2.4 and 2.5, and -whether the code relies on it by accident. diff --git a/docs/dev/releasing.md b/docs/dev/releasing.md index 99219d41e..216d6a00f 100644 --- a/docs/dev/releasing.md +++ b/docs/dev/releasing.md @@ -2,7 +2,7 @@ solprop is released as three distributions from one repository, at one version taken from the `v*` git tag; no other tag affects it -([SEP 29](seps/archive/sep-0029-compiled-backend-distribution.md)): +([SEP 29](https://github.com/LupoLab/solprop/blob/main/docs/dev/seps/archive/sep-0029-compiled-backend-distribution.md)): - **`solprop`**, pure Python: a source distribution and one universal wheel. - **`solprop-native`**, the compiled backend built from `native/`: **wheels only**, one @@ -11,8 +11,7 @@ the `v*` git tag; no other tag affects it build; source builds are made from the repository ([Building the native backend](../guide/performance/building-native.md)). - **`solprop-gui`**, the desktop front end built from `gui/`, pure Python: a source - distribution and one universal wheel, installed as `solprop[gui]` and published only - once its publishing is set up (pre-flight step 5). + distribution and one universal wheel, installed as `solprop[gui]`. Versions are 0.x for now: a minor release may break the API, the output schema or the resume key, and every break is listed under "Changed (breaking)" in the changelog @@ -35,7 +34,7 @@ also runs by hand. | OpenMP runtime | GCC's `libgomp` | GCC's `libgomp` | LLVM `libomp`, built for the target | LLVM `libomp` from the LLVM installation | the same | | BLAS | OpenBLAS 0.3.34, OpenMP, `DYNAMIC_ARCH`, `solprop_` prefix (built by the configure step) | the same | Accelerate | OpenBLAS 0.3.34, OpenMP, one fixed target per build (Haswell, Nehalem; no `DYNAMIC_ARCH`), static | OpenBLAS 0.3.34, OpenMP, Neoverse N1 target, static | | FFTW 3.3.11 | shared, SSE2 and AVX codelets | shared, cycle counter, NEON codelets | shared, cycle counter, NEON codelets | static, SSE2 and AVX codelets | static, cycle counter, NEON codelets | -| vector maths (ADR-059) | SLEEF 3.9.0, static, AVX2 in the v3 build and SSE2 in the v2 | the system libm | the system libm | SLEEF 3.9.0, static, AVX2 in the v3 build and SSE2 in the v2 | the system libm | +| vector maths (ADR-059) | SLEEF 3.9.0, static, AVX2 in the v3 build and SSE2 in the v2 | the system libm | SLEEF 3.9.0, static, AdvSIMD | SLEEF 3.9.0, static, AVX2 in the v3 build and SSE2 in the v2 | the system libm | | repair | `auditwheel` | `auditwheel` | `delocate` | `delvewheel` (mangled names) | `delvewheel` (mangled names) | An x86-64 wheel holds two extensions, `_core` at x86-64-v3 and `_core_v2` at x86-64-v2, and @@ -94,8 +93,8 @@ checkout and run, in order: 1. `python -I native/ci/smoke.py --version VERSION`: the package imports and passes `check_build()`, is the distribution build at the release's version, loads the FFT, - BLAS and OpenMP libraries from inside the wheel, and carries their licences; on Arm, - both precisions of its FFTW carry the NEON codelets; + BLAS and OpenMP libraries from inside the wheel, and carries their licences and no + single-precision FFTW; on Arm, its FFTW carries the NEON codelets; 2. `python -I -m solprop_native`: the build record; 3. `python -I native/ci/coexistence.py`: NumPy and SciPy imported before and after `solprop_native`, each order in a fresh process, every package's thread @@ -116,7 +115,7 @@ runs on a Penryn (no SSE4.2). It runs when the repository variables `SDE_URL` an unit-tested with stand-in processors in `native/tests/test_cpu_baseline.py`; no CI job runs them on a processor below the baseline. -**macOS and pyFFTW.** solprop no longer uses pyFFTW, but a script or another package may. +**macOS and pyFFTW.** solprop does not use pyFFTW, but a script or another package may. pyFFTW's macOS wheel carries its own `libomp`, which it initialises when it is imported. LLVM's OpenMP runtime refuses, or crashes on, a second initialised copy, so the native package raises at import when pyFFTW is already loaded @@ -124,6 +123,12 @@ copy, so the native package raises at import when pyFFTW is already loaded that says what to do. The test jobs' second coexistence check installs pyFFTW and Numba as outside packages and runs `native/ci/coexistence.py` among them, so that guard meets a real pyFFTW on every platform but Windows on Arm, which has no pyFFTW wheel. +The guard stays until a replacement is shown safe in fresh processes, in both import +orders, with interleaved short runs (SEP 29): importing solprop does not load +`solprop_native`, so nothing in solprop can decide the order. Run by hand on macOS with +pyFFTW installed, `python -I native/ci/coexistence.py --bypass-guard` adds a scenario that +hides pyFFTW from the guard and reports what happens, without failing; it is the evidence a +change to the rule would start from. **solprop's distributions.** The `solprop-dist` job builds solprop's sdist and wheel and installs each from the file in a fresh environment, outside the checkout, beside this run's @@ -186,8 +191,8 @@ reaches `main`, the next pending fragment starts a new draft for the next cycle. A release tag builds and tests everything but publishes nothing until a maintainer with admin rights on the repository and an account on PyPI has set up publishing. Steps 1 to -4 were done once, before 0.1.0, for solprop and solprop-native; step 5 is done once, before -the first release that publishes the front end. +4 were done once, before 0.1.0, for solprop and solprop-native, and step 5 before 0.2.0, +the first release that published the front end. 1. **On PyPI** (done), under *Your account → Publishing*, add a pending trusted publisher for each project, both naming the owner `LupoLab`, the repository `solprop` and the @@ -208,7 +213,7 @@ the first release that publishes the front end. (the organisation must grant Zenodo's application access). Zenodo archives each GitHub release, not a tag, with the metadata of `.zenodo.json`, and gives it a DOI, plus one concept DOI for every version, which `CITATION.cff` and the README cite. -5. **The front end, `solprop-gui`**, in this order: +5. **The front end, `solprop-gui`** (done), in this order: 1. On PyPI, add a pending trusted publisher for the project `solprop-gui`, naming the owner `LupoLab`, the repository `solprop`, the workflow `wheels.yml` and the environment `pypi-gui`. @@ -219,17 +224,16 @@ the first release that publishes the front end. reviewer and no tag rule, so with the variable set first the next tag would publish the front end unreviewed. - Until `PUBLISH_GUI` is `true`, each release builds the front end and checks an install - of `solprop[gui]` from the files, and the extra resolves only in the repository's - workspace. - Then, for every release: 6. In the rolling release PR, marked ready to freeze refreshes, check that every pending fragment has been collected and the changelog's `Unreleased` section describes the - release. Move it under the new version, `## [X.Y.Z] - YYYY-MM-DD`, retaining an empty - `## Unreleased` section above it, and give - `CITATION.cff` the same `version` and `date-released` + release. Check that the output schema the release writes, + `solprop.output.SCHEMA_VERSION`, is at most one above the last release's: it is bumped + at most once between two releases + ([the schema version](../guide/results/output.md#the-schema-version)). Move the + section under the new version, `## [X.Y.Z] - YYYY-MM-DD`, retaining an empty + `## Unreleased` section above it, and give `CITATION.cff` the same `version` and `date-released` (`tests/test_release_metadata.py` checks that they agree). The commit that does so is the release commit; it reaches `main` through this PR, after the required checks. 7. Check that CI passed on the release commit. When it merged a pull request whose head @@ -240,7 +244,11 @@ Then, for every release: workflow that builds and tests the Linux aarch64 wheel, and on `main` it otherwise runs only weekly. On a branch the publish jobs are skipped, so this is a dry run of the release. -9. Then tag that commit, as below. +9. Run the GPU lane on that commit by hand, on a machine with a device: `uv run poe + test-gpu` against a CUDA build of solprop-native, and against a HIP build where an AMD + device is available ([testing](testing.md#2-tiers-and-lanes)). No CI job reaches a + device. Record each result on the release's tracking issue. +10. Then tag that commit, as below. ### Tagging and publishing @@ -301,6 +309,11 @@ Then, for every release: and 0.1.0, which did not require the native backend, installs there with no error ([#463](https://github.com/LupoLab/solprop/issues/463)). A yanked version still installs when it is asked for exactly (`solprop==0.1.0`). +8. Record the release in the benchmark history: on each + [recorded hardware set](benchmarking.md#recorded-hardware), rerun the tracking set + from a checkout of the release tag with `uv run python -m benchmarks track + --append-history`, as [Recording a run](benchmarking.md#recording-a-run) describes, + and commit the rows it appends in a pull request. ### Rechecking a published release @@ -334,4 +347,4 @@ The actions in the workflows are pinned by commit; when updating one, take the c its release tag and keep the version in the trailing comment. The release recipe on this page was set up and qualified by -[SEP 29](seps/archive/sep-0029-compiled-backend-distribution.md). +[SEP 29](https://github.com/LupoLab/solprop/blob/main/docs/dev/seps/archive/sep-0029-compiled-backend-distribution.md). diff --git a/docs/dev/roadmap.md b/docs/dev/roadmap.md deleted file mode 100644 index 0e5065bf3..000000000 --- a/docs/dev/roadmap.md +++ /dev/null @@ -1,87 +0,0 @@ -# Roadmap - -```{note} -Planned work is tracked in [GitHub issues](https://github.com/LupoLab/solprop/issues) (ADR-062), which can be filtered by type, -priority and area. It is not listed here. This page now holds only the status lists of -accepted and draft SEPs below, and it goes when those lists move. - -The entries this page used to hold moved to issues on 2026-11-01. Where an older page or an -archived SEP says that something is "on the roadmap", look in the issues. The -[page as it stood before the move](https://github.com/LupoLab/solprop/blob/11cd808fe03db935457f432f790939d44a243c16/docs/dev/roadmap.md) -shows what it said. -``` - -Each item here is weighed against the project's priorities (ADR-020 in -[decisions.md](decisions.md)): accuracy and reliability first, then CPU performance, then -GPU. The lists are not a schedule, and none of the proposals is promised. What exists is -described in the user manual; how it is built, in the rest of these developer pages. A -major item, such as a new model, route or numerical scheme or a changed default or -convention, starts as an [enhancement proposal](seps/index.md) (SEP, ADR-035). - -## Accepted enhancement proposals - -SEPs that have been accepted and are not yet final, each waiting to be picked up or -being implemented. - -- [SEP 17 — Broadband two-photon continuum response beside strong-field ionisation](seps/sep-0017-gas-two-photon-ionisation.md): - prescribed-field diagnostics first, then an Ar/He continuum driven by the squared VUV - field, with polarisation and optical work from one interaction. The first model gives - final yield and optical feedback; additional plasma needs a separate electron-timing - qualification. Existing optmat OEP 6 quantities suffice for this approximation. - Before production implementation, its qualification covers threshold data and - completion, reactive matching, atomic validity and the complex convolution's work, - passivity and window convergence. A coupled optmat OEP is needed only if qualification - identifies a new material contract. Ne/Xe, mixtures, mode-averaged and multimode - routes, bound response and other geometries remain follow-up work; the first route is - a single-mode capillary with node quadrature. - -## Draft enhancement proposals - -SEPs under discussion; their scope may change and implementation has not been accepted. -The [SEP index](seps/index.md) lists every proposal and its current status. - -- [SEP 1 — Efficient causal Raman evaluation](seps/sep-0001-raman-response.md): - exact sampled recurrences, including the current lag taper and silica endpoints, - beside default exact FFT evaluation. A common execution contract retains analytic - poles, permits exact FFT evaluation of density-shifted lines and supports SEP 10's - explicit approximation. Population dynamics are separated into SEP 32. -- [SEP 2 — Two-photon absorption](seps/sep-0002-two-photon-absorption.md): - constant-coefficient, narrowband scalar absorption on field and envelope grids. - Broadband and tensor absorption, and solid carrier dynamics, remain outside its scope. -- [SEP 5 — Solid ionisation and bulk filamentation](seps/sep-0005-solid-ionisation.md): - scalar bulk silica/YAG photoionisation, explicit simple avalanche and carrier - removal, collisional currents, optmat solid rate models and parameter bundles - (which need upstream optmat work first), using SEP 34's shared medium flux and - radial adiabatic transport. - Delayed-heating kinetics, subcycle rates and solid-guide ionisation remain - follow-up work in [#282](https://github.com/LupoLab/solprop/issues/282); source-normalisation questions precede acceptance. -- [SEP 7 — Laser gain dynamics in solid-core fibres](seps/sep-0007-laser-gain-dynamics.md): - Yb/silica spectroscopy through optmat, conventional steady and time-dependent - populations, pump and ASE transport, and scalar spatial gain dynamics for nonlinear - amplifiers. The broadband filtered-field closure has a separate qualification gate; - general vector gain, other ions, stochastic field ASE and oscillators remain open. -- [SEP 8 — Second-order nonlinearity and birefringent crystal optics](seps/sep-0008-quadratic-crystal-optics.md): - vector forward propagation in homogeneous crystals, quadratic frequency mixing, - BBO/LBO material curation, field/envelope grids, interfaces, physical flux and - a separately qualified statistical OPG model. Guided overlaps, varying crystal - profiles, resonant THz response and bidirectional propagation remain open. -- [SEP 9 — Broadband beam measurements and propagation statistics](seps/sep-0009-propagation-statistics.md): - frequency-dependent modal fluence and time-resolved beam widths, spectral filters, - per-mode durations, transverse peak intensity and distinct quadrature/modal-span - diagnostics. General-guide embedded quadrature and current-source span diagnostics - remain open; SEP 34 covers the shared medium-flux correction. -- [SEP 10 — Low-rank Raman kernels along density paths](seps/sep-0010-low-rank-raman.md): - explicitly requested spectral compression of density-dependent Raman kernels, - extending SEP 1's contract and exact shifted-line FFT reference. Separate basis and - coefficient-path budgets, independent-state validation and observable convergence - bound the approximation; zero tolerance selects exact evaluation. -- [SEP 11 — Finite-density gas index and mixture optics](seps/sep-0011-finite-density-gas-index.md): - optmat's Lorentz–Lorenz law with refractivity virials, applied once to a mixture, - and a composition-preserving mixture EOS. One resolved state feeds linear optics, - Raman amplitudes, widths and shifts. Current upstream model selections, estimates - and validity records govern admission; nonlinear local-field corrections remain open. -- [SEP 32 — Raman Maxwell–Bloch dynamics](seps/sep-0032-raman-maxwell-bloch.md): - a separate scalar two-level population/coherence response, with equilibrium - subtraction, a weak-response limit and local temporal integration. Its ensemble, - data and integration questions must be settled before acceptance; shared-level - ladders, vector saturation and repeated-window histories remain future work. diff --git a/docs/dev/scans.md b/docs/dev/scans.md index de1f859f8..5c8e222ff 100644 --- a/docs/dev/scans.md +++ b/docs/dev/scans.md @@ -9,8 +9,7 @@ preserve the selected backend and reject unsupported contracts explicitly. The executors (`solprop.driver.executors`) are `Local` (sequentially, in the calling process, reusing one backend where it can), `Pool` (spawned worker processes), and the durable file `Queue` with its `Slurm` emitter, which runs queue or chunk modes as array -tasks. A fixed-schedule `Batch` executor ran compatible points as one group until -SEP 52 removed it: on native it built a backend per member for no gain in speed. +tasks. ## Why the standard library @@ -62,6 +61,12 @@ Different output layouts have their own arrays and global-index mappings. A poin results are staged and checked before its status becomes done; failed and unfinished points are masked by readers. Periodic statistics use exact CSR values and offsets. +A `Local` or `Pool` controller holds the scan file's exclusive lock for its whole +session, so a `running` mark it finds was left by a controller that has gone: it claims +that point at once, with no lease age. Whatever ends a scan early (a stop, a refused +admission, a conflict, an interrupt), the controller gives every point it claimed but +did not commit back as it was, so a rerun computes it. + Queue ownership follows the refreshed per-point leases of [Luna PR 441](https://github.com/LupoLab/Luna.jl/pull/441): elapsed run duration alone does not establish abandonment. An ownership token prevents a late worker from @@ -78,7 +83,8 @@ bytes change, and no second identity contract is introduced to work around it. ## Durable executor implementation -The queue manifest is immutable. A persistent `flock` file serialises state updates; +The queue manifest is immutable. A recipe scan's recipe is kept beside it once, outside +the scan identity, and collection records it in the scan file. A persistent `flock` file serialises state updates; its inode is never removed. Active point rows contain a controller UUID, host, PID, process creation identity, claim token and refreshed wall-clock lease. Local liveness wins over elapsed age; remote takeover requires lease expiry. The controller heartbeat diff --git a/docs/dev/seps/archive/sep-0018-band-exact-plasma-integrals.md b/docs/dev/seps/archive/sep-0018-band-exact-plasma-integrals.md index 29bd0dfb8..956f700c2 100644 --- a/docs/dev/seps/archive/sep-0018-band-exact-plasma-integrals.md +++ b/docs/dev/seps/archive/sep-0018-band-exact-plasma-integrals.md @@ -134,7 +134,7 @@ accuracy"). Where it is implemented: same column. - **`numba_cpu`.** `make_response_column` fuses the whole nonlinear term into one traversal of $t$ per node. It carries the three running sums as scalars, through the - shared increment `trapezoid` in {py:mod}`solprop.backends.bodies`, in the same order + shared increment `trapezoid` in `solprop.backends.bodies`, in the same order as SciPy, so it matches the oracle's multipass scan bit for bit. - **Kokkos.** The CPU build follows that traversal. The CUDA path evaluates the rate in parallel and then runs each running sum as a deterministic fixed-tree inclusive scan diff --git a/docs/dev/seps/archive/sep-0026-edge-free-tdse-source.md b/docs/dev/seps/archive/sep-0026-edge-free-tdse-source.md index 0bdb14676..cc86d96a2 100644 --- a/docs/dev/seps/archive/sep-0026-edge-free-tdse-source.md +++ b/docs/dev/seps/archive/sep-0026-edge-free-tdse-source.md @@ -1172,7 +1172,7 @@ hash `d9a512d3…` is recorded. The private `run_short.py` was not used. recorded figure is each run's `tdse_last_evaluation` complete-source norm, reproduced within twice its recorded floor. 5. *The current-form 60 fs segment was not rerun.* The provider pin has not moved - since `benchmarks/hacc_perf/evidence/perf.json` (job 483804, solprop `d482cdf0`): + since `benchmarks/hacc_perf/evidence/perf.json` (solprop `d482cdf0`): `time_collar` keeps its formula and path. The SAE rerun is compared with SEP 20 Phase 4's `sae-window` run at `ea2bfcaa`. No native file differs between `ea2bfcaa` and `876b72d1` (only `pyroraptor/hacc/*.py` changed), so the comparison @@ -1199,12 +1199,12 @@ The L6 segments ran on cluster CPU nodes: Placement was verified with taskset and numactl: -| run | job | node | CPUs | NUMA domains | elapsed | core-hours | -|---|---|---|---|---|---|---| -| (a) | 483988 | node19 | 0–31 | 0–1 | 1 h 15 | 39.8 | -| (b) | 483989 | node19 | 32–63 | 2–3 | 1 h 46 | 56.4 | -| (c) | 483990 | node20 | 0–31 | 0–1 | 1 h 35 | 50.7 | -| SAE | 483991 | node14 | 0–31 | 0–2 | 1 h 21 | 43.2 | +| run | CPUs | NUMA domains | elapsed | core-hours | +|---|---|---|---|---| +| (a) | 0–31 | 0–1 | 1 h 15 | 39.8 | +| (b) | 32–63 | 2–3 | 1 h 46 | 56.4 | +| (c) | 0–31 | 0–1 | 1 h 35 | 50.7 | +| SAE | 0–31 | 0–2 | 1 h 21 | 43.2 | With the build and the analysis, the total is 191.5 core-hours, against 215–270 estimated. Timing was not the aim; (a) and (b) shared a node. diff --git a/docs/dev/seps/archive/sep-0033-single-precision-mlx.md b/docs/dev/seps/archive/sep-0033-single-precision-mlx.md index eb2041404..58a05f680 100644 --- a/docs/dev/seps/archive/sep-0033-single-precision-mlx.md +++ b/docs/dev/seps/archive/sep-0033-single-precision-mlx.md @@ -14,10 +14,13 @@ | **Resolution** | Accepted 2026-10-24 by John Travers after his human review, the GPT-6 AI review and the revision answering it, recorded in Part III. Final 2026-10-25 with phase 4, its open questions moved to the roadmap (Part II, phase 4 report); merging its pull request is the maintainer's approval. | | **Requires** | [SEP 25](sep-0025-rounding-level-reproducibility.md) (the floating-point policy and the bound classes this extends to binary32) | | **Supersedes** | — | -| **Superseded-by** | — | +| **Superseded-by** | [ADR-077](../../decisions.md) | | **Implementation** | John Travers with Opus 5.5 (AI); phases 1–4 on `feature/sep-0033-single-precision`, one pull request | | **Manual pages** | Single precision (the page, retired by ADR-077); [Choosing a backend](../../../guide/performance/backends.md); the worked example Single precision (retired by ADR-077) | +**Note:** [ADR-077](../../decisions.md) retired what this SEP built: solprop is binary64 +only, and the `mlx` backend is removed. This page records what was done at the time. + ## Part I — Proposal *Revised on 2026-10-23 after the human and AI reviews, with the maintainer's decisions on diff --git a/docs/dev/seps/archive/sep-0042-tolerant-resume.md b/docs/dev/seps/archive/sep-0042-tolerant-resume.md index db45b9f51..790017d98 100644 --- a/docs/dev/seps/archive/sep-0042-tolerant-resume.md +++ b/docs/dev/seps/archive/sep-0042-tolerant-resume.md @@ -6,7 +6,7 @@ | **Title** | Resuming by what matters to the run | | **Author** | John Travers | | **Drafting agent** | Opus 5.5 | -| **Status** | Superseded | +| **Status** | Final | | **Review status** | Reviewed | | **Reviewers** | John Travers (human); Opus 5.5 (AI) | | **Type** | Change | diff --git a/docs/dev/seps/archive/sep-0046-machine-calibration.md b/docs/dev/seps/archive/sep-0046-machine-calibration.md index c46f4b06b..192ad2ff0 100644 --- a/docs/dev/seps/archive/sep-0046-machine-calibration.md +++ b/docs/dev/seps/archive/sep-0046-machine-calibration.md @@ -1077,8 +1077,8 @@ index entry and tracking issue change then. benchmark tests. A first native run in a fresh script on the Xeon's socket printed the notice once, calibrated and ran in 19 s; the second run did not calibrate. - **Limitations:** §7 items 1–3, 13 and 16 need the A/B campaign on the machines of §7 - item 1 (the Xeon quiet, DMOG's EPYC 7763, Google C4D under Linux and Windows and C4A, - and the maintainer's M5 Max), which is still to run, as is phase 6. + item 1 (the Intel Xeon Gold 6240 quiet, the AMD EPYC 7763 node, Google C4D under Linux + and Windows and C4A, and the maintainer's M5 Max), which is still to run, as is phase 6. ### Verification report — section 7 items 1–4, and the revisions it forced diff --git a/docs/dev/seps/index.md b/docs/dev/seps/index.md index c4e901c96..114af0064 100644 --- a/docs/dev/seps/index.md +++ b/docs/dev/seps/index.md @@ -7,8 +7,9 @@ options and how the result will be verified; once accepted it is implemented in on `numpy_ref` and the native backend in either order, and each phase appends its report to the SEP. Finished SEPs are archived and linked from the manual pages they produced. [SEP 0](sep-0000-process.md) describes the process and says when a SEP is -needed; new SEPs start from [the template](template.md). The [roadmap](../roadmap.md) -lists accepted and in-progress SEPs first, then drafts under discussion. +needed; new SEPs start from [the template](template.md). Each open SEP has a tracking +[issue](https://github.com/LupoLab/solprop/issues?q=label%3Asep), which says where it +stands. Commit hashes recorded before solprop's first public release (in proposals, reports and benchmark entries) refer to the unpublished development history; the public history @@ -34,59 +35,55 @@ Proposals that are active, in draft, accepted, in progress or deferred. | [17](sep-0017-gas-two-photon-ionisation.md) | Broadband two-photon continuum response beside strong-field ionisation | Accepted | Feature | | [32](sep-0032-raman-maxwell-bloch.md) | Raman Maxwell–Bloch dynamics | Draft | Feature | -SEP 13, the standalone numerical prerequisite for SEP 12, SEP 14, which carried it to -the compiled backends, and SEP 16, which unified the multistep family and made it the -default, are final and archived; numbering records creation order, not implementation -order. - ## Archived -Proposals that are final, rejected, withdrawn or superseded; the -[archive](archive/index.md) lists them. +Proposals that are final, rejected, withdrawn or superseded. The archive is kept in the +repository, under `docs/dev/seps/archive/`, and is not built into this manual: each row +links the SEP's file on GitHub. | SEP | Title | Status | Type | |---|---|---|---| -| [3](archive/sep-0003-optmat-materials.md) | Materials, Raman responses and ionisation rates from optmat | Final | Change | -| [4](archive/sep-0004-execution-autotuning.md) | Bounded execution autotuning | Superseded | Feature | -| [6](archive/sep-0006-dispersive-nonlinearity.md) | Frequency-dependent electronic third-order response | Final | Feature | -| [12](archive/sep-0012-tdse-nonlinear-response.md) | TDSE-driven nonlinear response for gas-filled capillaries | Final | Feature | -| [13](archive/sep-0013-expensive-response-steppers.md) | Low-call integration for expensive nonlinear responses | Final | Feature | -| [14](archive/sep-0014-stepper-efficiency.md) | Step efficiency across routes: limits, collars, tables and dense output | Final | Change | -| [15](archive/sep-0015-exponential-adams.md) | Exponential Adams stepping for dispersive, broadband problems | Superseded | Feature | -| [16](archive/sep-0016-unified-multistep.md) | Unified multistep integration and work–precision qualification | Final | Feature | -| [18](archive/sep-0018-band-exact-plasma-integrals.md) | Band-exact running integrals for the field-grid plasma | Final | Change | -| [19](archive/sep-0019-field-scale-quadrature.md) | Field-scale radial quadrature for single-mode capillaries | Final | Feature | -| [20](archive/sep-0020-hacc-helium-tdse.md) | haCC helium TDSE target | Final | Feature | -| [21](archive/sep-0021-absorbing-boundaries.md) | Temporal boundaries: wider windows, absorption and the escaped field | Final | Change | -| [22](archive/sep-0022-memory-lean-spatial-execution.md) | Memory-lean spatial execution: statistics-only planes, construct-once runs and operator settings | Final | Change | -| [23](archive/sep-0023-far-field-aperture-spectra.md) | Far-field aperture and angular-region spectra for free-space runs | Final | Feature | -| [24](archive/sep-0024-low-storage-interaction-picture-runge-kutta.md) | A low-storage interaction-picture Runge–Kutta march for memory-bound fixed-step runs | Final | Feature | -| [25](archive/sep-0025-rounding-level-reproducibility.md) | Rounding-level reproducibility and the performance it frees | Final | Change | -| [26](archive/sep-0026-edge-free-tdse-source.md) | An edge-free gated TDSE source: hold the current instead of switching it off | Final | Change | -| [27](archive/sep-0027-held-plasma-current.md) | An edge-free field-grid plasma source: hold the current at the temporal collar | Final | Change | -| [28](archive/sep-0028-free-space-evaluation.md) | Free-space evaluation at the memory bound | Final | Change | -| [29](archive/sep-0029-compiled-backend-distribution.md) | The native backend in solprop, distributed as binaries | Final | Change | -| [30](archive/sep-0030-standard-benchmark-suite.md) | Standard benchmark suite | Superseded | Process | -| [31](archive/sep-0031-simulation-coupling.md) | Coupling simulations and transporting ultrafast fields | Final | Feature | -| [33](archive/sep-0033-single-precision-mlx.md) | Single-precision propagation, and an MLX backend for Apple GPUs | Final | Feature | -| [34](archive/sep-0034-medium-flux.md) | Medium flux for free-space propagation | Final | Change | -| [35](archive/sep-0035-carrier-frame-exponential-adams.md) | A carrier frame for the exponential Adams history | Final | Change | -| [36](archive/sep-0036-native-reduced-precision.md) | Single and mixed precision on the native backend | Withdrawn | Feature | -| [37](archive/sep-0037-noise-and-stepper-defaults.md) | Shot noise on by default, and an integrator and tolerances chosen for each interface | Final | Change | -| [38](archive/sep-0038-performance-tracking.md) | Performance tracking: complete runs, about an hour per machine | Final | Process | -| [39](archive/sep-0039-native-adams-march.md) | A native Adams march: the Multistep step loop in the compiled backend | Final | Change | -| [40](archive/sep-0040-transverse-absorbing-boundaries.md) | Transverse absorbing boundaries for free-space propagation | Final | Change | -| [41](archive/sep-0041-recipes-and-front-ends.md) | Recipes, and the hooks a front end needs | Final | Change | -| [42](archive/sep-0042-tolerant-resume.md) | Resuming by what matters to the run | Superseded | Change | -| [43](archive/sep-0043-retire-numba-cpu.md) | Retire `numba_cpu` | Final | Change | -| [44](archive/sep-0044-native-edge-read.md) | Reading the transverse edge where the state lives | Final | Change | -| [45](archive/sep-0045-native-rk-march.md) | A native Runge–Kutta march, and boundary checks inside the compiled marches | Final | Change | -| [46](archive/sep-0046-machine-calibration.md) | Calibrating the native backend to its machine | Final | Change | -| [47](archive/sep-0047-run-ownership.md) | Backend-owned execution sessions | Final | Change | -| [48](archive/sep-0048-julia-backend.md) | A Julia backend: one engine for CPUs and GPUs, in both precisions | Withdrawn | Feature | -| [49](archive/sep-0049-tdse-on-native.md) | The TDSE response on native | Final | Change | -| [51](archive/sep-0051-save-planes.md) | One rule for the saved planes and the end of a run | Final | Change | -| [52](archive/sep-0052-backend-shape.md) | One backend shape and a small native seam | Final | Change | +| [3](https://github.com/LupoLab/solprop/blob/main/docs/dev/seps/archive/sep-0003-optmat-materials.md) | Materials, Raman responses and ionisation rates from optmat | Final | Change | +| [4](https://github.com/LupoLab/solprop/blob/main/docs/dev/seps/archive/sep-0004-execution-autotuning.md) | Bounded execution autotuning | Superseded | Feature | +| [6](https://github.com/LupoLab/solprop/blob/main/docs/dev/seps/archive/sep-0006-dispersive-nonlinearity.md) | Frequency-dependent electronic third-order response | Final | Feature | +| [12](https://github.com/LupoLab/solprop/blob/main/docs/dev/seps/archive/sep-0012-tdse-nonlinear-response.md) | TDSE-driven nonlinear response for gas-filled capillaries | Final | Feature | +| [13](https://github.com/LupoLab/solprop/blob/main/docs/dev/seps/archive/sep-0013-expensive-response-steppers.md) | Low-call integration for expensive nonlinear responses | Final | Feature | +| [14](https://github.com/LupoLab/solprop/blob/main/docs/dev/seps/archive/sep-0014-stepper-efficiency.md) | Step efficiency across routes: limits, collars, tables and dense output | Final | Change | +| [15](https://github.com/LupoLab/solprop/blob/main/docs/dev/seps/archive/sep-0015-exponential-adams.md) | Exponential Adams stepping for dispersive, broadband problems | Superseded | Feature | +| [16](https://github.com/LupoLab/solprop/blob/main/docs/dev/seps/archive/sep-0016-unified-multistep.md) | Unified multistep integration and work–precision qualification | Final | Feature | +| [18](https://github.com/LupoLab/solprop/blob/main/docs/dev/seps/archive/sep-0018-band-exact-plasma-integrals.md) | Band-exact running integrals for the field-grid plasma | Final | Change | +| [19](https://github.com/LupoLab/solprop/blob/main/docs/dev/seps/archive/sep-0019-field-scale-quadrature.md) | Field-scale radial quadrature for single-mode capillaries | Final | Feature | +| [20](https://github.com/LupoLab/solprop/blob/main/docs/dev/seps/archive/sep-0020-hacc-helium-tdse.md) | haCC helium TDSE target | Final | Feature | +| [21](https://github.com/LupoLab/solprop/blob/main/docs/dev/seps/archive/sep-0021-absorbing-boundaries.md) | Temporal boundaries: wider windows, absorption and the escaped field | Final | Change | +| [22](https://github.com/LupoLab/solprop/blob/main/docs/dev/seps/archive/sep-0022-memory-lean-spatial-execution.md) | Memory-lean spatial execution: statistics-only planes, construct-once runs and operator settings | Final | Change | +| [23](https://github.com/LupoLab/solprop/blob/main/docs/dev/seps/archive/sep-0023-far-field-aperture-spectra.md) | Far-field aperture and angular-region spectra for free-space runs | Final | Feature | +| [24](https://github.com/LupoLab/solprop/blob/main/docs/dev/seps/archive/sep-0024-low-storage-interaction-picture-runge-kutta.md) | A low-storage interaction-picture Runge–Kutta march for memory-bound fixed-step runs | Final | Feature | +| [25](https://github.com/LupoLab/solprop/blob/main/docs/dev/seps/archive/sep-0025-rounding-level-reproducibility.md) | Rounding-level reproducibility and the performance it frees | Final | Change | +| [26](https://github.com/LupoLab/solprop/blob/main/docs/dev/seps/archive/sep-0026-edge-free-tdse-source.md) | An edge-free gated TDSE source: hold the current instead of switching it off | Final | Change | +| [27](https://github.com/LupoLab/solprop/blob/main/docs/dev/seps/archive/sep-0027-held-plasma-current.md) | An edge-free field-grid plasma source: hold the current at the temporal collar | Final | Change | +| [28](https://github.com/LupoLab/solprop/blob/main/docs/dev/seps/archive/sep-0028-free-space-evaluation.md) | Free-space evaluation at the memory bound | Final | Change | +| [29](https://github.com/LupoLab/solprop/blob/main/docs/dev/seps/archive/sep-0029-compiled-backend-distribution.md) | The native backend in solprop, distributed as binaries | Final | Change | +| [30](https://github.com/LupoLab/solprop/blob/main/docs/dev/seps/archive/sep-0030-standard-benchmark-suite.md) | Standard benchmark suite | Superseded | Process | +| [31](https://github.com/LupoLab/solprop/blob/main/docs/dev/seps/archive/sep-0031-simulation-coupling.md) | Coupling simulations and transporting ultrafast fields | Final | Feature | +| [33](https://github.com/LupoLab/solprop/blob/main/docs/dev/seps/archive/sep-0033-single-precision-mlx.md) | Single-precision propagation, and an MLX backend for Apple GPUs | Final | Feature | +| [34](https://github.com/LupoLab/solprop/blob/main/docs/dev/seps/archive/sep-0034-medium-flux.md) | Medium flux for free-space propagation | Final | Change | +| [35](https://github.com/LupoLab/solprop/blob/main/docs/dev/seps/archive/sep-0035-carrier-frame-exponential-adams.md) | A carrier frame for the exponential Adams history | Final | Change | +| [36](https://github.com/LupoLab/solprop/blob/main/docs/dev/seps/archive/sep-0036-native-reduced-precision.md) | Single and mixed precision on the native backend | Withdrawn | Feature | +| [37](https://github.com/LupoLab/solprop/blob/main/docs/dev/seps/archive/sep-0037-noise-and-stepper-defaults.md) | Shot noise on by default, and an integrator and tolerances chosen for each interface | Final | Change | +| [38](https://github.com/LupoLab/solprop/blob/main/docs/dev/seps/archive/sep-0038-performance-tracking.md) | Performance tracking: complete runs, about an hour per machine | Final | Process | +| [39](https://github.com/LupoLab/solprop/blob/main/docs/dev/seps/archive/sep-0039-native-adams-march.md) | A native Adams march: the Multistep step loop in the compiled backend | Final | Change | +| [40](https://github.com/LupoLab/solprop/blob/main/docs/dev/seps/archive/sep-0040-transverse-absorbing-boundaries.md) | Transverse absorbing boundaries for free-space propagation | Final | Change | +| [41](https://github.com/LupoLab/solprop/blob/main/docs/dev/seps/archive/sep-0041-recipes-and-front-ends.md) | Recipes, and the hooks a front end needs | Final | Change | +| [42](https://github.com/LupoLab/solprop/blob/main/docs/dev/seps/archive/sep-0042-tolerant-resume.md) | Resuming by what matters to the run | Final | Change | +| [43](https://github.com/LupoLab/solprop/blob/main/docs/dev/seps/archive/sep-0043-retire-numba-cpu.md) | Retire `numba_cpu` | Final | Change | +| [44](https://github.com/LupoLab/solprop/blob/main/docs/dev/seps/archive/sep-0044-native-edge-read.md) | Reading the transverse edge where the state lives | Final | Change | +| [45](https://github.com/LupoLab/solprop/blob/main/docs/dev/seps/archive/sep-0045-native-rk-march.md) | A native Runge–Kutta march, and boundary checks inside the compiled marches | Final | Change | +| [46](https://github.com/LupoLab/solprop/blob/main/docs/dev/seps/archive/sep-0046-machine-calibration.md) | Calibrating the native backend to its machine | Final | Change | +| [47](https://github.com/LupoLab/solprop/blob/main/docs/dev/seps/archive/sep-0047-run-ownership.md) | Backend-owned execution sessions | Final | Change | +| [48](https://github.com/LupoLab/solprop/blob/main/docs/dev/seps/archive/sep-0048-julia-backend.md) | A Julia backend: one engine for CPUs and GPUs, in both precisions | Withdrawn | Feature | +| [49](https://github.com/LupoLab/solprop/blob/main/docs/dev/seps/archive/sep-0049-tdse-on-native.md) | The TDSE response on native | Final | Change | +| [51](https://github.com/LupoLab/solprop/blob/main/docs/dev/seps/archive/sep-0051-save-planes.md) | One rule for the saved planes and the end of a run | Final | Change | +| [52](https://github.com/LupoLab/solprop/blob/main/docs/dev/seps/archive/sep-0052-backend-shape.md) | One backend shape and a small native seam | Final | Change | ```{toctree} :hidden: @@ -104,5 +101,4 @@ sep-0011-finite-density-gas-index sep-0017-gas-two-photon-ionisation sep-0032-raman-maxwell-bloch template -archive/index ``` diff --git a/docs/dev/seps/sep-0000-process.md b/docs/dev/seps/sep-0000-process.md index 30cd66d45..d7f8e2a52 100644 --- a/docs/dev/seps/sep-0000-process.md +++ b/docs/dev/seps/sep-0000-process.md @@ -24,7 +24,7 @@ A solprop Enhancement Proposal (SEP) is a design document for one major change t a new physical model, route or numerical scheme, a changed default or convention, a redesigned public interface. It states what is proposed and why, sets out the theory with its references, discusses how the change could be implemented, and says how it will be -shown to work. Once accepted it is implemented on branches, in phases, and each phase +shown to work. Once accepted it is implemented on one branch, in phases, and each phase appends a report to the same document. When the work is complete the SEP is archived and the manual pages it produced link to it, so that every major feature carries the record of how it was specified, built and verified. @@ -60,7 +60,7 @@ physics (even when they rename, merge or refuse public parameters, or change whi parameters a route takes), documentation, tests, refactoring, tooling and continuous integration, dependency updates, small additions to the public interface (a keyword, a helper, a statistic), or optimisations that leave results unchanged (they -still need a benchmark ledger entry, [benchmarks.md](../benchmarks.md)). Those follow the +still need a measurement in the pull request, [benchmarking.md](../benchmarking.md)). Those follow the working agreement of `AGENTS.md`: an issue or a short agreed plan, then a pull request. When it is unclear whether a change needs a SEP, the maintainers decide; they may ask for @@ -85,20 +85,27 @@ Draft ──► Accepted ──► In progress ──► Final Any status ──► Superseded (by a later SEP) ``` -| Status | Meaning | Lives in | On the roadmap | -|---|---|---|---| -| Draft | Written and under discussion; may change freely | `seps/` | yes, under drafts | -| Accepted | Agreed by the maintainers; waiting to be picked up | `seps/` | yes | -| In progress | Being implemented; at least one phase has started | `seps/` | yes | -| Final | Implemented on `numpy_ref` and the native CPU build, tested and documented | `seps/archive/` | no | -| Deferred | Not pursued for now; may return to Draft | `seps/` | no | -| Rejected | Decided against; the reasons are recorded in the SEP | `seps/archive/` | no | -| Withdrawn | Abandoned by its author | `seps/archive/` | no | -| Superseded | Replaced by a later SEP, named in the header | `seps/archive/` | no | -| Active | A Process SEP in force | `seps/` | no | - -The folder, the [index](index.md) and the roadmap are kept consistent with the status in -the header; `tests/test_seps.py` checks it. A SEP's tracking issue (ADR-062) stays open +| Status | Meaning | Lives in | +|---|---|---| +| Draft | Written and under discussion; may change freely | `seps/` | +| Accepted | Agreed by the maintainers; waiting to be picked up | `seps/` | +| In progress | Being implemented; at least one phase has started | `seps/` | +| Final | Implemented on `numpy_ref` and the native CPU build, tested and documented | `seps/archive/` | +| Deferred | Not pursued for now; may return to Draft | `seps/` | +| Rejected | Decided against; the reasons are recorded in the SEP | `seps/archive/` | +| Withdrawn | Abandoned by its author | `seps/archive/` | +| Superseded | Replaced by a later SEP, named in the header | `seps/archive/` | +| Active | A Process SEP in force | `seps/` | + +The archive, `seps/archive/`, is kept in the repository and is not built into the +manual: the [index](index.md) and the pages that cite an archived SEP link its file on +GitHub, on `main`. + +A SEP whose design a later decision record replaces, rather than a later SEP, keeps its +status (a Final SEP stays Final), names the ADR in **Superseded-by** and carries a note +under its header (*Completion*, §6). + +The folder and the [index](index.md) are kept consistent with the status in the header; `tests/test_seps.py` checks it. A SEP's tracking issue (ADR-062) stays open through `Draft`, `Accepted`, `In progress` and `Deferred`, and closes when the SEP reaches `Final`, `Rejected`, `Withdrawn` or `Superseded`. A Process SEP has none. @@ -130,8 +137,7 @@ through `Draft`, `Accepted`, `In progress` and `Deferred`, and closes when the S 2. Fill in the header and Part I: the **Author**, any **Drafting agent**, status `Draft`, review status `Not reviewed` and **Reviewers** `—`. Leave Part II empty and start Part III with the date drafted. -3. Add the SEP to the index table, the index's toctree and the *Draft enhancement - proposals* section of the [roadmap](../roadmap.md), after the accepted proposals. +3. Add the SEP to the index's *Open* table and its toctree. 4. Search the open [issues](https://github.com/LupoLab/solprop/issues) for anything the SEP touches, and list what you find in its *Context* section: the issues it will fix, those that must be resolved before it, and any others it changes. @@ -143,9 +149,8 @@ through `Draft`, `Accepted`, `In progress` and `Deferred`, and closes when the S documentation and can be discussed. Revising a draft is free: edit it in place in further pull requests and add a line to -Part III for each substantial revision. Update its roadmap summary whenever its -scope changes; work that the revised scope no longer covers goes in an -issue (ADR-062). +Part III for each substantial revision. Work that a revised scope no longer covers goes +in an issue (ADR-062). ### Review @@ -196,16 +201,14 @@ A SEP is ready to accept when: The maintainers accept a SEP in a pull request that sets the status to `Accepted`, fills in **Resolution** (the date and the pull request or discussion where it was decided), adds -a line to Part III and moves the SEP from *Draft enhancement proposals* to *Accepted -enhancement proposals* on the [roadmap](../roadmap.md). A rejection or deferral records -the reasons in the SEP, removes its proposal listing from the roadmap and opens an issue -for any still-relevant work that it had replaced (ADR-062). Apply the same update on +a line to Part III and updates its index row. A rejection or deferral records the +reasons in the SEP and opens an issue for any still-relevant work that it had replaced (ADR-062). Apply the same update on withdrawal; for supersession, reconcile the work with the replacement SEP's scope. From acceptance, Part I is frozen. A deviation found during implementation is recorded in the phase report (§8), not edited into the proposal. A change large enough to invalidate the proposal sends the SEP back to `Draft` for re-acceptance, or is made in a new SEP that -supersedes it. A return to `Draft` moves its roadmap listing back to the draft section. +supersedes it. ### Implementation @@ -247,8 +250,10 @@ request sets `Final` only when the evidence for it can exist only after the merg of the published artefacts, for example); being documentation alone, it runs only the documentation checks in CI. The commit that sets `Final` fills in **Manual pages**, moves the file with `git mv` to `docs/dev/seps/archive/`, moves its index row to the -archived table and its toctree entry to the archive index, fixes the relative links the -move breaks, removes its roadmap link, and cites the SEP in its `changelog.d/` +archived table and removes its toctree entry, turns every link to it from a built page +(the index row among them) into a link to its file on GitHub +(`https://github.com/LupoLab/solprop/blob/main/docs/dev/seps/archive/<file>`), and cites +the SEP in its `changelog.d/` release-note fragment, collected by the [rolling release PR](../releasing.md#the-rolling-release-pr). A Final SEP is a historical record. It is not updated to follow later changes to the code; @@ -293,8 +298,9 @@ and compares options; it is not a line-by-line plan, which belongs to the implem name, with an error saying which backend does support it; it never falls back silently. A SEP is Final only when the backends that run the feature agree within tolerances derived from summation bounds, as for every other feature ([testing.md](../testing.md)). -- **The seam.** A change to the kernel problem, the stage bundles or the protected driver - surface rewrites the frozen tables and adds a release-note fragment, as `AGENTS.md` +- **The seam.** A change to the kernel problem (`PropagationProblem`), the run request + (`RunRequest`) or the stage bundles rewrites the frozen tables of + `tests/backends/test_driver.py` and adds a release-note fragment, as `AGENTS.md` requires; the SEP says in which phase. - **Tests.** Unit, invariant, convergence and parity tests as [testing.md](../testing.md) sets out, against the analytic and independent references the SEP names; every @@ -339,8 +345,8 @@ assumption that had to be invented are all said plainly. | ADR ([decisions.md](../decisions.md)) | A durable decision and its reasons; code comments cite ADRs | | Manual (`docs/`) | How the functionality works and how to use it, as it is now | | Design pages (`docs/dev/`) | How the code is built, as it is now | -| [Issues](https://github.com/LupoLab/solprop/issues) | Planned work (ADR-062) | -| [Roadmap](../roadmap.md) | Accepted and draft SEPs | +| [Issues](https://github.com/LupoLab/solprop/issues) | Planned work and open questions (ADR-062) | +| [SEP index](index.md) | Every SEP and its status | | `changelog.d/`, collected into `CHANGELOG.md` by the release PR | What changed in each release, citing the SEP | The theory of a SEP moves into the manual when it is implemented: the manual page carries @@ -382,7 +388,7 @@ that edits this document and adds a line to its history. work isn't divided across a stack, since every pull request and push runs CI's whole matrix (maintainer's decision). - 2026-11-09: John Travers approved a narrow exception for - [SEP 47](archive/sep-0047-run-ownership.md#11-phases): its implementation may merge through + [SEP 47](https://github.com/LupoLab/solprop/blob/main/docs/dev/seps/archive/sep-0047-run-ownership.md#11-phases): its implementation may merge through a small number of coherent phase PRs, each leaving main usable with green required CI. Temporary internal adapters are removed by Final, and its Implementation field retains the successive milestone branches and PRs. The general one-branch/one-PR @@ -394,9 +400,18 @@ that edits this document and adds a line to its history. even when they change public parameters; a public-interface redesign is no longer on the list of changes that require one (maintainer's decision). - 2026-11-15: John Travers approved a narrow exception for - [SEP 52](archive/sep-0052-backend-shape.md#11-phases): its implementation merges through four + [SEP 52](https://github.com/LupoLab/solprop/blob/main/docs/dev/seps/archive/sep-0052-backend-shape.md#11-phases): its implementation merges through four stacked phase pull requests, each based on the one before and each leaving main usable with green required CI when it merges, although one agent implements them. Temporary internal adapters are removed by Final, and its Implementation field lists the milestone branches and pull requests. The general rules are unchanged; this records the delivery exception, not acceptance of SEP 52. +- 2026-11-17: Clarifications: a SEP whose design a later ADR replaces stays at its status + with the ADR as its Superseded-by note (as SEP 42 and ADR-066 have it, and now SEP 33 + and ADR-077); the seam rule names the run request and drops the driver surface SEP 47 + removed; a SEP is implemented on one branch, and the template's phase reports follow + that rule. +- 2026-11-17: Clarifications: the archive stays in the repository but is no longer built + into the manual, so pages link an archived SEP's file on GitHub; the roadmap is gone, + its lists being the index's; an optimisation's measurement goes in its pull request + rather than a ledger page. diff --git a/docs/dev/seps/sep-0001-raman-response.md b/docs/dev/seps/sep-0001-raman-response.md index f57773cef..f8ca3075a 100644 --- a/docs/dev/seps/sep-0001-raman-response.md +++ b/docs/dev/seps/sep-0001-raman-response.md @@ -12,7 +12,7 @@ | **Type** | Feature | | **Created** | 2026-09-26 | | **Resolution** | — | -| **Requires** | [SEP 3](archive/sep-0003-optmat-materials.md) | +| **Requires** | [SEP 3](https://github.com/LupoLab/solprop/blob/main/docs/dev/seps/archive/sep-0003-optmat-materials.md) | | **Supersedes** | — | | **Superseded-by** | — | | **Implementation** | Not started | @@ -98,7 +98,7 @@ or arbitrary changing collision partners. | Proposal | Relationship | |---|---| | SEP 3 | Implemented material ownership, data identities and Raman tensor mapping | -| [SEP 6](archive/sep-0006-dispersive-nonlinearity.md) | Electronic response composition and harmonic-sector checks; no Raman dispersion model | +| [SEP 6](https://github.com/LupoLab/solprop/blob/main/docs/dev/seps/archive/sep-0006-dispersive-nonlinearity.md) | Electronic response composition and harmonic-sector checks; no Raman dispersion model | | SEP 10 | Extends this SEP's execution contract with approximate spectral bases | | [SEP 11](sep-0011-finite-density-gas-index.md) | Supplies consistent density paths from the selected EOS; is not a dependency of either evaluator | | SEP 32 | Separate nonlinear molecular state model; its weak limit can use these exact kernel references | @@ -847,9 +847,14 @@ No implementation phases have started. - 2026-10-22: Split the new material model into SEP 32; reviewed and revised the remaining proposal jointly with SEP 10, with compatibility changes to SEP 11. - 2026-11-01: Tracking issue [#113](https://github.com/LupoLab/solprop/issues/113). -- 2026-11-02: [SEP 43](archive/sep-0043-retire-numba-cpu.md) retired `numba_cpu` (ADR-064). Where this +- 2026-11-02: [SEP 43](https://github.com/LupoLab/solprop/blob/main/docs/dev/seps/archive/sep-0043-retire-numba-cpu.md) retired `numba_cpu` (ADR-064). Where this proposal names Numba or `numba_cpu`, it was written before that: such a phase or check falls away, and the feature goes on `numpy_ref` and the native backend (SEP 0). +- 2026-11-18: Written before the current architecture. Where this proposal names + solprop-kokkos or its files, read the native package in this repository (`native/`, + [SEP 29](https://github.com/LupoLab/solprop/blob/main/docs/dev/seps/archive/sep-0029-compiled-backend-distribution.md)); the backends have since been + cut to two, binary64 only, with one shape and a native seam that only marshals + ([SEP 52](https://github.com/LupoLab/solprop/blob/main/docs/dev/seps/archive/sep-0052-backend-shape.md), ADR-077, ADR-079). ### Maintainer decisions for this revision — 2026-10-22 diff --git a/docs/dev/seps/sep-0002-two-photon-absorption.md b/docs/dev/seps/sep-0002-two-photon-absorption.md index d7cf9342b..7fe4848ac 100644 --- a/docs/dev/seps/sep-0002-two-photon-absorption.md +++ b/docs/dev/seps/sep-0002-two-photon-absorption.md @@ -80,7 +80,7 @@ The [nonlinear model](../../guide/media/nonlinear.md), [general modal model](../../guide/waveguides/general-modal.md), [architecture](../architecture.md) and [kernel contract](../kernel-contract.md) provide the starting point. The proposal addresses the TPA item under -*Spectral-domain responses* in the [roadmap](../roadmap.md), and is related to, but +*Spectral-domain responses* in the [roadmap](https://github.com/LupoLab/solprop/blob/11cd808fe03db935457f432f790939d44a243c16/docs/dev/roadmap.md), and is related to, but does not implement, its separate *Ionisation in solids* item. The relevant current code is: @@ -1029,7 +1029,7 @@ appends its report to Part II in its merging pull request. strengthened measurement provenance, corrected-theory and subsequent two-band validation requirements. Retained the proposed scalar first scope and recorded the remaining supplement/data gaps. -- 2026-10-17: Restated for [SEP 25](archive/sep-0025-rounding-level-reproducibility.md). +- 2026-10-17: Restated for [SEP 25](https://github.com/LupoLab/solprop/blob/main/docs/dev/seps/archive/sep-0025-rounding-level-reproducibility.md). The disabled-term checks (§6.3 and the §7 table's last row) are exact only where the disabled case runs the unchanged old path, a structural no-op, and for counters, workspace, plans and the memory/transform ledger; a disabled case compiled as a @@ -1037,6 +1037,11 @@ appends its report to Part II in its merging pull request. Phase 2's thread invariance (§11) becomes thread-count agreement within such a bound. - 2026-11-01: Tracking issue [#114](https://github.com/LupoLab/solprop/issues/114). -- 2026-11-02: [SEP 43](archive/sep-0043-retire-numba-cpu.md) retired `numba_cpu` (ADR-064). Where this +- 2026-11-02: [SEP 43](https://github.com/LupoLab/solprop/blob/main/docs/dev/seps/archive/sep-0043-retire-numba-cpu.md) retired `numba_cpu` (ADR-064). Where this proposal names Numba or `numba_cpu`, it was written before that: such a phase or check falls away, and the feature goes on `numpy_ref` and the native backend (SEP 0). +- 2026-11-18: Written before the current architecture. Where this proposal names + solprop-kokkos or its files, read the native package in this repository (`native/`, + [SEP 29](https://github.com/LupoLab/solprop/blob/main/docs/dev/seps/archive/sep-0029-compiled-backend-distribution.md)); the backends have since been + cut to two, binary64 only, with one shape and a native seam that only marshals + ([SEP 52](https://github.com/LupoLab/solprop/blob/main/docs/dev/seps/archive/sep-0052-backend-shape.md), ADR-077, ADR-079). diff --git a/docs/dev/seps/sep-0005-solid-ionisation.md b/docs/dev/seps/sep-0005-solid-ionisation.md index 0c901a78d..77db10b23 100644 --- a/docs/dev/seps/sep-0005-solid-ionisation.md +++ b/docs/dev/seps/sep-0005-solid-ionisation.md @@ -12,7 +12,7 @@ | **Type** | Feature | | **Created** | 2026-09-27 | | **Resolution** | — | -| **Requires** | [SEP 3](archive/sep-0003-optmat-materials.md): material adapters and resolved material identities; [SEP 34](archive/sep-0034-medium-flux.md): shared medium flux and radial adiabatic transport | +| **Requires** | [SEP 3](https://github.com/LupoLab/solprop/blob/main/docs/dev/seps/archive/sep-0003-optmat-materials.md): material adapters and resolved material identities; [SEP 34](https://github.com/LupoLab/solprop/blob/main/docs/dev/seps/archive/sep-0034-medium-flux.md): shared medium flux and radial adiabatic transport | | **Supersedes** | — | | **Superseded-by** | — | | **Implementation** | — | @@ -29,7 +29,7 @@ Fused silica and undoped YAG are the first material targets. Recommend a cycle-averaged solid Keldysh rate spanning multiphoton and tunnelling regimes, an explicitly selected multiphoton alternative, and a bounded population model with optional avalanche and carrier removal. Following -[SEP 3](archive/sep-0003-optmat-materials.md)'s decision D15, optmat owns the solid +[SEP 3](https://github.com/LupoLab/solprop/blob/main/docs/dev/seps/archive/sep-0003-optmat-materials.md)'s decision D15, optmat owns the solid photoionisation rate models, with their normalisation, averaging declaration and validation, together with the curated material parameters and their provenance. solprop tabulates those rates and owns the population/current equations, the @@ -592,7 +592,7 @@ Pointwise broadband flux need not be nonnegative; do not clip it into a rate drive. Rates use §4.1's positive proxy. Specify zero-frequency/endpoints and refuse launch energy on nonpropagating support. -[SEP 34](archive/sep-0034-medium-flux.md) owns the shared implementation for isotropic +[SEP 34](https://github.com/LupoLab/solprop/blob/main/docs/dev/seps/archive/sep-0034-medium-flux.md) owns the shared implementation for isotropic media, including launches, noise, observations, endpoint rules, certified radial forward transport and backend qualification. Use its constants consistently with the scalar source prefactor. @@ -1181,13 +1181,18 @@ No implementation phases have started. Solid rates, kinetics and their qualification remain this proposal's scope. - 2026-10-23: Reassigned the shared medium-flux prerequisite to - [SEP 34](archive/sep-0034-medium-flux.md) following SEP 31's review and split. + [SEP 34](https://github.com/LupoLab/solprop/blob/main/docs/dev/seps/archive/sep-0034-medium-flux.md) following SEP 31's review and split. SEP 31 retains field exchange and coupling; the shared flux proposal includes admitted radial adiabatic transport and complex local flux. - 2026-10-23: Aligned the shared-flux description with SEP 34's review response: the real-index path certificate, forward-component local closure and deferral of varying absorption. Solid-ionisation scope is unchanged. - 2026-11-01: Tracking issue [#116](https://github.com/LupoLab/solprop/issues/116). -- 2026-11-02: [SEP 43](archive/sep-0043-retire-numba-cpu.md) retired `numba_cpu` (ADR-064). Where this +- 2026-11-02: [SEP 43](https://github.com/LupoLab/solprop/blob/main/docs/dev/seps/archive/sep-0043-retire-numba-cpu.md) retired `numba_cpu` (ADR-064). Where this proposal names Numba or `numba_cpu`, it was written before that: such a phase or check falls away, and the feature goes on `numpy_ref` and the native backend (SEP 0). +- 2026-11-18: Written before the current architecture. Where this proposal names + solprop-kokkos or its files, read the native package in this repository (`native/`, + [SEP 29](https://github.com/LupoLab/solprop/blob/main/docs/dev/seps/archive/sep-0029-compiled-backend-distribution.md)); the backends have since been + cut to two, binary64 only, with one shape and a native seam that only marshals + ([SEP 52](https://github.com/LupoLab/solprop/blob/main/docs/dev/seps/archive/sep-0052-backend-shape.md), ADR-077, ADR-079). diff --git a/docs/dev/seps/sep-0007-laser-gain-dynamics.md b/docs/dev/seps/sep-0007-laser-gain-dynamics.md index 3099587e2..eabfede28 100644 --- a/docs/dev/seps/sep-0007-laser-gain-dynamics.md +++ b/docs/dev/seps/sep-0007-laser-gain-dynamics.md @@ -12,7 +12,7 @@ | **Type** | Feature | | **Created** | 2026-09-27 | | **Resolution** | — | -| **Requires** | [SEP 3 — Materials, Raman responses and ionisation rates from optmat](archive/sep-0003-optmat-materials.md) | +| **Requires** | [SEP 3 — Materials, Raman responses and ionisation rates from optmat](https://github.com/LupoLab/solprop/blob/main/docs/dev/seps/archive/sep-0003-optmat-materials.md) | | **Supersedes** | — | | **Superseded-by** | — | | **Implementation** | — | @@ -107,7 +107,7 @@ small-ASE comparison, not a default justified by the presence of a seed. The current [solid-fibre guide](../../guide/waveguides/solid-fibres.md), [GNLSE](../../guide/waveguides/gnlse.md) and [general modal model](../../guide/waveguides/general-modal.md) already provide much of the passive propagation physics. The missing functionality is -the “Gain with saturation” item in the [roadmap](../roadmap.md). Prescribed gain in a +the “Gain with saturation” item in the [roadmap](https://github.com/LupoLab/solprop/blob/11cd808fe03db935457f432f790939d44a243c16/docs/dev/roadmap.md). Prescribed gain in a linear operator supplies neither populations nor a pump energy budget. The first delivery should extend the existing mode-averaged GNLSE interface, supplying @@ -139,7 +139,7 @@ The relevant boundaries are: uses physical vector fields, a flux metric, and a field grid. It cannot be advertised as a scalar envelope gain route without a new derivation and implementation. -[SEP 3](archive/sep-0003-optmat-materials.md) establishes the dependency and provenance pattern +[SEP 3](https://github.com/LupoLab/solprop/blob/main/docs/dev/seps/archive/sep-0003-optmat-materials.md) establishes the dependency and provenance pattern for optmat, but its scope is gases and passive silica properties. It does not supply rare-earth spectroscopy. This proposal needs an upstream gain-spectroscopy extension in addition to SEP 3. [SEP 32](sep-0032-raman-maxwell-bloch.md) proposes a Raman @@ -488,7 +488,7 @@ needs the noise to see only the emission gain, not the net gain. Either the nois injected separately and acted on by the emission part of the gain operator alone, as in the split of Chen and Wise (arXiv:2410.20567), which solprop's modified-noise injection path (ADR-008) could carry, or a gain Langevin term supplies the distributed -spontaneous emission. [SEP 37](archive/sep-0037-noise-and-stepper-defaults.md) keeps that +spontaneous emission. [SEP 37](https://github.com/LupoLab/solprop/blob/main/docs/dev/seps/archive/sep-0037-noise-and-stepper-defaults.md) keeps that injection path until this choice is made. Such stochastic work is deferred here; there is no claim of reproducing all stochastic figures in [1, 2]. @@ -1106,9 +1106,14 @@ is an algebraic consistency check, not experimental evidence. - 2026-10-26: Added a note to §4.6 that stochastic ASE needs the noise to see only the emission gain, through a separate injection path or a gain Langevin term (SEP 37). - 2026-11-01: Tracking issue [#117](https://github.com/LupoLab/solprop/issues/117). -- 2026-11-02: [SEP 43](archive/sep-0043-retire-numba-cpu.md) retired `numba_cpu` (ADR-064). Where this +- 2026-11-02: [SEP 43](https://github.com/LupoLab/solprop/blob/main/docs/dev/seps/archive/sep-0043-retire-numba-cpu.md) retired `numba_cpu` (ADR-064). Where this proposal names Numba or `numba_cpu`, it was written before that: such a phase or check falls away, and the feature goes on `numpy_ref` and the native backend (SEP 0). - 2026-11-17: The kernel-contract references follow the current seam: `PropagationProblem` for `KernelProblem`, and the frozen seam tables for the retired schema version and `StepDriver` surface (ADR-068, SEP 52). +- 2026-11-18: Written before the current architecture. Where this proposal names + solprop-kokkos or its files, read the native package in this repository (`native/`, + [SEP 29](https://github.com/LupoLab/solprop/blob/main/docs/dev/seps/archive/sep-0029-compiled-backend-distribution.md)); the backends have since been + cut to two, binary64 only, with one shape and a native seam that only marshals + ([SEP 52](https://github.com/LupoLab/solprop/blob/main/docs/dev/seps/archive/sep-0052-backend-shape.md), ADR-077, ADR-079). diff --git a/docs/dev/seps/sep-0008-quadratic-crystal-optics.md b/docs/dev/seps/sep-0008-quadratic-crystal-optics.md index d2b5c1eeb..7465dd19f 100644 --- a/docs/dev/seps/sep-0008-quadratic-crystal-optics.md +++ b/docs/dev/seps/sep-0008-quadratic-crystal-optics.md @@ -146,7 +146,7 @@ columns. Three local physical components do not mean changing that state axis to length three. The two wave branches are an internal factorization of each local linear block. -[SEP 3](archive/sep-0003-optmat-materials.md) proposes material ownership and identity +[SEP 3](https://github.com/LupoLab/solprop/blob/main/docs/dev/seps/archive/sep-0003-optmat-materials.md) proposes material ownership and identity through optmat, but its implementation scope is the gases and solids solprop already ships, with the principal indices of MgF2 and sapphire as fixed-axis choices. It does **not** supply BBO/LBO crystal records or second-order tensors. Those are additional @@ -157,7 +157,7 @@ observations include BBO, including refractive, absorption and third-order data. They do not yet constitute the coherent linear/thermal/quadratic bundle required below; no LBO material entry or public second-order tensor model was found. -[SEP 6](archive/sep-0006-dispersive-nonlinearity.md) shares the idea of filtered nonlinear +[SEP 6](https://github.com/LupoLab/solprop/blob/main/docs/dev/seps/archive/sep-0006-dispersive-nonlinearity.md) shares the idea of filtered nonlinear products and the need for susceptibility symmetries. It is not a prerequisite: this SEP must work with today's electronic response capabilities. Shared filtered execution machinery may be consolidated if both proposals are accepted; neither @@ -1293,7 +1293,7 @@ the transverse negative-wavevector/Fourier-origin convention as well as temporal conjugation; tests must cover both, not insert ad hoc sign changes in kernels. The general spatial vacuum-flux issue on the roadmap is solved here **only -for the new crystal route**. [SEP 34](archive/sep-0034-medium-flux.md) owns the +for the new crystal route**. [SEP 34](https://github.com/LupoLab/solprop/blob/main/docs/dev/seps/archive/sep-0034-medium-flux.md) owns the uniform isotropic scalar flux correction and its clean breaking change, with no legacy normalisation or old-file migration. Its scalar admittance must not replace this proposal's anisotropic vector E/H metric or interface solver. @@ -1576,10 +1576,18 @@ verification is not verification of all coefficients in an article. remain separate; no scalar-flux substitution is implied. - 2026-10-23: Reassigned the shared medium-flux prerequisite to - [SEP 34](archive/sep-0034-medium-flux.md) following SEP 31's review and split. + [SEP 34](https://github.com/LupoLab/solprop/blob/main/docs/dev/seps/archive/sep-0034-medium-flux.md) following SEP 31's review and split. SEP 31 retains field exchange and coupling; the shared flux proposal includes admitted radial adiabatic transport and complex local flux. - 2026-11-01: Tracking issue [#118](https://github.com/LupoLab/solprop/issues/118). -- 2026-11-02: [SEP 43](archive/sep-0043-retire-numba-cpu.md) retired `numba_cpu` (ADR-064). Where this +- 2026-11-02: [SEP 43](https://github.com/LupoLab/solprop/blob/main/docs/dev/seps/archive/sep-0043-retire-numba-cpu.md) retired `numba_cpu` (ADR-064). Where this proposal names Numba or `numba_cpu`, it was written before that: such a phase or check falls away, and the feature goes on `numpy_ref` and the native backend (SEP 0). +- 2026-11-18: Written before the current architecture. Where this proposal names + solprop-kokkos or its files, read the native package in this repository (`native/`, + [SEP 29](https://github.com/LupoLab/solprop/blob/main/docs/dev/seps/archive/sep-0029-compiled-backend-distribution.md)); the backends have since been + cut to two, binary64 only, with one shape and a native seam that only marshals + ([SEP 52](https://github.com/LupoLab/solprop/blob/main/docs/dev/seps/archive/sep-0052-backend-shape.md), ADR-077, ADR-079). +- 2026-11-18: The native lockstep `Batch` named in Part I went with the batch executor + ([SEP 52](https://github.com/LupoLab/solprop/blob/main/docs/dev/seps/archive/sep-0052-backend-shape.md), ADR-079); ensembles run as Local or Pool + scans, and that admission falls away. diff --git a/docs/dev/seps/sep-0009-propagation-statistics.md b/docs/dev/seps/sep-0009-propagation-statistics.md index 373b0b7ea..bc1f2bdff 100644 --- a/docs/dev/seps/sep-0009-propagation-statistics.md +++ b/docs/dev/seps/sep-0009-propagation-statistics.md @@ -62,7 +62,7 @@ supply a beam width. Scalar and vector profiles, taper motion, material regions, modal coherence and saved-field amplitude conventions are in scope. Existing radial, Cartesian, line and hybrid planar statistics remain supported; -their common flux measure follows [SEP 34](archive/sep-0034-medium-flux.md)'s +their common flux measure follows [SEP 34](https://github.com/LupoLab/solprop/blob/main/docs/dev/seps/archive/sep-0034-medium-flux.md)'s medium-flux correction. Adding further time-resolved spatial measurements is outside this SEP. SEP 31 also owns transported observation-plane fields; the measurements here describe fields inside the propagation route. @@ -957,7 +957,7 @@ No implementation has started. - 2026-09-27: Drafted after a capability and reconstruction audit. Scope includes both full-pulse fluence and time-resolved beam widths, explicit spectral filters, and separately defined quadrature and modal-span diagnostics. -- 2026-10-17: Restated for [SEP 25](archive/sep-0025-rounding-level-reproducibility.md). +- 2026-10-17: Restated for [SEP 25](https://github.com/LupoLab/solprop/blob/main/docs/dev/seps/archive/sep-0025-rounding-level-reproducibility.md). §7 item 11's "propagated arrays bitwise unchanged" by statistics becomes a structural rule (statistics only read the state and change no march operation) plus a rounding bound fixed before measurement for replayed runs and the case's @@ -972,10 +972,15 @@ No implementation has started. measurement scope; schema changes require no old-file compatibility layer. - 2026-10-23: Reassigned the shared medium-flux prerequisite to - [SEP 34](archive/sep-0034-medium-flux.md) following SEP 31's review and split. + [SEP 34](https://github.com/LupoLab/solprop/blob/main/docs/dev/seps/archive/sep-0034-medium-flux.md) following SEP 31's review and split. SEP 31 retains field exchange and coupling; the shared flux proposal includes admitted radial adiabatic transport and complex local flux. - 2026-11-01: Tracking issue [#119](https://github.com/LupoLab/solprop/issues/119). -- 2026-11-02: [SEP 43](archive/sep-0043-retire-numba-cpu.md) retired `numba_cpu` (ADR-064). Where this +- 2026-11-02: [SEP 43](https://github.com/LupoLab/solprop/blob/main/docs/dev/seps/archive/sep-0043-retire-numba-cpu.md) retired `numba_cpu` (ADR-064). Where this proposal names Numba or `numba_cpu`, it was written before that: such a phase or check falls away, and the feature goes on `numpy_ref` and the native backend (SEP 0). +- 2026-11-18: Written before the current architecture. Where this proposal names + solprop-kokkos or its files, read the native package in this repository (`native/`, + [SEP 29](https://github.com/LupoLab/solprop/blob/main/docs/dev/seps/archive/sep-0029-compiled-backend-distribution.md)); the backends have since been + cut to two, binary64 only, with one shape and a native seam that only marshals + ([SEP 52](https://github.com/LupoLab/solprop/blob/main/docs/dev/seps/archive/sep-0052-backend-shape.md), ADR-077, ADR-079). diff --git a/docs/dev/seps/sep-0010-low-rank-raman.md b/docs/dev/seps/sep-0010-low-rank-raman.md index c2e0c405e..41141ae84 100644 --- a/docs/dev/seps/sep-0010-low-rank-raman.md +++ b/docs/dev/seps/sep-0010-low-rank-raman.md @@ -12,7 +12,7 @@ | **Type** | Feature | | **Created** | 2026-09-29 | | **Resolution** | — | -| **Requires** | [SEP 3](archive/sep-0003-optmat-materials.md); [SEP 1](sep-0001-raman-response.md), the common execution contract and exact shifted-line reference from phase 1 | +| **Requires** | [SEP 3](https://github.com/LupoLab/solprop/blob/main/docs/dev/seps/archive/sep-0003-optmat-materials.md); [SEP 1](sep-0001-raman-response.md), the common execution contract and exact shifted-line reference from phase 1 | | **Supersedes** | — | | **Superseded-by** | — | | **Implementation** | Not started | @@ -93,7 +93,7 @@ For optmat mixtures, strengths already contain mole fractions and the response u the summed density of its labels. Do not multiply fractions twice. Supplied component amplitudes and collision-density paths retain their separate meanings. -[SEP 6](archive/sep-0006-dispersive-nonlinearity.md) owns electronic dispersion. +[SEP 6](https://github.com/LupoLab/solprop/blob/main/docs/dev/seps/archive/sep-0006-dispersive-nonlinearity.md) owns electronic dispersion. Its filters never act on Raman's drive or emitted source. The new [Maxwell–Bloch SEP](sep-0032-raman-maxwell-bloch.md) owns evolving molecular states; its nonlinear material solver is not compressed by this linear kernel representation. @@ -454,7 +454,7 @@ No implementation phases have started. - 2026-10-22: Reviewed with SEP 1 and revised to use its execution contract, exact default, explicit approximation and current material/state semantics. - 2026-11-01: Tracking issue [#120](https://github.com/LupoLab/solprop/issues/120). -- 2026-11-02: [SEP 43](archive/sep-0043-retire-numba-cpu.md) retired `numba_cpu` (ADR-064). Where this +- 2026-11-02: [SEP 43](https://github.com/LupoLab/solprop/blob/main/docs/dev/seps/archive/sep-0043-retire-numba-cpu.md) retired `numba_cpu` (ADR-064). Where this proposal names Numba or `numba_cpu`, it was written before that: such a phase or check falls away, and the feature goes on `numpy_ref` and the native backend (SEP 0). diff --git a/docs/dev/seps/sep-0011-finite-density-gas-index.md b/docs/dev/seps/sep-0011-finite-density-gas-index.md index 2eaa09842..b990fa18b 100644 --- a/docs/dev/seps/sep-0011-finite-density-gas-index.md +++ b/docs/dev/seps/sep-0011-finite-density-gas-index.md @@ -12,7 +12,7 @@ | **Type** | Change | | **Created** | 2026-09-29 | | **Resolution** | — | -| **Requires** | [SEP 3](archive/sep-0003-optmat-materials.md): optmat polarizabilities and material identities | +| **Requires** | [SEP 3](https://github.com/LupoLab/solprop/blob/main/docs/dev/seps/archive/sep-0003-optmat-materials.md): optmat polarizabilities and material identities | | **Supersedes** | — | | **Superseded-by** | — | | **Implementation** | — | @@ -28,7 +28,7 @@ applied once to the whole mixture. The selected upstream pair terms retain their curated, estimated or unknown status. Against the finite-density model, the dilute-law difference is about 0.02–0.05 % of $n-1$ at 1 bar, but 0.2–0.6 % at 10 bar and more above, comparable to the data improvements -[SEP 3](archive/sep-0003-optmat-materials.md) brings. +[SEP 3](https://github.com/LupoLab/solprop/blob/main/docs/dev/seps/archive/sep-0003-optmat-materials.md) brings. Because the new law is nonlinear in density, it changes solprop's frequency-only per-particle caches, the fast paths that multiply them by density, mode freezing, @@ -413,7 +413,7 @@ No implementation phases have started. shared response state and cache invalidation, and retained explicit questions for the standalone acceptance review. This is not a completed full review of SEP 11. - 2026-11-01: Tracking issue [#121](https://github.com/LupoLab/solprop/issues/121). -- 2026-11-02: [SEP 43](archive/sep-0043-retire-numba-cpu.md) retired `numba_cpu` (ADR-064). Where this +- 2026-11-02: [SEP 43](https://github.com/LupoLab/solprop/blob/main/docs/dev/seps/archive/sep-0043-retire-numba-cpu.md) retired `numba_cpu` (ADR-064). Where this proposal names Numba or `numba_cpu`, it was written before that: such a phase or check falls away, and the feature goes on `numpy_ref` and the native backend (SEP 0). diff --git a/docs/dev/seps/sep-0017-gas-two-photon-ionisation.md b/docs/dev/seps/sep-0017-gas-two-photon-ionisation.md index d4751ed86..9a3bb5dbc 100644 --- a/docs/dev/seps/sep-0017-gas-two-photon-ionisation.md +++ b/docs/dev/seps/sep-0017-gas-two-photon-ionisation.md @@ -12,7 +12,7 @@ | **Type** | Feature | | **Created** | 2026-10-08 | | **Resolution** | Re-accepted 2026-10-12 by John Travers after the independent review and the three follow-up corrections recorded in Part III. Phase 0 qualification remains required before production implementation in Phase 1. The earlier acceptance and return to Draft remain in the history. | -| **Requires** | [SEP 3](archive/sep-0003-optmat-materials.md) (material data); [SEP 6](archive/sep-0006-dispersive-nonlinearity.md) (electronic response composition); optmat OEP 6's implemented continuum data | +| **Requires** | [SEP 3](https://github.com/LupoLab/solprop/blob/main/docs/dev/seps/archive/sep-0003-optmat-materials.md) (material data); [SEP 6](https://github.com/LupoLab/solprop/blob/main/docs/dev/seps/archive/sep-0006-dispersive-nonlinearity.md) (electronic response composition); optmat OEP 6's implemented continuum data | | **Supersedes** | — | | **Superseded-by** | — | | **Implementation** | — | @@ -107,7 +107,7 @@ with their changed resolutions and scope made explicit. There is one implementat track and no separate rate-based two-photon response to enable beside it. The existing [plasma response](../../guide/media/field-plasma.md#the-plasma-response) supplies -pump-ionisation and free-electron currents. [SEP 18](archive/sep-0018-band-exact-plasma-integrals.md) +pump-ionisation and free-electron currents. [SEP 18](https://github.com/LupoLab/solprop/blob/main/docs/dev/seps/archive/sep-0018-band-exact-plasma-integrals.md) provides band-exact running integrals, but does not supply a physical ionisation-time history. The proposed optical continuum supplies a polarisation directly; it does not need to pass through the plasma current's running integral. Q18 still requires the @@ -115,7 +115,7 @@ correct source factor and discrete work. References in the archived SEP 18 to th proposal's former section 4.9 describe the earlier design; the current treatment is in sections 4.3 and 4.6 and Q18. -[SEP 12](archive/sep-0012-tdse-nonlinear-response.md) provides a TDSE comparison +[SEP 12](https://github.com/LupoLab/solprop/blob/main/docs/dev/seps/archive/sep-0012-tdse-nonlinear-response.md) provides a TDSE comparison route; its native response must be used without replacing its absorptive cubic by a real Kerr term. Its calibrated material and numerical limitations remain separate from this SEP's model error. For structural atomic comparisons use native scale one and @@ -128,7 +128,7 @@ optmat [OEP 6][oep6] supplies `two_photon_ionisation_model`, `cross_section`, `pair_cross_section`, thresholds, region masks, uncertainties and identities. [OEP 8][oep8] and its review explicitly leave propagation polarisation, electron accounting and energy balance in solprop. The optmat adapter and material identities -follow [SEP 3](archive/sep-0003-optmat-materials.md); no cross-section table is copied +follow [SEP 3](https://github.com/LupoLab/solprop/blob/main/docs/dev/seps/archive/sep-0003-optmat-materials.md); no cross-section table is copied into solprop. These APIs must be present in the optmat version pinned for implementation; the current optmat floor is not evidence that all of them are installed. @@ -879,7 +879,7 @@ Part I above. The revised Part I was reviewed on 2026-10-12 (the last section). of the Drude current. That factor also applies to the existing field-grid plasma path, independently of this SEP. The drafting-agent field now names the review revisions' agent. Part I is unchanged. -- 2026-11-02: [SEP 43](archive/sep-0043-retire-numba-cpu.md) retired `numba_cpu` (ADR-064). Part I stays +- 2026-11-02: [SEP 43](https://github.com/LupoLab/solprop/blob/main/docs/dev/seps/archive/sep-0043-retire-numba-cpu.md) retired `numba_cpu` (ADR-064). Part I stays as accepted; its Numba phase falls away, and the feature goes on `numpy_ref` and the native backend (SEP 0). diff --git a/docs/dev/seps/sep-0032-raman-maxwell-bloch.md b/docs/dev/seps/sep-0032-raman-maxwell-bloch.md index 843c0fa09..5b9909ebc 100644 --- a/docs/dev/seps/sep-0032-raman-maxwell-bloch.md +++ b/docs/dev/seps/sep-0032-raman-maxwell-bloch.md @@ -12,7 +12,7 @@ | **Type** | Feature | | **Created** | 2026-10-22 | | **Resolution** | — | -| **Requires** | [SEP 3](archive/sep-0003-optmat-materials.md) | +| **Requires** | [SEP 3](https://github.com/LupoLab/solprop/blob/main/docs/dev/seps/archive/sep-0003-optmat-materials.md) | | **Supersedes** | — | | **Superseded-by** | — | | **Implementation** | Not started | @@ -839,6 +839,6 @@ No implementation phases have started. compression remains SEP 10. Extraction does not constitute standalone acceptance or a completed standalone review. - 2026-11-01: Tracking issue [#123](https://github.com/LupoLab/solprop/issues/123). -- 2026-11-02: [SEP 43](archive/sep-0043-retire-numba-cpu.md) retired `numba_cpu` (ADR-064). Where this +- 2026-11-02: [SEP 43](https://github.com/LupoLab/solprop/blob/main/docs/dev/seps/archive/sep-0043-retire-numba-cpu.md) retired `numba_cpu` (ADR-064). Where this proposal names Numba or `numba_cpu`, it was written before that: such a phase or check falls away, and the feature goes on `numpy_ref` and the native backend (SEP 0). diff --git a/docs/dev/seps/template.md b/docs/dev/seps/template.md index eeeeaefb9..2fcc7c070 100644 --- a/docs/dev/seps/template.md +++ b/docs/dev/seps/template.md @@ -5,8 +5,8 @@ Copy this file to docs/dev/seps/sep-NNNN-short-slug.md, with the next free numbe the index, and replace every placeholder. Keep the headings: the parts and their order are the same in every SEP. Delete the italic guidance as you write each section. The process is SEP 0 (sep-0000-process.md); read it first. -Add the draft to the SEP index and its toctree, and to the roadmap's Draft enhancement -proposals section after the accepted proposals. Keep these entries current when the scope or status changes; +Add the draft to the SEP index's Open table and its toctree. Keep its row current when the +status changes; work this proposal gives back goes in an issue. Open the SEP's tracking issue (SEP 0) and name it in Part III. --> @@ -105,7 +105,8 @@ differences page.* ### 11. Phases -*The proposed phases, each independently mergeable with a green gate. numpy_ref and the +*The proposed phases, each independently qualified and reported, as commits on the SEP's +one branch (SEP 0 §6, Implementation). numpy_ref and the native CPU build come in either order, each with tests, and the manual page with whichever lands first. For each phase: its deliverables and what it must verify.* @@ -122,13 +123,12 @@ lands first. For each phase: its deliverables and what it must verify.* ## Part II — Implementation record -*One report per phase, appended in the pull request that merges the phase (SEP 0 §8). +*One report per phase, appended on the SEP's branch when the phase is complete (SEP 0 §8). Copy the skeleton below for each phase.* ### Phase 1 report — short title -- **Scope:** phase, date, implementer, branch, merge commits (solprop, and solprop-kokkos - when changed). +- **Scope:** phase, date, implementer, branch and the phase's commits. - **Delivered:** modules, tests and pages added or changed, as paths. - **Deviations from the proposal:** each, with why it was necessary. - **Decisions:** choices the proposal left open, with ADR numbers where one was written. diff --git a/docs/dev/stepper.md b/docs/dev/stepper.md index 0a00b3962..600e3a086 100644 --- a/docs/dev/stepper.md +++ b/docs/dev/stepper.md @@ -31,9 +31,9 @@ backend is validated against what it produces. | 1 | `stage_input` | `u = exp(ΔΦ_i) (y + h Σ_j a_ij k_j) + N₀ exp(i Im Φ(z_i))` | | 2 | `to_time` | zero-pad onto the fine grid and inverse transform every modal column | | 3 | `synthesise` | `E_ip(t) = τ(z) Σ_m S_ip,m a_m(t)` on a chunk of quadrature nodes, in V/m | -| 4 | `nonlinear_polarisation` | `P(t)` from the compiled responses, times the temporal collar | +| 4 | `nonlinear_sources` | the collared local polarisation `P(t)` from the compiled responses and, with field plasma, the ungated plasma current `J(t)`, held separately ([SEP 27](https://github.com/LupoLab/solprop/blob/main/docs/dev/seps/archive/sep-0027-held-plasma-current.md)) | | 5 | `project` | `P_m(t) = Σ_ip W_m,ip P_ip(t) / τ(z)`, accumulated over the chunks | -| 6 | `to_frequency` | forward transform every modal column and crop to the coarse grid | +| 6 | `to_frequency` | forward transform every modal column and crop to the coarse grid; a held current's streams join here (`held_plasma_spectrum`) | | 7 | `stage_output` | `k_i = exp(−ΔΦ_i) p(ω, z) W(ω) P̃` | | 8 | `accumulate` | `acc += b_i k_i`, and the embedded difference into its own accumulator | @@ -122,7 +122,7 @@ output multipliers and is added after: |---|---|---| | `intensity`, `ionisation_rate` | `ionisation_rate` | `W(abs(E))` from the table; `hypot(E_x, E_y)` for two components | | `plasma_scan` | `plasma_scan` | `f = 1 − (1 − f₀) exp(−∫W dt)` and `J_free = (e²/m_e) ∫ f E dt` | -| `plasma_current` | `plasma_current` | `J_loss = I_p W (1 − f) E / abs(E)²`, then `P = ρ ∫ (J_free + J_loss) dt` | +| `plasma_current` | `plasma_total_current` | `J = ρ (J_free + J_loss)` with `J_loss = I_p W (1 − f) E / abs(E)²`, held for pass 6 rather than integrated in time (`plasma_current`'s `P = ρ ∫ J dt` is the oracles' form, `nonlinear_polarisation`) | | `kerr` | `kerr_polarisation` | the two cubic forms of `solprop.translate.responses.KerrCoefficients` | | `dispersive_kerr` | `dispersive_kerr_polarisation` | per polynomial channel, or per symmetric group under its mixture filter, `P = ε₀ γ₀ ρ` times the filtered cubic of `solprop.nonlinear.responses.dispersive_cubic` on the multipliers of `solprop.translate.responses.DispersiveKerrTerms`, `G[w (G E)³]` with the collar `w` inside | | `raman_drive` | `raman_polarisation` | `P = ε₀ ρ E(t) irfft[H̃ · rfft(D)]` on the doubled grid, with `D` the real drive of the grid | @@ -158,7 +158,13 @@ depend on the field. A rule with no embedded pair reports `nan` rather than the difference with itself would give. Measured on a three-mode set: 1.6e-1, 2.1e-2, 4.1e-5, 7.2e-9 and 1.2e-15 at `n_r = 8, 16, 24, 32` and 48. -## 2. Scheme: IP-DOPRI5 (IP-Tsit5 available) +## 2. Schemes: IP-DOPRI5 (IP-Tsit5 available), low-storage RK4IP and the Adams methods + +Each route's default integrator is in `solprop.driver.defaults.ROUTE_DEFAULTS` (SEP 37): +`Multistep()`, the exponential Adams method of *Low-call Adams methods* below, on the +capillary (with or without the TDSE response), radial and planar routes and for settings +built by hand; `RungeKutta()`, the interaction-picture DOPRI5 march of this section's +first part, on the GNLSE, waveguide, slab and Cartesian and line free-space routes. The pairs, their orders and their tableau theory are [algorithms.md §2](algorithms.md#2-the-rungekutta-pairs). The evidence for choosing them: @@ -175,7 +181,7 @@ order conditions are checked for both weight vectors and the propagated solution fifth-order one, and the FSAL stage is not recycled before anything that depends on the completed step (irrelevant without dense output, but tested). -**Who marches** ([SEP 47](seps/archive/sep-0047-run-ownership.md), [SEP 52](seps/archive/sep-0052-backend-shape.md)). +**Who marches** ([SEP 47](https://github.com/LupoLab/solprop/blob/main/docs/dev/seps/archive/sep-0047-run-ownership.md), [SEP 52](https://github.com/LupoLab/solprop/blob/main/docs/dev/seps/archive/sep-0052-backend-shape.md)). The NumPy reference's session schedules its runs and drives its marches in `backends/numpy_ref/`: `HostSession` over `RungeKuttaMarch`, `HostAdamsMarch` and `HostLowStorageMarch`. Every native run is its native session's, whose compiled Runge-Kutta, Adams and low-storage @@ -253,7 +259,7 @@ section takes the section it **closes** in. ### The low-storage march -The design record is [SEP 24](seps/archive/sep-0024-low-storage-interaction-picture-runge-kutta.md). +The design record is [SEP 24](https://github.com/LupoLab/solprop/blob/main/docs/dev/seps/archive/sep-0024-low-storage-interaction-picture-runge-kutta.md). `stepper/low_storage.py` and `backends/low_storage.py` hold a third integrator, `LowStorageRungeKutta()` (ADR-050): classical RK4 in the interaction picture anchored at @@ -277,7 +283,7 @@ replay: each step's trial (`NumpyLowStorage.trial`) overwrites the state, in fli the engine's accept finishes it, and the march moves its position in the same commit (SEP 52 §5.2). The native backend holds no such march in Python: a timing probe's trial is one step of the workspace's own low-storage engine (`Workspace.probe`, which -closes the workspace afterwards, SEP 52 §5.5). The native execution session ([SEP 47](seps/archive/sep-0047-run-ownership.md) section 6.3, +closes the workspace afterwards, SEP 52 §5.5). The native execution session ([SEP 47](https://github.com/LupoLab/solprop/blob/main/docs/dev/seps/archive/sep-0047-run-ownership.md) section 6.3, `solprop_native.session`) owns the loop itself: the native Runge-Kutta march replays the schedule, and each step is one in-place native step whose stage scalars, the table keys of `table_steps` and the flows' increments, the native state forms from its stage @@ -311,9 +317,9 @@ of `prop_capillary`, `prop_free` on a radial grid and `prop_planar` (ADR-037, AD `stepper/runge_kutta.py`'s `RungeKutta` names the tableau's march, the default of `prop_gnlse`, `prop_waveguide` and `prop_free`). `Multistep` is an Adams march with a derivative history, in the exponential formulation -by default ([SEP 16](seps/archive/sep-0016-unified-multistep.md)) and in the interaction +by default ([SEP 16](https://github.com/LupoLab/solprop/blob/main/docs/dev/seps/archive/sep-0016-unified-multistep.md)) and in the interaction picture, transporting the history, on request -([SEP 13](seps/archive/sep-0013-expensive-response-steppers.md)): +([SEP 13](https://github.com/LupoLab/solprop/blob/main/docs/dev/seps/archive/sep-0013-expensive-response-steppers.md)): - one source call per accepted step (PEC); - a corrector one order higher than its predictor; @@ -337,22 +343,27 @@ so that its flow `exp(x)` is the propagator the interaction formulation would ap forms the moments `k! φ_{k+1}(x)` once (`backends/exponential.py`), and applies the predictor, the corrector and the neighbouring orders' defects in the monomial basis of their interpolants (`ExponentialKernels`): the defects are already at the step's end, -so no propagator multiplies them. The defect, the norm's scale and the lifecycle are +so no propagator multiplies them. The moments `φ_0 … φ_{q+2}` are formed for every element by a +scaled Taylor series and doubling for `|x| ≤ 3` and an upward recurrence beyond, so no +per-node weight array is formed; checked against augmented matrix exponentials and +quadrature, each is within a few hundred ulp of its scale, so no term for them enters the +error norm. The defect, the norm's scale and the lifecycle are the transported formulation's; so is the order choice, but for the in-stage collar's stability, which it weighs (`adams_core.order_weight`): each order's step factor is capped at `COLLAR_STABILITY` times PEC's negative-real interval over `h max(α) / 2`, the step itself left to the chosen order's defect. **Beside a coupled flow** (ADR-044) the workspace's `coupled_block` returns the frozen block of the step's -section (`CoupledBlock`); `coupled_moments` forms the trial's flow and moments as -matrix functions of `(ΔΦ/h) I + G_s` on the block's bins, `CoupledExponentialKernels` -applies them -- on the native backend in its kernels, which -take the matrix functions from the flow actions' eigenbasis (`CoupledBlock.basis`; -`numpy_ref` keeps the augmented exponential as the reference) -- and a frozen-residual section's residual joins the +section (`CoupledBlock`); `coupled_moments` forms the trial's flow and moments +(`MatrixMoments`) as matrix functions of `(ΔΦ/h) I + G_s` on the block's bins, and +`ExponentialKernels` applies them -- on the native backend in its kernels, which +take the matrix functions from the flow actions' eigenbasis +(`solprop.translate.coupled.schur_eigenbasis`; `numpy_ref` keeps the augmented +exponential as the reference) -- and a frozen-residual section's residual joins the compensation below, formed from each sample's flow weights against the step's own section. The lab-frame source runs without the flow's pipeline on every backend. The interaction formulation is refused by name (`backends.exponential.refuse_adams`). -**The carrier frame** ([SEP 35](seps/archive/sep-0035-carrier-frame-exponential-adams.md), +**The carrier frame** ([SEP 35](https://github.com/LupoLab/solprop/blob/main/docs/dev/seps/archive/sep-0035-carrier-frame-exponential-adams.md), `Multistep.carrier_frame`, opt-in) changes what an exponential trial interpolates and nothing it stores. `HostHistory` holds the run's `CarrierReference` (`backends.exponential.carrier_reference`: the active bin nearest the grids' `omega0`, @@ -392,32 +403,34 @@ structurally absent source (`source_absent`) takes the chord alone. **The engine** (ADR-043): the march keeps the controller -- the stencil, the orders, rejection, restarts, the budget and the ledger -- and hands every -state-sized operation of the fused and exponential paths to an `AdamsEngine`: the -startup sample, a trial's predictor, source, corrector and scored norms (held until the -decision), the adoption and transport of an accepted step, holding the accepted state -across a dense observation, and the observation. `HostHistory` is the host engine, -whose passes are the kernels above; a backend may return its own from the hook -`_adams_engine`, as `native` does to keep the history resident in its -native state, always -- beside a coupled flow too, whose block functions, coupled predictor, +state-sized operation of the fused and exponential paths to an `AdamsEngine` +(`backends/engines.py`, the Python statement of native's `march::Engine`): the startup +sample, a trial's predictor, source, corrector and scored norms (held until the +decision), and the adoption and transport of an accepted step. The dense hold and +observation and the snapshot rows are the session's (`backends/numpy_ref/dense.py` on +the reference); no engine holds, restores or observes (the commit contract of +`backends/engines.py`). `HostHistory` is the reference's engine, whose passes are the +kernels above; native's compiled Adams march runs on its own resident engine, which keeps +the history resident in its native state, always -- beside a coupled flow too, whose block functions, coupled predictor, corrector, carry and defect norms are native passes over its resident eigenbasis, a frozen-residual flow's generator applied once per sample. -**The native Runge–Kutta march** (ADR-069, [SEP 45](seps/archive/sep-0045-native-rk-march.md)): +**The native Runge–Kutta march** (ADR-069, [SEP 45](https://github.com/LupoLab/solprop/blob/main/docs/dev/seps/archive/sep-0045-native-rk-march.md)): `RungeKuttaMarch.march_to`'s decisions are pure functions of a `RungeKuttaPolicy` (`backends/rk_core.py`), held to a decision corpus recorded before the refactor (`tests/data/rk_traces.json.gz`), and `native` executes them (`native/src/march/rk_march.cpp`) on its staged trial and native norm, a call of attempts at a time, returning only at a host event and taking the boundary checks itself; the kernel contract's section 12 is the -interface. It covers interpolated planes (the step across a plane returns to solprop, which -holds its extension; in SEP 47's native session the march holds it through its engine, -`rk::Engine::extend`, finishes the step itself and the session observes the plane where the -state lives, `native/src/march/dense.cpp`), a replayed schedule, a coupled flow (its guards transcribed), a z table -the transverse edge (read on the host, as the Adams march reads it) and a weighted norm +interface. It covers interpolated planes (the march holds the crossing step's extension through its +engine, `rk::Engine::extend`, finishes the step itself, and the native session observes the +plane where the state lives, `native/src/march/dense.cpp`), a replayed schedule, a coupled +flow (its guards transcribed), a z table, the transverse edge (read by the native session +where the march returns to it, as for the Adams march) and a weighted norm (reduced natively in both loops), on CPU and device builds alike. `PIController` is final (ADR-077): defining a subclass raises `StepperError`, so its decisions and its norm are the only ones either backend takes. -**The policy and the native march** (ADR-060, [SEP 39](seps/archive/sep-0039-native-adams-march.md)): +**The policy and the native march** (ADR-060, [SEP 39](https://github.com/LupoLab/solprop/blob/main/docs/dev/seps/archive/sep-0039-native-adams-march.md)): every number the controller reads -- the order and its variability, the safety and growth factors, the restart and hysteresis constants, the collar's and the carrier's caps, the budget, the floor and ceiling, the landings and the run's end -- is one @@ -429,7 +442,7 @@ executes `Multistep()` in either formulation and replayed schedules from that re native session (`native/src/session/session.cpp`) only at an event: the target reached or crossed, an accepted step on which the session has work (a statistics row, a natural stop), a boundary check whose verdict the session gives, the call's bound, the budget, the floor or a native error. The march takes the -boundary monitor's checks itself ([SEP 45](seps/archive/sep-0045-native-rk-march.md) §4.8), +boundary monitor's checks itself ([SEP 45](https://github.com/LupoLab/solprop/blob/main/docs/dev/seps/archive/sep-0045-native-rk-march.md) §4.8), buffers their readings and predicts the monitor's verdict; a run with a transverse edge keeps returning at each check. The run's stop flag is polled before each call and a signal's handler runs after it, so the call's bound, 256 attempts or 0.1 s, is @@ -469,7 +482,7 @@ only at an accepted position with nothing ahead of it. the Runge–Kutta replay records it; a hard kink on an edge restarts the history. The derivation, the stability limits and the measured comparison are in -[SEP 13](seps/archive/sep-0013-expensive-response-steppers.md) and on the manual page +[SEP 13](https://github.com/LupoLab/solprop/blob/main/docs/dev/seps/archive/sep-0013-expensive-response-steppers.md) and on the manual page `docs/guide/numerics/adams.md`. Two differences from the Runge–Kutta march are deliberate: @@ -483,7 +496,11 @@ deliberate: The norm, the PI controller, landing and the equivalent norm are defined in [algorithms.md §3](algorithms.md#3-step-control); this section is the design choices and -the measurements behind them. +the measurements behind them. The error estimate and the PI controller below are the +Runge–Kutta march's (`RungeKutta()`); the Adams march scores its own defect and takes the +factor `safety · norm^(−1/(order+1))` of the order it chose, capped by its own +`max_growth` (default 2) and floored by `min_factor` (`factor` in `backends/adams_core.py`; +*Low-call Adams methods* above). The landings, the floor and the stretch are shared. - **Error estimate**: the embedded pair, order 4, observed order 4.03 (DOPRI5) / 3.99 (Tsit5) against the analytic local error in the prototype study, and 4.02 / 4.03 on solprop's own @@ -516,7 +533,7 @@ the measurements behind them. buys 2.4–22.7× better error, so it is neutral to favourable on efficiency. On the CPU the default is lag 1 with rejection allowed. The same controller is used on devices; `reject_free=True` is an explicit option, not a backend-selected default. -- **Start-up rule** (`auto_init`, [SEP 14](seps/archive/sep-0014-stepper-efficiency.md)): the first step is `dz_init`, a guess (the +- **Start-up rule** (`auto_init`, [SEP 14](https://github.com/LupoLab/solprop/blob/main/docs/dev/seps/archive/sep-0014-stepper-efficiency.md)): the first step is `dz_init`, a guess (the convenience interfaces' `1e-4` of the length); the step after it is the deadbeat step its own scaled norm implies, `safety · norm^(−1/(q+1))`, at most 100 times the first (`PIController.start_factor`), and the history is given the norm the first step would @@ -544,14 +561,15 @@ the measurements behind them. Landing on genuine kinks matters for splitting schemes (order 2.8 vs 6.3) and is harmless for IP-RK; landing on save planes replaces dense output (ADR-009) unless `interpolate_planes=True` asks for DOPRI5's continuous extension (ADR-039): then the save planes leave the landing targets, the accepted step that - crosses a plane is contracted into its five extension coefficients (driver hook - `_dense_stages`), and the plane is evaluated and carried there by the exact flow while + crosses a plane is contracted into its five extension coefficients + (`solprop.stepper.tableau.extension_coefficients`, applied by the engine's `extend`), + and the plane is evaluated and carried there by the exact flow while the march's own state is held ahead. A session keeps the two positions apart: a snapshot latched while a plane's field is held waits for the next accepted endpoint, every plane its step crossed observed first -- the end of that step itself when the next plane lies beyond it, since with planes closer than the steps every later step crosses another plane -- so a checkpoint never needs the extension to reconstruct a - plane ([SEP 47](seps/archive/sep-0047-run-ownership.md) section 5.5). After an observation + plane ([SEP 47](https://github.com/LupoLab/solprop/blob/main/docs/dev/seps/archive/sep-0047-run-ownership.md) section 5.5). After an observation the next step evaluates its first stage afresh rather than recycle the crossing step's last (FSAL), in the native session as on the host: a recycled stage once parted the two by up to 9e-8 in a norm, and by 2e-10 in the positions after it, under some FFT @@ -767,7 +785,7 @@ estimated (replayed schedule)" where a ratio would stand. **What a replay reproduces.** A replay is required to meet the overall accuracy target of the run it replays, not to reproduce its bits or every adaptive decision -([SEP 25](seps/archive/sep-0025-rounding-level-reproducibility.md)). `FixedSchedule` stores +([SEP 25](https://github.com/LupoLab/solprop/blob/main/docs/dev/seps/archive/sep-0025-rounding-level-reproducibility.md)). `FixedSchedule` stores step lengths and a start position, nothing more. The Runge–Kutta replay takes those steps with the same fixed-order method; the Adams replay does not repeat the original computation: `HostAdamsMarch._replay_to` chooses its orders afresh, by the adaptive rule from @@ -783,11 +801,13 @@ Recording and replaying every adaptive decision is not provided. ## 9. Open numerical questions -The solver's open questions — error norms for weak observables, reject-free efficiency at -matched error, schedule transfer, round-off growth with varying operators, save-plane -density and FSAL through a coupled flow — are listed with the others under -[numerical methods](open-questions.md#numerical-methods) in the open questions. None -blocks the current solver. +The solver's open questions are issues: error norms for weak observables +([#259](https://github.com/LupoLab/solprop/issues/259)), reject-free efficiency at +matched error ([#260](https://github.com/LupoLab/solprop/issues/260)), schedule transfer +([#261](https://github.com/LupoLab/solprop/issues/261)), round-off growth with varying +operators ([#262](https://github.com/LupoLab/solprop/issues/262)), save-plane density +([#263](https://github.com/LupoLab/solprop/issues/263)) and FSAL through a coupled flow +([#264](https://github.com/LupoLab/solprop/issues/264)). None blocks the current solver. ## 10. Traps (each silent, each measured) @@ -815,7 +835,7 @@ blocks the current solver. | rung | problem | truth | asserts | |---|---|---|---| | P0 | linear only, nasty D(ω, z) (pressure step, taper, absorbing edge) | `quad_vec` per ω to machine precision | Φ table 1e-14; right-endpoint rule reproduces `(h/2)ΔD` as a regression witness | -| P1 | N-soliton recurrence, constant D, N = 3…8 | analytic, phase-resolved | observed order 5 above the floor; phase `π/4`; error at ×4 steps ~1e-10 | +| P1 | N-soliton recurrence, constant D, N = 3 and 6 (`tests/backends/test_numpy_ref_soliton.py`) | analytic, phase-resolved | observed order 5 above the floor; phase `π/4`; error at ×4 steps ~1e-10 | | P2 | N-soliton with arbitrary z-varying d(z) and α(z), γ = d·e^Γ | analytic | dissipative, z-varying, exact; step-function α (P2b); out-of-band absorber (P2a) | | P3 | full UPPE: Kerr → shock → plasma → Raman; RDW parameters | three-level Richardson with order gate; cross-scheme reference | efficiency at matched error; weak-bin metric | | targets | RDW VUV 4-mode gradient; CtC H₂ 6-mode | stored Luna results and solprop's own converged references | regression within stated tolerance; convergence ladder | diff --git a/docs/dev/structure.md b/docs/dev/structure.md index 6a769e13b..193c38882 100644 --- a/docs/dev/structure.md +++ b/docs/dev/structure.md @@ -51,10 +51,10 @@ layer that owns it. The annotations between them are [architecture.md §5](architecture.md)'s own. The thing to notice is where the boundary falls: the service loop serves a session's events, while the session runs the step loop (the reference's `HostSession` over its Python marches, or native's session over its -compiled ones, [SEP 47](seps/archive/sep-0047-run-ownership.md), [SEP 52](seps/archive/sep-0052-backend-shape.md)). Reference passes, compiled kernels and library transforms, +compiled ones, [SEP 47](https://github.com/LupoLab/solprop/blob/main/docs/dev/seps/archive/sep-0047-run-ownership.md), [SEP 52](https://github.com/LupoLab/solprop/blob/main/docs/dev/seps/archive/sep-0052-backend-shape.md)). Reference passes, compiled kernels and library transforms, or one native trial do the numerical work behind that loop. -![One run of solprop, from prop_capillary through the kernel problem and the step driver to a saved plane](figures/one_run.svg) +![One run of solprop, from prop_capillary through the kernel problem and the backend's session to a saved plane](figures/one_run.svg) Text: [architecture.md §5](architecture.md). The seam itself is figure 5. @@ -67,10 +67,10 @@ at the bottom is the one thing about the contract that is not a field — Φ and prefactor each take one of four representations, and `device_ready` is a predicate over the pair. -![The eight sections of the kernel contract, what feeds each of them and what a backend does with each](figures/kernel_contract.svg) +![Sections 1 to 8 of the kernel contract, what feeds each of them and what a backend does with each](figures/kernel_contract.svg) Text: [kernel-contract.md §1](kernel-contract.md) to §8, the split in -[kernel-contract.md §3](kernel-contract.md) and +[kernel-contract.md §1](kernel-contract.md#1-identity-and-validation) and [backends.md §1](backends.md). ## 4. One stage @@ -89,16 +89,17 @@ Text: [architecture.md §8](architecture.md) for the passes, ## 5. The backends -The seam at the top is the whole of what a backend is. Under it is the step loop no -backend reimplements — the march, the replay, the landing, the controller, the history, -the noise and the per-stage bundle all live in the reference's session and marches, -`backends/numpy_ref/`, while the native backend's session marches natively -([SEP 47](seps/archive/sep-0047-run-ownership.md)) — and under that the -implemented backends: NumPy reference and native (built from `native/`). Each -supplies trial/state operations and the relevant hooks; the loop's -statistics channel and progress reporter call back through the seam. - -![The backend seam, the shared step driver, and the implemented backends](figures/backends.svg) +The seam at the top is the whole of what a backend is. Under it each backend runs its own +session and marches — the march, the replay, the landing, the controller, the history, +the noise and the per-stage bundle: the reference's in Python in `backends/numpy_ref/`, the +native backend's compiled ([SEP 47](https://github.com/LupoLab/solprop/blob/main/docs/dev/seps/archive/sep-0047-run-ownership.md), +[SEP 52](https://github.com/LupoLab/solprop/blob/main/docs/dev/seps/archive/sep-0052-backend-shape.md)), held to the same decisions by the shared +controller cores and run records of `solprop.backends` — and under that the +implemented backends: NumPy reference and native (built from `native/`). Each session +keeps its statistics rows between events and hands them, with its events, to the service +loop through the seam. + +![The backend seam, each backend's session and marches, and the implemented backends](figures/backends.svg) Text: [backends.md §1](backends.md) for the seam and the three things a backend owes, [backends.md §2–4](backends.md) for the implementations, and diff --git a/docs/dev/testing.md b/docs/dev/testing.md index e5389a695..ae7b44937 100644 --- a/docs/dev/testing.md +++ b/docs/dev/testing.md @@ -1,20 +1,22 @@ # Testing -All code is tested, to 100 % of statements and branches (the coverage lane fails below -it), in lanes, with several kinds of test -per feature (ADR-022). This page fixes the taxonomy, the lanes, the reference problems, the +solprop's package is tested to 100 % of statements and branches (the coverage lane fails +below it), and so are the front end's modules outside its Qt layer (`gui/pyproject.toml` +omits `ui/`, `views/`, `app.py`, `__main__.py` and `askpass.py`); the native package has +no coverage gate, only a weekly report of its C++ source coverage (`native-deep.yml`). +Tests run in lanes, with several kinds of test per feature (ADR-022). This page fixes the taxonomy, the lanes, the reference problems, the tolerance policy and the layout. `AGENTS.md` carries the short rules; this is the long form. ## Documentation-only changes -Adding or editing a SEP, its index or roadmap entry, or making other documentation-only +Adding or editing a SEP or its index, or making other documentation-only changes does **not** require `uv run poe check`, the full test suite, `uv run poe test-slow` or `uv run poe cov` before completion, commit or merge. This includes prose, links, documentation assets, contributor instructions and prose-only docstring edits. Select checks that cover what changed: - Run `git diff --check` and `uv run codespell <changed-files>`. -- For SEP content, status, index or roadmap entries, run `uv run pytest tests/test_seps.py`. +- For SEP content, status or index entries, run `uv run pytest tests/test_seps.py`. - For Sphinx content, links or assets, run `uv run poe docs` (warnings remain errors). - For docstring prose, run the relevant docstring validation and documentation build. @@ -39,7 +41,7 @@ do not launch the full suite merely because a SEP is being committed or merged. | reference problem | the ladder in [stepper.md §11](stepper.md#11-verification-ladder-for-solprops-solver-tests): P0 linear, P1 N-soliton with phase, P2 analytic z-varying loss and dispersion, P3 cross-scheme Richardson | solver work | | target simulation | RDW VUV and CtC against solprop's own converged references, and their inputs and plasma against stored Luna results (§8) | the named problems M2, M3, M4 | | doctest | every `Examples` section runs | all docstrings | -| smoke | import time budget; a run of every gallery example in reduced size | package, docs | +| smoke | the top-level import loads no heavy module; a gallery script that an example recipe mirrors builds the recipe's simulation, up to its first run (`tests/recipe/test_examples.py`); CI's docs job executes every lesson and tutorial at full size, and the worked examples run only by hand | package, docs | ## 2. Tiers and lanes @@ -78,16 +80,16 @@ instead of a tier marker: | lane | command | what it selects | |---|---|---| -| default | `uv run poe test` | fast **and** medium, compiled kernels, random order (`pytest-randomly`), warnings as errors, doctests included, under xdist with every thread pool at one thread per worker. Step 8 of `poe check`. Plain `uv run pytest` runs the same selection serially (`addopts` carries no `-n`), for one file or test and for debugging. | +| default | `uv run poe test` | fast **and** medium, compiled kernels, random order (`pytest-randomly`), warnings as errors, doctests included, under xdist with every thread pool at one thread per worker. The `test` step of `poe check`. Plain `uv run pytest` runs the same selection serially (`addopts` carries no `-n`), for one file or test and for debugging. | | medium alone | `uv run poe test-medium` | the medium tier, timed against its budget | | slow | `uv run poe test-slow` | the slow tier under xdist, one worker per core, `--dist loadgroup`, every thread pool pinned to one thread per worker | -| coverage | `uv run poe cov` | the fast and medium tiers under xdist with one thread per worker; 100 % of the package (`coverage-cpu.ini`) | +| coverage | `uv run poe cov` | the fast and medium tiers under xdist with one thread per worker; 100 % of the package (`[tool.coverage]` in `pyproject.toml`) | | gpu | `uv run poe test-gpu` | the `gpu`-marked tests of solprop and of solprop-native, against an installed CUDA or HIP build that sees a device; it fails on a CPU build rather than skipping every test | | benchmark | by hand, per docstring; `uv run poe bench` for `benchmarks/` | see [benchmarks.md](benchmarks.md) | Hypothesis properties use the `solprop` profile loaded by `tests/conftest.py`. Their example count bounds the work; the per-example wall-clock deadline is disabled -because imports, JIT compilation and contention on shared machines can exceed it +because imports and contention on shared machines can exceed it without indicating a correctness failure. Parallel lanes use `--dist loadgroup`. The collection hook groups a test with its @@ -153,34 +155,29 @@ For native development, a plain `uv sync` builds `native/` and installs it editable into the repository's environment before a lane runs; how, and when a build must be rebuilt, is [Building the native backend](../guide/performance/building-native.md#a-development-build). -`uv run poe check-native` runs the native package's own gate and `uv run poe check-all` -both gates. What the backend does not support it refuses by name +`uv run poe check-native` runs the native package's own gate, and a native change runs it +after `uv run poe check` ([tooling](tooling.md#the-gate-uv-run-poe-check)). What the +backend does not support it refuses by name ([backends.md](backends.md)). The `gpu` lane checks build coherence, one complete device step and same-card repeats within a rounding bound on an accelerator build; host thread-count tests skip on a device build by design, and fixed-geometry same-card repeats stand in for them. The slow equivalence and M2/CtC witnesses are selected by node id so one marker remains one tier. With the build -installed, the lanes run as: +installed, the lanes' poe tasks hold every thread pool, the native one included, at one +thread per worker, since eighteen xdist workers each initialising an eighteen-thread +Kokkos pool would oversubscribe the machine. The full gate, slow and coverage lanes run in +CI on the pull request, not locally (`AGENTS.md`, "Definition of done"). On an +accelerator build (the task sets `SOLPROP_TEST_BACKEND=native`): ```console -SOLPROP_NATIVE_THREADS=1 OMP_PROC_BIND=false uv run poe check -SOLPROP_NATIVE_THREADS=1 OMP_PROC_BIND=false uv run poe test-slow -SOLPROP_NATIVE_THREADS=1 OMP_PROC_BIND=false uv run poe cov -SOLPROP_TEST_BACKEND=native SOLPROP_NATIVE_THREADS=1 uv run poe test-slow - -# On an accelerator build (the task sets SOLPROP_TEST_BACKEND=native): uv run poe test-gpu ``` -The two thread settings matter: eighteen xdist workers each initialising an -eighteen-thread Kokkos pool oversubscribe the machine, and OpenMP binding pins each -worker's threads to the same first cores. - ### Shared code and out-of-process providers Parity between the backends checks what each computes independently. It cannot check code both call: a defect in the TDSE response's source assembly -(`solprop.backends.tdse_source`, [SEP 49](seps/archive/sep-0049-tdse-on-native.md)) is the same +(`solprop.backends.tdse_source`, [SEP 49](https://github.com/LupoLab/solprop/blob/main/docs/dev/seps/archive/sep-0049-tdse-on-native.md)) is the same on both. That module's tests state their expectations independently of it, analytic or manufactured (`tests/backends/test_tdse_source.py`, `tests/edge_source_cases.py`), and a deliberate defect in each term is shown to fail one of them; parity then covers what each @@ -196,7 +193,7 @@ Pyroraptor is not tested in CI; it is checked by hand (SEP 49, section 7.4). Step control, the session lifecycle and the service loop are tested with their numerical outcomes scripted, never by substituting the code under test. A scripted engine replaces -the engine under the real march and the real session ([SEP 52](seps/archive/sep-0052-backend-shape.md) +the engine under the real march and the real session ([SEP 52](https://github.com/LupoLab/solprop/blob/main/docs/dev/seps/archive/sep-0052-backend-shape.md) §6.3), as native's scripted engines test its compiled marches: - `tests/scripted_driver.py`'s `HostScriptedDriver` is the reference backend whose @@ -245,9 +242,7 @@ tier's total, the sum of its tests' times over the lane's shards, is held to a r `max_total` in `tests/tier_budget.toml`, which may only go down. Lower it when medium tests are trimmed or moved to slow; never raise it to let a change through. It was reset once, when the first baseline turned out to be one low run (#792). Time a new medium test -(`uv run pytest <file> --durations=0`) before adding it. Most of the default lane's time is the compiled-kernel tests, which -compile one kernel per parametrisation, so parametrise a compiled test only over what the -kernel actually branches on. +(`uv run pytest <file> --durations=0`) before adding it. The budgets are read from the lanes' JUnit reports. The collection hook in `tests/conftest.py` writes each test's tier into its report as the property `tier` @@ -284,7 +279,7 @@ rounding budget (Higham's `γ_n` bound for a reduction of length `n`, the transf `B_fft`, operation counts per step, with a stated margin); discretisation error of the grid or step; the accuracy of a reference (a table's stated accuracy, an experimental figure, a Luna result's own convergence). Independent floating-point computations are compared by -numerical error, never by bits ([SEP 25](seps/archive/sep-0025-rounding-level-reproducibility.md)): +numerical error, never by bits ([SEP 25](https://github.com/LupoLab/solprop/blob/main/docs/dev/seps/archive/sep-0025-rounding-level-reproducibility.md)): no comparison requires bitwise agreement across backends, builds, machines, thread counts, scan execution or repeated runs. Every comparison belongs to one of five classes, and `tests/bounds.py` holds the reusable parts of their bounds. @@ -312,6 +307,16 @@ the observed margin. A result that is mathematically zero but reached through in arithmetic gets a justified absolute tolerance; a zero that is a structural contract (a hard mask, a disabled term) stays exact. +**No default absolute tolerance.** Many of the suite's quantities are SI values far below +pytest's default absolute tolerance of 1e-12 or NumPy's 1e-8 (times of 1e-15 s, nonlinear +indices of 1e-25 m²/W), which would accept any result for them. So in the suite +`pytest.approx` has no absolute tolerance unless the test gives `abs=`, whether it gives +`rel=` or compares with a nonzero number bare (the test conftests wrap it; a bare +`approx` of zero or of a sequence keeps pytest's defaults), and every `np.allclose` or +`np.isclose` states its `atol`, 0.0 for a relative comparison +(`tests/test_tolerance_defaults.py` checks). A test that needs an absolute tolerance, an +expected zero among them, gives it explicitly. + **Accuracy envelopes** (class T) are set per case, in a comment: the run's error against a reference at a tighter tolerance, or against an existing stored converged reference, times a safety factor fixed before the candidate is measured (`AccuracyEnvelope`). Each @@ -359,7 +364,7 @@ reproducible. **Fixtures and the defaults.** Most tests pass `noise=None`, so that a run compares deterministically; noise is tested where it is the subject. Some pin the time-window -geometry of before [SEP 21](seps/archive/sep-0021-absorbing-boundaries.md) through +geometry of before [SEP 21](https://github.com/LupoLab/solprop/blob/main/docs/dev/seps/archive/sep-0021-absorbing-boundaries.md) through `tests/legacy_geometry.py` (`LEGACY_GRID`, `bare_absorber`). Pin it only where a stored measurement depends on it (a convergence record, a Luna witness, a frozen cross-backend comparison) and say which in a comment: it is the one compatibility option solprop keeps @@ -429,6 +434,11 @@ these records. The mechanism (`tests/convergence_records.py`), how a record is compared or written, the tolerance each column carries and the commands are in [accuracy.md, "Regenerating the numbers"](accuracy.md#9-regenerating-the-numbers). +Each record names the commit it was written at, and a test requires that commit to be in +the repository's history. A pull request that regenerates a record is therefore merged +with a merge commit, never squashed or rebased: squashing discards the recorded commit +and the test then fails on `main`. + ## 6. Layout and naming `tests/` mirrors `src/solprop/` (`tests/modes/test_capillary.py` ↔ `solprop/modes/capillary.py`); @@ -469,7 +479,7 @@ parity case is a row, not a new ladder. Two tests read the documentation rather than the package: `tests/test_guide_snippets.py` runs the user guide's code, and `tests/test_seps.py` keeps each enhancement proposal's -header, folder, index row and roadmap link consistent with its status +header, folder and index row consistent with its status ([SEP 0](seps/sep-0000-process.md)). ## 7. Definition of done for a pull request @@ -505,5 +515,5 @@ Tests, records and benchmarks refer to these by name. | **P0–P3** | the solver's verification ladder: linear only (P0), N-soliton recurrence with phase (P1), analytic z-varying loss and dispersion (P2), full UPPE against a Richardson reference (P3); see [stepper.md](stepper.md) §11 | | **M1** | N = 6 soliton recurrence through `prop_gnlse`: GNLSE, envelope grid, mode-averaged, checked against the analytic solution with its phase | | **M2**, **RDW** | resonant dispersive-wave emission into the VUV in a hollow capillary: 125 µm core radius, 1.5 m, helium from 0.8 bar to vacuum, four HE₁ₘ modes, a 7.5 fs 275 µJ pulse, field grid, Kerr and plasma; full and reduced sizes, against solprop's own converged reference, with its inputs against a stored Luna witness ([accuracy.md](accuracy.md) §5) | -| **M3** | the M2 case on a compiled backend (`numba_cpu` when it was recorded): against `numpy_ref` at equal achieved error; the whole-run benchmark rows | +| **M3** | the M2 case on native: against `numpy_ref` at equal achieved error; the whole-run benchmark rows | | **M4**, **CtC** | the comb-to-continuum supercontinuum: 16 µm core radius, 0.2 m of hydrogen at 40 bar, six HE₁ₘ modes, a 400 fs pulse at 515 nm on a 4 ps field grid, Raman and plasma; full and reduced sizes, with the reduced case's inputs and plasma against a stored Luna witness ([accuracy.md](accuracy.md) §6) | diff --git a/docs/dev/tooling.md b/docs/dev/tooling.md index d52aab779..df2b88979 100644 --- a/docs/dev/tooling.md +++ b/docs/dev/tooling.md @@ -14,7 +14,7 @@ this page is out of date. first tag); there is no version string to edit. - The target-specific native backend, `solprop-native`, is the repository's second distribution, built from `native/`, and a required dependency. The root is a uv workspace - with `native/` as its member and one `uv.lock`; `hatch_build.py` pins `solprop-native` to + with `native/` and `gui/` as its members and one `uv.lock`; `hatch_build.py` pins `solprop-native` to solprop's own version in the built metadata, and both take that version from the repository's tags. A plain `uv sync` builds and installs it editable. It removes a hand-installed Pyroraptor @@ -41,23 +41,30 @@ Runs, in order: `ruff check --fix .` → `ruff format .` → `ruff check .` → `numpydoc lint` (on `src/solprop` and the figure scripts) → `codespell` → `reuse lint` → `poe changelog-check` → `poe size-check` → `poe test` (fast and medium tiers, doctests included, under xdist) → -`sphinx-build -b html -W -n --keep-going docs docs/_build/html`. CI runs exactly the same -sequence plus `poe test-slow` and the CPU coverage lane; keep the two identical. +`sphinx-build -b html -W -n --keep-going docs docs/_build/html`. CI runs the same checks, +split across jobs ([CI](#ci)): **static** runs their non-mutating forms (`ruff check .`, +`ruff format --check .`) and adds `uv lock --check`; the default lane runs as **test** +and **coverage** shards; **docs** runs `poe docs` and executes the lessons and tutorials +again. It also runs `poe test-slow` and the other lanes listed there. A check added to +or removed from `poe check` is added to or removed from its CI job in the same commit. Other tasks: `poe test-medium` (the medium tier alone, timed against its budget), `poe test-slow`, `poe cov` (the default lane with coverage), `poe test-gpu` (the GPU lane, on a CUDA or HIP build with a device), `poe bench` (the benchmark plan in `benchmarks/`; `track` runs it on a quiet machine; -[manual](benchmarking.md)), `poe docs`, `poe docs-clean`, `poe figures` (redraw the -committed structure and geometry SVGs) and `poe docs-examples` (execute the stale +[manual](benchmarking.md)), `poe docs`, `poe docs-clean` (remove the untracked build +output, `docs/_build` and `docs/api/generated`; the committed gallery pages stay), +`poe figures` (redraw the +committed structure, geometry and primer figures) and `poe docs-examples` (execute the stale gallery scripts and refresh their committed output). The native package has a gate of its own, `uv run poe check-native` (`native/scripts/check.sh`, bash, so Linux and macOS): its ruff and strict pyright, clang-format, clang-tidy, the native tests, ASan and UBSan, its pytest suite on an -editable build, and the distribution wheel's build and isolated smoke test. `uv run poe -check-all` runs `check` and then `check-native`; a change that touches `native/` runs it. -Its rules are in `native/AGENTS.md`. +editable build, and the distribution wheel's build and isolated smoke test. A change that +touches `native/` runs `check` and `check-native`, and follows `native/AGENTS.md`. +`uv run poe check-all` runs three gates, `check`, `check-native` and the front end's +`check-gui`, so it needs `uv sync --extra gui --group gui-test`. ## ruff @@ -83,7 +90,7 @@ drop them too and allow `print` and cell-style imports; benchmarks allow `print` ## basedpyright -`include = ["src", "tests"]` without the oracles, `typeCheckingMode = "standard"` (strict once the baseline is +`include = ["src", "tests", "benchmarks", "tools"]` without the oracles, `typeCheckingMode = "standard"` (strict once the baseline is clean), `pythonVersion = "3.14"`, `failOnWarnings = true`, `reportMissingTypeStubs = false` because some dependencies ship no stubs (narrow ignores are still preferred over broad ones); `scipy-stubs` supplies SciPy's. The checker is pinned to an exact version and @@ -108,13 +115,11 @@ format refuses those properties under the suite's warnings-as-errors policy. ## coverage -One configuration: `coverage-cpu.ini` (`source = solprop`, `branch = True`) for -`poe cov`, one pass of the default lane; in CI, `poe cov-part` per shard and -`poe cov-report`, which combines them. -The `[tool.coverage]` tables in `pyproject.toml` are the shared defaults. The lane requires -100 % of statements and branches of the whole package -(`fail_under = 100`); -`# pragma: no cover` requires a reason on the same line. +One configuration, the `[tool.coverage]` tables in `pyproject.toml` (`source = ["solprop"]`, +`branch = true`), for `poe cov`, one pass of the default lane; in CI, `poe cov-part` per +shard and `poe cov-report`, which combines them. The lane requires 100 % of statements +and branches of the whole package (`fail_under = 100`); `# pragma: no cover` requires a +reason on the same line. ## numpydoc validation @@ -172,7 +177,7 @@ Python oracle for every result, and end-to-end runs as the measure of speed. | clang-tidy (pinned 23.1.4), whole families | adopted | `bugprone`, `performance`, `modernize`, `misc`, `readability`, `clang-analyzer` and `cppcoreguidelines-special-member-functions`, each exclusion stated in `native/.clang-tidy`; warnings are errors; the tidy stage; `poe tidy-native` for changed files | | compiler warnings | adopted | `-Wall -Wextra -Wpedantic -Wconversion -Wsign-conversion -Wshadow -Wundef -Wnon-virtual-dtor -Woverloaded-virtual`, with Clang's `-Wimplicit-fallthrough` and GCC's `-Wduplicated-cond -Wduplicated-branches -Wlogical-op`; errors in development and CI builds | | ASan + UBSan with Kokkos bounds checks | adopted | the `cpu-sanitize` preset over the GoogleTest suite, UBSan stopping at its first report | -| compute-sanitizer (memcheck, racecheck, initcheck, synccheck) | adopted | `.github/workflows/cuda.yml`, on a device | +| compute-sanitizer (memcheck, racecheck, initcheck, synccheck) | ad hoc | `.github/workflows/cuda.yml`, dispatched by hand: it needs a self-hosted runner labelled `nvidia-gpu`, and is part of no gate | | Clang source coverage | scheduled | `.github/workflows/native-deep.yml`, weekly: GoogleTest and native pytest, a report whose zero-count lines are the dead-code candidates | | ASan + UBSan on the extension | scheduled | `native-deep.yml`: the native pytest suite through the bindings | | `misc-include-cleaner` | scheduled | `native-deep.yml`, a report; too noisy across Kokkos's umbrella headers to gate | @@ -256,6 +261,13 @@ to it. end of the session). - In the docs build: `SOLPROP_RUN_EXAMPLES` (`stale` or a script name, set by `poe docs-examples`; `tutorials` in CI's docs job). +- Set by solprop for its own child processes; do not set them: `SOLPROP_CALIBRATION_ROLE` + (`worker` in a `Pool` scan's workers, which never calibrate on first use), + `SOLPROP_NATIVE_WAIT_REQUEST` (the OpenMP wait a scan worker or calibration child asks + for), `SOLPROP_NATIVE_WAIT` (the wait the native import chose, beside the variables it + set), `SOLPROP_SLURM_WORKER` and `SOLPROP_SCAN_INSTANCE` (a Slurm array task and its + controller instance, written by the generated script), and `SOLPROP_SERVICE_RUN_THREADS` + (the thread budget the front end's kernel keeps for the runs it starts). ## CI @@ -263,14 +275,18 @@ to it. `SOLPROP_FFTW_PLAN=estimate`. Its first job, **changes**, compares the commit with its base: when only `docs/` and Markdown files changed, static, docs and **docs-tests** run (the test modules that open a documentation file: the SEP structure, the guide's -snippets, the accuracy page, the catalogues, the kernel contract and the figures), and -the test lanes below are skipped. A push to `main` that merges a pull request runs no +snippets, the accuracy page, the catalogues, the kernel contract and the figures, with +the slow-tier test that executes every snippet of the guide), and the test lanes below +are skipped. A push to `main` that merges a pull request runs no further jobs when its tree is the pull request head's tree and CI passed on that head: the pull request was up to date with `main`, so its run tested exactly what was merged. A pull request that was behind `main` merges to a new tree, which runs in full. A change -confined to the front end (`gui/`, with `docs/` and Markdown files) runs static, docs and -**gui** only. Any other change, or a push whose base is unknown, runs every job except -docs-tests, gui included, so a change to solprop is checked against the front end. +confined to the front end (`gui/`, with `docs/` and Markdown files), or one that touches +its chapter of the user guide (`docs/guide/front-end/`, which its tests read), runs +static, docs, docs-tests and **gui** only. Any other change, `gui/pyproject.toml` +included (solprop's release tests read it), or a push whose base is unknown, runs every +job except docs-tests, gui included, so a change to solprop is checked against the front +end. The long lanes run as **shards**, parallel jobs that each take whole modules: `SOLPROP_TEST_SHARD=i/n` keeps shard *i* of *n* (`tests/shards.py`, ADR-053). The shards @@ -304,8 +320,9 @@ jaxtyping hook) run in the coverage lane only; the other test lanes set run `poe cov-part`. **coverage-report** combines their data (`poe cov-report`), requires 100 % of statements and branches, and uploads the report to Codecov for the badge. -- **slow** (Linux and macOS): `poe test-slow` with the wheel installed. On Linux, - `SOLPROP_TEST_BACKEND=native` selects the ladders' backend. Each job's budget is +- **slow** (Linux and macOS): `poe test-slow` with the wheel installed, failing on a + skip whose reason `native/ci/check_skips.py` does not expect, as the test and coverage + lanes do. On Linux, `SOLPROP_TEST_BACKEND=native` selects the ladders' backend. Each job's budget is about 50 min of pytest wall time ([testing.md](testing.md), "Budgets and timing assertions"); sharding the lane is #803. - **oldest** (Linux, three shards): the package installed with `uv pip install @@ -345,17 +362,19 @@ it does not reuse a previous commit's CI result or bypass required checks. `.github/workflows/wheels.yml` builds the native release wheels (Linux x86-64 and aarch64, macOS arm64, Windows x64 and Arm) on pull requests that change the wheel recipe -(`native/ci/`, `native/pyproject.toml`, the CMake files, the workflow), weekly, on release -tags and by hand, and tests each installed wheel. It also builds solprop's sdist and -wheel and checks a fresh install of each, builds solprop-gui's and checks that -`solprop[gui]` installs from the files and answers at the version, and on a release -tag, once enabled, publishes solprop-native, then solprop, then (once `PUBLISH_GUI` is -set) solprop-gui ([Releasing and the native wheels](releasing.md), whose -pre-flight checklist sets publishing up). +or a pure-Python distribution's build inputs (`native/ci/`, `native/pyproject.toml`, the +CMake files, `hatch_build.py`, `gui/pyproject.toml`, `gui/hatch_build.py`, `gui/README.md`, +the front end's chapter of the user guide `docs/guide/front-end/`, and the workflow), +weekly, on release tags and by hand, and tests each installed wheel. It also builds +solprop's sdist and wheel and checks a fresh install of each, builds solprop-gui's and +checks that `solprop[gui]` installs from the files and answers at the version, and on a +release tag publishes solprop-native, then solprop, then solprop-gui +([Releasing and the native wheels](releasing.md)). `native` runs in the coverage lane's driver tests; the parity tests check it against `numpy_ref` in every job. GPU tests run by hand on a node with a device -(`poe test-gpu`), at each release and on pull requests that change device code. The -self-hosted `.github/workflows/cuda.yml`, started by hand, builds the CUDA extension and runs the -native package's pytest suite and Compute Sanitizer on it. Keep the gate's steps identical to -`poe check`; a change to one is a change to the other, in the same commit. +(`poe test-gpu`), at each release and on pull requests that change device code. +`.github/workflows/cuda.yml` builds the CUDA extension with the `cuda` preset's options and +runs the native package's pytest suite and Compute Sanitizer on it. It is dispatch-only, +needs a self-hosted runner labelled `nvidia-gpu`, and is part of no gate. Keep CI's checks in step with +`poe check` ([the gate](#the-gate-uv-run-poe-check)), in the same commit. diff --git a/docs/guide/figures/geometries.py b/docs/guide/figures/geometries.py index 5d7e78bf4..b0cddbd2a 100644 --- a/docs/guide/figures/geometries.py +++ b/docs/guide/figures/geometries.py @@ -78,7 +78,6 @@ "DARK", "FIGURES", "LIGHT", - "PENDING", "UNFIGURED", "WIDTH", "Figure", @@ -2946,9 +2945,6 @@ class Figure(NamedTuple): } """File stem to the figure; the page shows exactly these, each in its own section.""" -PENDING: dict[str, str] = {} -"""Sections of the page whose decomposition, and so whose figure, a later slice adds.""" - UNFIGURED = ("The map", "Choosing a decomposition") """Sections of the page that are about every decomposition and draw none.""" diff --git a/docs/guide/free-space/beams.md b/docs/guide/free-space/beams.md index c9291a414..018222279 100644 --- a/docs/guide/free-space/beams.md +++ b/docs/guide/free-space/beams.md @@ -72,8 +72,8 @@ A beam is a temporal pulse wrapped in a transverse profile, {py:class}`~solprop.pulses.SpatialPulse`; `waist` is the 1/e² intensity radius, and the pulse's `energy` or `peak_power` is the whole beam's physical energy or peak power in the medium at the launch plane ([energy and flux in a medium](flux.md)). The medium is a -{py:class}`~solprop.spatial.SpatialMedium` — a gas at a pressure, a glass, or a constant -index; `SpatialMedium()` is vacuum. The responses are the same objects the fibre routes +{py:class}`~solprop.spatial.SpatialMedium` — a gas at a pressure, which a gas needs, a +glass, or a constant index; `SpatialMedium()` is vacuum. The responses are the same objects the fibre routes use. Here a 100 µm beam at 1.5 times the critical power propagates a centimetre through argon with the Kerr effect, on an envelope grid, saving ten planes: @@ -349,7 +349,7 @@ Marburger distance. Radial, Cartesian and line runs execute on `numpy_ref` and the native backend's CPU build; its CUDA build runs them too. A Cartesian run's memory grows -as $n_x n_y n_t$, and the [backends chapter](../performance/resources.md#memory) says how it is budgeted. +as $n_x n_y n_t$, and the page on [execution resources](../performance/resources.md#memory) says how it is budgeted. The thread pools a free-space run uses, including its separate transverse FFT pool, are on the model page under [CPU execution settings](model.md#cpu-execution-settings). @@ -371,7 +371,7 @@ A saved plane of a free-space run is a coherent field plane that can be transpor through lenses, apertures and free space or coupled into a capillary or fibre ([coupling simulations](../workflows/coupling.md)). The [crossing-beam lesson](../../introduction/lessons/plot_04_crossing_beams.rst) shows how to launch a custom coherent array. The [radial filament lesson](../../introduction/lessons/plot_03_filament.rst) connects fluence, peak intensity and plasma. Refine the spatial grid and temporal bandwidth independently before interpreting either example quantitatively. -A beam's displacement and tilt were proposed and carried out by -[SEP 41](../../dev/seps/archive/sep-0041-recipes-and-front-ends.md). +The design of a beam's displacement and tilt is +[SEP 41](https://github.com/LupoLab/solprop/blob/main/docs/dev/seps/archive/sep-0041-recipes-and-front-ends.md). The saved planes follow -[SEP 51](../../dev/seps/archive/sep-0051-save-planes.md). +[SEP 51](https://github.com/LupoLab/solprop/blob/main/docs/dev/seps/archive/sep-0051-save-planes.md). diff --git a/docs/guide/free-space/cartesian.md b/docs/guide/free-space/cartesian.md index 5797ae7fe..2c256a771 100644 --- a/docs/guide/free-space/cartesian.md +++ b/docs/guide/free-space/cartesian.md @@ -43,7 +43,7 @@ in the field, so no multiple of $K$ bounds their products, and only refinement j the grid. Every free-space run carries a **safety ramp** in $k_\perp$ -([SEP 40](../../dev/seps/archive/sep-0040-transverse-absorbing-boundaries.md)). With +([SEP 40](https://github.com/LupoLab/solprop/blob/main/docs/dev/seps/archive/sep-0040-transverse-absorbing-boundaries.md)). With $\rho=\max(|k_x|/k_{x,\max},|k_y|/k_{y,\max})$ its power rate is $\alpha_s P(\rho)$, zero for $\rho\le1-f_s$ and rising as a raised cosine to $\alpha_s$ at the grid's largest wavenumber, with $f_s = 0.1$ by default; on a {py:class}`~solprop.grid.LineGrid` it acts on diff --git a/docs/guide/free-space/flux.md b/docs/guide/free-space/flux.md index 1f3277570..9ea4305ea 100644 --- a/docs/guide/free-space/flux.md +++ b/docs/guide/free-space/flux.md @@ -5,7 +5,7 @@ Each is the axial Poynting flux of the scalar forward field in the medium at the measured plane, so a launch energy is what an energy meter in that medium would read. The page also derives how a radial run carries the field through a gas whose pressure varies along z, and gives the certificate that decides whether such a path is admitted. -The design is [SEP 34](../../dev/seps/archive/sep-0034-medium-flux.md). The operator, the units +The design is [SEP 34](https://github.com/LupoLab/solprop/blob/main/docs/dev/seps/archive/sep-0034-medium-flux.md). The operator, the units and the transverse grids are described on [the free-space model](model.md) page. ## What energy means @@ -451,5 +451,5 @@ wave numbers. the nth order derivative of the refractive index," *J. Opt.* **16**, 015707 (2014), [doi:10.1088/2040-8978/16/1/015707](https://doi.org/10.1088/2040-8978/16/1/015707). -The medium flux, the radial amplitude correction and its certificate were proposed and -carried out by [SEP 34](../../dev/seps/archive/sep-0034-medium-flux.md). +The design of the medium flux, the radial amplitude correction and its certificate is +[SEP 34](https://github.com/LupoLab/solprop/blob/main/docs/dev/seps/archive/sep-0034-medium-flux.md). diff --git a/docs/guide/free-space/model.md b/docs/guide/free-space/model.md index aee1bc306..7b439f789 100644 --- a/docs/guide/free-space/model.md +++ b/docs/guide/free-space/model.md @@ -165,7 +165,7 @@ this way. A free-space grid has a hard edge: the radial transform holds the field at zero at its outer radius, and the Cartesian, line and planar grids are periodic, so light that reaches the edge is reflected or wraps round into the aperture, and the answer is wrong. -solprop's answer, from [SEP 40](../../dev/seps/archive/sep-0040-transverse-absorbing-boundaries.md), +solprop's answer, from [SEP 40](https://github.com/LupoLab/solprop/blob/main/docs/dev/seps/archive/sep-0040-transverse-absorbing-boundaries.md), is **room first, detection always, and absorption only for declared fast light**. **Room first.** The grids take `collar_fraction`, the room outside the requested size, @@ -190,10 +190,10 @@ ceiling on the step: a low-source run, which would otherwise take long steps, ta more. The backstop `B` covers a spectrum that broadens after a read: it starts at `L/16` and doubles at each read whose spread has not grown by a tenth since it started, up to `L/4`, and starts again when it has. A beam whose spectrum holds, far from the edge, then -reads at `4g/v` and its steps are left alone; on the suite's `line` case the reads no -longer add a step. A fixed schedule cannot be held to it, and reports itself as `coarse`. A read covers +reads at `4g/v` and its steps are left alone; on the suite's `line` case the reads add +no step. A fixed schedule cannot be held to it, and reports itself as `coarse`. A read covers every frequency, and `native` takes it where the state lives, with only numbers crossing -([SEP 44](../../dev/seps/archive/sep-0044-native-edge-read.md)). +([SEP 44](https://github.com/LupoLab/solprop/blob/main/docs/dev/seps/archive/sep-0044-native-edge-read.md)). Every run reports a `transverse_status` in its monitor record and says at the start what it will be able to report: `clear` (read at the spacing, below the warning), `warned`, @@ -252,7 +252,7 @@ For one frequency, with $k_z(\kappa) = \sqrt{k^2 - \kappa^2}$ and a collar of po $\alpha(x) = \alpha_0 P(x/w)$ over a width $w$, a component of transverse wavenumber $\kappa$ crossing the collar and coming back is attenuated in field by the local WKB integral with the exact symbol -([SEP 40](../../dev/seps/archive/sep-0040-transverse-absorbing-boundaries.md), section 4.2), +([SEP 40](https://github.com/LupoLab/solprop/blob/main/docs/dev/seps/archive/sep-0040-transverse-absorbing-boundaries.md), section 4.2), $$ \Gamma(\kappa; \alpha_0) = 2 w \int_0^1 \left|\operatorname{Im} q\right| ds, @@ -384,9 +384,11 @@ output = simulation.run() The empty response sequence gives exact linear diffraction in the selected temporal frame; add response objects — a `KerrResponse`, a plasma response — to the sequence for nonlinear propagation ([nonlinear responses](../media/nonlinear.md)). The absolute tolerance is -in the stored Hankel spectrum's units, V m. The settings carry no absorber, so the collar -here absorbs nothing ([above](#spatial-collar-and-statistics)). Translation is cached, so -a second `run()` reuses it. +in the stored Hankel spectrum's units, V m. The settings declare no absorber, so the run +takes the grid's default temporal and spectral collar, applied once per accepted step +(`absorber=False` switches it off); with no `spatial_absorber=` the transverse boundary +is the safety ramp alone ([above](#spatial-collar-and-statistics)). Translation is +cached, so a second `run()` reuses it. A spatial run's output metadata stores the spatial axes, frequency ordering, integration weights, collar, units and transform scalings. The state-layout names are diff --git a/docs/guide/front-end/first-run.md b/docs/guide/front-end/first-run.md index 9f0ac70b0..17fae8d0d 100644 --- a/docs/guide/front-end/first-run.md +++ b/docs/guide/front-end/first-run.md @@ -114,5 +114,5 @@ setup. **⋯ → Save** keeps the setup as a recipe file of your own, and page's **Export** menu has *Copy as Python* too: the code that draws that page from the results file, with {py:mod}`solprop.processing` and {py:mod}`solprop.plotting`. -The two forms of the saved planes were proposed and implemented by -[SEP 51](../../dev/seps/archive/sep-0051-save-planes.md). +The design of the two forms of the saved planes is +[SEP 51](https://github.com/LupoLab/solprop/blob/main/docs/dev/seps/archive/sep-0051-save-planes.md). diff --git a/docs/guide/front-end/machines.md b/docs/guide/front-end/machines.md index c6812734a..11dc92bba 100644 --- a/docs/guide/front-end/machines.md +++ b/docs/guide/front-end/machines.md @@ -20,9 +20,11 @@ Choose **Run → Machines…**, or **Machines…** at the end of the list on the For each machine, say: -- **solprop's Python there**: the Python that has solprop, as the machine's shell - finds it (`~/env/bin/python`, say). **Set up solprop there…** installs one for you - (below). +- **solprop's Python there**: the Python that has solprop, as one path + (`~/env/bin/python`, say, where `~/` is your home folder there) or a command the + machine's shell finds on its `PATH` (`python3`). It is taken as written: a variable + (`$SCRATCH`) or `~user` is not expanded, so write the path out in full, and it takes + no options. **Set up solprop there…** installs one for you (below). - **Runs go in**: the folder of its runs on that machine (`~/solprop-runs` by default). On a cluster, choose a folder the compute nodes can reach. - **Runs start** **directly**, as a process of their own, or **as Slurm jobs**. For @@ -70,7 +72,8 @@ They come from the run's record on the machine, so nothing is lost while you are - A Slurm job waiting in the queue shows **queued**, with Slurm's reason (`Priority`, `Resources`). - **Stop** asks the run to stop at its next step. Its file can be resumed, as for a run - on your computer. + on your computer. A run stopped while it is queued or starting ends as soon as it + starts, before it computes anything. - A Slurm job is sent `SIGTERM` two minutes before its time limit, so solprop writes where the run stood. **Resume** then continues it as a new job. diff --git a/docs/guide/front-end/screenshots.py b/docs/guide/front-end/screenshots.py index 4bf74e011..760542b94 100644 --- a/docs/guide/front-end/screenshots.py +++ b/docs/guide/front-end/screenshots.py @@ -32,7 +32,7 @@ from PySide6.QtWidgets import QApplication, QWidget from solprop_gui.classes.workflow import Stage from solprop_gui.model.workspace import DEFAULT_WORKSPACE -from solprop_gui.ui.workflow_window import WorkflowWindow +from solprop_gui.ui.workflow_window import WorkflowWindow, collect_between_events from solprop_gui.views.page_plots import LinePlot IMAGES = Path(__file__).resolve().parent / "images" @@ -118,6 +118,7 @@ def main() -> None: # noqa: PLR0915 - one walk through the window QSettings.Format.IniFormat, QSettings.Scope.UserScope, str(scratch / "settings") ) app = QApplication(sys.argv[:1]) + collector = collect_between_events() window = WorkflowWindow(workspace=scratch / "runs") window.resize(*SIZE) window.show() @@ -241,6 +242,7 @@ def run_to_analyse() -> None: if model is not None: model._saved = model.revision window.close() + collector.timer.stop() app.quit() diff --git a/docs/guide/media/dispersive-kerr.md b/docs/guide/media/dispersive-kerr.md index e25410d05..074fae3de 100644 --- a/docs/guide/media/dispersive-kerr.md +++ b/docs/guide/media/dispersive-kerr.md @@ -10,12 +10,12 @@ which mixes widely separated colours, therefore uses a coefficient that is right some of its processes and wrong for others. This page describes the two **dispersive electronic policies** of -[SEP 6](../../dev/seps/archive/sep-0006-dispersive-nonlinearity.md), which evaluate optmat's whole +[SEP 6](https://github.com/LupoLab/solprop/blob/main/docs/dev/seps/archive/sep-0006-dispersive-nonlinearity.md), which evaluate optmat's whole fit of a gas's hyperpolarisability at the absolute frequencies of every quartet the cubic couples, in one broadband polarisation. It is for readers who want to know which polarisation such a run computes, what each of the two evaluators approximates and what it costs, what happens where the field leaves the gas's data, and how to read what a run -recorded. The [tutorial](../../auto_tutorials/capillaries/plot_11_dispersive_kerr) runs +recorded. The [tutorial](../../auto_tutorials/capillaries/plot_11_dispersive_kerr.rst) runs both of SEP 6's demonstration cases under all three policies. | `MaterialSelection.electronic` | Response | What it evaluates | @@ -147,8 +147,8 @@ polarisation off the edges of the time window, multiplies each product in time before its output multipliers and $\Pi_+$: $G[w\,(GE)^3]$, and likewise for every term of the polynomial. The constant cubic's collar multiplies its polarisation, and with no output multiplier the two orders coincide. For the dispersive evaluators the difference depends on the filtered fields and products near the collar. -Check it by enlarging the window while retaining resolution. The earlier comparison found a difference of a few parts in -$10^3$ for a pulse at nine tenths of the half-window. A statement of equivalence +Check it by enlarging the window while retaining resolution. For a pulse at nine tenths +of the half-window the difference is a few parts in $10^3$. A statement of equivalence for a well-contained pulse is conditional on the filtered field also remaining clear of the collar. @@ -235,7 +235,7 @@ translation, per gas, into three regions: A run whose band reaches the bounded or best-effort region logs that once, at INFO, naming the gas and the band; nothing is refused and nothing warns per step. The leg bounds and band edges are optmat's, read from its support record, never written into -solprop; at optmat 0.8.0 (unchanged since 0.4.0), for one linear polarisation: +solprop; at optmat 0.10, for one linear polarisation: | Gas | Leg bound (nm) | Band edge (nm) | |---|---:|---:| @@ -248,7 +248,7 @@ solprop; at optmat 0.8.0 (unchanged since 0.4.0), for one linear polarisation: | CO₂, CH₄, SF₆, N₂O, O₃ | 230.1, 224.7, 215.9, 383.4, 401.0 | undefined: no curated two-photon limit, so best effort beyond the leg bound | Air has no fit of its own; each of its populations carries its own, and O₂ makes air -best effort below about 305 nm. CO₂, CO and O₃ have optmat fits but are not yet +best effort below about 305 nm. CO₂, CO and O₃ have optmat fits but are not built-in species. ## Pump dynamics and emission in one response @@ -274,7 +274,7 @@ The dispersive wave's wavelength is set by phase matching to the soliton's nonli wavenumber, which comes from the exactly evaluated self-phase modulation, so it moves little between the policies; its energy, and its evolution after emission, are what change. In the full-size case (the -[worked example](../../auto_examples/processes/plot_07_rdw_dispersive_kerr)) the +[worked example](../../auto_examples/processes/plot_07_rdw_dispersive_kerr.rst)) the 100–150 nm band at the exit carries about 30 % more energy under both dispersive policies than under the carrier one with two or four modes, and about 53 % more with one, and its centre moves by 2–3 nm; in the tutorial's shorter two-mode case, about @@ -416,7 +416,7 @@ factorisation's own departure from the polynomial, 0.9 % and 1.3 %: as an approx of the polynomial the mixture's filter is as good as the exact sum. In a 3 cm, 150 µJ capillary run the exit field's nonlinear change departs from the polynomial's by 0.29 % (helium and argon) and 0.36 % (air), against 0.27 % and 0.29 % for the exact sum and -5–6 % for the carrier policy ([SEP 6](../../dev/seps/archive/sep-0006-dispersive-nonlinearity.md)). +5–6 % for the carrier policy ([SEP 6](https://github.com/LupoLab/solprop/blob/main/docs/dev/seps/archive/sep-0006-dispersive-nonlinearity.md)). A supplied species, which carries no optmat model, is refused under a dispersive policy by name rather than given a borrowed curve; air resolves through its populations. @@ -435,8 +435,8 @@ components is not represented. The run records it as `"isotropic-kleinman"`. Both of SEP 6's demonstration cases were run at full size, under all three policies on the default backend, in the worked examples -[the dispersive wave under a frequency-dependent response](../../auto_examples/processes/plot_07_rdw_dispersive_kerr) -and [deep-ultraviolet four-wave mixing in argon](../../auto_examples/processes/plot_08_duv_fwm_dispersive_kerr). +[the dispersive wave under a frequency-dependent response](../../auto_examples/processes/plot_07_rdw_dispersive_kerr.rst) +and [deep-ultraviolet four-wave mixing in argon](../../auto_examples/processes/plot_08_duv_fwm_dispersive_kerr.rst). Each difference below is the carrier policy's against the polynomial's, and the symmetric evaluator's against the polynomial's. Values are rounded from the recorded example output. @@ -615,7 +615,7 @@ entry["regions"]["best_effort"] # None: the band stays inside argon's band edge ``` After a run the same manifest is `output.metadata.materials`, and the -[tutorial](../../auto_tutorials/capillaries/plot_11_dispersive_kerr) shades the regions on a +[tutorial](../../auto_tutorials/capillaries/plot_11_dispersive_kerr.rst) shades the regions on a spectrum from it. ## Limitations @@ -644,4 +644,4 @@ spectrum from it. Hopper device (CUDA). This page documents the functionality proposed and implemented by -[SEP 6](../../dev/seps/archive/sep-0006-dispersive-nonlinearity.md). +[SEP 6](https://github.com/LupoLab/solprop/blob/main/docs/dev/seps/archive/sep-0006-dispersive-nonlinearity.md). diff --git a/docs/guide/media/envelope-plasma.md b/docs/guide/media/envelope-plasma.md index 70aa37bac..f3076e971 100644 --- a/docs/guide/media/envelope-plasma.md +++ b/docs/guide/media/envelope-plasma.md @@ -17,7 +17,7 @@ examples and rate options are in [strong-field ionisation](ionisation.md#envelope-plasma-sources), and the [carrier/envelope tutorial](../../auto_tutorials/capillaries/plot_05_envelope_plasma.rst) compares a complete envelope run with a carrier-resolved one. The field-grid plasma -response it is compared against is on [nonlinear responses](field-plasma.md#the-plasma-response). +response it is compared against is the [carrier-resolved plasma response](field-plasma.md#the-plasma-response). ## 1. Three separate choices make a plasma model diff --git a/docs/guide/media/field-plasma.md b/docs/guide/media/field-plasma.md index 57dcf9cbe..79938c416 100644 --- a/docs/guide/media/field-plasma.md +++ b/docs/guide/media/field-plasma.md @@ -71,7 +71,7 @@ The current is still built from the same population and free-current integrals; propagation does not run a third integral to form the plasma polarisation. Kerr and Raman retain their ordinary collared polarisation. The derivation, finite-window terms and validation requirements are in -[SEP 27](../../dev/seps/archive/sep-0027-held-plasma-current.md). +[SEP 27](https://github.com/LupoLab/solprop/blob/main/docs/dev/seps/archive/sep-0027-held-plasma-current.md). Translation certifies the steady-current identity once per grid: $\|\operatorname{DFT}[g]-\operatorname{DFT}[g']/q\|_A / @@ -86,9 +86,8 @@ sampling when those effects matter. The source needs no option: `plasma=True` on the capillary interface, for example, selects it. A direct {meth}`~solprop.nonlinear.responses.PlasmaResponse.evaluate` call still returns the -physical, ungated $P=\int J\,dt$, including any residual drift. The gated source -of the original equation is not available: the held current is the only form either -backend runs. +physical, ungated $P=\int J\,dt$, including any residual drift. Neither backend runs +a gated source: the held current is the only form either runs. ## How the current integrals are formed @@ -105,7 +104,7 @@ free current once and divides by $i\omega$ in frequency; its interior Drude multiplier is $\rho$. Collar and finite-window errors have separate budgets. {class}`~solprop.nonlinear.responses.PlasmaResponse`'s `integration` chooses between two rules -([SEP 18](../../dev/seps/archive/sep-0018-band-exact-plasma-integrals.md)). +([SEP 18](https://github.com/LupoLab/solprop/blob/main/docs/dev/seps/archive/sep-0018-band-exact-plasma-integrals.md)). **The band rule** (`integration="band"`) filters each integrand with symmetric taps before the trapezoid: @@ -153,7 +152,7 @@ integrands, the residual free current after the pulse included. Its parts: A well-contained pulse should make the integrands negligible at the leading edge; inspect the recorded boundary level, including any free-current contribution in a pre-ionised gas. The test construction and measurements are - retained in [SEP 18](../../dev/seps/archive/sep-0018-band-exact-plasma-integrals.md). + retained in [SEP 18](https://github.com/LupoLab/solprop/blob/main/docs/dev/seps/archive/sep-0018-band-exact-plasma-integrals.md). - **The exposure.** The filtered rate can dip below zero beside a spike sharper than a sample, so the exposure is floored at zero, pointwise. The fraction stays in $[f_0, 1)$ and is non-decreasing to within that undershoot. The floor acts on @@ -303,7 +302,7 @@ complex data, the same arithmetic would return a quantity nobody has derived. Th separate {py:class}`~solprop.nonlinear.envelope_plasma.EnvelopePlasmaResponse` implements the derived cycle moments, depletion and frequency-domain current assembly described in -[the ionisation manual](ionisation.md#envelope-plasma-sources). +[envelope plasma](envelope-plasma.md). ```{eval-rst} .. plot:: diff --git a/docs/guide/media/ionisation.md b/docs/guide/media/ionisation.md index c1f48dc53..b5c07f2a9 100644 --- a/docs/guide/media/ionisation.md +++ b/docs/guide/media/ionisation.md @@ -44,7 +44,7 @@ ionisation there. [optmat](https://github.com/LupoLab/optmat) curates strong-field rate models for every gas solprop ships, checked against all-electron static rates, a time-dependent calculation and measured yields. solprop takes them, and keeps no formula of its own -([SEP 3](../../dev/seps/archive/sep-0003-optmat-materials.md)). The free-space and planar +([SEP 3](https://github.com/LupoLab/solprop/blob/main/docs/dev/seps/archive/sep-0003-optmat-materials.md)). The free-space and planar routes, whose rates are the caller's, bind an `OptmatRate`'s energy per event to the input's peak field as the capillary route does. @@ -74,7 +74,7 @@ explicit-parameter constructor, or a rate of the caller's own ([below](#a-rate-of-your-own)). **The models.** All of optmat's rates are for linear polarisation, take the field in -V/m and return s⁻¹. At optmat 0.8.0 (unchanged since 0.4.0) the recommended models are, with the adapter's +V/m and return s⁻¹. At optmat 0.10 the recommended models are, with the adapter's values at 800 nm (the threshold below which the rate is exactly zero, the maximum field above which it is held, and the energy per event in the weak-field limit): @@ -110,12 +110,13 @@ the same [table](#tables) as every other rate. **The maximum field.** Each model declares the largest field its static correction was fitted to: twice the barrier-suppression field with Tong and Lin's correction (an atom), -4.5 times with Zhang's, 1.5 times for the molecules. Above it optmat's instantaneous rate -leaves its fit: it turns over a few per cent above the maximum field (4–7 % for Ar, Kr -and Xe, 16–19 % for N₂ and He), is erratic beyond (argon's spikes to 2600 times its -value at the maximum field at 1.6 times that field) and falls towards zero within a -decade, and a rate table, which by default reaches thirty times the input's peak, -would extend there. The adapter therefore **holds the rate at its value at the maximum +4.5 times with Zhang's, and for each molecule the range its own correction was fitted +to, 1.6 to 2 times (1.61 for H₂, 1.71 for N₂, 1.96 for O₂). Above it the corrected +instantaneous rate leaves its fit: extrapolated, it turns over above the maximum field +(36–42 % above it for Ar, Kr and Xe, 57 % for He, 28 % for N₂) and falls towards +zero within a decade (argon's to $10^{-7}$ of its value at the maximum field at ten +times that field), and a rate table, which by default reaches thirty times the input's +peak, would extend there. The adapter therefore **holds the rate at its value at the maximum field** above it, as a table holds its last knot, and the table stops there. Holding is the least bad of the choices: at that rate a population is depleted within a femtosecond, so the held value already ionises everything it reaches. optmat warns at @@ -151,7 +152,7 @@ with that energy as its potential loss term, the envelope's loss current and the species statistics all pay it. **Polarisation.** The rates are for a linearly polarised field. An elliptical or -circular run stays admitted, as before, on the quasi-static average of the +circular run is admitted, on the quasi-static average of the instantaneous rate around the polarisation ellipse, and the manifest records the approximation. A run whose input is not linearly polarised at its peak, at a Keldysh parameter above one there, warns once: there elliptic and orbital-resolved @@ -278,7 +279,7 @@ a whole column. A propagation evaluates the rate once per sample of the fine tim on every column, at every stage, so it uses a precomputed table: {py:class}`solprop.translate.ionisation.RateTable`, built by {py:func}`solprop.translate.ionisation.build_rate_table`, which brings that to about 10 ns -in NumPy; the compiled backends evaluate the same table inside their kernels. The table +in NumPy; the native backend evaluates the same table inside its kernels. The table controls interpolation accuracy and behaviour outside its sampled interval. Its tolerance is separate from the optical stepper tolerance and the rate model's physical uncertainty. @@ -348,7 +349,7 @@ table = build_rate_table(rate, (1e9, 1e11)) # converged to 1e-6, log-spaced k t = np.linspace(-40e-15, 40e-15, 2049) field = 4e10 * np.exp(-(t / 10e-15) ** 2) # 4e10 V/m peak, 17 fs FWHM in field fraction = ionisation_fraction(table, field, float(t[1] - t[0])) -print(f"{100 * fraction[-1]:.2f} % ionised") # 44.72 % ionised +print(f"{100 * fraction[-1]:.2f} % ionised") # 38.35 % ionised ``` ## Molecules: an orientation-averaged rate @@ -392,7 +393,7 @@ subtract the initial fraction before converting a result into a chemical increme The initial fraction may be a path along `z` per population, such as `preionisation={"N2": PiecewiseLinear(...), "O2": 0.0}`: the fraction ionised before the pulse arrives at each position, read by every backend at every stage, with the -steps landing on the path's kinks ([nonlinear.md](field-plasma.md#a-pre-ionised-fraction-along-the-fibre)). +steps landing on the path's kinks ([a pre-ionised fraction along the fibre](field-plasma.md#a-pre-ionised-fraction-along-the-fibre)). ## Envelope plasma sources diff --git a/docs/guide/media/material-selection.md b/docs/guide/media/material-selection.md index 2728343db..1b9255cbf 100644 --- a/docs/guide/media/material-selection.md +++ b/docs/guide/media/material-selection.md @@ -15,7 +15,7 @@ response — its total $n_2$, Raman fraction and Raman shape — from optmat's silica bundle, each gas's ionisation rate ([rates from optmat](ionisation.md#rates-from-optmat)) and a gas fill's Raman response ([Raman responses from optmat](raman-data.md#raman-responses-from-optmat)). An omitted selection is `MaterialSelection()`, which takes optmat's recommended -models. The [material integration proposal](../../dev/seps/archive/sep-0003-optmat-materials.md) +models. The [material integration proposal](https://github.com/LupoLab/solprop/blob/main/docs/dev/seps/archive/sep-0003-optmat-materials.md) records how the data are mapped into solprop. ## Selecting gases @@ -50,7 +50,7 @@ optmat's whole hyperpolarisability model ([below](#the-dispersive-electronic-policies)). `raman` selects a gas response in a gas-filled guide or a silica bundle for the GNLSE; the permitted objects differ between those contexts. `ionisation` names the run's rate models: `plasma=True` takes optmat's rate for each species, its plasma loss pays -that rate's own energy per event (`energy_loss="peak-weighted"`), and a custom species +that rate's own energy per event, and a custom species needs an explicit rate; see [rates from optmat](ionisation.md#rates-from-optmat). `raman` names a gas fill's Raman response and `raman_shift` its density-shift approximation ([Raman responses from optmat](raman-data.md#raman-responses-from-optmat)). @@ -109,7 +109,7 @@ n2("Ar", pressure=3.0, wavelength=800e-9, selection=selection) ## The dispersive electronic policies `MaterialSelection(electronic="gas-polynomial")` and `"symmetric-kerr"`, from -[SEP 6](../../dev/seps/archive/sep-0006-dispersive-nonlinearity.md), evaluate optmat's whole fit, +[SEP 6](https://github.com/LupoLab/solprop/blob/main/docs/dev/seps/archive/sep-0006-dispersive-nonlinearity.md), evaluate optmat's whole fit, $\gamma_T=\gamma_0[1+AS_2+BS_2^2+B'S_4]$ over each quartet's four signed vacuum wavenumbers, at the absolute frequencies of every quartet the cubic couples, instead of one coefficient: the polynomial itself, or a symmetric factorisation of its Kerr @@ -433,27 +433,15 @@ so two default walls or cores built separately are one material. and the compressors, which name their glasses. **Named models.** `model=` selects any other optmat model of the material, among them -the published Sellmeier formulas, made absolute (see below): +the published Sellmeier formulas, made absolute (see below). optmat's registry lists a +material's models by name, the recommended one among them; the material names are +`SiO2`, `CaF2`, `MgF2`, `BaF2`, `Al2O3` (sapphire) and `N-BK7`: -```{eval-rst} -.. list-table:: - :header-rows: 1 - :widths: 34 66 +```{code-block} python +from optmat.solid.models import registry - * - factory - - optmat model - * - ``fused_silica`` - - ``malitson_1965/sellmeier``; ``franta_2016/udm_lithosil_q2`` - * - ``calcium_fluoride`` - - ``daimon_2002/sellmeier_20C``; ``malitson_1963/sellmeier`` - * - ``magnesium_fluoride`` - - ``dodge_1984/sellmeier_o`` - * - ``bk7`` - - ``schott_2023/sellmeier`` - * - ``sapphire`` - - ``weber_2003/sellmeier_o`` (Malitson and Dodge's ordinary-ray formula, as Weber prints it) - * - ``barium_fluoride`` - - ``malitson_1964/sellmeier`` +sorted(registry.models("CaF2")) +# ['daimon_2002/sellmeier_20C', 'daimon_2002/sellmeier_25C', 'malitson_1963/sellmeier'] ``` - **Absolute index.** Every optmat index is relative to vacuum. The published @@ -465,7 +453,7 @@ the published Sellmeier formulas, made absolute (see below): - **Birefringence.** MgF₂ and sapphire are uniaxial, and an optmat model is per ray: a window or wall names its ray, `axis="o"` or `axis="e"`, and the recommended model without an axis is refused by name — `magnesium_fluoride()`, `sapphire()` and - `glass("MgF2")` included, a deliberate breaking change. A named model is per ray + `glass("MgF2")` included. A named model is per ray too, and refuses the other `axis`. - **Metals** are tables with their interpolant's exact derivative. Outside their range they hold their end values, with a warning. @@ -603,5 +591,5 @@ and carry their own citations. recommended model, as `MaterialSelection()` does. This page documents the functionality proposed and implemented by -[SEP 3](../../dev/seps/archive/sep-0003-optmat-materials.md); its dispersive electronic -policies are [SEP 6](../../dev/seps/archive/sep-0006-dispersive-nonlinearity.md)'s. +[SEP 3](https://github.com/LupoLab/solprop/blob/main/docs/dev/seps/archive/sep-0003-optmat-materials.md); its dispersive electronic +policies are [SEP 6](https://github.com/LupoLab/solprop/blob/main/docs/dev/seps/archive/sep-0006-dispersive-nonlinearity.md)'s. diff --git a/docs/guide/media/materials.md b/docs/guide/media/materials.md index e382e4da0..64408ab92 100644 --- a/docs/guide/media/materials.md +++ b/docs/guide/media/materials.md @@ -14,7 +14,7 @@ and a general anisotropic crystal response are not modelled. solprop keeps no material database of its own. Every built-in gas, solid and response comes from the curated package optmat -([SEP 3](../../dev/seps/archive/sep-0003-optmat-materials.md)): an omitted selection means +([SEP 3](https://github.com/LupoLab/solprop/blob/main/docs/dev/seps/archive/sep-0003-optmat-materials.md)): an omitted selection means `MaterialSelection()`, optmat's recommended model of every family, and [materials from optmat](material-selection.md#materials-from-optmat) says what that resolves to. What solprop keeps is the propagation physics (linear density scaling, the mixture rule, the flow @@ -58,11 +58,11 @@ Choosing is done in one of three ways, from the most to the least common: its own citation ([quick experiments](material-selection.md#quick-experiments)). A supplied object is never rebuilt or matched to a built-in by its name. The -[material-choices tutorial](../../auto_tutorials/basics/plot_06_material_choices) shows +[material-choices tutorial](../../auto_tutorials/basics/plot_06_material_choices.rst) shows all three on a short run, and reads from the runs' manifests which part of the physics each change touched. -**What is supported.** The recommended models of the built-in gases, at optmat 0.8.0 (unchanged since 0.4.0) +**What is supported.** The recommended models of the built-in gases, at optmat 0.10 (the shortest qualified wavelength of the index, rounded where shown; the rate's stated uncertainty factor at 800 nm). Inspect the record for your own carrier, and retain gaps in the qualified intervals: @@ -75,7 +75,7 @@ carrier, and retain gaps in the qualified intervals: | CH₄ | `fit/CH4` | 240 nm, five windows to 12.1 µm | `eos/`; transport provisional | `hyperpolarizability/` | validated | molecular; ×2 | | SF₆ | `fit/SF6` | 230 nm to 5 µm | `eos/`, `transport/` | `hyperpolarizability/` | validated | molecular, untested; ×10 | | N₂O | `fit/N2O` | 320 nm, four windows to 7.05 µm | `eos/`, `transport/` | `hyperpolarizability/` | provisional, opt-in | molecular; ×3 | -| air (`Gas.Air`) | `air/dry air (N2, O2, Ar)` | — | `eos/dry air (Lemmon 2000)` | none | none | none | +| air (`Gas.Air`) | `air/dry air (N2, O2, Ar)` | 195 nm | `eos/dry air (Lemmon 2000)` | none | none | none | Every index model reaches the static limit except where a window ends. The solids are in [solids](material-selection.md#solids): fused silica (`fit/SiO2`, absorbing, with its nonlinear bundle), diff --git a/docs/guide/media/mixtures.md b/docs/guide/media/mixtures.md index 1e0f39113..a21727a36 100644 --- a/docs/guide/media/mixtures.md +++ b/docs/guide/media/mixtures.md @@ -23,7 +23,7 @@ on the [profiles page](../waveguides/profiles.md). susceptibility, real-gas equation of state, transport properties and Kerr model are optmat's ([materials from optmat](material-selection.md#materials-from-optmat)), and its `IonisationData` is optmat's first ionisation energy. Its rate and Raman response are -optmat's too, resolved for the run ([SEP 3](../../dev/seps/archive/sep-0003-optmat-materials.md)); +optmat's too, resolved for the run ([SEP 3](https://github.com/LupoLab/solprop/blob/main/docs/dev/seps/archive/sep-0003-optmat-materials.md)); a built-in species carries no Raman constants of its own. A custom species carries its own data, Raman constants included ({class}`~solprop.physdata.raman_types.MolecularRaman`). Missing response data is @@ -66,7 +66,8 @@ deliberate approximation: argon is 0.93 % of dry air's molecules, so leaving it costs about 1 % of the dispersion and Kerr response, and its ionisation contribution must be assessed at the actual field strength. Its 15.76 eV ionisation potential does not exclude ionisation in every air calculation. Pass `gas=Mixture.air(...)` to keep it; argon then contributes dispersion and Kerr, and its -missing Raman response is logged at INFO. +missing Raman response is logged at INFO. {py:func}`~solprop.physdata.gases.is_air` is +the drivers' test of whether a name means air: `Gas.Air`, or `"air"` in any case. These rounded major constituents follow the dry-air composition described by [NOAA](https://www.noaa.gov/jetstream/atmosphere). The fractions define the model; they @@ -291,6 +292,11 @@ responses = responses_for( ) ``` +At 6 bar and 300 K the fill is 5.4 amagat, above the 2.07 amagat to which optmat +validates the air Raman response, so this warns once with a +{class}`~solprop.exceptions.MaterialRangeWarning` +([validated ranges](raman-data.md#validated-ranges-and-vacuum)). + **Selecting Raman.** `raman` takes the same vocabulary here and on the drivers: - `True` selects every available Raman term and logs, at INFO, the components without @@ -318,8 +324,10 @@ Pass `envelope=True` to `responses_for` for an envelope simulation. Explicit `plasma=True` or a per-label rate mapping then builds `EnvelopePlasmaResponse` channels and defaults third-harmonic generation off. Each rate must declare the instantaneous isotropic convention; a pre-averaged rate is rejected. For example, -`responses_for(fill, envelope=True, plasma={"N2": True}, raman=False)` -opens only nitrogen's channel. `Simulation.with_mixture` retains this response +`responses_for(fill, envelope=True, plasma={"N2": True}, raman=False, wavelength=800e-9)` +opens only nitrogen's channel (the carrier `wavelength` is needed because the Kerr +response, on by default, takes optmat's dispersive coefficient at it). +`Simulation.with_mixture` retains this response selection and reuses the immutable rate data while updating each population's density and preionisation paths. @@ -375,8 +383,8 @@ deposited by that pulse. Linear absorption is separate from this ionisation work `prop_capillary`, `prop_waveguide` and their `Simulation.from_capillary` and `Simulation.from_waveguide` constructors accept, as `gas`, a built-in gas, `"air"` (the two-component mixture [above](#air)), a mapping of species names to mole fractions, or a -complete `Mixture`. A built-in gas or a mapping takes `pressure` as the total pressure -(one bar when omitted); a `Mixture` carries its own paths, and `pressure`, +complete `Mixture`. A built-in gas or a mapping takes `pressure` as the total pressure, +and refuses to go without one; a `Mixture` carries its own paths, and `pressure`, `pressure_floor`, `vacuum_end`, `susceptibility` and a different `temperature` beside it are refused. Pressure endpoints require a length in mixture constructors; the capillary entry @@ -413,7 +421,7 @@ retain their component's declaration, including when the whole `preionisation` argument is omitted. A path is validated in `[0, 1]`, printed by its own description and recorded in the run metadata by its samples and breakpoints, like a density path; the steps of a run land on its kinks -([nonlinear.md](field-plasma.md#a-pre-ionised-fraction-along-the-fibre)). +([a pre-ionised fraction along the fibre](field-plasma.md#a-pre-ionised-fraction-along-the-fibre)). ```{code-block} python from dataclasses import replace @@ -494,7 +502,7 @@ A finite radial Hankel transform is only approximately unitary: its physical and spectral quadrature energies converge with radial resolution, rather than being bitwise equal on an arbitrary coarse grid. -The [air tutorial](../../auto_tutorials/capillaries/plot_04_air_mixture) shows separate nitrogen and +The [air tutorial](../../auto_tutorials/capillaries/plot_04_air_mixture.rst) shows separate nitrogen and oxygen ionisation, the nitrogen Raman kernel and a three-point composition update. A regression test uses a 15 µm capillary of length 0.225 m, air at 6 bar and 300 K, diff --git a/docs/guide/media/noise.md b/docs/guide/media/noise.md index f8503ec51..88f016af5 100644 --- a/docs/guide/media/noise.md +++ b/docs/guide/media/noise.md @@ -93,7 +93,8 @@ a seed keeps meaning one realisation on a given grid size. - the field without the seed; processing does not restore it * - refused beside - the planar grid - - it, plus interpolated planes, field planes for coupling and coupled flows + - it, plus interpolated planes, field planes for coupling, coupled flows, an + interior launch and a TDSE response ``` Both come from the same draw. {py:func}`~solprop.noise.input_noise` and @@ -252,8 +253,8 @@ polarisation and frequency bin in the same way. It takes the entrance plane's {py:class}`~solprop.spatial.SpatialFlux`: each column and bin is scaled so that its energy, weighted by the real axial admittance of the entrance medium, is $\hbar\omega$, the measure a launch is normalised in. Nonpropagating, inactive and zero-frequency bins -are not power ports and carry no photon; the random stream is drawn as before, so a seed -keeps its meaning ([energy and flux in a medium](../free-space/flux.md#the-discrete-measure-endpoints-and-noise)). +are not power ports and carry no photon; the random stream is still drawn over every bin, +so a seed keeps its meaning ([energy and flux in a medium](../free-space/flux.md#the-discrete-measure-endpoints-and-noise)). A planar grid carries no noise draw. An ensemble is a sequence of seeds. Run it on a fixed step schedule (`schedule=`, see @@ -261,7 +262,7 @@ An ensemble is a sequence of seeds. Run it on a fixed step schedule (`schedule=` across the members, so the spread between members is the physics and not the stepper. Calibrate that schedule with noise on: one discovered on a noiseless run integrates the seed's dynamics poorly. -The [supercontinuum examples](../../auto_examples/supercontinuum/plot_03_modulational_instability_supercontinuum) +The [supercontinuum examples](../../auto_examples/supercontinuum/plot_03_modulational_instability_supercontinuum.rst) run such ensembles and compute the relative intensity noise and the coherence from them ([processing](../results/processing.md)). diff --git a/docs/guide/media/nonlinear.md b/docs/guide/media/nonlinear.md index ffe1298f0..f4ab82543 100644 --- a/docs/guide/media/nonlinear.md +++ b/docs/guide/media/nonlinear.md @@ -188,7 +188,7 @@ Everything above multiplies the cubic by one $\chi^{(3)}$, which for a built-in its Kerr coefficient at the run's carrier ([materials](material-selection.md#the-electronic-kerr-coefficient-at-the-carrier)). A gas's electronic response is in fact a function of all four frequencies of each quartet, and rises towards the ultraviolet. The dispersive electronic policies of -[SEP 6](../../dev/seps/archive/sep-0006-dispersive-nonlinearity.md), +[SEP 6](https://github.com/LupoLab/solprop/blob/main/docs/dev/seps/archive/sep-0006-dispersive-nonlinearity.md), `MaterialSelection(electronic="gas-polynomial")` and `"symmetric-kerr"`, replace the constant by optmat's whole fit, evaluated at the absolute frequencies of every quartet in the same single broadband polarisation: diff --git a/docs/guide/media/raman-data.md b/docs/guide/media/raman-data.md index 69b60e58a..750f19314 100644 --- a/docs/guide/media/raman-data.md +++ b/docs/guide/media/raman-data.md @@ -5,7 +5,7 @@ The response strengths, line positions, damping and collision partners must desc ## Raman responses from optmat Every built-in gas's Raman response is optmat's -([SEP 3](../../dev/seps/archive/sep-0003-optmat-materials.md), +([SEP 3](https://github.com/LupoLab/solprop/blob/main/docs/dev/seps/archive/sep-0003-optmat-materials.md), [materials from optmat](material-selection.md#materials-from-optmat)). optmat's gas Raman responses are its per-line models of N₂, O₂, H₂, D₂, CH₄, SF₆ and N₂O, and of their mixtures, with the available gain and revival evidence recorded per response. @@ -61,7 +61,7 @@ wavelength, and its amplitudes already carry each constituent's mole fraction, s mixture's response is driven by its **total** density. Lines that share a width law and a shift form a **damping group**. Each group $g$ and -tensor family $\kappa$ becomes one existing Raman term, +tensor family $\kappa$ becomes one Raman term, $$ u_{g\kappa}(t) = w(t) \sum_{k\in g} A_{k\kappa} \sin(\Omega_k t), @@ -71,7 +71,7 @@ $$ with $w$ the grid's causal taper ([sampling the kernel](raman-numerics.md#sampling-the-kernel-and-the-density-it-depends-on)): an undamped row and a decay-rate path, exactly the two arrays the kernel contract -already carries. The mapping is **exact** for every gas whose lines do not shift, at +carries. The mapping is **exact** for every gas whose lines do not shift, at any density path: the rows do not depend on the density, and the decay rate is optmat's own group law, evaluated by optmat. An all-zero row is dropped and groups are never merged. The counts at 293.15 K and 800 nm: @@ -85,7 +85,7 @@ merged. The counts at 293.15 K and 800 nm: | CH₄, SF₆ | 1 each | 1 | 1 | | dry air (N₂, O₂, Ar) | 170 | 82 | 126 | -against two terms for solprop's own N₂ model. +against two terms for a supplied two-term N₂ model. **Tensor form.** optmat gives each line an isotropic and an anisotropic amplitude, in Hellwarth's decomposition @@ -105,8 +105,8 @@ it is given. The response always takes the run's carrier: the selection's `carrier_wavelength` when it names one, otherwise the grid reference `wavelength`. **Temperature.** A response fixes its temperature, which sets both the populations and -the widths' temperature laws. A temperature path along z takes the existing -[reference-temperature rule](raman-models.md#the-rotational-ladder), weighted now by the +the widths' temperature laws. A temperature path along z takes the +[reference-temperature rule](raman-models.md#the-rotational-ladder), weighted by the composition's summed density, or an explicit `MolecularOptions(temperature=...)`, and warns that the populations *and* the width laws are held there. @@ -155,7 +155,7 @@ depends on the density. $\sum_k |A_k| e^{-\Gamma_k t}$ times the frequency error times $t$, which the tests check against optmat's direct evaluation along the path. -[SEP 10](../../dev/seps/sep-0010-low-rank-raman.md) removes this restriction. +[SEP 10](../../dev/seps/sep-0010-low-rank-raman.md), a draft, proposes removing this restriction. ## Validated ranges, and vacuum @@ -189,9 +189,9 @@ The kernel rebuilds $\sum_g e^{-\gamma_g t} u_g$ and transforms it whenever a de changes: once per run at constant density, and at every stage on a density gradient. The rebuild scales with the number of rows: on this page's reference measurement, at $2^{14}$ fine samples, 6 ms for N₂'s 72 rows and 10 ms for dry air's 126, against -0.3 ms for solprop's own two-term N₂ model and 0.25 ms for one convolution -([benchmarks](../../dev/benchmarks.md#raman-kernel-rebuild)). SEP 10's low-rank -representation removes this cost. +0.3 ms for a supplied two-term N₂ model and 0.25 ms for one convolution +([benchmarks](../../dev/benchmarks.md#raman-kernel-rebuild)). SEP 10, a draft, proposes +a low-rank representation that would remove this cost. The run's manifest records the response's identity, the reference temperature (`raman_reference_temperature`) and, for each response, its labels, damping groups, diff --git a/docs/guide/media/raman-models.md b/docs/guide/media/raman-models.md index 5d3cc10c3..3d2570e92 100644 --- a/docs/guide/media/raman-models.md +++ b/docs/guide/media/raman-models.md @@ -79,8 +79,8 @@ $K$ is negative and so is the bracket, because the population per magnetic suble falls with $J$; the lines therefore come out positive, with the same sign as a vibration. The ladder is truncated wherever $E_J$ stops increasing with $J$: beyond that the two-term expansion has left its range of validity and the levels it predicts -are an artefact. For hydrogen's constants ($B = 58.9$, $D = 0.05$ cm⁻¹), whose -centrifugal distortion is large, that is $J(J+1) > B/2D = 589$, so $J \le 24$. The ladder otherwise runs from +are an artefact. For a supplied species with constants close to hydrogen's +($B = 58.9$, $D = 0.05$ cm⁻¹), whose centrifugal distortion is large, that is $J(J+1) > B/2D = 589$, so $J \le 24$. The ladder otherwise runs from `MolecularOptions.min_j` to `max_j` (default 0 and 50), and the populations are normalised over the levels retained. diff --git a/docs/guide/media/raman-numerics.md b/docs/guide/media/raman-numerics.md index 4802240c1..5af3e9549 100644 --- a/docs/guide/media/raman-numerics.md +++ b/docs/guide/media/raman-numerics.md @@ -23,8 +23,9 @@ implements The factor of one half is the cycle average of $\cos^2$: $E^2$ and $\tfrac12\lvert E_a\rvert^2$ agree in their slowly varying part and differ only by the $2\omega_0$ beat. When that beat lies well above the Raman lines, the response suppresses it -strongly. For a 1030 nm pulse in nitrogen the two -field-grid forms give polarisations differing by 2.4 × 10⁻⁴. The `thg` switch therefore +strongly. For a 120 fs, 1030 nm pulse in nitrogen at about one bar (the built-in +response) the two field-grid forms give polarisations differing by 4 × 10⁻⁴ of the +peak. The `thg` switch therefore matters far less for Raman than for Kerr, for that narrowband optical example. At longer wavelengths or with broad mixing bands, compare the beat frequency with the actual Raman spectrum instead. @@ -102,9 +103,11 @@ it differs by 12 % at its peak. **The dephasing is applied per term, per density.** The compiled response keeps separate undamped rows because the dephasing depends on the density, which varies along -a pressure gradient, and a molecular gas has *two* dephasing times: at one bar hydrogen's rotational and vibrational coherences decay -3.5 times apart, and nitrogen's 17 times apart. Summing the models first and damping the -sum once is wrong for every gas with both a rotation and a vibration. The undamped rows, +a pressure gradient, and a molecular gas's lines do not share one dephasing time: at one +bar and 293.15 K hydrogen's strongest rotational line, S(1), decays in 2.9 ns and its +Q(1) vibration in 0.84 ns, 3.4 times faster, and nitrogen's lines each have their own +width, between about 80 and 240 ps. Summing the models first and damping the sum once is +wrong for every gas whose lines have more than one width. The undamped rows, the expensive part, are sampled once per grid; the cheap part is one exponential per term at a decay rate that is a scalar path along z ({func}`solprop.translate.raman.decay_rate_profiles`), and the damped spectrum is diff --git a/docs/guide/media/raman-vector.md b/docs/guide/media/raman-vector.md index ee8e7650b..2972965cd 100644 --- a/docs/guide/media/raman-vector.md +++ b/docs/guide/media/raman-vector.md @@ -37,12 +37,15 @@ These averages are over a **three-dimensional** molecular orientation sphere. Propagating only two transverse field components does not change the factor three to two; embed the transverse $Q$ in three dimensions with zero z entries. -The vibrational model retains only the response of the mean polarisability, which -gives an isotropic (trace) channel. Real diatomic vibrational Raman scattering can also -have anisotropic contributions; those need further strengths and resolved tensor data, -and are absent from the defaults. CH4 and SF6 retain only their totally symmetric bands. -This isotropic vibration and the weak (first-order) rotational response are the model -solprop implements. +A supplied species' vibrational model +({class}`~solprop.physdata.raman_types.MolecularRaman`) retains only the response of the +mean polarisability, which gives an isotropic (trace) channel; with the weak +(first-order) rotational response, that is the model solprop builds from supplied +constants. optmat's built-in responses also carry each vibrational Q line's anisotropic +share, as a rank-two term +([Raman data](raman-data.md#the-same-convention-mapped-onto-terms)), and leave out the +vibrational O and S branches. CH4 and SF6 retain only their totally symmetric bands, which are +isotropic. ## Cartesian tensor and envelope conventions @@ -248,7 +251,7 @@ Replace the declaration with `response_for("H2", selection=MaterialSelection(carrier_wavelength=800e-9))` to include optmat's isotropic and rank-two terms. Add a delayed weak probe to either Cartesian component before evaluation to retain its full history. The deterministic -[vector Raman gallery](../../auto_tutorials/capillaries/plot_06_vector_raman) compares linear +[vector Raman gallery](../../auto_tutorials/capillaries/plot_06_vector_raman.rst) compares linear and circular pumps and an oblique-pump, cross-polarised delayed probe. A launch Jones vector sets the field amplitudes in the **real modal basis**. It does not make the modal profiles complex. The two supported modal diff --git a/docs/guide/media/raman.md b/docs/guide/media/raman.md index 0df6626b6..6db082856 100644 --- a/docs/guide/media/raman.md +++ b/docs/guide/media/raman.md @@ -143,7 +143,7 @@ Placed in a fill by hand, as in `Mixture.fill({"Air": 1.0}, 1.0)`, it contribute Raman response under the default and says nothing; a run that also asks for Kerr is refused (`Air (Air): Air has no Kerr data`), and an explicit `raman=("Air",)` raises. For nonlinear propagation in air use `gas="air"` or `Mixture.air`; the -[air tutorial](../../auto_tutorials/capillaries/plot_04_air_mixture) selects the N₂ +[air tutorial](../../auto_tutorials/capillaries/plot_04_air_mixture.rst) selects the N₂ response alone with `raman=("N2",)`. ### Hand-built problems and free space @@ -174,7 +174,8 @@ the species has it, `True` requires it and is refused by name otherwise, `False` it out. Its `temperature` sets the rotational populations (the run's or mixture's own when `None`, room temperature, 293.15 K, for a bare `response_for`), and `min_j`/`max_j` (default 0 and 50) bound the rotational ladder. A molecular gas's response is absolute -and is refused a `fraction`; silica's is a normalised shape that needs one. +and is refused a `fraction`; silica's is a normalised shape whose magnitude the caller +supplies, as `amplitude` (default 1) or, downstream, as a `fraction`. The compiler ({func}`~solprop.translate.responses.compile_responses`) never applies $(1 - f_R)$ to the Kerr term itself. A response that declares `fraction` is one whose @@ -295,6 +296,6 @@ Hydrogen at one amagat (about 1.09 bar at 293.15 K): optmat's response function The rotational $S(1)$ line at 17.6 THz dominates the low-frequency comb and the vibrational line sits at 124.6 THz, both with the sign that amplifies the Stokes side. -Full runs: the [Raman soliton self-frequency shift in hydrogen](../../auto_examples/processes/plot_05_raman_self_frequency_shift), -the [Raman-comb supercontinuum](../../auto_examples/supercontinuum/plot_04_raman_comb_supercontinuum) -and the [vector Raman tutorial](../../auto_tutorials/capillaries/plot_06_vector_raman). +Full runs: the [Raman soliton self-frequency shift in hydrogen](../../auto_examples/processes/plot_05_raman_self_frequency_shift.rst), +the [Raman-comb supercontinuum](../../auto_examples/supercontinuum/plot_04_raman_comb_supercontinuum.rst) +and the [vector Raman tutorial](../../auto_tutorials/capillaries/plot_06_vector_raman.rst). diff --git a/docs/guide/media/tdse.md b/docs/guide/media/tdse.md index 8fc385e62..9d0bc064a 100644 --- a/docs/guide/media/tdse.md +++ b/docs/guide/media/tdse.md @@ -66,7 +66,7 @@ and every higher order stay inside the current, and no optmat Kerr or plasma ter added for these atoms. The shadow is subtracted unscaled, then density and scale enter once. In the internal Fourier convention the projected current enters mode $m$ as $-\mathcal Q_m[\widehat J_{\rm NL}]/(2\epsilon_0c\operatorname{Re}n_{{\rm eff},m})$ through -the existing modal projection, which supplies the area weights; a one-mode run still +the modal projection, which supplies the area weights; a one-mode run still integrates the actual radial field. No mean, pulse area or residual current is removed. Two research policies for SAE, `"optmat_cubic"` and `"tdse_shadow"`, instead subtract @@ -249,7 +249,7 @@ repeated as a noise ensemble, and its checks are coherent. Input shot noise (`noise="input"`) can be asked for, with a warning; its draw is part of the launch, so the atom is driven by the pulse plus the draw, inside the same gated window and on the same active band, and the realisation is stored with the run like any other -([SEP 37](../../dev/seps/archive/sep-0037-noise-and-stepper-defaults.md), section 6). One photon +([SEP 37](https://github.com/LupoLab/solprop/blob/main/docs/dev/seps/archive/sep-0037-noise-and-stepper-defaults.md), section 6). One photon per bin drives the atom far below the weak-field consistency check's intensity, where its response is the certified linear one. `noise="modified"` is refused: its draw is kept apart from the field the atom is driven by. Each radial node is one atom in every call, so the node @@ -369,4 +369,4 @@ See also §10.6 of the primer's [ionisation chapter](../../primer/ionisation.md) [radial nodes for expensive responses](../waveguides/radial-quadrature.md), and the API reference of {mod}`solprop.nonlinear.tdse`, {mod}`solprop.driver.tdse` and {mod}`solprop.driver.tdse_consistency`. The native backend's TDSE response and the provider's -worker process are [SEP 49](../../dev/seps/archive/sep-0049-tdse-on-native.md). +worker process are [SEP 49](https://github.com/LupoLab/solprop/blob/main/docs/dev/seps/archive/sep-0049-tdse-on-native.md). diff --git a/docs/guide/numerics/adams.md b/docs/guide/numerics/adams.md index 1ad30202c..8f2d6d009 100644 --- a/docs/guide/numerics/adams.md +++ b/docs/guide/numerics/adams.md @@ -16,7 +16,7 @@ comparison, and [accuracy](accuracy.md) explains what to refine. This chapter gives configuration, equations, interpolation and restart behaviour, and limitations. Its design record is -[SEP 16](../../dev/seps/archive/sep-0016-unified-multistep.md). +[SEP 16](https://github.com/LupoLab/solprop/blob/main/docs/dev/seps/archive/sep-0016-unified-multistep.md). ## Using it @@ -141,21 +141,6 @@ and the full canonical and RDW runs 8 and 4 per cent fewer calls. The interactio unchanged: its history is carried through the propagators, whose stiffness the collar alone does not describe, and the cap cost it calls. -### What was compared - -SEP 13 also ran these variants. They were removed once the selection was settled: - -- **PECE**, which spends a second call at the corrected field; -- **plain Adams–Bashforth**, with an a-posteriori recheck; -- **matched predictor–corrector pairs**, controlled by Milne's estimate. - -None of them used fewer calls at the same accuracy on any case: - -- PECE does not repay its second call. -- The matched pairs underestimate their error at loose tolerances, and their small - stability regions meet the temporal collar first. -- Plain Adams–Bashforth takes about as many steps as PEC, but is less accurate. - ## The exponential formulation `Multistep(formulation="exponential")` keeps the predict–evaluate–correct recurrence, @@ -199,12 +184,10 @@ history is the one a polynomial follows: in the laboratory frame, thousands of radians per metre in a dense gas. Neither formulation makes it smooth; [the carrier frame](#the-carrier-frame) does. -On the scalar witnesses of `tests/stepper/test_exponential_scalar_march.py` the first -case gives the exponential formulation errors of $10^{-11}$ where the interaction +On scalar witnesses the first case gives the exponential formulation errors of $10^{-11}$ where the interaction picture's are of order one, at $|\operatorname{Im}D|h$ up to ten; the second gives the opposite. Real problems mix both, which is why the choice is measured per regime -rather than assumed. On a second-order soliton (`tests/backends/test_exponential_march.py`) -the populated bins converge at order $q+1$ in both formulations, the exponential one +rather than assumed. On a second-order soliton the populated bins converge at order $q+1$ in both formulations, the exponential one 30 to 200 times more accurately; but the weak wings, more than $10^8$ below the peak power, hold free radiation under the soliton's cross-phase modulation, a source linear in each bin's own field, and there the exponential formulation converges only at about @@ -212,25 +195,11 @@ order 0.6 once $|\operatorname{Im}D|h$ exceeds one, where the interaction pictur converges at order three to four. The step-size norm does not see bins that weak; a weak-band observable is scored separately for that reason. -**The moments.** $\varphi_0\ldots\varphi_{q+2}$ are formed once per trial for every -element, by a scaled Taylor series and doubling for $|x| \le 3$ and an upward -recurrence beyond, and every formula of the trial — predictor, corrector, the -neighbouring orders' estimates, an interpolated plane — is applied in the monomial -basis of its interpolant, so no per-node weight array is formed. Checked against -augmented matrix exponentials and quadrature, each moment is within a few hundred ulp -of its scale, so the coefficients add nothing measurable to a step's error and no term -for them enters the error norm. - **What it measured** (short windows, one thread, at common worst-plane field and weak-band errors from 1e-3 to 1e-5). On the six-mode hydrogen comb-to-continuum launch, a -Raman-active source that is costly to evaluate, it took 2.0 to 3.3 times less time -than IP-DOPRI5 and 1.5 to 2.5 times less than the interaction formulation on -the since-retired `numba_cpu` backend, and won on native CPU too. On developed GNLSE -supercontinuum windows it -took two to five times fewer calls than both and, from 3e-4 to 1e-5, 3 to 36 % less -time than IP-DOPRI5 and 8 to 31 % less than the interaction formulation, again on -`numba_cpu`; at 1e-3 the interaction formulation was as fast. -Where the source is cheap and the state small — a radial beam with Kerr alone — its +Raman-active source that is costly to evaluate, it took less time than IP-DOPRI5 and the +interaction formulation on native CPU. On developed GNLSE supercontinuum windows it took +two to five times fewer calls than both. Where the source is cheap and the state small — a radial beam with Kerr alone — its per-step arithmetic outweighs the calls it saves and the interaction formulation is faster. [Choosing a stepper](choosing-a-stepper.md#measured) ranks the methods on full runs, on the native backend's CPU build and on devices. Beside the @@ -277,7 +246,7 @@ limit (below) can set the step instead: with it, a 2 cm gradient held the Adams near 30 µm, where the per-step collar needed 18 times fewer attempts. The per-step collar is the remedy only when the collar holds no field. Treating the compensation in the untransported frame instead is kept only as a test witness: where the compensation dominates, its error is -under-reported to the controller ([SEP 16](../../dev/seps/archive/sep-0016-unified-multistep.md) +under-reported to the controller ([SEP 16](https://github.com/LupoLab/solprop/blob/main/docs/dev/seps/archive/sep-0016-unified-multistep.md) §4.2, Q8). **Where it runs.** On `numpy_ref` and native CPU, for the constant @@ -406,11 +375,11 @@ reference element, one number a step, so nothing is read back from the engine, a accepted step's $\sigma$ is held for its interpolated planes. It follows `numpy_ref` to rounding on matched steps. On ten replayed steps of a dense-gas capillary each step cost 4–6 % more than the unshifted method's with a cheap Kerr source and under 1 % more -with Raman ([benchmarks](../../dev/benchmarks.md)); the policy pays for itself only +with Raman ([benchmarks](../../dev/benchmarks.md#adams-carrier-frame-per-step)); the policy pays for itself only through the steps it saves. **What it measured.** On short windows of the benchmark suite's cases -([SEP 35](../../dev/seps/archive/sep-0035-carrier-frame-exponential-adams.md) Part II) — the +([SEP 35](https://github.com/LupoLab/solprop/blob/main/docs/dev/seps/archive/sep-0035-carrier-frame-exponential-adams.md) Part II) — the launch from the input plane and a developed window started from a plane of an earlier run, each against IP-DOPRI5 three orders tighter, one thread — the one-thread time each method needs at matched error in the total field and in the weak bins, as a ratio to @@ -474,7 +443,7 @@ left the comb-to-continuum's self-phase-modulated light above $2\omega_0$ and th fundamental band of an envelope run with the third harmonic several times less accurate, and with a boundary set from the launched spectrum it was the scalar shift everywhere but one launch window -([SEP 35](../../dev/seps/archive/sep-0035-carrier-frame-exponential-adams.md) §7.4). +([SEP 35](https://github.com/LupoLab/solprop/blob/main/docs/dev/seps/archive/sep-0035-carrier-frame-exponential-adams.md) §7.4). ## Stability, and the temporal collar @@ -519,10 +488,10 @@ the collar holds field. collar treatment would buy nothing beyond it (SEP 16 Q4). - **For such runs keep the in-stage collar**, the modal routes' default. With it, the interaction formulation needed about 2.4 times fewer calls than IP-DOPRI5 on the RDW case at - Luna's tolerance. [SEP 14](../../dev/seps/archive/sep-0014-stepper-efficiency.md) + Luna's tolerance. [SEP 14](https://github.com/LupoLab/solprop/blob/main/docs/dev/seps/archive/sep-0014-stepper-efficiency.md) studied a second-order split and did not adopt it: with a Kerr source it is first order wherever the collar holds field. An implicit collar is an open question of - [SEP 15](../../dev/seps/archive/sep-0015-exponential-adams.md). + [SEP 15](https://github.com/LupoLab/solprop/blob/main/docs/dev/seps/archive/sep-0015-exponential-adams.md). The higher orders' tiny imaginary-axis intervals are why variable order settles at orders two and three on the canonical capillary. On the measured runs the Kerr phase a @@ -588,7 +557,7 @@ uninterrupted run's computation, between planes too when it stopped at a termina checkpoint (a spent call budget, a failed source), and agrees with it within its accuracy envelope: to rounding while the steps are the same, and to the tolerance where a rounding difference changes an adaptive step, as one occasionally does. solprop does -not promise identical bits ([SEP 25](../../dev/seps/archive/sep-0025-rounding-level-reproducibility.md)). That is what makes a run +not promise identical bits ([SEP 25](https://github.com/LupoLab/solprop/blob/main/docs/dev/seps/archive/sep-0025-rounding-level-reproducibility.md)). That is what makes a run with a minutes-long source cheap to continue ([ADR-046](../../dev/decisions.md)). The native backend keeps its history resident and copies it to the host only for the snapshot. Without a snapshot -- `resume_history=False`, an unreadable one, or one @@ -614,7 +583,7 @@ SEP 13 counted the calls of the interaction formulation on the canonical helium capillary (4.2 m, steady fill peaking at 0.2 bar, 6 fs and 1 mJ at 800 nm, compressing to 1.25 fs, 50 save planes), in full-length runs scored at every plane against a converged reference. They are the method's call economy; run time, the exponential -formulation and the compiled backends are in [choosing a stepper](choosing-a-stepper.md). +formulation and the native backend are in [choosing a stepper](choosing-a-stepper.md). | Method | `rtol` | source calls | field error in the window | peak power | UV-band field | |---|---|---|---|---|---| @@ -643,11 +612,11 @@ times at loose and medium accuracy, falling to about two at the tightest: - 443 calls (PEC3/4) against 1001 (IP-DOPRI5) for a window error near 3e-3; - 594 calls (PEC4/5) against 1176 for 5e-4. -On a cheap source, calls are not run time. On the compiled backends one source +On a cheap source, calls are not run time. On the native backend one source evaluation can cost less than a Runge–Kutta step's own linear work, and the Adams march takes more steps, so the call saving shrinks in wall time or disappears: a single-mode capillary, a coupled wall. On `native` the `Multistep()` controller runs -natively as well ([SEP 39](../../dev/seps/archive/sep-0039-native-adams-march.md)), +natively as well ([SEP 39](https://github.com/LupoLab/solprop/blob/main/docs/dev/seps/archive/sep-0039-native-adams-march.md)), so a step costs its kernels and almost no Python. [Choosing a stepper](choosing-a-stepper.md) gives the measured ranking by regime, on the native backend's CPU build and on devices. @@ -663,8 +632,8 @@ gives the measured ranking by regime, on the native backend's CPU build and on d replayed, on every route it admits, and what it does not step is refused by name before the run starts. It takes the same steps as solprop's reference march. - **Resume across backends.** A frozen-residual coupled flow's history is kept in a - native form on `native` and as per-sample weights on the host engines, so its snapshot - continues only on a backend of the same kind; a resume elsewhere starts the history + native form on `native` and as per-sample weights on `numpy_ref`, so its snapshot + continues only on the backend that wrote it; a resume elsewhere starts the history afresh and says why. Every other history crosses between backends. - **Memory.** The history holds from seven (`numpy_ref`, constant operator) to about sixty (`native`, a varying operator) further copies of the state. On a capillary the @@ -703,7 +672,7 @@ gives the measured ranking by regime, on the native backend's CPU build and on d fixed for the run and added to each sample's field at that sample's own position, never to the propagating state, so conditional on the draw the source is a deterministic function of position, which the history interpolates - ([SEP 16](../../dev/seps/archive/sep-0016-unified-multistep.md) §4.4), on every backend. + ([SEP 16](https://github.com/LupoLab/solprop/blob/main/docs/dev/seps/archive/sep-0016-unified-multistep.md) §4.4), on every backend. Interpolated planes are refused beside it for every stepper. - **A prescribed schedule** is replayed with either formulation: its steps are taken as given and accepted, the predictor–corrector estimate is still computed and @@ -723,7 +692,7 @@ gives the measured ranking by regime, on the native backend's CPU build and on d time-dependent Schrödinger equation. The carrier frame on this page was proposed, measured and delivered by -[SEP 35](../../dev/seps/archive/sep-0035-carrier-frame-exponential-adams.md). +[SEP 35](https://github.com/LupoLab/solprop/blob/main/docs/dev/seps/archive/sep-0035-carrier-frame-exponential-adams.md). The native march, which runs the `Multistep()` controller in the compiled backend, was proposed, measured and delivered by -[SEP 39](../../dev/seps/archive/sep-0039-native-adams-march.md). +[SEP 39](https://github.com/LupoLab/solprop/blob/main/docs/dev/seps/archive/sep-0039-native-adams-march.md). diff --git a/docs/guide/numerics/boundaries.md b/docs/guide/numerics/boundaries.md index 7d98eb4c1..409daaaa4 100644 --- a/docs/guide/numerics/boundaries.md +++ b/docs/guide/numerics/boundaries.md @@ -108,7 +108,7 @@ represent it as a rate: - {py:func}`solprop.boundaries.nonlinear_absorber_term` — add `−α(t)E(t)/2` inside every stage, with its own modal transform, masked to the active band. **This is the default on the modal routes** (capillary, waveguide and GNLSE). -- {py:func}`solprop.boundaries.apply_split_step` — multiply the modal time-domain field by +- the split step — the backend multiplies the modal time-domain field by `exp(−α(t)h/2)` once per accepted step, followed by the hard band limit, because the product in time spreads content into every bin (on a field grid, chiefly the DC). One batched transform pair per step; the factors telescope, so the total is a rate @@ -302,7 +302,7 @@ since by the Planck taper's symmetry `W(x) + W(w − x) = 1` each edge of width window, and a packet re-enters the flat region only after crossing both. With `Γ = log(10³)`, the condition {py:func}`~solprop.boundaries.warn_walkoff` checks, the default strength `A·boundary_N = 252` stops a drift of `252 w/(2Γ) = 18.2 w` -([SEP 21](../../dev/seps/archive/sep-0021-absorbing-boundaries.md) §4.2). +([SEP 21](https://github.com/LupoLab/solprop/blob/main/docs/dev/seps/archive/sep-0021-absorbing-boundaries.md) §4.2). ```python drift = 1.5e-12 # s, over the grid's length @@ -336,7 +336,7 @@ The sizing assumes a steady drift over the run, as `warn_walkoff` does. Walk-off late, after fission or as a soliton decelerates, crosses faster than the mean and is absorbed less, so the [monitor](#watching-the-windows-edges) stays the measurement. The default strength stays what it is for that reason: weak light that walks far needs its margin -([SEP 21](../../dev/seps/archive/sep-0021-absorbing-boundaries.md), decision D3). +([SEP 21](https://github.com/LupoLab/solprop/blob/main/docs/dev/seps/archive/sep-0021-absorbing-boundaries.md), decision D3). ```{eval-rst} .. plot:: @@ -345,7 +345,7 @@ strength stays what it is for that reason: weak light that walks far needs its m import numpy as np import matplotlib.pyplot as plt - from solprop.boundaries import absorber, split_step_factor + from solprop.boundaries import absorber from solprop.grid import FieldGrid grid = FieldGrid.from_limits(1.5, 800e-9, (90e-9, 4e-6), 400e-15) @@ -379,7 +379,7 @@ strength stays what it is for that reason: weak light that walks far needs its m distance = 0.3 counts = np.array([1, 2, 5, 10, 20, 50, 100, 200, 500, 1000]) as_a_rate = [ - float(np.prod(split_step_factor(np.array([alpha]), distance / n) ** n)) + float(np.exp(-0.5 * alpha * distance / n) ** n) for n in counts ] ax_steps.loglog(counts, as_a_rate, "o-", label="as a rate") @@ -406,7 +406,7 @@ method can take ([the stable step](#the-two-temporal-schemes)). A measurement th a strong spectral absorber should not pay for it in steps. So {py:class}`~solprop.boundaries.Absorber` carries two lengths -([SEP 22](../../dev/seps/archive/sep-0022-memory-lean-spatial-execution.md) §4.6): +([SEP 22](https://github.com/LupoLab/solprop/blob/main/docs/dev/seps/archive/sep-0022-memory-lean-spatial-execution.md) §4.6): - `reference_length`, `ℓ`, sets the spectral rate and its ceiling `60/ℓ`; - `collar_length`, `ℓ_c`, sets the in-stage temporal collar — its largest rate is @@ -423,10 +423,10 @@ and the collars do not. `collar_length` is whatever sets the temporal collar's strength: `walkoff`, when [it is given](#sizing-the-collar-from-a-walk-off), or else `boundary_N` or `boundary_length`. Nothing but the temporal collar reads it. A free-space run's real-space collar, which -[SEP 21](../../dev/seps/archive/sep-0021-absorbing-boundaries.md) and -[SEP 22](../../dev/seps/archive/sep-0022-memory-lean-spatial-execution.md) expected to share +[SEP 21](https://github.com/LupoLab/solprop/blob/main/docs/dev/seps/archive/sep-0021-absorbing-boundaries.md) and +[SEP 22](https://github.com/LupoLab/solprop/blob/main/docs/dev/seps/archive/sep-0022-memory-lean-spatial-execution.md) expected to share this length, is designed from its own protected band -([SEP 40](../../dev/seps/archive/sep-0040-transverse-absorbing-boundaries.md)), so a walk-off +([SEP 40](https://github.com/LupoLab/solprop/blob/main/docs/dev/seps/archive/sep-0040-transverse-absorbing-boundaries.md)), so a walk-off moves no transverse strength. ### A custom spectral absorber @@ -662,20 +662,20 @@ pair, and the first-same-as-last stage recycled. `absorber_scheme` is still reco applies to nothing, and its refusal of interpolated planes does not fire. The grid is unchanged. Measured on a Cartesian envelope grid of 192 × 192 × 300 with a spectral-only collar, the pass that compiling away removes cost 1.2–1.6 times a step on native CPU -([SEP 22](../../dev/seps/archive/sep-0022-memory-lean-spatial-execution.md) §3; the phase-1 +([SEP 22](https://github.com/LupoLab/solprop/blob/main/docs/dev/seps/archive/sep-0022-memory-lean-spatial-execution.md) §3; the phase-1 re-measurement is in its -[implementation record](../../dev/seps/archive/sep-0022-memory-lean-spatial-execution.md#phase-1-report--driver-output-and-absorber)). Under the in-stage +[implementation record](https://github.com/LupoLab/solprop/blob/main/docs/dev/seps/archive/sep-0022-memory-lean-spatial-execution.md#phase-1-report--driver-output-and-absorber)). Under the in-stage scheme the zero rate only added zeros, so a run is unchanged; under the split it differs by the transform pair's rounding. A spectral-only collar is passed as `absorber=absorber(grid, temporal=False)`; a keyword that turns both soft collars off on the fibre entry points is -[SEP 21](../../dev/seps/archive/sep-0021-absorbing-boundaries.md)'s. +[SEP 21](https://github.com/LupoLab/solprop/blob/main/docs/dev/seps/archive/sep-0021-absorbing-boundaries.md)'s. ### The transverse boundary The collars above act on time and frequency. A free-space run's transverse boundary is -its own ([SEP 40](../../dev/seps/archive/sep-0040-transverse-absorbing-boundaries.md)): a wall or a +its own ([SEP 40](https://github.com/LupoLab/solprop/blob/main/docs/dev/seps/archive/sep-0040-transverse-absorbing-boundaries.md)): a wall or a wrap at the grid's outer size, a safety ramp in the transverse **wavenumber** on every geometry, which rides the linear operator exactly like the spectral rate, the monitor's transverse edge, and, on request, a designed real-space collar, @@ -708,7 +708,7 @@ The spatial routes apply the temporal collar by the split scheme unless the sett a scheme or interpolate their planes, which the split refuses: on the spatial cases of the performance-tracking suite the in-stage collar took 1.2 to 4.6 times the steps of the split one, at equal or worse accuracy inside the requested window -([SEP 21](../../dev/seps/archive/sep-0021-absorbing-boundaries.md)). The split is unconditionally +([SEP 21](https://github.com/LupoLab/solprop/blob/main/docs/dev/seps/archive/sep-0021-absorbing-boundaries.md)). The split is unconditionally stable, so a fixed schedule on a spatial route keeps its collar, within the split's [crossing limit](#the-two-temporal-schemes). @@ -727,7 +727,7 @@ through `SimulationSettings.boundary_check`). At the launch and at every committ measures the share of the field's energy in the outer 5 % of the realised window at each edge, the guards, and in the collar. The energy is the time-domain density summed over modes, polarisations and transverse columns with their quadrature weights, the proxy of -[SEP 21](../../dev/seps/archive/sep-0021-absorbing-boundaries.md) section 4.6: exact for +[SEP 21](https://github.com/LupoLab/solprop/blob/main/docs/dev/seps/archive/sep-0021-absorbing-boundaries.md) section 4.6: exact for modal true-power amplitudes, and on the spatial routes the quadrature-weighted field norm rather than the admittance-weighted flux. Every reading is a share, so the proxy's scale cancels. @@ -837,7 +837,7 @@ and the floor's expected removal (`floor_removed_fraction`), so that a resume co from the same numbers the whole run would hold. On a free-space run the monitor also watches the **transverse edge** -([SEP 40](../../dev/seps/archive/sep-0040-transverse-absorbing-boundaries.md)): the energy in the +([SEP 40](https://github.com/LupoLab/solprop/blob/main/docs/dev/seps/archive/sep-0040-transverse-absorbing-boundaries.md)): the energy in the outer 5 % of the grid's outer size above its launch value with no collar, and what returns with a requested one, at `BoundaryCheck`'s levels or its own `transverse_budget`, which relaxes the transverse edge without relaxing time. Its reads are spaced as a ceiling @@ -854,13 +854,13 @@ does, has an error floor of its own that is not the boundary's. Light the Kerr e generates at the low-frequency edge of the band sits where the spectral collar and the band mask are sampled on frequency bins, and those bins move with the bin spacing, so two runs on different windows differ at first order in the window factor even when no -light reaches an edge. [SEP 21's phase 0a](../../dev/seps/archive/sep-0021-absorbing-boundaries.md#phase-0a--decisions-and-interim-findings) +light reaches an edge. [SEP 21's phase 0a](https://github.com/LupoLab/solprop/blob/main/docs/dev/seps/archive/sep-0021-absorbing-boundaries.md#phase-0a--decisions-and-interim-findings) measured it (figures not re-run since): - widening the band from 1.6 to 3.2 µm cut the energy at its edge from 2.5e-3 to 1.4e-6, and the term about threefold; - it floors a comparison between requested windows at order 1e-5, 1.9e-5 on that - study's canonical case ([findings](../../dev/seps/archive/sep-0021-absorbing-boundaries.md#phase-0a-report--2026-10-25), item 1); + study's canonical case ([findings](https://github.com/LupoLab/solprop/blob/main/docs/dev/seps/archive/sep-0021-absorbing-boundaries.md#phase-0a-report--2026-10-25), item 1); - field errors near 1e-4 between smooth windows were this term, not the boundary. Under `fft_size="auto"` neighbouring requests realise different sizes @@ -873,7 +873,7 @@ $2F(2M) - F(M)$ for a window factor $M$, as SEP 21 did. ```{code-block} python import numpy as np -from solprop.boundaries import absorber, apply_band_mask, apply_split_step, warn_walkoff +from solprop.boundaries import absorber, warn_walkoff from solprop.grid import FieldGrid grid = FieldGrid.from_limits(1.5, 800e-9, (90e-9, 4e-6), 400e-15) @@ -883,10 +883,10 @@ boundary = absorber(grid, boundary_N=20) # is applied to the time-domain field once per accepted step: the `split_step` scheme, # which `absorber_scheme="split_step"` selects (the default applies it in every stage). field = np.ones((1, 1, grid.n_t)) -field = apply_split_step(field, boundary.temporal_rate, step=0.01) +field = field * np.exp(-0.5 * boundary.temporal_rate * 0.01) # The hard band limit is a separate, idempotent multiply on the spectrum. -spectrum = apply_band_mask(np.ones((1, 1, grid.n_omega)), boundary.band_mask) +spectrum = np.where(boundary.band_mask, np.ones((1, 1, grid.n_omega)), 0.0) # And the run says so if the absorber is too weak for the walk-off it will produce. warn_walkoff(grid, group_delay_span=1e-12) # SolpropWarning: widen trange, or ... diff --git a/docs/guide/numerics/choosing-a-stepper.md b/docs/guide/numerics/choosing-a-stepper.md index 0e10449a0..7d13550e8 100644 --- a/docs/guide/numerics/choosing-a-stepper.md +++ b/docs/guide/numerics/choosing-a-stepper.md @@ -19,7 +19,7 @@ a problem that wants another one. ## The defaults Each interface has its own default integrator and tolerances. All but one were chosen by -[SEP 37](../../dev/seps/archive/sep-0037-noise-and-stepper-defaults.md)'s rule: the fastest +[SEP 37](https://github.com/LupoLab/solprop/blob/main/docs/dev/seps/archive/sep-0037-noise-and-stepper-defaults.md)'s rule: the fastest method at matched accuracy on the benchmark suite's cases for that interface, with noise on and off, among the methods every route of the interface admits. The capillary is the exception: the rule prefers `RungeKutta()` there, and `prop_capillary` keeps @@ -58,41 +58,25 @@ on this page about each method's tolerance was measured at the levels it names, `rtol=` beside `integrator=` when you change the method; for instance, the capillary's Runge–Kutta comparison below is at `1e-5`. -On the GNLSE, the Runge–Kutta march is 2.5 to 4.8 times faster than the exponential -Adams method at matched accuracy, more with noise. On the waveguide route it is 4 times -faster; the interaction-formulation Adams method is faster still there but refuses the -coupled flows some waveguide routes carry. On the capillary the Adams method is the -default for every representation, by the maintainer's decision against the rule -([ADR-055](../../dev/decisions.md)): it wins the runs the capillary is mostly used for, -and loses the single-mode runs with plasma or Raman. With several resolved modes the -source beats at the modes' phase mismatches: the interaction-picture march has to -resolve that beat within its steps (going from one resolved mode to four multiplies its -steps by 3.6 on the RDW capillary), while the exponential Adams method carries it in its -propagator and is 2.1 to 2.2 times faster there at its 1e-6 than the Runge–Kutta march at -its 1e-5. With one mode, or a mode-averaged one, the Adams method at 1e-6 was 1.35 to 3 -times faster than the Runge–Kutta march at 1e-5 on the Kerr-only worked examples, and -more accurate (on self-phase modulation in argon, a field error of 4e-5 against 3e-4). -It spends one response evaluation per step where the Runge–Kutta march spends six, so -an expensive response widens the gap. The dispersive Kerr policies -(`MaterialSelection(electronic="symmetric-kerr")` or `"gas-polynomial"`) cost more per -evaluation than the carrier Kerr default: on a single-mode argon four-wave-mixing scan -with them, the Adams method was 3.6 times faster. On one mode or a mode-averaged one -with Raman or plasma, `RungeKutta()` is the faster choice: about twice as fast at 1e-5 on -the ionisation blueshift example, and 1.1 to 2.9 times on the benchmark suite's -single-mode and mode-averaged capillary cases, at a field error still far inside the -spectral budget below. There the Adams method needs about as many source calls as the -Runge–Kutta march, and on a cheap source each of its steps costs up to about twice a -Runge–Kutta stage. The TDSE response runs only on `Multistep()`. The radial and -planar defaults hold their methods, which are faster there than the Runge–Kutta march -(by 1.4 to 2.4 times on the radial filament), and set a tolerance where the caller gave -no controller. A free-space run takes the Runge–Kutta march: the Adams history's -memory rules the multistep method out for a large transverse state. Its tolerance is -looser because the spectrum never set it: on a Cartesian Kerr beam near self-focusing, -every level from 1e-3 to 1e-6 kept the spectrum within 0.002 dB of a tight reference, -and 1e-4 was taken for a field error 2.5 times smaller than at 1e-3. The adaptive march -needs no step calibration, and on that beam it was 26 to 53 times faster than a -0.5 µm fixed RK4IP schedule. A fixed `LowStorageRungeKutta()` step calibrated to the -same error is cheaper still, by about 1.6 times, and uses about half the memory. +Each default is the faster method on its interface's usual runs ([measured](#measured) +below, and the [gallery](#the-gallery)). On the capillary the Adams method is the default +for every representation, by the maintainer's decision against the rule +([ADR-055](../../dev/decisions.md)): it wins the runs the capillary is mostly used for and +loses the single-mode runs with plasma or Raman. With several resolved modes the source +beats at the modes' phase mismatches, which the interaction-picture march has to resolve +within its steps and the exponential Adams method carries in its propagator (2.1 to 2.2 +times faster on the RDW capillary at its 1e-6 than the Runge–Kutta march at its 1e-5); it +spends one response evaluation per step where the Runge–Kutta march spends six, so an +expensive response widens the gap. On one mode or a mode-averaged one with Raman or +plasma, `RungeKutta()` is the faster choice: there the Adams method needs about as many +source calls, and on a cheap source each of its steps costs up to about twice a +Runge–Kutta stage. The TDSE response runs only on `Multistep()`. The radial and planar +defaults hold their methods, which are faster there than the Runge–Kutta march, and set a +tolerance where the caller gave no controller. A free-space run takes the Runge–Kutta +march: the Adams history's memory rules the multistep method out for a large transverse +state. Its tolerance is looser because the spectrum never set it: on a Cartesian Kerr +beam near self-focusing, every level from 1e-3 to 1e-6 kept the spectrum within 0.002 dB +of a tight reference. The tolerances were set by a convergence test: the loosest of three levels a decade apart at which a seeded ensemble's mean spectrum stays within 0.5 dB, above −40 dB of @@ -168,7 +152,7 @@ the Adams method pays it for each call, and adds its history's arithmetic. When dominates — a multimode transform pair, an ionisation rate, a Raman convolution, a transverse transform — fewer calls is less time, nearly in proportion. When a call is a few fast Fourier transforms of a single mode, the step's own work weighs as much, and -three times fewer calls can be slower. The compiled backends make calls cheap, which is +three times fewer calls can be slower. The native backend makes calls cheap, which is why the ranking is measured per backend rather than read off the call count. **How complicated the nonlinearity is.** A richer response costs more per call, which @@ -211,7 +195,7 @@ its steps. Indicative ratios at matched error against a converged reference, one thread on a shared Darwin/arm64 workstation (the [gallery](#the-gallery) below has every point, and the -devices; [the benchmark notes](../../dev/benchmarks.md#indicative-results) say how to read +devices; [the benchmark rules](../../dev/benchmarks.md#rules) say how to read such ratios). Ratios are the Runge–Kutta march's time over the default's: above one, the default is faster. @@ -272,7 +256,7 @@ doesn't fit fails with an out-of-memory error `LowStorageRungeKutta()` is the classical fourth-order Runge–Kutta method in the interaction picture anchored at each step's midpoint, Hult's RK4IP -([SEP 24](../../dev/seps/archive/sep-0024-low-storage-interaction-picture-runge-kutta.md)). Only +([SEP 24](https://github.com/LupoLab/solprop/blob/main/docs/dev/seps/archive/sep-0024-low-storage-interaction-picture-runge-kutta.md)). Only forward half-step flows are applied, and on a constant operator one factor $e^{hD/2}$ serves every one of them. Each slope is folded into a running sum as soon as it is produced, so beside the source pipeline's scratch a step needs three copies of @@ -311,8 +295,8 @@ signal between a step's first source evaluation and its commit leaves a state th neither end of the step. The backend then refuses to be observed or stepped until a state is loaded again, and the run writes no terminal checkpoint, saying why: the file ends at its last saved plane, from which `resume=True` continues, and `step_planes=k` -bounds the loss to `k` steps. A last plane that kept no field is held by the backend, -one more copy of the state, and checkpointed instead +bounds the loss to `k` steps. A file whose last plane kept no field cannot be resumed +from there (`resume=True` refuses it by name), so keep the field at some planes ([field retention](../results/output.md)). A field that diverges is caught on the accepted state, in flight, with the same consequence. The march also watches its own stiffness: when the indicator $h\rho$ of SEP 24 §6.3 passes 2.785 on a step -- strong plasma loss near @@ -419,5 +403,5 @@ A planar guide: two slab modes. {download}`CSV <../figures/stepper-gallery/plana ``` The qualification on this page was proposed and carried out by -[SEP 16](../../dev/seps/archive/sep-0016-unified-multistep.md); the dense-gas advice -comes from [SEP 35](../../dev/seps/archive/sep-0035-carrier-frame-exponential-adams.md). +[SEP 16](https://github.com/LupoLab/solprop/blob/main/docs/dev/seps/archive/sep-0016-unified-multistep.md); the dense-gas advice +comes from [SEP 35](https://github.com/LupoLab/solprop/blob/main/docs/dev/seps/archive/sep-0035-carrier-frame-exponential-adams.md). diff --git a/docs/guide/numerics/fixed-schedules.md b/docs/guide/numerics/fixed-schedules.md index b477b019d..64df19ff0 100644 --- a/docs/guide/numerics/fixed-schedules.md +++ b/docs/guide/numerics/fixed-schedules.md @@ -9,7 +9,7 @@ accurate. It wins outright in three places: for ensembles, where identical steps the numerical error a common systematic that cancels between members instead of a per-member variance that adds; for repeat calculations and debugging, since a replayed run takes the recorded steps and meets the original run's accuracy target (it need not -reproduce its bits, [SEP 25](../../dev/seps/archive/sep-0025-rounding-level-reproducibility.md)); +reproduce its bits, [SEP 25](https://github.com/LupoLab/solprop/blob/main/docs/dev/seps/archive/sep-0025-rounding-level-reproducibility.md)); and on a device, where there is nothing to synchronise. Both modes are therefore first class. @@ -147,7 +147,7 @@ A stability limit belongs to the integrator, `Multistep()`'s being far shorter t `RungeKutta()`'s, so run the discovery with the integrator the replay will use: the printed limit is computed for it. -A requested spatial collar on a spatial route ([SEP 40](../../dev/seps/archive/sep-0040-transverse-absorbing-boundaries.md)) +A requested spatial collar on a spatial route ([SEP 40](https://github.com/LupoLab/solprop/blob/main/docs/dev/seps/archive/sep-0040-transverse-absorbing-boundaries.md)) adds three more limits on a replayed step: its own stable step, which also depends on the integrator, and the fixed-schedule crossing and damping bounds, which do not. An adaptive run is held only to the looser adaptive crossing limit, so its history can break them. @@ -190,7 +190,7 @@ mode fails silently. check it on more than the seed that discovered it. A schedule discovered on a noiseless run integrates the seed's own dynamics poorly: on a 20 pJ fibre soliton it got the noise-driven part of the field wrong by 6 % with `RungeKutta()` and 78 % with -`Multistep()` ([SEP 37](../../dev/seps/archive/sep-0037-noise-and-stepper-defaults.md), §3.4). +`Multistep()` ([SEP 37](https://github.com/LupoLab/solprop/blob/main/docs/dev/seps/archive/sep-0037-noise-and-stepper-defaults.md), §3.4). ## The low-storage march diff --git a/docs/guide/numerics/linear-operator.md b/docs/guide/numerics/linear-operator.md index ab101292a..fb5453914 100644 --- a/docs/guide/numerics/linear-operator.md +++ b/docs/guide/numerics/linear-operator.md @@ -273,4 +273,4 @@ the assembly: five digits of $\beta$ are lost to it, so a comparison of two implementations of the operator is best stated against $\beta$ rather than against `D`. The carrier frame's pointer above comes from -[SEP 35](../../dev/seps/archive/sep-0035-carrier-frame-exponential-adams.md). +[SEP 35](https://github.com/LupoLab/solprop/blob/main/docs/dev/seps/archive/sep-0035-carrier-frame-exponential-adams.md). diff --git a/docs/guide/numerics/linear-tables.md b/docs/guide/numerics/linear-tables.md index 209724b71..5bac4f6da 100644 --- a/docs/guide/numerics/linear-tables.md +++ b/docs/guide/numerics/linear-tables.md @@ -96,7 +96,7 @@ evaluated values, as on the host. A position already held, such as a step's end, is the next step's start, is not evaluated again. The compensated Adams march reads $D = \mathrm{d}\Phi/\mathrm{d}z$ from the derivative table in the same way. The GPU builds refuse a table rather than hold it on the device -([SEP 29](../../dev/seps/archive/sep-0029-compiled-backend-distribution.md), §6.6). +([SEP 29](https://github.com/LupoLab/solprop/blob/main/docs/dev/seps/archive/sep-0029-compiled-backend-distribution.md), §6.6). ### Hard kinks, and what caps a step diff --git a/docs/guide/numerics/reproducibility.md b/docs/guide/numerics/reproducibility.md index af5840d64..a8e04cdc5 100644 --- a/docs/guide/numerics/reproducibility.md +++ b/docs/guide/numerics/reproducibility.md @@ -4,7 +4,7 @@ solprop promises numerical accuracy, not identical bits. Two runs of the same pr on different machines, backends, builds or thread counts agree within the accuracy the problem was qualified to; they need not agree in every bit, and the faster code paths depend on that freedom. The policy and its derivations are in -[SEP 25](../../dev/seps/archive/sep-0025-rounding-level-reproducibility.md). +[SEP 25](https://github.com/LupoLab/solprop/blob/main/docs/dev/seps/archive/sep-0025-rounding-level-reproducibility.md). ## What is promised diff --git a/docs/guide/numerics/solver.md b/docs/guide/numerics/solver.md index e2f8398a5..219fc6346 100644 --- a/docs/guide/numerics/solver.md +++ b/docs/guide/numerics/solver.md @@ -60,7 +60,7 @@ longest step and `dz_init` is informational. ## The Runge–Kutta integrator On the native backend the adaptive Runge–Kutta loop runs in compiled code, with solprop's own -loop as its reference ([SEP 45](../../dev/seps/archive/sep-0045-native-rk-march.md)): a run's +loop as its reference ([SEP 45](https://github.com/LupoLab/solprop/blob/main/docs/dev/seps/archive/sep-0045-native-rk-march.md)): a run's metadata records it (`rk_march`). A controller with methods of its own is refused by name on `native` and runs on `numpy_ref`. @@ -201,7 +201,7 @@ below were measured on the test problems the controller was designed on: same step sizes. Norms that differ by rounding — another backend, thread count or build — can produce slightly different steps, or flip an accept/reject decision, so two adaptive runs agree to their accuracy, not bit for bit. A replayed schedule takes the -recorded steps and meets the run's accuracy target ([SEP 25](../../dev/seps/archive/sep-0025-rounding-level-reproducibility.md)). +recorded steps and meets the run's accuracy target ([SEP 25](https://github.com/LupoLab/solprop/blob/main/docs/dev/seps/archive/sep-0025-rounding-level-reproducibility.md)). Asking for a step below `dz_min` raises {py:obj}`~solprop.exceptions.ConvergenceError` rather than clamping and carrying on. A diff --git a/docs/guide/performance/backends.md b/docs/guide/performance/backends.md index bcfe4ff49..f47b065a2 100644 --- a/docs/guide/performance/backends.md +++ b/docs/guide/performance/backends.md @@ -12,7 +12,7 @@ native backend, which `"auto"` selects; `numpy_ref` is for the cases below. | backend | what it is | use it for | |---|---|---| | `native` | the [native backend](native.md), the solprop-native distribution built from the repository's `native/` directory and a required dependency of solprop: OpenMP, FFTW and a vendor BLAS on a CPU, or CUDA/HIP on a GPU | **the one to use**: what `"auto"` selects | -| `numpy_ref` | plain NumPy, the numerical **reference**: every other backend is tested against it. It is unthreaded, and roughly 6 to 40 times slower than threaded native | checking a result, and [the features native does not run](#features-that-run-on-the-reference-backend). Also problems a GPU build refuses or runs slowly, in a process that has only that build | +| `numpy_ref` | plain NumPy, the numerical **reference**: the native backend is tested against it. It is unthreaded, and roughly 6 to 40 times slower than threaded native | checking a result, and [problems a GPU build refuses](#features-that-run-on-the-reference-backend) or runs slowly, in a process that has only that build | ## Which backend a run uses @@ -64,7 +64,7 @@ build, transform plan or device can change floating-point summation order, so cross-backend agreement need not be bitwise. Nor is a repeat on the same build: solprop promises numerical accuracy, not identical bits, across backends, builds, machines, thread counts, batches and repeated runs -([SEP 25](../../dev/seps/archive/sep-0025-rounding-level-reproducibility.md)), and a rounding +([SEP 25](https://github.com/LupoLab/solprop/blob/main/docs/dev/seps/archive/sep-0025-rounding-level-reproducibility.md)), and a rounding difference can change an adaptive run's steps. Small differences can also grow in noise-sensitive propagation: compare the physical observable and numerical convergence, not only an array digest. Record the backend, build and thread @@ -87,27 +87,15 @@ a general waiver: a new feature still lands on both `numpy_ref` and `native` ([SEP 0](../../dev/seps/sep-0000-process.md)), and joins the list only as an accepted exception. -## Retired backends - -solprop has exactly two backends, `native` and `numpy_ref`, and will have no other. It once -had two more: `numba_cpu`, a third double-precision backend whose last release is 0.1.0, -and `mlx`, an experimental single-precision backend for Apple GPUs. Naming either now -raises {py:class}`~solprop.exceptions.BackendError`, naming `native` and `numpy_ref`, as -any name that is neither does, so a script or recipe that selects one needs -`backend="native"`, or no `backend=` at all. A run started on a release that had the -backend finishes on that release. - -The settings of `numba_cpu` are gone too: `SOLPROP_NUMBA_THREADS`, `SOLPROP_NUMBA_REGIME`, -`SOLPROP_FFTW_THREADS`, `SOLPROP_TRANSVERSE_FFTW_THREADS`, `SOLPROP_PASS_TIMERS`, -`NUMBA_DISABLE_JIT` and `NUMBA_NUM_THREADS` no longer do anything. - ## Which backend to use -Use the native backend. `numpy_ref` is unthreaded and roughly 6 to 40 times slower than -threaded native, so it is for checking a result and for what only it runs; the +solprop has exactly two backends, `native` and `numpy_ref`; any other name raises +{py:class}`~solprop.exceptions.BackendError`, naming the two. Use the native backend. +`numpy_ref` is unthreaded and roughly 6 to 40 times slower than threaded native, so it is +for checking a result and for a problem a GPU build refuses; the [performance history](../../dev/benchmarking.md) records the native backend's own timings. The measurements behind the advice below are in the -[indicative results](../../dev/benchmarks.md#indicative-results); time your own problem for +[current results](../../dev/benchmarks.md#current-performance); time your own problem for ten steps before committing a long campaign to one backend. - **Which native build.** Build the native backend on the machine that runs it, or install a diff --git a/docs/guide/performance/building-native.md b/docs/guide/performance/building-native.md index 40a67f08e..3d6a19456 100644 --- a/docs/guide/performance/building-native.md +++ b/docs/guide/performance/building-native.md @@ -22,7 +22,7 @@ the arithmetic is double precision throughout, and no build enables fast-math. | requirement | version and notes | |---|---| -| Python | 3.14, with NumPy 2.3 or newer, and solprop at the same version installed in the same environment | +| Python | 3.14, with NumPy 2.5 or newer, and solprop at the same version installed in the same environment | | CMake | 3.23 or newer (with build isolation, scikit-build-core fetches one from PyPI if none is found) | | build tool | Ninja is recommended; scikit-build-core uses it when available | | C++20 compiler, macOS | Clang 14 or newer; Homebrew LLVM is recommended and selected by default | @@ -50,7 +50,7 @@ them: The Python build requirements are scikit-build-core 0.11 and nanobind 3.1.0, pinned. CPU builds contract multiply-adds (`-ffp-contract=fast` with GCC, `-ffp-contract=fast-honor-pragmas` with Clang, after `-fno-fast-math`) except in a few protected blocks, as -[SEP 25](../../dev/seps/archive/sep-0025-rounding-level-reproducibility.md) sets out; +[SEP 25](https://github.com/LupoLab/solprop/blob/main/docs/dev/seps/archive/sep-0025-rounding-level-reproducibility.md) sets out; `build_info().compiler_flags` and `optimization_policy` record the setting. GPU builds follow their compilers' defaults throughout ([GPU builds](#gpu-builds)). @@ -145,10 +145,9 @@ native build has the [lightweight setup](../../dev/contributing.md). The editabl install does not rebuild itself: run `uv sync --reinstall-package solprop-native` after a native change, with any build options in `CMAKE_ARGS` ([below](#passing-cmake-options)); a device build is made the same way. `uv run poe -check-native` runs the native gate and `uv run poe check-all` both gates. A build stays -valid across solprop changes until the sources under `native/` change, when `check_build()` -refuses it and names that command, or until `check_build()` names a member the installed -solprop lacks. Running solprop's test lanes +check-native` runs the native gate, and a native change runs it after `uv run poe check`. +A build stays valid across solprop changes until the sources under `native/` change, when +`check_build()` refuses it and names that command. Running solprop's test lanes against the build is in the developer notes on [testing](../../dev/testing.md#tiers-and-backends), and the native package's own tests in `native/README.md`. @@ -189,7 +188,7 @@ python -c "import solprop_native as sn; sn.check_build(); print(sn.build_info(). ``` `python -m solprop_native` prints the build record, `build_info()`, as one sorted JSON -object suitable for a run log: +object suitable for a run log. Its fields include: - **provenance:** `package_version`, `git_commit` (with `+dirty` for a modified tree), `source_digest` (the SHA-256 of the C++ sources, `CMakeLists.txt` and the CMake modules @@ -197,7 +196,7 @@ object suitable for a run log: `solprop_version_built_against`; - **dependencies:** `kokkos_version`, `kokkos_kernels_version`, `kokkos_fft_version`, `nanobind_version`; -- **profile and BLAS:** `build_profile`, `cpu_baseline`, `gemm_provider`, +- **profile and BLAS:** `build_profile`, `cpu_baseline`, `vector_math`, `gemm_provider`, `tpl_blas_enabled`, `blas_backend`, `blas_selection`, `blas_thread_policy`, `blas_threads`, `blas_threading`, `blas_library`; - **execution:** `execution_space`, `host_execution_space`, `device_backend`, @@ -209,7 +208,7 @@ object suitable for a run log: ([Performance tuning](tuning.md#the-native-backends-pools)); - **compilation:** `compiler`, `compiler_family`, `compiler_flags`, `cxx_standard`, `build_type`, `native_arch_enabled`, `aggressive_vectorization_enabled`, - `ipo_enabled`, `fast_math_enabled`, `optimization_policy`, `precision`, `layout`; + `ipo_enabled`, `fast_math_enabled`, `optimization_policy`, `layout`; - **host:** `python_version`, `numpy_version`, `platform_machine`. The library paths (`fft_library`, `blas_library`, `openmp_library`) are the files @@ -223,9 +222,8 @@ hand through `CXXFLAGS` appear in `compiler_flags`. `check_build()` raises `solprop.exceptions.BackendError` when an editable checkout's sources under `native/` are not the ones the extension was compiled from (it names -`uv sync`; a wheel skips this); when the installed solprop lacks a driver member or bundle -field the build relies on (it names them); when the build enables fast-math; when the execution-space record is inconsistent; when a GPU build sees no -device; when the GEMM provider is unknown or its BLAS is unidentified; when +`uv sync`; a wheel skips this); when the build enables fast-math; when the execution-space +record is inconsistent; when a GPU build sees no device; when its BLAS is unidentified; when a reference build carries a vendor BLAS or machine-specific code, or a distribution build carries native code or no BLAS; and when a GPU build's BLAS is not the device's. Then, in solprop: @@ -354,7 +352,7 @@ The options are read by `native/CMakeLists.txt` and the modules it includes from | option | default | values and effect | |---|---|---| -| `SOLPROP_NATIVE_ENABLE_OPENMP` | `ON` | the OpenMP host execution space and threaded FFTW. `OFF` in GPU builds, whose host space is Serial | +| `SOLPROP_NATIVE_ENABLE_OPENMP` | `ON` | the OpenMP host execution space and threaded FFTW: `ON` in every CPU build, `OFF` in GPU builds, whose host space is Serial; configuration refuses any other pairing | | `SOLPROP_NATIVE_ENABLE_CUDA` | `OFF` | the CUDA execution space with cuFFT (Linux, GNU host compiler) | | `SOLPROP_NATIVE_ENABLE_HIP` | `OFF` | the HIP execution space with rocFFT (Linux, ROCm Clang); exclusive with CUDA | | `SOLPROP_NATIVE_CUDA_ARCH` | `HOPPER90` | the Kokkos architecture suffix, `Kokkos_ARCH_<value>` ([CUDA](#cuda)) | @@ -429,21 +427,23 @@ The CPU kernels form their transcendentals (the stage and step propagators, the exponential Adams method's flows, phi-functions and compensation, the ionisation rates and fractions) in passes over blocks of elements through one layer, `native/include/solprop_native/runtime/vmath.hpp` ([ADR-059](../../dev/decisions.md)). On x86-64 -it calls [SLEEF](https://sleef.org)'s vector functions, each within 1.0 ulp of the -correctly rounded value over its whole domain: AVX2 where the build's target has it (the -wheels' x86-64-v3 baseline and any local build on a processor from 2013 or later), SSE2 -otherwise. `SOLPROP_NATIVE_VECTOR_MATH_AVX512=ON` takes the AVX-512F functions on a +and macOS arm64 it calls [SLEEF](https://sleef.org)'s vector functions, each within 1.0 ulp +of the correctly rounded value over its whole domain: AVX2 where the build's target has it +(the wheels' x86-64-v3 baseline and any local build on a processor from 2013 or later), +SSE2 otherwise, and AdvSIMD on Arm. `SOLPROP_NATIVE_VECTOR_MATH_AVX512=ON` takes the AVX-512F functions on a target with AVX-512F: on one thread they ran the tracking cases about 4 % faster than the AVX2 ones on an AMD EPYC 9B45 (Zen 5) but 7 % slower on an Intel Xeon of the Ice Lake generation, whose cores lower their clock under 512-bit work. glibc's scalar `exp`, `cos` and `sin` cost a complex exponential 10 to 30 ns on an AMD EPYC 7763; SLEEF's AVX2 functions take it 3.3 to 3.6 times faster at the same worst error on the kernels' own arguments. On Apple silicon -the system libm is already about 3 ns, SLEEF's AdvSIMD functions gain nothing, and the -build keeps the libm and each element's own calls (`SOLPROP_NATIVE_VECTOR_MATH=SLEEF` -selects SLEEF there too). `build_info().vector_math` records the route, for example +the system libm is already about 3 ns, but SLEEF's AdvSIMD functions over the gathered +blocks, and the passes they enable, ran an Apple M5 Max's tracking cases faster +(geometric mean 0.934 of the libm's time), so the build takes SLEEF there too. On Linux +aarch64, where SLEEF measured level on a Neoverse V2, the build keeps the libm and each +element's own calls (`SOLPROP_NATIVE_VECTOR_MATH=SLEEF` selects SLEEF there too). `build_info().vector_math` records the route, for example `"SLEEF 3.9.0 u10, AVX2"` or `"scalar libm"`. Results differ between the routes only by rounding (the functions' own ulp), within the backend's derived rounding budgets -([SEP 25](../../dev/seps/archive/sep-0025-rounding-level-reproducibility.md)). +([SEP 25](https://github.com/LupoLab/solprop/blob/main/docs/dev/seps/archive/sep-0025-rounding-level-reproducibility.md)). SLEEF is configured and built at build time as its own CMake project, with its own `-ffp-contract=off` (its double-double steps need every product and sum rounded) and @@ -586,15 +586,6 @@ published [pyFFTW](https://github.com/pyFFTW/pyFFTW) wheels, for one, bundle the macOS `solprop_native` must then be imported first, and the package raises `RuntimeError` at import if pyFFTW is already loaded. -**The rule stays, and this is why.** pyFFTW's macOS wheel carries and initialises its own -`libomp`, and solprop no longer loads pyFFTW, so nothing in solprop can decide the order for -you: importing solprop does not load `solprop_native`, which is loaded when a run first uses the -backend. The refusal is a clear error rather than a wrong result, and a loaded second runtime is -what it guards against. No replacement has been shown safe, which -[SEP 29](../../dev/seps/archive/sep-0029-compiled-backend-distribution.md) asks of it in fresh -processes, in both import orders, with interleaved short runs. So the guard stays until such a -run exists. - **What to do.** Import `solprop_native` before pyFFTW, or any package that imports it. `import solprop` alone is not enough, since it does not load the backend. In a notebook where a cell has already loaded pyFFTW, restart the kernel, or do the work in a fresh process. `backend="numpy_ref"` @@ -602,19 +593,12 @@ does not load `solprop_native`, and is unthreaded and far slower. Import order a the second runtime, so where it matters pyFFTW is best built from source against the same FFTW and OpenMP runtime. -**What would lift it.** `native/ci/coexistence.py` runs both import orders in fresh processes, starts each package's thread pool and interleaves short -native and reference runs. On macOS it expects the refusal. Its `--bypass-guard` flag adds a scenario -that hides pyFFTW from the guard and reports what happens, without failing the script. Run by hand on -macOS with pyFFTW installed, with `python -I native/ci/coexistence.py --bypass-guard`, it is the -evidence a change to this rule would start from. The `Wheels` workflow runs the same script on -`macos-15`, without the flag. - ## Wheels and redistribution A wheel meant for other machines is built with `SOLPROP_NATIVE_PROFILE=DISTRIBUTION`. It carries its BLAS (on Linux and Windows the OpenMP OpenBLAS, BSD-3-Clause) with its licence, and the licence texts of Kokkos, Kokkos Kernels, Kokkos-FFT, nanobind, -robin_map and, on x86-64, SLEEF (BSL-1.0), which are compiled in. FFTW and the OpenMP +robin_map and, on x86-64 and macOS arm64, SLEEF (BSL-1.0), which are compiled in. FFTW and the OpenMP runtime are bundled by the wheel repair (`auditwheel repair` on Linux, `delocate` on macOS, `delvewheel` on Windows), and their licence texts by `SOLPROP_NATIVE_BUNDLED_LICENCES`; FFTW (GPL-2.0-or-later) is @@ -623,4 +607,4 @@ developer notes ([Releasing and the native wheels](../../dev/releasing.md)). CUD HIP builds link the vendors' libraries and are built from source only. The build profiles, CPU baselines and wheel recipes on this page were proposed and -qualified by [SEP 29](../../dev/seps/archive/sep-0029-compiled-backend-distribution.md). +qualified by [SEP 29](https://github.com/LupoLab/solprop/blob/main/docs/dev/seps/archive/sep-0029-compiled-backend-distribution.md). diff --git a/docs/guide/performance/calibration.md b/docs/guide/performance/calibration.md index 9600dafac..5f5fdc002 100644 --- a/docs/guide/performance/calibration.md +++ b/docs/guide/performance/calibration.md @@ -95,6 +95,12 @@ A job takes its own allocation's row. Without one, it takes the workspace settin the row with the same layout and the nearest smaller core count, and otherwise the built-in table. +A row is replaced only by a calibration of the same level or a higher one. A quick or +standard calibration of an allocation that already has a thorough row (or a quick one +over a standard row) publishes nothing: it reports `kept`, with the settings of the row +the store keeps, which are the ones later runs apply. To replace it with a lower level's +row, clear the store first with `solprop calibrate --clear`. + The same directory keeps the **FFT plans runs measure**, in `wisdom.json` beside the machine and build's profiles. The first run of a transform shape measures its plan in place, inside its own workspace, and stores it; every later run of that shape, in any @@ -216,4 +222,4 @@ fitted under spinning threads give way to the built-in table when you make the t sleep. The design and its measurements are in -[SEP 46](../../dev/seps/archive/sep-0046-machine-calibration.md). +[SEP 46](https://github.com/LupoLab/solprop/blob/main/docs/dev/seps/archive/sep-0046-machine-calibration.md). diff --git a/docs/guide/performance/index.md b/docs/guide/performance/index.md index f3c002a37..55b35ad04 100644 --- a/docs/guide/performance/index.md +++ b/docs/guide/performance/index.md @@ -10,7 +10,7 @@ given machine comes from [calibrating solprop to it](calibration.md), once, with To measure a change's performance, or to see roughly what each backend and method costs, read the developer pages: [Benchmarks](../../dev/benchmarks.md) gives the -measurement rules and indicative results, and +measurement rules and current results, and [Running the benchmarks](../../dev/benchmarking.md) is the manual for `uv run poe bench`. diff --git a/docs/guide/performance/native.md b/docs/guide/performance/native.md index c2c6c4537..af37549e7 100644 --- a/docs/guide/performance/native.md +++ b/docs/guide/performance/native.md @@ -18,7 +18,7 @@ It is the backend to use, and a required dependency: `pip install solprop` insta `backend="auto"` — the default of every entry point — selects it. `numpy_ref`, which is unthreaded and roughly 6 to 40 times slower than threaded native ([which backend to use](backends.md#which-backend-to-use)), remains the numerical -reference, and runs [the few features native does not](backends.md#features-that-run-on-the-reference-backend). +reference, and runs [a problem a GPU build refuses](backends.md#features-that-run-on-the-reference-backend). ## What it runs @@ -52,7 +52,7 @@ of an HDF5 output that keeps the resume history, and for each periodic snapshot. resume installs them again and continues the history ([resuming](../results/resuming.md)). A frozen-residual coupled flow's history is kept in a native form (each sample's generator applied to its state), so a snapshot of it continues only on the native -backend, and a host engine's snapshot of it only on `numpy_ref`; a +backend, and a `numpy_ref` snapshot of it only on `numpy_ref`; a mismatch starts the history afresh and says why. Other histories cross between backends. The planar guide resolved in y is built into the GPU builds but has not been qualified @@ -95,10 +95,10 @@ python -c "import solprop_native as sn; sn.check_build()" ``` `check_build()` raises if the build is inconsistent (for example a GPU build that sees -no device) or does not fit the installed solprop: the two packages share a kernel -contract, and `check_build()` names any solprop member the build relies on that is -missing. In a checkout it also refuses an extension built from other sources than -`native/`. Install the two at the same version, from one release or one checkout. The build +no device). In a checkout it also refuses an extension built from other sources than +`native/`. It does not compare the build with the installed solprop: solprop requires +solprop-native at exactly its own version, so install the two at the same version, from +one release or one checkout. The build record reports the profile (`build_profile`), the BLAS (`blas_selection`, `blas_library`), FFTW, the compiler flags, the thread counts and, on a GPU build, the device. Then, in Python: @@ -127,9 +127,9 @@ It needs a C++20 compiler; a contributor to the Python or the documentation can one ([contributing](../../dev/contributing.md)). The editable install does not rebuild itself: run `uv sync --reinstall-package solprop-native` after a native change. `uv run poe check-native` runs the native gate -and `uv run poe check-all` both gates. A build stays valid across solprop changes until -the sources under `native/` change, when `check_build()` refuses it and names that -command, or until `check_build()` names a member the installed solprop lacks. Running solprop's test lanes against the build is described in +and a native change runs it after `uv run poe check`. A build stays valid across solprop +changes until the sources under `native/` change, when `check_build()` refuses it and names that +command. Running solprop's test lanes against the build is described in the developer notes on [testing](../../dev/testing.md#tiers-and-backends). ## Running on a GPU @@ -164,7 +164,7 @@ planes. Things to know: device sums in its own order; the difference is at the level of rounding and is covered by the same derived error bounds that every backend is tested against. A repeat on one build is held to the same bounds, not to identical bits - ([SEP 25](../../dev/seps/archive/sep-0025-rounding-level-reproducibility.md)). + ([SEP 25](https://github.com/LupoLab/solprop/blob/main/docs/dev/seps/archive/sep-0025-rounding-level-reproducibility.md)). - **Time your own problem first.** Run ten steps on the device and on the CPU before committing to either for a long campaign. @@ -191,8 +191,8 @@ It is an environment setting with no keyword, and scan workers inherit it. It is backend selection, before any state is allocated or a step taken, by reading the build's `build_info().device_backend` and `device_count`, never a version label. It refuses, with a `BackendError`, a CPU build, the wrong device backend and a device build that sees no device. -It also refuses `numpy_ref`, by name or through `backend="auto"` for a TDSE run, because -such a run would not meet the job's requirement; unset it for such a run. +It also refuses `numpy_ref`, because such a run would not meet the job's requirement; unset +it for such a run. ## Threads on the CPU build @@ -214,8 +214,9 @@ large run, for a scan of many runs and on a cluster. ## When something goes wrong -- **`ImportError`, or `check_build()` naming a missing member.** The - installed solprop-native does not fit the installed solprop; install both at the same +- **`ImportError`, or another error from inside `solprop_native`, after one package was + installed alone.** The installed solprop-native does not fit the installed solprop; + install both at the same version (`pip install --force-reinstall solprop`, or both from one checkout as in [Building the native backend](building-native.md)). - **`check_build()` saying the extension was built from other sources.** A checkout's @@ -243,5 +244,5 @@ large run, for a scan of many runs and on a cluster. The native backend's place in this repository and its precompiled wheels were proposed and carried out by -[SEP 29](../../dev/seps/archive/sep-0029-compiled-backend-distribution.md), and -[SEP 43](../../dev/seps/archive/sep-0043-retire-numba-cpu.md) made it a required dependency. +[SEP 29](https://github.com/LupoLab/solprop/blob/main/docs/dev/seps/archive/sep-0029-compiled-backend-distribution.md), and +[SEP 43](https://github.com/LupoLab/solprop/blob/main/docs/dev/seps/archive/sep-0043-retire-numba-cpu.md) made it a required dependency. diff --git a/docs/guide/performance/progress.md b/docs/guide/performance/progress.md index 4f783fa85..a9a8469a5 100644 --- a/docs/guide/performance/progress.md +++ b/docs/guide/performance/progress.md @@ -199,8 +199,9 @@ against a fill that reaches exactly zero, closes at a ratio of `1.6e-01`. Progress goes through one {py:class}`~solprop.log.ProgressReporter` protocol of six calls: `summary(text)` with the start-of-run block before the first step (and the `resources` line after `finished`), `started(z_start, z_end, n_planes)` once, -`step(z, dz, accepted)` once per **attempted** step from inside the backend's own loop, -`plane(z, summary)` once per saved plane, and at the end `finished(total)`, or +`step(z, dz, accepted)` once per **attempted** step, in order, delivered in batches as +the run returns them (at each saved plane, and in between after at most 256 attempts or +0.1 s), `plane(z, summary)` once per saved plane, and at the end `finished(total)`, or `interrupted(z, error)` when the loop raises, `KeyboardInterrupt` included, before the error propagates -- it is how the bar gives the terminal back. Subclass {py:class}`~solprop.log.NullReporter` (or the protocol itself) and override the calls you @@ -218,9 +219,12 @@ prop_capillary(..., progress=Bar()) ``` Pass it as `progress=` and `progress_period` becomes your reporter's business. `step` is -called from inside the step loop, thousands of times a second on a small problem, so -anything it does must be cheap or be put on a clock of its own — the line reporter's -own `step` costs about 100 ns, five times the bare cost of the call. +called once per attempt, thousands of times a second on a small problem and up to 256 +times in a row when a batch arrives, so anything it does must be cheap or be put on a +clock of its own — the line reporter's own `step` costs about 100 ns, five times the +bare cost of the call. Because the attempts arrive a batch at a time, a stop flag that a +reporter sets lands up to one batch later, at most 256 attempts or 0.1 s, on either +backend. Nothing a reporter does may change the run: the calls are observers made after each step is decided, and a run with a reporter is the same computation as a run without one. @@ -307,4 +311,4 @@ boundaries, as their results are collected. The table per executor, and the scan `stop=` flag, are in [watching and stopping a scan](../workflows/scans.md#watching-and-stopping-a-scan). The plane observer, the scan reporter and the cost estimate were proposed and carried -out by [SEP 41](../../dev/seps/archive/sep-0041-recipes-and-front-ends.md). +out by [SEP 41](https://github.com/LupoLab/solprop/blob/main/docs/dev/seps/archive/sep-0041-recipes-and-front-ends.md). diff --git a/docs/guide/performance/tuning.md b/docs/guide/performance/tuning.md index 878450a56..fed040707 100644 --- a/docs/guide/performance/tuning.md +++ b/docs/guide/performance/tuning.md @@ -162,7 +162,7 @@ imported: | `SOLPROP_NATIVE_FFT_THREADS` | FFTW threads for the modal and spatial transforms | sized per plan, up to the cap | | `SOLPROP_NATIVE_RAMAN_FFT_THREADS` | threads for the Raman convolution transforms of complete node chunks | sized per plan, up to the cap | | `SOLPROP_NATIVE_RAMAN_TAIL_FFT_THREADS` | threads for the Raman transforms of the last, partial node chunk | sized from active rows, up to the cap | -| `SOLPROP_NATIVE_THREADED_FFT_MIN_SAMPLES` | the real-side samples per execution from which a modal or spatial FFT plan is threaded | 8,192 (32,768 on macOS) | +| `SOLPROP_NATIVE_THREADED_FFT_MIN_SAMPLES` | the real-side samples per execution from which a modal or spatial FFT plan is threaded | 8,192 (32,768 on macOS, divided by 16 there on a team of at most eight threads while the runtime spins within native calls, as it does by default; a value set here is never divided) | | `SOLPROP_NATIVE_FORWARD_PACK` | `0` transforms a modal stage's forward rows (projection, absorber, plasma currents) one transform at a time instead of in one batch | unset (one batch, except for one-column problems) | | `SOLPROP_NATIVE_BAND_TILES` | the field plasma column's band form: unset for the build's own (tiled on a GPU, a team per node on a CPU), `0` for the team column, a positive `N` for the tiled column with host teams of `N` threads | unset | @@ -171,74 +171,22 @@ value raises `ValueError` at import. An explicit pool setting forces its clamped and bypasses automatic sizing, including for short FFTs. Setting only the global cap retains automatic sizing. GPU builds ignore these CPU pool settings. -On OpenMP CPU builds, operation dimensions select serial, intermediate or full-width -execution. Stage and reduction work, packing and temporal copies, nonlinear responses, -native dense transforms, coupled matrix functions and FFT plans have separate size rules. Response sizing accounts for both the total -work, active columns and fine samples per column. The choices and plans are cached when the -backend is constructed; no runtime tuning occurs during propagation. Partial chunks -use their own work sizes. Vendor BLAS pools retain their -process-start settings. Non-OpenMP host builds preserve their execution-space policy; -`build_info().cpu_size_policy_enabled` reports whether operation widths are supported. - -The thresholds below are shared across CPU hosts, except that macOS keeps higher stage -and FFT starts (8,192 and 32,768), where a short serial loop is still the faster one; -`C` is the clamped capacity of the -relevant pool, and sizes count work in the operation itself, not bytes. Between the two -thresholds an operation uses `min(4, C)` threads; equal thresholds give only serial or -full-width execution. A kernel operation (any row but the two FFT rows) of a backend that -already runs a full-width kernel takes the full pool instead of four threads: GNU OpenMP -ends the surplus threads of its team whenever a narrower parallel region follows a wider -one and starts them again for the next wide one, which cost a four-thread kernel between -full-width ones about half a millisecond each time. FFT plans keep their four threads, -since FFTW's threaded loops run on the runtime's whole team. - -Modal and spatial FFT plans thread by their shape instead: from the start below, a -thread per 4,096 samples (32,768 on macOS, a sixteenth of that on a spinning top tier) -and at most one per row, since FFTW divides a batch's rows among its threads; rows of at -least 16,384 samples (65,536 on macOS) are split, up to `min(4, C)` threads. A batch of -a few long rows therefore takes about one thread a row, many short rows the full pool. -The calibration moves the samples per thread. - -| operation | work used for sizing | threading starts | full pool starts | -|---|---|---:|---:| -| stage, update and reduction | elements in the field | 4,096 (8,192 on macOS) | as threading | -| packing and temporal copies | entries actually copied | 65,536 | 65,536 | -| nonlinear response | active columns × components × fine samples | 32,768 | 196,608, or 65,536 fine samples per column, or 40 component columns | -| native/custom GEMM | output rows × inner dimension × samples | 1,048,576 | 1,048,576 | -| general modal synthesis/projection | active nodes × components × spectral samples × modes | 65,536 | 65,536 | -| coupled matrix functions | active spectral bins × modes³ | 32,768 | 32,768 | -| exponential Adams trial | elements in the field × history rows | 8,192 | 65,536 | -| modal/spatial FFT | real-side samples in the actual batch, by rows and row length (above) | 8,192, 32,768 on macOS (`SOLPROP_NATIVE_THREADED_FFT_MIN_SAMPLES`) | 4,194,304 | -| Raman FFT | real-side samples in the actual batch | 65,536 | 262,144 | - -A response column is one active node and one component; its column-length and -column-count rules apply only past its threading start. General modal map updates use -the two maps' combined element count times the polynomial degree. Native GEMM sizing -never changes a vendor BLAS's width or selects a different provider. - -The [CPU threading measurements](../../dev/benchmarks.md#kokkos-cpu-operation-size-threading) -explain the thresholds. For example, an 8,192-sample copy remains serial even when a -similarly sized arithmetic stage benefits from threading. Short response columns can -use four threads while long columns or wider batches use the full pool. The backend applies these -choices automatically; start by setting only the process cap when sharing a machine. - -`python -m solprop_native` records the policy constants and explicit override mask. -Its existing thread counts remain process capacities. The backend's metadata records -`execution_sizing`, with the chosen `threads` and sizing `elements` for each operation. -Response entries also report -`fine_samples` and `columns`, because equal total work can have different column -lengths. `build_info()` reports the resolved process values as `requested_threads`, -`runtime_threads`, `thread_count` (kernels), `fftw_threads`, `raman_fft_threads`, -`raman_tail_fft_threads`, `threaded_fft_min_samples`, `blas_threads` and -`blas_threading`; `cpu_size_policy_enabled` and `explicit_thread_pools` (a bit mask: -kernel 1, FFT 2, Raman 4, Raman tail 8) distinguish automatic sizing from explicit -requests. +On OpenMP CPU builds the backend sizes each operation from its dimensions when it is +constructed: stages, copies, responses, dense products, matrix functions and FFT plans +each run serially below a size of their own, on a few threads above it and on the whole +pool beyond, and transforms thread by their rows and row length. Nothing is tuned during +propagation, and a [machine calibration](calibration.md) may replace the built-in sizes. +Start by setting only the process cap when sharing a machine; the thresholds and the +measurements behind them are in the +[CPU threading measurements](../../dev/benchmarks.md#kokkos-cpu-operation-size-threading). +The backend's metadata records `execution_sizing`, the threads and work it chose for each +operation, and `python -m solprop_native` the policy constants. Free-space transforms are planned at `SOLPROP_FFTW_PLAN`'s effort (`measure` by default); `estimate` skips the measured planning for short runs and tests. Answers at different thread counts may differ by rounding; solprop holds them to its rounding bounds, not to identical bits -([SEP 25](../../dev/seps/archive/sep-0025-rounding-level-reproducibility.md)). +([SEP 25](https://github.com/LupoLab/solprop/blob/main/docs/dev/seps/archive/sep-0025-rounding-level-reproducibility.md)). Contiguous modal and Raman FFTW plans default to measured planning at one thread and estimate planning at wider widths; the explicit effort overrides both, including long Raman rows and partial chunks. Measured planning can add substantial construction @@ -279,13 +227,8 @@ read or written, is reported in the log and costs only the measurement. Wisdom c among FFTW's exact algorithms, so it changes no result beyond the rounding a fresh measurement can change; the run's metadata records `wisdom_loaded` (whether the file held plans) and the `wisdom_digest` of the plans the workspace built from wisdom or -measured. For a scan of one-thread jobs it removes most of each job's construction: -on a Xeon Gold 6240, constructing the averaged helium capillary took 1.40 s cold and -0.03 s with the plans in place, beside a 0.27 s window (1.78 s and 0.05 s on an AMD -EPYC 7763), and the comb-to-continuum capillary 5.0 s and 0.06 s -([measurements](../../dev/benchmarks.md#persistent-fftw-wisdom)). Under -`SOLPROP_FFTW_PLAN=measure` on 16 cores of an AMD EPYC 7763, the comb-to-continuum -capillary's construction fell from 13.7 s to 0.18 s, its window unchanged. +measured. For a scan of one-thread jobs it removes most of each job's construction +([measurements](../../dev/benchmarks.md#persistent-fftw-wisdom)). `OMP_NUM_THREADS` and `KOKKOS_NUM_THREADS` do **not** size the Kokkos pool — the backend initialises Kokkos with an explicit thread count, which takes precedence; set diff --git a/docs/guide/results/output.md b/docs/guide/results/output.md index 0288b3ba2..38b986375 100644 --- a/docs/guide/results/output.md +++ b/docs/guide/results/output.md @@ -81,7 +81,7 @@ handler.close() # idempotent A run that is wanted as spectra and diagnostics need not store a field at every plane. `SimulationSettings(fields=..., field_planes=...)` -([SEP 22](../../dev/seps/archive/sep-0022-memory-lean-spatial-execution.md)) chooses, with the +([SEP 22](https://github.com/LupoLab/solprop/blob/main/docs/dev/seps/archive/sep-0022-memory-lean-spatial-execution.md)) chooses, with the vocabulary {py:func}`~solprop.driver.scan.run_scan` already uses: | `fields` | what each saved plane keeps | @@ -171,11 +171,6 @@ known even when no plane will carry a field. A handler already holding planes under a different rule raises {py:class}`~solprop.exceptions.OutputError`, as a resumed store does. -In this phase the backend still observes the field at every plane, and the driver drops -it: the storage, the preallocation, the record copies and the conversion go, the -device transfer and the collar diagnostic of a Cartesian run remain until the -observation itself can skip the field. - ## What goes in, and in which convention A {py:class}`~solprop.output.records.SavedPlane` is what a driver hands over: the position @@ -290,16 +285,32 @@ lists their saved-plane indices; a `"none"` run has neither dataset. step-history and between-planes columns grow by doubling; a run that saves more planes than planned grows the plane-indexed ones by doubling too. The root attribute `n_saved` is the number of planes actually written. Each plane's data is written and flushed -first and the count raised last, so a hard stop — a SIGKILL, an out-of-memory kill, a -lost node — leaves the count at the last complete plane, even part-way through the next. -The attempts and rows belonging to the counted planes are the sums of +first and the count raised last, so the count never includes a plane that a stop cut off +part-way. The attempts and rows belonging to the counted planes are the sums of `step_history/counts` and `step_stats/counts` over them, so the one count fixes every -column. Every reader, {py:func}`~solprop.output.hdf5.resume` and a handler continuing +column. Every reader, {py:func}`~solprop.output.hdf5.read_resume_state` and a handler continuing the file use only what is counted, and a clean close trims every dataset to it, so a finished file holds no unused rows and its datasets' extents are exactly the counts. Read a file through {py:func}`~solprop.output.hdf5.open_file`, not `h5py` directly, if it may be one a hard stop left behind. +**What a hard stop can do.** The count is kept consistent, but the file is not made +crash-proof. A flush hands HDF5's buffers to the operating system without syncing them +to disk, and the file is not opened in HDF5's single-writer/multiple-reader (SWMR) mode. +HDF5 therefore does not promise that a file stopped hard — by a SIGKILL, an +out-of-memory kill or a lost node — while it was writing, part-way through a plane or +while a dataset grew, can be opened at all; a lost node or a power cut can also lose +writes the operating system had not yet made. For a copy that a hard stop cannot damage, +request [periodic snapshots](#periodic-snapshots-while-computing) with `snapshots=` (an +HDF5 run with `fields="all"`): each copies the closed files, syncs the copies to disk +and records their checksums, and +{py:func}`~solprop.output.snapshots.restore_snapshot` turns a verified one into working +files to resume. A scan's collected file has the same exposure on the `Local` and `Pool` +executors, which hold each completed point only in that file and take no snapshots; a +`Queue` or `Slurm` scan also keeps each point's artifact in the queue, synced to disk +before it is published, and `python -m solprop.scan collect` can write a collected +file from them again ([durable queues](../workflows/scans.md#durable-queues-and-slurm)). + The march snapshot is the Adams march's state at the last saved plane or terminal checkpoint, rewritten in place at each one (`SimulationSettings.resume_history`). It is outside the record and the configuration hash: it says where the march stood, not what @@ -402,7 +413,7 @@ coarse for the tolerance the norm is scaled by ([stepper.md](../../dev/stepper.m A rejected attempt that diverged, whose propagator or error overflowed (a long step under a strong collar), records an infinite norm; the stepper retried it at a much shorter step, so take the largest norm over the accepted -attempts. {py:func}`~solprop.output.hdf5.resume` returns the history recorded so far with the last +attempts. {py:func}`~solprop.output.hdf5.read_resume_state` returns the history recorded so far with the last plane, and an appending handler numbers the next attempt where the file left off, so a resumed run's file keeps one continuous record. @@ -428,27 +439,25 @@ it with `open_tdse_archive` ([the TDSE response](../media/tdse.md#the-raw-respon ## The schema version Every file records its `schema_version`; this release writes and reads output -schema **4** (`solprop.output.SCHEMA_VERSION`). Schema 1 was the first released layout, +schema **3** (`solprop.output.SCHEMA_VERSION`). Schema 1 was the first released layout, that of 0.1.0; schema 2, that of 0.2.0, adds `spectral_phase` to the record of a -{py:class}`~solprop.pulses.DataPulse`; schema 3 stores a march snapshot's `state` and -its engine `rows` without the leading axis of one they kept before; schema 4 records no -basis identity in the plane-reference record, whose `basis` entry is gone: a plane's -basis is derived when it is read ([coupling simulations](../workflows/coupling.md)). A -file of any other schema is refused by name wherever it is opened, read or resumed: files -written by an earlier release or by development versions of solprop, which declared -output schemas up to 28, are not read, and nor is a file from a later release. Read such -a file with the solprop version -that wrote it. A scan file is refused the same way, by the output schema each point's run -record declares, whether it is read or resumed; its own `scan_schema_version` versions -the scan container, not the records in it, and is still 1. A resume needs the file's -schema to be this one, and checks that before it compares the records +{py:class}`~solprop.pulses.DataPulse`; schema 3 makes two changes. It stores a march +snapshot's `state` and its engine `rows` without the leading axis of one they kept +before, and it records no basis identity in the plane-reference record, whose +`basis` entry is gone: a plane's basis is derived when it is read +([coupling simulations](../workflows/coupling.md)). A file of any other schema is +refused by name wherever it is opened, read or resumed, and the refusal names the file: +a file of an earlier or a later release is not read. Read such a file with the solprop version that wrote it: a 0.1.0 file (schema 1) with +solprop 0.1.x, a 0.2.0 file (schema 2) with solprop 0.2.x. A scan file is refused the +same way, by the output schema each point's run record declares, whether it is read or +resumed; its own `scan_schema_version` versions the scan container, not the records in +it, and is still 1. A resume needs the file's schema to be this one, and checks that +before it compares the records ([what a resume compares](resuming.md#what-a-resume-compares)). Every run records its plane-reference record (`RunMetadata.reference`, [provenance](provenance.md#the-metadata-schema)), from which a saved plane is read back -as a coherent field plane ([coupling simulations](../workflows/coupling.md)). The -configuration no longer records a precision: solprop computes in binary64 only. A run -started on an earlier release, whose configuration did, finishes on that release. +as a coherent field plane ([coupling simulations](../workflows/coupling.md)). How a run resumes from its last plane depends on what that plane is: @@ -499,16 +508,12 @@ version, which the next release is the first to write. Development builds betwee releases are therefore not compatible with one another: a file written by an earlier build of the same schema may be refused, and is read with the build that wrote it. -**Five columns of `absorbed_power`.** The fifth column, `custom`, folded into schema 2 the -same way, and the first column became the collar alone. A file from a development build -before it, with four columns, is not supported: read it with the build that wrote it. - ## A worked example ```{code-block} python import numpy as np from solprop.grid import EnvelopeGrid -from solprop.output import HDF5Output, MemoryOutput, resume +from solprop.output import HDF5Output, MemoryOutput, read_resume_state from solprop.output.metadata import RunMetadata from solprop.output.records import GridRecord, SavedPlane, StepperRecord from solprop.stepper import DOPRI5, PIController @@ -527,7 +532,7 @@ memory.open(metadata) memory.save(SavedPlane(z=0.0, field=np.ones((1, 1, grid.n_omega), complex))) memory.to_file("run.h5", compression="lzf") -state = resume("run.h5") +state = read_resume_state("run.h5") assert state.plane.z == 0.0 assert np.array_equal(state.plane.field, memory.planes()[0].field) ``` @@ -541,9 +546,9 @@ function. The default, `None`, leaves the run unchanged. This is an execution po outside the scientific configuration hash; `SimulationRunner`'s restriction on reusing TDSE across inputs still applies. -A snapshot requires an HDF5 run with `fields="all"`; it no longer needs -`step_planes`, and it is taken with interpolated planes too -([SEP 47](../../dev/seps/archive/sep-0047-run-ownership.md)). With `interpolate_planes=True` a +A snapshot requires an HDF5 run with `fields="all"`, and it is taken with interpolated +planes too +([SEP 47](https://github.com/LupoLab/solprop/blob/main/docs/dev/seps/archive/sep-0047-run-ownership.md)). With `interpolate_planes=True` a request is taken at the end of the step that crossed the plane being saved, once every plane that step crossed has been saved, so the snapshot holds a state the march passed through and `resume=True` continues it without `resume="interpolated"`. Adams runs must allow retained @@ -696,4 +701,4 @@ creation fails before it can return a writer and its handle also cannot close, ownership remains held until process exit; the exception reports both failures. The recipe stored in a run's output and the result capabilities were proposed and -carried out by [SEP 41](../../dev/seps/archive/sep-0041-recipes-and-front-ends.md). +carried out by [SEP 41](https://github.com/LupoLab/solprop/blob/main/docs/dev/seps/archive/sep-0041-recipes-and-front-ends.md). diff --git a/docs/guide/results/plotting.md b/docs/guide/results/plotting.md index a0ac03f33..f42c146f0 100644 --- a/docs/guide/results/plotting.md +++ b/docs/guide/results/plotting.md @@ -107,7 +107,9 @@ their figure, and a map follows a pulse that walks off or spreads along the run. {py:func}`~solprop.plotting.propagation.time_1d` and {py:func}`~solprop.plotting.propagation.spec_1d` draw one or more positions along the -fibre: a colour per position, a dash pattern per mode (the patterns repeat when there +fibre, chosen by position with `z=` or by index with `plane=` as the +[processing readers](processing.md) choose a plane (the spectrogram draws one, chosen +the same way): a colour per position, a dash pattern per mode (the patterns repeat when there are more modes than patterns), and the width at half maximum appended to each temporal legend entry. `time_1d` draws the power, the real field or its square; `spec_1d` draws the density on any of the three abscissae, logarithmic by default @@ -171,8 +173,10 @@ and transforms at evenly spaced positions, through $\tau$ resolves frequencies no better than $1/\tau$, so a short gate shows *when* and a long gate shows *what*. The gate below is at the geometric mean of the transform-limited duration and the chirped one, which is where a linear chirp is most legible. By default -the gate is a twentieth of the time range wide (`gate_fwhm`) and is placed at 256 -positions across it (`positions`); `log=True` draws decibels below the peak. A spectrogram +the gate's width (`gate_fwhm`) is a twentieth of the time range clipped to the window +({py:func}`~solprop.processing.fields.default_gate_fwhm`), and it is placed at 256 +positions across that range (`positions`); `log=True` draws decibels below the peak, down +to `db_min` (−40 dB by default). A spectrogram is of one field, so a multimode run must name the mode it means, and is refused if it does not. The map itself, without the figure, is {py:func}`~solprop.processing.fields.get_spectrogram`: the gate positions, the spectral @@ -326,4 +330,4 @@ icon.savefig(buffer, format="png") # 96 x 96 pixels, for a picker's icon ``` The geometry outlines were proposed and carried out by -[SEP 41](../../dev/seps/archive/sep-0041-recipes-and-front-ends.md). +[SEP 41](https://github.com/LupoLab/solprop/blob/main/docs/dev/seps/archive/sep-0041-recipes-and-front-ends.md). diff --git a/docs/guide/results/processing.md b/docs/guide/results/processing.md index 63f0d0710..c0059cb0e 100644 --- a/docs/guide/results/processing.md +++ b/docs/guide/results/processing.md @@ -486,7 +486,7 @@ every band wider than 256 bins keeps the 64-bin edge. A run with input shot noise ([shot noise](../media/noise.md)) saves a field that carries its seed: one photon per active bin and channel, a floor of $\hbar\omega/\Delta\omega$ under the whole spectrum. `get_spectral_density(..., noise_floor="subtract")` removes it -([SEP 37](../../dev/seps/archive/sep-0037-noise-and-stepper-defaults.md), section 5.5). It +([SEP 37](https://github.com/LupoLab/solprop/blob/main/docs/dev/seps/archive/sep-0037-noise-and-stepper-defaults.md), section 5.5). It subtracts the energy of the stored realisation, $|N_0|^2$ bin by bin and channel by channel in the route's own photon measure, before the polarisation components are summed and before any mode selection or smoothing: @@ -580,8 +580,8 @@ print(f"time-bandwidth product {float(time_bandwidth(output, plane=-1)):.3f}") Reading a run from disk goes through a handler that is **open**: during the run it already is, and afterwards {py:func}`~solprop.output.hdf5.open_file` opens the file read-only through the same protocol, as a context manager if you like. -{py:func}`~solprop.output.hdf5.resume` returns the last plane only; it is for continuing a -run, not for reading one. +{py:func}`~solprop.output.hdf5.read_resume_state` returns the last plane only, the state a +resume continues from; it is not for reading a run. ```{code-block} python from solprop.output import open_file diff --git a/docs/guide/results/provenance.md b/docs/guide/results/provenance.md index ad6567670..37db1957b 100644 --- a/docs/guide/results/provenance.md +++ b/docs/guide/results/provenance.md @@ -83,7 +83,7 @@ A saved result needs the grid, field convention, material models, response choic checkout when there is one, and when the run started. * - ``reference`` - The **plane-reference record** - (`SEP 31 <../../dev/seps/archive/sep-0031-simulation-coupling.html>`_): the carrier, the + (`SEP 31 <https://github.com/LupoLab/solprop/blob/main/docs/dev/seps/archive/sep-0031-simulation-coupling.md>`_): the carrier, the frame integral of the terms the linear operator removed (exact Chebyshev antiderivatives of the frame's ``beta_0`` and ``beta_1`` tables, with the frequency origin of the linear term), the reference origin of the run's path, and the @@ -97,7 +97,7 @@ A saved result needs the grid, field convention, material models, response choic strength, and a collar's strength, band, threshold and step limit; ``None`` without a transverse boundary. * - ``schema_version``, ``spectral_convention``, ``field_layout`` - - The version of this record layout (currently 4), the sign convention of the + - The version of this record layout (currently 3), the sign convention of the stored field (always ``"optics"``) and the axis order of the stored field. ``` @@ -171,8 +171,8 @@ holds two kinds of entry. is taken as transparent, with the absorption bound of that approximation; - `policies`, the approximations in force: linear density scaling of a gas susceptibility, with its warning threshold; the electronic policy and the carrier - wavelength; the Raman line-shift policy and reference temperature; and the plasma - energy-loss convention. A policy the run does not use (a Raman shift without a + wavelength; the Raman line-shift policy and reference temperature; and each optmat + ionisation rate's threshold and energy-loss convention. A policy the run does not use (a Raman shift without a shifting response, a GNLSE fraction off the GNLSE) is recorded as `None`. **Measurements**, which are recorded beside them and are not in the key: diff --git a/docs/guide/results/resuming.md b/docs/guide/results/resuming.md index 4cc4a36de..480d4ac05 100644 --- a/docs/guide/results/resuming.md +++ b/docs/guide/results/resuming.md @@ -36,10 +36,10 @@ Restrict a long job to one CPU family, for example with a scheduler constraint. driver's to decide: ```{code-block} python -from solprop.output import check_cache, resume +from solprop.output import check_cache, read_resume_state if check_cache("run.h5", metadata): # False when there is no file - state = resume("run.h5") # metadata, last plane, step history + state = read_resume_state("run.h5") # metadata, last plane, step history start_from(state.plane) # already back in the FFT convention ``` @@ -81,11 +81,11 @@ snapshot and a scan row compare it too. The record holds the schema version, the grid, the modes, the configuration, the noise, the stepper settings, the material manifest's identities and policies, the stepping method when the Adams integrator -([SEP 13](../../dev/seps/archive/sep-0013-expensive-response-steppers.md), +([SEP 13](https://github.com/LupoLab/solprop/blob/main/docs/dev/seps/archive/sep-0013-expensive-response-steppers.md), [the Adams integrator](../numerics/adams.md)) stepped the run instead of the tableau, named with its formulation, and the region the error norm scores. A run whose field plasma integrates by the band rule -([SEP 18](../../dev/seps/archive/sep-0018-band-exact-plasma-integrals.md)) records the +([SEP 18](https://github.com/LupoLab/solprop/blob/main/docs/dev/seps/archive/sep-0018-band-exact-plasma-integrals.md)) records the rule in its configuration as `plasma_integration`. The record holds the policy, `K`, $\theta_b$, the taps at full precision, the certified error, and the boundary and exposure policies. A resume that would integrate the plasma differently is therefore @@ -97,13 +97,13 @@ limit and taper counts are part of the identity; the measured certificate is exe evidence under `backend.settings.plasma_source`, outside the hash. A resolved modal run records its transverse rule in `quadrature` and in the key -- the family (`radial_rule`), the requested and realised counts, the nodes and the physical weights -([SEP 19](../../dev/seps/archive/sep-0019-field-scale-quadrature.md)) -- so a resume on +([SEP 19](https://github.com/LupoLab/solprop/blob/main/docs/dev/seps/archive/sep-0019-field-scale-quadrature.md)) -- so a resume on another rule is refused. A run on the plain trapezoid records none of these, and a response's `integration` is left out of the key when it is `"trapezoid"`. The key also includes the absolute launch position, the scientific TDSE descriptor, the interval-cap and start-up rules, interpolation of save planes (`interpolate_planes`) and saving of accepted-step endpoints (`step_planes`) -([SEP 14](../../dev/seps/archive/sep-0014-stepper-efficiency.md)). It is *not* Python's +([SEP 14](https://github.com/LupoLab/solprop/blob/main/docs/dev/seps/archive/sep-0014-stepper-efficiency.md)). It is *not* Python's `hash`, which is salted per interpreter, so the same run digests to the same string in every process — a test runs it in a subprocess with a different `PYTHONHASHSEED` and compares. @@ -115,7 +115,8 @@ and its breakpoints, so a run never resumes under another gate or window Four things are deliberately outside it: the wall-clock start time, the package versions, the git provenance and the backend record. An unrelated commit or a change of backend does not refuse to resume a run that is otherwise the same run, and nor does a -library upgrade, as long as it moves no number the record holds. So is the boundary +library upgrade other than optmat's, whose version the material manifest records, as long +as it moves no number the record holds. So is the boundary check's budget and guard width: a run stopped at the time window's edge may be resumed under a relaxed check, and its monitor's record continues across the resume ([watching the window's edges](../numerics/boundaries.md#watching-the-windows-edges)). @@ -130,7 +131,9 @@ A call without `seed=` draws fresh operating-system entropy each time it is buil ([reproducibility](../media/noise.md#reproducibility)). So that re-running the same call with `resume=True` continues its own file, a realisation the constructor drew without a seed is drawn again from the seed the file recorded before the hashes are compared, -and the run logs that it did. This covers the default noise of `prop_gnlse`, +and the run logs that it did. The redraw belongs to the resumed run alone: the +`Simulation` keeps its own realisation, so a later fresh `run` of it is not the file's +again. This covers the default noise of `prop_gnlse`, `prop_capillary`, `prop_waveguide` and `prop_free` on a radial grid, and an explicit `noise="input"` or `"modified"` given without a seed. A seed the call gives, or a realisation it passes in, is never replaced: a resume that differs in it is refused, and the refusal names the @@ -161,6 +164,11 @@ their hashes, and it does not choose its own limit: its `node_budget` is ignored yours applies. Opening an HDF5 file at all exposes the HDF5 library to it. +A file resumes on its own only if it holds every data file its recipe refers to. A run +embeds its data files up to 16 MiB in all (`solprop.recipe.provenance.EMBED_LIMIT`) and +records any beyond that by name and digest only; the file alone then cannot rebuild the +run, and resuming it is refused with a {py:class}`~solprop.recipe.errors.RecipeError`. + ### What a file allows {py:func}`solprop.output.resumable.resumability` answers three questions about a file without @@ -187,27 +195,29 @@ is tried. ### Stopping a run `Simulation.run(..., stop=flag)` takes any object with an `is_set()` method, such as a -{py:class}`threading.Event`. The run polls it before its first step, then before every -trial step, so it answers within one step. When it is set, the run writes its state as -SIGTERM would, tells the reporter through `interrupted`, and **returns** the handler: a -requested stop is not an error, and the outcome's message says the caller's flag stopped -it. `resume=True` continues the file. A front end sets the flag from any thread, on any -platform, with no signals; each run polls its own. `solprop run` and `solprop resume` set +{py:class}`threading.Event`. On `numpy_ref` the run polls it before its first step, then +before every trial step, so it answers within one step. When it is set, the run writes its +state as SIGTERM would, tells the reporter through `interrupted`, and **returns** the +handler: a requested stop is not an error, and the outcome's message says the caller's +flag stopped it. `resume=True` continues the file. A front end sets the flag from any +thread, on any platform, with no signals; each run polls its own. `solprop run` and `solprop resume` set it on Ctrl-C, SIGTERM and, on Windows, Ctrl-Break, and exit with the usual status; a second Ctrl-C interrupts at once. A signal that comes too late to stop anything, with the file already complete, exits with status zero and says so. One that comes while a recipe is building waits for the build to finish, since the flag is only polled once a march is running, so a large grid's build can take most of a batch system's grace period. -The exception is the native backend's `Multistep()` march, which runs many attempts in -one native call, where the flag cannot be read. The run polls before each call instead, -and a call returns after at most 256 attempts or 0.1 s of wall time, read after each -attempt, whichever comes first. So a stop waits for that bound and the attempt in flight: +The exception is the native backend, which runs many attempts in one native call, where +the flag cannot be read. The run polls before each call instead, and a call returns +after at most 256 attempts or 0.1 s of wall time, read after each attempt, whichever +comes first. So a stop waits for that bound and the attempt in flight: 256 attempts on a small problem, about 0.1 s on a larger one, one attempt where an attempt takes longer than 0.1 s. A call also returns at a save plane, a statistics row or a boundary check. Where a call returns changes nothing the run computes. SIGTERM and Ctrl-C in a script's `Simulation.run` wait for the same return, since Python runs a signal's -handler only then. +handler only then. A flag that the run's own progress reporter sets lands up to one such +batch later on either backend, since the reporter hears the attempts a batch at a time +([progress](../performance/progress.md#writing-your-own)). ## Completion status and terminal checkpoints @@ -227,19 +237,19 @@ dense observation can instead retain that interpolated field. It is separate fro `handler["field"]` and the per-plane statistics keep their original meanings. Checkpoint creation uses available observations and histories and makes no new material-statistics request. An interpolated checkpoint is labelled as such: -`resume(path)` reads it, while restarting requires the explicit +`read_resume_state(path)` reads it, while restarting requires the explicit `Simulation.run(..., resume="interpolated")` policy. Ordinary `resume=True` refuses it. TDSE uses landed save planes. ```{code-block} python -from solprop.output import open_file, resume +from solprop.output import open_file, read_resume_state with open_file("run.h5") as stored: status = stored.outcome.status if stored.outcome is not None else "unrecorded" checkpoint = stored.terminal_checkpoint regular_planes = stored.n_saved -state = resume("run.h5") +state = read_resume_state("run.h5") restart_z = state.plane.z ``` @@ -261,7 +271,7 @@ history neither repeats nor loses a step. A later saved plane supersedes it. A low-storage step abandoned in flight cannot be checkpointed; the file then falls back to its latest running checkpoint, or to the checkpoint the run resumed from, and only without one to its last saved plane -([SEP 47](../../dev/seps/archive/sep-0047-run-ownership.md)). +([SEP 47](https://github.com/LupoLab/solprop/blob/main/docs/dev/seps/archive/sep-0047-run-ownership.md)). ### What a restart keeps and restores @@ -313,7 +323,7 @@ last flushed state and `running` status rather than a manufactured completion re **A run that keeps no field at its planes** (`fields="none"` or `"planes"`, [output](output.md#statistics-only-planes-which-planes-keep-their-field)) continues only from a plane that carries a field -([SEP 22](../../dev/seps/archive/sep-0022-memory-lean-spatial-execution.md)). The terminal +([SEP 22](https://github.com/LupoLab/solprop/blob/main/docs/dev/seps/archive/sep-0022-memory-lean-spatial-execution.md)). The terminal checkpoint always carries the field, whatever the run keeps at its planes: it costs one observation when the run stops, and a run stopped by an error, a signal or a call budget resumes from it. A file whose last regular plane kept no field and which holds @@ -505,4 +515,4 @@ Independent resumed computations meet the repository's accuracy-envelope policy; stored copies, history arrays and structural identifiers remain exact. Resuming a run from its file and the recipe it records were proposed and carried out by -[SEP 41](../../dev/seps/archive/sep-0041-recipes-and-front-ends.md). +[SEP 41](https://github.com/LupoLab/solprop/blob/main/docs/dev/seps/archive/sep-0041-recipes-and-front-ends.md). diff --git a/docs/guide/results/run-access.md b/docs/guide/results/run-access.md index be02202b9..67b5dcb5a 100644 --- a/docs/guide/results/run-access.md +++ b/docs/guide/results/run-access.md @@ -20,6 +20,10 @@ steps = output["step_history/counts"] # attempts belonging to each plane rows = output["step_stats/energy"] # (n_rows, n_modes, n_pol), with a periodic spec ``` +From a {py:class}`~solprop.output.memory.MemoryOutput` these arrays are read-only views of +the stored run: writing through one raises `ValueError`, so take `.copy()` of an array to +change it. + Stored spectra are in the **optics convention** and the file says so (`spectral_convention = "optics"`): a spectral phase read out of one is referenced to `t = 0` and has the sign a textbook gives it ([conventions.md](../../dev/conventions.md) @@ -148,7 +152,7 @@ the last bit. An adaptive Adams run -- the default -- continues from the march's the output keeps at each plane and checkpoint, and on every backend continues the uninterrupted run's computation, agreeing with it to rounding while the steps are the same ([the Adams integrator](../numerics/adams.md)). No resume promises identical bits -([SEP 25](../../dev/seps/archive/sep-0025-rounding-level-reproducibility.md)). +([SEP 25](https://github.com/LupoLab/solprop/blob/main/docs/dev/seps/archive/sep-0025-rounding-level-reproducibility.md)). For a resume to work in a *new process*, everything in the configuration has to hash the same way twice. Objects that carry their data — the pulses, the profiles, the responses, diff --git a/docs/guide/results/statistics-catalogue.md b/docs/guide/results/statistics-catalogue.md index 682ed0bcb..3bf4a29d5 100644 --- a/docs/guide/results/statistics-catalogue.md +++ b/docs/guide/results/statistics-catalogue.md @@ -335,7 +335,7 @@ without plasma and the TDSE route (which never evaluates an atom for a statistic Every backend uses the same host routine for an extra axis scan, or reuses a Radau axis row from its own node scan. CPU parity is qualified. A GPU build of the native backend brings only that row's spectrum to the host; GPU qualification remains follow-up work -([SEP 19](../../dev/seps/archive/sep-0019-field-scale-quadrature.md)). A multimode +([SEP 19](https://github.com/LupoLab/solprop/blob/main/docs/dev/seps/archive/sep-0019-field-scale-quadrature.md)). A multimode field's largest density need not lie on the axis, so the node maxima keep their meaning beside them. diff --git a/docs/guide/results/statistics-definitions.md b/docs/guide/results/statistics-definitions.md index b234575f8..c8de54172 100644 --- a/docs/guide/results/statistics-definitions.md +++ b/docs/guide/results/statistics-definitions.md @@ -89,8 +89,10 @@ contrast, raises. {py:class}`~solprop.profiles.ZProfile` paths at the plane's position; the catalogue gives each its own units. -{py:func}`~solprop.stats.zdw` root-finds $\beta_2 = 0$ for each mode, which is why it is -off by default. {py:func}`~solprop.stats.collect` narrows the search window to the grid's +{py:func}`~solprop.stats.zdw` searches $\beta_2 = 0$ for each mode, which is why it is +off by default; `collect` takes the zero nearest the grid's reference wavelength that no +line separates from it, passing over fine structure such as silica's OH bands (the rule +is in [mode sets](../waveguides/mode-sets.md)). {py:func}`~solprop.stats.collect` narrows the search window to the grid's own band with {py:func}`~solprop.stats.inband_wavelengths`, because a zero-dispersion point outside the simulated band says nothing about the run and hunting for one there drives every material model into extrapolation. Each call stands alone -- no search diff --git a/docs/guide/results/statistics.md b/docs/guide/results/statistics.md index dc62a7db5..edbf49d56 100644 --- a/docs/guide/results/statistics.md +++ b/docs/guide/results/statistics.md @@ -140,8 +140,9 @@ mode, which would dominate the step if paid on every accepted one; `peak_intensi admitted because its on-axis matrix is built once and rescaled with the taper rather than rebuilt on every call. A spec naming `zdw` in the periodic subset raises {py:class}`~solprop.exceptions.ProcessingError` when it is built. `zdw` searches the grid's own -band; a mode with one sign of $\beta_2$ at both ends of the band records `nan` with a -warning, and the run continues. +band and records the zero nearest the grid's reference wavelength +({py:func}`~solprop.modes.base.zdw` with `near`); a mode whose band holds no zero on the +reference's side of its resonances records `nan` with a warning, and the run continues. ## Which names a basis admits @@ -647,15 +648,15 @@ output["stats/aperture_spectrum"] # (n_z, 4, n_omega) in J/(rad/s) The [far-field statistics tutorial](../../auto_tutorials/free_space/plot_07_far_field_statistics.rst) runs all five on a free-space run. The design is -[SEP 23](../../dev/seps/archive/sep-0023-far-field-aperture-spectra.md), and the -medium measure is [SEP 34](../../dev/seps/archive/sep-0034-medium-flux.md). +[SEP 23](https://github.com/LupoLab/solprop/blob/main/docs/dev/seps/archive/sep-0023-far-field-aperture-spectra.md), and the +medium measure is [SEP 34](https://github.com/LupoLab/solprop/blob/main/docs/dev/seps/archive/sep-0034-medium-flux.md). ## What `collect` guarantees Each statistic is evaluated by the public function of the same name, so there is exactly one definition of each and no path computes anything twice: no host definition beside a device one, and a backend's fused pass is validated against it. Reductions run over the contiguous frequency and time axes, and two evaluations of the -same input agree to rounding ([SEP 25](../../dev/seps/archive/sep-0025-rounding-level-reproducibility.md)). Every value is a NumPy array — zero-dimensional for a scalar — and its shape +same input agree to rounding ([SEP 25](https://github.com/LupoLab/solprop/blob/main/docs/dev/seps/archive/sep-0025-rounding-level-reproducibility.md)). Every value is a NumPy array — zero-dimensional for a scalar — and its shape is the `shape` field of its {py:class}`~solprop.stats.StatDefinition`. Spatial statistics are in field units on the geometry's transverse integration measure; diff --git a/docs/guide/setup/grids.md b/docs/guide/setup/grids.md index 66047d4e8..f53dc9ce1 100644 --- a/docs/guide/setup/grids.md +++ b/docs/guide/setup/grids.md @@ -157,8 +157,10 @@ $\omega_{\max}^{\mathrm{win}}=1.1\omega_{\max}$. 1. The fine spacing is $\delta t_{\mathrm{fine}}=2\pi/(\mathtt{ffac}\,\omega_{\max})$, or the requested `dt` if that is finer. The default is `ffac=6`, providing sampling for the third-harmonic content of a cubic response. `ffac=4` suffices - for a response without that content. The allowed minimum is 2; at that minimum - the upper collar is truncated rather than fully represented. + for a response without that content. The allowed minimum is 2.2, which puts the + fine Nyquist frequency $\mathtt{ffac}\,\omega_{\max}/2$ at the collar's upper edge + $1.1\omega_{\max}$; a smaller value is refused, because the coarse Nyquist bin + would then lie inside the collar and keep field. 2. The fine size `n_to` is an allowed transform size at least `trange/((1 - 2 f_c) dt_fine)`, the request widened to hold the temporal collar outside it ($f_c$ below). The realised duration is $T=n_{to}\delta t_{\mathrm{fine}}$, @@ -382,8 +384,10 @@ the original real signal, following {py:func}`scipy.signal.hilbert`. The field spectral-density formula above uses the interior-bin prefactor. For an arbitrary array with nonzero endpoint bins, summing that density over all bins therefore differs from the exact energy formula. Use -{py:func}`~solprop.fourier.energy_omega` for exact discrete energy. Normal -propagation grids suppress those endpoints through their spectral window. +{py:func}`~solprop.fourier.energy_omega` for exact discrete energy. On a field grid +both endpoints lie outside the spectral collar, where its window is exactly zero, so a +windowed spectrum carries nothing there; {py:meth}`~solprop.grid.TimeGrid.validate` +refuses a field grid whose collar reaches either endpoint. ## Check a sampled pulse diff --git a/docs/guide/setup/model-selection.md b/docs/guide/setup/model-selection.md index 22c7cf968..4b9a058b8 100644 --- a/docs/guide/setup/model-selection.md +++ b/docs/guide/setup/model-selection.md @@ -214,13 +214,12 @@ repeatability tests pass on a data-centre NVIDIA GPU (CUDA) and an AMD Instinct `backend="auto"`, the default, is `native`, and it **never falls back**: it refuses if the native package is missing or the processor is below its minimum, and a problem the native -backend refuses is refused, by name, and you choose `numpy_ref` for it explicitly. Its one -exception is the TDSE response, which it runs on `numpy_ref` +backend refuses is refused, by name, and you choose `numpy_ref` for it explicitly ([which backend a run uses](../performance/backends.md#which-backend-a-run-uses)). Whether the native backend runs on the CPU or on a GPU is decided by how it was built. The [backends chapter](../performance/backends.md) compares the backends and budgets memory; [the native backend](../performance/native.md) says how to build it, -locally or for a GPU; [performance](../performance/tuning.md) covers threads and tuning. Every -compiled backend agrees with `numpy_ref`, the oracle, to a rounding bound derived before +locally or for a GPU; [performance](../performance/tuning.md) covers threads and tuning. The +native backend agrees with `numpy_ref`, the oracle, to a rounding bound derived before any measurement; the measured departures are a few units in the last place (the bounds are in the [backend design notes](../../dev/backends.md)). diff --git a/docs/guide/setup/pulses.md b/docs/guide/setup/pulses.md index 0fb5fb4dd..04582be56 100644 --- a/docs/guide/setup/pulses.md +++ b/docs/guide/setup/pulses.md @@ -73,8 +73,10 @@ $m$ is; a $\operatorname{sech}^2$ pulse uses $\tau_w = \tau/[2\ln(1+\sqrt2)]$. ## Energy or peak power, never both A pulse is scaled by its `energy` or by its `peak_power`. Giving both, or neither, is an -error rather than a precedence rule. Both are realised *exactly* on the grid: the -spectrum is built, the +error rather than a precedence rule. That choice belongs to the three shaped pulses, +`GaussianPulse`, `SechPulse` and `CustomPulse`: the measured `DataPulse` and +`TimeDataPulse` are scaled by `energy` alone, and `CWPulse` by its `average_power`. +Whichever is given is realised *exactly* on the grid: the spectrum is built, the phase is applied, the realised quantity is measured with the grid's own functional, and one multiplication by a square root fixes it. Nothing is left to a quadrature error, and the round trip closes to a part in $10^{12}$ or better. @@ -110,12 +112,12 @@ The group delay is $T_g(\omega) = \mathrm{d}\phi/\mathrm{d}\omega$, so - a positive `t0` makes the pulse **arrive later** (it must lie strictly inside the window: a delay is a spectral phase, and one past the half-window would wrap the pulse round to the other end, so it is refused); -- `phase[1]`, the first-order coefficient, is a group delay and does exactly what `t0` +- `phases[1]`, the first-order coefficient, is a group delay and does exactly what `t0` does; -- a positive `phase[2]` (GDD) gives $T_g = \phi_2(\omega-\omega_p)$, so the blue arrives +- a positive `phases[2]` (GDD) gives $T_g = \phi_2(\omega-\omega_p)$, so the blue arrives after the red: an **upchirp**, the sign of propagation through normally dispersive glass; -- `phase[0]` is the carrier-envelope phase at the pulse's own peak, on either grid and +- `phases[0]` is the carrier-envelope phase at the pulse's own peak, on either grid and independent of the window length. **The stored array is the FFT convention.** The conversion happens once per build, where @@ -371,7 +373,7 @@ use this. A pulse given by keywords enters the first mode of a multimode run, and the others fill through the nonlinearity. `launch=` puts it into chosen modes instead, on `prop_capillary`, `prop_waveguide` and their `Simulation` constructors -([SEP 41](../../dev/seps/archive/sep-0041-recipes-and-front-ends.md)): a mapping from a mode to +([SEP 41](https://github.com/LupoLab/solprop/blob/main/docs/dev/seps/archive/sep-0041-recipes-and-front-ends.md)): a mapping from a mode to its share, or to a share and a phase in radians. ```python @@ -475,4 +477,4 @@ Where solprop's choices differ from Luna.jl's, the differences are listed in For a complete launch and analysis, follow the [RDW lesson](../../introduction/lessons/plot_01_rdw.rst) or [soliton lesson](../../introduction/lessons/plot_02_soliton.rst). [Polarisation](polarisation.md) extends the launch to vector fields; [beam setup](../free-space/beams.md) adds a transverse profile. Measured-spectrum loading with `load_spectrum` and the launch into chosen modes were -proposed and carried out by [SEP 41](../../dev/seps/archive/sep-0041-recipes-and-front-ends.md). +proposed and carried out by [SEP 41](https://github.com/LupoLab/solprop/blob/main/docs/dev/seps/archive/sep-0041-recipes-and-front-ends.md). diff --git a/docs/guide/setup/recipes.md b/docs/guide/setup/recipes.md index e50decfd1..3f6551101 100644 --- a/docs/guide/setup/recipes.md +++ b/docs/guide/setup/recipes.md @@ -10,7 +10,7 @@ build the same simulation, configuration hash included. Recipes describe the keyword routes `gnlse`, `capillary` and `waveguide`, and the free-space routes `radial`, `free` and `planar`, whose keywords are objects ([below](#free-space-routes)). They are specified in -[SEP 41](../../dev/seps/archive/sep-0041-recipes-and-front-ends.md). +[SEP 41](https://github.com/LupoLab/solprop/blob/main/docs/dev/seps/archive/sep-0041-recipes-and-front-ends.md). ## A recipe @@ -437,18 +437,20 @@ A test reads the source for every refusal marked with a rule and holds it to ```text solprop run rdw.toml -o rdw.h5 [--progress log] [--resume] solprop check rdw.toml # print the issues; exit 1 on an error -solprop export rdw.toml --python # print the equivalent script +solprop export rdw.toml # print the equivalent script (--form python) solprop resume rdw.h5 # continue a run from its file alone solprop scan ... # python -m solprop.scan, unchanged solprop calibrate --show # the native backend's machine profile, if any ``` `python -m solprop` is the same command. `check` exits 0 when the recipe builds (warnings -included), 1 when it does not, and 2 when the file cannot be read. `run` and `resume` stop +included), 1 when it does not, and 2 when the file cannot be read. Every command exits 2 +on arguments it refuses, and on a recipe or file it cannot read or build or a run or scan +that fails, which it reports in one `solprop:` line. `run` and `resume` stop cleanly on Ctrl-C, writing the state, and `solprop resume` continues it ([resuming from the file alone](../results/resuming.md#resuming-from-the-file-alone)). `solprop calibrate` reads and manages the native backend's machine calibration -([SEP 46](../../dev/seps/archive/sep-0046-machine-calibration.md)): `--show` prints the profile +([SEP 46](https://github.com/LupoLab/solprop/blob/main/docs/dev/seps/archive/sep-0046-machine-calibration.md)): `--show` prints the profile this allocation would use, with each setting beside the built-in value it replaces, or says that the built-in table applies; `--export FILE` and `--import FILE` move a profile between stores, for example to share one per node type of a cluster; and `--clear` @@ -478,6 +480,6 @@ its reason, in the test that holds the examples to the gallery, so the list stay and the pressure-and-energy scan, built with `with_mixture` and `with_input`. This page documents the functionality proposed and implemented by -[SEP 41](../../dev/seps/archive/sep-0041-recipes-and-front-ends.md). +[SEP 41](https://github.com/LupoLab/solprop/blob/main/docs/dev/seps/archive/sep-0041-recipes-and-front-ends.md). The saved planes follow -[SEP 51](../../dev/seps/archive/sep-0051-save-planes.md). +[SEP 51](https://github.com/LupoLab/solprop/blob/main/docs/dev/seps/archive/sep-0051-save-planes.md). diff --git a/docs/guide/setup/running.md b/docs/guide/setup/running.md index 5b75cfaca..ac6c6c05e 100644 --- a/docs/guide/setup/running.md +++ b/docs/guide/setup/running.md @@ -479,7 +479,9 @@ planes and the statistics a fresh run takes. once just as `translate()` does. Those two are what the run-layer functions take when you drive the loop over save planes yourself, for example `solprop.backends.registry.select(name, problem, request)` to construct a backend for -{py:func}`~solprop.driver.run.run_problem`. +{py:func}`~solprop.driver.run.run_problem`, which also takes the run's start +(`solprop.backends.session.Start.entrance(problem)` for a fresh run) and its +{py:class}`~solprop.output.metadata.RunMetadata` as the keywords `start` and `metadata`. {py:class}`~solprop.driver.settings.SimulationSettings` holds everything numerical: the controller and its tolerances, the save planes, the step limits, a fixed schedule, @@ -520,7 +522,8 @@ change what a simulation is built from: its `grid`, `modes`, `responses`, `initi `initial_z`, `noise`, `profiles`, `configuration`, `frame` and the rest are read-only, because the input was built, and the record is derived, from them when it was constructed. Assigning one raises `AttributeError`, naming these methods; only -`settings` may be replaced, before the first translation. +`settings` may be replaced: wholly before the first translation, and after it in the +execution settings that {py:attr}`~solprop.driver.simulation.Simulation.settings` lists. `SimulationSettings.fields` and `field_planes` choose which saved planes keep their field — every one by default, the named ones, or none for a run wanted as statistics @@ -547,7 +550,7 @@ that once. {py:meth}`~solprop.driver.simulation.Simulation.runner` translates (o the cached translation) and constructs one backend; each {py:meth}`~solprop.driver.runner.SimulationRunner.run` then loads one input into it and runs the save-plane loop -([SEP 22](../../dev/seps/archive/sep-0022-memory-lean-spatial-execution.md) §5.2): +([SEP 22](https://github.com/LupoLab/solprop/blob/main/docs/dev/seps/archive/sep-0022-memory-lean-spatial-execution.md) §5.2): ```{code-block} python import dataclasses @@ -647,7 +650,7 @@ instructions, and it refuses a bad input before it is loaded. **The boundary check on a free-space scan.** The default [`boundary_check`](../numerics/boundaries.md) reads a free-space run's transverse edge at the launch, at every plane and at every read, and a requested collar's at every committed step. `native` does it where the -state lives, with only numbers crossing, even on a device ([SEP 44](../../dev/seps/archive/sep-0044-native-edge-read.md)). `numpy_ref` reads a host copy of the state +state lives, with only numbers crossing, even on a device ([SEP 44](https://github.com/LupoLab/solprop/blob/main/docs/dev/seps/archive/sep-0044-native-edge-read.md)). `numpy_ref` reads a host copy of the state instead, and transform it out of place: on a device, a whole state's copy at each read. On native CPU at 256 × 256 × 48, with sixteen steps and two planes at sixteen threads, the check took a point from 1.8 to 2.0 s and from 1.5 to 2.1 volumes above the level before the run. A scan whose window is already settled can @@ -724,7 +727,7 @@ What the handler cannot do, it refuses by name: {py:class}`~solprop.exceptions.OutputError`, and so does whatever reads a run through them; `key in handler` answers `False`. - A resume: `resume=True` needs a path, and - {py:func}`~solprop.output.hdf5.check_cache`, {py:func}`~solprop.output.hdf5.resume` and + {py:func}`~solprop.output.hdf5.check_cache`, {py:func}`~solprop.output.hdf5.read_resume_state` and {py:func}`~solprop.output.resumable.resumability` read a file and refuse any handler. - A second run: having kept no plane, it has nothing to continue, so build one per run. - A TDSE run, whose call ledger has to be recorded. @@ -736,4 +739,4 @@ range ({py:class}`~solprop.exceptions.MaterialRangeWarning`). Read `peak_ionisat in the callable where that matters. The length and the saved planes were proposed and implemented by -[SEP 51](../../dev/seps/archive/sep-0051-save-planes.md). +[SEP 51](https://github.com/LupoLab/solprop/blob/main/docs/dev/seps/archive/sep-0051-save-planes.md). diff --git a/docs/guide/setup/spatial-decompositions.md b/docs/guide/setup/spatial-decompositions.md index 1315bba82..fa1c6396f 100644 --- a/docs/guide/setup/spatial-decompositions.md +++ b/docs/guide/setup/spatial-decompositions.md @@ -299,7 +299,7 @@ with {class}`~solprop.modes.antiresonant.VincettiMode` supplying the index. $r$, wall $t$, $N$ of them, clear gap $\delta = 2[(a+r)\sin(\pi/N) - r]$ — enter only through the fitted $n_{\rm eff}(\omega)$ and loss of Vincetti (2016), Vincetti and Rosa (2019) and Rosa, Melli and Vincetti (2021), in the form set out in -[the five conventions](../waveguides/antiresonant.md#the-five-conventions). +[the four conventions](../waveguides/antiresonant.md#the-four-conventions). **Propagation.** Exactly the capillary's. The field normalisation and the protocol's `aeff` are Marcatili's. The fitted area `effective_area(omega)` is a @@ -435,7 +435,7 @@ agreement is where the scalar routes on this page are the same physics. **Not valid when** the route refuses it; the refusals are not approximations: `peak_intensity` and the scalar-route power names (use `analytic_flux`), `quadrature_error` (no embedded rule), a nonorthogonal basis, a guide that does not span the active band, -`n_pol` > 1, and numeric `observable_rtol` ([declared, refused, +and `n_pol` > 1 ([declared, refused, recorded](../waveguides/general-modal.md#declared-refused-recorded)). **Entry point.** `prop_waveguide((), length, provider=guide, ...)` and diff --git a/docs/guide/waveguides/antiresonant.md b/docs/guide/waveguides/antiresonant.md index 43c4d63af..2f406fb2a 100644 --- a/docs/guide/waveguides/antiresonant.md +++ b/docs/guide/waveguides/antiresonant.md @@ -37,7 +37,7 @@ propagation_area = mode.aeff() # Marcatili field integral, m^2 To propagate, pass `lattice=` beside an integer `modes=` to `prop_capillary` or `Simulation.from_capillary`, or build a numbered set with `ModeCollection.vincetti`. Supplied mode objects carry their own geometry, so combining them with `lattice=` is -refused. The [antiresonant tutorial](../../auto_tutorials/waveguides/plot_01_antiresonant_fibre) +refused. The [antiresonant tutorial](../../auto_tutorials/waveguides/plot_01_antiresonant_fibre.rst) shows argon pressure tuning and a short Kerr propagation. The model combines the confinement-loss fits of @@ -45,15 +45,15 @@ The model combines the confinement-loss fits of [Vincetti and Rosa (2019)](https://doi.org/10.1364/OE.27.005230) with the dispersion fit of [Rosa, Melli and Vincetti (2021)](https://doi.org/10.3390/fib9100058). These are empirical fits, not an exact solution of Maxwell's equations for the tube -geometry. Every coefficient was transcribed from the papers and checked term by term -against the published text. The minimum-loss prefactor is the 2019 paper's +geometry. Every coefficient is the papers' own, checked term by term against the +published text. The minimum-loss prefactor is the 2019 paper's $3\times10^{-4}$, the minimum, rather than the 2016 paper's average $5\times10^{-4}$. The 2016 equation (its Eq. 3) has been checked against the typeset page and matches term for term, apart from the prefactor; the paper's normalised-loss definition carries an extra $\sqrt{r/\lambda}$ that would make it inconsistent with Eq. 3, which is the dimensionally consistent form and the one used. In -five places the printed papers and earlier published implementations of the model -differ; the form solprop uses is decided [below](#the-five-conventions), term by term. +four places the printed papers and earlier published implementations of the model +differ; the form solprop uses is decided [below](#the-four-conventions), term by term. With $\lambda=2\pi c/\omega$, tube index $n_t=\operatorname{Re}n_{\rm cladding}$, and gas index $n_g$ from the declared mixture, the normalised wall frequency is @@ -93,7 +93,7 @@ $$ \begin{aligned} R_{\rm eff}&=\left[1.027+10^{-3}(F+2/F^4)\right] \sqrt{a^2+\frac N\pi\frac3{64}r^2 - \left[1+(3+10\lambda/a)\delta/r\right]},\\ + \left[1+(3+20\lambda/a)\delta/r\right]},\\ L_i(F,F_0)&=\frac{F_0^2-F^2}{(F^2-F_0^2)^2+(0.03F)^2},\\ \Delta n&=4.5\times10^{-7}(1-t/r)^{-4}(\lambda/a)^2 A(1) \sum_{\nu=1}^{n_{\rm terms}} @@ -103,6 +103,9 @@ L_i(F,F_0)&=\frac{F_0^2-F^2}{(F^2-F_0^2)^2+(0.03F)^2},\\ \end{aligned} $$ +The coefficient 20 of $\lambda/a$ is Rosa 2021's: its Eq. 10 is typeset as +$3+2\cdot10\lambda/R_{co}$, Melli et al. (2025) Eq. 7 writes $3+20\lambda/R_{co}$, and +earlier implementations carry 20 too. The square on $r$ follows from the trapezoid area in the geometric derivation. The waveguide term is the first-order expansion of $\beta=\sqrt{n_g^2k^2-(u_{nm}/R_{\rm eff})^2}$, one power of $n_g$, as the parent's full model has it; the neglected @@ -124,7 +127,7 @@ where the fitted denominator changes sign. It is a diagnostic fit and does not replace the positive field integral used by the nonlinear transform or the area stored in output metadata. -### The five conventions +### The four conventions Earlier published implementations of the Vincetti model (pyJCMwave among them) share one form of the fits; the printed papers give another. One rule decides each term: a @@ -138,15 +141,25 @@ of them) in argon at 294 K, as solprop's form minus the earlier one. | term | solprop | earlier implementations | printed | reason | size | |---|---|---|---|---|---| | dispersion width $\gamma_d$ | 0.03 | 0.03 | 0.003 (2021 eq. 2) | fits the FEM better than the printed value: the near-resonance index is 3.2× (vacuum) and 1.9× (argon) worse with 0.003 | none | -| $R_{\rm eff}$ coefficient | $3+10\lambda/a$ | 20 | $3+2\cdot10\lambda/R_{co}$, that is 20 (2021 eq. 10, typeset); Melli et al. 2025 eq. 7 writes 20 | negligible (0.9 % of the decrement, a quarter of the fit's median residual); solprop's 10 came from a misreading of the printed bracket and is kept for now, with the vacuum index RMSE 13 % better than with 20 | $n_{\rm eff}$ $-1.7\times10^{-6}$ at 800 nm; $\beta_2$ $-7.7$ fs²/m (1.7 %) at 800 nm, $+2.2$ at 1030 nm; area $-1.0\,\%$ | | waveguide decrement | $D_0/n_g$ | $D_0/n_g^2$ | $D_0/n_g$ (2021 eqs. 21, 23) | physical: the expansion of $\beta$; the FEM's 10 bar index is predicted from its vacuum index to $2.2\times10^{-8}$ with one power and $6.7\times10^{-7}$ with two | 30 bar: $n_{\rm eff}$ $-1.3\times10^{-6}$ at 800 nm; $\beta_2$ $+0.1$ fs²/m at 800 nm, $+8.9$ (1.7 %) at 1030 nm | | area prefactor | $1/n_g$ | none | $1/n_g$ (2021 eq. 22) | physical: with the single-power decrement the area is fill independent, as the FEM's is to $10^{-4}$ | 30 bar: area $-0.8\,\%$ | | normalised frequency | $\sqrt{n_t^2-n_g^2}$ wherever $F$ enters | $\sqrt{n_t^2-1}$ | $\sqrt{n_t^2-n_g^2}$ (2021 eq. 23) | physical: the wall's slab resonance in the filled core | 30 bar: the $q=1$ loss peak 2.5 nm shorter (0.08 nm at 1 bar); loss ×0.74 at 400 nm, ×1.01 at 800 nm; $\beta_2$ $+71$ fs²/m (1.3 %) at 400 nm, $+2.4$ at 800 nm | -All five together at 30 bar: $n_{\rm eff}$ $-3.0\times10^{-6}$ and $\beta_2$ $-4.9$ -fs²/m at 800 nm (where $\beta_2=+74$ fs²/m), $+70$ fs²/m at 400 nm, area -$-2.4\,\%$; at 1 bar $-1.7\times10^{-6}$, $-7.7$ fs²/m at 800 nm, $+36$ at 400 nm, -area $-1.0\,\%$. Evacuated, only the radius coefficient acts. The earlier form can be +All four together at 30 bar: $n_{\rm eff}$ $-1.4\times10^{-6}$ and $\beta_2$ $+2.6$ +fs²/m at 800 nm (where $\beta_2=+88$ fs²/m), area $-1.5\,\%$; at 1 bar +$-4.5\times10^{-8}$, $+0.1$ fs²/m at 800 nm, area $-0.05\,\%$. Evacuated, the two +forms agree. + +The effective-radius coefficient is not among them, since the papers and earlier +implementations agree on 20. On the finite-element fibre a coefficient of 10 would fit +the vacuum index better (RMSE $7.5\times10^{-6}$ against $8.7\times10^{-6}$ over the +79 rows), the argon index equally ($4.45\times10^{-6}$ against $4.47\times10^{-6}$ +away from resonance), and the fitted area better in vacuum (median residual 2.5 % +against 3.1 %) but worse at 10 bar (1.2 % against 0.3 %). The term is 0.9 % of the +decrement, below the fit's median residual, so by the rule above the printed value +is used. + +The earlier form can be assembled from the same code as `solprop.modes.antiresonant.LEGACY_CONVENTIONS`, which the tests use to compare with earlier implementations and which no propagation uses; solprop's own form is checked @@ -168,25 +181,25 @@ The model is compared with converged finite-element (FEM) solutions of one fibre $t/r=0.017$ fibre outside the fits' validated 0.05–0.2. The FEM data cover 79 wavelengths from 200 to 1500 nm evacuated and 20 from 355 to 946 nm at 10 bar of argon and 293 K. The comparison uses the FEM's own silica index (without absorption) and the -same three-pole argon Sellmeier fit (solprop's `kingston` source, whose gas indices +same three-pole argon Sellmeier fit (Kingston's, as Luna uses it, whose gas indices match the FEM's exactly). No parameter was refitted. -With the conventions above, the index residual has RMSE $7.5\times10^{-6}$ over -the 79 vacuum rows and, away from the resonances, a median of 2.9 % of the -waveguide decrement (p90 12 %, maximum 26 %); at 10 bar $4.5\times10^{-6}$ and -0.7 %, and the vacuum-to-argon change of the index is reproduced to -$7\times10^{-8}$. The loss in the interior of the first window is 0.5–1.6 times +With the conventions above, the index residual has RMSE $8.7\times10^{-6}$ over +the 79 vacuum rows and, away from the resonances, a median of 3.4 % of the +waveguide decrement (p90 12 %, maximum 25 %); at 10 bar $4.5\times10^{-6}$ and +0.5 %, and the vacuum-to-argon change of the index is reproduced to +$8\times10^{-8}$. The loss in the interior of the first window is 0.5–1.6 times the FEM's; at the band edges the fit's Lorentzians are far narrower than the FEM resonances and the loss is up to 150 times too low. The fitted area's median -residual is 2.5 % (vacuum) and 1.2 % (argon) away from resonance. +residual is 3.1 % (vacuum) and 0.3 % (argon) away from resonance. **The group-velocity dispersion is the quantity this model is used for, and it is where the fit is weakest.** In the first transmission band of this fibre the FEM's -own $\beta_2$ is more negative than the model's by 1 % at 607 nm, 18 % at 782 nm, -48 % at 913 nm and 70 % at 1013 nm in vacuum ($-1268$ against $-744$ fs²/m), and by -24–67 % over 720–913 nm at 10 bar. It is the curvature of the model's U-shaped index +own $\beta_2$ is more negative than the model's by 3 % at 607 nm, 20 % at 782 nm, +49 % at 913 nm and 70 % at 1013 nm in vacuum ($-1268$ against $-745$ fs²/m), and by +24–68 % over 720–913 nm at 10 bar. It is the curvature of the model's U-shaped index residual (+24 % of the decrement at 400 nm, about zero at 800 nm, +5 % at 1360 nm), -not a differencing artefact, and none of the five conventions moves it by more than +not a differencing artefact, and none of the four conventions moves it by more than 2 %. The 2019 and 2021 fits were validated for $t/r$ between 0.05 and 0.2; this fibre lies outside that range, and so does the tutorial's. These numbers are pinned as a regression test in `tests/modes/test_vincetti_fem.py`. diff --git a/docs/guide/waveguides/capillaries.md b/docs/guide/waveguides/capillaries.md index 386b9fc50..5ea47523d 100644 --- a/docs/guide/waveguides/capillaries.md +++ b/docs/guide/waveguides/capillaries.md @@ -112,7 +112,8 @@ rather than silently dropped), and `model="reduced"` is refused because the condensation inverts the full model's eigenvalue. A tube lattice (`lattice=`) is refused beside it: an antiresonant fibre's loss is its tubes' resonances, not a boundary condition at one radius. Two -polarisations and a noise model are refused too, each by name. +polarisations and the `modified` noise model are refused too, each by name; the default +`input` draw is admitted. **Validity.** The condensation is quasi-static and paraxial. Three dimensionless ratios are computed for the highest retained mode over the band the run **scores** — the @@ -307,7 +308,8 @@ What applies it, and what does not: sparse or mixed set, tabulated modes) stays adiabatic and warns ({class}`~solprop.exceptions.AdiabaticTaperWarning`). * **What it refuses**, by name and naming the opt-out: an envelope grid (no coupled - flow is built on its frequency axis), a noise model, a second field component, and a + flow is built on its frequency axis), the `modified` noise model (the default `input` + draw is admitted), a second field component, and a radius profile without an analytic slope (the connection is $a'/a$). Beside a `wall`, `taper_coupling=False` is refused: the wall carries the connection. * **The step.** As with a wall, the interaction picture inverts the flow over each @@ -412,12 +414,14 @@ launch, each with three radial orders and the vector wall. ## Backends -Both CPU backends run the wall — scalar and TE/TM, straight, tapered or in a gradient — -and the taper coupling without one, with the frozen split. +Both backends run the wall — `numpy_ref` and `native`, on the CPU and on the GPU builds — +scalar and TE/TM, straight, tapered or in a gradient, and the taper coupling without one, +with the frozen split. The **adiabatic** opt-out of a multimode taper (`taper_coupling=False`) puts every mode on its own row of the linear operator, and where that expansion does not resolve (a -metre of kinked taper, for instance) it takes the general z table, which every CPU -backend runs, the native CPU build included, so `backend="auto"` runs such a comparison; -the native backend's GPU builds refuse it by name, naming the CPU backends. On the capillary's small grids a locally built native backend is the fastest backend at one -to four threads; see [backends](../performance/backends.md), [the native backend](../performance/native.md) and +metre of kinked taper, for instance) it takes the general z table, which `numpy_ref` and +the native CPU build run, so `backend="auto"` on a CPU build runs such a comparison; +the native backend's GPU builds refuse it by name, naming what runs it. On the capillary's +small grids a native backend built on the machine that runs it is the fastest choice at +one to four threads; see [backends](../performance/backends.md), [the native backend](../performance/native.md) and [performance](../performance/tuning.md). diff --git a/docs/guide/waveguides/capillary-model.md b/docs/guide/waveguides/capillary-model.md index 81db9118a..14d00253c 100644 --- a/docs/guide/waveguides/capillary-model.md +++ b/docs/guide/waveguides/capillary-model.md @@ -52,7 +52,7 @@ empty = MarcatiliMode(125e-6) # evacuated: gas=None, pressure 0 The defaults are `kind="HE"`, `n=1`, `m=1`, `model="full"`, the model's own loss (`alpha=None`, `loss_scale=1.0`), a fused-silica cladding and a fill at 293.15 K. A gas named here is the built-in gas, optmat's -([SEP 3](../../dev/seps/archive/sep-0003-optmat-materials.md)): its polarisability and its +([SEP 3](https://github.com/LupoLab/solprop/blob/main/docs/dev/seps/archive/sep-0003-optmat-materials.md)): its polarisability and its equation of state (one species per gas, shared by every mode that names it), as in a run's fill. `phi` rotates the mode about the axis ([normalisation and effective area](#normalisation-and-effective-area)), diff --git a/docs/guide/waveguides/coherent-wall.md b/docs/guide/waveguides/coherent-wall.md index e2780b458..17ce9eeed 100644 --- a/docs/guide/waveguides/coherent-wall.md +++ b/docs/guide/waveguides/coherent-wall.md @@ -74,7 +74,7 @@ builds exactly that — sharing one polarisation angle, one capillary model and declared guide. A sparse set, a mixed family, two polarisations and the `modified` noise model are refused by name, each at the layer that owns the refusal. The `input` noise model is admitted -([SEP 37](../../dev/seps/archive/sep-0037-noise-and-stepper-defaults.md), section 6): its +([SEP 37](https://github.com/LupoLab/solprop/blob/main/docs/dev/seps/archive/sep-0037-noise-and-stepper-defaults.md), section 6): its draw is part of the launch, one photon per channel and bin in the $\mathrm{HE}_{1m}$ set, which is orthonormal in true power (real Bessel profiles, orthogonal on the core, each normalised to its own power), and the block propagates it like any field. Both diff --git a/docs/guide/waveguides/general-modal.md b/docs/guide/waveguides/general-modal.md index 2bf2640e7..62830d166 100644 --- a/docs/guide/waveguides/general-modal.md +++ b/docs/guide/waveguides/general-modal.md @@ -93,8 +93,8 @@ output = prop_waveguide( ``` The run warns once, with a {py:class}`~solprop.exceptions.GeneralModalBasisWarning`: -thirteen knots leave the interpolated basis $1.1\times10^{-4}$ from orthonormal near -1.73 µm, at the long-wavelength edge of the active band where the launched pulse puts no +thirteen knots leave the interpolated basis $1.0\times10^{-4}$ from orthonormal near +1.72 µm, at the long-wavelength edge of the active band where the launched pulse puts no light. The warning, and why it is a warning rather than a refusal, are explained under [normalisation](modal-projection.md#normalisation-and-why-the-power-weight-is-one); more knots remove it. @@ -126,7 +126,7 @@ the basis's flux metric is the pulse's, and the run records `incident=` takes a {class}`~solprop.pulses.SpatialPulse` — a Gaussian or super-Gaussian beam carrying its own temporal pulse — and launches what the guide's channels capture of it, coupled under a declared model -([SEP 31](../../dev/seps/archive/sep-0031-simulation-coupling.md); +([SEP 31](https://github.com/LupoLab/solprop/blob/main/docs/dev/seps/archive/sep-0031-simulation-coupling.md); [coupling simulations](../workflows/coupling.md)): ```text @@ -199,10 +199,9 @@ Every gas keyword is **refused by name** beside a provider — `gas`, `pressure` `temperature`, `kerr`, `thg`, `plasma`, `raman`, `n_r`, `n_theta` and the rest — because a guide owns its materials, its responses and its transverse rule, and a keyword silently ignored would let you believe a fill or a resolution had been applied. -`observable_rtol` and `observable_atol` are accepted as `None`, which means the -solver's own `rtol` and `atol`: the route's basis is orthonormal in true power, so the -controller's weighted norm on the amplitudes already is a norm on the physical channel -powers. +The accuracy of the run's observables is the solver's own `rtol` and `atol`: the +route's basis is orthonormal in true power, so the controller's weighted norm on the +amplitudes already is a norm on the physical channel powers. For a worked example that runs and plots, see {doc}`../../auto_tutorials/waveguides/plot_05_general_modal`; for a **graded-index** guide, its @@ -217,7 +216,7 @@ multimode fibre at full size. **A guide must be solved over at least twice the band a run declares.** `Grid.active_mask` runs from half the lowest declared frequency to the window's highest, so the `FieldGrid` above, declared over 790–890 nm, has an active band of -724.9–1774.0 nm — a factor 2.45 in frequency — and the guide's table must cover all of +722.3–1763.7 nm — a factor 2.44 in frequency — and the guide's table must cover all of it, at the low end of which a weakly bound mode reaches furthest into the cladding and a truncating node rule discards most of it. Outside the table's own knots the stored reference is an explicit zero, and a run that reaches there is refused with both bands @@ -233,27 +232,28 @@ not the nonlinearity, is what the step controller reacts to. On the millimetre a general route takes 42 accepted steps with the collar and exactly 10 without, and `prop_capillary` on the same grid does the same thing: this is not the general route's doing, it only matters more here because a general modal step costs about a hundred -fused ones. Two settings change it: `absorber_scheme="split_step"` applies the same rates +fused ones. Two keywords change it: `absorber_scheme="split_step"` applies the same rates once per step, outside the stage, and reaches the same answer in the collar-free step -count; `absorber=None` in the settings removes the absorber, for a lossless check. -`absorber=None` passed to `from_waveguide` itself means "build the default collar", so -replace the settings before the first `translate()` or `run()` instead: +count; `absorber=False` switches the temporal and spectral collars off and keeps the hard +band mask, for a lossless check. `absorber=None`, the default, builds the default collar. ```{code-block} python -import dataclasses - from solprop.driver import Simulation simulation = Simulation.from_waveguide( - (), length, provider=guide, grid=grid, wavelength=835e-9, fwhm=40e-15, energy=4e-11 -) -simulation.settings = dataclasses.replace( - simulation.settings, absorber_scheme="split_step" + (), + length, + provider=guide, + grid=grid, + wavelength=835e-9, + fwhm=40e-15, + energy=4e-11, + absorber_scheme="split_step", ) ``` -`prop_gnlse` builds no absorber at all, so a like-for-like comparison with it needs one -of the two. +`prop_gnlse` builds its own grid's default collar too, so a like-for-like comparison with +it passes `absorber=False` to both. ## Noise, statistics and what comes back @@ -269,10 +269,10 @@ under unitary mixing, so drawing again in the declared basis would be a differen stochastic model. A basis with unequal channel norms is neither of those and is refused by name. -The route's statistics are **`physical_energy`** and **`analytic_flux`**, and they are -its defaults. Both are scalars: a coordinate energy and a coordinate power are not -additive on a basis that is not orthonormal, so the names that promise one are refused -here rather than redefined. `physical_energy` is the same-frequency product of the state +The route's default statistics are `omega0`, **`physical_energy`**, **`analytic_flux`**, +`fwhm_t` and `fwhm_t_outer`. The two in bold are its own names, and both are scalars: a +coordinate energy and a coordinate power are not additive on a basis that is not +orthonormal, so the names that promise one are refused here rather than redefined. `physical_energy` is the same-frequency product of the state with the basis's flux metric, integrated over frequency; `analytic_flux` is the peak over time of that same **same-frequency flux**, $\max_t \mathbf a^{\mathsf H}W\mathbf a$. On an identity metric — every guide in the provider's own coordinates — that is @@ -355,7 +355,7 @@ it. | the cubic's form | `kerr_form="real"` (the default, third harmonic included) or `"analytic"` | [the response at a node](modal-projection.md#the-response-at-a-node) | | the launch | `channel=` (an index or a label) or `incident=` (a `SpatialPulse` coupled under `coupling=`, of which the captured share enters) | [running one](#running-one) | | a unitary change of basis — of an exactly degenerate block, which stays diagonal, or of a split one, which becomes a coupled flow | `basis=` and `degenerate_blocks=` on `from_provider` | [declaring a circular basis](modal-bases.md#declaring-a-circular-basis), [a split block](modal-bases.md#a-declared-basis-of-a-block-that-is-only-nearly-degenerate) | -| the statistics | `physical_energy` and `analytic_flux` (the defaults), `spectral_flux` by name | [noise, statistics and what comes back](#noise-statistics-and-what-comes-back) | +| the statistics | `omega0`, `physical_energy`, `analytic_flux`, `fwhm_t` and `fwhm_t_outer` (the defaults), `spectral_flux` by name | [noise, statistics and what comes back](#noise-statistics-and-what-comes-back) | **What is refused, and why.** Every refusal names itself, at the entry point and again at the translation layer and in the backend. @@ -378,7 +378,6 @@ at the translation layer and in the backend. * The scalar-route power names, `quadrature_error` and — beside a split block — `zdw`: a statistic the basis does not define is refused with its replacement where it has one, rather than redefined. -* `observable_rtol` and `observable_atol` as numbers, which nothing would enforce. **How to read the record.** `output.metadata.modal` is the run's modal identity, and every entry of it is in the key a resume is checked against. `basis` says @@ -466,12 +465,10 @@ Not implemented, and refused rather than approximated: rebuilding the tables from the guide — tens of milliseconds for the route, about 0.7 s if the guide itself must still be solved — and every accessor checks them against the identity the file carries, path by path, with the guide, which they require; -* **`observable_rtol` and `observable_atol` as numbers.** `None` is accepted and means - the solver's own `rtol` and `atol`, which on this route is a true statement; a - different number is refused by name, because the separate error allocation it asks - for — over the table's frequency interpolation, the transverse rule and the step — is - not implemented, and accepting a number nothing enforces would be a silent claim about - accuracy; +* **a separate accuracy for the observables.** The solver's own `rtol` and `atol` bound + them, which on this route is a true statement; an accuracy of their own would need an + error allocation over the table's frequency interpolation, the transverse rule and the + step, which is not implemented, so the route takes no keyword for one; * a **backward or evanescent** declared launch. `incident=` (above) recovers the incident field through the flux pairing with the forward-field closure, and nothing in the arithmetic can see that a declared field was not forward-propagating; such a launch is @@ -499,5 +496,5 @@ the entrance geometry (a moving solid guide's rule moves with its interfaces, se section): the rule's certified tail bound and its sampled Gram belong to that geometry and to no other. -The incident-beam launch (`incident=` under `coupling=`) and its coupling budget were -proposed and carried out by [SEP 31](../../dev/seps/archive/sep-0031-simulation-coupling.md). +The design of the incident-beam launch (`incident=` under `coupling=`) and its coupling +budget is [SEP 31](https://github.com/LupoLab/solprop/blob/main/docs/dev/seps/archive/sep-0031-simulation-coupling.md). diff --git a/docs/guide/waveguides/gnlse.md b/docs/guide/waveguides/gnlse.md index cef8429e5..91f431b35 100644 --- a/docs/guide/waveguides/gnlse.md +++ b/docs/guide/waveguides/gnlse.md @@ -41,7 +41,7 @@ output = prop_gnlse( {class}`~solprop.nonlinear.gnlse.SpecifiedMode`, any other `Mode` or a measured `IndexTable`; `loss_db_per_m` sets a constant loss, `shock` (default `True`) the shock term, and `noise` the shot noise ([noise](../media/noise.md)). The -[soliton recurrence tutorial](../../introduction/lessons/plot_02_soliton) +[soliton recurrence tutorial](../../introduction/lessons/plot_02_soliton.rst) runs an N-soliton through it. ## The fibre is a mode @@ -109,7 +109,7 @@ $$ with the supplied $\gamma$ as the **entrance coefficient**: only the area's shape is used, and a constant area cancels exactly. With `n2` instead, the same holds through $\gamma = n_2\omega_0/(cA_\text{eff}(0))$. There is no second, absolute -division by an area anywhere, and no `VaryingAreaGnlse`: it is the same route. +division by an area anywhere. $A_\text{eff}(\omega, z)$ is *not* represented by one path. A frequency-dependent area is the declared reference-frequency slice $A_\text{eff}(\omega_0, z)$ on this @@ -381,7 +381,8 @@ material manifest records the fraction held back and where it came from — `"bu A lossless fibre with the shock term on conserves **photon number**, $\sum_k|\tilde A(\omega_k)|^2/\omega_k$, and not energy: the Raman response moves photons down in frequency and each one carries away less energy than it brought. Measured over a -hundredth of a soliton period with a given $f_R = 0.18$, the photon number is conserved exactly and +hundredth of a soliton period with `raman_fraction=0.18` given, the photon number is +conserved exactly and the energy falls by $7.2\times10^{-6}$. With `shock=False` the prefactor is frozen at the carrier and the equation conserves energy instead, which is the wrong invariant for a delayed response; with Raman off both hold to $5.6\times10^{-16}$. diff --git a/docs/guide/waveguides/modal-bases.md b/docs/guide/waveguides/modal-bases.md index 58c80c97a..869b33644 100644 --- a/docs/guide/waveguides/modal-bases.md +++ b/docs/guide/waveguides/modal-bases.md @@ -118,9 +118,11 @@ carries the absorbing collar, which two guides with different index tables carry differently, and the same comparison reads 2e-2. **Where it runs, and what it refuses by name.** Every backend executes the leaf — -`numpy_ref` and `native`, on the CPU and on a GPU. A **noise** model beside it is refused, because the shot-noise -draw ({doc}`../media/noise`) is transported by the unitary phase of a *diagonal* flow and its -transport through a coupled one has not been measured. And a block whose exponent over +`numpy_ref` and `native`, on the CPU and on a GPU. The **`modified`** noise model beside +it is refused, because its draw ({doc}`../media/noise`) is transported by the unitary +phase of a *diagonal* flow and its transport through a coupled one has not been measured; +the default `input` draw is part of the entrance state, which the flow propagates like any +field, and is admitted. And a block whose exponent over the largest declared step exceeds `MAX_GENERAL_FLOW_EXPONENT` (1e3) is refused: the block carries every channel's departure from the reference, so a basis declared over channels that were never a degenerate group would put their whole dispersion difference into a matrix diff --git a/docs/guide/waveguides/modal-projection.md b/docs/guide/waveguides/modal-projection.md index 79cf46854..686c4afba 100644 --- a/docs/guide/waveguides/modal-projection.md +++ b/docs/guide/waveguides/modal-projection.md @@ -28,9 +28,10 @@ renormalises that away. {func}`~solprop.translate.modal_tables.modal_transform_t evaluates the table on the grids a run will use and stores the execution maps. {meth}`~solprop.modes.guide.ModalGuide.from_provider` records what it solved on — the -knots, the position, the node rule, the declared degenerate blocks and the **measured** -profile interpolation error — as a {class}`~solprop.modes.guide.ModalSampling`, and that -is what a run rebuilds its reference from. A guide built by +knots, the position, the node rule, the declared degenerate blocks, any declared basis, +the **measured** profile interpolation error and, for a moving guide, its path — as a +{class}`~solprop.modes.guide.ModalSampling`, and that is what a run rebuilds its +reference from. A guide built by {meth}`~solprop.modes.guide.ModalGuide.from_step_index` carries no sampling, because nothing there declares a transverse resolution, and is refused by name when a run asks for it. @@ -196,7 +197,7 @@ the gas's own, under the run's `materials=` selection ([materials](../media/materials.md)). Under a carrier policy (the default) the region is the constant cubic above with $\chi^{(3)} = \sum_s N_s\gamma_{3,s}(\lambda_0)$, the Kerr coefficient at the run's carrier. Under one of the dispersive policies of -[SEP 6](../../dev/seps/archive/sep-0006-dispersive-nonlinearity.md), `"symmetric-kerr"` or +[SEP 6](https://github.com/LupoLab/solprop/blob/main/docs/dev/seps/archive/sep-0006-dispersive-nonlinearity.md), `"symmetric-kerr"` or `"gas-polynomial"`, each species of the fill is a channel of the frequency-dependent cubic ({class}`~solprop.nonlinear.responses.DispersiveKerrResponse`) acting at the region's nodes on the real three-component field, the scalar kernel times the @@ -277,7 +278,7 @@ the same `gram_atol`, because to first order that departure is what declaring $W the run's `physical_energy`. It is measured **where the launched light is**: the interpolation error lives at the long-wavelength end of the sampled band, where a pulse declared in the near infrared puts none of its own spectrum. On the weakly guiding test -fibre the whole-band figure is $1.1\times10^{-4}$ near 1.73 µm, inside the 790–890 nm +fibre the whole-band figure is $1.0\times10^{-4}$ near 1.72 µm, inside the 790–890 nm launch window it is $2.3\times10^{-7}$, and weighted by the pulse's own spectrum — which is what `from_waveguide` passes, since it builds the launch first — it is $3.7\times10^{-8}$. The number is on the record as `occupied_departure`, in the modal @@ -286,9 +287,9 @@ so a guide refused here is fixed by **adding knots**, not by widening the rule. **The weighting is the launched spectrum, so the gate certifies the launch and not the run.** The active band is where light *can* go, and a broadening run occupies bins the -launched spectrum discounted to nothing — on that same fibre the worst bin, 1.73 µm, is +launched spectrum discounted to nothing — on that same fibre the worst bin, 1.72 µm, is inside `grid.active_mask`, so a run that broadened an octave would pay -$1.1\times10^{-4}$ of its `physical_energy` there rather than the $3.7\times10^{-8}$ the +$1.0\times10^{-4}$ of its `physical_energy` there rather than the $3.7\times10^{-8}$ the gate saw. The route therefore also measures the **unweighted** maximum over the whole active band, records it as `active_departure`, and emits a {py:class}`~solprop.exceptions.GeneralModalBasisWarning` naming the worst bin's diff --git a/docs/guide/waveguides/modal-tables.md b/docs/guide/waveguides/modal-tables.md index b5bb7244a..44b6d0ffc 100644 --- a/docs/guide/waveguides/modal-tables.md +++ b/docs/guide/waveguides/modal-tables.md @@ -19,7 +19,8 @@ channel has no parity partner, so its `parity` is `None`. `handedness` is `None` on every real basis, and is **filled** where a guide declares a complex one: the circular partners of {py:func}`solprop.modes.guide.circular_pair` carry `left` and `right` in place of `even` and `odd`, by the convention -{doc}`general-modal` derives and {doc}`../setup/polarisation` fixes the sign of. +[a circular basis declares](modal-bases.md#declaring-a-circular-basis) and +{doc}`../setup/polarisation` fixes the sign of. **Parity means one thing across every family**, and `ChannelLabel`'s docstring is where it is defined: `"even"` is the member whose transverse pattern is the @@ -41,7 +42,8 @@ adding a second TE/TM parity is refused. A common physical step-index guide may have different mode-specific cladding tail radii; its collection uses a common enclosing domain. -`sample_index_table(mode, omega, z=..., include_area=True)` is the dense dispersion +{py:func}`~solprop.modes.tabulated.sample_index_table`, called as +`sample_index_table(mode, omega, z=..., include_area=True)`, is the dense dispersion bridge beside `IndexTable`. It retains the source's frequency derivative in a Hermite interpolant and records the snapshot position and source identity. Step-index areas are sampled at each frequency. Other modes retain their declared @@ -88,7 +90,8 @@ by the overlap of the fields, so two channels whose propagation constants exchan order across the band keep their identities, where sorting by eigenvalue would swap them. -`modal_transform_tables(table, omega, profile_error=...)` builds +{py:func}`~solprop.translate.modal_tables.modal_transform_tables`, called as +`modal_transform_tables(table, omega, profile_error=...)`, builds `ModalTransformTables`, the flat record a run's kernel problem carries as its `transform.modal_tables` leaf. It evaluates the table on the frequency grid a run will use -- which need not be the table's own knots, and in general is not -- and stores the @@ -98,8 +101,8 @@ propagation](modal-projection.md#the-synthesis-and-projection-maps)) and the node geometry as arrays, with frequency last and contiguous. Outside the table's band the record is explicitly zero rather than extrapolated, and a run whose active band leaves the guide's support is refused when the problem is assembled. The -execution maps are built for a snapshot table only; a moving guide's maps come from the -path sampling described above. +execution maps are built for a snapshot table only; a moving guide's maps come from +[its path sampling](moving-modal.md#a-guide-whose-geometry-moves-along-z). `coordinate_dual` recovers amplitudes from a physical field: contracted against the six components `(E, H)` at every node it returns the amplitude vector that @@ -115,7 +118,7 @@ nothing in the constructor infers the accuracy of its own representation. A snapshot declares one interval; a path declares one per pair of stored positions. -`validate_modal_table` compares held-out solves +{py:func}`~solprop.modes.tables.validate_modal_table` compares held-out solves against budgets supplied before the comparison; frequency derivatives can be checked through `generator_derivative`. Physical kinks require separate sections. Besides the weighted field and generator defects it reports the flux defect @@ -136,9 +139,9 @@ inspect: `Simulation.from_waveguide(..., provider=guide)` and `numpy_ref` and `native` (on the CPU and on the qualified GPU builds), and [the general modal page](general-modal.md) is the whole description. The guide carries its own {class}`~solprop.modes.guide.ModalSampling` --- the knots, the position, the node rule, the declared degenerate blocks and the -measured profile interpolation error -- and a run rebuilds its dense reference -from that; a guide built by `from_step_index` carries none, because nothing there +-- the knots, the position, the node rule, the declared degenerate blocks, any declared +basis, the measured profile interpolation error and, for a moving guide, its path -- and +a run rebuilds its dense reference from that; a guide built by `from_step_index` carries none, because nothing there declares a transverse resolution, and a run refuses it by name. A region's nonlinear response is declared on the region, with {class}`~solprop.modes.material.MaterialKerr`, by `chi3` or by `n2`. A diff --git a/docs/guide/waveguides/mode-sets.md b/docs/guide/waveguides/mode-sets.md index bff2a79dc..73ade0692 100644 --- a/docs/guide/waveguides/mode-sets.md +++ b/docs/guide/waveguides/mode-sets.md @@ -99,14 +99,16 @@ quarter turn from $x$ towards $y$ and so exchanges the two Cartesian components: pair runs $x$ then $y$ for $\mathrm{HE}_{1m}$. A transverse mode is carried once — $\mathrm{TE}_{0m}$ and $\mathrm{TM}_{0m}$ are different modes, not two states of one. -{func}`~solprop.modes.collection.overlap` integrates adaptively with -{func}`scipy.integrate.dblquad`, deliberately *not* on the fixed rule, so that the rule's -orthonormality can be checked against something independent rather than against itself. {meth}`~solprop.modes.collection.ModeCollection.orthonormality`, which a simulation runs -on every mode set it is given, integrates the whole matrix in one pass instead: adaptively -in $r$ (or $x$) with {func}`scipy.integrate.quad_vec`, every mode evaluated once per -point, and on a rule in $\theta$ (or $y$) doubled until no entry changes by more than -$10^{-12}$. It agrees with `overlap` pair by pair and takes seconds for 48 modes. +on every mode set it is given, integrates adaptively, deliberately *not* on the fixed +rule, so that the rule's orthonormality is checked against something independent rather +than against itself. It integrates the whole matrix in one pass: adaptively in $r$ (or +$x$) with {func}`scipy.integrate.quad_vec`, every mode evaluated once per point, and on +a rule in $\theta$ (or $y$) doubled until no entry changes by more than $10^{-12}$; it +refuses a set on which either coordinate does not converge, and takes seconds for 48 +modes. {func}`~solprop.modes.collection.overlap` is its entry for one pair. Step-index +channels of one fibre each bound the cladding at their own outer radius; their set is +integrated over the widest of those discs. ## A capillary worked example @@ -171,7 +173,58 @@ mode = MarcatiliMode(125e-6, "He", 0.4, model="reduced") zdw(mode) # 3.767e-07 m ``` -{func}`~solprop.modes.base.zdw` brackets the root of $\beta_2$ and **raises** when there is -none in the window, rather than returning a missing value that would propagate silently -into later arithmetic: a mode with no zero-dispersion point is a fact the caller has to -see. +{func}`~solprop.modes.base.zdw` samples the sign of $\beta_2$ at 512 frequencies across the +window and refines each change. Each change is then one of three things. + +- **A zero**, where the analytic group delay $\beta_1$ has an extremum that the + difference behind $\beta_2$ resolves -- its rise from the change grows quadratically + over the difference's stencil, on both sides -- and is monotone from it for 1.5 % in + frequency on either side, so that $\beta_2$ keeps each sign that far. +- **A line**, where $\beta_1$ is not finite or not continuous: across the stencil it + diverges, or drops to the evanescent floor, by more than a tenth of its value. A gas + resonance in the vacuum ultraviolet gives the differenced $\beta_2$ sign changes of + this kind that are not zeros (krypton has sixteen between 100 and 124 nm at 15 bar): + through the line's pole, where the stencil reaches a line, and on the evanescent + floor above one. +- **Fine structure**, anything else: a change the stencil does not resolve, or one of + the clustered zeros of a narrow feature that leaves $\beta_1$ finite and continuous. + Fused silica's OH absorption bands are the common case: optmat's silica (Franta's + model of a synthetic glass, OH bands included) flips the sign of $\beta_2$ four times + between 1.37 and 1.40 µm, through regimes 0.2-0.8 % wide, and again near 2.2 and + 2.7 µm, while its group delay varies by $10^{-4}$ and 5 % of its value. The inside of + an antiresonant wall's resonance can hold zeros closer than 1.5 % too; the zeros on its + flanks, which bound the normal dispersion beside it, lie 2 % or more from the next in the + fibres checked, and are zeros. Fine structure is passed over: it is neither a zero nor + a line. + +The search therefore resolves dispersion regimes 1.5 % wide and more, and its answer does +not depend on the window, as long as the window holds the zero: a standard telecom fibre +(NA 0.12, a 4.1 µm core radius) reports 1295.8 nm from a 1550 nm reference on a 100 nm +to 3 µm window, on 0.7 to 2.5 µm and on 1 to 2 µm alike, past its 1.38 µm OH band. Its +limits: two genuine zeros closer than 1.5 % (or a zero within 1.5 % of another sign +change) are passed over, a zero and another sign change inside one sample interval +restore the sign and are both missed, and a sample that is not finite brackets nothing. + +The default window runs from 150 nm to 3 µm: above the vacuum-ultraviolet lines of the +noble gases (the longest, xenon's, at 147 nm) and the absorption edge of fused silica, +below which a lossless solve takes silica as transparent and finds zeros with no +meaning. A deep-ultraviolet zero needs `wavelength_limits` set below it. + +A window can still hold several zeros: two zero-dispersion wavelengths, or the gas's own +zeros between two of its lines. Without `near` the call refuses them by name; with a +reference wavelength `near` (typically the pump) it returns the zero nearest it in +frequency among those no line separates from it, since light at the reference cannot +cross a line to reach the others: + +```{code-block} python +krypton = MarcatiliMode(14e-6, "Kr", 15.0) +zdw(krypton, wavelength_limits=(100e-9, 3e-6)) +# ModeError: beta2 has 3 zeros over 100-3000 nm, at 108.9, 119.9, 770.5 nm +zdw(krypton, wavelength_limits=(100e-9, 3e-6), near=800e-9) # 7.705e-07 m +zdw(krypton) # 7.705e-07 m: the default window starts above the lines +``` + +When the search finds no zero it **raises** +{class}`~solprop.exceptions.NoZeroDispersionError`, rather than returning a missing value +that would propagate silently into later arithmetic: a mode with no zero-dispersion point +is a fact the caller has to see. diff --git a/docs/guide/waveguides/profiles.md b/docs/guide/waveguides/profiles.md index 34f59798e..5b3689fc9 100644 --- a/docs/guide/waveguides/profiles.md +++ b/docs/guide/waveguides/profiles.md @@ -233,8 +233,9 @@ third order (docs/dev/stepper.md section 10, trap 5). Pass floor= to choose anot The default floor is $10^{-4}$ of the **highest** stage pressure, so it means the same thing for a 0.8 bar gradient as for a 40 bar one. At that level the residual gas contributes $10^{-4}$ of the fill's refractivity while the slope stays finite and cheap -for the adaptive split to resolve. Pass `floor=` to choose another value; `floor=0.0` -keeps the true vacuum end, for comparison with a calculation that has one, and logs a +for the adaptive split to resolve. Pass `floor=` to choose another value (to +`PressureGradient` or `steady_fill`; the entry points call it `pressure_floor=`); +`floor=0.0` keeps the true vacuum end, for comparison with a calculation that has one, and logs a stronger warning. Such a comparison also needs `vacuum_end="floor"`, since a choked end is not a vacuum. diff --git a/docs/guide/waveguides/radial-quadrature.md b/docs/guide/waveguides/radial-quadrature.md index bfa208f71..4d8455c8c 100644 --- a/docs/guide/waveguides/radial-quadrature.md +++ b/docs/guide/waveguides/radial-quadrature.md @@ -8,7 +8,7 @@ integral over the *field scale*, what the effective-area (mode-averaged) model is in those terms and what it gets wrong for ionisation, how the field-scale rules compare with the default, and how to choose. The rules and their qualification are described in -[SEP 19](../../dev/seps/archive/sep-0019-field-scale-quadrature.md), which also records +[SEP 19](https://github.com/LupoLab/solprop/blob/main/docs/dev/seps/archive/sep-0019-field-scale-quadrature.md), which also records the evidence. ## The radial integral is an integral over the field scale diff --git a/docs/guide/waveguides/solid-fibres.md b/docs/guide/waveguides/solid-fibres.md index ce13d8248..fb5a6c47f 100644 --- a/docs/guide/waveguides/solid-fibres.md +++ b/docs/guide/waveguides/solid-fibres.md @@ -192,7 +192,7 @@ frequency and projects it back, so it costs roughly the node count times the cha count times the frequency count, about a hundred times a capillary step of the same grid. The dense maps and the stored E/H reference are held for the whole run (`16 × nodes × components × channels × n_omega` bytes each): the -[backends chapter](../performance/resources.md#memory) says how that is estimated and budgeted before +[execution resources](../performance/resources.md#memory) says how that is estimated and budgeted before anything is allocated. ## A graded-index multimode fibre @@ -387,5 +387,5 @@ The ones a user meets first: * on a moving guide, the `modified` noise model or a fixed schedule that straddles a kink (above). -The incident-beam launch into a fibre and its coupling budget were proposed and carried -out by [SEP 31](../../dev/seps/archive/sep-0031-simulation-coupling.md). +The design of the incident-beam launch into a fibre and its coupling budget is +[SEP 31](https://github.com/LupoLab/solprop/blob/main/docs/dev/seps/archive/sep-0031-simulation-coupling.md). diff --git a/docs/guide/waveguides/supplied-guides.md b/docs/guide/waveguides/supplied-guides.md index ae2b902d5..d2a80701f 100644 --- a/docs/guide/waveguides/supplied-guides.md +++ b/docs/guide/waveguides/supplied-guides.md @@ -100,12 +100,11 @@ output = prop_waveguide( ``` The guide supplies the ordered channels, so `modes` is empty; `channel=` names the -one the pulse enters, by index or by display label. Every gas keyword above -- +one the pulse enters, by index or by display label. Every gas-filled keyword -- `gas`, `pressure`, `temperature`, `kerr`, `thg`, `plasma`, `raman`, `n_r`, -`n_theta`, `kronrod`, `envelope`, `node_budget` -- is refused **by name** beside a -provider, because the guide owns what each of them would set. -`observable_rtol` and `observable_atol` are accepted as `None`, meaning the -solver's own `rtol` and `atol`; a number is refused by name. **`kerr_form`** +`n_theta`, `radial_rule`, `envelope`, `node_budget` and the rest -- is refused +**by name** beside a provider when it departs from its default, because the guide owns +what each of them would set. **`kerr_form`** chooses the instantaneous cubic the regions respond with: `"real"`, the default, is the real-field cubic the field-grid routes above evaluate, third harmonic included, and `"analytic"` is the analytic-signal form, which carries the @@ -129,12 +128,14 @@ field that moved ([output](../results/resuming.md#what-a-general-modal-runs-key- A scan point writes one too ([scans](../workflows/scans.md)). A reconstruction of E and H needs the **guide beside the file**: the reference -arrays are not stored in it, so rebuild the tables from the guide and pass the -guide as well -- `guide=` is a **required** keyword of all six reconstruction -accessors, with no default, so the sampling and the regions are always checked too +arrays are not stored in it, so `guide=` is a **required** keyword of all six +reconstruction accessors, with no default. Each rebuilds the run's tables from the +guide, and checks the sampling and the regions; `tables=reference_tables(run, +guide=guide)` passed to each call reuses one rebuild ([reading E and H back](../results/resuming.md#reading-e-and-h-back)). -Its statistics are `physical_energy` and `analytic_flux`, the route's own scalar +Its default statistics are `omega0`, `physical_energy`, `analytic_flux`, `fwhm_t` and +`fwhm_t_outer`; `physical_energy` and `analytic_flux` are the route's own scalar names, with `spectral_flux` -- the same physical energy as a density in frequency, in J/(rad/s) -- admitted by name where it is asked for; `energy`, `peak_power`, `peak_power_total`, their windowed forms and `peak_intensity` are refused by name @@ -146,8 +147,11 @@ node rule carries no embedded coarse rule to difference, so there is no transverse-resolution alarm to offer instead ([statistics](../results/statistics.md#which-names-a-basis-admits)). -Like every field-grid route it applies the grid's default temporal absorber inside every -stage (`SimulationSettings.absorber_scheme="nonlinear"`, see [boundaries](../numerics/boundaries.md)), -which can set the step. `prop_gnlse` builds no absorber at all, so a comparison with it -needs either `absorber_scheme="split_step"` or `absorber=None` here. Read -[the general modal page](general-modal.md) before planning a run. +Like every field-grid route it builds the grid's default collar and applies its +temporal rate inside every stage (the default scheme, `"nonlinear"`; see +[boundaries](../numerics/boundaries.md)), which can set the step. +`absorber_scheme="split_step"` applies the same rates once per step instead, and +`absorber=False` switches the temporal and spectral collars off. `prop_gnlse` builds its +own grid's default collar too, so a like-for-like comparison with it passes +`absorber=False` to both. Read [the general modal page](general-modal.md) before +planning a run. diff --git a/docs/guide/waveguides/taper-coupling.md b/docs/guide/waveguides/taper-coupling.md index b31ddd13b..402d53704 100644 --- a/docs/guide/waveguides/taper-coupling.md +++ b/docs/guide/waveguides/taper-coupling.md @@ -67,7 +67,14 @@ These comparisons illustrate the model's accuracy and the need to converge the r - **The backends.** The native backend runs it within the flow-parity bounds, and a lossless multimode taper runs on `backend="auto"`. -**A strongly lossy taper at the default step bound.** The coupling carries each -channel's loss inside its block, and with the default `dz_max` of half the length the -flow's conditioning guard can refuse a strongly lossy multimode taper. The refusal says -to cap `dz_max`, or to pass `taper_coupling=False` for the adiabatic route. +**A lossy taper at the default step bound.** The coupling carries each channel's loss +inside its block, so over one step the channels spread by the difference of their +attenuations, and the flow's conditioning guard refuses a spread above $10^4$ over +`dz_max`. With the default loss and the default `dz_max` of half the length this refuses +a narrow-bore multimode taper: four helium-filled channels on a 125 to 62.5 µm taper are +refused, a 250 to 125 µm one is not. The rate depends on the bore, not on the length, +and the guard reads every frequency of the grid, so the worst is usually in the +long-wavelength collar, where the highest channel's wall loss is largest. The refusal +names the largest `dz_max` it admits (the bound is $\exp(\mathrm{d}z_{\max}\,\Delta\mu)$, +so that value is exact); pass it, or pass `taper_coupling=False` for the adiabatic +route. diff --git a/docs/guide/waveguides/vector-wall.md b/docs/guide/waveguides/vector-wall.md index a6700257c..eaa4598eb 100644 --- a/docs/guide/waveguides/vector-wall.md +++ b/docs/guide/waveguides/vector-wall.md @@ -104,7 +104,7 @@ $\mathrm{HE}_{11}, \mathrm{HE}_{12}, \mathrm{EH}_{11}, \mathrm{EH}_{12}$. ```{eval-rst} .. plot:: :filename-prefix: modes-vector-wall - :caption: The wall's anisotropy converts between the two radial families of one azimuthal order. Ten fixed steps of 20 micrometres of a 50 micrometre helium-filled bore, launched into HE_11 alone, with the fraction of the arriving energy in each channel. The vector block leaves 2.8e-8 in EH_11; the uncoupled route leaves 1e-50 there, and the scalar block cannot carry the set at all. + :caption: The wall's anisotropy converts between the two radial families of one azimuthal order. Adaptive steps of at most 20 micrometres along 200 micrometres of a 50 micrometre helium-filled bore, launched into HE_11 alone, with the fraction of the arriving energy in each channel. The vector block leaves 2.8e-8 in EH_11; the uncoupled route leaves 1e-50 there, and the scalar block cannot carry the set at all. import warnings diff --git a/docs/guide/workflows/compression.md b/docs/guide/workflows/compression.md index 399690892..9b520b2db 100644 --- a/docs/guide/workflows/compression.md +++ b/docs/guide/workflows/compression.md @@ -164,7 +164,7 @@ data sheet. join {py:func}`~solprop.physdata.glasses.fused_silica`, and {py:func}`~solprop.physdata.glasses.glass` finds any of them by name; so do the elements and the compressors that name a glass. Each is optmat's recommended absolute index -([SEP 3](../../dev/seps/archive/sep-0003-optmat-materials.md)), and magnesium fluoride and sapphire name their ray +([SEP 3](https://github.com/LupoLab/solprop/blob/main/docs/dev/seps/archive/sep-0003-optmat-materials.md)), and magnesium fluoride and sapphire name their ray (`glass("MgF2", axis="o")`); a gas path is the gas's optmat fill. They are described on [the materials page](../media/material-selection.md#solids). diff --git a/docs/guide/workflows/coupling.md b/docs/guide/workflows/coupling.md index 8a4de045e..5b47a939e 100644 --- a/docs/guide/workflows/coupling.md +++ b/docs/guide/workflows/coupling.md @@ -5,7 +5,7 @@ a fibre, a gas cell. Carrying only its spectrum or duration loses its wavefront, modal coherence and the frequency dependence of its transverse profile; carrying a bare array leaves its basis, units, frame and energy meaning implicit. {py:mod}`solprop.coupling` connects simulations through a **coherent field at a -reference plane** instead ([SEP 31](../../dev/seps/archive/sep-0031-simulation-coupling.md)). +reference plane** instead ([SEP 31](https://github.com/LupoLab/solprop/blob/main/docs/dev/seps/archive/sep-0031-simulation-coupling.md)). This page covers reading a saved plane as a field plane, moving it between temporal grids, and coupling it into another simulation: a relaunch into the same basis, a beam or a guide's exit into a capillary or another fibre, a guide's exit field @@ -138,7 +138,10 @@ is evaluated only on target bins inside the source lattice's own span: beyond it samples spaced $\Delta t$ repeats with period $2\pi/\Delta t$ and returns aliases of the record, not light. It is evaluated in bounded chunks of target bins, and its one acceleration is the identical lattice in an unchanged reference, where the map is the -identity and the samples are copied (checked against the direct sum by the tests). +identity: the samples inside the target's band are copied and those outside it zeroed, +as the sum leaves them (checked against the direct sum by the tests). The band is not +part of the lattice, so two grids with the same `dt` and window but different +wavelength limits share a lattice and still differ in what they can hold. ```python from solprop.coupling import regrid @@ -252,7 +255,7 @@ run keeps its ionisation tables and their ranges, as every derived run does. ## Coupling between different representations A different guide, radius or medium is not a relaunch. Three quantities must then be -kept apart ([SEP 31](../../dev/seps/archive/sep-0031-simulation-coupling.md), section 4.3): the +kept apart ([SEP 31](https://github.com/LupoLab/solprop/blob/main/docs/dev/seps/archive/sep-0031-simulation-coupling.md), section 4.3): the Hermitian E/H flux pairing $F$ of a modal basis, the Gram $G = S^\dagger MS$ of a scalar least-squares fit in a common measure $M$, and a representation's native power metric $Q$ -- the identity for ordinary true-power coefficients, a dense Gram for a declared @@ -731,7 +734,7 @@ certificate (ratio $2.5\times10^{-4}$ against the budget of $10^{-3}$). ## Composing simulations The blocks above compose into the calculations -[SEP 31](../../dev/seps/archive/sep-0031-simulation-coupling.md) set out to support. Each is an +[SEP 31](https://github.com/LupoLab/solprop/blob/main/docs/dev/seps/archive/sep-0031-simulation-coupling.md) set out to support. Each is an ordinary chain of runs and planes; nothing schedules them, and each run keeps its own step control. The test suite runs every one of them as a short integrated case (`tests/coupling/test_workflows.py`), asserting its energy ledger. @@ -810,4 +813,4 @@ print(ledger.specified_loss, ledger.removed, second.report.efficiency) ``` Field planes, coupling models and their budgets, and transport between planes were -proposed and carried out by [SEP 31](../../dev/seps/archive/sep-0031-simulation-coupling.md). +proposed and carried out by [SEP 31](https://github.com/LupoLab/solprop/blob/main/docs/dev/seps/archive/sep-0031-simulation-coupling.md). diff --git a/docs/guide/workflows/design-tools.md b/docs/guide/workflows/design-tools.md index faf2ae43b..1a63511b6 100644 --- a/docs/guide/workflows/design-tools.md +++ b/docs/guide/workflows/design-tools.md @@ -96,20 +96,17 @@ effective-area field instead; do not equate that with a resolved on-axis rate. I and a test compares it with the first plane of a run. **The zero-dispersion wavelength is searched, not bracketed once.** A gas resonance in -the vacuum ultraviolet flips the sign of $\beta_2$ twice (krypton near 120 nm), so a -single bracket over 100 nm to 3 µm sees the same sign at both ends and finds nothing. -The dispersion is sampled, each sign change refined, the changes through a pole -discarded (there $\beta_1$ diverges; at a zero it is extremal), and the zero nearest the -pump reported. When there is none the field is `nan` and the block says so. - -```{note} -The modes' own {py:func}`~solprop.modes.base.zdw`, and the `zdw` statistic that uses -it, do not search this way: they test only the signs of $\beta_2$ at the ends of the -window before a bracketed root search, so an even number of interior zeros — two -zero-dispersion wavelengths, or a resonance's pair of sign changes as in krypton or -xenon — reads as no zero, and the search raises. Use the design tools' search for such a -case. -``` +the vacuum ultraviolet flips the sign of $\beta_2$ many times (krypton near 120 nm), so a +single bracket over 100 nm to 3 µm can see the same sign at both ends and find nothing. +The design tools call {py:func}`~solprop.modes.base.zdw` with the pump as its `near` +reference: the dispersion is sampled, each sign change refined, the changes that are not +zeros discarded (at a zero $\beta_1$ has a resolved extremum; through a pole, beside a +line or on the evanescent floor it does not), and so are the clustered zeros of fine +structure narrower than 1.5 % in frequency, such as silica's OH bands; the zero nearest +the pump on its side of the lines is reported +([mode sets](../waveguides/mode-sets.md)). When there is none the field is `nan` and the block says +so. The `zdw` statistic searches the same way, with the grid's reference wavelength as +its reference. **The critical power** is {py:func}`~solprop.tools.beam.self_focusing_power`, $P_{\rm cr}=1.86226\,\lambda^2/(4\pi n_0n_2)$ (Fibich and Gaeta, Opt. Lett. **25**, 335 @@ -238,12 +235,9 @@ estimate with the linear condition. :alt: Computed phase mismatch versus wavelength for a helium-filled capillary; the Kerr term shifts the short-wavelength zero. :caption: The phase mismatch of the fundamental mode of a 125 µm capillary filled with 1 bar of helium, for an 800 nm soliton, with and without the nonlinear wavenumber of a 30 GW soliton. The dispersive wave is phase matched where a curve crosses zero; the linear curve has a double zero at the pump because its carrier and group-delay terms have been subtracted. The nonlinear curve is shifted and need not vanish there. - import warnings - import matplotlib.pyplot as plt import numpy as np - from solprop.exceptions import MaterialRangeWarning from solprop.modes import MarcatiliMode from solprop.physdata import n2 from solprop.tools import lambda_rdw, nonlinear_coefficient, phase_mismatch @@ -254,14 +248,11 @@ estimate with the linear condition. omega = 2 * np.pi * 299792458.0 / wavelength fig, ax = plt.subplots(figsize=(6.0, 3.4)) - with warnings.catch_warnings(): - # The window reaches below the 210 nm of the silica fit. - warnings.simplefilter("ignore", MaterialRangeWarning) - for power, label in ((None, "linear"), (30e9, "with the Kerr term, 30 GW")): - kerr = {} if power is None else {"peak_power": power, "gamma": gamma, "nonlinear_phase": "supplied_power"} - ax.plot(wavelength * 1e9, phase_mismatch(mode, omega, 800e-9, **kerr), label=label) - root = lambda_rdw(mode, 800e-9, **kerr) - ax.axvline(root * 1e9, color="0.6", lw=0.8, ls=":") + for power, label in ((None, "linear"), (30e9, "with the Kerr term, 30 GW")): + kerr = {} if power is None else {"peak_power": power, "gamma": gamma, "nonlinear_phase": "supplied_power"} + ax.plot(wavelength * 1e9, phase_mismatch(mode, omega, 800e-9, **kerr), label=label) + root = lambda_rdw(mode, 800e-9, **kerr) + ax.axvline(root * 1e9, color="0.6", lw=0.8, ls=":") ax.axhline(0.0, color="k", lw=0.6) ax.set_ylim(-60, 60) ax.set_xlabel("wavelength (nm)") @@ -284,10 +275,11 @@ at its ends, rather than returning a placeholder that would propagate silently. travels in, and the first argument the mode the wave is emitted into. **Range warnings.** The search evaluates the index across a window far wider than its -answer, and those probes are silent. The answer is not: a dispersive wave at 187 nm in a -silica capillary lies below the 210 nm of Malitson's fit, and -{py:class}`~solprop.exceptions.MaterialRangeWarning` says so, because the number then -rests on an extrapolated cladding index. +answer, and those probes are silent. The answer is not: the index is evaluated again at +the roots it finds, outside the probing, so a root that takes the gas or the cladding +beyond its index model's qualified range raises +{py:class}`~solprop.exceptions.MaterialRangeWarning`, because the number then rests on an +extrapolated index. ## The pressure that tunes it @@ -304,9 +296,9 @@ step, so a search costs milliseconds. >>> from solprop.modes import MarcatiliMode >>> mode = MarcatiliMode(125e-6, "He", 1.0, cladding=1.45) >>> f"{lambda_rdw(mode, 800e-9) * 1e9:.1f} nm" -'186.8 nm' +'200.1 nm' >>> f"{pressure_rdw(125e-6, 'He', 160e-9, 800e-9, cladding=1.45):.2f} bar" -'0.74 bar' +'0.66 bar' ``` Both refuse a bracket without a root by name. `pressure_rdw` samples the pressure @@ -604,4 +596,4 @@ the tools at the pressure where you expect the fission, not at the entrance. The suite checks this comparison against the run. The design solvers, `solve_parameter` and its targets, were proposed and carried out by -[SEP 41](../../dev/seps/archive/sep-0041-recipes-and-front-ends.md). +[SEP 41](https://github.com/LupoLab/solprop/blob/main/docs/dev/seps/archive/sep-0041-recipes-and-front-ends.md). diff --git a/docs/guide/workflows/interactive.md b/docs/guide/workflows/interactive.md index cbca382a3..4067c9f2d 100644 --- a/docs/guide/workflows/interactive.md +++ b/docs/guide/workflows/interactive.md @@ -113,8 +113,12 @@ takes a `plot_` prefix. {py:func}`solprop.processing.time.energy` is `sol.energy {py:func}`solprop.plotting.propagation.plot_energy` is `sol.plot_energy`, the figure; likewise `sol.plot_stats`. `numpy` and `matplotlib.pyplot` are deliberately **not** re-exported, so `from solprop.sol import *` never shadows your own `np` and `plt`. A test compares -`sol.__all__` with the public names of the home modules, so the namespace cannot fall -behind them. `SpecifiedMode` is here, but the dispersion data it is built from is not: +`sol.__all__` with the public names of nine home modules (`solprop.plotting`, +`solprop.processing`, `solprop.processing.compression`, `solprop.tools`, +`solprop.optics`, `solprop.driver.interface`, `solprop.nonlinear`, +`solprop.nonlinear.ionisation` and `solprop.profiles`), so the namespace cannot fall +behind those; what it takes from other modules, such as the grids, pulses, modes and +output, is a selection that no test checks for completeness. `SpecifiedMode` is here, but the dispersion data it is built from is not: `TaylorDispersion`, `TabulatedDispersion`, `DispersionPath`, `ConstantDispersion`, `InterpolatedDispersion` and `as_dispersion_path` are imported from {py:mod}`solprop.nonlinear.gnlse`, where they live beside the mapping that uses them. diff --git a/docs/guide/workflows/luna.md b/docs/guide/workflows/luna.md index f16327f97..2158ae908 100644 --- a/docs/guide/workflows/luna.md +++ b/docs/guide/workflows/luna.md @@ -80,7 +80,7 @@ Four conventions change what the numbers mean: | what | Luna | solprop | |---|---|---| | Raman response of a molecular fill | on for N₂, H₂, D₂, N₂O, CH₄ and SF₆ | optmat's response, on for every species whose response is validated: N₂, O₂, H₂, D₂, CH₄, SF₆ (and air through N₂ and O₂); N₂O's is provisional, so it warns and runs without unless `MaterialSelection(raman="provisional")` admits it | -| ionisation rate of a molecule | ADK for H₂, D₂, N₂O, CH₄, SF₆; PPT for N₂ and O₂ | optmat's recommended rate model of every gas ([SEP 3](../../dev/seps/archive/sep-0003-optmat-materials.md)) | +| ionisation rate of a molecule | ADK for H₂, D₂, N₂O, CH₄, SF₆; PPT for N₂ and O₂ | optmat's recommended rate model of every gas ([SEP 3](https://github.com/LupoLab/solprop/blob/main/docs/dev/seps/archive/sep-0003-optmat-materials.md)) | | barrier-suppression correction | none in released Luna (the pull request that proposes one uses Zhang's) | optmat's atomic rates carry Tong and Lin's correction, its molecular ones their own ([ionisation](../media/ionisation.md#rates-from-optmat)) | | a pressure gradient to vacuum | reaches zero pressure, where $dp/dz$ diverges | the steady flow is **choked** at the exit, at the pressure where the laminar throughput is sonic; `vacuum_end="floor"` with `pressure_floor=0.0` reproduces a true vacuum | | the fill of a taper | the uniform-bore law | the steady flow follows the bore ($p^2$ linear in $\int a^{-4}\,dz$), with a flow-regime check | @@ -124,12 +124,12 @@ has no plasma response on an envelope grid; solprop has a separate cycle-average response there. Luna forms the column's three running integrals with the cumulative trapezoid, which is 9 % short per integral at $\omega_{\max}$ on a default grid, and 11 % short at the top of the active band, $1.1\,\omega_{\max}$. solprop -offers a band-exact rule ([SEP 18](../../dev/seps/archive/sep-0018-band-exact-plasma-integrals.md), +offers a band-exact rule ([SEP 18](https://github.com/LupoLab/solprop/blob/main/docs/dev/seps/archive/sep-0018-band-exact-plasma-integrals.md), `integration="band"`) and keeps the trapezoid, `integration="trapezoid"`, which every comparison with Luna states among its frozen inputs. solprop's field-grid plasma holds the post-pulse current through `DFT[gJ]/(i omega) - DFT[g'J]/(i omega)**2` -([SEP 27](../../dev/seps/archive/sep-0027-held-plasma-current.md)); Luna's gated polarisation +([SEP 27](https://github.com/LupoLab/solprop/blob/main/docs/dev/seps/archive/sep-0027-held-plasma-current.md)); Luna's gated polarisation switches off both the residual current and polarisation at the temporal collar. No stored Luna run computes the held current, so the propagation comparisons whose exit spectra carry a plasma were dropped with the private gated source they ran: the reduced @@ -174,17 +174,17 @@ model's loss has one arithmetic kernel (Luna's cached path had its sign reversed $n_\text{eff} - 1$ is formed directly, gaining five digits at a gas fill. The azimuthal order is never negative, and frequency zero is refused. -**Antiresonant fibres (Vincetti model).** Four terms follow the papers or the physics +**Antiresonant fibres (Vincetti model).** Three terms follow the papers or the physics rather than Luna's (and pyJCMwave's) form; the legacy form is available as `solprop.modes.antiresonant.LEGACY_CONVENTIONS`. For the tutorial fibre (15 µm core, six 9 µm tubes with 180 nm walls) in argon: | term | solprop | Luna | effect | |---|---|---|---| -| effective-radius coefficient | $3 + 10\lambda/a$ (as printed) | 20 | $n_\text{eff}$ −1.7×10⁻⁶ and $\beta_2$ −7.7 fs²/m (1.7 %) at 800 nm; area −1.0 % | | waveguide decrement | $D_0/n_g$ | $D_0/n_g^2$ | at 30 bar, $\beta_2$ +8.9 fs²/m (1.7 %) at 1030 nm | | effective-area prefactor | $1/n_g$ | none | at 30 bar, area −0.8 % | | normalised frequency | $\sqrt{n_t^2 - n_g^2}$ | $\sqrt{n_t^2 - 1}$ | at 30 bar, the first loss peak 2.5 nm shorter; loss ×0.74 at 400 nm | +| effective-radius coefficient | $3 + 20\lambda/a$ (Rosa 2021 eq. 10 as printed) | $3 + 20\lambda/a$ | the same | | dispersion width $\gamma_d$ | 0.03 | 0.03 | the same (the paper prints 0.003; 0.03 fits finite-element solutions better) | The loss is $c\alpha/(2\omega)$ (Luna's `imag(neff)` carries twice the loss in its @@ -212,7 +212,8 @@ row of per-mode powers). The first-order coherence $g_{12}$ excludes the $i = j$ so it tends to zero for independent fields (Luna's tends to $1/N$). The ellipse orientation is $\tfrac12\operatorname{atan2}(U, Q)$ (Luna's is always zero). The zero-dispersion search is stateless and raises when there is no zero (Luna returns a -missing value and seeds the next search from it). `lambda_rdw` returns the longest root +missing value and seeds the next search from it); its default window starts at 150 nm, +above the noble gases' lines, where Luna's starts at 100 nm. `lambda_rdw` returns the longest root and raises when there is none. **Stepper.** `atol` is additive to the scaled error (Luna's weak norm uses it as a floor @@ -242,7 +243,7 @@ and the launch is the projected amplitudes as they are. The energy the modes do capture is not restored by renormalising to the requested energy (nor is it in Luna), and the coupling report states the incident, captured and uncaptured energies. A field taken from another run is coupled at its own physical scale ([coupling simulations](coupling.md), -[SEP 31](../../dev/seps/archive/sep-0031-simulation-coupling.md)). +[SEP 31](https://github.com/LupoLab/solprop/blob/main/docs/dev/seps/archive/sep-0031-simulation-coupling.md)). ## More accurate numerics, the same physics diff --git a/docs/guide/workflows/scans.md b/docs/guide/workflows/scans.md index 30096fd55..f7a464fea 100644 --- a/docs/guide/workflows/scans.md +++ b/docs/guide/workflows/scans.md @@ -49,13 +49,8 @@ Four executors, all in `solprop.driver.executors`, run the points: | `Queue(path)` | a durable queue on a shared filesystem, drained by one or more controllers | | `Slurm(script, ...)` | prepares a queue and submits a Slurm array job that drains it | -The `Batch` executor of earlier releases, which ran groups of compatible points in -lockstep, is removed ([SEP 52](../../dev/seps/archive/sep-0052-backend-shape.md)): it -held a complete run per member and was no faster. Use `Local()` in its place, or `Pool()` -with as many workers as the group had members. - A builder's omitted `backend` resolves to the native backend, as described in -[running a simulation](../performance/resources.md#backend-choice-and-scan-workers), and +[backend choice and scan workers](../performance/resources.md#backend-choice-and-scan-workers), and every executor keeps that concrete choice. ## Reuse a translated simulation @@ -216,10 +211,10 @@ can watch them. bar and the per-point lines. `scan_started(n_points)` is called once with the number of selected points, `point_started(index, point)` and `point_finished(index, status, wall)` once for each point dispatched or collected, and `scan_finished()` once when the scan -returns. The status is `"done"`, `"failed"`, `"skipped"` (complete in the file), -`"conflict"` (complete, with a stored record that agrees but for rounding, and kept) or -`"stopped"` (below); `wall` is the point's build and run time in seconds as its worker -measured it. `point_reporter(index)` is asked, before each point runs, for a +returns. The status is `"done"`, `"failed"`, `"skipped"` (complete in the file) or +`"stopped"` (below); a completed point whose rebuilt record differs from the stored one +aborts the scan with an `OutputError` naming the differing fields. `wall` is the point's +build and run time in seconds as its worker measured it. `point_reporter(index)` is asked, before each point runs, for a {py:class}`~solprop.log.ProgressReporter` that receives that point's own run ([writing your own](../performance/progress.md#writing-your-own)), or `None` for none. Subclass {py:class}`~solprop.log.NullScanReporter` and override what you need; the rest @@ -282,7 +277,9 @@ for one being retried), and a rerun of the same call computes them, skipping the complete ones as usual. `run_scan` returns normally after a stop, logs at `INFO` that the caller's flag stopped it with the counts of collected and stopped points, and tells a scan reporter `"stopped"` for each stopped point; a watched point's reporter is told -through `interrupted`, with a `StopRequested` error that carries the caller's flag. The design is [SEP 41](../../dev/seps/archive/sep-0041-recipes-and-front-ends.md), +through `interrupted`, with a `StopRequested` error that carries the caller's flag. A +`Pool` point whose own worker is interrupted, by Ctrl-C (which a terminal sends to every +worker) or SIGTERM, is a stopped point in the same way, never a failed one. The design is [SEP 41](https://github.com/LupoLab/solprop/blob/main/docs/dev/seps/archive/sep-0041-recipes-and-front-ends.md), S4 and S17. ## Noise and repeatability @@ -318,7 +315,7 @@ saved-plane indices, including negative indices. `fields="all"` retains every sa plane. A field reduction can retain one field independently of field-history storage. The worker keeps only the fields the scan reads -([SEP 22](../../dev/seps/archive/sep-0022-memory-lean-spatial-execution.md)): the planes `fields` +([SEP 22](https://github.com/LupoLab/solprop/blob/main/docs/dev/seps/archive/sep-0022-memory-lean-spatial-execution.md)): the planes `fields` retains, the target plane of each built-in reduction that reads a field, and, while a custom reduction reads fields, every plane of the run it is handed. The other planes are run as statistics-only planes @@ -374,9 +371,10 @@ its own objects, so its optmat models and policies are frozen for that run and d depend on what another point resolved. A model whose numbers changed, a changed policy or another optmat version is refused by name ([output](../results/provenance.md#the-material-manifest)). Failed points require -`retry_failed=True`. A stale `running` point becomes eligible after `stale_age` seconds -(600 by default). Queue ownership protection uses the live-owner and refreshed-lease rules -described below. +`retry_failed=True`. A point an earlier scan left `running`, because it was stopped, +interrupted or ended by an error, is computed again: one controller holds the file at a +time, so no other can still be running it. Queue ownership protection uses the +live-owner and refreshed-lease rules described below. Uniform scans expose rectangular `stats/`, `reduced/` and optional `fields/` datasets. Different shapes have separate `layouts/<digest>/` groups with global-point mappings. @@ -407,9 +405,8 @@ scan. For several controllers sharing a filesystem, choose `Queue("pressure_energy.queue")`. A queue keeps exact identities: its manifest hashes the builder's code and refuses a -change, and each point and collected artifact is checked by its configuration hash, so -the tolerance of a local rerun does not apply to it; `Slurm` drains a queue and -behaves alike. +change, and each point and collected artifact is checked by its configuration hash, as a +local rerun is; `Slurm` drains a queue and behaves alike. Each controller runs a memory-sized spawned `Pool`. Point artifacts are fsynced before publication; the collected file is written under one exclusive controller lock. Readers take the corresponding shared lock. The filesystem must support coherent @@ -418,6 +415,10 @@ The queue is tested on local disks (APFS and ext4); network and parallel filesys (NFS, Lustre, GPFS) differ in their locking guarantees, so check yours with a small scan before relying on it. +`Queue` and `Slurm` need a POSIX system and refuse to start on Windows, where `Local` and +`Pool` run. On Windows a scan's readers take its lock one at a time, where POSIX lets them +read together, so concurrent reads of one scan file wait for each other. + ```bash uv run python -m solprop.scan pressure_energy.py --queue pressure_energy.queue --workers 4 uv run python -m solprop.scan pressure_energy.py --queue pressure_energy.queue --chunk 1/3 @@ -433,8 +434,10 @@ Artifacts are JSON and numerical HDF5 datasets, never executable pickle payloads Failed artifacts keep their error and available provenance; collection rejects numerical arrays attached to a failed artifact. -A controller refreshes each active claim's lease. A live local PID with matching -creation identity remains protected even after `stale_age`; a remote owner remains +A controller refreshes each active claim's lease, `Queue(stale_age=...)` seconds long +(600 by default; `--stale-age` on the command line, which a Slurm submission passes to +its tasks). A live local PID with matching creation identity remains protected even +after its lease has expired; a remote owner remains protected while its lease is refreshed. A dead local owner or expired remote lease can be replaced. Unique claim tokens reject late results from superseded workers. Failed points require `retry_failed=True` in the script. `.nowork` means the invocation @@ -445,14 +448,17 @@ a live lock file would create a second lock inode and defeat mutual exclusion. ```{note} Recovery has known limits. A live but wedged owner on the same host holds its point indefinitely, because the lease age is not consulted while its process is alive: stop -that process to release the point. A `Local` or `Pool` scan interrupted by a signal or a -crash, rather than stopped by its `stop=` flag, skips its `running` points for -`stale_age` seconds on restart. A rerun that commits no point leaves the consolidated +that process to release the point. A rerun that commits no point leaves the consolidated `layouts` as they are, and adds only its row to `executions`, a few kilobytes. A rerun that commits points rebuilds `layouts`, a copy of every completed point's arrays, and HDF5 does not reclaim the space of the copy it replaces, so the file grows by about the size of all the completed points' arrays as well as the new points' own: with 32 points of 256 kB of fields each, a rerun that committed one point grew the file by 8.7 MB. +A `Local` or `Pool` scan updates its one HDF5 file in place, flushing after each write, +and HDF5 does not guarantee a consistent file after a crash: a power loss or a kill while +a write is in flight can leave the file unreadable, every committed point with it. A +queue keeps each point as its own artifact, fsynced and renamed into place, from which +`collect` builds the collected file again, so run long or precious scans with `Queue`. ``` Inspect a generated Slurm script before submission: @@ -489,4 +495,4 @@ Slurm memory uses `--mem`, while a direct `Pool` or queue accepts `--memory-limi bytes. Scan progress, the stop flag and scans from a recipe were proposed and carried out by -[SEP 41](../../dev/seps/archive/sep-0041-recipes-and-front-ends.md). +[SEP 41](https://github.com/LupoLab/solprop/blob/main/docs/dev/seps/archive/sep-0041-recipes-and-front-ends.md). diff --git a/docs/introduction/about.md b/docs/introduction/about.md index 454c1649c..61e75c7ba 100644 --- a/docs/introduction/about.md +++ b/docs/introduction/about.md @@ -79,7 +79,7 @@ it means for anyone relying on the code. - **Correctness is controlled by design.** Every change passes through a carefully designed development harness. Each model is derived and documented before it is implemented, tested against analytic results and independent references, and checked - for convergence. Every compiled backend is tested against the NumPy reference within + for convergence. The native backend is tested against the NumPy reference within rounding bounds derived before any measurement. The lead developer's two decades of experience with propagation codes decide what is checked, and how. - **Fewer bugs, better documentation, less line-by-line reading.** Compared with @@ -91,7 +91,7 @@ it means for anyone relying on the code. convergence studies and add accuracy checks that a small team would usually have to leave out. - **Complete test coverage.** Every line and branch of the package is exercised by a - broad test suite of more than 11,500 tests: unit and invariant tests, comparisons with + broad test suite of more than 20,000 tests: unit and invariant tests, comparisons with analytic solutions and independent references, convergence records, and parity between the backends. - **Faster development.** solprop has far more functionality than its hand-written @@ -130,5 +130,5 @@ licence (`CC-BY-4.0`). The chirped-mirror data taken from Luna.jl keep Luna's MI Every file in the repository states its copyright and licence, in an SPDX header or in `REUSE.toml`, following the [REUSE specification](https://reuse.software/). -The optional compiled backend, solprop-native, is built from the repository's `native/` +The compiled backend, solprop-native, is built from the repository's `native/` directory and distributed as a separate package under the same licence. diff --git a/docs/introduction/installation.md b/docs/introduction/installation.md index feb366931..b07ace4ab 100644 --- a/docs/introduction/installation.md +++ b/docs/introduction/installation.md @@ -216,24 +216,10 @@ The last step of every installation, wheel or source build, laptop or cluster no solprop calibrate ``` -In about a minute and a half it measures how the native backend should thread, wait and plan its +In about two minutes it measures how the native backend should thread, wait and plan its transforms on this machine, and keeps the result in your cache directory; every later run uses it ([Calibrating solprop to your machine](../guide/performance/calibration.md)). -`--quick` takes about 20 s, `--thorough` about five minutes. If you skip it, the first +`--quick` takes about 30 s, `--thorough` about seven minutes. If you skip it, the first native run calibrates quickly by itself, with a notice saying so, and the run above may have done just that. On a cluster, calibrate inside a job on each kind of compute node, not on a login node. - -## Platforms - -solprop is developed and tested on macOS (Apple silicon), Linux (x86-64) and Windows -(x86-64 and Arm). The native backend has wheels for the five platforms above, builds from -source on Linux and macOS, and builds for GPUs on Linux. The `Queue` and `Slurm` scan executors need a POSIX system and refuse to start -on Windows; `Local` and `Pool` run there. On Windows a scan's readers take its lock one -at a time, where POSIX lets them read together, so concurrent reads of one scan file -wait for each other. - -The precompiled native wheels were proposed and qualified by -[SEP 29](../dev/seps/archive/sep-0029-compiled-backend-distribution.md), and -[SEP 43](../dev/seps/archive/sep-0043-retire-numba-cpu.md) made the native backend a required -dependency. diff --git a/docs/introduction/lessons/images/sphx_glr_plot_02_soliton_001.png b/docs/introduction/lessons/images/sphx_glr_plot_02_soliton_001.png index 73ff26b06..5a0e47526 100644 Binary files a/docs/introduction/lessons/images/sphx_glr_plot_02_soliton_001.png and b/docs/introduction/lessons/images/sphx_glr_plot_02_soliton_001.png differ diff --git a/docs/introduction/lessons/images/sphx_glr_plot_02_soliton_002.png b/docs/introduction/lessons/images/sphx_glr_plot_02_soliton_002.png index 6db7b118a..579001fea 100644 Binary files a/docs/introduction/lessons/images/sphx_glr_plot_02_soliton_002.png and b/docs/introduction/lessons/images/sphx_glr_plot_02_soliton_002.png differ diff --git a/docs/introduction/lessons/images/sphx_glr_plot_03_filament_001.png b/docs/introduction/lessons/images/sphx_glr_plot_03_filament_001.png index 42c57573f..2b3b04a52 100644 Binary files a/docs/introduction/lessons/images/sphx_glr_plot_03_filament_001.png and b/docs/introduction/lessons/images/sphx_glr_plot_03_filament_001.png differ diff --git a/docs/introduction/lessons/images/sphx_glr_plot_04_crossing_beams_001.png b/docs/introduction/lessons/images/sphx_glr_plot_04_crossing_beams_001.png index 4ea597f02..5ffcb0d08 100644 Binary files a/docs/introduction/lessons/images/sphx_glr_plot_04_crossing_beams_001.png and b/docs/introduction/lessons/images/sphx_glr_plot_04_crossing_beams_001.png differ diff --git a/docs/introduction/lessons/images/sphx_glr_plot_04_crossing_beams_003.png b/docs/introduction/lessons/images/sphx_glr_plot_04_crossing_beams_003.png index 8ccf252ff..b7ad3a00d 100644 Binary files a/docs/introduction/lessons/images/sphx_glr_plot_04_crossing_beams_003.png and b/docs/introduction/lessons/images/sphx_glr_plot_04_crossing_beams_003.png differ diff --git a/docs/introduction/lessons/images/thumb/sphx_glr_plot_02_soliton_thumb.png b/docs/introduction/lessons/images/thumb/sphx_glr_plot_02_soliton_thumb.png index dd8e1538a..59b3229f8 100644 Binary files a/docs/introduction/lessons/images/thumb/sphx_glr_plot_02_soliton_thumb.png and b/docs/introduction/lessons/images/thumb/sphx_glr_plot_02_soliton_thumb.png differ diff --git a/docs/introduction/lessons/images/thumb/sphx_glr_plot_03_filament_thumb.png b/docs/introduction/lessons/images/thumb/sphx_glr_plot_03_filament_thumb.png index ec5b5fc6c..394531526 100644 Binary files a/docs/introduction/lessons/images/thumb/sphx_glr_plot_03_filament_thumb.png and b/docs/introduction/lessons/images/thumb/sphx_glr_plot_03_filament_thumb.png differ diff --git a/docs/introduction/lessons/images/thumb/sphx_glr_plot_04_crossing_beams_thumb.png b/docs/introduction/lessons/images/thumb/sphx_glr_plot_04_crossing_beams_thumb.png index 9a3090931..248c1e584 100644 Binary files a/docs/introduction/lessons/images/thumb/sphx_glr_plot_04_crossing_beams_thumb.png and b/docs/introduction/lessons/images/thumb/sphx_glr_plot_04_crossing_beams_thumb.png differ diff --git a/docs/introduction/lessons/plot_01_rdw.rst b/docs/introduction/lessons/plot_01_rdw.rst index 89ec37f34..3294dd710 100644 --- a/docs/introduction/lessons/plot_01_rdw.rst +++ b/docs/introduction/lessons/plot_01_rdw.rst @@ -302,7 +302,7 @@ value. largest recorded quadrature diagnostic: 9.84e-10 peak on-axis intensity 9.251e+14 W/cm² peak sampled electron density 1.619e+16 cm⁻³ - 15.8 s; backend native + 1.8 s; backend native @@ -320,7 +320,7 @@ illustrative calculation, not a fit to one measurement in that paper. .. rst-class:: sphx-glr-timing - **Total running time of the script:** (0 minutes 15.794 seconds) + **Total running time of the script:** (0 minutes 1.837 seconds) .. _sphx_glr_download_introduction_lessons_plot_01_rdw.py: diff --git a/docs/introduction/lessons/plot_01_rdw.zip b/docs/introduction/lessons/plot_01_rdw.zip index 41acad769..a95003dcc 100644 Binary files a/docs/introduction/lessons/plot_01_rdw.zip and b/docs/introduction/lessons/plot_01_rdw.zip differ diff --git a/docs/introduction/lessons/plot_02_soliton.codeobj.json b/docs/introduction/lessons/plot_02_soliton.codeobj.json index e37456120..f08b28dca 100644 --- a/docs/introduction/lessons/plot_02_soliton.codeobj.json +++ b/docs/introduction/lessons/plot_02_soliton.codeobj.json @@ -751,8 +751,8 @@ { "is_class": false, "is_explicit": false, - "module": "solprop.output.schema", - "module_short": "solprop.output", + "module": "solprop.output.store", + "module_short": "solprop.output.store", "name": "PlaneStore.fields" }, { @@ -816,8 +816,8 @@ { "is_class": false, "is_explicit": false, - "module": "solprop.output.schema", - "module_short": "solprop.output", + "module": "solprop.output.store", + "module_short": "solprop.output.store", "name": "PlaneStore.metadata" }, { @@ -881,8 +881,8 @@ { "is_class": false, "is_explicit": false, - "module": "solprop.output.schema", - "module_short": "solprop.output", + "module": "solprop.output.store", + "module_short": "solprop.output.store", "name": "PlaneStore.n_saved" }, { diff --git a/docs/introduction/lessons/plot_02_soliton.ipynb b/docs/introduction/lessons/plot_02_soliton.ipynb index 3d1aea7fb..99be92545 100644 --- a/docs/introduction/lessons/plot_02_soliton.ipynb +++ b/docs/introduction/lessons/plot_02_soliton.ipynb @@ -132,7 +132,7 @@ "name": "python", "nbconvert_exporter": "python", "pygments_lexer": "ipython3", - "version": "3.14.5" + "version": "3.14.6" } }, "nbformat": 4, diff --git a/docs/introduction/lessons/plot_02_soliton.rst b/docs/introduction/lessons/plot_02_soliton.rst index 9cf10d808..f601d6737 100644 --- a/docs/introduction/lessons/plot_02_soliton.rst +++ b/docs/introduction/lessons/plot_02_soliton.rst @@ -317,7 +317,7 @@ beam that focuses and ionises in free space. .. code-block:: none - 1.3 s; backend native + 0.7 s; backend native @@ -325,7 +325,7 @@ beam that focuses and ionises in free space. .. rst-class:: sphx-glr-timing - **Total running time of the script:** (0 minutes 1.307 seconds) + **Total running time of the script:** (0 minutes 0.694 seconds) .. _sphx_glr_download_introduction_lessons_plot_02_soliton.py: diff --git a/docs/introduction/lessons/plot_02_soliton.zip b/docs/introduction/lessons/plot_02_soliton.zip index 7182b9821..bfca90a95 100644 Binary files a/docs/introduction/lessons/plot_02_soliton.zip and b/docs/introduction/lessons/plot_02_soliton.zip differ diff --git a/docs/introduction/lessons/plot_03_filament.codeobj.json b/docs/introduction/lessons/plot_03_filament.codeobj.json index 072142a94..2b49ca72c 100644 --- a/docs/introduction/lessons/plot_03_filament.codeobj.json +++ b/docs/introduction/lessons/plot_03_filament.codeobj.json @@ -200,7 +200,7 @@ "is_class": true, "is_explicit": false, "module": "solprop.nonlinear.optmat_rates", - "module_short": "solprop.nonlinear.optmat_rates", + "module_short": "solprop.nonlinear", "name": "OptmatRate" }, { @@ -221,7 +221,7 @@ "is_class": false, "is_explicit": false, "module": "solprop.nonlinear.optmat_rates", - "module_short": "solprop.nonlinear.optmat_rates", + "module_short": "solprop.nonlinear", "name": "OptmatRate" } ], @@ -1748,8 +1748,8 @@ { "is_class": false, "is_explicit": false, - "module": "solprop.output.schema", - "module_short": "solprop.output", + "module": "solprop.output.store", + "module_short": "solprop.output.store", "name": "PlaneStore.metadata" }, { @@ -1813,8 +1813,8 @@ { "is_class": false, "is_explicit": false, - "module": "solprop.output.schema", - "module_short": "solprop.output.schema", + "module": "solprop.output.store", + "module_short": "solprop.output.store", "name": "PlaneStore.planes" }, { diff --git a/docs/introduction/lessons/plot_03_filament.ipynb b/docs/introduction/lessons/plot_03_filament.ipynb index f2476ea7d..a6c6c4855 100644 --- a/docs/introduction/lessons/plot_03_filament.ipynb +++ b/docs/introduction/lessons/plot_03_filament.ipynb @@ -114,7 +114,7 @@ "name": "python", "nbconvert_exporter": "python", "pygments_lexer": "ipython3", - "version": "3.14.5" + "version": "3.14.6" } }, "nbformat": 4, diff --git a/docs/introduction/lessons/plot_03_filament.rst b/docs/introduction/lessons/plot_03_filament.rst index 7945f224a..dafe27534 100644 --- a/docs/introduction/lessons/plot_03_filament.rst +++ b/docs/introduction/lessons/plot_03_filament.rst @@ -284,7 +284,7 @@ continue with :doc:`/guide/free-space/beams` and :doc:`/guide/free-space/hankel` .. code-block:: none exit energy / input energy: 0.919089 - 3.8 s; backend native + 3.3 s; backend native @@ -292,7 +292,7 @@ continue with :doc:`/guide/free-space/beams` and :doc:`/guide/free-space/hankel` .. rst-class:: sphx-glr-timing - **Total running time of the script:** (0 minutes 3.877 seconds) + **Total running time of the script:** (0 minutes 3.348 seconds) .. _sphx_glr_download_introduction_lessons_plot_03_filament.py: diff --git a/docs/introduction/lessons/plot_03_filament.zip b/docs/introduction/lessons/plot_03_filament.zip index 49597bb95..719e1ad09 100644 Binary files a/docs/introduction/lessons/plot_03_filament.zip and b/docs/introduction/lessons/plot_03_filament.zip differ diff --git a/docs/introduction/lessons/plot_04_crossing_beams.codeobj.json b/docs/introduction/lessons/plot_04_crossing_beams.codeobj.json index 6508ae05f..3b77ed8ea 100644 --- a/docs/introduction/lessons/plot_04_crossing_beams.codeobj.json +++ b/docs/introduction/lessons/plot_04_crossing_beams.codeobj.json @@ -289,7 +289,7 @@ { "is_class": true, "is_explicit": false, - "module": "solprop.driver.simulation", + "module": "solprop.driver.settings", "module_short": "solprop.driver", "name": "SimulationSettings" }, @@ -1079,8 +1079,8 @@ { "is_class": false, "is_explicit": false, - "module": "solprop.output.schema", - "module_short": "solprop.output.schema", + "module": "solprop.output.store", + "module_short": "solprop.output.store", "name": "PlaneStore.planes" }, { @@ -1150,7 +1150,7 @@ { "is_class": false, "is_explicit": false, - "module": "solprop.driver.simulation", + "module": "solprop.driver.settings", "module_short": "solprop.driver", "name": "SimulationSettings" }, @@ -1436,8 +1436,8 @@ { "is_class": false, "is_explicit": false, - "module": "solprop.output.schema", - "module_short": "solprop.output.schema", + "module": "solprop.output.store", + "module_short": "solprop.output.store", "name": "PlaneStore.planes" }, { @@ -1505,7 +1505,7 @@ { "is_class": false, "is_explicit": false, - "module": "solprop.output.schema", + "module": "solprop.output.records", "module_short": "solprop.output", "name": "SavedPlane" }, @@ -2292,8 +2292,8 @@ { "is_class": false, "is_explicit": false, - "module": "solprop.output.schema", - "module_short": "solprop.output", + "module": "solprop.output.store", + "module_short": "solprop.output.store", "name": "PlaneStore.fields" }, { @@ -2357,8 +2357,8 @@ { "is_class": false, "is_explicit": false, - "module": "solprop.output.schema", - "module_short": "solprop.output", + "module": "solprop.output.store", + "module_short": "solprop.output.store", "name": "PlaneStore.metadata" }, { @@ -2422,8 +2422,8 @@ { "is_class": false, "is_explicit": false, - "module": "solprop.output.schema", - "module_short": "solprop.output.schema", + "module": "solprop.output.store", + "module_short": "solprop.output.store", "name": "PlaneStore.planes" }, { @@ -2466,7 +2466,7 @@ { "is_class": false, "is_explicit": false, - "module": "solprop.driver.simulation", + "module": "solprop.driver.settings", "module_short": "solprop.driver", "name": "SimulationSettings" }, diff --git a/docs/introduction/lessons/plot_04_crossing_beams.ipynb b/docs/introduction/lessons/plot_04_crossing_beams.ipynb index 7faee157d..9f4f7048d 100644 --- a/docs/introduction/lessons/plot_04_crossing_beams.ipynb +++ b/docs/introduction/lessons/plot_04_crossing_beams.ipynb @@ -139,7 +139,7 @@ "name": "python", "nbconvert_exporter": "python", "pygments_lexer": "ipython3", - "version": "3.14.5" + "version": "3.14.6" } }, "nbformat": 4, diff --git a/docs/introduction/lessons/plot_04_crossing_beams.rst b/docs/introduction/lessons/plot_04_crossing_beams.rst index ca38ce70e..f1e8a2136 100644 --- a/docs/introduction/lessons/plot_04_crossing_beams.rst +++ b/docs/introduction/lessons/plot_04_crossing_beams.rst @@ -340,9 +340,9 @@ local maxima. We compare their fluence centroids with the straight-ray estimate. .. code-block:: none - relative field superposition error: 1.184e-15 + relative field superposition error: 1.188e-15 largest centroid error: 5.764e-04 μm - largest relative energy change: 1.436e-12 + largest relative energy change: 1.435e-12 largest energy fraction in the outer collar region: 0.000e+00 @@ -459,8 +459,8 @@ the edge. See :doc:`/guide/numerics/boundaries`. .. code-block:: none fitted fringe spacing: 80.002 μm; expected 80.001 μm - largest relative fluence change on spatial refinement: 6.930e-14 - 16.2 s including checks; backend native + largest relative fluence change on spatial refinement: 6.928e-14 + 14.6 s including checks; backend native @@ -485,7 +485,7 @@ demonstrates adding a material response to a Cartesian beam. .. rst-class:: sphx-glr-timing - **Total running time of the script:** (0 minutes 16.192 seconds) + **Total running time of the script:** (0 minutes 14.668 seconds) .. _sphx_glr_download_introduction_lessons_plot_04_crossing_beams.py: diff --git a/docs/introduction/lessons/plot_04_crossing_beams.zip b/docs/introduction/lessons/plot_04_crossing_beams.zip index a938ea12d..0fa79fb8a 100644 Binary files a/docs/introduction/lessons/plot_04_crossing_beams.zip and b/docs/introduction/lessons/plot_04_crossing_beams.zip differ diff --git a/docs/primer/grids.md b/docs/primer/grids.md index 749002d90..c5f0226e8 100644 --- a/docs/primer/grids.md +++ b/docs/primer/grids.md @@ -68,7 +68,8 @@ the carrier, for $\omega_{\max}$): $\tfrac34|E_a|^2E$, whose spectrum stays near the fundamental. A short calculation shows that it would not suffice for the full cubic: the third harmonic of the collar, at $3.3\omega_{\max}$, would fold back to $0.7\omega_{\max}$, inside the band. -- **`ffac=2`** is the minimum. On a field grid it truncates the upper collar. On an envelope grid `ffac` +- **`ffac=2.2`** is the field-grid minimum: it puts the fine Nyquist frequency at the collar's upper edge, + $1.1\omega_{\max}$, so the coarse Nyquist bin carries no field. **`ffac=2`** is the envelope-grid minimum. On an envelope grid `ffac` multiplies the relative half-span $\Omega=\max(|1.1\omega_{\max}-\omega_0|,|\omega_0-\omega_{\min}/2|)$ instead of $\omega_{\max}$, so the envelope default, `ffac=2` without a harmonic term, puts the Nyquist offset at exactly $\Omega$: the active band and its collars are represented, and the coarse and fine grids coincide. diff --git a/docs/primer/ionisation.md b/docs/primer/ionisation.md index 8ca99d489..1df58b79c 100644 --- a/docs/primer/ionisation.md +++ b/docs/primer/ionisation.md @@ -159,9 +159,11 @@ factor of at least about 3.55. The plain trapezoid remains available as an optio multiplier for components inside its design band, not the total error of the plasma polarisation, the ionisation or the work it does. Unresolved integrands, truncation at the ends of the window, an undershoot of the filtered rate beside a sharp spike, a small mismatch between the -work and the population, and a look-ahead of a few samples all remain. A run records -`plasma_undershoot`, `plasma_work_defect` and `plasma_boundary_level` at each save plane for -inspection; they are not used as pass/fail conditions, and temporal refinement remains the check +work and the population, and a look-ahead of a few samples all remain. On the capillary and +hollow-core waveguide routes a run whose field plasma uses this filter records +`plasma_undershoot`, `plasma_work_defect` and `plasma_boundary_level` at each save plane by +default; elsewhere they are recorded only when named in the run's statistics. They are for +inspection, not used as pass/fail conditions, and temporal refinement remains the check ([how the current integrals are formed](../guide/media/field-plasma.md#how-the-current-integrals-are-formed)). This is an example of a general principle in solprop's numerics: an error that is the same at every step, of the representation diff --git a/docs/primer/stepping.md b/docs/primer/stepping.md index 3fb88298f..a0edfd758 100644 --- a/docs/primer/stepping.md +++ b/docs/primer/stepping.md @@ -214,7 +214,7 @@ scheme at first ([the two temporal schemes](../guide/numerics/boundaries.md#the- integrated explicitly, so it limits the step to the integrator's stability interval, which binds only on very short runs. The split integrates the rate exactly and is unconditionally stable; on the spatial routes the in-stage collar took 1.2 to 4.6 times its steps at equal or worse accuracy, so the spatial routes take the split by default -([SEP 21](../dev/seps/archive/sep-0021-absorbing-boundaries.md)). +([SEP 21](https://github.com/LupoLab/solprop/blob/main/docs/dev/seps/archive/sep-0021-absorbing-boundaries.md)). ## 12.8 Linear coupling between modes diff --git a/docs/tutorials/basics/plot_06_material_choices.py b/docs/tutorials/basics/plot_06_material_choices.py index 74d8996c0..69fa1ab29 100644 --- a/docs/tutorials/basics/plot_06_material_choices.py +++ b/docs/tutorials/basics/plot_06_material_choices.py @@ -8,7 +8,8 @@ The default material data for gases, solids, Raman responses and ionisation rates come from the curated library optmat -(`SEP 3 <../../dev/seps/archive/sep-0003-optmat-materials.html>`_): a run +(`SEP 3 <https://github.com/LupoLab/solprop/blob/main/docs/dev/seps/archive/sep-0003-optmat-materials.md>`_): +a run with no ``materials=`` takes ``MaterialSelection()``, optmat's recommended model of each family. This tutorial shows how to see what a run resolved, how to declare a different material, and how to tell which part of the physics a change touches. diff --git a/docs/tutorials/capillaries/plot_11_dispersive_kerr.py b/docs/tutorials/capillaries/plot_11_dispersive_kerr.py index e3ef6ff3e..b18d2d3a3 100644 --- a/docs/tutorials/capillaries/plot_11_dispersive_kerr.py +++ b/docs/tutorials/capillaries/plot_11_dispersive_kerr.py @@ -11,9 +11,9 @@ ultraviolet: argon's Kerr coefficient at 267 nm is twice its value at 800 nm. The default ``carrier-kerr`` policy freezes it at the run's carrier and uses that value for every process the cubic drives. Two opt-in policies of -`SEP 6 <../../dev/seps/archive/sep-0006-dispersive-nonlinearity.html>`_ evaluate -optmat's whole fit instead, at the absolute frequencies of every quartet, in one -broadband polarisation (:doc:`/guide/media/dispersive-kerr`): +`SEP 6 <https://github.com/LupoLab/solprop/blob/main/docs/dev/seps/archive/sep-0006-dispersive-nonlinearity.md>`_ +evaluate optmat's whole fit instead, at the absolute frequencies of every quartet, +in one broadband polarisation (:doc:`/guide/media/dispersive-kerr`): - ``"gas-polynomial"`` evaluates the gas dispersion polynomial itself; - ``"symmetric-kerr"`` factorises its Kerr diagonal symmetrically over the four legs, a diff --git a/docs/tutorials/free_space/plot_06_four_wave_mixing_scan.py b/docs/tutorials/free_space/plot_06_four_wave_mixing_scan.py index 3e3aa4ae8..01091ba88 100644 --- a/docs/tutorials/free_space/plot_06_four_wave_mixing_scan.py +++ b/docs/tutorials/free_space/plot_06_four_wave_mixing_scan.py @@ -387,4 +387,4 @@ def kx_spectrum(spatial_grid, run): # statistics-only planes, :doc:`/guide/numerics/boundaries` the custom absorber and # the two lengths of a collar, and :doc:`/guide/free-space/cartesian` the one-half rule # and the transverse safety ramp. The design is -# :doc:`SEP 22 </dev/seps/archive/sep-0022-memory-lean-spatial-execution>`. +# `SEP 22 <https://github.com/LupoLab/solprop/blob/main/docs/dev/seps/archive/sep-0022-memory-lean-spatial-execution.md>`_. diff --git a/docs/tutorials/free_space/plot_07_far_field_statistics.py b/docs/tutorials/free_space/plot_07_far_field_statistics.py index 2b7225d69..c90b395c1 100644 --- a/docs/tutorials/free_space/plot_07_far_field_statistics.py +++ b/docs/tutorials/free_space/plot_07_far_field_statistics.py @@ -529,4 +529,4 @@ def exact_fraction(profile, weighting): # weightings and what each backend computes; :doc:`/guide/free-space/model` gives the # far-zone and Fourier-plane conditions and the paraxial error; # :doc:`/guide/results/output` describes statistics-only planes. The design is -# :doc:`SEP 23 </dev/seps/archive/sep-0023-far-field-aperture-spectra>`. +# `SEP 23 <https://github.com/LupoLab/solprop/blob/main/docs/dev/seps/archive/sep-0023-far-field-aperture-spectra.md>`_. diff --git a/docs/tutorials/free_space/plot_08_radial_capillary_coupling.py b/docs/tutorials/free_space/plot_08_radial_capillary_coupling.py index 019aee432..5b62231e4 100644 --- a/docs/tutorials/free_space/plot_08_radial_capillary_coupling.py +++ b/docs/tutorials/free_space/plot_08_radial_capillary_coupling.py @@ -516,4 +516,4 @@ # their budgets. :doc:`/guide/free-space/model` and # :doc:`/guide/waveguides/capillaries` describe the two propagations. # The design is -# :doc:`SEP 31 </dev/seps/archive/sep-0031-simulation-coupling>`. +# `SEP 31 <https://github.com/LupoLab/solprop/blob/main/docs/dev/seps/archive/sep-0031-simulation-coupling.md>`_. diff --git a/docs/tutorials/waveguides/plot_02_tabulated_modes.py b/docs/tutorials/waveguides/plot_02_tabulated_modes.py index c36d15e5b..c8ba1684f 100644 --- a/docs/tutorials/waveguides/plot_02_tabulated_modes.py +++ b/docs/tutorials/waveguides/plot_02_tabulated_modes.py @@ -47,6 +47,7 @@ from solprop.constants import C from solprop.driver import Simulation, prop_gnlse +from solprop.exceptions import NoZeroDispersionError from solprop.grid import EnvelopeGrid from solprop.log import NullReporter from solprop.modes import IndexTable, TabulatedHollowMode, TabulatedMode @@ -117,6 +118,10 @@ # %% # Bracket each root locally; broad endpoints can have the same sign even when # two roots lie inside. All probes stay inside the vacuum table and gas fit. +# ``zdw`` returns a zero only where it bounds a dispersion regime at least 1.5 % wide +# in frequency: the evacuated fibre's ``beta_2`` ripples through zero twice within +# 3 nm near 455 nm, which is fine structure of the interpolant and no zero-dispersion +# wavelength, so the search refuses it and the loop passes over it. probe_wavelength = np.linspace(450e-9, 990e-9, 200) root_pressures = [] root_wavelengths = [] @@ -132,17 +137,18 @@ curvature = beta2(mode, 2 * np.pi * C / probe_wavelength) brackets = np.flatnonzero(curvature[:-1] * curvature[1:] < 0) for index in brackets: - root_pressures.append(pressure) - root_wavelengths.append( - zdw( + try: + root = zdw( mode, wavelength_limits=( float(probe_wavelength[index]), float(probe_wavelength[index + 1]), ), ) - * 1e9 - ) + except NoZeroDispersionError: + continue + root_pressures.append(pressure) + root_wavelengths.append(root * 1e9) figure, axis = plt.subplots(figsize=(6, 3.5)) axis.scatter(root_pressures, root_wavelengths, s=22) axis.set( diff --git a/gui/AGENTS.md b/gui/AGENTS.md index 248a0cc0c..3c1ef7d69 100644 --- a/gui/AGENTS.md +++ b/gui/AGENTS.md @@ -34,6 +34,10 @@ them is corrected. both rules, statically and by what a fresh interpreter loads. - **Never block the window.** Anything that can take more than about 50 ms happens in another process. +- **Garbage is collected between events.** Whatever hosts `WorkflowWindow` (the + command, the guide's screenshot script) calls `collect_between_events()` before + making it: a plot freed by Python's automatic collection inside its own scene's + event deletes the scene under Qt's feet. The tests collect between tests instead. - **One way to run** (design 13.4, D21). The window's kernel is a child of the window's; every run, on this computer or another, is a job of its own that keeps its record in its folder, started through a machine's helper (this computer has one too) and @@ -46,7 +50,6 @@ them is corrected. |---|---| | Sync | `uv sync --extra gui --group gui-test`, which also builds the native backend (a sync removes any extra it does not name) | | Run the window | `uv run solprop-gui` | -| Run the workflow window being built (design, section 16) | `uv run solprop-gui --workflow` | | Run a prepared run folder with no window (what a machine's job runs) | `uv run python -m solprop.service.job FOLDER` | | The front end's gate | `uv run poe check-gui`: types (`gui-types`), docstrings (`gui-docstrings`) and tests (`gui-test`, offscreen, with coverage) | | Lint, format, spelling, licences | the repository's: `uv run ruff check .`, `uv run ruff format .`, `uv run codespell`, `uv run poe reuse` | diff --git a/gui/README.md b/gui/README.md index 065263db7..64bce81c4 100644 --- a/gui/README.md +++ b/gui/README.md @@ -35,7 +35,7 @@ sudo apt install libegl1 libxkbcommon0 libxcb-cursor0 for it (a soliton order, a zero-dispersion wavelength) and a preview plot. A number can be typed as a target, and solprop solves for the input that gives it. - **Run** shows the spectrum and the pulse growing along the waveguide, and can stop and - resume. A service process can keep runs going after the window closes. + resume. A run goes on after the window closes, unless it is tied to the window. - **Analyse** reads the results on pages of the class, all at one plane, with zoom, readouts, widths at half maximum and publication figures drawn by `solprop.plotting`. - **Scans** run a setup over a grid of its parameters, and any point opens as a setup. diff --git a/gui/hatch_build.py b/gui/hatch_build.py index 5044f2a4b..e4f472ae0 100644 --- a/gui/hatch_build.py +++ b/gui/hatch_build.py @@ -41,6 +41,8 @@ def update(self, metadata: dict[str, Any]) -> None: """ metadata["dependencies"] = [ f"solprop=={metadata['version']}", + # solprop's own floor: the window's views compute with NumPy directly. + "numpy>=2.5", # 6.10.1: the first release whose wheels admit CPython 3.14 (6.10.0 declares # <3.14). Essentials holds the Qt modules the front end uses, about a third # of the full PySide6. diff --git a/gui/pyproject.toml b/gui/pyproject.toml index 095f51dbe..a6e6beccb 100644 --- a/gui/pyproject.toml +++ b/gui/pyproject.toml @@ -12,7 +12,7 @@ name = "solprop-gui" description = "A desktop front end for solprop: set up, run and read ultrafast propagation simulations" readme = "README.md" # The code is GPL; the window's font, IBM Plex Sans, is under the Open Font License; the -# user guide's pages carried for Help, the help figures and the icon are CC-BY (REUSE.toml). +# user guide's pages carried for Help, the drawings and the icon are CC-BY (REUSE.toml). license = "GPL-3.0-or-later AND OFL-1.1 AND CC-BY-4.0" # The wheel carries the licences: copies of the root LICENSE and LICENSES/CC-BY-4.0.txt, # since license-files cannot reach outside the project directory (tests/test_licences.py). diff --git a/gui/src/solprop_gui/__init__.py b/gui/src/solprop_gui/__init__.py index 05de56837..9569b2e63 100644 --- a/gui/src/solprop_gui/__init__.py +++ b/gui/src/solprop_gui/__init__.py @@ -10,8 +10,9 @@ comes from a public solprop call, made in a separate process. The design is ``docs/dev/gui/design.md`` in the solprop repository. -The package's layers are ``model``, ``registry`` and ``service``, which import no -Qt, and ``ui``, ``views`` and ``help``, which build the window. +The package's layers are ``model``, ``registry``, ``classes`` and ``help``, which +import no Qt, and ``ui`` and ``views``, which build the window. The service the window +reaches its kernel and its runs through is ``solprop.service``, in solprop. """ from importlib.metadata import PackageNotFoundError, version diff --git a/gui/src/solprop_gui/app.py b/gui/src/solprop_gui/app.py index 0517c168d..f9edff387 100644 --- a/gui/src/solprop_gui/app.py +++ b/gui/src/solprop_gui/app.py @@ -31,15 +31,10 @@ def main(argv: Sequence[str] | None = None) -> int: prog="solprop-gui", description="A desktop front end for solprop." ) parser.add_argument("--version", action="version", version=__version__) - # Accepted, and no longer needed: the workflow window is the only one. - parser.add_argument("--workflow", action="store_true", help=argparse.SUPPRESS) - options = parser.parse_args(argv) + parser.parse_args(argv) # Qt is imported here, after the arguments: `--version` and `--help` answer without # loading it. - from pyqtgraph.util.garbage_collector import ( # noqa: PLC0415 - see above - GarbageCollector, - ) from PySide6.QtWidgets import QApplication # noqa: PLC0415 - see above from solprop_gui.ui.identity import ( # noqa: PLC0415 - see above @@ -48,17 +43,14 @@ def main(argv: Sequence[str] | None = None) -> int: ) from solprop_gui.ui.workflow_window import ( # noqa: PLC0415 - see above WorkflowWindow, + collect_between_events, ) # Before the first window, so that Windows shows this application's taskbar button. set_windows_app_id() application = QApplication.instance() or QApplication(sys.argv[:1]) apply_identity(application) # pyright: ignore[reportArgumentType] - del options - # Garbage is collected on a timer, between events, never by Python in the middle of - # one: a plot dropped while its scene still had an event queued was otherwise freed - # inside that event's handler, deleting the scene under Qt's feet. - collector = GarbageCollector(interval=1.0) + collector = collect_between_events() window = WorkflowWindow() window.show() try: diff --git a/gui/src/solprop_gui/classes/catalog.py b/gui/src/solprop_gui/classes/catalog.py index 4586d6754..1a7ff41bf 100644 --- a/gui/src/solprop_gui/classes/catalog.py +++ b/gui/src/solprop_gui/classes/catalog.py @@ -45,7 +45,6 @@ _ALONG = AnalysisPage("along", "Along z", ("statistics",)) _MODES = AnalysisPage("modes", "Modes", ("fields", "modes")) _COMPRESS = AnalysisPage("compress", "Compress", ("fields",), "compression") -_NOISE = AnalysisPage("noise", "Noise and coherence", ("fields", "ensemble")) _HEALTH = AnalysisPage("health", "Run health") _PULSE = Section( @@ -316,7 +315,7 @@ numbers="fibre_sheet", curve="fibre_curve", preview="Group-velocity dispersion against wavelength", - pages=(_OVERVIEW, _PLANE, _SPECTROGRAM, _ALONG, _COMPRESS, _NOISE, _HEALTH), + pages=(_OVERVIEW, _PLANE, _SPECTROGRAM, _ALONG, _COMPRESS, _HEALTH), statistics=("energy",), ) diff --git a/gui/src/solprop_gui/help/figures.py b/gui/src/solprop_gui/help/figures.py deleted file mode 100644 index 1884f0852..000000000 --- a/gui/src/solprop_gui/help/figures.py +++ /dev/null @@ -1,106 +0,0 @@ -# SPDX-FileCopyrightText: 2026 John C. Travers and contributors -# -# SPDX-License-Identifier: GPL-3.0-or-later - -"""The geometry classes' pictures, for the start page's gallery. - -Each class has a simple cross-section drawn for the gallery (``figures/<key>.svg``), -after the user guide's geometry figures but reduced to what tells the classes apart. -They are styled with CSS custom properties, a light palette and a dark one under -``prefers-color-scheme``, which Qt's SVG renderer does not read: :func:`resolved` writes -the chosen palette's colours in their place, so the gallery follows the window's theme. -""" - -import re -from importlib import resources -from typing import Final - -__all__ = ["FIGURES", "figure_text", "resolved"] - -FIGURES: Final = ( - "step-index", - "grin", - "capillary-averaged", - "capillary-modal", - "antiresonant", - "gnlse", - "rectangular", - "slab", - "cartesian", - "line", - "radial", -) -"""The geometry classes with a picture, by their cards' keys.""" - -_PALETTE = re.compile(r"svg\s*\{([^}]*)\}") -_PROPERTY = re.compile(r"--([\w-]+):\s*([^;]+);") -_DARK = re.compile( - r"@media\s*\(prefers-color-scheme:\s*dark\)\s*\{\s*svg\s*\{[^}]*\}\s*\}" -) -_VARIABLE = re.compile(r"var\(--([\w-]+)\)") - - -def resolved(text: str, *, dark: bool = False) -> str: - """Return a figure's SVG with its palette's colours written in for Qt. - - Parameters - ---------- - text : str - The figure, as the guide's script draws it. - dark : bool, optional - Whether to take the dark palette. - - Returns - ------- - str - The SVG without custom properties: each ``var(--name)`` replaced by the - colour, and the palettes removed. - - Examples - -------- - >>> svg = ( - ... "<style>svg { --ink: #111; } @media (prefers-color-scheme: dark) " - ... "{ svg { --ink: #eee; } } .o { stroke: var(--ink); }</style>" - ... ) - >>> resolved(svg).split("{")[-1].strip() - 'stroke: #111; }</style>' - >>> "#eee" in resolved(svg, dark=True), "var(" in resolved(svg) - (True, False) - >>> resolved("<style>svg { --a: #123; } .o { fill: var(--a); }</style>", dark=True) - '<style> .o { fill: #123; }</style>' - """ - palettes = _PALETTE.findall(text) - colours = dict(_PROPERTY.findall(palettes[0])) if palettes else {} - if dark: - dark_block = _DARK.search(text) - if dark_block is not None: - colours.update(_PROPERTY.findall(dark_block.group(0))) - text = _DARK.sub("", text) - text = _PALETTE.sub("", text, count=1) - return _VARIABLE.sub(lambda match: colours[match.group(1)].strip(), text) - - -def figure_text(key: str, *, dark: bool = False) -> str | None: - """Return a geometry class's figure, resolved for Qt. - - Parameters - ---------- - key : str - The card's key. - dark : bool, optional - Whether to take the dark palette. - - Returns - ------- - str or None - The SVG; ``None`` for a class without a figure. - - Examples - -------- - >>> "var(" in figure_text("antiresonant"), figure_text("nope") is None - (False, True) - """ - if key not in FIGURES: - return None - source = resources.files("solprop_gui.help") / "figures" / f"{key}.svg" - return resolved(source.read_text(encoding="utf-8"), dark=dark) diff --git a/gui/src/solprop_gui/help/figures/antiresonant.svg b/gui/src/solprop_gui/help/figures/antiresonant.svg deleted file mode 100644 index b3dde6a65..000000000 --- a/gui/src/solprop_gui/help/figures/antiresonant.svg +++ /dev/null @@ -1,70 +0,0 @@ -<?xml version="1.0" encoding="UTF-8"?> -<!-- SPDX-FileCopyrightText: 2026 John C. Travers and contributors --> -<!-- SPDX-License-Identifier: GPL-3.0-or-later --> -<svg xmlns="http://www.w3.org/2000/svg" width="200" height="150" viewBox="0 0 200 150"> -<style> -svg { - --ink: #1b1f24; - --dim: #5b6673; - --gas-fill: #e9f1fb; - --glass-fill: #d5e9dc; - --glass-edge: #2c7a55; - --core-fill: #cfe0f4; - --core-edge: #2f5eb0; - --beam: #b8334f; - --beam-b: #6f45a6; - --beam-c: #a96a15; -} -@media (prefers-color-scheme: dark) { - svg { - --ink: #e7eaef; - --dim: #9aa5b3; - --gas-fill: #18222f; - --glass-fill: #173528; - --glass-edge: #5cb98a; - --core-fill: #1d3150; - --core-edge: #7ba6e8; - --beam: #ee8ca0; - --beam-b: #b99ae6; - --beam-c: #e0a44f; - } -} -.glass { fill: var(--glass-fill); stroke: var(--glass-edge); stroke-width: 2; } -.gas { fill: var(--gas-fill); stroke: var(--glass-edge); stroke-width: 1.2; } -.core { fill: var(--core-fill); stroke: var(--core-edge); stroke-width: 1.5; } -.axis { fill: none; stroke: var(--dim); stroke-width: 1.2; } -.node { fill: var(--dim); stroke: none; } -.ring { fill: none; stroke: var(--dim); stroke-width: 1; stroke-dasharray: 3 3; } -.curve { fill: none; stroke: var(--beam); stroke-width: 2.4; } -.curve-b { fill: none; stroke: var(--beam-b); stroke-width: 2; } -.curve-c { fill: none; stroke: var(--beam-c); stroke-width: 2; } -.label { fill: var(--dim); font-family: sans-serif; font-size: 13px; - font-style: italic; } -</style> -<defs> -<radialGradient id="spot"> - <stop offset="0" stop-color="var(--beam)" stop-opacity="0.95"/> - <stop offset="0.55" stop-color="var(--beam)" stop-opacity="0.45"/> - <stop offset="1" stop-color="var(--beam)" stop-opacity="0"/> -</radialGradient> -<radialGradient id="graded"> - <stop offset="0" stop-color="var(--core-edge)" stop-opacity="0.75"/> - <stop offset="1" stop-color="var(--core-edge)" stop-opacity="0"/> -</radialGradient> -<linearGradient id="band" x1="0" y1="0" x2="0" y2="1"> - <stop offset="0" stop-color="var(--beam)" stop-opacity="0"/> - <stop offset="0.5" stop-color="var(--beam)" stop-opacity="0.9"/> - <stop offset="1" stop-color="var(--beam)" stop-opacity="0"/> -</linearGradient> -</defs> -<circle class="glass" cx="100" cy="75" r="70"/> -<circle class="gas" cx="100" cy="75" r="62"/> -<circle class="glass" cx="100.0" cy="122.0" r="13"/> -<circle class="glass" cx="63.3" cy="104.3" r="13"/> -<circle class="glass" cx="54.2" cy="64.5" r="13"/> -<circle class="glass" cx="79.6" cy="32.7" r="13"/> -<circle class="glass" cx="120.4" cy="32.7" r="13"/> -<circle class="glass" cx="145.8" cy="64.5" r="13"/> -<circle class="glass" cx="136.7" cy="104.3" r="13"/> -<ellipse cx="100" cy="75" rx="26" ry="26" fill="url(#spot)"/> -</svg> diff --git a/gui/src/solprop_gui/help/figures/capillary-averaged.svg b/gui/src/solprop_gui/help/figures/capillary-averaged.svg deleted file mode 100644 index d33435b00..000000000 --- a/gui/src/solprop_gui/help/figures/capillary-averaged.svg +++ /dev/null @@ -1,63 +0,0 @@ -<?xml version="1.0" encoding="UTF-8"?> -<!-- SPDX-FileCopyrightText: 2026 John C. Travers and contributors --> -<!-- SPDX-License-Identifier: GPL-3.0-or-later --> -<svg xmlns="http://www.w3.org/2000/svg" width="200" height="150" viewBox="0 0 200 150"> -<style> -svg { - --ink: #1b1f24; - --dim: #5b6673; - --gas-fill: #e9f1fb; - --glass-fill: #d5e9dc; - --glass-edge: #2c7a55; - --core-fill: #cfe0f4; - --core-edge: #2f5eb0; - --beam: #b8334f; - --beam-b: #6f45a6; - --beam-c: #a96a15; -} -@media (prefers-color-scheme: dark) { - svg { - --ink: #e7eaef; - --dim: #9aa5b3; - --gas-fill: #18222f; - --glass-fill: #173528; - --glass-edge: #5cb98a; - --core-fill: #1d3150; - --core-edge: #7ba6e8; - --beam: #ee8ca0; - --beam-b: #b99ae6; - --beam-c: #e0a44f; - } -} -.glass { fill: var(--glass-fill); stroke: var(--glass-edge); stroke-width: 2; } -.gas { fill: var(--gas-fill); stroke: var(--glass-edge); stroke-width: 1.2; } -.core { fill: var(--core-fill); stroke: var(--core-edge); stroke-width: 1.5; } -.axis { fill: none; stroke: var(--dim); stroke-width: 1.2; } -.node { fill: var(--dim); stroke: none; } -.ring { fill: none; stroke: var(--dim); stroke-width: 1; stroke-dasharray: 3 3; } -.curve { fill: none; stroke: var(--beam); stroke-width: 2.4; } -.curve-b { fill: none; stroke: var(--beam-b); stroke-width: 2; } -.curve-c { fill: none; stroke: var(--beam-c); stroke-width: 2; } -.label { fill: var(--dim); font-family: sans-serif; font-size: 13px; - font-style: italic; } -</style> -<defs> -<radialGradient id="spot"> - <stop offset="0" stop-color="var(--beam)" stop-opacity="0.95"/> - <stop offset="0.55" stop-color="var(--beam)" stop-opacity="0.45"/> - <stop offset="1" stop-color="var(--beam)" stop-opacity="0"/> -</radialGradient> -<radialGradient id="graded"> - <stop offset="0" stop-color="var(--core-edge)" stop-opacity="0.75"/> - <stop offset="1" stop-color="var(--core-edge)" stop-opacity="0"/> -</radialGradient> -<linearGradient id="band" x1="0" y1="0" x2="0" y2="1"> - <stop offset="0" stop-color="var(--beam)" stop-opacity="0"/> - <stop offset="0.5" stop-color="var(--beam)" stop-opacity="0.9"/> - <stop offset="1" stop-color="var(--beam)" stop-opacity="0"/> -</linearGradient> -</defs> -<circle class="glass" cx="100" cy="75" r="64"/> -<circle class="gas" cx="100" cy="75" r="50"/> -<ellipse cx="100" cy="75" rx="34" ry="34" fill="url(#spot)"/> -</svg> diff --git a/gui/src/solprop_gui/help/figures/capillary-modal.svg b/gui/src/solprop_gui/help/figures/capillary-modal.svg deleted file mode 100644 index d5b4d89f1..000000000 --- a/gui/src/solprop_gui/help/figures/capillary-modal.svg +++ /dev/null @@ -1,65 +0,0 @@ -<?xml version="1.0" encoding="UTF-8"?> -<!-- SPDX-FileCopyrightText: 2026 John C. Travers and contributors --> -<!-- SPDX-License-Identifier: GPL-3.0-or-later --> -<svg xmlns="http://www.w3.org/2000/svg" width="200" height="150" viewBox="0 0 200 150"> -<style> -svg { - --ink: #1b1f24; - --dim: #5b6673; - --gas-fill: #e9f1fb; - --glass-fill: #d5e9dc; - --glass-edge: #2c7a55; - --core-fill: #cfe0f4; - --core-edge: #2f5eb0; - --beam: #b8334f; - --beam-b: #6f45a6; - --beam-c: #a96a15; -} -@media (prefers-color-scheme: dark) { - svg { - --ink: #e7eaef; - --dim: #9aa5b3; - --gas-fill: #18222f; - --glass-fill: #173528; - --glass-edge: #5cb98a; - --core-fill: #1d3150; - --core-edge: #7ba6e8; - --beam: #ee8ca0; - --beam-b: #b99ae6; - --beam-c: #e0a44f; - } -} -.glass { fill: var(--glass-fill); stroke: var(--glass-edge); stroke-width: 2; } -.gas { fill: var(--gas-fill); stroke: var(--glass-edge); stroke-width: 1.2; } -.core { fill: var(--core-fill); stroke: var(--core-edge); stroke-width: 1.5; } -.axis { fill: none; stroke: var(--dim); stroke-width: 1.2; } -.node { fill: var(--dim); stroke: none; } -.ring { fill: none; stroke: var(--dim); stroke-width: 1; stroke-dasharray: 3 3; } -.curve { fill: none; stroke: var(--beam); stroke-width: 2.4; } -.curve-b { fill: none; stroke: var(--beam-b); stroke-width: 2; } -.curve-c { fill: none; stroke: var(--beam-c); stroke-width: 2; } -.label { fill: var(--dim); font-family: sans-serif; font-size: 13px; - font-style: italic; } -</style> -<defs> -<radialGradient id="spot"> - <stop offset="0" stop-color="var(--beam)" stop-opacity="0.95"/> - <stop offset="0.55" stop-color="var(--beam)" stop-opacity="0.45"/> - <stop offset="1" stop-color="var(--beam)" stop-opacity="0"/> -</radialGradient> -<radialGradient id="graded"> - <stop offset="0" stop-color="var(--core-edge)" stop-opacity="0.75"/> - <stop offset="1" stop-color="var(--core-edge)" stop-opacity="0"/> -</radialGradient> -<linearGradient id="band" x1="0" y1="0" x2="0" y2="1"> - <stop offset="0" stop-color="var(--beam)" stop-opacity="0"/> - <stop offset="0.5" stop-color="var(--beam)" stop-opacity="0.9"/> - <stop offset="1" stop-color="var(--beam)" stop-opacity="0"/> -</linearGradient> -</defs> -<circle class="glass" cx="100" cy="75" r="64"/> -<circle class="gas" cx="100" cy="75" r="50"/> -<ellipse cx="100" cy="75" rx="22" ry="22" fill="url(#spot)"/> -<circle class="curve-b" cx="100" cy="75" r="29"/> -<circle class="curve-c" cx="100" cy="75" r="40"/> -</svg> diff --git a/gui/src/solprop_gui/help/figures/cartesian.svg b/gui/src/solprop_gui/help/figures/cartesian.svg deleted file mode 100644 index 52bbf34eb..000000000 --- a/gui/src/solprop_gui/help/figures/cartesian.svg +++ /dev/null @@ -1,164 +0,0 @@ -<?xml version="1.0" encoding="UTF-8"?> -<!-- SPDX-FileCopyrightText: 2026 John C. Travers and contributors --> -<!-- SPDX-License-Identifier: GPL-3.0-or-later --> -<svg xmlns="http://www.w3.org/2000/svg" width="200" height="150" viewBox="0 0 200 150"> -<style> -svg { - --ink: #1b1f24; - --dim: #5b6673; - --gas-fill: #e9f1fb; - --glass-fill: #d5e9dc; - --glass-edge: #2c7a55; - --core-fill: #cfe0f4; - --core-edge: #2f5eb0; - --beam: #b8334f; - --beam-b: #6f45a6; - --beam-c: #a96a15; -} -@media (prefers-color-scheme: dark) { - svg { - --ink: #e7eaef; - --dim: #9aa5b3; - --gas-fill: #18222f; - --glass-fill: #173528; - --glass-edge: #5cb98a; - --core-fill: #1d3150; - --core-edge: #7ba6e8; - --beam: #ee8ca0; - --beam-b: #b99ae6; - --beam-c: #e0a44f; - } -} -.glass { fill: var(--glass-fill); stroke: var(--glass-edge); stroke-width: 2; } -.gas { fill: var(--gas-fill); stroke: var(--glass-edge); stroke-width: 1.2; } -.core { fill: var(--core-fill); stroke: var(--core-edge); stroke-width: 1.5; } -.axis { fill: none; stroke: var(--dim); stroke-width: 1.2; } -.node { fill: var(--dim); stroke: none; } -.ring { fill: none; stroke: var(--dim); stroke-width: 1; stroke-dasharray: 3 3; } -.curve { fill: none; stroke: var(--beam); stroke-width: 2.4; } -.curve-b { fill: none; stroke: var(--beam-b); stroke-width: 2; } -.curve-c { fill: none; stroke: var(--beam-c); stroke-width: 2; } -.label { fill: var(--dim); font-family: sans-serif; font-size: 13px; - font-style: italic; } -</style> -<defs> -<radialGradient id="spot"> - <stop offset="0" stop-color="var(--beam)" stop-opacity="0.95"/> - <stop offset="0.55" stop-color="var(--beam)" stop-opacity="0.45"/> - <stop offset="1" stop-color="var(--beam)" stop-opacity="0"/> -</radialGradient> -<radialGradient id="graded"> - <stop offset="0" stop-color="var(--core-edge)" stop-opacity="0.75"/> - <stop offset="1" stop-color="var(--core-edge)" stop-opacity="0"/> -</radialGradient> -<linearGradient id="band" x1="0" y1="0" x2="0" y2="1"> - <stop offset="0" stop-color="var(--beam)" stop-opacity="0"/> - <stop offset="0.5" stop-color="var(--beam)" stop-opacity="0.9"/> - <stop offset="1" stop-color="var(--beam)" stop-opacity="0"/> -</linearGradient> -</defs> -<circle class="node" cx="40" cy="27" r="1.6"/> -<circle class="node" cx="40" cy="39" r="1.6"/> -<circle class="node" cx="40" cy="51" r="1.6"/> -<circle class="node" cx="40" cy="63" r="1.6"/> -<circle class="node" cx="40" cy="75" r="1.6"/> -<circle class="node" cx="40" cy="87" r="1.6"/> -<circle class="node" cx="40" cy="99" r="1.6"/> -<circle class="node" cx="40" cy="111" r="1.6"/> -<circle class="node" cx="40" cy="123" r="1.6"/> -<circle class="node" cx="52" cy="27" r="1.6"/> -<circle class="node" cx="52" cy="39" r="1.6"/> -<circle class="node" cx="52" cy="51" r="1.6"/> -<circle class="node" cx="52" cy="63" r="1.6"/> -<circle class="node" cx="52" cy="75" r="1.6"/> -<circle class="node" cx="52" cy="87" r="1.6"/> -<circle class="node" cx="52" cy="99" r="1.6"/> -<circle class="node" cx="52" cy="111" r="1.6"/> -<circle class="node" cx="52" cy="123" r="1.6"/> -<circle class="node" cx="64" cy="27" r="1.6"/> -<circle class="node" cx="64" cy="39" r="1.6"/> -<circle class="node" cx="64" cy="51" r="1.6"/> -<circle class="node" cx="64" cy="63" r="1.6"/> -<circle class="node" cx="64" cy="75" r="1.6"/> -<circle class="node" cx="64" cy="87" r="1.6"/> -<circle class="node" cx="64" cy="99" r="1.6"/> -<circle class="node" cx="64" cy="111" r="1.6"/> -<circle class="node" cx="64" cy="123" r="1.6"/> -<circle class="node" cx="76" cy="27" r="1.6"/> -<circle class="node" cx="76" cy="39" r="1.6"/> -<circle class="node" cx="76" cy="51" r="1.6"/> -<circle class="node" cx="76" cy="63" r="1.6"/> -<circle class="node" cx="76" cy="75" r="1.6"/> -<circle class="node" cx="76" cy="87" r="1.6"/> -<circle class="node" cx="76" cy="99" r="1.6"/> -<circle class="node" cx="76" cy="111" r="1.6"/> -<circle class="node" cx="76" cy="123" r="1.6"/> -<circle class="node" cx="88" cy="27" r="1.6"/> -<circle class="node" cx="88" cy="39" r="1.6"/> -<circle class="node" cx="88" cy="51" r="1.6"/> -<circle class="node" cx="88" cy="63" r="1.6"/> -<circle class="node" cx="88" cy="75" r="1.6"/> -<circle class="node" cx="88" cy="87" r="1.6"/> -<circle class="node" cx="88" cy="99" r="1.6"/> -<circle class="node" cx="88" cy="111" r="1.6"/> -<circle class="node" cx="88" cy="123" r="1.6"/> -<circle class="node" cx="100" cy="27" r="1.6"/> -<circle class="node" cx="100" cy="39" r="1.6"/> -<circle class="node" cx="100" cy="51" r="1.6"/> -<circle class="node" cx="100" cy="63" r="1.6"/> -<circle class="node" cx="100" cy="75" r="1.6"/> -<circle class="node" cx="100" cy="87" r="1.6"/> -<circle class="node" cx="100" cy="99" r="1.6"/> -<circle class="node" cx="100" cy="111" r="1.6"/> -<circle class="node" cx="100" cy="123" r="1.6"/> -<circle class="node" cx="112" cy="27" r="1.6"/> -<circle class="node" cx="112" cy="39" r="1.6"/> -<circle class="node" cx="112" cy="51" r="1.6"/> -<circle class="node" cx="112" cy="63" r="1.6"/> -<circle class="node" cx="112" cy="75" r="1.6"/> -<circle class="node" cx="112" cy="87" r="1.6"/> -<circle class="node" cx="112" cy="99" r="1.6"/> -<circle class="node" cx="112" cy="111" r="1.6"/> -<circle class="node" cx="112" cy="123" r="1.6"/> -<circle class="node" cx="124" cy="27" r="1.6"/> -<circle class="node" cx="124" cy="39" r="1.6"/> -<circle class="node" cx="124" cy="51" r="1.6"/> -<circle class="node" cx="124" cy="63" r="1.6"/> -<circle class="node" cx="124" cy="75" r="1.6"/> -<circle class="node" cx="124" cy="87" r="1.6"/> -<circle class="node" cx="124" cy="99" r="1.6"/> -<circle class="node" cx="124" cy="111" r="1.6"/> -<circle class="node" cx="124" cy="123" r="1.6"/> -<circle class="node" cx="136" cy="27" r="1.6"/> -<circle class="node" cx="136" cy="39" r="1.6"/> -<circle class="node" cx="136" cy="51" r="1.6"/> -<circle class="node" cx="136" cy="63" r="1.6"/> -<circle class="node" cx="136" cy="75" r="1.6"/> -<circle class="node" cx="136" cy="87" r="1.6"/> -<circle class="node" cx="136" cy="99" r="1.6"/> -<circle class="node" cx="136" cy="111" r="1.6"/> -<circle class="node" cx="136" cy="123" r="1.6"/> -<circle class="node" cx="148" cy="27" r="1.6"/> -<circle class="node" cx="148" cy="39" r="1.6"/> -<circle class="node" cx="148" cy="51" r="1.6"/> -<circle class="node" cx="148" cy="63" r="1.6"/> -<circle class="node" cx="148" cy="75" r="1.6"/> -<circle class="node" cx="148" cy="87" r="1.6"/> -<circle class="node" cx="148" cy="99" r="1.6"/> -<circle class="node" cx="148" cy="111" r="1.6"/> -<circle class="node" cx="148" cy="123" r="1.6"/> -<circle class="node" cx="160" cy="27" r="1.6"/> -<circle class="node" cx="160" cy="39" r="1.6"/> -<circle class="node" cx="160" cy="51" r="1.6"/> -<circle class="node" cx="160" cy="63" r="1.6"/> -<circle class="node" cx="160" cy="75" r="1.6"/> -<circle class="node" cx="160" cy="87" r="1.6"/> -<circle class="node" cx="160" cy="99" r="1.6"/> -<circle class="node" cx="160" cy="111" r="1.6"/> -<circle class="node" cx="160" cy="123" r="1.6"/> -<ellipse cx="100" cy="75" rx="40" ry="30" fill="url(#spot)"/> -<path class="axis" d="M28,137 L72,137 M65.7,140.0 L72,137 L65.7,134.0"/> -<text class="label" x="76" y="141">x</text> -<path class="axis" d="M28,137 L28,93 M31.0,99.3 L28,93 L25.0,99.3"/> -<text class="label" x="16" y="95">y</text> -</svg> diff --git a/gui/src/solprop_gui/help/figures/gnlse.svg b/gui/src/solprop_gui/help/figures/gnlse.svg deleted file mode 100644 index 006f41576..000000000 --- a/gui/src/solprop_gui/help/figures/gnlse.svg +++ /dev/null @@ -1,64 +0,0 @@ -<?xml version="1.0" encoding="UTF-8"?> -<!-- SPDX-FileCopyrightText: 2026 John C. Travers and contributors --> -<!-- SPDX-License-Identifier: GPL-3.0-or-later --> -<svg xmlns="http://www.w3.org/2000/svg" width="200" height="150" viewBox="0 0 200 150"> -<style> -svg { - --ink: #1b1f24; - --dim: #5b6673; - --gas-fill: #e9f1fb; - --glass-fill: #d5e9dc; - --glass-edge: #2c7a55; - --core-fill: #cfe0f4; - --core-edge: #2f5eb0; - --beam: #b8334f; - --beam-b: #6f45a6; - --beam-c: #a96a15; -} -@media (prefers-color-scheme: dark) { - svg { - --ink: #e7eaef; - --dim: #9aa5b3; - --gas-fill: #18222f; - --glass-fill: #173528; - --glass-edge: #5cb98a; - --core-fill: #1d3150; - --core-edge: #7ba6e8; - --beam: #ee8ca0; - --beam-b: #b99ae6; - --beam-c: #e0a44f; - } -} -.glass { fill: var(--glass-fill); stroke: var(--glass-edge); stroke-width: 2; } -.gas { fill: var(--gas-fill); stroke: var(--glass-edge); stroke-width: 1.2; } -.core { fill: var(--core-fill); stroke: var(--core-edge); stroke-width: 1.5; } -.axis { fill: none; stroke: var(--dim); stroke-width: 1.2; } -.node { fill: var(--dim); stroke: none; } -.ring { fill: none; stroke: var(--dim); stroke-width: 1; stroke-dasharray: 3 3; } -.curve { fill: none; stroke: var(--beam); stroke-width: 2.4; } -.curve-b { fill: none; stroke: var(--beam-b); stroke-width: 2; } -.curve-c { fill: none; stroke: var(--beam-c); stroke-width: 2; } -.label { fill: var(--dim); font-family: sans-serif; font-size: 13px; - font-style: italic; } -</style> -<defs> -<radialGradient id="spot"> - <stop offset="0" stop-color="var(--beam)" stop-opacity="0.95"/> - <stop offset="0.55" stop-color="var(--beam)" stop-opacity="0.45"/> - <stop offset="1" stop-color="var(--beam)" stop-opacity="0"/> -</radialGradient> -<radialGradient id="graded"> - <stop offset="0" stop-color="var(--core-edge)" stop-opacity="0.75"/> - <stop offset="1" stop-color="var(--core-edge)" stop-opacity="0"/> -</radialGradient> -<linearGradient id="band" x1="0" y1="0" x2="0" y2="1"> - <stop offset="0" stop-color="var(--beam)" stop-opacity="0"/> - <stop offset="0.5" stop-color="var(--beam)" stop-opacity="0.9"/> - <stop offset="1" stop-color="var(--beam)" stop-opacity="0"/> -</linearGradient> -</defs> -<rect class="glass" x="10" y="86" width="180" height="40" rx="4"/> -<rect class="core" x="10" y="100" width="180" height="12"/> -<path class="curve" d="M20,78.0 L22,78.0 L24,78.0 L26,78.0 L28,78.0 L30,78.0 L32,77.9 L34,77.9 L36,77.9 L38,77.9 L40,77.9 L42,77.8 L44,77.8 L46,77.7 L48,77.7 L50,77.6 L52,77.5 L54,77.4 L56,77.2 L58,77.0 L60,76.8 L62,76.5 L64,76.1 L66,75.6 L68,75.0 L70,74.3 L72,73.4 L74,72.2 L76,70.8 L78,69.0 L80,66.9 L82,64.2 L84,60.9 L86,57.0 L88,52.4 L90,47.1 L92,41.4 L94,35.7 L96,30.7 L98,27.3 L100,26.0 L102,27.3 L104,30.7 L106,35.7 L108,41.4 L110,47.1 L112,52.4 L114,57.0 L116,60.9 L118,64.2 L120,66.9 L122,69.0 L124,70.8 L126,72.2 L128,73.4 L130,74.3 L132,75.0 L134,75.6 L136,76.1 L138,76.5 L140,76.8 L142,77.0 L144,77.2 L146,77.4 L148,77.5 L150,77.6 L152,77.7 L154,77.7 L156,77.8 L158,77.8 L160,77.9 L162,77.9 L164,77.9 L166,77.9 L168,77.9 L170,78.0 L172,78.0 L174,78.0 L176,78.0 L178,78.0 L180,78.0"/> -<text class="label" x="150" y="40">β(ω), γ</text> -</svg> diff --git a/gui/src/solprop_gui/help/figures/grin.svg b/gui/src/solprop_gui/help/figures/grin.svg deleted file mode 100644 index 3c6c91ef7..000000000 --- a/gui/src/solprop_gui/help/figures/grin.svg +++ /dev/null @@ -1,63 +0,0 @@ -<?xml version="1.0" encoding="UTF-8"?> -<!-- SPDX-FileCopyrightText: 2026 John C. Travers and contributors --> -<!-- SPDX-License-Identifier: GPL-3.0-or-later --> -<svg xmlns="http://www.w3.org/2000/svg" width="200" height="150" viewBox="0 0 200 150"> -<style> -svg { - --ink: #1b1f24; - --dim: #5b6673; - --gas-fill: #e9f1fb; - --glass-fill: #d5e9dc; - --glass-edge: #2c7a55; - --core-fill: #cfe0f4; - --core-edge: #2f5eb0; - --beam: #b8334f; - --beam-b: #6f45a6; - --beam-c: #a96a15; -} -@media (prefers-color-scheme: dark) { - svg { - --ink: #e7eaef; - --dim: #9aa5b3; - --gas-fill: #18222f; - --glass-fill: #173528; - --glass-edge: #5cb98a; - --core-fill: #1d3150; - --core-edge: #7ba6e8; - --beam: #ee8ca0; - --beam-b: #b99ae6; - --beam-c: #e0a44f; - } -} -.glass { fill: var(--glass-fill); stroke: var(--glass-edge); stroke-width: 2; } -.gas { fill: var(--gas-fill); stroke: var(--glass-edge); stroke-width: 1.2; } -.core { fill: var(--core-fill); stroke: var(--core-edge); stroke-width: 1.5; } -.axis { fill: none; stroke: var(--dim); stroke-width: 1.2; } -.node { fill: var(--dim); stroke: none; } -.ring { fill: none; stroke: var(--dim); stroke-width: 1; stroke-dasharray: 3 3; } -.curve { fill: none; stroke: var(--beam); stroke-width: 2.4; } -.curve-b { fill: none; stroke: var(--beam-b); stroke-width: 2; } -.curve-c { fill: none; stroke: var(--beam-c); stroke-width: 2; } -.label { fill: var(--dim); font-family: sans-serif; font-size: 13px; - font-style: italic; } -</style> -<defs> -<radialGradient id="spot"> - <stop offset="0" stop-color="var(--beam)" stop-opacity="0.95"/> - <stop offset="0.55" stop-color="var(--beam)" stop-opacity="0.45"/> - <stop offset="1" stop-color="var(--beam)" stop-opacity="0"/> -</radialGradient> -<radialGradient id="graded"> - <stop offset="0" stop-color="var(--core-edge)" stop-opacity="0.75"/> - <stop offset="1" stop-color="var(--core-edge)" stop-opacity="0"/> -</radialGradient> -<linearGradient id="band" x1="0" y1="0" x2="0" y2="1"> - <stop offset="0" stop-color="var(--beam)" stop-opacity="0"/> - <stop offset="0.5" stop-color="var(--beam)" stop-opacity="0.9"/> - <stop offset="1" stop-color="var(--beam)" stop-opacity="0"/> -</linearGradient> -</defs> -<circle class="glass" cx="100" cy="75" r="64"/> -<circle cx="100" cy="75" r="34" fill="url(#graded)"/> -<ellipse cx="100" cy="75" rx="20" ry="20" fill="url(#spot)"/> -</svg> diff --git a/gui/src/solprop_gui/help/figures/line.svg b/gui/src/solprop_gui/help/figures/line.svg deleted file mode 100644 index fc816dac1..000000000 --- a/gui/src/solprop_gui/help/figures/line.svg +++ /dev/null @@ -1,84 +0,0 @@ -<?xml version="1.0" encoding="UTF-8"?> -<!-- SPDX-FileCopyrightText: 2026 John C. Travers and contributors --> -<!-- SPDX-License-Identifier: GPL-3.0-or-later --> -<svg xmlns="http://www.w3.org/2000/svg" width="200" height="150" viewBox="0 0 200 150"> -<style> -svg { - --ink: #1b1f24; - --dim: #5b6673; - --gas-fill: #e9f1fb; - --glass-fill: #d5e9dc; - --glass-edge: #2c7a55; - --core-fill: #cfe0f4; - --core-edge: #2f5eb0; - --beam: #b8334f; - --beam-b: #6f45a6; - --beam-c: #a96a15; -} -@media (prefers-color-scheme: dark) { - svg { - --ink: #e7eaef; - --dim: #9aa5b3; - --gas-fill: #18222f; - --glass-fill: #173528; - --glass-edge: #5cb98a; - --core-fill: #1d3150; - --core-edge: #7ba6e8; - --beam: #ee8ca0; - --beam-b: #b99ae6; - --beam-c: #e0a44f; - } -} -.glass { fill: var(--glass-fill); stroke: var(--glass-edge); stroke-width: 2; } -.gas { fill: var(--gas-fill); stroke: var(--glass-edge); stroke-width: 1.2; } -.core { fill: var(--core-fill); stroke: var(--core-edge); stroke-width: 1.5; } -.axis { fill: none; stroke: var(--dim); stroke-width: 1.2; } -.node { fill: var(--dim); stroke: none; } -.ring { fill: none; stroke: var(--dim); stroke-width: 1; stroke-dasharray: 3 3; } -.curve { fill: none; stroke: var(--beam); stroke-width: 2.4; } -.curve-b { fill: none; stroke: var(--beam-b); stroke-width: 2; } -.curve-c { fill: none; stroke: var(--beam-c); stroke-width: 2; } -.label { fill: var(--dim); font-family: sans-serif; font-size: 13px; - font-style: italic; } -</style> -<defs> -<radialGradient id="spot"> - <stop offset="0" stop-color="var(--beam)" stop-opacity="0.95"/> - <stop offset="0.55" stop-color="var(--beam)" stop-opacity="0.45"/> - <stop offset="1" stop-color="var(--beam)" stop-opacity="0"/> -</radialGradient> -<radialGradient id="graded"> - <stop offset="0" stop-color="var(--core-edge)" stop-opacity="0.75"/> - <stop offset="1" stop-color="var(--core-edge)" stop-opacity="0"/> -</radialGradient> -<linearGradient id="band" x1="0" y1="0" x2="0" y2="1"> - <stop offset="0" stop-color="var(--beam)" stop-opacity="0"/> - <stop offset="0.5" stop-color="var(--beam)" stop-opacity="0.9"/> - <stop offset="1" stop-color="var(--beam)" stop-opacity="0"/> -</linearGradient> -</defs> -<circle class="node" cx="30" cy="105" r="1.8"/> -<circle class="node" cx="37" cy="105" r="1.8"/> -<circle class="node" cx="44" cy="105" r="1.8"/> -<circle class="node" cx="51" cy="105" r="1.8"/> -<circle class="node" cx="58" cy="105" r="1.8"/> -<circle class="node" cx="65" cy="105" r="1.8"/> -<circle class="node" cx="72" cy="105" r="1.8"/> -<circle class="node" cx="79" cy="105" r="1.8"/> -<circle class="node" cx="86" cy="105" r="1.8"/> -<circle class="node" cx="93" cy="105" r="1.8"/> -<circle class="node" cx="100" cy="105" r="1.8"/> -<circle class="node" cx="107" cy="105" r="1.8"/> -<circle class="node" cx="114" cy="105" r="1.8"/> -<circle class="node" cx="121" cy="105" r="1.8"/> -<circle class="node" cx="128" cy="105" r="1.8"/> -<circle class="node" cx="135" cy="105" r="1.8"/> -<circle class="node" cx="142" cy="105" r="1.8"/> -<circle class="node" cx="149" cy="105" r="1.8"/> -<circle class="node" cx="156" cy="105" r="1.8"/> -<circle class="node" cx="163" cy="105" r="1.8"/> -<circle class="node" cx="170" cy="105" r="1.8"/> -<path class="curve" d="M30,97.1 L32,96.9 L34,96.7 L36,96.6 L38,96.3 L40,96.1 L42,95.8 L44,95.4 L46,95.0 L48,94.6 L50,94.1 L52,93.5 L54,92.8 L56,92.0 L58,91.0 L60,90.0 L62,88.8 L64,87.4 L66,85.8 L68,83.9 L70,81.8 L72,79.4 L74,76.7 L76,73.6 L78,70.1 L80,66.3 L82,62.0 L84,57.5 L86,52.6 L88,47.7 L90,42.7 L92,38.1 L94,34.0 L96,30.8 L98,28.7 L100,28.0 L102,28.7 L104,30.8 L106,34.0 L108,38.1 L110,42.7 L112,47.7 L114,52.6 L116,57.5 L118,62.0 L120,66.3 L122,70.1 L124,73.6 L126,76.7 L128,79.4 L130,81.8 L132,83.9 L134,85.8 L136,87.4 L138,88.8 L140,90.0 L142,91.0 L144,92.0 L146,92.8 L148,93.5 L150,94.1 L152,94.6 L154,95.0 L156,95.4 L158,95.8 L160,96.1 L162,96.3 L164,96.6 L166,96.7 L168,96.9 L170,97.1"/> -<path class="axis" d="M30,125 L174,125 M167.7,128.0 L174,125 L167.7,122.0"/> -<text class="label" x="178" y="129">x</text> -</svg> diff --git a/gui/src/solprop_gui/help/figures/radial.svg b/gui/src/solprop_gui/help/figures/radial.svg deleted file mode 100644 index e68d8cf60..000000000 --- a/gui/src/solprop_gui/help/figures/radial.svg +++ /dev/null @@ -1,68 +0,0 @@ -<?xml version="1.0" encoding="UTF-8"?> -<!-- SPDX-FileCopyrightText: 2026 John C. Travers and contributors --> -<!-- SPDX-License-Identifier: GPL-3.0-or-later --> -<svg xmlns="http://www.w3.org/2000/svg" width="200" height="150" viewBox="0 0 200 150"> -<style> -svg { - --ink: #1b1f24; - --dim: #5b6673; - --gas-fill: #e9f1fb; - --glass-fill: #d5e9dc; - --glass-edge: #2c7a55; - --core-fill: #cfe0f4; - --core-edge: #2f5eb0; - --beam: #b8334f; - --beam-b: #6f45a6; - --beam-c: #a96a15; -} -@media (prefers-color-scheme: dark) { - svg { - --ink: #e7eaef; - --dim: #9aa5b3; - --gas-fill: #18222f; - --glass-fill: #173528; - --glass-edge: #5cb98a; - --core-fill: #1d3150; - --core-edge: #7ba6e8; - --beam: #ee8ca0; - --beam-b: #b99ae6; - --beam-c: #e0a44f; - } -} -.glass { fill: var(--glass-fill); stroke: var(--glass-edge); stroke-width: 2; } -.gas { fill: var(--gas-fill); stroke: var(--glass-edge); stroke-width: 1.2; } -.core { fill: var(--core-fill); stroke: var(--core-edge); stroke-width: 1.5; } -.axis { fill: none; stroke: var(--dim); stroke-width: 1.2; } -.node { fill: var(--dim); stroke: none; } -.ring { fill: none; stroke: var(--dim); stroke-width: 1; stroke-dasharray: 3 3; } -.curve { fill: none; stroke: var(--beam); stroke-width: 2.4; } -.curve-b { fill: none; stroke: var(--beam-b); stroke-width: 2; } -.curve-c { fill: none; stroke: var(--beam-c); stroke-width: 2; } -.label { fill: var(--dim); font-family: sans-serif; font-size: 13px; - font-style: italic; } -</style> -<defs> -<radialGradient id="spot"> - <stop offset="0" stop-color="var(--beam)" stop-opacity="0.95"/> - <stop offset="0.55" stop-color="var(--beam)" stop-opacity="0.45"/> - <stop offset="1" stop-color="var(--beam)" stop-opacity="0"/> -</radialGradient> -<radialGradient id="graded"> - <stop offset="0" stop-color="var(--core-edge)" stop-opacity="0.75"/> - <stop offset="1" stop-color="var(--core-edge)" stop-opacity="0"/> -</radialGradient> -<linearGradient id="band" x1="0" y1="0" x2="0" y2="1"> - <stop offset="0" stop-color="var(--beam)" stop-opacity="0"/> - <stop offset="0.5" stop-color="var(--beam)" stop-opacity="0.9"/> - <stop offset="1" stop-color="var(--beam)" stop-opacity="0"/> -</linearGradient> -</defs> -<circle class="ring" cx="100" cy="75" r="14"/> -<circle class="ring" cx="100" cy="75" r="28"/> -<circle class="ring" cx="100" cy="75" r="42"/> -<circle class="ring" cx="100" cy="75" r="56"/> -<circle class="ring" cx="100" cy="75" r="68"/> -<ellipse cx="100" cy="75" rx="32" ry="32" fill="url(#spot)"/> -<path class="axis" d="M100,75 L166,51 M161.1,56.0 L166,51 L159.0,50.3"/> -<text class="label" x="168" y="49">r</text> -</svg> diff --git a/gui/src/solprop_gui/help/figures/rectangular.svg b/gui/src/solprop_gui/help/figures/rectangular.svg deleted file mode 100644 index 8fb10ce70..000000000 --- a/gui/src/solprop_gui/help/figures/rectangular.svg +++ /dev/null @@ -1,63 +0,0 @@ -<?xml version="1.0" encoding="UTF-8"?> -<!-- SPDX-FileCopyrightText: 2026 John C. Travers and contributors --> -<!-- SPDX-License-Identifier: GPL-3.0-or-later --> -<svg xmlns="http://www.w3.org/2000/svg" width="200" height="150" viewBox="0 0 200 150"> -<style> -svg { - --ink: #1b1f24; - --dim: #5b6673; - --gas-fill: #e9f1fb; - --glass-fill: #d5e9dc; - --glass-edge: #2c7a55; - --core-fill: #cfe0f4; - --core-edge: #2f5eb0; - --beam: #b8334f; - --beam-b: #6f45a6; - --beam-c: #a96a15; -} -@media (prefers-color-scheme: dark) { - svg { - --ink: #e7eaef; - --dim: #9aa5b3; - --gas-fill: #18222f; - --glass-fill: #173528; - --glass-edge: #5cb98a; - --core-fill: #1d3150; - --core-edge: #7ba6e8; - --beam: #ee8ca0; - --beam-b: #b99ae6; - --beam-c: #e0a44f; - } -} -.glass { fill: var(--glass-fill); stroke: var(--glass-edge); stroke-width: 2; } -.gas { fill: var(--gas-fill); stroke: var(--glass-edge); stroke-width: 1.2; } -.core { fill: var(--core-fill); stroke: var(--core-edge); stroke-width: 1.5; } -.axis { fill: none; stroke: var(--dim); stroke-width: 1.2; } -.node { fill: var(--dim); stroke: none; } -.ring { fill: none; stroke: var(--dim); stroke-width: 1; stroke-dasharray: 3 3; } -.curve { fill: none; stroke: var(--beam); stroke-width: 2.4; } -.curve-b { fill: none; stroke: var(--beam-b); stroke-width: 2; } -.curve-c { fill: none; stroke: var(--beam-c); stroke-width: 2; } -.label { fill: var(--dim); font-family: sans-serif; font-size: 13px; - font-style: italic; } -</style> -<defs> -<radialGradient id="spot"> - <stop offset="0" stop-color="var(--beam)" stop-opacity="0.95"/> - <stop offset="0.55" stop-color="var(--beam)" stop-opacity="0.45"/> - <stop offset="1" stop-color="var(--beam)" stop-opacity="0"/> -</radialGradient> -<radialGradient id="graded"> - <stop offset="0" stop-color="var(--core-edge)" stop-opacity="0.75"/> - <stop offset="1" stop-color="var(--core-edge)" stop-opacity="0"/> -</radialGradient> -<linearGradient id="band" x1="0" y1="0" x2="0" y2="1"> - <stop offset="0" stop-color="var(--beam)" stop-opacity="0"/> - <stop offset="0.5" stop-color="var(--beam)" stop-opacity="0.9"/> - <stop offset="1" stop-color="var(--beam)" stop-opacity="0"/> -</linearGradient> -</defs> -<rect class="glass" x="22" y="27" width="156" height="96" rx="3"/> -<rect class="gas" x="36" y="41" width="128" height="68"/> -<ellipse cx="100" cy="75" rx="50" ry="26" fill="url(#spot)"/> -</svg> diff --git a/gui/src/solprop_gui/help/figures/slab.svg b/gui/src/solprop_gui/help/figures/slab.svg deleted file mode 100644 index 4d0156e68..000000000 --- a/gui/src/solprop_gui/help/figures/slab.svg +++ /dev/null @@ -1,68 +0,0 @@ -<?xml version="1.0" encoding="UTF-8"?> -<!-- SPDX-FileCopyrightText: 2026 John C. Travers and contributors --> -<!-- SPDX-License-Identifier: GPL-3.0-or-later --> -<svg xmlns="http://www.w3.org/2000/svg" width="200" height="150" viewBox="0 0 200 150"> -<style> -svg { - --ink: #1b1f24; - --dim: #5b6673; - --gas-fill: #e9f1fb; - --glass-fill: #d5e9dc; - --glass-edge: #2c7a55; - --core-fill: #cfe0f4; - --core-edge: #2f5eb0; - --beam: #b8334f; - --beam-b: #6f45a6; - --beam-c: #a96a15; -} -@media (prefers-color-scheme: dark) { - svg { - --ink: #e7eaef; - --dim: #9aa5b3; - --gas-fill: #18222f; - --glass-fill: #173528; - --glass-edge: #5cb98a; - --core-fill: #1d3150; - --core-edge: #7ba6e8; - --beam: #ee8ca0; - --beam-b: #b99ae6; - --beam-c: #e0a44f; - } -} -.glass { fill: var(--glass-fill); stroke: var(--glass-edge); stroke-width: 2; } -.gas { fill: var(--gas-fill); stroke: var(--glass-edge); stroke-width: 1.2; } -.core { fill: var(--core-fill); stroke: var(--core-edge); stroke-width: 1.5; } -.axis { fill: none; stroke: var(--dim); stroke-width: 1.2; } -.node { fill: var(--dim); stroke: none; } -.ring { fill: none; stroke: var(--dim); stroke-width: 1; stroke-dasharray: 3 3; } -.curve { fill: none; stroke: var(--beam); stroke-width: 2.4; } -.curve-b { fill: none; stroke: var(--beam-b); stroke-width: 2; } -.curve-c { fill: none; stroke: var(--beam-c); stroke-width: 2; } -.label { fill: var(--dim); font-family: sans-serif; font-size: 13px; - font-style: italic; } -</style> -<defs> -<radialGradient id="spot"> - <stop offset="0" stop-color="var(--beam)" stop-opacity="0.95"/> - <stop offset="0.55" stop-color="var(--beam)" stop-opacity="0.45"/> - <stop offset="1" stop-color="var(--beam)" stop-opacity="0"/> -</radialGradient> -<radialGradient id="graded"> - <stop offset="0" stop-color="var(--core-edge)" stop-opacity="0.75"/> - <stop offset="1" stop-color="var(--core-edge)" stop-opacity="0"/> -</radialGradient> -<linearGradient id="band" x1="0" y1="0" x2="0" y2="1"> - <stop offset="0" stop-color="var(--beam)" stop-opacity="0"/> - <stop offset="0.5" stop-color="var(--beam)" stop-opacity="0.9"/> - <stop offset="1" stop-color="var(--beam)" stop-opacity="0"/> -</linearGradient> -</defs> -<rect class="glass" x="8" y="22" width="166" height="22"/> -<rect class="glass" x="8" y="106" width="166" height="22"/> -<rect class="gas" x="8" y="44" width="166" height="62" stroke="none"/> -<rect x="8" y="50" width="166" height="50" fill="url(#band)"/> -<path class="axis" d="M36,140 L150,140 M143.7,143.0 L150,140 L143.7,137.0"/> -<text class="label" x="156" y="144">y</text> -<path class="axis" d="M186,100 L186,50 M189.0,56.3 L186,50 L183.0,56.3"/> -<text class="label" x="182" y="44">x</text> -</svg> diff --git a/gui/src/solprop_gui/help/figures/step-index.svg b/gui/src/solprop_gui/help/figures/step-index.svg deleted file mode 100644 index fd138858b..000000000 --- a/gui/src/solprop_gui/help/figures/step-index.svg +++ /dev/null @@ -1,63 +0,0 @@ -<?xml version="1.0" encoding="UTF-8"?> -<!-- SPDX-FileCopyrightText: 2026 John C. Travers and contributors --> -<!-- SPDX-License-Identifier: GPL-3.0-or-later --> -<svg xmlns="http://www.w3.org/2000/svg" width="200" height="150" viewBox="0 0 200 150"> -<style> -svg { - --ink: #1b1f24; - --dim: #5b6673; - --gas-fill: #e9f1fb; - --glass-fill: #d5e9dc; - --glass-edge: #2c7a55; - --core-fill: #cfe0f4; - --core-edge: #2f5eb0; - --beam: #b8334f; - --beam-b: #6f45a6; - --beam-c: #a96a15; -} -@media (prefers-color-scheme: dark) { - svg { - --ink: #e7eaef; - --dim: #9aa5b3; - --gas-fill: #18222f; - --glass-fill: #173528; - --glass-edge: #5cb98a; - --core-fill: #1d3150; - --core-edge: #7ba6e8; - --beam: #ee8ca0; - --beam-b: #b99ae6; - --beam-c: #e0a44f; - } -} -.glass { fill: var(--glass-fill); stroke: var(--glass-edge); stroke-width: 2; } -.gas { fill: var(--gas-fill); stroke: var(--glass-edge); stroke-width: 1.2; } -.core { fill: var(--core-fill); stroke: var(--core-edge); stroke-width: 1.5; } -.axis { fill: none; stroke: var(--dim); stroke-width: 1.2; } -.node { fill: var(--dim); stroke: none; } -.ring { fill: none; stroke: var(--dim); stroke-width: 1; stroke-dasharray: 3 3; } -.curve { fill: none; stroke: var(--beam); stroke-width: 2.4; } -.curve-b { fill: none; stroke: var(--beam-b); stroke-width: 2; } -.curve-c { fill: none; stroke: var(--beam-c); stroke-width: 2; } -.label { fill: var(--dim); font-family: sans-serif; font-size: 13px; - font-style: italic; } -</style> -<defs> -<radialGradient id="spot"> - <stop offset="0" stop-color="var(--beam)" stop-opacity="0.95"/> - <stop offset="0.55" stop-color="var(--beam)" stop-opacity="0.45"/> - <stop offset="1" stop-color="var(--beam)" stop-opacity="0"/> -</radialGradient> -<radialGradient id="graded"> - <stop offset="0" stop-color="var(--core-edge)" stop-opacity="0.75"/> - <stop offset="1" stop-color="var(--core-edge)" stop-opacity="0"/> -</radialGradient> -<linearGradient id="band" x1="0" y1="0" x2="0" y2="1"> - <stop offset="0" stop-color="var(--beam)" stop-opacity="0"/> - <stop offset="0.5" stop-color="var(--beam)" stop-opacity="0.9"/> - <stop offset="1" stop-color="var(--beam)" stop-opacity="0"/> -</linearGradient> -</defs> -<circle class="glass" cx="100" cy="75" r="64"/> -<circle class="core" cx="100" cy="75" r="18"/> -<ellipse cx="100" cy="75" rx="20" ry="20" fill="url(#spot)"/> -</svg> diff --git a/gui/src/solprop_gui/help/guide.py b/gui/src/solprop_gui/help/guide.py index d783f4aa2..414ce1c58 100644 --- a/gui/src/solprop_gui/help/guide.py +++ b/gui/src/solprop_gui/help/guide.py @@ -5,8 +5,8 @@ """Where solprop's manual explains a keyword (design 12.4). solprop's metadata gives each keyword an anchor: a page under ``docs/`` with an -optional section. The front end opens it in the online manual of the installed -version's series; the bundled manual comes with the installers (milestone M8). +optional section. The front end opens it in the online manual of the newest release +(:data:`MANUAL`). """ from typing import Final diff --git a/gui/src/solprop_gui/model/compressor.py b/gui/src/solprop_gui/model/compressor.py index 60ca44990..184692d9f 100644 --- a/gui/src/solprop_gui/model/compressor.py +++ b/gui/src/solprop_gui/model/compressor.py @@ -4,7 +4,7 @@ """A compressor: a chain of linear optical elements after the run, some searched. -The Post-process step builds a :class:`Stage` list: a Taylor spectral phase, a +The Compress page builds a :class:`Stage` list: a Taylor spectral phase, a material (a glass, or a gas such as an air path), chirped mirrors (optionally with wedges), a prism pair or a grating pair, each of :mod:`solprop.optics`. A stage is either **fixed**, its values as given, or **auto**: solprop's compressor of that kind diff --git a/gui/src/solprop_gui/model/plot_options.py b/gui/src/solprop_gui/model/plot_options.py index 236f11960..562ad144d 100644 --- a/gui/src/solprop_gui/model/plot_options.py +++ b/gui/src/solprop_gui/model/plot_options.py @@ -2,33 +2,22 @@ # # SPDX-License-Identifier: GPL-3.0-or-later -"""The plot options shared by the live run, the Overview and the plane views. +"""The plot options shared by the live run, the Overview and the Analyse pages. -One :class:`PlotOptions` holds what the plot options panel sets: the spectral axis -(wavelength or frequency), typed limits for the spectral and time axes, the spectral -scale and its floor, and a bandpass for the time-domain views. Values are kept in SI -(m, Hz, s); the panel shows them in nm, THz and fs (:data:`UNITS`). +One :class:`PlotOptions` holds the spectral axis (wavelength or frequency), limits for +the spectral and time axes, the spectral scale and its floor, a bandpass for the +time-domain views and the spectrogram's gate. Values are kept in SI (m, Hz, s); the +views show them in nm, THz and fs (:data:`UNITS`). The axis and the bandpass change what solprop computes (the spectral density on the -axis, the power within the band), so they travel to the kernel and the run's worker -(:meth:`PlotOptions.request`); the limits, scale and floor only change how a view -draws what it has. +axis, the power within the band), so they travel to the kernel; the limits, scale and +floor only change how a view draws what it has. """ -from collections.abc import Mapping from dataclasses import dataclass from typing import Final, Literal -__all__ = [ - "AXES", - "SCALES", - "UNITS", - "PlotOptions", - "from_display", - "from_mapping", - "parse_limit", - "to_display", -] +__all__ = ["AXES", "UNITS", "PlotOptions", "parse_limit", "to_display"] Axis = Literal["wavelength", "f"] Scale = Literal["dB", "linear"] @@ -36,9 +25,6 @@ AXES: Final[dict[str, str]] = {"wavelength": "Wavelength", "f": "Frequency"} """The spectral axes, by solprop's name, with their labels.""" -SCALES: Final = ("dB", "linear") -"""The spectral scales.""" - UNITS: Final[dict[str, tuple[str, float]]] = { "wavelength": ("nm", 1e-9), "f": ("THz", 1e12), @@ -70,29 +56,6 @@ def to_display(axis: str, value: float) -> float: return value / UNITS[axis][1] -def from_display(axis: str, value: float) -> float: - """Return a value in its axis's display unit in SI. - - Parameters - ---------- - axis : str - ``"wavelength"``, ``"f"`` or ``"time"``. - value : float - The value in nm, THz or fs. - - Returns - ------- - float - It in m, Hz or s. - - Examples - -------- - >>> from_display("f", 375.0) - 375000000000000.0 - """ - return value * UNITS[axis][1] - - def parse_limit(text: str) -> float | None: """Read a typed limit: a number, or nothing for automatic. @@ -127,7 +90,7 @@ def parse_limit(text: str) -> float | None: @dataclass(frozen=True) class PlotOptions: - """What the plot options panel sets. + """What the views draw with, and what they ask solprop for. Attributes ---------- @@ -153,8 +116,8 @@ class PlotOptions: Examples -------- - >>> PlotOptions().request() - {'axis': 'wavelength', 'bandpass': None} + >>> PlotOptions().label() + 'Wavelength (nm)' """ axis: Axis = "wavelength" @@ -166,61 +129,6 @@ class PlotOptions: gate_fwhm: float | None = None positions: int = 256 - def spectrogram(self) -> tuple[object, ...]: - """Return what a spectrogram is computed with. - - Returns - ------- - tuple - The axis, band, time limits, gate and positions: the spectrogram is - asked for again when they change. - - Examples - -------- - >>> PlotOptions().spectrogram() == PlotOptions(floor=-20).spectrogram() - True - """ - return ( - self.axis, - self.bandpass, - self.time_limits, - self.gate_fwhm, - self.positions, - ) - - def request(self) -> dict[str, object]: - """Return what solprop is asked to compute differently. - - Returns - ------- - dict - ``axis`` and ``bandpass``, as the kernel's handlers and the run's - display take them. - """ - return {"axis": self.axis, "bandpass": self.bandpass} - - def same_request(self, other: PlotOptions) -> bool: - """Return whether another set of options asks solprop for the same data. - - Parameters - ---------- - other : PlotOptions - The other options. - - Returns - ------- - bool - True when only the drawing differs. - - Examples - -------- - >>> PlotOptions().same_request(PlotOptions(scale="linear")) - True - >>> PlotOptions().same_request(PlotOptions(axis="f")) - False - """ - return self.request() == other.request() - def shown_limits(self, which: str) -> Limits: """Return an axis's limits in its display unit, ascending. @@ -276,68 +184,3 @@ def describe(self) -> str: return "" low, high = (to_display("wavelength", v) for v in self.bandpass) return f"time domain within {low:.0f}-{high:.0f} nm" - - -def from_mapping(values: Mapping[str, object]) -> PlotOptions: - """Return options saved as a mapping, defaults where a value is missing or bad. - - Parameters - ---------- - values : Mapping - What :func:`dataclasses.asdict` gave, as settings keep it. - - Returns - ------- - PlotOptions - The options. - - Examples - -------- - >>> options = from_mapping({"axis": "f", "floor": "-40", "scale": "nonsense"}) - >>> options.axis, options.floor, options.scale - ('f', -40.0, 'dB') - """ - axis = values.get("axis") - scale = values.get("scale") - - def limits(name: str) -> Limits: - """Return a saved pair of limits; automatic where it is not a pair. - - Parameters - ---------- - name : str - The field. - - Returns - ------- - tuple - The limits. - """ - pair = values.get(name) - if not isinstance(pair, list | tuple) or len(pair) != 2: - return (None, None) - low, high = (None if v is None else float(v) for v in pair) # pyright: ignore[reportArgumentType] - return low, high - - band = values.get("bandpass") - bandpass = None - if isinstance(band, list | tuple) and len(band) == 2: - bandpass = (float(band[0]), float(band[1])) # pyright: ignore[reportArgumentType] - try: - floor = float(values.get("floor", -60.0)) # pyright: ignore[reportArgumentType] - except TypeError, ValueError: - floor = -60.0 - gate = values.get("gate_fwhm") - gate_fwhm = float(gate) if isinstance(gate, int | float) and gate > 0 else None - count = values.get("positions") - positions = int(count) if isinstance(count, int) and count > 0 else 256 - return PlotOptions( - axis=axis if axis in AXES else "wavelength", # pyright: ignore[reportArgumentType] - spectral_limits=limits("spectral_limits"), - time_limits=limits("time_limits"), - scale=scale if scale in SCALES else "dB", # pyright: ignore[reportArgumentType] - floor=floor, - bandpass=bandpass, - gate_fwhm=gate_fwhm, - positions=positions, - ) diff --git a/gui/src/solprop_gui/model/stats_layout.py b/gui/src/solprop_gui/model/stats_layout.py deleted file mode 100644 index 8eb5e402f..000000000 --- a/gui/src/solprop_gui/model/stats_layout.py +++ /dev/null @@ -1,115 +0,0 @@ -# SPDX-FileCopyrightText: 2026 John C. Travers and contributors -# -# SPDX-License-Identifier: GPL-3.0-or-later - -"""What the Statistics view's four panels show. - -The view is a 2 by 2 grid; each panel draws one quantity against z on its left axis -and, optionally, a second on its right. A quantity is a statistic the run recorded -(by its name in ``stats/``) or the run's step size (:data:`STEP`). A layout is kept -across files: a choice the next file also recorded stays, the rest are filled from -:func:`default_layout`. -""" - -from collections.abc import Sequence -from typing import Final - -__all__ = ["PANELS", "STEP", "Layout", "Panel", "default_layout", "kept_layout"] - -STEP: Final = "step size" -"""The quantity that is the run's step size, accepted and rejected, against z.""" - -PANELS: Final = 4 -"""The grid's panels.""" - -PREFERRED: Final = ("energy", "peak_power", "fwhm_t", "peak_intensity") -"""The statistics a new layout shows first, where the run recorded them.""" - -Panel = tuple[str | None, str | None] -"""A panel's left and right quantities; ``None`` for none.""" - -Layout = tuple[Panel, ...] -"""The four panels, row by row.""" - - -def default_layout(names: Sequence[str]) -> Layout: - """Return a first layout for a run's statistics: one per panel, none on the right. - - Parameters - ---------- - names : Sequence of str - The statistics the run recorded. - - Returns - ------- - Layout - The preferred statistics first, then the others in the run's order; a - panel left empty when there are fewer than four. The step size is not - shown unless chosen. - - Examples - -------- - >>> default_layout(["zdw", "energy"]) - (('energy', None), ('zdw', None), (None, None), (None, None)) - """ - order = [n for n in PREFERRED if n in names] + [ - n for n in names if n not in PREFERRED - ] - chosen: list[str | None] = [*order[:PANELS]] - chosen += [None] * (PANELS - len(chosen)) - return tuple((name, None) for name in chosen) - - -def kept_layout(layout: Layout, names: Sequence[str]) -> Layout: - """Return a layout for another run: its choices where the run has them. - - Parameters - ---------- - layout : Layout - The layout shown. - names : Sequence of str - The statistics the new run recorded. - - Returns - ------- - Layout - Each choice the run also has (the step size always) kept; a panel whose - left choice is gone moves its right one there, or takes the next statistic - of :func:`default_layout` not shown elsewhere. - - Examples - -------- - >>> kept_layout((("energy", "zdw"), ("peak_power", None), (None, None), - ... ("step size", None)), ["energy", "fwhm_t"]) - (('energy', None), ('fwhm_t', None), (None, None), ('step size', None)) - >>> kept_layout((("zdw", "energy"),) + ((None, None),) * 3, ["energy"])[0] - ('energy', None) - """ - - def known(name: str | None) -> str | None: - """Return a choice the run can show, or ``None``. - - Parameters - ---------- - name : str or None - The choice. - - Returns - ------- - str or None - It, when it is the step size or a statistic of the run. - """ - return name if name == STEP or name in names else None - - kept = [(known(left), known(right)) for left, right in layout] - kept = [(right, None) if left is None else (left, right) for left, right in kept] - shown = {name for panel in kept for name in panel if name is not None} - spare = [ - name - for name, _ in default_layout(names) - if name is not None and name not in shown - ] - for index, (left, right) in enumerate(kept): - if left is None and layout[index][0] is not None and spare: - kept[index] = (spare.pop(0), right) - return tuple(kept) diff --git a/gui/src/solprop_gui/model/workspace.py b/gui/src/solprop_gui/model/workspace.py index a08f6af75..1bf4380b4 100644 --- a/gui/src/solprop_gui/model/workspace.py +++ b/gui/src/solprop_gui/model/workspace.py @@ -6,29 +6,19 @@ Each run has its own folder, ``<date>-<title>``, holding ``run.h5``, ``recipe.toml`` and ``run.log``. The folder is the truth: the list of runs is read from the disk each -time, and copying a run's folder elsewhere loses nothing. +time (:func:`solprop.service.runs.list_runs`), and copying a run's folder elsewhere +loses nothing. This module names new run folders. """ import re -from dataclasses import dataclass from datetime import date, datetime from pathlib import Path, PurePosixPath -__all__ = [ - "DEFAULT_WORKSPACE", - "RunEntry", - "list_runs", - "new_run_folder", - "remote_run_folder", - "slug", -] +__all__ = ["DEFAULT_WORKSPACE", "new_run_folder", "remote_run_folder", "slug"] DEFAULT_WORKSPACE = Path.home() / "solprop-runs" """The workspace when the user has chosen none.""" -_OUTPUT = "run.h5" -_RECIPE = "recipe.toml" - def slug(title: str | None) -> str: """Return a title as a folder name's part. @@ -85,40 +75,6 @@ def new_run_folder(root: Path, title: str | None, today: date | None = None) -> return candidate -@dataclass(frozen=True) -class RunEntry: - """One run folder of the workspace. - - Attributes - ---------- - folder : pathlib.Path - The folder. - output : pathlib.Path or None - Its results file, if it has one. - recipe : pathlib.Path or None - Its recipe, if it has one. - modified : float - When its results file, or else the folder, last changed (seconds since the - epoch). - """ - - folder: Path - output: Path | None - recipe: Path | None - modified: float - - @property - def name(self) -> str: - """Return the run's name, its folder's. - - Returns - ------- - str - The folder's name. - """ - return self.folder.name - - def remote_run_folder( workspace: str, home: str, title: str | None, now: datetime | None = None ) -> str: @@ -155,42 +111,3 @@ def remote_run_folder( base = home.rstrip("/") + base[1:] name = f"{when:%Y-%m-%d}-{slug(title)}-{when:%H%M%S}" return str(PurePosixPath(base) / name) - - -def list_runs(root: Path) -> list[RunEntry]: - """List the run folders of a workspace, newest first. - - Parameters - ---------- - root : pathlib.Path - The workspace. - - Returns - ------- - list of RunEntry - Every folder holding a results file or a recipe; empty when the workspace - does not exist. - """ - if not root.is_dir(): - return [] - entries: list[RunEntry] = [] - for folder in root.iterdir(): - if not folder.is_dir(): - continue - output = folder / _OUTPUT - recipe = folder / _RECIPE - has_output = output.is_file() - has_recipe = recipe.is_file() - if not (has_output or has_recipe): - continue - modified = (output if has_output else folder).stat().st_mtime - entries.append( - RunEntry( - folder, - output if has_output else None, - recipe if has_recipe else None, - modified, - ) - ) - entries.sort(key=lambda entry: (entry.modified, entry.name), reverse=True) - return entries diff --git a/gui/src/solprop_gui/registry/pages.py b/gui/src/solprop_gui/registry/pages.py index a4dd08873..07e2d8af4 100644 --- a/gui/src/solprop_gui/registry/pages.py +++ b/gui/src/solprop_gui/registry/pages.py @@ -2,120 +2,19 @@ # # SPDX-License-Identifier: GPL-3.0-or-later -"""The setup pages, and the presentation the front end adds to solprop's metadata. +"""The labels the front end adds to solprop's metadata. solprop's parameter metadata says each keyword's group, level, unit, display unit, range, summary and manual anchor (SEP 41, S9). The front end adds only what is -presentation (design 12.1): which page a group is shown on, and a label where the -keyword's own name does not read well. A test holds every label to a real keyword. +presentation (design 12.1): a label where the keyword's own name does not read well, +and how the sheets name a gas. A test holds every label to a real keyword. """ -from dataclasses import dataclass from typing import Final -__all__ = [ - "GAS_TITLES", - "GROUP_TITLES", - "LABELS", - "PAGES", - "ROUTE_GROUP_TITLES", - "ROUTE_HELP", - "TYPE_LABELS", - "Page", - "label", - "page_of", - "type_label", -] +__all__ = ["GAS_TITLES", "LABELS", "TYPE_LABELS", "label", "type_label"] -@dataclass(frozen=True) -class Page: - """One step of the setup. - - Attributes - ---------- - key : str - Its identity. - title : str - Its title in the step bar. - groups : tuple of str - The metadata groups it shows. - help : str - What the page sets, in a sentence or two. - short : str - Its name under its icon in the step bar, where the title is long. - """ - - key: str - title: str - groups: tuple[str, ...] - help: str - short: str = "" - - -PAGES: Final = ( - Page( - "geometry", - "Geometry", - ("geometry",), - "The waveguide: its kind, its size and its length, and the modes it carries.", - ), - Page( - "medium", - "Medium", - ("medium",), - "What fills the guide: the gas or mixture, its pressure and temperature, and " - "the guide's loss and cladding.", - ), - Page( - "nonlinear", - "Nonlinearity", - ("nonlinear",), - "The responses the run includes: the Kerr effect, photoionisation and the " - "plasma, and the molecular Raman response.", - ), - Page( - "input", - "Input and grid", - ("input", "grid"), - "The input pulse, its noise, and the time-frequency grid the run is held on.", - "Input", - ), - Page( - "propagate", - "Propagate", - ("output", "numerics"), - "What the run saves, how it steps, and the run itself.", - ), - Page( - "results", - "Results", - (), - "The run's results: the spectrum and the power along the guide, a plane, " - "its spectrogram, and the statistics.", - ), - Page( - "postprocess", - "Post-process", - (), - "Compress the pulse after the run: a chain of linear optics, from a Taylor " - "phase to chirped mirrors, prisms and gratings, some elements searched by " - "solprop.", - ), -) -"""The steps, in order.""" - -GROUP_TITLES: Final = { - "geometry": "Waveguide", - "medium": "Fill", - "nonlinear": "Responses", - "input": "Input pulse", - "grid": "Grid", - "output": "Output", - "numerics": "Numerics", -} -"""The section titles of the metadata groups, where a page shows several.""" - LABELS: Final = { "radius": "Core radius", "length": "Length", @@ -179,27 +78,6 @@ class Page: """Labels for keywords of registered types, where the type changes what a name means (a radial grid's ``radius`` is its extent, a capillary's its core).""" -ROUTE_HELP: Final = { - ("geometry", "free"): ( - "The beam's transverse grid -- its half-widths and nodes -- and how far the " - "beam goes." - ), - ("geometry", "radial"): ( - "The beam's radial grid -- its radius and nodes -- and how far the beam goes." - ), - ("medium", "free"): "What the beam travels through: a gas, a glass or vacuum.", - ("medium", "radial"): "What the beam travels through: a gas, a glass or vacuum.", -} -"""A step's help where a route makes it read differently, by step and route.""" - -ROUTE_GROUP_TITLES: Final = { - ("free", "geometry"): "Beam and grid", - ("radial", "geometry"): "Beam and grid", - ("free", "medium"): "Medium", - ("radial", "medium"): "Medium", -} -"""A section's title where a route makes it read differently, by route and group.""" - def label(name: str) -> str: """Return a keyword's label. @@ -248,27 +126,3 @@ def type_label(type_name: str, name: str) -> str: 'Duration (FWHM)' """ return TYPE_LABELS.get((type_name, name)) or label(name) - - -def page_of(group: str) -> Page | None: - """Return the page a metadata group is shown on. - - Parameters - ---------- - group : str - The group. - - Returns - ------- - Page or None - The page, or ``None`` for a group no page shows. - - Examples - -------- - >>> page_of("grid").key - 'input' - """ - for page in PAGES: - if group in page.groups: - return page - return None diff --git a/gui/src/solprop_gui/registry/routes.py b/gui/src/solprop_gui/registry/routes.py index 40d4048bd..b25a92ec0 100644 --- a/gui/src/solprop_gui/registry/routes.py +++ b/gui/src/solprop_gui/registry/routes.py @@ -2,36 +2,24 @@ # # SPDX-License-Identifier: GPL-3.0-or-later -"""The routes the geometry page offers, as cards (design 6.1). +"""The geometries solprop's routes build, as cards that name them (design 6.1). -A card is presentation: a title, a sentence, the solprop route it builds and the -values that make it that card (the mode-averaged capillary is the capillary route with -``mode_average = true``; a line beam is the free route with a ``LineGrid`` space). A new -setup from a card starts from solprop's example of it, or holds the card's values and -nothing else; what else the route requires, solprop's check says. A card the window -does not offer yet is hidden, its code kept. +A card is presentation: a title, the solprop route it builds and the values that make +a recipe that card's (the mode-averaged capillary is the capillary route with +``mode_average = true``; a line beam is the free route with a ``LineGrid`` space). A +recipe on a route no problem class takes is named by its card (:func:`card_of`). """ -from collections.abc import Mapping, Sequence +from collections.abc import Mapping from dataclasses import dataclass, field from typing import Final -__all__ = [ - "CARDS", - "EXPLORER_SETUP", - "GUIDED", - "IMPLIED", - "RouteCard", - "card", - "card_of", - "group_examples", - "type_of", -] +__all__ = ["CARDS", "IMPLIED", "RouteCard", "card_of", "type_of"] @dataclass(frozen=True) class RouteCard: - """One choice on the geometry page. + """One geometry a route builds. Attributes ---------- @@ -39,21 +27,14 @@ class RouteCard: Its identity. title : str What it is called. - summary : str - One sentence. route : str The solprop route it builds. preset : dict The ``[build]`` values that make a recipe this card's; a value equal to solprop's default (:data:`IMPLIED`) may also be left out of a recipe. - extra : dict - Values a new setup from the card starts with beyond its preset, which do not - make a recipe the card's. - reason : str or None - Why it cannot be chosen yet; ``None`` when it can. example : str or None - The solprop example a new setup from the card starts from - (``Recipe.example``), in place of a blank recipe of the preset. + solprop's example of it (``Recipe.example``), or of the example + :attr:`rewrite` changes into it. marker : tuple of str Keywords whose presence makes a recipe the card's, beside its preset (an antiresonant fibre is a capillary with a ``lattice``). @@ -62,89 +43,24 @@ class RouteCard: with the type names that do (a line beam's ``space`` is a ``LineGrid``); for a list, its first entry's type. rewrite : dict - Changes made to :attr:`example`'s ``[build]`` for a new setup, where solprop - has no example of the card's own: a value replaces the keyword's, ``None`` + Changes that make :attr:`example`'s ``[build]`` the card's, where solprop has + no example of the card's own: a value replaces the keyword's, ``None`` removes it. - group : str - The heading the gallery shows it under. - hidden : bool - Whether the gallery and the examples leave it out. Examples -------- - >>> card("capillary-averaged").enabled - True + >>> RouteCard("gnlse", "Fibre (GNLSE)", "gnlse").preset + {} """ key: str title: str - summary: str route: str preset: dict[str, object] = field(default_factory=dict) - extra: dict[str, object] = field(default_factory=dict) - reason: str | None = None example: str | None = None marker: tuple[str, ...] = () types: dict[str, tuple[str, ...]] = field(default_factory=dict) rewrite: dict[str, object] = field(default_factory=dict) - group: str = "Guided" - hidden: bool = False - - @property - def enabled(self) -> bool: - """Return whether the card can be chosen. - - Returns - ------- - bool - True when it has no reason against it. - """ - return self.reason is None - - def blank(self, title: str | None = None) -> str: - """Return a new recipe for this card, holding its preset values only. - - Parameters - ---------- - title : str or None, optional - The recipe's title. - - Returns - ------- - str - The recipe's TOML text. - """ - lines = ["[recipe]", "format = 1", f'route = "{self.route}"'] - if title is not None: - escaped = title.replace("\\", "\\\\").replace('"', '\\"') - lines.append(f'title = "{escaped}"') - lines.append("") - lines.append("[build]") - for name, value in {**self.preset, **self.extra}.items(): - if name in IMPLIED and IMPLIED[name] == value: - continue # solprop's default: left to solprop - lines.append(f"{name} = {_toml(value)}") - return "\n".join(lines) + "\n" - - -def _toml(value: object) -> str: - """Write a preset value as TOML. - - Parameters - ---------- - value : object - A boolean, an integer or a string. - - Returns - ------- - str - Its TOML. - """ - if isinstance(value, bool): - return "true" if value else "false" - if isinstance(value, int): - return str(value) - return '"' + str(value).replace("\\", "\\\\").replace('"', '\\"') + '"' IMPLIED: Final = {"mode_average": False} @@ -152,107 +68,58 @@ def _toml(value: object) -> str: solprop's metadata.""" CARDS: Final = ( + RouteCard("gnlse", "Fibre (GNLSE)", "gnlse", example="soliton"), RouteCard( - "gnlse", - "Fibre (GNLSE)", - "A single-mode fibre given by its dispersion and nonlinear coefficient.", - "gnlse", - example="soliton", - group="Solid-core fibres", - ), - RouteCard( - "step-index", - "Step-index fibre", - "A solid core in a cladding of lower index, its modes solved from the two " - "indices.", - "gnlse", - reason="solprop's recipes cannot describe a step-index fibre yet (#472).", - types={"fibre": ("StepIndexMode",)}, - group="Solid-core fibres", + "step-index", "Step-index fibre", "gnlse", types={"fibre": ("StepIndexMode",)} ), RouteCard( "grin", "Graded-index fibre", - "A solid core whose index falls smoothly from its axis, its modes solved " - "from the profile.", "gnlse", - reason="solprop's recipes cannot describe a graded-index fibre yet (#473).", types={"fibre": ("GradedIndexProvider",)}, - group="Solid-core fibres", ), RouteCard( "capillary-averaged", "Capillary, mode-averaged", - "A gas-filled hollow capillary, one mode with its nonlinearity averaged over " - "the profile: the quickest model of a capillary.", "capillary", {"mode_average": True}, - group="Hollow-core fibres", ), RouteCard( - "capillary-modal", - "Capillary, multimode", - "The capillary's modes coupled through the nonlinearity: the first HE1m " - "modes by number, or any HE, TE and TM modes listed.", - "capillary", - {"mode_average": False}, - {"modes": 4}, - group="Hollow-core fibres", + "capillary-modal", "Capillary, multimode", "capillary", {"mode_average": False} ), RouteCard( "antiresonant", "Antiresonant fibre", - "A hollow core bounded by a ring of thin-walled tubes, gas-filled: the " - "capillary's modes with the lattice's loss and dispersion.", "capillary", example="antiresonant_fibre", marker=("lattice",), - group="Hollow-core fibres", ), RouteCard( "cartesian", "Free space, Cartesian", - "A beam in a bulk medium or gas on a transverse x-y grid.", "free", example="cartesian_beam", types={"space": ("FreeGrid",)}, - group="Free space", ), RouteCard( "line", "Free space, line", - "A beam uniform in y on a line of x nodes: energies and powers are per unit " - "width.", "free", example="cartesian_beam", types={"space": ("LineGrid",)}, rewrite={"space": {"type": "LineGrid", "radius_x": "6 mm", "n_x": 64}}, - group="Free space", - ), - RouteCard( - "radial", - "Free space, radial", - "A radially symmetric beam in a bulk medium or gas, on a Hankel grid.", - "radial", - example="radial_kerr", - group="Free space", ), + RouteCard("radial", "Free space, radial", "radial", example="radial_kerr"), RouteCard( "rectangular", "Rectangular waveguide", - "A gas-filled hollow channel of rectangular section, in its modes.", "waveguide", example="hollow_rectangular", types={"modes": ("RectMode",)}, - group="Hollow waveguides", - reason="Hollow waveguides are not offered for now.", - hidden=True, ), RouteCard( "slab", "Slab waveguide", - "A gas-filled gap between two plates, in its slab modes: uniform along the " - "plates, so energies and powers are per unit width.", "waveguide", example="hollow_rectangular", types={"modes": ("SlabMode", "ModeCollection.slab")}, @@ -262,51 +129,14 @@ def _toml(value: object) -> str: "n_theta": None, "seed": None, }, - group="Hollow waveguides", - reason="Hollow waveguides are not offered for now.", - hidden=True, - ), - RouteCard( - "planar", - "Planar waveguide", - "A slab waveguide, its modes across and free space along.", - "planar", - reason="Planar guides are not offered for now.", - example="planar_hybrid", - hidden=True, ), + RouteCard("planar", "Planar waveguide", "planar", example="planar_hybrid"), ) -"""The cards, in the order the page shows them.""" - - -def card(key: str) -> RouteCard: - """Return a card by its key. +"""The cards.""" - Parameters - ---------- - key : str - The card's key. - - Returns - ------- - RouteCard - The card. - - Raises - ------ - KeyError - If no card has that key. - """ - for entry in CARDS: - if entry.key == key: - return entry - raise KeyError(key) - -def card_of( - route: str, build: dict[str, object], *, enabled_only: bool = True -) -> RouteCard | None: - """Return the enabled card a recipe is, if any. +def card_of(route: str, build: dict[str, object]) -> RouteCard | None: + """Return the card a recipe is, if any. Parameters ---------- @@ -314,15 +144,12 @@ def card_of( The recipe's route. build : dict Its ``[build]`` table. - enabled_only : bool, optional - Whether only an enabled card counts (the default); ``False`` names the - class of an example on a route the window does not offer yet. Returns ------- RouteCard or None - The enabled card of that route whose preset values, marker keywords and - keyword types the recipe holds, the cards with markers or types tried first. + The card of that route whose preset values, marker keywords and keyword + types the recipe holds, the cards with markers or types tried first. Examples -------- @@ -334,13 +161,9 @@ class of an example on a route the window does not offer yet. 'antiresonant' >>> card_of("free", {"space": {"type": "LineGrid"}}).key 'line' - >>> slab = {"modes": [{"type": "SlabMode"}]} - >>> card_of("waveguide", slab) is None # not offered for now - True - >>> card_of("waveguide", slab, enabled_only=False).key + >>> card_of("waveguide", {"modes": [{"type": "SlabMode"}]}).key 'slab' - >>> collection = {"modes": {"type": "ModeCollection.slab"}} - >>> card_of("waveguide", collection, enabled_only=False).key + >>> card_of("waveguide", {"modes": {"type": "ModeCollection.slab"}}).key 'slab' >>> card_of("radial", {}).key 'radial' @@ -349,8 +172,7 @@ class of an example on a route the window does not offer yet. """ for entry in sorted(CARDS, key=lambda c: -len(c.marker) - len(c.types)): if ( - (entry.enabled or not enabled_only) - and entry.route == route + entry.route == route and all(build.get(k, IMPLIED.get(k)) == v for k, v in entry.preset.items()) and all(k in build for k in entry.marker) and all(type_of(build.get(k)) in v for k, v in entry.types.items()) @@ -383,68 +205,3 @@ def type_of(value: object) -> str | None: found = value.get("type") return None if found is None else str(found) return None - - -GUIDED: Final = frozenset({"capillary", "waveguide", "planar", "gnlse"}) -"""The routes with a mode set for the explorer to show (``Recipe.modes``).""" - -EXPLORER_SETUP: Final = """\ -[recipe] -format = 1 -route = "capillary" -title = "Waveguide explorer" - -[build] -radius = "125 um" -length = "1 m" -gas = "He" -pressure = "1 bar" -modes = 4 -wavelength = "800 nm" -fwhm = "10 fs" -energy = "100 uJ" -wavelength_limits = ["150 nm", "4 um"] -trange = "400 fs" -""" -"""The setup the standalone waveguide explorer opens with: a helium-filled capillary -and its first four modes, a starting point to change and sweep.""" - - -def group_examples( - examples: Sequence[Mapping[str, object]], -) -> dict[str, list[Mapping[str, object]]]: - """Sort solprop's examples into the geometry classes the cards name. - - Parameters - ---------- - examples : Sequence of Mapping - Each example's ``name``, ``title``, ``route`` and ``build`` table. - - Returns - ------- - dict - By card key, in the cards' order, the examples it recognises as its own - (:func:`card_of`, disabled cards included); ``"other"`` for the rest. A - hidden card's examples are left out. - - Examples - -------- - >>> grouped = group_examples([ - ... {"name": "a", "route": "capillary", "build": {"mode_average": True}}, - ... {"name": "b", "route": "gnlse", "build": {}}, - ... {"name": "c", "route": "nope", "build": {}}, - ... {"name": "d", "route": "planar", "build": {}}, - ... ]) - >>> {key: [e["name"] for e in found] for key, found in grouped.items()} - {'gnlse': ['b'], 'capillary-averaged': ['a'], 'other': ['c']} - """ - grouped: dict[str, list[Mapping[str, object]]] = {} - for example in examples: - given = example.get("build") - build: dict[str, object] = dict(given) if isinstance(given, Mapping) else {} - entry = card_of(str(example["route"]), build, enabled_only=False) - if entry is not None and entry.hidden: - continue - grouped.setdefault("other" if entry is None else entry.key, []).append(example) - order = [card.key for card in CARDS] + ["other"] - return {key: grouped[key] for key in order if key in grouped} diff --git a/gui/src/solprop_gui/ui/document.py b/gui/src/solprop_gui/ui/document.py index 7f06d029d..58343a699 100644 --- a/gui/src/solprop_gui/ui/document.py +++ b/gui/src/solprop_gui/ui/document.py @@ -4,7 +4,7 @@ """The open setup: its recipe, undo, checks and files, apart from any window. -Both windows hold one of these. It owns the recipe model, the undo stack, the kernel's +The window holds one of these. It owns the recipe model, the undo stack, the kernel's check and summary of each revision, the route's description, saving and the recovery copy, and says what happened through signals, so a window only shows the result. """ @@ -308,21 +308,20 @@ def open_example( self._adapt[request] = adapt def open_recipe(self, path: str | Path) -> None: - """Open a recipe file. + """Open a recipe file; one that cannot be read is said, and nothing is lost. Parameters ---------- path : str or pathlib.Path The file. """ - if not self.may_discard(): - return try: model = RecipeModel.load(path) except (OSError, ValueError) as error: self.message.emit(f"Cannot open {path}: {error}") return - self.set_model(model, base=str(Path(path).parent)) + if self.may_discard(): + self.set_model(model, base=str(Path(path).parent)) def open_text(self, text: str, base: str | None) -> None: """Open a recipe's text as a new, unsaved setup. diff --git a/gui/src/solprop_gui/ui/home.py b/gui/src/solprop_gui/ui/home.py index ee2757a6b..64cc0a927 100644 --- a/gui/src/solprop_gui/ui/home.py +++ b/gui/src/solprop_gui/ui/home.py @@ -4,7 +4,7 @@ """Home: shown when nothing is open, it asks what you want to do (design 5.2).""" -from collections.abc import Callable, Sequence +from collections.abc import Callable, Mapping, Sequence from datetime import UTC, datetime from pathlib import Path @@ -22,7 +22,6 @@ ) from solprop_gui.classes.catalog import CLASSES -from solprop_gui.model.workspace import RunEntry from solprop_gui.ui.theme import clear_layout, named_label from solprop_gui.ui.tile_art import tile_pixmap @@ -251,22 +250,28 @@ def show_workspace(self, folder: Path) -> None: self.workspace.setText(f"In {shown}") self.workspace.setToolTip(str(folder)) - def show_runs(self, runs: Sequence[RunEntry]) -> None: - """List the workspace's latest runs. + def show_runs(self, runs: Sequence[Mapping[str, object]]) -> None: + """List the workspace's latest runs that have a results file. Parameters ---------- - runs : Sequence of RunEntry - The runs, newest first. + runs : Sequence of Mapping + The runs' summaries, newest first, as + :func:`solprop.service.runs.list_runs` gives them. """ entries = [] - for run in [run for run in runs if run.output is not None][:_RECENT]: - when = datetime.fromtimestamp(run.modified, tz=UTC).astimezone() - output = str(run.output) + for run in [run for run in runs if run.get("output")][:_RECENT]: + # When it ended, or started; a run that kept no record says neither. + stamp = run.get("ended") or run.get("started") or run.get("submitted") + detail = "" + if isinstance(stamp, int | float): + when = datetime.fromtimestamp(stamp, tz=UTC).astimezone() + detail = when.strftime("%d %b %Y, %H:%M") + output = str(run["output"]) entries.append( ( - run.name, - when.strftime("%d %b %Y, %H:%M"), + str(run["run_id"]), + detail, lambda path=output: self.results_chosen.emit(path), ) ) diff --git a/gui/src/solprop_gui/ui/machines_hub.py b/gui/src/solprop_gui/ui/machines_hub.py index b3884535b..70798c428 100644 --- a/gui/src/solprop_gui/ui/machines_hub.py +++ b/gui/src/solprop_gui/ui/machines_hub.py @@ -17,6 +17,7 @@ import contextlib import json import threading +import time from collections.abc import Callable, Mapping from concurrent.futures import ThreadPoolExecutor from pathlib import Path @@ -31,6 +32,10 @@ _KEY = "machines" +_CLOSE_SECONDS = 10.0 +"""How long closing waits for the machines' sessions to end, together, s: one stuck +session's own stop and the wait for its reader.""" + def _read_marker(path: Path) -> dict[str, object] | None: """Return the source a partial copy was taken from, as its marker records it. @@ -135,7 +140,7 @@ def save(self, machines: list[Machine]) -> None: class MachineRun: - """A run on a machine, as a run panel holds a worker's handle. + """A run on a machine, as a run panel follows it. Stop writes the run's stop file; Kill ends its job (``scancel``, or ``SIGTERM``), which still leaves a resumable file. @@ -161,16 +166,6 @@ def stop(self) -> None: """Ask the run to stop at its next step.""" self.hub.call(self.machine, "stop", {"folder": self.folder}) - def subscribe(self, from_plane: int = 0) -> None: - """Do nothing: a run's record drops no rows, so none need replaying. - - Parameters - ---------- - from_plane : int, optional - The first plane wanted. - """ - del from_plane - def cancel(self) -> None: """End the run's job (``SIGTERM``, ``scancel``); solprop saves where it was.""" self.hub.call(self.machine, "cancel", {"folder": self.folder}) @@ -236,12 +231,17 @@ class MachineHub(QObject): kernel. answered : Signal Emitted with a call's token and its value, or the error it raised. + copied : Signal + Emitted from a copying thread with a fetch's token, the bytes copied and the + total, to reach its progress on the window's thread. """ state_changed = Signal(str, str, object) run_event = Signal(object) replied = Signal(object) answered = Signal(int, object, object) + # Sizes as objects: a results file can exceed what a C int holds. + copied = Signal(int, object, object) def __init__( self, parent: QObject | None = None, *, askpass: str | None = None @@ -259,8 +259,10 @@ def __init__( ) self._tokens = iter(range(1, 1 << 62)) self._callbacks: dict[int, Callable[[object, object], None]] = {} + self._progress: dict[int, Callable[[int, int], None]] = {} self._closed = False self.answered.connect(self._answer) + self.copied.connect(self._copied) # -------------------------------------------------------------- connections @@ -474,10 +476,42 @@ def _answer(self, token: int, value: object, error: object) -> None: error : object Its error's text, or ``None``. """ + self._progress.pop(token, None) done = self._callbacks.pop(token, None) if done is not None: done(value, error) + def _piece_copied(self, token: int, have: int, total: int) -> None: + """Hand a fetch's progress to the window's thread, unless the hub has closed. + + Parameters + ---------- + token : int + The fetch. + have : int + The bytes copied. + total : int + The file's size, bytes. + """ + if not self._closed: + self.copied.emit(token, have, total) + + def _copied(self, token: int, have: int, total: int) -> None: + """Hand a fetch's progress to whoever asked, on the window's thread. + + Parameters + ---------- + token : int + The fetch. + have : int + The bytes copied. + total : int + The file's size, bytes. + """ + progress = self._progress.get(token) + if progress is not None: + progress(have, total) + def kernel(self, name: str, request: Request) -> None: """Send a request to a machine's kernel; its reply comes as :attr:`replied`. @@ -610,7 +644,8 @@ def fetch( local : pathlib.Path Where the copy goes. progress : Callable - Called, from the copying thread, with the bytes copied and the total. + Called on the window's thread with the bytes copied and the total, as + each piece arrives. done : Callable Called on the window's thread with the copy's path and ``None``, or ``None`` and the error's text. @@ -622,6 +657,7 @@ def fetch( """ token = next(self._tokens) self._callbacks[token] = done + self._progress[token] = progress cancelled = threading.Event() def copy() -> None: @@ -656,7 +692,7 @@ def copy() -> None: break stream.write(data) have += len(data) - progress(have, total) + self._piece_copied(token, have, total) if cancelled.is_set(): msg = "the copy was cancelled" raise ServiceError(msg) @@ -717,9 +753,21 @@ def copy() -> None: self._pool.submit(copy) def close(self) -> None: - """Close every connection, now; the machines' runs go on.""" + """Close every connection, now; the machines' runs go on. + + The connections close together, each on a thread of its own, within one + deadline: a stuck session waits for its process to stop and its reader to + end, and closed one after another the waits would add up machine by machine. + """ self._closed = True - for connection in self.connections.values(): - connection.close() + closers = [ + threading.Thread(target=connection.close, daemon=True) + for connection in self.connections.values() + ] + for closer in closers: + closer.start() + deadline = time.monotonic() + _CLOSE_SECONDS + for closer in closers: + closer.join(max(0.0, deadline - time.monotonic())) self.connections.clear() self._pool.shutdown(wait=False, cancel_futures=True) diff --git a/gui/src/solprop_gui/ui/pages.py b/gui/src/solprop_gui/ui/pages.py index 9ffea8f80..25aca642b 100644 --- a/gui/src/solprop_gui/ui/pages.py +++ b/gui/src/solprop_gui/ui/pages.py @@ -2,36 +2,12 @@ # # SPDX-License-Identifier: GPL-3.0-or-later -"""The settings panels: the start, and the setup steps built from solprop's metadata.""" +"""Parts of a settings panel: a collapsible section, and the keyword an issue names.""" -from collections.abc import Iterable, Mapping, Sequence +from PySide6.QtCore import Qt +from PySide6.QtWidgets import QToolButton, QVBoxLayout, QWidget -from PySide6.QtCore import Qt, Signal -from PySide6.QtWidgets import ( - QCheckBox, - QFrame, - QHBoxLayout, - QLabel, - QScrollArea, - QToolButton, - QVBoxLayout, - QWidget, -) - -from solprop_gui.model.recipe import MISSING, RecipeModel -from solprop_gui.registry.pages import ( - GROUP_TITLES, - ROUTE_GROUP_TITLES, - ROUTE_HELP, - Page, -) -from solprop_gui.ui.fields import ParameterRow -from solprop_gui.ui.objects import Catalog - -__all__ = ["PER_WIDTH", "ParameterPage", "Section", "issue_keyword"] - -PER_WIDTH = ("energy", "peak_power") -"""The keywords per metre of y on a slab set (solprop's ``PER_WIDTH_KEYWORDS``).""" +__all__ = ["Section", "issue_keyword"] def issue_keyword(parameter: object) -> list[str]: @@ -114,323 +90,3 @@ def add(self, widget: QWidget) -> None: The widget. """ self.rows.addWidget(widget) - - -class ParameterPage(QWidget): - """One step's settings: the rows of the keywords in its groups, in sections. - - The page is a narrow panel at the window's left; a page of several groups - shows each in a collapsible section. - - Parameters - ---------- - page : solprop_gui.registry.pages.Page - The page. - parent : PySide6.QtWidgets.QWidget or None, optional - The owner. - - Attributes - ---------- - edited : Signal - Emitted with (name, table, value) when a row's value is changed. - roots_wanted : Signal - Emitted with a pinned keyword when the user asks for its pin's roots. - """ - - edited = Signal(str, str, object) - roots_wanted = Signal(str) - scan_wanted = Signal(str, object) - - def __init__(self, page: Page, parent: QWidget | None = None) -> None: - """Make the page, with no rows until the route is described.""" - super().__init__(parent) - self.page = page - self.rows: dict[tuple[str, str], ParameterRow] = {} - self.sections: dict[str, Section] = {} - self.title = QLabel(f"<b>{page.title}</b>") - self.help = QLabel(page.help) - self.help.setWordWrap(True) - self.help.setStyleSheet("color: palette(placeholder-text);") - self.advanced = QCheckBox("Advanced") - self.advanced.setToolTip("Show the expert settings too.") - self.advanced.toggled.connect(self._show_levels) - self.empty = QLabel( - "<p><b>Select a setup first.</b></p><p>Choose a geometry class or one of " - "solprop's examples on the Start step, or open a setup file.</p>" - ) - self.empty.setObjectName("select-setup-first") - self.empty.setWordWrap(True) - self.empty.setAlignment(Qt.AlignmentFlag.AlignTop) - self.body = QWidget() - self.form = QVBoxLayout(self.body) - self.form.setAlignment(Qt.AlignmentFlag.AlignTop) - self.form.setContentsMargins(6, 4, 6, 4) - self.form.setSpacing(2) - self.top = QVBoxLayout() - self.top.setContentsMargins(0, 0, 0, 0) - self.form.addLayout(self.top) - for group in page.groups: - section = Section(GROUP_TITLES.get(group, group.capitalize())) - section.setVisible(False) - self.sections[group] = section - self.form.addWidget(section) - scroll = QScrollArea() - scroll.setWidgetResizable(True) - scroll.setFrameShape(QFrame.Shape.NoFrame) - scroll.setHorizontalScrollBarPolicy(Qt.ScrollBarPolicy.ScrollBarAlwaysOff) - scroll.setWidget(self.body) - header = QHBoxLayout() - header.addWidget(self.title, 1) - header.addWidget(self.advanced) - layout = QVBoxLayout(self) - layout.setContentsMargins(4, 4, 0, 0) - layout.setSpacing(2) - layout.addLayout(header) - layout.addWidget(self.help) - layout.addWidget(self.empty, 1) - layout.addWidget(scroll, 1) - self.fields_area = scroll - self.page_layout = layout - self._show_empty(True) - - def set_route(self, route: str) -> None: - """Word the page for a route: its help and its sections' titles. - - Parameters - ---------- - route : str - The recipe's route (a beam's grid is no waveguide). - """ - key = self.page.key - self.help.setText(ROUTE_HELP.get((key, route), self.page.help)) - for group, section in self.sections.items(): - default = GROUP_TITLES.get(group, group.capitalize()) - section.header.setText(ROUTE_GROUP_TITLES.get((route, group), default)) - - def add_footer(self, title: str, widget: QWidget) -> Section: - """Put a section below the page's fields, always in view. - - Parameters - ---------- - title : str - Its title. - widget : PySide6.QtWidgets.QWidget - What it holds. - - Returns - ------- - Section - The section. - """ - section = Section(title) - section.add(widget) - self.page_layout.addWidget(section) - return section - - def _show_empty(self, empty: bool) -> None: - """Show the page's fields, or that a setup must be chosen first. - - Parameters - ---------- - empty : bool - Whether there is no setup yet. - """ - self.empty.setVisible(empty) - self.fields_area.setVisible(not empty) - self.advanced.setVisible(not empty) - - def add_section(self, title: str, widget: QWidget) -> Section: - """Put a section of the window's own above the keywords' sections. - - Parameters - ---------- - title : str - Its title. - widget : PySide6.QtWidgets.QWidget - What it holds. - - Returns - ------- - Section - The section. - """ - section = Section(title) - section.add(widget) - self.top.addWidget(section) - return section - - def build( - self, - parameters: Iterable[Mapping[str, object]], - table: str = "build", - catalog: Catalog | None = None, - ) -> None: - """Add a row for each keyword of the page's groups. - - Parameters - ---------- - parameters : Iterable of Mapping - The route's keyword metadata, in its order. - table : str, optional - The recipe table they belong to. - catalog : Catalog or None, optional - The registered types the keywords can name, for their own editors. - """ - for meta in parameters: - if meta.get("group") not in self.page.groups: - continue - if not any(form.get("recipe", True) for form in meta.get("forms", [])): # pyright: ignore[reportGeneralTypeIssues, reportAttributeAccessIssue] - continue - row = ParameterRow(meta, table, catalog=catalog) - row.edited.connect(self.edited) - row.scan_wanted.connect(self.scan_wanted) - if row.pin_targets: - row.pin.roots_wanted.connect( - lambda name=row.name: self.roots_wanted.emit(name) - ) - self.rows[row.name, table] = row - section = self.sections[str(meta.get("group"))] - section.add(row) - section.setVisible(True) - self._show_empty(False) - # One group needs no heading of its own: the page's title says it. - for section in self.sections.values(): - section.header.setVisible(len(self.sections) > 1) - self._show_levels(self.advanced.isChecked()) - - def clear(self) -> None: - """Remove every row.""" - for row in self.rows.values(): - row.setParent(None) - row.deleteLater() - self.rows = {} - for section in self.sections.values(): - section.setVisible(False) - - def _show_levels(self, advanced: bool) -> None: - """Show the basic rows, and the advanced ones when asked. - - Parameters - ---------- - advanced : bool - Whether to show the advanced rows. - """ - for row in self.rows.values(): - row.setVisible(advanced or row.level == "basic" or row.is_set) - - def show_values(self, model: RecipeModel) -> None: - """Show the recipe's values in the rows. - - Parameters - ---------- - model : solprop_gui.model.recipe.RecipeModel - The recipe. - """ - advanced = self.advanced.isChecked() - for (name, table), row in self.rows.items(): - value = model.get(name, table) - pin = model.get(name, "pins") if row.pin_targets else MISSING - if isinstance(pin, dict): - row.set_pin(pin) - else: - row.set_value(value) - # An advanced keyword the recipe sets is shown: nothing set is hidden. - row.setVisible(advanced or row.level == "basic" or row.is_set) - - def show_per_width(self, per_width: bool) -> None: - """Say on the energy and the peak power whether they are per metre of y. - - Parameters - ---------- - per_width : bool - Whether the setup is a slab mode set, uniform in y. - """ - for (name, _), row in self.rows.items(): - if name in PER_WIDTH: - row.set_per_width(per_width) - - def show_pinned(self, pinned: Mapping[str, object]) -> None: - """Show the values solprop solved the pins to. - - Parameters - ---------- - pinned : Mapping - By pinned keyword, its solved value in the keyword's unit. - """ - for (name, _), row in self.rows.items(): - if row.pin_targets: - row.pin.set_solved(pinned.get(name), row.unit) - - def set_mode_labels(self, labels: Sequence[str]) -> None: - """Offer the setup's mode labels to its tables of modes. - - Parameters - ---------- - labels : Sequence of str - The labels, as the mode preview gives them. - """ - for row in self.rows.values(): - if "table" in row.modes: - row.launch.set_labels(labels) - - def show_resolved(self, resolved: Mapping[str, Sequence[object]]) -> None: - """Show what unset defaults resolve to. - - Parameters - ---------- - resolved : Mapping - By keyword, the value and the rule. - """ - for (name, _), row in self.rows.items(): - row.set_resolved(resolved.get(name)) - - def reveal(self, name: str) -> ParameterRow | None: - """Show a keyword's row, opening its section, and focus its field. - - Parameters - ---------- - name : str - The keyword. - - Returns - ------- - ParameterRow or None - The row, or ``None`` if the page has none for it. - """ - for (row_name, _), row in self.rows.items(): - if row_name == name: - for section in self.sections.values(): - if section.isAncestorOf(row): - section.header.setChecked(True) - row.setVisible(True) - row.editor.setFocus() - return row - return None - - def show_issues(self, issues: Sequence[Mapping[str, object]]) -> str | None: - """Show the issues at their rows. - - Parameters - ---------- - issues : Sequence of Mapping - The issues solprop found: ``message``, ``parameter`` and ``severity``. - - Returns - ------- - str or None - The worst severity shown on this page, or ``None`` for none. - """ - for row in self.rows.values(): - row.set_issue(None) - worst: str | None = None - for issue in issues: - for name in issue_keyword(issue.get("parameter")): - for (row_name, _), row in self.rows.items(): - if row_name != name: - continue - severity = str(issue.get("severity", "error")) - row.set_issue(str(issue.get("message")), severity) - row.setVisible(True) - if worst != "error": - worst = severity - return worst diff --git a/gui/src/solprop_gui/ui/pin.py b/gui/src/solprop_gui/ui/pin.py index 3a62ebf1b..b27ee956d 100644 --- a/gui/src/solprop_gui/ui/pin.py +++ b/gui/src/solprop_gui/ui/pin.py @@ -7,8 +7,8 @@ A pinnable keyword's row offers "pinned" beside its value. Pinned, the keyword is set by solprop from a target (a zero-dispersion wavelength, a dispersive-wave wavelength or a soliton order) within a search range, and the editor writes the recipe's -``[pins]`` entry; the value solprop solves for is shown beside it, and "Roots" asks -for every root in the range, so another can be chosen than the lowest. +``[pins]`` entry, with the root it takes (the lowest or the highest in the range); +the value solprop solves for is shown beside it. """ from collections.abc import Mapping, Sequence @@ -19,7 +19,6 @@ QGridLayout, QLabel, QStackedWidget, - QToolButton, QVBoxLayout, QWidget, ) @@ -56,15 +55,12 @@ class PinField(QWidget): Emitted with the ``[pins]`` entry when it is complete and changed. refused : Signal Emitted with the reason a part of it does not read. - roots_wanted : Signal - Emitted when the user asks for every root. """ changed = Signal(object) refused = Signal(str) - roots_wanted = Signal() - def __init__( # noqa: PLR0915 - one field per target key + def __init__( self, name: str, targets: Sequence[Mapping[str, object]], @@ -107,12 +103,6 @@ def __init__( # noqa: PLR0915 - one field per target key for text, value in _ROOTS: self.root.addItem(text, value) self.root.currentIndexChanged.connect(self._changed) - self.find_button = QToolButton() - self.find_button.setText("Roots") - self.find_button.setToolTip( - "Find every value in the search range that meets the target." - ) - self.find_button.clicked.connect(self.roots_wanted) self.solved = QLabel("") self.solved.setObjectName(f"pin-solved-{name}") self.solved.setWordWrap(True) @@ -122,7 +112,6 @@ def __init__( # noqa: PLR0915 - one field per target key grid.addWidget(self.search_label, 0, 0) grid.addWidget(self.search, 0, 1, 1, 2) grid.addWidget(self.root, 1, 1) - grid.addWidget(self.find_button, 1, 2) layout = QVBoxLayout(self) layout.setContentsMargins(0, 0, 0, 0) layout.setSpacing(2) @@ -154,7 +143,7 @@ def _target_changed(self, index: int) -> None: """ self.keys.setCurrentIndex(max(index, 0)) guide = self._current()["stage"] == "guide" - for widget in (self.search_label, self.search, self.root, self.find_button): + for widget in (self.search_label, self.search, self.root): widget.setVisible(guide) if guide and self.search.read() is None and self.name in PIN_SEARCH: self.search.set_value(PIN_SEARCH[self.name]) @@ -236,7 +225,7 @@ def set_value(self, entry: Mapping[str, object]) -> None: self._updating = False self._entry = dict(entry) guide = self._current()["stage"] == "guide" - for widget in (self.search_label, self.search, self.root, self.find_button): + for widget in (self.search_label, self.search, self.root): widget.setVisible(guide) def set_solved(self, value: object, unit: str | None) -> None: @@ -254,33 +243,3 @@ def set_solved(self, value: object, unit: str | None) -> None: return text = f"{value:.6g}" if isinstance(value, float) else inline(value) self.solved.setText(f"Solved: {text} {unit or ''}".rstrip()) - - def set_roots(self, found: Mapping[str, object], unit: str | None) -> None: - """Offer every root solprop found, or say what the range reaches. - - Parameters - ---------- - found : Mapping - The kernel's ``pin_roots`` reply: ``roots``, ``quantity`` and - ``attainable``. - unit : str or None - The keyword's unit. - """ - roots: list[float] = list(found.get("roots") or []) # pyright: ignore[reportArgumentType] - self._updating = True - try: - while self.root.count() > len(_ROOTS): - self.root.removeItem(self.root.count() - 1) - for index, root in enumerate(roots): - self.root.addItem(f"root {index}: {root:.6g} {unit or ''}", index) - finally: - self._updating = False - if roots: - self.solved.setText(f"{len(roots)} root(s) in the search range.") - else: - reach = found.get("attainable") - self.solved.setText( - f"No root: the {found.get('quantity')} reaches {reach} in this range." - if reach - else "No root, and the target is not reached in this range." - ) diff --git a/gui/src/solprop_gui/ui/plot_options.py b/gui/src/solprop_gui/ui/plot_options.py deleted file mode 100644 index 16cd31f9c..000000000 --- a/gui/src/solprop_gui/ui/plot_options.py +++ /dev/null @@ -1,439 +0,0 @@ -# SPDX-FileCopyrightText: 2026 John C. Travers and contributors -# -# SPDX-License-Identifier: GPL-3.0-or-later - -"""The plot options panel, at the bottom left of the Propagate and Results steps. - -It edits one :class:`~solprop_gui.model.plot_options.PlotOptions`: the spectral axis, -typed limits for the spectral and time axes (blank for automatic), the spectral scale -and floor, and a bandpass for the time-domain views. The window keeps one set of -options and shows it in each step's panel. -""" - -from PySide6.QtCore import Signal -from PySide6.QtWidgets import ( - QCheckBox, - QComboBox, - QDoubleSpinBox, - QFormLayout, - QHBoxLayout, - QLabel, - QLineEdit, - QPushButton, - QSpinBox, - QWidget, -) - -from solprop_gui.model.plot_options import ( - AXES, - SCALES, - UNITS, - PlotOptions, - from_display, - parse_limit, - to_display, -) - -__all__ = ["PlotOptionsPanel", "SpectrogramOptions"] - -_BAD = "QLineEdit { border: 1px solid #c62828; }" - - -def _text(value: float | None) -> str: - """Return a limit as the panel shows it. - - Parameters - ---------- - value : float or None - The limit in its display unit; ``None`` for automatic. - - Returns - ------- - str - The number, compactly, or blank. - """ - return "" if value is None else f"{value:.6g}" - - -class _Range(QWidget): - """Two typed limits, low and high, with a unit. - - Parameters - ---------- - name : str - The fields' object-name prefix. - unit : str - The unit shown after them. - """ - - edited = Signal() - - def __init__(self, name: str, unit: str) -> None: - """Make the two fields.""" - super().__init__() - self.low = QLineEdit() - self.high = QLineEdit() - for field, end in ((self.low, "low"), (self.high, "high")): - field.setObjectName(f"{name}-{end}") - field.setPlaceholderText("auto") - field.setMaximumWidth(80) - field.editingFinished.connect(self.edited) - self.unit = QLabel(unit) - layout = QHBoxLayout(self) - layout.setContentsMargins(0, 0, 0, 0) - layout.addWidget(self.low) - layout.addWidget(QLabel("to")) - layout.addWidget(self.high) - layout.addWidget(self.unit) - layout.addStretch(1) - - def values(self) -> tuple[float | None, float | None] | None: - """Return the typed limits, ascending, marking a field that is not a number. - - Returns - ------- - tuple or None - The limits in the display unit, ``None`` where blank; ``None`` when - either is not a number. - """ - found: list[float | None] = [] - good = True - for field in (self.low, self.high): - try: - found.append(parse_limit(field.text())) - field.setStyleSheet("") - except ValueError: - field.setStyleSheet(_BAD) - good = False - if not good: - return None - low, high = found - if low is not None and high is not None and low > high: - low, high = high, low - return low, high - - def show_values(self, low: float | None, high: float | None) -> None: - """Show two limits. - - Parameters - ---------- - low, high : float or None - The limits in the display unit; ``None`` for automatic. - """ - self.low.setText(_text(low)) - self.high.setText(_text(high)) - for field in (self.low, self.high): - field.setStyleSheet("") - - -class PlotOptionsPanel(QWidget): - """Edit the plot options. - - Parameters - ---------- - name : str - A prefix for its widgets' object names, to tell two panels apart. - parent : PySide6.QtWidgets.QWidget or None, optional - The owner. - - Attributes - ---------- - changed : Signal - Emitted with the new :class:`PlotOptions` when an option is changed. - """ - - changed = Signal(object) - - def __init__(self, name: str = "plot", parent: QWidget | None = None) -> None: # noqa: PLR0915 - a form - """Make the fields, showing the default options.""" - super().__init__(parent) - self.setObjectName(f"{name}-options") - self._options = PlotOptions() - self.axis = QComboBox() - self.axis.setObjectName(f"{name}-axis") - for key, label in AXES.items(): - self.axis.addItem(f"{label} ({UNITS[key][0]})", key) - self.axis.setToolTip( - "The abscissa of spectra, maps and spectrograms. solprop gives the " - "density per unit of the axis chosen." - ) - self.axis.currentIndexChanged.connect(self._axis_changed) - self.spectral = _Range(f"{name}-spectral", UNITS["wavelength"][0]) - self.time = _Range(f"{name}-time", UNITS["time"][0]) - self.scale = QComboBox() - self.scale.setObjectName(f"{name}-scale") - self.scale.addItems(list(SCALES)) - self.floor = QDoubleSpinBox() - self.floor.setObjectName(f"{name}-floor") - self.floor.setRange(-200.0, -5.0) - self.floor.setSuffix(" dB") - self.floor.setToolTip("The bottom of the dB scale.") - scale = QWidget() - scale_row = QHBoxLayout(scale) - scale_row.setContentsMargins(0, 0, 0, 0) - scale_row.addWidget(self.scale) - scale_row.addWidget(QLabel("floor")) - scale_row.addWidget(self.floor) - scale_row.addStretch(1) - self.band_on = QCheckBox("within") - self.band_on.setObjectName(f"{name}-band-on") - self.band_on.setToolTip( - "Compute power, the time-domain views and the spectrogram from the light " - "in this wavelength band only (solprop's Planck-tapered bandpass)." - ) - self.band = _Range(f"{name}-band", UNITS["wavelength"][0]) - band = QWidget() - band_row = QHBoxLayout(band) - band_row.setContentsMargins(0, 0, 0, 0) - band_row.addWidget(self.band_on) - band_row.addWidget(self.band, 1) - self.note = QLabel("") - self.note.setObjectName(f"{name}-options-note") - self.note.setWordWrap(True) - self.reset = QPushButton("Reset") - self.reset.setObjectName(f"{name}-options-reset") - self.reset.clicked.connect(lambda: self._emit(PlotOptions())) - - form = QFormLayout(self) - form.setContentsMargins(0, 0, 0, 0) - form.addRow("Spectral axis", self.axis) - form.addRow("Spectral range", self.spectral) - form.addRow("Time range", self.time) - form.addRow("Spectra", scale) - form.addRow("Bandpass", band) - form.addRow(self.note) - form.addRow(self.reset) - for signal in ( - self.spectral.edited, - self.time.edited, - self.band.edited, - self.scale.currentIndexChanged, - self.floor.valueChanged, - self.band_on.toggled, - ): - signal.connect(self._edited) - self.set_options(self._options) - - @property - def options(self) -> PlotOptions: - """Return the options shown. - - Returns - ------- - PlotOptions - The options. - """ - return self._options - - def set_options(self, options: PlotOptions) -> None: - """Show options, without announcing them. - - Parameters - ---------- - options : PlotOptions - The options. - """ - self._options = options - widgets = (self.axis, self.scale, self.floor, self.band_on) - for widget in widgets: - widget.blockSignals(True) - self.axis.setCurrentIndex(self.axis.findData(options.axis)) - self.spectral.unit.setText(UNITS[options.axis][0]) - self.spectral.show_values(*options.shown_limits("spectral")) - self.time.show_values(*options.shown_limits("time")) - self.scale.setCurrentText(options.scale) - self.floor.setValue(options.floor) - self.floor.setEnabled(options.scale == "dB") - self.band_on.setChecked(options.bandpass is not None) - if options.bandpass is not None: - low, high = (to_display("wavelength", v) for v in options.bandpass) - self.band.show_values(low, high) - for widget in widgets: - widget.blockSignals(False) - - def _limits(self, field: _Range, axis: str) -> tuple[float | None, float | None]: - """Return a range's typed limits in SI, or raise for a bad one. - - Parameters - ---------- - field : _Range - The range. - axis : str - Its axis. - - Returns - ------- - tuple - The limits in SI, ascending, ``None`` where automatic. - - Raises - ------ - ValueError - If either is not a number. - """ - values = field.values() - if values is None: - msg = "not a number" - raise ValueError(msg) - low, high = (None if v is None else from_display(axis, v) for v in values) - return low, high - - def _read(self) -> PlotOptions | None: - """Return the options the fields show, or ``None`` while one is invalid. - - Returns - ------- - PlotOptions or None - The options. - """ - axis = str(self.axis.currentData()) - try: - spectral = self._limits(self.spectral, axis) - time = self._limits(self.time, "time") - band = self._limits(self.band, "wavelength") - except ValueError: - self.note.setText("A limit is not a number: type a number, or leave blank.") - return None - bandpass = None - if self.band_on.isChecked(): - if band[0] is None or band[1] is None or band[0] <= 0: - self.note.setText("A bandpass needs two positive wavelengths.") - return None - bandpass = (band[0], band[1]) - self.note.setText("") - return PlotOptions( - axis=axis, # pyright: ignore[reportArgumentType] - spectral_limits=spectral, - time_limits=time, - scale=self.scale.currentText(), # pyright: ignore[reportArgumentType] - floor=self.floor.value(), - bandpass=bandpass, - gate_fwhm=self._options.gate_fwhm, # the spectrogram's, set elsewhere - positions=self._options.positions, - ) - - def _edited(self, *_args: object) -> None: - """Announce the options after a field changed, if they are valid. - - Parameters - ---------- - *_args : object - What the signal carries, unused. - """ - self.floor.setEnabled(self.scale.currentText() == "dB") - options = self._read() - if options is not None and options != self._options: - self._options = options - self.changed.emit(options) - - def _axis_changed(self, _index: int) -> None: - """Change the spectral axis: its typed limits, in the old unit, are cleared. - - Parameters - ---------- - _index : int - The axis's place, unused. - """ - axis = str(self.axis.currentData()) - self.spectral.unit.setText(UNITS[axis][0]) - self.spectral.show_values(None, None) - self._edited() - - def _emit(self, options: PlotOptions) -> None: - """Show options and announce them. - - Parameters - ---------- - options : PlotOptions - The options. - """ - self.set_options(options) - self.band.show_values(None, None) - self.note.setText("") - self.changed.emit(options) - - -class SpectrogramOptions(QWidget): - """The spectrogram's gate: its width and the number of its positions. - - The time range is the plot options' time range; the mode is the Plane view's - (a sum of modes takes the first: a spectrogram is of one field). - - Parameters - ---------- - parent : PySide6.QtWidgets.QWidget or None, optional - The owner. - - Attributes - ---------- - changed : Signal - Emitted with the gate's width (s, or ``None`` for solprop's default) and - the positions. - """ - - changed = Signal(object, int) - - def __init__(self, parent: QWidget | None = None) -> None: - """Make the two fields.""" - super().__init__(parent) - self.gate = QLineEdit() - self.gate.setObjectName("spectrogram-gate") - self.gate.setPlaceholderText("auto") - self.gate.setMaximumWidth(80) - self.gate.setToolTip( - "The Gaussian gate's full width at half maximum. A short gate shows when, " - "a long one shows what; solprop's default is a twentieth of the time range." - ) - self.gate.editingFinished.connect(self._edited) - self.positions = QSpinBox() - self.positions.setObjectName("spectrogram-positions") - self.positions.setRange(8, 4096) - self.positions.setValue(256) - self.positions.setToolTip("How many gate positions across the time range.") - self.positions.editingFinished.connect(self._edited) - gate = QWidget() - row = QHBoxLayout(gate) - row.setContentsMargins(0, 0, 0, 0) - row.addWidget(self.gate) - row.addWidget(QLabel(UNITS["time"][0])) - row.addStretch(1) - form = QFormLayout(self) - form.setContentsMargins(0, 0, 0, 0) - form.addRow("Gate width", gate) - form.addRow("Positions", self.positions) - form.addRow(QLabel("Its time range is the plot options'.")) - self._shown: tuple[float | None, int] = (None, 256) - - def set_options(self, options: PlotOptions) -> None: - """Show the gate the options hold, without announcing it. - - Parameters - ---------- - options : PlotOptions - The options. - """ - gate = options.gate_fwhm - self.gate.setText("" if gate is None else _text(to_display("time", gate))) - self.gate.setStyleSheet("") - self.positions.blockSignals(True) - self.positions.setValue(options.positions) - self.positions.blockSignals(False) - self._shown = (gate, options.positions) - - def _edited(self) -> None: - """Announce the gate, if it is blank or a positive number.""" - try: - value = parse_limit(self.gate.text()) - except ValueError: - value = -1.0 - if value is not None and value <= 0: - self.gate.setStyleSheet(_BAD) - return - self.gate.setStyleSheet("") - chosen = ( - None if value is None else from_display("time", value), - self.positions.value(), - ) - if chosen != self._shown: - self._shown = chosen - self.changed.emit(*chosen) diff --git a/gui/src/solprop_gui/ui/postprocess.py b/gui/src/solprop_gui/ui/postprocess.py index 2e8a9522a..ad04d5d67 100644 --- a/gui/src/solprop_gui/ui/postprocess.py +++ b/gui/src/solprop_gui/ui/postprocess.py @@ -2,12 +2,12 @@ # # SPDX-License-Identifier: GPL-3.0-or-later -"""The Post-process step: a compressor after the run, built and searched. +"""The Compress page's chain: a compressor after the run, built and searched. The page builds a chain of :class:`~solprop_gui.model.compressor.Stage` elements -- a Taylor phase, a material (a glass, or a gas such as an air path), chirped mirrors with optional wedges, a prism pair, a grating pair -- each fixed or searched ("auto") -by solprop, and asks the kernel to apply it to the plane the Results step shows +by solprop, and asks the kernel to apply it to the plane Analyse is on (:mod:`solprop.service.postprocess`). The pulse before, after and at the transform limit is drawn by :class:`~solprop_gui.views.compression.CompressionView`; the values an auto stage found can be taken into the chain, to change by hand. @@ -46,7 +46,6 @@ from solprop_gui.ui.analysis import AnalysisSession from solprop_gui.ui.bridge import ServiceBridge from solprop_gui.ui.pages import Section -from solprop_gui.ui.results import ResultsPage from solprop_gui.views.compression import CompressionView __all__ = ["PostprocessPage", "StageEditor"] @@ -235,14 +234,15 @@ def _auto_toggled(self, on: bool) -> None: class PostprocessPage(QWidget): - """The Post-process step's panel: the compressor's elements, and its search. + """The compressor's panel: its elements, and its search. Parameters ---------- bridge : solprop_gui.ui.bridge.ServiceBridge The service. - results : solprop_gui.ui.results.ResultsPage - The Results step, whose file, plane and mode selection are compressed. + results : solprop_gui.ui.analysis.AnalysisSession + The results file open in Analyse, whose plane and mode selection are + compressed. parent : PySide6.QtWidgets.QWidget or None, optional The owner. @@ -257,7 +257,7 @@ class PostprocessPage(QWidget): def __init__( # noqa: PLR0915 - the page's layout self, bridge: ServiceBridge, - results: ResultsPage | AnalysisSession, + results: AnalysisSession, parent: QWidget | None = None, ) -> None: """Make the page, with an empty compressor.""" diff --git a/gui/src/solprop_gui/ui/results.py b/gui/src/solprop_gui/ui/results.py deleted file mode 100644 index 2c916b138..000000000 --- a/gui/src/solprop_gui/ui/results.py +++ /dev/null @@ -1,482 +0,0 @@ -# SPDX-FileCopyrightText: 2026 John C. Travers and contributors -# -# SPDX-License-Identifier: GPL-3.0-or-later - -"""The Results step: one solprop results file, its views, and how they are drawn. - -The panel holds the file's controls, the workspace's runs (any earlier run opens from -there), the plot options and what the Statistics view's panels show; the views -(Overview, Plane, Statistics, Scan) are shown by the window among its views. The -compare of several runs is kept (:meth:`ResultsPage.add_to_compare`) but not offered. - -A file opens whether the window ran it or not: what it can show is asked of solprop -(``capabilities.output``), and its planes are reduced in the kernel. A file that -records its recipe can give its setup back ("Open its setup", the resolved -recipe, design 4). -""" - -from collections.abc import Mapping, Sequence -from dataclasses import replace -from pathlib import Path - -from PySide6.QtCore import Qt, Signal -from PySide6.QtWidgets import ( - QFileDialog, - QFrame, - QGridLayout, - QLabel, - QListWidget, - QListWidgetItem, - QPushButton, - QScrollArea, - QVBoxLayout, - QWidget, -) -from solprop.service.messages import Reply - -from solprop_gui.model.plot_options import PlotOptions -from solprop_gui.model.workspace import RunEntry -from solprop_gui.ui.bridge import ServiceBridge -from solprop_gui.ui.pages import Section -from solprop_gui.ui.plot_options import PlotOptionsPanel, SpectrogramOptions -from solprop_gui.views.compare import CompareView -from solprop_gui.views.live import OverviewView -from solprop_gui.views.plane import PlaneView -from solprop_gui.views.scan_browser import ScanView -from solprop_gui.views.statistics import StatisticsView, StatsSelector - -__all__ = ["ResultsPage"] - - -class ResultsPage(QWidget): - """Open a results file, list the workspace's runs, and choose how it is drawn. - - Parameters - ---------- - bridge : solprop_gui.ui.bridge.ServiceBridge - The service. - parent : PySide6.QtWidgets.QWidget or None, optional - The owner. - - Attributes - ---------- - setup_opened : Signal - Emitted with (recipe text, results file) when the user opens a run's setup. - view_wanted : Signal - Emitted with the name of the view to bring forward. - described : Signal - Emitted with what the open file can give, the kernel's ``describe_output``. - """ - - setup_opened = Signal(str, str) - view_wanted = Signal(str) - described = Signal(object) - - def __init__( # noqa: PLR0915 - the page's layout - self, bridge: ServiceBridge, parent: QWidget | None = None - ) -> None: - """Make the page, with no file.""" - super().__init__(parent) - self.bridge = bridge - self.path: str | None = None - self.capabilities: dict[str, object] | None = None - self._pending: dict[int, tuple[str, str]] = {} - self.options = PlotOptions() - self.plot_options = PlotOptionsPanel("results") - self.spectrogram_options = SpectrogramOptions() - self.spectrogram_options.changed.connect( - lambda gate, positions: self.plot_options.changed.emit( - replace(self.options, gate_fwhm=gate, positions=positions) - ) - ) - - self.open_button = QPushButton("Open results…") - self.open_button.setObjectName("open-results") - self.open_button.clicked.connect(self.choose) - self.setup_button = QPushButton("Open its setup") - self.setup_button.setObjectName("open-setup") - self.setup_button.setToolTip( - "Loads the recipe the file records, as resolved: the values that rebuild " - "this run." - ) - self.setup_button.clicked.connect(self.open_setup) - self.info = QLabel("No results file open.") - self.info.setObjectName("results-info") - self.info.setWordWrap(True) - self.runs = QListWidget() - self.runs.setObjectName("runs") - self.runs.itemActivated.connect( - lambda item: self.open(item.data(Qt.ItemDataRole.UserRole)) - ) - - self.overview = OverviewView() - self.compare = CompareView() - self.plane = PlaneView() - self.statistics = StatisticsView() - self.scan = ScanView() - self.plane.plane_wanted.connect(self._ask_plane) - self.plane.spectrogram_wanted.connect(self._ask_spectrogram) - self.plane.figure_wanted.connect(self._ask_figure) - self.statistics.figure_wanted.connect(self._ask_figure) - self.stats_selector = StatsSelector() - self.stats_selector.changed.connect(self.statistics.set_layout) - self.statistics.layout_changed.connect(self.stats_selector.set_layout) - - file = QWidget() - buttons = QGridLayout(file) - buttons.setContentsMargins(0, 0, 0, 0) - buttons.addWidget(self.open_button, 0, 0) - buttons.addWidget(self.setup_button, 0, 1) - buttons.addWidget(self.info, 1, 0, 1, 2) - self.runs.setMinimumHeight(80) - sections = QWidget() - column = QVBoxLayout(sections) - column.setContentsMargins(0, 0, 0, 0) - column.setSpacing(2) - for title, widget, stretch in ( - ("Results file", file, 0), - ("Runs in the workspace", self.runs, 1), - ("Plot options", self.plot_options, 0), - ("Spectrogram", self.spectrogram_options, 0), - ("Statistics panels", self.stats_selector, 0), - ): - section = Section(title) - section.add(widget) - column.addWidget(section, stretch) - scroll = QScrollArea() - scroll.setWidgetResizable(True) - scroll.setFrameShape(QFrame.Shape.NoFrame) - scroll.setWidget(sections) - layout = QVBoxLayout(self) - layout.setContentsMargins(4, 4, 0, 0) - layout.setSpacing(2) - layout.addWidget(QLabel("<b>Results</b>")) - layout.addWidget(scroll, 1) - bridge.replied.connect(self.on_reply) - self._update_buttons() - - def show_runs(self, runs: Sequence[RunEntry]) -> None: - """List the workspace's runs. - - Parameters - ---------- - runs : Sequence of RunEntry - The runs, newest first. - """ - self.runs.clear() - for run in runs: - if run.output is None: - continue - item = QListWidgetItem(run.name) - item.setData(Qt.ItemDataRole.UserRole, str(run.output)) - item.setToolTip(str(run.output)) - self.runs.addItem(item) - - def _update_buttons(self) -> None: - """Enable what the open file allows.""" - has_file = self.path is not None - recipe = bool(self.capabilities and self.capabilities.get("recipe")) - self.setup_button.setEnabled(has_file and recipe) - - def choose(self) -> None: - """Pick a results file and open it.""" - chosen, _ = QFileDialog.getOpenFileName( - self, "Open results", "", "solprop results (*.h5 *.hdf5);;All files (*)" - ) - if chosen: - self.open(chosen) - - def _ask(self, kind: str, payload: dict[str, object], purpose: str) -> None: - """Send a request about a file, remembering what it is for. - - Parameters - ---------- - kind : str - The handler. - payload : dict - Its arguments. - purpose : str - What the reply is for. - """ - request = self.bridge.request(kind, payload, key=f"results-{purpose}") - self._pending[request] = (purpose, str(payload.get("path"))) - - def open(self, path: str | Path, *, show: bool = True) -> None: - """Open a results file. - - Parameters - ---------- - path : str or pathlib.Path - The file. - show : bool, optional - Whether to bring its Overview forward. - """ - self.path = str(path) - self.capabilities = None - self.info.setText(f"{_short(self.path)}: reading…") - self.info.setToolTip(self.path) - self.overview.clear() - self.plane.clear() - self.statistics.clear() - self._update_buttons() - if show: - self.view_wanted.emit("results") - self._ask("describe_output", {"path": self.path}, "describe") - self._ask_overview() - self._ask("statistics", {"path": self.path}, "statistics") - - def _ask_overview(self) -> None: - """Ask for the open file's Overview, its power within the options' band.""" - if self.path is not None: - payload = {"path": self.path, "bandpass": self.options.bandpass} - self._ask("overview", payload, "overview") - - def apply_options(self, options: PlotOptions) -> None: - """Take new plot options, asking solprop again where they change its data. - - The bandpass changes what solprop computes for the Overview, and the axis - too for a plane; the rest only how the views draw. - - Parameters - ---------- - options : PlotOptions - The options. - """ - band = self.options.bandpass != options.bandpass - again = not self.options.same_request(options) - spectrogram = self.options.spectrogram() != options.spectrogram() - self.options = options - self.plot_options.set_options(options) - self.spectrogram_options.set_options(options) - self.overview.apply_options(options) - self.plane.apply_options(options) - if self.path is None: - return - if band: - self._ask_overview() - if again and self.plane.planes: - self._ask_plane(self.plane.index(), self.plane.selection()) - if spectrogram: - self.plane.ask_spectrogram() - - def open_scan(self, path: str | Path, *, show: bool = True) -> None: - """Open a scan's results file in the scan browser. - - Parameters - ---------- - path : str or pathlib.Path - The scan's file. - show : bool, optional - Whether to bring the browser forward. - """ - self.info.setText(f"{_short(str(path))}: reading the scan…") - self.scan.status.setText("Reading the scan…") - if show: - self.view_wanted.emit("scan") - self._ask("scan_overview", {"path": str(path)}, "scan") - - def _ask_plane(self, index: int, modes: object) -> None: - """Ask for one plane of the open file. - - Parameters - ---------- - index : int - The plane. - modes : object - The mode selection. - """ - if self.path is not None: - payload = { - "path": self.path, - "index": index, - "modes": modes, - **self.options.request(), - } - self._ask("plane", payload, "plane") - - def _ask_spectrogram(self, index: int, modes: object) -> None: - """Ask for a plane's spectrogram, as the plot options set it. - - Parameters - ---------- - index : int - The plane. - modes : object - The mode selection; a sum takes the first mode. - """ - if self.path is None or self.capabilities is None: - return - options = self.options - if self.capabilities.get("basis") == "spatial": - # A beam has no one field to gate: its intensity across the centre. - body = {"path": self.path, "index": index, "bandpass": options.bandpass} - self._ask("beam", body, "spectrogram") - return - low, high = options.time_limits - payload = { - "path": self.path, - "index": index, - "modes": modes, - "axis": options.axis, - "bandpass": options.bandpass, - "time_range": None if low is None or high is None else (low, high), - "gate_fwhm": options.gate_fwhm, - "positions": options.positions, - } - self._ask("spectrogram", payload, "spectrogram") - - def _ask_figure(self, figure: Mapping[str, object]) -> None: - """Ask for one of solprop's plots of the open file as a figure. - - Parameters - ---------- - figure : Mapping - The figure's ``file``, ``plot`` and its keys. - """ - if self.path is not None: - self._ask("result_figure", {"path": self.path, **figure}, "figure") - - def open_setup(self) -> None: - """Ask for the recipe the open file records, as resolved.""" - if self.path is not None: - self._ask("recipe_of", {"path": self.path, "resolved": True}, "setup") - - def add_to_compare(self) -> None: - """Add the open file's run to the compare view.""" - if self.path is not None: - self._ask("overview", {"path": self.path}, "compare") - - def on_reply(self, reply: Reply) -> None: - """Take a kernel reply to one of the page's requests. - - Parameters - ---------- - reply : solprop.service.messages.Reply - The reply; replies to other requests are ignored. - """ - entry = self._pending.pop(reply.request_id, None) - if entry is None: - return - purpose, path = entry - if purpose == "scan": - self._show_scan(path, reply) - return - if not reply.ok: - if purpose in ("plane", "spectrogram"): - self.plane.show_error(f"{purpose}: {reply.error}") - else: - self.info.setText(f"{_short(path)}: {reply.error}") - return - value = reply.value - if path != self.path and purpose != "compare": - return # a reply about the file shown before - if purpose in ("plane", "spectrogram", "statistics", "figure"): - self._show_view_reply(purpose, value) - return - if purpose == "describe" and path == self.path and isinstance(value, dict): - self._show_description(path, value) - elif purpose == "overview" and path == self.path and isinstance(value, dict): - self.overview.set_rows(value.get("axes", {}), value.get("rows", [])) # pyright: ignore[reportArgumentType] - elif purpose == "compare" and isinstance(value, dict): - name = Path(path).parent.name - self.compare.add_run(name, value.get("axes", {}), value.get("rows", [])) # pyright: ignore[reportArgumentType] - self.view_wanted.emit("compare") - elif purpose == "setup" and isinstance(value, str): - self.setup_opened.emit(value, path) - - def _show_scan(self, path: str, reply: Reply) -> None: - """Show a scan's overview in the browser, or why there is none. - - Parameters - ---------- - path : str - The scan's file. - reply : solprop.service.messages.Reply - The ``scan_overview`` reply. - """ - if reply.ok and isinstance(reply.value, Mapping): - self.scan.set_scan(reply.value) - self.info.setText(f"{_short(path)}: a scan") - else: - self.scan.show_error(f"No scan: {reply.error}") - - def _show_description(self, path: str, value: dict[str, object]) -> None: - """Show what a results file holds, and offer its planes and views. - - Parameters - ---------- - path : str - The file. - value : dict - The kernel's ``describe_output`` reply. - """ - self.capabilities = value - outcome = value.get("outcome") or {} - status = outcome.get("status") if isinstance(outcome, dict) else None - text = ( - f"{_short(path)}: " - f"{value.get('simulation_kind')} run, {status or 'no outcome'}" - ) - message = outcome.get("message") if isinstance(outcome, dict) else None - if message: - text += f" ({message})" - planes = value.get("field_planes") or [] - text += f"; {len(planes)} planes with fields" # pyright: ignore[reportArgumentType] - if not value.get("recipe"): - text += "; it records no recipe (a file from a script)" - self.info.setText(text) - self._update_buttons() - z: list[float] = list(value.get("z") or []) # pyright: ignore[reportArgumentType] - planes = [int(p) for p in planes] # pyright: ignore[reportGeneralTypeIssues] - self.plane.set_planes( - planes, - [z[p] for p in planes if p < len(z)], - list(value.get("labels") or []), # pyright: ignore[reportArgumentType] - ) - self.overview.set_spatial(value.get("basis") == "spatial") - self.described.emit(value) - - def _show_view_reply(self, purpose: str, value: object) -> None: - """Hand a view its reply. - - Parameters - ---------- - purpose : str - ``"plane"``, ``"spectrogram"``, ``"statistics"`` or - ``"figure"``. - value : object - The reply's value. - """ - if purpose == "figure": - written: Sequence[str] = value if isinstance(value, list) else [] - self.info.setText("Wrote " + ", ".join(_short(f) for f in written)) - elif not isinstance(value, Mapping): - return - elif purpose == "plane": - self.plane.show_plane(value) - elif purpose == "spectrogram": - self.plane.show_spectrogram(value) - else: - self.statistics.set_statistics(value) - - -def _short(path: str) -> str: - """Name a results file by its folder and its name. - - Parameters - ---------- - path : str - The file. - - Returns - ------- - str - ``folder/name``. - - Examples - -------- - >>> _short("/a/b/2026-11-02-rdw/run.h5") - '2026-11-02-rdw/run.h5' - """ - file = Path(path) - return f"{file.parent.name}/{file.name}" diff --git a/gui/src/solprop_gui/ui/run_panel.py b/gui/src/solprop_gui/ui/run_panel.py index e8b036f85..2eabe19e7 100644 --- a/gui/src/solprop_gui/ui/run_panel.py +++ b/gui/src/solprop_gui/ui/run_panel.py @@ -5,12 +5,13 @@ """The run: pre-flight, run, stop, resume, and what the live view is fed. The panel runs the recipe revision current when Run is pressed, in a new folder of the -workspace, in a worker of its own (design 10). The panel's controls sit on the -Propagate step, its actions also on the window's toolbar; its live view, log and -progress are shown by the window, among its views, in its bottom panel and in its -status bar. Its execution state is the window's -(:mod:`solprop.service.states`); whether the file can be continued is asked of -solprop after every ending, and Resume follows that answer alone. +workspace, as a job of its own that a machine's helper starts and the panel follows +from the run's record (design 13.4). The window shows the panel's state, progress, +steps and boundary lamp on the Run stage's strip and its live view on the Overview +page, and its primary button runs, stops and resumes through the panel. Its execution +state is the window's (:mod:`solprop.service.states`); whether the file can be +continued is asked of solprop after every ending, and Resume follows that answer +alone. """ import os @@ -32,9 +33,10 @@ ) from solprop.service.machines import LOCAL, Machine from solprop.service.messages import Event, Reply +from solprop.service.recipes import is_scan from solprop.service.reduce import Display from solprop.service.states import ACTIVE, ExecutionState, advance, failure_advice -from solprop.service.worker import OUTPUT, RunSpec +from solprop.service.worker import OUTPUT, SCAN_OUTPUT, RunSpec from solprop_gui.model.plot_options import PlotOptions from solprop_gui.model.workspace import new_run_folder, remote_run_folder @@ -95,7 +97,8 @@ class RunPanel(QWidget): point_seen : Signal Emitted with a scan's ``point`` and ``scan_started`` events' data. ended : Signal - Emitted with the results file when a run ends, however it ends. + Emitted with the results file when a run ends, however it ends; with an + empty string when the run left none. state_changed : Signal Emitted with the new execution state's value. workspace_changed : Signal @@ -123,6 +126,8 @@ def __init__( # noqa: PLR0915 - the panel's layout self.state = ExecutionState.QUEUED self.run_id: str | None = None self.folder: PurePath | None = None + # Whether the run is a scan, from what was started or taken over. + self.scan = False self.client: MachineRun | None = None # Where new runs go: another machine, or None for this computer. self.machine: Machine | None = None @@ -136,7 +141,6 @@ def __init__( # noqa: PLR0915 - the panel's layout self.resume_mode: object = None self.can_run = False self._pending: dict[int, str] = {} - self._last_index = -1 self._z_end = 0.0 self.options = PlotOptions() self.report: Callable[[str, str, str], None] = self._report @@ -182,8 +186,8 @@ def __init__( # noqa: PLR0915 - the panel's layout self.workspace_button.clicked.connect(self.choose_workspace) self._show_workspace() - # Shown by the window: the progress in its status bar, the live view among - # its views, the log in its bottom panel. + # Shown by the window: the state, bar, steps, sparkline and lamp on the Run + # stage's strip, the live view on the Overview page. self.lamp = QLabel("boundary: ok") self.lamp.setToolTip("The time window's edges, as solprop's monitor reports.") self.progress = QProgressBar() @@ -276,7 +280,7 @@ def _set_state(self, state: ExecutionState) -> None: def _action( self, text: str, drawing: str, slot: Callable[[], object], colour: QColor ) -> QAction: - """Make one of the panel's actions, shared with the window's toolbar. + """Make one of the panel's actions. Parameters ---------- @@ -401,8 +405,7 @@ def start(self) -> None: threads=self.threads, reductions=tuple(self.reductions), owner=self._owner(), - ), - fresh=True, + ) ) def resume(self) -> None: @@ -423,8 +426,7 @@ def resume(self) -> None: resume=mode, # pyright: ignore[reportArgumentType] display=self.display(), owner=self._owner(), - ), - fresh=False, + ) ) def display(self) -> Display: @@ -486,20 +488,17 @@ def _progress(self, value: int, *, reset: bool = False) -> None: for bar in (self.progress, self.bar): bar.setValue(min(max(value, 0), 1000)) - def _launch(self, spec: RunSpec, *, fresh: bool) -> None: - """Start a worker. + def _launch(self, spec: RunSpec) -> None: + """Start a run, new or continued, through its machine's helper. Parameters ---------- spec : solprop.service.worker.RunSpec What it runs. - fresh : bool - Whether it is a new run, rather than a continued one. """ self.run_id = spec.run_id self.folder = self._place(spec.folder) - if fresh: - self._last_index = -1 + self.scan = is_scan(spec.recipe) self._z_end = 0.0 self.lamp.setText("boundary: ok") self.lamp.setStyleSheet("") @@ -561,7 +560,7 @@ def attach_on(self, machine: Machine, run: Mapping[str, object]) -> bool: self.client = self.bridge.attach_on(machine, run_id, folder) self.run_id = run_id self.folder = self._place(folder) - self._last_index = -1 + self.scan = bool(run.get("scan")) self.view.clear() self.log.clear() self.state = ExecutionState.RUNNING @@ -591,6 +590,7 @@ def resume_on(self, machine: Machine, run: Mapping[str, object]) -> bool: self.run_machine = None if machine.local else machine self.run_id = str(run["run_id"]) self.folder = self._place(str(run["folder"])) + self.scan = False # a scan is never continued self.state = ExecutionState.STOPPED # an ended run, the panel's now if not machine.local: self.bridge.know_folder(machine.name, str(run["folder"])) @@ -642,11 +642,6 @@ def on_event(self, event: Event) -> None: if event.kind == "axes": self.view.set_axes(data) elif event.kind == "row": - index = int(data["index"]) # pyright: ignore[reportArgumentType] - if index > self._last_index + 1 and self.client is not None: - # Rows were dropped on the way: the worker replays them. - self.client.subscribe(self._last_index + 1) - self._last_index = max(self._last_index, index) self.view.add_row(data) z = float(data["z"]) # pyright: ignore[reportArgumentType] self.steps.setText( @@ -709,7 +704,7 @@ def _report(self, title: str, message: str, detail: str) -> None: """ box = QMessageBox(QMessageBox.Icon.Warning, title, message, parent=self) box.setObjectName("run-failed") - box.setInformativeText("The run's log, in the bottom panel, has it too.") + box.setInformativeText("The run's log, on the Run health page, has it too.") if detail: box.setDetailedText(detail) box.setTextInteractionFlags(Qt.TextInteractionFlag.TextSelectableByMouse) @@ -767,7 +762,7 @@ def _ended(self, event: Event) -> None: "finished": "complete", "stopped": "stopped", "failed": "failed", - "lost": "the worker was lost", + "lost": "lost", }[event.kind] text = f"{self.run_id}: {words}" if event.kind == "failed" and message: @@ -781,15 +776,15 @@ def _ended(self, event: Event) -> None: detail, ) elif event.kind == "lost": - advice = failure_advice("lost", "", event.data.get("exitcode")) + advice = failure_advice("lost", message) self.log.appendPlainText(advice) self.report(f"The run {self.run_id} stopped short", advice, "") self.state_label.setText(text) if event.kind == "finished": self._progress(1000) - if self.folder is not None and event.data.get("scan"): - # A scan's points are run again with retry_failed, not resumed. - self.ended.emit(str(event.data["path"])) + if self.folder is not None and (self.scan or event.data.get("scan")): + # A scan is never continued: its file opens as it ended, unchecked. + self.ended.emit(self._results(SCAN_OUTPUT, event.data)) elif self.folder is not None: path = ( (self.folder / OUTPUT).as_posix() @@ -800,10 +795,23 @@ def _ended(self, event: Event) -> None: "check_resume", {"path": path}, key="panel-resume" ) self._pending[request] = "check_resume" - self.ended.emit(path) + self.ended.emit(self._results(OUTPUT, event.data)) self.reread() # a band changed while it ran self._update_buttons() + def _results(self, name: str, data: Mapping[str, object]) -> str: + """Return the ended run's results file, or an empty string where it wrote none. + + A file of this computer's is looked for; a run on another machine says in its + ending whether it wrote one (``output``). + """ + folder = self.folder + if folder is None: + return "" + if self.run_machine is None: + return str(folder / name) if Path(folder, name).exists() else "" + return (folder / name).as_posix() if data.get("output") else "" + def on_reply(self, reply: Reply) -> None: """Take a kernel reply to one of the panel's requests. diff --git a/gui/src/solprop_gui/ui/runs_window.py b/gui/src/solprop_gui/ui/runs_window.py index bc9bca460..4c82ff05c 100644 --- a/gui/src/solprop_gui/ui/runs_window.py +++ b/gui/src/solprop_gui/ui/runs_window.py @@ -490,7 +490,7 @@ def _fetch(self) -> None: dialog.setMinimumDuration(300) def progress(have: int, total: int) -> None: - """Show how far the copy has got, on the window's thread. + """Show how far the copy has got. Parameters ---------- @@ -499,8 +499,7 @@ def progress(have: int, total: int) -> None: total : int The file's size, bytes. """ - share = int(1000 * have / total) if total else 1000 - QTimer.singleShot(0, lambda: dialog.setValue(share)) + dialog.setValue(int(1000 * have / total) if total else 1000) def done(value: object, error: object) -> None: """Say what came of the request, and list again. diff --git a/gui/src/solprop_gui/ui/workflow_window.py b/gui/src/solprop_gui/ui/workflow_window.py index afe935fcc..a403a5be3 100644 --- a/gui/src/solprop_gui/ui/workflow_window.py +++ b/gui/src/solprop_gui/ui/workflow_window.py @@ -6,15 +6,15 @@ A problem class decides what is on screen, so nothing here asks which class it is drawing. The window holds a :class:`~solprop_gui.ui.document.SetupDocument` for the open -setup and moves between the stages; each stage only shows. It is built beside the step -window, which stays runnable until every route has moved here. +setup and moves between the stages; each stage only shows. """ import contextlib from collections.abc import Mapping, Sequence from pathlib import Path, PurePosixPath -from PySide6.QtCore import Qt, QTimer, QUrl +from pyqtgraph.util.garbage_collector import GarbageCollector +from PySide6.QtCore import Qt, QUrl, Signal from PySide6.QtGui import QAction, QCloseEvent, QDesktopServices, QKeySequence from PySide6.QtWidgets import ( QFileDialog, @@ -47,7 +47,7 @@ from solprop_gui.classes.workflow import Progress, Stage, primary_action, stage_open from solprop_gui.model.recipe import RecipeModel from solprop_gui.model.scans import profile_points -from solprop_gui.model.workspace import DEFAULT_WORKSPACE, list_runs, slug +from solprop_gui.model.workspace import DEFAULT_WORKSPACE, slug from solprop_gui.registry.pages import label from solprop_gui.registry.routes import card_of from solprop_gui.ui.analyse import AnalyseStage @@ -67,7 +67,7 @@ from solprop_gui.ui.sheet import SheetStage from solprop_gui.ui.theme import STYLE, app_settings, load_font, named_label, repolish -__all__ = ["WorkflowWindow"] +__all__ = ["WorkflowWindow", "collect_between_events"] _RECENT_SETUPS = "recent-setups" """The setting that lists recent setups.""" @@ -106,8 +106,13 @@ class WorkflowWindow(QMainWindow): Whether a run has been started from the open setup. has_results : bool Whether a results file is open. + runs_listed : Signal + Emitted when Home has listed this computer's runs afresh. """ + runs_listed = Signal() + _listed = Signal(int, object) + def __init__( # noqa: PLR0915 - the window's parts self, bridge: ServiceBridge | None = None, @@ -133,6 +138,8 @@ def __init__( # noqa: PLR0915 - the window's parts self._own_run = False self._failed = False self._pending: dict[int, str] = {} + self._listing = 0 + self._follow_going = False saved = self.settings.value("workspace") self.workspace = workspace or (Path(str(saved)) if saved else DEFAULT_WORKSPACE) @@ -243,6 +250,7 @@ def __init__( # noqa: PLR0915 - the window's parts self.session.setup_found.connect(self._file_has_setup) self.bridge.kernel_lost.connect(self._kernel_lost) self.bridge.replied.connect(self._on_reply) + self._listed.connect(self._runs_listed) self.setWindowTitle("solprop") self.resize(1280, 800) @@ -252,12 +260,11 @@ def __init__( # noqa: PLR0915 - the window's parts self._ask_kernel("gases", {}, "gases") self._ask_kernel("run_options", {}, "run options") self._show_machines(str(self.settings.value("machine") or LOCAL)) - self.refresh_home() - self.show_stage(Stage.HOME) # This computer's helper, warm before the first run; then a run the last - # window left going is taken over, found from its record. + # window left going is taken over, found from its record by Home's listing. self.bridge.hub.ensure(Machine(LOCAL)) - self._find_going_run() + self._follow_going = True + self.show_stage(Stage.HOME) # ------------------------------------------------------------------ the frame @@ -602,7 +609,7 @@ def _ask_kernel( """ self._pending[self.bridge.request(kind, payload, key=purpose)] = purpose - def _on_reply(self, reply: Reply) -> None: + def _on_reply(self, reply: Reply) -> None: # noqa: PLR0912 - one per purpose """Take a kernel reply to one of the window's requests. Parameters @@ -611,7 +618,11 @@ def _on_reply(self, reply: Reply) -> None: The reply; replies to other requests are ignored. """ purpose = self._pending.pop(reply.request_id, None) - if purpose == "examples" and reply.ok: + asked = _asked_for(purpose) + if asked is not None and reply.error is not None: + # A superseded reply has no error: a newer request answers instead. + self.notify(f"solprop could not give {asked}: {reply.error}") + elif purpose == "examples" and reply.ok: self._examples_arrived(reply.value) # pyright: ignore[reportArgumentType] elif purpose is not None and purpose.startswith("warm-") and reply.ok: self._ask_kernel("check", {"text": str(reply.value)}, f"warmed-{purpose}") @@ -842,19 +853,13 @@ def choose_setup(self) -> None: self.open_setup(chosen) def open_setup(self, path: str) -> None: - """Open a setup file; a route that is no class's goes to the step window. + """Open a setup file; a route that is no class's opens on the generic form. Parameters ---------- path : str The file. """ - try: - model = RecipeModel.load(path) - except (OSError, ValueError) as error: - self._say(f"Cannot open {path}: {error}") - return - del model self.document.open_recipe(path) def choose_results(self) -> None: @@ -1111,10 +1116,48 @@ def _workspace_changed(self, folder: str) -> None: self.refresh_home() def refresh_home(self) -> None: - """List the recent runs and setups on Home.""" - self.home.show_runs(list_runs(self.run_panel.workspace)) + """List the recent setups on Home, and this computer's runs, read on a thread. + + The first listing after the window opens also follows the newest run on this + computer still going (:meth:`_find_going_run`). + """ + import threading # noqa: PLC0415 - only here + + from solprop.service.runs import list_runs # noqa: PLC0415 - light + saved = self.settings.value(_RECENT_SETUPS) or [] self.home.show_setups([saved] if isinstance(saved, str) else list(saved)) # pyright: ignore[reportArgumentType, reportCallIssue] + self._listing += 1 + listing = self._listing + workspace = self.run_panel.workspace.expanduser() + + def look() -> None: + """List the workspace's runs, and hand them to the window's thread.""" + runs: list[dict[str, object]] = [] + with contextlib.suppress(OSError, ValueError): + runs = list_runs(workspace, None) + with contextlib.suppress(RuntimeError): # the window has been deleted + self._listed.emit(listing, runs) + + threading.Thread(target=look, daemon=True).start() + + def _runs_listed(self, listing: int, runs: list[dict[str, object]]) -> None: + """Show a listing of this computer's runs on Home, unless a newer one is coming. + + Parameters + ---------- + listing : int + Which listing it is; an older one than the last asked for is dropped. + runs : list of dict + The runs' summaries, newest first. + """ + if listing != self._listing: + return + self.home.show_runs(runs) + if self._follow_going: + self._follow_going = False + self._find_going_run(runs) + self.runs_listed.emit() # ------------------------------------------------------------------ runs @@ -1160,18 +1203,27 @@ def _run_ended(self, path: str) -> None: Parameters ---------- path : str - Its results file. + Its results file; empty where it wrote none. """ + # Every ending of a scan leaves scan mode, so the next Run runs the setup once. + scanning, self._scanning = self._scanning, False if self._leaving_run: # A run stopped to open something else: it is listed, and not shown. self._leaving_run = False - self._scanning = False self.refresh_home() self._refresh() return - if Path(path).name == SCAN_OUTPUT: - self._scanning = False - self.open_scan(path) + if scanning or Path(path).name == SCAN_OUTPUT: + if path: + self.open_scan(path) + else: + self.scans.progress.setText("The scan ended before it wrote anything.") + self.refresh_home() + self._refresh() + return + if not path: + # Nothing to open: the run ended before it wrote its file. + self.overview.end_of_run() self.refresh_home() self._refresh() return @@ -1227,40 +1279,23 @@ def _file_has_setup(self, text: str, path: str) -> None: self.document.set_model(model, base=str(Path(path).parent)) self.has_results = True - def _find_going_run(self) -> None: - """Look, on a thread, for a run on this computer still going, and follow it.""" - import threading # noqa: PLC0415 - only here + def _find_going_run(self, runs: list[dict[str, object]]) -> None: + """Follow the newest run on this computer that is still going, if any. - from solprop.service.runs import list_runs # noqa: PLC0415 - light - - workspace = self.run_panel.workspace.expanduser() - found: list[list[dict[str, object]]] = [] - - def look() -> None: - """List the workspace's runs.""" - with contextlib.suppress(OSError, ValueError): - found.append(list_runs(workspace, None)) - - thread = threading.Thread(target=look, daemon=True) - thread.start() - - def check() -> None: - """Take over the newest run still going, once the list is read.""" - if thread.is_alive(): - QTimer.singleShot(100, check) - return - runs = found[0] if found else [] - going = [ - run - for run in runs - if run.get("state") in {"starting", "running"} and run.get("record") - ] - if going and self.run_panel.attach_on(Machine(LOCAL), going[0]): - self.has_run = True - self.show_stage(Stage.RUN) - self.notify(f"Following {going[0]['run_id']}, still going.") - - QTimer.singleShot(100, check) + Parameters + ---------- + runs : list of dict + This computer's runs' summaries, newest first. + """ + going = [ + run + for run in runs + if run.get("state") in {"starting", "running"} and run.get("record") + ] + if going and self.run_panel.attach_on(Machine(LOCAL), going[0]): + self.has_run = True + self.show_stage(Stage.RUN) + self.notify(f"Following {going[0]['run_id']}, still going.") # ------------------------------------------------------------------ machines @@ -1530,6 +1565,22 @@ def closeEvent(self, event: QCloseEvent) -> None: # noqa: N802 - Qt's name event.accept() +def collect_between_events() -> GarbageCollector: + """Have Python's garbage collected on a timer, between Qt's events. + + Whatever hosts a :class:`WorkflowWindow` calls this before making it, and keeps + the collector while the window lives. Automatic collection is turned off: a plot + dropped while its scene still had an event queued could otherwise be freed inside + that event's handler, deleting the scene under Qt's feet. + + Returns + ------- + pyqtgraph.util.garbage_collector.GarbageCollector + The collector; stop its ``timer`` once the window has closed. + """ + return GarbageCollector(interval=1.0) + + _WARM_EXAMPLES = ("rdw", "filament") """Examples checked once as the window opens: a route's first check costs the most (about 0.9 s on the capillary and 0.5 s on the radial route), and is then the @@ -1541,9 +1592,26 @@ def closeEvent(self, event: QCloseEvent) -> None: # noqa: N802 - Qt's name _NOTICE_MS = 20_000 """How long a passing notice stays, in milliseconds.""" +_ASKED = { + "examples": "the examples", + "gases": "the list of gases", + "run options": "the run options", + "curve": "the curve", + "template": "the class's example", +} +"""What the window's own requests ask for, by purpose, as the foot of the window names +it when one fails.""" + + +def _asked_for(purpose: str | None) -> str | None: + """Return what a request asked for, as its failure names it, or ``None``.""" + if purpose is not None and purpose.startswith("warm-"): + return f"the example {purpose.removeprefix('warm-')}" + return _ASKED.get(purpose or "") + def _class_of(model: RecipeModel) -> ProblemClass: - """Return a recipe's class: one of the four, or Other geometry's for its route. + """Return a recipe's class: a catalogued one, or Other geometry's for its route. Parameters ---------- @@ -1559,5 +1627,5 @@ def _class_of(model: RecipeModel) -> ProblemClass: found = class_of(model.route, build) if found is not None: return found - card = card_of(model.route, build, enabled_only=False) + card = card_of(model.route, build) return other_class(model.route, model.route if card is None else card.title, build) diff --git a/gui/src/solprop_gui/views/compare.py b/gui/src/solprop_gui/views/compare.py deleted file mode 100644 index f2f633a1a..000000000 --- a/gui/src/solprop_gui/views/compare.py +++ /dev/null @@ -1,114 +0,0 @@ -# SPDX-FileCopyrightText: 2026 John C. Travers and contributors -# -# SPDX-License-Identifier: GPL-3.0-or-later - -"""Compare runs: their last planes' spectra and power, overlaid (design 11.2, Q10). - -The spectra share **one** dB reference, the highest first-plane peak among the runs -shown, so a difference in energy stays visible; the view says so. Each run is reduced -on its own display bins, as its overview is. -""" - -from collections.abc import Mapping, Sequence - -import numpy as np -import pyqtgraph as pg -from PySide6.QtWidgets import QVBoxLayout, QWidget - -from solprop_gui.views.live import decibels -from solprop_gui.views.plotting import PALETTE, HoverLayout - -__all__ = ["CompareView"] - - -class CompareView(QWidget): - """Overlaid lines of several runs. - - Parameters - ---------- - parent : PySide6.QtWidgets.QWidget or None, optional - The owner. - """ - - def __init__(self, parent: QWidget | None = None) -> None: - """Make the two plots, empty.""" - super().__init__(parent) - self.runs: dict[ - str, tuple[Mapping[str, object], list[Mapping[str, object]]] - ] = {} - self.plots = HoverLayout() - self.spectra = self.plots.ci.addPlot(row=0, col=0) - self.spectra.setTitle("Last plane: spectral energy density (dB, one reference)") - self.spectra.setLabel("bottom", "Wavelength (nm)") - self.spectra.setLabel("left", "dB") - self.spectra_legend = self.spectra.addLegend() - self.power = self.plots.ci.addPlot(row=1, col=0) - self.power.setTitle("Last plane: power") - self.power.setLabel("bottom", "Time (fs)") - self.power.setLabel("left", "Power (GW)") - self.power_legend = self.power.addLegend() - layout = QVBoxLayout(self) - layout.setContentsMargins(0, 0, 0, 0) - layout.addWidget(self.plots) - - def add_run( - self, - name: str, - axes: Mapping[str, object], - rows: Sequence[Mapping[str, object]], - ) -> None: - """Add a run, or replace one of the same name. - - Parameters - ---------- - name : str - The run's name in the legend. - axes : Mapping - Its display bins' centres. - rows : Sequence of Mapping - Its overview rows. - """ - if rows: - self.runs[name] = (axes, sorted(rows, key=lambda r: int(r["index"]))) # pyright: ignore[reportArgumentType] - self._redraw() - - def clear(self) -> None: - """Remove every run.""" - self.runs = {} - self._redraw() - - def reference(self) -> float: - """Return the shared dB reference. - - Returns - ------- - float - The largest first-plane density peak among the runs; 0 with none. - """ - peaks = [ - float(np.max(np.asarray(rows[0]["density"]["wavelength"]))) # pyright: ignore[reportIndexIssue] - for _, rows in self.runs.values() - ] - return max(peaks, default=0.0) - - def _redraw(self) -> None: - """Redraw every run's lines.""" - self.spectra.clear() - self.power.clear() - self.spectra_legend.clear() - self.power_legend.clear() - reference = self.reference() - for number, (name, (axes, rows)) in enumerate(self.runs.items()): - pen = PALETTE[number % len(PALETTE)] - last = rows[-1] - wavelength = np.asarray(axes["wavelength"], dtype=float) * 1e9 - time = np.asarray(axes["time"], dtype=float) * 1e15 - density = np.asarray(last["density"]["wavelength"]) # pyright: ignore[reportIndexIssue] - db = np.maximum(decibels(density, reference), -80.0) - self.spectra.plot(wavelength, db, pen=pg.mkPen(pen, width=1.5), name=name) - self.power.plot( - time, - np.asarray(last["power"]) / 1e9, - pen=pg.mkPen(pen, width=1.5), - name=name, - ) diff --git a/gui/src/solprop_gui/views/compression.py b/gui/src/solprop_gui/views/compression.py index 84c474660..571b6e153 100644 --- a/gui/src/solprop_gui/views/compression.py +++ b/gui/src/solprop_gui/views/compression.py @@ -4,7 +4,7 @@ """The Compression view: the pulse before, after the compressor, and at its limit. -The Post-process step's result (:func:`solprop.service.postprocess.compress_chain`): +The Compress page's result (:func:`solprop.service.postprocess.compress_chain`): the power before the compressor, after it and at the transform limit, with solprop's width and peak of each, and what each searched element found. """ diff --git a/gui/src/solprop_gui/views/plane.py b/gui/src/solprop_gui/views/plane.py deleted file mode 100644 index 658dbff6a..000000000 --- a/gui/src/solprop_gui/views/plane.py +++ /dev/null @@ -1,650 +0,0 @@ -# SPDX-FileCopyrightText: 2026 John C. Travers and contributors -# -# SPDX-License-Identifier: GPL-3.0-or-later - -"""The Plane view: one saved plane's spectrum, power, phase and spectrogram. - -A results file's field planes are stepped through with a slider (design 11.2); for the -plane shown the kernel gives the spectral density, the power and the spectral phase -from :mod:`solprop.processing`, and the spectrogram (``get_spectrogram``) drawn here -as an image to zoom and read, with each plane. Compression is the Post-process step's. -A mode sum has a power and a spectrum but no phase or field, so the phase and the -spectrogram take the first mode then, and say so. -""" - -import csv -from collections.abc import Mapping, Sequence -from pathlib import Path - -import numpy as np -import pyqtgraph as pg -from PySide6.QtCore import QRectF, Qt, Signal -from PySide6.QtWidgets import ( - QComboBox, - QFileDialog, - QHBoxLayout, - QLabel, - QSlider, - QSplitter, - QVBoxLayout, - QWidget, -) - -from solprop_gui.model.plot_options import UNITS, PlotOptions -from solprop_gui.registry.units import si -from solprop_gui.views.live import set_range -from solprop_gui.views.plotting import ( - PALETTE, - HoverLayout, - choose_figure, - colormap, - curve_lookup, -) - -__all__ = ["PlaneView"] - -_C = 299_792_458.0 - -PHASE_FLOOR = 1e-3 -"""The share of the spectrum's peak below which the phase is not drawn: noise there.""" - - -class SpectrogramPlot: - """A plane's spectrogram as an image: zoom, pan and a readout, in dB or linear. - - Parameters - ---------- - layout : solprop_gui.views.plotting.HoverLayout - The layout it is drawn in. - """ - - def __init__(self, layout: HoverLayout) -> None: - """Make the plot, its image and colour bar.""" - self.plot = layout.add_plot(0, 0, "Spectrogram") - self.plot.setLabel("bottom", "Time (fs)") - self.image = pg.ImageItem(axisOrder="row-major") - self.plot.addItem(self.image) - self.bar = pg.ColorBarItem( - colorMap=colormap("viridis"), label="dB", interactive=True, width=12 - ) - self.bar.setImageItem(self.image, insert_in=self.plot) - self.data: Mapping[str, object] | None = None - self.shown = np.zeros((0, 0)) - self.unit = 1.0 - layout.add_readout(self.plot, self.lookup) - - def show(self, data: Mapping[str, object], options: PlotOptions) -> None: - """Draw a spectrogram, or a beam's intensity across its centre, as scaled. - - Parameters - ---------- - data : Mapping - The kernel's ``spectrogram`` reply (``t``, ``x``, ``values`` and a - spectral ``axis``) or its ``beam`` reply (an ``axis`` of ``"x"`` or - ``"r"``, in m). - options : PlotOptions - The scale, floor and ranges. - """ - self.data = data - self.redraw(options) - - def redraw(self, options: PlotOptions) -> None: - """Draw the spectrogram held with new options. - - Parameters - ---------- - options : PlotOptions - The scale, floor and ranges. - """ - if self.data is None: - return - data = self.data - axis = str(data["axis"]) - spectral = axis in UNITS - self.unit = UNITS[axis][1] if spectral else 1e-3 - t = np.asarray(data["t"], dtype=float) * 1e15 - x = np.asarray(data["x"], dtype=float) / self.unit - values = np.asarray(data["values"], dtype=float) - peak = float(values.max()) if values.size and values.max() > 0 else 1.0 - if options.scale == "dB": - floor = options.floor - self.shown = np.clip( - 10 * np.log10(np.maximum(values / peak, 1e-30)), floor, 0.0 - ) - levels, unit = (floor, 0.0), "dB" - else: - self.shown = values / peak - levels, unit = (0.0, 1.0), "relative" - self.image.setImage(self.shown, autoLevels=False) - self.image.setRect(QRectF(t[0], x[0], float(t[-1] - t[0]), float(x[-1] - x[0]))) - self.bar.setLevels(levels) - self.bar.getAxis("left").setLabel(unit) - if spectral: - name = "Wavelength" if axis == "wavelength" else "Frequency" - self.plot.setLabel("left", f"{name} ({UNITS[axis][0]})") - mode = data.get("mode") - gate = float(data.get("gate_fwhm") or 0.0) * 1e15 # pyright: ignore[reportArgumentType] - self.plot.setTitle(f"Spectrogram, mode {mode}, gate {gate:.3g} fs") - else: # a beam's intensity across its centre, against time - self.plot.setLabel("left", f"{axis} (mm)") - self.plot.setTitle("Intensity across the beam's centre") - self.plot.getViewBox().autoRange(items=[self.image], padding=0) - set_range(self.plot, "x", options.shown_limits("time")) - if axis == options.axis: - set_range(self.plot, "y", options.shown_limits("spectral")) - - def lookup(self, x: float, y: float) -> tuple[float, float, str] | None: - """Read the map's value under the mouse. - - Parameters - ---------- - x, y : float - The mouse, in fs and the axis's unit. - - Returns - ------- - tuple or None - The point and its label; ``None`` off the map. - """ - if self.data is None or self.shown.size == 0: - return None - t = np.asarray(self.data["t"], dtype=float) * 1e15 - rows = np.asarray(self.data["x"], dtype=float) / self.unit - if not (t[0] <= x <= t[-1] and rows[0] <= y <= rows[-1]): - return None - column = int(np.argmin(np.abs(t - x))) - row = int(np.argmin(np.abs(rows - y))) - return x, y, f"{x:.1f} fs, {y:.4g}\n{self.shown[row, column]:.3g}" - - def clear(self) -> None: - """Forget the spectrogram.""" - self.data = None - self.shown = np.zeros((0, 0)) - self.image.clear() - self.plot.setTitle("Spectrogram") - - -class PlaneView(QWidget): - """One plane of a results file. - - Parameters - ---------- - parent : PySide6.QtWidgets.QWidget or None, optional - The owner. - - Attributes - ---------- - plane_wanted : Signal - Emitted with the plane's index and the mode selection. - spectrogram_wanted : Signal - Emitted with the plane's index and the mode selection, with each plane. - figure_wanted : Signal - Emitted with a figure's ``file``, ``plot``, ``z`` and ``modes``. - """ - - plane_wanted = Signal(int, object) - spectrogram_wanted = Signal(int, object) - figure_wanted = Signal(object) - - def __init__(self, parent: QWidget | None = None) -> None: # noqa: PLR0915 - a layout - """Make the controls and the empty plots.""" - super().__init__(parent) - self.planes: list[int] = [] - self.z: list[float] = [] - self.current_z: float | None = None - self.slider = QSlider(Qt.Orientation.Horizontal) - self.slider.setObjectName("plane-slider") - self.slider.valueChanged.connect(self._moved) - self.where = QLabel("No results file open.") - self.where.setObjectName("plane-where") - self.modes = QComboBox() - self.modes.setObjectName("plane-modes") - self.modes.addItem("mode sum", "sum") - self.modes.currentIndexChanged.connect(self._ask) - self.options = PlotOptions() - self.axis = "wavelength" - self.figure = QComboBox() - self.figure.setObjectName("plane-figure") - self.figure.addItem("Export figure…", None) - for title, kind in ( - ("spectrum at this plane", "spec_1d"), - ("power at this plane", "time_1d"), - ("spectrogram at this plane", "spectrogram"), - ("the maps along z", "prop_2d"), - ): - self.figure.addItem(title, kind) - self.figure.addItem("this plane's curves as CSV", "csv") - self.figure.activated.connect(self._figure_picked) - self.status = QLabel("") - self.status.setObjectName("plane-status") - self.status.setWordWrap(True) - - self.plots = HoverLayout() - self.spectrum_plot = self.plots.add_plot(0, 0, "Spectrum") - self.power_plot = self.plots.add_plot(0, 1, "Power") - self.phase_plot = self.plots.add_plot(1, 0, "Spectral phase") - self.power_plot.addLegend(offset=(-10, 10)) - for plot in (self.spectrum_plot, self.power_plot, self.phase_plot): - plot.showGrid(x=True, y=True, alpha=0.15) - self.spectrum_plot.setLabel("bottom", "Wavelength (nm)") - self.power_plot.setLabel("bottom", "Time (fs)") - self.power_plot.setLabel("left", "Power", units="W") - self.phase_plot.setLabel("bottom", "Wavelength (nm)") - self.phase_plot.setLabel("left", "Phase (rad)") - self.spectrum_curve = self.spectrum_plot.plot( - pen=pg.mkPen(PALETTE[0], width=1.4) - ) - self.power_curve = self.power_plot.plot( - pen=pg.mkPen(PALETTE[0], width=1.4), name="at the plane" - ) - self.phase_curve = self.phase_plot.plot(pen=pg.mkPen(PALETTE[1], width=1.4)) - self.plots.add_readout( - self.spectrum_plot, curve_lookup(self.spectrum_curve, "{0:.1f}, {1:.4g}") - ) - self.plots.add_readout( - self.power_plot, curve_lookup(self.power_curve, "{0:.1f} fs, {1:.4g} W") - ) - self.plots.add_readout( - self.phase_plot, curve_lookup(self.phase_curve, "{0:.1f}, {1:.3g} rad") - ) - self.image = pg.ImageItem() - self.image.setColorMap(colormap("viridis")) - self.phase_plot.addItem(self.image) - self.image.hide() - self.spectrogram_area = HoverLayout() - self.spectrogram = SpectrogramPlot(self.spectrogram_area) - self._spectrum: tuple[np.ndarray, np.ndarray] | None = None - self._quantity = "" - - controls = QHBoxLayout() - self.plane_label = QLabel("Plane") - controls.addWidget(self.plane_label) - controls.addWidget(self.slider, 2) - controls.addWidget(self.where) - controls.addWidget(self.modes) - controls.addSpacing(12) - controls.addWidget(self.figure) - split = QSplitter(Qt.Orientation.Horizontal) - split.addWidget(self.plots) - split.addWidget(self.spectrogram_area) - split.setStretchFactor(0, 3) - split.setStretchFactor(1, 2) - split.setSizes([640, 420]) - layout = QVBoxLayout(self) - layout.setContentsMargins(4, 4, 4, 0) - layout.setSpacing(4) - layout.addLayout(controls) - layout.addWidget(self.status) - layout.addWidget(split, 1) - self.set_planes([], []) - - # ------------------------------------------------------------------ input - - def set_planes( - self, planes: Sequence[int], z: Sequence[float], labels: Sequence[str] = () - ) -> None: - """Know a file's field planes and modes, and ask for the last plane. - - Parameters - ---------- - planes : Sequence of int - The indices of the planes that kept a field. - z : Sequence of float - Their positions, m. - labels : Sequence of str, optional - The file's modes. - """ - self.planes = [int(p) for p in planes] - self.z = [float(v) for v in z] - self.modes.blockSignals(True) - self.modes.clear() - self.modes.addItem("mode sum", "sum") - for index, name in enumerate(labels): - self.modes.addItem(name, index) - self.modes.setVisible(bool(labels)) # a beam has no modes to choose - self.modes.blockSignals(False) - enabled = bool(self.planes) - for widget in ( - self.slider, - self.modes, - self.figure, - ): - widget.setEnabled(enabled) - self.slider.blockSignals(True) - self.slider.setRange(0, max(len(self.planes) - 1, 0)) - self.slider.setValue(max(len(self.planes) - 1, 0)) - self.slider.blockSignals(False) - if enabled: - self._moved(self.slider.value()) - else: - self.where.setText("No plane kept a field.") - - def selection(self) -> object: - """Return the mode selection picked. - - Returns - ------- - object - ``"sum"`` or a mode's index. - """ - return self.modes.currentData() - - def index(self) -> int: - """Return the file's index of the plane shown. - - Returns - ------- - int - The plane. - """ - return self.planes[self.slider.value()] - - def _moved(self, position: int) -> None: - """Show where the slider is, and ask for that plane. - - Parameters - ---------- - position : int - The slider's position among the field planes. - """ - if not self.planes: - return - self.current_z = self.z[position] - self.where.setText(f"z = {self.current_z * 100:.4g} cm") - self._ask() - - def _ask(self, *_args: object) -> None: - """Ask for the plane shown. - - Parameters - ---------- - *_args : object - What the signal that calls it carries, unused. - """ - if self.planes: - self.status.setText("Reading the plane…") - self.plane_wanted.emit(self.index(), self.selection()) - self.ask_spectrogram() - - def ask_spectrogram(self) -> None: - """Ask for the shown plane's spectrogram.""" - if self.planes: - self.spectrogram_wanted.emit(self.index(), self.selection()) - - def _figure_picked(self, index: int) -> None: # pragma: no cover - a modal dialog - """Ask where to write the figure picked, and ask for it. - - Parameters - ---------- - index : int - The item picked. - """ - kind = self.figure.itemData(index) - self.figure.setCurrentIndex(0) - if kind is None: - return - if kind == "csv": - chosen, _ = QFileDialog.getSaveFileName( - self, "Export the plane", "plane.csv", "CSV (*.csv)" - ) - if chosen: - self.export_data(chosen) - return - path = choose_figure(self, f"{kind}.pdf") - if path: - self.export_figure(path, str(kind)) - - def export_data(self, path: str | Path) -> None: - """Write the plane's curves as CSV, as the kernel gave them (full resolution). - - Parameters - ---------- - path : str or pathlib.Path - The file: a column per abscissa and value, the shorter ones padded. - """ - columns: list[tuple[str, np.ndarray]] = [] - for name, curve, x_title, y_title in ( - ("spectrum", self.spectrum_curve, self._axis_title(), "spectral density"), - ("power", self.power_curve, "time (fs)", "power (W)"), - ("phase", self.phase_curve, self._axis_title(), "phase (rad)"), - ): - x, y = curve.getData() - if x is None or y is None: - continue - if name == "spectrum" and self._spectrum is not None: - order = np.argsort(self._spectrum[0]) - x, y = self._spectrum[0][order], self._spectrum[1][order] - columns.append((f"{name}: {x_title}", np.asarray(x, dtype=float))) - columns.append((f"{name}: {y_title}", np.asarray(y, dtype=float))) - length = max((len(values) for _, values in columns), default=0) - with Path(path).open("w", newline="", encoding="utf-8") as stream: - writer = csv.writer(stream) - writer.writerow([title for title, _ in columns]) - for row in range(length): - writer.writerow( - [repr(float(v[row])) if row < len(v) else "" for _, v in columns] - ) - - def export_figure(self, path: str, kind: str) -> None: - """Ask for one of solprop's plots of the plane as a figure. - - Parameters - ---------- - path : str - The file. - kind : str - The plot: ``"spec_1d"``, ``"time_1d"``, ``"spectrogram"`` or - ``"prop_2d"``. - """ - self.figure_wanted.emit( - {"file": path, "plot": kind, "z": self.current_z, "modes": self.selection()} - ) - - # ------------------------------------------------------------------ showing - - def show_plane(self, plane: Mapping[str, object]) -> None: - """Draw the kernel's plane. - - Parameters - ---------- - plane : Mapping - The ``plane`` reply. - """ - spectrum: Mapping[str, object] = plane["spectrum"] # pyright: ignore[reportAssignmentType] - power: Mapping[str, object] = plane["power"] # pyright: ignore[reportAssignmentType] - phase: Mapping[str, object] = plane["phase"] # pyright: ignore[reportAssignmentType] - notes = [] - self._quantity = str(spectrum.get("unit") or "") - self.axis = str(plane.get("axis") or "wavelength") - unit = UNITS[self.axis][1] - self.spectrum_plot.setLabel("bottom", self._axis_title(capital=True)) - if "error" in spectrum: - self._spectrum = None - self.spectrum_curve.setData([], []) - notes.append(f"No spectrum: {spectrum['error']}") - else: - x = np.asarray(spectrum["x"], dtype=float) / unit - self._spectrum = (x, np.asarray(spectrum["y"], dtype=float)) - self._redraw_spectrum() - t = np.asarray(power["t"], dtype=float) * 1e15 - self.power_curve.setData(t, np.asarray(power["y"], dtype=float)) - fluence = plane.get("fluence") - if isinstance(fluence, Mapping): - self._show_fluence(fluence, notes) - elif "error" in phase: - self.phase_curve.setData([], []) - notes.append(f"No phase: {phase['error']}") - else: - self._phase_axes() - frequency = np.asarray(phase["omega"], dtype=float) / (2 * np.pi) - along = _C / frequency if self.axis == "wavelength" else frequency - along = along / unit - values = np.asarray(phase["y"], dtype=float) - x, y = self._spectrum or (np.zeros(0), np.zeros(0)) - if x.size and y.size and np.max(y) > 0: - # Where there is no light the phase is noise: drawn as gaps. - order = np.argsort(x) - light = np.interp(along, x[order], y[order]) / np.max(y) - values = np.where(light >= PHASE_FLOOR, values, np.nan) - order = np.argsort(along) - self.phase_curve.setData(along[order], values[order], connect="finite") - if self.selection() == "sum" and self.modes.count() > 2: - notes.append("The phase is the first mode's: a sum of modes has none.") - values = np.asarray(power["y"], dtype=float) - peak = float(values.max()) if values.size else 0.0 - notes.insert(0, f"Peak power {si(peak, 'W')}.") - if self.options.bandpass is not None: - notes.insert(1, f"{self.options.describe().capitalize()}.") - self.status.setText(" ".join(notes)) - self._frame() - - def _phase_axes(self) -> None: - """Show the third plot as the spectral phase.""" - self.image.hide() - self.phase_plot.setTitle("Spectral phase") - self.phase_plot.setLabel("bottom", self._axis_title(capital=True)) - self.phase_plot.setLabel("left", "Phase (rad)") - - def _show_fluence(self, fluence: Mapping[str, object], notes: list[str]) -> None: - """Show a spatial plane's fluence in the third plot, a map or a profile. - - Parameters - ---------- - fluence : Mapping - The plane's ``fluence``: ``axes``, ``values`` and ``unit``, or - ``error``. - notes : list of str - The status line's notes, added to. - """ - self.phase_curve.setData([], []) - if "error" in fluence: - self._phase_axes() - notes.append(f"No fluence: {fluence['error']}") - return - axes: Mapping[str, object] = fluence["axes"] # pyright: ignore[reportAssignmentType] - values = np.asarray(fluence["values"], dtype=float) - unit = str(fluence["unit"]) - self.phase_plot.setTitle(f"Fluence ({unit})") - if values.ndim == 2: - x = np.asarray(axes["x"], dtype=float) * 1e3 - y = np.asarray(axes["y"], dtype=float) * 1e3 - self.image.setImage(values.T) - self.image.setRect( - float(x.min()), float(y.min()), float(np.ptp(x)), float(np.ptp(y)) - ) - self.image.show() - self.phase_plot.setLabel("bottom", "x (mm)") - self.phase_plot.setLabel("left", "y (mm)") - self.phase_plot.getViewBox().autoRange(items=[self.image]) - return - self.image.hide() - name = "r" if "r" in axes else "x" - self.phase_curve.setData(np.asarray(axes[name], dtype=float) * 1e3, values) - self.phase_plot.setLabel("bottom", f"{name} (mm)") - self.phase_plot.setLabel("left", f"Fluence ({unit})") - - def _axis_title(self, *, capital: bool = False) -> str: - """Return the spectral axis's title, with its unit. - - Parameters - ---------- - capital : bool, optional - Whether to capitalise it, for a plot's label. - - Returns - ------- - str - ``"wavelength (nm)"`` or ``"frequency (THz)"``. - """ - name = "wavelength" if self.axis == "wavelength" else "frequency" - if capital: - name = name.capitalize() - return f"{name} ({UNITS[self.axis][0]})" - - def apply_options(self, options: PlotOptions) -> None: - """Draw with new plot options: scale, floor and the typed limits. - - The axis and the bandpass are solprop's to compute: they take effect with - the next plane asked for. - - Parameters - ---------- - options : PlotOptions - The options. - """ - self.options = options - self._redraw_spectrum() - self._frame() - self.spectrogram.redraw(options) - - def _frame(self) -> None: - """Set the plots' ranges to the typed limits, automatic where blank.""" - spectral = self.options.shown_limits("spectral") - if self.axis != self.options.axis: - spectral = (None, None) # limits in another axis's unit - set_range(self.spectrum_plot, "x", spectral) - if self.image.isVisible(): - return # the third plot is a fluence map - set_range(self.phase_plot, "x", spectral) - set_range(self.power_plot, "x", self.options.shown_limits("time")) - - def _spectrum_title(self) -> str: - """Return what the spectrum plot shows. - - Returns - ------- - str - The spectral density, or a beam's energy per frequency bin. - """ - return "Energy per bin" if self._quantity == "J per bin" else "Spectral density" - - def _redraw_spectrum(self, *_args: object) -> None: - """Draw the spectrum, in dB of its peak or linear. - - Parameters - ---------- - *_args : object - What the signal that calls it carries, unused. - """ - if self._spectrum is None: - return - x, y = self._spectrum - if self.options.scale == "dB": - peak = float(np.max(y)) if y.size and np.max(y) > 0 else 1.0 - shown = 10 * np.log10(np.maximum(y / peak, 1e-30)) - self.spectrum_plot.setLabel("left", f"{self._spectrum_title()} (dB)") - self.spectrum_plot.getViewBox().setYRange(self.options.floor, 3) - else: - shown = y - self.spectrum_plot.setLabel("left", self._spectrum_title()) - self.spectrum_plot.getViewBox().enableAutoRange(axis="y") - order = np.argsort(x) - self.spectrum_curve.setData(x[order], shown[order]) - - def show_spectrogram(self, data: Mapping[str, object]) -> None: - """Show a plane's spectrogram. - - Parameters - ---------- - data : Mapping - The kernel's ``spectrogram`` reply. - """ - self.spectrogram.show(data, self.options) - - def show_error(self, message: str) -> None: - """Say why the plane or its spectrogram is not shown. - - Parameters - ---------- - message : str - The reason. - """ - self.status.setText(message) - - def clear(self) -> None: - """Forget the file shown.""" - self._spectrum = None - for curve in (self.spectrum_curve, self.power_curve, self.phase_curve): - curve.setData([], []) - self.spectrogram.clear() - self.set_planes([], []) diff --git a/gui/src/solprop_gui/views/plotting.py b/gui/src/solprop_gui/views/plotting.py index dec4ed1e1..cdf6940c7 100644 --- a/gui/src/solprop_gui/views/plotting.py +++ b/gui/src/solprop_gui/views/plotting.py @@ -16,7 +16,6 @@ import pyqtgraph as pg from PySide6.QtCore import QEvent, QPointF, Qt from PySide6.QtGui import QPen -from PySide6.QtWidgets import QFileDialog, QWidget __all__ = [ "BLUE", @@ -24,15 +23,11 @@ "HoverLayout", "Lookup", "Readout", - "choose_figure", "colormap", "curve_lookup", "figure_spec", ] -FIGURE_FILTER = "PNG image (*.png);;SVG drawing (*.svg);;PDF document (*.pdf)" -"""The figure formats offered, for a file dialog.""" - pg.setConfigOptions(antialias=True, background="w", foreground="k") BLUE = "#1f77b4" @@ -358,24 +353,3 @@ def figure_spec(plot: pg.PlotItem) -> dict[str, object]: "lines": lines, "points": points, } - - -def choose_figure(parent: QWidget, name: str) -> str | None: # pragma: no cover - modal - """Ask where to write a figure. - - Parameters - ---------- - parent : PySide6.QtWidgets.QWidget - The dialog's owner. - name : str - The file name offered. - - Returns - ------- - str or None - The file chosen, or ``None`` when the dialog is cancelled. - """ - chosen, _ = QFileDialog.getSaveFileName( - parent, "Export figure", name, FIGURE_FILTER - ) - return chosen or None diff --git a/gui/src/solprop_gui/views/scan_browser.py b/gui/src/solprop_gui/views/scan_browser.py deleted file mode 100644 index 1e0093714..000000000 --- a/gui/src/solprop_gui/views/scan_browser.py +++ /dev/null @@ -1,149 +0,0 @@ -# SPDX-FileCopyrightText: 2026 John C. Travers and contributors -# -# SPDX-License-Identifier: GPL-3.0-or-later - -"""The scan browser: one result of a scan over its variables (design 12.7). - -A scan's results (each point's statistics and reductions, at its last plane) are drawn -over the scan's variables: a line over one variable, a map over the first two (the -others held at their first value). Failed points are marked; points not run are gaps. -""" - -from collections.abc import Mapping, Sequence - -import numpy as np -import pyqtgraph as pg -from PySide6.QtWidgets import QComboBox, QHBoxLayout, QLabel, QVBoxLayout, QWidget - -from solprop_gui.registry.pages import label -from solprop_gui.views.plotting import PALETTE, HoverLayout, colormap, curve_lookup - -__all__ = ["ScanView"] - - -class ScanView(QWidget): - """A scan's results over its variables. - - Parameters - ---------- - parent : PySide6.QtWidgets.QWidget or None, optional - The owner. - """ - - def __init__(self, parent: QWidget | None = None) -> None: - """Make the result picker and the empty plot.""" - super().__init__(parent) - self.scan: Mapping[str, object] = {} - self.result = QComboBox() - self.result.setObjectName("scan-result") - self.result.currentIndexChanged.connect(self.redraw) - self.status = QLabel("No scan open.") - self.status.setObjectName("scan-status") - self.status.setWordWrap(True) - self.plots = HoverLayout() - self.plot = self.plots.add_plot(0, 0, "") - self.plot.showGrid(x=True, y=True, alpha=0.15) - self.curve = self.plot.plot( - pen=pg.mkPen(PALETTE[0], width=1.4), symbol="o", symbolSize=6 - ) - self.failed = pg.ScatterPlotItem(symbol="x", size=10, pen=pg.mkPen("#c62828")) - self.plot.addItem(self.failed) - self.image = pg.ImageItem() - self.image.setColorMap(colormap("viridis")) - self.plot.addItem(self.image) - self.plots.add_readout( - self.plot, curve_lookup(self.curve, "{0:.4g}: {1:.4g}"), dot=True - ) - line = QHBoxLayout() - line.addWidget(QLabel("Result")) - line.addWidget(self.result, 1) - layout = QVBoxLayout(self) - layout.setContentsMargins(4, 4, 4, 0) - layout.addLayout(line) - layout.addWidget(self.status) - layout.addWidget(self.plots, 1) - - def set_scan(self, scan: Mapping[str, object]) -> None: - """Show a scan's overview. - - Parameters - ---------- - scan : Mapping - The kernel's ``scan_overview`` reply. - """ - self.scan = scan - results: Mapping[str, object] = scan.get("results") or {} # pyright: ignore[reportAssignmentType] - self.result.blockSignals(True) - self.result.clear() - for name in results: - self.result.addItem(name, name) - self.result.blockSignals(False) - status = np.asarray(scan.get("status") or [], dtype=object).ravel() - done = int(np.count_nonzero(status == "done")) - failed = int(np.count_nonzero(status == "failed")) - variables: Sequence[Mapping[str, object]] = scan.get("variables") or [] # pyright: ignore[reportAssignmentType] - over = " × ".join(label(str(v["name"])).lower() for v in variables) # noqa: RUF001 - times - self.status.setText( - f"{status.size} points over {over or 'nothing'}: {done} done, " - f"{failed} failed. Each point's value is at its last plane, summed over " - "its modes." - ) - self.redraw() - - def redraw(self, *_args: object) -> None: - """Draw the result picked over the variables. - - Parameters - ---------- - *_args : object - What the signal that calls it carries, unused. - """ - self.curve.setData([], []) - self.failed.setData([], []) - self.image.hide() - name = self.result.currentData() - results: Mapping[str, Mapping[str, object]] = self.scan.get("results") or {} # pyright: ignore[reportAssignmentType] - variables: Sequence[Mapping[str, object]] = self.scan.get("variables") or [] # pyright: ignore[reportAssignmentType] - if name is None or name not in results or not variables: - return - entry = results[name] - values = np.asarray(entry["values"], dtype=float) - status = np.asarray(self.scan.get("status"), dtype=object) - units = str(entry["units"]) - self.plot.setTitle(str(entry["summary"])) - first = variables[0] - x = np.asarray(first["values"], dtype=float) - self.plot.setLabel("bottom", label(str(first["name"]))) - if values.ndim == 1 or len(variables) == 1: - line = values.reshape(x.size, -1)[:, 0] - self.curve.setData(x, line, connect="finite") - bad = status.reshape(x.size, -1)[:, 0] == "failed" - self.failed.setData(x[bad], np.zeros(int(bad.sum()))) - self.plot.setLabel("left", name, units=units or None) - return - # Over the first two variables, the rest at their first value. - second = variables[1] - y = np.asarray(second["values"], dtype=float) - grid = values.reshape(x.size, y.size, -1)[:, :, 0] - self.image.setImage(grid) - self.image.setRect( - float(x.min()), - float(y.min()), - float(np.ptp(x)) or 1.0, - float(np.ptp(y)) or 1.0, - ) - self.image.show() - self.plot.setLabel("left", label(str(second["name"]))) - - def show_error(self, message: str) -> None: - """Say why the scan is not shown. - - Parameters - ---------- - message : str - The reason. - """ - self.scan = {} - self.result.clear() - self.redraw() - self.status.setText(message) diff --git a/gui/src/solprop_gui/views/statistics.py b/gui/src/solprop_gui/views/statistics.py deleted file mode 100644 index 0ea20f184..000000000 --- a/gui/src/solprop_gui/views/statistics.py +++ /dev/null @@ -1,501 +0,0 @@ -# SPDX-FileCopyrightText: 2026 John C. Travers and contributors -# -# SPDX-License-Identifier: GPL-3.0-or-later - -"""The Statistics view: the recorded statistics against z, four panels of two. - -The statistics a run recorded (``stats/*``) come with solprop's own summary and unit -(``solprop.stats.CATALOGUE``). The view is a 2 by 2 grid; each panel draws one -quantity on its left axis and optionally a second on its right, dashed, which is how -two statistics are read against each other. A quantity is a statistic, a column per -mode and component where it has several, or the run's step size with its rejected -steps marked (:data:`~solprop_gui.model.stats_layout.STEP`), which is where a run's -cost and its difficult stretches show. What each panel shows is chosen on the Results -step (:class:`StatsSelector`). -""" - -from collections.abc import Mapping, Sequence - -import numpy as np -import pyqtgraph as pg -from PySide6.QtCore import Qt, Signal -from PySide6.QtWidgets import ( - QComboBox, - QGridLayout, - QHBoxLayout, - QLabel, - QPushButton, - QVBoxLayout, - QWidget, -) - -from solprop_gui.model.stats_layout import ( - PANELS, - STEP, - Layout, - default_layout, - kept_layout, -) -from solprop_gui.views.plotting import PALETTE, HoverLayout, choose_figure, curve_lookup - -__all__ = ["StatisticsView", "StatsSelector"] - -_PLAIN = ("J", "W", "s", "m", "rad") -"""Units pyqtgraph may prefix (GW, fs); any other goes in the label as it is.""" - - -class _Panel: - """One panel: a plot with a left axis, and a second view box on its right. - - Parameters - ---------- - layout : solprop_gui.views.plotting.HoverLayout - The grid it is drawn in. - row, column : int - Its place. - """ - - def __init__(self, layout: HoverLayout, row: int, column: int) -> None: - """Make the plot and its right-hand view box, linked in z.""" - self.plot = layout.add_plot(row, column, "") - self.plot.showGrid(x=True, y=True, alpha=0.15) - self.plot.setLabel("bottom", "z (cm)") - self.legend = self.plot.addLegend(offset=(-10, 10)) - self.right = pg.ViewBox() - self.plot.showAxis("right") - scene = self.plot.scene() - if scene is not None: - scene.addItem(self.right) - self.plot.getAxis("right").linkToView(self.right) - self.right.setXLink(self.plot) - self.plot.getViewBox().sigResized.connect(self._fit) - self.items: list[pg.GraphicsObject] = [] - self.curves: list[pg.PlotDataItem] = [] - layout.add_readout(self.plot, self.lookup, dot=True) - - def _fit(self) -> None: - """Lay the right view box over the plot's own.""" - self.right.setGeometry(self.plot.getViewBox().sceneBoundingRect()) - self.right.linkedViewChanged(self.plot.getViewBox(), self.right.XAxis) - - def clear(self) -> None: - """Remove what the panel draws.""" - for item in self.items: - box = item.getViewBox() - if box is not None: - box.removeItem(item) - self.items = [] - self.curves = [] - self.legend.clear() - self.plot.setTitle("") - for side in ("left", "right"): - axis = self.plot.getAxis(side) - axis.setLabel("") - axis.setLogMode(False, False) - self.plot.getAxis("right").setStyle(showValues=False) - - def lookup(self, x: float, y: float) -> tuple[float, float, str] | None: - """Read the left quantity's curve nearest the mouse. - - Parameters - ---------- - x, y : float - The mouse, in the plot's coordinates. - - Returns - ------- - tuple or None - The point and its label; ``None`` with nothing drawn. - """ - best: tuple[float, float, str] | None = None - distance = np.inf - for curve in self.curves: - hit = curve_lookup(curve, "z = {0:.4g} cm: {1:.4g}")(x, y) - if hit is not None and abs(hit[1] - y) < distance: - distance = abs(hit[1] - y) - best = hit - return best - - -class StatisticsView(QWidget): - """A results file's statistics against z, in four panels of up to two each. - - Parameters - ---------- - parent : PySide6.QtWidgets.QWidget or None, optional - The owner. - - Attributes - ---------- - figure_wanted : Signal - Emitted with a figure's ``file`` and ``plot`` (solprop's ``plot_stats``). - layout_changed : Signal - Emitted with the :data:`~solprop_gui.model.stats_layout.Layout` shown, the - quantities to choose from and their descriptions, when a file's statistics - arrive. - """ - - figure_wanted = Signal(object) - layout_changed = Signal(object, object, object) - - def __init__(self, parent: QWidget | None = None) -> None: - """Make the empty panels.""" - super().__init__(parent) - self.stats: dict[str, Mapping[str, object]] = {} - self.z = np.zeros(0) - self.steps: Mapping[str, object] = {} - self.chosen: Layout | None = None - self.summary = QLabel("No results file open.") - self.summary.setObjectName("stats-summary") - self.summary.setWordWrap(True) - self.figure_button = QPushButton("Export figures…") - self.figure_button.setToolTip("Every statistic, drawn by solprop (plot_stats).") - self.figure_button.clicked.connect(self._choose_figure) - self.plots = HoverLayout() - self.panels = [_Panel(self.plots, index // 2, index % 2) for index in range(4)] - line = QHBoxLayout() - line.addWidget(self.summary, 1) - line.addWidget(self.figure_button) - layout = QVBoxLayout(self) - layout.setContentsMargins(4, 4, 4, 0) - layout.addLayout(line) - layout.addWidget(self.plots, 1) - - @property - def names(self) -> list[str]: - """Return the quantities a panel can show. - - Returns - ------- - list of str - The recorded statistics, then the step size. - """ - return [*self.stats, STEP] - - def panel_choice(self, index: int) -> tuple[str | None, str | None]: - """Return what a panel shows. - - Parameters - ---------- - index : int - The panel, row by row. - - Returns - ------- - tuple - Its left and right quantities; ``None`` for none. - """ - return (self.chosen or default_layout([]))[index] - - def set_statistics(self, reply: Mapping[str, object]) -> None: - """Show a file's statistics and step history. - - Parameters - ---------- - reply : Mapping - The kernel's ``statistics`` reply. - """ - self.z = np.asarray(reply["z"], dtype=float) - entries: Sequence[Mapping[str, object]] = reply["stats"] # pyright: ignore[reportAssignmentType] - self.stats = {str(entry["name"]): entry for entry in entries} - self.steps = reply["steps"] # pyright: ignore[reportAttributeAccessIssue] - names = list(self.stats) - self.chosen = ( - default_layout(names) - if self.chosen is None - else kept_layout(self.chosen, names) - ) - self.figure_button.setEnabled(bool(self.stats)) - accepted = len(self.steps.get("z", [])) # pyright: ignore[reportArgumentType] - rejected = len(self.steps.get("rejected_z", [])) # pyright: ignore[reportArgumentType] - self.summary.setText( - f"{len(self.stats)} statistics at {self.z.size} planes; " - f"{accepted} accepted steps, {rejected} rejected." - ) - self.redraw() - self.layout_changed.emit(self.chosen, self.names, self.summaries()) - - def summaries(self) -> dict[str, str]: - """Return each quantity's description, as solprop gives it. - - Returns - ------- - dict - By name: the summary and unit. - """ - found = { - name: f"{entry['summary']} ({entry['units'] or 'no unit'})" - for name, entry in self.stats.items() - } - found[STEP] = "The run's step size against z, the rejected steps marked." - return found - - def set_layout(self, layout: Layout) -> None: - """Show a layout chosen. - - Parameters - ---------- - layout : Layout - The four panels' left and right quantities. - """ - self.chosen = tuple(layout) - self.redraw() - - def redraw(self) -> None: - """Draw every panel; a panel with nothing chosen gives its space to the rest.""" - layout = self.chosen or default_layout([]) - self._arrange([left is not None or right is not None for left, right in layout]) - for panel, (left, right) in zip(self.panels, layout, strict=True): - panel.clear() - titles = [] - for side, name in (("left", left), ("right", right)): - if name is not None and (name == STEP or name in self.stats): - titles.append(self._draw(panel, side, name)) - panel.plot.setTitle(" · ".join(titles)) - panel.plot.getViewBox().autoRange() - panel.right.autoRange() - - def _arrange(self, shown: Sequence[bool]) -> None: - """Lay out the panels shown: one or two in a column, more in the grid. - - Parameters - ---------- - shown : Sequence of bool - Whether each panel is shown. - """ - grid = self.plots.ci - for panel in self.panels: - if panel.plot in grid.items: - grid.removeItem(panel.plot) - visible = [panel for panel, on in zip(self.panels, shown, strict=True) if on] - for place, panel in enumerate(visible): - row, column = (place, 0) if len(visible) <= 2 else divmod(place, 2) - grid.addItem(panel.plot, row=row, col=column) - for panel, on in zip(self.panels, shown, strict=True): - panel.plot.setVisible(on) - panel.right.setVisible(on) - - def _draw(self, panel: _Panel, side: str, name: str) -> str: - """Draw one quantity on one side of a panel. - - Parameters - ---------- - panel : _Panel - The panel. - side : {'left', 'right'} - Its axis. - name : str - The statistic, or :data:`STEP`. - - Returns - ------- - str - Its name, for the panel's title (solprop's summary is too long for - one; the selector shows it). - """ - box = panel.plot.getViewBox() if side == "left" else panel.right - style = Qt.PenStyle.SolidLine if side == "left" else Qt.PenStyle.DashLine - offset = 0 if side == "left" else 3 - axis = panel.plot.getAxis(side) - axis.setStyle(showValues=True) - if name == STEP: - return self._draw_steps(panel, box, axis, style) - entry = self.stats[name] - units = str(entry["units"]) - plain = units in _PLAIN - axis.setLabel( - name if plain or not units else f"{name} ({units})", - units=units if plain else None, - ) - columns: Sequence[Mapping[str, object]] = entry["columns"] # pyright: ignore[reportAssignmentType] - for number, column in enumerate(columns): - colour = PALETTE[(number + offset) % len(PALETTE)] - curve = pg.PlotDataItem( - self.z * 100, - np.asarray(column["y"], dtype=float), - pen=pg.mkPen(colour, width=1.4, style=style), - symbol="o", - symbolSize=4, - symbolBrush=colour, - ) - box.addItem(curve) - panel.items.append(curve) - label = str(column["label"]) if len(columns) > 1 else name - panel.legend.addItem(curve, label) - if side == "left": - panel.curves.append(curve) - return name - - def _draw_steps( - self, - panel: _Panel, - box: pg.ViewBox, - axis: pg.AxisItem, - style: Qt.PenStyle, - ) -> str: - """Draw the step size, on a log axis, with the rejected steps marked. - - Parameters - ---------- - panel : _Panel - The panel. - box : pyqtgraph.ViewBox - The view box of its side. - axis : pyqtgraph.AxisItem - The side's axis. - style : PySide6.QtCore.Qt.PenStyle - The line's style. - - Returns - ------- - str - The title. - """ - steps = self.steps - z = np.asarray(steps.get("z", []), dtype=float) * 100 - h = np.asarray(steps.get("h", []), dtype=float) - rejected_z = np.asarray(steps.get("rejected_z", []), dtype=float) * 100 - rejected_h = np.asarray(steps.get("rejected_h", []), dtype=float) - axis.setLogMode(False, True) # pyright: ignore[reportArgumentType] - its stub - axis.setLabel("step", units="m") - curve = pg.PlotDataItem( - z, - np.log10(np.maximum(h, 1e-30)), - pen=pg.mkPen(PALETTE[0], width=1.0, style=style), - connect="finite", - ) - marks = pg.ScatterPlotItem( - rejected_z, - np.log10(np.maximum(rejected_h, 1e-30)), - symbol="x", - size=7, - pen=pg.mkPen("#c62828"), - ) - for item in (curve, marks): - box.addItem(item) - panel.items.append(item) - panel.legend.addItem(curve, "step, accepted") - panel.legend.addItem(marks, "rejected") - return STEP - - def _choose_figure(self) -> None: # pragma: no cover - a modal dialog - """Ask where to write the figures, and ask for them.""" - path = choose_figure(self, "statistics.pdf") - if path: - self.export_figure(path) - - def export_figure(self, path: str) -> None: - """Ask for solprop's figures of every statistic. - - Parameters - ---------- - path : str - The file (numbered for several). - """ - self.figure_wanted.emit({"file": path, "plot": "plot_stats"}) - - def clear(self) -> None: - """Forget the file shown.""" - self.stats = {} - self.z = np.zeros(0) - self.steps = {} - for panel in self.panels: - panel.clear() - self.figure_button.setEnabled(False) - self.summary.setText("No results file open.") - - -class StatsSelector(QWidget): - """Choose what each of the Statistics view's panels shows. - - Parameters - ---------- - parent : PySide6.QtWidgets.QWidget or None, optional - The owner. - - Attributes - ---------- - changed : Signal - Emitted with the new :data:`~solprop_gui.model.stats_layout.Layout`. - """ - - changed = Signal(object) - - def __init__(self, parent: QWidget | None = None) -> None: - """Make a left and a right choice for each panel.""" - super().__init__(parent) - self.choices: list[tuple[QComboBox, QComboBox]] = [] - grid = QGridLayout(self) - grid.setContentsMargins(0, 0, 0, 0) - grid.addWidget(QLabel("left axis"), 0, 1) - grid.addWidget(QLabel("right axis"), 0, 2) - places = ("Top left", "Top right", "Bottom left", "Bottom right") - for index, place in enumerate(places[:PANELS]): - pair = (QComboBox(), QComboBox()) - for side, box in zip(("left", "right"), pair, strict=True): - box.setObjectName(f"stats-{index}-{side}") - box.setSizeAdjustPolicy( - QComboBox.SizeAdjustPolicy.AdjustToMinimumContentsLengthWithIcon - ) - box.setMinimumContentsLength(8) - box.currentIndexChanged.connect(self._picked) - grid.addWidget(QLabel(place), index + 1, 0) - grid.addWidget(pair[0], index + 1, 1) - grid.addWidget(pair[1], index + 1, 2) - self.choices.append(pair) - self.set_layout(default_layout([]), [STEP]) - - def set_layout( - self, - layout: Layout, - names: Sequence[str], - summaries: Mapping[str, str] | None = None, - ) -> None: - """Show a layout and the quantities to choose from, without announcing it. - - Parameters - ---------- - layout : Layout - The four panels' choices. - names : Sequence of str - The quantities. - summaries : Mapping or None, optional - Each quantity's description, shown as its tooltip. - """ - summaries = summaries or {} - for pair, panel in zip(self.choices, layout, strict=True): - for box, name in zip(pair, panel, strict=True): - box.blockSignals(True) - box.clear() - box.addItem("(none)", None) - for option in names: - box.addItem(option, option) - box.setItemData( - box.count() - 1, - summaries.get(option, ""), - Qt.ItemDataRole.ToolTipRole, - ) - box.setCurrentIndex(max(box.findData(name), 0)) - box.blockSignals(False) - - def chosen(self) -> Layout: - """Return the layout chosen. - - Returns - ------- - Layout - The four panels' left and right quantities. - """ - return tuple( - (left.currentData(), right.currentData()) for left, right in self.choices - ) - - def _picked(self, _index: int) -> None: - """Announce the layout after a choice. - - Parameters - ---------- - _index : int - The choice's place, unused. - """ - self.changed.emit(self.chosen()) diff --git a/gui/tests/conftest.py b/gui/tests/conftest.py index 0476cc913..555d0e256 100644 --- a/gui/tests/conftest.py +++ b/gui/tests/conftest.py @@ -5,6 +5,7 @@ """Shared test configuration: widgets are drawn without a display.""" import gc +import numbers import os import shutil import time @@ -22,6 +23,40 @@ # own suite: a first native run would otherwise calibrate, and its notice is an error. os.environ.setdefault("SOLPROP_CALIBRATION", "off") +_PYTEST_APPROX = pytest.approx +_PYTEST_REL = 1e-6 +"""pytest's default relative tolerance, which a bare ``approx`` of a number keeps.""" + + +def _approx(expected, rel=None, abs=None, nan_ok=False): + """Return ``pytest.approx`` with no absolute tolerance unless the test gives one. + + The rule of solprop's ``tests/conftest.py``: pytest keeps an absolute tolerance of + 1e-12 beside any ``rel``, which accepts any result for a quantity far below it (a + time limit of 1e-13 s, a wavelength). With ``rel=`` alone the comparison is + relative only, and a bare ``approx(x)`` of a nonzero number is relative to pytest's + 1e-6 only; a bare ``approx`` of zero, or of a sequence, array or mapping, keeps + pytest's defaults. A test that needs an absolute tolerance gives ``abs=``. + """ + if abs is None: + if rel is not None: + abs = 0.0 + elif _nonzero_number(expected): + rel, abs = _PYTEST_REL, 0.0 + return _PYTEST_APPROX(expected, rel=rel, abs=abs, nan_ok=nan_ok) + + +def _nonzero_number(value: object) -> bool: + """Return whether `value` is a real or complex number, not a bool, other than 0.""" + return ( + isinstance(value, numbers.Complex) + and not isinstance(value, bool) + and value != 0 + ) + + +pytest.approx = _approx + def pytest_configure(config: pytest.Config) -> None: """Collect garbage only between tests, as the window collects it between events. diff --git a/gui/tests/test_app.py b/gui/tests/test_app.py index 2fb411407..56dd4fc90 100644 --- a/gui/tests/test_app.py +++ b/gui/tests/test_app.py @@ -15,3 +15,10 @@ def test_version_answers_and_exits(capsys: pytest.CaptureFixture[str]): main(["--version"]) assert exit_info.value.code == 0 assert capsys.readouterr().out.strip() == __version__ + + +def test_an_unknown_option_is_refused(capsys: pytest.CaptureFixture[str]): + with pytest.raises(SystemExit) as exit_info: + main(["--workflow"]) + assert exit_info.value.code == 2 + assert "unrecognized arguments: --workflow" in capsys.readouterr().err diff --git a/gui/tests/test_beam.py b/gui/tests/test_beam.py index faa50c29e..04e78b603 100644 --- a/gui/tests/test_beam.py +++ b/gui/tests/test_beam.py @@ -2,21 +2,17 @@ # # SPDX-License-Identifier: GPL-3.0-or-later -"""A free-space plane measured: in the kernel, in a run's worker, and in the views.""" +"""A free-space beam in the Overview view, offscreen.""" import warnings -from collections.abc import Iterator, Mapping +from collections.abc import Iterator from pathlib import Path -from typing import Any import numpy as np import pytest from pytestqt.qtbot import QtBot -from solprop.service import handlers -from solprop_gui.model.plot_options import PlotOptions from solprop_gui.views.live import OverviewView -from solprop_gui.views.plane import PlaneView from test_ui import shot @@ -27,10 +23,6 @@ def _quiet() -> Iterator[None]: yield -def ask(kind: str, body: Mapping[str, object]) -> Any: - return handlers.HANDLERS[kind](body) - - def row(index: int) -> dict[str, object]: x = np.linspace(-1e-3, 1e-3, 9) return { @@ -70,18 +62,11 @@ def test_the_overview_maps_a_beam_across_its_centre(qtbot: QtBot, tmp_path: Path assert not view.spatial and view.profile_map.plot not in view.maps.ci.items -def test_the_plane_view_draws_a_beam_s_intensity_slice(qtbot: QtBot): - view = PlaneView() +def test_the_overview_names_a_beam_s_readings(qtbot: QtBot): + view = OverviewView() qtbot.addWidget(view) - view.resize(1000, 600) - t = np.linspace(-5e-14, 5e-14, 20) - x = np.linspace(-1e-3, 1e-3, 11) - data = {"t": t, "x": x, "axis": "x", "values": np.ones((11, 20))} - view.show_spectrogram(data) - plot = view.spectrogram - assert plot.plot.getAxis("left").labelText == "x (mm)" - assert "across the beam" in plot.plot.titleLabel.text - hit = plot.lookup(0.0, 0.5) # mm - assert hit is not None - view.apply_options(PlotOptions(axis="f", spectral_limits=(1e14, 2e14))) - assert plot.plot.getViewBox().viewRange()[1][1] == pytest.approx(1.0, abs=0.2) + view.set_spatial(True) + assert "Axial power" in view.power_map.plot.titleLabel.text + assert "Energy per bin" in view.spectrum_map.plot.titleLabel.text + view.set_spatial(False) + assert view.power_line.titleLabel.text == "Power at z" diff --git a/gui/tests/test_design.py b/gui/tests/test_design.py index f2621e1cc..a2dde4c16 100644 --- a/gui/tests/test_design.py +++ b/gui/tests/test_design.py @@ -2,61 +2,14 @@ # # SPDX-License-Identifier: GPL-3.0-or-later -"""The kernel's design requests: modes, sweeps and pins (no Qt), and a multimode run.""" +"""The route cards held to solprop's pins, defaults and examples, and a scan setup.""" -import warnings -from collections.abc import Iterator, Mapping -from typing import Any - -import pytest from solprop.recipe import Recipe, parameters from solprop.recipe.pins import TARGETS -from solprop.service import handlers from solprop.service.explore import PIN_KEYS, PIN_SEARCH from conftest import TINY -from solprop_gui.registry.routes import CARDS, EXPLORER_SETUP, IMPLIED, card_of - -MULTIMODE = TINY.replace("mode_average = true", "modes = 2").replace( - "n_save = 6", - 'n_save = 3\nlaunch = { "HE1,1" = 0.8, "HE1,2" = { share = 0.2, phase = 1.0 } }', -) -"""The tiny capillary in two modes, launched into both.""" - -PINNED = TINY.replace('pressure = "1 bar"\n', "") + ( - '\n[pins]\npressure = { target = "zdw", wavelength = "500 nm", ' - 'search = ["0.1 bar", "10 bar"] }\n' -) -"""The tiny capillary with its pressure pinned to a zero-dispersion wavelength.""" - - -@pytest.fixture(autouse=True) -def _quiet() -> Iterator[None]: - """Ignore the material-range warnings of the wide bands.""" - with warnings.catch_warnings(): - warnings.simplefilter("ignore") - yield - - -def ask(kind: str, payload: Mapping[str, object]) -> Any: - return handlers.HANDLERS[kind](payload) - - -def test_the_modes_of_a_setup_are_plain_arrays(): - reply = ask("modes", {"text": EXPLORER_SETUP}) - assert reply["pump"] == pytest.approx(800e-9) and reply["sweep"] is None - (only,) = reply["sets"] - assert only["value"] is None and only["z"] == 0.0 - labels = [mode["label"] for mode in only["modes"]] - assert labels == [f"HE1,{m}:even" for m in range(1, 5)] - first = only["modes"][0] - names = ("neff_minus_one", "beta1", "beta2", "beta3", "alpha", "gamma") - for name in (*names, "phase_mismatch"): - assert first[name].shape == only["omega"].shape - assert 4e-7 < first["zdw"] < 6e-7 and first["aeff"] > 0 - # Each mode's wave phase-matched to the soliton in the first: bluer in higher ones. - rdw = [mode["rdw"][0] for mode in only["modes"][:3]] - assert rdw == sorted(rdw, reverse=True) and 1.5e-7 < rdw[-1] < rdw[0] < 2.1e-7 +from solprop_gui.registry.routes import CARDS, IMPLIED, card_of def test_the_registry_agrees_with_solprops_pins_and_defaults(): @@ -68,17 +21,6 @@ def test_the_registry_agrees_with_solprops_pins_and_defaults(): assert capillary[name].default == value -DESIGN_PINS = { - "pressure": { - "target": "zdw", - "wavelength": "500 nm", - "search": ["0.1 bar", "10 bar"], - }, - "energy": {"target": "soliton_order", "order": 3}, -} -"""The design tool's two targets: the ZDW at 500 nm, then a third-order soliton.""" - - def test_each_card_s_example_is_solprop_s_and_the_card_s(): for entry in CARDS: if entry.example is None: @@ -92,18 +34,7 @@ def test_each_card_s_example_is_solprop_s_and_the_card_s(): build.pop(name) else: build[name] = value - assert card_of(recipe.route, build, enabled_only=False) is entry, entry.key - - -_RECT = '{ type = "RectMode", half_width_x = "125 um", half_width_y = "50 um" }' -_SLAB_MODES = '{ type = "ModeCollection.slab", half_gap = "63.5 um", orders = [1, 3] }' -SLAB = ( - Recipe.example("hollow_rectangular") - .to_text() - .replace(f"modes = [{_RECT}]", f"modes = {_SLAB_MODES}") - .replace("n_theta = 12\n", "") # a slab set is uniform in y: one y node -) -"""The waveguide example with a slab mode set in place of its rectangular mode.""" + assert card_of(recipe.route, build) is entry, entry.key SCAN = TINY.replace("n_save = 6", "n_save = 2") + ( diff --git a/gui/tests/test_lifecycle.py b/gui/tests/test_lifecycle.py index 92108fb22..e65e71abe 100644 --- a/gui/tests/test_lifecycle.py +++ b/gui/tests/test_lifecycle.py @@ -20,11 +20,12 @@ from solprop.service.launch import prepare, start_direct from solprop.service.messages import Event, Reply from solprop.service.record import read_events, read_status, request_stop +from solprop.service.runs import list_runs from solprop.service.worker import OUTPUT, RunSpec from conftest import TINY from solprop_gui.model.recipe import RecipeModel -from solprop_gui.model.workspace import list_runs, new_run_folder +from solprop_gui.model.workspace import new_run_folder TIMEOUT = 120.0 @@ -124,7 +125,7 @@ def test_the_whole_lifecycle(kernel: Kernel, tmp_path: Path): assert resumed[-1].kind == "finished" described = kernel.ask("describe_output", {"path": output}) assert described["outcome"]["status"] == "complete" # pyright: ignore[reportIndexIssue] - assert [run.folder for run in list_runs(workspace)] == [folder] + assert [run["folder"] for run in list_runs(workspace, None)] == [str(folder)] # Compare: the run and the exported script's run end on the same spectrum. window = {"wavelength_range": [200e-9, 2e-6]} # the script's file has no recipe diff --git a/gui/tests/test_postprocess.py b/gui/tests/test_postprocess.py index 44e7380bc..cf5876f46 100644 --- a/gui/tests/test_postprocess.py +++ b/gui/tests/test_postprocess.py @@ -84,7 +84,7 @@ def test_fixed_elements_are_applied_in_order(run: str): assert pulses["limit"]["peak"] >= pulses["before"]["peak"] * 0.999 assert math.isclose(found["wavelength"], 8e-7, rel_tol=1e-3) empty = chain(run) # no elements: after is before - assert np.allclose(empty["after"], empty["before"]) + assert np.allclose(empty["after"], empty["before"], atol=0.0) def test_auto_elements_are_searched_one_at_a_time(run: str): diff --git a/gui/tests/test_pure.py b/gui/tests/test_pure.py index 9b4dac683..c1d4393c2 100644 --- a/gui/tests/test_pure.py +++ b/gui/tests/test_pure.py @@ -8,34 +8,17 @@ from pathlib import Path from typing import Any -import numpy as np import pytest from solprop.service.handlers import HANDLERS -from solprop.service.reduce import stats_row from solprop_gui.help.guide import guide_url -from solprop_gui.model.workspace import list_runs, new_run_folder, slug -from solprop_gui.registry.pages import LABELS, PAGES, label, page_of -from solprop_gui.registry.routes import CARDS, card, card_of +from solprop_gui.model.workspace import new_run_folder, slug +from solprop_gui.registry.pages import LABELS, label +from solprop_gui.registry.routes import card_of # ---------------------------------------------------------------------- messages -# ---------------------------------------------------------------------- reduction - - -def test_stats_row_totals_numbers_and_skips_the_rest(): - row = stats_row( - { - "energy": np.array([[1.0, 2.0]]), - "zdw": float("nan"), - "label": object(), - "count": 3, - } - ) - assert row == {"energy": 3.0, "count": 3.0} - - # ---------------------------------------------------------------------- states @@ -52,75 +35,20 @@ def test_run_folders_are_named_by_date_and_title(tmp_path: Path): assert len(slug("x" * 100)) == 40 -def test_the_workspace_lists_runs_newest_first(tmp_path: Path): - assert list_runs(tmp_path / "missing") == [] - old = tmp_path / "a" - old.mkdir() - (old / "run.h5").write_bytes(b"") - new = tmp_path / "b" - new.mkdir() - (new / "recipe.toml").write_text("") - (tmp_path / "empty").mkdir() - (tmp_path / "loose.txt").write_text("") - import os # noqa: PLC0415 - only here +# ---------------------------------------------------------------------- registry - os.utime(old / "run.h5", (1, 1)) - runs = list_runs(tmp_path) - assert [run.name for run in runs] == ["b", "a"] - assert runs[0].output is None and runs[0].recipe == new / "recipe.toml" - assert runs[1].output == old / "run.h5" and runs[1].recipe is None +def _card_key(route: str, build: dict[str, object]) -> str | None: + found = card_of(route, build) + return None if found is None else found.key -# ---------------------------------------------------------------------- registry - -def test_the_cards_are_presentation_over_routes(): - averaged = card("capillary-averaged") - assert averaged.enabled and averaged.route == "capillary" - assert "mode_average = true" in averaged.blank('A "quoted" title') - assert 'title = "A \\"quoted\\" title"' in averaged.blank('A "quoted" title') - assert "title" not in averaged.blank() - modal = card("capillary-modal") - assert modal.enabled and "mode_average" not in modal.blank() - assert "modes = 4" in modal.blank() - enabled = {entry.key for entry in CARDS if entry.enabled} - assert enabled == { - "capillary-averaged", - "capillary-modal", - "antiresonant", - "gnlse", - "cartesian", - "line", - "radial", - } - for key in ("planar", "rectangular", "slab"): - assert card(key).hidden and not card(key).enabled # not offered for now - for key in ("step-index", "grin"): # shown, until recipes can say them - assert not card(key).hidden and "#47" in str(card(key).reason) - with pytest.raises(KeyError): - card("nope") - assert card_of("capillary", {"mode_average": True}) is averaged - assert card_of("capillary", {}) is modal # solprop's default: multimode - assert card_of("gnlse", {}) is card("gnlse") - assert card_of("nope", {}) is None - assert card_of("free", {}) is None # no space: neither Cartesian nor a line - - -def test_a_cards_preset_values_are_written_as_toml(): - from solprop_gui.registry.routes import RouteCard # noqa: PLC0415 - only here - - text = RouteCard("k", "t", "s", "capillary", {"a": True, "b": 2, "c": "x"}).blank() - assert "a = true" in text and "b = 2" in text and 'c = "x"' in text - assert "a = false" in RouteCard("k", "t", "s", "r", {"a": False}).blank() - - -def test_pages_and_labels(): - assert [page.key for page in PAGES][-2:] == ["results", "postprocess"] - numerics = page_of("numerics") - assert numerics is not None and numerics.key == "propagate" - assert page_of("nothing") is None - assert label("energy") == LABELS["energy"] - assert label("pressure_floor") == "Pressure floor" +def test_a_recipe_is_named_by_its_route_s_card(): + assert _card_key("capillary", {"mode_average": True}) == "capillary-averaged" + assert _card_key("capillary", {}) == "capillary-modal" # solprop's default + assert _card_key("gnlse", {}) == "gnlse" + assert _card_key("nope", {}) is None + assert _card_key("free", {}) is None # no space: neither Cartesian nor a line def test_guide_addresses(): @@ -131,7 +59,7 @@ def test_guide_addresses(): # ---------------------------------------------------------------------- the explorer -def test_plot_options_read_typed_limits_and_saved_values(): +def test_plot_options_read_typed_limits(): from solprop_gui.model import plot_options as po # noqa: PLC0415 - only here with pytest.raises(ValueError): @@ -139,20 +67,6 @@ def test_plot_options_read_typed_limits_and_saved_values(): options = po.PlotOptions(axis="f", spectral_limits=(3e14, None)) assert options.shown_limits("spectral") == (pytest.approx(300.0), None) assert options.label() == "Frequency (THz)" and options.describe() == "" - assert po.to_display("f", po.from_display("f", 2.5)) == pytest.approx(2.5) - saved = { - "axis": "f", - "spectral_limits": [1e14, None], - "time_limits": "bad", - "scale": "linear", - "floor": None, - "bandpass": [7e-7, 9e-7], - } - restored = po.from_mapping(saved) - assert restored.spectral_limits == (1e14, None) - assert restored.time_limits == (None, None) and restored.floor == -60.0 - assert restored.bandpass == (7e-7, 9e-7) and restored.scale == "linear" - assert po.from_mapping({"axis": "omega"}).axis == "wavelength" def test_every_label_names_a_keyword_of_a_route(): @@ -164,6 +78,8 @@ def test_every_label_names_a_keyword_of_a_route(): for entries in described["types"].values(): keywords |= {entry["name"] for entry in entries} assert set(LABELS) <= keywords + assert label("energy") == LABELS["energy"] + assert label("pressure_floor") == "Pressure floor" def test_a_remote_run_folder_keeps_a_workspace_given_in_full(): @@ -175,11 +91,3 @@ def test_a_remote_run_folder_keeps_a_workspace_given_in_full(): found = remote_run_folder("/scratch/runs", "/home/me", None, when) assert found.startswith("/scratch/runs/2026-11-07-") and found.endswith("-090001") assert remote_run_folder("~", "/home/me/", "t", when).startswith("/home/me/2026") - - -def test_the_per_width_keywords_are_solprop_s(): - from solprop.recipe.metadata import PER_WIDTH_KEYWORDS # noqa: PLC0415 - - from solprop_gui.ui.pages import PER_WIDTH # noqa: PLC0415 - - assert PER_WIDTH == PER_WIDTH_KEYWORDS diff --git a/gui/tests/test_ui.py b/gui/tests/test_ui.py index da6c80679..535e91127 100644 --- a/gui/tests/test_ui.py +++ b/gui/tests/test_ui.py @@ -17,7 +17,6 @@ from solprop_gui.model.recipe import MISSING from solprop_gui.ui.fields import ParameterRow from solprop_gui.ui.icons import DRAWINGS, icon -from solprop_gui.views.compare import CompareView from solprop_gui.views.live import OverviewView, decibels WAIT_MS = 120_000 @@ -298,20 +297,6 @@ def test_decibels_are_relative_to_the_reference(): assert decibels(np.array([0.0]), 0.0)[0] == pytest.approx(-300.0) -def test_compare_shares_one_reference(qtbot: QtBot, tmp_path: Path): - view = CompareView() - qtbot.addWidget(view) - view.add_run("a", AXES, [row_data(1, 0.5), row_data(0, 2.0)]) - view.add_run("b", AXES, [row_data(0, 1.0)]) - view.add_run("empty", AXES, []) - assert list(view.runs) == ["a", "b"] - peak = float(np.max(np.asarray(row_data(0, 2.0)["density"]["wavelength"]))) # pyright: ignore[reportIndexIssue] - assert view.reference() == pytest.approx(peak) # the highest first plane - shot(view, tmp_path, "compare") - view.clear() - assert view.reference() == 0.0 - - def test_every_drawing_makes_an_icon_with_each_badge(qtbot: QtBot): from PySide6.QtGui import QColor # noqa: PLC0415 - only here diff --git a/gui/tests/test_ui_machines.py b/gui/tests/test_ui_machines.py index e050e26a6..f847d6fe4 100644 --- a/gui/tests/test_ui_machines.py +++ b/gui/tests/test_ui_machines.py @@ -9,8 +9,12 @@ helper and the connection in depth. """ +import contextlib import json +import os import shutil +import sys +import threading from pathlib import Path from typing import Any @@ -45,6 +49,29 @@ def test_machines_are_remembered_with_this_computer_first(): assert [m.name for m in store.machines()] == [LOCAL] +def test_closing_closes_every_machine_s_connection_together(qtbot: QtBot): + del qtbot # the application + hub = MachineHub() + together = threading.Barrier(3) + met: list[str] = [] + + class Stuck: + """A connection whose close waits until every other close has begun.""" + + def __init__(self, name: str) -> None: + self.name = name + + def close(self) -> None: + with contextlib.suppress(threading.BrokenBarrierError): + together.wait(timeout=2.0) + met.append(self.name) + + for name in ("a", "b", "c"): + hub.connections[name] = Stuck(name) # pyright: ignore[reportArgumentType] + hub.close() + assert sorted(met) == ["a", "b", "c"] and hub.connections == {} + + def test_the_runs_on_line_offers_the_machines(qtbot: QtBot, tmp_path: Path): options = RunOptions() qtbot.addWidget(options) @@ -170,7 +197,6 @@ def test_a_run_is_started_and_followed_through_a_machine(qtbot: QtBot, tmp_path: assert kinds.count("row") == 6 and kinds[-1] == "finished" again = bridge.attach_on(Machine(LOCAL), "r1", str(tmp_path / "r1")) qtbot.waitUntil(again.ended.is_set, timeout=WAIT_MS) - handle.subscribe(3) # a record drops nothing: no replay needed bridge.close() @@ -198,6 +224,116 @@ def test_the_setup_dialog_shows_its_script_before_running_it( assert released.note.text() == "" and released.run_button.isEnabled() +@pytest.mark.skipif(sys.platform == "win32", reason="the script runs in a POSIX shell") +def test_the_setup_dialog_runs_its_script_and_keeps_the_python( + qtbot: QtBot, monkeypatch: pytest.MonkeyPatch +): + from solprop.service import install # noqa: PLC0415 - only here + + from solprop_gui.ui.setup_dialog import SetupDialog # noqa: PLC0415 - only here + + def local_shell(machine: Machine, askpass: str) -> tuple[list[str], dict[str, str]]: + """Run the script with this computer's shell, as ssh runs it on the machine.""" + del machine, askpass + return ["sh", "-s"], dict(os.environ) + + # The transport is this computer's shell, and the install a stub that names its + # Python as the real script's last line does; the thread, the log and the ending + # are the dialog's own. + monkeypatch.setattr(install, "_ssh_shell", local_shell) + dialog = SetupDialog(SLURM, "0.3.0") + qtbot.addWidget(dialog) + dialog.script.setPlainText( + f'echo installing\necho "{install.PYTHON_LINE}/env/bin/python"\n' + ) + dialog.start() + qtbot.waitUntil(lambda: dialog.python is not None, timeout=WAIT_MS) + assert dialog.python == "/env/bin/python" + log = dialog.log.toPlainText() + assert log.startswith("installing\n") + assert log.endswith("Set up: runs on cluster use /env/bin/python") + assert dialog.run_button.isEnabled() + + +def test_the_setup_dialog_says_why_a_machine_was_not_set_up(qtbot: QtBot): + from solprop_gui.ui.setup_dialog import SetupDialog # noqa: PLC0415 - only here + + # This computer has no SSH host, so the setup thread fails before running anything + # and the dialog reports the refusal rather than a Python. + dialog = SetupDialog(Machine(LOCAL), "0.3.0") + qtbot.addWidget(dialog) + dialog.start() + assert not dialog.run_button.isEnabled() + qtbot.waitUntil(lambda: "Not set up" in dialog.log.toPlainText(), timeout=WAIT_MS) + assert dialog.log.toPlainText().strip() == "Not set up: local has no SSH host" + assert dialog.python is None + assert dialog.run_button.isEnabled() + + +@pytest.mark.parametrize( + ("question", "echo"), + [("me@lab's password:", "Password"), ("Verification code:", "Normal")], +) +def test_askpass_prints_the_answer_to_ssh_s_question( + qtbot: QtBot, + monkeypatch: pytest.MonkeyPatch, + capsys: pytest.CaptureFixture[str], + question: str, + echo: str, +): + from PySide6.QtWidgets import QInputDialog, QLineEdit # noqa: PLC0415 - only here + + from solprop_gui import askpass # noqa: PLC0415 - only here + + del qtbot # the application + asked: list[tuple[str, QLineEdit.EchoMode]] = [] + + def answer( + parent: object, title: str, label: str, mode: QLineEdit.EchoMode + ) -> tuple[str, bool]: + del parent, title + asked.append((label, mode)) + return "the answer", True + + monkeypatch.setattr(QInputDialog, "getText", answer) + assert askpass.main(question.split()) == 0 + # A password is asked hidden; a one-time code is shown as it is typed. + assert asked == [(question, getattr(QLineEdit.EchoMode, echo))] + assert capsys.readouterr().out == "the answer\n" + + +def test_askpass_answers_nothing_when_cancelled( + qtbot: QtBot, + monkeypatch: pytest.MonkeyPatch, + capsys: pytest.CaptureFixture[str], +): + from PySide6.QtWidgets import QInputDialog # noqa: PLC0415 - only here + + from solprop_gui import askpass # noqa: PLC0415 - only here + + del qtbot # the application + monkeypatch.setattr(QInputDialog, "getText", lambda *args: ("", False)) + assert askpass.main([]) == 1 + assert capsys.readouterr().out == "" + + +@pytest.mark.skipif(sys.platform == "win32", reason="the POSIX script") +def test_askpass_program_is_a_private_script_running_the_module( + monkeypatch: pytest.MonkeyPatch, tmp_path: Path +): + from solprop_gui import askpass # noqa: PLC0415 - only here + + monkeypatch.setattr(Path, "home", lambda: tmp_path) + written = askpass.askpass_program() + program = tmp_path / ".solprop-gui" / "askpass.sh" + assert written == str(program) + text = program.read_text(encoding="utf-8") + assert text == ( + f"#!/bin/sh\nexec '{sys.executable}' -m solprop_gui.askpass \"$@\"\n" + ) + assert program.stat().st_mode & 0o777 == 0o700 + + def test_a_copy_is_fetched_in_pieces_and_resumed( qtbot: QtBot, tmp_path: Path, monkeypatch ): @@ -247,20 +383,27 @@ def test_a_copy_is_fetched_in_pieces_and_resumed( assert target.read_bytes() == source.read_bytes() # A file that changes while it is copied is not kept. growing: list[tuple[object, object]] = [] + connection = hub.connections[LOCAL] + piece = connection.call - def grow(have: int, total: int) -> None: - if have < total: + def grow(kind: str, body: Any = None) -> Any: + """Answer as the helper does, the file growing after each piece.""" + value = piece(kind, body) + if kind == "fetch": with source.open("ab") as stream: stream.write(b"more") - - hub.fetch( - LOCAL, - str(source), - tmp_path / "copies" / "grown.h5", - grow, - lambda value, error: growing.append((value, error)), - ) - qtbot.waitUntil(lambda: bool(growing), timeout=WAIT_MS) + return value + + with monkeypatch.context() as patched: + patched.setattr(connection, "call", grow) + hub.fetch( + LOCAL, + str(source), + tmp_path / "copies" / "grown.h5", + lambda have, total: None, + lambda value, error: growing.append((value, error)), + ) + qtbot.waitUntil(lambda: bool(growing), timeout=WAIT_MS) assert growing[0][0] is None and "changed while it was copied" in str(growing[0][1]) assert not (tmp_path / "copies" / "grown.h5").exists() missing: list[tuple[object, object]] = [] @@ -418,6 +561,50 @@ def test_files_are_copied_to_a_machine_before_its_request( hub.close() +def test_the_runs_window_shows_how_far_a_fetched_copy_has_got( + qtbot: QtBot, tmp_path: Path, run: str, monkeypatch +): + import threading # noqa: PLC0415 - only here + + from solprop_gui.ui import machines_hub, runs_window # noqa: PLC0415 + + monkeypatch.setattr(machines_hub, "CHUNK", 4096) # a copy in many pieces + shown: list[tuple[int, bool]] = [] + + class Dialog(runs_window.QProgressDialog): + """The fetch's progress dialog, remembering each value and its thread.""" + + def setValue(self, value: int) -> None: # noqa: N802 - Qt's name + here = threading.current_thread() is threading.main_thread() + shown.append((value, here)) + super().setValue(value) + + monkeypatch.setattr(runs_window, "QProgressDialog", Dialog) + workspace = tmp_path / "runs" + folder = workspace / "r1" + folder.mkdir(parents=True) + shutil.copy(run, folder / "run.h5") + (folder / "recipe.toml").write_text('[recipe]\ntitle = "Two modes"\n', "utf-8") + target = tmp_path / "copies" / "run.h5" + hub = MachineHub() + hub.ensure(Machine(LOCAL)) + window = RunsWindow( + lambda: [Machine(LOCAL)], hub, lambda: workspace, lambda *_: target + ) + qtbot.addWidget(window) + window.show() + qtbot.waitUntil(lambda: window.table.rowCount() == 1, timeout=WAIT_MS) + window.table.selectRow(0) + with qtbot.waitSignal(window.fetched, timeout=WAIT_MS) as fetched: + window._fetch() + assert fetched.args == [str(target)] + assert target.read_bytes() == (folder / "run.h5").read_bytes() + assert len(shown) > 2 and shown[-1] == (1000, True) # piece by piece, to the end + assert all(here for _, here in shown) # every value set on the window's thread + window.hide() + hub.close() + + def test_a_stopped_run_is_resumed_from_the_runs_window(qtbot: QtBot, tmp_path: Path): from conftest import SLOW # noqa: PLC0415 - only here from solprop_gui.ui.workflow_window import WorkflowWindow # noqa: PLC0415 diff --git a/gui/tests/test_ui_options.py b/gui/tests/test_ui_options.py deleted file mode 100644 index ba59fc0d3..000000000 --- a/gui/tests/test_ui_options.py +++ /dev/null @@ -1,53 +0,0 @@ -# SPDX-FileCopyrightText: 2026 John C. Travers and contributors -# -# SPDX-License-Identifier: GPL-3.0-or-later - -"""The plot options panel, and the window keeping one set of options everywhere.""" - -from pathlib import Path - -import pytest -from pytestqt.qtbot import QtBot - -from solprop_gui.model.plot_options import PlotOptions -from solprop_gui.ui.plot_options import PlotOptionsPanel -from test_ui import WAIT_MS, private_settings, shot # noqa: F401 - a fixture - - -def type_into(field, text: str) -> None: - field.setText(text) - field.editingFinished.emit() - - -def test_the_panel_reads_limits_scale_and_band(qtbot: QtBot, tmp_path: Path): - panel = PlotOptionsPanel("t") - qtbot.addWidget(panel) - seen: list[PlotOptions] = [] - panel.changed.connect(seen.append) - type_into(panel.spectral.low, "1200") - type_into(panel.spectral.high, "400") # either order - assert seen[-1].spectral_limits == (pytest.approx(4e-7), pytest.approx(1.2e-6)) - type_into(panel.time.low, "-100") - assert seen[-1].time_limits == (pytest.approx(-1e-13), None) - type_into(panel.time.high, "soon") # not a number: marked, nothing sent - assert "not a number" in panel.note.text() and len(seen) == 3 - assert panel.time.high.styleSheet() - type_into(panel.time.high, "") - panel.scale.setCurrentText("linear") - assert seen[-1].scale == "linear" and not panel.floor.isEnabled() - panel.band_on.setChecked(True) # no band typed yet - assert "two positive wavelengths" in panel.note.text() - type_into(panel.band.low, "700") - type_into(panel.band.high, "900") - assert seen[-1].bandpass == (pytest.approx(7e-7), pytest.approx(9e-7)) - count = len(seen) - type_into(panel.band.high, "900") # unchanged: not sent again - assert len(seen) == count - # A new axis clears the limits typed in the old one's unit. - panel.axis.setCurrentIndex(panel.axis.findData("f")) - assert seen[-1].axis == "f" and seen[-1].spectral_limits == (None, None) - assert panel.spectral.unit.text() == "THz" - shot(panel, tmp_path, "plot-options") - panel.reset.click() - assert seen[-1] == PlotOptions() and not panel.band_on.isChecked() - assert panel.options == PlotOptions() diff --git a/gui/tests/test_ui_results.py b/gui/tests/test_ui_results.py deleted file mode 100644 index 35e3500dd..000000000 --- a/gui/tests/test_ui_results.py +++ /dev/null @@ -1,248 +0,0 @@ -# SPDX-FileCopyrightText: 2026 John C. Travers and contributors -# -# SPDX-License-Identifier: GPL-3.0-or-later - -"""The Plane and Statistics views, alone and with a real run, offscreen.""" - -from pathlib import Path - -import numpy as np -import pytest -from pytestqt.qtbot import QtBot - -from solprop_gui.model.plot_options import PlotOptions -from solprop_gui.model.stats_layout import STEP -from solprop_gui.views.plane import PlaneView -from solprop_gui.views.statistics import StatisticsView, StatsSelector -from test_ui import WAIT_MS, private_settings, shot # noqa: F401 - a fixture - -OMEGA = 2 * np.pi * 299_792_458.0 / np.linspace(1.2e-6, 5e-7, 50) - - -def spectrogram_reply() -> dict[str, object]: - t = np.linspace(-5e-14, 5e-14, 30) - x = np.linspace(6e-7, 1e-6, 40) - values = np.exp(-(((x[:, None] - 8e-7) / 5e-8) ** 2) - (t[None, :] / 1e-14) ** 2) - return { - "t": t, - "x": x, - "values": values, - "axis": "wavelength", - "mode": 0, - "gate_fwhm": 5e-15, - } - - -def _gate(results) -> float: - data = results.plane.spectrogram.data - return 0.0 if data is None else float(data["gate_fwhm"]) - - -def plane_reply(*, phase: bool = True) -> dict[str, object]: - wavelength = 2 * np.pi * 299_792_458.0 / OMEGA - density = np.exp(-(((wavelength - 8e-7) / 5e-8) ** 2)) - t = np.linspace(-1e-13, 1e-13, 64) - return { - "z": 0.05, - "labels": ["HE1,1", "HE1,2"], - "spectrum": {"x": wavelength, "y": density}, - "power": {"t": t, "y": 1e9 * np.exp(-((t / 1e-14) ** 2))}, - "phase": {"omega": OMEGA, "y": np.linspace(0, 3, OMEGA.size)} - if phase - else {"error": "a sum has no phase"}, - } - - -def test_the_plane_view_asks_and_draws(qtbot: QtBot, tmp_path: Path): - view = PlaneView() - qtbot.addWidget(view) - view.resize(1000, 600) - assert not view.slider.isEnabled() - asked = [] - view.plane_wanted.connect(lambda *args: asked.append(("plane", *args))) - view.spectrogram_wanted.connect(lambda *args: asked.append(("sg", *args))) - view.figure_wanted.connect(lambda figure: asked.append(("figure", figure))) - view.set_planes([0, 2], [0.0, 0.05], ["HE1,1", "HE1,2"]) - # Each plane is asked for with its spectrogram. - assert asked[-2:] == [("plane", 2, "sum"), ("sg", 2, "sum")] - assert "5 cm" in view.where.text() - view.slider.setValue(0) - assert asked[-2] == ("plane", 0, "sum") - view.modes.setCurrentIndex(2) - assert asked[-2:] == [("plane", 0, 1), ("sg", 0, 1)] - view.modes.setCurrentIndex(0) - view.show_plane(plane_reply()) - assert "Peak power 975.1 MW" in view.status.text() # the 64-sample peak - assert "first mode" in view.status.text() # a sum of two modes - ys = np.asarray(view.phase_curve.getData()[1], dtype=float) - assert np.isnan(ys).any() and np.isfinite(ys).any() # dark edges left out - shot(view, tmp_path, "plane") - view.export_data(tmp_path / "plane.csv") - lines = (tmp_path / "plane.csv").read_text(encoding="utf-8").splitlines() - assert lines[0].startswith("spectrum: wavelength (nm)") and len(lines) == 1 + 64 - view.show_plane(plane_reply(phase=False)) - assert "No phase" in view.status.text() - view.export_figure("x.pdf", "spec_1d") - assert asked[-1][1]["plot"] == "spec_1d" - view.show_error("refused") - assert view.status.text() == "refused" - view.clear() - assert view.planes == [] and "No plane" in view.where.text() - count = len(asked) - view.ask_spectrogram() # no planes: nothing asked - view._ask() - assert len(asked) == count - - -def test_the_plane_view_draws_its_spectrogram(qtbot: QtBot): - view = PlaneView() - qtbot.addWidget(view) - view.resize(1000, 600) - view.show_spectrogram(spectrogram_reply()) - plot = view.spectrogram - assert plot.shown.shape == (40, 30) and plot.shown.max() == pytest.approx(0.0) - hit = plot.lookup(0.0, 800.0) - assert hit is not None and "fs" in hit[2] and plot.lookup(1e6, 0.0) is None - view.apply_options(PlotOptions(scale="linear", time_limits=(-2e-14, 2e-14))) - assert plot.shown.max() == pytest.approx(1.0) - assert plot.plot.getViewBox().viewRange()[0] == pytest.approx([-20, 20]) - view.clear() - assert plot.lookup(0.0, 800.0) is None # forgotten - plot.redraw(PlotOptions()) # nothing to draw - - -def test_the_plane_view_follows_the_plot_options(qtbot: QtBot): - view = PlaneView() - qtbot.addWidget(view) - view.resize(1000, 600) - view.show_plane(plane_reply()) - view.apply_options(PlotOptions(scale="linear", time_limits=(-5e-14, 5e-14))) - assert view.power_plot.getViewBox().viewRange()[0] == pytest.approx([-50, 50]) - view.apply_options(PlotOptions(spectral_limits=(6e-7, 1e-6))) - assert view.spectrum_plot.getViewBox().viewRange()[0] == pytest.approx([600, 1000]) - # A frequency axis: the spectrum and the phase in THz; wavelength limits unused. - frequency = {**plane_reply(), "axis": "f"} - frequency["spectrum"] = {"x": OMEGA / (2 * np.pi), "y": np.ones(OMEGA.size)} - view.apply_options(PlotOptions(bandpass=(7e-7, 9e-7))) - view.show_plane(frequency) - assert view.spectrum_plot.getAxis("bottom").labelText == "Frequency (THz)" - xs = np.asarray(view.phase_curve.getData()[0], dtype=float) - assert 240 < xs.min() < xs.max() < 610 # 1.2 µm to 500 nm, in THz - assert "within 700-900 nm" in view.status.text() - view.apply_options(PlotOptions(axis="f", spectral_limits=(300e12, 400e12))) - assert view.spectrum_plot.getViewBox().viewRange()[0] == pytest.approx([300, 400]) - view.show_plane(plane_reply()) - - -def test_a_spatial_plane_shows_its_fluence(qtbot: QtBot, tmp_path: Path): - view = PlaneView() - qtbot.addWidget(view) - view.set_planes([0, 1], [0.0, 0.02]) - x, y = np.linspace(-1e-3, 1e-3, 4), np.linspace(-2e-3, 2e-3, 5) - reply = plane_reply() - spatial = { - **reply, - "spectrum": {**reply["spectrum"], "unit": "J per bin"}, # pyright: ignore[reportGeneralTypeIssues] - "fluence": { - "axes": {"y": y, "x": x}, - "values": np.ones((5, 4)), - "unit": "J/m^2", - }, - } - view.show_plane(spatial) - assert ( - view.image.isVisible() - and "Energy per bin" in view.spectrum_plot.getAxis("left").labelText - ) - shot(view, tmp_path, "fluence") - radial = {"axes": {"r": x}, "values": np.ones(4), "unit": "J/m^2"} - view.show_plane({**spatial, "fluence": radial}) - assert not view.image.isVisible() - view.show_plane({**spatial, "fluence": {"error": "not rebuilt"}}) - assert "No fluence: not rebuilt" in view.status.text() - # A planar plane: no spectrum, solprop says why; the phase still drawn. - view.show_plane({**reply, "spectrum": {"error": "planar planes are not exchanged"}}) - assert "No spectrum: planar" in view.status.text() - - -def test_the_statistics_view_draws_every_statistic(qtbot: QtBot, tmp_path: Path): - view = StatisticsView() - qtbot.addWidget(view) - view.resize(900, 600) - reply = { - "z": [0.0, 0.01, 0.02], - "stats": [ - { - "name": "energy", - "summary": "Energy.", - "units": "J", - "columns": [ - {"label": "HE1,1", "y": [1e-6, 1e-6, 0.9e-6]}, - {"label": "HE1,2", "y": [0.0, 1e-8, 2e-8]}, - ], - }, - { - "name": "density", - "summary": "Density.", - "units": "m^-3", - "columns": [{"label": "density", "y": [1, 2, 3]}], - }, - ], - "steps": { - "z": [0.0, 0.01, 0.02], - "h": [1e-4, 2e-4, 2e-4], - "rejected_z": [0.015], - "rejected_h": [5e-4], - }, - } - selector = StatsSelector() - qtbot.addWidget(selector) - view.layout_changed.connect(selector.set_layout) - selector.changed.connect(view.set_layout) - view.set_statistics(reply) - # One statistic a panel, no step size: two panels, in a column. - empty = (None, None) - assert view.chosen == (("energy", None), ("density", None), empty, empty) - shown = [panel.plot.isVisible() for panel in view.panels] - assert shown == [True, True, False, False] and "1 rejected" in view.summary.text() - top = view.panels[0] - assert len(top.curves) == 2 # a column per mode - hit = top.lookup(1.0, 1e-6) - assert hit is not None and "z = 1 cm" in hit[2] - assert "m^-3" in view.panels[1].plot.getAxis("left").labelText - assert selector.chosen() == view.chosen - # Two on one panel, dual axes, and the step size where it is asked for. - left, right = selector.choices[0] - right.setCurrentIndex(right.findData("density")) - assert selector.chosen()[0] == view.panel_choice(0) == ("energy", "density") - assert "density" in top.plot.getAxis("right").labelText - assert len(top.curves) == 2 # the readout reads the left axis - left, _ = selector.choices[3] - left.setCurrentIndex(left.findData(STEP)) - steps = view.panels[3] - assert steps.plot.isVisible() and steps.plot.getAxis("left").logMode - assert all(panel.plot.isVisible() for panel in view.panels[:2]) - shot(view, tmp_path, "statistics") - # Another run keeps the choices it can. - view.set_statistics({**reply, "stats": reply["stats"][1:]}) - assert view.panel_choice(0) == ("density", None) - assert view.panel_choice(3) == (STEP, None) - seen = [] - view.figure_wanted.connect(seen.append) - view.export_figure("s.pdf") - assert seen == [{"file": "s.pdf", "plot": "plot_stats"}] - view.clear() - assert view.panels[0].curves == [] and view.panels[0].lookup(0.0, 0.0) is None - assert not view.figure_button.isEnabled() - - -def test_the_overview_names_a_beam_s_readings(qtbot: QtBot): - from solprop_gui.views.live import OverviewView # noqa: PLC0415 - only here - - view = OverviewView() - qtbot.addWidget(view) - view.set_spatial(True) - assert "Axial power" in view.power_map.plot.titleLabel.text - assert "Energy per bin" in view.spectrum_map.plot.titleLabel.text - view.set_spatial(False) - assert view.power_line.titleLabel.text == "Power at z" diff --git a/gui/tests/test_ui_review.py b/gui/tests/test_ui_review.py index 7e562bbcf..7b2493f52 100644 --- a/gui/tests/test_ui_review.py +++ b/gui/tests/test_ui_review.py @@ -2,30 +2,16 @@ # # SPDX-License-Identifier: GPL-3.0-or-later -"""The second review's details: a failed run's dialog, a route's words, cross-hairs.""" +"""A plot readout's cross-hairs, offscreen.""" import numpy as np import pyqtgraph as pg from pytestqt.qtbot import QtBot -from solprop_gui.registry.pages import PAGES -from solprop_gui.ui.pages import ParameterPage from solprop_gui.views.plotting import HoverLayout, curve_lookup, figure_spec from test_ui import private_settings # noqa: F401 - a fixture -def test_a_free_space_route_words_the_geometry_step(qtbot: QtBot): - geometry = next(page for page in PAGES if page.key == "geometry") - page = ParameterPage(geometry) - qtbot.addWidget(page) - page.set_route("free") - assert "transverse grid" in page.help.text() - assert page.sections["geometry"].header.text() == "Beam and grid" - page.set_route("capillary") - assert page.help.text() == geometry.help - assert page.sections["geometry"].header.text() == "Waveguide" - - def test_a_readout_has_cross_hairs_left_out_of_a_figure(qtbot: QtBot): layout = HoverLayout() qtbot.addWidget(layout) diff --git a/gui/tests/test_ui_scans.py b/gui/tests/test_ui_scans.py index 578fcd64a..20df42a89 100644 --- a/gui/tests/test_ui_scans.py +++ b/gui/tests/test_ui_scans.py @@ -2,7 +2,7 @@ # # SPDX-License-Identifier: GPL-3.0-or-later -"""The scan editor, the scan browser and a scan run from its stage, offscreen.""" +"""The scan editor and a scan run from its stage, offscreen.""" from pathlib import Path @@ -17,7 +17,6 @@ from solprop_gui.ui.scan_editor import ScanEditor from solprop_gui.ui.scan_stage import ScanStage from solprop_gui.ui.workflow_window import WorkflowWindow -from solprop_gui.views.scan_browser import ScanView from test_design import SCAN from test_ui import WAIT_MS, private_settings, shot # noqa: F401 - a fixture @@ -68,44 +67,6 @@ def test_the_scan_editor_writes_the_scan_table(qtbot: QtBot): editor.enabled.setChecked(False) -def test_the_scan_browser_draws_a_line_or_a_map(qtbot: QtBot, tmp_path: Path): - view = ScanView() - qtbot.addWidget(view) - view.resize(700, 450) - line = { - "variables": [{"name": "pressure", "values": [0.5, 1.0, 1.5]}], - "shape": [3], - "status": ["done", "failed", "done"], - "results": { - "stats/energy": { - "summary": "Energy.", - "units": "J", - "values": np.array([1e-4, np.nan, 0.9e-4]), - } - }, - } - view.set_scan(line) - assert "1 failed" in view.status.text() - xs = np.asarray(view.failed.getData()[0], dtype=float) - assert list(xs) == [1.0] - shot(view, tmp_path, "scan-line") - grid = { - "variables": [ - {"name": "pressure", "values": [0.5, 1.0]}, - {"name": "energy", "values": [1e-4, 2e-4, 3e-4]}, - ], - "shape": [2, 3], - "status": [["done"] * 3] * 2, - "results": { - "stats/energy": {"summary": "", "units": "J", "values": np.ones((2, 3))} - }, - } - view.set_scan(grid) - assert view.image.isVisible() - view.show_error("no scan") - assert view.status.text() == "no scan" and view.result.count() == 0 - - def test_a_scan_set_up_on_its_stage_runs_and_shows_its_results( # noqa: PLR0915 - one story qtbot: QtBot, tmp_path: Path ) -> None: @@ -169,6 +130,44 @@ def test_a_scan_set_up_on_its_stage_runs_and_shows_its_results( # noqa: PLR0915 window.close() +def test_a_scan_stopped_before_it_starts_leaves_scan_mode( + qtbot: QtBot, tmp_path: Path +) -> None: + window = WorkflowWindow(workspace=tmp_path / "workspace") + qtbot.addWidget(window) + window.show() + window.document.confirm = lambda _title, _text: "discard" + window.document.set_model(RecipeModel(SCAN), base=None) + qtbot.waitUntil(lambda: window.stage is Stage.SETUP, timeout=WAIT_MS) + qtbot.waitUntil(lambda: "pressure" in window.scans.editor.paths, timeout=WAIT_MS) + qtbot.waitUntil(lambda: window.progress().can_run, timeout=WAIT_MS) + window.show_stage(Stage.SCAN) + assert window.primary.isEnabled() + ended: list[str] = [] + window.run_panel.ended.connect(ended.append) + window.primary.click() + + def submitted() -> bool: + return any((tmp_path / "workspace").rglob("submitted.json")) + + # Started, and its job still importing solprop (about a second): Stop now is + # found by the job when it starts. + qtbot.waitUntil(submitted, timeout=WAIT_MS) + window.run_panel.stop() + qtbot.waitUntil(lambda: bool(ended), timeout=WAIT_MS) + (folder,) = (tmp_path / "workspace").iterdir() + assert window.run_panel.state_label.text().endswith("stopped") + # Nothing written, so nothing opened, and the window has left scan mode: the + # next Run from the sheet runs the setup once, not the scan. + written = folder / SCAN_OUTPUT + assert not written.exists() # stopped before it started + assert ended == [""] + assert window.session.path is None and window.stage is Stage.SCAN + assert not window._scanning + assert "[scan]" not in window._run_recipe()[0] + window.close() + + def test_a_number_s_menu_on_the_sheet_scans_it(qtbot: QtBot, tmp_path: Path) -> None: window = WorkflowWindow(workspace=tmp_path / "workspace") qtbot.addWidget(window) diff --git a/gui/tests/test_ui_workflow.py b/gui/tests/test_ui_workflow.py index e499b9be3..b613fa633 100644 --- a/gui/tests/test_ui_workflow.py +++ b/gui/tests/test_ui_workflow.py @@ -4,6 +4,7 @@ """The workflow window, offscreen: Home, Setup, Run and Analyse, for every class.""" +import gc import warnings from collections.abc import Iterator from pathlib import Path @@ -18,7 +19,7 @@ from shiboken6 import isValid from solprop.constants import C from solprop.output import open_file -from solprop.service.messages import Event +from solprop.service.messages import Event, Reply from solprop.service.states import ExecutionState from conftest import TINY @@ -53,7 +54,7 @@ from solprop_gui.ui.home import HomePage from solprop_gui.ui.quantity import QuantityField, _readable from solprop_gui.ui.theme import FONT -from solprop_gui.ui.workflow_window import WorkflowWindow +from solprop_gui.ui.workflow_window import WorkflowWindow, collect_between_events from solprop_gui.views.cross_section import CrossSection WAIT_MS = 120_000 @@ -91,6 +92,19 @@ def shot(widget: QWidget, folder: Path, name: str) -> None: assert image.save(str(folder / f"{name}.png")) +def listed_runs(home: HomePage) -> list[str]: + """Return the first line of each item Home lists under its runs.""" + texts = [] + for index in range(home.runs.count()): + entry: Any = home.runs.itemAt(index) + item = entry.widget() + if not isinstance(item, QLabel): # an item: its title line + item = item.findChild(QLabel, "itemTitle") + assert isinstance(item, QLabel) + texts.append(item.text()) + return texts + + def open_tiny(window: WorkflowWindow, qtbot: QtBot) -> None: """Open the quick capillary, and wait until solprop has accepted it.""" window.document.set_model(RecipeModel(TINY), base=None) @@ -124,10 +138,11 @@ def test_home_offers_each_class_and_asks_for_nothing_open( assert window.home.workspace.text().startswith("In ") elsewhere = tmp_path / "elsewhere" elsewhere.mkdir() - window.run_panel.set_workspace(elsewhere) + with qtbot.waitSignal(window.runs_listed, timeout=WAIT_MS): + window.run_panel.set_workspace(elsewhere) assert window.home.workspace.toolTip() == str(elsewhere) assert window.settings.value("workspace") == str(elsewhere) - assert window.home.runs.count() == 1 # "No runs yet." in the new folder + assert listed_runs(window.home) == ["No runs yet."] # none in the new folder window.home.show_workspace(Path.home() / "runs") assert window.home.workspace.text() == "In ~/runs" @@ -299,17 +314,47 @@ def test_the_gas_is_a_list_with_plain_names( assert row.choice.currentText().startswith("Helium") -def test_a_lost_worker_explains_itself(window: WorkflowWindow, qtbot: QtBot) -> None: +def test_a_lost_run_explains_itself(window: WorkflowWindow, qtbot: QtBot) -> None: open_tiny(window, qtbot) panel = window.run_panel panel.run_id = "gone" panel.state = ExecutionState.RUNNING - panel.on_event(Event("gone", "lost", {"exitcode": -9})) + panel.on_event(Event("gone", "lost", {"message": "out of memory"})) assert not window.analyse.advice.isHidden() - assert "out of memory" in window.analyse.advice_text.text() + assert "(out of memory)" in window.analyse.advice_text.text() assert "LowStorageRungeKutta" in window.analyse.advice_text.text() +def test_a_host_collects_garbage_on_a_timer_not_automatically(qtbot: QtBot) -> None: + del qtbot # the application, for the collector's timer + gc.enable() + try: + collector = collect_between_events() + assert not gc.isenabled() and collector.timer.isActive() + collector.timer.stop() + finally: + gc.disable() # as the suite keeps it (conftest.py) + + +def test_a_failed_reply_to_the_windows_own_request_is_said( + window: WorkflowWindow, +) -> None: + bar = window.statusBar() + window._pending[-7] = "gases" + window._on_reply(Reply("gases", -7, 0, error="no gas data")) + assert ( + bar.currentMessage() == "solprop could not give the list of gases: no gas data" + ) + window._pending[-6] = "warm-rdw" + window._on_reply(Reply("example", -6, 0, error="gone")) + assert bar.currentMessage() == "solprop could not give the example rdw: gone" + # A superseded reply is no failure: a newer request answers instead. + bar.clearMessage() + window._pending[-5] = "curve" + window._on_reply(Reply("curve", -5, 0, superseded=True)) + assert bar.currentMessage() == "" + + def test_the_sheet_helps_finds_and_folds(window: WorkflowWindow, qtbot: QtBot) -> None: open_tiny(window, qtbot) sheet = window.sheet @@ -415,9 +460,10 @@ def test_a_run_goes_from_setup_to_analyse_with_one_scrubber( assert not window.analyse.rail.isVisible() window.show_stage(Stage.SETUP) assert window.top.isVisible() - window.show_stage(Stage.HOME) + with qtbot.waitSignal(window.runs_listed, timeout=WAIT_MS): + window.show_stage(Stage.HOME) assert window.top.isVisible() # the stages lead back to what is open - assert window.home.runs.count() == 1 + assert listed_runs(window.home) == [Path(session.path or "").parent.name] def test_results_from_home_find_their_class_and_restore_the_setup( @@ -1043,7 +1089,7 @@ def test_a_solid_core_fibre_runs_and_every_page_reads_it( # noqa: PLR0915 - one low, high = overview.spectrum_map.box.viewRange()[0] assert low > 500.0 assert high < 2000.0 - assert not analyse.buttons["noise"].isEnabled() + assert "noise" not in analyse.buttons # no run is a seeded ensemble yet # A plane that has arrived but is not drawn yet is read as the last drawn one. top = float(overview.rows[-1]["z"]) * overview._unit[1] overview.rows.append({**overview.rows[-1], "z": 2 * float(overview.rows[-1]["z"])}) @@ -1229,7 +1275,7 @@ def test_a_fibre_has_its_own_rows_and_no_map( assert stage.fields["lattice.n_tubes"].isVisible() assert not stage.solve_button.isEnabled() zero = stage.numbers["zdw"] - qtbot.waitUntil(lambda: zero.text() == "483 nm", timeout=WAIT_MS) + qtbot.waitUntil(lambda: zero.text() == "484 nm", timeout=WAIT_MS) stage.show_page("map") assert stage.page == "curves" assert "capillary" in stage.note.text() diff --git a/gui/tools/geometry_icons.py b/gui/tools/geometry_icons.py deleted file mode 100644 index 6a0cbe74d..000000000 --- a/gui/tools/geometry_icons.py +++ /dev/null @@ -1,225 +0,0 @@ -# SPDX-FileCopyrightText: 2026 John C. Travers and contributors -# -# SPDX-License-Identifier: GPL-3.0-or-later - -"""Draw the start page's geometry pictures: a simple cross-section of each class. - -Run ``python gui/tools/geometry_icons.py`` to rewrite -``gui/src/solprop_gui/help/figures/<card key>.svg``; a test checks the committed -pictures are this script's. They are after the user guide's geometry figures, reduced -to what tells the classes apart, and styled with the guide's palette as CSS custom -properties (light, and dark under ``prefers-color-scheme``). -""" - -import math -import sys -from pathlib import Path - -FIGURES = ( - Path(__file__).resolve().parents[1] / "src" / "solprop_gui" / "help" / "figures" -) - -HEAD = """<?xml version="1.0" encoding="UTF-8"?> -<!-- SPDX-FileCopyrightText: 2026 John C. Travers and contributors --> -<!-- SPDX-License-Identifier: GPL-3.0-or-later --> -<svg xmlns="http://www.w3.org/2000/svg" width="200" height="150" viewBox="0 0 200 150"> -<style> -svg { - --ink: #1b1f24; - --dim: #5b6673; - --gas-fill: #e9f1fb; - --glass-fill: #d5e9dc; - --glass-edge: #2c7a55; - --core-fill: #cfe0f4; - --core-edge: #2f5eb0; - --beam: #b8334f; - --beam-b: #6f45a6; - --beam-c: #a96a15; -} -@media (prefers-color-scheme: dark) { - svg { - --ink: #e7eaef; - --dim: #9aa5b3; - --gas-fill: #18222f; - --glass-fill: #173528; - --glass-edge: #5cb98a; - --core-fill: #1d3150; - --core-edge: #7ba6e8; - --beam: #ee8ca0; - --beam-b: #b99ae6; - --beam-c: #e0a44f; - } -} -.glass { fill: var(--glass-fill); stroke: var(--glass-edge); stroke-width: 2; } -.gas { fill: var(--gas-fill); stroke: var(--glass-edge); stroke-width: 1.2; } -.core { fill: var(--core-fill); stroke: var(--core-edge); stroke-width: 1.5; } -.axis { fill: none; stroke: var(--dim); stroke-width: 1.2; } -.node { fill: var(--dim); stroke: none; } -.ring { fill: none; stroke: var(--dim); stroke-width: 1; stroke-dasharray: 3 3; } -.curve { fill: none; stroke: var(--beam); stroke-width: 2.4; } -.curve-b { fill: none; stroke: var(--beam-b); stroke-width: 2; } -.curve-c { fill: none; stroke: var(--beam-c); stroke-width: 2; } -.label { fill: var(--dim); font-family: sans-serif; font-size: 13px; - font-style: italic; } -</style> -<defs> -<radialGradient id="spot"> - <stop offset="0" stop-color="var(--beam)" stop-opacity="0.95"/> - <stop offset="0.55" stop-color="var(--beam)" stop-opacity="0.45"/> - <stop offset="1" stop-color="var(--beam)" stop-opacity="0"/> -</radialGradient> -<radialGradient id="graded"> - <stop offset="0" stop-color="var(--core-edge)" stop-opacity="0.75"/> - <stop offset="1" stop-color="var(--core-edge)" stop-opacity="0"/> -</radialGradient> -<linearGradient id="band" x1="0" y1="0" x2="0" y2="1"> - <stop offset="0" stop-color="var(--beam)" stop-opacity="0"/> - <stop offset="0.5" stop-color="var(--beam)" stop-opacity="0.9"/> - <stop offset="1" stop-color="var(--beam)" stop-opacity="0"/> -</linearGradient> -</defs> -""" -CX, CY = 100, 75 - - -def spot(r: float, cx: float = CX, cy: float = CY, rx: float | None = None) -> str: - """Return a soft spot of light, the beam's place in a cross-section.""" - rx = r if rx is None else rx - return f'<ellipse cx="{cx}" cy="{cy}" rx="{rx}" ry="{r}" fill="url(#spot)"/>\n' - - -def arrow( - start: tuple[float, float], - tip: tuple[float, float], - name: str, - offset: tuple[float, float] = (4, 4), -) -> str: - """Return an axis arrow from one point to another, labelled at its tip.""" - (x1, y1), (x2, y2), (dx, dy) = start, tip, offset - a = math.atan2(y2 - y1, x2 - x1) - h = [ - (x2 - 7 * math.cos(a - 0.45), y2 - 7 * math.sin(a - 0.45)), - (x2 - 7 * math.cos(a + 0.45), y2 - 7 * math.sin(a + 0.45)), - ] - return ( - f'<path class="axis" d="M{x1},{y1} L{x2},{y2} M{h[0][0]:.1f},{h[0][1]:.1f} ' - f'L{x2},{y2} L{h[1][0]:.1f},{h[1][1]:.1f}"/>\n' - f'<text class="label" x="{x2 + dx}" y="{y2 + dy}">{name}</text>\n' - ) - - -def capillary(body: str = "") -> str: - """Return a capillary's section: a glass ring around its gas, and what is in it.""" - return ( - f'<circle class="glass" cx="{CX}" cy="{CY}" r="64"/>\n' - f'<circle class="gas" cx="{CX}" cy="{CY}" r="50"/>\n' + body - ) - - -icons: dict[str, str] = {} -icons["capillary-averaged"] = capillary(spot(34)) -icons["capillary-modal"] = capillary( - spot(22) - + f'<circle class="curve-b" cx="{CX}" cy="{CY}" r="29"/>\n' - + f'<circle class="curve-c" cx="{CX}" cy="{CY}" r="40"/>\n' -) -tubes = "".join( - f'<circle class="glass" cx="{CX + 47 * math.cos(angle):.1f}" ' - f'cy="{CY + 47 * math.sin(angle):.1f}" r="13"/>\n' - for angle in (2 * math.pi * k / 7 + math.pi / 2 for k in range(7)) -) -icons["antiresonant"] = ( - f'<circle class="glass" cx="{CX}" cy="{CY}" r="70"/>\n' - f'<circle class="gas" cx="{CX}" cy="{CY}" r="62"/>\n' + tubes + spot(26) -) -icons["gnlse"] = ( - '<rect class="glass" x="10" y="86" width="180" height="40" rx="4"/>\n' - '<rect class="core" x="10" y="100" width="180" height="12"/>\n' - + '<path class="curve" d="' - + " ".join( - f"{'M' if k == 0 else 'L'}{x},{78 - 52 / math.cosh((x - 100) / 9):.1f}" - for k, x in enumerate(range(20, 182, 2)) - ) - + '"/>\n' - + '<text class="label" x="150" y="40">β(ω), γ</text>\n' # noqa: RUF001 -) -icons["step-index"] = ( - f'<circle class="glass" cx="{CX}" cy="{CY}" r="64"/>\n' - f'<circle class="core" cx="{CX}" cy="{CY}" r="18"/>\n' + spot(20) -) -icons["grin"] = ( - f'<circle class="glass" cx="{CX}" cy="{CY}" r="64"/>\n' - f'<circle cx="{CX}" cy="{CY}" r="34" fill="url(#graded)"/>\n' + spot(20) -) -icons["rectangular"] = ( - '<rect class="glass" x="22" y="27" width="156" height="96" rx="3"/>\n' - '<rect class="gas" x="36" y="41" width="128" height="68"/>\n' + spot(26, rx=50) -) -icons["slab"] = ( - '<rect class="glass" x="8" y="22" width="166" height="22"/>\n' - '<rect class="glass" x="8" y="106" width="166" height="22"/>\n' - '<rect class="gas" x="8" y="44" width="166" height="62" stroke="none"/>\n' - '<rect x="8" y="50" width="166" height="50" fill="url(#band)"/>\n' - + arrow((36, 140), (150, 140), "y", (6, 4)) - + arrow((186, 100), (186, 50), "x", (-4, -6)) -) -dots = "".join( - f'<circle class="node" cx="{40 + 12 * i}" cy="{27 + 12 * j}" r="1.6"/>\n' - for i in range(11) - for j in range(9) -) -icons["cartesian"] = ( - dots - + spot(30, rx=40) - + arrow((28, 137), (72, 137), "x") - + arrow((28, 137), (28, 93), "y", (-12, 2)) -) -xs = [30 + 2 * k for k in range(71)] -curve = " ".join( - f"{'M' if k == 0 else 'L'}{x},{98 - 70 / math.cosh((x - 100) / 14):.1f}" - for k, x in enumerate(xs) -) -icons["line"] = ( - "".join( - f'<circle class="node" cx="{30 + 7 * i}" cy="105" r="1.8"/>\n' - for i in range(21) - ) - + f'<path class="curve" d="{curve}"/>\n' - + arrow((30, 125), (174, 125), "x") -) -icons["radial"] = ( - "".join( - f'<circle class="ring" cx="{CX}" cy="{CY}" r="{r}"/>\n' - for r in (14, 28, 42, 56, 68) - ) - + spot(32) - + arrow((CX, CY), (CX + 66, CY - 24), "r", (2, -2)) -) - - -def pictures() -> dict[str, str]: - """Return each class's picture, by its card's key. - - Returns - ------- - dict - The SVG text of each. - """ - return {key: HEAD + body + "</svg>\n" for key, body in icons.items()} - - -def main(out: Path = FIGURES) -> None: - """Write the pictures. - - Parameters - ---------- - out : pathlib.Path, optional - The folder; the package's by default. - """ - out.mkdir(parents=True, exist_ok=True) - for key, text in pictures().items(): - (out / f"{key}.svg").write_text(text, encoding="utf-8") - - -if __name__ == "__main__": - main(Path(sys.argv[1]) if len(sys.argv) > 1 else FIGURES) diff --git a/hatch_build.py b/hatch_build.py index c4bcf49fe..612956e43 100644 --- a/hatch_build.py +++ b/hatch_build.py @@ -18,7 +18,7 @@ class NativePinHook(MetadataHookInterface): - """Write the dependencies, with native pinned, and the two extras.""" + """Write the dependencies, with native pinned, and the gui extra.""" PLUGIN_NAME = "custom" diff --git a/native/AGENTS.md b/native/AGENTS.md index 5ab5809ca..2a524f95d 100644 --- a/native/AGENTS.md +++ b/native/AGENTS.md @@ -50,8 +50,8 @@ approved dependencies are Kokkos, Kokkos Kernels (BLAS component) with a vendor behind it (the distribution build's BLAS on Linux and in the Windows wheel is OpenBLAS built with OpenMP from pinned source; a Windows build without it falls back to `scipy-openblas32`, a build requirement; each is carried in the wheel), Kokkos-FFT with -FFTW or the device FFT, SLEEF (the host vector maths, static, on x86-64 CPU builds; -solprop's ADR-059), nanobind +FFTW or the device FFT, SLEEF (the host vector maths, static, on x86-64 and macOS arm64 +CPU builds; solprop's ADR-059), nanobind and scikit-build-core; GoogleTest is test-only. Adding any other dependency needs approval. Major changes follow solprop's enhancement proposal process (SEPs, @@ -82,7 +82,7 @@ The native gate runs from the repository root: ```console uv run poe check-native # native/scripts/check.sh -uv run poe check-all # solprop's gate (poe check), then the native gate +uv run poe check-all # solprop's, the native and the front end's gates (gui extra) uv run poe fmt-native # clang-format every tracked C++ file in place uv run poe tidy-native # clang-tidy the C++ files changed from main (or those named) ``` @@ -91,8 +91,8 @@ uv run poe tidy-native # clang-tidy the C++ files changed from main (or those clang-tidy and warnings, native tests, ASan+UBSan native tests, an editable build with pytest, a distribution wheel build and a clean wheel smoke test; per-file copyright and licence (`reuse lint`) is in solprop's `poe check`, which covers `native/` too. A change -under `native/` is finished when `poe check-all` is green, so that solprop's test suite -has passed with this backend freshly built. Report the compiler, build type, execution +under `native/` is finished when `poe check` and `poe check-native` are green, so that +solprop's test suite has passed with this backend freshly built. Report the compiler, build type, execution space, thread settings and any check that was not run. CI (the repository's `.github/workflows/ci.yml`) runs on every push and pull request: @@ -101,9 +101,9 @@ each (`SOLPROP_NATIVE_CHECK_STAGES`). The `native-wheel` jobs build the CPU dist wheel on Linux, macOS and Windows, cached under a hash of `native/`, and solprop's default lane runs on it on macOS and Windows with the native backend selected, and in the coverage lane on Linux. The `device-compile` lanes compile the CUDA and HIP targets, tests included, on a change to -`native/`, with no device. Running on one stays by hand -(`.github/workflows/cuda.yml` on a self-hosted runner, with compute-sanitizer's four -tools, or `pytest -m gpu` on a machine with a device). `.github/workflows/native-deep.yml` +`native/`, with no device. Running on one stays by hand: `poe test-gpu` on a machine with +a device, or `.github/workflows/cuda.yml`, dispatched on a self-hosted runner labelled +`nvidia-gpu` (part of no gate), with compute-sanitizer's four tools. `.github/workflows/native-deep.yml` runs weekly and reports without gating: source coverage over the native tests, the extension under ASan and UBSan through the native pytest suite, and `misc-include-cleaner`. The tools adopted, scheduled and rejected are in @@ -210,7 +210,7 @@ the gate. Never call Python from a Kokkos or OpenMP worker, or during teardown. - Public Python has complete annotations, NumPy-style docstrings, `__all__`, `py.typed` and a complete stub for the private extension, generated whole with its `_testing` - stub by nanobind's stubgen (`scripts/problem_stub.py`, checked in the lint stage): + stub by nanobind's stubgen (`scripts/stubs.py`, checked in the lint stage): a binding that takes or returns a record names its Python type with `nb::sig`, and a stub is regenerated, never edited. An entry point only solprop's tests reach goes in the extension's private `_testing` submodule (solprop SEP 52), which ships in the diff --git a/native/CMakeLists.txt b/native/CMakeLists.txt index da4b8d63b..394152d1b 100644 --- a/native/CMakeLists.txt +++ b/native/CMakeLists.txt @@ -191,9 +191,10 @@ if(SOLPROP_NATIVE_TREE_DIRTY) endif() # solprop and solprop-native are released together from one repository at one # version, so the solprop version this build belongs to is its own. The record is -# provenance: check_build() compares an editable checkout's sources by digest and looks -# the driver members it relies on up by name, which catches mismatched halves (an -# editable checkout beside a stale extension, a local device build). +# provenance, which nothing compares: check_build() compares only an editable +# checkout's sources with the extension by digest (a stale extension beside newer +# sources), and an installed pair is held to one version by solprop's exact +# requirement on solprop-native (hatch_build.py). if(DEFINED SKBUILD_PROJECT_VERSION_FULL) set(SOLPROP_NATIVE_SOLPROP_BUILT_AGAINST "${SKBUILD_PROJECT_VERSION_FULL}") else() @@ -314,6 +315,13 @@ if(SOLPROP_NATIVE_ENABLE_OPENMP AND message(FATAL_ERROR "Accelerator variants use a Serial host execution space; disable OpenMP.") endif() +if(NOT SOLPROP_NATIVE_ENABLE_OPENMP AND + NOT (SOLPROP_NATIVE_ENABLE_CUDA OR SOLPROP_NATIVE_ENABLE_HIP)) + message(FATAL_ERROR + "A CPU build runs the OpenMP host execution space, and the backend refuses a " + "CPU build without it; enable SOLPROP_NATIVE_ENABLE_OPENMP, or enable " + "SOLPROP_NATIVE_ENABLE_CUDA or SOLPROP_NATIVE_ENABLE_HIP for a device build.") +endif() if(SOLPROP_NATIVE_ENABLE_SANITIZERS AND (SOLPROP_NATIVE_ENABLE_CUDA OR SOLPROP_NATIVE_ENABLE_HIP)) diff --git a/native/README.md b/native/README.md index 93149cb79..07896cd6c 100644 --- a/native/README.md +++ b/native/README.md @@ -41,6 +41,11 @@ The documentation covers both: - [Performance tuning](https://solprop.readthedocs.io/en/stable/guide/performance/tuning.html): threads, BLAS settings and profiling with Kokkos Tools +Importing the package starts its OpenMP runtime: start child processes after it with the +`spawn` start method. A `fork` child inherits the runtime without its threads and usually +hangs at its first parallel region; so can a `forkserver` child when the main module +imports the package. + ## Development The package is a member of the repository's uv workspace and shares its environment and @@ -121,7 +126,7 @@ and `tests/test_band_stress.py` with `SOLPROP_NATIVE_BAND_TILES=4`; on a GPU, ```sh uv run poe check-native # at the repository root; runs native/scripts/check.sh -uv run poe check-all # solprop's gate, then this one +uv run poe check-all # solprop's, this and the front end's gates (gui extra) uv run poe fmt-native # format every tracked C++ file in place uv run poe tidy-native # clang-tidy on the C++ files changed from main, or on those named ``` @@ -139,7 +144,7 @@ weekly in `.github/workflows/native-deep.yml` and report without gating: source coverage, the extension under ASan and UBSan, and an include-cleaner report. `SOLPROP_NATIVE_QUALIFICATION_PYTHON=/path/to/python` installs the wheel into that environment and runs the Python tests there instead. A change to the backend also passes -solprop's own suite with this package installed (`poe check-all`, or `uv run poe test` +solprop's own suite with this package installed (`poe check`, or `uv run poe test` with `SOLPROP_TEST_BACKEND=native`). ### The kernel contract @@ -183,7 +188,7 @@ The private extension `_core` is a thin seam (solprop SEP 52 section 5.3): the workspace's Runge-Kutta (or low-storage) and Adams engines, which solprop's tests run through the same engine protocols as the reference's. - **Generated stubs.** `_core.pyi` and `_core_testing.pyi` are generated whole by - nanobind's stubgen (`scripts/problem_stub.py`; `--check` in the lint stage). A binding + nanobind's stubgen (`scripts/stubs.py`; `--check` in the lint stage). A binding that takes or returns a record names its Python type with `nb::sig`, so the stubs stay typed: edit the binding and regenerate, never the stub. diff --git a/native/ci/check_skips.py b/native/ci/check_skips.py index 0ba6d3982..b330a5fc8 100644 --- a/native/ci/check_skips.py +++ b/native/ci/check_skips.py @@ -36,6 +36,7 @@ r"a read-only directory mode is not enforced on Windows", r"Slurm is faked with POSIX shell scripts", r"a machine's setup script runs in a POSIX shell", + r"the remote shell is POSIX; the check runs it here", r"a machine's helper hosts its kernel on Linux and macOS, not Windows", r"the CI change filter runs in Linux Bash", # A platform's own branch, on the other platforms. @@ -69,8 +70,6 @@ r"this build does not fuse a product and a sum, so the witness proves nothing", # Settings of the lane: ci.yml's coverage lane runs the type checks. r"the runtime type checks are off \(SOLPROP_TEST_TYPECHECK=0\)", - # A record cites a commit that a squash removed from the history. - r"[0-9a-f]{12} is not in this checkout \(squashed or rebased\)", # pytest-xdist's report for a collected module with nothing to run. r"collection skipped", ) diff --git a/native/cmake/HostLibraries.cmake b/native/cmake/HostLibraries.cmake index 3fc9ba6fa..8d01c2dad 100644 --- a/native/cmake/HostLibraries.cmake +++ b/native/cmake/HostLibraries.cmake @@ -95,7 +95,7 @@ if(NOT SOLPROP_NATIVE_PROFILE STREQUAL "LOCAL") if(_native_request STREQUAL "ON") message(FATAL_ERROR "A ${SOLPROP_NATIVE_BUILD_PROFILE} build runs on other machines; it cannot be " - "combined with ENABLE_NATIVE_ARCH=ON.") + "combined with SOLPROP_NATIVE_HOST_ARCH=ON.") endif() if(NOT SOLPROP_NATIVE_BLAS_VENDOR STREQUAL "AUTO" OR SOLPROP_NATIVE_BLAS_LIBRARIES) message(FATAL_ERROR @@ -114,7 +114,8 @@ if(SOLPROP_NATIVE_PROFILE STREQUAL "DISTRIBUTION" AND _tpl_request STREQUAL "OFF "combined with ENABLE_TPL_BLAS=OFF.") endif() if(_native_request STREQUAL "AUTO") - # Device builds keep their host code generic, as their qualified presets did. + # Device builds keep their host code generic, as the qualified cuda and hip presets + # set it (CMakePresets.json). if(SOLPROP_NATIVE_PROFILE STREQUAL "LOCAL" AND NOT _device_build) set(SOLPROP_NATIVE_HOST_ARCH ON) else() @@ -179,7 +180,7 @@ if(NOT SOLPROP_NATIVE_CPU_BASELINE STREQUAL "none" AND if(SOLPROP_NATIVE_HOST_ARCH) message(FATAL_ERROR "SOLPROP_NATIVE_CPU_BASELINE=${SOLPROP_NATIVE_CPU_BASELINE} and " - "ENABLE_NATIVE_ARCH=ON both choose the architecture; set one.") + "SOLPROP_NATIVE_HOST_ARCH=ON both choose the architecture; set one.") endif() if(_x86_processor) set(SOLPROP_NATIVE_CPU_BASELINE_FLAG "-march=${SOLPROP_NATIVE_CPU_BASELINE}") @@ -207,7 +208,7 @@ if(SOLPROP_NATIVE_ENABLE_CUDA OR SOLPROP_NATIVE_ENABLE_HIP) message(FATAL_ERROR "Host BLAS/FFT selections cannot be used in device builds.") endif() # The device's vendor BLAS (cuBLAS, rocBLAS) is the local default; KokkosKernels - # finds it with the toolkit and a missing one fails there, as before. + # finds it with the toolkit and a missing one fails there. if(_tpl_request STREQUAL "AUTO") if(SOLPROP_NATIVE_PROFILE STREQUAL "REFERENCE") set(SOLPROP_NATIVE_ENABLE_TPL_BLAS OFF) diff --git a/native/cmake/VectorMath.cmake b/native/cmake/VectorMath.cmake index f3504a071..b9a3812bf 100644 --- a/native/cmake/VectorMath.cmake +++ b/native/cmake/VectorMath.cmake @@ -9,11 +9,11 @@ # 6240, and SLEEF's AVX2 and AVX-512 functions take it 3 to 3.6 times faster at the same # worst error on the kernels' own arguments. On Apple silicon the system libm is already # about 3 ns, but SLEEF's AdvSIMD functions over the gathered blocks, and the passes and -# lanes kernels they enable, ran an Apple M5 Max's cases faster once the plasma column -# gathered its live samples: comb-to-continuum 0.84 at one thread and 0.87 at six, the +# lanes kernels they enable, run an Apple M5 Max's cases faster since the plasma column +# gathers its live samples: comb-to-continuum 0.84 at one thread and 0.87 at six, the # averaged helium 0.91, the Raman GNLSE 0.91, the graded-index guide level within its -# A/A spread; geometric mean 0.934 (solprop issue #339, November 2026). Earlier, with -# per-sample plasma kernels, it was 11.6 % slower there. +# A/A spread; geometric mean 0.934 (solprop issue #339, November 2026). The gain depends +# on that gathering: over per-sample plasma kernels SLEEF measured 11.6 % slower there. # # AUTO takes SLEEF on x86-64 CPU builds and on macOS arm64, and the system libm on Linux # aarch64 (where SLEEF measured level, 1.00 on a Neoverse V2) and in device builds, whose diff --git a/native/include/solprop_native/response/dispersive.hpp b/native/include/solprop_native/response/dispersive.hpp index c86f33fb6..ccb035c1a 100644 --- a/native/include/solprop_native/response/dispersive.hpp +++ b/native/include/solprop_native/response/dispersive.hpp @@ -45,7 +45,7 @@ namespace solprop_native { // transform, and one batched inverse transform gives every filtered modal field; // 2. the filtered fields are synthesised at a chunk's nodes by the same real matrix as // the bare field, and the products are formed there in the leaf's sector, the -// collar multiplying each (`G[w (G E)^3]`, decided 2026-10-08); +// collar multiplying each (`G[w (G E)^3]`, the reference's operator); // 3. each product is projected onto the modal columns (and onto the embedded rule's); // 4. one batched forward transform, and the products' stage multipliers -- the output // multipliers times the channels' `eps0 gamma0 rho` -- land them in the stage's own diff --git a/native/include/solprop_native/response/plasma.hpp b/native/include/solprop_native/response/plasma.hpp index 1d7b9dbda..5c826150f 100644 --- a/native/include/solprop_native/response/plasma.hpp +++ b/native/include/solprop_native/response/plasma.hpp @@ -209,9 +209,8 @@ inline constexpr int band_host_filter_block = 512; * Filter the interior samples `[low, high)` of a host row, `half` taps a side known at * compile time: each sample's sum in `band_filter_at`'s order, the centre and then each * pair, so the values are its own bit for bit. With the tap count fixed the sum unrolls - * and the compiler runs it across samples, the form of the Julia backend experiment's - * single-pass filter (solprop issue #560, idea 6). The caller keeps the samples within - * `half` of the row's ends out of `[low, high)`. + * and the compiler runs it across samples in one pass (solprop issue #560, idea 6). + * The caller keeps the samples within `half` of the row's ends out of `[low, high)`. */ template <int Half> KOKKOS_INLINE_FUNCTION void band_filter_interior(const double* row, double* out, diff --git a/native/include/solprop_native/transforms/gemm.hpp b/native/include/solprop_native/transforms/gemm.hpp index 7dde1e9d0..a2b58e077 100644 --- a/native/include/solprop_native/transforms/gemm.hpp +++ b/native/include/solprop_native/transforms/gemm.hpp @@ -282,11 +282,11 @@ void engine_gemm(const ExecutionSpace& execution_space, const AView& a, const BV // on the caller's team instead, the response team that writes the node rows (solprop // docs/dev/benchmarks.md, "One-mode products on the response team"). Each element is // one product, or a sum over the nodes in order from zero, within the GEMM rounding -// bound. With Apple's Accelerate they were once left out: on an 18-core Apple M5 Max -// the kernels on the 18-thread response team, with idle threads asleep, took -// argon_blueshift from 3.0 to 3.8 s. On its six top-tier cores with idle threads -// spinning (ADR-070, ADR-071) they take its window to 0.96 and rdw_one_mode's to 0.97 -// (November 2026), so every host BLAS takes them. +// bound. Every host BLAS takes them, Apple's Accelerate included: on an 18-core Apple +// M5 Max's six top-tier cores with idle threads spinning (ADR-070, ADR-071) they take +// argon_blueshift's window to 0.96 and rdw_one_mode's to 0.97 (November 2026). On the +// whole 18-thread response team with idle threads asleep they took argon_blueshift +// from 3.0 to 3.8 s. inline constexpr bool one_mode_products_enabled = #if defined(KOKKOSKERNELS_ENABLE_TPL_BLAS) && !defined(KOKKOS_ENABLE_CUDA) && \ !defined(KOKKOS_ENABLE_HIP) diff --git a/native/include/solprop_native/workspace/workspace.hpp b/native/include/solprop_native/workspace/workspace.hpp index 3db48e24f..b3e95e317 100644 --- a/native/include/solprop_native/workspace/workspace.hpp +++ b/native/include/solprop_native/workspace/workspace.hpp @@ -213,7 +213,7 @@ class Workspace { keys come from. Its march state, history and monitor are not read. */ std::unique_ptr<Probe> probe(const RunStart& start); - // -- what the old seam's accessors read + // -- what `Run` and the `_testing` bindings read [[nodiscard]] const std::optional<stage::Tables>& stage_tables() const noexcept { return stage_tables_; } diff --git a/native/pyproject.toml b/native/pyproject.toml index 836e662b9..9cf21f864 100644 --- a/native/pyproject.toml +++ b/native/pyproject.toml @@ -89,7 +89,7 @@ archs = ["auto64"] build-verbosity = 1 config-settings = { "cmake.define.SOLPROP_NATIVE_PROFILE" = "DISTRIBUTION", "cmake.define.SOLPROP_NATIVE_WARNINGS_AS_ERRORS" = "ON", "build-dir" = "build/cibw-{wheel_tag}" } # A first smoke test in cibuildwheel's test environment, beside solprop from the same -# checkout (check_build reads solprop's kernel contract); the suite and the +# checkout (check_build and the adapter import solprop); the suite and the # coexistence check run in the workflow's test jobs. before-test = "python {package}/ci/install_solprop.py {project}" test-command = "python -I {package}/ci/smoke.py" diff --git a/native/scripts/check.sh b/native/scripts/check.sh index 8b8895483..db99f4907 100755 --- a/native/scripts/check.sh +++ b/native/scripts/check.sh @@ -64,7 +64,7 @@ if stage lint; then uv run ruff format --check . uv run ruff check . # The bound problem's part of _core.pyi is stubgen's, from the build installed above. -uv run python scripts/problem_stub.py --check +uv run python scripts/stubs.py --check uv run python - "$repo_root" "$workspace_root" <<'PY' import json import sys diff --git a/native/scripts/problem_stub.py b/native/scripts/stubs.py similarity index 97% rename from native/scripts/problem_stub.py rename to native/scripts/stubs.py index f4cdd3be0..1a50e6ee1 100644 --- a/native/scripts/problem_stub.py +++ b/native/scripts/stubs.py @@ -32,7 +32,7 @@ # # SPDX-License-Identifier: GPL-3.0-or-later -# Generated by native/scripts/problem_stub.py from nanobind.stubgen: do not edit. +# Generated by native/scripts/stubs.py from nanobind.stubgen: do not edit. """ PAIR = re.compile( r"@property\n(\s*)def (\w+)\(self\) -> (.+): \.\.\.\n\n" @@ -157,7 +157,7 @@ def main(argv: list[str]) -> int: path.write_text(text, encoding="utf-8") stale.append(path.name) if stale and "--check" in argv: - print(f"{', '.join(stale)} stale: run native/scripts/problem_stub.py") + print(f"{', '.join(stale)} stale: run native/scripts/stubs.py") return 1 return 0 diff --git a/native/src/bindings/bind.hpp b/native/src/bindings/bind.hpp index a5ef9537c..d041aa126 100644 --- a/native/src/bindings/bind.hpp +++ b/native/src/bindings/bind.hpp @@ -28,8 +28,9 @@ namespace solprop_native::bindings { namespace nb = nanobind; namespace native = solprop_native; -// A native object the runtime closes before Kokkos is finalised: a state or a -// workspace, each of which closes the session that leases it first. +// A native object the runtime closes before Kokkos is finalised: a workspace +// (`BoundWorkspace`, module.hpp, the one implementer), which closes the session that +// leases it first. class Owned { public: Owned() = default; diff --git a/native/src/bindings/runtime.cpp b/native/src/bindings/runtime.cpp index 536041716..ab4400a10 100644 --- a/native/src/bindings/runtime.cpp +++ b/native/src/bindings/runtime.cpp @@ -6,8 +6,8 @@ // applies the runtime record once: Kokkos initialised with its thread count (and owned // for finalisation), the thread policy and spin set, and a host OpenBLAS fitted to the // pool (`fit_blas_threads`, `register_host_blas`). `register_owned` and `forget_owned` -// hold the states and workspaces closed before `shutdown_after_interpreter` finalises -// the owned runtime. `build_record` reports the build's provenance, providers and +// hold the workspaces closed before `shutdown_after_interpreter` finalises the owned +// runtime. `build_record` reports the build's provenance, providers and // settings. The BLAS and FFT libraries are found by symbol among those the extension // loaded (dlsym on POSIX, a walk of the imported modules on Windows). diff --git a/native/src/general/exponentials.hpp b/native/src/general/exponentials.hpp index 9bce5856d..321c9d94a 100644 --- a/native/src/general/exponentials.hpp +++ b/native/src/general/exponentials.hpp @@ -38,7 +38,7 @@ KOKKOS_INLINE_FUNCTION void cosine_sine(const double theta, double& cosine, // A flow's magnitude: on a lossless bin `exp(+-0)`, exactly one, taken without a // binary64 `exp` per element. Out of line on a host, whose call to its library was out // of line already: inlined there, this branch took the tabulated fold's whole kernel -// past the compiler's inlining limit, 40 % slower (solprop's docs/dev/benchmarks.md). +// past the compiler's inlining limit, 40 % slower. #if defined(__GNUC__) && !defined(KOKKOS_ENABLE_CUDA) && !defined(KOKKOS_ENABLE_HIP) [[gnu::noinline]] #endif diff --git a/native/src/general/general_workspace.hpp b/native/src/general/general_workspace.hpp index 453963ed2..e4300d441 100644 --- a/native/src/general/general_workspace.hpp +++ b/native/src/general/general_workspace.hpp @@ -889,7 +889,7 @@ class GeneralWorkspace { RealView2 held_pack_; ComplexView2 held_pack_spectrum_; std::unique_ptr<ForwardRealPlan> held_pack_forward_; - // A device's forward rows of a stage, one buffer and its spectrum (`packs_forward`): + // The forward rows of a stage, one buffer and its spectrum (`packs_forward`): // the in-stage absorber's rows, then the projection's, then the held pack's, and the // plans of all of them and of the rows after the absorber's (a quiet collar's stage). RealView2 forward_pack_, forward_pack_tail_; diff --git a/native/src/general/ionisation.hpp b/native/src/general/ionisation.hpp index c22cb0ed5..e38841ace 100644 --- a/native/src/general/ionisation.hpp +++ b/native/src/general/ionisation.hpp @@ -29,8 +29,9 @@ KOKKOS_INLINE_FUNCTION double trapezoid(const double current, const double previ } // The fraction ionised from an exposure's decay `exp(-X)`, `1 - (1 - p) exp(-X)`, as -// `bodies.fraction_at` rounds it. A small response: strict arithmetic (solprop SEP 25 -// section 4.2, `fp.hpp`), so the product and the difference round separately. +// solprop's `numpy_ref.passes.plasma.plasma_scan` rounds it. A small response: strict +// arithmetic (solprop SEP 25 section 4.2, `fp.hpp`), so the product and the difference +// round separately. SOLPROP_NATIVE_STRICT_FUNCTION KOKKOS_INLINE_FUNCTION double decayed_fraction(const double decay, const double preionisation) { @@ -88,7 +89,8 @@ KOKKOS_INLINE_FUNCTION Complex compensation_residual(const Complex rate, return strict_mul(strict_sub(rate, strict_scale(inverse_dz, exponent)), state); } -// `bodies.loss_scale`: the loss current's coefficient of the field, or zero. +// The loss current's coefficient of the field, or zero, as solprop's +// `numpy_ref.passes.plasma.plasma_total_current` forms it. KOKKOS_INLINE_FUNCTION double band_loss_scale(const double rate, const double fraction, const double squared, const double ionisation_potential) { diff --git a/native/src/general/setup.cpp b/native/src/general/setup.cpp index d8cb16ec5..5facc8981 100644 --- a/native/src/general/setup.cpp +++ b/native/src/general/setup.cpp @@ -520,14 +520,14 @@ void GeneralWorkspace::allocate_transforms(const std::size_t columns, } } -// The forward rows and spectra: the projection's, the absorber's, a device's pack and +// The forward rows and spectra: the projection's, the absorber's, the forward pack and // the held plasma current's. void GeneralWorkspace::allocate_forward_rows(const std::size_t columns, const std::size_t chunk_rows, const std::size_t temporal_columns) { - // A device's packed forward rows (`packs_forward`): the absorber's, the projection's, - // the coarse projection's and the held pack's, in that order, carved from one buffer - // and one spectrum. + // The packed forward rows (`packs_forward`): the absorber's, the projection's, the + // coarse projection's and the held pack's, carved from one buffer and one spectrum, + // in the host's or the device's order below. const bool pack = packs_forward(); const std::size_t absorber_rows = pack && problem_.absorber.in_stage ? temporal_columns : 0; diff --git a/native/src/general/trial.cpp b/native/src/general/trial.cpp index 259b5d4b5..f84e87efc 100644 --- a/native/src/general/trial.cpp +++ b/native/src/general/trial.cpp @@ -462,7 +462,7 @@ void GeneralWorkspace::upload_trial(const TrialScalars& scalars, stage_staging_next_ = (stage_staging_next_ + 1) % stage_staging_.size(); if (staged) // A device's staging buffer starts from the last values uploaded, so that a view - // this trial does not set keeps them, as the separate copies did. + // this trial does not set keeps them. std::copy(previous.data(), previous.data() + staging.size(), staging.data()); const auto fill_slot = [&](const std::size_t slot, const TrialScalars& values) { double* const base = staging.data() + slot * stage_slot_size_; diff --git a/native/src/general/trial_low_storage.inc b/native/src/general/trial_low_storage.inc index bc949cb1e..bbadfb9bb 100644 --- a/native/src/general/trial_low_storage.inc +++ b/native/src/general/trial_low_storage.inc @@ -41,10 +41,10 @@ constexpr int term_absorber = 2; constexpr std::size_t low_storage_rows[4] = {0, 1, 1, 2}; // One evaluation's fold into the registers at one element: solprop's -// `bodies.low_storage_fold`, the finish column of SEP 24 section 4.3. A pass that -// evaluates twice -- the material response, then the in-stage absorber's term, from the -// same input -- folds the first at the exchange (pass 3's C left unflowed) and the -// second after it, whose sum is the pass's. +// `numpy_ref.engines.NumpyLowStorage._step`, the finish column of SEP 24 section 4.3. +// A pass that evaluates twice -- the material response, then the in-stage absorber's +// term, from the same input -- folds the first at the exchange (pass 3's C left +// unflowed) and the second after it, whose sum is the pass's. KOKKOS_INLINE_FUNCTION void low_storage_fold(const int stage, const int mode, const double step, const Complex source, Complex& state, Complex& accumulator, diff --git a/native/src/general/trial_response.inc b/native/src/general/trial_response.inc index 84dfb08af..c3c39ac80 100644 --- a/native/src/general/trial_response.inc +++ b/native/src/general/trial_response.inc @@ -242,8 +242,8 @@ void GeneralWorkspace::response_impl(const std::size_t stage, } } // Cache contiguous pointwise addresses to avoid repeated View stride loads. - // Plasma retains its measured recurrence-loop layout; applying - // the same change there regresses HE plasma by 8-9% (kokkos-reopt report). + // Plasma keeps its measured recurrence-loop layout: the same change there made + // the helium plasma case slower. auto* const real_input = input_real.data(); auto* const complex_input = input_complex.data(); auto* const real_target = target_real.data(); @@ -278,7 +278,6 @@ void GeneralWorkspace::response_impl(const std::size_t stage, first_value * first_value + (Components == 2 ? second_value * second_value : Complex{}); if constexpr (Plasma) { - // IntelLLVM's precise model retains an unused hypot outside this branch. const double magnitude = Components == 2 ? Kokkos::hypot(first_value.real(), second_value.real()) : Kokkos::abs(first_value.real()); diff --git a/native/src/solprop_native/__init__.py b/native/src/solprop_native/__init__.py index 13090e2c6..344c46c11 100644 --- a/native/src/solprop_native/__init__.py +++ b/native/src/solprop_native/__init__.py @@ -8,6 +8,13 @@ time-domain Raman, weighted control and statistics. Native states remain resident in their execution space between calls; observations are owning host ``complex128`` arrays. + +The import starts the Kokkos runtime and its OpenMP thread pool. Start child processes +after it with the ``spawn`` start method, not ``fork``: a forked child inherits the +initialised runtime without its threads, and GNU's OpenMP runtime then usually hangs at +the child's first parallel region. ``forkserver`` forks from a server that imports the +main module, so it inherits the runtime too when that module imports this package. +solprop's own scans and service spawn their processes. """ from __future__ import annotations diff --git a/native/src/solprop_native/_bind.py b/native/src/solprop_native/_bind.py index 9c8788d49..ec7ed9ed2 100644 --- a/native/src/solprop_native/_bind.py +++ b/native/src/solprop_native/_bind.py @@ -13,9 +13,10 @@ LLVM's runtimes give when nothing is set. So, before the core starts Kokkos, the import sets ``OMP_PROC_BIND=false``: the threads -stay where the scheduler puts them, as before, and the notice is not printed. The +stay where the scheduler puts them and the notice is not printed. The setting stays in the environment, so that a runtime that reads it later and a solprop -worker process run alike. Any of ``OMP_PROC_BIND``, ``OMP_PLACES``, +worker process run alike; a process started from this one inherits it with +:data:`MARKER`, which tells it from a user's. Any of ``OMP_PROC_BIND``, ``OMP_PLACES``, ``GOMP_CPU_AFFINITY`` and ``KMP_AFFINITY`` already set is the user's choice of placement, and nothing is changed. """ @@ -23,21 +24,38 @@ from __future__ import annotations import os -from collections.abc import MutableMapping +from collections.abc import Mapping, MutableMapping VARIABLES = ("OMP_PROC_BIND", "OMP_PLACES", "GOMP_CPU_AFFINITY", "KMP_AFFINITY") """The variables by which a user chooses where OpenMP's threads run.""" +MARKER = "SOLPROP_NATIVE_PROC_BIND" +"""Set beside ``OMP_PROC_BIND=false`` when this module set it.""" + + +def _ours(environ: Mapping[str, str]) -> bool: + """Whether the placement variables set are exactly the one this module set.""" + return ( + environ.get(MARKER) == "false" + and environ.get("OMP_PROC_BIND", "").strip() == "false" + and not any(environ.get(name, "").strip() for name in VARIABLES[1:]) + ) + def proc_bind(environ: MutableMapping[str, str] = os.environ) -> str: """Set ``OMP_PROC_BIND=false`` in `environ` unless the user chose; say which. - Returns ``"false"`` when it was set here, else ``"environment: NAME=value"`` for - the first of :data:`VARIABLES` the user set. + Returns ``"false"`` when it was set here or by the process this one was started + from (:data:`MARKER`), else ``"environment: NAME=value"`` for the first of + :data:`VARIABLES` the user set. """ + if _ours(environ): + return "false" + environ.pop(MARKER, None) for name in VARIABLES: value = environ.get(name, "").strip() if value: return f"environment: {name}={value}" environ["OMP_PROC_BIND"] = "false" + environ[MARKER] = "false" return "false" diff --git a/native/src/solprop_native/_build.py b/native/src/solprop_native/_build.py index 602bd62cc..051076e0a 100644 --- a/native/src/solprop_native/_build.py +++ b/native/src/solprop_native/_build.py @@ -42,8 +42,9 @@ class BuildInfo: with an editable checkout's sources. solprop_version_built_against The solprop version beside which CMake configured the extension, or - ``unknown``. Informational: the contract is the seam members - :func:`check_build` looks for, not a version string. + ``unknown``. Informational: :func:`check_build` does not compare it, and an + installed pair is held to one version by solprop's exact requirement on + ``solprop-native``. kokkos_version, kokkos_fft_version, kokkos_kernels_version, nanobind_version Native dependency versions. build_profile @@ -59,8 +60,8 @@ class BuildInfo: vector_math The host kernels' transcendental functions: ``"SLEEF 3.9.0 u10, AVX2"`` (its 1.0 ulp vector functions, in the variant the build selected: ``AVX2``, ``SSE2``, - ``AVX-512F`` on request or ``AdvSIMD``), the default on x86-64, or - ``"scalar libm"``, the system's, on Arm and in device builds + ``AVX-512F`` on request or ``AdvSIMD``), the default on x86-64 and macOS arm64, + or ``"scalar libm"``, the system's, on Linux aarch64 and in device builds (``SOLPROP_NATIVE_VECTOR_MATH``). gemm_provider, tpl_blas_enabled, blas_backend, blas_thread_policy Dense-transform implementation (always ``"HYBRID"``: the vendor GEMM for an @@ -411,8 +412,6 @@ def check_build() -> None: raise BackendError( f"the {info.device_backend} build has no visible accelerator device" ) - if info.gemm_provider != "HYBRID": - raise BackendError(f"unknown compiled GEMM provider {info.gemm_provider!r}") if info.tpl_blas_enabled and info.blas_backend == "none": raise BackendError("the build enables a BLAS TPL but identifies no provider") if info.build_profile not in {"local", "distribution", "reference"}: diff --git a/native/src/solprop_native/_core.pyi b/native/src/solprop_native/_core.pyi index 23757e94c..5c3a7fced 100644 --- a/native/src/solprop_native/_core.pyi +++ b/native/src/solprop_native/_core.pyi @@ -2,7 +2,7 @@ # # SPDX-License-Identifier: GPL-3.0-or-later -# Generated by native/scripts/problem_stub.py from nanobind.stubgen: do not edit. +# Generated by native/scripts/stubs.py from nanobind.stubgen: do not edit. from __future__ import annotations diff --git a/native/src/solprop_native/_core_testing.pyi b/native/src/solprop_native/_core_testing.pyi index 33de1ee9c..179833206 100644 --- a/native/src/solprop_native/_core_testing.pyi +++ b/native/src/solprop_native/_core_testing.pyi @@ -2,7 +2,7 @@ # # SPDX-License-Identifier: GPL-3.0-or-later -# Generated by native/scripts/problem_stub.py from nanobind.stubgen: do not edit. +# Generated by native/scripts/stubs.py from nanobind.stubgen: do not edit. # The private test module `solprop_native._core._testing` (solprop SEP 52 section 6.5): # the entry points only solprop's own tests reach. It promises nothing. diff --git a/native/src/solprop_native/_device.py b/native/src/solprop_native/_device.py index 1423a5789..b6ef39ffb 100644 --- a/native/src/solprop_native/_device.py +++ b/native/src/solprop_native/_device.py @@ -94,7 +94,7 @@ def device_node_chunk( otherwise the largest that does, and never fewer nodes than the host plan's chunk at the route's default budget. It is consulted only for an automatic plan: an explicit budget or chunk always wins. It runs at backend construction, after the - translation, so no device runtime starts before a scan forks. + translation, so no device runtime starts before a scan spawns its workers. Parameters ---------- @@ -165,13 +165,11 @@ def _low_storage_flows( The flows solprop's estimate counts (solprop kernel schema 32) -- except that a device build recomputes under ``"auto"``, where the estimate's CPU count over-states it by the table. A device's input crosses the state's layout through - tiles (``docs/dev/benchmarks.md``); a CPU's has its own. + tiles; a CPU's has its own. """ if not isinstance(stepper.integrator, LowStorageRungeKutta): return None - return _resident_flows( - low_storage_flows(problem, stepper, "native"), stepper, device=device - ) + return _resident_flows(low_storage_flows(problem, stepper), stepper, device=device) def _resident_flows(flows: int, stepper: StepperSettings, *, device: bool) -> int: diff --git a/native/src/solprop_native/_statistics.py b/native/src/solprop_native/_statistics.py index 5fe156803..e670c729b 100644 --- a/native/src/solprop_native/_statistics.py +++ b/native/src/solprop_native/_statistics.py @@ -266,7 +266,6 @@ _TRANSLATED: tuple[tuple[str, type[SolpropError]], ...] = ( ("species statistics require", OutputError), ("is outside a statistics table's span", TranslationError), - ("a metric-weighted statistic needs", OutputError), ("need a nonnegative fluence profile", BackendError), ("fluence widths require", GridError), ("fluence axes must be uniformly increasing", GridError), @@ -275,10 +274,11 @@ ) """Native refusals and the exceptions the reference raises for the same condition: the species reduction's domain (``species_statistics``), a position outside a table -(``PiecewiseChebyshev.interval_containing``), a metric with no root, and the fluence -widths' refusals (:func:`solprop.backends.spatial.signed_fluence_widths`, +(``PiecewiseChebyshev.interval_containing``), the fluence widths' refusals +(:func:`solprop.backends.spatial.signed_fluence_widths`, :func:`solprop.spatial.radial_fluence_widths`, ``cartesian_fluence_widths``) and the -axis populations' domain (:func:`solprop.backends.populations.axis_statistics`).""" +axis populations' domain (:func:`solprop.backends.populations.axis_statistics`). Each +marker is text the C++ raises, which ``native/tests/test_session_failure.py`` holds.""" def translated(error: BaseException) -> BaseException: @@ -815,7 +815,14 @@ def _plane_tables( values = np.empty(points.size) for slot, z in enumerate(points): try: - values[slot] = float(zdw(mode, float(z), wavelength_limits=window)) + values[slot] = float( + zdw( + mode, + float(z), + wavelength_limits=window, + near=grid.reference_wavelength, + ) + ) except NoZeroDispersionError: values[slot] = math.nan if np.any(np.isnan(values)): @@ -830,9 +837,10 @@ def _plane_tables( ) if missing: warnings.warn( - f"the 'zdw' statistic records nan for modes {missing}: beta_2 has one " - f"sign at both ends of the grid's {window[0] * 1e9:.4g}-" - f"{window[1] * 1e9:.4g} nm band at a plane", + f"the 'zdw' statistic records nan for modes {missing}: the search found " + f"no zero of beta_2 in the grid's {window[0] * 1e9:.4g}-" + f"{window[1] * 1e9:.4g} nm band that no resonance separates from its " + "reference wavelength, at a plane", SolpropWarning, stacklevel=4, ) @@ -897,7 +905,9 @@ def _lowered_zdw_tables( def root(mode: Mode, z: float) -> float: try: - return float(zdw(mode, z, wavelength_limits=window)) + return float( + zdw(mode, z, wavelength_limits=window, near=grid.reference_wavelength) + ) except NoZeroDispersionError: return math.nan @@ -905,9 +915,10 @@ def root(mode: Mode, z: float) -> float: missing = [index for index, value in enumerate(first) if math.isnan(value)] if missing: warnings.warn( - f"the 'zdw' statistic records nan for modes {missing}: beta_2 has one " - f"sign at both ends of the grid's {window[0] * 1e9:.4g}-" - f"{window[1] * 1e9:.4g} nm band", + f"the 'zdw' statistic records nan for modes {missing}: the search found " + f"no zero of beta_2 in the grid's {window[0] * 1e9:.4g}-" + f"{window[1] * 1e9:.4g} nm band that no resonance separates from its " + "reference wavelength", SolpropWarning, stacklevel=4, ) diff --git a/native/src/solprop_native/_wait.py b/native/src/solprop_native/_wait.py index 2aea7b5ad..f528b036a 100644 --- a/native/src/solprop_native/_wait.py +++ b/native/src/solprop_native/_wait.py @@ -13,10 +13,10 @@ AMD EPYC 7763 node, and in 0.87 on 16 cores of an AMD EPYC 9B45 under Windows (ADR-071). -ADR-056 had made idle threads sleep at once, after spinning cost an EPYC 7763 1.4 to -3.3 times at 10,000 spins while the backend ran several thread teams in turn (Kokkos's, -the threaded FFTs', the BLAS's and NumPy's). Those now share one runtime and NumPy's -BLAS holds one thread, and the same test no longer loses. +The spin is cheap because the backend's thread teams (Kokkos's, the threaded FFTs' and +the BLAS's) share one runtime and NumPy's BLAS holds one thread +(:mod:`solprop_native._host_blas`): with several teams run in turn, each spinning +10,000 times, an EPYC 7763 ran 1.4 to 3.3 times slower (ADR-056). So, unless the user chose, the import sets before the core loads the runtime: @@ -27,7 +27,7 @@ :data:`SPIN_MILLISECONDS` while a native call runs (``kmp_set_blocktime``). Each runtime ignores the other's variable. Idle threads sleep at once -(``OMP_WAIT_POLICY=passive``), as before, where the team is wider than a chip's +(``OMP_WAIT_POLICY=passive``) where the team is wider than a chip's fastest cores: spinning on an M5 Max's second-tier cores ran most cases 1.1 to 1.35 times slower at 18 threads. Any of :data:`VARIABLES` already set is the user's choice, and nothing is changed; a process diff --git a/native/src/solprop_native/backend.py b/native/src/solprop_native/backend.py index df4cbebcd..3f5231f58 100644 --- a/native/src/solprop_native/backend.py +++ b/native/src/solprop_native/backend.py @@ -12,7 +12,7 @@ import weakref from collections.abc import Mapping, Sequence from pathlib import Path -from typing import Any, ClassVar, Literal, cast +from typing import Any, Literal, cast import numpy as np import numpy.typing as npt @@ -49,7 +49,6 @@ from solprop.monitor import BoundaryMonitor from solprop.noise import NoiseRealisation from solprop.profiles import ZProfile -from solprop.spatial import FAR_FIELD_STATISTICS from solprop.stats import StatsSpec from solprop.stepper.low_storage import LowStorageRungeKutta from solprop.stepper.multistep import Multistep @@ -178,12 +177,6 @@ class NativeBackend: name = "native" helpers = NATIVE - far_field_statistics: ClassVar[frozenset[str]] = frozenset(FAR_FIELD_STATISTICS) - """The far-field statistics of solprop SEP 23 this build forms natively. - - solprop's registry admits them on this backend by this attribute and refuses - them, by name, on a build without it. - """ def __init__( self, @@ -235,8 +228,6 @@ def __init__( self._modes = modes self._profiles = profiles self._closed = False - # The start the native state was last loaded with (`_load`). - self._loaded: Loaded | None = None # solprop SEP 47 section 6.5: this backend's lowering of the host plan, and # the general route's own chunk at the plan's budget. self._node_chunk = native_node_chunk( @@ -300,76 +291,84 @@ def __init__( # One workspace for the backend's life (solprop SEP 52 section 5.3): the # problem and every set-once table, guard and geometry cross once, here. self._workspace = _core.Workspace(_lower(problem, request, plan)) - diagnostics = self._workspace.diagnostics() - self._applied_execution = ExecutionRecord.from_native( - diagnostics["cpu_execution"] - ) - if cpu_execution is None: - # A stage-2 refinement of this very execution (solprop SEP 46 section - # 6.6): the workspace is built again with its record. - refined = _refined_record(problem, stepper, diagnostics) - if refined is not None: - stored |= _keep_plans(diagnostics, wisdom) - self._workspace.close() - self._workspace = _core.Workspace( - _lower( - problem, - request, - dataclasses.replace( - plan, - cpu_execution=refined[0], - fft_planning=_planning(fft_planning, stored), - ), + # A failure before the constructor returns closes the workspace, whose device + # memory and place in the runtime's close-before-finalise registry the garbage + # collector would otherwise hold. + try: + diagnostics = self._workspace.diagnostics() + self._applied_execution = ExecutionRecord.from_native( + diagnostics["cpu_execution"] + ) + if cpu_execution is None: + # A stage-2 refinement of this very execution (solprop SEP 46 section + # 6.6): the workspace is built again with its record. + refined = _refined_record(problem, stepper, diagnostics) + if refined is not None: + stored |= _keep_plans(diagnostics, wisdom) + self._workspace.close() + self._workspace = _core.Workspace( + _lower( + problem, + request, + dataclasses.replace( + plan, + cpu_execution=refined[0], + fft_planning=_planning(fft_planning, stored), + ), + ) + ) + diagnostics = self._workspace.diagnostics() + self._execution_source = refined[1] + self._applied_execution = ExecutionRecord.from_native( + diagnostics["cpu_execution"] + ) + # The workspace's facts that its build fixes, for every metadata record; its + # counters are read live (`Workspace.counters`). + self._facts: dict[str, Any] = dict(diagnostics) + # solprop SEP 49: the TDSE response is the march's host source, handed to + # each run and probe; the driver owns the binding and closes it. + self._tdse_binding = tdse_binding + self._host_source: TDSEHostSource | None = None + if tdse_binding is not None: + self._host_source = TDSEHostSource(tdse_binding, problem, self._terms) + if fft_planning is None: + _keep_plans(diagnostics, wisdom) + self._wisdom_digest = ( + _wisdom.digest( + _applied_plans( + diagnostics, + stored, + fft_planning if fft_planning is not None else _package.PLANNING, ) ) - diagnostics = self._workspace.diagnostics() - self._execution_source = refined[1] - self._applied_execution = ExecutionRecord.from_native( - diagnostics["cpu_execution"] - ) - # The workspace's facts that its build fixes, for every metadata record; its - # counters are read live (`Workspace.counters`). - self._facts: dict[str, Any] = dict(diagnostics) - # solprop SEP 49: the TDSE response is the march's host source, handed to each - # run and probe; the driver owns the binding and closes it. - self._tdse_binding = tdse_binding - self._host_source: TDSEHostSource | None = None - if tdse_binding is not None: - self._host_source = TDSEHostSource(tdse_binding, problem, self._terms) - if fft_planning is None: - _keep_plans(diagnostics, wisdom) - self._wisdom_digest = ( - _wisdom.digest( - _applied_plans( - diagnostics, - stored, - fft_planning if fft_planning is not None else _package.PLANNING, - ) + if not _on_device() + else None ) - if not _on_device() - else None - ) - # The native Adams march's record (SEP 39): its policy, ledger and history, - # over the resident history the workspace keeps. - self._adams: _NativeAdamsMarch | None = ( - _NativeAdamsMarch(self, integrator, diagnostics["history_rows"]) - if isinstance(integrator, Multistep) - else None - ) - # The low-storage march (SEP 24) is the native session's; its resident - # registers' step is a timing probe's trial (`timing_probe`), and the - # evaluations the probes make are counted for the metadata. - self._low_storage = isinstance(integrator, LowStorageRungeKutta) - self._low_storage_evaluations = 0 - # The open timing probe, which leases the workspace until the next run or probe. - self._probe: _core.Probe | None = None - # NumPy's own BLAS pool would spin beside the native one while this backend - # lives; it is held to one thread until the last native backend closes. - self._host_blas = _host_blas.hold( - build_info().blas_library, - THREAD_BUDGET.threads, - acquire=acquire_host_blas, - ) + # The native Adams march's record (SEP 39): its policy, ledger and history, + # over the resident history the workspace keeps. + self._adams: _NativeAdamsMarch | None = ( + _NativeAdamsMarch(self, integrator, diagnostics["history_rows"]) + if isinstance(integrator, Multistep) + else None + ) + # The low-storage march (SEP 24) is the native session's; its resident + # registers' step is a timing probe's trial (`timing_probe`), and the + # evaluations the probes make are counted for the metadata. + self._low_storage = isinstance(integrator, LowStorageRungeKutta) + self._low_storage_evaluations = 0 + # The open timing probe, which leases the workspace until the next run or + # probe. + self._probe: _core.Probe | None = None + # NumPy's own BLAS pool would spin beside the native one while this backend + # lives; it is held to one thread until the last native backend closes. + self._host_blas = _host_blas.hold( + build_info().blas_library, + THREAD_BUDGET.threads, + acquire=acquire_host_blas, + ) + except BaseException: + self._workspace.close() + raise @property def request(self) -> RunRequest: # numpydoc ignore=RT01 @@ -867,8 +866,8 @@ def metadata(self) -> dict[str, object]: work["source_evaluations"] = self._low_storage_evaluations else: work["source_evaluations"] = native["rk_source_evaluations"] - # Which march steps the run (solprop SEP 39 and 45 section 5): the native one, - # the only one since SEP 47 phase 5. + # Which march steps the run (solprop SEP 39 and 45 section 5): the key present + # names the march, and its value is always "native", the only march there is. if self._adams is not None: work["adams_march"] = "native" elif not self._low_storage: @@ -917,6 +916,8 @@ def metadata(self) -> dict[str, object]: "plasma_channels": len(self._problem.responses.population_channels), "envelope_plasma_enabled": self._problem.responses.envelope_plasma is not None, + # A constant: a planned scalar status readback refuses an unresolved + # angular quadrature before the envelope current's transforms. "envelope_refinement_boundary": "scalar status read before transforms", "raman_components": len(self._problem.responses.raman_terms), "raman_drive": ( @@ -948,16 +949,6 @@ def node_chunk(self) -> int: # numpydoc ignore=RT01 """The nodes a native response pass holds at once: the host plan, lowered.""" return self._node_chunk - def available_device_memory(self) -> int | None: - """Return free accelerator bytes, or None for a host build. - - Returns - ------- - int or None - Free bytes from the selected accelerator runtime. - """ - return _core.available_device_memory() - def memory_ledger(self) -> dict[str, int]: """Return every persistent native allocation's byte count by role. @@ -1174,8 +1165,8 @@ def _refuse_unknown_method(stepper: StepperSettings) -> None: def _refuse_unsupported(problem: PropagationProblem, stepper: StepperSettings) -> None: _refuse_unknown_method(stepper) # The route by its variant (solprop SEP 47 section 6.2), refused by name before - # anything is allocated: every route of the union but the modal route's TDSE - # extension, which is the reference's alone. + # anything is allocated: every route of the union, the modal route's TDSE + # extension on CPU builds only. # Read as any object: a variant this build does not know is refused by name too. route = cast("object", problem.route) match route: @@ -1323,10 +1314,7 @@ def _refined_record( from ._store import refinement, stores key = descriptor( - # The store's key keeps the four-axis shape it has always been written with, - # so that refinements recorded before the batch axis left the problem (solprop - # SEP 47 section 6.2) are found again. - shape=(1, *problem.shape), + shape=problem.shape, grid_kind=problem.grid_kind, integrator=type(stepper.integrator).__name__, sizing=diagnostics["execution_sizing"], diff --git a/native/src/solprop_native/session.py b/native/src/solprop_native/session.py index ed3dd49c9..6f851cb94 100644 --- a/native/src/solprop_native/session.py +++ b/native/src/solprop_native/session.py @@ -256,6 +256,9 @@ def _aperture_payload( """A load whose state crossed to the workspace keeps no host copy.""" _NO_ORDERS = 1 << 62 """An order index past any run's, to read the march's state without its orders.""" +_POWER_WEIGHTS_REFUSAL = "power weights" +"""Text of the native export's refusal of malformed power weights (``session.cpp``), +which the reference refuses with :class:`~solprop.exceptions.GridError`.""" _LEDGER_COUNTERS = ( "startup", "predictor", @@ -1026,7 +1029,7 @@ def export( except _core.SessionLifecycleError as error: raise SessionError(str(error)) from None except ValueError as error: - if "power weights" in str(error): + if _POWER_WEIGHTS_REFUSAL in str(error): raise GridError(str(error)) from None raise if (counters := _counters.active) is not None: diff --git a/native/src/transforms/fftw_wisdom.cpp b/native/src/transforms/fftw_wisdom.cpp index d36bc17ed..3f9ce163e 100644 --- a/native/src/transforms/fftw_wisdom.cpp +++ b/native/src/transforms/fftw_wisdom.cpp @@ -407,7 +407,8 @@ void seed_fftw_wisdom(const ExecutionSpace& space, Complex* input, Complex* outp auto* const seeded = fftw_plan_many_dft( static_cast<int>(extents.size()), extents.data(), howmany, in, nullptr, 1, input_distance, out, nullptr, 1, output_distance, sign, *chosen); - // The policy has always tolerated a plane it cannot seed; a profile records it. + // Under the plan policy a plane that cannot be seeded stays unseeded rather than + // refused; under a profile's planning the outcome is recorded (`end_seed`). if (seeded == nullptr && (*chosen & FFTW_WISDOM_ONLY) == 0U && (detail::planning == nullptr || detail::planning->mode == FftPlanning::Mode::policy)) { diff --git a/native/src/workspace/run_records.cpp b/native/src/workspace/run_records.cpp index d39c54592..82a6b8dc5 100644 --- a/native/src/workspace/run_records.cpp +++ b/native/src/workspace/run_records.cpp @@ -30,7 +30,11 @@ namespace { template <class Slots> void numbers_into(const std::map<std::string, double>& numbers, const Slots& known, const char* record) { - for (const auto& [name, value] : numbers) { + for (const auto& entry : numbers) { + // Named variables, not a structured binding: Clang 18 does not capture one in a + // lambda of a unit built with OpenMP. + const std::string& name = entry.first; + const double value = entry.second; const auto found = std::ranges::find_if( known, [&name](const auto& slot) { return name == slot.first; }); if (found == known.end()) diff --git a/native/tests/conftest.py b/native/tests/conftest.py index 8725504fc..1c5c784ff 100644 --- a/native/tests/conftest.py +++ b/native/tests/conftest.py @@ -11,6 +11,7 @@ from __future__ import annotations +import numbers import os import numpy as np @@ -31,6 +32,45 @@ # Trigger the documented macOS runtime ordering without adding an unused binding. __import__("solprop_native") +_PYTEST_APPROX = pytest.approx +_PYTEST_REL = 1e-6 +"""pytest's default relative tolerance, which a bare ``approx`` of a number keeps.""" + + +def _approx( + expected: object, + rel: float | None = None, + abs: float | None = None, + nan_ok: bool = False, +): + """Return ``pytest.approx`` with no absolute tolerance unless the test gives one. + + The rule of solprop's ``tests/conftest.py``: pytest keeps an absolute tolerance of + 1e-12 beside any ``rel``, which accepts any result for a quantity far below it (a + trial's error norm, a time in seconds). With ``rel=`` alone the comparison is + relative only, and a bare ``approx(x)`` of a nonzero number is relative to pytest's + 1e-6 only; a bare ``approx`` of zero, or of a sequence, array or mapping, keeps + pytest's defaults. A test that needs an absolute tolerance gives ``abs=``. + """ + if abs is None: + if rel is not None: + abs = 0.0 + elif _nonzero_number(expected): + rel, abs = _PYTEST_REL, 0.0 + return _PYTEST_APPROX(expected, rel=rel, abs=abs, nan_ok=nan_ok) + + +def _nonzero_number(value: object) -> bool: + """Return whether `value` is a real or complex number, not a bool, other than 0.""" + return ( + not isinstance(value, bool) + and isinstance(value, numbers.Complex) + and value != 0 + ) + + +pytest.approx = _approx + type PhaseACase = tuple[PropagationProblem, RunRequest, EnvelopeGrid] type RamanCase = tuple[PropagationProblem, RunRequest, EnvelopeGrid] type ComplexArray = npt.NDArray[np.complex128] diff --git a/native/tests/test_api_contract.py b/native/tests/test_api_contract.py index de8fdc805..dbe9ee62d 100644 --- a/native/tests/test_api_contract.py +++ b/native/tests/test_api_contract.py @@ -398,6 +398,41 @@ def test_threads_stay_unbound_unless_the_user_placed_them( assert environ.get("OMP_PROC_BIND") == binding +@pytest.mark.parametrize( + ("environ", "expected", "marked"), + [ + # A process started from one whose import set the binding inherits both. + ({"OMP_PROC_BIND": "false", _bind.MARKER: "false"}, "false", True), + # The same value without the marker is the user's. + ({"OMP_PROC_BIND": "false"}, "environment: OMP_PROC_BIND=false", False), + # A placement added beside an inherited binding is the user's. + ( + {"OMP_PROC_BIND": "false", "OMP_PLACES": "cores", _bind.MARKER: "false"}, + "environment: OMP_PROC_BIND=false", + False, + ), + # A marker left behind after the user changed the binding. + ( + {"OMP_PROC_BIND": "spread", _bind.MARKER: "false"}, + "environment: OMP_PROC_BIND=spread", + False, + ), + ], +) +def test_an_inherited_binding_is_reported_as_set_by_the_import( + environ: dict[str, str], expected: str, marked: bool +) -> None: + """The marker beside ``OMP_PROC_BIND=false`` tells the import's from a user's.""" + assert _bind.proc_bind(environ) == expected + assert (_bind.MARKER in environ) is marked + + +def test_the_binding_set_by_the_import_carries_the_marker() -> None: + environ: dict[str, str] = {} + assert _bind.proc_bind(environ) == "false" + assert environ == {"OMP_PROC_BIND": "false", _bind.MARKER: "false"} + + def test_the_first_native_import_prints_no_binding_notice() -> None: """Kokkos's four-line ``OMP_PROC_BIND`` notice is not printed by default.""" completed = subprocess.run( diff --git a/native/tests/test_backend.py b/native/tests/test_backend.py index fb813ffb5..a54fe3ecc 100644 --- a/native/tests/test_backend.py +++ b/native/tests/test_backend.py @@ -444,6 +444,30 @@ def forbidden(*_arguments: object, **_keywords: object) -> NoReturn: NativeBackend(requested, requested_request, grid=grid) +def test_a_constructor_failing_after_the_workspace_closes_it( + phase_a_case: PhaseACase, monkeypatch: pytest.MonkeyPatch +) -> None: + # A failure after the workspace is built (here the last step, the host BLAS + # hold) closes the workspace rather than leaving it to the garbage collector. + problem, run_request, grid = phase_a_case + built: list[_core.Workspace] = [] + workspace_type = _core.Workspace + + def recorded(lowered: _core.Problem) -> _core.Workspace: + built.append(workspace_type(lowered)) + return built[-1] + + def failing(*_arguments: object, **_keywords: object) -> NoReturn: + raise RuntimeError("host BLAS hold failed") + + monkeypatch.setattr(_core, "Workspace", recorded) + monkeypatch.setattr("solprop_native._host_blas.hold", failing) + with pytest.raises(RuntimeError, match="host BLAS hold failed"): + NativeBackend(problem, run_request, grid=grid) + assert built + assert all(workspace.closed for workspace in built) + + def _resumed(problem: PropagationProblem, ledgers: dict[str, object]) -> Start: """Return the problem's launch as a start that restores `ledgers`.""" return Start( diff --git a/native/tests/test_band_plasma.py b/native/tests/test_band_plasma.py index a3272c39e..f5a7e88a4 100644 --- a/native/tests/test_band_plasma.py +++ b/native/tests/test_band_plasma.py @@ -373,7 +373,7 @@ def test_the_band_rule_matches_the_reference_on_every_route(name: str) -> None: @pytest.mark.parametrize( ("trange", "ffac", "half"), [ - (5e-15, 2.0, 6), # n_to = 8 < 2K: both ends reflect into one window + (5e-15, 2.2, 6), # the smallest ffac: both ends reflect into one window (5e-15, 4.0, 8), # n_to = 16 = 2K: the two edge regions meet (1e-14, 4.0, 8), # n_to = 32 < 3K + 2K + 1: every stage on an edge ], diff --git a/native/tests/test_band_statistics_per_node.py b/native/tests/test_band_statistics_per_node.py index 7463be20a..2f56903ac 100644 --- a/native/tests/test_band_statistics_per_node.py +++ b/native/tests/test_band_statistics_per_node.py @@ -4,10 +4,10 @@ """The band statistics of one node and of each channel, against numpy_ref (SEP 43). -Inventory item 25. The retired Numba tests held the statistics column's per-node -fraction, peak rate and diagnostics, and the column's per-channel fractions, to the -band column's budget ``64 (2K + 1) n_to eps``, about 1e-10 relative. What survived was -plane-level, at ``1e3`` times that for the rates and absolutely for the diagnostics. +The retired Numba tests held the statistics column's per-node fraction, peak rate and +diagnostics, and the column's per-channel fractions, to the band column's budget +``64 (2K + 1) n_to eps``, about 1e-10 relative. What survived was plane-level, at +``1e3`` times that for the rates and absolutely for the diagnostics. **How it is reached.** Native reports no node's statistics, only the largest over a plane, so each node of the original (a pulse of 6e10, 9e10 or 1.2e10 V/m, 4 fs, on the diff --git a/native/tests/test_build_consistency.py b/native/tests/test_build_consistency.py new file mode 100644 index 000000000..39910545a --- /dev/null +++ b/native/tests/test_build_consistency.py @@ -0,0 +1,179 @@ +# SPDX-FileCopyrightText: 2026 John C. Travers and contributors +# +# SPDX-License-Identifier: GPL-3.0-or-later + +"""``check_build``'s refusals of an inconsistent build record. + +Each case is a consistent record with one rule broken, read through the seam +``check_build`` reads its build from (``_build.build_info``), so that a refusal left +out lets its case through. The checkout's digest is a separate refusal, tested in +``test_api_contract.py``; here it reads as an installed wheel's, which has none. +""" + +from __future__ import annotations + +import dataclasses + +import pytest +from solprop.exceptions import BackendError + +import solprop_native as native +from solprop_native import _build # pyright: ignore[reportPrivateUsage] + +# Consistent records of each kind: a CPU build with a vendor BLAS, the reference and +# distribution profiles, and a CUDA and a HIP build with their device BLAS. +CPU: dict[str, object] = { + "fast_math_enabled": False, + "openmp_enabled": True, + "execution_space": "OpenMP", + "device_backend": "none", + "device_count": 0, + "gemm_provider": "HYBRID", + "tpl_blas_enabled": True, + "blas_backend": "OpenBLAS", + "build_profile": "local", + "native_arch_enabled": False, + "cpu_baseline": "none", +} +REFERENCE = CPU | { + "build_profile": "reference", + "tpl_blas_enabled": False, + "blas_backend": "none", +} +DISTRIBUTION = CPU | {"build_profile": "distribution", "cpu_baseline": "x86-64-v3"} +CUDA = CPU | { + "openmp_enabled": False, + "execution_space": "Cuda", + "device_backend": "cuda", + "device_count": 1, + "blas_backend": "cuBLAS", +} +HIP = CUDA | { + "execution_space": "HIP", + "device_backend": "hip", + "blas_backend": "rocBLAS", +} + +ACCEPTED = [ + pytest.param(CPU, id="local CPU"), + pytest.param(CPU | {"native_arch_enabled": True}, id="local native CPU"), + pytest.param( + CPU | {"tpl_blas_enabled": False, "blas_backend": "none"}, id="no BLAS" + ), + pytest.param(REFERENCE, id="reference"), + pytest.param(DISTRIBUTION, id="distribution"), + pytest.param(CUDA, id="CUDA"), + pytest.param(HIP, id="HIP"), + pytest.param( + CUDA | {"tpl_blas_enabled": False, "blas_backend": "none"}, + id="CUDA without a BLAS", + ), +] + +REFUSED = [ + pytest.param( + CPU | {"fast_math_enabled": True}, + "solprop-native was built with forbidden fast-math", + id="fast-math", + ), + pytest.param( + CUDA | {"openmp_enabled": True}, + "the build enables OpenMP but its Kokkos execution space is 'Cuda'", + id="OpenMP off its space", + ), + pytest.param( + CPU | {"openmp_enabled": False, "execution_space": "Serial"}, + "the 'none' device backend is inconsistent with execution space 'Serial'", + id="serial CPU build", + ), + pytest.param( + CUDA | {"execution_space": "HIP"}, + "the 'cuda' device backend is inconsistent with execution space 'HIP'", + id="CUDA on the HIP space", + ), + pytest.param( + CPU | {"device_backend": "sycl"}, + "the 'sycl' device backend is inconsistent with execution space 'OpenMP'", + id="unknown device backend", + ), + pytest.param( + CUDA | {"device_count": 0}, + "the cuda build has no visible accelerator device", + id="no visible device", + ), + pytest.param( + CPU | {"blas_backend": "none"}, + "the build enables a BLAS TPL but identifies no provider", + id="BLAS TPL with no provider", + ), + pytest.param( + CPU | {"build_profile": "native"}, + "unknown build profile 'native'", + id="unknown profile", + ), + pytest.param( + REFERENCE | {"tpl_blas_enabled": True, "blas_backend": "OpenBLAS"}, + "the reference build links a vendor BLAS or machine-specific code", + id="reference with a vendor BLAS", + ), + pytest.param( + REFERENCE | {"native_arch_enabled": True}, + "the reference build links a vendor BLAS or machine-specific code", + id="reference with native code", + ), + pytest.param( + REFERENCE | {"cpu_baseline": "x86-64-v3"}, + "the reference build links a vendor BLAS or machine-specific code", + id="reference with a CPU baseline", + ), + pytest.param( + DISTRIBUTION | {"native_arch_enabled": True}, + "the distribution build carries machine-native code or no BLAS", + id="distribution with native code", + ), + pytest.param( + DISTRIBUTION | {"tpl_blas_enabled": False, "blas_backend": "none"}, + "the distribution build carries machine-native code or no BLAS", + id="distribution without a BLAS", + ), + pytest.param( + CUDA | {"blas_backend": "OpenBLAS"}, + "the selected BLAS provider cannot access this accelerator's memory", + id="CUDA with a host BLAS", + ), + pytest.param( + HIP | {"blas_backend": "cuBLAS"}, + "the selected BLAS provider cannot access this accelerator's memory", + id="HIP with another device's BLAS", + ), +] + + +@pytest.fixture(autouse=True) +def no_checkout_digest(monkeypatch: pytest.MonkeyPatch) -> None: + """Compare no checkout's sources, as in an installed wheel.""" + monkeypatch.setattr(_build, "_checkout_digest", lambda: None) + + +def built(monkeypatch: pytest.MonkeyPatch, fields: dict[str, object]) -> None: + """Make ``check_build`` read this build's record with `fields` in place.""" + info = dataclasses.replace(native.build_info(), **fields) + monkeypatch.setattr(_build, "build_info", lambda: info) + + +@pytest.mark.parametrize("fields", ACCEPTED) +def test_a_consistent_build_is_accepted( + monkeypatch: pytest.MonkeyPatch, fields: dict[str, object] +) -> None: + built(monkeypatch, fields) + assert native.check_build() is None + + +@pytest.mark.parametrize(("fields", "message"), REFUSED) +def test_an_inconsistent_build_is_refused_naming_what_is_wrong( + monkeypatch: pytest.MonkeyPatch, fields: dict[str, object], message: str +) -> None: + built(monkeypatch, fields) + with pytest.raises(BackendError) as refusal: + native.check_build() + assert str(refusal.value) == message diff --git a/native/tests/test_cpu_baseline.py b/native/tests/test_cpu_baseline.py index ea44f234a..79ca7a100 100644 --- a/native/tests/test_cpu_baseline.py +++ b/native/tests/test_cpu_baseline.py @@ -344,9 +344,19 @@ def test_nothing_is_logged_unless_the_processor_chose_a_lower_build( ) == "_core_v2" ) - # A processor that cannot be asked gets the best build, with nothing to name. + # A processor cpuinfo cannot read is asked through NumPy; a capable one gets the + # best build, with nothing to name. absent = tmp_path / "absent" - assert _cpu.select_variant(package, platform="linux", cpuinfo=absent) == "_core" + capable = frozenset(V3_FLAGS.split()) + assert ( + _cpu.select_variant( + package, + platform="linux", + cpuinfo=absent, + numpy_query=lambda: capable, + ) + == "_core" + ) assert caplog.messages == [] diff --git a/native/tests/test_session_failure.py b/native/tests/test_session_failure.py index c2bd68668..d7c7e3ecc 100644 --- a/native/tests/test_session_failure.py +++ b/native/tests/test_session_failure.py @@ -8,11 +8,14 @@ -- a plane's statistics evaluation, say -- and ends the run with it. Its class is the one the marches give the same native exception (``rk_march.cpp``, ``adams_march.cpp``): an unresolved angular source is a ``ConvergenceError``, as the reference raises, not a -``RuntimeError``. +``RuntimeError``. A native refusal the adapter recognises by its text keeps that text +in the C++ sources, so that a reworded message cannot lose its solprop class unseen. """ from __future__ import annotations +from pathlib import Path + import numpy as np import pytest from solprop.backends.events import Terminal @@ -21,7 +24,8 @@ from test_envelope_plasma import envelope_case, envelope_options, terms import solprop_native.backend as adapter -from solprop_native import NativeBackend, _core +import solprop_native.session as native_session +from solprop_native import NativeBackend, _core, _statistics from solprop_native._lowering import ( _lower, # pyright: ignore[reportPrivateUsage] _LowerPlan, # pyright: ignore[reportPrivateUsage] @@ -72,3 +76,27 @@ def corrupt_payload(*args: object, **keywords: object) -> _core.Problem: # The launch plane's populations refuse before any step is taken. assert isinstance(terminal.error, ConvergenceError) assert "angular refinement" in str(terminal.error) + + +def test_every_refusal_the_adapter_recognises_by_text_is_raised_by_the_cpp() -> None: + root = Path(__file__).parents[1] + sources = { + path: path.read_text(encoding="utf-8") + for folder in ("src", "include") + for path in sorted((root / folder).rglob("*")) + if path.suffix in {".cpp", ".hpp", ".inc"} + } + # The C++ tree was found: over a hundred files, the session's among them. + assert len(sources) > 50 + assert root / "src" / "session" / "session.cpp" in sources + markers = [ + *(marker for marker, _ in _statistics._TRANSLATED), # pyright: ignore[reportPrivateUsage] + native_session._POWER_WEIGHTS_REFUSAL, # pyright: ignore[reportPrivateUsage] + ] + assert len(markers) == 8 + missing = [ + marker + for marker in markers + if not any(marker in text for text in sources.values()) + ] + assert missing == [] diff --git a/pyproject.toml b/pyproject.toml index f89a2ed9f..04768ee0b 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -41,8 +41,7 @@ Changelog = "https://github.com/LupoLab/solprop/blob/main/CHANGELOG.md" # The `gui` extra, pinned by hatch_build.py, installs the desktop front end, the # distribution solprop-gui built from gui/, at solprop's own version: -# `pip install solprop[gui]`, then `solprop-gui`. Until it is published, the TDSE provider -# Pyroraptor is installed separately (docs/guide/media/tdse.md). +# `pip install solprop[gui]`, then `solprop-gui`. [dependency-groups] dev = [ @@ -156,8 +155,6 @@ exclude = [ ".hypothesis", ".pytest_cache", ".coverage*", - "*.nbi", - "*.nbc", "*.fftw_wisdom", ".DS_Store", "/docs/_build", @@ -250,7 +247,6 @@ max-positional-args = 5 # past this, parameters are keyword-only "docs/introduction/tutorials/**" = ["D", "ANN", "T20", "E402"] # the same gallery cell conventions "docs/tutorials/**" = ["D", "ANN", "T20", "E402"] # gallery scripts: cells and prints "docs/examples/**" = ["D", "ANN", "T20", "E402"] # worked examples: the same -"docs/auto_examples/**" = ["D", "ANN", "T20", "E402"] # their committed copies # -------------------------------------------------------------------------- type check [tool.basedpyright] # basedpyright also reads [tool.pyright] @@ -356,8 +352,10 @@ size = "python -m tools.size_report" # where the lines go, per p size-check = "python -m tools.size_report --check" # the ratchets of tools/size_budget.toml test-medium = "pytest -m medium --durations=0" # each test timed against its 30 s budget docs = "sphinx-build -b html -W -n --keep-going docs docs/_build/html" -# Python rather than `rm -rf`, so the task also runs on Windows. -docs-clean = "python -c \"import shutil; [shutil.rmtree(p, ignore_errors=True) for p in ('docs/_build', 'docs/introduction/lessons', 'docs/auto_tutorials', 'docs/api/generated')]\"" +# Python rather than `rm -rf`, so the task also runs on Windows. It removes only the +# untracked build output: the galleries' generated pages are committed, and a build +# refuses a gallery whose pages are missing. +docs-clean = "python -c \"import shutil; [shutil.rmtree(p, ignore_errors=True) for p in ('docs/_build', 'docs/api/generated')]\"" [tool.poe.tasks.bench] cmd = "python -m benchmarks" @@ -402,27 +400,27 @@ sequence = [ env = { PYTHONUTF8 = "1", SOLPROP_TEST_BACKEND = "native" } help = "GPU lane: the gpu-marked tests of solprop and solprop-native against an installed CUDA or HIP build, on a device." -# The CPU coverage lane measures coverage-cpu.ini's source, which is the whole package. +# The coverage lane measures [tool.coverage]'s source, which is the whole package. # It runs under xdist with one thread per worker, as `poe test` does, and pytest-cov # combines the workers' data. [tool.poe.tasks.cov] -cmd = "pytest --cov --cov-config=coverage-cpu.ini --cov-report=term-missing --cov-report=xml --durations=25 -m 'not slow and not gpu and not benchmark' -n auto --dist loadgroup" +cmd = "pytest --cov --cov-report=term-missing --cov-report=xml --durations=25 -m 'not slow and not gpu and not benchmark' -n auto --dist loadgroup" env = { PYTHONUTF8 = "1", SOLPROP_THREADS = "1", SOLPROP_NATIVE_THREADS = "1", VECLIB_MAXIMUM_THREADS = "1", OPENBLAS_NUM_THREADS = "1", MKL_NUM_THREADS = "1", OMP_NUM_THREADS = "1" } -help = "Coverage lane: 100 % of the CPU source required." +help = "Coverage lane: 100 % of the package required." # CI runs the coverage lane as parallel jobs: cov-part once per shard # (SOLPROP_TEST_SHARD=i/n, tests/shards.py), each leaving its own data file, which # cov-report combines from coverage-data/ and holds to the 100 %. [tool.poe.tasks.cov-part] -cmd = "pytest --cov --cov-config=coverage-cpu.ini --cov-report= --cov-fail-under=0 -m 'not slow and not gpu and not benchmark' -n auto --dist loadgroup" +cmd = "pytest --cov --cov-report= --cov-fail-under=0 -m 'not slow and not gpu and not benchmark' -n auto --dist loadgroup" env = { PYTHONUTF8 = "1", SOLPROP_THREADS = "1", SOLPROP_NATIVE_THREADS = "1", VECLIB_MAXIMUM_THREADS = "1", OPENBLAS_NUM_THREADS = "1", MKL_NUM_THREADS = "1", OMP_NUM_THREADS = "1" } help = "The coverage lane for one shard (SOLPROP_TEST_SHARD), without the 100 % check." [tool.poe.tasks.cov-report] sequence = [ - { cmd = "coverage combine --rcfile=coverage-cpu.ini coverage-data" }, - { cmd = "coverage xml --rcfile=coverage-cpu.ini --fail-under=0" }, - { cmd = "coverage report --rcfile=coverage-cpu.ini" }, + { cmd = "coverage combine coverage-data" }, + { cmd = "coverage xml --fail-under=0" }, + { cmd = "coverage report" }, ] help = "Combine the coverage parts in coverage-data/, write coverage.xml, require 100 %." diff --git a/src/solprop/__main__.py b/src/solprop/__main__.py index a1181207f..9c3feca0d 100644 --- a/src/solprop/__main__.py +++ b/src/solprop/__main__.py @@ -6,5 +6,7 @@ from solprop.cli import main +__all__: list[str] = [] + if __name__ == "__main__": raise SystemExit(main()) diff --git a/src/solprop/_process.py b/src/solprop/_process.py index b46cf246a..e945b9d68 100644 --- a/src/solprop/_process.py +++ b/src/solprop/_process.py @@ -387,8 +387,8 @@ class ThreadBudget: threads : int The budget, at least one. source : str - The tightest limit: ``"affinity"``, ``"cgroup quota"`` or the name of the - environment variable that set it. + The tightest limit: ``"affinity"``, ``"physical cores"``, + ``"top-tier cores"``, ``"cgroup quota"`` or ``"SOLPROP_THREADS"``. oversubscribe : bool Whether ``SOLPROP_OVERSUBSCRIBE`` lets an explicit count exceed the CPUs and the quota (see :meth:`explicit`). @@ -420,7 +420,7 @@ def explicit(self, count: int) -> int: Examples -------- - >>> from solprop._process import ThreadBudget + >>> from solprop.backends import ThreadBudget >>> ThreadBudget(4, "affinity").explicit(8) 4 >>> ThreadBudget(4, "affinity", oversubscribe=True).explicit(8) @@ -732,12 +732,12 @@ def parallel_rows[T](n_rows: int, nbytes: int, work: Callable[[slice], T]) -> li def thread_budget() -> ThreadBudget: """Return how many threads this process may run at once (ADR-052). - The smallest of the CPUs it may run on (:func:`allowed_cpus`: ``taskset``, a batch + The smallest of the CPUs it may run on (``allowed_cpus``: ``taskset``, a batch scheduler's allocation), the physical cores that hold them - (:func:`physical_cores`) and, on a chip with cores of several kinds, those of the - fastest kind (:func:`top_tier_cores`), both unless ``SOLPROP_THREADS`` is set, its + (``physical_cores``) and, on a chip with cores of several kinds, those of the + fastest kind (``top_tier_cores``), both unless ``SOLPROP_THREADS`` is set, its control groups' - CPU quota (:func:`cgroup_cpus`) and ``SOLPROP_THREADS``. Every pool solprop sizes + CPU quota (``cgroup_cpus``) and ``SOLPROP_THREADS``. Every pool solprop sizes is held within it, and so is any count asked for explicitly unless ``SOLPROP_OVERSUBSCRIBE=1`` (:meth:`ThreadBudget.explicit`); the pools take turns, so each may use the whole @@ -756,7 +756,7 @@ def thread_budget() -> ThreadBudget: Examples -------- - >>> from solprop._process import thread_budget + >>> from solprop.backends import thread_budget >>> thread_budget().threads >= 1 True """ diff --git a/src/solprop/backends/exponential.py b/src/solprop/backends/exponential.py index d8eb210b2..79f9af237 100644 --- a/src/solprop/backends/exponential.py +++ b/src/solprop/backends/exponential.py @@ -212,8 +212,6 @@ def _phi_near( out[0] = np.exp(y) for level in range(int(squarings.max(initial=0))): active = squarings > level - if not np.any(active): # pragma: no cover - squarings.max bounds the loop - break old = out[:, active] doubled = np.empty_like(old) doubled[0] = old[0] * old[0] diff --git a/src/solprop/backends/memory.py b/src/solprop/backends/memory.py index 6a3d56e51..a6aa8037c 100644 --- a/src/solprop/backends/memory.py +++ b/src/solprop/backends/memory.py @@ -234,13 +234,11 @@ def _low_storage_rows( "accumulator_error": 0, "register_accumulator": field_bytes, "register_stage": field_bytes, - "propagators": low_storage_flows(problem, stepper, "numpy_ref") * field_bytes, + "propagators": low_storage_flows(problem, stepper) * field_bytes, } -def low_storage_flows( - problem: PropagationProblem, stepper: StepperSettings, backend: str -) -> int: +def low_storage_flows(problem: PropagationProblem, stepper: StepperSettings) -> int: """Return how many flow volumes a compiled backend's low-storage march holds. The one predicate the engines share (SEP 24 section 4.3): with @@ -258,8 +256,6 @@ def low_storage_flows( The translated problem. stepper : solprop.stepper.settings.StepperSettings The run's stepper section, whose propagator mode decides the count. - backend : str - A registry name; every backend that runs the march counts the same. Returns ------- @@ -282,10 +278,9 @@ def low_storage_flows( ... controller=PIController(rtol=1e-8, atol=1e-16), ... save_planes=[0.01], dz_max=0.01, dz_init=1e-3, ... density=1.0, shock=False, prefactor_index=1.0) - >>> low_storage_flows(problem, request.stepper, "native") # a constant table + >>> low_storage_flows(problem, request.stepper) # a constant table 1 """ - del backend asked = stepper.propagator_mode constant = problem.flags.constant_linop if asked == "recompute" or (asked == "auto" and not constant): diff --git a/src/solprop/backends/node_chunk.py b/src/solprop/backends/node_chunk.py index fee0a25d0..a7497e3bb 100644 --- a/src/solprop/backends/node_chunk.py +++ b/src/solprop/backends/node_chunk.py @@ -30,11 +30,10 @@ cannot hold one node (or one planar row), and the last step spreads the nodes evenly over the passes the admitted chunk needs. -The counts are conservative inventories, not the live buffers of each route: SEP 28's -phase 0 found the twenty Cartesian column-equivalents about three times the live group -buffers (solprop issue #349). They stay, so that a user's budget keeps buying the chunk -it bought before; counting a route's live buffers changes the chunk of every explicit -budget, which is the maintainer's decision under #349 and #89, not this move's. +The counts are conservative inventories, not the live buffers of each route: the twenty +Cartesian column-equivalents are about three times the live group buffers (solprop +issue #349). An inventory fixed per route makes the chunk an explicit budget buys +predictable. A device backend may choose differently when no budget is given (solprop issue #361); the native backend's rule is ``solprop_native._device.device_node_chunk``, and an diff --git a/src/solprop/backends/numpy_ref/adams_kernels.py b/src/solprop/backends/numpy_ref/adams_kernels.py index dc8894838..99ce68a0e 100644 --- a/src/solprop/backends/numpy_ref/adams_kernels.py +++ b/src/solprop/backends/numpy_ref/adams_kernels.py @@ -25,7 +25,6 @@ from scipy.linalg import expm from solprop.backends.exponential import phi_functions -from solprop.backends.numpy_ref.adams_tables import exponential_rows from solprop.backends.numpy_ref.passes.stepping import accumulate __all__ = [ @@ -631,29 +630,6 @@ def predict( # noqa: PLR0917 - buffers are a kernel's parameters moments, coefficients, values, dz ) - def defect_rows( - self, nodes: list[float], orders: list[int], width: int - ) -> np.ndarray: - """Return the defects' coefficients in the form :meth:`correct` takes. - - Parameters - ---------- - nodes : list of float - The history's normalised positions, newest first. - orders : list of int - The orders scored, the step's own first. - width : int - ``1 + max(orders)``. - - Returns - ------- - numpy.ndarray - The monomial rows of - :func:`~solprop.backends.numpy_ref.adams_tables.exponential_rows`, shape - ``(len(orders), width, width)``. - """ - return exponential_rows(nodes, orders, width) - def correct( # noqa: PLR0917 - buffers are a kernel's parameters self, state: _State, diff --git a/src/solprop/backends/numpy_ref/backend.py b/src/solprop/backends/numpy_ref/backend.py index 72f353541..1bcaa3754 100644 --- a/src/solprop/backends/numpy_ref/backend.py +++ b/src/solprop/backends/numpy_ref/backend.py @@ -269,7 +269,6 @@ def method(self, host: object) -> HostMethod: host, schedule=schedule, proposal=stepper.dz_init, - lag=stepper.controller.lag, name=self.name, ) ) @@ -346,7 +345,6 @@ def _adams(self, method: Multistep, host: object) -> HostMethod: interpolate=interpolate, shape=self._problem.shape, proposal=stepper.dz_init, - lag=stepper.controller.lag, name=self.name, ) dense = AdamsDense(self._workspace, engine, march) if interpolate else None @@ -437,9 +435,10 @@ def timing_probe(self, start: Start) -> TimingProbe: The start's field, noise, position and resume flag are loaded as a session loads them; its method history, ledgers and monitor continuation are not read. - A Runge-Kutta trial leaves the loaded state alone; a low-storage march's step - advances the discarded registers in place, so a backend probed so is closed - afterwards (SEP 47 section 6.6). + An Adams run is probed with a Runge-Kutta trial of its tableau, as the + protocol states. A Runge-Kutta trial leaves the loaded state alone; a + low-storage march's step advances the discarded registers in place, so a + backend probed so is closed afterwards (SEP 47 section 6.6). Parameters ---------- @@ -479,16 +478,6 @@ def timing_probe(self, start: Start) -> TimingProbe: ) return _TrialProbe(self, engine, position, cursor, low_storage=False) - def available_device_memory(self) -> int | None: - """Return None for host execution. - - Returns - ------- - int or None - None: the reference runs on the host. - """ - return None - def metadata(self) -> dict[str, object]: """Return what this execution was, for the run's record. diff --git a/src/solprop/backends/numpy_ref/dense.py b/src/solprop/backends/numpy_ref/dense.py index c3c2f44d6..4e4aa5ccb 100644 --- a/src/solprop/backends/numpy_ref/dense.py +++ b/src/solprop/backends/numpy_ref/dense.py @@ -31,10 +31,10 @@ from solprop.backends.numpy_ref.engines import NumpyRungeKutta from solprop.backends.numpy_ref.marches.adams import AcceptedStep, HostAdamsMarch from solprop.backends.numpy_ref.multistep import ( + DenseStep, ExponentialHistory, + ExponentialStep, HostHistory, - _DenseStep, - _ExponentialStep, ) from solprop.backends.numpy_ref.workspace import NumpyWorkspace from solprop.exceptions import BackendError @@ -101,6 +101,9 @@ def crosses(position: float, target: float) -> bool: bool True past the plane's landing tolerance (``not reached(target, z)``). """ + # The march's own rule for holding a step's extension + # (`RungeKuttaMarch.march_to`): a step that ends within the landing tolerance + # of the plane holds none, so it must count as landing there, not crossing. return not reached(target, position) def observe(self, position: float) -> None: @@ -176,6 +179,9 @@ def crosses(position: float, target: float) -> bool: bool True when `position` is past it. """ + # Strict, unlike the Runge-Kutta rule: the Adams march records every accepted + # step (`HostAdamsMarch.last_step`), so any step past the plane, however + # slightly, can be interpolated, and a step that lands snaps to its target. return position > target def observe(self, position: float) -> None: @@ -196,10 +202,10 @@ def observe(self, position: float) -> None: raise BackendError("no accepted Adams step is held for a dense observation") held = self._engine.dense if isinstance(self._engine, ExponentialHistory): - assert isinstance(held, _ExponentialStep) + assert isinstance(held, ExponentialStep) observed = self._observe_exponential(held, step, position) else: - assert isinstance(held, _DenseStep) + assert isinstance(held, DenseStep) observed = self._observe_fused(held, step, position) self._held.hold(observed) @@ -208,7 +214,7 @@ def restore(self) -> None: self._held.restore() def _observe_fused( - self, held: _DenseStep, step: AcceptedStep, position: float + self, held: DenseStep, step: AcceptedStep, position: float ) -> _State: """Return the interaction formulation's field at `position`.""" workspace = self._workspace @@ -224,7 +230,7 @@ def _observe_fused( return workspace.mask(workspace.propagator(held.z, position, hold=True) * value) def _observe_exponential( - self, held: _ExponentialStep, step: AcceptedStep, position: float + self, held: ExponentialStep, step: AcceptedStep, position: float ) -> _State: """Return the exponential formulation's field at `position`. diff --git a/src/solprop/backends/numpy_ref/marches/__init__.py b/src/solprop/backends/numpy_ref/marches/__init__.py index dad519f62..772aca421 100644 --- a/src/solprop/backends/numpy_ref/marches/__init__.py +++ b/src/solprop/backends/numpy_ref/marches/__init__.py @@ -17,3 +17,5 @@ Only the reference runs them; the native session's compiled marches are traced against them (``docs/dev/backends.md`` section 1). """ + +__all__: list[str] = [] diff --git a/src/solprop/backends/numpy_ref/marches/adams.py b/src/solprop/backends/numpy_ref/marches/adams.py index 5804e1f70..36b7ca20a 100644 --- a/src/solprop/backends/numpy_ref/marches/adams.py +++ b/src/solprop/backends/numpy_ref/marches/adams.py @@ -8,7 +8,7 @@ engine protocol (:class:`solprop.backends.engines.AdamsEngine`) that native's ``march::Engine`` mirrors: the reference's engine is :class:`solprop.backends.numpy_ref.multistep.HostHistory`. The march holds its own state --- position, proposal, replay cursor and accepted norms +-- position, proposal and replay cursor (:class:`~solprop.backends.numpy_ref.marches.host.MarchState`), the history's entries, the order, the rejections and the call ledger -- and asks its session only through :class:`~solprop.backends.numpy_ref.marches.host.MarchHost`. The decisions are @@ -19,11 +19,10 @@ """ import math -from collections import deque from collections.abc import Callable, Iterator, Mapping from contextlib import contextmanager from dataclasses import dataclass -from typing import Any, cast +from typing import Any, cast, get_protocol_members import numpy as np @@ -31,7 +30,12 @@ from solprop.backends import adams_core from solprop.backends.engines import AdamsEngine, AttemptOutcome, HistoryEntry from solprop.backends.ledger import CallLedger -from solprop.backends.numpy_ref.marches.host import MarchHost, MarchState +from solprop.backends.numpy_ref.marches.host import ( + MarchHost, + MarchState, + replay_divergence, + replay_shortfall, +) from solprop.exceptions import BackendError, ConvergenceError, ResponseBudgetError from solprop.output.records import MarchSnapshot from solprop.stepper.controller import limit_step @@ -97,15 +101,13 @@ class HostAdamsMarch: The state's shape, which a snapshot's is checked against. proposal : float, optional The first proposal, m. - lag : int, optional - The lag of the controller whose norms a replay keeps. name : str, optional The backend's name, for messages. Attributes ---------- state : solprop.backends.numpy_ref.marches.host.MarchState - The march's position, proposal, cursor and accepted norms. + The march's position, proposal and cursor. ledger : solprop.backends.ledger.CallLedger The run's call counts. last_step : AcceptedStep or None @@ -130,7 +132,6 @@ def __init__( interpolate: bool = False, shape: tuple[int, ...] = (), proposal: float = 0.0, - lag: int = 1, name: str = "numpy_ref", ) -> None: """Hold the engine and start with no history.""" @@ -144,7 +145,7 @@ def __init__( self._interpolate = interpolate self._shape = shape self._name = name - self.state = MarchState(z=0.0, proposal=proposal, norms=deque(maxlen=lag + 2)) + self.state = MarchState(z=0.0, proposal=proposal) self._history: list[HistoryEntry] = [] self._rejections = 0 self._last_rejected = False @@ -389,17 +390,12 @@ def _replay_to(self, schedule: FixedSchedule, target: float) -> None: state.cursor += 1 host.record(end, dz, norm, accepted=True) attempt.end(AttemptOutcome.ACCEPTED) - state.norms.append(norm) self._raise_floor() host.stepped() if host.natural_stop(target): return if state.z < target - slack: - msg = ( - f"the replayed schedule ends at {float(schedule.z_end):.6g} m and " - f"cannot reach z = {target:.6g} m" - ) - raise BackendError(msg) + raise BackendError(replay_shortfall(float(schedule.z_end), target)) def replay_step(self, dz: float, end: float, slack: float) -> float: """Take one prescribed step from the march's position and accept it. @@ -433,18 +429,11 @@ def replay_step(self, dz: float, end: float, slack: float) -> float: kink = adams_core.replay_kink(self._policy, end, slack) _, norm = self._attempt(dz, fixed=True, landing=(end, kink)) if not math.isfinite(norm): - msg = ( + step = ( f"{self._name}: a replayed {self._method.name} step of " - f"{dz:.4g} m ending at z = {end:.6g} m has a non-finite error norm " - f"({norm!r}): the field has diverged. A replayed schedule takes " - "its steps as given and cannot reject one, so a step beyond an " - "explicit stability limit -- the in-stage temporal collar's or a " - "coupled flow's advisory step -- grows until it overflows; the " - "translation refuses a declared step past the collar's limit and " - "warns on one past the flow's. Take shorter steps, or let the " - "controller choose them" + f"{dz:.4g} m ending at z = {end:.6g} m" ) - raise ConvergenceError(msg) + raise ConvergenceError(replay_divergence(step, norm)) return norm def _end(self, attempt: "_Attempt", *, accepted: bool) -> None: @@ -754,17 +743,8 @@ def end(self, outcome: AttemptOutcome) -> None: self._engine.end_attempt(outcome) -_ENGINE_MEMBERS = ( - "start", - "trial", - "accept", - "chord_phase", - "step_carrier", - "begin_attempt", - "end_attempt", - "reading", -) -"""What the march asks of an engine: the protocol.""" +_ENGINE_MEMBERS = tuple(sorted(get_protocol_members(AdamsEngine))) +"""What the march asks of an engine: the protocol's members, sorted.""" def _check_engine(engine: object) -> None: diff --git a/src/solprop/backends/numpy_ref/marches/host.py b/src/solprop/backends/numpy_ref/marches/host.py index a67ee52b4..6d3917b64 100644 --- a/src/solprop/backends/numpy_ref/marches/host.py +++ b/src/solprop/backends/numpy_ref/marches/host.py @@ -22,7 +22,13 @@ from solprop.backends.engines import AcceptRecord -__all__ = ["MarchHost", "MarchState", "in_flight_refusal"] +__all__ = [ + "MarchHost", + "MarchState", + "in_flight_refusal", + "replay_divergence", + "replay_shortfall", +] @dataclass(eq=False) @@ -38,8 +44,8 @@ class MarchState: cursor : int A replay's next step: how many steps of the schedule are consumed. norms : collections.deque - The accepted steps' norms the controller reads, oldest first, at most its - lag and two more. + The accepted steps' norms the adaptive Runge-Kutta controller reads, oldest + first, at most its lag and two more; the other marches leave it empty. """ z: float @@ -173,3 +179,49 @@ def in_flight_refusal(name: str, z: float, dz: float) -> str: "neither end of the step; start a new session from the last saved plane " "before observing or propagating again" ) + + +def replay_divergence(step: str, norm: float) -> str: + """Return why a replayed step whose error norm is not finite stops the run. + + Parameters + ---------- + step : str + The step, as the march names it, beginning with the backend's name. + norm : float + The step's error norm. + + Returns + ------- + str + The message. + """ + return ( + f"{step} has a non-finite error norm ({norm!r}): the field has diverged. A " + "replayed schedule takes its steps as given and cannot reject one, so a step " + "beyond an explicit stability limit -- the in-stage temporal collar's or a " + "coupled flow's advisory step -- grows until it overflows; the translation " + "refuses a declared step past the collar's limit and warns on one past the " + "flow's. Take shorter steps, or let the controller choose them" + ) + + +def replay_shortfall(z_end: float, target: float) -> str: + """Return why a replayed schedule that ends short of a target stops the run. + + Parameters + ---------- + z_end : float + Where the schedule ends, m. + target : float + The position it was asked to reach, m. + + Returns + ------- + str + The message. + """ + return ( + f"the replayed schedule ends at {z_end:.6g} m and cannot reach " + f"z = {target:.6g} m" + ) diff --git a/src/solprop/backends/numpy_ref/marches/low_storage.py b/src/solprop/backends/numpy_ref/marches/low_storage.py index d6bfdb943..02817db7a 100644 --- a/src/solprop/backends/numpy_ref/marches/low_storage.py +++ b/src/solprop/backends/numpy_ref/marches/low_storage.py @@ -16,7 +16,6 @@ import logging import math -from collections import deque from typing import cast from solprop._interrupts import committing @@ -25,6 +24,7 @@ MarchHost, MarchState, in_flight_refusal, + replay_shortfall, ) from solprop.exceptions import BackendError, ConvergenceError from solprop.stepper.low_storage import LowStorageRungeKutta @@ -55,15 +55,13 @@ class HostLowStorageMarch: The schedule it replays. proposal : float The proposal it keeps, m, which a replay never updates. - lag : int, optional - The lag of the controller whose norms the replay keeps. name : str, optional The backend's name, for messages. Attributes ---------- state : solprop.backends.numpy_ref.marches.host.MarchState - The march's position, proposal, cursor and accepted norms. + The march's position, proposal and cursor. source_evaluations : int Source evaluations of the committed steps since the state was last loaded, four a step: a physical count, never a logical response call (SEP 24 section @@ -88,7 +86,6 @@ def __init__( *, schedule: FixedSchedule, proposal: float, - lag: int = 1, name: str = "numpy_ref", ) -> None: """Hold the engine; the march stands at the entrance.""" @@ -100,7 +97,7 @@ def __init__( self._warned = False # The step whose trial the engine left in flight, while it is. self._pending: tuple[float, float] | None = None - self.state = MarchState(z=0.0, proposal=proposal, norms=deque(maxlen=lag + 2)) + self.state = MarchState(z=0.0, proposal=proposal) self.source_evaluations = 0 @property @@ -174,26 +171,19 @@ def replay_to(self, schedule: FixedSchedule, target: float) -> None: host.poll_stop() dz = float(schedule.steps[state.cursor]) end = float(edges[state.cursor + 1]) - norm = self.replay_step(dz, end, slack) + norm = self.replay_step(dz, end) state.cursor += 1 host.record(end, dz, norm, accepted=True) - state.norms.append(norm) host.stepped() if host.natural_stop(target): return if state.z < target - slack: - msg = ( - f"the replayed schedule ends at {float(schedule.z_end):.6g} m and " - f"cannot reach z = {target:.6g} m" - ) - raise BackendError(msg) + raise BackendError(replay_shortfall(float(schedule.z_end), target)) - def replay_step(self, dz: float, end: float, slack: float) -> float: + def replay_step(self, dz: float, end: float) -> float: """Take one prescribed step from the march's position and accept it. - The unit a replay advances by, with - :meth:`solprop.backends.numpy_ref.marches.adams.HostAdamsMarch.replay_step`'s - signature. + The unit a replay advances by. Parameters ---------- @@ -201,9 +191,6 @@ def replay_step(self, dz: float, end: float, slack: float) -> float: The step, m. end : float The schedule's edge it ends on, m. - slack : float - How far an edge may sit from a target it lands on, m; unused, since the - march restarts nothing at a kink. Returns ------- @@ -218,7 +205,6 @@ def replay_step(self, dz: float, end: float, slack: float) -> float: If the accepted state is not finite: the field has diverged, and a replay cannot reject the step. Raised in flight, so the state is lost with it. """ - del slack refusal = self.refusal() if refusal is not None: raise BackendError(refusal) diff --git a/src/solprop/backends/numpy_ref/marches/runge_kutta.py b/src/solprop/backends/numpy_ref/marches/runge_kutta.py index d02487e38..3f2192f56 100644 --- a/src/solprop/backends/numpy_ref/marches/runge_kutta.py +++ b/src/solprop/backends/numpy_ref/marches/runge_kutta.py @@ -26,7 +26,12 @@ from solprop._interrupts import committing from solprop.backends import rk_core from solprop.backends.engines import RungeKuttaEngine -from solprop.backends.numpy_ref.marches.host import MarchHost, MarchState +from solprop.backends.numpy_ref.marches.host import ( + MarchHost, + MarchState, + replay_divergence, + replay_shortfall, +) from solprop.backends.records import RungeKuttaPolicy from solprop.exceptions import BackendError, ConvergenceError from solprop.stepper.schedule import ( @@ -242,18 +247,11 @@ def replay_to(self, schedule: FixedSchedule, target: float) -> None: self._trying = (state.z, dz) norm = engine.trial(state.z, dz) if not math.isfinite(norm): - msg = ( + step = ( f"{self._name}: replayed step {state.cursor + 1} of " - f"{schedule.n_steps}, {dz:.4g} m from z = {state.z:.6g} m, has a " - f"non-finite error norm ({norm!r}): the field has diverged. A " - "replayed schedule takes its steps as given and cannot reject " - "one, so a step beyond an explicit stability limit -- the " - "in-stage temporal collar's or a coupled flow's advisory step -- " - "grows until it overflows; the translation refuses a declared step " - "past the collar's limit and warns on one past the flow's. Take " - "shorter steps, or let the controller choose them" + f"{schedule.n_steps}, {dz:.4g} m from z = {state.z:.6g} m," ) - raise ConvergenceError(msg) + raise ConvergenceError(replay_divergence(step, norm)) end = float(edges[state.cursor + 1]) with committing(): record = engine.accept(dz) @@ -266,8 +264,4 @@ def replay_to(self, schedule: FixedSchedule, target: float) -> None: if host.natural_stop(target): return if state.z < target - slack: - msg = ( - f"the replayed schedule ends at {float(schedule.z_end):.6g} m and " - f"cannot reach z = {target:.6g} m" - ) - raise BackendError(msg) + raise BackendError(replay_shortfall(float(schedule.z_end), target)) diff --git a/src/solprop/backends/numpy_ref/multistep.py b/src/solprop/backends/numpy_ref/multistep.py index dec78ef22..0a692da18 100644 --- a/src/solprop/backends/numpy_ref/multistep.py +++ b/src/solprop/backends/numpy_ref/multistep.py @@ -44,7 +44,11 @@ ExponentialKernels, coupled_moments, ) -from solprop.backends.numpy_ref.adams_tables import defect_rows, exponential_corrector +from solprop.backends.numpy_ref.adams_tables import ( + defect_rows, + exponential_corrector, + exponential_rows, +) from solprop.exceptions import BackendError from solprop.stepper.multistep import ( Multistep, @@ -57,7 +61,14 @@ from solprop.backends.numpy_ref.workspace import NumpyWorkspace from solprop.stepper.controller import PIController -__all__ = ["AdamsRows", "ExponentialHistory", "HostHistory", "InteractionHistory"] +__all__ = [ + "AdamsRows", + "DenseStep", + "ExponentialHistory", + "ExponentialStep", + "HostHistory", + "InteractionHistory", +] logger = logging.getLogger(__name__) @@ -69,12 +80,22 @@ @dataclass -class _DenseStep: +class DenseStep: """The last accepted step, in its anchor's frame, for dense observation. - Its slopes, the new source first; the observation's weights are the session's, from - the march's record of the step + The observation's weights are the session's, from the march's record of the step (:class:`solprop.backends.numpy_ref.marches.adams.AcceptedStep`). + + Attributes + ---------- + z : float + The step's start, m. + dz : float + The step, m. + start : numpy.ndarray + The state at its start, ``(n_modes, n_pol, n_omega)``. + slopes : list of numpy.ndarray + Its slopes, the new source first, each of the state's shape. """ z: float @@ -84,12 +105,28 @@ class _DenseStep: @dataclass -class _ExponentialStep: +class ExponentialStep: """The last accepted exponential step, for dense observation. - Its samples as stored, the new one first; the observation's coefficients and, under - a carrier frame, its rotations are the session's, from the march's record of the - step (:class:`solprop.backends.numpy_ref.marches.adams.AcceptedStep`). + The observation's coefficients and, under a carrier frame, its rotations are the + session's, from the march's record of the step + (:class:`solprop.backends.numpy_ref.marches.adams.AcceptedStep`). + + Attributes + ---------- + z : float + The step's start, m. + dz : float + The step, m. + start : numpy.ndarray + The state at its start, ``(n_modes, n_pol, n_omega)``. + exponent : numpy.ndarray + The step's chord exponent ``x = h B_n``, of the state's shape. + values : list of numpy.ndarray + Its samples as stored, the new one first, each of the state's shape. + compensation : tuple or None + A varying operator's corrector nodes ``(1, theta_0, ...)`` and matching + untransported compensations; ``None`` without compensation. """ z: float @@ -756,7 +793,7 @@ def _accept(self, keep: np.ndarray, free: int) -> AcceptRecord: trial.source, *(store[slot].copy() for slot in trial.slots[:order]), ] - self.dense = _DenseStep( + self.dense = DenseStep( z=trial.z, dz=trial.dz, start=trial.state.copy(), @@ -893,8 +930,6 @@ def _trial( # noqa: PLR0917 - called positionally width = 1 + max(orders) # The exponent is the backend's own increment of Phi over the step, so the # flow below is exactly the propagator the interaction formulation applies. - # Copied: a z table's host evaluator returns its own reused buffer, which the - # source evaluation writes again. exponent = np.array(workspace.delta_phi(workspace.stage_scalars(z, z + dz))) # A coupled section's step (SEP 16 phase 5): its flow and moments are matrix # functions of the frozen block on the bins that carry one, applied by the @@ -942,7 +977,7 @@ def _trial( # noqa: PLR0917 - called positionally lab = lab + compensation.predictor(order) source = workspace.lab_source(lab, z + dz, purpose="predictor") corrector = exponential_corrector(nodes, order, width) - rows = kernels.defect_rows(nodes, orders, width) + rows = exponential_rows(nodes, orders, width) extra = None if compensation is not None: rate = phi_rate( @@ -1007,7 +1042,7 @@ def _accept(self, keep: np.ndarray, free: int) -> AcceptRecord: # below leave out (they are the diagonal chord's alone). assert self._workspace.problem.linear.coupled_flow is None # Copied: the store's rows are overwritten by later steps. - self.dense = _ExponentialStep( + self.dense = ExponentialStep( z=z, dz=dz, start=trial.state.copy(), diff --git a/src/solprop/backends/numpy_ref/passes/__init__.py b/src/solprop/backends/numpy_ref/passes/__init__.py index 113dcbadc..791145cf9 100644 --- a/src/solprop/backends/numpy_ref/passes/__init__.py +++ b/src/solprop/backends/numpy_ref/passes/__init__.py @@ -50,3 +50,5 @@ change the stated units of ``raman_kernel_undamped`` and cost the bitwise agreement with :meth:`solprop.nonlinear.raman.RamanResponse.evaluate` that pins that pass. """ + +__all__: list[str] = [] diff --git a/src/solprop/backends/numpy_ref/passes/stepping.py b/src/solprop/backends/numpy_ref/passes/stepping.py index 41737df4d..843d9cc56 100644 --- a/src/solprop/backends/numpy_ref/passes/stepping.py +++ b/src/solprop/backends/numpy_ref/passes/stepping.py @@ -110,7 +110,8 @@ def stage_output( The modal polarisation on the coarse grid, complex128, shape ``(n_modes, n_pol, n_omega)``, in C/m^2. prefactor : numpy.ndarray - ``responses.prefactor_at(responses, z)``, complex128, in m/(V s), broadcastable + ``responses.prefactor_at(responses, z)``, complex128, in the unit + :class:`~solprop.translate.responses.CompiledResponses` states, broadcastable against the polarisation. omega_window : numpy.ndarray The spectral collar profile in ``[0, 1]``, float64, shape ``(n_omega,)``. diff --git a/src/solprop/backends/numpy_ref/workspace.py b/src/solprop/backends/numpy_ref/workspace.py index d44076fb0..41484fc9f 100644 --- a/src/solprop/backends/numpy_ref/workspace.py +++ b/src/solprop/backends/numpy_ref/workspace.py @@ -644,7 +644,8 @@ def prefactor( Returns ------- numpy.ndarray - The prefactor times the crop scale, in m/(V s) per unit polarisation. + The prefactor times the crop scale, in the unit + :class:`~solprop.translate.responses.CompiledResponses` states. """ if bundle.prefactor is None or self._terms.prefactor is None: return prefactor_at(self._problem.responses, bundle.z1, helpers=PLAIN) diff --git a/src/solprop/backends/protocol.py b/src/solprop/backends/protocol.py index 9484864e3..20cb01f44 100644 --- a/src/solprop/backends/protocol.py +++ b/src/solprop/backends/protocol.py @@ -617,9 +617,9 @@ class Backend(Protocol): >>> from solprop.backends.protocol import Backend >>> names = [name for name in sorted(dir(Backend)) if not name.startswith("_")] >>> names[:4] - ['available_device_memory', 'close', 'closed', 'edge_memory'] + ['close', 'closed', 'edge_memory', 'memory_ledger'] >>> names[4:] - ['memory_ledger', 'metadata', 'prepare', 'request', 'timing_probe'] + ['metadata', 'prepare', 'request', 'timing_probe'] """ name: str @@ -697,6 +697,9 @@ def timing_probe( The start's field, noise, position and resume flag are loaded as a session loads them; its method history, ledgers and monitor continuation are not read. + An Adams run is probed with a Runge-Kutta trial of its tableau: a start holds + no history to step from, and the probe's callers want the cost of one + right-hand-side evaluation, which they get by dividing by the stage count. Parameters ---------- @@ -710,17 +713,6 @@ def timing_probe( """ ... - def available_device_memory(self) -> int | None: - """Return currently free device bytes, or None for a host backend. - - Returns - ------- - int or None - Free device memory excluding live allocations and allocator reserves. - Host memory is admitted independently by the controller. - """ - ... - def memory_ledger(self) -> dict[str, int]: """Return the size of every buffer the backend holds. diff --git a/src/solprop/backends/records.py b/src/solprop/backends/records.py index ae977ef51..bd6e5127c 100644 --- a/src/solprop/backends/records.py +++ b/src/solprop/backends/records.py @@ -44,9 +44,9 @@ from solprop.backends.exponential import carrier_reference from solprop.backends.memory import low_storage_flows from solprop.monitor import ( - _FLOOR, # pyright: ignore[reportPrivateUsage] - the floor the monitor judges by + _FLOOR, # the floor the monitor judges by FLOOR_MARGIN, - _count, # pyright: ignore[reportPrivateUsage] - one refusal of a count + _count, # one refusal of a count ) from solprop.spatial_absorber import RAMP_K_FLOOR from solprop.stepper.controller import START_GROWTH, PIController @@ -363,7 +363,7 @@ def low_storage_settings( if not isinstance(stepper.integrator, LowStorageRungeKutta): return None return LowStorageSettings( - flows=low_storage_flows(problem, stepper, "native"), + flows=low_storage_flows(problem, stepper), separable=problem.linear.separable is not None, origin=float(problem.linear.z_span[0]), ) @@ -684,8 +684,8 @@ def edge_config( The configuration. """ design = edge.design - faces = edge._faces # pyright: ignore[reportPrivateUsage] - the edge's own geometry - weights = edge._weights # pyright: ignore[reportPrivateUsage] + faces = edge._faces # the edge's own geometry + weights = edge._weights first = faces[0].edge modes = max(int(np.count_nonzero(first)), 1) * max(int(edge.band.size), 1) return EdgeConfig( @@ -693,7 +693,7 @@ def edge_config( warn=edge.budget**2, stop=(edge.stop_factor * edge.budget) ** 2, length=float(edge.length), - guard=float(edge._guard), # pyright: ignore[reportPrivateUsage] + guard=float(edge._guard), k_min=float(edge.k_min), k_floor=float(RAMP_K_FLOOR), reads=float(READS), @@ -701,15 +701,15 @@ def edge_config( reach_growth=float(REACH_GROWTH), noise_factor=float(NOISE_FACTOR), columns=np.ascontiguousarray( - edge._columns, # pyright: ignore[reportPrivateUsage] + edge._columns, dtype=np.float64, ), kappa=np.ascontiguousarray( - edge._kappa, # pyright: ignore[reportPrivateUsage] + edge._kappa, dtype=np.float64, ), kappa_order=np.ascontiguousarray( - edge._kappa_order, # pyright: ignore[reportPrivateUsage] + edge._kappa_order, dtype=np.uint64, ), design=design is not None, @@ -969,7 +969,7 @@ def monitor_continuation( cast("Mapping[str, object]", record) if isinstance(record, Mapping) else None ) edge = monitor.transverse - faces = 0 if edge is None else len(edge._faces) # pyright: ignore[reportPrivateUsage] + faces = 0 if edge is None else len(edge._faces) stretches = cast("Sequence[tuple[float, float]]", continuation.get("unwatched", ())) return MonitorContinuation( record=resumption(mapping), diff --git a/src/solprop/backends/registry.py b/src/solprop/backends/registry.py index de3c4fa31..712524e95 100644 --- a/src/solprop/backends/registry.py +++ b/src/solprop/backends/registry.py @@ -23,7 +23,7 @@ import importlib.util import logging import os -from collections.abc import Callable, Collection, Mapping, Sequence +from collections.abc import Callable, Mapping, Sequence from pathlib import Path from types import ModuleType from typing import Final, cast @@ -34,7 +34,6 @@ from solprop.grid import TimeGrid from solprop.modes.protocol import Mode from solprop.profiles import ZProfile -from solprop.spatial import FAR_FIELD_STATISTICS from solprop.translate.problem import PropagationProblem from solprop.translate.run_request import RunRequest from solprop.translate.tdse import TDSEBinding @@ -46,7 +45,6 @@ "available", "resolve_name", "select", - "statistics_refusal", ] logger = logging.getLogger(__name__) @@ -98,52 +96,11 @@ def _native_installed() -> bool: return importlib.util.find_spec(_NATIVE_PACKAGE) is not None -def statistics_refusal(name: str, names: Sequence[str]) -> str | None: - """Return why a backend cannot form some of the statistics named, or ``None``. - - Asking about the native backend imports the installed package, as selecting it - would, to read the far-field statistics its class declares it forms. - - Parameters - ---------- - name : str - The resolved backend name. - names : collections.abc.Sequence of str - The statistics asked for. - - Returns - ------- - str or None - The refusal, naming the backend that forms them, or ``None`` when the backend - forms every one (or is not installed, which selecting it reports). - - Examples - -------- - >>> from solprop.backends.registry import statistics_refusal - >>> statistics_refusal("numpy_ref", ["energy", "beam_spectrum"]) is None - True - """ - asked = [one for one in names if one in FAR_FIELD_STATISTICS] - # numpy_ref forms every far-field statistic. - if not asked or name != "native" or not _native_installed(): - return None - from solprop_native import ( # noqa: PLC0415 # pyright: ignore[reportMissingImports] - NativeBackend, - ) - - formed = cast(Collection[str], NativeBackend.far_field_statistics) - missing = [one for one in asked if one not in formed] - if not missing: - return None - return ( - f"the installed native backend does not form the far-field statistics " - f"{missing}; install a solprop-native build that does, or run them on " - "numpy_ref" - ) - - def available() -> tuple[str, ...]: - """Return the names of the backends that can run here and now. + """Return the names of the backends installed here. + + An installed native package may still be refused when selected: on a processor + below its build's CPU baseline (:func:`resolve_name`), or when it does not load. Detection is by :func:`importlib.util.find_spec`, so nothing is imported and nothing is cached: a native package installed while the process runs becomes available @@ -153,7 +110,7 @@ def available() -> tuple[str, ...]: Returns ------- tuple of str - The usable names, in the order of :data:`BACKEND_NAMES`. + The installed names, in the order of :data:`BACKEND_NAMES`. Examples -------- @@ -366,8 +323,9 @@ def select( Raises ------ BackendError - If ``name`` is neither backend, or the backend does not run what the problem - asks for; the message says what to use instead. + If ``name`` is neither backend, the native package refuses one of its + process-start settings as it loads, or the backend does not run what the + problem asks for; the message says what to use instead. ImportError If ``name`` is ``"native"`` and its package is missing; the message says what to install. @@ -379,19 +337,17 @@ def select( ('numpy_ref', 'native') """ name = resolve_name(name) + _check_required_device(name) if name == "native": + if not _native_installed(): + raise ImportError(_NATIVE_INSTALL) # SEP 46: a first native workspace in an allocation with no profile row runs - # the quick calibration first, before the extension's runtime starts if it - # has not yet. + # the quick calibration first, once every refusal above has passed, and before + # the extension's runtime starts if it has not yet. A required device that + # passed is a device build, which never calibrates. from solprop.calibration.first_use import ensure # noqa: PLC0415 - layer above ensure() - _check_required_device(name) - refusal = statistics_refusal(name, request.observation.stats.names) - if refusal is not None: - raise BackendError(refusal) - if name == "native" and not _native_installed(): - raise ImportError(_NATIVE_INSTALL) backend = _construct( name, problem, @@ -420,14 +376,20 @@ def _construct( """Import and build the named backend, whose package is installed. Imported here, not at module scope: selecting a backend must not be a reason to - import the other or initialize a native runtime. A TDSE binding goes to either - backend, which refuses a problem without its binding by name. + import the other or initialize a native runtime. The native package reads its + process-start settings (thread counts, the CPU variant, the wait policy) as it + loads, and refuses a malformed one with a plain ``ValueError`` or ``RuntimeError``, + which is re-raised as a :class:`BackendError` with its text. A TDSE binding goes to + either backend, which refuses a problem without its binding by name. """ factory: Callable[..., Backend] if name == "native": - from solprop_native import ( # noqa: PLC0415 # pyright: ignore[reportMissingImports] - NativeBackend, - ) + try: + from solprop_native import ( # noqa: PLC0415 # pyright: ignore[reportMissingImports] + NativeBackend, + ) + except (ValueError, RuntimeError) as error: + raise BackendError(f"solprop-native did not load: {error}") from error factory = cast("Callable[..., Backend]", NativeBackend) else: diff --git a/src/solprop/backends/session.py b/src/solprop/backends/session.py index 3edf21efb..a4ca28bc2 100644 --- a/src/solprop/backends/session.py +++ b/src/solprop/backends/session.py @@ -664,7 +664,12 @@ def execution_record(self) -> Mapping[str, object]: ... def monitor_record(self) -> Mapping[str, object] | None: - """Return the boundary monitor's record, or ``None`` without a monitor.""" + """Return the boundary monitor's record, or ``None`` without a monitor. + + The run layer reads the record from :meth:`execution_record`, which carries it + once the monitor watches; this member is the seam the session conformance + tests read it through, on either backend, before and between events. + """ ... def continue_monitor(self, continuation: Mapping[str, object]) -> None: diff --git a/src/solprop/backends/spatial.py b/src/solprop/backends/spatial.py index d0463fb31..b6bb8121d 100644 --- a/src/solprop/backends/spatial.py +++ b/src/solprop/backends/spatial.py @@ -98,7 +98,7 @@ def collar_field_fraction( of frequency** (:func:`collar_block`), never as the whole volume: each node's fluence is a sum over frequency, so blocks accumulate it exactly, up to the order of the sum (SEP 22 section 6.3), and the transient is one block, bounded by the - node chunk. The radial kind synthesises by node chunk, as before. + node chunk. The radial kind synthesises by node chunk. """ transform = problem.transform chunk = plan_node_chunk(problem).chunk if node_chunk is None else node_chunk @@ -975,8 +975,10 @@ def _axis_statistics( - Returns: requested on-axis statistics and axial fluence in J/m^2. """ conversion = 0.5 * EPS0 * C - factor = fourier.spectral_density( - np.ones(grid.n_omega, complex), grid.dt, kind=grid.kind + # The energy weight of each bin per unit frequency: on a field grid the end bins + # take the analytic signal's weight, a quarter of an interior bin's. + factor = ( + fourier.energy_weights(grid.n_omega, grid.dt, kind=grid.kind) / grid.d_omega ) density = conversion * factor * np.sum(np.real(axis * np.conj(closure)), axis=0) values: dict[str, np.ndarray] = {} diff --git a/src/solprop/boundaries.py b/src/solprop/boundaries.py index 8fa69220b..db42c63d9 100644 --- a/src/solprop/boundaries.py +++ b/src/solprop/boundaries.py @@ -17,11 +17,11 @@ (:data:`DEFAULT_BOUNDARY_N`) and an optional separate collar length or walk-off. - The spectral rate is folded into the linear operator. The temporal rate is applied inside every stage (:func:`nonlinear_absorber_term`, bounded by :func:`stable_step`) - or as a split factor after each accepted step (:func:`split_step_factor`, - :func:`apply_split_step`, with the walk-off step limit of :class:`SplitCrossing`, + or, by the backends, as the split factor ``exp(-alpha(t) h / 2)`` after each + accepted step, with the walk-off step limit of :class:`SplitCrossing`, :func:`split_crossing_step`, :func:`split_rate_buckets` and - :func:`split_bucket_rates`). :func:`apply_band_mask` is the idempotent hard band - limit, and :func:`warn_walkoff` says when the absorber is too weak for the run. + :func:`split_bucket_rates`. :func:`warn_walkoff` says when the absorber is too weak + for the run. - :class:`SpatialAbsorber` and :class:`SpatialAbsorberDesign`, a free-space run's transverse boundary, are re-exported from :mod:`solprop.spatial_absorber`. @@ -43,6 +43,7 @@ from jaxtyping import Bool, Complex, Float, Inexact, UInt8 from solprop._process import parallel_rows +from solprop._validation import PACKAGE_FILES from solprop.exceptions import GridError, SolpropWarning from solprop.grid import Collar, TimeGrid from solprop.spatial_absorber import SpatialAbsorber, SpatialAbsorberDesign @@ -63,8 +64,6 @@ "SpatialAbsorberDesign", "SplitCrossing", "absorber", - "apply_band_mask", - "apply_split_step", "collar_rate", "custom_absorber", "no_absorber", @@ -72,7 +71,6 @@ "split_bucket_rates", "split_crossing_step", "split_rate_buckets", - "split_step_factor", "stable_step", "temporal_collar_rate", "warn_walkoff", @@ -217,8 +215,7 @@ class Absorber: strength, whose largest rate is ``12.6 / ell_c``; it also sets the temporal rates' ceiling, ``60 / ell_c``. A free-space run's real-space collar is designed separately (:class:`SpatialAbsorber`, SEP 40). ``None``, the - default, means - `reference_length`, as for every absorber before SEP 22; a value equal to + default, means `reference_length`; a value equal to `reference_length` is stored as ``None``, so that the record carries it only where the two differ. Left out of the run record at ``None``. temporal : bool @@ -1084,8 +1081,8 @@ def stable_step(temporal_rate: Float[np.ndarray, " n_t"]) -> float: The ``"nonlinear"`` absorber scheme adds ``-alpha(t) E(t) / 2`` to the derivative, so the collar's largest rate becomes an eigenvalue of the linearised problem and an explicit Runge-Kutta method must keep ``h alpha / 2`` inside its stability region. - The split factor of :func:`split_step_factor` integrates the same term *exactly* and - is unconditionally stable, which is the one thing it is better at. + The ``"split_step"`` scheme's factor ``exp(-alpha h / 2)`` integrates the same term + *exactly* and is unconditionally stable, which is the one thing it is better at. DOPRI5's and Tsit5's stability region reaches :data:`STABILITY_RADIUS` along the negative real axis, so the limit is ``2 R / max(alpha)``. Measured on the 1 mm @@ -1126,90 +1123,6 @@ def stable_step(temporal_rate: Float[np.ndarray, " n_t"]) -> float: return 2.0 * STABILITY_RADIUS / largest -def split_step_factor( - temporal_rate: Float[np.ndarray, " n_t"], step: float -) -> Float[np.ndarray, " n_t"]: - """Return the factor the temporal absorber multiplies the field by over one step. - - ``exp(-alpha(t) h / 2)``: the field, not the power, because that is what the state - holds, and ``alpha`` is a power coefficient. Successive factors telescope exactly to - ``exp(-alpha(t) L / 2)`` however the solver subdivides the propagation, which is the - whole point of rate semantics -- and the property the tests assert. - - The factor of one half is required: ``exp(-alpha(t) h)`` could not be right - alongside the ``-alpha(t) E(t) / 2`` of the alternative scheme, or alongside - ``alpha = -2 log W / ell``: with it, one reference length would apply the collar - profile to the field twice, and the two schemes would differ at first order in the - step rather than agreeing there. - - Parameters - ---------- - temporal_rate : numpy.ndarray - Power absorption coefficient on the time axis, 1/m, shape ``(n_t,)``. - step : float - Distance travelled in metres, non-negative. - - Returns - ------- - numpy.ndarray - Multiplicative factor in ``(0, 1]``, shape ``(n_t,)``. - - Raises - ------ - GridError - If the step is negative or not finite. - - Examples - -------- - >>> import numpy as np - >>> from solprop.boundaries import collar_rate, split_step_factor - >>> alpha = collar_rate(np.array([1.0, 0.5]), 0.1) - >>> np.round(split_step_factor(alpha, 0.1), 6).tolist() - [1.0, 0.5] - """ - if not (math.isfinite(step) and step >= 0.0): - msg = f"step must be non-negative and finite, got {step!r}" - raise GridError(msg) - return np.exp(-0.5 * temporal_rate * step) - - -def apply_split_step( - field: Inexact[np.ndarray, "*batch n_t"], - temporal_rate: Float[np.ndarray, " n_t"], - step: float, -) -> Inexact[np.ndarray, "*batch n_t"]: - """Apply the temporal absorber to a time-domain field over one accepted step. - - The reference implementation of the split-step absorber scheme, the alternative to - the in-stage term of :func:`nonlinear_absorber_term`, and what that term is - measured against. - - Parameters - ---------- - field : numpy.ndarray - Time-domain field, shape ``(..., n_t)``; real on a field grid, complex on an - envelope grid. - temporal_rate : numpy.ndarray - Power absorption coefficient on the time axis, 1/m, shape ``(n_t,)``. - step : float - Distance travelled in metres. - - Returns - ------- - numpy.ndarray - The attenuated field, with the shape of ``field``. - - Examples - -------- - >>> import numpy as np - >>> from solprop.boundaries import apply_split_step, collar_rate - >>> alpha = collar_rate(np.array([1.0, 0.5]), 0.1) - >>> np.round(apply_split_step(np.ones((1, 2)), alpha, 0.1), 6).tolist() - [[1.0, 0.5]] - """ - return field * split_step_factor(temporal_rate, step) - - def nonlinear_absorber_term( field: Inexact[np.ndarray, "*batch n_t"], temporal_rate: Float[np.ndarray, " n_t"], @@ -1218,10 +1131,10 @@ def nonlinear_absorber_term( ``-alpha(t) E(t) / 2``: the derivative form of the same rate, and the reference implementation of the in-stage absorber scheme, the modal routes' default. - Integrating it exactly over a step would give :func:`apply_split_step`; a - Runge-Kutta stage integrates it to the order of the method, so the two agree to - first order in the step and differ at second, which is what the comparison of the - two schemes measures. + Integrating it exactly over a step gives the ``"split_step"`` scheme's factor + ``exp(-alpha(t) h / 2)``; a Runge-Kutta stage integrates it to the order of the + method, so the two agree to first order in the step and differ at second, which is + what the comparison of the two schemes measures. Parameters ---------- @@ -1246,39 +1159,6 @@ def nonlinear_absorber_term( return -0.5 * temporal_rate * field -def apply_band_mask( - spectrum: Inexact[np.ndarray, "*batch n_omega"], - band_mask: Bool[np.ndarray, " n_omega"], -) -> Inexact[np.ndarray, "*batch n_omega"]: - """Zero a spectrum outside the active band. - - The hard part of the boundary, kept as a 0/1 multiply rather than made a rate: it is - idempotent, so applying it once per accepted step never accumulates, and it is the - definition of the band the equation is solved on rather than an absorber. - - Parameters - ---------- - spectrum : numpy.ndarray - Spectral amplitudes, shape ``(..., n_omega)``. - band_mask : numpy.ndarray - True where the physics lives, shape ``(n_omega,)``. - - Returns - ------- - numpy.ndarray - The masked spectrum, with the shape of ``spectrum``. - - Examples - -------- - >>> import numpy as np - >>> from solprop.boundaries import apply_band_mask - >>> mask = np.array([True, False, True]) - >>> apply_band_mask(np.array([1.0, 2.0, 3.0]), mask).tolist() - [1.0, 0.0, 3.0] - """ - return np.where(band_mask, spectrum, 0.0) - - def warn_walkoff( grid: TimeGrid, group_delay_span: float, @@ -1356,7 +1236,7 @@ def warn_walkoff( "strengthening the spectral collar too, raise boundary_N above " f"{grid.length / length * MIN_COLLAR_ATTENUATION / max(crossing, 1e-30):.3g}", SolpropWarning, - stacklevel=2, + skip_file_prefixes=PACKAGE_FILES, ) diff --git a/src/solprop/calibration/child.py b/src/solprop/calibration/child.py index 8c28a5c34..483bec721 100644 --- a/src/solprop/calibration/child.py +++ b/src/solprop/calibration/child.py @@ -206,7 +206,7 @@ def capture( share what is left of it, at most `limit` each, and the problems it leaves no time for are skipped and listed. - - ``effort``: ``"measure"`` or ``"patient"``. + - ``effort``: the FFTW planning effort, ``"measure"``. - ``limit``: FFTW's planning time limit per transform, in seconds. - ``budget``: the seconds the whole capture may take; none bounds it but `limit`. @@ -259,7 +259,7 @@ def capture( options=simulation.settings.execution_options(), ) try: - found = backend._diagnostics()["fft_planning"] # pyright: ignore[reportPrivateUsage] + found = backend._diagnostics()["fft_planning"] finally: backend.close() wisdom |= cast(dict[str, str], found["captured"]) diff --git a/src/solprop/calibration/command.py b/src/solprop/calibration/command.py index 2ad9a3513..6fedf5557 100644 --- a/src/solprop/calibration/command.py +++ b/src/solprop/calibration/command.py @@ -276,4 +276,4 @@ def run(arguments: argparse.Namespace) -> int: progress=lambda line: sys.stderr.write(f"solprop calibrate: {line}\n"), ) sys.stdout.write(report.describe()) - return 0 if report.status == "published" else 1 + return 0 if report.status in {"published", "kept"} else 1 diff --git a/src/solprop/calibration/controller.py b/src/solprop/calibration/controller.py index 6438866ad..1cc164977 100644 --- a/src/solprop/calibration/controller.py +++ b/src/solprop/calibration/controller.py @@ -162,8 +162,16 @@ class Level: "SOLPROP_NATIVE_WAIT", "SOLPROP_NATIVE_WAIT_REQUEST", "OMP_NUM_THREADS", + "SOLPROP_BLAS_THREADS", + "SOLPROP_OVERSUBSCRIBE", + "SOLPROP_NATIVE_BAND_TILES", + "SOLPROP_NATIVE_FORWARD_PACK", ) -"""The user's thread, wait and wisdom settings, which a child never inherits.""" +"""The user's thread, wait, wisdom and kernel-form settings: a child inherits none. + +A stored row records only the settings it chose (``fitted_under``), so a child timed +under an override of the user's would choose for a process that later runs without it. +""" @dataclass(frozen=True) @@ -194,11 +202,12 @@ def name(self) -> str: # numpydoc ignore=RT01 def environment(self, base: Mapping[str, str]) -> dict[str, str]: """Return a child's environment, which never calibrates. - `base` without the user's thread, wait and wisdom settings, with this - candidate's, and with FFT plans at estimate, so that no stage outside the - FFT stage spends its time planning (SEP 46 section 6.3). NumPy's and SciPy's - BLAS threads go idle at once (``solprop._process.child_environment``), - so that they do not spin on the CPUs being timed. + `base` without the user's thread, wait, wisdom and kernel-form settings, + with this candidate's, and with FFT plans at estimate, so that no stage + outside the FFT stage spends its time planning (SEP 46 section 6.3). NumPy's + and SciPy's BLAS threads go idle at once + (``solprop._process.child_environment``), so that they do not spin on the + CPUs being timed. Parameters ---------- @@ -232,9 +241,11 @@ class CalibrationReport: level : str The level run. status : str - ``"published"``, ``"inconclusive"`` (nothing published: a busy or noisy - machine, a failed child, or too little time), or ``"held"`` (another process - is calibrating this allocation). + ``"published"``, ``"kept"`` (nothing published: the store holds a row of + this allocation from a higher level, which a lower one does not replace; + `chosen` is that row's settings), ``"inconclusive"`` (nothing published: a + busy or noisy machine, a failed child, or too little time), or ``"held"`` + (another process is calibrating this allocation). fingerprint : str The machine and build's store key. allocation : Mapping[str, object] @@ -255,7 +266,7 @@ class CalibrationReport: """ level: str - status: Literal["published", "inconclusive", "held"] + status: Literal["published", "kept", "inconclusive", "held"] fingerprint: str allocation: Mapping[str, object] chosen: Mapping[str, object] = field(default_factory=dict[str, object]) @@ -1196,7 +1207,7 @@ def capture(effort: str, share: float) -> dict[str, object]: Each capture takes its share of the stage's time, so that the timing in the step still has the rest (SEP 46 section 6.7). - - ``effort``: ``"measure"`` or ``"patient"``. + - ``effort``: the FFTW planning effort, ``"measure"``. """ budget = max(0.0, plan.deadline.remaining() - until) * share return cast( @@ -1313,6 +1324,41 @@ def capture(effort: str, share: float) -> dict[str, object]: return {"efforts": chosen}, wisdom, evidence +def _classified( + generation: Generation | None, allocation: AllocationClass +) -> list[tuple[Row, bool]]: + """Return a generation's readable rows, each with whether it is `allocation`'s. + + A row whose allocation cannot be read is dropped. + """ + rows: list[tuple[Row, bool]] = [] + for row in () if generation is None else generation.rows: + try: + same = _native.allocation.AllocationClass.read(row.allocation) == allocation + except ValueError: + continue + rows.append((row, same)) + return rows + + +def _higher_row( + store: Store, fingerprint: str, allocation: AllocationClass, level: str +) -> Row | None: + """Return the store's row of `allocation` from a level above `level`, if any. + + A lower level does not replace it: a quick or standard run after a thorough one + would otherwise discard the better measurement. + """ + return next( + ( + row + for row, same in _classified(store.current(fingerprint), allocation) + if same and ORDER.get(row.level, -1) > ORDER[level] + ), + None, + ) + + def _publish( store: Store, fingerprint: str, @@ -1320,23 +1366,9 @@ def _publish( allocation: AllocationClass, wisdom: Mapping[str, str] | None = None, ) -> Path: - """Publish `row` in a new generation, keeping the other classes' rows. - - A row of the same class from a higher level is kept instead. - """ + """Publish `row` in a new generation, keeping the other classes' rows.""" previous: Generation | None = store.current(fingerprint) - rows: list[Row] = [] - for kept in () if previous is None else previous.rows: - try: - same = ( - _native.allocation.AllocationClass.read(kept.allocation) == allocation - ) - except ValueError: - continue - if not same: - rows.append(kept) - elif ORDER.get(kept.level, -1) > ORDER[row.level]: - row = kept + rows = [kept for kept, same in _classified(previous, allocation) if not same] rows.append(row) return store.publish( _native.store.Generation( @@ -1427,6 +1459,25 @@ def _calibrate_allocation( "grain": grain_evidence, "planning": planning_evidence, } + higher = _higher_row(plan.store, plan.digest, allocation, plan.level.name) + if higher is not None: + # Report what later runs apply, and publish nothing: neither this run's + # row nor its wisdom, which the kept row's plans were not chosen with. + return CalibrationReport( + level=plan.level.name, + status="kept", + fingerprint=plan.digest, + allocation=allocation.record(), + chosen={**higher.process, **higher.workspace}, + builtin=builtin | {name: table[name] for name in higher.workspace}, + evidence=evidence, + reason=( + f"the store keeps its {higher.level} row of this allocation, " + f"which a {plan.level.name} calibration does not replace; this " + f"run's result is discarded ({reason})" + ), + seconds=plan.deadline.elapsed(), + ) row = _native.store.Row( allocation=allocation.record(), level=plan.level.name, diff --git a/src/solprop/calibration/first_use.py b/src/solprop/calibration/first_use.py index 9103a5511..4a3af6874 100644 --- a/src/solprop/calibration/first_use.py +++ b/src/solprop/calibration/first_use.py @@ -145,15 +145,16 @@ def _calibrate( # No native backend, or one without the calibration's modules: selecting it # fails, or runs on its own table, on its own terms. return None - if not _allowed(environ): - return None from solprop import calibration # noqa: PLC0415 - imports this module's package from solprop.calibration.controller import LEVELS, calibrate # noqa: PLC0415 + found = calibration.choice(environ) if _allowed(environ) else None + if found is None or found.fingerprint is None: + # Not a process that measures, or its store could not be read (choice has + # warned): the built-in table runs. + return None machine = _native.topology.read_topology() allocation = _native.allocation.classify(machine, cpus, _process.cgroup_cpus()) - found = calibration.choice(environ) - assert found.fingerprint is not None # "auto" always fingerprints digest = found.fingerprint.digest store = _native.store.Store(calibration.store_directory(environ)) key = (digest, allocation.key(), level) diff --git a/src/solprop/calibration/refine.py b/src/solprop/calibration/refine.py index 6f99cad39..6c27e9026 100644 --- a/src/solprop/calibration/refine.py +++ b/src/solprop/calibration/refine.py @@ -319,11 +319,8 @@ def _refine( base = opened[0] try: sizing = cast(dict[str, object], base.backend.metadata()["execution_sizing"]) - key = native._profile.descriptor( # pyright: ignore[reportPrivateUsage] - # The store's key keeps the four-axis shape it has always been written - # with, so that refinements recorded before the batch axis left the - # problem (SEP 47 section 6.2) are found again. - shape=(1, *problem.shape), + key = native._profile.descriptor( + shape=problem.shape, grid_kind=problem.grid_kind, integrator=type(simulation.run_request().stepper.integrator).__name__, sizing=sizing, diff --git a/src/solprop/cli.py b/src/solprop/cli.py index dd3c15515..72f68c20e 100644 --- a/src/solprop/cli.py +++ b/src/solprop/cli.py @@ -7,7 +7,7 @@ Six commands, parsed by ``_parser`` and dispatched by :func:`main`: ``solprop run recipe.toml -o out.h5`` builds and runs a recipe, ``solprop resume out.h5`` continues it from the file and the recipe it records, ``solprop check`` -reports what stops it building, ``solprop export --python`` prints the equivalent +reports what stops it building, ``solprop export`` prints the equivalent script, ``solprop scan`` is ``python -m solprop.scan``, and ``solprop calibrate`` measures, shows, exports, imports or forgets the native backend's machine profile (:mod:`solprop.calibration.command`, SEP 46). A run maps SIGINT and SIGTERM onto its @@ -38,7 +38,8 @@ def _parser() -> argparse.ArgumentParser: """Return the command line's parser.""" parser = argparse.ArgumentParser( prog="solprop", - description="Run, check and export solprop recipes.", + description="Run, resume, check and export solprop recipes, run scans, and " + "calibrate the native backend.", ) commands = parser.add_subparsers(dest="command", required=True) run = commands.add_parser("run", help="build and run a recipe") @@ -75,7 +76,10 @@ def _parser() -> argparse.ArgumentParser: export = commands.add_parser("export", help="print a recipe as another form") export.add_argument("recipe", type=Path, help="the recipe file") export.add_argument( - "--python", action="store_true", required=True, help="print a Python script" + "--form", + choices=("python",), + default="python", + help="the form to print: a Python script (default: python)", ) export.add_argument( "-o", "--output", default=None, help="the file the script's run writes" @@ -229,8 +233,11 @@ def main(argv: Sequence[str] | None = None) -> int: Returns ------- int - The exit status: zero on success, one when a recipe has an error, two for a - refused recipe or arguments. + The exit status: zero on success; one when ``check`` finds an error in a + recipe, or a calibration is inconclusive; two for refused arguments or input + (a recipe or file that cannot be read or built) and for a run or scan that + fails with a solprop error; ``128`` plus the signal's number when a signal + stopped a run. Examples -------- @@ -239,13 +246,12 @@ def main(argv: Sequence[str] | None = None) -> int: 2 """ arguments = list(sys.argv[1:] if argv is None else argv) - if arguments and arguments[0] == "scan": - from solprop.scan import main as scan # noqa: PLC0415 - its own parser - - return scan(arguments[1:]) - args = _parser().parse_args(arguments) try: - return _command(args) + if arguments and arguments[0] == "scan": + from solprop.scan import main as scan # noqa: PLC0415 - its own parser + + return scan(arguments[1:]) + return _command(_parser().parse_args(arguments)) except (SolpropError, OSError) as error: sys.stderr.write(f"solprop: {error}\n") return 2 diff --git a/src/solprop/coupling/models.py b/src/solprop/coupling/models.py index 8bbd49873..a6e577a78 100644 --- a/src/solprop/coupling/models.py +++ b/src/solprop/coupling/models.py @@ -785,21 +785,20 @@ def _step_index( "holds a step-index fibre's HE1m (LP0m) modes only" ) raise CouplingError(msg) + # Not dimlimits: each channel bounds its cladding at its own radius. if ( mode.profile_wavelength != first.profile_wavelength - or mode._core != first._core - or mode._cladding != first._cladding - or mode.dimlimits(z)[2] != first.dimlimits(z)[2] + or not first.same_guide(mode) ): msg = "step-index modes of one scalar basis share one fibre and profile" raise CouplingError(msg) radius = float(first._radius(z)) - omega_p = 2.0 * math.pi * 299792458.0 / first.profile_wavelength + omega_p = 2.0 * math.pi * C / first.profile_wavelength core_p = float(real_index_and_slope(first._core, np.array([omega_p]))[0][0]) cladding_p = float( real_index_and_slope(first._cladding, np.array([omega_p]))[0][0] ) - v = omega_p / 299792458.0 * radius * math.sqrt(core_p**2 - cladding_p**2) + v = omega_p / C * radius * math.sqrt(core_p**2 - cladding_p**2) parameters = [_lp_parameter(v, mode.m) for mode in modes] live = grid.active_mask & (grid.omega > 0) core = np.zeros(grid.n_omega) diff --git a/src/solprop/coupling/outcouple.py b/src/solprop/coupling/outcouple.py index 8f3051fec..99e4f43e2 100644 --- a/src/solprop/coupling/outcouple.py +++ b/src/solprop/coupling/outcouple.py @@ -32,7 +32,7 @@ from solprop import fourier from solprop.constants import EPS0, C -from solprop.coupling.coupler import target_columns +from solprop.coupling.coupler import _channels, target_columns from solprop.coupling.plane import FieldPlane, PlaneBasis, PlaneMetric from solprop.coupling.port import METRIC_TOLERANCE from solprop.exceptions import CouplingError @@ -177,13 +177,7 @@ def apply(self, plane: FieldPlane) -> OutcoupleResult: ) raise CouplingError(msg) columns = target_columns(profiles, self.space) - jones = np.asarray(profiles.jones) - n_pol_in = plane.samples.shape[1] - if n_pol_in == 2: - jones_c = np.tile(np.eye(2), (profiles.n_modes, 1)) - mode_of = np.repeat(np.arange(profiles.n_modes), 2) - else: - jones_c, mode_of = jones, np.arange(profiles.n_modes) + jones_c, mode_of = _channels(profiles, plane.samples.shape[1]) n_pol = 2 if np.any(jones_c[:, 1] != 0.0) else 1 effective = profiles.effective_index[mode_of] factor = np.where( diff --git a/src/solprop/coupling/remap.py b/src/solprop/coupling/remap.py index 0ce65b3c4..ec8156aef 100644 --- a/src/solprop/coupling/remap.py +++ b/src/solprop/coupling/remap.py @@ -10,16 +10,18 @@ (:class:`~solprop.coupling.plane.PlaneReference`) so that the absolute spectrum is unchanged. It is a direct sum, evaluated only on target bins inside the source lattice's span (beyond it the sum returns aliases), with the identical lattice in an -unchanged reference copied. Light outside the target's band or window is removed only -on request (``crop_band``, ``truncate``) and its share reported in a -:class:`RegridReport`; a record with light at its edges is not extended without -``truncate``; nothing is renormalised. :data:`DEFAULT_TOLERANCE` is the share of a -record's norm below which a band or window counts as unoccupied. +unchanged reference copied inside the target's band and zeroed outside it, as the sum +leaves it. Light outside the target's band or window is removed only on request +(``crop_band``, ``truncate``) and its share reported in a :class:`RegridReport`; a +record with light at its edges is not extended without ``truncate``; nothing is +renormalised. :data:`DEFAULT_TOLERANCE` is the share of a record's norm below which a +band or window counts as unoccupied. The map and the normalisation it preserves are in ``docs/guide/workflows/coupling.md``, section "Moving a plane between grids". """ +import dataclasses import math from dataclasses import dataclass from typing import Literal @@ -29,6 +31,7 @@ from solprop.coupling.plane import ( FieldPlane, + NodalField, PlaneMetric, PlaneReference, lattice_identity, @@ -64,7 +67,8 @@ class RegridReport: Attributes ---------- method : {'copy', 'direct'} - Identity copy on an identical lattice and reference, or the direct sum. + Identity copy on an identical lattice and reference (the bins outside the + target's band zeroed), or the direct sum. source_lattice, target_lattice : str :func:`~solprop.coupling.plane.lattice_identity` of the two grids. shift : float @@ -169,6 +173,18 @@ def _within_band(grid: TimeGrid, omega: np.ndarray) -> np.ndarray: return (omega >= float(np.min(active))) & (omega <= float(np.max(active))) +def _band_limited(nodal: NodalField | None, in_band: np.ndarray) -> NodalField | None: + """Return nodal fields with the bins outside a band zeroed, as the samples are.""" + if nodal is None: + return None + magnetic = ( + None if nodal.magnetic is None else np.where(in_band, nodal.magnetic, 0.0) + ) + return dataclasses.replace( + nodal, electric=np.where(in_band, nodal.electric, 0.0), magnetic=magnetic + ) + + def regrid( plane: FieldPlane, grid: TimeGrid, @@ -283,10 +299,15 @@ def regrid( ) raise CouplingError(msg) + nodal = None if method == "auto" and same and shift == 0.0 and phase_shift == 0.0: - # The identity is exact: what lies outside the band, below the tolerance, is - # left for the receiving run's own hard mask, as the sum would zero it. - result = columns.copy() + # The identity is exact inside the target's band. The bins outside it are + # zeroed, as the direct sum leaves them, so that the samples agree with + # band_loss and energy_out: the band is not part of the lattice, so an + # identical lattice may still have a narrower band. + in_band = _within_band(grid, grid.omega) + result = np.where(in_band, columns, 0.0) + nodal = _band_limited(plane.nodal, in_band) report_method: Literal["copy", "direct"] = "copy" window_loss = edge_share = 0.0 else: @@ -324,7 +345,7 @@ def regrid( plane.exterior, plane.medium, plane.certificate, - plane.nodal if report_method == "copy" else None, + nodal, plane.provenance.then(history), ) energy_in = None if plane.metric.kind == "unknown" else plane.energy() diff --git a/src/solprop/driver/_pyroraptor.py b/src/solprop/driver/_pyroraptor.py index df195e366..cf254d16d 100644 --- a/src/solprop/driver/_pyroraptor.py +++ b/src/solprop/driver/_pyroraptor.py @@ -96,8 +96,16 @@ class _Provider(Protocol): def _load_provider() -> _Provider: """Load the optional package, in the worker only.""" + # Pyroraptor's package declares Python 3.14 alone (requires-python >=3.14,<3.15), + # though solprop's own floor admits later interpreters: another one is refused by + # name here, before its native extension is imported. if sys.version_info[:2] != (3, 14): - raise BackendError("the pinned TDSE provider requires Python 3.14") + major, minor = sys.version_info[:2] + msg = ( + "the TDSE provider, Pyroraptor, supports Python 3.14 only, and this is " + f"Python {major}.{minor}: run a TDSE response under Python 3.14" + ) + raise BackendError(msg) try: return cast("_Provider", importlib.import_module("pyroraptor")) except (ImportError, OSError) as error: diff --git a/src/solprop/driver/_scan_model.py b/src/solprop/driver/_scan_model.py index 7a2362efe..2fcbf5fdf 100644 --- a/src/solprop/driver/_scan_model.py +++ b/src/solprop/driver/_scan_model.py @@ -70,6 +70,17 @@ def name_seed(name: str, index: int) -> int: return int(sequence.generate_state(1, dtype=np.uint64)[0]) +def _axis_summary(values: np.ndarray) -> str: + """Describe an axis by its length and end values, of any kind and length.""" + if values.size == 0: + return "no values" + if values.dtype.kind in "iuf": + first, last = f"{values[0]:.6g}", f"{values[-1]:.6g}" + else: + first, last = (repr(value) for value in values[[0, -1]].tolist()) + return f"{values.size} values, {first} to {last}" + + class Scan(Displayed): """Declare an ordered Cartesian product of one-dimensional variable arrays. @@ -136,8 +147,7 @@ def _describe(self) -> tuple[str, list[tuple[str, object]]]: - Returns: the title and ``(key, value)`` rows. """ rows: list[tuple[str, object]] = [ - (name, f"{values.size} values, {values[0]:.6g} to {values[-1]:.6g}") - for name, values in self._variables.items() + (name, _axis_summary(values)) for name, values in self._variables.items() ] rows.append(("base seed", self.base_seed)) if self._indices is not None: diff --git a/src/solprop/driver/_scan_run.py b/src/solprop/driver/_scan_run.py index 5b3bd048b..782bc89b1 100644 --- a/src/solprop/driver/_scan_run.py +++ b/src/solprop/driver/_scan_run.py @@ -810,19 +810,20 @@ def _retained(simulation: Simulation, capture: _Capture) -> Simulation: return retained -def _jobs( # noqa: PLR0917 - called positionally +def _jobs( scan: Scan, writer: ScanWriter, retry: bool, - age: float, stop: StopFlag | None, claims: dict[int, tuple[str, float]], ) -> Iterator[_Job]: """Claim eligible points lazily as dispatch capacity becomes available. - - ``age``: positive abandonment interval, s. + A ``running`` point is claimed whatever its age: the writer holds the file's lock + for its whole session, so that mark was left by a controller that has gone. + - ``claims``: filled with each claimed point's state and update time before the - claim, so that a stopped point is given back as it was (`_release`). + claim, so that a point not committed is given back as it was (`_release`). """ for point in scan.points(): if stop is not None and stop.is_set(): @@ -830,8 +831,6 @@ def _jobs( # noqa: PLR0917 - called positionally state, digest, updated = writer.state(point.index) if state == "failed" and not retry: continue - if state == "running" and time.time() - updated < age: - continue if state != "done": claims[point.index] = state, updated writer.mark_running(point.index, time.time()) @@ -839,10 +838,10 @@ def _jobs( # noqa: PLR0917 - called positionally def _release(writer: ScanWriter, index: int, claim: tuple[str, float]) -> None: - """Give a stopped point back as it was before this scan claimed it. + """Give a point not committed back as it was before this scan claimed it. - A stopped point is not committed, so a rerun computes it again: left ``running``, - a rerun would skip it for ``stale_age``. + A stopped point, or one still claimed when the scan raises, is not committed, so + the file shows it as it was and a rerun computes it again. - ``claim``: its state and update time before the claim. """ @@ -852,6 +851,44 @@ def _release(writer: ScanWriter, index: int, claim: tuple[str, float]) -> None: writer.file.flush() +def _release_uncommitted( + writer: ScanWriter | None, claims: Mapping[int, tuple[str, float]] +) -> None: + """Give back every point still claimed when the scan ends, whatever ended it. + + - ``writer``: local controller writer, or None for a durable queue, whose claims + are leases. + """ + if writer is not None: + for index, claim in claims.items(): + _release(writer, index, claim) + + +def _end_execution( + executor: Executor, + build: Callable[[ScanPoint], Simulation], + writer: ScanWriter | None, + output: Path | str, + claims: Mapping[int, tuple[str, float]], + *, + failing: bool, +) -> None: + """Give back the uncommitted claims, then record provenance and close the writer. + + The writer, and the lock it holds, are closed whatever the release did. A scan + already failing, most likely on the same file, reports its own error rather than + the release's, which follows from it and is logged. + """ + try: + _release_uncommitted(writer, claims) + except Exception: + if not failing: + raise + logger.exception("the failing scan could not give back its claimed points") + finally: + _finish_execution(executor, build, writer, output) + + def execute_scan( scan: Scan, build: Callable[[ScanPoint], Simulation], @@ -863,7 +900,6 @@ def execute_scan( field_planes: Sequence[int], stats: str | Sequence[str], retry_failed: bool, - stale_age: float, progress: ProgressChoice | ScanReporter, stop: StopFlag | None = None, recipe: RecipeRecord | None = None, @@ -871,9 +907,8 @@ def execute_scan( """Validate, dispatch and commit a scan through one writer. - ``executor``: execution policy; None selects the CLI policy or Local. - - ``stale_age``: positive abandonment interval, s. """ - _validate_options(fields, field_planes, stats, stale_age, reductions) + _validate_options(fields, field_planes, stats, reductions) if progress not in _PROGRESS_CHOICES and not isinstance( progress, ScanReporter ): # pragma: no cover - refused by the annotation where it is checked @@ -919,17 +954,22 @@ def execute_scan( writer = None claims: dict[int, tuple[str, float]] = {} if isinstance(executor, (Queue, Slurm)): - executor.prepare(ScanRequest(scan, settings, output, work, retry_failed)) + executor.prepare( + ScanRequest(scan, settings, output, work, retry_failed, recipe) + ) jobs = (_Job(point) for point in scan.points()) else: writer = ScanWriter(output, scan, settings) writer.record_recipe(recipe) - jobs = _jobs(scan, writer, retry_failed, stale_age, stop, claims) + jobs = _jobs(scan, writer, retry_failed, stop, claims) counts = dict.fromkeys(("finished", "stopped"), 0) + completed = False try: events.reporter.scan_started(len(scan)) for result in executor.run(jobs, work): - _collect(result, writer, claims.pop(result.index, None)) + _collect(result, writer, claims.get(result.index)) + # Only once committed: a point whose commit raised is given back below. + claims.pop(result.index, None) counts["stopped" if result.status == "stopped" else "finished"] += 1 events.finish(result) if stop is not None and stop.is_set(): @@ -942,11 +982,12 @@ def execute_scan( counts["stopped"], ) events.reporter.scan_finished() + completed = True finally: work.close() if display is not None: display.close() - _finish_execution(executor, build, writer, output) + _end_execution(executor, build, writer, output, claims, failing=not completed) return ScanOutput(output) @@ -1009,8 +1050,10 @@ def _finish_execution( policy["script_hash"] = hashlib.sha256(Path(source).read_bytes()).hexdigest() policy["script"] = source if writer is not None: - writer.record_execution(type(executor).__qualname__, policy) - writer.close() + try: + writer.record_execution(type(executor).__qualname__, policy) + finally: + writer.close() elif isinstance(executor, Queue) and executor.path is not None: collect(executor.path, output) elif isinstance(executor, Slurm) and executor.queue_path is not None: @@ -1021,18 +1064,12 @@ def _validate_options( fields: str, field_planes: Sequence[int], stats: str | Sequence[str], - stale_age: float, reductions: Sequence[Reduction], ) -> None: - """Reject ambiguous retention controls before opening the output. - - - ``stale_age``: positive abandonment interval, s. - """ + """Reject ambiguous retention controls before opening the output.""" refusal = field_retention_refusal(fields, field_planes) if refusal is not None: raise DriverError(refusal) - if not math.isfinite(stale_age) or stale_age <= 0: - raise DriverError("stale_age must be positive and finite") if isinstance(stats, str) and stats not in ("all", "none"): raise DriverError("stats must be all, none or a sequence of names") names = [r.name for r in reductions] diff --git a/src/solprop/driver/_source_worker.py b/src/solprop/driver/_source_worker.py index e3e0f9378..cc242580e 100644 --- a/src/solprop/driver/_source_worker.py +++ b/src/solprop/driver/_source_worker.py @@ -36,6 +36,7 @@ import weakref from collections import deque from collections.abc import Callable, Iterator, Mapping, Sequence +from pathlib import Path from types import SimpleNamespace from typing import IO, Any, Protocol, cast, runtime_checkable @@ -352,6 +353,26 @@ def write_message( # ---------------------------------------------------------------------- the parent +def _import_path() -> list[str]: + """Return this process's import path, less the directory a script put first. + + The worker starts with ``-P`` so that a directory holding a module named like a + standard-library one cannot shadow it there; the directory of the script this + process runs, which Python puts first on the path, would undo that. + """ + script = Path(sys.argv[0] if sys.argv else "") + path = sys.path + if ( + not sys.flags.safe_path + and path + and path[0] + and script.is_file() + and Path(path[0]).resolve() == script.resolve().parent + ): + path = path[1:] + return [entry for entry in path if entry] + + def worker_environment( environ: Mapping[str, str], explicit: Mapping[str, str] ) -> dict[str, str]: @@ -359,11 +380,11 @@ def worker_environment( The OpenMP wait variables solprop-native set for itself (ADR-071), which its marker names, are removed so that the provider's runtime keeps its own defaults; a user's - own settings pass through. The worker imports from this process's import path. - ``explicit`` (the thread count, the device) wins. + own settings pass through. The worker imports from this process's import path + (:func:`_import_path`). ``explicit`` (the thread count, the device) wins. """ environment = child_environment(environ) - environment["PYTHONPATH"] = os.pathsep.join(entry for entry in sys.path if entry) + environment["PYTHONPATH"] = os.pathsep.join(_import_path()) settings = _NATIVE_WAIT_SETTINGS.get(environment.get(_NATIVE_WAIT_MARKER, ""), {}) if settings: for name, value in settings.items(): diff --git a/src/solprop/driver/executors/__init__.py b/src/solprop/driver/executors/__init__.py index 7607ee9d0..2fadbf36e 100644 --- a/src/solprop/driver/executors/__init__.py +++ b/src/solprop/driver/executors/__init__.py @@ -27,7 +27,16 @@ @runtime_checkable class Executor(Protocol): - """Run point work while preserving the identity carried by every result.""" + """Run point work while preserving the identity carried by every result. + + :func:`~solprop.driver.scan.run_scan` needs only :meth:`run`, and calls a + ``validate(work)`` method before it writes anything where an executor has one. The + rest of what it does is decided by the four executors' classes, a closed set: an + executor of any other class runs as ``Local`` and ``Pool`` do, its points' results + written by the calling process, without the backend ``Local`` keeps between + points, or the stop refusal, durable preparation and collection of ``Queue`` and + ``Slurm``. + """ def run[T, R](self, points: Iterable[T], work: Callable[[T], R]) -> Iterator[R]: """Execute work for each point. diff --git a/src/solprop/driver/executors/_request.py b/src/solprop/driver/executors/_request.py index c24b80ea9..20aee1edd 100644 --- a/src/solprop/driver/executors/_request.py +++ b/src/solprop/driver/executors/_request.py @@ -9,6 +9,7 @@ from pathlib import Path from solprop.driver._scan_model import Scan +from solprop.output.records import RecipeRecord @dataclass(frozen=True) @@ -27,6 +28,9 @@ class ScanRequest: Pickleable point worker with a backend memory probe. retry_failed : bool Whether previously failed points may be claimed again. + recipe : solprop.output.records.RecipeRecord or None + The recipe the scan was built from, which the collected file records once; + ``None`` for a scan from a script. """ scan: Scan @@ -34,3 +38,4 @@ class ScanRequest: output: Path | str work: Callable retry_failed: bool = False + recipe: RecipeRecord | None = None diff --git a/src/solprop/driver/executors/pool.py b/src/solprop/driver/executors/pool.py index 69d74e22a..b0ad1497e 100644 --- a/src/solprop/driver/executors/pool.py +++ b/src/solprop/driver/executors/pool.py @@ -40,7 +40,12 @@ spawn_environment, thread_budget, ) -from solprop.exceptions import DriverError, ExecutorError, StopRequested +from solprop.exceptions import ( + DriverError, + ExecutorError, + RunTerminated, + StopRequested, +) from solprop.log import PlaneSummary, ProgressReporter, StopFlag __all__ = ["ControlledWork", "MemoryBudget", "PlaneScalars", "Pool", "peak_rss"] @@ -56,16 +61,22 @@ # The worker pipe's messages. Controller to worker: ``("run", point)`` or # ``("probe", point)``, the ``STOP`` string while a point runs, and ``None`` to exit. -# Worker to controller: ``(ok, value)`` once per command, and while a watched point runs -# ``(PROGRESS, call, args)``, one of that run's reporter calls (`_WorkerReporter`). +# Worker to controller: ``(ok, value)`` once per command, ``(INTERRUPTED, text)`` in its +# place when Ctrl-C, SIGTERM or a stop flag ended the command, and while a watched point +# runs ``(PROGRESS, call, args)``, one of that run's reporter calls (`_WorkerReporter`). STOP = "stop" PROGRESS = "progress" +INTERRUPTED = "interrupted" -class _WorkerError(DriverError): +class _WorkerError(ExecutorError): """Report an abnormal child exit separately from an invalid resource budget.""" +class _WorkerInterruptedError(_WorkerError): + """Report a worker whose command was interrupted, which is a stop, not a crash.""" + + @runtime_checkable class ControlledWork(Protocol): """Point work a pool can stop and watch (SEP 41, S4 and S17). @@ -456,6 +467,10 @@ def _serve( else: value = work(point) connection.send((True, value)) + except (KeyboardInterrupt, RunTerminated, StopRequested) as error: + # Ctrl-C reaches every worker of a terminal's scan; the run has written its + # state, and the point is stopped rather than failed. + connection.send((INTERRUPTED, f"{type(error).__name__}: {error}")) except BaseException: connection.send((False, traceback.format_exc())) finally: @@ -505,6 +520,8 @@ def _receive(connection: _Pipe) -> object: if len(message) == 3 and isinstance(message[0], str) and message[0] == PROGRESS: return _Progress(message[1], message[2]) success, value = message + if isinstance(success, str) and success == INTERRUPTED: + raise _WorkerInterruptedError(f"scan worker was interrupted: {value}") if not success: raise _WorkerError(f"scan worker failed:\n{value}") return value @@ -521,6 +538,19 @@ def _failed_work(work: Callable, point: object, error: _WorkerError) -> object: return failed(point, str(error)) +def _interrupted_work( + work: Callable, point: object, error: _WorkerInterruptedError +) -> object: + """Let a scan give back a point its worker was interrupted in; others raise. + + - Returns: the work's stopped result, if it has a ``stopped`` hook. + """ + stopped = getattr(work, "stopped", None) + if not callable(stopped): + raise error + return stopped(point) + + def _stop(process: BaseProcess, connection: _Pipe) -> None: """Close a worker and release its pipe even after a failure.""" try: @@ -603,6 +633,9 @@ def run[T, R](self, points: Iterable[T], work: Callable[[T], R]) -> Iterator[R]: the abrupt ``terminate`` of a worker that does not exit stays the last resort. While a watched point runs, its worker sends the run's reporter calls, which the pool hands to :meth:`ControlledWork.relay`. + A point whose worker is interrupted (Ctrl-C, which a terminal sends to every + worker, SIGTERM, or another stop flag) is handed to the work's ``stopped`` + hook rather than its ``failure`` hook: a stop, not a crash. Parameters ---------- @@ -619,7 +652,11 @@ def run[T, R](self, points: Iterable[T], work: Callable[[T], R]) -> Iterator[R]: Raises ------ DriverError - If resource admission fails or a worker exits abnormally. + If resource admission fails. + ExecutorError + If a worker exits abnormally or fails, and the work has no ``failure`` + hook to record it; or is interrupted, and the work has no ``stopped`` + hook. """ self.validate(work) iterator = iter(points) @@ -631,6 +668,8 @@ def run[T, R](self, points: Iterable[T], work: Callable[[T], R]) -> Iterator[R]: try: available, count = self._admit(work, first) break + except _WorkerInterruptedError as error: + yield cast(R, _interrupted_work(work, first, error)) except _WorkerError as error: yield cast(R, _failed_work(work, first, error)) session = _Session(self, work) @@ -719,6 +758,10 @@ def drain(self) -> Iterator[object]: crashed = False try: received = _receive(connection) + except _WorkerInterruptedError as error: + # Its worker has left its loop, so it is replaced as after a crash. + received = _interrupted_work(self.work, point, error) + crashed = True except _WorkerError as error: received = _failed_work(self.work, point, error) crashed = True diff --git a/src/solprop/driver/executors/queue.py b/src/solprop/driver/executors/queue.py index 5f95d2806..55f79fa06 100644 --- a/src/solprop/driver/executors/queue.py +++ b/src/solprop/driver/executors/queue.py @@ -22,6 +22,7 @@ import inspect import json import math +import os import pickle import sys import threading @@ -51,7 +52,8 @@ from solprop.driver.executors._request import ScanRequest from solprop.driver.executors.pool import Pool from solprop.exceptions import DriverError, ExecutorError, OutputError -from solprop.output.hdf5 import _dataset, _group +from solprop.output.hdf5 import _dataset, _group, read_recipe, write_recipe +from solprop.output.records import RecipeRecord from solprop.output.scan import PointResult, ScanWriter, _json from solprop.output.scan_artifacts import artifact_digest, read_artifact, write_artifact from solprop.output.serialisation import deserialise @@ -59,6 +61,8 @@ __all__ = ["Queue", "collect"] +_RECIPE = "recipe.h5" + def _point(job: object) -> ScanPoint: """Require a work description carrying a globally indexed ScanPoint.""" @@ -73,6 +77,25 @@ def _point_id(point: ScanPoint) -> str: return text_digest(_json(point)) +def _keep_recipe(path: Path, record: RecipeRecord | None) -> None: + """Keep the scan's recipe in the queue, once, for :func:`collect` to record. + + Outside the manifest and its scan identity, as a scan file keeps it outside the + run records: a recipe is provenance, written once and never rewritten. + """ + target = path / _RECIPE + if record is None or target.exists(): + return + staged = path / f".{uuid.uuid4().hex}{_RECIPE}" + with h5py.File(staged, "x") as file: + write_recipe(file, record) + # Windows commits a file only through a handle open for writing. + with staged.open("r+b") as stream: + os.fsync(stream.fileno()) + staged.replace(target) + sync_directory(path) + + def _filename(manifest: Mapping, index: int) -> str: """Keep artifact names independent of task and chunk ordering. @@ -341,6 +364,7 @@ def prepare(self, request: ScanRequest) -> None: ) if not saved.exists(): atomic_json(saved, manifest) + _keep_recipe(self.path, request.recipe) if ( not (self.path / "queue.json").exists() and not (self.path / ".done").exists() @@ -499,6 +523,10 @@ def collect(path: Path | str, output: Path | str) -> ScanOutput: ) changed = True changed |= _collect_points(path, manifest, record, writer) + if (path / _RECIPE).exists() and "recipe" not in writer.file: + with h5py.File(path / _RECIPE, "r") as file: + writer.record_recipe(read_recipe(file)) + changed = True seen = set( json.loads(str(writer.file.attrs.get("collected_controllers", "[]"))) ) diff --git a/src/solprop/driver/executors/slurm.py b/src/solprop/driver/executors/slurm.py index 433b297e0..935e560e5 100644 --- a/src/solprop/driver/executors/slurm.py +++ b/src/solprop/driver/executors/slurm.py @@ -14,6 +14,7 @@ """ import hashlib +import math import os import re import shlex @@ -84,6 +85,9 @@ class Slurm: Whether every point uses a fresh process. workdir : pathlib.Path, str or None Shared working directory; defaults to the submitting process's directory. + stale_age : float + Positive remote lease duration of the tasks' shared queue, s, as for + :class:`~solprop.driver.executors.queue.Queue`. job_id : str or None Scheduler identifier after a successful submission. """ @@ -102,6 +106,7 @@ class Slurm: threads: int = 1 fresh: bool = False workdir: Path | str | None = None + stale_age: float = 600.0 job_id: str | None = field(init=False, default=None) _queue: Queue | None = field(init=False, default=None, repr=False) @@ -119,6 +124,8 @@ def __post_init__(self) -> None: ) if self.workers is not None and self.workers < 1: raise DriverError("Slurm workers must be positive") + if not math.isfinite(self.stale_age) or self.stale_age <= 0: + raise DriverError("Slurm stale_age must be positive and finite") _memory_bytes(self.mem) for value in (str(self.script), self.time, self.partition, self.gres): if value is not None and any(char in value for char in "\r\n\x00"): @@ -168,7 +175,9 @@ def prepare(self, request: ScanRequest) -> None: threads=self.threads, fresh=self.fresh, ) - self._queue = Queue(self.queue_path, pool=pool, chunk=chunk) + self._queue = Queue( + self.queue_path, stale_age=self.stale_age, pool=pool, chunk=chunk + ) self._queue.prepare(request) def render(self) -> str: @@ -255,6 +264,8 @@ def render(self) -> str: str(self.threads), "--memory-limit", str(_memory_bytes(self.mem) // count), + "--stale-age", + str(self.stale_age), ] workers = self.workers or (1 if self._has_gpu else None) if workers is not None: @@ -295,7 +306,7 @@ def submit(self, destination: Path | str | None = None) -> str: Raises ------ - DriverError + ExecutorError If sbatch is unavailable or refuses the submission. """ queue = ( diff --git a/src/solprop/driver/inputs.py b/src/solprop/driver/inputs.py index 886f2423f..69be7f8b6 100644 --- a/src/solprop/driver/inputs.py +++ b/src/solprop/driver/inputs.py @@ -70,6 +70,7 @@ from solprop.translate.linop import power_weight_at from solprop.translate.masks import noise_spectrum from solprop.translate.problem import ( + Flags, PropagationProblem, _held_block, _held_state, @@ -472,8 +473,8 @@ def _with_noise( """Return `problem` carrying `noise`, every other leaf shared by identity. A realisation reaches a translation only through the initial record and the - ``has_noise`` flag; what else consults it is a refusal keyed on the model, and a - replacement that changes the model is checked by its caller. + ``has_noise`` flag, re-derived here; what else consults it is a refusal keyed on the + model, and a replacement that changes the model is checked by its caller. - ``noise``: the realisation in true sqrt(W) on a modal route, or ``None`` for no noise. @@ -485,15 +486,15 @@ def _with_noise( noise0 = power_amplitude( noise0, power_weight_at(problem, problem.initial.z), inverse=True ) - return dataclasses.replace( - problem, - initial=dataclasses.replace( - problem.initial, - noise0=noise0, - noise_model="none" if noise is None else noise.model, - ), - flags=dataclasses.replace(problem.flags, has_noise=noise0 is not None), + initial = dataclasses.replace( + problem.initial, + noise0=noise0, + noise_model="none" if noise is None else noise.model, + ) + flags = Flags.from_content( + problem.shape, problem.linear, problem.transform, problem.responses, initial ) + return dataclasses.replace(problem, initial=initial, flags=flags) def _redrawable( diff --git a/src/solprop/driver/interface.py b/src/solprop/driver/interface.py index 2321ab995..59cda0d3b 100644 --- a/src/solprop/driver/interface.py +++ b/src/solprop/driver/interface.py @@ -29,13 +29,17 @@ from solprop.coupling.models import CouplingModel from solprop.driver.defaults import DEFAULT_ATOL, WAVEGUIDE_ATOL from solprop.driver.inputs import ModalLaunch -from solprop.driver.resume import _ResumeChoice from solprop.driver.settings import NoiseSetting, SimulationSettings from solprop.driver.simulation import Simulation from solprop.gasflow import VacuumEnd from solprop.grid import FreeGrid, RadialGrid, TimeGrid from solprop.linear import Frame -from solprop.log import DEFAULT_PROGRESS_PERIOD, ProgressChoice, ProgressReporter +from solprop.log import ( + DEFAULT_PROGRESS_PERIOD, + ProgressChoice, + ProgressReporter, + ResumeChoice, +) from solprop.modes.antiresonant import TubeLattice from solprop.modes.capillary import GlassIndex, MarcatiliModel from solprop.modes.fill import LossFunction @@ -88,31 +92,6 @@ ) """The keywords of a ``prop_*`` function that are :meth:`Simulation.run`'s.""" -_RUN_CONTROLS_DOC: Final = """\ -output : solprop.output.store.Output or pathlib.Path or str or None, optional - Where the run goes: a handler, a path to stream an HDF5 file to, or ``None`` for - a :class:`solprop.output.memory.MemoryOutput`. -snapshots : solprop.output.SnapshotController or None, optional - Immutable local checkpoints at committed accepted steps; requires HDF5, - all fields and non-interpolated observations. -resume : bool or {'interpolated'}, optional - Continue the file at `output` when its record and this run's have one - configuration hash; otherwise it is refused, naming what changed. Only a - path can be resumed. ``"interpolated"`` also continues from a plane - interpolated inside a step - (:meth:`solprop.driver.simulation.Simulation.run`). -progress : ProgressReporter, {'auto', 'bar', 'log', 'none'} or None, optional - Where progress goes; ``None`` takes the process default: a bar on a terminal - or in a notebook, log lines otherwise (:func:`solprop.driver.run.run_problem`). -progress_period : float, optional - Seconds between the default reporter's periodic lines, s; ``0`` leaves only the - plane and closing lines. Ignored when `progress` is given. -tdse_archive : solprop.output.TDSEArchive or None, optional - Archive every raw provider evaluation of `tdse` in a separate HDF5 file - (:meth:`~solprop.driver.simulation.Simulation.run`); refused without `tdse`. -""" -"""The run controls' parameter entries, in :data:`_RUN_CONTROLS` order.""" - _SECTION = re.compile(r"^(\w[\w ]*)\n-{3,}\n", re.MULTILINE) """A numpydoc section header: its title, then its underline.""" @@ -129,8 +108,12 @@ def _parameters(doc: str) -> str: def _run_controls(names: Sequence[str]) -> str: - """Return the entries of the run controls among `names`, in their order.""" - entries = re.split(r"\n(?=\S)", _RUN_CONTROLS_DOC.strip("\n")) + """Return :meth:`Simulation.run`'s entries for the run controls among `names`. + + In the order of `names`; each control is documented once, on the method. + """ + run_doc = inspect.getdoc(Simulation.run) or "" + entries = re.split(r"\n(?=\S)", _parameters(run_doc).strip("\n")) by_name = {entry.split(" :", 1)[0]: entry for entry in entries} return "".join(by_name[name] + "\n" for name in names if name in by_name) @@ -204,7 +187,7 @@ def prop_free( # numpydoc ignore=PR01 spatial_absorber: SpatialAbsorber | Literal[False] | None = None, output: Output | Path | str | None = None, snapshots: SnapshotController | None = None, - resume: _ResumeChoice = False, + resume: ResumeChoice = False, progress: ProgressReporter | ProgressChoice | None = None, progress_period: float = DEFAULT_PROGRESS_PERIOD, ) -> Output: @@ -243,7 +226,7 @@ def prop_planar( # numpydoc ignore=PR01 spatial_absorber: SpatialAbsorber | Literal[False] | None = None, output: Output | Path | str | None = None, snapshots: SnapshotController | None = None, - resume: _ResumeChoice = False, + resume: ResumeChoice = False, progress: ProgressReporter | ProgressChoice | None = None, progress_period: float = DEFAULT_PROGRESS_PERIOD, ) -> Output: @@ -313,7 +296,7 @@ def prop_gnlse( # numpydoc ignore=PR01 materials: MaterialSelection | None = None, output: Output | Path | str | None = None, snapshots: SnapshotController | None = None, - resume: _ResumeChoice = False, + resume: ResumeChoice = False, progress: ProgressReporter | ProgressChoice | None = None, progress_period: float = DEFAULT_PROGRESS_PERIOD, ) -> Output: @@ -446,7 +429,7 @@ def prop_capillary( # numpydoc ignore=PR01 tdse_execution: TDSEExecution | None = None, output: Output | Path | str | None = None, snapshots: SnapshotController | None = None, - resume: _ResumeChoice = False, + resume: ResumeChoice = False, progress: ProgressReporter | ProgressChoice | None = None, progress_period: float = DEFAULT_PROGRESS_PERIOD, tdse_archive: TDSEArchive | None = None, @@ -533,8 +516,6 @@ def prop_waveguide( # numpydoc ignore=PR01 incident: SpatialPulse | None = None, coupling: CouplingModel | None = None, kerr_form: KerrForm = "real", - observable_rtol: float | None = None, - observable_atol: float | None = None, pressure_floor: float | None = None, vacuum_end: VacuumEnd | None = None, wavelength: float, @@ -586,7 +567,7 @@ def prop_waveguide( # numpydoc ignore=PR01 materials: MaterialSelection | None = None, output: Output | Path | str | None = None, snapshots: SnapshotController | None = None, - resume: _ResumeChoice = False, + resume: ResumeChoice = False, progress: ProgressReporter | ProgressChoice | None = None, progress_period: float = DEFAULT_PROGRESS_PERIOD, ) -> Output: diff --git a/src/solprop/driver/material_output.py b/src/solprop/driver/material_output.py index 62bc31a3d..a2bcec7c6 100644 --- a/src/solprop/driver/material_output.py +++ b/src/solprop/driver/material_output.py @@ -470,7 +470,6 @@ def _policies( for one in raman if (assembly := one.assembly) is not None ], - "energy_loss": None if selection is None else selection.energy_loss, } diff --git a/src/solprop/driver/metadata.py b/src/solprop/driver/metadata.py index 72cd82f4e..41d42e5d6 100644 --- a/src/solprop/driver/metadata.py +++ b/src/solprop/driver/metadata.py @@ -47,7 +47,6 @@ from solprop.translate.plasma_integration import integration_record from solprop.translate.plasma_source import plasma_source_record from solprop.translate.problem import PropagationProblem -from solprop.translate.responses import declares_harmonic_carrier from solprop.translate.routes import flux_of, tdse_descriptor, transverse_of from solprop.translate.run_request import RunRequest @@ -219,8 +218,8 @@ def metadata_for( if measure != "area": # A run uniform in y reports its powers per metre of y; processing and # plotting label them from this key (RunMetadata.transverse_measure). It is - # written only where it is not the default, so every area run keeps the - # digest it was stamped with. + # written only where it is not the default, "area", which a reader assumes + # where it is absent, so the record stays short. record["transverse_measure"] = measure if problem.responses.envelope_plasma is not None: record["statistic_rate_conventions"] = { @@ -320,27 +319,6 @@ def metadata_for( ) -def _frame_follows_the_electronic_rule( - responses: Sequence[object], grid: TimeGrid -) -> bool: - """Return whether a run's co-moving frame changed when it stopped reading Raman. - - Before the frame followed - :func:`solprop.translate.responses.declares_harmonic_carrier`, any response's - ``thg`` kept ``beta_0`` on an envelope grid. The two rules disagree exactly when a - response other than the electronic ones declares ``thg=True`` and no electronic one - does. - - - Returns: True when the earlier rule would have kept ``beta_0`` and this one - removes it. - """ - return ( - grid.kind == "envelope" - and any(bool(getattr(one, "thg", False)) for one in responses) - and not declares_harmonic_carrier(responses, grid) - ) - - def _plane_reference_record( problem: PropagationProblem, grid: TimeGrid, diff --git a/src/solprop/driver/mixtures.py b/src/solprop/driver/mixtures.py index 4440e7e3d..303cb26e1 100644 --- a/src/solprop/driver/mixtures.py +++ b/src/solprop/driver/mixtures.py @@ -170,8 +170,8 @@ def capillary_fill( material : Gas, str, Mapping or Mixture A built-in gas, mole fractions or a complete mixture declaration. pressure : float, sequence, ZProfile or None - Total pressure in bar; None uses one bar for a built-in gas or fractions. - A supplied Mixture requires None because it already carries its paths. + Total pressure in bar, required for a built-in gas or fractions. A supplied + Mixture requires None because it already carries its paths. length : float Capillary length in m, needed by endpoint pressure pairs. temperature : float, ZProfile or None @@ -209,8 +209,8 @@ def capillary_fill( Raises ------ DriverError - If pressure, temperature or optical arguments conflict, or a label is - unknown. + If a built-in gas or fractions come without a pressure, pressure, + temperature or optical arguments conflict, or a label is unknown. """ if isinstance(material, Mixture): if temperature is not None and not _same_temperature( @@ -247,6 +247,7 @@ def capillary_fill( ) mixture = material else: + pressure = _gas_pressure(material, pressure) temperature = ROOM_TEMPERATURE if temperature is None else temperature # The bore shapes only a fill built here from end pressures; a supplied # profile is used as given, and the constructor warns if it is boreless. @@ -279,7 +280,7 @@ def capillary_fill( rule="mixture-carries-susceptibility", ) mixture = Mixture.air( - 1.0 if pressure is None else pressure, + pressure, temperature=temperature, argon=False, length=length, @@ -296,7 +297,7 @@ def capillary_fill( fractions = {selected: 1.0} mixture = Mixture.fill( fractions, - 1.0 if pressure is None else pressure, + pressure, temperature=temperature, length=length, floor=floor, @@ -306,6 +307,19 @@ def capillary_fill( return _with_initial_populations(mixture, preionisation) +def _gas_pressure( + material: Gas | str | Mapping[str, float], pressure: Pressure | None +) -> Pressure: + """Return the pressure of a fill built from a gas or fractions, which needs one.""" + if pressure is None: + msg = ( + f"a gas fill needs its pressure: pass pressure= in bar beside " + f"gas={material!r}, or a Mixture that carries its own paths" + ) + raise DriverError(msg, parameter="pressure") + return pressure + + def _with_initial_populations( mixture: Mixture, preionisation: float | ZProfile | Mapping[str, float | ZProfile] | None, diff --git a/src/solprop/driver/resume.py b/src/solprop/driver/resume.py index d79f5fd5c..b1381054b 100644 --- a/src/solprop/driver/resume.py +++ b/src/solprop/driver/resume.py @@ -16,7 +16,7 @@ import warnings from collections.abc import Callable, Mapping from pathlib import Path -from typing import TYPE_CHECKING, Literal +from typing import TYPE_CHECKING import numpy as np @@ -26,9 +26,15 @@ from solprop.driver.run import retention_at from solprop.exceptions import DriverError, SolpropWarning from solprop.fourier import power_amplitude +from solprop.log import ResumeChoice from solprop.nonlinear.tdse import TDSEExecution -from solprop.output.hdf5 import HDF5Output, ResumeState, _stored_metadata, check_cache -from solprop.output.hdf5 import resume as resume_state +from solprop.output.hdf5 import ( + HDF5Output, + ResumeState, + _stored_metadata, + check_cache, + read_resume_state, +) from solprop.output.memory import MemoryOutput from solprop.output.metadata import RunMetadata from solprop.output.records import MarchSnapshot @@ -48,21 +54,22 @@ logger = logging.getLogger(__name__) -type _ResumeChoice = bool | Literal["interpolated"] -"""What ``resume`` takes: no, yes, or from a plane interpolated inside a step.""" - -def _adopt_recorded_seed( +def _resumed_simulation( simulation: "Simulation", output: Output | Path | str | None -) -> None: - """Take the noise seed of the file a resume continues, where the call gave none. +) -> "Simulation": + """Return the run a resume continues, drawn from the file's seed if unseeded. The maintainers' ruling on resuming a default call (``seed=None``): the realisation is drawn again from the seed the file recorded, so the re-run - call describes the run it continues. Nothing happens when there is no file, - the file recorded no seed or another noise model, or the realisation was - seeded or supplied by the caller; :func:`~solprop.output.hdf5.check_cache` - then judges the run as before. + call describes the run it continues. It is drawn on a copy + (:meth:`~solprop.driver.simulation.Simulation._reseeded`), so the caller's + simulation keeps its own realisation and a later fresh run of it does not carry + the file's; the copy shares the caller's material log, as the caller's own run + would. `simulation` itself is returned when there is no file, the file recorded + no seed or another noise model, or the realisation was seeded or supplied by the + caller; :func:`~solprop.output.hdf5.check_cache` then compares the call's + realisation as it was built. """ if ( simulation._noise_redraw is None @@ -70,17 +77,20 @@ def _adopt_recorded_seed( or not isinstance(output, Path | str) or not Path(output).exists() ): - return + return simulation stored = _stored_metadata(output)[0].noise if stored is None or stored.seed is None or stored.model != simulation.noise.model: - return - if simulation._reseed(stored.seed): + return simulation + resumed = simulation._reseeded(stored.seed) + if resumed is not simulation: + resumed._material_log = simulation._material_log logger.info( "resuming %s: the noise was drawn without a seed, so it is drawn again " "from the seed the file recorded, %d", output, stored.seed, ) + return resumed def _start( @@ -90,6 +100,7 @@ def _start( *, kept: bool = False, restoration: dict[str, object] | None = None, + next_plane: int | None = None, ) -> Start: """Return where the run starts: the entrance, or the state a file resumes. @@ -100,13 +111,16 @@ def _start( the entrance. - ``kept``: the backend was built for another input, so this one's noise has to be handed to it. + - ``next_plane``: what :func:`_validate_resume` returned for `state`, which a + caller that has validated it passes; ``None`` validates it here. """ if state is None: return Start.entrance(problem, noise=_realisation(problem) if kept else None) request = simulation.run_request() - next_plane = _validate_resume( - problem, request, state, simulation.settings.tdse_execution - ) + if next_plane is None: + next_plane = _validate_resume( + problem, request, state, simulation.settings.tdse_execution + ) logger.info( "resuming at z = %.6e m, plane %d of %d", state.plane.z, @@ -240,7 +254,7 @@ def _missing_history( if kept == "omitted" and why == "explicit_policy": return reset("explicit_policy") # Nothing to continue (a position the march held no history at), or a file - # that does not say: as before, the history starts afresh without a warning. + # that does not say: the history starts afresh without a warning. return reset("unavailable_history") @@ -303,20 +317,11 @@ def _validate_resume( return next_plane -def _interpolated(state: ResumeState) -> bool: - """Return whether the plane a file resumes from was interpolated inside a step. - - A landed plane is the end of an accepted step of the run; an interpolated one lies - inside a step. The entrance is the initial field. - """ - return state.interpolated - - def _open_output( output: Output | Path | str | None, metadata: RunMetadata, *, - resume: _ResumeChoice, + resume: ResumeChoice, ) -> tuple[Output, ResumeState | None]: """Choose the handler a run writes to, and read what a resumed file holds. @@ -326,7 +331,7 @@ def _open_output( if isinstance(output, Path | str): path = Path(output) if resume and check_cache(path, metadata): - return HDF5Output(path, append=True), resume_state(path) + return HDF5Output(path, append=True), read_resume_state(path) return HDF5Output(path), None if resume: msg = ( @@ -361,14 +366,14 @@ def _work_left(request: RunRequest, state: ResumeState, next_plane: int) -> bool ) -def _refuse_interpolated(path: Path, state: ResumeState, resume: _ResumeChoice) -> None: +def _refuse_interpolated(path: Path, state: ResumeState, resume: ResumeChoice) -> None: """Refuse to continue from a plane interpolated inside a step, unless accepted. An interpolated plane is not a state the march passed through, so a run restarted there is not the run it continues (SEP 14 section 5); ``resume="interpolated"`` accepts that. """ - if resume == "interpolated" or not _interpolated(state): + if resume == "interpolated" or not state.interpolated: return msg = ( f"{path} ends on a plane interpolated inside a step at z = " @@ -383,7 +388,7 @@ def _continues( request: RunRequest, state: ResumeState, next_plane: int, - resume: _ResumeChoice, + resume: ResumeChoice, ) -> bool: """Say whether a resume of a file computes anything, once its hash has passed. diff --git a/src/solprop/driver/routes/__init__.py b/src/solprop/driver/routes/__init__.py index 9e695140d..2285df867 100644 --- a/src/solprop/driver/routes/__init__.py +++ b/src/solprop/driver/routes/__init__.py @@ -11,3 +11,5 @@ selection they share in :mod:`~solprop.driver.routes.materials` and the naming of the keyword a refusal concerns in :mod:`~solprop.driver.routes.keywords`. """ + +__all__: list[str] = [] diff --git a/src/solprop/driver/routes/general.py b/src/solprop/driver/routes/general.py index 8d4e43d07..c5ab3040c 100644 --- a/src/solprop/driver/routes/general.py +++ b/src/solprop/driver/routes/general.py @@ -74,8 +74,6 @@ class _GeneralRequest: - ``length``: guide length, m. - ``channel``: which channel the pulse enters; ``None`` takes the first. - - ``observable_rtol``, ``observable_atol``: accepted only as ``None``, which - means the solver's own tolerances. - ``fwhm``, ``width``, ``shape``, ``energy``, ``peak_power``, ``phases``, ``pulses``: the input pulse, as :func:`_shaped_pulse` takes it. - ``absorber``: the collar rates; ``None`` builds the grid's default collar, and @@ -83,8 +81,9 @@ class _GeneralRequest: - ``absorber_scheme``: how the temporal collar is applied; ``None`` is the default scheme. - ``stats``: which statistics to record; ``None`` takes :func:`_general_stats`. - - ``integrator``: the method that steps the run; ``None`` takes ``Multistep()``, - and ``LowStorageRungeKutta()`` replays `schedule` in three registers. + - ``integrator``: the method that steps the run; ``None`` takes the waveguide row + of :data:`~solprop.driver.defaults.ROUTE_DEFAULTS`, ``RungeKutta()``, and + ``LowStorageRungeKutta()`` replays `schedule` in three registers. - ``step_planes``: also save the end of every `step_planes`-th accepted step; ``None`` is ``0``. - ``refused``: every gas-filled keyword, by name; each is refused when it is @@ -98,8 +97,6 @@ class _GeneralRequest: incident: SpatialPulse | None coupling: CouplingModel | None kerr_form: KerrForm - observable_rtol: float | None - observable_atol: float | None wavelength: float wavelength_limits: tuple[float, float] | None trange: float | None @@ -149,21 +146,6 @@ def _from_general(cls: type["Simulation"], request: _GeneralRequest) -> "Simulat provider, MaterialSelection() if request.materials is None else request.materials, ) - for name, value in ( - ("observable_rtol", request.observable_rtol), - ("observable_atol", request.observable_atol), - ): - if value is not None: - msg = ( - f"{name}={value!r}: a general modal run's observables are its " - "channel amplitudes in a basis orthonormal in true power, so " - "the controller's own rtol and atol already bound them, and " - "the separate allocation a different number would ask for -- " - "over the table's frequency interpolation, the transverse rule " - "and the step -- is not implemented. Pass None, and set rtol " - "and atol" - ) - raise DriverError(msg) working = _capillary_grid( request.grid, request.length, diff --git a/src/solprop/driver/routes/hollow.py b/src/solprop/driver/routes/hollow.py index f7d2241bf..9fdf54592 100644 --- a/src/solprop/driver/routes/hollow.py +++ b/src/solprop/driver/routes/hollow.py @@ -167,7 +167,7 @@ class _HollowRequest: - ``length``: capillary length, m. - ``gas``: Built-in gas, mole fractions keyed by species name, or ordered populations carrying their own density paths. A mapping uses total pressure. - - ``pressure``: None uses one bar for a gas or fractions. Omit pressure beside a + - ``pressure``: required beside a built-in gas or fractions. Omit it beside a Mixture; every explicit pressure is refused because it already carries its paths. Fill pressure in **bar**: a number for a constant fill, a pair ``(p_in, p_out)`` for the steady-flow gradient of @@ -312,8 +312,10 @@ class _HollowRequest: - ``dz_init``: first step, m; ``None`` takes ``length * 1e-4``. - ``integrator``: the method that steps the run (``docs/guide/numerics/choosing-a-stepper.md``). ``None``, the default, takes - ``Multistep()``: the low-call exponential Adams method, one response - evaluation per step. ``RungeKutta()`` is the interaction-picture DOPRI5 march, + the `route`'s row of :data:`~solprop.driver.defaults.ROUTE_DEFAULTS`: + ``Multistep()`` on a capillary, the low-call exponential Adams method, one + response evaluation per step, and ``RungeKutta()`` on a gas-filled waveguide. + ``RungeKutta()`` is the interaction-picture DOPRI5 march, for a cheap response or a state too large for the Adams history. ``LowStorageRungeKutta()`` replays `schedule` in three registers (SEP 24). - ``route``: the interface building the run, whose row of @@ -805,7 +807,7 @@ class _TDSEEntry: execution : TDSEExecution Atomic runtime resources. backend : str - The resolved backend, ``numpy_ref``. + The resolved backend (``"auto"`` resolves to ``native``). step_planes : int Resolved natural-step save interval. n_save : int or None diff --git a/src/solprop/driver/routes/keywords.py b/src/solprop/driver/routes/keywords.py index cc5851588..a069cc12c 100644 --- a/src/solprop/driver/routes/keywords.py +++ b/src/solprop/driver/routes/keywords.py @@ -12,6 +12,7 @@ import contextlib import dataclasses +import threading import warnings from collections.abc import Iterator, Mapping from typing import Any, Final, cast @@ -65,6 +66,9 @@ def _about( a warning once per location and text rather than once per run. """ +_CATCHING: Final = threading.RLock() +"""Held through a :func:`_warnings_about` block; re-entrant, so a nested block runs.""" + @contextlib.contextmanager def _warnings_about( @@ -80,24 +84,30 @@ def _warnings_about( every other warning is issued as it was. """ caught: list[warnings.WarningMessage] = [] - try: - with warnings.catch_warnings(record=True) as caught: - warnings.simplefilter("always") - yield - finally: - for record in caught: - # A recorded warning is an instance of its category, never a string. - message = cast("Warning", record.message) - if isinstance(message, categories) and message.parameter is None: - message.parameter = parameter - warnings.warn_explicit( - message, - record.category, - record.filename, - record.lineno, - registry=_REISSUED, - source=record.source, - ) + # `catch_warnings` swaps the process's filters, so two threads' blocks that overlap + # would each restore the other's: they take turns. Another thread's warning issued + # during a block is still recorded by it. The lock is held across the `yield`, and + # is re-entrant for this thread only: code inside the block must never wait on + # another thread that itself enters a block here, or both wait for ever. + with _CATCHING: + try: + with warnings.catch_warnings(record=True) as caught: + warnings.simplefilter("always") + yield + finally: + for record in caught: + # A recorded warning is an instance of its category, never a string. + message = cast("Warning", record.message) + if isinstance(message, categories) and message.parameter is None: + message.parameter = parameter + warnings.warn_explicit( + message, + record.category, + record.filename, + record.lineno, + registry=_REISSUED, + source=record.source, + ) _MATERIAL_WARNINGS: Final = (MaterialRangeWarning, MaterialStatusWarning) diff --git a/src/solprop/driver/routes/spatial.py b/src/solprop/driver/routes/spatial.py index a499dccec..da35c38fd 100644 --- a/src/solprop/driver/routes/spatial.py +++ b/src/solprop/driver/routes/spatial.py @@ -259,7 +259,9 @@ def _selected_medium( selected = dataclasses.replace(selected, susceptibility=medium.susceptibility) # A constructed medium holds its resolved temperature, a number. fill = Mixture.fill( - {selected: 1.0}, medium.pressure, temperature=cast("float", medium.temperature) + {selected: 1.0}, + cast("float | ZProfile", medium.pressure), + temperature=cast("float", medium.temperature), ) return SpatialMedium(fill) diff --git a/src/solprop/driver/run.py b/src/solprop/driver/run.py index 741724284..852c3732c 100644 --- a/src/solprop/driver/run.py +++ b/src/solprop/driver/run.py @@ -6,19 +6,19 @@ The inner loop, many adaptive or replayed steps between two save planes, lives inside a backend and is compiled; :func:`run_problem` is the Python loop around it, which runs a -few hundred times at most (``docs/dev/architecture.md`` section 5). It opens the -output (:func:`open_run`), starts the backend's session and hands it to -:mod:`solprop.driver.session_loop`, which lands on each save plane in turn and hands -the plane (:func:`plane_from_observation`, :func:`history_of`) to the output handler. -It never conjugates a spectrum and never touches the state between planes: the +few hundred times at most (``docs/dev/architecture.md`` section 5). It starts the +backend's session and hands it to :mod:`solprop.driver.session_loop`, which opens the +output (:func:`open_run`), lands on each save plane in turn and hands the plane, its +step history converted by :func:`history_of`, to the output handler; +:func:`plane_from_observation` builds the same plane from one session observation by +hand. It never conjugates a spectrum and never touches the state between planes: the backend owns the step loop and the output handler the sign convention on disk (``docs/dev/conventions.md`` section 2); a plane crosses as a :class:`solprop.output.records.SavedPlane` in the internal FFT convention, with modal amplitudes in true-power units. :func:`field_retention`, :func:`retention_at` and :func:`check_snapshot_request` resolve what a run keeps. Progress goes to a -:class:`solprop.log.ProgressReporter`, re-exported here with -:class:`solprop.log.LogReporter` because this is where a run reaches them; the -protocol is ``docs/dev/architecture.md`` section 14. The manual page is +:class:`solprop.log.ProgressReporter`; the protocol is ``docs/dev/architecture.md`` +section 14. The manual page is ``docs/guide/setup/running.md``. """ @@ -32,8 +32,8 @@ from solprop._interrupts import handled from solprop.backends.populations import axis_refusal from solprop.backends.protocol import Backend, BackendHistory, Observation -from solprop.backends.registry import statistics_refusal from solprop.backends.session import RunSession, Start, statistics_unavailable +from solprop.driver.settings import _FIELDS_BESIDE_STEP_PLANES from solprop.exceptions import ( BackendError, DriverError, @@ -42,7 +42,6 @@ ) from solprop.log import ( DEFAULT_PROGRESS_PERIOD, - LogReporter, ProgressChoice, ProgressReporter, StopFlag, @@ -85,8 +84,6 @@ __all__ = [ "RESTART_RECORD", - "LogReporter", - "ProgressReporter", "SessionFacts", "check_snapshot_request", "field_retention", @@ -99,6 +96,9 @@ logger = logging.getLogger(__name__) +# Refused here and, before the atomic provider is started, by Simulation.run. +_TDSE_OUTPUT_REFUSAL = "TDSE output must support terminal checkpoints and call ledgers" + def history_of(history: BackendHistory) -> StepHistory: """Return a backend's step history in the form an output handler stores. @@ -243,20 +243,14 @@ def march_snapshot(self) -> MarchSnapshot | None: ticket = session.pending_ticket() return None if ticket is None else session.march_snapshot(ticket) - def march_snapshot_nbytes(self, z: float) -> int | None: + def march_snapshot_nbytes(self) -> int | None: """Return the size of the session's method-history snapshot, or ``None``. - Parameters - ---------- - z : float - The position, m. - Returns ------- int or None Bytes, or ``None`` without one. """ - del z return self._session.march_snapshot_nbytes() @@ -296,10 +290,11 @@ def run_problem( then each save plane in turn: propagate, observe, collect statistics, save. Steps land on the planes exactly, so a saved field is an exact step endpoint and there is no interpolation (``docs/dev/stepper.md`` section 3), unless the request asks - for dense output. With ``stepper.step_planes`` the march also stops at the end of - every ``step_planes``-th accepted step, which is saved too before the same plane - is asked for again. A plane whose propagation did not meet its tolerance is logged - as a warning naming that plane (``docs/dev/stepper.md`` section 8). + for dense output. With ``backend.request.observation.step_planes`` the march also + stops at the end of every ``step_planes``-th accepted step, which is saved too + before the same plane is asked for again. A plane whose propagation did not meet + its tolerance is logged as a warning naming that plane (``docs/dev/stepper.md`` + section 8). Parameters ---------- @@ -445,20 +440,13 @@ def run_problem( _refuse_unrunnable( problem, prepared, spec, start_plane, planes.size, metadata=metadata ) - # The backend's door for a spec handed here rather than the problem's own, which - # `select` already checked (SEP 23: a backend without a statistic refuses it). - refusal = statistics_refusal(backend.name, spec.names) - if refusal is not None: - raise DriverError(refusal) retention = field_retention(prepared, fields, field_planes) _check_retainable(output, retention) check_snapshot_request(prepared, output, snapshots, resume_history, fields) if tdse_descriptor(problem.route) is not None and not isinstance( output, CheckpointOutput ): - raise DriverError( - "TDSE output must support terminal checkpoints and call ledgers" - ) + raise DriverError(_TDSE_OUTPUT_REFUSAL) if progress is not None and not isinstance( progress, str | ProgressReporter ): # pragma: no cover - refused by the annotation where it is checked @@ -657,12 +645,7 @@ def field_retention( raise DriverError(refusal) observation = request.observation if fields == "planes" and observation.step_planes: - msg = ( - "fields='planes' names saved planes by index, and step_planes saves the " - "march's own steps as well, so the plane count is not known in advance; " - "keep fields='all' or 'none' beside step_planes" - ) - raise DriverError(msg) + raise DriverError(_FIELDS_BESIDE_STEP_PLANES) try: return FieldRetention( cast("FieldsChoice", fields), tuple(int(index) for index in field_planes) diff --git a/src/solprop/driver/scan.py b/src/solprop/driver/scan.py index fe467b16a..ecaf51437 100644 --- a/src/solprop/driver/scan.py +++ b/src/solprop/driver/scan.py @@ -38,7 +38,6 @@ def run_scan( field_planes: Sequence[int] = (), stats: Literal["all", "none"] | Sequence[str] = "all", retry_failed: bool = False, - stale_age: float = 600.0, progress: ProgressChoice | ScanReporter = "auto", stop: StopFlag | None = None, recipe: RecipeRecord | None = None, @@ -57,7 +56,9 @@ def run_scan( callables. Cache a base simulation lazily inside this callable for one translation per worker. output : pathlib.Path or str - Collected HDF5 path. Matching completed points are skipped on rerun. + Collected HDF5 path. Matching completed points are skipped on rerun; on + ``Local`` and ``Pool``, a point an earlier scan left ``running`` is computed + again. executor : Executor or None, optional Execution policy. None uses the CLI policy, or Local outside the CLI. reductions : sequence of Reduction, optional @@ -71,8 +72,6 @@ def run_scan( statistics are the diagnostics needed to assess a scan. retry_failed : bool, optional Retry previously failed points; false leaves them recorded as failures. - stale_age : float, optional - Positive lease age in seconds before abandoned running points are recovered. progress : {'auto', 'bar', 'log', 'none'} or solprop.log.ScanReporter, optional One outer progress display; individual runs never draw their own bars. A :class:`~solprop.log.ScanReporter` replaces the display and is told when the @@ -115,7 +114,6 @@ def run_scan( field_planes=field_planes, stats=stats, retry_failed=retry_failed, - stale_age=stale_age, progress=progress, stop=stop, recipe=recipe, diff --git a/src/solprop/driver/session_loop.py b/src/solprop/driver/session_loop.py index 9aa948de0..cd4012e85 100644 --- a/src/solprop/driver/session_loop.py +++ b/src/solprop/driver/session_loop.py @@ -107,6 +107,8 @@ "serve", ] +# Not `__name__`: a run's lines, from run_problem and from this loop it serves, share +# one logger, so a caller filtering on it sees all of them. logger = logging.getLogger("solprop.driver.run") _CONSUMER = ExportRecipe(power=True, optics=False) @@ -710,7 +712,7 @@ def _service_snapshot( # noqa: PLR0917 - the snapshot transaction's context event: ServiceRequired, output: HDF5Output, checkpoint_output: CheckpointOutput | None, - backend: object, + backend: SessionFacts, keeper: _MarchKeeper, exports: _Exports, context: ServiceContext, @@ -740,7 +742,7 @@ def persist() -> None: keeper.keep(z, required=adams) _record_execution( checkpoint_output, - backend, # pyright: ignore[reportArgumentType] + backend, context.tdse_binding, _Status("running", z), clock=clock, @@ -1186,7 +1188,7 @@ def keep(self, z: float, *, required: bool = False) -> None: # noqa: PLR0911, P if self._policy is None and not required and not self._within_limit: # Before any copy: the snapshot over the limit is the state and the whole # history, on the host. - nbytes = self._snapshot_nbytes(z) + nbytes = self._snapshot_nbytes() if nbytes is None: self._decide(z, "omitted", "unavailable_history") return diff --git a/src/solprop/driver/settings.py b/src/solprop/driver/settings.py index 0d8abfcd4..ba4761126 100644 --- a/src/solprop/driver/settings.py +++ b/src/solprop/driver/settings.py @@ -56,6 +56,14 @@ from solprop.stepper.settings import PropagatorMode from solprop.translate.masks import AbsorberScheme +# The refusal of fields='planes' beside step_planes, shared with the run's own check +# (solprop.driver.run.field_retention). +_FIELDS_BESIDE_STEP_PLANES = ( + "fields='planes' names saved planes by index, and step_planes saves the march's " + "own steps as well, so the plane count is not known in advance; keep fields='all' " + "or 'none' beside step_planes" +) + __all__ = [ "DEFAULT_N_SAVE", "LOOSE_ADAMS_RTOL", @@ -199,7 +207,9 @@ class SimulationSettings(Displayed): reject-free controller. interval_cap : bool or None Whether a step is capped at the width of its operator-table interval. ``None`` - caps it only for a coupled flow or a reject-free controller (SEP 14). + caps it only for a coupled flow or a reject-free controller (SEP 14). An Adams + integrator caps by its own ``Multistep(interval_cap=...)``; a different value + here is refused. interpolate_planes : bool Observe the save planes inside accepted steps instead of landing on them (SEP 14 phase 3): through the Adams march's own polynomial or, with @@ -212,14 +222,15 @@ class SimulationSettings(Displayed): saves the requested planes only. Not in scans. integrator : Multistep, RungeKutta, LowStorageRungeKutta or None The method that steps the run (``docs/guide/numerics/choosing-a-stepper.md``). - ``None``, the default, takes ``Multistep()``, or ``RungeKutta()`` where the - interface's builder sets it - (:meth:`~solprop.driver.simulation.Simulation.from_gnlse`, - :meth:`~solprop.driver.simulation.Simulation.from_waveguide` and - :meth:`~solprop.driver.simulation.Simulation.from_free`; - ``docs/guide/numerics/choosing-a-stepper.md``); the stored value is the resolved - method. ``Multistep()`` is the low-call exponential Adams method, which - ``numpy_ref`` and ``native`` execute for supported configurations; + ``None``, the default, takes the route's method in every ``Simulation.from_*`` + constructor (:data:`~solprop.driver.defaults.ROUTE_DEFAULTS`: ``RungeKutta()`` + for :meth:`~solprop.driver.simulation.Simulation.from_gnlse`, + :meth:`~solprop.driver.simulation.Simulation.from_waveguide` and a Cartesian or + line :meth:`~solprop.driver.simulation.Simulation.from_free`, ``Multistep()`` + for the others) and ``Multistep()`` on a + :class:`~solprop.driver.simulation.Simulation` built directly; the stored + value is the resolved method. ``Multistep()`` is the low-call exponential Adams + method, which ``numpy_ref`` and ``native`` execute for supported configurations; ``RungeKutta()`` is the interaction-picture DOPRI5 march, which every backend executes and which holds a third of the Adams history's memory. ``LowStorageRungeKutta()`` replays `schedule` with RK4 in three registers and no @@ -345,8 +356,8 @@ class SimulationSettings(Displayed): along z must meet (SEP 34 section 4.5). ``None``, the default, is ``AdiabaticAccuracy()``, both 1e-4; a path exceeding them is refused. tdse_execution : solprop.nonlinear.tdse.TDSEExecution or None - Explicit atomic runtime resources for a TDSE response. Requires an explicit - ``backend="numpy_ref"`` and a Multistep integrator. Execution resources are + Explicit atomic runtime resources for a TDSE response. Requires a Multistep + integrator. Execution resources are outside the scientific resume identity; attempted-call budgets are cumulative. boundary_check : solprop.monitor.BoundaryCheck or None How the run watches its time window's edges (SEP 21): guard and collar @@ -556,13 +567,8 @@ def __post_init__(self) -> None: raise DriverError(msg, parameter="resume_history") self._resolve_defaults() if self.fields == "planes" and self.step_planes: - msg = ( - "fields='planes' names saved planes by index, and step_planes saves " - "the march's own steps as well, so the plane count is not known in " - "advance; keep fields='all' or 'none' beside step_planes" - ) raise DriverError( - msg, + _FIELDS_BESIDE_STEP_PLANES, parameter=("fields", "step_planes"), rule="fields-planes-step-planes", ) @@ -572,15 +578,14 @@ def __post_init__(self) -> None: # checked at run time, as in the test suite. if not isinstance( self.integrator, Multistep | RungeKutta | LowStorageRungeKutta - ): # pragma: no cover + ): # pragma: no cover - its annotation refuses it first msg = ( "integrator must be Multistep(), RungeKutta() or " f"LowStorageRungeKutta(), got {self.integrator!r}" ) raise DriverError(msg, parameter="integrator") if isinstance(self.integrator, LowStorageRungeKutta): - backend = _admit_low_storage(self.integrator, self.backend, self) - object.__setattr__(self, "backend", backend) + _admit_low_storage(self.integrator, self) # An Adams integrator resolves "auto" as the Runge-Kutta march does: every # backend steps the exponential formulation on every route, and the # interaction one on every route but a coupled flow, which it refuses by name @@ -901,13 +906,13 @@ def keyword_settings( def _admit_low_storage( - integrator: LowStorageRungeKutta, backend: str, settings: SimulationSettings -) -> str: + integrator: LowStorageRungeKutta, settings: SimulationSettings +) -> None: """Refuse what the low-storage march cannot run, before translation (SEP 24 5). The march replays a prescribed schedule, lands on its edges and accepts every step, so it needs a schedule and has no interpolated planes. Every registered - backend executes it (:data:`LOW_STORAGE_BACKENDS`), so the backend passes as asked. + backend executes it (:data:`LOW_STORAGE_BACKENDS`). """ if settings.schedule is None: msg = ( @@ -927,7 +932,6 @@ def _admit_low_storage( parameter=("integrator", "interpolate_planes"), rule="low-storage-no-interpolation", ) - return backend def _same_setting(old: object, new: object) -> bool: diff --git a/src/solprop/driver/simulation.py b/src/solprop/driver/simulation.py index 2043b82d7..65fc7890a 100644 --- a/src/solprop/driver/simulation.py +++ b/src/solprop/driver/simulation.py @@ -71,7 +71,6 @@ from solprop.driver.material_output import material_manifest from solprop.driver.metadata import ( RecipeSource, - _frame_follows_the_electronic_rule, _plane_frame, metadata_for, ) @@ -82,12 +81,10 @@ mixture_profiles, ) from solprop.driver.resume import ( - _adopt_recorded_seed, _check_resume_choice, _continues, - _interpolated, _open_output, - _ResumeChoice, + _resumed_simulation, _start, _validate_resume, ) @@ -122,7 +119,12 @@ _selected_planar, _transverse_specification, ) -from solprop.driver.run import check_snapshot_request, field_retention, run_problem +from solprop.driver.run import ( + _TDSE_OUTPUT_REFUSAL, + check_snapshot_request, + field_retention, + run_problem, +) from solprop.driver.runner import SimulationRunner, _peak_field_reports from solprop.driver.settings import ( _EXECUTION_SETTINGS, @@ -165,6 +167,7 @@ DEFAULT_PROGRESS_PERIOD, ProgressChoice, ProgressReporter, + ResumeChoice, StopFlag, ) from solprop.modes.antiresonant import TubeLattice @@ -277,15 +280,18 @@ class Simulation(Displayed): """A run that can be translated once and executed many times. Construct it from the physics objects and a - :class:`~solprop.driver.settings.SimulationSettings`, or through - :meth:`from_gnlse` for a GNLSE fibre. :meth:`translate` assembles the kernel problem + :class:`~solprop.driver.settings.SimulationSettings`, or through one of the + ``from_*`` constructors: :meth:`from_free`, :meth:`from_planar`, + :meth:`from_gnlse`, :meth:`from_capillary` and :meth:`from_waveguide`. + :meth:`translate` assembles the kernel problem and caches it, so a second :meth:`run` -- into another handler, or resuming a file -- reuses it. :attr:`settings` may be replaced until that first translation; - after it only its ``backend`` may change. What the run is built from -- the grid, - the modes, the responses, the input and the rest of the parameters below -- is - read-only, because the input, the translation and the record are derived from it: - :meth:`with_input` derives a run with a new input, noise or launch position, - :meth:`with_mixture` one with a new fill, and anything else is a new simulation. + after it only the execution settings :attr:`settings` lists may change. What the + run is built from -- the grid, the modes, the responses, the input and the rest of + the parameters below -- is read-only, because the input, the translation and the + record are derived from it: :meth:`with_input` derives a run with a new input, + noise or launch position, :meth:`with_mixture` one with a new fill, and anything + else is a new simulation. Parameters ---------- @@ -551,9 +557,10 @@ def settings(self) -> SimulationSettings: # numpydoc ignore=RT01 Assigning a new :class:`~solprop.driver.settings.SimulationSettings` before the first :meth:`translate` (or :meth:`run`) takes effect. After it the translated problem is cached, so an assignment that changes anything the translation - consumed is refused, because it could no longer change the run; the ``backend`` - and ``tdse_execution`` resources, which are read when the run executes, may - still change. + consumed is refused, because it could no longer change the run. The execution + settings, read when the run executes, may still change: ``backend``, + ``node_budget``, ``resume_history``, ``tdse_execution``, ``fields``, + ``field_planes`` and ``boundary_check``. The settings the run is, or will be, translated with. """ @@ -579,9 +586,8 @@ def settings(self, settings: SimulationSettings) -> None: DriverError If the planes do not fit this run's interval, a replayed schedule does not cover it, or the simulation has already been translated and the - replacement changes a setting other than ``backend``, ``resume_history``, - ``fields``, ``field_planes``, ``tdse_execution`` or ``boundary_check``, - naming them. + replacement changes a setting other than the execution settings + :attr:`settings` lists, naming them. """ settings = _adopted( settings, entrance=float(self.initial_z), length=float(self.grid.length) @@ -601,9 +607,8 @@ def settings(self, settings: SimulationSettings) -> None: f"this Simulation is already translated, so a new " f"{', '.join(changed)} would be ignored; set the settings before " "the first translate() or run(), or build a new Simulation (only " - "the backend, resume_history, fields, field_planes, the TDSE " - "execution resources and boundary_check may change after " - "translation)" + f"{', '.join(_EXECUTION_SETTINGS[:-1])} and " + f"{_EXECUTION_SETTINGS[-1]} may change after translation)" ) raise DriverError(msg) if self._recipe is not None: @@ -1547,15 +1552,9 @@ def _record(self, initial: object) -> RunMetadata: ) if self.frame is not None: configuration["frame"] = self.frame - elif _frame_follows_the_electronic_rule(self.responses, self.grid): - # A Raman thg flag kept beta_0 on an envelope grid before the frame - # followed the electronic responses alone (issue #77). Recording the - # co-moving frame here, and only here, refuses a resume of such an - # earlier run by name, which would otherwise continue under another - # frame with the same digest; every other run keeps its digest. - configuration["frame"] = Frame.comoving(self.grid) - # The operator settings of SEP 22 phase 2, recorded only where set, so - # every earlier run keeps its digest; a collar as its two numbers. + # The operator settings of SEP 22 phase 2, recorded only where set: unset, + # each is its documented default, which its absence implies, so the record + # stays short. A collar as its two numbers. if self.settings.evanescent_rate is not None: configuration["evanescent_rate"] = self.settings.evanescent_rate if self.settings.spatial_absorber is not None: @@ -1797,7 +1796,7 @@ def run( *, progress: ProgressReporter | ProgressChoice | None = None, progress_period: float = DEFAULT_PROGRESS_PERIOD, - resume: _ResumeChoice = False, + resume: ResumeChoice = False, tdse_archive: TDSEArchive | None = None, snapshots: SnapshotController | None = None, stop: StopFlag | None = None, @@ -1829,8 +1828,10 @@ def run( file is returned. Only a path can be resumed: the driver has to open the file in append mode itself. Noise a constructor drew without a seed is drawn again from the seed the file recorded, so re-running the same call continues - its file. A file whose last plane was interpolated inside a step is refused - unless this is ``"interpolated"``: it then continues afresh from the + its file; the redraw is the resume's own, and this simulation keeps its + realisation for a later fresh run. A file whose last plane was interpolated + inside a step is refused unless this is ``"interpolated"``: it then + continues afresh from the interpolated field, and the position is recorded in the annotation :data:`~solprop.output.metadata.INTERPOLATED_RESUMES_ANNOTATION` before the first step, so a session that stops later still records it. @@ -1847,7 +1848,7 @@ def run( interpolated plane its step crossed. Requires HDF5 and ``fields='all'``. Adams history cannot be explicitly disabled. A configured archive is copied together with the optical file. - stop : object or None, optional + stop : solprop.log.StopFlag or None, optional This run's own stop flag: any object with an ``is_set()`` method, such as a :class:`threading.Event` (SEP 41, S17). It is polled before the first step and before every trial step, so the run answers within one step or @@ -1909,7 +1910,7 @@ def _run( *, progress: ProgressReporter | ProgressChoice | None = None, progress_period: float = DEFAULT_PROGRESS_PERIOD, - resume: _ResumeChoice = False, + resume: ResumeChoice = False, tdse_archive: TDSEArchive | None = None, snapshots: SnapshotController | None = None, stop: StopFlag | None = None, @@ -1917,20 +1918,53 @@ def _run( ) -> Output: """Execute the run, on a new backend or on one a caller keeps between runs. + A resume runs the copy :func:`~solprop.driver.resume._resumed_simulation` + returns, so this simulation keeps its own noise realisation; what the run + learns about its peak fields is kept here as for any run. + - ``progress_period``: as for :meth:`run`, s. - ``kept``: a backend built for this problem but for its input, which is loaded and left open for the caller; ``None`` constructs one and closes it. It serves a fresh run only, with no TDSE response. """ _check_resume_choice(resume) + simulation = self + if resume: + with _optmat.material_context(self._material_log): + simulation = _resumed_simulation(self, output) + handler = simulation._execute( + output, + progress=progress, + progress_period=progress_period, + resume=resume, + tdse_archive=tdse_archive, + snapshots=snapshots, + stop=stop, + kept=kept, + ) + self._peak_fields = simulation._peak_fields + return handler + + def _execute( + self, + output: Output | Path | str | None, + *, + progress: ProgressReporter | ProgressChoice | None, + progress_period: float, + resume: ResumeChoice, + tdse_archive: TDSEArchive | None, + snapshots: SnapshotController | None, + stop: StopFlag | None, + kept: Backend | None, + ) -> Output: + """Execute the run on this simulation as it is (:meth:`_run`).""" with _optmat.material_context(self._material_log): - if resume: - _adopt_recorded_seed(self, output) problem = self.translate() request = self.run_request() _refuse_pending_check(problem) metadata = self.metadata() handler, state = _open_output(output, metadata, resume=resume) + next_plane: int | None = None if state is not None: next_plane = _validate_resume( problem, request, state, self.settings.tdse_execution @@ -1952,9 +1986,7 @@ def _run( if tdse_descriptor(problem.route) is not None and not isinstance( handler, CheckpointOutput ): - raise DriverError( - "TDSE output must support terminal checkpoints and call ledgers" - ) + raise DriverError(_TDSE_OUTPUT_REFUSAL) _check_tdse_archive(tdse_archive, problem, handler) check_snapshot_request( request, @@ -2004,6 +2036,7 @@ def _run( state, kept=kept is not None, restoration=restoration, + next_plane=next_plane, ) _restore_atomic(binding, start) _consistency_gate(self, binding, problem, handler, metadata, backend) @@ -2027,12 +2060,14 @@ def _run( recipe=None if self._recipe is None else self._recipe.record(self), restoration=restoration or None, # Allowed only by resume="interpolated"; the record says where. - interpolated_resume=state is not None and _interpolated(state), + interpolated_resume=state is not None and state.interpolated, ) except StopRequested as error: - failure = error - # A stop raised by another run's flag is that run's to catch. + # A stop raised by another run's flag is that run's to catch. The run's + # own stop is not an error, so a resource that fails to close after it + # is raised rather than noted on a stop nobody sees. if error.flag is not stop: + failure = error raise except BaseException as error: failure = error @@ -2898,7 +2933,7 @@ def from_capillary( populations carrying their own density paths. A mapping uses total pressure. pressure : float, sequence, ZProfile or None, optional - None uses one bar for a gas or fractions. Omit pressure beside a Mixture; + Required beside a built-in gas or fractions. Omit it beside a Mixture; every explicit pressure is refused because it already carries its paths. Fill pressure in **bar**: a number for a constant fill, a pair ``(p_in, p_out)`` for the steady-flow gradient of @@ -3251,8 +3286,6 @@ def from_waveguide( incident: SpatialPulse | None = None, coupling: CouplingModel | None = None, kerr_form: KerrForm = "real", - observable_rtol: float | None = None, - observable_atol: float | None = None, pressure_floor: float | None = None, vacuum_end: VacuumEnd | None = None, wavelength: float, @@ -3325,9 +3358,10 @@ def from_waveguide( three-component E and H at quadrature nodes, whose material regions own their responses and whose channels are Poynting-normalised, so that a channel amplitude is a - true-power amplitude by construction. It is qualified on ``numpy_ref`` and the - native CPU backend, a declared split block's coupled - flow included, and propagates constant geometry on a **field** grid. + true-power amplitude by construction. It runs on ``numpy_ref`` and the + native backend, its CPU build and its CUDA and HIP device builds alike, a + declared split block's coupled flow included, on a **field** grid, for a + guide of constant geometry or a solid guide whose geometry moves along z. Every gas keyword is refused by name beside a provider, because a guide's materials are its regions' and not a fill. @@ -3354,7 +3388,7 @@ def from_waveguide( carrying their own density paths. A mapping uses total pressure. Required without `provider` and refused beside one. pressure : float, sequence, ZProfile or None, optional - None uses one bar for a gas or fractions. Omit pressure beside a Mixture; + Required beside a built-in gas or fractions. Omit it beside a Mixture; every explicit pressure is refused because it already carries its paths. Fill pressure in **bar**: a number for a constant fill, a pair ``(p_in, p_out)`` for the steady-flow gradient of @@ -3414,14 +3448,6 @@ def from_waveguide( dispersive electronic policies a region's gas fill takes the dispersive cubic in the matching sector: ``"real"`` its full cubic, ``"analytic"`` its number-conserving sector. Requires `provider`. - observable_rtol, observable_atol : float or None, optional - Requested accuracy of the named physical observables of a general modal run. - ``None``, the only value accepted, means **the solver's own** `rtol` and - `atol`: the route's basis is orthonormal in true power, so the controller's - weighted norm on the amplitudes already is a norm on the physical channel - powers. A different number is refused by name, because the separate error - allocation it would ask for -- over the table's interpolation, the - transverse rule and the step -- is not implemented. Require `provider`. pressure_floor : float or None, optional Lowest pressure the fill is allowed to reach, bar; ``None`` takes :data:`solprop.profiles.DEFAULT_PRESSURE_FLOOR_FRACTION` of the highest @@ -3697,8 +3723,6 @@ def from_waveguide( ("incident", incident), ("coupling", coupling), ("kerr_form", None if kerr_form == "real" else kerr_form), - ("observable_rtol", observable_rtol), - ("observable_atol", observable_atol), ): if value is not None: msg = ( diff --git a/src/solprop/exceptions.py b/src/solprop/exceptions.py index 243a91226..c05e7198f 100644 --- a/src/solprop/exceptions.py +++ b/src/solprop/exceptions.py @@ -34,7 +34,6 @@ "GeneralModalBasisWarning", "GrazingIncidenceWarning", "GridError", - "HostMarchWarning", "MaterialError", "MaterialRangeWarning", "MaterialStatusWarning", @@ -43,6 +42,7 @@ "NoiseError", "OpticsGeometryError", "OutputError", + "OutputRequestError", "ParameterPath", "PolarisationError", "ProcessingError", @@ -238,7 +238,7 @@ class ModeError(SolpropError, ValueError): class NoZeroDispersionError(ModeError): - """``beta_2`` has one sign at both ends of a zero-dispersion search window.""" + """A zero-dispersion search found no zero of ``beta_2`` in its window.""" class PulseError(SolpropError, ValueError): @@ -269,6 +269,16 @@ class OutputError(SolpropError, RuntimeError): """An output handler could not save, load or resume a run.""" +class OutputRequestError(SolpropError, ValueError): + """An output request was given a value it refuses. + + Raised when a :class:`~solprop.output.snapshots.SnapshotController` or a + :class:`~solprop.output.tdse_archive.TDSEArchive` is built, so it is a + ``ValueError``, as the driver's refusals are. A file that cannot be written or + read later is an :class:`OutputError`. + """ + + class TDSEArchiveError(OutputError): """A TDSE response archive could not be opened, serialized or written (SEP 20). @@ -423,16 +433,6 @@ class CalibrationNotice(SolpropWarning): """ -class HostMarchWarning(SolpropWarning): - """The native backend steps a run with solprop's Python march. - - No built-in backend issues it since SEP 47's phase 5: the native backend steps - every run it admits with its own ``Multistep()`` (SEP 39) and ``RungeKutta()`` - (SEP 45) marches and refuses the rest by name. The class stays importable for - warning filters that name it. - """ - - class AdiabaticTaperWarning(SolpropWarning): """A multimode run on a guide whose modes move along z omits their coupling.""" diff --git a/src/solprop/fourier.py b/src/solprop/fourier.py index 5744ecf2c..a9f7a4000 100644 --- a/src/solprop/fourier.py +++ b/src/solprop/fourier.py @@ -664,8 +664,9 @@ def oversample( On a field grid this preserves energy only when the coarse Nyquist bin is zero: that bin is self-conjugate on the coarse grid but becomes an ordinary interior bin on the - fine one, so a non-zero value there gains a factor of two in amplitude. Every grid - built by :mod:`solprop.grid` apodises it to zero, so the condition holds in use. + fine one, so a non-zero value there gains a factor of two in amplitude. Every + :class:`solprop.grid.FieldGrid` that validates has its spectral window exactly zero + at that bin, so the condition holds in use. Parameters ---------- @@ -916,9 +917,11 @@ def spectral_density( On the field grid the zero-frequency and Nyquist bins are the one exception to ``δω Σ_k S_k = U``: the analytic signal does not double them, so summing this density over every bin overcounts those two, by ``3 δt (|Ẽ_0|² + |Ẽ_Nyq|²) / n_t`` - in total. Every interior bin agrees exactly, and both end bins are identically zero - on any grid built by :mod:`solprop.grid`, whose spectral collar apodises them away. - Use :func:`energy_omega` when an exact energy is wanted. + in total. Every interior bin agrees exactly, and every + :class:`solprop.grid.FieldGrid` that validates has its spectral window exactly zero + at both end bins, so the sum is exact on an apodised spectrum. Use + :func:`energy_omega` or :func:`energy_weights` when an exact energy is wanted on an + arbitrary array. Parameters ---------- diff --git a/src/solprop/gasflow.py b/src/solprop/gasflow.py index b148da90b..657d41d1d 100644 --- a/src/solprop/gasflow.py +++ b/src/solprop/gasflow.py @@ -431,8 +431,8 @@ def throughput( gas: Composition | Mixture, radius: float | ZProfile, length: float, - start_bar: float, - end_bar: float, + start_pressure: float, + end_pressure: float, *, temperature: float = ROOM_TEMPERATURE, ) -> float: @@ -448,7 +448,7 @@ def throughput( Core radius in m, > 0, over ``[0, length]``. length : float Length in m, > 0. - start_bar, end_bar : float + start_pressure, end_pressure : float Pressures in bar at ``z = 0`` and ``z = length``, >= 0. temperature : float, optional Gas temperature in K. @@ -476,8 +476,8 @@ def throughput( """ flow = _FlowGas.of(gas, temperature) _, resistance = _resistance(radius, length) - high = _checked_pressure(start_bar, "start_bar") * BAR - low = _checked_pressure(end_bar, "end_bar") * BAR + high = _checked_pressure(start_pressure, "start_pressure") * BAR + low = _checked_pressure(end_pressure, "end_pressure") * BAR return _poiseuille(flow, high, low, resistance) @@ -499,7 +499,7 @@ def choked_pressure( gas: Composition | Mixture, radius: float | ZProfile, length: float, - high_bar: float, + high_pressure: float, *, exit_end: Literal["start", "end"] = "end", temperature: float = ROOM_TEMPERATURE, @@ -514,7 +514,7 @@ def choked_pressure( Core radius in m, > 0, over ``[0, length]``. length : float Length in m, > 0. - high_bar : float + high_pressure : float Pressure in bar at the fed end, >= 0. exit_end : {'end', 'start'}, optional Which end exhausts: ``z = length`` (the default) or ``z = 0``. Its radius sets @@ -549,7 +549,7 @@ def choked_pressure( path, resistance = _resistance(radius, length) position = 0.0 if exit_end == "start" else float(length) exit_radius = float(path(np.array([position]))[0]) - high = _checked_pressure(high_bar, "high_bar") * BAR + high = _checked_pressure(high_pressure, "high_pressure") * BAR return _choke(flow, high, exit_radius, resistance) / BAR @@ -868,7 +868,7 @@ class StageFlow(Displayed): ---------- start, end : float The stage's ends in m. - start_bar, end_bar : float + start_pressure, end_pressure : float The fill's pressures in bar at the two ends. temperature : float Gas temperature in K. @@ -899,8 +899,8 @@ class StageFlow(Displayed): start: float end: float - start_bar: float - end_bar: float + start_pressure: float + end_pressure: float temperature: float throughput: float mass_flow: float @@ -921,7 +921,9 @@ def exit_knudsen(self) -> float: # numpydoc ignore=RT01 ``knudsen_end`` when the flow runs towards +z, else ``knudsen_start``. """ return ( - self.knudsen_end if self.end_bar <= self.start_bar else self.knudsen_start + self.knudsen_end + if self.end_pressure <= self.start_pressure + else self.knudsen_start ) @property @@ -971,7 +973,7 @@ class FlowReport(Displayed): The gas viscosity in Pa s. sound_speed : float The dilute adiabatic sound speed in m s^-1. - choked_start_bar, choked_end_bar : float or None + choked_start_pressure, choked_end_pressure : float or None The choked pressure in bar of the first and last outer end, where that end is the low end of its stage; ``None`` where it is not. start_is_choked, end_is_choked : bool @@ -982,8 +984,8 @@ class FlowReport(Displayed): stages: tuple[StageFlow, ...] viscosity: float sound_speed: float - choked_start_bar: float | None - choked_end_bar: float | None + choked_start_pressure: float | None + choked_end_pressure: float | None start_is_choked: bool end_is_choked: bool @@ -1050,8 +1052,8 @@ def _describe(self) -> tuple[str, list[tuple[str, object]]]: ) ) for name, value, flag in ( - ("start", self.choked_start_bar, self.start_is_choked), - ("end", self.choked_end_bar, self.end_is_choked), + ("start", self.choked_start_pressure, self.start_is_choked), + ("end", self.choked_end_pressure, self.end_is_choked), ): if value is not None: state = "choked" if flag else "not choked" @@ -1140,8 +1142,8 @@ def free_path_of(z: Float[np.ndarray, " n_z"]) -> Float[np.ndarray, " n_z"]: return StageFlow( start=float(samples[0]), end=float(samples[-1]), - start_bar=first, - end_bar=second, + start_pressure=first, + end_pressure=second, temperature=temperature, throughput=rate, mass_flow=mass, @@ -1237,7 +1239,7 @@ def column(low: float, high: float) -> float: def _outer_chokes( flows: tuple[_FlowGas, _FlowGas], - pressures_bar: Float[np.ndarray, " n_positions"], + pressures: Float[np.ndarray, " n_positions"], exit_radii: tuple[float, float], resistances: tuple[float, float], ) -> tuple[float | None, float | None]: @@ -1245,7 +1247,7 @@ def _outer_chokes( - ``flows``: the gas properties at the first and the last end: the same object at a constant temperature, each end's own along a temperature path. - - ``pressures_bar``: stage pressures in bar. + - ``pressures``: stage pressures in bar. - ``exit_radii``: the core radius in m at the first and the last position. - ``resistances``: the ``int a^-4 dz`` in m^-3 of the first and the last stage; along a temperature path ``int (eta T) / (eta_e T_e) a^-4 dz`` with the end's own @@ -1259,8 +1261,8 @@ def _outer_chokes( (0, 1, flows[0], exit_radii[0], resistances[0]), (-1, -2, flows[1], exit_radii[1], resistances[1]), ): - if pressures_bar[end] < pressures_bar[other]: - high = float(pressures_bar[other]) * BAR + if pressures[end] < pressures[other]: + high = float(pressures[other]) * BAR chokes.append(_choke(flow, high, exit_radius, float(resistance)) / BAR) else: chokes.append(None) @@ -1386,8 +1388,8 @@ def flow_report( ), viscosity=flow.viscosity, sound_speed=flow.sound_speed, - choked_start_bar=choked_start, - choked_end_bar=choked_end, + choked_start_pressure=choked_start, + choked_end_pressure=choked_end, start_is_choked=_at_choke(float(fill.pressures[0]), choked_start), end_is_choked=_at_choke(float(fill.pressures[-1]), choked_end), ) @@ -1450,7 +1452,7 @@ def temperature_weight( def steady_fill( gas: Composition | Mixture, positions: Sequence[float] | np.ndarray, - pressures_bar: Sequence[float] | np.ndarray, + pressures: Sequence[float] | np.ndarray, *, radius: float | ZProfile, temperature: float | ZProfile = ROOM_TEMPERATURE, @@ -1484,7 +1486,7 @@ def steady_fill( a shared fill. positions : array_like Stage boundaries in m, strictly increasing, at least two. - pressures_bar : array_like + pressures : array_like Declared pressure in bar at each boundary, >= 0. radius : float or ZProfile Core radius in m, > 0, over the fill. @@ -1532,7 +1534,7 @@ def steady_fill( """ choice(vacuum_end, "vacuum_end", get_args(VacuumEnd), TranslationError) edges = _checked_edges(positions, "steady_fill") - declared = _checked_pressures(edges, pressures_bar) + declared = _checked_pressures(edges, pressures) path = as_profile(radius) kelvin = _checked_temperature(temperature, "the steady-flow fill") try: diff --git a/src/solprop/grid.py b/src/solprop/grid.py index 9d6d9e11b..4596067ac 100644 --- a/src/solprop/grid.py +++ b/src/solprop/grid.py @@ -64,6 +64,11 @@ # has somewhere to fall to zero. WINDOW_FACTOR = 1.1 +# The least field-grid ffac: the fine Nyquist frequency, ffac omega_max / 2, must reach +# the collar's foot at WINDOW_FACTOR omega_max, so that the coarse Nyquist bin lies at +# or past it and carries no field. +FIELD_FFAC_MIN = 2.0 * WINDOW_FACTOR + # Relative tolerance for the grid invariants. They are exact in real arithmetic and are # built from products and quotients of a handful of exactly representable integers, so # only a few units in the last place separate them from equality. @@ -1245,7 +1250,8 @@ class TimeGrid(Displayed): Fine sample spacing, s. ffac : float Oversampling factor: the fine grid is sampled at ``ffac`` times the highest - frequency of the window. At least 2. + frequency of the window. At least 2 (at least 2.2 when a field grid is built + by :meth:`FieldGrid.from_limits`). omega_collar : Collar Spectral collar geometry, rad/s: rises over ``[omega_min/2, omega_min]`` and falls over ``[omega_max, 1.1 omega_max]``. @@ -1659,7 +1665,9 @@ class FieldGrid(TimeGrid): """Grid for field-resolved propagation of a real electric field. The state is the one-sided spectrum on ``omega_k = k d_omega``, ``k = 0 ... n_t/2``, - so ``n_omega = n_t/2 + 1`` and the time samples are real. Build one with + so ``n_omega = n_t/2 + 1`` and the time samples are real. Both end bins, zero + frequency and Nyquist, lie outside the spectral collar, where its window is exactly + zero, so they carry no field; :meth:`~TimeGrid.validate` checks it. Build one with :meth:`from_limits`; see :class:`TimeGrid` for the stored attributes. Examples @@ -1714,11 +1722,12 @@ def from_limits( Requested fine sample spacing, s. The value used is this or the value the frequency window demands, whichever is smaller. ffac : float, optional - Fine-grid oversampling factor, at least 2. The default 6 resolves a cubic + Fine-grid oversampling factor, at least 2.2. The default 6 resolves a cubic response, whose third harmonic reaches ``3 omega_max``; 4 suffices for a - response that generates no third harmonic, such as ``|E_a|^2 E``. At exactly - 2 the fine Nyquist frequency is ``omega_max`` itself, so the apodisation - collar above it is truncated rather than represented. + response that generates no third harmonic, such as ``|E_a|^2 E``. The fine + Nyquist frequency is ``ffac omega_max / 2``, and the least value puts it at + the collar's foot, ``1.1 omega_max``: below that the coarse Nyquist bin + would lie inside the collar and keep field there. fft_size : {'auto', 'pow2', 'smooth'}, optional How the transform sizes are rounded up: ``'auto'``, the default, takes the cheapest even 2-3-5-smooth size between the requirement and the next power @@ -1757,6 +1766,14 @@ def from_limits( 2.0 """ _check_common(length, reference_wavelength, trange, dt, ffac, collar_fraction) + if ffac < FIELD_FFAC_MIN: + msg = ( + f"ffac must be at least {FIELD_FFAC_MIN:g} on a field grid, so that " + f"the fine Nyquist frequency, ffac omega_max / 2, reaches the spectral " + f"collar's foot at {WINDOW_FACTOR:g} omega_max and the Nyquist bin " + f"carries no field, got {ffac!r}" + ) + raise GridError(msg, parameter="ffac") omega_min, omega_max = _frequency_limits(wavelength_limits) omega_max_window = WINDOW_FACTOR * omega_max @@ -1780,28 +1797,37 @@ def _half_bins(d_omega: float, n_to: int) -> int: # dt comes from the integer ratio rather than from pi/omega[-1], so that the # dt/dt_fine == n_to/n_t invariant holds by construction, not to round-off. dt_coarse = dt_fine * (n_to // n_t) + omega = np.arange(n_t // 2 + 1, dtype=float) * d_omega + # At the least ffac the Nyquist bin is the collar's foot in exact arithmetic, + # and rounding can leave it an ulp below, where the taper is about 1e-305 + # rather than zero; the foot then moves onto the bin. Above that, or with a + # finer dt, the Nyquist bin lies past the foot and this changes nothing. + zero_high = min(omega_max_window, float(omega[-1])) _log_grid("field", n_t, n_to, dt_coarse, trange_even) grid = cls( length=float(length), reference_wavelength=float(reference_wavelength), t=(np.arange(n_t, dtype=float) - n_t / 2) * dt_coarse, - omega=np.arange(n_t // 2 + 1, dtype=float) * d_omega, + omega=omega, t_fine=(np.arange(n_to, dtype=float) - n_to / 2) * dt_fine, omega_fine=np.arange(n_to // 2 + 1, dtype=float) * d_omega, dt=dt_coarse, dt_fine=float(dt_fine), ffac=float(ffac), - omega_collar=Collar( - 0.5 * omega_min, omega_min, omega_max, omega_max_window - ), + omega_collar=Collar(0.5 * omega_min, omega_min, omega_max, zero_high), t_collar=_temporal_collar(trange, trange_even, collar_fraction), ) grid.validate() return grid def _validate_spectrum(self) -> None: - """Check that the frequency axis is the one-sided rfft axis of the time axis.""" + """Check the one-sided rfft axis, and that the collar is zero at both its ends. + + The end bins are self-conjugate, so the analytic signal does not double them: + the identities of :func:`solprop.fourier.oversample` and + :func:`solprop.fourier.spectral_density` hold only where they carry no field. + """ expected_dt = np.pi / self.omega[-1] if not math.isclose(self.dt, expected_dt, rel_tol=INVARIANT_RTOL): msg = f"dt is {self.dt!r}, expected pi/omega[-1] = {expected_dt!r}" @@ -1810,6 +1836,22 @@ def _validate_spectrum(self) -> None: if not np.allclose(self.omega, expected, rtol=INVARIANT_RTOL, atol=0.0): msg = "omega is not the non-negative rfft axis k*d_omega, k = 0 ... n_t/2" raise GridError(msg) + ends = self.omega_collar.window(self.omega[[0, -1]]) + for end, frequency, value in zip( + ("zero frequency", "Nyquist"), self.omega[[0, -1]], ends, strict=True + ): + if value != 0.0: + hint = ( + f"; build the grid with ffac >= {FIELD_FFAC_MIN:g}" + if end == "Nyquist" + else "" + ) + msg = ( + f"the spectral collar must vanish at the {end} bin of a field " + f"grid, but its window at {frequency:.6g} rad/s is {value:.3g}" + f"{hint}" + ) + raise GridError(msg) @dataclass(frozen=True, eq=False, repr=False) diff --git a/src/solprop/log.py b/src/solprop/log.py index 0e224f472..7b1bbb1a3 100644 --- a/src/solprop/log.py +++ b/src/solprop/log.py @@ -17,9 +17,10 @@ - **Scan reporters**: :class:`ScanReporter` and :class:`NullScanReporter`. - **Helpers**: :class:`StopFlag`, :func:`is_interactive` and :func:`format_duration`. -The module imports nothing from the rest of the package: ``import solprop`` imports it -eagerly, and reaching the seam would pull NumPy and jaxtyping into that import and take -it from 0.06 s to 0.6 s, past the budget ``tests/test_package.py`` holds. Hence +The module imports nothing from the rest of the package but the exception hierarchy, +which imports nothing itself: ``import solprop`` imports it eagerly, and reaching the +seam would pull NumPy and jaxtyping into that import and take it from 0.06 s to 0.6 s, +past the budget ``tests/test_package.py`` holds. Hence :class:`PlaneSummary`, the structural half of :class:`solprop.backends.protocol.StepSummary` that a reporter reads. """ @@ -40,6 +41,8 @@ from statistics import median from typing import Any, Literal, Protocol, runtime_checkable +from solprop.exceptions import DriverError + __all__ = [ "BAR_FORMAT", "DEFAULT_BAR_PERIOD", @@ -53,6 +56,7 @@ "ProgressChoice", "ProgressReporter", "ProgressStatus", + "ResumeChoice", "ScanReporter", "StopFlag", "configure_logging", @@ -88,6 +92,9 @@ reports nothing. """ +ResumeChoice = bool | Literal["interpolated"] +"""What ``resume=`` takes: no, yes, or from a plane interpolated inside a step.""" + _PROGRESS_CHOICES: tuple[str, ...] = ("auto", "bar", "log", "none") _DEFAULTS: dict[str, ProgressChoice] = {"progress": "auto"} @@ -158,7 +165,7 @@ def configure_logging( handler.close() handler: logging.Handler handler = ( - logging.FileHandler(file) + logging.FileHandler(file, encoding="utf-8") if file is not None else logging.StreamHandler(sys.stderr) ) @@ -182,7 +189,7 @@ def set_default_progress(choice: ProgressChoice) -> None: Raises ------ - ValueError + solprop.exceptions.DriverError If the choice is not one of the four names. Examples @@ -194,7 +201,8 @@ def set_default_progress(choice: ProgressChoice) -> None: >>> set_default_progress("auto") """ if choice not in _PROGRESS_CHOICES: - raise ValueError(f"progress must be one of {_PROGRESS_CHOICES}, got {choice!r}") + msg = f"progress must be one of {_PROGRESS_CHOICES}, got {choice!r}" + raise DriverError(msg) _DEFAULTS["progress"] = choice @@ -719,8 +727,8 @@ def eta_error(self) -> float: # numpydoc ignore=RT01 def eta_error_whole_run(self) -> float: # numpydoc ignore=RT01 """How far off the whole-run estimator would have been. - Formed on the same lines as :attr:`eta_error` but never reported, so that the - two can be compared on every run. + For tests: formed on the same lines as :attr:`eta_error` but never reported, + so that the two can be compared on every run. Median absolute relative error of the whole-run estimate; NaN as for :attr:`eta_error`. @@ -1126,7 +1134,7 @@ class BarReporter(LogReporter): Raises ------ - ValueError + solprop.exceptions.DriverError If the period is not positive and finite. Examples @@ -1158,10 +1166,11 @@ def __init__( echo: bool = True, ) -> None: if not (math.isfinite(period) and period > 0.0): - raise ValueError( + msg = ( "a progress bar redraws every `period` seconds, which must be " f"positive and finite; got {period!r}" ) + raise DriverError(msg) super().__init__( period=period, logger=logger, @@ -1383,7 +1392,7 @@ def default_reporter( Raises ------ - ValueError + solprop.exceptions.DriverError If the choice is not one of the four names. Examples @@ -1395,16 +1404,18 @@ def default_reporter( """ selected = default_progress() if choice is None else choice if selected not in _PROGRESS_CHOICES: - raise ValueError( + msg = ( f"progress must be one of {_PROGRESS_CHOICES} or a reporter, got " f"{selected!r}" ) + raise DriverError(msg) if selected == "auto": selected = "bar" if is_interactive(stream) else "log" if selected == "bar" and not _tqdm_available(): - # An environment that has solprop but not its newest dependency: say so - # once and log lines rather than fail the run. An explicit "bar" still - # raises, because it was asked for. + # Deliberately kept: an environment without tqdm, a required dependency + # (a broken install, or a kernel started from another environment), is + # told once and logs lines rather than failing the run. An explicit "bar" + # still raises, because it was asked for. warnings.warn( f"{TQDM_MISSING}; logging progress lines instead", RuntimeWarning, diff --git a/src/solprop/modes/antiresonant.py b/src/solprop/modes/antiresonant.py index 8f9946af6..89493fd2d 100644 --- a/src/solprop/modes/antiresonant.py +++ b/src/solprop/modes/antiresonant.py @@ -15,9 +15,7 @@ Where the printed papers and earlier published implementations of them, pyJCMwave among them, differ, ``CONVENTIONS`` names the choice and ``LEGACY_CONVENTIONS`` the form those implementations share, so that a test can assemble the latter from the same -building blocks. The 2016 paper's equations were read from a degraded text extraction -and have not been checked against the typeset page. The manual page is -``docs/guide/waveguides/antiresonant.md``. +building blocks. The manual page is ``docs/guide/waveguides/antiresonant.md``. """ import logging @@ -70,12 +68,12 @@ and 1.9 (argon) times better. """ -RADIUS_COEFFICIENT: Final = 10.0 +RADIUS_COEFFICIENT: Final = 20.0 """Coefficient of ``wavelength / core_radius`` in the effective radius. -The gap-penetration term of Rosa 2021 eq. 10 as printed; earlier implementations carry -20. The factor is empirical: no derivation decides between 10 and 20, and no erratum or -author confirmation has been found. +The gap-penetration term of Rosa, Melli and Vincetti (2021) eq. 10, whose typeset +bracket is ``3 + 2 * 10 wavelength / R_co``; Melli et al. (2025) eq. 7 writes ``3 + 20 +wavelength / R_co``, and earlier implementations carry 20 too. The factor is empirical. """ MINIMUM_LOSS_PREFACTOR: Final = 3e-4 @@ -113,13 +111,14 @@ @dataclass(frozen=True) class _Conventions: - """Name the four choices in which the papers and earlier implementations differ. + """Name the form of the fits: the radius coefficient and three disputed choices. Attributes ---------- radius_coefficient : float - Coefficient of ``wavelength / core_radius`` in the effective radius: 10 in - Rosa 2021 eq. 10, 20 in earlier implementations. + Coefficient of ``wavelength / core_radius`` in the effective radius, + ``RADIUS_COEFFICIENT`` in both forms; a field so that its effect can be + evaluated. single_power_decrement : bool True divides the waveguide decrement ``(u c / (omega R_eff))^2 / 2`` by the gas index once, the first-order expansion of ``beta = sqrt(n_g^2 k^2 - @@ -147,7 +146,7 @@ class _Conventions: CONVENTIONS: Final = _Conventions(RADIUS_COEFFICIENT, True, True, True) # The form earlier published implementations share, for the witness tests only; # production code never passes it. -LEGACY_CONVENTIONS: Final = _Conventions(20.0, False, False, False) +LEGACY_CONVENTIONS: Final = _Conventions(RADIUS_COEFFICIENT, False, False, False) def _tube_angle(n_tubes: int) -> float: @@ -928,14 +927,9 @@ def __repr__(self) -> str: Ar 1 bar, loss=model)``; a gradient shows its pressure at ``z = 0``. """ radius = float(self.core_radius(np.array([0.0]))[0]) - if self.gas is None: - fill = "evacuated" if self.mixture is None else "mixture" - else: - pressure = float(as_profile(self.pressure)(np.array([0.0]))[0]) - fill = f"{self.gas} {pressure:g} bar" return ( f"VincettiMode({self.kind}{self.n}{self.m}, a={radius * 1e6:g} um, " f"t={self.lattice.wall_thickness * 1e9:g} nm, " f"r_ext={self.lattice.tube_radius * 1e6:g} um, " - f"N={self.lattice.n_tubes}, {fill}, loss={self._loss_text()})" + f"N={self.lattice.n_tubes}, {self._fill_text()}, loss={self._loss_text()})" ) diff --git a/src/solprop/modes/base.py b/src/solprop/modes/base.py index 71507020d..1708ca6df 100644 --- a/src/solprop/modes/base.py +++ b/src/solprop/modes/base.py @@ -8,9 +8,9 @@ on one, so a new mode family gets them for nothing: the propagation constant and power loss (:func:`beta`, :func:`alpha`, :func:`loss_length`, :func:`db_per_m`, :func:`transmission`), the dispersion orders (:func:`beta1`, :func:`beta2`, -:func:`beta3`), the zero-dispersion wavelength (:func:`zdw`, which brackets its root) -and the effective area (:func:`aeff`). The conversions are the package's -(``docs/dev/conventions.md`` section 2): +:func:`beta3`), the zero-dispersion wavelength (:func:`zdw`, a sampled search of +``beta_2``'s sign) and the effective area (:func:`aeff`). The conversions are the +package's (``docs/dev/conventions.md`` section 2): :math:`\beta = (\omega/c)\,\mathrm{Re}\,n_{\rm eff}` and :math:`\alpha = (2\omega/c)\,\mathrm{Im}\,n_{\rm eff}`, so a positive imaginary index is loss and ``alpha`` is a power loss coefficient per metre. @@ -24,15 +24,20 @@ import logging import math +import warnings from typing import Final import numpy as np from jaxtyping import Float from scipy.integrate import quad_vec -from scipy.optimize import brentq from solprop.constants import C -from solprop.exceptions import ModeError, NoZeroDispersionError +from solprop.exceptions import ( + DiluteScalingWarning, + MaterialRangeWarning, + ModeError, + NoZeroDispersionError, +) from solprop.modes.protocol import Mode __all__ = [ @@ -84,6 +89,51 @@ _DECIBEL_PER_NEPER: Final = 10.0 / math.log(10.0) """Conversion from a power loss coefficient in 1/m to dB/m.""" +_ZDW_SAMPLES: Final = 512 +"""Samples, evenly spaced in frequency, on which :func:`zdw` reads the sign of +``beta_2``: 2.3e13 rad/s apart across its default window.""" + +_ZDW_REFINE_ROUNDS: Final = 5 +"""Rounds of array samples that refine a sign change of the dispersion. Five take a +bracket of 2.3e13 rad/s to 2.2e7 rad/s, where interpolating linearly reaches the noise +of the differenced ``beta2``.""" + +_ZDW_REFINE_SAMPLES: Final = 17 +"""Samples of each refinement round: 16 intervals, so each round narrows 16-fold. A +mode solved point by point (a step-index fibre) pays per sample, so fewer samples in +more rounds reach the same bracket for less.""" + +_ZDW_STENCIL_RATIO: Final = (2.0, 8.0) +"""Bounds on the rise of ``beta1`` from a candidate zero at a full step of the +``beta2`` stencil over its rise at a half step, on each side. A resolved extremum +gives 4; see :func:`_is_zero`.""" + +_ZDW_LINE_SPREAD: Final = 0.1 +"""Spread of ``beta1`` across the ``beta2`` stencil, as a fraction of its value at the +change, beyond which a sign change that is not a zero is a line (:func:`_is_line`). +At a gas line the group delay diverges or drops to the evanescent floor, and every +such change of krypton and argon fills spreads by 1 or more; a smooth feature +spreads by far less: 1e-4 at silica's OH overtone near 1.38 um, 2e-2 at its +fundamental near 2.7 um, 6e-3 at an antiresonant wall's resonance. A tenth is five +times the largest smooth spread and a tenth of the smallest at a line.""" + +_ZDW_ISOLATION: Final = 1.5e-2 +"""Relative frequency distance on each side of a zero of ``beta2`` over which it must +be the only sign change to be a zero-dispersion point (:func:`_is_isolated`): the +narrowest dispersion regime :func:`zdw` resolves, five times the ``beta2`` stencil. +Narrower regimes are the fine structure of an absorption band, whose zeros come in +clusters: fused silica's OH bands (optmat's ``fit/SiO2``) give zeros 0.2-0.8 % apart +near 1.38 um and 0.9 % apart near 2.2 and 2.7 um. An antiresonant wall's resonance +is broader: the normal dispersion beside it, which bounds the band's zeros, spans +2.1-2.4 % before the resonance's inner zeros, which are 0.5-2.5 % apart. A standard +fibre's zero near 1.3 um lies 5.5 % from the nearest other sign change.""" + +_ZDW_ISOLATION_SAMPLES: Final = 32 +"""Samples of ``beta1`` on each side of a zero across :data:`_ZDW_ISOLATION`: 4.7e-4 +apart in relative frequency, finer than the ``beta2`` stencil. Beside a standard +fibre's zero ``beta1`` changes by 1.7e-17 s/m between samples, a million times its +noise.""" + def _as_omega(omega: Float[np.ndarray, " n_omega"]) -> Float[np.ndarray, " n_omega"]: """Validate an angular-frequency argument for a derived quantity. @@ -204,9 +254,9 @@ def beta2( Departs from the analytic derivatives elsewhere in this module, and says so: the second derivative of a gas susceptibility is not part of the material interface, so this is a Richardson-extrapolated central difference of :func:`beta1` at a - relative step of :data:`BETA2_RELATIVE_STEP`. It reaches about 1e-10 relative, - against the 1e-6 of differencing ``beta`` twice, and only the co-moving frame - needs better -- which uses ``beta1``, not this. + relative step of :data:`BETA2_RELATIVE_STEP`, whose documentation gives the + measured accuracy. Only the co-moving frame needs better -- which uses + ``beta1``, not this. Parameters ---------- @@ -323,14 +373,207 @@ def _second_difference( return np.asarray((above - 2.0 * centre + below) / step**2) +def _refine_zero(mode: Mode, low: float, high: float, z: float) -> float: + """Return a sign change of the dispersion inside a bracket, by array samples. + + A mode's index models evaluate an array at about the cost of one point, so each + round narrows the bracket 16-fold for the cost of one Brent step, where a scalar + search costs a glass model evaluation per iterate. The rounds stop short of a pole + of the differenced ``beta2``, which a scalar search converges onto until the model + returns NaN. + + - ``low``, ``high``: the bracket, rad/s, whose ends have ``beta2`` of opposite + signs. + - ``z``: position along the waveguide, m. + - Returns: the first sign change upwards in frequency, rad/s, linearly interpolated + in the last bracket; or NaN when samples that are not finite separate the signs. + """ + first = last = math.nan + for _ in range(_ZDW_REFINE_ROUNDS): + grid = np.linspace(low, high, _ZDW_REFINE_SAMPLES) + sampled = beta2(mode, grid, z) + crossing = np.flatnonzero(np.sign(sampled[:-1]) * np.sign(sampled[1:]) <= 0.0) + if crossing.size == 0: + return math.nan + i = int(crossing[0]) + low, high = float(grid[i]), float(grid[i + 1]) + # The first change has a nonzero sample below it, so the two cannot be equal. + first, last = float(sampled[i]), float(sampled[i + 1]) + return low - first * (high - low) / (last - first) + + +def _stencil_delays(mode: Mode, omega: float, z: float) -> Float[np.ndarray, " 5"]: + """Return the analytic `beta1` across the stencil of `beta2` at a frequency. + + The five frequencies ``omega (1 + s h)`` for ``s`` in -1, -1/2, 0, 1/2, 1 and + ``h`` :data:`BETA2_RELATIVE_STEP` that span the difference behind :func:`beta2`; + s/m. + """ + offsets = BETA2_RELATIVE_STEP * np.array([-1.0, -0.5, 0.0, 0.5, 1.0]) + return beta1(mode, omega * (1.0 + offsets), z) + + +def _is_zero(delays: Float[np.ndarray, " 5"]) -> bool: + """Whether a refined sign change of the differenced `beta2` is a zero of it. + + - ``delays``: ``beta1`` across the stencil at the change (:func:`_stencil_delays`). + + At a zero of ``beta_2`` that the difference resolves, ``beta1`` is strictly + extremal there and its Taylor series converges across the stencil, so its rise + from the centre is quadratic: four times as large at a full step as at a half + step, on each side. A factor of two either way (:data:`_ZDW_STENCIL_RATIO`) admits + a cubic term up to two thirds of the quadratic one at the full step. Each artefact + of a resonance fails it: a pole at the change (``beta1`` diverges, its rise does not + grow with the step), a stencil point on or across a line (the rise is lopsided, or + one-signed through the centre so ``beta1`` is monotone), and the evanescent floor + (``beta1`` constant, no rise). So does a feature narrower than the stencil. A + non-finite ``beta1`` fails every comparison. + """ + rise = delays - delays[2] + half, full = rise[[1, 3]], rise[[0, 4]] + if not half[0] * half[1] > 0.0: + return False + ratio = full / half + low, high = _ZDW_STENCIL_RATIO + return bool(np.all((ratio >= low) & (ratio <= high))) + + +def _is_line(delays: Float[np.ndarray, " 5"]) -> bool: + """Whether a sign change that is not a zero lies at a line, which blocks the search. + + - ``delays``: ``beta1`` across the stencil at the change (:func:`_stencil_delays`). + + At a line the group delay is not finite, or diverges, or drops to the evanescent + floor: it spreads across the stencil by more than :data:`_ZDW_LINE_SPREAD` of its + value at the change. A smooth feature, the dispersion of an absorption band or of + an antiresonant wall, leaves it finite and continuous, and light crosses it. + """ + spread = np.max(np.abs(delays - delays[2])) + return not spread <= _ZDW_LINE_SPREAD * abs(float(delays[2])) + + +def _is_isolated(mode: Mode, omega: float, z: float) -> bool: + """Whether a zero of `beta2` is its only one within the resolution scale. + + The analytic ``beta1`` is read at :data:`_ZDW_ISOLATION_SAMPLES` frequencies on + each side, out to a relative distance :data:`_ZDW_ISOLATION`, on a grid fixed + relative to the zero, so the answer does not depend on the search window. The zero + is isolated when ``beta1`` rises (or falls) monotonically from it on both sides: + an extremum with no other sign change of ``beta_2`` beside it. A value that is not + finite fails it. + """ + reach = _ZDW_ISOLATION * np.linspace(0.0, 1.0, _ZDW_ISOLATION_SAMPLES + 1) + delays = beta1(mode, omega * (1.0 + np.concatenate([-reach[::-1], reach[1:]])), z) + middle = _ZDW_ISOLATION_SAMPLES + # Steps outwards from the zero on each side, all of one sign at an extremum. + steps = np.concatenate([-np.diff(delays[: middle + 1]), np.diff(delays[middle:])]) + return bool(np.all(steps > 0.0) or np.all(steps < 0.0)) + + +def _zero_frequencies( + mode: Mode, z: float, lower: float, upper: float, near: float | None +) -> tuple[list[float], int]: + """Return the zeros of `beta2` in a frequency window, and its sign changes there. + + ``beta2`` is sampled at :data:`_ZDW_SAMPLES` frequencies evenly spaced across the + window and each sign change is refined (:func:`_refine_zero`); a sample that is + exactly zero between samples of opposite signs is a change too. A change is a zero + if ``beta1`` has a resolved extremum there (:func:`_is_zero`) and no other change + lies within the resolution scale (:func:`_is_isolated`). A change that is not a + zero is a line if ``beta1`` is not finite or not continuous across it + (:func:`_is_line`, or a bracket the refinement finds no finite change in); + anything else -- an unresolved or clustered change of a smooth feature -- is + passed over. With a reference frequency ``near``, the changes are taken outwards + from it and only the nearest zero is returned; the changes beyond a line on that + side are not taken: light at the reference cannot cross the line to reach them. A + change further than the best zero so far cannot beat it, which spares the dozens an + antiresonant fibre's resonances give. + + - ``lower``, ``upper``: the window, rad/s. + - ``near``: reference frequency, rad/s, or ``None`` for every zero. + - Returns: the zeros in rad/s, increasing, and the number of sign changes sampled. + """ + grid = np.linspace(lower, upper, _ZDW_SAMPLES) + zeros: list[float] = [] + # The nearest lines found below and above the reference, rad/s. + below, above = -math.inf, math.inf + # The window is probed, not answered: a model's range and dilute-scaling warnings + # are left to the caller's evaluation at the answer. The refinement converges onto + # a pole as readily as onto a zero, and a model may divide by zero exactly there. + with ( + warnings.catch_warnings(), + np.errstate(divide="ignore", invalid="ignore"), + ): + warnings.simplefilter("ignore", MaterialRangeWarning) + warnings.simplefilter("ignore", DiluteScalingWarning) + sampled = beta2(mode, grid, z) + # A sample that is exactly zero takes the sign of the last nonzero sample below + # it, so a zero that falls on a sample is a change in the interval above it and + # not two products of zero. One that only touches zero changes nothing. + signs = np.sign(sampled) + last = np.maximum.accumulate(np.where(signs != 0.0, np.arange(signs.size), 0)) + signs = signs[last] + changes = np.flatnonzero(signs[:-1] * signs[1:] < 0.0) + if near is not None: + # How near each bracket can bring a zero: 0 for one holding the reference. + reach = np.maximum.reduce( + [grid[changes] - near, near - grid[changes + 1], np.zeros(changes.size)] + ) + changes = changes[np.argsort(reach, kind="stable")] + for i in changes: + low, high = float(grid[i]), float(grid[i + 1]) + if near is not None: + best = min((abs(zero - near) for zero in zeros), default=math.inf) + if max(low - near, near - high) >= best: + break + if high <= below or low >= above: + continue + root = _refine_zero(mode, low, high, z) + delays = None if math.isnan(root) else _stencil_delays(mode, root, z) + if delays is None or not _is_zero(delays): + if near is not None and (delays is None or _is_line(delays)): + if low >= near: + above = low + elif high <= near: + below = high + continue + if _is_isolated(mode, root, z): + zeros.append(root) + if near is not None: + # The nearest; of two as near, the one found first. + zeros = sorted(zeros, key=lambda zero: abs(zero - near))[:1] + return sorted(zeros), int(changes.size) + + def zdw( mode: Mode, z: float = 0.0, *, - wavelength_limits: tuple[float, float] = (100e-9, 3e-6), + wavelength_limits: tuple[float, float] = (150e-9, 3e-6), + near: float | None = None, ) -> float: """Return the zero-dispersion wavelength of a mode. + A sampled search (``docs/guide/waveguides/mode-sets.md``): ``beta_2`` is read at + 512 frequencies evenly spaced across the window and each sign change is refined. + A change is a **zero** when the analytic group delay ``beta_1`` has an extremum + there that the difference behind ``beta_2`` resolves (its rise grows + quadratically across the difference's stencil, :data:`BETA2_RELATIVE_STEP` either + side) and when ``beta_1`` is monotone from it for 1.5 % in frequency on either + side, so that ``beta_2`` keeps each sign that far. A change that is not a zero is + a **line** when ``beta_1`` is not finite or not continuous across it -- it + diverges, or drops to the evanescent floor, by more than a tenth across the + stencil -- as at a gas resonance. Every other change is passed over, neither zero + nor line: a change the stencil does not resolve, or one of the clustered zeros of + a narrow feature that leaves ``beta_1`` finite and continuous, such as fused + silica's OH absorption bands near 1.38 and 2.7 um or the inside of an + antiresonant wall's resonance. So the search resolves dispersion regimes 1.5 % + wide and more, and its answer does not depend on the window, as long as the + window holds the zero. Two limits remain: two genuine zeros closer than 1.5 % (or + a zero within 1.5 % of another sign change) are passed over, and a zero and + another sign change inside one sample interval restore the sign and are both + missed. + Parameters ---------- mode : Mode @@ -338,10 +581,17 @@ def zdw( z : float, optional Position along the waveguide, m. wavelength_limits : tuple of float, optional - Shortest and longest wavelength in m to bracket the root in. Defaults to - 100 nm to 3 um. A bracket wider than the validity range of a - material model behind the mode makes that model warn, once per evaluation: - the ends are only probes, but they are still extrapolation. + Shortest and longest wavelength in m to search. Defaults to 150 nm to 3 um: + above the vacuum-ultraviolet lines of the noble gases (the longest, xenon's, + at 147 nm) and the absorption edge of fused silica, where a lossless solve + takes silica as transparent and finds zeros with no meaning. The window is + probed silently; the zero found is evaluated again, so one that lies outside + the validity range of a material model behind the mode warns. + near : float, optional + Reference wavelength in m, > 0, typically the pump's. The zero nearest it in + frequency is returned, among those no line separates from it: light at the + reference cannot cross a line to reach a zero beyond. ``None`` (the default) + takes every zero in the window, and refuses several. Returns ------- @@ -351,11 +601,13 @@ def zdw( Raises ------ ModeError - If the range is not ordered and positive. + If the range is not ordered and positive, if `near` is not a positive finite + wavelength, or if the window holds several zeros and `near` is ``None``: the + message lists them. NoZeroDispersionError - If ``beta_2`` does not change sign across it: a mode with no zero-dispersion - point in the window is a fact the caller has to see, not a missing value to - propagate. + If the search finds no zero in the window (on the side of the lines that + holds `near`, when it is given): a mode with no zero-dispersion point there is + a fact the caller has to see, not a missing value to propagate. Examples -------- @@ -370,26 +622,45 @@ def zdw( raise ModeError( f"wavelength_limits must be positive and ordered, got {wavelength_limits}" ) - lower = 2.0 * math.pi * C / longest - upper = 2.0 * math.pi * C / shortest - - def _dispersion(value: float) -> float: - """Return beta2 at one angular frequency, for the root finder. - - - ``value``: angular frequency in rad/s. - - Returns: ``beta_2`` in s^2/m. - """ - return float(beta2(mode, np.array([value]), z)[0]) - - at_lower, at_upper = _dispersion(lower), _dispersion(upper) - if at_lower * at_upper > 0.0: + if near is not None and not (math.isfinite(near) and near > 0.0): + raise ModeError(f"near must be a positive, finite wavelength in m, got {near}") + window = f"{shortest * 1e9:.4g}-{longest * 1e9:.4g} nm" + zeros, changes = _zero_frequencies( + mode, + z, + 2.0 * math.pi * C / longest, + 2.0 * math.pi * C / shortest, + None if near is None else 2.0 * math.pi * C / near, + ) + if not zeros: + sampled = f"{_ZDW_SAMPLES} samples over {window}" + if changes == 0: + found = f"beta2 does not change sign between the {sampled}" + elif near is None: + found = ( + f"beta2 changes sign {changes} times between the {sampled}, but none " + "is a zero: each is a line, an artefact of the differenced beta2 at " + "one, or one of the clustered zeros of a narrow feature" + ) + else: + found = ( + f"beta2 changes sign {changes} times between the {sampled}, but none " + f"is a zero between the lines nearest {near * 1e9:.4g} nm" + ) raise NoZeroDispersionError( - f"beta2 does not change sign over {shortest * 1e9:.4g}-" - f"{longest * 1e9:.4g} nm (it is {at_lower:.4g} and {at_upper:.4g} s^2/m at " - "the ends), so there is no zero-dispersion wavelength in that window" + f"{found}, so the search found no zero-dispersion wavelength there" + ) + if len(zeros) > 1: + listed = ", ".join( + f"{2.0 * math.pi * C / root * 1e9:.1f}" for root in reversed(zeros) + ) + raise ModeError( + f"beta2 has {len(zeros)} zeros over {window}, at {listed} nm; pass near= " + "a reference wavelength to choose the nearest, or narrow wavelength_limits" ) - root = brentq(_dispersion, lower, upper) - return 2.0 * math.pi * C / float(root) + # Outside the probing, so a zero beyond a material model's range warns. + beta(mode, np.array([zeros[0]]), z) + return 2.0 * math.pi * C / zeros[0] def loss_length( diff --git a/src/solprop/modes/capillary.py b/src/solprop/modes/capillary.py index 563b03818..13e6e0bc7 100644 --- a/src/solprop/modes/capillary.py +++ b/src/solprop/modes/capillary.py @@ -145,7 +145,7 @@ class MarcatiliTerms: core_susceptibility : numpy.ndarray Per-particle susceptibility ``gamma(omega)`` in m^3, so that ``chi = gamma * rho``. Mixtures carry shape ``(n_species, n_omega)``; - the existing single-gas spelling retains its frequency vector. Values are + a single gas carries shape ``(n_omega,)``. Values are real for transparent built-in gases and complex for absorbing custom species. dcore_susceptibility_domega : numpy.ndarray Its analytic frequency derivative in m^3 s/rad. @@ -257,6 +257,8 @@ class MarcatiliMode(GasFillMixin): The fill species, or ``None`` for an evacuated capillary. pressure : float or ZProfile Absolute pressure in **bar**, >= 0 (``docs/dev/conventions.md`` section 1). + Required beside `gas`: a gas without it is refused. Without a gas it is + omitted, and holds 0 once the mode is built. kind : str ``"HE"`` (hybrid), ``"TE"`` or ``"TM"``. The transverse families require ``n == 0``; hybrids require ``n != 0``. @@ -331,7 +333,7 @@ class MarcatiliMode(GasFillMixin): radius: float | ZProfile gas: Gas | str | None = None - pressure: float | ZProfile = 0.0 + pressure: float | ZProfile | None = None _: KW_ONLY kind: ModeKind = "HE" n: int = 1 @@ -382,7 +384,8 @@ def __post_init__(self) -> None: ModeError If the family and the azimuthal index disagree, the radial index is not positive, the model is unknown, ``alpha`` or ``loss_scale`` is invalid or - both are given, or the radius or temperature is not positive. + both are given, a gas comes without its pressure, or the radius or + temperature is not positive. """ self._check_arguments() # The transverse families sit on a zero of J_1; the hybrids on one of J_(n-1). @@ -413,7 +416,7 @@ def __repr__(self) -> str: """ if self.mixture is not None: # A mode the run interfaces build carries its fill as a mixture and no - # `gas`; before this branch it printed as evacuated. + # `gas`, so the mixture names the fill. fill = "+".join(self.mixture.labels) else: fill = "evacuated" if self.gas is None else str(self.gas) @@ -847,8 +850,8 @@ def _model_values( """Return ``n_eff - 1`` and ``dn_eff/domega`` before the loss specification. - ``radius``: core radius in m. - - ``density``: number density in m^-3, scalar for the existing gas spelling or - one entry per sampled mixture component. + - ``density``: number density in m^-3, scalar for a single gas or one entry + per sampled mixture component. - Returns: the refractivity and its derivative, with the model's own loss included. """ @@ -1142,10 +1145,10 @@ def dneff_dz( ``W = (u s)^2 (1 - i v s)^2``, ``s = c/(omega a)``, so that ``dW/da = -(2 u^2 s^2/a)(1 - i v s)(1 - 2 i v s)`` and ``dn/dz = (sum_s gamma_s rho_s' - (dW/da) a')/(2 n)``; the reduced model - differentiates its own polynomial. The loss specification acts on the - imaginary part exactly as it does on the index: ``False`` drops it, a float - scales it, a measured curve ``alpha(omega)`` does not depend on ``z`` and - contributes nothing, where the no-gain clamp binds the imaginary part's slope + differentiates its own polynomial. The loss declaration acts on the + imaginary part exactly as it does on the index: ``loss_scale`` scales it (0 + drops it), and an ``alpha`` replaces it and, having no ``z``, contributes + nothing; where the no-gain clamp binds the imaginary part's slope is zero, and where the evanescent floor binds the whole slope is zero, as :meth:`dneff_domega`'s is. What the coherent wall route reads is the real part, the slope of the power weight @@ -1430,7 +1433,7 @@ def _effective_area_factor(self) -> float: Keyed by ``id(mode)`` with the mode itself held beside its terms, so an id cannot be reused by another mode while the scope lasts; ``None`` outside a scope, where every -call samples afresh exactly as it always has.""" +call samples afresh.""" @contextmanager @@ -1443,7 +1446,7 @@ def shared_sampling() -> Iterator[None]: translation cost. Inside this scope :meth:`MarcatiliMode.sampled_terms` returns the terms it already built for the same mode and the same frequencies: the same function of the same inputs, so every array - built from them is bitwise what it was. The shared + built from them is bitwise the unshared one. The shared arrays are made read-only, so a caller that wrote into one would fail loudly rather than change what the next caller reads. diff --git a/src/solprop/modes/collection.py b/src/solprop/modes/collection.py index e657bdeb9..35f1fbb96 100644 --- a/src/solprop/modes/collection.py +++ b/src/solprop/modes/collection.py @@ -11,26 +11,24 @@ polarisation partners (:func:`polarisation_pairs`). :func:`transverse_measure` names the measure a set is integrated over. -:func:`overlap` integrates adaptively (:func:`scipy.integrate.dblquad`, or -:func:`scipy.integrate.quad` over x alone, per metre of y, for a slab set), and -:func:`orthonormality` integrates the whole matrix in one pass, adaptively in the first -coordinate with :func:`scipy.integrate.quad_vec` and on a rule refined to convergence -in the second -- both deliberately *not* on the fixed rule whose orthonormality they -check. They use the package normalisation (``docs/dev/conventions.md`` section 4), +:func:`orthonormality` integrates the whole matrix in one pass, adaptively in the +first coordinate with :func:`scipy.integrate.quad_vec` and on a rule refined to +convergence in the second, and :func:`overlap` is its entry for one pair -- +deliberately *not* on the fixed rule whose orthonormality they check. They use the +package normalisation (``docs/dev/conventions.md`` section 4), :math:`\langle m_1|m_2\rangle = \tfrac12\sqrt{\varepsilon_0/\mu_0}\int e_1^*\cdot e_2\,\mathrm{d}A / \sqrt{N_1N_2}`, so a mode overlaps itself by one. The manual page is ``docs/guide/waveguides/mode-sets.md``. """ import logging -import math -from collections.abc import Callable, Iterator, Sequence +from collections.abc import Iterator, Sequence from dataclasses import dataclass from typing import cast import numpy as np from jaxtyping import Float -from scipy.integrate import dblquad, quad, quad_vec +from scipy.integrate import quad_vec from solprop._display import Displayed from solprop.constants import EPS0, C @@ -48,8 +46,8 @@ Mode, TransverseMeasure, ) +from solprop.modes.quadrature import _normalisation, _shared_limits from solprop.modes.slab import SlabMode, SlabPolarisation -from solprop.modes.stepindex import StepIndexMode from solprop.physdata.gases import Gas from solprop.physdata.glasses import GlassIndex from solprop.physdata.mixtures import Mixture @@ -80,21 +78,6 @@ more: a set that needs more is refused.""" -def _normalisation(mode: Mode, z: float) -> float: - """Return a mode's closed-form normalisation. - - - ``z``: position along the waveguide, m. - - Returns: ``N`` in W. - """ - closed_form: Callable[[float], float] | None = getattr(mode, "normalisation", None) - if not callable(closed_form): - raise ModeError( - f"{type(mode).__name__} provides no normalisation(z), so its overlaps " - "cannot be normalised" - ) - return float(closed_form(z)) - - def overlap(first: Mode, second: Mode, z: float = 0.0) -> float: """Return the normalised overlap integral of two modes. @@ -108,15 +91,16 @@ def overlap(first: Mode, second: Mode, z: float = 0.0) -> float: Returns ------- float - ``1`` for a mode with itself and ``0`` for an orthogonal pair. Integrated - adaptively, not on the transform's fixed rule, so that the rule can be - checked against it. + ``1`` for a mode with itself and ``0`` for an orthogonal pair: the + off-diagonal entry of the pair's :func:`orthonormality`, to about ``1e-12``. + Integrated adaptively, not on the transform's fixed rule, so that the rule + can be checked against it. Raises ------ ModeError - If the modes do not share a cross-section, or either has no closed-form - normalisation. + If the modes do not share a cross-section, either has no closed-form + normalisation, or the integration does not converge. Examples -------- @@ -126,62 +110,7 @@ def overlap(first: Mode, second: Mode, z: float = 0.0) -> float: >>> f"{overlap(mode, mode):.9f}" '1.000000000' """ - limits = first.dimlimits(z) - if second.dimlimits(z) != limits: - raise ModeError( - f"an overlap needs one cross-section; {limits} and " - f"{second.dimlimits(z)} differ" - ) - kind, lower, upper = limits - # The scale goes inside the integrands: the integrals are then of order one, so - # the adaptive rules' default absolute tolerance is small against them. Outside, - # an unnormalised integral (2e-13 for a 75 um capillary's HE1,24) lies below - # that tolerance and the rule stops unconverged, without a warning. - scale = ( - 0.5 * EPS0 * C / math.sqrt(_normalisation(first, z) * _normalisation(second, z)) - ) - - def _integrand(inner: float, outer: float) -> float: - """Return the scaled product of the two profiles times the area element. - - - ``inner``: the first cross-section coordinate, ``r`` or ``x`` in m. dblquad - passes the *inner* variable first, which is why the order looks reversed. - - ``outer``: the second coordinate, ``theta`` in rad or ``y`` in m. - """ - point = np.array([[inner, outer]]) - product = scale * float(np.sum(first.field(point, z) * second.field(point, z))) - return product * inner if kind == "polar" else product - - if kind == "slab": - # Uniform in y: the overlap is per metre of y, over x alone, as N is. - return _overlap_along_x(first, second, (lower[0], upper[0]), z, scale) - # The outer variable is the second coordinate and the inner the first, with the - # polar Jacobian r folded into the integrand above. - value, _ = dblquad(_integrand, lower[1], upper[1], lower[0], upper[0]) - return value - - -def _overlap_along_x( - first: Mode, second: Mode, limits: tuple[float, float], z: float, scale: float -) -> float: - """Return the scaled integral over x of two slab profiles' product, per metre of y. - - - ``limits``: the gap's edges in m. - - ``z``: position along the waveguide, m. - - ``scale``: the overlap's normalisation, multiplied into the integrand. - - Returns: ``scale * int e_1 . e_2 dx``, integrated adaptively. - """ - - def along_x(x: float) -> float: - """Return the product of the two slab profiles at one x. - - - ``x``: transverse coordinate in m. - """ - point = np.array([[x, 0.0]]) - return scale * float(np.sum(first.field(point, z) * second.field(point, z))) - - value, _ = quad(along_x, limits[0], limits[1], limit=200) - return value + return float(orthonormality([first, second], z)[0, 1]) def orthonormality( @@ -232,14 +161,7 @@ def orthonormality( """ if not modes: raise ModeError("orthonormality needs at least one mode") - limits = modes[0].dimlimits(z) - for mode in modes[1:]: - if mode.dimlimits(z) != limits: - raise ModeError( - f"an overlap needs one cross-section; {limits} and " - f"{mode.dimlimits(z)} differ" - ) - kind, lower, upper = limits + kind, lower, upper = _shared_limits(modes, z) # Each mode's share of the overlap's normalisation, inside the integrand: the # integrals are then of order one, as the absolute tolerance assumes. scale = np.sqrt(0.5 * EPS0 * C / np.array([_normalisation(m, z) for m in modes])) @@ -440,7 +362,7 @@ def polarisation_pairs(modes: Sequence[Mode]) -> tuple[Mode, ...]: Raises ------ ModeError - If a mode cannot say whether it has a partner, which every ported mode can. + If a mode cannot say whether it has a partner. Examples -------- @@ -497,13 +419,7 @@ def __post_init__(self) -> None: raise ModeError("a mode collection needs at least one mode") transverse_measure(self.modes) self._validate_channels() - limits = self.modes[0].dimlimits(0.0) - for index, mode in enumerate(self.modes[1:], start=1): - if mode.dimlimits(0.0) != limits and not self._same_stepindex_guide(mode): - raise ModeError( - f"every mode in a collection must share a cross-section; mode " - f"{index} has {mode.dimlimits(0.0)} against {limits}" - ) + limits = _shared_limits(self.modes, 0.0) logger.debug( "mode collection of %d modes, %s, azimuthal order %d, full rule %s", len(self.modes), @@ -512,17 +428,6 @@ def __post_init__(self) -> None: self.needs_full_rule, ) - def _same_stepindex_guide(self, mode: Mode) -> bool: - """Check whether a channel shares the first physical guide.""" - first = self.modes[0] - return ( - isinstance(first, StepIndexMode) - and isinstance(mode, StepIndexMode) - and (first.radius is mode.radius or first.radius == mode.radius) - and first._core == mode._core - and first._cladding == mode._cladding - ) - def _validate_channels(self) -> None: """Reject two members that name the same physical channel. @@ -590,7 +495,7 @@ def he1m( cls, radius: float | ZProfile, gas: Gas | str | None = None, - pressure: float | ZProfile = 0.0, + pressure: float | ZProfile | None = None, *, count: int = 1, model: MarcatiliModel = "full", @@ -619,8 +524,9 @@ def he1m( Core radius, m, constant or along z. gas : Gas, str or None, optional Filling gas; None for vacuum or an explicit mixture. - pressure : float or ZProfile, optional - Fill pressure, bar, constant or along z; default zero. + pressure : float, ZProfile or None, optional + Fill pressure, bar, constant or along z; required beside `gas`, and + ``None`` without one. count : int, optional How many modes, at least one; the modes are HE_11 to HE_1count. model : {'full', 'reduced'}, optional @@ -686,7 +592,7 @@ def slab( cls, half_gap: float | ZProfile, gas: Gas | str | None = None, - pressure: float | ZProfile = 0.0, + pressure: float | ZProfile | None = None, *, orders: Sequence[int] = (1,), polarisation: SlabPolarisation = "te", @@ -713,8 +619,9 @@ def slab( Half the plate separation in m, constant or along z. gas : Gas, str or None, optional Filling gas; None for vacuum or an explicit mixture. - pressure : float or ZProfile, optional - Gas pressure in bar, constant or along z; default zero. + pressure : float, ZProfile or None, optional + Gas pressure in bar, constant or along z; required beside `gas`, and + ``None`` without one. orders : sequence of int, optional Mode orders ``p >= 1``, non-empty and without repeats, in state order; default the lowest order alone. @@ -780,7 +687,7 @@ def vincetti( cls, radius: float | ZProfile, gas: Gas | str | None = None, - pressure: float | ZProfile = 0.0, + pressure: float | ZProfile | None = None, *, count: int = 1, lattice: TubeLattice, @@ -802,8 +709,9 @@ def vincetti( Positive core radius in m, constant or along z. gas : Gas, str or None, optional Filling gas; None for vacuum or an explicit mixture. - pressure : float or ZProfile, optional - Gas pressure in bar, constant or along z; default zero. + pressure : float, ZProfile or None, optional + Gas pressure in bar, constant or along z; required beside `gas`, and + ``None`` without one. count : int, optional Number of modes, at least one, in radial order. lattice : TubeLattice @@ -858,7 +766,7 @@ def marcatili( cls, radius: float | ZProfile, gas: Gas | str | None = None, - pressure: float | ZProfile = 0.0, + pressure: float | ZProfile | None = None, *, kinds: Sequence[ModeKind], n: Sequence[int], @@ -879,8 +787,9 @@ def marcatili( Core radius, m, constant or along z. gas : Gas, str or None, optional Filling gas; None for vacuum or an explicit mixture. - pressure : float or ZProfile, optional - Fill pressure, bar, constant or along z; default zero. + pressure : float, ZProfile or None, optional + Fill pressure, bar, constant or along z; required beside `gas`, and + ``None`` without one. kinds : sequence of {'HE', 'TE', 'TM'} Family of each mode, non-empty. n : sequence of int @@ -1042,21 +951,7 @@ def dimlimits( >>> ModeCollection([MarcatiliMode(125e-6, "He", 1.0)]).dimlimits()[0] 'polar' """ - limits = self.modes[0].dimlimits(z) - for index, mode in enumerate(self.modes[1:], start=1): - if mode.dimlimits(z) != limits and self._same_stepindex_guide(mode): - other = mode.dimlimits(z) - limits = ( - limits[0], - limits[1], - (max(limits[2][0], other[2][0]), limits[2][1]), - ) - elif mode.dimlimits(z) != limits: - raise ModeError( - f"the modes disagree about the cross-section at z = {z}: mode " - f"{index} has {mode.dimlimits(z)} against {limits}" - ) - return limits + return _shared_limits(self.modes, z) @property def azimuthal_order(self) -> int: # numpydoc ignore=RT01 diff --git a/src/solprop/modes/fill.py b/src/solprop/modes/fill.py index 41d8c2a3b..061c6bbc9 100644 --- a/src/solprop/modes/fill.py +++ b/src/solprop/modes/fill.py @@ -95,6 +95,54 @@ def _sqrt1p_minus_one( """Relative step of the Richardson difference used for a loss curve with no slope.""" +def _alpha_values( + alpha: float | LossFunction, omega: Float[np.ndarray, " n_omega"] +) -> tuple[Float[np.ndarray, " n_omega"], Float[np.ndarray, " n_omega"]]: + """Return a mode's absolute power attenuation and its frequency slope, checked. + + The one evaluation of a declared ``alpha`` for every mode family that takes one. + A number is constant and was checked when the mode was built. A callable's values + are refused unless finite, non-negative (a negative attenuation is gain) and of + the shape of `omega`; its slope is its ``derivative`` attribute when it has one, + and otherwise a Richardson-extrapolated central difference at a relative step of + :data:`_FD_RELATIVE_STEP`, with a relative floor near 1e-10. + + - ``omega``: positive angular frequencies in rad/s. + - Returns: the attenuation in 1/m and its slope in s/(rad m). + """ + if not callable(alpha): + return ( + np.full_like(omega, float(alpha), dtype=float), + np.zeros_like(omega, dtype=float), + ) + attenuation = np.asarray(alpha(omega), dtype=float) + if ( + attenuation.shape != omega.shape + or not np.all(np.isfinite(attenuation)) + or np.any(attenuation < 0.0) + ): + raise ModeError( + "alpha callable must return finite non-negative coefficients with the " + "shape of omega" + ) + analytic = getattr(alpha, "derivative", None) + if callable(analytic): + slope = np.asarray(analytic(omega), dtype=float) + else: + step = _FD_RELATIVE_STEP * omega + wide = (np.asarray(alpha(omega + step)) - np.asarray(alpha(omega - step))) / ( + 2.0 * step + ) + half = step / 2.0 + narrow = (np.asarray(alpha(omega + half)) - np.asarray(alpha(omega - half))) / ( + 2.0 * half + ) + slope = np.asarray((4.0 * narrow - wide) / 3.0, dtype=float) + if slope.shape != omega.shape or not np.all(np.isfinite(slope)): + raise ModeError("alpha derivative must be finite with the shape of omega") + return attenuation, slope + + class GasFillMixin(Displayed): """Provide material and loss methods for frozen hollow-mode dataclasses. @@ -112,7 +160,7 @@ class GasFillMixin(Displayed): """ gas: Gas | str | None - pressure: float | ZProfile + pressure: float | ZProfile | None temperature: float | ZProfile | None susceptibility: GasSusceptibility | None mixture: Mixture | None @@ -122,6 +170,11 @@ class GasFillMixin(Displayed): model: Literal["full", "reduced"] _gain_warned: bool + @property + def _pressure_profile(self) -> ZProfile: + """The fill pressure in bar along z; never ``None`` once constructed.""" + return as_profile(cast("float | ZProfile", self.pressure)) + @property def _lossless(self) -> bool: """Whether the mode is declared lossless: no ``alpha`` and a zero scale.""" @@ -158,7 +211,7 @@ def _fill_text(self) -> str: return f"{labels} {float(shared(entrance)[0]):g} bar" if self.gas is None: return "evacuated" - return f"{self.gas} {float(as_profile(self.pressure)(entrance)[0]):g} bar" + return f"{self.gas} {float(self._pressure_profile(entrance)[0]):g} bar" def _check_fill_arguments(self) -> None: """Check the fill declaration and loss specification.""" @@ -190,13 +243,23 @@ def _check_fill_arguments(self) -> None: if self.mixture is not None and ( self.gas is not None - or self.pressure != 0.0 + or (self.pressure is not None and self.pressure != 0.0) or self.susceptibility is not None ): raise ModeError( "mixture carries its gas, pressure and susceptibility; " "omit those arguments" ) + if self.pressure is None: + if self.gas is not None: + msg = ( + f"a gas fill needs its pressure: pass pressure= in bar beside " + f"gas={self.gas!r}, or omit the gas for an evacuated guide" + ) + raise ModeError(msg, parameter="pressure") + # No gas: an evacuated guide, or a mixture's own paths. No pressure + # applies, and the field holds zero bar. + object.__setattr__(self, "pressure", 0.0) def _check_loss_arguments(self) -> None: """Check ``loss_scale`` and ``alpha``, alone and against each other.""" @@ -245,7 +308,7 @@ def _resolve_fill(self) -> None: object.__setattr__( self, "susceptibility", default_species(self.gas).susceptibility ) - pressure = as_profile(self.pressure) + pressure = self._pressure_profile temperature = cast("float | ZProfile", self.temperature) # The gas whose equation of state, and whose flow weight, the fill takes. material: Species | None = ( @@ -309,9 +372,10 @@ def absorption_by_species( Raises ------ ModeError - If omega is non-positive or non-finite, or the mode declares an + If omega is non-positive or non-finite, the mode declares an ``alpha``, whose total attenuation cannot be assigned to individual - species. + species, or a single gas's susceptibility is absorbing (a mixture + component attributes it). """ if np.any(omega <= 0) or not np.all(np.isfinite(omega)): raise ModeError("species absorption requires positive finite omega") @@ -336,10 +400,18 @@ def absorption_by_species( scale * density * omega * np.imag(model.susceptibility(omega)) / C ) return result - if self.susceptibility is None: - return np.zeros((1, omega.size)) - # The single-gas slot carries a real GasSusceptibility. Absorbing supplied - # optical tables belong to explicit Species components of a mixture. + # Per-species attribution is the mixture's: an absorbing law in the + # single-gas slot puts loss into neff, which this row would not show. + if ( + scale != 0 + and self.susceptibility is not None + and self.susceptibility.absorbing + ): + msg = ( + "an absorbing susceptibility on a single gas has no species " + "attribution; declare the gas as a component of a Mixture" + ) + raise ModeError(msg) return np.zeros((1, omega.size)) def _fill_paths(self) -> Mapping[str, ZProfile]: @@ -541,12 +613,7 @@ def _apply_loss( # An absolute power loss coefficient: alpha = 2 omega Im(n) / c, so # Im n = c alpha / (2 omega) and its derivative follows by the quotient rule. # Only the imaginary part is replaced; beta and beta_1 stay analytic. - if callable(self.alpha): - alpha = np.asarray(self.alpha(omega), dtype=float) - dalpha = self._loss_derivative(self.alpha, omega) - else: - alpha = np.full_like(omega, float(self.alpha), dtype=float) - dalpha = np.zeros_like(omega, dtype=float) + alpha, dalpha = _alpha_values(self.alpha, omega) extinction = 0.5 * C * alpha / omega dextinction = 0.5 * C * (dalpha * omega - alpha) / omega**2 return ( @@ -589,30 +656,6 @@ def _no_gain( np.asarray(np.where(gain, np.real(derivative), derivative), dtype=complex), ) - def _loss_derivative( - self, curve: LossFunction, omega: Float[np.ndarray, " n_omega"] - ) -> Float[np.ndarray, " n_omega"]: - """Return the frequency derivative of an attenuation supplied as a callable. - - - ``curve``: the loss curve ``alpha(omega)`` in 1/m. - - ``omega``: angular frequencies in rad/s. - - Returns: ``d(alpha)/d(omega)`` in 1/(m rad/s), analytic when the callable - carries a ``derivative`` attribute and otherwise a Richardson-extrapolated - central difference with a relative floor near 1e-10. - """ - analytic = getattr(curve, "derivative", None) - if callable(analytic): - return np.asarray(analytic(omega), dtype=float) - step = _FD_RELATIVE_STEP * omega - wide = (np.asarray(curve(omega + step)) - np.asarray(curve(omega - step))) / ( - 2.0 * step - ) - half = step / 2.0 - narrow = (np.asarray(curve(omega + half)) - np.asarray(curve(omega - half))) / ( - 2.0 * half - ) - return np.asarray((4.0 * narrow - wide) / 3.0, dtype=float) - def _floored( self, refractivity: Complex[np.ndarray, " n_omega"], diff --git a/src/solprop/modes/guide.py b/src/solprop/modes/guide.py index 924737734..a4ceb0184 100644 --- a/src/solprop/modes/guide.py +++ b/src/solprop/modes/guide.py @@ -1148,8 +1148,7 @@ def from_provider( then taken at the entrance, which is the provider's own z domain start, and each channel carries its index and area along the path (:class:`ModalPath`, :attr:`ProviderChannelMode.path`). A guide whose - geometry does not move is a **snapshot at one position** and is bitwise what - it was. + geometry does not move is a **snapshot at one position**, with no path. Parameters ---------- @@ -1185,14 +1184,14 @@ def from_provider( name. The guide's channels then carry the declaration's labels -- handedness rather than parity -- and its ``ProviderChannelMode`` rows carry the transformed channels' surrogate areas. ``None`` keeps the - provider's own coordinates, and the guide is then bitwise what it was. + provider's own coordinates and applies no transformation. beta_rtol : float, optional Budget on the two propagation-constant checks, default :data:`PROVIDER_BETA_RTOL`. sections : int, optional Sections each kink interval of a moving guide is divided into, positive; - one by default. Ignored by nothing: a snapshot refuses any other value, - because it has no path to divide. + one by default. A snapshot refuses any other value, because it has no + path to divide. path_rtol : float or None, optional Budget on a moving guide's held-out departure along z; ``None`` takes the frequency interpolation's own measured profile error, floored at diff --git a/src/solprop/modes/protocol.py b/src/solprop/modes/protocol.py index ee60fc895..a3a898f9f 100644 --- a/src/solprop/modes/protocol.py +++ b/src/solprop/modes/protocol.py @@ -510,7 +510,7 @@ class ParameterisedMode(Mode, Protocol): A mode whose declared paths are **not** the whole of its z dependence says so with the optional ``parameters_own_z`` trait, which :func:`solprop.translate.linop.parameters_own_z` reads by name. It defaults to - ``True`` -- what every mode written before the trait existed implied -- and a mode + ``True`` -- the declared paths are the mode's whole z dependence -- and a mode that reports ``False`` keeps the translation layer on the z table instead of an expansion its parameters cannot reproduce. The case is a :class:`solprop.nonlinear.gnlse.SpecifiedMode` whose dispersion follows a path diff --git a/src/solprop/modes/quadrature.py b/src/solprop/modes/quadrature.py index fd3f1835d..3335ea950 100644 --- a/src/solprop/modes/quadrature.py +++ b/src/solprop/modes/quadrature.py @@ -54,6 +54,7 @@ from solprop.exceptions import ModeError from solprop.modes.capillary import MarcatiliMode from solprop.modes.protocol import CrossSection, Mode +from solprop.modes.stepindex import StepIndexMode __all__ = [ "BASIS_NORMALISATION", @@ -1440,15 +1441,7 @@ def mode_matrix( f"components must be a non-empty subset of {_COMPONENTS}, got " f"{tuple(components)}" ) - limits = modes[0].dimlimits(z) - # islice rather than a slice, because a mode set may be an ordered collection whose - # indexing is by position only. - for mode in itertools.islice(modes, 1, None): - if mode.dimlimits(z) != limits: - raise ModeError( - "every mode in a set must share a cross-section; " - f"{limits} and {mode.dimlimits(z)} differ" - ) + limits = _shared_limits(modes, z) points = quadrature.nodes(limits) weights = quadrature.weights(limits) coarse = quadrature.weights(limits, coarse=True) @@ -1472,6 +1465,41 @@ def mode_matrix( ) +def _shared_limits( + modes: Sequence[Mode], z: float +) -> tuple[CrossSection, tuple[float, ...], tuple[float, ...]]: + """Return the one cross-section of a mode set at a position, or refuse the set. + + Every mode's ``dimlimits`` must agree, except among step-index channels of one + guide (:meth:`solprop.modes.stepindex.StepIndexMode.same_guide`): each bounds the + cladding at its own outer radius, where its evanescent field has decayed, and the + set takes the widest, over which every channel's field is still exact. + + - ``modes``: non-empty. + - ``z``: position along the waveguide, m. + """ + first = modes[0] + limits = first.dimlimits(z) + # islice rather than a slice, because a mode set may be an ordered collection whose + # indexing is by position only. + for index, mode in enumerate(itertools.islice(modes, 1, None), start=1): + other = mode.dimlimits(z) + if other == limits: + continue + if isinstance(first, StepIndexMode) and first.same_guide(mode): + limits = ( + limits[0], + limits[1], + (max(limits[2][0], other[2][0]), limits[2][1]), + ) + continue + raise ModeError( + f"the modes do not share a cross-section at z = {z:g} m: mode {index} has " + f"{other} against {first.dimlimits(z)}" + ) + return limits + + def _normalisation(mode: Mode, z: float) -> float: """Return the power carried by a mode's unnormalised transverse profile. diff --git a/src/solprop/modes/rectangular.py b/src/solprop/modes/rectangular.py index 34abd01c6..168d64541 100644 --- a/src/solprop/modes/rectangular.py +++ b/src/solprop/modes/rectangular.py @@ -421,6 +421,8 @@ class RectMode(_WallPairFill): The fill gas; None means vacuum unless a mixture is supplied. pressure : float or ZProfile Absolute fill pressure in **bar**, non-negative, or a path of it along z. + Required beside `gas`: a gas without it is refused. Without a gas it is + omitted, and holds 0 once the mode is built. n, m : int Positive mode indices along y and x respectively. polarisation : {'x', 'y'} @@ -473,7 +475,7 @@ class RectMode(_WallPairFill): half_width_x: float | ZProfile half_width_y: float | ZProfile gas: Gas | str | None = None - pressure: float | ZProfile = 0.0 + pressure: float | ZProfile | None = None _: KW_ONLY n: int = 1 m: int = 1 diff --git a/src/solprop/modes/slab.py b/src/solprop/modes/slab.py index a9aff2987..062d548fd 100644 --- a/src/solprop/modes/slab.py +++ b/src/solprop/modes/slab.py @@ -107,6 +107,8 @@ class SlabMode(_WallPairFill): The fill gas; None means vacuum unless a mixture is supplied. pressure : float or ZProfile Absolute fill pressure in **bar**, non-negative, or a path of it along z. + Required beside `gas`: a gas without it is refused. Without a gas it is + omitted, and holds 0 once the mode is built. order : int Mode order ``p >= 1``; odd orders are symmetric about the mid-plane, so a centred launch couples only to them. @@ -168,7 +170,7 @@ class SlabMode(_WallPairFill): half_gap: float | ZProfile gas: Gas | str | None = None - pressure: float | ZProfile = 0.0 + pressure: float | ZProfile | None = None _: KW_ONLY order: int = 1 polarisation: SlabPolarisation = "te" diff --git a/src/solprop/modes/stepindex.py b/src/solprop/modes/stepindex.py index 27bb43a10..ee434fba2 100644 --- a/src/solprop/modes/stepindex.py +++ b/src/solprop/modes/stepindex.py @@ -22,7 +22,7 @@ from dataclasses import KW_ONLY, dataclass, field, replace from functools import cache, cached_property from types import MappingProxyType -from typing import Literal +from typing import Literal, cast import numpy as np from jaxtyping import Complex, Float @@ -34,7 +34,7 @@ from solprop._display import Displayed, engineering, line from solprop.constants import EPS0, C from solprop.exceptions import ModeError -from solprop.modes.fill import LossFunction +from solprop.modes.fill import LossFunction, _alpha_values from solprop.modes.protocol import ChannelLabel, CrossSection from solprop.physdata.glasses import GlassIndex, fused_silica, lossless_index from solprop.profiles import ZProfile, as_profile @@ -646,11 +646,29 @@ def _cutoff(kind: _Kind, n: int, m: int, ratio: float) -> float: @dataclass(frozen=True, eq=False, kw_only=True) class _ApertureIndex(GlassIndex): - """Implement the numerical-aperture core index and its material slope.""" + """Implement the numerical-aperture core index and its material slope. + + Compared by the index it computes, its cladding law and aperture, so that two + channels built for one fibre share a guide (:meth:`StepIndexMode.same_guide`). + """ cladding: GlassIndex | float numerical_aperture: float + def __eq__(self, other: object) -> bool: + """Compare two aperture indices by cladding law and numerical aperture.""" + if type(other) is not type(self): + return NotImplemented + aperture = cast("_ApertureIndex", other) + return (self.cladding, self.numerical_aperture) == ( + aperture.cladding, + aperture.numerical_aperture, + ) + + def __hash__(self) -> int: + """Hash as :meth:`__eq__` compares.""" + return hash((self.cladding, self.numerical_aperture)) + def _index_and_derivative( self, omega: Float[np.ndarray, "*shape"] ) -> tuple[Complex[np.ndarray, "*shape"], Complex[np.ndarray, "*shape"]]: @@ -944,6 +962,44 @@ def from_numerical_aperture( alpha=alpha, ) + def same_guide(self, other: object) -> bool: + """Return whether another mode is a channel of this mode's physical guide. + + Each channel bounds the cladding at its own outer radius, where its evanescent + field has decayed, so two channels of one fibre have different + ``dimlimits``; one guide means the same core radius and the same core and + cladding index laws. A set of such channels shares the widest of their discs + (:meth:`solprop.modes.collection.ModeCollection.dimlimits`). + + Parameters + ---------- + other : object + Another mode. + + Returns + ------- + bool + Whether `other` is a :class:`StepIndexMode` of the same radius, core and + cladding. + + Examples + -------- + >>> from solprop.modes import StepIndexMode + >>> one, two = ( + ... StepIndexMode(10e-6, core=1.46, cladding=1.44, m=m, + ... profile_wavelength=1e-6) + ... for m in (1, 2) + ... ) + >>> one.same_guide(two) + True + """ + return ( + isinstance(other, StepIndexMode) + and (self.radius is other.radius or self.radius == other.radius) + and self._core == other._core + and self._cladding == other._cladding + ) + def _radius(self, z: float) -> float: """Evaluate and validate the radius at every requested position. @@ -1038,40 +1094,6 @@ def _loss_text(self) -> str: return "alpha(omega)" return "none" if self.alpha == 0 else f"alpha {self.alpha:g} 1/m" - def _alpha_values( - self, omega: Float[np.ndarray, " n_omega"] - ) -> tuple[Float[np.ndarray, " n_omega"], Float[np.ndarray, " n_omega"]]: - """Return absolute power attenuation and its slope. - - - ``omega``: positive angular frequencies in rad/s. - - Returns: attenuation in 1/m and its derivative in s/(rad m). - """ - if not callable(self.alpha): - return np.full_like(omega, self.alpha), np.zeros_like(omega) - attenuation = np.asarray(self.alpha(omega), dtype=float) - if ( - attenuation.shape != omega.shape - or not np.all(np.isfinite(attenuation)) - or np.any(attenuation < 0) - ): - raise ModeError( - "alpha callable must return finite non-negative coefficients " - "with the shape of omega" - ) - analytic = getattr(self.alpha, "derivative", None) - if callable(analytic): - slope = np.asarray(analytic(omega), dtype=float) - else: - # Same fourth-order difference and step as the existing absolute-loss - # path; the lossless eigenvalue derivative is always analytic. - step, curve = omega * 1e-5, self.alpha - wide = (curve(omega + step) - curve(omega - step)) / (2 * step) - narrow = (curve(omega + step / 2) - curve(omega - step / 2)) / step - slope = (4 * narrow - wide) / 3 - if slope.shape != omega.shape or not np.all(np.isfinite(slope)): - raise ModeError("alpha derivative must be finite with the shape of omega") - return attenuation, slope - def neff( self, omega: ArrayLike | float, z: float = 0.0 ) -> Complex[np.ndarray, " n_omega"]: @@ -1095,7 +1117,7 @@ def neff( If inputs are invalid or any frequency is below cutoff. """ values = _checked_omega(omega) - attenuation, _ = self._alpha_values(values) + attenuation, _ = _alpha_values(self.alpha, values) return np.asarray( self._eigenpairs(values, z)[0] + 0.5j * C * attenuation / values ) @@ -1175,7 +1197,7 @@ def dneff_domega( if partial_index == 0 or not math.isfinite(float(partial_index)): raise ModeError("eigenvalue derivative is singular") slope[row] = -partial_frequency / partial_index - attenuation, dattenuation = self._alpha_values(values) + attenuation, dattenuation = _alpha_values(self.alpha, values) result = np.asarray( slope + 0.5j * C * (dattenuation * values - attenuation) / values**2 ) @@ -1228,7 +1250,15 @@ def channel_label(self) -> ChannelLabel: # numpydoc ignore=RT01 @property def azimuthal_order(self) -> int: # numpydoc ignore=RT01 - """Azimuthal mode index n.""" + """Azimuthal mode index n. + + This departs from the :class:`~solprop.modes.protocol.Mode` definition, + the highest harmonic of the profile: the Cartesian components of ``HE_nm`` + and ``EH_nm`` carry harmonics up to ``n + 1``, and those of ``TE_0m`` and + ``TM_0m`` up to 1. A rule sized from it alone is too small; + :meth:`~solprop.modes.stepindex_vector.StepIndexProvider.node_rule` sizes + its own polar rule from ``n + 1``. + """ return self.n def principal_component(self, z: float = 0.0) -> None: @@ -1558,7 +1588,7 @@ def electromagnetic_field( omega, z = float(omega), float(z) # A public boundary owes its caller a ModeError, not the AttributeError a - # list of pairs used to raise on the first `.ndim` inside the field helper. + # list of pairs raises on the first `.ndim` inside the field helper. points = np.asarray(xy, dtype=float) if points.ndim != 2 or points.shape[1] != 2: raise ModeError( diff --git a/src/solprop/modes/stepindex_vector.py b/src/solprop/modes/stepindex_vector.py index 8eae9e349..3f11035b9 100644 --- a/src/solprop/modes/stepindex_vector.py +++ b/src/solprop/modes/stepindex_vector.py @@ -31,6 +31,7 @@ from solprop.constants import EPS0, C from solprop.exceptions import ModeError from solprop.modes.collection import ModeCollection +from solprop.modes.fill import _alpha_values from solprop.modes.material import JsonValue, MaterialRegion from solprop.modes.stepindex import ( PROFILE_MIN_W, @@ -152,7 +153,7 @@ def _field_parameters(mode: StepIndexMode, omega: float, z: float) -> _FieldPara if not np.isfinite(omega) or omega <= 0 or not np.isfinite(z): raise ModeError("omega must be positive and z finite") frequency = np.array([omega], dtype=float) - if np.any(mode._alpha_values(frequency)[0] != 0): + if np.any(_alpha_values(mode.alpha, frequency)[0] != 0): raise ModeError( "leaky or attenuating E/H modes are unqualified: bound lossless fields only" ) @@ -444,9 +445,7 @@ def __post_init__(self) -> None: If the channels or material ownership are inconsistent. """ ModeCollection(self.modes) - if any( - not ModeCollection(self.modes)._same_stepindex_guide(m) for m in self.modes - ): + if any(not self.modes[0].same_guide(mode) for mode in self.modes): raise ModeError("step-index channels must share one physical guide") if len(self.regions) != 2 or self.regions[-1].outer_radius is not None: raise ModeError("step-index provider requires core and unbounded cladding") diff --git a/src/solprop/modes/tables.py b/src/solprop/modes/tables.py index c7c7f0479..5e8443662 100644 --- a/src/solprop/modes/tables.py +++ b/src/solprop/modes/tables.py @@ -321,8 +321,8 @@ def composed_gauge(gauge_id: str, basis: ChannelBasis | None) -> str: applied **after** it, so the composed transform is ``T_track U`` and the composed identity is ``"<tracking gauge>+<basis gauge>"``. That order is what a resume has to reproduce, and it is the one that leaves a run with no declared - basis bitwise what it was: the tracking is untouched and the declaration is a - second, independent step on top of it. + basis on the tracking alone: the declaration is a second, independent step on + top of it. Parameters ---------- @@ -924,8 +924,8 @@ def sample_modal_table( block it acts inside must be one of `degenerate_blocks`: tracking rotates freely inside a declared block, so a transform of a block the tracking did not know about would be applied on top of an ordering the eigenvalues - cannot resolve. ``None`` keeps the provider's own coordinates, and then - this function is bitwise what it was. + cannot resolve. ``None`` keeps the provider's own coordinates and applies + no transformation. gram_atol : float, optional Budget on each knot's sampled Gram defect, default :data:`DEFAULT_GRAM_ATOL`; the table refuses a basis above it. @@ -994,7 +994,7 @@ def sample_modal_table( rows.append(tuple(row)) if basis is not None: # After the tracking, never inside it: the composed transform is - # `T_track U` and a run with no declared basis is bitwise what it was. + # `T_track U`, and a run with no declared basis has the tracking alone. rows = [tuple(apply_channel_basis(one, basis) for one in row) for row in rows] return DenseModalTable(omega, z, tuple(rows), nodes, blocks, gram_atol, basis) diff --git a/src/solprop/modes/tabulated.py b/src/solprop/modes/tabulated.py index 49de696a9..0fce0c4bd 100644 --- a/src/solprop/modes/tabulated.py +++ b/src/solprop/modes/tabulated.py @@ -490,7 +490,8 @@ def __repr__(self) -> str: low, high = self.wavelength_range return ( f"IndexTable({np.asarray(self.omega).size} rows, " - f"{low * 1e9:g}-{high * 1e9:g} nm, loss={self.loss_interpolation})" + f"{low * 1e9:g}-{high * 1e9:g} nm, " + f"loss_interpolation={self.loss_interpolation})" ) @@ -585,16 +586,12 @@ def _describe(self) -> tuple[str, list[tuple[str, object]]]: return title, [*kept, ("table", repr(self.table))] def __repr__(self) -> str: - """Return the mode, geometry, fill and table support.""" + """Return the mode, geometry, fill, loss and table support.""" radius = float(self.core_radius(np.array([0.0]))[0]) - fill = ( - repr(self.mixture) - if self.mixture is not None - else f"{self.gas}, pressure={self.pressure!r}" - ) return ( f"{type(self).__name__}({self.kind}{self.n}{self.m}, " - f"a={radius * 1e6:g} um, {fill}, {self.table!r})" + f"a={radius * 1e6:g} um, {self._fill_text()}, loss={self._loss_text()}, " + f"{self.table!r})" ) @@ -745,8 +742,8 @@ def absorption_by_species( class _SampledIndexTable(IndexTable): """Retain sampled dispersion derivatives and snapshot provenance. - ``repr=False``: a regenerated dataclass ``__repr__`` dumped 809 characters of - arrays and undid :class:`IndexTable`'s one-line description. + ``repr=False``: a generated dataclass ``__repr__`` would print the arrays in + place of :class:`IndexTable`'s one-line description. - ``omega``: positive finite angular frequencies in rad/s, shape ``(n_nodes,)``. - ``area``: positive finite effective areas in m^2 at the same samples. diff --git a/src/solprop/monitor.py b/src/solprop/monitor.py index 30463a0f8..f1f68108f 100644 --- a/src/solprop/monitor.py +++ b/src/solprop/monitor.py @@ -767,20 +767,11 @@ def resume( ] self._collar_max = _number(record, "collar_max", 0.0) self._raw_removed = _number(record, "raw_removed_fraction", 0.0) - # The floor's expected removal, uncapped; a record from before it was kept - # gives it back from the signed or the reported removal. - judged = _number(record, "removed_signed", math.nan) - if not math.isfinite(judged): - judged = _number(record, "removed_fraction", 0.0) - self._floor_removed = _number( - record, "floor_removed_fraction", self._raw_removed - judged + self._floor_removed = _number(record, "floor_removed_fraction", 0.0) + self._restored_quiet = ( + _count(_number(record, "quiet_checks", 0.0), "quiet_checks"), + bool(record.get("collar_quiet", False)), ) - quiet_checks = _number(record, "quiet_checks", math.nan) - if math.isfinite(quiet_checks): - self._restored_quiet = ( - _count(quiet_checks, "quiet_checks"), - bool(record.get("collar_quiet", False)), - ) self._raw_guard_max = _number(record, "raw_guard_max", 0.0) self._steps = _count(_number(record, "steps", 0.0), "steps") self._skipped = _count(_number(record, "skipped", 0.0), "skipped") @@ -983,7 +974,7 @@ def due(self, z: float) -> bool: """ if self._busy or self._since_check + 1 >= CADENCE: return True - return self._last is None or z - self._last[0] >= self.interval + return self._last is None or bool(z - self._last[0] >= self.interval) def skip(self, z: float) -> None: """Count a committed step that is not checked. @@ -1046,6 +1037,8 @@ def watch_policy(self) -> dict[str, object]: def watch_state(self) -> dict[str, object]: """Return what a compiled march's predictions read and change of this monitor. + For tests: the native march keeps its own copy, which they compare with this. + Returns ------- dict diff --git a/src/solprop/noise.py b/src/solprop/noise.py index 25e6b5edf..6339b3151 100644 --- a/src/solprop/noise.py +++ b/src/solprop/noise.py @@ -368,10 +368,9 @@ def transformed_noise( **What is conserved and what is not.** ``sum_m |d_m|^2 = c.H U U.H c = sum_n |c_n|^2`` for a unitary ``U``, so the **total** photon number in each bin is exactly what it was; the per-channel numbers are redistributed, and the moduli - are no longer all equal. That is the physics the A2 companion names -- "fixed - modulus random phases are not invariant in distribution under arbitrary unitary - mixing" -- and it is why the draw is made once, in the basis it is defined in, - rather than again in each basis a run chooses. + are no longer all equal: fixed-modulus random phases are not invariant in + distribution under an arbitrary unitary mixing. That is why the draw is made once, + in the basis it is defined in, rather than again in each basis a run chooses. Parameters ---------- diff --git a/src/solprop/nonlinear/ionisation.py b/src/solprop/nonlinear/ionisation.py index 5ec373564..63a88a3a1 100644 --- a/src/solprop/nonlinear/ionisation.py +++ b/src/solprop/nonlinear/ionisation.py @@ -35,6 +35,7 @@ from numpy.typing import ArrayLike from scipy import integrate +from solprop._validation import positive from solprop.constants import AU_EFIELD, AU_ENERGY, AU_TIME, C from solprop.exceptions import GridError, MaterialError from solprop.physdata.gases import Gas, as_gas @@ -232,8 +233,7 @@ def rate_energy(rate: EvaluableRate) -> tuple[str, float] | None: A rate that carries its own energy per event (SEP 3, D8: the loss uses the energy the rate's exponent uses, :class:`solprop.nonlinear.optmat_rates.OptmatRate`) declares it as ``plasma_energy`` beside its ``species_identity``. Every other rate - declares none, and its response takes the species' ionisation potential, as - before. + declares none, and its response takes the species' ionisation potential. Parameters ---------- @@ -386,7 +386,7 @@ def keldysh( >>> f"{keldysh('Ar', 800e-9, 5e10):.3f}" '0.630' """ - _validate_positive("wavelength", wavelength) + positive(wavelength, "wavelength", MaterialError, reject_bool=True) ip_au = ionisation_potential(gas) / AU_ENERGY omega0_au = 2.0 * math.pi * C / wavelength * AU_TIME field = _finite_field(field_amplitude) @@ -503,7 +503,7 @@ def __post_init__(self) -> None: return # The annotation refuses another rule first wherever the annotations are # checked at run time, as in the test suite. - if self.policy != "band": # pragma: no cover + if self.policy != "band": # pragma: no cover - its annotation refuses it first msg = f"integration must be 'band' or 'trapezoid', got {self.policy!r}" raise GridError(msg) for name in ("dt", "band_edge"): @@ -736,7 +736,7 @@ def ionisation_fraction( >>> f"{fraction[-1]:.4f}" '0.2148' """ - _validate_positive("dt", dt) + positive(dt, "dt", MaterialError, reject_bool=True) if not 0.0 <= preionisation <= 1.0: msg = f"preionisation must be in [0, 1], got {preionisation!r}" raise MaterialError(msg) @@ -745,13 +745,6 @@ def ionisation_fraction( return 1.0 - (1.0 - preionisation) * np.exp(-exposure) -def _validate_positive(name: str, value: float) -> None: - """Raise unless ``value`` is a positive, finite number.""" - if not math.isfinite(value) or value <= 0.0: - msg = f"{name} must be positive and finite, got {value!r}" - raise MaterialError(msg) - - def _finite_field(field_amplitude: ArrayLike | float) -> Float[np.ndarray, " *shape"]: """Return ``|field_amplitude|`` as a float array, rejecting anything not finite. diff --git a/src/solprop/nonlinear/normalisation.py b/src/solprop/nonlinear/normalisation.py index a4e39dd63..dfc128f4f 100644 --- a/src/solprop/nonlinear/normalisation.py +++ b/src/solprop/nonlinear/normalisation.py @@ -134,7 +134,8 @@ def uppe_prefactor( Returns ------- numpy.ndarray - The prefactor in m/(V s) per unit polarisation, purely imaginary, shape + The prefactor in V/C, the unit of ``omega / (eps0 c)``: times a polarisation + in C/m^2 it gives a field's rate in V/m per m. Purely imaginary, shape ``(n_omega,)``. Raises diff --git a/src/solprop/nonlinear/optmat_raman.py b/src/solprop/nonlinear/optmat_raman.py index 90d68b4ae..15ed445ef 100644 --- a/src/solprop/nonlinear/optmat_raman.py +++ b/src/solprop/nonlinear/optmat_raman.py @@ -931,7 +931,7 @@ def _assemble( if entry.status == "provisional" and request.selection.raman != "provisional": msg = ( f"{request.where}: optmat's Raman response {entry.name} is provisional " - f"({entry.status_reason}). It is admitted only with " + f"({entry.status_reason.rstrip('.')}). It is admitted only with " "MaterialSelection(raman='provisional'), which warns once and is recorded " "(SEP 3, D13)" ) diff --git a/src/solprop/nonlinear/optmat_rates.py b/src/solprop/nonlinear/optmat_rates.py index d4180ca96..3d20295ab 100644 --- a/src/solprop/nonlinear/optmat_rates.py +++ b/src/solprop/nonlinear/optmat_rates.py @@ -35,6 +35,7 @@ from jaxtyping import Float from numpy.typing import ArrayLike +from solprop._validation import positive from solprop.exceptions import MaterialError, MaterialRangeWarning from solprop.nonlinear.envelope_plasma import EnvelopePlasmaResponse from solprop.nonlinear.ionisation import MAX_RATE, RateConvention @@ -115,14 +116,6 @@ above a negligible value there, so a model that is is refused rather than tabulated.""" -def _validate_positive(name: str, value: float) -> float: - """Return a positive finite number, or refuse it by name.""" - if isinstance(value, bool) or not (math.isfinite(value) and value > 0): - msg = f"OptmatRate: {name} must be positive and finite, got {value!r}" - raise MaterialError(msg) - return float(value) - - def _is_rate_model(value: object) -> bool: """Return whether an object is an optmat rate model.""" return all( @@ -339,10 +332,20 @@ def __post_init__(self) -> None: """Resolve the model, its threshold and the energy per event.""" if isinstance(self.source, Gas): object.__setattr__(self, "source", self.source.value) - _validate_positive("negligible_rate", self.negligible_rate) - _validate_positive("maximum", self.maximum) + positive( + self.negligible_rate, + "OptmatRate: negligible_rate", + MaterialError, + reject_bool=True, + ) + positive(self.maximum, "OptmatRate: maximum", MaterialError, reject_bool=True) if self.reference_field is not None: - _validate_positive("reference_field", self.reference_field) + positive( + self.reference_field, + "OptmatRate: reference_field", + MaterialError, + reject_bool=True, + ) if self.field_range is not None: low, high = (float(v) for v in self.field_range) if not (math.isfinite(high) and 0.0 < low < high): @@ -371,7 +374,12 @@ def _resolve_model(self) -> object: "its rate is evaluated at" ) raise MaterialError(msg) - wavelength = _validate_positive("wavelength", self.wavelength) + wavelength = positive( + self.wavelength, + "OptmatRate: wavelength", + MaterialError, + reject_bool=True, + ) return _resolve(self.source, wavelength, self.model) if not _is_rate_model(self.source): msg = ( @@ -830,7 +838,7 @@ def __call__( Raises ------ MaterialError - If the field is not finite. + If the field is not finite, or optmat's rate for it is NaN. """ values = np.asarray(np.abs(np.asarray(field_amplitude, dtype=np.float64))) if not np.all(np.isfinite(values)): @@ -859,8 +867,17 @@ def __call__( "rate is held at its value there", ), ) + # The ceiling clips an infinite rate; a NaN (or a negative infinity) within + # the fitted range is a defect in the model, never a full-strength rate. np.minimum(rate, self.maximum, out=rate) - rate[~np.isfinite(rate)] = self.maximum + broken = ~np.isfinite(rate) + if bool(np.any(broken)): + field = float(np.minimum(flat[broken][0], self.maximum_field)) + msg = ( + f"{self.species_identity}: optmat's rate {rate[broken][0]} at " + f"{field:.4g} V/m is not finite" + ) + raise MaterialError(msg) return rate.reshape(values.shape) diff --git a/src/solprop/nonlinear/raman.py b/src/solprop/nonlinear/raman.py index f00754c9d..58f9272f3 100644 --- a/src/solprop/nonlinear/raman.py +++ b/src/solprop/nonlinear/raman.py @@ -1536,9 +1536,9 @@ class SilicaTensorResponse(Displayed): carry, at the field-domain amplitude :data:`SILICA_TENSOR_AMPLITUDE` explains, which is what makes the declared ``n2`` come out right on the fundamental. - On an **envelope** grid, and on a field grid with the analytic-signal cubic, the - drive is the beat-free ``Re(E_a,k conj(E_a,l))/2`` instead, exactly as - :func:`raman_drive` chooses it for the scalar response. + On a field grid with the analytic-signal cubic, the drive is the beat-free + ``Re(E_a,k conj(E_a,l))/2`` instead, exactly as :func:`raman_drive` chooses it + for the scalar response. The response runs on field grids only (its `traits`). **From optmat.** With `parameters` an optmat tensor bundle (:class:`~solprop.physdata.glasses.SilicaBundle`, ``SilicaBundle.resolve( diff --git a/src/solprop/nonlinear/responses.py b/src/solprop/nonlinear/responses.py index b6b82d432..4af3ec857 100644 --- a/src/solprop/nonlinear/responses.py +++ b/src/solprop/nonlinear/responses.py @@ -1103,7 +1103,10 @@ def __post_init__(self) -> None: """ # The annotation refuses another rule first wherever the annotations are # checked at run time, as in the test suite. - if self.integration not in {"band", "trapezoid"}: # pragma: no cover + if self.integration not in { + "band", + "trapezoid", + }: # pragma: no cover - its annotation refuses it first msg = f"integration must be 'band' or 'trapezoid', got {self.integration!r}" raise MaterialError(msg) if not isinstance(self.gas, Species): diff --git a/src/solprop/output/__init__.py b/src/solprop/output/__init__.py index 019b4a125..15cda6656 100644 --- a/src/solprop/output/__init__.py +++ b/src/solprop/output/__init__.py @@ -15,9 +15,9 @@ - The handlers: :mod:`~solprop.output.memory` (:class:`~solprop.output.memory.MemoryOutput`), :mod:`~solprop.output.hdf5` (:class:`~solprop.output.hdf5.HDF5Output` with :func:`~solprop.output.hdf5.open_file`, - :func:`~solprop.output.hdf5.resume` and :func:`~solprop.output.hdf5.check_cache`) and - :mod:`~solprop.output.callback` (:class:`~solprop.output.callback.CallbackOutput`, for - a run reduced plane by plane). + :func:`~solprop.output.hdf5.read_resume_state` and + :func:`~solprop.output.hdf5.check_cache`) and :mod:`~solprop.output.callback` + (:class:`~solprop.output.callback.CallbackOutput`, for a run reduced plane by plane). - The other files a run leaves: :mod:`~solprop.output.tdse_archive` (the raw TDSE response archive), :mod:`~solprop.output.snapshots` (checkpoints published while a run computes), :mod:`~solprop.output.resumable` (whether a file can continue), and a @@ -42,7 +42,7 @@ ResumeState, check_cache, open_file, - resume, + read_resume_state, ) from solprop.output.memory import MemoryOutput from solprop.output.metadata import SCHEMA_VERSION, RunMetadata @@ -101,10 +101,10 @@ "check_cache", "open_file", "open_tdse_archive", + "read_resume_state", "read_snapshot", "restore_snapshot", "resumability", - "resume", ] _HOMES: Final = { @@ -135,10 +135,10 @@ "check_cache": "hdf5", "open_file": "hdf5", "open_tdse_archive": "tdse_archive", + "read_resume_state": "hdf5", "read_snapshot": "snapshots", "restore_snapshot": "snapshots", "resumability": "resumable", - "resume": "hdf5", } """The submodule each name of ``__all__`` is defined in, imported on first access.""" diff --git a/src/solprop/output/callback.py b/src/solprop/output/callback.py index 63fedd555..28141915e 100644 --- a/src/solprop/output/callback.py +++ b/src/solprop/output/callback.py @@ -74,9 +74,9 @@ class CallbackOutput: :meth:`fields`, :meth:`plane_field`) raises :class:`~solprop.exceptions.OutputError`, and a handler that has served a run refuses another, which would continue it. A resume needs a file - (:func:`~solprop.output.hdf5.check_cache`, :func:`~solprop.output.hdf5.resume`, - ``resume=True``), as does a TDSE run's ledger. A stopped run returns the handler - with no state written. + (:func:`~solprop.output.hdf5.check_cache`, + :func:`~solprop.output.hdf5.read_resume_state`, ``resume=True``), as does a TDSE + run's ledger. A stopped run returns the handler with no state written. A run with an optmat ionisation rate reads its peak rates back from its output to report the peak field and warn past the rate's range diff --git a/src/solprop/output/hdf5.py b/src/solprop/output/hdf5.py index 62b158fb8..ef86ad6c9 100644 --- a/src/solprop/output/hdf5.py +++ b/src/solprop/output/hdf5.py @@ -6,12 +6,12 @@ - :class:`HDF5Output` streams a run to one file, kept open between optional snapshot transactions; it preallocates the planes the run reserved, writes the saved-plane - count ``n_saved`` last so a hard stop leaves a readable file, follows the run's field - retention, and with ``append=True`` continues a file it wrote earlier. + count ``n_saved`` last so that it never covers a partly written plane, follows the + run's field retention, and with ``append=True`` continues a file it wrote earlier. - :func:`check_cache` is the resume gate: the file's configuration hash must equal the - requested one (ADR-066); :func:`resume` returns a :class:`ResumeState`: the record, - the terminal checkpoint or else the last plane, back in the internal convention, the - whole step history, the outcome and any Adams march snapshot. + requested one (ADR-066); :func:`read_resume_state` returns a :class:`ResumeState`: the + record, the terminal checkpoint or else the last plane, back in the internal + convention, the whole step history, the outcome and any Adams march snapshot. - :func:`open_file` opens a finished run read-only through the same protocol, which is how :mod:`solprop.processing` reads it; :func:`read_recipe` and :func:`write_recipe` read and write the recipe group (SEP 41). @@ -53,7 +53,7 @@ StoredField, TerminalCheckpoint, ) -from solprop.output.serialisation import JsonValue +from solprop.output.serialisation import JsonValue, _rebuild from solprop.output.store import ( FieldRetention, FieldsChoice, @@ -69,7 +69,7 @@ "check_cache", "open_file", "read_recipe", - "resume", + "read_resume_state", "write_recipe", ] @@ -85,12 +85,13 @@ """Entries per chunk of a one-dimensional column; one per plane would be wasteful.""" _METADATA_KEY = "meta/json" +"""Dataset holding the whole run record as JSON.""" + _RECORD_ARRAYS_KEY = "meta/arrays" """The group of the record's arrays, named by digest, dtype and shape (#309).""" _ANNOTATIONS_KEY = "meta/annotations" """Group of the post-run annotations, one JSON string dataset each; optional.""" -"""Dataset holding the whole run record as JSON.""" _OUTCOME_KEY = "meta/outcome" _CHECKPOINT_KEY = "terminal_checkpoint" @@ -101,15 +102,23 @@ def _read_outcome(file: h5py.File) -> RunOutcome | None: """Read the execution status a file records, if it records one. + Read as the record is (:func:`~solprop.output.serialisation._rebuild`), so that + another build's status reads: an entry this build lacks is dropped and an absent + one takes its default. + - Returns: validated execution status; ``None`` when the file records none. """ if _OUTCOME_KEY not in file: return None - stored = _dataset(file, _OUTCOME_KEY)[()] - text = stored.decode("utf-8") if isinstance(stored, bytes) else str(stored) - record = json.loads(text) - record["previous_executions"] = tuple(record["previous_executions"]) - return RunOutcome(**record) + try: + record = json.loads(_text(_dataset(file, _OUTCOME_KEY)[()])) + if not isinstance(record, dict): + raise OutputError("it is not a JSON object") + record["previous_executions"] = tuple(record.get("previous_executions", ())) + return _rebuild(RunOutcome, record, ("outcome",)) + except (ValueError, TypeError, OutputError) as error: + msg = f"{file.filename}: cannot read the execution status it records: {error}" + raise OutputError(msg) from error def _overwrite(group: h5py.Group, name: str, data: np.ndarray) -> None: @@ -426,11 +435,19 @@ def _write_record(file: h5py.File, metadata: RunMetadata) -> None: def _read_record(file: h5py.File) -> RunMetadata: - """Return the run record of an open file, with the arrays beside it.""" + """Return the run record of an open file, with the arrays beside it. + + A record that cannot be read, or declares another output schema, is refused with the + file's name. + """ + text = _read_json(file) held = file.get(_RECORD_ARRAYS_KEY) - return RunMetadata.from_json( - _read_json(file), held if isinstance(held, h5py.Group) else None - ) + try: + return RunMetadata.from_json( + text, held if isinstance(held, h5py.Group) else None + ) + except OutputError as error: + raise OutputError(f"{file.filename}: {error}") from error _RECIPE_KEY = "recipe" @@ -522,8 +539,7 @@ def _read_annotations(file: h5py.File) -> dict[str, JsonValue]: found: dict[str, JsonValue] = {} group = _group(file, _ANNOTATIONS_KEY) for name in group: - stored = _dataset(group, str(name))[()] - text = stored.decode("utf-8") if isinstance(stored, bytes) else str(stored) + text = _text(_dataset(group, str(name))[()]) found[str(name)] = cast("JsonValue", json.loads(text)) return found @@ -536,8 +552,7 @@ def _read_json(file: h5py.File) -> str: "solprop output file" ) raise OutputError(msg) - stored = _dataset(file, _METADATA_KEY)[()] - return stored.decode("utf-8") if isinstance(stored, bytes) else str(stored) + return _text(_dataset(file, _METADATA_KEY)[()]) def _current_checkpoint( @@ -554,7 +569,7 @@ def _current_checkpoint( (SEP 47 section 5.5): a process killed between the two leaves a checkpoint behind the last plane, or one the ``running`` outcome does not name. That state is stale, not inconsistent, and is ignored. A closing (non-running) record that disagrees - with its checkpoint is refused, as before. + with its checkpoint is refused. """ if checkpoint is None: return None @@ -689,11 +704,11 @@ class HDF5Output(PlaneStore): Level for ``'gzip'``, 0 to 9; not accepted for the other choices. append : bool, optional Continue the run the file already holds instead of replacing the file: the - resume path, after :func:`resume` has handed the driver the last plane. The - record given to ``open`` is refused when its configuration hash differs from - the file's; the file's own record is kept, creation time included, and becomes - the handler's ``metadata``, and the run's layout is read from the file so that - the next plane is checked against the ones already there. + resume path, after :func:`read_resume_state` has handed the driver the last + plane. The record given to ``open`` is refused when its configuration hash + differs from the file's; the file's own record is kept, creation time + included, and becomes the handler's ``metadata``, and the run's layout is read + from the file so that the next plane is checked against the ones already there. readonly : bool, optional Open the file at once, for reading only: the handler comes back open, with the file's own record as its ``metadata``, and refuses ``open`` and ``save``. @@ -842,12 +857,15 @@ def open(self, metadata: RunMetadata, *, force: bool = False) -> None: def save(self, plane: SavedPlane) -> None: """Store one saved plane and flush it to disk; refused on a read-only handler. - The flush is what makes a hard stop -- a SIGKILL, an out-of-memory kill, a lost - node -- lose at most the plane being written: the plane's data is flushed before - the file's ``n_saved`` count is raised, so a plane cut off half-way is not - counted, and readers do not see it. An ordinary interruption - (``KeyboardInterrupt``, an error) never needed it: the run loop closes the - handler in a ``finally`` and closing writes everything. One flush per plane + The flush keeps the file's ``n_saved`` count consistent through a hard stop -- + a SIGKILL, an out-of-memory kill, a lost node: the plane's data is flushed + before the count is raised, so a plane cut off half-way is not counted, and + readers do not see it. The flush does not sync to disk and the file is not + opened in SWMR mode, so HDF5 does not promise that a file stopped mid-write + can be opened at all; ``snapshots=`` on a run publishes synced, checksummed + copies that a hard stop cannot damage. An ordinary interruption + (``KeyboardInterrupt``, an error) never needed the flush: the run loop closes + the handler in a ``finally`` and closing writes everything. One flush per plane costs nothing against the steps between planes. Parameters @@ -933,13 +951,13 @@ def _open_readonly(self) -> None: raise OutputError(msg) from error try: self._metadata = _read_record(file) - except OutputError: + self._adopt_state(file) + self._annotations = _read_annotations(file) + self._recipe = read_recipe(file) + except BaseException: file.close() raise self._file = file - self._adopt_state(file) - self._annotations = _read_annotations(file) - self._recipe = read_recipe(file) def _open_file(self) -> h5py.File: """Open the file once: fresh, or read-write to continue what it holds.""" @@ -979,7 +997,6 @@ def _open_owned_file(self) -> h5py.File: return file if self._path.exists(): logger.warning("replacing the existing output file %s", self._path) - self._path.parent.mkdir(parents=True, exist_ok=True) return h5py.File(self._path, "w") def suspend(self) -> None: @@ -1125,7 +1142,9 @@ def _reading(self) -> Iterator[h5py.File]: A finished handler opens its file read-only for the one read and closes it again, so a closed run stays readable without holding a handle; a suspended - writer keeps refusing, because its run still owns the file. + writer keeps refusing, because its run still owns the file. A file that no + longer holds the run as the handler closed it is refused, since its counts + and record would describe another file's rows. """ if self._file is not None or not self._closed: yield self._require_file() @@ -1136,8 +1155,28 @@ def _reading(self) -> Iterator[h5py.File]: msg = f"cannot read the output file {self._path}: {error}" raise OutputError(msg) from error with file: + self._refuse_changed(file) yield file + def _refuse_changed(self, file: h5py.File) -> None: + """Refuse a file another run replaced, or continued, since this one closed.""" + metadata = self._require_metadata() + # A run's record keeps its creation time across a resume, so the time and the + # hash name the run, and the counts how much of it the file holds. + if ( + str(file.attrs.get("created", "")) == metadata.created + and str(file.attrs.get("configuration_hash", "")) + == metadata.configuration_hash() + and (_stored_counts(file) if "z" in file else (0, 0, 0)) + == (self._n_saved, self._history_length, self._step_stats_length) + ): + return + msg = ( + f"{self._path} has changed since this handler closed: another run wrote " + "it or continued the run in it; open it again with open_file to read it" + ) + raise OutputError(msg) + def _write_metadata(self, metadata: RunMetadata) -> None: """Open the file if it is not open yet, and write the run record. @@ -1722,7 +1761,7 @@ def _last_step_stats(file: h5py.File, index: int) -> StepStats: ) -def resume(path: Path | str | Output) -> ResumeState: +def read_resume_state(path: Path | str | Output) -> ResumeState: """Read a file's resumable state and cumulative work, preferring its checkpoint. The last plane comes back in the **internal** FFT convention, through @@ -1762,7 +1801,7 @@ def resume(path: Path | str | Output) -> ResumeState: >>> from pathlib import Path >>> from solprop.grid import EnvelopeGrid >>> from solprop.output import HDF5Output - >>> from solprop.output.hdf5 import resume + >>> from solprop.output.hdf5 import read_resume_state >>> from solprop.output.metadata import _example_metadata >>> from solprop.output.records import SavedPlane >>> metadata = _example_metadata() @@ -1772,7 +1811,7 @@ def resume(path: Path | str | Output) -> ResumeState: ... handler.open(metadata) ... handler.save(SavedPlane(z=0.25, field=np.ones((1, 1, n_omega), complex))) ... handler.close() - ... state = resume(Path(folder) / "run.h5") + ... state = read_resume_state(Path(folder) / "run.h5") >>> state.n_saved, state.plane.z (1, 0.25) @@ -1787,10 +1826,10 @@ def resume(path: Path | str | Output) -> ResumeState: ... again.open(metadata) ... again.save(SavedPlane(z=0.5, field=np.ones((1, 1, n_omega), complex))) ... again.close() - ... resume(Path(folder) / "run.h5").n_saved + ... read_resume_state(Path(folder) / "run.h5").n_saved 2 """ - path = _file_path(path, "resume") + path = _file_path(path, "read_resume_state") metadata, _ = _stored_metadata(path) with h5py.File(path, "r") as file: outcome = _read_outcome(file) @@ -1872,8 +1911,8 @@ def open_file(path: Path | str) -> HDF5Output: ``stat_names``, ``n_saved`` and ``metadata`` answer from the file, ``open`` and ``save`` are refused, and ``close`` releases the file -- a ``with`` block does that on the way out. It is how :mod:`solprop.processing` reads a file after the run that - wrote it has ended; :func:`resume` reads the last plane only, and a handler built - with ``append=True`` opens the file read-write to continue the run. + wrote it has ended; :func:`read_resume_state` reads the last plane only, and a + handler built with ``append=True`` opens the file read-write to continue the run. Parameters ---------- diff --git a/src/solprop/output/memory.py b/src/solprop/output/memory.py index 2575ff5a5..b1247d70e 100644 --- a/src/solprop/output/memory.py +++ b/src/solprop/output/memory.py @@ -585,7 +585,7 @@ def to_file( >>> from pathlib import Path >>> from solprop.grid import EnvelopeGrid >>> from solprop.output import HDF5Output, MemoryOutput - >>> from solprop.output.hdf5 import resume + >>> from solprop.output.hdf5 import read_resume_state >>> from solprop.output.metadata import RunMetadata >>> from solprop.output.records import GridRecord, SavedPlane, StepperRecord >>> from solprop.stepper import DOPRI5, PIController @@ -606,7 +606,7 @@ def to_file( >>> with tempfile.TemporaryDirectory() as folder: ... path = Path(folder) / "run.h5" ... handler.to_file(path) - ... resume(path).plane.z + ... read_resume_state(path).plane.z 0.5 """ # Imported here rather than at the top so that this module, and everything @@ -619,6 +619,8 @@ def to_file( ) try: handler.open(metadata) + if self.recipe is not None: + handler.record_recipe(self.recipe) handler.reserve(self._n_saved) handler.retain(self.retention, self.field_shape) for plane in self.planes(): diff --git a/src/solprop/output/metadata.py b/src/solprop/output/metadata.py index 4ca157213..685e40a4d 100644 --- a/src/solprop/output/metadata.py +++ b/src/solprop/output/metadata.py @@ -82,22 +82,24 @@ _ARRAY_PART = re.compile(r"\.__(?:ndarray|imaginary)__$") """The key of an array record's real or imaginary part, dropped from its stem.""" -SCHEMA_VERSION = 4 +SCHEMA_VERSION = 3 """Version of the saved-output layout; incremented when a stored field changes meaning. Schema 1 is the first released layout, 0.1.0's: the record types of this module, written by :class:`solprop.output.memory.MemoryOutput` and :class:`solprop.output.hdf5.HDF5Output` as ``docs/guide/results/output.md`` describes -them. Schema 2 records ``DataPulse.spectral_phase``. Schema 3 stores a march snapshot's -state and engine rows without the leading axis of one they kept before. Schema 4 records -no basis identities in the plane reference: a plane's basis is derived when it is read. -A record that -declares any other version is refused by name (:class:`RunMetadata`): files written by -an earlier release or by development versions of solprop before 0.1.0, which declared -output schemas up to 28, are not read, and nor is a file from a later release. Read such -a file with the solprop version that wrote it. +them. Schema 2, 0.2.0's, records ``DataPulse.spectral_phase``. Schema 3 stores a march +snapshot's state and engine rows without the leading axis of one they kept before, and +records no basis identities in the plane reference: a plane's basis is derived when it +is read. A record that declares any other version is refused by name +(:class:`RunMetadata`): files written by an earlier release or by development versions +of solprop before 0.1.0, which declared output schemas up to 28, are not read, and nor +is a file from a later release. Read such a file with the solprop version that wrote it. """ +_WRITTEN_BY = {1: "0.1", 2: "0.2"} +"""The release series that wrote each earlier output schema, which its refusal names.""" + PEAK_FIELDS_ANNOTATION = "material_peak_fields" """Name of the post-run annotation holding the material manifest's peak-field report. @@ -170,11 +172,22 @@ def _refuse_schema(declared: object) -> None: f"this record declares output schema_version {declared!r}, and this release " f"of solprop reads output schema {SCHEMA_VERSION} only: a file written by an " "earlier release, by a development version of solprop or by a later release is " - "not read; read it with the solprop version that wrote it" + f"not read; {_schema_remedy(declared)}" ) raise OutputError(msg) +def _schema_remedy(declared: object) -> str: + """Say which solprop reads a file of another output schema: its release if known.""" + # A bool equals 0 or 1 but is not a schema number, so it names no release. + release = _WRITTEN_BY.get(declared) if type(declared) is int else None + if release is None: + return "read it with the solprop version that wrote it" + return ( + f"output schema {declared} is solprop {release}.x's: read it with that release" + ) + + def _stored_hashed(document: Mapping[str, JsonValue]) -> dict[str, JsonValue]: """Return the hashed part of a stored record, as the stored text holds it. diff --git a/src/solprop/output/resumable.py b/src/solprop/output/resumable.py index 6d4bfa125..24fe14850 100644 --- a/src/solprop/output/resumable.py +++ b/src/solprop/output/resumable.py @@ -27,8 +27,8 @@ from solprop.exceptions import OutputError, SolpropError from solprop.output._writer_lock import WriterHeldError, WriterLock -from solprop.output.hdf5 import ResumeState, _file_path, resume -from solprop.output.metadata import SCHEMA_VERSION +from solprop.output.hdf5 import ResumeState, _file_path, read_resume_state +from solprop.output.metadata import SCHEMA_VERSION, _schema_remedy from solprop.output.serialisation import deserialise from solprop.output.store import Output from solprop.recipe.document import FORMAT @@ -179,12 +179,12 @@ def _refused(reason: str) -> Resumability: if schema != SCHEMA_VERSION: return _refused( f"the file is of output schema {schema}, and this solprop reads " - f"{SCHEMA_VERSION} only" + f"{SCHEMA_VERSION} only; {_schema_remedy(schema)}" ) if _writer_alive(path): return _refused("a writer still holds the file") try: - state = resume(path) + state = read_resume_state(path) except OutputError as error: return _refused(f"no state to continue from: {error}") planes = np.asarray( diff --git a/src/solprop/output/scan.py b/src/solprop/output/scan.py index 2acb0749c..1225e79a8 100644 --- a/src/solprop/output/scan.py +++ b/src/solprop/output/scan.py @@ -750,7 +750,7 @@ def _refuse_point_schema(file: h5py.File, index: int, document: object) -> None: try: _refuse_schema(_expand(file, declared)) except OutputError as error: - raise OutputError(f"scan point {index}: {error}") from None + raise OutputError(f"{file.filename}, scan point {index}: {error}") from None def _refuse_other_schemas(file: h5py.File) -> None: diff --git a/src/solprop/output/snapshots.py b/src/solprop/output/snapshots.py index 1c2e2f14a..5735c43b3 100644 --- a/src/solprop/output/snapshots.py +++ b/src/solprop/output/snapshots.py @@ -35,9 +35,9 @@ import numpy as np from solprop._interrupts import deferred_handlers -from solprop.exceptions import OutputError, TDSEArchiveError +from solprop.exceptions import OutputError, OutputRequestError, TDSEArchiveError from solprop.output._writer_lock import SNAPSHOT_SCHEMA, WriterLock -from solprop.output.hdf5 import HDF5Output, ResumeState, resume +from solprop.output.hdf5 import HDF5Output, ResumeState, read_resume_state from solprop.output.metadata import RunMetadata from solprop.output.tdse_archive import ( ArchiveOutputs, @@ -181,7 +181,7 @@ class SnapshotController: Raises ------ - OutputError + OutputRequestError If the interval or capacity is invalid. Examples @@ -205,13 +205,15 @@ def __init__( or not math.isfinite(interval_seconds) or interval_seconds <= 0 ): - raise OutputError("snapshot interval_seconds must be positive and finite") + msg = "snapshot interval_seconds must be positive and finite" + raise OutputRequestError(msg) if ( isinstance(max_snapshots, bool) or not isinstance(max_snapshots, int) or max_snapshots < 1 ): - raise OutputError("snapshot max_snapshots must be a positive integer") + msg = "snapshot max_snapshots must be a positive integer" + raise OutputRequestError(msg) self._directory = Path(directory).resolve() self._interval = interval_seconds self._capacity = max_snapshots @@ -596,11 +598,11 @@ def _checkpoint(directory: Path, records: list[_FileRecord]) -> dict[str, object - Returns: checkpoint identity and provenance checked against the actual files. """ optical = directory / records[0].path - state = resume(optical) + state = read_resume_state(optical) outcome = state.outcome # The endpoint is the last saved plane, or a running checkpoint beyond it at the - # running outcome's position (SEP 47 section 5.5), which `resume` prefers; it is - # an accepted endpoint, never a dense observation. + # running outcome's position (SEP 47 section 5.5), which `read_resume_state` + # prefers; it is an accepted endpoint, never a dense observation. if ( outcome is None or outcome.status != "running" diff --git a/src/solprop/output/tdse_archive.py b/src/solprop/output/tdse_archive.py index 6539f817a..948084da0 100644 --- a/src/solprop/output/tdse_archive.py +++ b/src/solprop/output/tdse_archive.py @@ -44,7 +44,7 @@ import numpy as np from jaxtyping import Float -from solprop.exceptions import OutputError, TDSEArchiveError +from solprop.exceptions import OutputError, OutputRequestError, TDSEArchiveError from solprop.output._writer_lock import WriterLock __all__ = [ @@ -130,10 +130,9 @@ class TDSEArchive: Raises ------ - TypeError - If `path` is not a path or a string. - ValueError - If `path` is empty or `outputs` is neither selection. + OutputRequestError + If `path` is not a path or a string or is empty, or `outputs` is neither + selection. Examples -------- @@ -151,12 +150,12 @@ def __init__(self, path: Path | str, *, outputs: ArchiveOutputs = "full") -> Non candidate: object = path if not isinstance(candidate, Path | str): msg = f"TDSEArchive path must be a path or a string, got {type(path)!r}" - raise TypeError(msg) + raise OutputRequestError(msg) if str(candidate) == "": - raise ValueError("TDSEArchive path must not be empty") + raise OutputRequestError("TDSEArchive path must not be empty") if outputs not in ("full", "required"): msg = f"TDSEArchive outputs must be 'full' or 'required', got {outputs!r}" - raise ValueError(msg) + raise OutputRequestError(msg) object.__setattr__(self, "path", Path(candidate)) object.__setattr__(self, "outputs", outputs) diff --git a/src/solprop/physdata/_optmat.py b/src/solprop/physdata/_optmat.py index 7b67efb82..c5e48496b 100644 --- a/src/solprop/physdata/_optmat.py +++ b/src/solprop/physdata/_optmat.py @@ -4,9 +4,13 @@ """Bridge solprop's physics layer to optmat: units, identities, warnings and errors. -Every call into optmat goes through this module, which imports optmat only inside its -functions: optmat's registries take more than a second to import, and ``import solprop`` -must not pay for them. +The units, identities, warning and error translation and caching that every optmat +adapter shares live here; each adapter (``species``, ``sellmeier``, ``glasses``, +``nonlinear_data``, ``transport``, ``solprop.nonlinear.optmat_rates`` and +``optmat_raman``, ``solprop.capabilities``) imports the optmat modules it needs +directly. All of them, this module included, import optmat only inside functions: +optmat's registries take more than a second to import, and ``import solprop`` must not +pay for them. - **Units**: :func:`bar_to_pa` and :func:`pa_to_bar` (exactly ``1e5``), :func:`omega_to_wavelength` and :func:`wavelength_to_omega` (``omega = 0`` is optmat's @@ -195,15 +199,20 @@ def material_context(log: MaterialLog | None = None) -> Iterator[MaterialLog]: _LOGS.reset(token) -_TRACKER_IDS: Final = re.compile(r"\s*\(TC-\d+(?:,\s*TC-\d+)*\)") -"""A parenthesis holding only optmat's internal tracker ids, ``(TC-527, TC-688)``.""" +_TRACKER_IDS: Final = re.compile( + r"\s*\(TC-\d+(?:,\s*TC-\d+)*\)" # a parenthesis of ids only: (TC-1, TC-2) + r"|[;,]\s*TC-\d+(?:,\s*TC-\d+)*(?=\))" # ids closing one: (a stopgap, TC-1) + r"|(?<=\()TC-\d+(?:,\s*TC-\d+)*[;,]\s*" # ids opening one: (TC-1; a source) +) +"""optmat's internal tracker ids, with the parenthesis or separator that holds them.""" def optmat_text(message: Warning | str) -> str: - """Return the text of an optmat warning without its internal tracker ids. + """Return the text of an optmat warning or status reason without its tracker ids. - optmat cites its development tracker in some warnings, a reference a solprop - user cannot look up (issue #166); the rest of the text is kept as it is. + optmat cites its development tracker in some warnings and status reasons, a + reference a solprop user cannot look up (issue #166); the rest of the text is kept + as it is. """ return _TRACKER_IDS.sub("", str(message)) @@ -256,10 +265,11 @@ def check_status(model: object, material: str) -> MaterialRecord: """ entry = record(model) if entry.status in _FLAGGED: + reason = entry.status_reason.rstrip(".") warn_once( ("status", entry.digest), f"{material}: optmat's {entry.kind} model {entry.name} is {entry.status}" - f" ({entry.status_reason}); it is used as selected, and recorded", + f" ({reason}); it is used as selected, and recorded", MaterialStatusWarning, ) return entry diff --git a/src/solprop/physdata/equation_of_state.py b/src/solprop/physdata/equation_of_state.py index 7fbc02407..af4cd5dee 100644 --- a/src/solprop/physdata/equation_of_state.py +++ b/src/solprop/physdata/equation_of_state.py @@ -18,6 +18,7 @@ import functools import logging +import math import numbers from solprop.constants import BAR, K_B, ROOM_TEMPERATURE @@ -70,8 +71,24 @@ def _check_temperature(temperature: object) -> None: f"{type(temperature).__name__}: a temperature path along z reaches the " "density through solprop.profiles.DensityPath, not a single state" ) - if not float(temperature) > 0.0: - raise MaterialError(f"temperature must be positive, got {temperature} K") + value = float(temperature) + if not (math.isfinite(value) and value > 0.0): + raise MaterialError( + f"temperature must be finite and positive, got {temperature} K" + ) + + +def _check_state(quantity: str, value: float, unit: str, temperature: object) -> None: + """Refuse a state the ideal law would turn into NaN or infinity, on every path. + + - ``quantity``: what ``value`` is, for the message: a pressure or a number density. + - ``unit``: the unit of ``value`` as the message prints it (``" bar"``, or empty). + """ + if not (math.isfinite(value) and value >= 0.0): + raise MaterialError( + f"{quantity} must be finite and non-negative, got {value}{unit}" + ) + _check_temperature(temperature) def ideal_gas_density(pressure: float, temperature: float = ROOM_TEMPERATURE) -> float: @@ -94,7 +111,8 @@ def ideal_gas_density(pressure: float, temperature: float = ROOM_TEMPERATURE) -> Raises ------ MaterialError - If the pressure is negative or the temperature is not positive. + If the pressure is negative or not finite, or the temperature is not positive + and finite. Examples -------- @@ -104,9 +122,7 @@ def ideal_gas_density(pressure: float, temperature: float = ROOM_TEMPERATURE) -> >>> f"{ideal_gas_density(1.01325, 273.15):.6e}" '2.686780e+25' """ - if pressure < 0.0: - raise MaterialError(f"pressure must not be negative, got {pressure} bar") - _check_temperature(temperature) + _check_state("pressure", pressure, " bar", temperature) return pressure * BAR / (K_B * temperature) @@ -140,8 +156,9 @@ def density( Raises ------ MaterialError - If the gas is unknown, the pressure is negative, the temperature is not - positive, or the state lies outside the equation of state's domain. + If the gas is unknown, the pressure is negative or not finite, the + temperature is not positive and finite, or the state lies outside the + equation of state's domain; the ideal law refuses the same states. Notes ----- @@ -158,9 +175,7 @@ def density( 0.0 """ species = as_gas(gas) - if pressure < 0.0: - raise MaterialError(f"pressure must not be negative, got {pressure} bar") - _check_temperature(temperature) + _check_state("pressure", pressure, " bar", temperature) if pressure == 0.0: return 0.0 if ideal: @@ -198,8 +213,9 @@ def pressure( Raises ------ MaterialError - If the gas is unknown, the density is negative, the temperature is not - positive, or the state lies outside the equation of state's domain. + If the gas is unknown, the density is negative or not finite, the + temperature is not positive and finite, or the state lies outside the + equation of state's domain; the ideal law refuses the same states. Examples -------- @@ -208,11 +224,7 @@ def pressure( '5.000000' """ species = as_gas(gas) - if number_density < 0.0: - raise MaterialError( - f"number density must not be negative, got {number_density}" - ) - _check_temperature(temperature) + _check_state("number density", number_density, " m^-3", temperature) if number_density == 0.0: return 0.0 if ideal: diff --git a/src/solprop/physdata/gases.py b/src/solprop/physdata/gases.py index c67505e41..bd2c2b0ac 100644 --- a/src/solprop/physdata/gases.py +++ b/src/solprop/physdata/gases.py @@ -12,6 +12,9 @@ :class:`~solprop.physdata.selection.MaterialSelection`. """ +import math +import sys +from collections.abc import Sequence from enum import StrEnum from solprop.exceptions import MaterialError @@ -147,3 +150,18 @@ def is_air(material: Gas | str) -> bool: if isinstance(material, Gas): return material is Gas.Air return material.strip().lower() == "air" + + +def _fractions(values: Sequence[float]) -> tuple[float, ...]: + """Validate mole fractions without silently renormalising them. + + The one rule for a mixture's fill and a gas-flow composition, so that both accept + the same sets. + """ + result = tuple(float(v) for v in values) + if not result or any(not math.isfinite(v) or v < 0 for v in result): + raise MaterialError("fractions must be finite, non-negative and non-empty") + # A supplied distribution can incur one rounding per entry and its sum. + if abs(math.fsum(result) - 1.0) > 2 * len(result) * sys.float_info.epsilon: + raise MaterialError(f"fractions must sum to one, got {math.fsum(result):.17g}") + return result diff --git a/src/solprop/physdata/glasses.py b/src/solprop/physdata/glasses.py index 10ad61a7a..0e4c6a0ac 100644 --- a/src/solprop/physdata/glasses.py +++ b/src/solprop/physdata/glasses.py @@ -94,7 +94,7 @@ class GlassIndex(ABC): name : str The material, e.g. ``"SiO2"``. source : str - The name used to select this model, e.g. ``"malitson"``. + The name used to select this model, e.g. ``"fit/SiO2"``. wavelength_range : tuple of float Shortest and longest wavelength in m over which the source is valid. citation : str diff --git a/src/solprop/physdata/mixtures.py b/src/solprop/physdata/mixtures.py index 79e8c4320..630a740c0 100644 --- a/src/solprop/physdata/mixtures.py +++ b/src/solprop/physdata/mixtures.py @@ -38,7 +38,7 @@ from solprop.constants import ROOM_TEMPERATURE from solprop.exceptions import DiluteScalingWarning, MaterialError from solprop.physdata import _optmat -from solprop.physdata.gases import Gas +from solprop.physdata.gases import Gas, _fractions from solprop.physdata.raman_types import Dephasing, MolecularOptions from solprop.physdata.selection import ( DiluteScalingCheck, @@ -432,17 +432,6 @@ def _check_flow_weight( ) -def _fractions(values: Sequence[float]) -> tuple[float, ...]: - """Validate a distribution without silently renormalising supplied fractions.""" - result = tuple(float(v) for v in values) - if not result or any(not math.isfinite(v) or v < 0 for v in result): - raise MaterialError("fractions must be finite, non-negative and non-empty") - # A supplied distribution can incur one rounding per entry and its sum. - if abs(math.fsum(result) - 1.0) > 2 * len(result) * np.finfo(float).eps: - raise MaterialError(f"fractions must sum to one, got {math.fsum(result):.17g}") - return result - - _PREIONISATION_PROBES = 65 """Evenly spaced positions a finite path is sampled at, beside its breakpoints. diff --git a/src/solprop/physdata/nonlinear_data.py b/src/solprop/physdata/nonlinear_data.py index dae8c0c2d..62e764358 100644 --- a/src/solprop/physdata/nonlinear_data.py +++ b/src/solprop/physdata/nonlinear_data.py @@ -227,8 +227,8 @@ def n2( *, pressure: float, temperature: float = ROOM_TEMPERATURE, - wavelength: float | None = None, selection: MaterialSelection | None = None, + wavelength: float | None = None, ) -> float: """Return the nonlinear index of a gas at a carrier. @@ -244,12 +244,12 @@ def n2( Absolute pressure in **bar** (the documented non-SI user-interface unit), >= 0. temperature : float, optional Temperature in K, > 0. Defaults to 293.15 K. + selection : MaterialSelection or None, optional + ``None`` is ``MaterialSelection()``. wavelength : float or None, optional The carrier wavelength in m at which the dispersive Kerr coefficient and ``n0`` are evaluated: it, or the selection's ``carrier_wavelength``, is required, and the two must agree when both are given. - selection : MaterialSelection or None, optional - ``None`` is ``MaterialSelection()``. Returns ------- @@ -774,7 +774,7 @@ class DispersiveKerrModel: :math:`\nu_c`, m^-1, positive. band_edge_linear : float or None The band edge for one linear polarisation, m^-1; ``None`` where optmat's - record leaves it undefined (CO2, CH4, SF6, N2O and O3 at optmat 0.4). + record leaves it undefined (CH4, SF6 and N2O among the built-in gases). band_edge_any : float or None The band edge for any polarisation, m^-1, or ``None``. material_records : tuple of MaterialRecord diff --git a/src/solprop/physdata/selection.py b/src/solprop/physdata/selection.py index f181cac3c..7c0341a64 100644 --- a/src/solprop/physdata/selection.py +++ b/src/solprop/physdata/selection.py @@ -36,7 +36,6 @@ __all__ = [ "DISPERSIVE_POLICIES", "ELECTRONIC_POLICIES", - "ENERGY_LOSS_POLICIES", "RAMAN_POLICIES", "RAMAN_SHIFT_POLICIES", "STATUSES", @@ -82,9 +81,6 @@ } """The dispersive electronic policies and the evaluator each selects (SEP 6).""" -ENERGY_LOSS_POLICIES: Final[tuple[str, ...]] = ("peak-weighted",) -"""The plasma energy-loss conventions: the rate-weighted energy at the peak field.""" - RAMAN_POLICIES: Final[tuple[str, ...]] = ("recommended", "provisional") """The names ``MaterialSelection.raman`` takes, for a gas and for silica alike. @@ -243,9 +239,6 @@ class MaterialSelection: the Raman pump dispersion and the rate are evaluated; positive and finite, or ``None`` to take the run's grid reference. A dispersive electronic policy does not use it: its response is evaluated at absolute frequencies. - energy_loss : str - The plasma energy-loss convention; ``"peak-weighted"`` is the only one, the - rate-weighted energy per event at the run's peak field. raman_shift : str or None ``None``, or ``"reference-density"``: the explicit approximation that holds a density-dependent Raman line shift at a reference density. @@ -259,12 +252,12 @@ class MaterialSelection: -------- >>> from solprop.physdata.selection import MaterialSelection >>> selection = MaterialSelection(carrier_wavelength=800e-9) - >>> selection.linear, selection.energy_loss - ('recommended', 'peak-weighted') - >>> MaterialSelection(energy_loss="mean") # doctest: +ELLIPSIS + >>> selection.linear, selection.carrier_wavelength + ('recommended', 8e-07) + >>> MaterialSelection(electronic="mean") # doctest: +ELLIPSIS Traceback (most recent call last): ... - solprop.exceptions.MaterialError: MaterialSelection.energy_loss must be one of ... + solprop.exceptions.MaterialError: MaterialSelection.electronic must be one of ... """ linear: ModelChoice = "recommended" @@ -272,7 +265,6 @@ class MaterialSelection: raman: ModelChoice = "recommended" ionisation: ModelChoice = "recommended" carrier_wavelength: float | None = None - energy_loss: str = "peak-weighted" raman_shift: str | None = None def __post_init__(self) -> None: @@ -281,7 +273,6 @@ def __post_init__(self) -> None: object.__setattr__(self, name, _choice(getattr(self, name), name)) policies: tuple[tuple[str, object, tuple[str | None, ...]], ...] = ( ("electronic", self.electronic, ELECTRONIC_POLICIES), - ("energy_loss", self.energy_loss, ENERGY_LOSS_POLICIES), ("raman_shift", self.raman_shift, RAMAN_SHIFT_POLICIES), ) for name, value, allowed in policies: @@ -323,7 +314,6 @@ def to_dict(self) -> dict[str, object]: "raman": _choice_record(self.raman), "ionisation": _choice_record(self.ionisation), "carrier_wavelength": self.carrier_wavelength, - "energy_loss": self.energy_loss, "raman_shift": self.raman_shift, } @@ -407,15 +397,19 @@ def from_identity(cls, identity: ModelIdentityLike) -> "MaterialRecord": Returns ------- MaterialRecord - Its name, kind, material, digest, status and override fields. + Its name, kind, material, digest, status and override fields; the + status reason without optmat's internal tracker ids. """ + # _optmat imports this module: the import waits for the call. + from solprop.physdata._optmat import optmat_text # noqa: PLC0415 + return cls( name=identity.name, kind=identity.kind, material=identity.material, digest=identity.digest, status=identity.status, - status_reason=identity.status_reason, + status_reason=optmat_text(identity.status_reason), optmat_version=identity.optmat_version, modified=identity.modified, base=identity.base, @@ -697,9 +691,9 @@ class MaterialManifest: electronic response is SEP 6's dispersive one), ``gnlse_raman`` (a GNLSE run's held-back fraction, where it came from and the silica bundle), ``raman_shift`` and ``raman_reference_temperature``, - ``energy_loss``, and ``ionisation``: one entry per optmat rate, with its - threshold kind, its reference field, its constant energy per event and that - energy's bound + and ``ionisation``: one entry per optmat rate, with its threshold kind, its + reference field, its energy-loss convention, its constant energy per event + and that energy's bound (:meth:`solprop.nonlinear.optmat_rates.OptmatRate.manifest_entry`). A policy a later phase resolves is recorded as selected, or ``None``. dilute_scaling : tuple of collections.abc.Mapping diff --git a/src/solprop/physdata/sellmeier.py b/src/solprop/physdata/sellmeier.py index 6cc7e06e8..7684ae280 100644 --- a/src/solprop/physdata/sellmeier.py +++ b/src/solprop/physdata/sellmeier.py @@ -765,7 +765,7 @@ def dilute_scaling_error( wavelength = wavelength[inside] state = f"{density:.6g} m^-3 and {temperature:g} K" # Beside a pole of the law 1 + chi can fall below zero, in optmat's refractivity - # and in the comparison below; the error there is NaN, as before, without a + # and in the comparison below; the error there is NaN, without a # RuntimeWarning at every sample of a pressure search. with ( np.errstate(invalid="ignore"), @@ -779,8 +779,7 @@ def dilute_scaling_error( ): # optmat's ideal-gas state of this density: its law then takes N = p / # (k_B T), which is `density` to one rounding, and the refractivity - # virial still enters. Its real-gas inverse is not needed (and before - # optmat 0.1.1 it failed for Ar, N2 and CH4 below about 255-284 K). + # virial still enters. Its real-gas inverse is not needed. ideal = State(density * K_B * temperature, temperature) exact = np.asarray( model.refractivity(wavelength, ideal, ideal=True, warn=False) @@ -932,15 +931,32 @@ def _one_plus_chi( - Raises :class:`MaterialError` at or below -1 for ``chi1``, which happens only when a model is extrapolated onto a pole. """ - values = np.asarray( - 1.0 + chi1(gas, omega, pressure=pressure, temperature=temperature) + return np.asarray(1.0 + _checked_chi(gas, omega, pressure, temperature)) + + +def _checked_chi( + gas: Gas | str, + omega: ArrayLike | float | int, + pressure: float, + temperature: float, +) -> Float[np.ndarray, "*shape"]: + """Return ``chi1``, checked to exceed -1 so that the index is real. + + - ``omega``: angular frequency in rad/s. + - ``pressure``: absolute pressure in bar. + - ``temperature``: temperature in K. + - Raises :class:`MaterialError` at or below -1, which happens only when a model is + extrapolated onto a pole. + """ + susceptibility = np.asarray( + chi1(gas, omega, pressure=pressure, temperature=temperature) ) - if np.any(values <= 0.0): + if np.any(susceptibility <= -1.0): raise MaterialError( f"the index model for {as_gas(gas).value} gives a non-positive dielectric " "constant here; it has been extrapolated onto a pole of the expansion" ) - return values + return susceptibility def refractive_index( @@ -1028,8 +1044,8 @@ def refractive_index_minus_one( >>> f"{float(refractive_index_minus_one(Gas.Ar, 2.356e15, pressure=1.0)):.6e}" '2.570726e-04' """ - values = _one_plus_chi(gas, omega, pressure, temperature) - return np.asarray((values - 1.0) / (1.0 + np.sqrt(values))) + susceptibility = _checked_chi(gas, omega, pressure, temperature) + return np.asarray(susceptibility / (1.0 + np.sqrt(1.0 + susceptibility))) def drefractive_index_domega( diff --git a/src/solprop/physdata/species.py b/src/solprop/physdata/species.py index 8f45ffa8a..30e7075b3 100644 --- a/src/solprop/physdata/species.py +++ b/src/solprop/physdata/species.py @@ -31,7 +31,7 @@ from solprop.constants import BAR, K_B, ROOM_TEMPERATURE, C from solprop.exceptions import MaterialError from solprop.physdata import _optmat -from solprop.physdata.equation_of_state import ideal_gas_density +from solprop.physdata.equation_of_state import _check_state, ideal_gas_density from solprop.physdata.gases import Gas, as_gas from solprop.physdata.nonlinear_data import OptmatKerr from solprop.physdata.raman_types import MolecularRaman @@ -113,10 +113,6 @@ def density(self, pressure: float, temperature: float = ROOM_TEMPERATURE) -> flo MaterialError If pressure or temperature is non-finite or outside its domain. """ - if not math.isfinite(pressure) or pressure < 0: - raise MaterialError("partial pressure must be finite and non-negative") - if not math.isfinite(temperature) or temperature <= 0: - raise MaterialError("temperature must be finite and positive") return ideal_gas_density(pressure, temperature) def pressure( @@ -141,9 +137,7 @@ def pressure( MaterialError If density or temperature is outside its domain. """ - self.density(0.0, temperature) - if not math.isfinite(number_density) or number_density < 0: - raise MaterialError("number density must be finite and non-negative") + _check_state("number density", number_density, " m^-3", temperature) return number_density * K_B * temperature / BAR @@ -455,7 +449,8 @@ def sound_speed(self, pressure: float, temperature: float) -> float: pressure : float Pressure in bar, > 0. temperature : float - Temperature in K, within :attr:`temperature_range`. + Temperature in K, within the equation of state's range (the transport + range, :attr:`temperature_range`, does not apply). Returns ------- @@ -465,14 +460,19 @@ def sound_speed(self, pressure: float, temperature: float) -> float: Raises ------ MaterialError - If the pressure is not positive, or the state is outside the domain. + If the pressure is not positive, the temperature not positive and finite, + or the state is outside the equation of state's domain. """ from optmat.conditions import State # noqa: PLC0415 - optmat is lazy from optmat.exceptions import StateError # noqa: PLC0415 - as above - kelvin = self._checked(temperature) if not (math.isfinite(pressure) and pressure > 0.0): raise MaterialError(f"pressure must be positive, got {pressure} bar") + kelvin = float(temperature) + if not (math.isfinite(kelvin) and kelvin > 0.0): + raise MaterialError(f"temperature must be positive, got {temperature} K") + # The equation of state alone: its own range and status, as density's. + _optmat.check_status(self._equation, self.key.value) try: return float( self._equation.speed_of_sound( diff --git a/src/solprop/physdata/transport.py b/src/solprop/physdata/transport.py index b8df98eaa..7326fd6b4 100644 --- a/src/solprop/physdata/transport.py +++ b/src/solprop/physdata/transport.py @@ -29,7 +29,7 @@ from solprop.constants import BAR, K_B, N_A, ROOM_TEMPERATURE from solprop.exceptions import MaterialError -from solprop.physdata.gases import Gas, as_gas +from solprop.physdata.gases import Gas, _fractions, as_gas from solprop.physdata.species import OptmatGas, Species __all__ = [ @@ -113,16 +113,9 @@ def _composition( if not isinstance(gas, Mapping): return ((_member(gas, quantity), 1.0),) merged: dict[OptmatGas, float] = {} - for key, fraction in gas.items(): - value = float(fraction) - if not math.isfinite(value) or value < 0.0: - raise MaterialError("mole fractions must be finite and not negative") + for key, value in zip(gas, _fractions(tuple(gas.values())), strict=True): member = _member(key, quantity) merged[member] = merged.get(member, 0.0) + value - total = math.fsum(merged.values()) - # A distribution normalised in floating point is one to a few ulps per entry. - if not merged or abs(total - 1.0) > 1e-12: - raise MaterialError(f"mole fractions must sum to one, got {total:.17g}") return tuple((member, value) for member, value in merged.items() if value > 0.0) @@ -272,8 +265,9 @@ def sound_speed( :func:`molar_mass`. A pressure in **bar**, > 0, gives the real-gas value from the equation of state, for a pure gas only. temperature : float, optional - Temperature in K, inside :func:`temperature_range` of every gas. Defaults to - 293.15 K. + Temperature in K, inside :func:`temperature_range` of every gas for the dilute + value, and inside the equation of state's range for the real-gas value. + Defaults to 293.15 K. Returns ------- diff --git a/src/solprop/plotting/propagation.py b/src/solprop/plotting/propagation.py index bc02aeafe..914b124bf 100644 --- a/src/solprop/plotting/propagation.py +++ b/src/solprop/plotting/propagation.py @@ -320,6 +320,7 @@ def time_1d( output: Output, z: float | Sequence[float] | None = None, *, + plane: int | Sequence[int] | None = None, quantity: SliceQuantity = "power", modes: ModeSelection = None, oversampling: int = 4, @@ -338,6 +339,8 @@ def time_1d( An opened output handler. z : float, sequence of float or None Positions to draw, m; the end of the run by default. + plane : int, sequence of int or None + Saved planes to draw, by index, negative from the end; refused beside `z`. quantity : {'power', 'field', 'field_squared'} What to draw: the instantaneous power, the real field, or its square. modes : int, sequence of int, 'sum' or None @@ -369,6 +372,8 @@ def time_1d( ------ solprop.exceptions.OutputError If the stored run is a spatial one, whose columns are not modal amplitudes. + solprop.exceptions.ProcessingError + If both `z` and `plane` are given. Examples -------- @@ -383,7 +388,7 @@ def time_1d( _refuse_by_basis(output, "time_1d") choice(quantity, "quantity", SLICE_QUANTITIES, ProcessingError) ax = _axis(ax, (8.5, 5.0)) - planes = _plane_indices(output, z) + planes = _plane_indices(output, z, plane) traces = [] for index in planes: if quantity == "power": @@ -445,6 +450,7 @@ def spec_1d( z: float | Sequence[float] | None = None, axis: SpectralAxis = "wavelength", *, + plane: int | Sequence[int] | None = None, modes: ModeSelection = None, spec_range: tuple[float, float] | None = None, log: bool = True, @@ -463,6 +469,8 @@ def spec_1d( Positions to draw, m; the end of the run by default. axis : {'wavelength', 'f', 'omega'} Spectral abscissa. + plane : int, sequence of int or None + Saved planes to draw, by index, negative from the end; refused beside `z`. modes : int, sequence of int, 'sum' or None Which modes to draw. spec_range : tuple of float or None @@ -492,6 +500,8 @@ def spec_1d( ------ solprop.exceptions.OutputError If the stored run is a spatial one, whose columns are not modal amplitudes. + solprop.exceptions.ProcessingError + If both `z` and `plane` are given. Examples -------- @@ -505,7 +515,7 @@ def spec_1d( """ _refuse_by_basis(output, "spec_1d") ax = _axis(ax, (8.5, 5.0)) - planes = _plane_indices(output, z) + planes = _plane_indices(output, z, plane) limits = _limits(output, axis, spec_range) factor, label = spectral_display(axis) traces = [ @@ -690,11 +700,21 @@ def _limits( return float(min(spec_range)), float(max(spec_range)) -def _plane_indices(output: Output, z: float | Sequence[float] | None) -> list[int]: +def _plane_indices( + output: Output, + z: float | Sequence[float] | None, + plane: int | Sequence[int] | None = None, +) -> list[int]: """Return the plane indices a slice plot draws. - - ``z``: positions, m; ``None`` means the last saved plane. + - ``z``: positions, m; ``plane``: indices, negative from the end. Neither means the + last saved plane; both are refused, as by the processing readers. """ + if plane is not None and z is not None: + msg = f"give plane indices or positions, not both: plane={plane}, z={z}" + raise ProcessingError(msg) + if plane is not None: + return [plane] if isinstance(plane, int) else list(plane) if z is None: return [output.n_saved - 1] positions = [z] if isinstance(z, float | int) else list(z) diff --git a/src/solprop/plotting/spectrograms.py b/src/solprop/plotting/spectrograms.py index 4bae8461c..374852376 100644 --- a/src/solprop/plotting/spectrograms.py +++ b/src/solprop/plotting/spectrograms.py @@ -25,12 +25,11 @@ _figure_of, spectral_display, ) -from solprop.processing.axes import ModeSelection, SpectralAxis +from solprop.processing.axes import ModeSelection, SpectralAxis, _plane_index from solprop.processing.fields import ( DEFAULT_GATE_POSITIONS, _check_spec_range, get_spectrogram, - nearest_plane, ) __all__ = ["DEFAULT_GATE_POSITIONS", "spectrogram"] @@ -41,6 +40,7 @@ def spectrogram( z: float | None = None, axis: SpectralAxis = "wavelength", *, + plane: int | None = None, modes: ModeSelection = None, time_range: tuple[float, float] | None = None, gate_fwhm: float | None = None, @@ -64,9 +64,12 @@ def spectrogram( output : solprop.output.store.Output An opened output handler. z : float or None - Position of the plane, m; the end of the run by default. + Position of the plane, m: the nearest saved plane; the end of the run by + default. axis : {'wavelength', 'f', 'omega'} Spectral abscissa of the ordinate. + plane : int or None + The saved plane by index, negative from the end; refused beside `z`. modes : int, sequence of int, 'sum' or None Which mode to draw. A multimode run must name one: a spectrogram is of a field, and modal fields do not add away from a point in space. @@ -84,7 +87,9 @@ def spectrogram( log : bool Whether to show decibels below the peak rather than a linear scale. db_min : float - Bottom of a logarithmic colour scale, dB. + Bottom of a logarithmic colour scale, dB below the peak: -40 dB by default, + where :func:`~solprop.plotting.propagation.prop_2d` and + :func:`~solprop.plotting.propagation.spec_1d` default to -60 dB. cmap : str, matplotlib.colors.Colormap or None Colour map. ax : matplotlib.axes.Axes or None @@ -103,7 +108,8 @@ def spectrogram( solprop.exceptions.ModeError If a multimode run does not name a single mode. solprop.exceptions.ProcessingError - If ``spec_range`` selects no sample of the spectral axis. + If ``spec_range`` selects no sample of the spectral axis, or both `z` and + `plane` are given. Examples -------- @@ -115,7 +121,7 @@ def spectrogram( 'Time (fs)' >>> plt.close(figure) """ - plane = output.n_saved - 1 if z is None else nearest_plane(output, z) + plane = _plane_index(output, plane, z) if time_range is None: time_range = _plane_time_range(output, plane, modes, transfer) # The map per unit frequency, drawn against the axis asked for as it stands: diff --git a/src/solprop/plotting/statistics.py b/src/solprop/plotting/statistics.py index 3c3d0233c..e84771231 100644 --- a/src/solprop/plotting/statistics.py +++ b/src/solprop/plotting/statistics.py @@ -97,7 +97,7 @@ def plot_stats(output: Output, **kwargs: Any) -> list[Figure]: (:attr:`solprop.stats.StatsSpec.periodic`), the between-planes rows are drawn instead: they are the same numbers on a far denser grid of z, so a curve that a few save planes would render as a polygon is drawn as the trace it is. A run - without that channel is drawn from its planes exactly as before. + without that channel is drawn from its planes. Parameters ---------- diff --git a/src/solprop/processing/_examples.py b/src/solprop/processing/_examples.py index 524c72695..cd7f3cf44 100644 --- a/src/solprop/processing/_examples.py +++ b/src/solprop/processing/_examples.py @@ -139,7 +139,7 @@ def example_output( Examples -------- - >>> from solprop.processing._examples import example_output + >>> from solprop.processing import example_output >>> output = example_output(n_modes=2) >>> output.n_saved, output["field"].shape[1:3] (5, (2, 1)) diff --git a/src/solprop/processing/axes.py b/src/solprop/processing/axes.py index 23f7d35a2..320933681 100644 --- a/src/solprop/processing/axes.py +++ b/src/solprop/processing/axes.py @@ -548,15 +548,15 @@ def _refuse_by_basis(output: Output, name: str) -> None: The whitelist's fourth door (:mod:`solprop.output.capability`). The readers of :mod:`solprop.processing.time`, :mod:`solprop.processing.fields` and the plots - drawn from them were written when every run's mode axis was an orthogonal one- or - two-component basis whose coordinate powers add up to the physical power. A - general modal file is not that, and ``peak_power(modes='sum')`` is - :func:`solprop.stats.peak_power_total`, which the run loop, both CPU backends and - :mod:`solprop.processing.modal` all refuse on that basis. A spatial file is not - that either: its columns are fields in V m or V/m or slab amplitudes, and the - readers of :data:`~solprop.output.capability.COLUMN_READINGS` would read them as - modes in sqrt(W). Without this check the same numbers came back through a - different import, silently wrong in joules and watts. + drawn from them read the mode axis as an orthogonal one- or two-component basis + whose coordinate powers add up to the physical power. A general modal file is not + that, and ``peak_power(modes='sum')`` is :func:`solprop.stats.peak_power_total`, + which the run loop, both CPU backends and :mod:`solprop.processing.modal` all + refuse on that basis. A spatial file is not that either: its columns are fields in + V m or V/m or slab amplitudes, and the readers of + :data:`~solprop.output.capability.COLUMN_READINGS` would read them as modes in + sqrt(W). Read through these readers, either would give numbers silently wrong in + joules and watts. Nothing changes for a run on an ordinary modal basis, which is every gas-filled guided run. Each public reader calls this once, under its own name; what it reads diff --git a/src/solprop/processing/compression.py b/src/solprop/processing/compression.py index 81718821f..2813507b7 100644 --- a/src/solprop/processing/compression.py +++ b/src/solprop/processing/compression.py @@ -36,7 +36,7 @@ from solprop import fourier from solprop._display import Displayed, engineering, line, phase_text from solprop.constants import C -from solprop.exceptions import OpticsGeometryError, ProcessingError +from solprop.exceptions import ModeError, OpticsGeometryError, ProcessingError from solprop.grid import TimeGrid from solprop.optics import ( Chain, @@ -51,7 +51,13 @@ from solprop.output.capability import capability_of, compression_refusal from solprop.output.store import Output from solprop.processing import spectra, time -from solprop.processing.axes import _keep_index, _plane_field, _plane_index, grid_of +from solprop.processing.axes import ( + _check_mode_index, + _keep_index, + _plane_field, + _plane_index, + grid_of, +) from solprop.processing.fields import _fft_norm, _to_time __all__ = [ @@ -388,12 +394,10 @@ def _select_modes( if modes is None: return stored chosen = [modes] if isinstance(modes, int) else list(modes) - if not chosen or any( - not -stored.shape[0] <= index < stored.shape[0] for index in chosen - ): - raise ProcessingError( - f"modes={modes!r} does not select from the {stored.shape[0]} modes saved" - ) + if not chosen: + raise ModeError(f"modes={modes!r} selects no mode") + for index in chosen: + _check_mode_index(index, stored.shape[0]) return stored[chosen] @@ -489,6 +493,8 @@ def apply_transfer( ------ solprop.exceptions.ProcessingError If the plane is named both by index and by position. + solprop.exceptions.ModeError + If `modes` selects no mode, or a mode the output does not hold. Examples -------- @@ -553,6 +559,11 @@ def transform_limit( peak_power : float Its peak power, W. + Raises + ------ + solprop.exceptions.ModeError + If `modes` selects no mode, or a mode the output does not hold. + Examples -------- >>> from solprop.processing._examples import example_output @@ -692,6 +703,8 @@ def compress_taylor( solprop.exceptions.ProcessingError If `order` is below two, `bound_factor` is not positive, or the input forms are mixed. + solprop.exceptions.ModeError + If `modes` selects no mode, or a mode the output does not hold. Examples -------- @@ -828,6 +841,8 @@ def compress_material( ------ solprop.exceptions.ProcessingError If the thickness range is not ordered, or the input forms are mixed. + solprop.exceptions.ModeError + If `modes` selects no mode, or a mode the output does not hold. Examples -------- @@ -953,6 +968,8 @@ def compress_mirrors( solprop.exceptions.ProcessingError If `max_reflections` is below one, a medium is given without a range or a range without a medium, or the input forms are mixed. + solprop.exceptions.ModeError + If `modes` selects no mode, or a mode the output does not hold. Examples -------- @@ -1396,6 +1413,8 @@ def compress_gratings( ProcessingError If bounds, inputs or selection are invalid, the output is spatial or general modal, or no feasible setting is found by the scan. + ModeError + If `modes` selects no mode, or a mode the output does not hold. MaterialError If the optical or material inputs are invalid. """ @@ -1486,6 +1505,8 @@ def compress_prisms( ProcessingError If no range is supplied, bounds or inputs are invalid, the output is spatial or general modal, selection is empty, or no feasible setting is found. + ModeError + If `modes` selects no mode, or a mode the output does not hold. MaterialError If an optical input or material model is invalid; material errors propagate. """ diff --git a/src/solprop/processing/fields.py b/src/solprop/processing/fields.py index fed31468d..2deaa5b2b 100644 --- a/src/solprop/processing/fields.py +++ b/src/solprop/processing/fields.py @@ -64,6 +64,7 @@ "FieldKind", "ModeSelection", "NoiseFloor", + "default_gate_fwhm", "field_spectrogram", "get_field", "get_phase", @@ -358,8 +359,8 @@ def _check_spec_range( ) -> None: """Refuse a ``spec_range`` that selects no sample of the abscissa. - Without it the density came back empty, and a plot failed later inside NumPy with - a message that named neither the range nor its units. + An empty selection would give an empty density, and a plot would fail later inside + NumPy with a message that named neither the range nor its units. - ``x``: the abscissa, ascending, in the units of ``axis``. """ @@ -863,7 +864,8 @@ def get_spectrogram( The time range the gate positions cover, s, in either order and clipped to the time window; the whole window by default. gate_fwhm : float or None - Width of the gate, s; a twentieth of the time range by default. + Width of the gate, s; a twentieth of the time range by default + (:func:`default_gate_fwhm`). positions : int How many gate positions to place across the time range. bandpass : tuple of float, Passband, numpy.ndarray or None @@ -988,7 +990,8 @@ def field_spectrogram( The time range the gate positions cover, s, in either order and clipped to the time window; the whole window by default. gate_fwhm : float or None - Width of the gate, s; a twentieth of the time range by default. + Width of the gate, s; a twentieth of the time range by default + (:func:`default_gate_fwhm`). positions : int How many gate positions to place across the time range. @@ -1013,17 +1016,9 @@ def field_spectrogram( msg = f"a spectrogram needs at least one gate position, got {positions!r}" raise ProcessingError(msg) window = (float(t[0]), float(t[-1])) - low, high = window if time_range is None else time_range - low, high = min(low, high), max(low, high) - if high < window[0] or low > window[1]: - msg = ( - f"the time range {time_range!r} holds no gate position: the window is " - f"{window[0]:.4g} s to {window[1]:.4g} s" - ) - raise ProcessingError(msg) - low, high = max(low, window[0]), min(high, window[1]) + low, high = _gate_range(t, time_range) span = high - low - width = span / 20.0 if gate_fwhm is None else gate_fwhm + width = default_gate_fwhm(t, time_range) if gate_fwhm is None else gate_fwhm if not 0.0 < width <= window[1] - window[0]: msg = ( f"the gate's width must be positive and within the time window " @@ -1047,6 +1042,62 @@ def field_spectrogram( return times[inside], x[order], values[order] +def default_gate_fwhm( + t: Float[np.ndarray, " n_t"], time_range: tuple[float, float] | None = None +) -> float: + """Return the gate width a spectrogram uses when it is given none. + + A twentieth of the time range its gate positions cover, that range clipped to the + field's time window: what :func:`get_spectrogram`, :func:`field_spectrogram` and + :func:`~solprop.processing.beams.on_axis_spectrogram` take for ``gate_fwhm=None``. + + Parameters + ---------- + t : numpy.ndarray + The field's times, s, evenly spaced and ascending: for a saved plane, + :func:`time_axis` at :func:`real_field_oversampling`. + time_range : tuple of float or None, optional + The time range of the gate positions, s, in either order; the whole window by + default. + + Returns + ------- + float + The gate's full width at half maximum, s. + + Raises + ------ + solprop.exceptions.ProcessingError + If the time range misses the time window. + + Examples + -------- + >>> import numpy as np + >>> t = np.linspace(-1e-12, 1e-12, 401) + >>> whole, half = default_gate_fwhm(t), default_gate_fwhm(t, (0.0, 9.0)) + >>> round(whole * 1e15, 6), round(half * 1e15, 6) + (100.0, 50.0) + """ + low, high = _gate_range(t, time_range) + return (high - low) / 20.0 + + +def _gate_range( + t: Float[np.ndarray, " n_t"], time_range: tuple[float, float] | None +) -> tuple[float, float]: + """Return the time range of a spectrogram's gate positions, within the window, s.""" + window = (float(t[0]), float(t[-1])) + low, high = window if time_range is None else time_range + low, high = min(low, high), max(low, high) + if high < window[0] or low > window[1]: + msg = ( + f"the time range {time_range!r} holds no gate position: the window is " + f"{window[0]:.4g} s to {window[1]:.4g} s" + ) + raise ProcessingError(msg) + return max(low, window[0]), min(high, window[1]) + + def _gate_transform( dt: float, width: float, span: float, positions: int ) -> "ShortTimeFFT": diff --git a/src/solprop/processing/scans.py b/src/solprop/processing/scans.py index 094626594..0f0356877 100644 --- a/src/solprop/processing/scans.py +++ b/src/solprop/processing/scans.py @@ -228,12 +228,11 @@ def evaluate(self, output: Output, plane: int) -> np.ndarray: if self.operation == "modes": return np.asarray(energy(output, plane=plane)) if self.operation in ("field", "on_axis_intensity", "beam_radius"): - values = ( - output.fields() + return np.asarray( + output.plane_field(plane) if self.operation == "field" - else output[f"stats/{self.operation}"] + else output[f"stats/{self.operation}"][plane] ) - return np.asarray(values[plane]) raise ProcessingError(f"unknown reduction {self.operation}") diff --git a/src/solprop/profiles.py b/src/solprop/profiles.py index c704ab95f..1a41a9f2e 100644 --- a/src/solprop/profiles.py +++ b/src/solprop/profiles.py @@ -85,9 +85,9 @@ pressure the fill evaluates -- the default floor of :data:`DEFAULT_PRESSURE_FLOOR_FRACTION` times the highest stage included -- must square to a normal float. ``(1e-4 * 1e-150)^2 = 1e-308`` is the smallest normal double; below -this the floored end squares to zero and the slope there is infinite. Found by -hypothesis: a fill from 0 to 6.5e-159 bar passed the old exact-zero guard and returned -an infinite derivative at the entrance. +this the floored end squares to zero and the slope there is infinite, as for a fill from +0 to 6.5e-159 bar (found by hypothesis), which an exact-zero guard alone admits with an +infinite derivative at the entrance. """ _DENSITY_SAMPLES: Final = 1024 @@ -1456,8 +1456,8 @@ def __post_init__(self) -> None: def two_point( cls, length: float, - start_bar: float, - end_bar: float, + start_pressure: float, + end_pressure: float, *, floor: float | None = None, radius: float | ZProfile | None = None, @@ -1469,7 +1469,7 @@ def two_point( ---------- length : float Length of the fill in m, > 0. - start_bar, end_bar : float + start_pressure, end_pressure : float Absolute pressures in bar at ``z = 0`` and ``z = length``, >= 0. floor : float or None, optional Smallest pressure in bar any stage end may take. ``None`` uses @@ -1503,7 +1503,7 @@ def two_point( ) return cls.from_stages( [0.0, float(length)], - [start_bar, end_bar], + [start_pressure, end_pressure], floor=floor, radius=radius, weight=weight, diff --git a/src/solprop/pulses.py b/src/solprop/pulses.py index ee6efce94..0ff13470f 100644 --- a/src/solprop/pulses.py +++ b/src/solprop/pulses.py @@ -30,6 +30,7 @@ import io import logging import math +import operator import os import warnings from collections.abc import Callable, Sequence @@ -178,7 +179,8 @@ class SpatialPulse(Displayed): Raises ------ PulseError - If the waist, `m`, distance, Jones vector, displacement or tilt is invalid. + If the temporal pulse is a beam, or the waist, `m`, distance, Jones vector, + displacement or tilt is invalid. Notes ----- @@ -207,10 +209,15 @@ class SpatialPulse(Displayed): def __post_init__(self) -> None: """Validate the beam specification before sampling any grids.""" + if isinstance(self.temporal, SpatialPulse | SpatialPulseSum): + msg = ( + f"the temporal pulse of a SpatialPulse is a " + f"{type(self.temporal).__name__}, which is a beam: give a temporal " + "pulse such as a GaussianPulse" + ) + raise PulseError(msg, parameter="temporal") positive(self.waist, "waist", PulseError, parameter="waist") - if isinstance(self.m, bool) or not isinstance(self.m, int) or self.m < 1: - msg = f"m must be a super-Gaussian order of at least 1, got {self.m!r}" - raise PulseError(msg, parameter="m") + object.__setattr__(self, "m", _order(self.m)) if not math.isfinite(self.propz): msg = "spatial propz must be finite" raise PulseError(msg) @@ -332,7 +339,7 @@ def build( if isinstance(space, PlanarGrid): msg = ( "a planar grid's launch is projected onto its slab modes in x: use " - "PlanarPulse(temporal, waist_y, waist_x=...), not a SpatialPulse" + "PlanarPulse(temporal, waist, waist_x=...), not a SpatialPulse" ) raise PulseError(msg) aligner = _Aligner.of(self, grid, space, medium, plane_sample(medium, z, side)) @@ -912,7 +919,8 @@ class PlanarPulse(SpatialPulse): Raises ------ PulseError - If a waist, `m`, `offset_x`, `propz` or `jones` is invalid. + If a waist, `m`, `offset_x`, `propz` or `jones` is invalid, or + `displacement` or `tilt` is set: they apply on a FreeGrid only. Examples -------- @@ -966,13 +974,13 @@ def __repr__(self) -> str: Returns ------- str - For example ``PlanarPulse(waist_x=47 um, waist_y=2 mm, ...)``. + For example ``PlanarPulse(waist_x=47 um, waist=2 mm, ...)``. """ return line( "PlanarPulse", [ ("waist_x", engineering(self.waist_x, "m")), - ("waist_y", engineering(self.waist, "m")), + ("waist", engineering(self.waist, "m")), ("", repr(self.temporal)), ], ) @@ -1394,6 +1402,22 @@ def _frozen_phase(phases: Sequence[float] | np.ndarray) -> Float[np.ndarray, " n return coefficients +def _order(m: object) -> int: + """Return a super-Gaussian order as an int, refusing one below 1 or not integral. + + A NumPy integer, as an ``np.arange`` of orders gives, is an integer here; a bool + is not. + """ + try: + order = operator.index(m) # pyright: ignore[reportArgumentType] - checked here + except TypeError: + order = 0 + if isinstance(m, bool) or order < 1: + msg = f"m must be a super-Gaussian order of at least 1, got {m!r}" + raise PulseError(msg, parameter="m") + return order + + def _check_delay(grid: TimeGrid, t0: float) -> None: """Reject a delay that would move the pulse out of the time window. @@ -1713,13 +1737,21 @@ def __post_init__(self) -> None: Raises ------ PulseError - If there are no members, or a member has no ``build`` method. + If there are no members, or a member is a beam or has no ``build`` + method. """ members = tuple(self.pulses) if not members: msg = "a PulseSum needs at least one pulse" raise PulseError(msg) for index, member in enumerate(members): + if isinstance(member, SpatialPulse | SpatialPulseSum): + msg = ( + f"member {index} of the PulseSum is a {type(member).__name__}, " + "which is a beam: a PulseSum adds temporal pulses, and a " + "SpatialPulseSum adds beams" + ) + raise PulseError(msg) if not callable(getattr(member, "build", None)): msg = ( f"member {index} of the PulseSum is a {type(member).__name__}, " @@ -1850,13 +1882,11 @@ def __post_init__(self) -> None: Raises ------ PulseError - If ``fwhm`` is not positive or ``m`` is less than one. + If ``fwhm`` is not positive or ``m`` is not an integer of at least one. """ super().__post_init__() positive(self.fwhm, "fwhm", PulseError, parameter="fwhm") - if self.m < 1: - msg = f"m must be a super-Gaussian order of at least 1, got {self.m!r}" - raise PulseError(msg) + object.__setattr__(self, "m", _order(self.m)) def _shape_fields(self) -> list[tuple[str, object]]: """Return the duration, and the order when it is not the plain Gaussian's. diff --git a/src/solprop/recipe/core.py b/src/solprop/recipe/core.py index 88cb4bb2e..939ea8a50 100644 --- a/src/solprop/recipe/core.py +++ b/src/solprop/recipe/core.py @@ -783,14 +783,7 @@ def resolve(self) -> "Recipe": """ self._require_keywords() pins = read_pins(self) - working = self._copy(("pins",)) - for pin in pins: - if pin.stage == "pulse": - working._document["build"] = set_path( - working._document["build"], - parse_path(pin.path), - placeholder(pin.path), - ) + working = self._working_copy(pins) for pin in pins: value = _pick(pin, working._solve(pin)) working._document["build"] = set_path( @@ -828,14 +821,7 @@ def pin_roots(self, path: str) -> "DesignRoots": if chosen is None: msg = "this path is not pinned" raise RecipeError(msg, path=path) - working = self._copy(("pins",)) - for pin in pins: - if pin.stage == "pulse": - working._document["build"] = set_path( - working._document["build"], - parse_path(pin.path), - placeholder(pin.path), - ) + working = self._working_copy(pins) if chosen.stage == "pulse": for pin in pins: if pin.stage == "guide": @@ -895,6 +881,18 @@ def preview_input(self) -> "InputPreview": """ return preview.preview_input(self) + def _working_copy(self, pins: Sequence[Pin]) -> "Recipe": + """Return a copy to solve pins on: no ``[pins]``, pulse pins at placeholders.""" + working = self._copy(("pins",)) + for pin in pins: + if pin.stage == "pulse": + working._document["build"] = set_path( + working._document["build"], + parse_path(pin.path), + placeholder(pin.path), + ) + return working + def _copy(self, drop: tuple[str, ...]) -> "Recipe": """Return a copy without some top-level tables, its data files kept.""" document = { @@ -1330,7 +1328,9 @@ def resume_file( Resuming a file runs the setup it holds. A file received from someone else does not choose its own limit: the recipe's ``node_budget`` is ignored, and the caller's - applies. + applies. A data file the run recorded by name only, beyond the 16 MiB it embeds + (:data:`~solprop.recipe.provenance.EMBED_LIMIT`), is not in the file, so such a + file does not resume on its own. Parameters ---------- @@ -1354,16 +1354,13 @@ def resume_file( Raises ------ RecipeError - If the file records no recipe, or one of a newer format. + If the file records no recipe, or one of a newer format, or its recipe refers + to a data file the file does not hold. """ - recipe = Recipe.from_output(path, resolved=True) - document = recipe.to_dict() - document["build"].pop("node_budget", None) + rebuilt = Recipe.from_output(path, resolved=True)._copy(()) + rebuilt._document["build"].pop("node_budget", None) if node_budget is not None: - document["build"]["node_budget"] = node_budget - rebuilt = Recipe(document) - rebuilt._embedded = recipe._embedded - rebuilt._filed = recipe._filed + rebuilt.set("node_budget", node_budget) return rebuilt.build().run( Path(path), resume=mode, @@ -1394,7 +1391,8 @@ class RecipeBuilder: Attributes ---------- text : str - The recipe, without its ``[scan]`` and ``[execution]`` tables. + The recipe, without its ``[scan]`` table and the ``[execution]`` keys + :func:`~solprop.driver.scan.run_scan` takes. base : str or None Its directory, for data files. allow_outside : bool diff --git a/src/solprop/recipe/metadata.py b/src/solprop/recipe/metadata.py index 7118f5a68..947ef5186 100644 --- a/src/solprop/recipe/metadata.py +++ b/src/solprop/recipe/metadata.py @@ -409,15 +409,6 @@ def _raman(values: Mapping[str, object]) -> Resolution: ) -def _pressure(values: Mapping[str, object]) -> Resolution: - """Return the capillary's default pressure. - - - Returns: one bar. - """ - del values - return Resolution(1.0, "one bar when no pressure is given") - - # ------------------------------------------------------------------- the forms @@ -906,11 +897,10 @@ def _capillary() -> tuple[Parameter, ...]: ), "medium", "basic", - "Fill pressure: a number, an end-to-end gradient, (z, p) pairs or a " - "profile.", + "Fill pressure, required beside a gas: a number, an end-to-end " + "gradient, (z, p) pairs or a profile.", "guide/media/mixtures.md", display="bar", - resolver=_pressure, ), Parameter( "pressure_floor", @@ -1194,7 +1184,6 @@ def _waveguide() -> tuple[Parameter, ...]: """ supplied = "guide/waveguides/supplied-guides.md" provider = f"{supplied}#a-guide-instead-of-a-fill" - general = "guide/waveguides/general-modal.md" beam = "guide/workflows/coupling.md#a-beam-into-a-general-modal-guide" rule = "guide/waveguides/mode-sets.md#the-transverse-quadrature" return ( @@ -1253,22 +1242,6 @@ def _waveguide() -> tuple[Parameter, ...]: "The cubic a provider's material regions respond with.", provider, ), - Parameter( - "observable_rtol", - (Form("number", minimum=0.0),), - "numerics", - "advanced", - "Accuracy of a provider run's observables; only the solver's own, none.", - f"{general}#declared-refused-recorded", - ), - Parameter( - "observable_atol", - (Form("number", minimum=0.0),), - "numerics", - "advanced", - "Accuracy of a provider run's observables; only the solver's own, none.", - f"{general}#declared-refused-recorded", - ), Parameter( "n_r", (Form("integer", minimum=1),), diff --git a/src/solprop/recipe/preview.py b/src/solprop/recipe/preview.py index 3bffa1f8a..37611a534 100644 --- a/src/solprop/recipe/preview.py +++ b/src/solprop/recipe/preview.py @@ -75,8 +75,10 @@ class ModePreview: aeff : float Effective area in m^2; for a slab mode, an effective width in m. zdw : float or None - Zero-dispersion wavelength in m within the band, or ``None`` where the - dispersion keeps one sign across it (or changes it more than once). + Zero-dispersion wavelength in m within the band, the one nearest the grid's + reference wavelength as the ``zdw`` statistic records it + (:func:`solprop.modes.base.zdw` with ``near``), or ``None`` where the band + holds none on the reference's side of the lines. gamma : numpy.ndarray or None The nonlinear coefficient ``n2 omega / (c A_eff)`` in rad/(W m), with the fill's ``n2`` at the grid's reference wavelength, the carrier its Kerr data @@ -248,7 +250,9 @@ def modes(recipe: "Recipe", z: float | None = None) -> ModeSetPreview: previews = [] for mode in channels: try: - zero: float | None = zdw(mode, at, wavelength_limits=limits) + zero: float | None = zdw( + mode, at, wavelength_limits=limits, near=grid.reference_wavelength + ) except ModeError: zero = None area = aeff(mode, at) diff --git a/src/solprop/recipe/registry.py b/src/solprop/recipe/registry.py index c6ca4de8b..22455fce0 100644 --- a/src/solprop/recipe/registry.py +++ b/src/solprop/recipe/registry.py @@ -226,8 +226,8 @@ def _pressure_pair(index: int) -> Unit: } _GRADIENT_UNITS: Final[Mapping[str, UnitSpec]] = { "length": "m", - "start_bar": "bar", - "end_bar": "bar", + "start_pressure": "bar", + "end_pressure": "bar", "floor": "bar", "radius": "m", "positions": "m", @@ -723,8 +723,9 @@ def plane_parameter(error: DriverError) -> str | None: def refuse_plane_count(key: str, value: object, path: str) -> None: """Refuse a bare integer given as ``save_planes``, naming ``n_save`` (SEP 51). - A recipe once read ``save_planes = 80`` as one plane at 80 m (#533); positions and - a count have one name each, so the integer is refused with the fix. + A bare number is ambiguous between a count of planes and one plane's position in + m; positions and a count have one name each, so the integer is refused with the + fix. Parameters ---------- diff --git a/src/solprop/recipe/type_metadata.py b/src/solprop/recipe/type_metadata.py index 17fede6df..58ce01b44 100644 --- a/src/solprop/recipe/type_metadata.py +++ b/src/solprop/recipe/type_metadata.py @@ -495,9 +495,15 @@ def _plasma(*extra: Row) -> tuple[Parameter, ...]: "PressureGradient.two_point": _gradient( _keyword("length", _LENGTH, "basic", "Length of the fill.", display="m"), _keyword( - "start_bar", _PRESSURE, "basic", "Pressure at the entrance.", display="bar" + "start_pressure", + _PRESSURE, + "basic", + "Pressure at the entrance.", + display="bar", + ), + _keyword( + "end_pressure", _PRESSURE, "basic", "Pressure at the exit.", display="bar" ), - _keyword("end_bar", _PRESSURE, "basic", "Pressure at the exit.", display="bar"), ), "PressureGradient.from_stages": _gradient( _keyword( @@ -652,7 +658,7 @@ def _plasma(*extra: Row) -> tuple[Parameter, ...]: "FieldGrid.from_limits": _grid( _keyword( "ffac", - _number(minimum=2.0), + _number(minimum=2.2), "advanced", "Fine-grid oversampling factor; 6 resolves a cubic response.", ), @@ -1033,12 +1039,6 @@ def _plasma(*extra: Row) -> tuple[Parameter, ...]: "Carrier wavelength the carrier coefficients are evaluated at.", display="nm", ), - _keyword( - "energy_loss", - _choice("peak-weighted"), - "advanced", - "The plasma energy-loss convention.", - ), _keyword( "raman_shift", _choice("reference-density"), diff --git a/src/solprop/scan.py b/src/solprop/scan.py index ce06dac20..26eda0942 100644 --- a/src/solprop/scan.py +++ b/src/solprop/scan.py @@ -63,8 +63,10 @@ def main(argv: Sequence[str] | None = None) -> int: epilog=_COLLECT_HELP, formatter_class=argparse.RawDescriptionHelpFormatter, ) - parser.add_argument("queue", type=Path) - parser.add_argument("--output", "-o", type=Path, required=True) + parser.add_argument("queue", type=Path, help="the shared queue directory") + parser.add_argument( + "--output", "-o", type=Path, required=True, help="the scan file to write" + ) args = parser.parse_args(arguments[1:]) collect(args.queue, args.output) return 0 @@ -94,25 +96,87 @@ def _parser() -> argparse.ArgumentParser: epilog=_COLLECT_HELP, formatter_class=argparse.RawDescriptionHelpFormatter, ) - parser.add_argument("script", type=Path) - parser.add_argument("--local", action="store_true") - parser.add_argument("--queue", type=Path) - parser.add_argument("--chunk") - parser.add_argument("--submit", action="store_true") - parser.add_argument("--emit-slurm", type=Path) - parser.add_argument("--workers", type=int) - parser.add_argument("--threads", type=int, default=1) - parser.add_argument("--memory-limit", type=int) - parser.add_argument("--fresh", action="store_true") - parser.add_argument("--stale-age", type=float, default=600.0) - parser.add_argument("--ntasks", type=int, default=1) - parser.add_argument("--cpus-per-task", type=int, default=1) - parser.add_argument("--mem", default="4G") - parser.add_argument("--time", default="01:00:00") - parser.add_argument("--partition") - parser.add_argument("--gres") - parser.add_argument("--mode", choices=("queue", "chunk"), default="queue") - parser.add_argument("--instances", type=int, default=0) + parser.add_argument("script", type=Path, help="the scan script to run") + parser.add_argument( + "--local", + action="store_true", + help="run every point in this process, one after another", + ) + parser.add_argument( + "--queue", type=Path, help="the shared queue directory to claim points from" + ) + parser.add_argument( + "--chunk", + help="claim only chunk k of n of the points, zero-based, written k/n", + ) + parser.add_argument( + "--submit", action="store_true", help="submit the scan as a Slurm array" + ) + parser.add_argument( + "--emit-slurm", + type=Path, + help="write the Slurm array script to this file instead of submitting it", + ) + parser.add_argument( + "--workers", + type=int, + help="the most worker processes (default: as the CPUs and memory admit)", + ) + parser.add_argument( + "--threads", type=int, default=1, help="threads per worker (default: 1)" + ) + parser.add_argument( + "--memory-limit", + type=int, + help="the memory the workers may use, in bytes (default: the allocation's)", + ) + parser.add_argument( + "--fresh", + action="store_true", + help="start a fresh interpreter for every point", + ) + parser.add_argument( + "--stale-age", + type=float, + help="seconds after which a queue claim on a point lapses, with --queue, " + "--chunk or a Slurm mode (default: 600)", + ) + parser.add_argument( + "--ntasks", type=int, default=1, help="Slurm array tasks (default: 1)" + ) + parser.add_argument( + "--cpus-per-task", + type=int, + default=1, + help="CPUs allocated to each Slurm task (default: 1)", + ) + parser.add_argument( + "--mem", + default="4G", + help="memory for each Slurm task, MiB without a K/M/G/T suffix (default: 4G)", + ) + parser.add_argument( + "--time", + default="01:00:00", + help="the Slurm wall-clock limit of each task (default: 01:00:00)", + ) + parser.add_argument("--partition", help="the Slurm partition") + parser.add_argument( + "--gres", help="Slurm generic resources for each task, for example gpu:1" + ) + parser.add_argument( + "--mode", + choices=("queue", "chunk"), + default="queue", + help="Slurm tasks claim points from a shared queue, or each runs a disjoint " + "chunk (default: queue)", + ) + parser.add_argument( + "--instances", + type=int, + default=0, + help="controllers per Slurm task; 0 runs one (default: 0)", + ) return parser @@ -129,6 +193,12 @@ def _policy(args: argparse.Namespace, parser: argparse.ArgumentParser) -> Execut parser.error("--local cannot be combined with queue, chunk or Slurm modes") if args.local and worker_controls: parser.error("--local cannot use process-pool resource controls") + queued = args.queue is not None or args.chunk is not None + if args.stale_age is not None and not (queued or slurm): + parser.error( + "--stale-age is a queue lease: use it with --queue, --chunk or Slurm" + ) + lease = {} if args.stale_age is None else {"stale_age": args.stale_age} if slurm: if args.memory_limit is not None: parser.error("use --mem for a Slurm allocation") @@ -148,6 +218,7 @@ def _policy(args: argparse.Namespace, parser: argparse.ArgumentParser) -> Execut workers=args.workers, threads=args.threads, fresh=args.fresh, + **lease, ) chunk = None if args.chunk is not None: @@ -156,10 +227,10 @@ def _policy(args: argparse.Namespace, parser: argparse.ArgumentParser) -> Execut chunk = (int(k), int(n)) except ValueError as error: parser.error(f"chunk must be zero-based k/n: {error}") - if args.queue is not None or chunk is not None: + if queued: return Queue( args.queue, - stale_age=args.stale_age, + **lease, pool=Pool( workers=args.workers, memory_limit=args.memory_limit, diff --git a/src/solprop/service/agent.py b/src/solprop/service/agent.py index b82d90455..ce65ec842 100644 --- a/src/solprop/service/agent.py +++ b/src/solprop/service/agent.py @@ -47,6 +47,7 @@ "FOLLOW_PERIOD", "LIVENESS_PERIOD", "REQUESTS", + "SLURM_LIVENESS_PERIOD", "Agent", "hello", "main", @@ -58,6 +59,11 @@ LIVENESS_PERIOD: Final = 2.0 """How often a followed run with a quiet record is checked for having gone, s.""" +SLURM_LIVENESS_PERIOD: Final = 60.0 +"""How often a followed Slurm run with a quiet record is checked for having gone, s: +each check asks the scheduler (``squeue``), which sites ask not to be polled often, and +a queued job is quiet for as long as it waits.""" + FOLLOW_LIMITS: Final = (0.02, 5.0) """The shortest and longest period a window may ask a record to be read at, s.""" @@ -189,7 +195,10 @@ def start(self, body: Mapping[str, Any]) -> dict[str, Any]: Raises ------ solprop.service.messages.ServiceError - For a launcher that is not known. + For a launcher that is not known, a continuation of a run that has not + ended or whose Slurm job the scheduler cannot be asked about, or a run + that could not be launched (a continued run's folder is then left as it + was). """ from dataclasses import replace # noqa: PLC0415 - light @@ -199,21 +208,36 @@ def start(self, body: Mapping[str, Any]) -> dict[str, Any]: start_direct, submit_slurm, ) + from solprop.service.record import _aside_number, put_back # noqa: PLC0415 from solprop.service.runs import summarise # noqa: PLC0415 - light spec = spec_from_value(body["spec"]) spec = replace(spec, folder=str(Path(spec.folder).expanduser())) - folder = prepare(spec) - python = str(Path(str(body.get("python") or sys.executable)).expanduser()) launcher = body.get("launcher", "direct") - if launcher == "direct": - start_direct(folder, python) - elif launcher == "slurm": - resources = SlurmResources.from_value(body.get("resources") or {}) - submit_slurm(folder, python, resources, threads=spec.threads) - else: + if launcher not in {"direct", "slurm"}: msg = f"no launcher {launcher!r}: 'direct' or 'slurm'" raise ServiceError(msg) + aside = None + if spec.resume is not None: + state = _scheduled(Path(spec.folder), "continued")["state"] + if state in _GOING: + msg = f"{Path(spec.folder).name} is {state}: continue it once it ends" + raise ServiceError(msg) + aside = _aside_number(Path(spec.folder)) # where prepare sets it aside + python = str(Path(str(body.get("python") or sys.executable)).expanduser()) + try: + folder = prepare(spec) + if launcher == "direct": + start_direct(folder, python) + else: + resources = SlurmResources.from_value(body.get("resources") or {}) + submit_slurm(folder, python, resources, threads=spec.threads) + except Exception: + if aside is not None: + # Not launched: the earlier part's record, its ending included, is + # the run's again, and the failure goes to the window. + put_back(Path(spec.folder), aside) + raise return summarise(folder) def follow(self, body: Mapping[str, Any]) -> int: @@ -261,13 +285,18 @@ def _follow( A run that has gone without recording an ending (its process killed, out of memory, its job cancelled) is said ``lost``, from its state (:func:`~solprop.service.runs.summarise`) checked every - :data:`LIVENESS_PERIOD` seconds while its record stays quiet. + :data:`LIVENESS_PERIOD` seconds while its record stays quiet, or every + :data:`SLURM_LIVENESS_PERIOD` seconds for a Slurm run. The terminal event is sent only once the run's summary records its ending (:mod:`solprop.service.record`), so a window that hears a run has ended finds it ended in a list of runs and can continue it at once; a run that goes - between the two has its terminal event sent as it wrote it. + between the two has its terminal event sent as it wrote it, and one whose + record could not take its terminal event has it sent from its summary. """ + from solprop.service.runs import slurm_jobs # noqa: PLC0415 - light + + liveness = SLURM_LIVENESS_PERIOD if slurm_jobs([folder]) else LIVENESS_PERIOD checked = time.monotonic() while not done.is_set(): try: @@ -282,7 +311,7 @@ def _follow( ) return held = any(e.terminal for e in events) and not _ending_recorded(folder) - if held and time.monotonic() - checked >= LIVENESS_PERIOD: + if held and time.monotonic() - checked >= liveness: checked = time.monotonic() held = _lost(folder) is None if held: @@ -304,15 +333,30 @@ def _follow( ) if any(event.terminal for event in events): return - elif time.monotonic() - checked >= LIVENESS_PERIOD: + elif time.monotonic() - checked >= liveness: checked = time.monotonic() + ending = _summary_ending(folder, offset) + if ending is not None: + self.send( + { + "kind": "events", + "folder": key, + "offset": offset, + "events": [ending], + } + ) + return lost = _lost(folder) if lost is not None: # Gone without an ending: killed, out of memory, cancelled. lost_event = { "run_id": folder.name, "kind": "lost", - "data": {"exitcode": None, "message": lost}, + "data": { + "message": str(lost["detail"]), + "output": lost["output"], + "scan": lost["scan"], + }, } self.send( { @@ -350,9 +394,11 @@ def stop(self, body: Mapping[str, Any]) -> None: def cancel(self, body: Mapping[str, Any]) -> None: """End a run's job: ``scancel``, or ``SIGTERM`` to its process (``cancel``). - Either way solprop writes where the run stood, so it can be resumed. With - ``force``, a process of this machine is killed outright (``SIGKILL``), for a run - that does not end on ``SIGTERM``; its file may then hold no restart state. + Only the Slurm job solprop submitted the run as is cancelled; a run started + directly is signalled, even inside a Slurm allocation, which goes on. Either + way solprop writes where the run stood, so it can be resumed. With ``force``, a + process of this machine is killed outright (``SIGKILL``), for a run that does + not end on ``SIGTERM``; its file may then hold no restart state. Parameters ---------- @@ -362,10 +408,15 @@ def cancel(self, body: Mapping[str, Any]) -> None: Raises ------ solprop.service.messages.ServiceError - If the run has no job this machine can end. + If the run has no job this machine can end, or its process's start was + not recorded, so that its number cannot be told from a later process's. """ - from solprop.service.launch import cancel_slurm # noqa: PLC0415 - light - from solprop.service.record import alive, read_job # noqa: PLC0415 - light + from solprop.service.launch import SUBMITTED, cancel_slurm # noqa: PLC0415 + from solprop.service.record import ( # noqa: PLC0415 - light + _read_json, + alive, + read_job, + ) from solprop.service.runs import summarise # noqa: PLC0415 - light folder = _folder(body) @@ -374,10 +425,25 @@ def cancel(self, body: Mapping[str, Any]) -> None: cancel_slurm(str(summary["slurm_job"])) return job = read_job(folder) - if job is not None and job.host == socket.gethostname(): - if alive(job.pid, job.stamp): - hard = getattr(signal, "SIGKILL", signal.SIGTERM) - os.kill(job.pid, hard if body.get("force") else signal.SIGTERM) + if job is not None: + host, pid, stamp = job.host, job.pid, job.stamp + else: + # Started and not yet recorded: the process its launcher started. + submitted = _read_json(folder / SUBMITTED) or {} + host = submitted.get("host") + pid, stamp = int(submitted.get("pid", -1)), submitted.get("stamp") + if host == socket.gethostname(): + if not alive(pid, stamp): + return # gone: nothing to end + if stamp is None: + # Its number alone may by now be another process's. + msg = ( + f"{folder.name}'s process {pid} cannot be told from another with " + "its number, as its start was not recorded: end it by hand" + ) + raise ServiceError(msg) + hard = getattr(signal, "SIGKILL", signal.SIGTERM) + os.kill(pid, hard if body.get("force") else signal.SIGTERM) return msg = f"{folder.name} has no process or job on this machine to end" raise ServiceError(msg) @@ -393,13 +459,12 @@ def remove(self, body: Mapping[str, Any]) -> None: Raises ------ solprop.service.messages.ServiceError - If the run has not ended, or the folder holds no run. + If the run has not ended or its Slurm job the scheduler cannot be asked + about, or the folder holds no run. """ - from solprop.service.runs import summarise # noqa: PLC0415 - light - folder = _folder(body) - summary = summarise(folder) - if summary["state"] in {"queued", "starting", "running"}: + summary = _scheduled(folder, "removed") + if summary["state"] in _GOING: msg = f"{folder.name} is {summary['state']}: stop or cancel it first" raise ServiceError(msg) if not any((folder / name).exists() for name in ("recipe.toml", "spec.json")): @@ -572,20 +637,72 @@ def _ending_recorded(folder: Path) -> bool: return "ending" in (read_status(folder) or {}) -def _lost(folder: Path) -> str | None: - """Return why a run that recorded no ending has gone, or ``None`` while it lives. +def _summary_ending(folder: Path, offset: int) -> dict[str, Any] | None: + """Return the ending a run's summary records and its record lacks, as an event. + + The record misses the terminal event only when it could not be written (and the + record not cut back to its whole frames); the summary, written after it, still + has the ending. + + - ``offset``: where the record has been read to, bytes. + - Returns: the terminal event; ``None`` without a recorded ending, or with + events in the record still to be read (the terminal one among them). + """ + status = read_status(folder) or {} + ending = status.get("ending") + if not isinstance(ending, Mapping) or read_events(folder, offset)[0]: + return None + return { + "run_id": str(status.get("run_id") or folder.name), + "kind": str(ending.get("kind")), # pyright: ignore[reportUnknownMemberType] + "data": dict(ending.get("data") or {}), # pyright: ignore[reportUnknownMemberType, reportUnknownArgumentType] + } + + +_GOING: Final = frozenset({"queued", "starting", "running"}) +"""The states of a run that has not ended.""" + + +def _summary(folder: Path) -> dict[str, Any]: + """Return a run's summary, with the scheduler's word on its own Slurm job. - - Returns: the reason, as the run's summary gives it; ``None`` for a run queued, - starting, running or ended with its own record. + One query names that job alone; a run with no Slurm job of its own, or whose + ending is recorded, asks nothing. + + - Raises: :class:`ServiceError` where the scheduler cannot be asked about the + run's job. """ from solprop.service.launch import slurm_states # noqa: PLC0415 - light from solprop.service.runs import slurm_jobs, summarise # noqa: PLC0415 - light jobs = slurm_jobs([folder]) + return summarise(folder, slurm_states(jobs, strict=True) if jobs else None) + + +def _scheduled(folder: Path, doing: str) -> dict[str, Any]: + """Return a run's summary (:func:`_summary`) before it is ``doing``, or refuse. + + - ``doing``: what is refused, as ``"removed"``. + - Raises: :class:`ServiceError` where the scheduler cannot be asked, saying so. + """ + try: + return _summary(folder) + except ServiceError as error: + msg = f"{folder.name} is not {doing}: {error}" + raise ServiceError(msg) from error + + +def _lost(folder: Path) -> dict[str, Any] | None: + """Return the summary of a run that has gone without an ending, or ``None``. + + - Returns: its summary, whose ``detail`` says why (empty when it gives none); + ``None`` for a run queued, starting, running or ended with its own record, and + while the scheduler cannot be asked. + """ with contextlib.suppress(ServiceError): - summary = summarise(folder, slurm_states(jobs) if jobs else None) + summary = _summary(folder) if summary["state"] == "lost": - return str(summary["detail"] or "its process ended without saying how") + return summary return None diff --git a/src/solprop/service/design.py b/src/solprop/service/design.py index 52609ea63..0be7ea8b2 100644 --- a/src/solprop/service/design.py +++ b/src/solprop/service/design.py @@ -6,7 +6,7 @@ The waveguide explorer draws what ``Recipe.modes`` gives, per mode, as plain arrays, for the recipe as it is or for each value of one keyword swept; the pins' editors ask -what a route can pin and, for a pinned value, every root solprop finds. Like +what a route can pin. Like :mod:`solprop.service.handlers`, this module runs only in the kernel process and computes nothing of its own. """ @@ -27,7 +27,6 @@ "DESIGN_HANDLERS", "PRESSURE_ZDW_KEYWORDS", "modes", - "pin_roots", "pin_targets", "zdw_chart", ] @@ -183,32 +182,6 @@ def pin_targets(payload: Payload) -> dict[str, list[dict[str, object]]]: return found -def pin_roots(payload: Payload) -> dict[str, object]: - """Return every root of one pin's target (``Recipe.pin_roots``). - - Parameters - ---------- - payload : Mapping - ``text``, optionally ``base``, and ``path``, the pinned path. - - Returns - ------- - dict - ``roots`` (ascending, in the keyword's unit), ``search``, ``quantity`` (what - ``attainable`` measures) and ``attainable`` (the range of it reached when no - root is found, or ``None``). - """ - found = read_recipe(payload).pin_roots(str(payload["path"])) - return { - "roots": [float(root) for root in found.roots], - "search": [float(end) for end in found.search], - "quantity": found.quantity, - "attainable": ( - None if found.attainable is None else [float(v) for v in found.attainable] - ), - } - - PRESSURE_ZDW_KEYWORDS = ("temperature", "model", "cladding", "materials") """The capillary's keywords that ``tools.pressure_zdw`` also takes, by name.""" @@ -295,7 +268,6 @@ def zdw_chart(payload: Payload) -> dict[str, object]: DESIGN_HANDLERS = { "modes": modes, - "pin_roots": pin_roots, "pin_targets": pin_targets, "zdw_chart": zdw_chart, } diff --git a/src/solprop/service/job.py b/src/solprop/service/job.py index 5eaf113d7..4f73e68a1 100644 --- a/src/solprop/service/job.py +++ b/src/solprop/service/job.py @@ -4,11 +4,16 @@ """A run with no window: ``python -m solprop.service.job FOLDER`` (design 13.4). -What a window's worker does over pipes, this does from a folder alone. It reads the -run's spec from ``spec.json`` (:data:`~solprop.service.worker.SPEC`), runs it with its -record (:mod:`solprop.service.record`), and exits. It is how a run starts directly on a +Every run is this process, and needs nothing but its folder. It reads the run's spec +from ``spec.json`` (:data:`~solprop.service.worker.SPEC`), runs it with its record +(:mod:`solprop.service.record`), and exits. It is how a run starts directly on a machine, as a detached process, and inside a Slurm job; it outlives whoever started it, and anyone who can read the folder can follow it. + +``--slurm`` says the process is the Slurm job solprop submitted for the run (its batch +script, :func:`~solprop.service.launch.slurm_script`, passes it), so the run records +that job as its own. Without it the run is a direct one, even inside a Slurm +allocation: the allocation is not the run's to cancel. """ import json @@ -30,7 +35,8 @@ def main(argv: Sequence[str] | None = None) -> int: Parameters ---------- argv : Sequence of str or None, optional - The folder, alone; ``None`` reads the command line. + The folder, after ``--slurm`` for the Slurm job solprop submitted for the run; + ``None`` reads the command line. Returns ------- @@ -39,8 +45,12 @@ def main(argv: Sequence[str] | None = None) -> int: record says), 2 when the folder holds no spec. """ arguments = list(sys.argv[1:] if argv is None else argv) + slurm = arguments[:1] == ["--slurm"] + if slurm: + del arguments[0] if len(arguments) != 1: - print("usage: python -m solprop.service.job FOLDER", file=sys.stderr) # noqa: T201 + usage = "usage: python -m solprop.service.job [--slurm] FOLDER" + print(usage, file=sys.stderr) # noqa: T201 return 2 folder = Path(arguments[0]).resolve() try: @@ -49,8 +59,7 @@ def main(argv: Sequence[str] | None = None) -> int: except (OSError, ValueError, ServiceError) as error: print(f"no run to start in {folder}: {error}", file=sys.stderr) # noqa: T201 return 2 - launcher = "slurm" if os.environ.get("SLURM_JOB_ID") else "direct" - spec = replace(spec, folder=str(folder), launcher=launcher) + spec = replace(spec, folder=str(folder), launcher="slurm" if slurm else "direct") if spec.threads is not None: os.environ["SOLPROP_THREADS"] = str(spec.threads) from solprop.service.run import execute # noqa: PLC0415 - after the threads diff --git a/src/solprop/service/kernel.py b/src/solprop/service/kernel.py index eba9a9c1f..dc6474d3c 100644 --- a/src/solprop/service/kernel.py +++ b/src/solprop/service/kernel.py @@ -28,7 +28,7 @@ KERNEL_THREADS = "2" """The thread budget of the kernel process (``SOLPROP_THREADS``).""" -RUN_THREADS = "SOLPROP_GUI_RUN_THREADS" +RUN_THREADS = "SOLPROP_SERVICE_RUN_THREADS" """Where the kernel keeps the ``SOLPROP_THREADS`` it started with, empty for unset.""" Handler = Callable[[Mapping[str, object]], object] @@ -138,9 +138,15 @@ def serve( The handlers, by kind; ``None`` imports solprop's (:data:`solprop.service.handlers.HANDLERS`). """ - # What a run would get: a run's worker starts from the window's environment. + # What a run would get: a run's process starts from the window's environment. + # The kernel's own budget is its own, whatever the window was started with. os.environ[RUN_THREADS] = os.environ.get("SOLPROP_THREADS", "") - os.environ.setdefault("SOLPROP_THREADS", KERNEL_THREADS) + os.environ["SOLPROP_THREADS"] = KERNEL_THREADS + # Figures are only ever written to files or bytes: never an interactive backend, + # which on macOS would open a window server connection from a background process. + import matplotlib # noqa: PLC0415 - child only + + matplotlib.use("Agg") # solprop's check reports a material out of its range on the Ready line; the # same warning from every edit's numbers would only fill the terminal. warnings.filterwarnings("ignore", category=MaterialRangeWarning) diff --git a/src/solprop/service/launch.py b/src/solprop/service/launch.py index 315eaa7df..a2a623c62 100644 --- a/src/solprop/service/launch.py +++ b/src/solprop/service/launch.py @@ -31,8 +31,8 @@ from solprop._process import batch_script, child_environment from solprop.service.messages import ServiceError -from solprop.service.record import process_stamp, set_aside, write_json -from solprop.service.worker import SPEC, RunSpec, spec_value +from solprop.service.record import clear_stop, process_stamp, set_aside, write_json +from solprop.service.worker import OUTPUT, SCAN_OUTPUT, SPEC, RunSpec, spec_value __all__ = [ "JOB_OUTPUT", @@ -82,20 +82,27 @@ def prepare(spec: RunSpec) -> Path: Raises ------ solprop.service.messages.ServiceError - If the folder already holds a run that has not been continued. + If the folder already holds a run's or a scan's results and the run is not + a continuation. Notes ----- A continued run's earlier record is set aside - (:func:`~solprop.service.record.set_aside`). + (:func:`~solprop.service.record.set_aside`), and a stop file already in the folder + is removed, so a stop file found by the run when it starts is a Stop pressed while + it waited, and is obeyed. """ folder = Path(spec.folder).expanduser() folder.mkdir(parents=True, exist_ok=True) - if spec.resume is None and (folder / "run.h5").exists(): + if spec.resume is None and any( + (folder / name).exists() for name in (OUTPUT, SCAN_OUTPUT) + ): msg = f"{folder} already holds a run; a new run needs a folder of its own" raise ServiceError(msg) if spec.resume is not None: set_aside(folder) + else: + clear_stop(folder) write_json(folder / SPEC, spec_value(spec)) return folder @@ -303,7 +310,7 @@ def slurm_script( >>> resources = SlurmResources(cpus=4) >>> script = slurm_script(Path("/runs/r1"), "/env/bin/python", resources) >>> "#SBATCH --cpus-per-task=4" in script, script.splitlines()[-1] - (True, 'exec /env/bin/python -m solprop.service.job /runs/r1') + (True, 'exec /env/bin/python -m solprop.service.job --slurm /runs/r1') """ name = re.sub(r"[^A-Za-z0-9_.-]", "_", folder.name)[:40] posix = folder.as_posix() # a cluster's path, whatever this computer writes @@ -324,7 +331,7 @@ def slurm_script( *(line for line in resources.setup if line.strip()), ] budget = str(threads) if threads is not None else "${SLURM_CPUS_PER_TASK:-1}" - command = shlex.join([python, "-m", "solprop.service.job", posix]) + command = shlex.join([python, "-m", "solprop.service.job", "--slurm", posix]) return batch_script( directives, [f"export SOLPROP_THREADS={budget}", f"exec {command}"], site=site ) @@ -415,18 +422,28 @@ class SlurmState: reason: str = "" -def slurm_states(jobs: Sequence[str]) -> dict[str, SlurmState]: +def slurm_states(jobs: Sequence[str], *, strict: bool = False) -> dict[str, SlurmState]: """Return the states of Slurm jobs: from the queue, else from the accounts. Parameters ---------- jobs : Sequence of str The jobs. + strict : bool, optional + Whether a job the scheduler could not be asked about is an error: ``squeue`` + failed for another reason than not knowing it, and ``sacct`` gave no state. Returns ------- dict Each job's state, by job; a job neither command knows is left out. + + Raises + ------ + solprop.service.messages.ServiceError + If a command is not on this machine or does not answer in time, and with + `strict` for a job the scheduler could not be asked about, with what + ``squeue`` said. """ if not jobs: return {} @@ -457,6 +474,17 @@ def slurm_states(jobs: Sequence[str]) -> dict[str, SlurmState]: if len(parts) == 2 and parts[0] in missing: # "CANCELLED by 1234" names who cancelled it. found[parts[0]] = SlurmState(parts[1].split()[0]) + said = (queue.stderr or queue.stdout).strip() or f"status {queue.returncode}" + unasked = [job for job in jobs if job not in found] + # squeue refuses a job it no longer holds with "Invalid job id": an answer. + if ( + strict + and unasked + and queue.returncode != 0 + and "invalid job id" not in said.lower() + ): + msg = f"Slurm could not be asked about job {', '.join(unasked)}: {said}" + raise ServiceError(msg) return found diff --git a/src/solprop/service/machines.py b/src/solprop/service/machines.py index c479c9031..79e1e4d1e 100644 --- a/src/solprop/service/machines.py +++ b/src/solprop/service/machines.py @@ -134,8 +134,10 @@ class Machine: port : int or None A port other than the configuration's. python : str - The Python with solprop on the machine, as its shell finds it (``~`` is - expanded there). + The Python with solprop on the machine: one path, a leading ``~/`` standing + for the home folder there, or a command its shell finds on its ``PATH`` + (``"python3"``). It is quoted whole, so variables, ``~user`` and options + are not read. workspace : str The folder of its runs, on the machine. launcher : str @@ -223,8 +225,8 @@ def ssh_command( Examples -------- >>> command, _ = ssh_command(Machine("lab", "me@lab", port=2222), "true") - >>> command[0], command[-2:], "2222" in command - ('ssh', ['me@lab', 'true'], True) + >>> command[0], command[-3:], "2222" in command + ('ssh', ['--', 'me@lab', 'true'], True) """ if not machine.destination: msg = f"{machine.name} has no SSH host" @@ -257,7 +259,8 @@ def ssh_command( environment["SSH_ASKPASS"] = askpass environment["SSH_ASKPASS_REQUIRE"] = "force" environment.setdefault("DISPLAY", ":0") - return ["ssh", *options, str(machine.destination), remote], environment + # "--" ends the options: a destination is never read as one. + return ["ssh", *options, "--", str(machine.destination), remote], environment def agent_command( @@ -285,15 +288,25 @@ def agent_command( Examples -------- >>> command, _ = agent_command(Machine("lab", "me@lab", python="~/env/bin/python")) - >>> command[0], command[-2:] - ('ssh', ['me@lab', 'exec ~/env/bin/python -m solprop.service.agent']) + >>> command[0], command[-1] + ('ssh', 'exec "$HOME"/env/bin/python -m solprop.service.agent') """ if machine.local: return [sys.executable, "-m", "solprop.service.agent"], dict(os.environ) - remote = f"exec {machine.python} -m solprop.service.agent" + remote = f"exec {_shell_path(machine.python)} -m solprop.service.agent" return ssh_command(machine, remote, askpass=askpass) +def _shell_path(path: str) -> str: + """Return a path quoted whole for a POSIX shell, a leading ``~/`` still the home. + + Nothing else in it is read by the shell: no variable, ``~user`` or option. + """ + if path == "~" or path.startswith("~/"): + return '"$HOME"' + shlex.quote(path[1:]) if path != "~" else '"$HOME"' + return shlex.quote(path) + + def _drain(stream: BinaryIO, into: list[bytes]) -> None: """Read a stream to its end, keeping what it said, and close it.""" with contextlib.suppress(OSError, ValueError): @@ -457,9 +470,16 @@ def _read(self, stream: BinaryIO, said: Callable[[], str]) -> str: self._deliver(cast("dict[str, Any]", frame)) def _no_helper(self, said: str) -> str: - """Return why a session gave no hello, as the user should read it.""" - missing = ( - "No module named" in said or "not found" in said or "No such file" in said + """Return why a session gave no hello, as the user should read it. + + Only a missing solprop, or a shell's word that the machine's Python is not + there, refuses the machine for good; any other error, a network filesystem's + passing "No such file" among them, leaves the session to be tried again. + """ + last = said.splitlines()[-1].lower() if said.strip() else "" + python = self.machine.python.removeprefix("~").lower() # the shell expands ~ + missing = "No module named" in said or ( + python in last and ("not found" in last or "no such file" in last) ) if missing: reason = ( diff --git a/src/solprop/service/radial_pages.py b/src/solprop/service/radial_pages.py index aecbe03ae..7708fe10a 100644 --- a/src/solprop/service/radial_pages.py +++ b/src/solprop/service/radial_pages.py @@ -21,12 +21,19 @@ far_field, fluence_along, fluence_map, + grid_of, on_axis_power, on_axis_spectra, on_axis_spectrogram, radial_intensity, radial_spectrum, ) +from solprop.processing.fields import ( + DEFAULT_GATE_POSITIONS, + default_gate_fwhm, + real_field_oversampling, + time_axis, +) from solprop.service._payload import Payload from solprop.service.reduce import TIME_OVERSAMPLING, even_rows from solprop.service.results import _window @@ -139,21 +146,27 @@ def beam_on_axis(payload: Payload) -> dict[str, object]: path = str(payload["path"]) axis = str(payload.get("axis") or "wavelength") index = int(payload["index"]) # pyright: ignore[reportArgumentType] - gate = payload.get("gate_fwhm") + given = payload.get("gate_fwhm") with open_file(path) as output: t, power = on_axis_power(output, plane=index, oversampling=TIME_OVERSAMPLING) kept = np.asarray(output["field_planes"]) x, rows = on_axis_spectra(output, axis) # pyright: ignore[reportArgumentType] spectrum = rows[int(np.flatnonzero(kept == index)[0])] + if given is None: + # solprop's default, asked of solprop and passed on: the gate reported is + # the gate used. + grid = grid_of(output) + gate = default_gate_fwhm(time_axis(grid, real_field_oversampling(grid))) + else: + gate = float(given) # pyright: ignore[reportArgumentType] map_t, map_x, values = on_axis_spectrogram( output, axis, # pyright: ignore[reportArgumentType] plane=index, - gate_fwhm=None if gate is None else float(gate), # pyright: ignore[reportArgumentType] - positions=int(payload.get("positions") or 256), # pyright: ignore[reportArgumentType] + gate_fwhm=gate, + positions=int(payload.get("positions") or DEFAULT_GATE_POSITIONS), # pyright: ignore[reportArgumentType] ) bins, image = even_rows(map_x, values, _window(path, axis, map_x, values), _ROWS) - span = float(map_t[-1] - map_t[0]) # In arbitrary units, and a field in V/m squares beyond single precision. image = image / (float(image.max()) or 1.0) return { @@ -166,7 +179,7 @@ def beam_on_axis(payload: Payload) -> dict[str, object]: "t": map_t, "x": bins, "values": image.astype(np.float32), - "gate_fwhm": float(gate) if gate is not None else span / 20.0, # pyright: ignore[reportArgumentType] + "gate_fwhm": gate, }, } diff --git a/src/solprop/service/recipes.py b/src/solprop/service/recipes.py index 0957e6e6f..995f66739 100644 --- a/src/solprop/service/recipes.py +++ b/src/solprop/service/recipes.py @@ -4,10 +4,10 @@ """Read and trim a recipe's text, for the service and the window alike. -:func:`split`, :func:`without_table` and :func:`data_files` work on a recipe's TOML, -and :data:`BEAM_ROUTES` names the free-space routes. They import only the light parts -of :mod:`solprop.recipe` (its document and nothing that builds), so the window's process -may use them as freely as the kernel. +:func:`split`, :func:`without_table`, :func:`is_scan` and :func:`data_files` work on a +recipe's TOML, and :data:`BEAM_ROUTES` names the free-space routes. They import only +the light parts of :mod:`solprop.recipe` (its document and nothing that builds), so +the window's process may use them as freely as the kernel. """ import re @@ -16,7 +16,7 @@ from solprop.recipe.document import dump_text, parse_text -__all__ = ["BEAM_ROUTES", "data_files", "split", "without_table"] +__all__ = ["BEAM_ROUTES", "data_files", "is_scan", "split", "without_table"] BEAM_ROUTES: Final = frozenset({"radial", "free", "planar"}) """The routes of a beam in free space, whose files solprop reads by its spatial readers @@ -81,6 +81,36 @@ def without_table(text: str, table: str) -> str: return dump_text(tables) +def is_scan(text: str | None) -> bool: + r"""Return whether a recipe's text runs as a scan: it has a ``[scan]`` table. + + Parameters + ---------- + text : str or None + The recipe; ``None`` for a continued run, which is never a scan. + + Returns + ------- + bool + True for a recipe with a ``[scan]`` table; False for any other text, + including text that is not TOML. + + Examples + -------- + >>> text = '[recipe]\nformat = 1\nroute = "capillary"\n' + >>> is_scan(text), is_scan(text + '[scan]\nname = "s"\n'), is_scan(None) + (False, True, False) + """ + import tomllib # noqa: PLC0415 - only here + + if text is None: + return False + try: + return "scan" in tomllib.loads(text) + except tomllib.TOMLDecodeError: + return False + + def data_files(text: str) -> list[str]: r"""Return the data files a recipe reads, as it names them. diff --git a/src/solprop/service/record.py b/src/solprop/service/record.py index 8c603b5d2..ec9d734c0 100644 --- a/src/solprop/service/record.py +++ b/src/solprop/service/record.py @@ -12,8 +12,9 @@ :func:`watch_stop`, :func:`clear_stop`). So a run needs no connection: whoever can read its folder can follow it, whoever can write there can stop it, and its state is read from these files, never kept by a daemon. :func:`set_aside` keeps a continued run's -earlier record apart, :func:`write_json` replaces a file whole, and :func:`alive` says -whether a run's process still lives. +earlier record apart (and :func:`put_back` returns it when the continuation cannot be +launched), :func:`write_json` replaces a file whole, and :func:`alive` says whether a +run's process still lives. **The ending is recorded last**: the terminal event, then ``job.json``'s end, and only then ``status.json``, after which the run writes nothing more, so a reader acting on a @@ -41,7 +42,7 @@ if TYPE_CHECKING: # Only named here: this module stays light (no propagation imports), and the - # worker that runs the propagation makes the token. + # run's process, which runs the propagation, makes the token. from solprop.backends.session import StopToken __all__ = [ @@ -57,6 +58,7 @@ "alive", "clear_stop", "process_stamp", + "put_back", "read_events", "read_job", "read_status", @@ -157,8 +159,7 @@ class Job: run_id : str The run, its folder's name. launcher : str - ``"window"`` (a window's own worker), ``"direct"`` (a detached process) or - ``"slurm"``. + ``"direct"`` (a detached process) or ``"slurm"``. host : str The machine the run's process runs on. pid : int @@ -166,7 +167,8 @@ class Job: stamp : str or None When that process started (:func:`process_stamp`). slurm_job : str or None - Its Slurm job, when it runs in one. + The Slurm job solprop submitted it as (launcher ``"slurm"``); ``None`` for a + run started any other way, even one inside a Slurm allocation. started : float When it started, s since the epoch. ended : float or None @@ -202,7 +204,8 @@ def here(cls, run_id: str, launcher: str, threads: int | None = None) -> "Job": run_id : str The run. launcher : str - How it was started. + How it was started; ``"slurm"`` records this process's Slurm job as the + run's own. threads : int or None, optional Its thread budget. @@ -219,7 +222,7 @@ def here(cls, run_id: str, launcher: str, threads: int | None = None) -> "Job": host=socket.gethostname(), pid=os.getpid(), stamp=process_stamp(os.getpid()), - slurm_job=os.environ.get("SLURM_JOB_ID"), + slurm_job=os.environ.get("SLURM_JOB_ID") if launcher == "slurm" else None, started=time.time(), solprop=__version__, threads=threads, @@ -306,40 +309,91 @@ def stop_requested(folder: Path) -> bool: return (folder / STOP).exists() -def set_aside(folder: Path) -> None: +def _aside(count: int) -> tuple[tuple[str, str], ...]: + """Return each record file and its name when set aside as the ``count``-th part.""" + return ( + (EVENTS, f"events-{count}.bin"), + (JOB, f"job-{count}.json"), + (STATUS, f"status-{count}.json"), + ) + + +def _aside_number(folder: Path) -> int: + """Return the number :func:`set_aside` keeps a folder's record under next.""" + count = 1 + while any((folder / kept).exists() for _, kept in _aside(count)): + count += 1 + return count + + +def set_aside(folder: Path) -> int: """Keep a continued run's earlier record apart, so its new one starts empty. A window following the continued run reads its new events from the start, not the ending of the part before (``events.bin`` becomes ``events-1.bin``, then - ``events-2.bin``, ...); its summary and stop file start afresh too. A folder with - no record is left as it is. + ``events-2.bin``, ...), and the earlier part's ``job.json`` and ``status.json`` + go beside them (``job-1.json``, ``status-1.json``, ...), so its process is never + taken for the new part's and its summary starts afresh; the stop file is + removed. A folder with no record is left as it is. Parameters ---------- folder : pathlib.Path The run's folder. + Returns + ------- + int + The number the record is kept under, as :func:`put_back` takes it. + Examples -------- >>> import tempfile >>> folder = Path(tempfile.mkdtemp()) >>> _ = (folder / EVENTS).write_bytes(b"") + >>> _ = (folder / JOB).write_text("{}", encoding="utf-8") >>> set_aside(folder) + 1 >>> sorted(path.name for path in folder.iterdir()) - ['events-1.bin'] + ['events-1.bin', 'job-1.json'] """ - events = folder / EVENTS - if events.exists(): - count = 1 - while (folder / f"events-{count}.bin").exists(): - count += 1 - events.replace(folder / f"events-{count}.bin") - (folder / STATUS).unlink(missing_ok=True) + count = _aside_number(folder) + for name, kept in _aside(count): + if (folder / name).exists(): + (folder / name).replace(folder / kept) clear_stop(folder) + return count + + +def put_back(folder: Path, count: int) -> None: + """Return a record :func:`set_aside` kept apart to its place, as before. + + For a continuation that could not be launched: the folder then reads as the + earlier part left it, its ending included. + + Parameters + ---------- + folder : pathlib.Path + The run's folder. + count : int + The number the record was kept under. + + Examples + -------- + >>> import tempfile + >>> folder = Path(tempfile.mkdtemp()) + >>> _ = (folder / EVENTS).write_bytes(b"") + >>> put_back(folder, set_aside(folder)) + >>> sorted(path.name for path in folder.iterdir()) + ['events.bin'] + """ + for name, kept in _aside(count): + if (folder / kept).exists(): + (folder / kept).replace(folder / name) def clear_stop(folder: Path) -> None: - """Remove a run's stop file, as a run does when it starts or continues. + """Remove a run's stop file, as a launcher does before a run starts. Parameters ---------- @@ -498,6 +552,8 @@ def __init__( self._status: dict[str, Any] = {"run_id": run_id, "updated": time.time()} self._written = -float("inf") self._stream = (folder / EVENTS).open("ab") + self._length = self._stream.tell() # appending starts at the end + self._intact = True self._thread = threading.Thread( target=self._write, name="solprop-record", daemon=True ) @@ -577,11 +633,34 @@ def _write(self) -> None: def _append(self, event: Event) -> bool: """Append one event to ``events.bin``; return whether it was written.""" + if not self._intact: + return False try: - self._stream.write(encode(_value(event))) + frame = encode(_value(event)) + self._stream.write(frame) self._stream.flush() - except OSError, ServiceError: - # A full disk or an unwritable value costs the record, not the run. + except ServiceError: + return False # an unwritable value costs that event, not the run + except OSError: + # A full disk costs the event, not the run. Part of the frame may have + # been written, and a reader would take the frames after it for its rest. + self._intact = self._cut_back() + return False + self._length += len(frame) + return True + + def _cut_back(self) -> bool: + """Cut ``events.bin`` back to its whole frames and reopen it; return success. + + Closing drops what the failed write left buffered; a record that cannot be cut + back keeps no more events, so none follows a part of a frame. + """ + with contextlib.suppress(OSError): + self._stream.close() + try: + os.truncate(self.folder / EVENTS, self._length) + self._stream = (self.folder / EVENTS).open("ab") + except OSError: return False return True diff --git a/src/solprop/service/results.py b/src/solprop/service/results.py index b4a7c0bac..549293337 100644 --- a/src/solprop/service/results.py +++ b/src/solprop/service/results.py @@ -27,6 +27,7 @@ from matplotlib.figure import Figure from solprop import capabilities, plotting +from solprop.constants import C from solprop.driver import Simulation from solprop.exceptions import OutputError, SolpropError from solprop.grid import FreeGrid, LineGrid, RadialGrid @@ -38,13 +39,16 @@ get_phase, get_power, get_spectral_density, + grid_of, node_fluence, physical_energy, transverse_units, ) from solprop.processing.fields import ( DEFAULT_GATE_POSITIONS, + default_gate_fwhm, get_spectrogram, + real_field_oversampling, time_axis, ) from solprop.processing.scans import ScanOutput @@ -62,9 +66,6 @@ __all__ = ["RESULTS_HANDLERS", "band_of", "spatial_plane"] -C = 299_792_458.0 - - def _modes(payload: Payload) -> ModeSelection: """Return the mode selection a payload asks for. @@ -557,28 +558,35 @@ def spectrogram(payload: Payload) -> dict[str, object]: modes = _modes(payload) mode = 0 if modes == "sum" else modes time_range = band_of({"bandpass": payload.get("time_range")}) - gate = payload.get("gate_fwhm") + given = payload.get("gate_fwhm") with open_file(path) as handler: + if given is None: + # solprop's default, asked of solprop and passed on: the gate reported is + # the gate used. + grid = grid_of(handler) + times = time_axis(grid, real_field_oversampling(grid)) + gate = default_gate_fwhm(times, time_range) + else: + gate = float(given) # pyright: ignore[reportArgumentType] t, x, values = get_spectrogram( handler, axis, # pyright: ignore[reportArgumentType] plane=int(payload["index"]), # pyright: ignore[reportArgumentType] modes=mode, time_range=time_range, - gate_fwhm=None if gate is None else float(gate), # pyright: ignore[reportArgumentType] + gate_fwhm=gate, positions=int(payload.get("positions") or DEFAULT_GATE_POSITIONS), # pyright: ignore[reportArgumentType] bandpass=band_of(payload), ) window = _window(path, axis, x, values) rows, image = even_rows(x, values, window, SPECTROGRAM_ROWS) - span = float(t[-1] - t[0]) if time_range is None else abs(np.ptp(time_range)) return { "t": t, "x": rows, "values": image.astype(np.float32), "axis": axis, "mode": int(mode), # pyright: ignore[reportArgumentType] - "gate_fwhm": float(gate) if gate is not None else span / 20.0, # pyright: ignore[reportArgumentType] + "gate_fwhm": gate, } @@ -638,26 +646,34 @@ def figure(payload: Payload) -> list[str] | list[dict[str, object]]: """ import io # noqa: PLC0415 - only here + import matplotlib.pyplot as plt # noqa: PLC0415 - loaded by solprop.plotting + target = Path(str(payload["file"])) with open_file(str(payload["path"])) as handler: drawn = _drawn(handler, payload) written: list[str] = [] given: list[dict[str, object]] = [] - for number, one in enumerate(drawn, start=1): - path = ( - target - if len(drawn) == 1 - else target.with_name(f"{target.stem}-{number}{target.suffix}") - ) - if payload.get("bytes"): - buffer = io.BytesIO() - kind = path.suffix.lstrip(".").lower() or "png" - one.savefig(buffer, dpi=200, format=kind) - data = np.frombuffer(buffer.getvalue(), dtype=np.uint8) - given.append({"name": path.name, "data": data}) - else: - one.savefig(path, dpi=200) - written.append(str(path)) + try: + for number, one in enumerate(drawn, start=1): + path = ( + target + if len(drawn) == 1 + else target.with_name(f"{target.stem}-{number}{target.suffix}") + ) + if payload.get("bytes"): + buffer = io.BytesIO() + kind = path.suffix.lstrip(".").lower() or "png" + one.savefig(buffer, dpi=200, format=kind) + data = np.frombuffer(buffer.getvalue(), dtype=np.uint8) + given.append({"name": path.name, "data": data}) + else: + one.savefig(path, dpi=200) + written.append(str(path)) + finally: + # The plots draw through pyplot, which keeps every figure until it is + # closed: in the long-lived kernel each export would stay for the session. + for one in drawn: + plt.close(one) return given if payload.get("bytes") else written diff --git a/src/solprop/service/run.py b/src/solprop/service/run.py index 437ad0d17..194cecce0 100644 --- a/src/solprop/service/run.py +++ b/src/solprop/service/run.py @@ -12,9 +12,9 @@ turns a scan's progress into events and :class:`EventHandler` forwards log records. The run's stop file sets its stop token (:class:`solprop.backends.session.StopToken`). -Whether a run *stopped* comes from the worker's own flag and the run's clean return, -never from solprop's outcome, which records a stop as a failure. This module imports -solprop and runs only in a worker process. +Whether a run *stopped* comes from its own stop flag and its clean return, never from +solprop's outcome, which records a stop as a failure. This module imports solprop and +runs only in a run's process. """ import logging @@ -37,11 +37,14 @@ from solprop.recipe import Recipe, resume_file from solprop.service.beam import beam_reading, profile_row from solprop.service.messages import Event +from solprop.service.recipes import is_scan from solprop.service.record import ( + EVENTS, + JOB, EventLog, Job, - clear_stop, set_aside, + stop_requested, watch_stop, ) from solprop.service.reduce import ( @@ -300,7 +303,7 @@ def point_finished(self, index: int, status: str, wall: float) -> None: ) def scan_finished(self) -> None: - """Do nothing: the scan's terminal event is the worker's.""" + """Do nothing: the scan's terminal event is the run's own (:func:`execute`).""" class EventHandler(logging.Handler): @@ -448,11 +451,17 @@ def execute(spec: RunSpec) -> None: """Run, or continue, one run, recording its events until its terminal one. The run appends its events to its record and obeys its stop file - (:mod:`solprop.service.record`). A signal that ends the run (``SIGTERM``, as Slurm + (:mod:`solprop.service.record`); one already there when it starts, a Stop pressed + while it waited in a queue or started, ends it as stopped before anything is + built. A signal that ends the run (``SIGTERM``, as Slurm sends at a time limit or ``scancel``, and as Kill sends) leaves the file resumable, so it ends the run as stopped. A run tied to a window (``spec.owner``) stops, in the same way as Stop, when that window's process has gone. + However it ends, its terminal event names its results file (``path``: a scan's, + with ``scan`` true, for a recipe with a ``[scan]`` table) and gives ``output``, + that file where it exists and ``None`` where the run wrote none. + Parameters ---------- spec : solprop.service.worker.RunSpec @@ -460,12 +469,23 @@ def execute(spec: RunSpec) -> None: """ folder = Path(spec.folder) folder.mkdir(parents=True, exist_ok=True) - output = folder / OUTPUT + # Every ending of a scan names the scan's file and says it was a scan, however it + # comes: a window decides what to open from it. + scanning = spec.resume is None and is_scan(spec.recipe) + output = folder / (SCAN_OUTPUT if scanning else OUTPUT) + ending: dict[str, object] = {"path": str(output)} + if scanning: + ending["scan"] = True stop = StopToken() done = threading.Event() - if spec.resume is not None: - set_aside(folder) # as the launcher did, for a run continued by hand - clear_stop(folder) + if spec.resume is not None and any( + (folder / name).exists() for name in (EVENTS, JOB) + ): + # Continued by hand: the earlier part's record is still in place. A launcher + # sets it aside before the job exists, so that a stop file found here is a + # Stop pressed while the run waited, and is obeyed below. + set_aside(folder) + stopped_early = stop_requested(folder) owner = None if spec.owner is None else (int(spec.owner[0]), spec.owner[1]) watch_stop(folder, stop, done, owner=owner) record = EventLog( @@ -477,20 +497,28 @@ def execute(spec: RunSpec) -> None: detach = _attach_log(folder, spec.run_id, record.put) kind = "failed" - data: dict[str, object] = {"path": str(output)} + data: dict[str, object] = dict(ending) try: - kind, data = _march(spec, folder, record.put, observer, stop) + if stopped_early: + # Nothing built and nothing written: a continued run's file is as it was. + kind = "stopped" + data = {**ending, "message": "stopped before it started"} + else: + kind, data = _march(spec, folder, record.put, observer, stop) except RunTerminated as error: # solprop wrote the state a resume needs before raising. - kind, data = "stopped", {"path": str(output), "terminated": True} + kind, data = "stopped", {**ending, "terminated": True} data["message"] = str(error) or "ended by a signal" except BaseException as error: data = { - "path": str(output), + **ending, "message": str(error) or type(error).__name__, "detail": traceback.format_exc(), } finally: + # The results file, where there is one to open: a run can end before it + # writes any. + data["output"] = str(output) if output.exists() else None record.put(Event(spec.run_id, kind, data)) done.set() record.close() # records the job's end too diff --git a/src/solprop/service/runs.py b/src/solprop/service/runs.py index a20ed04e9..89d7d311c 100644 --- a/src/solprop/service/runs.py +++ b/src/solprop/service/runs.py @@ -79,6 +79,19 @@ def _title(folder: Path) -> str: return folder.name +def _own_slurm_job(submitted: Mapping[str, Any]) -> str | None: + """Return the Slurm job solprop submitted a run as, or ``None`` for any other run. + + - ``submitted``: its ``submitted.json``. + + Only the job ``sbatch`` named for the run is its own: a run started directly + inside a Slurm allocation sits in a job that is not the run's to follow or cancel, + whatever its ``job.json`` says. + """ + job = submitted.get("slurm_job") if submitted.get("launcher") == "slurm" else None + return str(job) if job else None + + def slurm_jobs(folders: Sequence[Path]) -> list[str]: """Return the Slurm jobs of the runs that have not recorded an ending. @@ -97,9 +110,9 @@ def slurm_jobs(folders: Sequence[Path]) -> list[str]: status = read_status(folder) if status is not None and "ending" in status: continue - submitted = _read(folder / SUBMITTED) - if submitted is not None and submitted.get("slurm_job"): - jobs.append(str(submitted["slurm_job"])) + job = _own_slurm_job(_read(folder / SUBMITTED) or {}) + if job is not None: + jobs.append(job) return jobs @@ -125,9 +138,10 @@ def summarise( ------- dict ``run_id``, ``folder``, ``title``, ``state`` (as the module lists them), - ``detail`` (a reason or a message), ``launcher``, ``slurm_job``, - ``submitted``, ``started`` and ``ended`` (s since the epoch, or ``None``), - ``progress`` (the last, or ``None``), ``points`` and ``done`` for a scan, + ``detail`` (a reason or a message), ``launcher``, ``slurm_job`` (the job + solprop submitted it as, or ``None``), ``submitted``, ``started`` and + ``ended`` (s since the epoch, or ``None``), ``progress`` (the last, or + ``None``), ``points`` and ``done`` for a scan, ``scan``, ``output`` (its results file, or ``None`` before one exists), ``record`` (whether it keeps one) and ``stopping`` (asked to stop and not yet ended). @@ -135,16 +149,19 @@ def summarise( status = read_status(folder) or {} job = read_job(folder) submitted = _read(folder / SUBMITTED) or {} - scan = (folder / SCAN_OUTPUT).exists() or "points" in status - output = folder / (SCAN_OUTPUT if scan else OUTPUT) ending = status.get("ending") - slurm_job = submitted.get("slurm_job") or (job.slurm_job if job else None) + scan = ( + (folder / SCAN_OUTPUT).exists() + or "points" in status + or (isinstance(ending, Mapping) and bool(ending.get("data", {}).get("scan"))) # pyright: ignore[reportUnknownMemberType] + ) + output = folder / (SCAN_OUTPUT if scan else OUTPUT) summary: dict[str, Any] = { "run_id": folder.name, "folder": str(folder), "title": _title(folder), "launcher": submitted.get("launcher") or (job.launcher if job else None), - "slurm_job": slurm_job, + "slurm_job": _own_slurm_job(submitted), "submitted": submitted.get("submitted"), "started": job.started if job else None, "ended": job.ended if job else None, @@ -188,9 +205,9 @@ def _living_state( # noqa: PLR0917 - called positionally - Returns: the state and its detail. """ del folder - slurm_job = submitted.get("slurm_job") or (job.slurm_job if job else None) + slurm_job = _own_slurm_job(submitted) if slurm_job is not None: - known = slurm.get(str(slurm_job)) + known = slurm.get(slurm_job) if known is None and job is None: # Not listed, and not started: just submitted (the scheduler lists a job # a moment later), or asked about without the scheduler. diff --git a/src/solprop/service/states.py b/src/solprop/service/states.py index 6c2a69578..91bdc02eb 100644 --- a/src/solprop/service/states.py +++ b/src/solprop/service/states.py @@ -4,9 +4,9 @@ """A run's execution state, the window's own (design 4 and 10.2). -The execution state says what the window and the worker are doing; solprop's outcome -says what the run achieved, and whether a file can be continued is always asked of -solprop (``resumability``), never read from either. +The execution state says what the window and the run's process are doing; solprop's +outcome says what the run achieved, and whether a file can be continued is always asked +of solprop (``resumability``), never read from either. :: @@ -14,7 +14,7 @@ │ │ └──▶ failed │ └─▶ stopping ─▶ stopped └─▶ failed └──▶ (complete, failed: the run ended first) - any active state ─▶ worker lost + any active state ─▶ lost """ from enum import StrEnum @@ -33,7 +33,7 @@ class ExecutionState(StrEnum): STOPPED = "stopped" COMPLETE = "complete" FAILED = "failed" - LOST = "worker lost" + LOST = "lost" ACTIVE: Final = frozenset( @@ -80,7 +80,7 @@ def advance(state: ExecutionState, event: str) -> ExecutionState: state : ExecutionState The run's state. event : str - A worker event's kind (``"started"``, ``"stopped"``, ``"finished"``, + A run's event kind (``"started"``, ``"stopped"``, ``"finished"``, ``"failed"``, ``"lost"``) or a window action (``"launch"``, ``"stop"``). Any other event (progress, rows, logs) leaves the state as it is. @@ -106,20 +106,20 @@ def advance(state: ExecutionState, event: str) -> ExecutionState: ) -def failure_advice(kind: str, message: str, exitcode: object = None) -> str: +def failure_advice(kind: str, message: str) -> str: """Say why a run stopped short, and what to try. solprop admits every run and a run that does not fit fails where it fails: with a - ``MemoryError``, or with its worker killed and no Python error (ADR-065). + ``MemoryError``, or with its process killed and no Python error (ADR-065). Parameters ---------- kind : {'failed', 'lost'} How it ended. message : str - The message solprop gave, if any. - exitcode : object, optional - The worker's exit status, for one that was lost. + The message solprop gave a failed run, or the reason a lost run went, as its + state says it (Slurm's ``out of memory`` or ``timeout``, say); empty when there + is none. Returns ------- @@ -132,15 +132,14 @@ def failure_advice(kind: str, message: str, exitcode: object = None) -> str: 'The grid is too small.' >>> failure_advice("failed", "MemoryError").endswith("help too.") True - >>> failure_advice("lost", "", -9).startswith("The run's worker was killed") + >>> failure_advice("lost", "timeout") + "The run's process ended without recording how (timeout)." + >>> failure_advice("lost", "out of memory").endswith("help too.") True - >>> failure_advice("lost", "", 1) - "The run's worker ended without saying why (exit status 1)." """ + memory = "MemoryError" in message or "out of memory" in message.lower() if kind == "failed": - if "MemoryError" in message or "out of memory" in message.lower(): - return f"{message} {_MEMORY_HINT}" - return message - if exitcode in (-9, 137): - return f"The run's worker was killed, with no error from Python. {_MEMORY_HINT}" - return f"The run's worker ended without saying why (exit status {exitcode})." + return f"{message} {_MEMORY_HINT}" if memory else message + reason = f" ({message})" if message else "" + said = f"The run's process ended without recording how{reason}." + return f"{said} {_MEMORY_HINT}" if memory else said diff --git a/src/solprop/spatial.py b/src/solprop/spatial.py index fd40a6abe..c6abb4bef 100644 --- a/src/solprop/spatial.py +++ b/src/solprop/spatial.py @@ -134,9 +134,11 @@ class SpatialMedium: Gas name, existing glass model, or constant index. Default 1 is vacuum. Positive imaginary index is loss; negative imaginary index is gain. A mixture supplies its own density paths, temperature and optical models. - pressure : float or solprop.profiles.ZProfile - Absolute gas pressure in bar, nonnegative, optionally varying along z. - Only gas media use pressure; other materials require the default 1. + pressure : float or solprop.profiles.ZProfile or None + Absolute gas pressure in bar, nonnegative, optionally varying along z. A gas + needs it: ``None`` (the default) beside a gas is refused. A glass, a constant + index or a mixture takes none; the attribute then holds 1, which nothing + reads, and an explicit 1 is accepted so that a recorded medium rebuilds. temperature : float or None Gas temperature in K, finite and positive; ``None`` (the default) is room temperature for a gas and the mixture's own beside a mixture, which is what @@ -160,7 +162,7 @@ class SpatialMedium: """ material: Gas | str | GlassIndex | complex | Mixture = 1.0 - pressure: float | ZProfile = 1.0 + pressure: float | ZProfile | None = None temperature: float | None = None susceptibility: GasSusceptibility | None = None density: ZProfile = field(init=False, repr=False) @@ -168,8 +170,13 @@ class SpatialMedium: def __post_init__(self) -> None: """Resolve the material and its scalar density path.""" self._resolve_temperature() + given = self.pressure is not None and self.pressure != 1.0 + if not isinstance(self.material, str | Gas): + # No gas, so no pressure applies; the field holds a placeholder 1, which + # keeps the records of such media as they were. + object.__setattr__(self, "pressure", 1.0) if isinstance(self.material, Mixture): - if self.pressure != 1.0 or self.susceptibility is not None: + if given or self.susceptibility is not None: raise MaterialError("mixture carries its pressure and susceptibility") paths = tuple(c.density for c in self.material.components) object.__setattr__( @@ -178,7 +185,7 @@ def __post_init__(self) -> None: elif isinstance(self.material, str | Gas): self._resolve_gas() else: - if self.pressure != 1.0 or self.susceptibility is not None: + if given or self.susceptibility is not None: msg = "pressure and susceptibility apply only to gas media" raise MaterialError(msg) if not isinstance(self.material, GlassIndex): @@ -233,6 +240,12 @@ def _resolve_gas(self) -> None: The built-in gas is optmat's: its law and its equation of state. """ gas = as_gas(cast("str | Gas", self.material)) + if self.pressure is None: + msg = ( + f"a gas fill needs its pressure: pass pressure= in bar beside " + f"material={self.material!r}" + ) + raise MaterialError(msg, parameter="pressure") pressure = as_profile(self.pressure) if float(pressure(np.array([0.0]))[0]) < 0: msg = "spatial medium pressure must be nonnegative" @@ -1709,8 +1722,11 @@ def on_axis_spectrum( ------- numpy.ndarray Real spectral fluence in J s/m^2 per angular frequency bin, shape - ``(n_omega,)``. Its sum times ``grid.d_omega`` is the on-axis fluence. - It is a density, so changing Fourier convention leaves it unchanged. + ``(n_omega,)``. Each bin carries its weight in + :func:`solprop.fourier.energy_weights` per ``grid.d_omega``, so a field grid's + end bins count a quarter of an interior bin, as in the analytic signal, and the + sum times ``grid.d_omega`` is exactly the on-axis fluence. It is a density, so + changing Fourier convention leaves it unchanged. Raises ------ @@ -1719,8 +1735,10 @@ def on_axis_spectrum( """ field, closure = _on_axis_pair(spectrum, flux) grid = flux.grid - factor = fourier.spectral_density( - np.ones(grid.n_omega, complex), grid.dt, kind=grid.kind + # The energy weight of each bin per unit frequency: on a field grid the end bins + # take the analytic signal's weight, a quarter of an interior bin's. + factor = ( + fourier.energy_weights(grid.n_omega, grid.dt, kind=grid.kind) / grid.d_omega ) return 0.5 * EPS0 * C * factor * np.sum(np.real(field * np.conj(closure)), axis=0) @@ -1746,8 +1764,9 @@ def node_spectrum( ------- numpy.ndarray Real spectral fluence in J s/m^2 per angular frequency bin, shape - ``(n_nodes, n_omega)``. Its sum over frequency times ``grid.d_omega`` is the - node's :func:`spatial_fluence`. + ``(n_nodes, n_omega)``, weighted per bin as :func:`on_axis_spectrum` is. Its + sum over frequency times ``grid.d_omega`` is the node's + :func:`spatial_fluence`. Raises ------ @@ -1757,8 +1776,10 @@ def node_spectrum( _check_flux(spectrum, flux, planar=False) field, closure = _local_pair(spectrum, flux) grid = flux.grid - factor = fourier.spectral_density( - np.ones(grid.n_omega, complex), grid.dt, kind=grid.kind + # The energy weight of each bin per unit frequency: on a field grid the end bins + # take the analytic signal's weight, a quarter of an interior bin's. + factor = ( + fourier.energy_weights(grid.n_omega, grid.dt, kind=grid.kind) / grid.d_omega ) return 0.5 * EPS0 * C * factor * np.sum(np.real(field * np.conj(closure)), axis=1) @@ -2984,8 +3005,9 @@ def values(self) -> dict[str, np.ndarray]: """Return the requested statistics from the accumulated partials.""" conversion = 0.5 * EPS0 * C grid = self._grid - factor = fourier.spectral_density( - np.ones(grid.n_omega, complex), grid.dt, kind=grid.kind + # Per unit frequency, with the analytic signal's end-bin weights. + factor = ( + fourier.energy_weights(grid.n_omega, grid.dt, kind=grid.kind) / grid.d_omega ) on_axis = factor * np.sum( np.real(self._amplitude * np.conj(self._closure)), axis=1 diff --git a/src/solprop/stats/__init__.py b/src/solprop/stats/__init__.py index 07fbff78c..853179893 100644 --- a/src/solprop/stats/__init__.py +++ b/src/solprop/stats/__init__.py @@ -76,11 +76,9 @@ # Not part of the surface, and read from here by the backends: the reference backend's # statistics (the Poynting-weighted set and its evaluator), solprop-native (the # far-field names, defined in solprop.spatial) and processing.time (the half-maximum -# crossings). solprop-native also names the whitening and the crossings here as the -# definitions it mirrors. +# crossings). from solprop.spatial import FAR_FIELD_STATISTICS as FAR_FIELD_STATISTICS from solprop.stats.definitions import _half_max_range as _half_max_range -from solprop.stats.definitions import _whitened as _whitened from solprop.stats.evaluation import _POYNTING_STATISTICS as _POYNTING_STATISTICS from solprop.stats.evaluation import _poynting_statistics as _poynting_statistics diff --git a/src/solprop/stats/catalogue.py b/src/solprop/stats/catalogue.py index 2229786e4..fed491ca3 100644 --- a/src/solprop/stats/catalogue.py +++ b/src/solprop/stats/catalogue.py @@ -512,7 +512,7 @@ def _catalogue() -> dict[str, StatDefinition]: ), StatDefinition( name="absorbed_power", - summary="Power each absorbing channel of the linear operator removes.", + summary="Energy per metre each absorbing channel of the operator removes.", shape="(5,)", units="J/m", requires=("spatial_geometry", "separable_operator"), @@ -524,7 +524,7 @@ def _catalogue() -> dict[str, StatDefinition]: name="quadrature_error", summary="Relative error of the transverse quadrature on the polarisation.", shape="()", - units="dimensionless", + units="1", backend=True, between_planes=True, general="diagnostic", @@ -572,7 +572,7 @@ def _catalogue() -> dict[str, StatDefinition]: ``spectral_flux`` is the one array of the family -- the same flux as a density in frequency rather than integrated. It is **admitted but not a default** of the route: it is ``n_omega`` wide per plane where -the other five are scalars, so a run asks for it by name. +the other five are scalars (``omega0`` one per channel), so a run asks for it by name. Two names of :mod:`solprop.processing.modal` are deliberately absent. ``quadrature_error`` is refused separately, by the driver, because what disqualifies diff --git a/src/solprop/stats/definitions.py b/src/solprop/stats/definitions.py index 6ebd1fe0c..f60de08be 100644 --- a/src/solprop/stats/definitions.py +++ b/src/solprop/stats/definitions.py @@ -140,8 +140,9 @@ def species_statistics( } -DEFAULT_ZDW_RANGE = (100e-9, 3e-6) -"""Search window of :func:`zdw` when no narrower one is given, m.""" +DEFAULT_ZDW_RANGE = (150e-9, 3e-6) +"""Search window of :func:`zdw` when no narrower one is given, m: the default of +:func:`solprop.modes.base.zdw`.""" def analytic_field( @@ -1041,6 +1042,7 @@ def zdw( z: float, *, wavelength_limits: tuple[float, float] = DEFAULT_ZDW_RANGE, + near: float | None = None, ) -> Float[np.ndarray, " n_modes"]: """Return the zero-dispersion wavelength of each mode at one position. @@ -1056,10 +1058,16 @@ def zdw( z : float Position along the waveguide, m. wavelength_limits : tuple of float, optional - Shortest and longest wavelength in m to bracket the root in. Defaults to a 100 - nm to 3 um window; :func:`~solprop.stats.collect` narrows it to the grid's own + Shortest and longest wavelength in m to search. Defaults to + ``DEFAULT_ZDW_RANGE``, 150 nm to 3 um; :func:`~solprop.stats.collect` + narrows it to the grid's own band with :func:`inband_wavelengths`, which is where the answer means anything and where the material models are not extrapolating. + near : float, optional + Reference wavelength in m: of several zeros, return the one nearest it that + no resonance separates from it (:func:`solprop.modes.base.zdw`). + :func:`~solprop.stats.collect` passes the grid's reference wavelength. + ``None`` refuses several zeros. Returns ------- @@ -1069,10 +1077,12 @@ def zdw( Raises ------ solprop.exceptions.NoZeroDispersionError - If a mode has no zero-dispersion point in the search window, rather than a - missing value that would propagate silently. :func:`~solprop.stats.collect` - records ``nan`` with a warning instead, so that a run is not stopped by its - band. + If the search finds no zero-dispersion point of a mode in the window, rather + than a missing value that would propagate silently. + :func:`~solprop.stats.collect` records ``nan`` with a warning instead, so that + a run is not stopped by its band. + solprop.exceptions.ModeError + If a mode has several zeros in the window and `near` is ``None``. Examples -------- @@ -1083,5 +1093,8 @@ def zdw( '376.7' """ return np.asarray( - [modes_base.zdw(mode, z, wavelength_limits=wavelength_limits) for mode in modes] + [ + modes_base.zdw(mode, z, wavelength_limits=wavelength_limits, near=near) + for mode in modes + ] ) diff --git a/src/solprop/stats/evaluation.py b/src/solprop/stats/evaluation.py index da67497e5..bac99c237 100644 --- a/src/solprop/stats/evaluation.py +++ b/src/solprop/stats/evaluation.py @@ -80,9 +80,10 @@ def _zdw_or_nan( ) -> Float[np.ndarray, " n_modes"]: """Return each mode's zero-dispersion wavelength in a grid's band, or ``nan``. - A run asked for this statistic is not stopped because its band holds no zero: the - plane records ``nan`` with a warning, as :func:`fwhm_t` does for a missing crossing. - A direct call to :func:`zdw` still raises. + Of several zeros in the band, the one nearest the grid's reference wavelength. A + run asked for this statistic is not stopped because its band holds no zero: the + plane records ``nan`` with a warning, as :func:`fwhm_t` records ``nan`` for a + missing crossing (logged at debug level). A direct call to :func:`zdw` still raises. - ``z``: position along the waveguide, m. - Returns: Zero-dispersion wavelength or ``nan``, shape ``(n_modes,)``, m. @@ -91,15 +92,18 @@ def _zdw_or_nan( values = np.full(len(modes), np.nan) for index, mode in enumerate(modes): try: - values[index] = zdw([mode], z, wavelength_limits=window)[0] + values[index] = zdw( + [mode], z, wavelength_limits=window, near=grid.reference_wavelength + )[0] except NoZeroDispersionError: continue missing = np.flatnonzero(np.isnan(values)) if missing.size: warnings.warn( - f"the 'zdw' statistic records nan for modes {missing.tolist()}: beta_2 has " - f"one sign at both ends of the grid's {window[0] * 1e9:.4g}-" - f"{window[1] * 1e9:.4g} nm band", + f"the 'zdw' statistic records nan for modes {missing.tolist()}: the " + "search found no zero of beta_2 in the grid's " + f"{window[0] * 1e9:.4g}-{window[1] * 1e9:.4g} nm band that no resonance " + "separates from its reference wavelength", SolpropWarning, stacklevel=3, ) diff --git a/src/solprop/stats/spec.py b/src/solprop/stats/spec.py index 1d74667b2..3b8041206 100644 --- a/src/solprop/stats/spec.py +++ b/src/solprop/stats/spec.py @@ -14,7 +14,7 @@ import math import warnings -from collections.abc import Sequence +from collections.abc import Callable, Sequence from dataclasses import dataclass, field from typing import Literal @@ -68,15 +68,28 @@ def _aperture_array( array = np.array(values, dtype=np.float64, order="C", copy=True) except (TypeError, ValueError) as error: msg = f"ApertureSet.{name} must be numeric, {stated}" - raise OutputError(msg) from error + raise ProcessingError(msg) from error fits = array.ndim == 1 if shape is None else array.shape == shape if not fits or not np.all(np.isfinite(array)): msg = f"ApertureSet.{name} must be finite, {stated}, got {array.shape}" - raise OutputError(msg) + raise ProcessingError(msg) array.setflags(write=False) return array +def _known(check: Callable[[object], None], value: object) -> None: + """Refuse an unknown aperture profile or shape as a malformed request. + + - ``check``: :func:`~solprop.spatial.check_aperture_profile` or + :func:`~solprop.spatial.check_aperture_shape`, whose refusal is the spatial + tables' :class:`~solprop.exceptions.OutputError`. + """ + try: + check(value) + except OutputError as error: + raise ProcessingError(str(error)) from error + + def check_aperture_choices(profile: object, weighting: object) -> None: """Refuse, by name, an aperture profile or weighting that does not exist. @@ -93,7 +106,7 @@ def check_aperture_choices(profile: object, weighting: object) -> None: Raises ------ - OutputError + ProcessingError If either is not one of its choices. Examples @@ -102,13 +115,13 @@ def check_aperture_choices(profile: object, weighting: object) -> None: >>> check_aperture_choices("tanh", "quadrature") is None True """ - check_aperture_profile(profile) + _known(check_aperture_profile, profile) if weighting not in ("amplitude", "quadrature"): msg = ( f"unknown aperture weighting {weighting!r}; choose 'amplitude' or " "'quadrature'" ) - raise OutputError(msg) + raise ProcessingError(msg) def _off_axis(shape: str) -> int: @@ -174,7 +187,7 @@ class ApertureSet: Raises ------ - OutputError + ProcessingError If there are no apertures or more than :data:`~solprop.stats.spec.MAX_APERTURES`; an array is not finite or not of its stated shape; a diameter, an extent or a distance @@ -243,14 +256,14 @@ def __post_init__(self) -> None: Raises ------ - OutputError + ProcessingError Naming the field and the rule it breaks. """ diameters = _aperture_array(self.diameters, None, "diameters") count = diameters.size if not 1 <= count <= MAX_APERTURES: msg = f"an ApertureSet holds 1 to {MAX_APERTURES} apertures, got {count}" - raise OutputError(msg) + raise ProcessingError(msg) object.__setattr__(self, "diameters", diameters) object.__setattr__( self, "centres", _aperture_array(self.centres, (count, 2), "centres") @@ -263,7 +276,7 @@ def __post_init__(self) -> None: self._check_outlines(count) if np.any(np.asarray(self.distances) <= 0): msg = "every aperture diameter and distance must be positive" - raise OutputError(msg) + raise ProcessingError(msg) self._check_edges(count) self._check_paraxial() labels = ( @@ -277,7 +290,7 @@ def __post_init__(self) -> None: or len(set(labels)) != count ): msg = f"ApertureSet.labels must be {count} unique non-empty strings" - raise OutputError(msg) + raise ProcessingError(msg) object.__setattr__(self, "labels", labels) def _adopt_rows(self, count: int) -> None: @@ -290,9 +303,9 @@ def _adopt_rows(self, count: int) -> None: shapes = tuple(self.shapes) if len(shapes) != count: msg = f"ApertureSet.shapes must hold {count}, got {len(shapes)}" - raise OutputError(msg) + raise ProcessingError(msg) for shape in shapes: - check_aperture_shape(shape) + _known(check_aperture_shape, shape) object.__setattr__( self, "shapes", None if set(shapes) == {"circle"} else shapes ) @@ -303,15 +316,15 @@ def _adopt_rows(self, count: int) -> None: msg = ( f"ApertureSet.profiles must hold {count} profiles, got {len(profiles)}" ) - raise OutputError(msg) + raise ProcessingError(msg) for profile in profiles: - check_aperture_profile(profile) + _known(check_aperture_profile, profile) if self.profile != "hard": msg = ( "give the set's edge profile or a profile per row, not both; pass " "profile or profiles" ) - raise OutputError(msg) + raise ProcessingError(msg) one = set(profiles) object.__setattr__(self, "profile", profiles[0] if len(one) == 1 else "hard") object.__setattr__(self, "profiles", None if len(one) == 1 else profiles) @@ -324,14 +337,14 @@ def _check_outlines(self, count: int) -> None: diameters = np.asarray(self.diameters) if np.any(diameters[circle] <= 0): msg = "every aperture diameter and distance must be positive" - raise OutputError(msg) + raise ProcessingError(msg) if np.any(diameters[~circle] != 0): msg = "a diameter is a circle's; give zero on every row of another shape" - raise OutputError(msg) + raise ProcessingError(msg) if self.extents is None: if np.any(sized): msg = "an ellipse or a rectangle needs extents, (D_x, D_y) per aperture" - raise OutputError(msg) + raise ProcessingError(msg) else: extents = _aperture_array(self.extents, (count, 2), "extents") object.__setattr__(self, "extents", extents) @@ -340,13 +353,13 @@ def _check_outlines(self, count: int) -> None: "extents are an ellipse's or a rectangle's, and would be silently " "unused here; pass extents=None" ) - raise OutputError(msg) + raise ProcessingError(msg) if np.any(extents[sized] <= 0) or np.any(extents[~sized] != 0): msg = ( "ApertureSet.extents must be positive on the row of an ellipse or " "a rectangle and zero on any other" ) - raise OutputError(msg) + raise ProcessingError(msg) centres = np.asarray(self.centres) for row, shape in enumerate(shapes): if shape.startswith("half_plane") and centres[row, _off_axis(shape)] != 0: @@ -354,7 +367,7 @@ def _check_outlines(self, count: int) -> None: f"aperture {row}, a half-plane, has an edge on one axis only; its " "centre on the other must be zero" ) - raise OutputError(msg) + raise ProcessingError(msg) def _edge_measures(self) -> Float[np.ndarray, " n_apertures"]: """Return the width each row's edge width is measured against. @@ -383,11 +396,11 @@ def _check_edges(self, count: int) -> None: "a hard aperture has no edge, and an edge given beside it would " "be silently unused; pass edges=None" ) - raise OutputError(msg) + raise ProcessingError(msg) return if self.edges is None: msg = f"a {smooth[0]} aperture needs edges, one per aperture" - raise OutputError(msg) + raise ProcessingError(msg) edges = _aperture_array(self.edges, (count,), "edges") object.__setattr__(self, "edges", edges) rows = np.array(kinds) @@ -396,7 +409,7 @@ def _check_edges(self, count: int) -> None: "a hard aperture has no edge, and an edge given beside it would be " "silently unused; give zero on its row" ) - raise OutputError(msg) + raise ProcessingError(msg) for kind in dict.fromkeys(smooth): if kind == "supergauss": self._check_orders(edges, rows == kind) @@ -412,7 +425,7 @@ def _check_orders( "quadrature weighting needs a symmetric edge, and a supergauss " "profile has none; use amplitude weighting" ) - raise OutputError(msg) + raise ProcessingError(msg) if any( shape.startswith("half_plane") for shape, row in zip(self.row_shapes, rows, strict=True) @@ -422,10 +435,10 @@ def _check_orders( "a supergauss profile falls from a centre, and a half-plane has none; " "use a hard, tanh or rcos edge" ) - raise OutputError(msg) + raise ProcessingError(msg) if np.any(edges[rows] < 2): msg = "every supergauss order must be at least 2" - raise OutputError(msg) + raise ProcessingError(msg) def _check_widths( self, kind: str, edges: Float[np.ndarray, " n_apertures"], rows: np.ndarray @@ -452,10 +465,10 @@ def _check_widths( f"a {kind} aperture under {self.weighting} weighting needs " f"0 < w <= D/{fraction} for every aperture" ) - raise OutputError(msg) + raise ProcessingError(msg) if np.any(edges[rows & half_plane] <= 0): msg = f"a {kind} half-plane needs a positive edge width" - raise OutputError(msg) + raise ProcessingError(msg) if kind == "tanh" and self.weighting == "amplitude": # tanh is not flat at its centre: W'(0) = -sech^2(r/w) / 2w, so for # r/w < 4 a bright beam there converges only at third order in the mask @@ -493,7 +506,7 @@ def _check_paraxial(self) -> None: "|X| + D/2 (+ w for rcos) >= z; a component there cannot leave the " "exit face (SEP 23 section 4.2)" ) - raise OutputError(msg) + raise ProcessingError(msg) def _reach(self, row: int, shape: str, centre: Float[np.ndarray, " 2"]) -> float: """Return how far from the origin a row's outline reaches in the mask plane. @@ -856,7 +869,7 @@ def far_field_tables( Raises ------ - OutputError + ProcessingError On a line, for an aperture whose centre is off ``y = 0``, a half-plane bounded in y or an ellipse, which have no meaning uniform in y, or a region whose ``kappa_y`` interval excludes zero, which would select nothing. @@ -870,7 +883,7 @@ def far_field_tables( "on a line uniform in y an aperture is a slit along x, so its y centre " "must be zero" ) - raise OutputError(msg) + raise ProcessingError(msg) if apertures is not None: _refuse_off_line(apertures) excluded = np.flatnonzero(~((regions[:, 2] <= 0) & (regions[:, 3] > 0))) @@ -880,7 +893,7 @@ def far_field_tables( f"{excluded.tolist()}, whose kappa_y interval excludes zero, would " "select nothing" ) - raise OutputError(msg) + raise ProcessingError(msg) if apertures is None: empty = np.empty(0) return ApertureTables( @@ -926,7 +939,7 @@ def _refuse_off_line(apertures: ApertureSet) -> None: "a circle or a rectangle, each a slit along x, or a half-plane bounded " "in x" ) - raise OutputError(msg) + raise ProcessingError(msg) def _outlines(apertures: ApertureSet, *, line: bool) -> list[ApertureOutline]: diff --git a/src/solprop/stepper/controller.py b/src/solprop/stepper/controller.py index 64a6ecdc0..a3ca85730 100644 --- a/src/solprop/stepper/controller.py +++ b/src/solprop/stepper/controller.py @@ -121,8 +121,7 @@ def weighted_norm_scale( .. note:: Provisional. Which weighting actually serves weak observables best -- fixed per-band weights, per-mode weights or a rolling per-bin scale -- has not been - measured: it is the open question "Error norms for observables far below the - pump" in ``docs/dev/open-questions.md`` (solprop issue #259). + measured: it is solprop issue #259. Parameters ---------- diff --git a/src/solprop/stepper/low_storage.py b/src/solprop/stepper/low_storage.py index 51f559915..969475da2 100644 --- a/src/solprop/stepper/low_storage.py +++ b/src/solprop/stepper/low_storage.py @@ -15,8 +15,10 @@ on the measured observable, by :func:`~solprop.stepper.schedule.calibrate` (``docs/guide/numerics/fixed-schedules.md``). -This module holds the specification a run carries. The march and its register passes -are in :mod:`solprop.backends.low_storage`. +This module holds the specification a run carries. The reference's march is +:mod:`solprop.backends.numpy_ref.marches.low_storage` and its register passes are +:class:`solprop.backends.numpy_ref.engines.NumpyLowStorage`; the table keys both +backends share are in :mod:`solprop.backends.low_storage`. References ---------- diff --git a/src/solprop/stepper/multistep.py b/src/solprop/stepper/multistep.py index 7b68ea9e9..b31b2fb7d 100644 --- a/src/solprop/stepper/multistep.py +++ b/src/solprop/stepper/multistep.py @@ -223,13 +223,19 @@ def __post_init__(self) -> None: """ # The Literal annotation refuses an unknown formulation first wherever the # annotations are checked at run time, as in the test suite. - if self.formulation not in ("interaction", "exponential"): # pragma: no cover + if self.formulation not in ( + "interaction", + "exponential", + ): # pragma: no cover - its annotation refuses it first msg = ( "formulation must be 'interaction' or 'exponential', got " f"{self.formulation!r}" ) raise StepperError(msg) - if self.carrier_frame not in ("off", "scalar"): # pragma: no cover + if self.carrier_frame not in ( + "off", + "scalar", + ): # pragma: no cover - its annotation refuses it first msg = f"carrier_frame must be 'off' or 'scalar', got {self.carrier_frame!r}" raise StepperError(msg) if self.carrier_frame != "off" and self.formulation != "exponential": diff --git a/src/solprop/stepper/runge_kutta.py b/src/solprop/stepper/runge_kutta.py index 3551f4fe3..c852c83d0 100644 --- a/src/solprop/stepper/runge_kutta.py +++ b/src/solprop/stepper/runge_kutta.py @@ -23,8 +23,9 @@ class RungeKutta: """The interaction-picture Runge-Kutta march with an embedded error estimate. - Every accepted step pays the tableau's stages in source calls (six for DOPRI5, the - first-same-as-last stage recycled) and keeps no history, where the Adams method + Every accepted step pays the tableau's stages in source calls (six for DOPRI5 on + the native backend, which recycles the first-same-as-last stage, and all seven on + the NumPy reference) and keeps no history, where the Adams method holds from seven to about sixty further copies of the state, by backend and formulation: the integrator to choose when a source evaluation is cheap or the state is too large for the Adams history diff --git a/src/solprop/stepper/settings.py b/src/solprop/stepper/settings.py index 63cf6e1bc..7f0a1f029 100644 --- a/src/solprop/stepper/settings.py +++ b/src/solprop/stepper/settings.py @@ -100,7 +100,8 @@ class StepperSettings: kink. ``None`` for an adaptive run. save_planes : numpy.ndarray Positions in z the driver will ask for, m, shape ``(n_z,)``, increasing. Steps - land on them exactly; there is no dense output. + land on them exactly, unless `interpolate_planes` observes them inside + accepted steps. propagator_mode : {'auto', 'tabulate', 'recompute'} Whether the backend tabulates the stage propagator factors or recomputes them. ``"auto"`` leaves the choice to the backend, which records what it resolved. @@ -113,7 +114,10 @@ class StepperSettings: Whether a step is capped at the width of the operator-table interval it starts in. The cumulative table makes the flow exact across intervals, so the cap is off on the diagonal-flow routes and on for a coupled flow, whose flow error the - embedded estimate does not see (SEP 14 section 4.1). + embedded estimate does not see (SEP 14 section 4.1). The Runge-Kutta and + low-storage marches read it; an Adams march caps by its method's own + :attr:`~solprop.stepper.multistep.Multistep.interval_cap`, which ``assemble`` + records here. auto_init : bool Whether the start-up rule takes the step after the first from the first step's own error estimate (``PIController.start_factor``); ``False`` grows from diff --git a/src/solprop/tools/capillary.py b/src/solprop/tools/capillary.py index 974618c87..0301a78b0 100644 --- a/src/solprop/tools/capillary.py +++ b/src/solprop/tools/capillary.py @@ -152,9 +152,9 @@ class SolitonParams(Displayed): fission_length : float In m. zdw : float - Zero-dispersion wavelength in m within 100 nm to 3 um, or NaN when the - dispersion does not change sign there. No second, guess-seeded search is - tried. + Zero-dispersion wavelength in m within 100 nm to 3 um nearest the pump, + among those no resonance separates from it (:func:`solprop.modes.base.zdw` + with ``near``), or NaN when there is none. loss_length : float The 1/e **power** loss length of the mode at the pump in m. effective_area : float diff --git a/src/solprop/tools/design.py b/src/solprop/tools/design.py index 7680b3ba1..82fb5ed4d 100644 --- a/src/solprop/tools/design.py +++ b/src/solprop/tools/design.py @@ -103,7 +103,7 @@ readily as onto a zero; at a zero the residual it ends on is of the order of the slope times the tolerance, many orders below the ends, and at a pole it diverges past both. A parameter has no integral like ``beta1`` to test the change against (see -:data:`~solprop.tools.waveguide._POLE_FACTOR`), so the residual's own size decides.""" +:func:`~solprop.modes.base._is_zero`), so the residual's own size decides.""" def _pressure_root( diff --git a/src/solprop/tools/waveguide.py b/src/solprop/tools/waveguide.py index 388eb9866..279198db4 100644 --- a/src/solprop/tools/waveguide.py +++ b/src/solprop/tools/waveguide.py @@ -22,6 +22,7 @@ DiluteScalingWarning, MaterialError, MaterialRangeWarning, + NoZeroDispersionError, ToolsError, ) from solprop.modes import base @@ -46,30 +47,9 @@ _ZDW_RANGE = (100e-9, 3e-6) -"""Window of the zero-dispersion search in m: :func:`modes.base.zdw`'s.""" - - -_ZDW_SAMPLES = 512 -"""Samples, evenly spaced in frequency, on which the dispersion's sign is read.""" - - -_ZDW_REFINE_ROUNDS = 4 -"""Rounds of array samples that refine a sign change of the dispersion. Four take a -bracket of 3.6e13 rad/s to 3.4e7 rad/s, where interpolating linearly reaches the noise -of the differenced ``beta2``.""" - - -_ZDW_REFINE_SAMPLES = 33 -"""Samples of each refinement round: 32 intervals, so each round narrows 32-fold.""" - - -_POLE_FACTOR = 2.0 -"""How far the group delay at a refined sign change of ``beta2`` may sit from its value -at the bracket's ends, in units of the change a bounded ``beta2`` could produce across -the bracket, before the sign change is read as a pole rather than a zero. At a zero -``beta1`` is extremal and moves by at most half that unit; at a gas resonance it -diverges. The differenced ``beta2`` itself cannot tell them apart: ``beta1`` is even -about a pole, so its central difference vanishes there too.""" +"""Window of the zero-dispersion search in m: from below the default of +:func:`modes.base.zdw`, so a deep-ultraviolet zero of a thin fill is found; the pump, +as the search's reference, keeps the gas lines below it out of reach.""" @contextmanager @@ -201,85 +181,19 @@ def _fill_n2( return n2_from_chi3(chi3, index), index -def _refine_zero(mode: Mode, low: float, high: float, z: float) -> float: - """Return a sign change of the dispersion inside a bracket, by array samples. - - A mode's index models evaluate an array at about the cost of one point, so each - round narrows the bracket 32-fold for the cost of one Brent step, where a scalar - search costs a glass model evaluation per iterate. The rounds stop short of a pole - of the differenced ``beta2``, which a scalar search converges onto until the model - returns NaN. - - - ``low``, ``high``: the bracket, rad/s, whose ends have ``beta2`` of opposite - signs. - - ``z``: position along the waveguide, m. - - Returns: the first sign change upwards in frequency, rad/s, linearly interpolated - in the last bracket; or NaN when samples that are not finite separate the signs. - """ - first = last = math.nan - for _ in range(_ZDW_REFINE_ROUNDS): - grid = np.linspace(low, high, _ZDW_REFINE_SAMPLES) - sampled = base.beta2(mode, grid, z) - crossing = np.flatnonzero(np.sign(sampled[:-1]) * np.sign(sampled[1:]) <= 0.0) - if crossing.size == 0: - return math.nan - i = int(crossing[0]) - low, high = float(grid[i]), float(grid[i + 1]) - # The first change has a nonzero sample below it, so the two cannot be equal. - first, last = float(sampled[i]), float(sampled[i + 1]) - return low - first * (high - low) / (last - first) - - def _zdw_near(mode: Mode, omega: float, z: float) -> float: - """Return the zero-dispersion wavelength nearest a pump frequency. - - :func:`solprop.modes.base.zdw` brackets one sign change across its whole window, - which a gas resonance in the vacuum ultraviolet defeats: krypton flips the sign of - the dispersion twice near 120 nm, the ends then agree, and the zero at 769 nm of a - 14 um capillary at 15 bar is refused. Here the sign is sampled, the changes are - refined outwards from the pump, the changes through a pole are dropped, and the zero - nearest the pump is the one reported; a change further than the best so far cannot - beat it, which spares the dozens of changes an antiresonant fibre's resonances - give. Two limits of a sampled search remain: a zero and a pole inside one sample - interval (3.6e13 rad/s) restore the sign and are both missed, and a sample that is - not finite cannot bracket anything. + """Return the zero-dispersion wavelength nearest a pump frequency, or NaN. + + :func:`solprop.modes.base.zdw` over :data:`_ZDW_RANGE` with the pump as its + reference: the nearest zero that no resonance separates from the pump. - ``omega``: pump angular frequency in rad/s. - ``z``: position along the waveguide, m. - - Returns: wavelength in m, or NaN when the dispersion has no zero in 100 nm to 3 - um. + - Returns: wavelength in m, or NaN when the search finds no zero. """ - grid = np.linspace( - 2.0 * math.pi * C / _ZDW_RANGE[1], - 2.0 * math.pi * C / _ZDW_RANGE[0], - _ZDW_SAMPLES, - ) - nearest = math.nan - # The refinement converges onto a pole as readily as onto a zero, and a model may - # divide by zero exactly there; the group-delay test below tells the two apart. - with _probing(), np.errstate(divide="ignore", invalid="ignore"): - sampled = base.beta2(mode, grid, z) - changes = np.flatnonzero(np.sign(sampled[:-1]) * np.sign(sampled[1:]) < 0.0) - # How near each bracket can bring a zero: 0 for one holding the pump. - reach = np.maximum.reduce( - [grid[changes] - omega, omega - grid[changes + 1], np.zeros(changes.size)] + try: + return base.zdw( + mode, z, wavelength_limits=_ZDW_RANGE, near=2.0 * math.pi * C / omega ) - for i in changes[np.argsort(reach, kind="stable")]: - low, high = float(grid[i]), float(grid[i + 1]) - if not math.isnan(nearest) and max(low - omega, omega - high) >= abs( - nearest - omega - ): - break - root = _refine_zero(mode, low, high, z) - if math.isnan(root): - continue - delay = base.beta1(mode, np.array([low, root, high]), z) - bounded = max(abs(sampled[i]), abs(sampled[i + 1])) * (high - low) - closer = math.isnan(nearest) or abs(root - omega) < abs(nearest - omega) - if closer and abs(delay[1] - delay[0]) <= _POLE_FACTOR * bounded: - nearest = root - if math.isnan(nearest): + except NoZeroDispersionError: return math.nan - # Outside the probing context, so a zero beyond the index model's range warns. - base.beta(mode, np.array([nearest]), z) - return 2.0 * math.pi * C / nearest diff --git a/src/solprop/translate/assembly.py b/src/solprop/translate/assembly.py index 0338ab8f1..69e59d99c 100644 --- a/src/solprop/translate/assembly.py +++ b/src/solprop/translate/assembly.py @@ -136,7 +136,6 @@ ) from solprop.translate.transverse import checked_design, resolve_transverse from solprop.translate.validation import ( - _INPUT_NOISE_ADMITTED, DEFAULT_FLOW_CONDITION_LIMIT, MOVING_FLOW_CERTIFICATE, _Assembly, @@ -146,6 +145,7 @@ _check_tdse_assembly_route, _refuse_a_wall_off_the_capillary_route, _refuse_carrier_removing_frame, + _refuse_modified_noise, _refuse_planes_at_jumps, _refuse_split_crossing, _validated, @@ -558,14 +558,7 @@ def _general_flow( n_modes, n_omega)``. - ``grid``: the run's grid, whose coarse axis the leaf is tabulated on. """ - if build.noise_model == "modified": - msg = ( - "a split block's coupled flow refuses the 'modified' noise model: its " - "draw is transported by the unitary phase of a diagonal flow, and the " - "transport of a draw through a nonunitary coupled flow is not measured " - "in this package; the backend refuses it too. " + _INPUT_NOISE_ADMITTED - ) - raise TranslationError(msg) + _refuse_modified_noise(build.noise_model, "a split block's coupled flow") exponent = float(build.dz_max) * float(np.max(abs(coupled))) if exponent > MAX_GENERAL_FLOW_EXPONENT: worst = int(np.argmax(np.max(abs(coupled), axis=(0, 1)))) @@ -796,14 +789,7 @@ def _moving_flow( flow's sections are the maps' here, which is natural and not required: the stage bundle carries the two weight rows separately (kernel schema 14). """ - if build.noise_model == "modified": - msg = ( - "a moving guide's coupled flow refuses the 'modified' noise model: its " - "draw is transported by the unitary phase of a diagonal flow, and its " - "transport through a moving guide's coupled flow is not measured in " - "this package; the backend refuses it too. " + _INPUT_NOISE_ADMITTED - ) - raise TranslationError(msg) + _refuse_modified_noise(build.noise_model, "a moving guide's coupled flow") assert route.moving_generator is not None return frozen_residual_flow( grid.omega, @@ -869,7 +855,7 @@ def _general_prefactor( Re n_eff)`` with the crop scale folded in. On the general route that factor is replaced by the record's own ``source_frequency_factor`` and by the reciprocal normalisation inside Q, so what is left for this row is the crop scale - ``n_t / n_to`` -- which stays here, where it has always been, because the + ``n_t / n_to`` -- which stays here, as on every other route, because the projection is frequency dependent and folding a grid convention into it would hide it. It is real, and it is exactly zero outside the active band as every other route's prefactor is, so no unnormalised @@ -938,12 +924,23 @@ def _stepper_settings( SEP 14 phase 1 relaxes the step limits on the diagonal-flow routes only. A coupled flow's error lies outside the embedded estimate, and a reject-free run cannot undo - an overshoot, so both keep the version-16 policy: the interval cap and no start-up - rule. + an overshoot, so both keep the interval cap and no start-up rule. - - ``interval_cap``: the interval cap asked for; ``None`` takes the route's. + - ``interval_cap``: the interval cap asked for; ``None`` takes the route's. The + Adams march caps by its method's own ``interval_cap`` (ADR-037), which is what + is recorded; a different request is refused. """ restrained = linear.coupled_flow is not None or controller.reject_free + method = fields.get("integrator") + if isinstance(method, Multistep): + if interval_cap is not None and interval_cap != method.interval_cap: + msg = ( + f"interval_cap={interval_cap} would be ignored: Multistep() caps its " + f"steps by its own interval_cap. Use " + f"Multistep(interval_cap={interval_cap}), or leave interval_cap unset" + ) + raise TranslationError(msg) + interval_cap = method.interval_cap return StepperSettings( controller=controller, interval_cap=restrained if interval_cap is None else interval_cap, @@ -1083,6 +1080,8 @@ def assemble( # noqa: PLR0915 - one keyword per physics object of a run interval_cap : bool or None, optional Whether a step is capped at its operator-table interval's width. ``None`` caps it only for a coupled flow or a reject-free controller (SEP 14 section 4.1). + An Adams `integrator` caps by its own ``interval_cap``, which ``None`` takes and + a different value is refused. auto_init : bool, optional Whether the start-up rule chooses the step after the first; `dz_init` is the first. Default ``False``, the convenience interfaces' choice when no `dz_init` @@ -1436,7 +1435,7 @@ def assemble( # noqa: PLR0915 - one keyword per physics object of a run grids=build_masks( grid, polarisation_taper=polarisation_taper, - region=getattr(settings.controller, "region", "active"), + region=settings.controller.region, harmonic_carrier=compiled.harmonic_carrier, ), linear=linear, diff --git a/src/solprop/translate/coupled.py b/src/solprop/translate/coupled.py index f793d8e3c..c430455a3 100644 --- a/src/solprop/translate/coupled.py +++ b/src/solprop/translate/coupled.py @@ -2,7 +2,7 @@ # # SPDX-License-Identifier: GPL-3.0-or-later -"""The metric and the coupled-flow representation of a general modal guide. +"""The flux metric and coupled flow of a general modal guide, capillary wall or taper. Two leaves of section 3 of ``docs/dev/kernel-contract.md``. Units are SI throughout (``omega`` in rad/s, ``z_edges`` in m, generators in 1/m, metric entries, errors and @@ -2261,15 +2261,26 @@ def frozen_residual_flow( conditioning[index] = np.maximum(bound, 1.0) residual[index] = _residual_enclosure(coefficients[index], block, link, index) worst = int(np.argmax(np.max(conditioning, axis=0))) - if conditioning[:, worst].max() > float(condition_limit): + reached = float(conditioning[:, worst].max()) + if reached > float(condition_limit): + # The bound is exp(dz_max spread), so the step it admits follows exactly; + # printed rounded down, so that the printed value is admitted too. A limit of + # one admits no positive step against any spread. + admitted = "a limit of one admits no positive step" + if float(condition_limit) > 1.0: + cap = float(dz_max) * math.log(float(condition_limit)) / math.log(reached) + unit = 10.0 ** (math.floor(math.log10(cap)) - 2) + admitted = ( + f"a dz_max of at most {math.floor(cap / unit) * unit:.3g} m is admitted" + ) msg = ( f"a frozen-residual flow's inverse conditioning reaches " - f"{float(conditioning[:, worst].max()):.4g} over a step of " + f"{reached:.4g} over a step of " f"{float(dz_max):.4g} m at {float(np.asarray(omega)[worst]):.6g} rad/s, " f"above the {float(condition_limit):.4g} this flow admits: the " "interaction picture's inverse action would amplify the nonlinear source " - "by that factor. Cap dz_max, divide the sections, retain fewer channels, " - "or raise the limit deliberately" + f"by that factor. Cap dz_max ({admitted}), divide the sections, retain " + "fewer channels, or raise the limit deliberately" ) raise TranslationError(msg) return CoupledFlowTables( diff --git a/src/solprop/translate/envelope_plasma.py b/src/solprop/translate/envelope_plasma.py index 1d6ab63a0..1fb4659a7 100644 --- a/src/solprop/translate/envelope_plasma.py +++ b/src/solprop/translate/envelope_plasma.py @@ -61,6 +61,10 @@ _NEGLIGIBLE_RATE = 1e-30 _FORMAT_VERSION = 1 _CYCLES: dict[str, CycleIntegralData] = {} +"""Validated cycle integrals by identity; the oldest is dropped past `_CYCLES_KEPT`.""" +_CYCLES_KEPT = 16 +"""Cycle integrals kept: the field range, and so the identity, follows each input, so +an in-process energy scan would otherwise keep one per point.""" @dataclass(frozen=True, eq=False) @@ -667,5 +671,7 @@ def build_cycle_integrals( f"{np.max(validation.residuals):.3e}" ) result = CycleIntegralData(table, rules, validation, identity) + if len(_CYCLES) >= _CYCLES_KEPT: + del _CYCLES[next(iter(_CYCLES))] _CYCLES[identity] = result return result diff --git a/src/solprop/translate/general.py b/src/solprop/translate/general.py index 819d64deb..9969f1766 100644 --- a/src/solprop/translate/general.py +++ b/src/solprop/translate/general.py @@ -820,7 +820,7 @@ def general_modal_route( guide, grid, z_end=float(z_max) * (1.0 + float(margin)), gram_atol=gram_atol ) # One sampling of the reference's own flux Gram at the run's coarse bins, used - # twice: for the occupied-support certificate every route now carries, and for + # twice: for the occupied-support certificate every route carries, and for # the dense metric a declared basis declares. Measuring it once is what keeps # the two from drifting apart, and it costs 2.2 ms of a 28.2 ms route build -- # 8 % -- on the 1.5 um strand fixture, and nothing per step. @@ -1584,8 +1584,8 @@ def guide_identity(guide: ModalGuide) -> Mapping[str, JsonValue]: "raman": None if region.raman is None else _raman_identity(region.raman.parameters), - # Written only for a region with a gas fill, so that every other - # guide's identity, and its resume key, is what it was. + # Written only for a region with a gas fill, so that a guide without + # one carries no gas entry in its identity or its resume key. **({} if region.gas is None else {"gas": _gas_identity(region.gas)}), } for region in guide.regions @@ -1782,7 +1782,7 @@ def modal_identity( "chi3": [float(one) for one in responses.chi3[0, 0]], }, # Written only where a gas region takes SEP 6's dispersive cubic, so that - # every other route's record is what it was. + # every other route's record carries no dispersive entry. **( {} if route.dispersive is None @@ -1815,7 +1815,7 @@ def modal_identity( "certificate_id": flow.certificate_id, "reference_channel": int(route.reference_channel), # A moving guide's connection certificate, written only where there is - # one so that a split block's file keeps the key it was stamped with. + # one, so that a split block's key carries no certificate entry. **( { "connection_certificate": quantised_measurement( diff --git a/src/solprop/translate/ionisation.py b/src/solprop/translate/ionisation.py index 1213d0061..583e54b46 100644 --- a/src/solprop/translate/ionisation.py +++ b/src/solprop/translate/ionisation.py @@ -123,7 +123,8 @@ class RateTable: The largest relative deviation from direct evaluation measured during the build. key : str A digest of the rate's parameters and the build settings, stable across - processes. Names a cache entry; two tables with the same key are the same table. + processes; two tables with the same key are the same table. A plasma channel's + identity records it, so a run's record names the table it used. convention : str Optical-cycle convention retained from the source rate. A table constructed by hand defaults to ``'unspecified'``. @@ -329,7 +330,7 @@ def rate_table_key( Every setting that changes the table appears once, in name order, so the key cannot depend on the order in which the rate's keyword arguments were written: the same - settings in a different order give the same cache file. + settings in a different order give the same entry in the in-memory cache. Parameters ---------- @@ -586,20 +587,7 @@ def build_rate_table( def _finalise(table: RateTable, error: float) -> RateTable: """Return a copy of the table with the measured error recorded.""" - return RateTable( - log_rate=table.log_rate, - coefficients=table.coefficients, - log_field_min=table.log_field_min, - d_log_field=table.d_log_field, - field_min=table.field_min, - field_max=table.field_max, - rate_max=table.rate_max, - error=error, - key=table.key, - convention=table.convention, - species_identity=table.species_identity, - ionisation_potential=table.ionisation_potential, - ) + return replace(table, error=error) def frozen_table(table: RateTable) -> RateTable: @@ -629,10 +617,11 @@ def frozen_table(table: RateTable) -> RateTable: def _digest(key: tuple[object, ...]) -> str: - """Return a stable hexadecimal digest of a cache key. + """Return a stable hexadecimal digest of a table's settings. Through :mod:`hashlib` rather than :func:`hash`, whose value for a string is salted - per process: the digest names a cache entry that may outlive this process. + per process: the digest is recorded in a run's identity + (``rate_table_identity``), which must name the same table in every process. """ return hashlib.blake2b(repr(key).encode("utf-8"), digest_size=8).hexdigest() diff --git a/src/solprop/translate/linop.py b/src/solprop/translate/linop.py index 88fe75eab..c1858cea9 100644 --- a/src/solprop/translate/linop.py +++ b/src/solprop/translate/linop.py @@ -139,16 +139,15 @@ smallest round decade that leaves margin above the floor; see ``docs/guide/numerics/linear-operator.md``. -The factor was originally what stood between a floor measured against the *global* -envelope and a tail measured *per element*, and it was not enough: with the spectral -collar active the global envelope is the collar's own rate, the floor is read two orders -too small, and the interval budget is exhausted before the tolerance is relaxed and the -whole search paid again. The floor is now measured in the -acceptance test's own norm, so the two are comparable and the factor is a margin rather -than a correction. Measured on a capillary with its absorber (1.5 m, 90 nm to 4 um, -n_omega 2049, four modes): the floor goes from 1.5e-13 to 2.3e-7 at 1 mm and the first -build from 416 s to 1.1 s, at half the memory and an agreement with ``quad_vec`` of -5.5e-11 against 2.5e-12. +The floor is measured in the acceptance test's own norm, per element, so floor and tail +are comparable and the factor is a margin rather than a correction. A floor read against +the *global* envelope would not be: with the spectral collar active that envelope is the +collar's own rate, the floor would be read two orders too small, and the interval budget +would be exhausted before the tolerance is relaxed and the whole search paid again. +Measured on a capillary with its absorber (1.5 m, 90 nm to 4 um, n_omega 2049, four +modes), the per-element floor is 2.3e-7 at 1 mm against 1.5e-13 for the global one, and +the first build takes 1.1 s against 416 s, at half the memory and an agreement with +``quad_vec`` of 5.5e-11 against 2.5e-12. """ MAX_TOL = 1e-7 @@ -898,8 +897,8 @@ def build_phi( that expansion against scalar integral tables along z (:mod:`solprop.translate.expansion`). The paths' breakpoints are mandatory edges of the scalar tables, so a stage boundary or a taper corner is never crossed and - becomes a hard kink, exactly as before; what changes is that the cusps and the - corners are resolved in tables of ``n_terms`` scalars rather than of the state. + becomes a hard kink, as in the z table; the cusps and the corners are resolved in + tables of ``n_terms`` scalars rather than of the state. Anything else takes the **z table**: the scalar paths are resolved first, because they are cheap and carry the structure that makes the operator hard, and the @@ -1035,58 +1034,9 @@ def _dispersion_phi( reuse: ParameterExpansion | None = None, kinks: Sequence[float] | np.ndarray = (), ) -> LinearOperator: - """Build the cumulative linear operator of a mode set over a run. - - Three representations, in the order they are tried. + """Build the operator of :func:`build_phi` without its power weight. - A mode set that reports ``z_constant`` takes :func:`constant_phi`: one interval, - degree 1, and a :func:`delta_phi` that is exact to the last bit. - - A mode set whose whole z dependence runs through scalar paths it declares - (:class:`solprop.modes.protocol.ParameterisedMode`) takes the **expansion in those - parameters**: ``D`` is resolved once over the range each path spans, and ``Phi`` is - that expansion against scalar integral tables along z - (:mod:`solprop.translate.expansion`). The paths' breakpoints are mandatory edges of - the scalar tables, so a stage boundary or a taper corner is never crossed and - becomes a hard kink, exactly as before; what changes is that the cusps and the - corners are resolved in tables of ``n_terms`` scalars rather than of the state. - - Anything else takes the **z table**: the scalar paths are resolved first, because - they are cheap and carry the structure that makes the operator hard, and the - operator itself is then resolved on the union of their edges and integrated exactly - in the Chebyshev basis. That is the general representation and the fallback for a - mode whose parameters do not resolve; the only approximation anywhere in ``Phi`` is - the interpolation of ``D`` (``docs/guide/numerics/linear-operator.md``). - - - ``mode``: only ``neff``, ``dneff_domega``, the declared ``core_radius`` and - ``density`` paths and, for the expansion, ``at_parameters`` are used. - - ``grid``: the grid; supplies the frequency axis, the active band and the layout. - - ``z_max``: length the run covers, m, positive and finite. - - ``n_pol``: polarisation components, 1 or 2. ``D`` is the same for both components - of one mode, and is stored for each so that a birefringent mode needs no new - layout. - - ``absorber_rate``: spectral absorber rate in 1/m, shape ``(n_omega,)``, folded - into ``D`` before the integration so the collar is exact as a rate. - - ``loss``: applied to ``D`` before ``Phi`` is integrated, never to an accumulated - exponent afterwards. - - ``tol``: target bound on the uniform error of the table relative to the value - scale. The request is raised to :data:`ROUNDOFF_SAFETY` times the measured - round-off floor of ``D`` when that is larger, because no interpolant can resolve a - function below the noise of its own evaluation, and relaxed further, by decades up - to :data:`MAX_TOL`, if the interval budget is exhausted anyway - (``docs/dev/stepper.md`` section 4, step 4). Both are logged. - - ``max_intervals``: exceeding it sets the fallback flag and logs a warning. - - ``representation``: which representation to build. ``"auto"``, the default, - prefers the expansion; ``"table"`` forces the z table, which is what an - equivalence test between the two needs; ``"expansion"`` refuses to fall back. A - ``z_constant`` mode set takes :func:`constant_phi` whatever this says, since that - path is exact. - - ``reuse``: coefficients of the identical operator function on the same grid, frame - and fixed parameters. The caller must establish function identity. Covered paths - receive new scalar weights; other paths rebuild normally, with a logged reason. - - ``kinks``: further hard kinks in m beside the mode set's breakpoints, as for - :func:`build_phi`. - - Returns: section 3 of the kernel contract, covering ``[0, z_max (1 + margin)]``. + :func:`build_phi` describes the three representations and every argument. """ _checked_representation(representation) span = _checked_span(z_max, margin) @@ -1348,7 +1298,7 @@ def power_weight_row( """Evaluate the modal power weight of an assembled linear group at one position. :func:`power_weight_at` on a problem and the entrance conversion of the launch in - :mod:`solprop.translate.problem` are the same quantity, so they share this one + :mod:`solprop.translate.assembly` are the same quantity, so they share this one arithmetic path: a second, independent evaluation of the mode's index would leave the launch and the output sites disagreeing at the last few bits and break the exactness of the entrance round trip. diff --git a/src/solprop/translate/masks.py b/src/solprop/translate/masks.py index b3b98d230..865966b42 100644 --- a/src/solprop/translate/masks.py +++ b/src/solprop/translate/masks.py @@ -281,6 +281,11 @@ def build_masks( Grids Section 2 of the kernel contract, with read-only arrays. + Raises + ------ + TranslationError + If `region` is neither ``"active"`` nor ``"band"``. + Examples -------- >>> import numpy as np @@ -300,6 +305,9 @@ def build_masks( >>> masks.carrier_2w0 is None True """ + if region not in {"active", "band"}: + msg = f"the error norm's region {region!r} is not 'active' or 'band'" + raise TranslationError(msg) # The grid evaluates its masks and windows afresh at every access, so each is # this group's own: held in place rather than copied again by the group. The # frequency axis is the grid's, which it already holds. diff --git a/src/solprop/translate/modal_tables.py b/src/solprop/translate/modal_tables.py index 8661b1ac9..3c6f77827 100644 --- a/src/solprop/translate/modal_tables.py +++ b/src/solprop/translate/modal_tables.py @@ -282,9 +282,8 @@ def identity(self) -> Mapping[str, JsonValue]: # numpydoc ignore=RT01 """ positions, nodes, components, modes, frequencies = np.shape(self.electric) factors = self.factors - # A moving guide's maps add their sections and degree, - # written only where the maps move so that every snapshot record keeps the - # identity it was stamped with. + # A moving guide's maps add their sections and degree, written only where the + # maps move, so that a snapshot record's identity carries no section entry. synthesis = self.synthesis moving: dict[str, JsonValue] = ( { diff --git a/src/solprop/translate/plasma_integration.py b/src/solprop/translate/plasma_integration.py index 1ab6e4d7b..1b9ae6ecd 100644 --- a/src/solprop/translate/plasma_integration.py +++ b/src/solprop/translate/plasma_integration.py @@ -150,7 +150,7 @@ def design_running_integral( return RunningIntegral.trapezoid() # The annotation refuses another rule first wherever the annotations are checked # at run time, as in the test suite. - if policy != "band": # pragma: no cover + if policy != "band": # pragma: no cover - its annotation refuses it first msg = f"integration must be 'band' or 'trapezoid', got {policy!r}" raise TranslationError(msg) return _design(float(grid.dt_fine), float(grid.omega_max_window)) diff --git a/src/solprop/translate/problem.py b/src/solprop/translate/problem.py index ed7d35eca..261fa7ea4 100644 --- a/src/solprop/translate/problem.py +++ b/src/solprop/translate/problem.py @@ -208,8 +208,10 @@ class Flags: """Static booleans a kernel specialises on at compile time. Section 1 of the kernel contract. They are *derived* from the content of the problem - by :meth:`from_content` and never passed in, so a flag cannot disagree with the - arrays it describes. + by :meth:`from_content`, which every solprop path that builds or changes a problem + calls, so that a flag agrees with the arrays it describes. The problem's + constructor and :meth:`PropagationProblem.validate` do not re-derive them: a problem + built by hand keeps them consistent itself. Attributes ---------- @@ -749,6 +751,40 @@ def _check_integrator(self, stepper: StepperSettings) -> None: ) raise TranslationError(msg) + def _tdse_route_departures(self, stepper: StepperSettings | None) -> list[str]: + """Return how the problem departs from the TDSE's route, each by name.""" + flags = self.flags + checks = [ + (self.grid_kind != "field", "an envelope grid"), + (self.shape[:2] != (1, 1), "more than one mode or polarisation"), + (self.transform.n_pol != 1, "a polarised transform"), + (flags.mode_averaged, "a mode-averaged transform"), + # The input draw is part of the launch and drives the atom with it; the + # modified one is kept apart and is not (SEP 37, section 6). + (self.initial.noise_model == "modified", "the 'modified' noise model"), + (flags.has_plasma, "a plasma response"), + (flags.has_raman, "a Raman response"), + (self.linear.coupled_flow is not None, "a coupled linear flow"), + ] + if stepper is not None: + checks += [ + ( + not isinstance(stepper.integrator, Multistep), + "a method other than Adams", + ), + (stepper.interpolate_planes, "interpolated save planes"), + (stepper.schedule is not None, "a fixed schedule"), + ] + scheme = self.responses.absorber_scheme + checks.append( + ( + scheme != "nonlinear", + f"the {scheme!r} absorber scheme (it takes the in-stage 'nonlinear' " + "one)", + ) + ) + return [reason for failed, reason in checks if failed] + def _check_tdse(self, source: TDSESource, stepper: StepperSettings | None) -> None: """Refuse a manually constructed atomic seam outside the admitted route. @@ -756,30 +792,13 @@ def _check_tdse(self, source: TDSESource, stepper: StepperSettings | None) -> No :func:`validate_run`. """ descriptor = source.descriptor - if ( - self.grid_kind != "field" - or self.shape[:2] != (1, 1) - or self.transform.n_pol != 1 - or self.flags.mode_averaged - # The input draw is part of the launch and drives the atom with it; the - # modified one is kept apart and is not (SEP 37, section 6). - or self.initial.noise_model == "modified" - or self.flags.has_plasma - or self.flags.has_raman - or ( - stepper is not None - and ( - not isinstance(stepper.integrator, Multistep) - or stepper.interpolate_planes - or stepper.schedule is not None - ) - ) - or self.linear.coupled_flow is not None - or self.responses.absorber_scheme != "nonlinear" - ): - raise TranslationError( - "TDSE requires the scalar resolved modal Adams route" + reasons = self._tdse_route_departures(stepper) + if reasons: + msg = ( + "TDSE requires the scalar resolved modal Adams route, not " + f"{', '.join(reasons)}" ) + raise TranslationError(msg) if ( descriptor.samples != self.grids.n_to or descriptor.spacing != self.grids.dt_fine @@ -1980,7 +1999,7 @@ def visit(prefix: str, node: object) -> None: if run is not None: visit("stepper", run.stepper) visit("stats_spec", run.stats) - # The route's leaves keep the names they have always had: + # The route's leaves are named without the route prefix: # ``transform.synthesis``, ``flux.base.kperp_sq``. visit(prefix, getattr(node, entry.name)) continue @@ -2011,7 +2030,7 @@ def _walk_tables(problem: PropagationProblem) -> list[tuple[str, PiecewiseChebys ("responses.density", problem.responses.density), ("responses.prefactor", problem.responses.prefactor), ( - "responses.prefactor.weights", + "responses.prefactor_expansion.weights", None if problem.responses.prefactor_expansion is None else problem.responses.prefactor_expansion.weights, diff --git a/src/solprop/translate/radial.py b/src/solprop/translate/radial.py index 7b323b9a1..cd3d3a30e 100644 --- a/src/solprop/translate/radial.py +++ b/src/solprop/translate/radial.py @@ -271,8 +271,6 @@ def _at_parameters(values: Mapping[str, float]) -> tuple[np.ndarray, np.ndarray] dispersion, lambda model, z: longitudinal_root(_material(model, z))[:2], paths, - kinks, - span, n_pol, ) if len(paths) > MAX_PARAMETERS: @@ -478,17 +476,17 @@ class _AdiabaticAmplitude: - ``roots``: ``(model, z) -> (k_z, propagating)``, each ``(n_r, n_omega)``, from the one root evaluation the operator uses (:func:`solprop.translate.spatial.longitudinal_root`). - - ``kinks``: breakpoints of those paths, m. - - ``span``: end of the tabulated range, m. + + The adiabatic certificate (:mod:`solprop.adiabatic`) has already refused a path + crossing a cutoff, and every sample the builders take is checked again by + :meth:`_admitted`, so the paths' breakpoints need no check of their own. """ - def __init__( # noqa: PLR0917 - called positionally + def __init__( self, dispersion: SpatialDispersion, roots: Callable[[SpatialDispersion, float], tuple[np.ndarray, np.ndarray]], paths: Mapping[str, ZProfile], - kinks: np.ndarray, - span: float, n_pol: int, ) -> None: self._dispersion = dispersion @@ -498,9 +496,6 @@ def __init__( # noqa: PLR0917 - called positionally root, propagating = roots(dispersion, 0.0) self._mask = propagating & dispersion.grid.active_mask[None, :] self._reference = np.where(self._mask, np.real(root), 1.0) - # The adiabatic certificate (solprop.adiabatic) has already refused a path - # crossing a cutoff; every sample the builders take is checked again below. - del kinks, span def _admitted(self, model: SpatialDispersion, z: float) -> np.ndarray: """Return ``Re k_z`` where the term applies, refusing a cutoff crossing. diff --git a/src/solprop/translate/raman.py b/src/solprop/translate/raman.py index ee79f652f..94f69d05b 100644 --- a/src/solprop/translate/raman.py +++ b/src/solprop/translate/raman.py @@ -17,7 +17,8 @@ - :func:`kernel_spectrum` transforms a sampled kernel with the convolution's ``dt`` folded in (an internal-convention array: never pass it to ``to_optics``); :class:`RamanKernels` (:func:`build_raman_kernels`) holds the undamped rows and - memoises the damped spectrum whenever a rate changes. + memoises the damped spectrum whenever a rate changes, the reference the backend + tests compare the backends' own damping and transform against. A pump-probe delay entering the taper collar samples an attenuated response even inside the window. The design, the doubled grid, the taper's bias and the per-density @@ -398,14 +399,14 @@ class RamanKernels: """The Raman kernel of one response on one grid, with its spectrum cached on rho. The two arrays the kernel contract needs, kept together with the transform that - joins them. :attr:`undamped` is sampled once; :meth:`spectrum` applies the - dephasings, transforms, and remembers the result, so that a propagation at constant - density transforms the kernel once and one along a pressure gradient transforms it - once per density the stepper asks for. + joins them. A run carries only :attr:`undamped` (``raman_kernel_undamped``), and + each backend damps and transforms it itself; :meth:`spectrum` applies the + dephasings and transforms here, and is the reference arithmetic the backend tests + compare the backends' damped spectra against. - Only the most recent density is remembered, which is the right behaviour here: a - gradient presents a new density at every stage, so a growing cache would hold - thousands of spectra and hit none of them. + Only the most recent density is remembered: a gradient presents a new density at + every stage, so a growing cache would hold thousands of spectra and hit none of + them. Build one with :func:`build_raman_kernels`. @@ -636,7 +637,7 @@ def rate( def build_raman_kernels(response: RamanResponse, grid: TimeGrid) -> RamanKernels: - """Sample a Raman response onto a grid, ready for a backend to convolve with. + """Sample a Raman response onto a grid, with the damped spectrum tests compare to. Parameters ---------- diff --git a/src/solprop/translate/responses.py b/src/solprop/translate/responses.py index bf5d3f073..298b2a8fa 100644 --- a/src/solprop/translate/responses.py +++ b/src/solprop/translate/responses.py @@ -275,8 +275,8 @@ class KerrCoefficients: Whether the polarisation is the real part of the result. True on a field grid. density : PiecewiseChebyshev or None The scale multiplying coefficient at each z. A composite uses sum(rho*gamma3) - with coefficient=eps0; a single response retains its original coefficient and - density operation order. None is used only by the standalone leaf builder. + with coefficient=eps0; a single response keeps its own coefficient, scaled by + its density. None is used only by the standalone leaf builder. Examples -------- @@ -677,6 +677,11 @@ def dispersive_terms( "dispersive Kerr responses must agree on their evaluator; one run takes " "one electronic law" ) + if len({one.thg for one in responses}) != 1: + raise TranslationError( + "dispersive Kerr responses must agree on thg; one leaf carries one cubic " + "sector" + ) envelope = grid.kind == "envelope" if envelope and first.thg and grid.ffac < THG_OVERSAMPLING: msg = ( @@ -1030,11 +1035,11 @@ class RamanCoefficients: """The delayed response of a Raman-active medium, as a fused pass needs it. A leaf of section 5 of the kernel contract, like :class:`PlasmaCoefficients`, so - its fields are not rows of that document. It replaces the three separate rows of - contract version 2 and carries the drive form, which they had nowhere to put: - which real quadratic form drives the coherence on a *field* grid -- ``E^2``, or the - cycle-averaged ``|E_a|^2/2`` -- is a property of the problem, and the translation - layer checks that the declared Kerr and Raman responses agree about it. + its fields are not rows of that document. It carries the kernels, the decay rates + and the drive form together: which real quadratic form drives the coherence on a + *field* grid -- ``E^2``, or the cycle-averaged ``|E_a|^2/2`` -- is a property of + the problem, and the translation layer checks that the declared Kerr and Raman + responses agree about it. Attributes ---------- @@ -1776,9 +1781,13 @@ class CompiledResponses: (:attr:`solprop.translate.problem.PropagationProblem.device_ready`). prefactor : solprop.translate.chebyshev.PiecewiseChebyshev or None The UPPE or envelope prefactor times the crop scale, as a table along z with - value shape ``(n_modes, n_pol, n_omega)``, complex128, in m/(V s) per unit - polarisation. Purely imaginary and exactly zero outside the active band at every - position. The table spans the same z range as ``Phi``. Present when + value shape ``(n_modes, n_pol, n_omega)``, complex128. In V/C, the unit of + ``omega / (eps0 c)``, where the transform's projection carries the effective + area; a mode-averaged problem folds the area conversion in + (:func:`~solprop.nonlinear.normalisation.sqrtw_to_vm`, V/(m sqrt(W))), so there + it is in m sqrt(W)/C and turns a polarisation in C/m^2 into the amplitude's + rate in sqrt(W)/m. Purely imaginary and exactly zero outside the active band at + every position. The table spans the same z range as ``Phi``. Present when `prefactor_representation` is ``"table"`` and also for ``"constant"``, whose one interval of degree 0 is exact; absent for ``"expansion"``. prefactor_expansion : solprop.translate.expansion.ParameterExpansion or None @@ -1975,7 +1984,7 @@ def population_channels( @property def plasma_coefficients(self) -> PlasmaChannel | None: # numpydoc ignore=RT01 - """One-channel leaf for the original specialised execution path. + """One-channel leaf, for the reference's one-channel plasma pass. The sole channel, or ``None`` when there are zero or multiple channels. """ @@ -1983,7 +1992,7 @@ def plasma_coefficients(self) -> PlasmaChannel | None: # numpydoc ignore=RT01 @property def raman_coefficients(self) -> RamanCoefficients | None: # numpydoc ignore=RT01 - """One-component Raman leaf for its original arithmetic. + """One-component Raman leaf, for the reference's one-component Raman pass. The sole component, or ``None`` when there are zero or multiple terms. """ @@ -2304,7 +2313,7 @@ def _log_prefactor(compiled: "CompiledResponses", z_max: float) -> None: The swing is measured from the representation rather than from the physics, so the report is free: it is the largest departure from the entrance value over the run, - which is exactly what freezing the prefactor at ``z = 0`` used to discard. + which is what freezing the prefactor at ``z = 0`` would discard. - ``z_max``: length the run covers, m. """ @@ -2405,7 +2414,7 @@ class _ResponseBuild: def _material_profiles( modes: tuple[Mode, ...], mixture: Mixture | None, profile: ZProfile ) -> _MaterialProfiles: - """Resolve component profiles while preserving the original single path. + """Resolve component profiles, keeping one material on its single path. - ``mixture``: ordered component populations; None keeps the single-material path. - ``profile``: total density path in m^-3, or the single material's nonlinear @@ -2797,10 +2806,11 @@ def compile_responses( ) -> CompiledResponses: """Compile a set of responses into the nonlinear term a kernel executes. - The instantaneous Kerr response, the delayed Raman response and the plasma response - are compiled. A response of any other kind raises rather than being silently - dropped, because a problem that reaches a backend missing a term it declared would - run, converge and be wrong. + The instantaneous and the dispersive Kerr responses, the delayed Raman response and + the field and envelope plasma responses are compiled, one of each kind per + population (species label). A response of any other kind raises rather than being + silently dropped, because a problem that reaches a backend missing a term it + declared would run, converge and be wrong. A plasma response carries its own ionisation rate, so it supplies the run's `ionisation_table`; without one there is no rate table. @@ -2808,8 +2818,8 @@ def compile_responses( A Raman response fills the three rows of section 5 from :func:`solprop.translate.raman.build_raman_kernels` and :func:`solprop.translate.raman.decay_rate_profiles`, and adds ``raman_drive`` to - `response_order` after ``kerr``. It is refused on a two-component problem, which - would need a tensor kernel no backend can consume, and on a + `response_order` after ``kerr``. On a two-component problem it is refused unless + every term declares a tensor contraction (``tensor_capable``), and on a field grid it is refused without a Kerr response beside it, or beside one that disagrees about ``thg``: the drive form is a property of the problem and reaches a backend through the Kerr row. @@ -2817,10 +2827,12 @@ def compile_responses( Parameters ---------- responses : sequence - The declared responses: at most one - :class:`solprop.nonlinear.responses.KerrResponse`, at most one + The declared responses, each defined on this grid: per population, at most one + electronic response (a :class:`solprop.nonlinear.responses.KerrResponse` or a + :class:`solprop.nonlinear.responses.DispersiveKerrResponse`), at most one :class:`solprop.nonlinear.raman.RamanResponse` and at most one - :class:`solprop.nonlinear.responses.PlasmaResponse`, each defined on this grid. + :class:`solprop.nonlinear.responses.PlasmaResponse` or + :class:`solprop.nonlinear.envelope_plasma.EnvelopePlasmaResponse`. grid : solprop.grid.TimeGrid The grid; decides the cubic form and supplies the crop scale. mode : Mode or sequence of Mode diff --git a/src/solprop/translate/routes.py b/src/solprop/translate/routes.py index 953dffed3..adf30c215 100644 --- a/src/solprop/translate/routes.py +++ b/src/solprop/translate/routes.py @@ -83,12 +83,12 @@ def spatial_kind(geometry: SpatialGeometry) -> SpatialKind: @dataclass(frozen=True, eq=False) class TDSESource: - """The TDSE response: the modal route's reference-only extension (SEP 26). + """The TDSE response: the modal route's extension (SEP 26). - Only the NumPy reference executes it; every other backend refuses it by name - (``docs/dev/kernel-contract.md`` section 6). The atomic binding itself is an - execution resource, owned by the driver and handed to the backend explicitly; this - record is its immutable scientific identity. + The NumPy reference and the native CPU build execute it; a native device build + refuses it by name (``docs/dev/kernel-contract.md`` section 6). The atomic binding + itself is an execution resource, owned by the driver and handed to the backend + explicitly; this record is its immutable scientific identity. Attributes ---------- @@ -154,7 +154,8 @@ class ModalRoute: transform : solprop.translate.modal.Transform Synthesis and projection, of kind ``"mode_averaged"`` or ``"modal"``. tdse : TDSESource or None, optional - The TDSE response, the reference's alone; ``None`` without one. + The TDSE response, executed by the reference and the native CPU build; + ``None`` without one. Raises ------ diff --git a/src/solprop/translate/run_request.py b/src/solprop/translate/run_request.py index 5aafa4c2d..6316d6722 100644 --- a/src/solprop/translate/run_request.py +++ b/src/solprop/translate/run_request.py @@ -293,7 +293,7 @@ def stepper(self) -> StepperSettings: # numpydoc ignore=RT01 into :class:`~solprop.stepper.settings.StepperSettings` for the code that reads them together: the march drivers, the request-aware checks (:func:`solprop.translate.problem.validate_run`) and the run's configuration - record, whose hash they enter exactly as before. + record, whose hash they enter. The record, built once per request. diff --git a/src/solprop/translate/spatial.py b/src/solprop/translate/spatial.py index df7a63c02..068075243 100644 --- a/src/solprop/translate/spatial.py +++ b/src/solprop/translate/spatial.py @@ -338,16 +338,17 @@ class SeparableOperator: ``beta_p = omega n_eff,p / c`` is the mode's own complex propagation constant (the wall term under the mode's loss policy). Column ``c`` belongs to channel ``c % n_channels`` (the channel index fastest). Zero at inactive - frequencies. ``None`` (the default) for every other kind, which leaves the - operator exactly as before. + frequencies. ``None`` (the default) for every other kind, which adds no wall + term to the operator. kperp_rate : numpy.ndarray or None Kernel schema 31: the transverse-wavevector power absorption rate ``alpha_perp`` of a run's safety ramp (SEP 40), in m^-1, one per column, shape ``(n_modes,)``, finite and nonnegative. It enters the operator on the active band only, beside the spectral rate, ``D -= alpha_perp / 2`` (SEP 22 section 5.3), and never the unitary phase. - ``None`` (the default) is stored as zeros, whose operator is today's to the - last bit. On the hybrid planar kind it acts per ``(p, k_y)`` column (SEP 40). + ``None`` (the default) is stored as zeros, which leave every element of the + operator bitwise unchanged. On the hybrid planar kind it acts per ``(p, k_y)`` + column (SEP 40). user_rate : numpy.ndarray or None The user's share of `spectral_rate`, in m^-1, shape ``(n_omega,)``; only ``absorbed_power`` reads it, since the operator takes the total. ``None`` (the @@ -672,8 +673,8 @@ def separable_values( root, propagating, attenuation = longitudinal_root(coefficients, columns) transverse_rate = _kperp_rate(coefficients, columns)[:, None] # The transverse rate joins the field attenuation inside the active factor (SEP - # 22, Q6), so an inactive bin's operator is today's whatever the collar; a zero - # rate leaves every element as it was, signed zeros included: -a - 0 = -a. + # 22, Q6), so an inactive bin's operator does not depend on the collar; a zero + # rate leaves every element bitwise unchanged, signed zeros included: -a - 0 = -a. operator = ( (-attenuation - 0.5 * transverse_rate) - 1j * (np.real(root) - coefficients.frame) @@ -976,10 +977,11 @@ def aperture_tables( Raises ------ OutputError - For a radial or planar-hybrid geometry or none at all; and on a line, for an - aperture whose centre is off ``y = 0``, a half-plane bounded in y or an ellipse, - which have no meaning uniform in y, or a region whose ``kappa_y`` interval - excludes zero, which would select nothing. + For a radial or planar-hybrid geometry or none at all. + ProcessingError + On a line, for an aperture whose centre is off ``y = 0``, a half-plane bounded + in y or an ellipse, which have no meaning uniform in y, or a region whose + ``kappa_y`` interval excludes zero, which would select nothing. """ if not set(spec.names) & set(FAR_FIELD_STATISTICS): return None diff --git a/src/solprop/translate/stage.py b/src/solprop/translate/stage.py index 9a2241f0a..1ffbc1920 100644 --- a/src/solprop/translate/stage.py +++ b/src/solprop/translate/stage.py @@ -95,7 +95,7 @@ class StageTerms: def device_ready(self) -> bool: # numpydoc ignore=RT01 """Whether both quantities are a weighted sum of fixed arrays. - True when neither member is ``None``. + True when `separable` is set, or when neither `phi` nor `prefactor` is ``None``. """ return self.separable is not None or ( self.phi is not None and self.prefactor is not None @@ -785,12 +785,6 @@ def require_device_ready(problem: PropagationProblem, name: str) -> None: solprop.exceptions.BackendError If either quantity is a z table, naming which, its size and the backends that run it. - - Examples - -------- - >>> from solprop.translate.stage import require_device_ready - >>> require_device_ready.__name__ - 'require_device_ready' """ if problem.device_ready: return diff --git a/src/solprop/translate/tdse.py b/src/solprop/translate/tdse.py index eecdfd64e..b03cb87f4 100644 --- a/src/solprop/translate/tdse.py +++ b/src/solprop/translate/tdse.py @@ -82,6 +82,9 @@ TDSEPurpose = Literal["startup", "predictor", "corrected", "diagnostic"] """The relation of an evaluated field to the optical integration or diagnostics.""" _PURPOSES = ("startup", "predictor", "corrected", "diagnostic") +_MEMO_SIZE = 16 +"""Configurations each per-configuration memo keeps: a run reads one, and a long scan +or a front-end session must not keep a gate array for every configuration it met.""" def refine_response_grid(grid: TimeGrid, sampling: TDSESampling) -> FieldGrid: @@ -408,7 +411,7 @@ def _hacc_setup() -> dict[str, object]: } -@functools.cache +@functools.lru_cache(maxsize=_MEMO_SIZE) def _window_from_json(encoded: str) -> AtomicWindowRecord | None: """Parse a descriptor's resolved atomic window once per configuration. @@ -791,7 +794,7 @@ def _setup_fields(model: TDSEModel, setup: Mapping[str, object]) -> _SetupScalar return _SetupScalars(0, 0, str(setup["growing"]), 1e-3, None, False) -@functools.cache +@functools.lru_cache(maxsize=_MEMO_SIZE) def _cached_response(encoded: str) -> TDSEGasResponse: """Rebuild a descriptor's response once per configuration.""" return _response_from_json(encoded) @@ -809,7 +812,7 @@ def _breakpoints_from_json(encoded: str) -> tuple[float, float, float, float]: return (collar.zero_low, collar.one_low, collar.one_high, collar.zero_high) -@functools.cache +@functools.lru_cache(maxsize=_MEMO_SIZE) def _gate_derivative_from_json( encoded: str, *, error: bool = False ) -> Float[np.ndarray, " n_to"]: @@ -825,7 +828,7 @@ def _gate_derivative_from_json( return hold(derivative) -@functools.cache +@functools.lru_cache(maxsize=_MEMO_SIZE) def _gate_from_json(encoded: str) -> Float[np.ndarray, " n_to"] | None: """Evaluate a descriptor's window gate once per configuration. diff --git a/src/solprop/translate/tdse_source.py b/src/solprop/translate/tdse_source.py index 92d2b2975..786cc9c46 100644 --- a/src/solprop/translate/tdse_source.py +++ b/src/solprop/translate/tdse_source.py @@ -284,7 +284,8 @@ def steady_current_certificate( ) -@functools.cache +# Bounded as the descriptor's own memos are: one configuration per run. +@functools.lru_cache(maxsize=16) def _steady_current_certificate( descriptor: TDSEDescriptor, omega: bytes, active: bytes ) -> float: diff --git a/src/solprop/translate/transverse.py b/src/solprop/translate/transverse.py index d9452bcd2..ea09e0e6f 100644 --- a/src/solprop/translate/transverse.py +++ b/src/solprop/translate/transverse.py @@ -205,7 +205,7 @@ def _intermediate_return( # noqa: PLR0917 - the design and its weights SEP 40 section 4.4: content between the protected band and the ramp is absorbed at the edge only to ``Gamma(kappa)``; its return is ``exp(-2 Gamma)`` with the exact symbol per frequency, weighted by the launch's spectrum. The band is taken in - sixteen contiguous groups of bins, each at its power-weighted wavenumber. + at most 128 contiguous groups of bins, each at its power-weighted wavenumber. - ``axes``: the grid's axes. - ``kappa_p``: the protected band's edge per axis. diff --git a/src/solprop/translate/validation.py b/src/solprop/translate/validation.py index 629c02e21..dcc9a2c5e 100644 --- a/src/solprop/translate/validation.py +++ b/src/solprop/translate/validation.py @@ -2,7 +2,7 @@ # # SPDX-License-Identifier: GPL-3.0-or-later -"""What translation refuses, and what it warns about, before a problem is returned. +"""The route policy translation refuses or warns on before a problem is returned. The policy :func:`solprop.translate.assembly.assemble` applies to its arguments and to the problem it assembled: the refusals of a route's settings (a wall off the capillary @@ -14,7 +14,10 @@ :meth:`solprop.translate.problem.PropagationProblem.validate` and :func:`solprop.translate.problem.validate_run`, which also refuses dense observation where its interpolant is not the run's field, so a request changed after assembly is -refused there too. +refused there too. The checks that the arguments agree with one another (the state's +layout with the mode set, a spatial grid with its medium, the save planes' range) stay +inline in :func:`~solprop.translate.assembly.assemble` and the builders it calls, +beside the code that reads them. """ import math @@ -75,21 +78,35 @@ ] -_INPUT_NOISE_ADMITTED = ( - "The 'input' model is admitted: its draw is part of the entrance state, in the " - "channel basis, which is orthonormal in true power on every coupled-flow route, " - "and the flow propagates it like any field" -) -"""The clause every coupled-flow refusal of the modified noise model ends with. - -SEP 37 section 6. The input draw is one photon per channel and bin only in a basis -orthonormal in true power. The capillary's ``HE_1m`` set (and the vector wall's -``TE_0m``/``TM_0m`` families) are real Bessel profiles, orthogonal on the core and -each normalised to its own power by -:meth:`solprop.modes.capillary.MarcatiliMode.normalisation`. A general modal guide's -basis is gated by :func:`solprop.translate.general.check_noise_basis` before any flow -is built, at the entrance of a moving guide as everywhere else. -""" +def _refuse_modified_noise( + noise_model: str | None, flow: str, remedy: str = "" +) -> None: + """Refuse the 'modified' noise model beside the coupled flow `flow` names. + + - ``flow``: the flow, as the message's subject ("a split block's coupled flow"). + - ``remedy``: a route's own way out, a sentence, put before the input model's. + + SEP 37 section 6. The modified model's draw is kept apart from the field and + advanced by the unitary phase of a diagonal flow; its transport through a coupled + flow is not measured. The input draw is one photon per channel and bin only in a + basis orthonormal in true power. The capillary's ``HE_1m`` set (and the vector + wall's ``TE_0m``/``TM_0m`` families) are real Bessel profiles, orthogonal on the + core and each normalised to its own power by + :meth:`solprop.modes.capillary.MarcatiliMode.normalisation`. A general modal + guide's basis is gated by :func:`solprop.translate.general.check_noise_basis` + before any flow is built, at the entrance of a moving guide as everywhere else. + """ + if noise_model != "modified": + return + msg = ( + f"{flow} refuses the 'modified' noise model: its draw is transported by the " + "unitary phase of a diagonal flow, and its transport through a coupled flow " + f"is not measured in this package. {remedy}{' ' if remedy else ''}The 'input' " + "model is admitted: its draw is part of the entrance state, in the channel " + "basis, which is orthonormal in true power on every coupled-flow route, and " + "the flow propagates it like any field" + ) + raise TranslationError(msg) @dataclass(frozen=True) @@ -259,12 +276,6 @@ def validate_coupled_flow( solprop.exceptions.SolpropWarning Naming the step that exceeds the limit, with the term, the section, the frequency, ``K``, the conditioning factor and the limit. - - Examples - -------- - >>> from solprop.translate.validation import validate_coupled_flow - >>> validate_coupled_flow.__name__ - 'validate_coupled_flow' """ flow = problem.linear.coupled_flow if flow is None: @@ -351,12 +362,11 @@ def _refuse_a_wall_off_the_capillary_route( ) -> None: """Refuse a coherent wall declared beside a route that cannot carry it. - The **first** door of the route, before anything is assembled, because it is the - one a wall silently fell through: :func:`assemble` reads ``wall`` only in its - modal branch, so a general modal or spatial run carrying one used to translate - with ``linear.coupled_flow`` absent, no ``modal.flow`` key on its record and no - word said. The other two doors are the mode set's - (:func:`solprop.modes.wall.wall_operator`) and the backend's. + The **first** door of the route, before anything is assembled: :func:`assemble` + reads ``wall`` only in its modal branch, so without this check a general modal or + spatial run carrying one would translate with ``linear.coupled_flow`` absent, no + ``modal.flow`` key on its record and no word said. The other two doors are the + mode set's (:func:`solprop.modes.wall.wall_operator`) and the backend's. """ if wall is not None and not taper_coupling: msg = ( diff --git a/src/solprop/translate/walls.py b/src/solprop/translate/walls.py index e4b678e49..1c557ac01 100644 --- a/src/solprop/translate/walls.py +++ b/src/solprop/translate/walls.py @@ -55,10 +55,10 @@ with_power_weight, ) from solprop.translate.validation import ( - _INPUT_NOISE_ADMITTED, DEFAULT_FLOW_CONDITION_LIMIT, TAPER_FLOW_CERTIFICATE, _Assembly, + _refuse_modified_noise, ) __all__: list[str] = [] @@ -511,15 +511,12 @@ def _check_taper_route(build: _Assembly, grid: TimeGrid) -> None: "taper_coupling=False for the adiabatic route" ) raise TranslationError(msg) - if build.noise_model == "modified": - msg = ( - "the taper coupling of a multimode capillary refuses the 'modified' " - "noise model: its draw is transported by the unitary phase of a " - "diagonal flow, and its transport through a coupled flow is not " - "measured in this package. Pass taper_coupling=False for the adiabatic " - "route, whose diagonal flow carries the draw. " + _INPUT_NOISE_ADMITTED - ) - raise TranslationError(msg) + _refuse_modified_noise( + build.noise_model, + "the taper coupling of a multimode capillary", + "Pass taper_coupling=False for the adiabatic route, whose diagonal flow " + "carries the draw.", + ) def _taper_generator_at( @@ -906,14 +903,7 @@ def _check_wall_route(build: _Assembly) -> None: "are channels of the mode set, one component each" ) raise TranslationError(msg) - if build.noise_model == "modified": - msg = ( - "a coherent wall block refuses the 'modified' noise model: its draw is " - "transported by the unitary phase of a diagonal flow, and the transport " - "of a draw through a nonunitary coupled flow is not measured in this " - "package. " + _INPUT_NOISE_ADMITTED - ) - raise TranslationError(msg) + _refuse_modified_noise(build.noise_model, "a coherent wall block") def _check_wall_total( diff --git a/src/solprop/transverse_monitor.py b/src/solprop/transverse_monitor.py index 35b363a1e..3f504bd2f 100644 --- a/src/solprop/transverse_monitor.py +++ b/src/solprop/transverse_monitor.py @@ -1302,8 +1302,8 @@ def step(self, current: float, z: float) -> None: def next_read(self) -> float: # numpydoc ignore=RT01 """Where the edge is next read, m; infinite when nothing is read. - A backend that marches without the host, as the native Adams march does, - holds its steps to it as :meth:`ceiling` does and hands the state back there. + No solprop code reads it: the native session holds its steps to its own edge's + value, and this is the reference that value is tested against. """ return self._next diff --git a/tests/backend_corpus_cases.py b/tests/backend_corpus_cases.py index 76e38bb42..9e2b1985d 100644 --- a/tests/backend_corpus_cases.py +++ b/tests/backend_corpus_cases.py @@ -53,7 +53,7 @@ from solprop.modes import PlanarGrid, SlabMode from solprop.monitor import CHECKS, BoundaryCheck from solprop.nonlinear.responses import KerrResponse -from solprop.output.hdf5 import open_file, resume +from solprop.output.hdf5 import open_file, read_resume_state from solprop.output.records import HISTORY_FIELDS from solprop.output.store import PlaneStore from solprop.physdata import gamma3 @@ -636,7 +636,7 @@ def _resumed( with open_file(path) as handle: arrays["resumed/field"] = np.asarray(handle["field"][-1:]) arrays["resumed/z"] = np.asarray(handle["z"]) - outcome = resume(path).outcome + outcome = read_resume_state(path).outcome assert outcome is not None return { "monitor": _monitor(outcome.execution), diff --git a/tests/backends/adams_source_cases.py b/tests/backends/adams_source_cases.py index 1feb4fcea..71dd18cbd 100644 --- a/tests/backends/adams_source_cases.py +++ b/tests/backends/adams_source_cases.py @@ -6,7 +6,8 @@ Shared by ``test_compiled_multistep.py`` and the catalogue's march rows (``backends/ladder_rows.py``): a helium capillary on the analytic field (no harmonic) -and on the envelope with its plasma, its launch reaching into the temporal collar; one +and an argon one on the envelope with its plasma, which ionises at this launch, each +launch reaching into the temporal collar; one evaluation of the source a step from the anchor (:func:`one_evaluation`), and a matched run of fixed steps at the method's top order (:func:`matched_run`). """ @@ -25,9 +26,12 @@ ROUTES = { "analytic field": {"thg": False, "plasma": False}, - "envelope plasma": {"envelope": True, "plasma": True}, + "envelope plasma": {"envelope": True, "plasma": True, "gas": "Ar"}, } -"""The stage pipeline's two other column families, for one evaluation of the source.""" +"""The stage pipeline's two other column families, for one evaluation of the source. + +Each is the capillary's settings, and its gas where not helium: argon for the envelope +plasma, which helium would leave without a free electron at this launch.""" SOURCE_STEPS = 8 @@ -41,7 +45,7 @@ def source_case(route, length, **settings): - """Return `route`'s helium capillary of `length` and its edged launch. + """Return `route`'s capillary of `length` and its edged launch. The window's own grid, whose collar is the original evaluation's. The launch is the pulse plus half of it rolled two fifths of the window along, which reaches into the @@ -56,10 +60,12 @@ def source_case(route, length, **settings): # A run ends at its grid's length (SEP 51): the grid is cut at the run's length, # with the collar the centimetre window gave. grid = grid_at(window, length) + route = dict(route) + gas = route.pop("gas", "He") simulation = Simulation.from_capillary( 150e-6, length, - "He", + gas, 1.0, wavelength=800e-9, fwhm=10e-15, diff --git a/tests/backends/adams_traces.py b/tests/backends/adams_traces.py index 751f88fee..ce4688030 100644 --- a/tests/backends/adams_traces.py +++ b/tests/backends/adams_traces.py @@ -515,7 +515,6 @@ def adams_march(self, method: Multistep) -> HostAdamsMarch: interpolate=stepper.interpolate_planes, shape=(1, 1, 1), proposal=self.scenario.proposal, - lag=1, name=self.name, ) march.state.z = self.scenario.z0 diff --git a/tests/backends/column_rows.py b/tests/backends/column_rows.py index 4c764b438..780cc2b6e 100644 --- a/tests/backends/column_rows.py +++ b/tests/backends/column_rows.py @@ -4,10 +4,9 @@ """SEP 43's retired column tests: their rows of the case catalogue. -**What is compared.** The compiled CPU backend's kernel tests (``test_numba_cpu.py``, -``test_numba_cpu_kernels.py`` and ``test_numba_band_kernels.py``), retired with that -backend in SEP 43, held its columns to the reference on inputs of their own. Native took -over their claims against ``numpy_ref`` on the same inputs, and they are these rows: +**What is compared.** The kernel tests of the compiled CPU backend retired in SEP 43 +held its columns to the reference on inputs of their own. Native holds their claims +against ``numpy_ref`` on the same inputs in these rows: - the ionising capillary (:func:`ionising_capillary`): argon in a pressure gradient, a thousandth pre-ionised and ionising hard, two fixed Dormand-Prince steps; diff --git a/tests/backends/driver_rows.py b/tests/backends/driver_rows.py index 58cd8c0f5..c35a8cbab 100644 --- a/tests/backends/driver_rows.py +++ b/tests/backends/driver_rows.py @@ -16,8 +16,8 @@ ``prop_gnlse``, ten fixed steps at the Adams method's fixed top order (``tests/entry_point_cases.py``); the last saved plane (``last_plane``), from the native instance of ``tests/driver/test_coherent_capillary.py``'s - ``test_the_prop_entry_points_are_what_they_were``, which keeps each run's record and - native's repeat of its own run; + ``test_the_prop_entry_points_match_their_recorded_final_states``, which keeps each + run's record and native's repeat of its own run; - ``rk replay ...`` rows: the GNLSE and coherent-wall capillary routes of ``capability_routes.ROUTES`` replaying 400 uniform steps on the Runge-Kutta march (``tests/rk_route_cases.py``); every saved plane (``run``), from diff --git a/tests/backends/flow_rows.py b/tests/backends/flow_rows.py index f8eaa578c..df62ffa72 100644 --- a/tests/backends/flow_rows.py +++ b/tests/backends/flow_rows.py @@ -37,8 +37,7 @@ taper coupling whose ``auto`` runs ``test_native_coupled_flow.py`` and ``test_taper_coupling.py`` keep (``scalar wall driver``, ``taper coupling driver``); and the kinked taper through the entry point, its plane and physical energy - (``moving guide entry point``, from the deleted - ``tests/driver/test_native_moving_entry.py``). + (``moving guide entry point``). **The bounds are the old tests', fixed before native runs.** A ``flow marches`` row is bounded by ``flow_parity.ten_step_bound`` (``B_10``): the declared conditioning ``C`` @@ -124,7 +123,6 @@ # Noise-free launches into time windows kept tight for speed: the boundary monitor # warns (SEP 21), and the window's edge is not what these rows hold. "ignore::solprop.exceptions.BoundaryWarning", - "ignore::solprop.exceptions.HostMarchWarning", ) """The warning filters of the old modules, which every row's run needs.""" diff --git a/tests/backends/free_rows.py b/tests/backends/free_rows.py index 8fe7b4dab..9e048b619 100644 --- a/tests/backends/free_rows.py +++ b/tests/backends/free_rows.py @@ -20,7 +20,7 @@ - the Cartesian plane carrying SEP 40's safety ramp over ten steps (:func:`ramped_case`, once ``test_kperp_collar.py``'s); - the radial collar's in-stage term beside a temporal rate ramped across the samples - (:func:`ramped_rate_case`, once ``test_radial_absorber_ramp.py``'s). + (:func:`ramped_rate_case`). A ladder compares one nonlinear evaluation (``derivative``), the statistics the session observes at the launch (``launch``, each statistic one by one), one step over diff --git a/tests/backends/general_rows.py b/tests/backends/general_rows.py index 1fb66eac7..f93c813ad 100644 --- a/tests/backends/general_rows.py +++ b/tests/backends/general_rows.py @@ -10,9 +10,8 @@ block and a graded-index guide of two LP modes, each launched with random phases in every channel and scaled to a nonlinear scale ``Phi = 0.5`` over the millimetre: -- ``source``: one evaluation of the whole stage source at the launch (from - ``test_native_general_source_bound.py``); -- ``steps``: the field after the case's ten fixed Runge-Kutta steps (the same module); +- ``source``: one evaluation of the whole stage source at the launch; +- ``steps``: the field after the case's ten fixed Runge-Kutta steps; - the pair under the split temporal collar, launched with content outside the active band, on either march (from ``test_native_general_split.py``, which keeps the out-of-band bins' exact zeros on both backends); @@ -331,6 +330,25 @@ def switch(problem: PropagationProblem) -> PropagationProblem: return switch +def without_delayed(problem: PropagationProblem) -> PropagationProblem: + """Return the problem whose regions' delayed (Raman) tensor is zero. + + The instantaneous Kerr term is kept, so a guard built on this switch measures the + Raman term's share alone rather than the whole source's. + """ + regional = problem.responses.regional_responses + assert regional is not None + delayed = np.zeros_like(regional.delayed_tensor) + delayed.setflags(write=False) + return dataclasses.replace( + problem, + responses=dataclasses.replace( + problem.responses, + regional_responses=dataclasses.replace(regional, delayed_tensor=delayed), + ), + ) + + def without_regional_cubic(problem: PropagationProblem) -> PropagationProblem: """Return the problem whose regions' third-order susceptibility is zero. @@ -409,7 +427,11 @@ def rows() -> tuple[Row, ...]: "one-stage count times the projected sum's measured conditioning, and its " "ten-step carry at the launch's nonlinear scale.", build=partial(case, name), - switch_off=without_source(name), + # The Raman case's guard drops its delayed term alone: dropping the whole + # source would let its Kerr term satisfy the guard by itself. Measured on + # numpy_ref, Raman alone moves the source and the ten steps by 9.4e11 and + # 3.0e11 bounds. + switch_off=without_delayed if name == "raman" else without_source(name), rungs={ "source": one_stage(name), "steps": ten_steps(name), diff --git a/tests/backends/geometry_rows.py b/tests/backends/geometry_rows.py index 73f3f9a22..fbeceba96 100644 --- a/tests/backends/geometry_rows.py +++ b/tests/backends/geometry_rows.py @@ -15,8 +15,7 @@ ``test_envelope_plasma_geometries.py``); - the two-channel mixture (``mixture_cases.py``) on the radial and Cartesian routes, with and without the Kerr term's harmonic, one and two polarisations: the field after - eight fixed steps and every mixture statistic, at the launch and at the end (from - ``test_spatial_mixture_channels.py``); + eight fixed steps and every mixture statistic, at the launch and at the end; - the two channels' final fractions and peak rates at a radial launch of 3.6e10 V/m (``native_mixture_launch_probe.py``), on the real and the analytic column: ``launch`` (from ``test_native_mixture_fractions.py``, which held native to the passes on the @@ -614,7 +613,9 @@ def the_leaf_is_pathological(built: Built) -> bool: leaves.assert_the_leaf_is_pathological(leaf) if leaf.kappa_sq is not None and built.run_request.stepper.integrator is None: operator = leaves.separable_values(leaf)[0] - assert not np.allclose(operator[0], operator[1]) + assert not np.allclose( + operator[0], operator[1], atol=1e-5 * np.max(np.abs(operator)) + ) return True diff --git a/tests/backends/host_cases_envelope_propagation.py b/tests/backends/host_cases_envelope_propagation.py index 83660a72a..733353335 100644 --- a/tests/backends/host_cases_envelope_propagation.py +++ b/tests/backends/host_cases_envelope_propagation.py @@ -9,7 +9,6 @@ import numpy as np from backends.host_cases_envelope_qualification import InstantaneousPolynomial -from envelope_oracle_angular import order_record from sessions.runs import run as session_run from sessions.runs import summary as run_summary from solprop.backends.numpy_ref import NumpyRefBackend @@ -120,65 +119,6 @@ def propagate_pair( } -def refinement_record(rows, reference, expected_order): - """Keep an independent numerical floor beside every propagation order study.""" - floor = ( - 128 - * max(one["n_to"] for one in reference["models"].values()) - * np.finfo(float).eps - ) - return { - "levels": rows, - "reference": reference, - "fraction_orders": { - kind: order_record( - [ - abs( - one["models"][kind]["final_fraction"] - - reference["models"][kind]["final_fraction"] - ) - / reference["models"][kind]["final_fraction"] - for one in rows - ], - expected_order, - floor, - ) - for kind in ("field", "envelope") - }, - } - - -def propagation_studies(): - return { - "mixture_temporal_levels": [mixture_propagation(value) for value in (4, 8, 16)], - "model_comparisons": [ - propagate_pair(cycles, depletion, ratio) - for cycles in (2, 8) - for depletion in (1e-3, 0.05, 0.5) - for ratio in (0.0, 0.35, 1.0) - ], - "temporal_refinement": [ - refinement_record( - [ - propagate_pair(2, 0.05, ratio, oversampling=value) - for value in (4, 8, 16) - ], - propagate_pair(2, 0.05, ratio, oversampling=32), - 2, - ) - for ratio in (0.0, 0.35, 1.0) - ], - "step_refinement": [ - refinement_record( - [propagate_pair(2, 0.05, ratio, steps=value) for value in (2, 4, 8)], - propagate_pair(2, 0.05, ratio, steps=16), - 5, - ) - for ratio in (0.0, 0.35, 1.0) - ], - } - - def mixture_propagation(oversampling, *, backend_class=NumpyRefBackend): """Compare two independently depleting species through complete propagation.""" fill = Mixture.fill({"Ar": 0.3, "He": 0.7}, 1.0) diff --git a/tests/backends/ladder_rows.py b/tests/backends/ladder_rows.py index 331636d26..f35bfb96a 100644 --- a/tests/backends/ladder_rows.py +++ b/tests/backends/ladder_rows.py @@ -11,10 +11,11 @@ their readings into the backend equivalence record (:func:`ladder_record`); - the soliton's eight steps with the propagators tabulated and with them recomputed (from ``test_numpy_ref_backend.py``); -- the Adams march's source on the analytic field and on the envelope with its plasma: - one evaluation a step from the anchor at the launch (``source``), and eight fixed - steps at the method's top order (``steps``) (from ``test_compiled_multistep.py``, - which keeps the propagator and the run's source contribution); +- the Adams march's source on a helium capillary's analytic field and on an argon + capillary's envelope with its plasma, which ionises there: one evaluation a step + from the anchor at the launch (``source``), and eight fixed steps at the method's + top order (``steps``) (from ``test_compiled_multistep.py``, which keeps the + propagator and the run's source contribution); - SEP 35's carrier frame on a hydrogen window and on its gradient, replayed on the reference's own accepted steps at a fixed order (from ``test_carrier_frame.py``); - the vector Raman tensor on modal routes: a mode whose polarisation direction depends @@ -34,8 +35,10 @@ the rows make, now strict. **The guard.** Each row's term is switched off on the translated problem: the Kerr -term (``optmat_rows.without_kerr``), every response (``planar_rows.without_responses``, -which keeps the temporal collar) or the Raman rows (``optmat_rows.without_raman``). +term (``optmat_rows.without_kerr``), every response of a case that holds one +(``planar_rows.without_responses``, which keeps the temporal collar), the plasma's +density (``optmat_rows.without_plasma``) or the Raman rows +(``optmat_rows.without_raman``). Each guarded rung's reference must then move by more than ``parity_ladder.DETECTION`` (a thousand) of its bounds. @@ -76,7 +79,7 @@ from backends.carrier_frame_cases import WINDOW, capillary, gradient, matched_window from backends.conftest import BETA2, GAMMA, GNLSE_SETTINGS, WAVELENGTH, soliton_field from backends.host_cases_envelope_plasma import geometry_options -from backends.optmat_rows import without_kerr, without_raman +from backends.optmat_rows import without_kerr, without_plasma, without_raman from backends.planar_rows import without_responses from bounds import EPS, fft_bound, ladder_bound, record_backend from convergence_records import record @@ -331,6 +334,20 @@ def _soliton_rows() -> tuple[Row, ...]: return (*ladder, *modes) +ADAMS_TERMS = { + "analytic field": ("kerr", without_responses), + "envelope plasma": ("envelope plasma", without_plasma), +} +"""Each Adams source route's response axis and the switch-off of the term it claims: +the analytic field holds Kerr alone, the envelope its plasma beside Kerr.""" + +ADAMS_SHARES = { + "analytic field": "1.1e-5", + "envelope plasma": "3.1e-4, its plasma by 5.5e-8 (6e4 bounds),", +} +"""How far each route's source moves its matched run's field, relative to it.""" + + def _adams_rows() -> tuple[Row, ...]: """Return the Adams march's source rows and its carrier-frame windows.""" sources = tuple( @@ -343,7 +360,7 @@ def _adams_rows() -> tuple[Row, ...]: if route == "envelope plasma" else "capillary (mode-averaged)", stepper="adams", - response="kerr, plasma" if route == "envelope plasma" else "kerr", + response=ADAMS_TERMS[route][0], features=f"{route}, launch into the temporal collar, one evaluation " "a millimetre from the anchor", why=f"On the {route} column family the Adams march's untransported " @@ -355,7 +372,7 @@ def _adams_rows() -> tuple[Row, ...]: # The envelope plasma's one evaluation takes 1.6 s, the analytic # field's 0.1 s (measured). medium=route == "envelope plasma", - switch_off=without_responses, + switch_off=ADAMS_TERMS[route][1], rungs={"source": one_transform}, source_z=SOURCE_AT, ), @@ -365,14 +382,15 @@ def _adams_rows() -> tuple[Row, ...]: if route == "envelope plasma" else "capillary (mode-averaged)", stepper="adams", - response="kerr, plasma" if route == "envelope plasma" else "kerr", + response=ADAMS_TERMS[route][0], features=f"{route}, {SOURCE_STEPS} fixed steps at the top order", why=f"On the {route} column family the Adams march's eight fixed steps " "at its top order are the reference's.", bound_note="512 eps a step relative to the field, the matched-window " - "bound. The source moves the field by 1.1e-5 of it over the run.", + f"bound. The source moves the field by {ADAMS_SHARES[route]} of it " + "over the run.", build=partial(matched_run, route), - switch_off=without_responses, + switch_off=ADAMS_TERMS[route][1], rungs={"steps": matched_steps}, ), ) diff --git a/tests/backends/low_storage_cases.py b/tests/backends/low_storage_cases.py index d095c1bde..0763403bf 100644 --- a/tests/backends/low_storage_cases.py +++ b/tests/backends/low_storage_cases.py @@ -18,10 +18,9 @@ import numpy as np -from bounds import EPS, assert_within, departure, step_budget +from bounds import EPS, step_budget from legacy_geometry import with_collar_rate from sessions.runs import run -from solprop.backends.numpy_ref import NumpyRefBackend from solprop.backends.session import ExecutionOptions, Start from solprop.boundaries import absorber from solprop.driver import Simulation @@ -192,52 +191,6 @@ def replay( backend.close() -def assert_compiled( - backend_class, problem, run_request, grid, limit, *, what="march", **replaying -): - """Replay on the reference and `backend_class`; assert it within `limit`. - - Returns the departure measured. - """ - expected = replay(NumpyRefBackend, problem, run_request, grid, **replaying) - got = replay(backend_class, problem, run_request, grid, **replaying) - assert_within( - got, expected, limit, what=f"{backend_class.name} against numpy_ref, {what}" - ) - return departure(got, expected) - - -def assert_parity( - backend_class, - problem, - run_request, - grid, - *, - modes=None, - noise=None, - options=None, - **bound, -): - """Replay on both backends and assert the states within :func:`parity_bound`. - - `options` are both backends' execution options, an exact node chunk among them. - """ - limit = parity_bound(problem, run_request, **bound) - return ( - assert_compiled( - backend_class, - problem, - run_request, - grid, - limit, - modes=modes, - noise=noise, - options=options, - ), - limit, - ) - - def uniform(length, steps=STEPS, **planes): """Return a uniform schedule of `steps` steps over `length`.""" return FixedSchedule.uniform(0.0, length, length / steps * 1.0000001, **planes) diff --git a/tests/backends/planar_rows.py b/tests/backends/planar_rows.py index c650e08bc..0da097f19 100644 --- a/tests/backends/planar_rows.py +++ b/tests/backends/planar_rows.py @@ -17,7 +17,8 @@ plasma, Raman, and the y collar in both schemes). ``derivative``: one nonlinear evaluation at the launch; ``launch``: the spatial (and plasma) statistics the session observes at the launch; ``one_step``: one step over the whole plate; ``steps``: ten - steps over it, with every statistic at their end; + steps over it, with every statistic at their end; the envelope plasma plate also + over two steps of the Adams method (``steps``); - the hybrid cases (``planar_cases.py``): the hybrid families launched as a Gaussian in y on an argon- or nitrogen-filled 127 um gap, the analytic-signal field family and the collar alone, on Runge-Kutta and on the Adams method pinned to its top order @@ -47,8 +48,9 @@ run takes the plates' bound over its 10 cm. **The guard.** Each row's term is switched off on the translated problem: every -response (:func:`without_responses`) or the plasma's density -(``optmat_rows.without_plasma``), the y collar (:func:`without_collar`), the safety ramp +response (:func:`without_responses`) where the case holds one, otherwise the plasma's +density (``optmat_rows.without_plasma``) or the Raman rows +(``optmat_rows.without_raman``), the y collar (:func:`without_collar`), the safety ramp (:func:`without_ramp`), or the slab channels' own transverse term in the linear flow (:func:`without_slab_term`). Each guarded rung's reference must then move by more than ``parity_ladder.DETECTION`` (a thousand) of that rung's bounds. These replace the old @@ -57,7 +59,9 @@ thousand bounds, and the safety ramp moving native by one bound. The statistics at the launch read the launch itself, which no term has touched, so a ``launch`` rung is unguarded; at the launch a collar plate's y collar reads only the beam's wings, so its -``derivative`` rung is unguarded too (:data:`COLLAR_AT_THE_LAUNCH`). +``derivative`` rung is unguarded too (:data:`COLLAR_AT_THE_LAUNCH`). The hybrid +envelope plasma frees no electron at its launch, so its rows are declared vacuous +(:data:`HYBRID_VACUOUS`); the plates hold the envelope plasma on both marches. **How to read a row.** Every row is a :func:`planar_row` call, for example:: @@ -94,7 +98,7 @@ from backends import planar_cases from backends import planar_plate_cases as plates -from backends.optmat_rows import without_plasma +from backends.optmat_rows import without_plasma, without_raman from backends.planar_hybrid_cases import FAMILIES from bounds import gamma, step_evaluations from parity_ladder import Built, Row, Statistic @@ -200,6 +204,7 @@ def has_a_ramp(problem: PropagationProblem) -> bool: SWITCH_OFFS: dict[str, Callable[[PropagationProblem], PropagationProblem]] = { "responses": without_responses, "plasma": without_plasma, + "raman": without_raman, "collar": without_collar, } """Each guard's switch-off, by the term it removes.""" @@ -326,6 +331,13 @@ def held_after_ten_steps( """The plates whose ten-step row is slow by cost, and why.""" +def plate_adams_built(family: str, steps: int) -> Built: + """Return a plate family on `steps` uniform steps of the fixed-order Adams march.""" + grid, space, problem, run_request = _plate(family) + request = on_march(plates.with_steps(run_request, steps), "adams") + return Built(problem, request, grid, options=plates.chunked(space)) + + def plate_rows() -> list[Row]: """Return the plates' rows: one step with the launch, and ten steps.""" rows = [] @@ -368,6 +380,23 @@ def plate_rows() -> list[Row]: slow=SLOW_BY_COST.get(family, ""), ), ] + features, response, subject, term = PLATES["envelope_plasma"] + rows.append( + planar_row( + name="plate envelope_plasma adams two steps", + stepper="adams", + response=response, + features=f"plates, {features}, fixed-order Adams", + why=f"On the plates {subject} is the reference's over two steps of the " + "Adams method at its top order.", + bound_note="The plates' two-step bound, which counts Runge-Kutta's seven " + "evaluations a step, more than the Adams method makes. Measured 7.8e-14 " + "against 1.0e-11; the plasma moves the reference by 5e7 bounds.", + build=partial(plate_adams_built, "envelope_plasma", 2), + switch_off=SWITCH_OFFS[term], + rungs={"steps": partial(plate_bound, "envelope_plasma", 2)}, + ) + ) return rows @@ -509,12 +538,12 @@ def hybrid_bound(name: str, march: str, steps: int | None, built: Built) -> floa "the hybrid Kerr gap with its collar split off", "collar", ), - "raman": ("raman", "hybrid, nitrogen", "the hybrid Raman gap", "responses"), + "raman": ("raman", "hybrid, nitrogen", "the hybrid Raman gap", "raman"), "field-plasma": ( "plasma", "hybrid, field grid", "the hybrid field plasma", - "responses", + "plasma", ), "field-kerr": ( "kerr", @@ -526,7 +555,7 @@ def hybrid_bound(name: str, march: str, steps: int | None, built: Built) -> floa "envelope plasma", "hybrid, envelope grid", "the hybrid envelope plasma", - "responses", + "plasma", ), "collar-only": ( "none", @@ -537,6 +566,16 @@ def hybrid_bound(name: str, march: str, steps: int | None, built: Built) -> floa } """Each hybrid case's axes, its claim's subject and the term its guard removes.""" +HYBRID_VACUOUS = { + "envelope-plasma": "The hybrid envelope plasma frees no electron at this 0.5 J/m " + "launch: switching it off moves the reference by 3.9e-4 and 2.4e-4 bounds (one " + "step and two on Runge-Kutta) and 4.3e-5 and 2.5e-5 (on Adams), measured. The rows " + "are kept as a case each march must carry; the Kerr term moves them by 1e7 bounds " + "or more, and the plates hold the live envelope plasma on both marches.", +} +"""The hybrid cases whose term reaches none of the row's rungs, with what was +measured.""" + def hybrid_rows() -> list[Row]: """Return the hybrid cases' rows: one step and their run, on either march.""" @@ -559,6 +598,7 @@ def hybrid_rows() -> list[Row]: "one_step": partial(hybrid_bound, name, march, 1), "steps": partial(hybrid_bound, name, march, None), }, + vacuous=HYBRID_VACUOUS.get(name, ""), ) ) return rows diff --git a/tests/backends/session_rows.py b/tests/backends/session_rows.py index 4023bf1a2..2a3bbf394 100644 --- a/tests/backends/session_rows.py +++ b/tests/backends/session_rows.py @@ -11,7 +11,8 @@ - **the low-storage RK4IP march** (SEP 24 section 7.2, ``low storage ...`` rows): the mode-averaged soliton, plain and under the modified noise, in both propagator modes; the modal route with no response, or the in-stage collar alone; a nitrogen gradient - capillary with Raman and plasma (a varying operator); a dispersion declared along + capillary with Raman and plasma (a varying operator); an argon capillary's envelope + with its plasma; a dispersion declared along z, which takes the operator's z table; the radial route with its in-stage collar; the general modal route; a Cartesian Kerr beam in every flow treatment, with and without the collars and the noise; a recomputed flow beside a small loss; the line; @@ -80,6 +81,7 @@ import numpy as np +from backends.adams_source_cases import ROUTES, source_case from backends.conftest import ( BETA2, DISPERSION_LENGTH, @@ -223,6 +225,31 @@ def varying(mode: str) -> Built: return Built(problem, run_request, simulation.grid, modes=simulation.modes) +def envelope_plasma_capillary(steps: int = 2) -> Built: + """Return the Adams rows' argon envelope-plasma capillary on low-storage steps. + + ``adams_source_cases``' case, whose plasma ionises and whose launch reaches into + the temporal collar, over `steps` steps of 5 um, inside the in-stage collar's + stability limit. + """ + length = steps * 5e-6 + schedule = FixedSchedule.uniform(0.0, length, 5e-6) + simulation, problem, lab = source_case( + ROUTES["envelope plasma"], length, schedule=schedule + ) + problem = dataclasses.replace( + problem, initial=dataclasses.replace(problem.initial, field0=lab) + ) + problem, run_request = marched(problem, simulation.run_request(), schedule) + return Built( + problem, + run_request, + simulation.grid, + modes=simulation.modes, + simulation=simulation, + ) + + def tabled_fibre(mode: str) -> Built: """Return a fibre whose dispersion is declared along z, a millimetre in ten steps. @@ -1061,6 +1088,21 @@ def _modal_rows() -> tuple[Row, ...]: ) for mode in MODES ), + # The reference's envelope-plasma cycle moments dominate: about 10 s. + session_row( + name="low storage capillary envelope plasma", + route="capillary (envelope)", + stepper="low storage", + response="envelope plasma", + features="argon, launch into the temporal collar, two steps", + why="The low-storage march carries an argon capillary's envelope with its " + "plasma, which ionises, as the reference does.", + bound_note="The parity bound with the plasma's prefix over n_to. Measured " + "4.5e-17 against 7.4e-13; the plasma moves the reference by 1.9e4 bounds.", + build=envelope_plasma_capillary, + switch_off=without_plasma, + rungs={"steps": parity(sums=True)}, + ), *( session_row( name=f"low storage z table operator {mode}", diff --git a/tests/backends/test_adams_resume_ledgers.py b/tests/backends/test_adams_resume_ledgers.py index 1aa21c125..c69114522 100644 --- a/tests/backends/test_adams_resume_ledgers.py +++ b/tests/backends/test_adams_resume_ledgers.py @@ -17,7 +17,7 @@ from solprop.backends.sessions import start_session from solprop.driver import Simulation from solprop.exceptions import BackendError, ResponseBudgetError -from solprop.output import resume +from solprop.output import read_resume_state from solprop.stepper.multistep import Multistep @@ -47,7 +47,7 @@ def test_saved_adams_resume_preserves_exhausted_call_budget(backend_name, tmp_pa path = tmp_path / "stopped.h5" with pytest.raises(ResponseBudgetError, match="budget of 4"): simulation.run(path, progress="none") - stopped = resume(path) + stopped = read_resume_state(path) assert stopped.outcome is not None assert stopped.outcome.status == "budget_exhausted" assert CallLedger.from_record(stopped.outcome.logical_calls).total == 4 @@ -55,7 +55,7 @@ def test_saved_adams_resume_preserves_exhausted_call_budget(backend_name, tmp_pa assert 0.0 < stopped.plane.z < 1e-5 with pytest.raises(ResponseBudgetError, match="budget of 4"): simulation.run(path, resume=True, progress="none") - again = resume(path) + again = read_resume_state(path) assert again.outcome is not None assert again.outcome.logical_calls == stopped.outcome.logical_calls assert again.plane.z == stopped.plane.z diff --git a/tests/backends/test_adams_traces.py b/tests/backends/test_adams_traces.py index ddfc1c4ea..8b3802f31 100644 --- a/tests/backends/test_adams_traces.py +++ b/tests/backends/test_adams_traces.py @@ -21,8 +21,8 @@ from typing import Any import pytest -from tests.backends.adams_traces import Scenario, run_scenario +from backends.adams_traces import Scenario, run_scenario from solprop.stepper.multistep import Multistep STATE = ( diff --git a/tests/backends/test_backend_protocol.py b/tests/backends/test_backend_protocol.py index dc933c3cc..8695428d3 100644 --- a/tests/backends/test_backend_protocol.py +++ b/tests/backends/test_backend_protocol.py @@ -409,9 +409,6 @@ def metadata(self) -> dict[str, object]: def memory_ledger(self): return {"state": 64} - def available_device_memory(self): - return None - def close(self): return None @@ -421,7 +418,6 @@ def test_a_minimal_backend_satisfies_the_protocol(): assert isinstance(backend, Backend) assert backend.edge_memory(None) == 0 assert backend.memory_ledger() == {"state": 64} - assert backend.available_device_memory() is None assert backend.metadata()["backend"] == "stub" assert backend.close() is None diff --git a/tests/backends/test_carrier_frame.py b/tests/backends/test_carrier_frame.py index 99bca2499..e026a9022 100644 --- a/tests/backends/test_carrier_frame.py +++ b/tests/backends/test_carrier_frame.py @@ -318,15 +318,6 @@ def test_a_backend_refuses_what_it_does_not_deliver(): refuse_carrier_frame(problem, stepper, "a backend") -@pytest.mark.parametrize("backend_name", sorted(COMPILED)) -def test_a_compiled_cpu_backend_accepts_the_shift(backend_name): - for method in (OFF, SCALAR): - built = capillary(method) - COMPILED[backend_name]( - built.translate(), built.run_request(), grid=built.grid, modes=built.modes - ).close() - - # --- the reference rule (section 6.1) ------------------------------------------------- @@ -1179,9 +1170,9 @@ def test_a_compiled_backend_interpolates_planes_as_the_reference_does(backend_na expected = march(simulation) found = march(simulation, backend_class=COMPILED[backend_name]) assert found.ledger is not None and found.ledger.dense_observations > 0 - assert np.array_equal(found.steps, expected.steps) or len(found.steps) == len( - expected.steps - ) + # The same number of accepted steps, which the planes' rounding budget below + # counts; the positions may differ by rounding, so they are not compared (SEP 25). + assert len(found.steps) == len(expected.steps) for one, other in zip(found.fields, expected.fields, strict=True): assert_within( one, other, len(expected.steps) * 512 * EPS, what=f"{backend_name} plane" diff --git a/tests/backends/test_compiled_multistep.py b/tests/backends/test_compiled_multistep.py index 7fd6bc24f..83716656f 100644 --- a/tests/backends/test_compiled_multistep.py +++ b/tests/backends/test_compiled_multistep.py @@ -2,13 +2,12 @@ # # SPDX-License-Identifier: GPL-3.0-or-later -"""SEP 14 phase 2: the Adams march on the compiled backends, against the reference. +"""SEP 14 phase 2: the Adams march on the compiled backend, against the reference. -The march is shared (``solprop.backends.numpy_ref.multistep``); only the one source -evaluation and the propagator differ: Kokkos evaluates through its general engine's -stage pipeline. Parity is the reference's trajectory to round-off: the same steps, -orders and calls, and fields that agree to the accumulated rounding of the evaluation -orders. +Native runs its own compiled Adams march, evaluating the source through its general +engine's stage pipeline. Parity is the reference's trajectory to round-off: the same +steps, orders and calls, and fields that agree to the accumulated rounding of the +evaluation orders. """ import dataclasses @@ -185,10 +184,11 @@ def test_native_marches_a_problem_without_responses( SOURCE_SHARE_BOUND = 1e-10 """The matched runs' source contributions' departure, relative to the reference's. -Measured 5.4e-12 (analytic field) and 7.5e-12 (envelope plasma) on native. The floor is -the fields' own rounding over the source's share of them (1.1e-5): an eps of the field -is 2e-11 of the source, and the linear runs alone part by 2e-17 to 5e-17 of their -field. 1e-10 is about five eps of the field, 13 times the worst measured. +Measured 3.0e-12 (analytic field) and 1.9e-13 (envelope plasma) on native. The floor is +the fields' own rounding over the source's share of them (1.1e-5 on helium's analytic +field, 3.1e-4 on argon's envelope): an eps of the field is 2e-11 of the smaller source, +and the linear runs alone part by 2e-17 to 5e-17 of their field. 1e-10 is about five +eps of that field, 33 times the worst measured. """ @@ -244,18 +244,21 @@ def assert_sources_the_reference(backend_class, route): """Assert `backend_class`'s Adams march sources a column family as the reference. The Adams source through the stage pipeline's two other column families: the - analytic signal of a field without THG, and the envelope with its plasma assembly, - at a launch that reaches into the temporal collar. The propagator is compared as - before SEP 47 (:func:`assert_propagates_as_the_reference`); then the march's use of - the source: both backends replay :data:`SOURCE_STEPS` fixed steps at the method's - top order through their sessions, the same discrete method and history - (``backends/matched.py``), so they part by rounding alone. Each backend's source - contribution is its run's field less its own run of the launch scaled to the linear - limit (``faint``), where the source's share falls a millionfold; the two + analytic signal of a field without THG, on helium, and the envelope with its plasma + assembly, on argon, which ionises; each launch reaches into the temporal collar. + The propagator is compared as before SEP 47 + (:func:`assert_propagates_as_the_reference`); then the march's use of the source: + both backends replay :data:`SOURCE_STEPS` fixed steps at the method's top order + through their sessions, the same discrete method and history + (``backends/matched.py``), so they part by rounding alone. Each backend's + source contribution is its run's field less its own run of the launch scaled to the + linear limit (``faint``), where the source's share falls a millionfold; the two contributions are held to :data:`SOURCE_SHARE_BOUND` of the reference's. The source - moves the field by 1.1e-5 of it over the run, seven decades above the fields' - matched-window bound (512 eps a step); the fields themselves are the catalogue's - row ``ladder adams matched run ...``. + moves the field by 1.1e-5 of it over the run on the analytic field and 3.1e-4 on the + envelope, seven decades and more above the fields' matched-window bound (512 eps a + step); the envelope plasma is 2e-4 of its source's contribution, so a backend that + dropped it would miss the bound by a millionfold. The fields themselves are the + catalogue's row ``ladder adams matched run ...``. """ assert_propagates_as_the_reference(backend_class, route) built = matched_run(route) diff --git a/tests/backends/test_dense_output.py b/tests/backends/test_dense_output.py index f0ae46d45..cc4133db7 100644 --- a/tests/backends/test_dense_output.py +++ b/tests/backends/test_dense_output.py @@ -22,14 +22,13 @@ from solprop.backends import available from solprop.backends.numpy_ref import NumpyRefBackend from solprop.backends.registry import select -from solprop.driver.resume import _interpolated from solprop.driver.simulation import Simulation from solprop.exceptions import DriverError, OutputError, TranslationError from solprop.grid import EnvelopeGrid from solprop.log import NullReporter from solprop.noise import modified_noise from solprop.output import MemoryOutput -from solprop.output.hdf5 import open_file, resume +from solprop.output.hdf5 import open_file, read_resume_state from solprop.output.metadata import INTERPOLATED_RESUMES_ANNOTATION, _example_metadata from solprop.output.records import StepLimits, StepperRecord from solprop.output.store import PlaneStore @@ -351,14 +350,14 @@ def test_a_stopped_interpolated_resume_records_its_position(tmp_path): dense = {"backend": "numpy_ref", "integrator": RungeKutta(), "n_save": 6} with pytest.raises(StopError): capillary(interpolate_planes=True, **dense).run(path, progress=Stop()) - first = resume(path) - assert _interpolated(first) + first = read_resume_state(path) + assert first.interpolated with pytest.raises(StopError): capillary(interpolate_planes=True, **dense).run( path, resume="interpolated", progress=Stop() ) - second = resume(path) - assert _interpolated(second) + second = read_resume_state(path) + assert second.interpolated assert second.n_saved > first.n_saved with open_file(path) as stored: assert stored.annotations[INTERPOLATED_RESUMES_ANNOTATION] == [first.plane.z] @@ -396,8 +395,8 @@ def test_an_interpolated_plane_is_resumed_only_on_request(tmp_path, dense): path = tmp_path / "dense.h5" with pytest.raises(StopError): capillary(backend="numpy_ref", **dense).run(path, progress=Stop()) - state = resume(path) - assert _interpolated(state) + state = read_resume_state(path) + assert state.interpolated with pytest.raises(DriverError, match="resume='interpolated'"): capillary(backend="numpy_ref", **dense).run(path, resume=True) # A run asking for no interpolation is another run, which the hash refuses. @@ -410,9 +409,9 @@ def test_an_interpolated_plane_is_resumed_only_on_request(tmp_path, dense): assert isinstance(handler, PlaneStore) assert handler.annotations[INTERPOLATED_RESUMES_ANNOTATION] == [state.plane.z] # The run is complete and ends landed, so it resumes without the request. - finished = resume(path) + finished = read_resume_state(path) assert finished.n_saved == 4 - assert not _interpolated(finished) + assert not finished.interpolated capillary(backend="numpy_ref", **dense).run(path, resume=True, progress="none") diff --git a/tests/backends/test_dispersive_kerr_routes.py b/tests/backends/test_dispersive_kerr_routes.py index 5783e0370..3580ce9e2 100644 --- a/tests/backends/test_dispersive_kerr_routes.py +++ b/tests/backends/test_dispersive_kerr_routes.py @@ -4,10 +4,9 @@ """SEP 6's dispersive response on numpy_ref's free-space, planar and general routes. -Slice 1b of the SEP's phase 1: the Cartesian free-space pipeline (and the line grid -that shares it) and the hybrid planar pipeline evaluate ``responses.dispersive_kerr`` -node by node, and the general modal route evaluates a gas region's channels at the -nodes of that region. Per route: +The Cartesian free-space pipeline (and the line grid that shares it) and the hybrid +planar pipeline evaluate ``responses.dispersive_kerr`` node by node, and the general +modal route evaluates a gas region's channels at the nodes of that region. Per route: - one nonlinear evaluation, caught where the route calls it, equals the reference :meth:`~solprop.nonlinear.responses.DispersiveKerrResponse.evaluate` at a node, bit diff --git a/tests/backends/test_driver.py b/tests/backends/test_driver.py index ba8b15512..285429786 100644 --- a/tests/backends/test_driver.py +++ b/tests/backends/test_driver.py @@ -16,7 +16,6 @@ import dataclasses import io import logging -import sys import typing from typing import Any, cast @@ -360,7 +359,7 @@ def test_the_modified_noise_model_keeps_its_realisation_apart( made.workspace.noise_at(made.workspace.stage_scalars(0.0, LENGTH / 2)) ) # Dispersion yes, loss and gain no: the magnitude is untouched by the advance. - assert np.allclose(np.abs(advanced), np.abs(drawn)) + assert np.allclose(np.abs(advanced), np.abs(drawn), atol=0.0) assert not np.array_equal(advanced, drawn) assert present(made.workspace.noise_phase(0.0)).shape == problem.shape @@ -946,7 +945,6 @@ def test_the_bundles_a_compiled_backend_packs_are_frozen(): BACKEND_MEMBERS = ( - "available_device_memory", "close", "closed", "edge_memory", @@ -960,29 +958,6 @@ def test_the_bundles_a_compiled_backend_packs_are_frozen(): complete (SEP 52 section 5.1): its one attribute is ``name``. A change here changes the seam, in the same commit.""" -RETIRED_MEMBERS = ( - "attach_monitor", - "drain_attempts", - "halt_ahead", - "march_export_refusal", - "march_snapshot", - "march_snapshot_nbytes", - "observe", - "propagate_to", - "reads_transverse_edge", - "request_halt", - "restore_call_ledgers", - "restore_march", - "set_halt_check", - "set_initial", - "set_progress", - "set_stop", - "stats", -) -"""The members the seam dropped: the host stepping seam SEP 52 deleted, every run -being a session's, which schedules it and reads the state through the workspace, and -the answers every backend gave alike.""" - REFERENCE_ATTRIBUTES = ("name",) """The class attributes the NumPy reference backend sets.""" @@ -995,9 +970,6 @@ def test_the_backend_surface_the_reference_implements_is_frozen(): assert isinstance(NumpyRefBackend.__dict__["request"], property) for name in (*BACKEND_MEMBERS, *REFERENCE_ATTRIBUTES): assert hasattr(NumpyRefBackend, name), name - retired = [name for name in RETIRED_MEMBERS if hasattr(NumpyRefBackend, name)] - assert retired == [] - assert not hasattr(sys.modules["solprop.backends.protocol"], "HostStepping") def test_separable_operator_fields_are_frozen_with_the_driver_seam(): diff --git a/tests/backends/test_envelope_plasma_geometries.py b/tests/backends/test_envelope_plasma_geometries.py index 79c1f0acd..b0319dadc 100644 --- a/tests/backends/test_envelope_plasma_geometries.py +++ b/tests/backends/test_envelope_plasma_geometries.py @@ -161,7 +161,7 @@ def test_the_taper_case_meets_its_tolerance_on_both_backends( @pytest.mark.medium @pytest.mark.parametrize("geometry", ["modal", "radial", "free"]) @pytest.mark.parametrize("n_pol", [1, 2]) -def test_envelope_statistics_use_cycle_rates_on_all_host_geometries( +def test_the_last_periodic_row_is_the_saved_plane_s_scan_on_every_geometry( envelope_mixture, geometry, n_pol, equivalence_backend_class ): """Each backend's last periodic row is its saved plane's scan, within the budget. diff --git a/tests/backends/test_far_field_statistics.py b/tests/backends/test_far_field_statistics.py index 1a9445051..57230e131 100644 --- a/tests/backends/test_far_field_statistics.py +++ b/tests/backends/test_far_field_statistics.py @@ -5,9 +5,8 @@ """The far-field statistics in a run: the operator's two, the doors and the host path. SEP 23 section 7, items 8 (the axial flux) and 9 (the absorbed power) on -``numpy_ref``, the backend-level refusals of item 12, the solprop-side admission that -refuses the native backend until its native pass, the native statistics of a launch -beside the reference's, and the slots and bands every pass shares. +``numpy_ref``, the backend-level refusals of item 12, the native statistics of a +launch beside the reference's, and the slots and bands every pass shares. """ import dataclasses @@ -23,10 +22,8 @@ from builders import grid_at from legacy_geometry import bare_absorber from sessions.runs import launch_statistics -from solprop.backends import registry, select +from solprop.backends import select from solprop.backends import spatial as backend_spatial -from solprop.backends.registry import statistics_refusal -from solprop.backends.session import Start from solprop.backends.spatial import ( FarFieldLayout, FarFieldTables, @@ -38,10 +35,8 @@ from solprop.boundaries import SpatialAbsorber, absorber, custom_absorber from solprop.constants import EPS0, C from solprop.driver import Simulation, SimulationSettings -from solprop.driver.run import run_problem from solprop.exceptions import ( BackendError, - DriverError, OutputError, TranslationError, ) @@ -697,72 +692,6 @@ def test_radial_and_planar_geometry_are_refused_before_any_step(grid): select(name, problem, run_request, grid=planar_grid) -def test_an_older_native_build_is_refused_the_far_field_statistics_by_name( - grid, monkeypatch -): - native = pytest.importorskip("solprop_native") - space = FreeGrid(3e-4, 8, 3e-4, 8, collar_fraction=0.1) - simulation = free_simulation(grid, space, gaussian(60e-6)) - problem = simulation.translate() - run_request = simulation.run_request() - # A build that declares none of them, as every build before SEP 23's third phase: - # the refusal precedes the native build and names the backend that forms them. - monkeypatch.setattr(native.NativeBackend, "far_field_statistics", frozenset()) - with pytest.raises(BackendError, match="or run them on numpy_ref"): - select("native", problem, run_request, grid=grid) - assert statistics_refusal("native", ["energy"]) is None - assert statistics_refusal("numpy_ref", list(ALL_SIX)) is None - # A build that declares some of them is refused the others, by name. - monkeypatch.setattr( - native.NativeBackend, "far_field_statistics", frozenset({"beam_spectrum"}) - ) - refusal = statistics_refusal("native", ["beam_spectrum", "region_spectrum"]) - assert refusal is not None - assert "['region_spectrum']" in refusal - assert statistics_refusal("native", ["beam_spectrum"]) is None - monkeypatch.setattr(native.NativeBackend, "far_field_statistics", frozenset()) - - plain = free_simulation( - grid, space, gaussian(60e-6), spec=StatsSpec(names=("energy",)) - ) - problem = plain.translate() - owner = select("numpy_ref", problem, run_request, grid=grid) - try: - monkeypatch.setattr(owner, "name", "native") - # The run loop's door, for a spec handed to it rather than the problem's own. - with pytest.raises(DriverError, match="far-field statistics"): - run_problem( - problem, - owner, - MemoryOutput(), - start=Start.entrance(problem), - metadata=plain.metadata(), - stats_spec=far_spec(), - ) - finally: - owner.close() - - -def test_the_native_probe_reads_what_the_installed_build_declares(monkeypatch): - # Not installed: no refusal here, and selecting it reports the missing package. - monkeypatch.setattr(registry, "_native_installed", lambda: False) - assert statistics_refusal("native", ["beam_spectrum"]) is None - monkeypatch.undo() - assert statistics_refusal("numpy_ref", list(ALL_SIX)) is None - if importlib.util.find_spec("solprop_native") is None: - pytest.skip("solprop-native is not installed") - # The package is imported only after its availability check. - from solprop_native import ( # noqa: PLC0415 # pyright: ignore[reportMissingImports] - NativeBackend, - ) - - assert statistics_refusal("native", list(ALL_SIX)) is None - # A build that declares none is refused every one, naming numpy_ref. - monkeypatch.setattr(NativeBackend, "far_field_statistics", frozenset()) - refusal = statistics_refusal("native", list(ALL_SIX)) - assert refusal is not None and "numpy_ref" in refusal - - def test_the_host_pass_refuses_what_it_was_not_given(grid): space = FreeGrid(3e-4, 8, 3e-4, 8, collar_fraction=0.1) simulation = free_simulation(grid, space, gaussian(60e-6)) diff --git a/tests/backends/test_flux_paths.py b/tests/backends/test_flux_paths.py index c9bbc0d7c..2745f0dce 100644 --- a/tests/backends/test_flux_paths.py +++ b/tests/backends/test_flux_paths.py @@ -43,7 +43,10 @@ def _case( """Return a short linear radial run of a 3 nJ beam through `medium`. On the former grid and without a collar, as an undeclared absorber meant before - SEP 21: the subject is the flux through the path, which a collar would drain. + SEP 21: the subject is the flux through the path, which a collar would drain. 32 + radial nodes resolve the 60 um beam's angular spectrum (1.5e-11 of its peak at the + last k_r); on 16, where that is 1.8e-3, even vacuum loses 6e-6 of the energy over + the length. """ grid = EnvelopeGrid.from_limits( LENGTH, 800e-9, (600e-9, 1.2e-6), 150e-15, **LEGACY_GRID @@ -62,7 +65,7 @@ def _case( absorber=bare_absorber(grid), ) return Simulation.from_free( - grid, RadialGrid(6e-4, 16), medium, [], pulse, settings=settings, noise=None + grid, RadialGrid(6e-4, 32), medium, [], pulse, settings=settings, noise=None ) diff --git a/tests/backends/test_general_modal.py b/tests/backends/test_general_modal.py index f58bdf2a3..630878e1a 100644 --- a/tests/backends/test_general_modal.py +++ b/tests/backends/test_general_modal.py @@ -4,21 +4,16 @@ """The general modal route across the seam: its leaves, and its absence. -Kernel schema 12 adds four optional leaves and no behaviour: every route that exists -carries all four as ``None``, nothing new crosses the seam, and every backend refuses -each leaf by name until it executes that exact representation. +Every other route carries the four general modal leaves as ``None`` and puts nothing +of them across the seam, and every backend refuses a leaf beside a problem it does not +belong to by its dotted name. -The refusal is not the schema check in disguise. A backend compiled against schema 12 -accepts every schema-12 problem, so without these four checks a wheel would take a -problem carrying a representation it has no kernel for and silently run the old -physical model. - -The second half of this module is the route itself on ``numpy_ref``: the nonlinear +The second part of this module is the route itself on ``numpy_ref``: the nonlinear source of a general modal guide against the modal Kerr coefficient and against a separately written quadrature, its chunking, its ledger and every combination it -refuses. The translation layer's half -- the record, the -placeholders and the assembly's refusals -- is -``tests/translate/test_general_route.py``. +refuses. The last holds native's ten fixed steps of the route to the reference's. The +translation layer's half -- the record, the placeholders and the assembly's refusals -- +is ``tests/translate/test_general_route.py``. """ import copy diff --git a/tests/backends/test_held_plasma_contract.py b/tests/backends/test_held_plasma_contract.py index 65dd00f82..abd269ce5 100644 --- a/tests/backends/test_held_plasma_contract.py +++ b/tests/backends/test_held_plasma_contract.py @@ -8,8 +8,8 @@ import numpy as np import pytest -from tests.backends import test_numpy_ref_plasma as plasma_fixtures +from backends import test_numpy_ref_plasma as plasma_fixtures from solprop.backends.numpy_ref import NumpyRefBackend from solprop.driver.metadata import metadata_for from solprop.exceptions import TranslationError diff --git a/tests/backends/test_held_plasma_leading.py b/tests/backends/test_held_plasma_leading.py index e8a088add..3ed85774d 100644 --- a/tests/backends/test_held_plasma_leading.py +++ b/tests/backends/test_held_plasma_leading.py @@ -8,8 +8,8 @@ import numpy as np from scipy.integrate import quad, quad_vec -from tests.backends.test_held_plasma import EPS, grid_case +from backends.test_held_plasma import EPS, grid_case from solprop.backends.numpy_ref.passes.plasma import held_plasma_spectrum diff --git a/tests/backends/test_held_plasma_physics.py b/tests/backends/test_held_plasma_physics.py index 0b6090e4f..6707c5e9e 100644 --- a/tests/backends/test_held_plasma_physics.py +++ b/tests/backends/test_held_plasma_physics.py @@ -10,8 +10,8 @@ import pytest from scipy.integrate import quad_vec from scipy.special import erf -from tests.backends.test_held_plasma import EPS, grid_case, rounding_budget, source +from backends.test_held_plasma import EPS, grid_case, rounding_budget, source from solprop.translate.plasma_integration import design_running_integral diff --git a/tests/backends/test_held_plasma_routes.py b/tests/backends/test_held_plasma_routes.py index 7d225451a..0677c480e 100644 --- a/tests/backends/test_held_plasma_routes.py +++ b/tests/backends/test_held_plasma_routes.py @@ -8,10 +8,10 @@ import numpy as np import pytest -from tests.backends.plasma_column_cases import CASES, case, options_for -from tests.backends.test_radial_nonlinear import derivative -from tests.bounds import gamma +from backends.plasma_column_cases import CASES, case, options_for +from backends.test_radial_nonlinear import derivative +from bounds import gamma from solprop.backends.numpy_ref import NumpyRefBackend from solprop.backends.numpy_ref.passes.plasma import plasma_channels_current from solprop.backends.numpy_ref.passes.responses import nonlinear_polarisation diff --git a/tests/backends/test_host_marches.py b/tests/backends/test_host_marches.py index 9f2168f8d..14a559d11 100644 --- a/tests/backends/test_host_marches.py +++ b/tests/backends/test_host_marches.py @@ -168,7 +168,7 @@ def test_the_low_storage_march_reports_a_step_left_in_flight(): assert march.in_flight == (0.25, 0.25) assert march.refusal() == in_flight_refusal("numpy_ref", 0.25, 0.25) with pytest.raises(BackendError, match="abandoned in flight"): - march.replay_step(0.25, 0.5, 0.0) + march.replay_step(0.25, 0.5) # A load clears it, and the count is the loaded run's. march.load(0.0, 0.25, 0) assert march.in_flight is None diff --git a/tests/backends/test_monitor_owner.py b/tests/backends/test_monitor_owner.py index 20f16241d..d53a92251 100644 --- a/tests/backends/test_monitor_owner.py +++ b/tests/backends/test_monitor_owner.py @@ -403,21 +403,6 @@ def test_a_resume_without_a_record_starts_again(): pair.records() -def test_an_old_record_s_floor_removal_is_reconstructed(): - # A record from before the floor's removal and the signed removal were kept. - earlier = Pair(_python(split=False, quiet=False), can_rest=False) - _launch(earlier) - record = earlier.python.summary() - for name in ("floor_removed_fraction", "removed_signed", "quiet_checks"): - del record[name] - record["removed_fraction"] = 1e-9 - record["raw_removed_fraction"] = 3e-9 - pair = Pair(_python(split=False, quiet=False), can_rest=False) - pair.resume(record, plane=False) - _launch(pair) - pair.records() - - @pytest.mark.parametrize("split", [False, True]) def test_the_thresholds_and_their_neighbours_agree(split): # The warning and stop thresholds exactly and at the doubles beside them, warned diff --git a/tests/backends/test_multistep_march.py b/tests/backends/test_multistep_march.py index 9cd6ec722..6db741ae7 100644 --- a/tests/backends/test_multistep_march.py +++ b/tests/backends/test_multistep_march.py @@ -104,12 +104,13 @@ def solve(n, integrator, rtol=1e-2): reference = solve(1, None, rtol=1e-12) errors = [ np.linalg.norm(solve(n, method) - reference) / np.linalg.norm(reference) - for n in (20, 80) + for n in (20, 40, 80) ] - observed = math.log(errors[0] / errors[1]) / math.log(4) - # Three levels of the measurement: 2.0 for Richter's; the margin admits the - # irregular startup and landing steps. - assert observed > order - 0.6 + observed = [math.log2(errors[i] / errors[i + 1]) for i in range(2)] + # Three levels at Richter's order 2: measured 2.00 and 1.99, so the irregular + # startup and landing steps cost nothing visible and 0.3 below is margin; the + # upper gate rejects an order the method cannot have (testing.md section 1). + assert all(order - 0.3 < one < order + 3 for one in observed), observed def test_adams_is_the_exact_linear_flow_without_a_source(narrow_grid, linear_problem): diff --git a/tests/backends/test_native_edge_collar.py b/tests/backends/test_native_edge_collar.py index 751f53977..e871ed62a 100644 --- a/tests/backends/test_native_edge_collar.py +++ b/tests/backends/test_native_edge_collar.py @@ -41,7 +41,7 @@ from solprop.grid import LineGrid from solprop.log import NullReporter from solprop.noise import NoiseRealisation -from solprop.output.hdf5 import resume +from solprop.output.hdf5 import read_resume_state from solprop.stepper import ( FixedSchedule, LowStorageRungeKutta, @@ -486,7 +486,7 @@ def build() -> Simulation: flag = threading.Event() build().run(path, progress=_StopAtFirstPlane(flag), stop=flag) build().run(path, resume=True, progress="none") - resumed = resume(path).outcome + resumed = read_resume_state(path).outcome assert resumed is not None expected = whole.outcome.execution["boundary_monitor"]["transverse"] found = cast("Any", resumed).execution["boundary_monitor"]["transverse"] @@ -519,7 +519,7 @@ def build() -> Simulation: build().run(path, progress="none", stop=flag) whole = cast("Any", build().run(progress="none")) build().run(path, resume=True, progress="none") - resumed = resume(path).outcome + resumed = read_resume_state(path).outcome assert resumed is not None expected = whole.outcome.execution["boundary_monitor"]["transverse"] found = cast("Any", resumed).execution["boundary_monitor"]["transverse"] diff --git a/tests/backends/test_native_low_storage.py b/tests/backends/test_native_low_storage.py index 7092cf875..94405237b 100644 --- a/tests/backends/test_native_low_storage.py +++ b/tests/backends/test_native_low_storage.py @@ -119,9 +119,7 @@ def at_end(_session, batch): "propagators": field if mode == "tabulate" else 0, } assert low_storage_stage_register(problem, "native") == collar - assert low_storage_flows(problem, run_request.stepper, "native") == ( - mode == "tabulate" - ) + assert low_storage_flows(problem, run_request.stepper) == (mode == "tabulate") assert sum(volumes.values()) == field * (3 + int(collar) + (mode == "tabulate")) for row in (*RUNGE_KUTTA_ROWS, "noise", "adams_history"): assert ledger[row] == 0, row @@ -149,7 +147,7 @@ def test_a_varying_operator_holds_its_pair_tabulated_and_none_recomputed(): field = 16 * math.prod(problem.shape) ledger = backend.memory_ledger() assert ledger["propagators"] == held * field - assert low_storage_flows(problem, run_request.stepper, "native") == held + assert low_storage_flows(problem, run_request.stepper) == held # The modal route holds C: its input is a padded fine spectrum. assert ledger["register_stage"] == field assert all(ledger[row] == 0 for row in RUNGE_KUTTA_ROWS) diff --git a/tests/backends/test_native_march_admission.py b/tests/backends/test_native_march_admission.py index f89ef08ca..aa56f4111 100644 --- a/tests/backends/test_native_march_admission.py +++ b/tests/backends/test_native_march_admission.py @@ -12,7 +12,6 @@ import copy import dataclasses -import warnings import numpy as np import pytest @@ -20,7 +19,7 @@ from capability_routes import ROUTES from solprop.backends import available from solprop.driver import Simulation -from solprop.exceptions import BackendError, HostMarchWarning +from solprop.exceptions import BackendError from solprop.stepper.multistep import Multistep from solprop.stepper.schedule import FixedSchedule @@ -59,10 +58,8 @@ def on_route(route: str, integrator) -> Simulation: "radial", ], ) -def test_the_default_march_is_native_without_a_warning(route): - with warnings.catch_warnings(): - warnings.simplefilter("error", HostMarchWarning) - backend = built(on_route(route, Multistep())) +def test_the_default_march_is_native(route): + backend = built(on_route(route, Multistep())) try: assert backend.metadata()["adams_march"] == "native" finally: @@ -70,9 +67,7 @@ def test_the_default_march_is_native_without_a_warning(route): def test_the_fused_method_is_native(): - with warnings.catch_warnings(): - warnings.simplefilter("error", HostMarchWarning) - backend = built(on_route("gnlse", Multistep(formulation="interaction"))) + backend = built(on_route("gnlse", Multistep(formulation="interaction"))) try: assert backend.metadata()["adams_march"] == "native" finally: @@ -90,9 +85,7 @@ def test_a_replayed_schedule_is_native(): save_planes=np.asarray(stepper.save_planes).tolist(), ) simulation.settings = dataclasses.replace(simulation.settings, schedule=schedule) - with warnings.catch_warnings(): - warnings.simplefilter("error", HostMarchWarning) - backend = built(simulation) + backend = built(simulation) try: assert backend.metadata()["adams_march"] == "native" finally: @@ -132,9 +125,7 @@ def test_a_representation_the_stage_tables_do_not_read_is_refused_at_admission( "route", ["general guide (moving)", "capillary (coherent wall)", "radial"] ) def test_moving_maps_and_coupled_flows_are_native(route): - with warnings.catch_warnings(): - warnings.simplefilter("error", HostMarchWarning) - backend = built(on_route(route, Multistep())) + backend = built(on_route(route, Multistep())) try: assert backend.metadata()["adams_march"] == "native" finally: @@ -162,9 +153,7 @@ def test_the_carrier_frame_is_native(): from backends.carrier_frame_cases import capillary # noqa: PLC0415 from backends.test_carrier_frame import SCALAR # noqa: PLC0415 - a heavy module - with warnings.catch_warnings(): - warnings.simplefilter("error", HostMarchWarning) - backend = built(capillary(SCALAR)) + backend = built(capillary(SCALAR)) try: assert backend.metadata()["adams_march"] == "native" assert backend._adams._policy.carrier diff --git a/tests/backends/test_native_march_traces.py b/tests/backends/test_native_march_traces.py index ebfff27f4..6ac8cae88 100644 --- a/tests/backends/test_native_march_traces.py +++ b/tests/backends/test_native_march_traces.py @@ -24,13 +24,13 @@ import numpy as np import pytest -from tests.backends.adams_traces import ( + +from backends.adams_traces import ( Scenario, _HostHarness, _march_state, run_scenario, ) - from solprop.backends import available from solprop.exceptions import BackendError, ConvergenceError, ResponseBudgetError from solprop.log import NullReporter @@ -44,7 +44,7 @@ native = pytest.importorskip("solprop_native") _testing = pytest.importorskip("solprop_native._core")._testing -from tests.backends.native_trace_marches import TraceAdamsMarch # noqa: E402 +from backends.native_trace_marches import TraceAdamsMarch # noqa: E402 CORPUS = Path(__file__).parents[1] / "data" / "adams_traces.json.gz" diff --git a/tests/backends/test_native_planar_statistics.py b/tests/backends/test_native_planar_statistics.py index 4af83c4bb..ef2ed703f 100644 --- a/tests/backends/test_native_planar_statistics.py +++ b/tests/backends/test_native_planar_statistics.py @@ -104,13 +104,15 @@ def run(backend_class, problem, run_request, grid, length): def test_each_statistic_is_the_reference_s_on_the_same_state(name): """Every spatial statistic, and each plasma one, at the reference's final state. - The field statistics are one shared host function on both backends - (:func:`solprop.backends.spatial.collect_spatial`, synthesising the node volume - itself), so they agree to that function's own reductions, the Cartesian statistics' - ``gamma``. The plasma statistics are native's columns against the reference's passes - on nodes that differ by one evaluation's rounding; each is bounded by its own - measured response to a one-ulp launch perturbation (the largest of three random-sign - draws) times that rounding in ulps, plus ``gamma(n_to)`` for either side's own scan. + Each backend forms the field statistics itself: the reference through + :func:`solprop.backends.spatial.collect_spatial`, which synthesises the node volume, + native from its own columns and nodes by the geometry's rules. Both are reductions + over the same columns, nodes and time samples, so they agree within either side's + reduction bound, the Cartesian statistics' ``gamma``. The plasma statistics are + native's columns against the reference's passes on nodes that differ by one + evaluation's rounding; each is bounded by its own measured response to a one-ulp + launch perturbation (the largest of three random-sign draws) times that rounding in + ulps, plus ``gamma(n_to)`` for either side's own scan. """ grid, space, problem, run_request = planar_case(name) plasma = name in PLASMA_CASES diff --git a/tests/backends/test_native_rk_admission.py b/tests/backends/test_native_rk_admission.py index 7d5383411..a0310fb58 100644 --- a/tests/backends/test_native_rk_admission.py +++ b/tests/backends/test_native_rk_admission.py @@ -20,7 +20,6 @@ from sessions.runs import run from solprop.backends import available from solprop.backends.events import Outcome -from solprop.exceptions import HostMarchWarning from solprop.stepper.runge_kutta import RungeKutta pytestmark = pytest.mark.skipif( @@ -68,13 +67,12 @@ def launched(route: str, **settings): *((route, True) for route in ROUTES_NATIVE if route not in FLOWS), ], ) -def test_the_default_loop_is_native_without_a_warning(route, dense): - """The backend's session steps the whole run natively, warning of no host march.""" +def test_the_default_loop_is_native(route, dense): + """The backend's session steps the whole run natively.""" backend, problem, run_request = launched(route, interpolate_planes=dense) try: with warnings.catch_warnings(): warnings.simplefilter("ignore") - warnings.simplefilter("error", HostMarchWarning) landed = run(backend, problem, run_request) assert landed.terminal.outcome is Outcome.COMPLETED assert committed_steps(landed) > 0 diff --git a/tests/backends/test_native_rk_traces.py b/tests/backends/test_native_rk_traces.py index 70ad7a21a..d2aa709ca 100644 --- a/tests/backends/test_native_rk_traces.py +++ b/tests/backends/test_native_rk_traces.py @@ -25,9 +25,9 @@ import numpy as np import pytest -from tests.backends.native_trace_marches import TraceRungeKuttaMarch -from tests.backends.rk_traces import Scenario, _HostHarness, same_trace +from backends.native_trace_marches import TraceRungeKuttaMarch +from backends.rk_traces import Scenario, _HostHarness, same_trace from solprop.backends import available from solprop.backends.records import RungeKuttaPolicy from solprop.exceptions import BackendError, ConvergenceError diff --git a/tests/backends/test_numpy_ref_backend.py b/tests/backends/test_numpy_ref_backend.py index 21a2aaaae..6fc4acb26 100644 --- a/tests/backends/test_numpy_ref_backend.py +++ b/tests/backends/test_numpy_ref_backend.py @@ -628,7 +628,11 @@ def test_the_two_propagator_modes_agree(soliton_problem, soliton_grid): def test_the_envelope_third_harmonic_term_is_executed( backend_class, thg_problem, thg_grid ): - """The one compiled Kerr path nothing else exercises; the carrier is built here.""" + """The harmonic switch reaches the run's Kerr term and leaves the pump's peak. + + How much harmonic the term radiates is held against the weak-conversion estimate on + both backends (``tests/driver/test_envelope_harmonic.py``). + """ with_harmonic, with_harmonic_request = thg_problem(thg=True) without, without_request = thg_problem(thg=False) assert with_harmonic.responses.kerr_coefficients.harmonic_factor == 0.25 @@ -638,7 +642,7 @@ def test_the_envelope_third_harmonic_term_is_executed( difference = np.max(np.abs(first.field - second.field)) assert difference > 0.0 # The harmonic is radiated near 3 omega_0, far outside the band the fundamental - # occupies, so it must show up above the pump's own bins there and nowhere else. + # occupies, so the pump's peak stays where it was. assert np.max(np.abs(first.field)) == pytest.approx( np.max(np.abs(second.field)), rel=1e-3 ) @@ -693,7 +697,7 @@ def test_the_alarm_is_weighted_at_the_stage_it_was_scored_from( # which lands on the plane rather than sitting at the entrance. assert stage_z == pytest.approx(0.1, abs=1e-12) weight = prefactor_at(problem.responses, stage_z) - assert not np.allclose(weight, prefactor_at(problem.responses, 0.0)) + assert not np.allclose(weight, prefactor_at(problem.responses, 0.0), atol=0.0) backend.close() diff --git a/tests/backends/test_numpy_ref_multimode.py b/tests/backends/test_numpy_ref_multimode.py index e07419829..e82bd5e3d 100644 --- a/tests/backends/test_numpy_ref_multimode.py +++ b/tests/backends/test_numpy_ref_multimode.py @@ -19,7 +19,10 @@ import numpy as np import pytest +from bounds import assert_within +from builders import load_reference from convergence_records import Column, Study, record +from march_bounds import evaluation_rounding from sessions.executors import IDENTITY from sessions.runs import launch_statistics, launched, run from solprop import fourier @@ -34,6 +37,7 @@ from solprop.grid import FieldGrid from solprop.modes import MarcatiliMode, ModeCollection, transverse_quadrature from solprop.nonlinear.responses import KerrResponse +from solprop.profiles import Linear from solprop.pulses import GaussianPulse from solprop.stats import StatsSpec, analytic_field from solprop.stepper import FixedSchedule, PIController @@ -314,6 +318,54 @@ def drift_at(energy): assert strong < 1e-7 +# ------------------------------------------------------------------------ a taper + + +def test_a_taper_s_source_at_z_is_the_local_radius_s_source(grid): + """A tapered capillary's source at ``z`` is a straight one's of radius ``a(z)``. + + The reference synthesises the fields on the entrance's quadrature times the taper + factor and projects back divided by it: the Bessel modes are self-similar in the + radius, so that is the straight capillary's own pipeline on its own nodes, scaled. + One evaluation each, on the reference alone (native's taper is held to this by the + parity catalogue's taper rows), for the same internal modal state. + """ + taper = Linear(125e-6, 75e-6, LENGTH) + z = 0.75 * LENGTH + + def built(radius): + modes = [ + MarcatiliMode(radius, "He", 1.0, m=m, cladding=1.45, loss_scale=0.0) + for m in (1, 2) + ] + rule = transverse_quadrature(modes, n_r=CONVERGED_N_R_SET) + # Steps short enough for the taper's mode coupling, which would warn at the + # module's default; the source evaluated here does not depend on them. + problem, run_request = build( + grid, modes, pulse(grid, 2), quadrature=rule, dz_max=LENGTH / 16 + ) + return NumpyRefBackend(problem, run_request, grid=grid, modes=modes), rule + + tapered, rule = built(taper) + straight, _ = built(float(taper(np.array([z]))[0])) + try: + state = load_reference(straight) + taper_scale = tapered.workspace.problem.transform.taper_scale + assert taper_scale is not None + scale = float(taper_scale(z)) + expected = straight.workspace.lab_source(state, 0.0) + found = tapered.workspace.lab_source(state, z) + finally: + tapered.close() + straight.close() + # Both sides' rounding of one evaluation, on the same nodes up to the radius. + # Measured 9.0e-16 of the source. A projection that applied the factor the wrong + # way round would be off by its square less one, 1.04 here. + bound = evaluation_rounding(grid.n_to, rule.n_nodes, 2) + assert scale**2 - 1.0 > 1e6 * bound + assert_within(found, expected, bound, what="tapered source") + + # ----------------------------------------------------------------------- node chunks diff --git a/tests/backends/test_numpy_ref_p2.py b/tests/backends/test_numpy_ref_p2.py index 170fc3857..2aa6d7e1f 100644 --- a/tests/backends/test_numpy_ref_p2.py +++ b/tests/backends/test_numpy_ref_p2.py @@ -255,7 +255,7 @@ def test_the_parameters_are_the_ones_the_design_note_records(): * np.exp(-smooth_loss_integral(probe)) / dispersion ) - assert np.allclose(ratio, 1.0) + assert np.allclose(ratio, 1.0, atol=0.0) # And alpha, whose integral the reference uses, is the one that was written down. step = 1e-6 numerical = ( diff --git a/tests/backends/test_numpy_ref_plasma.py b/tests/backends/test_numpy_ref_plasma.py index a5004e2bc..a0ffe099f 100644 --- a/tests/backends/test_numpy_ref_plasma.py +++ b/tests/backends/test_numpy_ref_plasma.py @@ -64,7 +64,7 @@ from solprop.stepper import PIController from solprop.translate.assembly import assemble from solprop.translate.ionisation import build_rate_table -from solprop.translate.linop import delta_phi, profile_table +from solprop.translate.linop import profile_table from solprop.translate.responses import ( PlasmaCoefficients, prefactor_at, @@ -401,25 +401,6 @@ def test_the_pre_ionisation_is_read_at_the_plane(ionising_capillary): assert replaced.preionisation == pytest.approx(0.4, rel=1e-14) -def test_a_plasma_run_steps_and_ionises(backend_class, ionising_capillary, field_grid): - """A propagation that actually frees electrons, end to end.""" - problem, run_request, _, _ = ionising_capillary() - plane = run( - backend_class(problem, run_request, grid=field_grid), - problem, - run_request, - owns=True, - until=0.1, - ).final - assert plane.z == 0.1 - assert plane.summary.met_tolerance - assert np.all(np.isfinite(plane.field)) - # The plasma blue-shifts the pulse, so the spectrum must not be the linear one. - linear = np.exp(delta_phi(problem.linear, 0.0, 0.1)) * problem.initial.field0 - moved = np.max(np.abs(plane.field - linear)) / np.max(np.abs(linear)) - assert moved > 1e-3 - - # ------------------------------------------------------------------------- refusals diff --git a/tests/backends/test_numpy_ref_raman.py b/tests/backends/test_numpy_ref_raman.py index 7d36a5ce9..e904ffcaa 100644 --- a/tests/backends/test_numpy_ref_raman.py +++ b/tests/backends/test_numpy_ref_raman.py @@ -785,16 +785,18 @@ def first_moment_of_silica(): return float(np.trapezoid(delays * shape, dx=dt) / np.trapezoid(shape, dx=dt)) -def test_the_soliton_self_frequency_shift_matches_gordons_rate( - selected_backend_name, -): +@pytest.mark.medium +def test_the_soliton_self_frequency_shift_matches_gordons_rate(backend_name): """A fundamental soliton red-shifts at ``-8 |beta2| T_R / (15 T0^4)``. Gordon's rate, from first-order perturbation theory with the delayed response linearised about zero frequency, so it holds for a soliton long enough that the Raman gain is linear across its bandwidth. Measured against it here at 800 fs, where the pulse has covered 1.1 dispersion lengths and the shift is 1.8e-4 of its own - bandwidth: the centroid is what resolves it, not the spectrum's shape. + bandwidth: the centroid is what resolves it, not the spectrum's shape. On each + backend, so that the reference's Raman term answers to the closed form and not only + to native's agreement with it. Medium: sixty metres of fibre, about 2 s on the + reference. """ tau0, length = 800e-15, 60.0 peak = abs(SSFS_BETA2) / (SSFS_GAMMA * tau0**2) @@ -814,7 +816,7 @@ def test_the_soliton_self_frequency_shift_matches_gordons_rate( n_save=3, rtol=1e-9, atol=1e-22, - backend=selected_backend_name, + backend=backend_name, noise=None, ) z = handler["z"] @@ -830,7 +832,7 @@ def test_the_soliton_self_frequency_shift_matches_gordons_rate( assert rate == pytest.approx(gordon, rel=3e-2) -def test_a_run_without_raman_does_not_shift_its_centroid(selected_backend_name): +def test_a_run_without_raman_does_not_shift_its_centroid(backend_name): """The same fibre with Raman off: a soliton keeps its centre frequency.""" tau0, length = 800e-15, 60.0 peak = abs(SSFS_BETA2) / (SSFS_GAMMA * tau0**2) @@ -849,7 +851,7 @@ def test_a_run_without_raman_does_not_shift_its_centroid(selected_backend_name): n_save=3, rtol=1e-9, atol=1e-22, - backend=selected_backend_name, + backend=backend_name, noise=None, ) centroid = handler["stats/omega0"][:, 0, 0] @@ -878,7 +880,7 @@ def photon_number_and_energy(handler, grid): @pytest.mark.parametrize("raman", [True, False], ids=["raman", "kerr"]) def test_the_shock_term_conserves_photon_number_and_raman_costs_energy( - photon_grid, raman, selected_backend_name + photon_grid, raman, backend_name ): """With the ``omega`` prefactor in place the equation conserves photon number. @@ -907,7 +909,7 @@ def test_the_shock_term_conserves_photon_number_and_raman_costs_energy( n_save=5, rtol=1e-12, atol=1e-26, - backend=selected_backend_name, + backend=backend_name, noise=None, ) photons, energy = photon_number_and_energy(handler, photon_grid) diff --git a/tests/backends/test_on_axis_statistics.py b/tests/backends/test_on_axis_statistics.py index ee5365c1b..0929ce99c 100644 --- a/tests/backends/test_on_axis_statistics.py +++ b/tests/backends/test_on_axis_statistics.py @@ -619,12 +619,14 @@ def envelope_run(radial_rule, n_r): return {name: np.asarray(output[f"stats/{name}"]) for name in names} -def test_an_envelope_mixture_in_a_taper_reads_the_same_axis_on_every_rule(): - """Cycle-averaged rates, an Ar/He mixture, preionisation and a taper. +def test_an_envelope_mixture_reads_the_same_axis_on_every_rule_at_the_entrance(): + """Cycle-averaged rates, an Ar/He mixture and preionisation, in a tapered bore. At the entrance every rule sees the same field, so the axis statistics agree; the non-ionising helium stays at zero; the Radau rule's node maximum is its axis node; - the five-node Gauss rule's is below the axis. + the five-node Gauss rule's is below the axis. The taper's factor is one at the + entrance, so this does not test the taper: ``test_numpy_ref_plasma.py``'s + ``test_the_on_axis_matrix_follows_a_taper`` does. """ runs = { rule: envelope_run(rule, n_r) diff --git a/tests/backends/test_parity_catalogue.py b/tests/backends/test_parity_catalogue.py index 1b4f64773..49d3f8fd6 100644 --- a/tests/backends/test_parity_catalogue.py +++ b/tests/backends/test_parity_catalogue.py @@ -12,6 +12,8 @@ import pytest import parity_ladder +from backends.adams_source_cases import one_evaluation +from backends.planar_rows import without_responses from capability_routes import catalogue solprop_native = pytest.importorskip("solprop_native") @@ -29,3 +31,21 @@ def _param(row: parity_ladder.Row): @pytest.mark.parametrize("row", [_param(row) for row in catalogue()]) def test_every_rung_agrees_with_the_reference(row, request): parity_ladder.check(solprop_native.NativeBackend, row, request) + + +# Medium: the argon capillary's translation takes about a second. +@pytest.mark.medium +def test_a_guard_that_switches_off_every_response_of_several_is_refused(): + """Kerr beside the plasma: removing both would let Kerr clear a plasma guard.""" + built = one_evaluation("envelope plasma") + assert parity_ladder.responses_held(built.problem) == ("kerr", "envelope plasma") + row = parity_ladder.Row( + id="every response of two", + why="The envelope plasma's source is the reference's.", + axes={"response": "envelope plasma"}, + build=lambda: built, + rungs={"source": lambda _: 1.0}, + switch_off=without_responses, + ) + with pytest.raises(AssertionError, match=r"holds \('kerr', 'envelope plasma'\)"): + parity_ladder.check(solprop_native.NativeBackend, row) diff --git a/tests/backends/test_radial_absorber.py b/tests/backends/test_radial_absorber.py index b37d3cca8..79b6b3018 100644 --- a/tests/backends/test_radial_absorber.py +++ b/tests/backends/test_radial_absorber.py @@ -192,7 +192,7 @@ def test_spatial_absorber_step_refinement_matches_matrix_exponential( @pytest.mark.parametrize("illumination", ["confined", "extended"]) def test_spatial_collar_diagnostic_reports_the_measured_fraction( - absorber_case, spatial_backend_class, illumination + absorber_case, illumination ): grid, space, _, _, _, _, _, _ = absorber_case problem, run_request = problem_for(absorber_case, 8) @@ -215,9 +215,6 @@ def test_spatial_collar_diagnostic_reports_the_measured_fraction( assert expected > run_request.stepper.controller.rtol else: assert expected < run_request.stepper.controller.rtol - # The end-of-plane log of this share is retired (SEP 40 section 5.3): the - # monitor's transverse edge judges the boundary instead. - del spatial_backend_class def test_spatial_rate_stability_refusal_is_not_lifted_by_temporal_split( diff --git a/tests/backends/test_radial_statistics.py b/tests/backends/test_radial_statistics.py index daedb1502..dfa91658b 100644 --- a/tests/backends/test_radial_statistics.py +++ b/tests/backends/test_radial_statistics.py @@ -11,7 +11,7 @@ import pytest from numpy.testing import assert_allclose -from builders import load_reference +from builders import live_nyquist, load_reference from hankel_oracles import gamma from sessions.runs import bare, final_field, launch_statistics from solprop.backends.numpy_ref import NumpyRefBackend @@ -21,7 +21,12 @@ from solprop.output.records import SavedPlane from solprop.profiles import Constant from solprop.pulses import GaussianPulse, SpatialPulse -from solprop.spatial import SpatialFlux, SpatialMedium, spatial_fluence +from solprop.spatial import ( + SpatialFlux, + SpatialMedium, + on_axis_spectrum, + spatial_fluence, +) from solprop.stats import StatsSpec, collect, default_spec from solprop.stepper import FixedSchedule, PIController from solprop.translate.assembly import assemble @@ -191,6 +196,52 @@ def test_radial_statistics_match_the_host_without_field_observation( oracle.close() +def test_the_on_axis_spectrum_weighs_the_end_bins_as_the_definition( + spatial_backend_class, +): + """A backend's on-axis spectrum is the reference's at the end bins too. + + Both end bins carry field; DC has no admittance, so the Nyquist bin, made active by + widening the collar past it, is where the analytic signal's end-bin weight shows. + """ + grid = live_nyquist(FieldGrid.from_limits(1e-4, 800e-9, (600e-9, 1.2e-6), 150e-15)) + assert grid.active_mask[-1] + space = RadialGrid(6e-4, 16, collar_fraction=0.0) + rng = np.random.default_rng(155) + shape = (space.n_r, 1, grid.n_omega) + state = rng.standard_normal(shape) + 1j * rng.standard_normal(shape) + # The end bins of a real field are real. + state[..., [0, -1]] = np.real(state[..., [0, -1]]) + spec = StatsSpec(names=("on_axis_spectrum",)) + problem, run_request = assemble( + grid, + None, + [], + state, + spatial_grid=space, + medium=SpatialMedium(), + controller=PIController(rtol=1e-8, atol=1e-14), + save_planes=[grid.length], + dz_max=grid.length, + dz_init=grid.length / 8, + stats_spec=spec, + ) + flux = SpatialFlux.resolve(grid, space, SpatialMedium()) + expected = on_axis_spectrum(state, flux) + backend = spatial_backend_class(problem, run_request, grid=grid) + try: + actual = launch_statistics(backend, problem, run_request, field=state) + finally: + backend.close() + # Each bin's coherent sum over n_r columns, its pairing and the weight, in any + # order (the flux statistics' budget). + bound = gamma(32 * (space.n_r + grid.n_omega)) * float(np.max(np.abs(expected))) + assert_allclose(actual["on_axis_spectrum"], expected, rtol=0, atol=bound) + # Non-vacuous: the interior weight at the Nyquist bin, 4 for 1, would move it by + # three times its value, far beyond the bound. + assert 3 * abs(expected[-1]) > 1e3 * bound + + def test_empty_spatial_widths_and_intensities(case, spatial_backend_class): grid, space = case spec = default_spec("radial") diff --git a/tests/backends/test_records.py b/tests/backends/test_records.py index 45b7daf52..8e5bffebf 100644 --- a/tests/backends/test_records.py +++ b/tests/backends/test_records.py @@ -283,7 +283,7 @@ def test_a_low_storage_replay_carries_its_flows_and_its_operator_s_origin(): records = run_records(problem, request, _entrance(problem)) assert isinstance(records.policy, RungeKuttaPolicy) assert records.low_storage == LowStorageSettings( - flows=low_storage_flows(problem, stepper, "native"), + flows=low_storage_flows(problem, stepper), separable=False, origin=float(problem.linear.z_span[0]), ) diff --git a/tests/backends/test_reference_independence.py b/tests/backends/test_reference_independence.py index 7b8d975b2..9ad4475e5 100644 --- a/tests/backends/test_reference_independence.py +++ b/tests/backends/test_reference_independence.py @@ -66,7 +66,7 @@ def test_an_injected_adams_engine_is_gated_and_checked_as_the_bridge_s( problem, run_request = soliton_problem(narrow_grid, 1, save_planes=[1e-3]) with ( closing(NumpyRefBackend(problem, run_request, grid=narrow_grid)) as backend, - pytest.raises(BackendError, match="Adams engine lacks start, trial"), + pytest.raises(BackendError, match="Adams engine lacks accept, begin_attempt"), ): HostAdamsMarch( object(), diff --git a/tests/backends/test_registry.py b/tests/backends/test_registry.py index 2e28f780e..6818fc62f 100644 --- a/tests/backends/test_registry.py +++ b/tests/backends/test_registry.py @@ -143,7 +143,6 @@ def test_select_builds_the_reference_backend(linear_problem, narrow_grid, caplog assert isinstance(backend, NumpyRefBackend) assert isinstance(backend, Backend) assert backend.name == "numpy_ref" - assert backend.available_device_memory() is None backend.close() assert caplog.messages == ["Using numpy_ref backend"] @@ -187,6 +186,39 @@ def constructor(actual, request, **options): } +class _Unconfigurable(ModuleType): + """A native package whose import-time settings are malformed.""" + + def __init__(self, error: Exception) -> None: + super().__init__("solprop_native") + self.error = error + + def __getattr__(self, name: str) -> Any: + raise self.error + + +@pytest.mark.parametrize( + "error", + [ + ValueError("SOLPROP_THREADS must be a positive thread count, got 'x'"), + RuntimeError("SOLPROP_THREADS must be a positive thread count, got 'x'"), + ], + ids=["value", "runtime"], +) +def test_a_native_configuration_error_at_import_is_a_backend_error( + linear_problem, narrow_grid, monkeypatch, error +): + problem, run_request = linear_problem(narrow_grid, save_planes=[LENGTH]) + monkeypatch.setitem(sys.modules, "solprop_native", _Unconfigurable(error)) + with pytest.raises( + BackendError, match=r"solprop-native did not load: SOLPROP_THREADS must be" + ) as raised: + _construct( + "native", problem, run_request, grid=narrow_grid, modes=None, profiles=None + ) + assert raised.value.__cause__ is error + + def test_there_are_exactly_two_backends(): """ADR-077: the reference and native; numba_cpu and mlx are gone.""" assert BACKEND_NAMES == ("numpy_ref", "native") @@ -343,6 +375,11 @@ def install_native( "find_spec", lambda name: spec if name == "solprop_native" else real_find_spec(name), ) + # A stand-in is never calibrated: the calibration would load its private copies + # of the package's modules from these files, and keep them after the test. + from solprop.calibration import first_use # noqa: PLC0415 + + monkeypatch.setattr(first_use, "ensure", lambda: None) return package @@ -540,6 +577,24 @@ def test_a_required_device_is_refused_before_anything_is_constructed( assert not built +def test_a_required_device_is_refused_before_the_first_use_calibration( + linear_problem, narrow_grid, monkeypatch +): + from solprop.calibration import first_use # noqa: PLC0415 + + problem, run_request = linear_problem(narrow_grid, save_planes=[LENGTH]) + fake_build(monkeypatch, "none", 0) + monkeypatch.setenv(registry.REQUIRE_DEVICE_SETTING, "cuda") + calibrated = [] + monkeypatch.setattr(first_use, "ensure", lambda: calibrated.append(True)) + built = [] + monkeypatch.setattr(registry, "_construct", lambda *a, **k: built.append(a)) + with pytest.raises(BackendError, match="device backend 'none'"): + select("native", problem, run_request, grid=narrow_grid) + assert not calibrated + assert not built + + def test_a_required_device_leaves_a_missing_package_to_the_selection(monkeypatch): monkeypatch.setenv(registry.REQUIRE_DEVICE_SETTING, "cuda") monkeypatch.setattr(registry, "_native_installed", lambda: False) diff --git a/tests/backends/test_resident_adams.py b/tests/backends/test_resident_adams.py index 1ff4178ba..0e06e06cf 100644 --- a/tests/backends/test_resident_adams.py +++ b/tests/backends/test_resident_adams.py @@ -34,9 +34,6 @@ pytestmark = [ pytest.mark.medium, pytest.mark.skipif("native" not in available(), reason="native is not installed"), - # The host engine these tests compare with runs solprop's march, with the warning - # tests/backends/test_native_march_admission.py asserts (SEP 39). - pytest.mark.filterwarnings("ignore::solprop.exceptions.HostMarchWarning"), ] NativeBackend = pytest.importorskip("solprop_native").NativeBackend diff --git a/tests/backends/test_rk_traces.py b/tests/backends/test_rk_traces.py index 64cd5c15e..f22ba236a 100644 --- a/tests/backends/test_rk_traces.py +++ b/tests/backends/test_rk_traces.py @@ -20,7 +20,8 @@ from typing import Any import pytest -from tests.backends.rk_traces import Scenario, run_scenario, same_trace + +from backends.rk_traces import Scenario, run_scenario, same_trace CORPUS = Path(__file__).parents[1] / "data" / "rk_traces.json.gz" diff --git a/tests/backends/test_spatial_execution.py b/tests/backends/test_spatial_execution.py index efe6ae093..5ef0f5629 100644 --- a/tests/backends/test_spatial_execution.py +++ b/tests/backends/test_spatial_execution.py @@ -54,14 +54,15 @@ def radial_blas_case(n_r, n_pol, chunk, duration): @pytest.mark.parametrize(("n_r", "n_pol", "chunk", "duration"), RADIAL_BLAS_CASES) def test_radial_real_blas_preserves_transform_and_memory_contract( - spatial_backend_class, n_r, n_pol, chunk, duration, request + spatial_equivalence_backend_class, n_r, n_pol, chunk, duration, request ): + backend_class = spatial_equivalence_backend_class grid, problem, run_request, options = radial_blas_case(n_r, n_pol, chunk, duration) # Two radial reductions and temporal transforms, with the existing chunk # ladder's association allowance, fixed before either backend runs. bound = gamma(64 * n_r + 32 * grid.n_to) reference = derivative(NumpyRefBackend, problem, run_request, grid, options) - actual = derivative(spatial_backend_class, problem, run_request, grid, options) + actual = derivative(backend_class, problem, run_request, grid, options) np.testing.assert_allclose( actual, reference, rtol=0, atol=bound * np.max(np.abs(reference)) ) @@ -71,28 +72,27 @@ def test_radial_real_blas_preserves_transform_and_memory_contract( f"r={n_r}, p={n_pol}, chunk={chunk}, time={grid.n_to}", np.max(np.abs(actual - reference)) / np.max(np.abs(reference)), bound, - spatial_backend_class.name, + backend_class.name, ) - backend = spatial_backend_class(problem, run_request, grid=grid, options=options) + backend = backend_class(problem, run_request, grid=grid, options=options) try: metadata, ledger = backend.metadata(), backend.memory_ledger() - if backend.name == "native": - # Device builds keep their existing provider. - packed = str(metadata["synthesis_provider"]).endswith("-packed-real") - eligible = ( - metadata["device_backend"] == "none" - and n_pol == 1 - and chunk == n_r - and n_r >= 256 - and grid.n_to >= 256 - and 22 * 16 * n_r * grid.n_to <= 64 * 1024 * 1024 - ) - assert packed == eligible - if packed: - assert n_pol == 1 and chunk == n_r - assert ledger["radial_blas_buffers"] == 32 * n_r * grid.n_to - assert 22 * 16 * n_r * grid.n_to <= 64 * 1024 * 1024 - else: - assert ledger["radial_blas_buffers"] == 0 + # Device builds keep their existing provider. + packed = str(metadata["synthesis_provider"]).endswith("-packed-real") + eligible = ( + metadata["device_backend"] == "none" + and n_pol == 1 + and chunk == n_r + and n_r >= 256 + and grid.n_to >= 256 + and 22 * 16 * n_r * grid.n_to <= 64 * 1024 * 1024 + ) + assert packed == eligible + if packed: + assert n_pol == 1 and chunk == n_r + assert ledger["radial_blas_buffers"] == 32 * n_r * grid.n_to + assert 22 * 16 * n_r * grid.n_to <= 64 * 1024 * 1024 + else: + assert ledger["radial_blas_buffers"] == 0 finally: backend.close() diff --git a/tests/backends/test_step_limits.py b/tests/backends/test_step_limits.py index 03c5a3c82..1420e1486 100644 --- a/tests/backends/test_step_limits.py +++ b/tests/backends/test_step_limits.py @@ -21,6 +21,7 @@ from solprop.backends.session import Start from solprop.driver import simulation as simulation_module from solprop.driver.simulation import Simulation +from solprop.exceptions import TranslationError from solprop.gasflow import steady_fill from solprop.output.metadata import _example_metadata from solprop.output.records import StepLimits, StepperRecord @@ -121,6 +122,39 @@ def test_a_coupled_flow_keeps_the_version_16_limits(narrow_grid, soliton_problem assert settings.auto_init is False +def test_the_adams_march_records_and_takes_its_own_interval_cap( + narrow_grid, soliton_problem +): + # The Adams march caps by Multistep.interval_cap (ADR-037), so the run records that + # and refuses a stepper-wide request that would differ from it. + for method in (Multistep(), Multistep(interval_cap=True)): + _, run_request = soliton_problem( + narrow_grid, 1, save_planes=[LENGTH], integrator=method + ) + assert run_request.stepper.interval_cap is method.interval_cap + with pytest.raises(TranslationError, match=r"Multistep\(interval_cap=True\)"): + soliton_problem( + narrow_grid, + 1, + save_planes=[LENGTH], + integrator=Multistep(), + interval_cap=True, + ) + with pytest.raises(TranslationError, match=r"Multistep\(interval_cap=False\)"): + soliton_problem( + narrow_grid, + 1, + save_planes=[LENGTH], + integrator=Multistep(interval_cap=True), + interval_cap=False, + ) + # Asking for what the method applies is no conflict. + same = soliton_problem( + narrow_grid, 1, save_planes=[LENGTH], integrator=Multistep(), interval_cap=False + ) + assert same.request.stepper.interval_cap is False + + @pytest.mark.medium @pytest.mark.filterwarnings("ignore::solprop.exceptions.MaterialRangeWarning") def test_without_the_cap_a_step_outgrows_the_table_s_intervals(): diff --git a/tests/backends/test_vector_raman.py b/tests/backends/test_vector_raman.py index b0c504a85..a37b4ee73 100644 --- a/tests/backends/test_vector_raman.py +++ b/tests/backends/test_vector_raman.py @@ -14,6 +14,7 @@ from bounds import gamma, ladder_bound from former_raman import FORMER_H2, former_response +from solprop import fourier from solprop.backends.node_chunk import _raman_chunk from solprop.backends.numpy_ref import NumpyRefBackend from solprop.backends.numpy_ref.passes.responses import ( @@ -170,10 +171,13 @@ def test_compiled_tensor_rows_keep_physical_labels_and_damping(material): np.testing.assert_array_equal(scalar.tensor_weights, leaf.tensor_weights) +@pytest.mark.parametrize("layout", ["envelope", "real field", "analytic field"]) @pytest.mark.parametrize("count", [17, 64, 97]) -def test_effective_kernel_convolution_matches_physical_term_sums(count): +def test_effective_kernel_convolution_matches_physical_term_sums(count, layout): # Distinct signed kernels, dephasings, species densities and fractions ensure - # combining before damping or applying total density to amplitude fails. + # combining before damping or applying total density to amplitude fails. Each + # sample layout forms its own drive: the envelope's and the analytic signal's cycle + # averages, and the real field's instantaneous square, which keeps the harmonic. dt = 0.07 delays = np.arange(count) * dt response = former_response(FORMER_H2) @@ -195,18 +199,32 @@ def test_effective_kernel_convolution_matches_physical_term_sums(count): * np.exp(-rates[2 * i + 1] * delays) ) rng = np.random.default_rng(4003) - values = rng.standard_normal((3, 2, count)) + 1j * rng.standard_normal( - (3, 2, count) - ) + values = rng.standard_normal((3, 2, count)) + if layout == "envelope": + values = values + 1j * rng.standard_normal((3, 2, count)) spectrum = tensor_raman_spectrum(tuple(components), rates, densities, dt) actual = raman_polarisation( - values, spectrum, kind="envelope", thg=response.thg, density=1.0 + values, + spectrum, + kind="envelope" if layout == "envelope" else "field", + thg=response.thg if layout == "envelope" else layout == "real field", + density=1.0, ) for node in range(3): - expected = EPS0 * cartesian_direct(values[node], hv, hr, dt, envelope=True) + samples, envelope = values[node], layout != "real field" + if layout == "analytic field": + # The drive is the analytic signal's cycle average; the real channel + # matrix then multiplies the real field, the analytic signal's real part. + samples = fourier.analytic_signal(samples) + expected = EPS0 * cartesian_direct(samples, hv, hr, dt, envelope=envelope) + if layout == "analytic field": + expected = expected.real bound = EPS0 * convolution_bound( - values[node], hv, hr, dt, envelope=True, fft=True + samples, hv, hr, dt, envelope=envelope, fft=True ) + # The rounding bound must sit far below the polarisation, so that a factor + # missing from a drive cannot pass inside it. + assert bound < 1e-6 * np.max(np.abs(expected)) assert_allclose(actual[node], expected, rtol=0, atol=bound) diff --git a/tests/builders.py b/tests/builders.py index 7d1e8f6fd..fca4afdbe 100644 --- a/tests/builders.py +++ b/tests/builders.py @@ -26,7 +26,7 @@ from solprop.driver import Simulation from solprop.driver.scan import ScanPoint from solprop.exceptions import GridError -from solprop.grid import EnvelopeGrid, TimeGrid +from solprop.grid import EnvelopeGrid, FieldGrid, TimeGrid from solprop.stats import StatsSpec from solprop.stepper import FixedSchedule from solprop.translate.problem import PropagationProblem @@ -38,6 +38,7 @@ "grid_at", "held_collar", "launch_derivative", + "live_nyquist", "load_reference", "numpy_ref_launch_derivative", "reference_trial", @@ -99,6 +100,17 @@ def grid_at[G: TimeGrid](grid: G, length: float) -> G: return dataclasses.replace(grid, length=length) +def live_nyquist(grid: FieldGrid) -> FieldGrid: + """Return `grid` with its spectral collar widened past its Nyquist bin. + + No field grid that validates has one; :func:`dataclasses.replace` does not + validate, so a test can reach the end-bin weights of a spectral statistic where they + differ from the interior ones. The Nyquist bin becomes active, its window non-zero. + """ + collar = dataclasses.replace(grid.omega_collar, zero_high=1.1 * grid.omega[-1]) + return dataclasses.replace(grid, omega_collar=collar) + + def held_collar(grid: TimeGrid, length: float) -> Absorber: """Return the default collar on `grid`, at the rates a grid of `length` gave. diff --git a/tests/calibration/test_child.py b/tests/calibration/test_child.py index d1b862698..b0fbebd4d 100644 --- a/tests/calibration/test_child.py +++ b/tests/calibration/test_child.py @@ -66,19 +66,33 @@ def test_a_child_prepares_times_and_probes_regions() -> None: assert len(replies) == 7 -def test_a_child_times_under_a_given_record() -> None: - from solprop_native import ( # noqa: PLC0415 # pyright: ignore[reportMissingImports] - BUILTIN_EXECUTION, - ) +def test_a_child_times_each_candidate_under_the_record_it_is_given() -> None: + import solprop_native # noqa: PLC0415 # pyright: ignore[reportMissingImports] - serial = BUILTIN_EXECUTION.updated( + serial = solprop_native.BUILTIN_EXECUTION.updated( {"stage_threshold": 1 << 40, "stage_full": 1 << 40} - ) - replies = _serve( - {"op": "prepare", "problems": {"gnlse": 0.5}}, - {"op": "time", "problem": "gnlse", "repeats": 1, "record": serial.native()}, - ) - assert isinstance(replies[1]["ok"], float) + ).native() + own = solprop_native.EXECUTION.native() + # The candidate differs from the process's own record, so its application shows. + assert own["stage_threshold"] != serial["stage_threshold"] + session = child._Session() # pyright: ignore[reportPrivateUsage] + try: + session.prepare({"gnlse": 0.5}) + assert session.time("gnlse", 1, serial) > 0 + for record, expected, source in ( + (serial, serial, "given"), + (None, own, solprop_native.EXECUTION_SOURCE), + ): + key = session._key("gnlse", record) # pyright: ignore[reportPrivateUsage] + backend, _ = session.backends[key] + # What the workspace applied, as it reads its record back. + calibration = cast(dict[str, object], backend.metadata()["calibration"]) + assert calibration["workspace_source"] == source + workspace = cast(dict[str, dict[str, object]], calibration["workspace"]) + applied = {name: entry["applied"] for name, entry in workspace.items()} + assert applied == expected + finally: + session.close() def test_every_calibration_problem_builds() -> None: diff --git a/tests/calibration/test_controller.py b/tests/calibration/test_controller.py index 47d4ffe0f..dcea8cacf 100644 --- a/tests/calibration/test_controller.py +++ b/tests/calibration/test_controller.py @@ -208,6 +208,11 @@ def test_a_childs_environment_drops_the_users_settings() -> None: "SOLPROP_THREADS": "4", "OMP_WAIT_POLICY": "active", "SOLPROP_FFTW_WISDOM": "/w", + # Kernel-form and pool overrides change what is timed, and no row records them. + "SOLPROP_NATIVE_BAND_TILES": "0", + "SOLPROP_NATIVE_FORWARD_PACK": "0", + "SOLPROP_BLAS_THREADS": "2", + "SOLPROP_OVERSUBSCRIBE": "1", "HOME": "/h", } built = Candidate().environment(base) @@ -324,6 +329,34 @@ def test_no_winner_publishes_the_built_in_rules( assert "validation" not in report.evidence +def test_a_lower_level_reports_the_higher_row_the_store_keeps( + scripted: tuple[type[_Scripted], dict[str, str]], +) -> None: + script, environ = scripted + script.factor = staticmethod(lambda name, call: 0.8 if name == "spin/4" else 1.0) + first = calibrate("standard", environ=environ, cpus=range(8)) + assert first.status == "published" and first.path is not None + published = first.path.read_text(encoding="utf-8") + # A quick run that would choose the built-in rules leaves the standard row. + script.factor = staticmethod(lambda name, call: 1.0) + report = calibrate("quick", environ=environ, cpus=range(8)) + assert report.status == "kept" + assert report.chosen == {"threads": 4, "wait": "spin"} + assert report.path is None + assert "standard row" in report.reason + assert "calibration (quick): kept" in report.describe() + # Nothing is published: the store's generation, wisdom included, is the first. + rows = _rows(environ) + assert len(rows) == 1 + assert rows[0]["level"] == "standard" + assert rows[0]["process"] == {"threads": 4, "wait": "spin"} + current = next((Path(environ["SOLPROP_CACHE_DIR"]) / "machines").glob("*/current")) + assert current.parent / (current.read_text(encoding="utf-8").strip() + ".json") == ( + first.path + ) + assert first.path.read_text(encoding="utf-8") == published + + def test_a_winner_that_fails_validation_is_dropped( scripted: tuple[type[_Scripted], dict[str, str]], ) -> None: diff --git a/tests/calibration/test_first_use.py b/tests/calibration/test_first_use.py index c391d271a..7db71cab9 100644 --- a/tests/calibration/test_first_use.py +++ b/tests/calibration/test_first_use.py @@ -122,6 +122,16 @@ def test_a_single_cpu_is_never_measured( assert auto == [] +def test_an_unreadable_store_leaves_the_built_in_table( + auto: list[tuple[str, tuple[int, ...]]], monkeypatch: pytest.MonkeyPatch +) -> None: + # What choice() returns, having warned, when reading the store raises OSError. + unread = _native.profile.Choice(mode="auto", note="the store is unreadable") + monkeypatch.setattr(calibration, "choice", lambda environ=None: unread) + assert first_use.ensure() is None + assert auto == [] + + def test_a_device_build_is_left_to_its_own_calibration( auto: list[tuple[str, tuple[int, ...]]], monkeypatch: pytest.MonkeyPatch ) -> None: @@ -236,13 +246,20 @@ def test_selecting_native_and_admitting_a_scan_ask_for_a_calibration( class StopError(Exception): pass - def stop(*args: object) -> None: + def stop(*args: object, **kwargs: object) -> None: raise StopError + simulation = problems.build("gnlse") + problem, request = simulation.translate(), simulation.run_request() + # A refusal of the required device comes first, and nothing is calibrated for it. monkeypatch.setattr(registry, "_check_required_device", stop) with pytest.raises(StopError): - simulation = problems.build("gnlse") - registry.select("native", simulation.translate(), simulation.run_request()) + registry.select("native", problem, request) + assert asked == [] + monkeypatch.setattr(registry, "_check_required_device", lambda name: None) + monkeypatch.setattr(registry, "_construct", stop) + with pytest.raises(StopError): + registry.select("native", problem, request) assert asked == ["ensure"] monkeypatch.setattr(first_use, "for_workers", lambda cpus: asked.append("workers")) monkeypatch.setattr(pool, "_spawn", stop) diff --git a/tests/calibration/test_profiles.py b/tests/calibration/test_profiles.py index 864dc5cf0..f5bd5dbc2 100644 --- a/tests/calibration/test_profiles.py +++ b/tests/calibration/test_profiles.py @@ -231,7 +231,14 @@ def fake( progress("measuring") return controller.CalibrationReport( level=level, - status="published" if level != "thorough" else "inconclusive", + # A kept higher row is a success too: the store holds a profile. + status=( + "published" + if level == "standard" + else "kept" + if level == "quick" + else "inconclusive" + ), fingerprint="f", allocation={}, reason="because", diff --git a/tests/conftest.py b/tests/conftest.py index 5df66de68..1f90fa901 100644 --- a/tests/conftest.py +++ b/tests/conftest.py @@ -14,6 +14,7 @@ import importlib import importlib.util +import numbers import os import sys @@ -93,6 +94,45 @@ def _resolve_for_tests(backend="auto"): driver_settings.resolve_name = _resolve_for_tests +_PYTEST_APPROX = pytest.approx +_PYTEST_REL = 1e-6 +"""pytest's default relative tolerance, which a bare ``approx`` of a number keeps.""" + + +def _approx(expected, rel=None, abs=None, nan_ok=False): + """Return ``pytest.approx`` with no absolute tolerance unless the test gives one. + + pytest's ``approx`` keeps a default absolute tolerance of 1e-12 beside any ``rel``, + and accepts ``|actual - expected| <= max(rel |expected|, 1e-12)``. The suite's + quantities are SI values, many of 1e-15 to 1e-53 (times, nonlinear indices, + polarisabilities, energies), and for them that default accepts any result. So in + this suite the absolute tolerance is zero unless the test gives ``abs=``: with + ``rel=`` alone the comparison is relative only, and a bare ``approx(x)`` of a + nonzero number is relative to pytest's 1e-6 only. A bare ``approx`` of zero, or of + a sequence, array or mapping, keeps pytest's defaults. A test that needs an + absolute tolerance, an expected value of exactly zero among them, gives ``abs=`` + (``docs/dev/testing.md`` section 3). + """ + if abs is None: + if rel is not None: + abs = 0.0 + elif _nonzero_number(expected): + rel, abs = _PYTEST_REL, 0.0 + return _PYTEST_APPROX(expected, rel=rel, abs=abs, nan_ok=nan_ok) + + +def _nonzero_number(value) -> bool: + """Return whether `value` is a real or complex number, not a bool, other than 0.""" + return ( + isinstance(value, numbers.Complex) + and not isinstance(value, bool) + and value != 0 + ) + + +pytest.approx = _approx + + @pytest.fixture(autouse=True) def _keep_the_real_auto(request, monkeypatch): """Give a ``real_auto`` test the refusal that the session otherwise replaces.""" diff --git a/tests/coupling/test_elements.py b/tests/coupling/test_elements.py index 6d1e74c95..4a86d4b0c 100644 --- a/tests/coupling/test_elements.py +++ b/tests/coupling/test_elements.py @@ -264,8 +264,12 @@ def test_spectral_transfer_attenuates_by_its_squared_modulus( np.testing.assert_allclose( report.spectrum_out[band], factor * report.spectrum_in[band], rtol=1e-12 ) + # Silica absorbs too little over 2 cm at 800 nm for the energies to differ by more + # than their rounding, so the loss is held at the rounding of energy_in. assert report.specified_loss == pytest.approx( - report.energy_in - report.energy_out, rel=1e-12 + report.energy_in - report.energy_out, + rel=1e-12, + abs=16 * EPS * report.energy_in, ) assert report.calibration[0].removes_delay is True assert report.calibration[0].removes_phase is False diff --git a/tests/coupling/test_leaky.py b/tests/coupling/test_leaky.py index b611fba50..822d98149 100644 --- a/tests/coupling/test_leaky.py +++ b/tests/coupling/test_leaky.py @@ -54,7 +54,9 @@ def integral(p, q, radius): ) def test_the_disc_overlap_is_lommels_integral(p, q, rel): got = complex(leaky.disc_overlap(np.array(p), np.array(q), RADIUS)) - assert got == pytest.approx(integral(p, q, RADIUS), rel=rel) + # Also to rel of the disc's scale R^2: two zeros of J0 are orthogonal on it (the + # first row), and their overlap is zero to the rounding of that scale. + assert got == pytest.approx(integral(p, q, RADIUS), rel=rel, abs=rel * RADIUS**2) def test_inner_products_are_normalised_and_hermitian(): diff --git a/tests/coupling/test_models.py b/tests/coupling/test_models.py index 982eadd59..6889d5166 100644 --- a/tests/coupling/test_models.py +++ b/tests/coupling/test_models.py @@ -112,3 +112,26 @@ def test_a_scalar_basis_refuses_sets_it_has_no_profiles_for(grid): ScalarModeBasis.from_modes([step_index_mode(6e-6, n=2)], grid) with pytest.raises(CouplingError, match="share one fibre and profile"): ScalarModeBasis.from_modes([step_index_mode(), step_index_mode(4.4e-6)], grid) + with pytest.raises(CouplingError, match="share one fibre and profile"): + ScalarModeBasis.from_modes( + [ + step_index_mode(), + StepIndexMode( + 4e-6, core=CORE, cladding=CLADDING, profile_wavelength=1e-6 + ), + ], + grid, + ) + + +def test_a_step_index_basis_holds_several_radial_orders_of_one_fibre(grid): + """HE11 and HE12 of one fibre bound their cladding at different radii, and are + still one fibre: LP01 and LP02 at the fibre's own V.""" + modes = [step_index_mode(12e-6, m=m) for m in (1, 2)] + assert modes[0].dimlimits()[2] != modes[1].dimlimits()[2] + profiles = ScalarModeBasis.from_modes(modes, grid) + v = 2 * math.pi / 800e-9 * 12e-6 * math.sqrt(CORE**2 - CLADDING**2) + expected = [_lp_parameter(v, m)[0] for m in (1, 2)] + # The same solve on the same V, up to the rounding of V's two products. + np.testing.assert_allclose(profiles.u, expected, rtol=1e-12, atol=0.0) + assert expected[0] < expected[1] diff --git a/tests/coupling/test_remap.py b/tests/coupling/test_remap.py index eccc87cfa..da9817aef 100644 --- a/tests/coupling/test_remap.py +++ b/tests/coupling/test_remap.py @@ -11,12 +11,16 @@ from numpy.testing import assert_allclose from solprop.coupling import ( + CouplingModel, FieldPlane, + InputPort, + NodalField, PlaneBasis, PlaneGeometry, PlaneMetric, PlaneReference, basis_identity, + couple, regrid, ) from solprop.exceptions import CouplingError @@ -98,8 +102,11 @@ def test_an_identical_lattice_copies_and_the_direct_sum_agrees(): plane = plane_of(gaussian(), envelope()) copied, report = regrid(plane, plane.grid) assert report.method == "copy" - # The identity map is an exact structural contract. - assert np.array_equal(copied.samples, plane.samples) + # The identity map is an exact structural contract inside the band; the tails + # outside it are zeroed, as the direct sum leaves them. + band = plane.grid.active_mask + assert np.array_equal(copied.samples[..., band], plane.samples[..., band]) + assert not np.any(copied.samples[..., ~band]) direct, report = regrid(plane, plane.grid, method="direct") assert report.method == "direct" assert_allclose( @@ -148,7 +155,8 @@ def test_a_delay_moves_the_record_and_leaves_the_absolute_spectrum(): plane = plane_of(gaussian(), grid, reference=PlaneReference(0.3, 2e-12)) step = 40 * grid.dt moved, report = regrid(plane, grid, delay=2e-12 - step) - assert report.shift == pytest.approx(step, rel=1e-15) + # The shift is a difference of two delays of 2 ps and keeps their rounding. + assert report.shift == pytest.approx(step, rel=1e-15, abs=16 * EPS * 2e-12) assert_allclose( moved.samples, direct_sum(plane, grid, shift=step), @@ -234,6 +242,66 @@ def test_an_occupied_band_the_target_cannot_hold_is_refused_or_reported(): assert moved.energy() == report.energy_out +def test_a_band_crop_on_the_same_lattice_removes_what_it_reports(): + source = envelope(limits=(500e-9, 1.6e-6)) + # Equal dt and window, a different short-wavelength limit: one lattice whose + # active band no longer holds the pulse's blue wing. + target = EnvelopeGrid.from_limits( + 1.0, 800e-9, (850e-9, 1.6e-6), 1e-12, dt=source.dt + ) + assert np.array_equal(target.omega, source.omega) + plane = plane_of(gaussian(), source) + moved, report = regrid(plane, target, crop_band=True) + assert report.method == "copy" + assert report.band_loss > 0.01 + outside = ~target.active_mask + assert not np.any(moved.samples[..., outside]) + # Inside the band the identity map is an exact structural contract. + assert np.array_equal(moved.samples[..., ~outside], plane.samples[..., ~outside]) + # The ledger closes: the share reported outside the band is the energy that left, + # to the rounding of two sums over the same few hundred bins. + assert report.energy_in is not None and report.energy_out is not None + assert report.energy_out == pytest.approx( + report.energy_in * (1.0 - report.band_loss), rel=1e-12 + ) + port = InputPort( + "modal", + target, + plane.basis, + (1, 1, target.n_omega), + PlaneGeometry(0.0), + PlaneReference(), + PlaneMetric("identity"), + ) + launch = couple(moved, port, model=CouplingModel("same_basis")).launch + assert np.array_equal(launch.samples, moved.samples) + + +@pytest.mark.parametrize("magnetic", [False, True], ids=["electric", "both"]) +def test_a_band_crop_on_the_same_lattice_zeroes_the_nodal_fields_too(magnetic): + source = envelope(limits=(500e-9, 1.6e-6)) + target = EnvelopeGrid.from_limits( + 1.0, 800e-9, (850e-9, 1.6e-6), 1e-12, dt=source.dt + ) + spectra = np.ones((2, 3, source.n_omega), complex) + nodal = NodalField( + np.zeros((2, 2)), np.ones(2), spectra, spectra.copy() if magnetic else None + ) + plane = dataclasses.replace(plane_of(gaussian(), source), nodal=nodal) + moved, report = regrid(plane, target, crop_band=True) + assert report.method == "copy" and moved.nodal is not None + band = target.active_mask + fields = [moved.nodal.electric] + if magnetic: + assert moved.nodal.magnetic is not None + fields.append(moved.nodal.magnetic) + else: + assert moved.nodal.magnetic is None + for one in fields: + assert np.array_equal(one[..., band], spectra[..., band]) + assert not np.any(one[..., ~band]) + + def test_a_window_that_cannot_hold_the_record_is_refused_or_cut(): plane = plane_of(gaussian(t0=300e-15), envelope(1e-12)) short = envelope(0.4e-12) diff --git a/tests/coupling/test_transport.py b/tests/coupling/test_transport.py index 6ff8e3331..20b8d81f3 100644 --- a/tests/coupling/test_transport.py +++ b/tests/coupling/test_transport.py @@ -336,7 +336,12 @@ def test_element_order_matters_and_a_chain_commutes_only_internally( gap = FreeSpace(0.2, air, beyond_window="remove", edge_tolerance=1e-2) first = apply_sequence(state, [aperture, gap]) second = apply_sequence(state, [gap, aperture]) - assert not np.allclose(first.state.spectrum, second.state.spectrum, rtol=1e-3) + assert not np.allclose( + first.state.spectrum, + second.state.spectrum, + rtol=1e-3, + atol=1e-3 * np.max(np.abs(second.state.spectrum)), + ) gdd = TaylorPhase((0.0, 0.0, 200e-30), 800e-9) tod = TaylorPhase((0.0, 0.0, 0.0, 3000e-45), 800e-9) forward = apply_sequence(state, [Chain((gdd, tod)), gap]) diff --git a/tests/coupling/test_transport_plane.py b/tests/coupling/test_transport_plane.py index 05ff24aed..ba76e81fb 100644 --- a/tests/coupling/test_transport_plane.py +++ b/tests/coupling/test_transport_plane.py @@ -179,7 +179,10 @@ def test_an_interface_changes_the_plane_medium_and_metric(): plane = _plane(grid, RadialGrid(4e-3, 64), air) inside, report = transport(plane, [PlanarInterface(air, glass)]) assert inside.medium is glass - assert inside.energy() == pytest.approx(0.96 * ENERGY, rel=1e-7) + # The normal-incidence factor on every angular column raises an oblique column's + # flux by cos(theta_t) / cos(theta_i): (1 - 1/n^2) <theta^2> / 2 = 1.0e-7 of the + # energy for this 0.3 mm waist, which the report counts as approximation error. + assert inside.energy() == pytest.approx(0.96 * ENERGY, rel=2e-7) assert report.specified_loss == pytest.approx(0.04 * ENERGY, rel=1e-7) diff --git a/tests/data/convergence/spatial_accuracy.json b/tests/data/convergence/spatial_accuracy.json index 54007e25e..7baa60000 100644 --- a/tests/data/convergence/spatial_accuracy.json +++ b/tests/data/convergence/spatial_accuracy.json @@ -2506,13 +2506,6 @@ "write": 0, "written_by": "tests/driver/test_prop_radial.py::test_radial_interface_caches_and_saves_geometry[envelope-numpy_ref]" }, - { - "axis": "largest", - "fraction": 0.0, - "series": "numpy_ref: radial real BLAS derivative (relative)", - "write": 0, - "written_by": "tests/backends/test_spatial_execution.py::test_radial_real_blas_preserves_transform_and_memory_contract[numpy_ref-128-1-128-3e-13]" - }, { "axis": "largest", "fraction": 0.08579503574802753, diff --git a/tests/data/generate_symbolic_vincetti.py b/tests/data/generate_symbolic_vincetti.py index 56f46481e..49ac08a00 100644 --- a/tests/data/generate_symbolic_vincetti.py +++ b/tests/data/generate_symbolic_vincetti.py @@ -12,7 +12,7 @@ centres and offsets of the dispersion width, in addition to 200 nm--2 um. The expression is solprop's form of the fits: dispersion width 0.03, the printed ``3 + -10 lambda/a`` in the effective radius, the normalised frequency ``(2t/lambda) sqrt(n_t^2 +20 lambda/a`` in the effective radius, the normalised frequency ``(2t/lambda) sqrt(n_t^2 - n_g^2)`` wherever it enters (the minimum loss keeps its ``n_t^2 - 1`` factors), the waveguide decrement divided by the gas index once, and the area with the paper's ``1/n_g`` prefactor. The gas symbol is real in the algebra and complex in the numbers, @@ -106,7 +106,7 @@ def symbolic_expressions(geometry): * 3 / 64 * outer**2 - * (1 + (3 + 10 * wavelength / radius) * gap / outer) + * (1 + (3 + 20 * wavelength / radius) * gap / outer) ) shift = 4.5e-7 * (1 - ratio) ** -4 * (wavelength / radius) ** 2 * dispersion decrement = ( @@ -220,7 +220,7 @@ def residual( "bessel_zero": BESSEL_ZERO, "conventions": { "dispersion_width": 0.03, - "radius_coefficient": 10, + "radius_coefficient": 20, "single_power_decrement": True, "area_over_gas_index": True, "filled_frequency": True, diff --git a/tests/data/jcmwave_vincetti.json b/tests/data/jcmwave_vincetti.json index a4cd6aec6..53c9ff2d4 100644 --- a/tests/data/jcmwave_vincetti.json +++ b/tests/data/jcmwave_vincetti.json @@ -1,6 +1,7 @@ { "provenance": { "generated": "2026-09-13T17:57:16.743485+00:00", + "generated_by": "tests/data/generate_jcmwave_vincetti.py", "generator_sha256": "37cac048b74ae43a972df6aea3cb67b08d7f7d180a945bf50916b911117ef5bd", "library_root": "pyJCMwave", "source_sha256": { diff --git a/tests/data/luna_mixture_propagation.json b/tests/data/luna_mixture_propagation.json index 56ee7647c..f21b9bc3f 100644 --- a/tests/data/luna_mixture_propagation.json +++ b/tests/data/luna_mixture_propagation.json @@ -26364,6 +26364,7 @@ }, "provenance": { "generated": "2026-09-11T00:46:50.611870+00:00", + "generated_by": "tests/data/generate_luna_mixture_propagation.py", "julia_version": "julia version 1.12.6", "luna_commit": "de9db7c9a3b6e37fc71bb657540abab177242883", "luna_path": "~/.julia/dev/Luna", diff --git a/tests/data/luna_tools_optics.json b/tests/data/luna_tools_optics.json index 5519a24de..b806960c8 100644 --- a/tests/data/luna_tools_optics.json +++ b/tests/data/luna_tools_optics.json @@ -1,5 +1,6 @@ { "generated": "2026-09-17T15:31:57+00:00", + "generated_by": "tests/data/generate_luna_tools_optics.py", "luna_commit": "de9db7c9a3b6e37fc71bb657540abab177242883", "program_sha256": "ccb1bdf50fbe9ea636cfe042ed9c4b7178f630831b255ba01db62562d9fc9137", "glass_wavelengths": [ diff --git a/tests/data/symbolic_vincetti.json b/tests/data/symbolic_vincetti.json index 08b581970..767267802 100644 --- a/tests/data/symbolic_vincetti.json +++ b/tests/data/symbolic_vincetti.json @@ -1,13 +1,14 @@ { "provenance": { - "generated": "2026-09-13T17:56:03.617272+00:00", - "generator_sha256": "f99bb223b31f9d286d17f39d04e6c43d57429cd9c59c04b07f945601b5c79c1a", + "generated": "2026-11-17T23:34:01.017033+00:00", + "generated_by": "tests/data/generate_symbolic_vincetti.py", + "generator_sha256": "b1d20fa1b3470a8714721cf3d59354269f46a38264642165a4facae81a91fd6b", "sympy_version": "1.14.0", "light_speed": 299792458, "bessel_zero": 2.404825557695773, "conventions": { "dispersion_width": 0.03, - "radius_coefficient": 10, + "radius_coefficient": 20, "single_power_decrement": true, "area_over_gas_index": true, "filled_frequency": true @@ -548,423 +549,423 @@ ], "refractivity": [ [ - 0.00664091246902232, - 4.709180490319152e-08 + 0.006640941328551753, + 4.709180355644518e-08 ], [ - 0.006191579753716203, - 4.55444671777536e-08 + 0.0061916117926901215, + 4.554446573275015e-08 ], [ - 0.006050411741157724, - 4.516090338669699e-08 + 0.006050444941174904, + 4.516090190662501e-08 ], [ - 0.005905939954393036, - 4.441029336552603e-08 + 0.00590597438478313, + 4.441029184872994e-08 ], [ - 0.005901506306544624, - 4.4393678354214677e-08 + 0.005901540775343994, + 4.439367683627917e-08 ], [ - 0.00523977662163988, - 4.184713043347992e-08 + 0.00523981778334881, + 4.1847128722889627e-08 ], [ - 0.00465259406452212, - 3.944802791714463e-08 + 0.004652643211171981, + 3.94480259897156e-08 ], [ - 0.004130453491716368, - 3.7186505615717585e-08 + 0.004130512163460942, + 3.7186503444189124e-08 ], [ - 0.0036659529602571794, - 3.5054680535804074e-08 + 0.0036660229925407073, + 3.505467808942621e-08 ], [ - 0.0032525518076607085, - 3.304515793705889e-08 + 0.003252635387150926, + 3.3045155181114976e-08 ], [ - 0.002884403216000697, - 3.1151054249583674e-08 + 0.0028845029468096417, + 3.1151051144834003e-08 ], [ - 0.002556206201511424, - 2.9366224268114497e-08 + 0.00255632518345017, + 2.9366220770142933e-08 ], [ - 0.002262906308498236, - 2.7686966908534366e-08 + 0.002263048229328213, + 2.7686962966973887e-08 ], [ - 0.0019981783135130105, - 2.615983486837277e-08 + 0.001998347557358171, + 2.6159830425978123e-08 ], [ - 0.0018184158357990032, - 2.7188691348827835e-08 + 0.0018186084417755044, + 2.7188686497025217e-08 ], [ - 0.0017736372887484642, - 2.7497950574204743e-08 + 0.0017738390629948864, + 2.749794556572967e-08 ], [ - 0.0017383555803849315, - 2.8634462886444456e-08 + 0.0017385648660708242, + 2.8634457751120747e-08 ], [ - 0.0016421645893047732, - 2.371766658120295e-08 + 0.0016423926198798622, + 2.3717661134771864e-08 ], [ - 0.001578140684251883, - 2.3246110688757992e-08 + 0.0015783811673182324, + 2.3246105039579916e-08 ], [ - 0.0013878674941989466, - 2.188158744371795e-08 + 0.0013881540064561992, + 2.1881581068133387e-08 ], [ - 0.001219971804524267, - 2.0622055620349562e-08 + 0.001220313004229423, + 2.0622048419437424e-08 ], [ - 0.0010698117654757144, - 1.9439395471481593e-08 + 0.0010702178707080456, + 1.9439387330397202e-08 ], [ - 0.0009348010504355297, - 1.8326604283432463e-08 + 0.0009352840863936507, + 1.8326595067951434e-08 ], [ - 0.0008128869086418966, - 1.727929540231393e-08 + 0.000813460976910596, + 1.7279284954391415e-08 ], [ - 0.0007022926661797158, - 1.6294017079179057e-08 + 0.0007029742281488005, + 1.6294005211228125e-08 ], [ - 0.0006014366147013561, - 1.5368006254102335e-08 + 0.0006022447745024362, + 1.5367992741632498e-08 ], [ - 0.0005088929981813539, - 1.4499276488666812e-08 + 0.0005098497603450713, + 1.4499261060876326e-08 ], [ - 0.0004233676362217498, - 1.3686916750619334e-08 + 0.000424498098642756, + 1.3686899078536059e-08 ], [ - 0.0003436804918528491, - 1.2931670171713606e-08 + 0.0003450129144300096, + 1.293164985359094e-08 ], [ - 0.0002687522591979796, - 1.2236990675857893e-08 + 0.0002703179218910279, + 1.223696721985868e-08 ], [ - 0.00019759305041677777, - 1.1610977258194432e-08 + 0.00019942578172726932, + 1.1610950063099795e-08 ], [ - 0.0001292907319543346, - 1.1069983861950895e-08 + 0.00013142595279180824, + 1.1069952197939537e-08 ], [ - 6.299470294224285e-05, - 1.0645547869231217e-08 + 6.546779889937682e-05, + 1.0645510862951448e-08 ], [ - -2.112368610251991e-06, - 1.039818083703697e-08 + 7.314536272229333e-07, + 1.0398137468433543e-08 ], [ - -6.686769969777018e-05, - 1.0446141005300583e-08 + -6.362637319545783e-05, + 1.0446090127840276e-08 ], [ - -0.00013222744351226723, - 1.102934245020122e-08 + -0.00012857254269416085, + 1.1029282850383867e-08 ], [ - -0.0001994444025643638, - 1.2664340180999495e-08 + -0.0001953761206332505, + 1.2664270695120335e-08 ], [ - -0.00027037367441618, - 1.657498324393346e-08 + -0.0002659143932388641, + 1.657490294604087e-08 ], [ - -0.0003479795337298919, - 2.628240651114282e-08 + -0.0003431790812685742, + 2.628231497104962e-08 ], [ - -0.0004371564793482774, - 6.019133402075055e-08 + -0.00043209521111697846, + 6.019123160170806e-08 ], [ - -0.0005460529425729277, - 3.329834393141572e-07 + -0.0005408409367105849, + 3.329833274405355e-07 ], [ - -0.000688232139042233, - 1.7921765583184355e-06 + -0.0006830031666192893, + 1.7921764396109532e-06 ], [ - -0.0008861823750400122, - 5.8599045258461866e-06 + -0.0008810824346884294, + 5.859904404022642e-06 ], [ - -0.0011759294985399515, - 1.3664181046941438e-05 + -0.0011711014021820176, + 1.3664180926435942e-05 ], [ - -0.0016014437437222862, - 9.08172701860169e-06 + -0.0015970108606885303, + 9.081726903957418e-06 ], [ - -0.002085949903365303, - 7.3253900528681725e-06 + -0.002082002860727683, + 7.325389948060778e-06 ] ], "derivative": [ [ - 1.4171576975140322e-18, - 4.999428948972501e-24 + 1.4171484749926286e-18, + 4.999429239017116e-24 ], [ - 1.3781883917287369e-18, - 2.650198885135092e-24 + 1.3781777971623647e-18, + 2.6501992070303945e-24 ], [ - 1.2866658706236371e-18, - 1.1446578384543434e-23 + 1.2866547634684826e-18, + 1.144657871807391e-23 ], [ - 1.346926318897928e-18, - 5.0490181173988884e-24 + 1.3469146620560077e-18, + 5.049018463261913e-24 ], [ - 1.3461911727552629e-18, - 5.0435211144590105e-24 + 1.34617949864762e-18, + 5.043521460707075e-24 ], [ - 1.2597223150488174e-18, - 5.0000242160986955e-24 + 1.2597075393070826e-18, + 5.00002462948434e-24 ], [ - 1.1879432801404902e-18, - 4.9999169637771405e-24 + 1.187924581085024e-18, + 4.999917457388906e-24 ], [ - 1.1208667185452372e-18, - 4.9998424908945994e-24 + 1.1208430578813969e-18, + 4.9998430804162526e-24 ], [ - 1.0579890145817337e-18, - 4.9997129298856095e-24 + 1.0579590808155573e-18, + 4.99971363413538e-24 ], [ - 9.991342129770063e-19, - 4.9994003274813246e-24 + 9.990963503432815e-19, + 4.999401169075634e-24 ], [ - 9.442821893251487e-19, - 4.998469114579263e-24 + 9.442343086870767e-19, + 4.998470120755605e-24 ], [ - 8.937669908741186e-19, - 4.994871468880897e-24 + 8.937064582903037e-19, + 4.994872672526597e-24 ], [ - 8.494383714821501e-19, - 4.972446734628359e-24 + 8.493618692725171e-19, + 4.972448175578895e-24 ], [ - 8.256739284360695e-19, - 3.788101434443256e-24 + 8.255772826456079e-19, + 3.788103161137795e-24 ], [ - 6.119897191451598e-19, - 3.7725970953040794e-23 + 6.118749854556735e-19, + 3.7725972926904777e-23 ], [ - 6.818434574129508e-19, - -5.983027593490943e-23 + 6.817214246448825e-19, + -5.983027386329361e-23 ], [ - 4.661936554428731e-19, - 5.527709979581347e-23 + 4.660655624805499e-19, + 5.52771019478412e-23 ], [ - 7.807649372839089e-19, - 6.128277788927883e-24 + 7.806214188823292e-19, + 6.128280142931563e-24 ], [ - 7.488822425943767e-19, - 5.344519070920652e-24 + 7.487282484072559e-19, + 5.344521560156248e-24 ], [ - 6.893595544813524e-19, - 5.046098644602545e-24 + 6.891653751794552e-19, + 5.046101641346707e-24 ], [ - 6.515505022263685e-19, - 5.012228534172641e-24 + 6.513058823685804e-19, + 5.0122321503911236e-24 ], [ - 6.200597318447084e-19, - 5.000489759469195e-24 + 6.197519318960046e-19, + 5.000494135768873e-24 ], [ - 5.927123737880589e-19, - 4.992554018413012e-24 + 5.92325647227391e-19, + 4.992559332914132e-24 ], [ - 5.690414693192114e-19, - 4.9839523999984884e-24 + 5.685564780421006e-19, + 4.983958880361921e-24 ], [ - 5.489949910434326e-19, - 4.971991720005738e-24 + 5.483881848250404e-19, + 4.971999659715504e-24 ], [ - 5.326812359081443e-19, - 4.953429762149532e-24 + 5.319242500121521e-19, + 4.953439542404605e-24 ], [ - 5.202986173811391e-19, - 4.92310827549519e-24 + 5.193577875468081e-19, + 4.923120394222973e-24 ], [ - 5.12110780024503e-19, - 4.872088386503231e-24 + 5.109469428335206e-19, + 4.872103495864592e-24 ], [ - 5.08435497508266e-19, - 4.784344676563869e-24 + 5.070043437730262e-19, + 4.784363629478688e-24 ], [ - 5.096404989705002e-19, - 4.6304936509454726e-24 + 5.078938833381431e-19, + 4.630517554928625e-24 ], [ - 5.161497597594595e-19, - 4.355494673505601e-24 + 5.140385380840617e-19, + 4.355524945352325e-24 ], [ - 5.284742807342431e-19, - 3.8537757055934026e-24 + 5.259534254035434e-19, + 3.853814111648238e-24 ], [ - 5.472979815997273e-19, - 2.9170937920914278e-24 + 5.443348536091564e-19, + 2.917142444329562e-24 ], [ - 5.736774163080199e-19, - 1.1202818377106645e-24 + 5.70264029108353e-19, + 1.1203430950181101e-24 ], [ - 6.09460000874169e-19, - -2.4438724826565225e-24 + 6.056296901246108e-19, + -2.443796282886558e-24 ], [ - 6.580972707653725e-19, - -9.829174430995142e-24 + 6.539451099800199e-19, + -9.829081502757543e-24 ], [ - 7.261382318682184e-19, - -2.609725639514723e-23 + 7.218425537032107e-19, + -2.6097146373142754e-23 ], [ - 8.258541582338685e-19, - -6.556696243084309e-23 + 8.216936669437415e-19, + -6.556683757620927e-23 ], [ - 9.797262144622125e-19, - -1.8527055704221523e-22 + 9.76084080375888e-19, + -1.852704235998625e-22 ], [ - 1.2280738395180332e-18, - -1.0706049886973105e-21 + 1.225418550161006e-18, + -1.0706048579473853e-21 ], [ - 1.6422568223635515e-18, - -1.3860435289447933e-20 + 1.641091978319774e-18, + -1.3860435177742094e-20 ], [ - 2.3479821517758475e-18, - 4.514976236819684e-21 + 2.3487658958432498e-18, + 4.514976309746356e-21 ], [ - 3.5631991038091595e-18, - 9.905217337007901e-20 + 3.5662475445103274e-18, + 9.905217338474158e-20 ], [ - 5.614062423199446e-18, - -4.800903245260921e-19 + 5.619464503782163e-18, + -4.800903245840839e-19 ], [ - 8.436088757617031e-18, - -4.727988444965841e-19 + 8.44366365591657e-18, + -4.727988446321498e-19 ], [ - 6.0250448294100136e-18, - 1.8440382273843004e-19 + 6.034361390762612e-18, + 1.8440382253186632e-19 ] ], "effective_area": [ - 3.7017548393444476e-10, - 3.198240980639362e-10, - 4.501899690749026e-10, - 4.81637757095234e-10, - 4.797529682022159e-10, - 4.09322015469204e-10, - 3.996970082707088e-10, - 3.945159095924446e-10, - 3.90185512454172e-10, - 3.8560010777197384e-10, - 3.798943476080065e-10, - 3.716690960478719e-10, - 3.5739044143535594e-10, - 3.233206018496208e-10, - 2.884852749919961e-10, - 3.898672366484912e-10, - 5.06923312672683e-10, - 5.937877468197471e-10, - 5.228313932114004e-10, - 4.50763932594568e-10, - 4.2928054960287934e-10, - 4.1843023790860587e-10, - 4.114955507504237e-10, - 4.0642384239335355e-10, - 4.023911798370012e-10, - 3.9901705092955696e-10, - 3.9611715114922704e-10, - 3.9360852510335637e-10, - 3.91467462137792e-10, - 3.897077671688094e-10, - 3.8836655032360046e-10, - 3.874909652515212e-10, - 3.871211060905578e-10, - 3.87264148391245e-10, - 3.8785378904062826e-10, - 3.886880054901183e-10, - 3.893389781931699e-10, - 3.89035815861886e-10, - 3.8654086844407667e-10, - 3.800821989928846e-10, - 3.674647418542428e-10, - 3.465201303534554e-10, - 3.1599201393012366e-10, - 2.768188462050233e-10, - 2.341853380292492e-10, - 2.0523952290193872e-10 + 3.710787467785719e-10, + 3.205219062814787e-10, + 4.5159028138554034e-10, + 4.832603775285052e-10, + 4.813634888692277e-10, + 4.1056487831945954e-10, + 4.009538111589505e-10, + 3.958143625317822e-10, + 3.9153229113461977e-10, + 3.869946810524019e-10, + 3.8132934751126863e-10, + 3.731249869359134e-10, + 3.588170086314856e-10, + 3.245573316609982e-10, + 2.895121423143893e-10, + 3.9177390192350035e-10, + 5.101905388803479e-10, + 5.984038765457173e-10, + 5.264697591017321e-10, + 4.536249210425402e-10, + 4.320261379857268e-10, + 4.2118936052667284e-10, + 4.1431634818683803e-10, + 4.093304158793894e-10, + 4.0539777175324e-10, + 4.021329056465202e-10, + 3.993484893064671e-10, + 3.9695939111943155e-10, + 3.949400253966705e-10, + 3.9330227214557996e-10, + 3.920809479836474e-10, + 3.913201620386343e-10, + 3.9105568855632956e-10, + 3.9128837031792e-10, + 3.9194256364581863e-10, + 3.9280269695647477e-10, + 3.9342208947973377e-10, + 3.930054935909702e-10, + 3.9028778839215634e-10, + 3.8347372342634686e-10, + 3.7036262987467514e-10, + 3.488146168578855e-10, + 3.1764336645119863e-10, + 2.7788349532532076e-10, + 2.3480626667229083e-10, + 2.0561656624854994e-10 ] }, { @@ -1427,369 +1428,369 @@ ], "refractivity": [ [ - 0.006568253503268728, - 4.789249490881818e-08 + 0.006568664754445619, + 4.789247542137755e-08 ], [ - 0.005804496696684813, - 4.478657186662474e-08 + 0.005804986876917662, + 4.478654983322212e-08 ], [ - 0.005127197975887565, - 4.218943106348426e-08 + 0.005127781858169866, + 4.218940612789807e-08 ], [ - 0.004522510684915826, - 3.98255874197518e-08 + 0.004523205643359285, + 3.9825559164137367e-08 ], [ - 0.0039810352482587685, - 3.767108105959232e-08 + 0.003981861633876704, + 3.767104898975851e-08 ], [ - 0.0034948004777930475, - 3.5752974054459686e-08 + 0.0034957820055445676, + 3.575293758078863e-08 ], [ - 0.003056720661178236, - 3.415802584786842e-08 + 0.003057884782230902, + 3.4157984260692166e-08 ], [ - 0.00266036148462101, - 3.311182421043213e-08 + 0.00266173970111816, + 3.3111776648586495e-08 ], [ - 0.002299756778553652, - 3.3295188244460414e-08 + 0.002301384834673792, + 3.329513365587346e-08 ], [ - 0.001969197079111362, - 3.9308215357829495e-08 + 0.0019711149305563502, + 3.930815245162136e-08 ], [ - 0.001662910943073026, - 2.1373951684342932e-07 + 0.0016651623669676763, + 2.1373944403450685e-07 ], [ - 0.001374480088341512, - 5.662375447103304e-07 + 0.0013771117490120055, + 5.662374600604497e-07 ], [ - 0.0010955899905384925, - 1.5885298973039845e-06 + 0.00109864973076923, + 1.5885297984684785e-06 ], [ - 0.0008129988947660483, - 8.921153448299047e-06 + 0.0008165329922569242, + 8.92115333249658e-06 ], [ - 0.0005005069574075538, - 3.3583538079640185e-06 + 0.0005045560997489762, + 3.3583536719979595e-06 ], [ - 0.00010468721382239643, - 1.4988728891523854e-06 + 0.00010928104390139914, + 1.498872729525138e-06 ], [ - -0.00010798374299558766, - 6.645704740569107e-06 + -0.00010283342484174174, + 6.645704553740278e-06 ], [ - 0.0010306443099474816, - 5.228052102310006e-06 + 0.0010363374304156459, + 5.228051885146175e-06 ], [ - 0.0008250293866034486, - 1.5385070031844512e-06 + 0.0008312187254004844, + 1.5385067536190365e-06 ], [ - 0.0005634859677641213, - 5.316563733418765e-06 + 0.0005700865726629978, + 5.31656345127312e-06 ], [ - 0.0003698198455239776, - 4.108820689870384e-06 + 0.0003767070043285692, + 4.10882037768421e-06 ], [ - 0.000214923283695434, - 5.131859264200463e-06 + 0.00022193719012220114, + 5.1318589278136214e-06 ], [ - 7.848848150526777e-05, - 6.113117333393277e-05 + 8.544588769532346e-05, + 6.113117298251786e-05 ], [ - -5.5092995004168976e-05, - 3.164568185207333e-05 + -4.8381113695206146e-05, + 3.164568149740993e-05 ], [ - -0.00020080863883020772, - 2.2701367394952983e-05 + -0.0001945165377529312, + 2.2701367049974086e-05 ], [ - -0.00037478039389238216, - 8.10501026485986e-05 + -0.0003690486631041656, + 8.105010232553793e-05 ], [ - -0.0005950569484326484, - 0.0016620475638442342 + -0.0005899795980581768, + 0.0016620475635528947 ], [ - -0.0008822050939137904, - 0.00022512061435436373 + -0.0008778251028103146, + 0.00022512061410099064 ], [ - -0.0012601282751801834, - 0.0001511600608537593 + -0.0012564414519378175, + 0.00015116006064074867 ], [ - -0.0017573330234257334, - 0.0002641000650788634 + -0.0017542978327725889, + 0.0002641000649052285 ], [ - -0.002408742612174164, - 0.0010030974508779867 + -0.0024062926661644335, + 0.0010030974507402866 ], [ - -0.0032580904320841375, - 0.012503325463329471 + -0.003256146664102455, + 0.01250332546322286 ], [ - -0.004360907889236265, - 0.007178110118709345 + -0.004359388488431648, + 0.007178110118628496 ], [ - -0.005788271382215271, - 0.002776489399294529 + -0.005787098735161478, + 0.0027764893992342863 ], [ - -0.0076312831456288865, - 0.0021582663010095066 + -0.007630387905533276, + 0.0021582663009652816 ], [ - -0.010006613148971666, - 0.0022799144468687227 + -0.01000593601548383, + 0.002279914446836661 ], [ - -0.013063077652618271, - 0.0028843160217589653 + -0.013062569571448024, + 0.002884316021735966 ], [ - -0.016989221627600082, - 0.00414419074637395 + -0.016988843045426916, + 0.0041441907463576 ], [ - -0.022021346749444115, - 0.006588480674942695 + -0.022021066405232048, + 0.006588480674931159 ], [ - -0.028450420083704908, - 0.011427481642583795 + -0.028450213657369883, + 0.011427481642575711 ] ], "derivative": [ [ - 1.4675984383740978e-18, - 6.958546967429224e-24 + 1.4674683794863025e-18, + 6.958551257273524e-24 ], [ - 1.368636356528358e-18, - 5.244109244408228e-24 + 1.3684724582931506e-18, + 5.244114423632086e-24 ], [ - 1.2936975150590927e-18, - 4.999428837593163e-24 + 1.293491242752575e-18, + 4.999435110733932e-24 ], [ - 1.2272725002500981e-18, - 4.8521681971214626e-24 + 1.2270133255953016e-18, + 4.852175824817087e-24 ], [ - 1.1674266856809576e-18, - 4.6563426233779044e-24 + 1.1671017167821728e-18, + 4.6563519409212565e-24 ], [ - 1.1138305289296132e-18, - 4.296170347208987e-24 + 1.1134241317631813e-18, + 4.296181789733501e-24 ], [ - 1.0666415349137612e-18, - 3.530838186517847e-24 + 1.0661349917462455e-18, + 3.5308523228172836e-24 ], [ - 1.0263657464141212e-18, - 1.6861450794879414e-24 + 1.0257370308488551e-18, + 1.6861626565366862e-24 ], [ - 9.939644499719129e-19, - -4.0370273492997474e-24 + 9.931882492202495e-19, + -4.037005349648325e-24 ], [ - 9.711811954861799e-19, - -7.957122028398958e-23 + 9.702293816855249e-19, + -7.95711925766315e-23 ], [ - 9.61299727345096e-19, - -2.1565330014732495e-21 + 9.601425719058762e-19, + -2.1565329663948987e-21 ], [ - 9.70956146500539e-19, - 1.3659513735820777e-20 + 9.695646767327954e-19, + 1.365951378037891e-20 ], [ - 1.0148287942345546e-18, - 4.012886065986198e-20 + 1.0131787845741972e-18, + 4.012886071648405e-20 ], [ - 1.1289409519817779e-18, - 1.5874354177002784e-19 + 1.1270190672482143e-18, + 1.5874354184171196e-19 ], [ - 1.4086943325709482e-18, - -7.362716571940238e-20 + 1.4065067982159647e-18, + -7.362716562948129e-20 ], [ - 1.9756652988283737e-18, - 8.220870869945534e-21 + 1.9732490173428855e-18, + 8.220870980929903e-21 ], [ - -3.047814989074322e-18, - -1.475653881028654e-19 + -3.0503798838708888e-18, + -1.4756538796926845e-19 ], [ - -9.696709717703793e-19, - 8.140877176609442e-20 + -9.722495963341885e-19, + 8.140877192119449e-20 ], [ - 1.5663895639122053e-18, - 8.841894575734116e-22 + 1.5639930692322277e-18, + 8.841896287023448e-22 ], [ - 1.227677058260553e-18, - -1.126450007528684e-19 + 1.2257148447781425e-18, + -1.126450005771447e-19 ], [ - 9.968198194457685e-19, - 2.8097775250195794e-20 + 9.95579466000172e-19, + 2.8097775412422253e-20 ], [ - 8.876939657377426e-19, - -3.76024809759545e-20 + 8.874595829805539e-19, + -3.7602480850836796e-20 ], [ - 8.736550930361877e-19, - -1.8287638772962435e-18 + 8.746552547574639e-19, + -1.828763877233806e-18 ], [ - 9.585891600739233e-19, - 3.6313931784742388e-19 + 9.609443448978501e-19, + 3.631393178252241e-19 ], [ - 1.1646753447640704e-18, - -9.92554770936216e-20 + 1.1683620444238827e-18, + -9.92554772128629e-20 ], [ - 1.5259605982478805e-18, - -1.2967499509224685e-18 + 1.5308062202117664e-18, + -1.29674995113764e-18 ], [ - 2.0871022975116867e-18, - -1.2019077690616972e-17 + 2.0928143682141664e-18, + -1.2019077690913214e-17 ], [ - 2.906365569039111e-18, - 2.223645119338119e-18 + 2.9125857448632365e-18, + 2.2236451189857965e-18 ], [ - 4.0612575281588785e-18, - -2.1777773570678477e-19 + 4.0676227121231255e-18, + -2.1777773608595343e-19 ], [ - 5.6584278844688414e-18, - -2.463020815718137e-18 + 5.66462114766529e-18, + -2.463020816096556e-18 ], [ - 7.845834738977219e-18, - -1.904930781883016e-17 + 7.851615944011747e-18, + -1.9049307819185998e-17 ], [ - 1.0828838548740022e-17, - -4.2522298953464266e-16 + 1.0834053483123648e-17, + -4.252229895349616e-16 ], [ - 1.4890465395143536e-17, - 1.3724679662300886e-16 + 1.4895038517295147e-17, + 1.372467966227339e-16 ], [ - 2.0418811321602676e-17, - 1.7217512101341068e-17 + 2.0422729457851037e-17, + 1.7217512101111436e-17 ], [ - 2.794183682969891e-17, - 1.9244161608342477e-18 + 2.794513028521454e-17, + 1.924416160647335e-18 ], [ - 3.8172590650813934e-17, - -5.097466160618452e-18 + 3.817531595818344e-17, + -5.097466160767432e-18 ], [ - 5.2065473839829036e-17, - -1.3236163572882373e-17 + 5.206770013245933e-17, + -1.3236163572999106e-17 ], [ - 7.088060031812735e-17, - -2.7556026062668368e-17 + 7.088239971904958e-17, + -2.755602606275857e-17 ], [ - 9.624538367520965e-17, - -5.683807668571083e-17 + 9.624682521731065e-17, + -5.683807668577973e-17 ], [ - 1.3018257908557416e-16, - -1.2150037699277307e-16 + 1.3018372534989274e-16, + -1.215003769928252e-16 ] ], "effective_area": [ - 5.192957818859075e-11, - 4.605776521996268e-11, - 4.4110359356665834e-11, - 4.299384128723961e-11, - 4.217488632703423e-11, - 4.148055515406011e-11, - 4.0832675940661685e-11, - 4.0184363272841637e-11, - 3.949731352630616e-11, - 3.8729204292009055e-11, - 3.782182206523399e-11, - 3.6684474945446865e-11, - 3.516657228144016e-11, - 3.301214379073799e-11, - 2.980977364615425e-11, - 2.5255021701144024e-11, - 2.621342715369101e-11, - -2.3999073628646095e-10, - -1.1991753313295601e-09, - 2.925653924695207e-10, - 1.820250070764825e-10, - 1.5396472145390456e-10, - 1.4235194192198092e-10, - 1.3482866718722605e-10, - 1.2694318146245773e-10, - 1.1706440823501216e-10, - 1.0527637704344583e-10, - 9.258464023555111e-11, - 8.012746355922869e-11, - 6.870106352085409e-11, - 5.867018612200991e-11, - 5.0084833791755964e-11, - 4.28279244894467e-11, - 3.672042197788478e-11, - 3.157831397905155e-11, - 2.723710135407597e-11, - 2.355890301839211e-11, - 2.0431771131937484e-11, - 1.776626436141798e-11, - 1.5491611428744703e-11 + 5.2183503708087317e-11, + 4.6269113717385463e-11, + 4.4315430131309016e-11, + 4.319980698542963e-11, + 4.2384240789051604e-11, + 4.169424430266776e-11, + 4.105086237708058e-11, + 4.040663626794107e-11, + 3.972269208877822e-11, + 3.895601218718739e-11, + 3.80474340853929e-11, + 3.6904895790116134e-11, + 3.537579439312999e-11, + 3.320130594609814e-11, + 2.996671464120093e-11, + 2.5368483362912674e-11, + 2.6335211057161887e-11, + -2.3040974878565996e-10, + -9.987229198413213e-10, + 3.0680121804066403e-10, + 1.8703096733641073e-10, + 1.57184918281388e-10, + 1.4476889023658195e-10, + 1.3668139352906827e-10, + 1.2830722496680205e-10, + 1.1800081978919055e-10, + 1.058711041511902e-10, + 9.29365846879581e-11, + 8.032437047308999e-11, + 6.88068590339787e-11, + 5.872549491934687e-11, + 5.0113239480589284e-11, + 4.2842348449462314e-11, + 3.672769292664985e-11, + 3.158196153056036e-11, + 2.7238925128651295e-11, + 2.3559812761552673e-11, + 2.043222419012543e-11, + 1.776648977256134e-11, + 1.5491723569067303e-11 ] }, { @@ -2301,405 +2302,405 @@ ], "refractivity": [ [ - 0.006647796517180504, - 4.709151616945765e-08 + 0.006647801312081203, + 4.7091515948862636e-08 ], [ - 0.005906197207709241, - 4.439171422062205e-08 + 0.005906202944337524, + 4.4391713971469356e-08 ], [ - 0.005247041774486982, - 4.184669765461522e-08 + 0.005247048636026763, + 4.184669737330181e-08 ], [ - 0.004661127959788569, - 3.9447592412897763e-08 + 0.004661136165002411, + 3.94475920953676e-08 ], [ - 0.004140275304961971, - 3.718603313149107e-08 + 0.004140285115071585, + 3.718603277317885e-08 ], [ - 0.0036772100261146523, - 3.505413382824044e-08 + 0.003677221753015214, + 3.505413342400821e-08 ], [ - 0.003265459590411357, - 3.304445960974046e-08 + 0.0032654736064732237, + 3.30444591538063e-08 ], [ - 0.002899225488948831, - 3.114998928945111e-08 + 0.0028992422387144057, + 3.114998877530891e-08 ], [ - 0.0025739571611109735, - 2.9367963006129653e-08 + 0.0025739771752504303, + 2.9367962426458914e-08 ], [ - 0.002283865278534414, - 2.768075513607008e-08 + 0.0022838891904954917, + 2.768075448263445e-08 ], [ - 0.0020269192045434536, - 2.6250586785352066e-08 + 0.0020269477704140115, + 2.6250586048885363e-08 ], [ - 0.0017965731610201097, - 2.459793208993404e-08 + 0.0017966072832227287, + 2.4597931260012077e-08 ], [ - 0.0015917685236950252, - 2.3187923918415382e-08 + 0.0015918092792470695, + 2.318792298331193e-08 ], [ - 0.0014120031194635452, - 2.1873485071499026e-08 + 0.0014120517936868637, + 2.1873484018023927e-08 ], [ - 0.0012473111565891593, - 2.0605631385037164e-08 + 0.001247369283308819, + 2.0605630198354417e-08 ], [ - 0.0011017307073413196, - 1.9424525549196348e-08 + 0.001101800116825702, + 1.9424524212619673e-08 ], [ - 0.0009707744758284953, - 1.831763097113638e-08 + 0.0009708573519520147, + 1.83176294658995e-08 ], [ - 0.0008574355908550491, - 1.726717244345523e-08 + 0.0008575345392536349, + 1.7267170748453737e-08 ], [ - 0.0007519010345196087, - 1.6272952125897082e-08 + 0.000752019163843265, + 1.627295021739837e-08 ], [ - 0.0006574897910327504, - 1.5340627638824376e-08 + 0.0006576308098020789, + 1.5340625490141678e-08 ], [ - 0.0005717883196709739, - 1.4467052518771254e-08 + 0.0005719566517188301, + 1.4467050099897305e-08 ], [ - 0.00048649999188388193, - 1.6702314261635736e-08 + 0.000486700913930882, + 1.6702311538830996e-08 ], [ - 0.00043000208482046887, - 1.2876545615895264e-08 + 0.00043024189040208327, + 1.2876542551224986e-08 ], [ - 0.00036415128625399973, - 1.2123503695396549e-08 + 0.00036443748101255835, + 1.2123500246210143e-08 ], [ - 0.000304360225153788, - 1.1429407664833834e-08 + 0.0003047017594519641, + 1.1429403783179091e-08 ], [ - 0.00024858906195546204, - 1.0783421252826098e-08 + 0.0002489966078809136, + 1.0783416884789715e-08 ], [ - 0.0001951689998958006, - 1.0208400417393624e-08 + 0.0001956552810391532, + 1.020839550235818e-08 ], [ - 0.00013892854840902302, - 1.1484810744501365e-08 + 0.00013950873235257788, + 1.148480521430721e-08 ], [ - 0.00011712144658515555, - 4.1969456948102576e-08 + 0.00011778996121614149, + 4.196945086891397e-08 ], [ - 0.00010224947400105933, - 3.0713961266273685e-08 + 0.00010294163927060396, + 3.071395504427225e-08 ], [ - 0.00011541143956228517, - 8.909005120333152e-08 + 0.00011610982417442628, + 8.909004494404534e-08 ], [ - 0.00012003677253669132, - 1.0476763037702127e-08 + 0.00012076683672335164, + 1.0476756590177677e-08 ], [ - 7.168299671356237e-05, - 8.800387549765243e-09 + 7.250868807795463e-05, + 8.800380549747706e-09 ], [ - 2.2199328689298525e-05, - 8.170172083364675e-09 + 2.3184217176064337e-05, + 8.17016420834654e-09 ], [ - -2.4345884600984746e-05, - 7.697374482629625e-09 + -2.3171217727657734e-05, + 7.697365623467564e-09 ], [ - -7.106889596253385e-05, - 7.297798501552615e-09 + -6.966802872232503e-05, + 7.297788535363995e-09 ], [ - -0.00011945434874194305, - 6.985678257474589e-09 + -0.00011778391516226172, + 6.985667045822198e-09 ], [ - -0.0001709966272011032, - 6.848233431914791e-09 + -0.0001690050107727714, + 6.848220818708343e-09 ], [ - -0.0002278804158395431, - 7.275581293488482e-09 + -0.00022550620467864935, + 7.275567102538962e-09 ], [ - -0.00029457799829391007, - 2.3906403108941505e-08 + -0.0002917481622125573, + 2.390638714108244e-08 ], [ - -0.00038595236428029533, - 1.0133376189091494e-07 + -0.00038258010929470565, + 1.0133374392057283e-07 ], [ - -0.0005501941166681235, - 3.676946808075778e-07 + -0.0005461763684563303, + 3.676946605786275e-07 ], [ - -0.0004954442315646679, - 1.5387704165980705e-06 + -0.0004906844596901383, + 1.538770393902293e-06 ], [ - -0.000505971918056014, - 2.7317650088771695e-06 + -0.0005011863835213681, + 2.731764986097842e-06 ] ], "derivative": [ [ - 1.4138210976667843e-18, - 4.999974745481867e-24 + 1.4138195501638087e-18, + 4.99997479384787e-24 ], [ - 1.333038316460749e-18, - 4.999971803301191e-24 + 1.3330363554860816e-18, + 4.9999718610829575e-24 ], [ - 1.2569413373106665e-18, - 4.9999685934491595e-24 + 1.2569388524690106e-18, + 4.999968662477344e-24 ], [ - 1.1852730018904927e-18, - 4.999965181442135e-24 + 1.1852698533818518e-18, + 4.999965263901505e-24 ], [ - 1.1177943688875662e-18, - 4.999961807438987e-24 + 1.1177903796768645e-18, + 4.9999619059370814e-24 ], [ - 1.0542872843014973e-18, - 4.99995944259927e-24 + 1.0542822302080654e-18, + 4.999959560248223e-24 ], [ - 9.945722817991758e-19, - 4.9999641608025324e-24 + 9.945658789531644e-19, + 4.999964301316634e-24 ], [ - 9.38832172554583e-19, - 5.000101107045017e-24 + 9.388240615210468e-19, + 5.0001012748570555e-24 ], [ - 8.891123480503718e-19, - 5.154866162366754e-24 + 8.891020737365844e-19, + 5.1548663627667714e-24 ], [ - 8.365256191119364e-19, - 4.999743281782971e-24 + 8.365126053392685e-19, + 4.999743521083719e-24 ], [ - 6.552911910937932e-19, - 5.799350605919648e-23 + 6.552747084193053e-19, + 5.799350634493075e-23 ], [ - 7.46407309307466e-19, - 4.999939600441983e-24 + 7.463864343059001e-19, + 4.9999399415979e-24 ], [ - 7.065185025963113e-19, - 4.997505925439997e-24 + 7.06492066339828e-19, + 4.9975063327416e-24 ], [ - 7.13825075737799e-19, - 6.323230329735024e-24 + 7.137915986125716e-19, + 6.3232308159768145e-24 ], [ - 6.32762834470579e-19, - 5.0007797826172e-24 + 6.327204437134053e-19, + 5.000780363063028e-24 ], [ - 6.001893812018189e-19, - 4.997002941315552e-24 + 6.001357065848703e-19, + 4.9970036341742255e-24 ], [ - 5.824103886170105e-19, - 4.81508126118526e-24 + 5.823424305025117e-19, + 4.815082088177583e-24 ], [ - 5.555321584383742e-19, - 5.100971375255898e-24 + 5.554461209016986e-19, + 5.100972362290752e-24 ], [ - 5.176112285135167e-19, - 5.0025755467848215e-24 + 5.175023083101465e-19, + 5.0025767247652856e-24 ], [ - 4.952697534968055e-19, - 4.991054135617403e-24 + 4.951318732217806e-19, + 4.9910555414019925e-24 ], [ - 4.817458321173969e-19, - 4.9062135831432055e-24 + 4.815713028445521e-19, + 4.90621526069221e-24 ], [ - 6.419462454745249e-19, - 3.2721588804192414e-22 + 6.417253403029366e-19, + 3.27215890043667e-22 ], [ - 4.666187800996427e-19, - 5.339218612984267e-24 + 4.663391951708292e-19, + 5.3392210014509e-24 ], [ - 4.356808828083487e-19, - 5.024157587142209e-24 + 4.353270562330614e-19, + 5.0241604369103486e-24 ], [ - 4.2683405960074584e-19, - 4.973661490930442e-24 + 4.2638631102853583e-19, + 4.973664890950898e-24 ], [ - 4.2687002682979006e-19, - 4.872201882406725e-24 + 4.2630347071025987e-19, + 4.87220593878228e-24 ], [ - 4.437400521132687e-19, - 4.2013792293787904e-24 + 4.430232255433342e-19, + 4.201384068688182e-24 ], [ - 5.746281008599693e-19, - -1.2232651930898462e-22 + 5.737212316822838e-19, + -1.2232651353570568e-22 ], [ - 1.2073550047976878e-18, - 9.476719244378885e-21 + 1.2062597380888188e-18, + 9.476719251031025e-21 ], [ - -1.5008248675274913e-18, - -3.2473946338163337e-21 + -1.501972045750077e-18, + -3.2473946269288177e-21 ], [ - -3.019185428820446e-18, - 1.191090522597077e-22 + -3.020346356960056e-18, + 1.1910905920912586e-22 ], [ - 9.748674950524206e-19, - 9.011948111926587e-23 + 9.736359020667e-19, + 9.011948838402538e-23 ], [ - 5.3860951935996005e-19, - 8.518754828129594e-24 + 5.371585161119248e-19, + 8.518763045125909e-24 ], [ - 4.983173778560527e-19, - 5.486635566585811e-24 + 4.964823119527521e-19, + 5.48664537019838e-24 ], [ - 5.1976360323395e-19, - 4.872128560210703e-24 + 5.174431433839443e-19, + 4.8721402578437554e-24 ], [ - 5.629937634466269e-19, - 4.310195709406383e-24 + 5.60059984923882e-19, + 4.3102096689077025e-24 ], [ - 6.269676375319146e-19, - 3.149856004702644e-24 + 6.2325911224261425e-19, + 3.1498726668023053e-24 ], [ - 7.194680320438373e-19, - -3.0087113702390935e-25 + 7.147811604099328e-19, + -3.008512433980493e-25 ], [ - 8.618102178483252e-19, - -1.6417485709953715e-23 + 8.558883769009844e-19, + -1.6417461948647706e-23 ], [ - 1.1240021377833085e-18, - -4.490666216488615e-21 + 1.1165221305060557e-18, + -4.490666188092345e-21 ], [ - 1.8962509828923404e-18, - -4.862310214112461e-22 + 1.8868061751486864e-18, + -4.862309874511716e-22 ], [ - -5.788689006241674e-18, - -5.903118216535576e-20 + -5.8006095762077165e-18, + -5.903118212470214e-20 ], [ - 6.091916563356596e-18, - -5.56753273303275e-19 + 6.076986598343746e-18, + -5.567532732548185e-19 ], [ - 6.1483593342754494e-18, - -6.815712246880972e-19 + 6.133321990449504e-18, + -6.815712246393677e-19 ] ], "effective_area": [ - 8.827033787570274e-10, - 8.80808953670676e-10, - 8.789569013558325e-10, - 8.770763325189492e-10, - 8.750647305285276e-10, - 8.727253075930561e-10, - 8.695058629388515e-10, - 8.620054123799973e-10, - 8.894237493888052e-10, - 8.656493904735957e-10, - 9.161794102456172e-10, - 8.725923263129762e-10, - 8.593964246668295e-10, - 9.617190811479862e-10, - 8.746893946467564e-10, - 8.625240533944755e-10, - 8.347441824371792e-10, - 9.052446913258771e-10, - 8.744065114675974e-10, - 8.625828571090693e-10, - 8.462559492593099e-10, - 7.446509324893383e-10, - 9.096168129774147e-10, - 8.79455019516812e-10, - 8.666745692187136e-10, - 8.548649563307939e-10, - 8.374391431126342e-10, - 7.904438986016801e-10, - 8.888609780570521e-10, - 8.511102719440839e-10, - 9.547919743915073e-10, - 1.0835588331784428e-09, - 9.35295329965161e-10, - 8.959124929325556e-10, - 8.787464145091418e-10, - 8.662801522444274e-10, - 8.544292877369579e-10, - 8.409743035316249e-10, - 8.233116303306047e-10, - 7.960860182616435e-10, - 7.41897035804936e-10, - 6.280470699653525e-10, - 7.8291176898933e-10, - 7.716572603508884e-10 + 8.835554568191875e-10, + 8.817103456468146e-10, + 8.799103790051185e-10, + 8.780846834489248e-10, + 8.761306491758495e-10, + 8.738510978076407e-10, + 8.706923492419867e-10, + 8.632433861816299e-10, + 8.908229308178012e-10, + 8.670561977467961e-10, + 9.178521866071839e-10, + 8.742026643542548e-10, + 8.610540926281884e-10, + 9.639225974023891e-10, + 8.766232242098559e-10, + 8.645193005001556e-10, + 8.367269042660165e-10, + 9.077192106766767e-10, + 8.768557924043212e-10, + 8.651113903188738e-10, + 8.488375903769943e-10, + 7.467705518195375e-10, + 9.129738603701468e-10, + 8.827831835891161e-10, + 8.701025062630479e-10, + 8.584019627900425e-10, + 8.410385322872098e-10, + 7.938436485455958e-10, + 8.933697977739165e-10, + 8.552913631916255e-10, + 9.600726176837897e-10, + 1.0904661105530547e-09, + 9.406518347228559e-10, + 9.011224001435696e-10, + 8.840596866555333e-10, + 8.717535996984667e-10, + 8.600729770340687e-10, + 8.467684163410168e-10, + 8.291958206169707e-10, + 8.019138606291403e-10, + 7.472563077431549e-10, + 6.321101343171203e-10, + 7.895965769340059e-10, + 7.781619300201496e-10 ] } ] diff --git a/tests/driver/snapshot_worker.py b/tests/driver/snapshot_worker.py index b7aee098c..be75be67d 100644 --- a/tests/driver/snapshot_worker.py +++ b/tests/driver/snapshot_worker.py @@ -20,9 +20,9 @@ HDF5Output, SnapshotController, TDSEArchive, + read_resume_state, read_snapshot, restore_snapshot, - resume, ) from solprop.output import snapshots as module from solprop.output.tdse_archive import TDSEArchiveWriter @@ -72,14 +72,14 @@ def main(): fake.response = alpha_law(1.0, lambda5=2.0**-200) if phase == "restore": files = restore_snapshot(sys.argv[3], directory / "restored") - before = resume(files.output) + before = read_resume_state(files.output) _run( _simulation(), files.output, resume=True, tdse_archive=files.tdse_archive, ) - after = resume(files.output) + after = read_resume_state(files.output) assert before.outcome is not None and after.outcome is not None assert after.outcome.status == "complete" assert ( @@ -116,7 +116,7 @@ def signal_once(): assert controller.last_result.generation is not None assert controller.last_result.disposition == "published" info = read_snapshot(controller.last_result.generation) - stopped = resume(directory / "working.h5") + stopped = read_resume_state(directory / "working.h5") assert stopped.outcome is not None assert stopped.outcome.status == "failed" and stopped.march is not None assert info.z == stopped.outcome.z diff --git a/tests/driver/test_abandoned_step.py b/tests/driver/test_abandoned_step.py index 8f2db76bc..fd09c644e 100644 --- a/tests/driver/test_abandoned_step.py +++ b/tests/driver/test_abandoned_step.py @@ -24,7 +24,12 @@ from solprop.driver.run import run_problem from solprop.exceptions import DriverError, StopRequested from solprop.log import NullReporter -from solprop.output import MemoryOutput, SnapshotController, open_file, resume +from solprop.output import ( + MemoryOutput, + SnapshotController, + open_file, + read_resume_state, +) from solprop.stepper import FixedSchedule, LowStorageRungeKutta # A soliton in a tight window, without a collar: its edges are not what is tested here. @@ -267,7 +272,8 @@ def test_a_step_abandoned_after_a_running_checkpoint_falls_back_to_it( # the matched march's rounding budget (SEP 25). for name in ("z", "h", "accepted"): assert np.array_equal( - getattr(resume(path).history, name), getattr(resume(whole).history, name) + getattr(read_resume_state(path).history, name), + getattr(read_resume_state(whole).history, name), ), name with open_file(path) as stored, open_file(whole) as reference: assert stored.terminal_checkpoint is None diff --git a/tests/driver/test_coherent_capillary.py b/tests/driver/test_coherent_capillary.py index 1e181621c..b1a3306f4 100644 --- a/tests/driver/test_coherent_capillary.py +++ b/tests/driver/test_coherent_capillary.py @@ -58,7 +58,7 @@ from solprop.backends.exponential import FLOW_MAX_SQUARINGS from solprop.backends.numpy_ref import NumpyRefBackend from solprop.backends.numpy_ref.coupled_flow import _triangular_exponential -from solprop.boundaries import absorber +from solprop.boundaries import absorber, no_absorber from solprop.constants import EPS0, C from solprop.driver import Simulation, prop_capillary from solprop.exceptions import ( @@ -345,6 +345,26 @@ def test_the_constructor_refuses_a_conditioning_bound_it_cannot_meet(): ) +def test_a_condition_limit_of_one_is_refused_by_name_not_by_a_domain_error(): + """One is the least limit a flow takes, and it admits no step against a spread.""" + block = np.zeros((2, 1, 2, 2, 3), dtype=complex) + block[:, 0, 0, 0], block[:, 0, 1, 1], block[:, 0, 0, 1] = -1.0, -3.0, 50.0 + with pytest.raises( + TranslationError, match="a limit of one admits no positive step" + ): + frozen_residual_flow( + np.linspace(1e15, 2e15, 3), + np.array([0.0, 5e-4, 1e-3]), + block, + None, + dz_max=1e-1, + condition_limit=1.0, + representation_error=0.0, + gauge_id="lab", + certificate_id="frozen-residual", + ) + + def test_the_constructor_checks_its_own_arguments(): """A bad generator shape, dz_max or limit is named before anything is decomposed.""" omega = np.array([2.3e15, 2.4e15]) @@ -424,7 +444,7 @@ def test_the_route_records_its_flow_on_the_modal_identity(): assert record["residual_norm_bound"] == 0.0 assert record["radius"] == RADIUS assert 0.0 < float(cast("float", record["quasi_static"])) < 0.25 - assert metadata.schema_version == 4 + assert metadata.schema_version == 3 assert capability_of(metadata) == "modal" assert "mean impedance coherent wall" in str(metadata) # Nothing that is not a scalar reaches the resume key. @@ -669,13 +689,25 @@ def test_the_wall_block_refuses_a_mode_set_it_is_not_derived_for(modes, expected def test_the_default_glass_asked_for_by_name_is_the_same_guide(): - wall_operator( - [ - MarcatiliMode(RADIUS, "He", 1.0, m=1), - MarcatiliMode(RADIUS, "He", 1.0, m=2, cladding=fused_silica()), - ], - np.array([2.356e15, 2.4e15, 2.5e15]), - ) + """Naming the default cladding builds the default guide, alone or beside it.""" + omega = np.array([2.356e15, 2.4e15, 2.5e15]) + + def block(*claddings): + modes = [ + MarcatiliMode(RADIUS, "He", 1.0, m=m, cladding=cladding) + for m, cladding in enumerate(claddings, start=1) + ] + return wall_operator(modes, omega) + + default = block(None, None) + # The block reads its guide from the lowest channel, so the glass is named there + # too; beside the default it must not be refused as another cladding. + for claddings in ((fused_silica(), fused_silica()), (None, fused_silica())): + operator = block(*claddings) + # Exact: the same glass sampled by the same code is the same guide, not one + # that agrees to rounding. + for name in ("generator", "coupling", "wavenumber", "impedance"): + assert np.array_equal(getattr(operator, name), getattr(default, name)), name def test_a_varying_section_takes_the_frozen_residual_route(): @@ -1105,9 +1137,11 @@ def test_ten_steps_apply_the_block_the_translation_layer_declared(): pure exponential, so the only departure is the rounding of ten products of a Schur action by a scalar propagator. What this adds to the operator tests is that the step loop applies the operator it was given, in the right convention, - with the carrier and the block multiplied rather than added. + with the carrier and the block multiplied rather than added. The case's weak + collar is left out: a single bin fills the whole window, collar included, and the + collar would take 2.2e-7 of its amplitude over this length. """ - simulation = capillary(wall=CoherentWall(), modes=1) + simulation = capillary(wall=CoherentWall(), modes=1, absorber=no_absorber(GRID)) problem = simulation.translate() flow = problem.linear.coupled_flow assert flow is not None @@ -1333,11 +1367,13 @@ def test_the_flow_record_survives_a_file_and_a_resume_checks_it(tmp_path): @pytest.mark.medium @pytest.mark.parametrize("entry", ["prop_capillary", "prop_gnlse"]) @pytest.mark.parametrize("backend", ["numpy_ref", "native"]) -def test_the_prop_entry_points_are_what_they_were(entry, backend, ndarrays_regression): - """Ten steps of each entry point are the run they were, on every backend here. +def test_the_prop_entry_points_match_their_recorded_final_states( + entry, backend, ndarrays_regression +): + """Ten steps of each entry point match their recorded final state, on each backend. - A wall is an **opt-in** leaf, so a run that declares none must be the run it was - before the leaf existed. The final plane matches its record within the matched + A wall is an **opt-in** leaf, so a run that declares none is the run without the + leaf. The final plane matches its record within the matched march's rounding budget (``tests/state_records.py``), which a change to the route's operator above rounding exceeds. diff --git a/tests/driver/test_coherent_capillary/test_the_prop_entry_points_are_what_they_were_numpy_ref_prop_capillary_.npz b/tests/driver/test_coherent_capillary/test_the_prop_entry_points_match_their_recorded_final_states_numpy_ref_prop_capillary_.npz similarity index 100% rename from tests/driver/test_coherent_capillary/test_the_prop_entry_points_are_what_they_were_numpy_ref_prop_capillary_.npz rename to tests/driver/test_coherent_capillary/test_the_prop_entry_points_match_their_recorded_final_states_numpy_ref_prop_capillary_.npz diff --git a/tests/driver/test_coherent_capillary/test_the_prop_entry_points_are_what_they_were_numpy_ref_prop_gnlse_.npz b/tests/driver/test_coherent_capillary/test_the_prop_entry_points_match_their_recorded_final_states_numpy_ref_prop_gnlse_.npz similarity index 100% rename from tests/driver/test_coherent_capillary/test_the_prop_entry_points_are_what_they_were_numpy_ref_prop_gnlse_.npz rename to tests/driver/test_coherent_capillary/test_the_prop_entry_points_match_their_recorded_final_states_numpy_ref_prop_gnlse_.npz diff --git a/tests/driver/test_entrance_only_resume.py b/tests/driver/test_entrance_only_resume.py index 3e4ceb8df..19653a4b1 100644 --- a/tests/driver/test_entrance_only_resume.py +++ b/tests/driver/test_entrance_only_resume.py @@ -8,7 +8,7 @@ from numpy.testing import assert_allclose, assert_array_equal from solprop.driver import Simulation -from solprop.output import MemoryOutput, open_file, resume +from solprop.output import MemoryOutput, open_file, read_resume_state from solprop.output.metadata import INTERPOLATED_RESUMES_ANNOTATION from solprop.stats import StatsSpec from solprop.stepper.multistep import Multistep @@ -43,7 +43,7 @@ def test_entrance_without_terminal_checkpoint_resumes_dense_run_normally(tmp_pat path = tmp_path / "entrance-only.h5" # A file written from a MemoryOutput has its planes but no terminal checkpoint. entrance_only.to_file(path) - state = resume(path) + state = read_resume_state(path) assert state.n_saved == 1 assert state.plane.z == 0.0 assert state.history.n_steps == 0 diff --git a/tests/driver/test_envelope_harmonic.py b/tests/driver/test_envelope_harmonic.py index 3c09fb0ff..56264a977 100644 --- a/tests/driver/test_envelope_harmonic.py +++ b/tests/driver/test_envelope_harmonic.py @@ -40,7 +40,7 @@ OMEGA0 = 2.0 * np.pi * C / WAVELENGTH -def harmonic_fraction(kind: str) -> float: +def harmonic_fraction(kind: str, backend: str) -> float: """Return the energy fraction within 2.6-3.4 omega0 after the short capillary.""" limits, window = (250e-9, 4e-6), 1.2e-12 if kind == "field": @@ -64,7 +64,7 @@ def harmonic_fraction(kind: str) -> float: rtol=1e-8, atol=1e-10, n_save=2, - backend="native", + backend=backend, thg=True, ) output = simulation.run(progress="none") @@ -97,10 +97,17 @@ def weak_conversion_fraction() -> float: return float(coupling**2 * (f4 / f2) ** 2 * peak_sq**2 / np.sqrt(3.0)) -def test_the_envelope_harmonic_matches_the_field_grid_and_the_estimate(): - pytest.importorskip("solprop_native") - field = harmonic_fraction("field") - envelope = harmonic_fraction("envelope") +# On the reference as well as native: the estimate is the oracle both backends' harmonic +# terms answer to, and parity alone cannot see a term both get wrong. Medium on the +# reference, whose two runs take about 2.5 s. +@pytest.mark.parametrize( + "backend", ["native", pytest.param("numpy_ref", marks=pytest.mark.medium)] +) +def test_the_envelope_harmonic_matches_the_field_grid_and_the_estimate(backend): + if backend == "native": + pytest.importorskip("solprop_native") + field = harmonic_fraction("field", backend) + envelope = harmonic_fraction("envelope", backend) estimate = weak_conversion_fraction() # Measured: the two grids agree to 1e-4 and the estimate to 0.3 %, the difference # being the dispersion and self-phase modulation the estimate leaves out. The diff --git a/tests/driver/test_envelope_plasma.py b/tests/driver/test_envelope_plasma.py index e268bacb5..2a613dd7c 100644 --- a/tests/driver/test_envelope_plasma.py +++ b/tests/driver/test_envelope_plasma.py @@ -26,7 +26,7 @@ from solprop.nonlinear.raman import RamanResponse from solprop.nonlinear.responses import KerrResponse from solprop.output import open_file -from solprop.output.hdf5 import resume +from solprop.output.hdf5 import read_resume_state from solprop.physdata import Mixture from solprop.processing import node_fluence, species_ionisation from solprop.stats import StatsSpec @@ -211,7 +211,7 @@ def test_envelope_hdf5_resume_and_reconstruction( whole = build(**options).run(progress="none") path = tmp_path / "envelope.h5" run_until(build(**options), path, after=1) - continued = resume(path).march is not None + continued = read_resume_state(path).march is not None build(**options).run(path, resume=True, progress="none") with open_file(path) as restored: scale = float(np.max(np.abs(whole.fields()))) @@ -254,7 +254,7 @@ def test_envelope_hdf5_resume_and_reconstruction( budget = max(budget, fresh) np.testing.assert_allclose(actual, expected, rtol=0, atol=budget * scale) assert restored.metadata is not None - assert restored.metadata.schema_version == 4 + assert restored.metadata.schema_version == 3 assert restored.metadata.configuration["statistic_rate_conventions"] == { "peak_ionisation_rate": "cycle-averaged", "species_peak_ionisation_rate": "cycle-averaged", diff --git a/tests/driver/test_field_free_planes.py b/tests/driver/test_field_free_planes.py index 56ce3b08b..6389ab100 100644 --- a/tests/driver/test_field_free_planes.py +++ b/tests/driver/test_field_free_planes.py @@ -13,7 +13,6 @@ """ import dataclasses -import logging import math from typing import cast @@ -524,17 +523,6 @@ def observe(self, *, field): assert asked.index(True, 2) > asked.index(False, 2) -def test_no_saved_plane_logs_the_retired_collar_diagnostic(caplog): - # SEP 40 section 5.3 retires the end-of-plane collar diagnostic: the boundary - # monitor's transverse edge judges the boundary instead. - simulation = keeping(cartesian("numpy_ref"), "all") - with caplog.at_level(logging.INFO, logger="solprop.backends.numpy_ref.backend"): - output = stored(simulation.run(progress="none")) - assert not [r for r in caplog.records if "collar" in r.message] - assert output.outcome is not None - assert "collar_diagnostic_skipped" not in output.outcome.execution - - def test_a_field_free_observation_relies_on_the_step_loop_for_finiteness(): simulation = cartesian("numpy_ref") problem = simulation.translate() diff --git a/tests/driver/test_flow_collar.py b/tests/driver/test_flow_collar.py index 4aca00de8..50ef00fa9 100644 --- a/tests/driver/test_flow_collar.py +++ b/tests/driver/test_flow_collar.py @@ -347,9 +347,7 @@ def spied(monitor, crossing, *, can_rest): @pytest.mark.medium @pytest.mark.parametrize("name", BACKENDS) -def test_a_seeded_collar_no_longer_grows_towards_a_frozen_section_s_end( - transient, name -): +def test_a_seeded_collar_does_not_grow_towards_a_frozen_section_s_end(transient, name): """The collar transient of a long frozen section, reproduced in ten steps, and gone. At the end of a long frozen section the collar's residual reaches 7.3e3 1/m at diff --git a/tests/driver/test_general_gnlse.py b/tests/driver/test_general_gnlse.py index 27633124b..ecb996171 100644 --- a/tests/driver/test_general_gnlse.py +++ b/tests/driver/test_general_gnlse.py @@ -192,7 +192,7 @@ def test_scalar_reduction(): assert fibre(Constant(ENTRANCE_AREA)).z_constant -def test_a_constant_area_is_still_frozen_where_it_always_was(): +def test_a_constant_area_is_frozen_and_a_path_s_area_follows_it(): mode = fibre(ENTRANCE_AREA) assert mode.aeff() == mode.aeff(0.5) == ENTRANCE_AREA assert mode.radius(1.0) == mode.radius() diff --git a/tests/driver/test_general_modal.py b/tests/driver/test_general_modal.py index 7e3a5d312..07bd666b9 100644 --- a/tests/driver/test_general_modal.py +++ b/tests/driver/test_general_modal.py @@ -80,7 +80,7 @@ from solprop.noise import photons_per_bin from solprop.nonlinear.normalisation import modal_kerr_coefficient from solprop.nonlinear.raman import SilicaTensorResponse -from solprop.output.hdf5 import resume +from solprop.output.hdf5 import read_resume_state from solprop.output.memory import MemoryOutput from solprop.physdata import n2_from_chi3 from solprop.physdata.sellmeier import gamma as gas_susceptibility @@ -275,26 +275,6 @@ def test_the_gas_route_still_needs_a_gas_and_refuses_the_guide_keywords(): noise=None, integrator=Multistep(), ) - with pytest.raises(DriverError, match="observable_rtol= belongs to the general"): - Simulation.from_waveguide( - (), - GENERAL_Z_END, - "He", - wavelength=835e-9, - observable_rtol=1e-6, - noise=None, - integrator=Multistep(), - ) - with pytest.raises(DriverError, match="observable_atol= belongs to the general"): - Simulation.from_waveguide( - (), - GENERAL_Z_END, - "He", - wavelength=835e-9, - observable_atol=1e-16, - noise=None, - integrator=Multistep(), - ) with pytest.raises(DriverError, match="kerr_form= belongs to the general"): Simulation.from_waveguide( (), @@ -336,16 +316,6 @@ def test_an_envelope_grid_is_refused_at_the_entry_point(guide): build(guide, envelope) -@pytest.mark.parametrize("keyword", ["observable_rtol", "observable_atol"]) -def test_an_observable_tolerance_is_accepted_only_as_the_solvers_own( - guide, grid, keyword -): - """`None` means the solver's rtol and atol; a number is refused.""" - assert build(guide, grid, **{keyword: None}).general is not None - with pytest.raises(DriverError, match="is not implemented"): - build(guide, grid, **{keyword: 1e-7}) - - def test_a_guide_narrower_than_the_active_band_is_refused_at_construction(grid): narrow = general_guide( grid=FieldGrid.from_limits(GENERAL_Z_END, 835e-9, (830e-9, 840e-9), 60e-15) @@ -1197,8 +1167,8 @@ def test_an_hdf5_file_carries_the_labels_and_the_identities(guide, grid, tmp_pat path = tmp_path / "general.h5" simulation = build(guide, grid) simulation.run(path, progress="none") - stored = resume(path).metadata - assert stored.schema_version == 4 + stored = read_resume_state(path).metadata + assert stored.schema_version == 3 assert stored.modal is not None assert dict(stored.modal)["basis"] == "general_modal" labels = [dict(one.label) for one in stored.modes if one.label is not None] diff --git a/tests/driver/test_harmonic_frame.py b/tests/driver/test_harmonic_frame.py index c071b3b2f..d6f4bdfdb 100644 --- a/tests/driver/test_harmonic_frame.py +++ b/tests/driver/test_harmonic_frame.py @@ -17,15 +17,13 @@ import numpy as np import pytest -import solprop.driver.simulation as simulation_module import solprop.translate.assembly as assembly_module from solprop.backends.exponential import carrier_reference from solprop.constants import C from solprop.driver import Simulation, SimulationSettings -from solprop.exceptions import OutputError, TranslationError +from solprop.exceptions import TranslationError from solprop.grid import EnvelopeGrid, FieldGrid, RadialGrid from solprop.linear import Frame -from solprop.log import NullReporter from solprop.modes import PlanarGrid, SlabMode from solprop.nonlinear.raman import DampedOscillator, RamanResponse, undamped_dephasing from solprop.nonlinear.responses import KerrResponse @@ -254,48 +252,3 @@ def test_a_frame_the_compiled_carrier_disagrees_with_is_refused(thg, monkeypatch ) with pytest.raises(TranslationError, match="internal inconsistency"): capillary(thg=thg, raman=False).translate() - - -def test_only_a_run_whose_frame_the_rule_changed_records_it(): - # Every other run keeps the record, and so the digest, it had before. - changed = raman_harmonic_flag().metadata().configuration - assert changed["frame"] == Frame(envelope_grid(thg=False).omega0, True) - for thg, raman in ((False, True), (True, False), (False, False)): - configuration = capillary(thg=thg, raman=raman).metadata().configuration - assert "frame" not in configuration - - -class StoppedError(RuntimeError): - """What an interrupted run raises, standing in for a machine going away.""" - - -class StopAfterPlane(NullReporter): - """A reporter that stops the run once its first plane after the launch is saved.""" - - def __init__(self) -> None: - self.seen = 0 - - def plane(self, z, summary): - self.seen += 1 - if self.seen >= 2: - raise StoppedError - - -@pytest.mark.medium -def test_a_run_saved_under_the_earlier_frame_rule_is_not_resumed(tmp_path, monkeypatch): - # Before the frame followed the electronic responses alone, this run kept beta_0 - # and its record held no frame. Written with that record, it is refused by name - # rather than continued in another frame under the same digest. - path = tmp_path / "earlier.h5" - with monkeypatch.context() as earlier: - earlier.setattr( - simulation_module, "_frame_follows_the_electronic_rule", lambda *_: False - ) - with pytest.raises(StoppedError): - raman_harmonic_flag(length=0.01, n_save=4).run( - path, progress=StopAfterPlane() - ) - with pytest.raises(OutputError, match=r"configuration\.frame"): - raman_harmonic_flag(length=0.01, n_save=4).run( - path, resume=True, progress="none" - ) diff --git a/tests/driver/test_initial_z_and_checkpoint.py b/tests/driver/test_initial_z_and_checkpoint.py index 513f323a4..0d9e54bd6 100644 --- a/tests/driver/test_initial_z_and_checkpoint.py +++ b/tests/driver/test_initial_z_and_checkpoint.py @@ -15,6 +15,7 @@ from tests.driver.test_run import NullBackend from builders import load_reference +from march_bounds import assert_matched, march_bound from solprop.backends.ledger import CallLedger from solprop.backends.numpy_ref.session import HostSession from solprop.backends.numpy_ref.workspace import NumpyWorkspace @@ -51,9 +52,9 @@ RunOutcome, SavedPlane, StepHistory, - resume, + read_resume_state, ) -from solprop.output.hdf5 import ResumeState +from solprop.output.hdf5 import ResumeState, open_file from solprop.output.metadata import RunMetadata from solprop.output.records import Convention, TerminalCheckpoint from solprop.output.serialisation import serialise @@ -61,9 +62,10 @@ from solprop.pulses import GaussianPulse, SpatialPulse from solprop.spatial import SpatialMedium from solprop.stats import StatsSpec -from solprop.stepper import PIController +from solprop.stepper import FixedSchedule, PIController, RungeKutta from solprop.stepper.multistep import Multistep from solprop.translate import problem as problem_module +from solprop.translate.linop import power_weight_at from solprop.translate.routes import tdse_descriptor from solprop.translate.tdse import AtomicCallLedger @@ -447,6 +449,78 @@ def test_interior_input_uses_actual_z_modal_weight(): ) +@pytest.mark.medium +def test_a_resume_divides_the_stored_field_by_the_modal_weight_at_its_position( + tmp_path, +): + """A resumed run on a pressure gradient continues the uninterrupted one. + + The file stores the interface amplitude ``sqrt(Re n_eff(z)) a``, and a resume that + restores no march history (any Runge-Kutta method) starts from the stored field + divided by the weight at the plane's position. On a fixed schedule both runs then + take the same steps from the same state, so they agree to the matched march's + rounding budget (SEP 25). Argon rising to 10 bar moves the weight by about 2e-3 + over the fibre, eight decades above that budget, so a weight taken anywhere else + starts the continuation visibly mis-scaled. Medium: three short runs of a + single-mode capillary, about 4 s on the reference. + """ + length = 0.002 + planes = list(np.linspace(0.0, length, 5)[1:]) + + def built(): + return Simulation.from_capillary( + 100e-6, + length, + "Ar", + PressureGradient.two_point(length, 0.0, 10.0), + wavelength=800e-9, + wavelength_limits=(400e-9, 1.6e-6), + trange=60e-15, + fwhm=10e-15, + energy=1e-9, + plasma=False, + noise=None, + backend="numpy_ref", + integrator=RungeKutta(), + # A sixteen-step replay is far longer than the default collar's explicit + # stability limit; the split step integrates its rate exactly. + absorber_scheme="split_step", + schedule=FixedSchedule.uniform( + 0.0, length, length / 16, save_planes=planes + ), + n_save=5, + ) + + whole, interrupted = tmp_path / "whole.h5", tmp_path / "part.h5" + simulation = built() + simulation.run(whole, progress="none") + run_until(built(), interrupted, after=3) + position = read_resume_state(interrupted).plane.z + assert 0.0 < position < length + problem = simulation.translate() + mask = problem.grids.active_mask + shift = np.max( + np.abs( + power_weight_at(problem, position)[..., mask] + / power_weight_at(problem, 0.0)[..., mask] + - 1.0 + ) + ) + bound = march_bound(problem, simulation.run_request()) + # The weight at the resume's position must differ from the entrance's by far more + # than the budget, or a resume at the wrong position could pass. + assert shift > 1e6 * bound + built().run(interrupted, resume=True, progress="none") + with open_file(interrupted) as resumed, open_file(whole) as reference: + assert resumed["z"].tolist() == reference["z"].tolist() + assert_matched( + np.asarray(resumed["field"]), + np.asarray(reference["field"]), + bound, + what="field", + ) + + @pytest.mark.parametrize("z", [-1.0, np.nan, np.inf, 1e-5, 2e-5]) def test_interior_launch_refuses_invalid_position(z): simulation = tiny_simulation() @@ -477,7 +551,7 @@ def test_budget_stop_is_separate_and_resume_cannot_reset_its_budget(tmp_path): path = tmp_path / "budget.h5" with pytest.raises(ResponseBudgetError): simulation.run(path, progress="none") - stopped = resume(path) + stopped = read_resume_state(path) assert stopped.n_saved == 1 assert 0 < stopped.plane.z < 1e-5 assert stopped.checkpoint is not None and stopped.checkpoint.next_save_index == 0 @@ -485,7 +559,7 @@ def test_budget_stop_is_separate_and_resume_cannot_reset_its_budget(tmp_path): calls = stopped.outcome.logical_calls with pytest.raises(ResponseBudgetError): simulation.run(path, resume=True, progress="none") - again = resume(path) + again = read_resume_state(path) assert again.plane.z == stopped.plane.z assert again.outcome is not None and again.outcome.logical_calls == calls assert_array_equal(again.plane.field, stopped.plane.field) @@ -527,7 +601,7 @@ def test_resume_uses_checkpoint_position_and_rejects_inconsistent_index(tmp_path ) path = tmp_path / "checkpoint.h5" memory.to_file(path) - state = resume(path) + state = read_resume_state(path) backend = select( "numpy_ref", problem, run_request, grid=simulation.grid, modes=simulation.modes ) @@ -567,7 +641,7 @@ def test_ordinary_resume_without_outcome_restores_plane_and_starts_fresh_ledgers memory.save(SavedPlane(z=5e-6, field=simulation._field0)) path = tmp_path / "without-outcome.h5" memory.to_file(path) - state = resume(path) + state = read_resume_state(path) assert state.outcome is None backend = select( "numpy_ref", problem, run_request, grid=simulation.grid, modes=simulation.modes @@ -824,11 +898,11 @@ def fail_final(self, spec, z): monkeypatch.setattr(NumpyWorkspace, "stats", fail_final) with pytest.raises(DriverError, match="final statistics"): simulation.run(path, progress="none") - first = resume(path) + first = read_resume_state(path) assert first.n_saved == 1 and first.plane.z == 1e-5 monkeypatch.setattr(NumpyWorkspace, "stats", original) simulation.run(path, resume=True, progress="none") - finished = resume(path) + finished = read_resume_state(path) assert finished.n_saved == 2 assert finished.checkpoint is None assert finished.outcome is not None and finished.outcome.status == "complete" diff --git a/tests/driver/test_interrupts.py b/tests/driver/test_interrupts.py index bc8dd2ce6..f8f09ff4a 100644 --- a/tests/driver/test_interrupts.py +++ b/tests/driver/test_interrupts.py @@ -24,7 +24,7 @@ from solprop._interrupts import committing, handled, interruptible, raise_held from solprop.exceptions import RunTerminated from solprop.log import NullReporter -from solprop.output.hdf5 import open_file, resume +from solprop.output.hdf5 import open_file, read_resume_state # The fixtures here launch noise-free into time windows kept tight for speed, which # hold more than a millionth of the energy in their guards or collar: the boundary @@ -50,7 +50,7 @@ def step(self, z, dz, accepted): accepted and not self.done and z > self.planes[1] - and not any(np.isclose(z, one) for one in self.planes) + and not any(np.isclose(z, one, atol=0.0) for one in self.planes) ): self.done = True self.action() @@ -82,7 +82,7 @@ def test_an_exception_as_a_step_is_recorded_leaves_a_consistent_checkpoint( with pytest.raises(CrashError): build().run(part, progress=reporter) assert reporter.done - state = resume(part) + state = read_resume_state(part) assert state.checkpoint is not None and state.march is not None assert state.march.z == state.checkpoint.plane.z build().run(part, resume=True, progress="none") @@ -110,7 +110,7 @@ def test_sigterm_writes_the_run_s_state_and_a_resume_continues_it( assert stopped.value.code == 128 + signal.SIGTERM # The handler is the run's alone. assert signal.getsignal(signal.SIGTERM) is signal.SIG_DFL - state = resume(part) + state = read_resume_state(part) assert state.outcome is not None and state.outcome.status == "failed" assert "terminated by SIGTERM" in state.outcome.message assert state.checkpoint is not None and state.march is not None diff --git a/tests/driver/test_material_manifest.py b/tests/driver/test_material_manifest.py index b54b6ea70..35dac827e 100644 --- a/tests/driver/test_material_manifest.py +++ b/tests/driver/test_material_manifest.py @@ -567,7 +567,7 @@ def test_ten_steps_write_the_manifest_and_a_changed_identity_is_refused(tmp_path **{"noise": None, **options}, ) stored: Any = open_file(path).metadata - assert stored.schema_version == 4 + assert stored.schema_version == 3 assert names(stored.materials) == [ "eos/Ar", "fit/Ar", diff --git a/tests/driver/test_mixture_connected.py b/tests/driver/test_mixture_connected.py index be1a0d4c3..4d2e9ef9b 100644 --- a/tests/driver/test_mixture_connected.py +++ b/tests/driver/test_mixture_connected.py @@ -11,7 +11,6 @@ qualification of the air data in the ultraviolet. """ -import json from dataclasses import replace from itertools import pairwise @@ -110,6 +109,7 @@ def connected_simulation(ffac=6.0, *, passive=False): def assert_saved_accounting(simulation, output): + """Check a run's saved ionisation and absorption records; return its new ions.""" problem = simulation.translate() grid = simulation.grid # Each independent exposure is a non-negative trapezoid sum. The backend @@ -176,7 +176,7 @@ def assert_saved_accounting(simulation, output): output["stats/species_electron_density"], expected_electrons, rtol=bound, atol=0 ) np.testing.assert_array_equal(fractions[:, 2:], 0.0) - omega, absorbed = processing.absorbed_spectral_energy(output, species="absorber") + _, absorbed = processing.absorbed_spectral_energy(output, species="absorber") _, spectral = processing.get_spectral_density(output, axis="omega", band="active") np.testing.assert_allclose(absorbed[:, 0], 1e-4 * spectral, rtol=bound, atol=0) fluence = processing.node_fluence(output) @@ -184,16 +184,11 @@ def assert_saved_accounting(simulation, output): np.testing.assert_allclose( fluence, expected_fluence, rtol=bound, atol=bound * np.max(fluence) ) - return { - "rounding_bound": bound, - "omega_points": omega.size, - "inventory_J_per_m": inventory.tolist(), - "new_ions_per_m": np.sum(new_source * weights, axis=-1).tolist(), - } + return np.sum(new_source * weights, axis=-1) @pytest.mark.slow -def test_connected_air_saved_source_and_spectrum_converge(tmp_path): +def test_connected_air_saved_source_converges_with_the_fine_spacing(): # Refining the fine temporal spacing halves the exposure trapezoid's h^2 # defect. Compare successive differences on the unchanged coarse spectral # grid: the asymptotic ratio is 1/4; 1/2 allows the next-order remainder. @@ -201,11 +196,6 @@ def test_connected_air_saved_source_and_spectrum_converge(tmp_path): # comparison floor. This is a convergence test, not a physical UV error bar. ratio_bound = 0.5 floor = 100 * 1e-7 - budgets: dict[str, object] = { - "difference_ratio_bound": ratio_bound, - "controller_floor": floor, - } - (tmp_path / "bounds.json").write_text(json.dumps(budgets, indent=2)) outputs = [] records = [] for ffac in (6.0, 12.0, 24.0): @@ -213,23 +203,25 @@ def test_connected_air_saved_source_and_spectrum_converge(tmp_path): output = simulation.run() records.append(assert_saved_accounting(simulation, output)) outputs.append((simulation, output)) + sources = [record[:, :2] for record in records] + scale = np.linalg.norm(sources[-1]) + errors = [ + float(np.linalg.norm(right - left) / scale) for left, right in pairwise(sources) + ] + # Measured 7.1e-4 and 2.6e-8: the coarse difference stands clear of the floor, so + # the refinement's gain is not met by the floor alone. + assert errors[0] > 10 * floor, errors + assert errors[1] <= ratio_bound * errors[0] + floor, errors + # The saved spectrum does not move with the fine spacing here (measured 3.5e-13 + # and 5.2e-13 between levels), so it carries no convergence claim; the floor + # admits adaptive runs that place their steps differently. spectra = [ processing.get_spectral_density(output, axis="omega", band="active")[1] for _, output in outputs ] - sources = [np.array(record["new_ions_per_m"])[:, :2] for record in records] - for name, values in (("spectrum", spectra), ("source", sources)): - scale = np.linalg.norm(values[-1]) - errors = [ - float(np.linalg.norm(right - left) / scale) - for left, right in pairwise(values) - ] - budgets[name] = errors - (tmp_path / "measurements.json").write_text( - json.dumps(budgets | {"records": records}, indent=2) - ) - # Each refinement must at least halve the error, to a floor of 1e-5. - assert errors[1] <= ratio_bound * errors[0] + floor, (name, errors, budgets) + scale = np.linalg.norm(spectra[-1]) + for left, right in pairwise(spectra): + assert np.linalg.norm(right - left) / scale <= floor @pytest.mark.slow diff --git a/tests/driver/test_mixture_interface.py b/tests/driver/test_mixture_interface.py index eb80dcb7e..c2f5aa8d0 100644 --- a/tests/driver/test_mixture_interface.py +++ b/tests/driver/test_mixture_interface.py @@ -106,6 +106,7 @@ def test_mixture_optics_conflict_is_explicit(material_grid, fractions): 30e-6, grid.length, material, + 1.0 if fractions else None, wavelength=800e-9, grid=grid, fwhm=10e-15, diff --git a/tests/driver/test_moving_guide.py b/tests/driver/test_moving_guide.py index 359053a03..b05ba26b1 100644 --- a/tests/driver/test_moving_guide.py +++ b/tests/driver/test_moving_guide.py @@ -75,7 +75,7 @@ from solprop.modes.tables import apply_channel_basis, channel_area from solprop.nonlinear.gnlse import GnlseProblem, SpecifiedMode, _warn_surrogate_area from solprop.nonlinear.normalisation import modal_kerr_coefficient -from solprop.output.hdf5 import check_cache, resume +from solprop.output.hdf5 import check_cache, read_resume_state from solprop.output.memory import MemoryOutput from solprop.output.records import ModeRecord from solprop.processing.modal import ( @@ -229,7 +229,7 @@ def test_a_fixed_schedule_straddling_the_kink_is_refused(kinked): def test_a_run_longer_than_the_declared_path_is_refused(kinked): """The geometry is declared over the provider's z domain and not past it.""" - with pytest.raises((DriverError, TranslationError, Exception), match="path"): + with pytest.raises(ModeError, match=r"path covers \[0, 0\.001\] m"): moving_simulation( kinked, grin_grid(z_end=2 * LENGTH), length=2 * LENGTH ).translate() @@ -245,7 +245,7 @@ def test_a_resume_across_a_changed_path_is_refused_by_the_field_that_moved( first = moving_simulation(kinked, grid) first.settings = dataclasses.replace(first.settings, absorber=None) first.run(written, progress="none") - stored = resume(written).metadata + stored = read_resume_state(written).metadata other = moving_simulation(grin_taper(kinked_radius(), kerr=True, sections=2), grid) other.settings = dataclasses.replace(other.settings, absorber=None) metadata = other.metadata() diff --git a/tests/driver/test_native_flow_marches.py b/tests/driver/test_native_flow_marches.py index d05d7ddd6..431f6406b 100644 --- a/tests/driver/test_native_flow_marches.py +++ b/tests/driver/test_native_flow_marches.py @@ -46,7 +46,6 @@ # Noise-free launches into time windows kept tight for speed: the boundary monitor # warns (SEP 21), and the window's edge is not what this module tests. pytest.mark.filterwarnings("ignore::solprop.exceptions.BoundaryWarning"), - pytest.mark.filterwarnings("ignore::solprop.exceptions.HostMarchWarning"), ] diff --git a/tests/driver/test_native_flow_pathological.py b/tests/driver/test_native_flow_pathological.py index eb49947b0..e0c7ce31e 100644 --- a/tests/driver/test_native_flow_pathological.py +++ b/tests/driver/test_native_flow_pathological.py @@ -54,9 +54,6 @@ pytest.mark.filterwarnings("ignore:the temporal absorber attenuates"), # Windows kept tight for speed: the window's edge isn't what this module tests. pytest.mark.filterwarnings("ignore::solprop.exceptions.BoundaryWarning"), - # A bin off the eigenbasis route takes the host march, which is the route these - # tests form actions for and never step. - pytest.mark.filterwarnings("ignore::solprop.exceptions.HostMarchWarning"), ] solprop_native = pytest.importorskip("solprop_native") @@ -273,7 +270,13 @@ def capture(error, state, advanced, reference_mask, controller): scales = flow_parity.flow_scales(problem, run_request, grid, expected) bound = 2.0 * flow_parity.ten_step_bound(scales) assert new == pytest.approx(captured["partials"][1], rel=bound) - assert error == pytest.approx(captured["partials"][2], rel=bound) + # The error is a difference of two solutions, so its rounding is the state's: a + # departure of bound |y| in e moves |e|^2 by 2 bound |e| |y|. + assert error == pytest.approx( + captured["partials"][2], + rel=bound, + abs=2.0 * bound * np.sqrt(captured["partials"][2] * captured["partials"][1]), + ) def test_a_flow_on_a_wrapped_crop_is_refused_at_translation(): diff --git a/tests/driver/test_native_march_lifecycle.py b/tests/driver/test_native_march_lifecycle.py index e35483e31..698dc02d2 100644 --- a/tests/driver/test_native_march_lifecycle.py +++ b/tests/driver/test_native_march_lifecycle.py @@ -42,7 +42,7 @@ from solprop.cli import main from solprop.exceptions import ConvergenceError, ResponseBudgetError, RunTerminated from solprop.log import NullReporter -from solprop.output.hdf5 import open_file, resume +from solprop.output.hdf5 import open_file, read_resume_state from solprop.recipe import Recipe from solprop.stepper.multistep import Multistep @@ -80,7 +80,7 @@ def arming(self, backend, start): def assert_consistent_stop(part) -> None: """Assert the stopped run's checkpoint and march state belong to one position.""" - state = resume(part) + state = read_resume_state(part) assert state.checkpoint is not None and state.march is not None assert state.march.z == state.checkpoint.plane.z assert state.march.positions[-1] == state.march.z @@ -118,7 +118,7 @@ def test_a_native_failure_raises_its_class_at_the_last_accepted_step( # The startup sample was charged before it failed, and nothing was accepted: # the checkpoint is the entrance, with no history to keep. assert (ledger["startup"], ledger["accepted_steps"]) == (1, 0) - state = resume(part) + state = read_resume_state(part) assert state.checkpoint is not None and state.checkpoint.plane.z == 0.0 assert state.march is None return @@ -127,7 +127,7 @@ def test_a_native_failure_raises_its_class_at_the_last_accepted_step( orders = cast("list[list[int]]", ledger["orders"]) assert sum(count for _, count in orders) == ledger["accepted_steps"] assert_consistent_stop(part) - state = resume(part) + state = read_resume_state(part) assert state.march is not None assert state.march.z == state.outcome.z # pyright: ignore[reportOptionalMemberAccess] @@ -169,7 +169,7 @@ def test_a_failure_inside_a_trial_s_source_leaves_the_accepted_state( with pytest.raises(RuntimeError, match="an injected native failure"): build().run(part, progress="none") assert_consistent_stop(part) - stops[stage] = resume(part) + stops[stage] = read_resume_state(part) before, inside = stops["trial"], stops["trial_source"] assert before.checkpoint is not None and inside.checkpoint is not None assert before.march is not None and inside.march is not None @@ -248,7 +248,7 @@ def test_sigterm_during_a_native_call_waits_for_its_commit( with pytest.raises(RunTerminated): build().run(part, progress="none") assert calls.signalled(40) - state = resume(part) + state = read_resume_state(part) assert state.checkpoint is not None and state.march is not None # The call ran to its end before the signal was raised: the checkpoint is where # it returned, past where it began. @@ -614,7 +614,7 @@ def test_a_reporter_cannot_lose_the_failure_s_checkpoint( build().run(part, progress=reporter) assert not getattr(stopped.value, "__notes__", None) assert_consistent_stop(part) - state = resume(part) + state = read_resume_state(part) assert state.checkpoint is not None history = state.checkpoint.plane.step_history assert history.n_steps > 0 diff --git a/tests/driver/test_native_resume_history.py b/tests/driver/test_native_resume_history.py index 17f249684..22dd5d3c0 100644 --- a/tests/driver/test_native_resume_history.py +++ b/tests/driver/test_native_resume_history.py @@ -45,7 +45,7 @@ from solprop.driver import Simulation from solprop.grid import EnvelopeGrid from solprop.output import open_file -from solprop.output.hdf5 import resume +from solprop.output.hdf5 import read_resume_state from solprop.output.records import MarchSnapshot from solprop.stepper import FixedSchedule, LowStorageRungeKutta, Multistep, RungeKutta @@ -314,7 +314,7 @@ def test_a_resumed_native_run_is_the_uninterrupted_one( tmp_path / "tight.h5", ) run_until(build(), part, after=2) - state = resume(part) + state = read_resume_state(part) assert state.march is not None assert set(state.march.rows) == ROWS[case] # The resume decides in the simulation; the run's session installs the history. @@ -348,11 +348,13 @@ def test_a_native_run_stopped_between_planes_continues_from_its_checkpoint( with_fault(patch, "trial", 120, "backend") with pytest.raises(RuntimeError, match="an injected native failure"): build().run(part, progress="none") - state = resume(part) + state = read_resume_state(part) assert state.checkpoint is not None assert state.march is not None and state.march.z == state.checkpoint.plane.z stop = state.checkpoint.plane.z - assert stop > planes[1] and not any(np.isclose(stop, one) for one in planes) + assert stop > planes[1] and not any( + np.isclose(stop, one, atol=0.0) for one in planes + ) with caplog.at_level(logging.INFO, logger="solprop.driver"): build().run(part, resume=True, progress="none") assert AFRESH not in caplog.text @@ -539,7 +541,7 @@ def test_a_native_resume_under_modified_noise_continues_the_same_march( whole = build(**options).run(progress="none") path = tmp_path / "envelope.h5" run_until(build(**options), path, after=1) - stored = resume(path).march + stored = read_resume_state(path).march assert stored is not None # The snapshot installs losslessly beside the modified noise: a session resumed at # its plane, the plane owed, holds exactly the stored history there. diff --git a/tests/driver/test_native_rk_march.py b/tests/driver/test_native_rk_march.py index eba5e5a0a..b9cf9a028 100644 --- a/tests/driver/test_native_rk_march.py +++ b/tests/driver/test_native_rk_march.py @@ -4,20 +4,22 @@ """The native Runge-Kutta march on real fields (SEP 45 sections 4.9, 7.3; SEP 47). -Until SEP 47's phase 5 these runs were held bit for bit to solprop's Python loop on the -same build, selected by a private switch that phase retired with the loop's forcing -hooks (SEP 47 section 6.3). That comparison's diagnostic purpose is kept by two -independent checks: the march's decisions reproduce the recorded identical-input traces -exactly (``tests/backends/test_native_rk_traces.py``, ``tests/backends/rk_traces.py``), -and here each route's native session is the same run twice -- its steps, norms, fields -and boundary-monitor record bit for bit on one thread, where the reductions' order is -fixed -- and is held to ``numpy_ref``'s run of the same problem within a hundred times -the controller's relative tolerance of the field's peak. The two adaptive runs take -their own steps (SEP 25 class T), and each keeps its local error within the tolerance; -a hundred covers the error's growth over these short runs (measured at most 4.2e-8 of -the peak, against tolerances of 1e-6 and looser). The replays on a fixed schedule are -held to the reference by the catalogue's rows ``rk replay ...`` -(``backends/driver_rows.py``); here they take the schedule's steps exactly. +Each route's native session is run twice and is the same run -- its steps, norms, +fields and boundary-monitor record bit for bit on one thread, where the reductions' +order is fixed -- and is held to ``numpy_ref``'s run of the same problem within a +hundred times the controller's relative tolerance of the field's peak. The two adaptive +runs take their own steps (SEP 25 class T), and each keeps its local error within the +tolerance; a hundred covers the error's growth over these short runs (measured at most +4.2e-8 of the peak, against tolerances of 1e-6 and looser). + +That bound shows the native march runs each route and stays near the reference; it is +not a parity check of the physics: on these short probes the Kerr phase can move the +field by less than the bound, so a wrong nonlinear term may pass here. The terms are +held by the parity catalogue's guarded rows +(``tests/backends/test_parity_catalogue.py``), the replays on a fixed schedule by its +rows ``rk replay ...`` (``backends/driver_rows.py``), and the march's decisions by the +recorded identical-input traces (``tests/backends/test_native_rk_traces.py``, +``tests/backends/rk_traces.py``). """ from __future__ import annotations @@ -35,7 +37,7 @@ from rk_route_cases import replayed, runge_kutta_route from sessions.runs import load_native, native_trial from solprop.backends import available -from solprop.exceptions import BoundaryWarning, HostMarchWarning +from solprop.exceptions import BoundaryWarning from solprop.monitor import BoundaryCheck from solprop.stepper.controller import PIController from solprop.stepper.runge_kutta import RungeKutta @@ -73,7 +75,6 @@ def _run(build, backend: str = "native") -> dict[str, Any]: rtol = simulation.run_request().stepper.controller.rtol with warnings.catch_warnings(): warnings.simplefilter("ignore", BoundaryWarning) - warnings.simplefilter("error", HostMarchWarning) run = simulation.run(progress="none") outcome = run.outcome assert outcome is not None and outcome.execution is not None diff --git a/tests/driver/test_optmat_raman_runs.py b/tests/driver/test_optmat_raman_runs.py index 435e0c995..9ba7f4cee 100644 --- a/tests/driver/test_optmat_raman_runs.py +++ b/tests/driver/test_optmat_raman_runs.py @@ -101,7 +101,9 @@ def test_ten_steps_of_a_nitrogen_capillary_under_a_selection(): (entry,) = manifest.raman assert entry["groups"] == 43 assert entry["shift_phase_bound_rad"] is None - assert entry["window_s"] == pytest.approx(400e-15, rel=0.1) + # The grid's realised window, which from_limits rounds up from the 400 fs asked. + window = simulation.grid.n_t * simulation.grid.dt + assert entry["window_s"] == pytest.approx(window, rel=1e-10) @pytest.mark.medium diff --git a/tests/driver/test_parameter_paths.py b/tests/driver/test_parameter_paths.py index 8dffdc6c7..d9f1fc755 100644 --- a/tests/driver/test_parameter_paths.py +++ b/tests/driver/test_parameter_paths.py @@ -12,6 +12,7 @@ is run but the boundary monitor's: every refusal comes while the simulation is built. """ +import threading import warnings from collections.abc import Callable from typing import Any, cast @@ -332,6 +333,20 @@ def _parameters(records: pytest.WarningsRecorder) -> list[ParameterPath | None]: "pressure must be a number", id="capillary-pressure", ), + pytest.param( + lambda: _hollow(100e-6, 0.01, "He"), + DriverError, + "pressure", + "a gas fill needs its pressure", + id="capillary-gas-without-pressure", + ), + pytest.param( + lambda: _hollow(100e-6, 0.01, "air"), + DriverError, + "pressure", + "a gas fill needs its pressure", + id="capillary-air-without-pressure", + ), pytest.param( lambda: _hollow( 100e-6, 0.01, Mixture.fill({"He": 1.0}, 1.0), 1.0, pressure_floor=1e-3 @@ -454,11 +469,11 @@ def test_a_refusal_names_the_keyword_it_refuses( # Which rule each refusal enforces, if any, is tests/test_capability_queries.py's. -def test_an_error_raised_outside_an_interface_names_no_parameter() -> None: +def test_an_error_names_a_parameter_only_when_its_raiser_gives_one() -> None: assert DriverError("refused").parameter is None with pytest.raises(PulseError, match="super-Gaussian order") as caught: GaussianPulse(wavelength=800e-9, fwhm=30e-15, energy=1e-6, m=0) - assert caught.value.parameter is None + assert caught.value.parameter == "m" def test_a_material_status_warning_names_the_gas() -> None: @@ -519,3 +534,41 @@ def test_an_inner_refusal_that_names_its_keyword_keeps_it() -> None: with pytest.raises(DriverError) as caught, _about("pulses"): raise DriverError("refused", parameter="pulses[0].energy") assert caught.value.parameter == "pulses[0].energy" + + +def test_overlapping_warning_blocks_on_two_threads_leave_the_filters_as_they_were(): + """Two threads' constructors never restore each other's warning state. + + ``catch_warnings`` swaps the process's filters, so a block entered on one thread + and left after another thread's block began would restore that block's filters, + leaving its ``"always"`` and its recorder in place for good. The first block waits + a while for the second to enter: they take turns instead. + """ + from solprop.driver.routes.keywords import ( # noqa: PLC0415 - a private seam + _MATERIAL_WARNINGS, + _warnings_about, + ) + + before = list(warnings.filters) + first_in, second_in, first_out = (threading.Event() for _ in range(3)) + + def first() -> None: + with _warnings_about("gas", _MATERIAL_WARNINGS): + first_in.set() + second_in.wait(timeout=0.5) + first_out.set() + + def second() -> None: + with _warnings_about("raman", _MATERIAL_WARNINGS): + second_in.set() + first_out.wait(timeout=5.0) + + one = threading.Thread(target=first) + one.start() + assert first_in.wait(timeout=5.0) + two = threading.Thread(target=second) + two.start() + one.join(timeout=10.0) + two.join(timeout=10.0) + assert not one.is_alive() and not two.is_alive() + assert warnings.filters == before diff --git a/tests/driver/test_prop_capillary.py b/tests/driver/test_prop_capillary.py index b2c45ae72..6eebd1449 100644 --- a/tests/driver/test_prop_capillary.py +++ b/tests/driver/test_prop_capillary.py @@ -93,7 +93,7 @@ from solprop.nonlinear.raman import RamanResponse, RotationalLines from solprop.nonlinear.responses import KerrResponse from solprop.output import MemoryOutput, open_file -from solprop.output.hdf5 import resume +from solprop.output.hdf5 import read_resume_state from solprop.physdata import Gas, Mixture, ReferenceState, gamma, n2 from solprop.physdata._optmat import composition_fractions from solprop.physdata.glasses import TabulatedGlass, fused_silica @@ -978,7 +978,7 @@ def test_a_replayed_schedule_resumes_onto_the_same_trajectory(tmp_path): with open_file(path) as partial: # The entrance plus the two planes the reporter saw before it stopped. assert partial["z"].size == 3 - continued = resume(path).march is not None + continued = read_resume_state(path).march is not None run(output=path, resume=True, **settings) with open_file(path) as stored: np.testing.assert_array_equal(stored["z"], whole["z"]) diff --git a/tests/driver/test_prop_gnlse.py b/tests/driver/test_prop_gnlse.py index 80c7e274c..b10bd7380 100644 --- a/tests/driver/test_prop_gnlse.py +++ b/tests/driver/test_prop_gnlse.py @@ -5,6 +5,7 @@ """`prop_gnlse`: milestone M1, and the keyword surface that reaches it.""" import logging +import math import os import subprocess import sys @@ -25,6 +26,7 @@ from solprop.backends.registry import select from solprop.constants import C from solprop.driver import Simulation, prop_gnlse +from solprop.driver.defaults import default_rtol from solprop.driver.inputs import _shot_noise from solprop.driver.routes.gnlse import _dispersion_table, _gnlse_mode from solprop.exceptions import DriverError, ModeError @@ -40,6 +42,7 @@ from solprop.output import HDF5Output, MemoryOutput from solprop.output.serialisation import serialise from solprop.physdata import Mixture +from solprop.processing.axes import grid_of from solprop.profiles import Linear from solprop.stepper import FixedSchedule @@ -348,7 +351,100 @@ def test_the_shock_term_can_be_switched_on(): """`shock=True` is the prefactor's omega dependence, and it changes the answer.""" without = cheap(shock=False) with_shock = cheap(shock=True) - assert not np.allclose(with_shock["field"][-1], without["field"][-1]) + # Over this short run the shock moves the field by about 1e-6 of its peak, far + # above the 1e-9 of it held here and the rounding below that. + assert not np.allclose( + with_shock["field"][-1], + without["field"][-1], + rtol=0.0, + atol=1e-9 * np.max(np.abs(without["field"][-1])), + ) + + +# ------------------------------------------------------------ linear dispersion + + +def test_a_gaussian_disperses_as_the_closed_form_says(): + """With no nonlinearity a Gaussian keeps its shape, broadens and chirps in closed + form: power ``P0 tau0/T exp(-t^2/T^2)`` with ``T = tau0 sqrt(1 + (z/L_D)^2)``, + ``L_D = tau0^2/|beta2|``, and the spectral phase grows by ``beta2 domega^2 z/2`` + (the optics convention, ``exp(+i beta z)``). Both are written here, independently + of the operator the run builds from ``betas``; the fibre is sqrt(3) L_D long, so + the pulse doubles in duration and a beta2 off by a factor misses by order one.""" + beta2 = -11.83e-27 + fwhm = 100e-15 + tau0 = fwhm / (2.0 * math.sqrt(math.log(2.0))) + dispersion_length = tau0**2 / abs(beta2) + length = math.sqrt(3.0) * dispersion_length + handler = prop_gnlse( + 0.0, + length, + [0.0, 0.0, beta2], + wavelength=835e-9, + wavelength_limits=(500e-9, 2e-6), + trange=2e-12, + fwhm=fwhm, + peak_power=1.0, + shape="gauss", + shock=False, + raman=False, + noise=None, + n_save=2, + backend=selected_backend(), + ) + grid = cast("EnvelopeGrid", grid_of(handler)) + width = tau0 * math.sqrt(1.0 + (length / dispersion_length) ** 2) + envelope = fourier.inverse(handler.fields("fft")[-1, 0, 0], kind="envelope") + expected = tau0 / width * np.exp(-(grid.t**2) / width**2) + # Where the pulse is, the run is the operator's flow, exact to rounding through the + # transforms; the absorber's residual (below) lies in the collar, where it enters + # the power only squared: measured 1.6e-14 to 2.3e-14 of the 1 W launch peak. + assert np.max(np.abs(np.abs(envelope) ** 2 - expected)) < 1e-12 + launch, exit_ = handler["field"][0, 0, 0], handler["field"][-1, 0, 0] + detuning = grid.omega - grid.omega0 + # Over the bins within a hundredth of the spectral peak, where the phase reaches + # 7.5 rad. The temporal absorber's in-stage term is the run's only source, which + # the embedded pair integrates under the controller: each accepted step's error + # estimate is held to rtol max(|y|, |y_new|) + atol in the whole-field Euclidean + # norm (docs/dev/stepper.md section 3; atol is 1e-14 against rtol |y| = 3e-5 here). + # The flow is unitary and the absorber only removes energy, so after n accepted + # steps a bin's error is at most n rtol |y| and its phase that over |y_k|: 1.5e-5 + # rad at the peak, 1.2e-3 rad at the outermost bin. Within it the residual follows + # the step sequence, which rounding moves: launches a few ulps apart measured 5e-12 + # to 4e-7 rad on both backends, the Linux aarch64 wheel 2.2e-6 rad, and a run + # without the absorber 1.5e-15 rad. A beta2 off by 1 % misses by 0.075 rad. + held = np.abs(launch) > 1e-2 * np.max(np.abs(launch)) + growth = np.angle(exit_[held] * np.conj(launch[held])) + departure = np.angle( + np.exp(1j * (growth - beta2 / 2 * detuning[held] ** 2 * length)) + ) + steps = np.count_nonzero(handler["step_history/accepted"]) + bound = ( + steps * default_rtol("gnlse") * np.linalg.norm(launch) / np.abs(launch[held]) + ) + assert np.max(bound) < 7.5e-3 + assert np.all(np.abs(departure) < bound) + + +def test_a_numpy_float_length_runs(): + # numpy.float64 is a float, so a length computed with numpy is a valid request. A + # run long enough for the reference backend's host boundary monitor to check a + # step by distance (the same run passes on the native backend). + handler = prop_gnlse( + 0.0, + np.float64(0.5), + [0.0, 0.0, -11.83e-27], + wavelength=835e-9, + wavelength_limits=(500e-9, 2e-6), + trange=2e-12, + fwhm=100e-15, + peak_power=1.0, + shape="gauss", + noise=None, + n_save=2, + backend="numpy_ref", + ) + assert handler.n_saved == 2 # --------------------------------------------------------------- the pulse keywords @@ -381,8 +477,18 @@ def test_the_energy_and_the_peak_power_specify_the_same_sech_pulse(): # the two requests differ by the sech's truncated tails on that window: the # sampled energy of the peak-scaled pulse is 8.0e-8 below the analytic value, which # is the difference measured here (7.9e-8 relative in amplitude). - assert np.allclose(by_energy["field"][-1], by_power["field"][-1], rtol=1e-7) - assert not np.allclose(by_energy["field"][-1], by_power["field"][-1], rtol=1e-9) + assert np.allclose( + by_energy["field"][-1], + by_power["field"][-1], + rtol=1e-7, + atol=1e-7 * np.max(np.abs(by_power["field"][-1])), + ) + assert not np.allclose( + by_energy["field"][-1], + by_power["field"][-1], + rtol=1e-9, + atol=1e-9 * np.max(np.abs(by_power["field"][-1])), + ) def test_a_group_delay_phase_moves_the_pulse_later(soliton): @@ -791,6 +897,7 @@ def test_index_table_gnlse_metadata_hash_across_processes(use_mode): import numpy as np from solprop.modes import IndexTable, MarcatiliMode from solprop.physdata import Mixture +from solprop.processing.axes import grid_of from solprop.driver import Simulation omega = np.linspace(.3e15, 4.5e15, 200) table = IndexTable(omega, np.full(200, 1.45 + 1e-9j), area=np.full(200, 1e-10)) diff --git a/tests/driver/test_prop_planar.py b/tests/driver/test_prop_planar.py index c78a65bbe..368c4ea56 100644 --- a/tests/driver/test_prop_planar.py +++ b/tests/driver/test_prop_planar.py @@ -399,7 +399,7 @@ def test_a_planar_pulse_refuses_what_it_does_not_carry(keywords, match): def test_a_planar_pulse_prints_its_two_waists(): launch = pulse() assert repr(launch).startswith("PlanarPulse(waist_x=") - assert "waist_y=400 um" in repr(launch) + assert "waist=400 um" in repr(launch) assert "astigmatic Gaussian" in str(launch) diff --git a/tests/driver/test_prop_radial.py b/tests/driver/test_prop_radial.py index 7bcdb771f..35e821f1c 100644 --- a/tests/driver/test_prop_radial.py +++ b/tests/driver/test_prop_radial.py @@ -73,7 +73,7 @@ def test_radial_interface_caches_and_saves_geometry(case, backend, request): # Preserve the compact pulse specification; serializing the built transverse # volume here would duplicate the input and make Cartesian metadata enormous. assert metadata.configuration["initial"] is pulse - assert metadata.schema_version == 4 + assert metadata.schema_version == 3 assert metadata.simulation_kind == "radial" assert metadata.spatial is not None assert metadata.spatial["stored_field_units"] == "V m" diff --git a/tests/driver/test_prop_slab.py b/tests/driver/test_prop_slab.py index 1cef95b8c..142b1182c 100644 --- a/tests/driver/test_prop_slab.py +++ b/tests/driver/test_prop_slab.py @@ -240,7 +240,7 @@ def test_the_run_records_its_measure_and_labels_per_unit_width(): back = RunMetadata.from_json(metadata.to_json()) assert back.transverse_measure == "per_unit_width" assert back.configuration_hash() == metadata.configuration_hash() - assert json.loads(metadata.to_json())["schema_version"] == 4 + assert json.loads(metadata.to_json())["schema_version"] == 3 units = transverse_units(output) assert (units.power, units.energy, units.intensity) == ("W/m", "J/m", "W/m^2") figures = plot_stats(output) diff --git a/tests/driver/test_restart_record.py b/tests/driver/test_restart_record.py index d9888921f..32abfbc69 100644 --- a/tests/driver/test_restart_record.py +++ b/tests/driver/test_restart_record.py @@ -32,8 +32,8 @@ HDF5Output, SnapshotController, open_file, + read_resume_state, read_snapshot, - resume, ) from solprop.output.hdf5 import _dataset from solprop.stepper import Multistep, RungeKutta @@ -76,7 +76,7 @@ def warned_once_and_reset(build, path, text, reason) -> None: def interrupted(build, path) -> float: """Run into `path`, stop after two planes and return where it stopped.""" run_until(build(), path, after=2) - return resume(path).plane.z + return read_resume_state(path).plane.z @pytest.mark.parametrize( @@ -200,7 +200,7 @@ def build(): return low_storage(fields="all") run_until(build(), path, after=1) - z = resume(path).plane.z + z = read_resume_state(path).plane.z assert restart(path)["retention"] == { "state": "not_applicable", "reason": "no_method_history", @@ -233,7 +233,7 @@ def test_a_record_that_states_no_retention_reads_as_unknown_and_resumes( ) if not march: del file["march_snapshot"] - state = resume(path) + state = read_resume_state(path) assert state.outcome is not None and "restart" not in state.outcome.execution assert run_module.retention_at(state.outcome.execution, z) is None assert resumed(build, path) == [] @@ -302,7 +302,7 @@ def torn(self, snapshot): build().run(path, progress="none") retention = restart(path)["retention"] assert (retention["state"], retention["reason"]) == ("omitted", "write_failed") - assert resume(path).march is None + assert read_resume_state(path).march is None warned_once_and_reset(build, path, "write failed", "unavailable_history") diff --git a/tests/driver/test_resume.py b/tests/driver/test_resume.py index 4d8dc775f..080f569a8 100644 --- a/tests/driver/test_resume.py +++ b/tests/driver/test_resume.py @@ -28,7 +28,7 @@ from solprop.grid import EnvelopeGrid from solprop.log import NullReporter from solprop.output import MemoryOutput -from solprop.output.hdf5 import resume +from solprop.output.hdf5 import read_resume_state from solprop.stepper import FixedSchedule # The fixtures here launch noise-free into time windows kept tight for speed, which @@ -282,7 +282,7 @@ def build(): with pytest.raises(CrashError): build().run(path, progress=StopAtTheEntrance()) - stored = resume(path) + stored = read_resume_state(path) assert stored.n_saved == 1 assert stored.plane.z == 0.0 assert stored.plane.field is not None @@ -325,7 +325,7 @@ def interior(): path = tmp_path / "part.h5" with pytest.raises(CrashError): interior().run(path, progress=StopAtTheEntrance()) - assert resume(path).plane.z == interior().grid.length / 2 + assert read_resume_state(path).plane.z == interior().grid.length / 2 interior().run(path, resume=True) interior().run(tmp_path / "whole.h5") whole = read_file(tmp_path / "whole.h5", "field") @@ -432,13 +432,50 @@ def test_a_default_noise_run_without_a_seed_resumes_from_the_seed_it_recorded( path, after=2, ) - stored = resume(path).metadata.noise + stored = read_resume_state(path).metadata.noise assert stored is not None and stored.seed is not None again = scheduled(build_simulation, noise="default", backend="numpy_ref") assert again.noise is not None and again.noise.seed != stored.seed + drawn = again.noise again.run(path, resume=True) - assert again.noise.seed == stored.seed - assert resume(path).n_saved == N_SAVE + assert read_resume_state(path).n_saved == N_SAVE + # The resume ran on a copy: the caller's own realisation is untouched, and a fresh + # run of it afterwards records that realisation, not the resumed file's. + assert again.noise is drawn + again.run(tmp_path / "fresh.h5") + fresh = read_resume_state(tmp_path / "fresh.h5").metadata.noise + assert fresh is not None and fresh.seed == drawn.seed + whole = scheduled( + build_simulation, noise="default", seed=stored.seed, backend="numpy_ref" + ) + whole.run(tmp_path / "whole.h5") + for key in ("field", "noise_phase"): + assert_matched( + read_file(path, key), + read_file(tmp_path / "whole.h5", key), + budget(whole), + what=key, + ) + + +def test_an_unseeded_run_resumed_by_its_own_simulation_continues_its_draw( + build_simulation, tmp_path +): + """The interrupted object holds the recorded realisation, so nothing is redrawn. + + It continues its file, which then matches the uninterrupted run seeded with the + recorded seed to the matched march's rounding budget, as a new object's resume does. + """ + path = tmp_path / "part.h5" + simulation = scheduled(build_simulation, noise="default", backend="numpy_ref") + drawn = simulation.noise + assert drawn is not None + run_until(simulation, path, after=2) + stored = read_resume_state(path).metadata.noise + assert stored is not None and stored.seed == drawn.seed + simulation.run(path, resume=True) + assert simulation.noise is drawn + assert read_resume_state(path).n_saved == N_SAVE whole = scheduled( build_simulation, noise="default", seed=stored.seed, backend="numpy_ref" ) @@ -497,9 +534,9 @@ def test_a_resumed_run_continues_the_file_rather_than_replacing_it( ): path = tmp_path / "run.h5" run_until(scheduled(build_simulation), path, after=1) - created = resume(path).metadata.created + created = read_resume_state(path).metadata.created scheduled(build_simulation).run(path, resume=True) - state = resume(path) + state = read_resume_state(path) assert state.n_saved == N_SAVE # The file keeps its own record, creation time included: it is the same run. assert state.metadata.created == created @@ -545,7 +582,7 @@ def fail_first_march(self, **bounds): patch.setattr(native.NativeSession, "advance", fail_first_march) with pytest.raises(CrashError, match="before the first step"): scheduled(build_simulation).run(path, progress="none") - stopped = resume(path) + stopped = read_resume_state(path) assert stopped.n_saved == 1 and stopped.plane.z == 0.0 assert stopped.checkpoint is not None and stopped.checkpoint.landed scheduled(build_simulation).run(path, resume=True) diff --git a/tests/driver/test_resume_history.py b/tests/driver/test_resume_history.py index 708aa972d..32942476e 100644 --- a/tests/driver/test_resume_history.py +++ b/tests/driver/test_resume_history.py @@ -42,7 +42,7 @@ from solprop.exceptions import OutputError, SolpropWarning from solprop.log import NullReporter from solprop.output import HDF5Output -from solprop.output.hdf5 import open_file, resume +from solprop.output.hdf5 import open_file, read_resume_state from solprop.output.metadata import _example_metadata from solprop.output.records import MarchSnapshot, SavedPlane from solprop.stepper import Multistep, RungeKutta @@ -172,7 +172,7 @@ def test_a_resumed_run_is_the_uninterrupted_one( CASES[case](build_simulation, rtol=RTOL / TIGHTER), tmp_path / "tight.h5" ) run_until(build(), part, after=2) - state = resume(part) + state = read_resume_state(part) assert state.march is not None assert state.march.z == state.plane.z with caplog.at_level(logging.INFO, logger="solprop.driver"): @@ -204,7 +204,9 @@ def failing(self, field, position, *args, **keywords): # The first call after a step accepted strictly between two planes past the # first: the run stops there, with no plane to resume from. last = positions[-1] if positions else 0.0 - if last > planes[1] and not any(np.isclose(last, one) for one in planes): + if last > planes[1] and not any( + np.isclose(last, one, atol=0.0) for one in planes + ): raise CrashError("the source failed") positions.append(position) return original(self, field, position, *args, **keywords) @@ -213,7 +215,7 @@ def failing(self, field, position, *args, **keywords): patch.setattr(NumpyWorkspace, "lab_source", failing) with pytest.raises(CrashError): build().run(part, progress="none") - state = resume(part) + state = read_resume_state(part) assert state.checkpoint is not None assert state.march is not None and state.march.z == state.checkpoint.plane.z with open_file(whole) as first: @@ -236,7 +238,7 @@ def test_without_the_history_a_resume_starts_afresh(build_simulation, tmp_path): tmp_path / "tight.h5", ) run_until(build(), part, after=2) - assert resume(part).march is None + assert read_resume_state(part).march is None build().run(part, resume=True, progress="none") found, truth = fields(part)[1], fields(whole)[1] # A fresh history at order one is a different trajectory, as accurate as the first. @@ -252,13 +254,13 @@ def test_a_snapshot_over_the_default_size_is_kept_only_on_request( path = tmp_path / "run.h5" with caplog.at_level(logging.INFO, logger="solprop.driver.run"): soliton(build_simulation, "numpy_ref")().run(path, progress="none") - assert resume(path).march is None + assert read_resume_state(path).march is None assert "resume_history=True keeps it" in caplog.text asked = tmp_path / "asked.h5" soliton(build_simulation, "numpy_ref", resume_history=True)().run( asked, progress="none" ) - assert resume(asked).march is not None + assert read_resume_state(asked).march is not None @pytest.mark.parametrize("backend", ["numpy_ref", "native"]) @@ -281,7 +283,7 @@ def refuse(*_): ) path = tmp_path / "run.h5" soliton(build_simulation, backend)().run(path, progress="none") - assert resume(path).march is None + assert read_resume_state(path).march is None @pytest.mark.parametrize( @@ -425,7 +427,7 @@ def test_native_keeps_its_history_resident_and_continues_it( build = soliton(build_simulation, "native") path = tmp_path / "run.h5" run_until(build(), path, after=2) - march = resume(path).march + march = read_resume_state(path).march assert march is not None and set(march.rows) == {"store"} with caplog.at_level(logging.INFO, logger="solprop.driver"): build().run(path, resume=True, progress="none") @@ -497,7 +499,7 @@ def test_a_rewritten_snapshot_holds_only_its_own_rows(tmp_path): store = np.zeros((4, 1, 1, 1, 4), complex) compensated = {"store": store, "states": store + 1, "rates": store + 2} saved_with(path, march(rows=compensated), march(rows={"store": store + 3})) - snapshot = resume(path).march + snapshot = read_resume_state(path).march assert snapshot is not None assert set(snapshot.rows) == {"store"} assert np.array_equal(snapshot.rows["store"], store + 3) @@ -506,10 +508,10 @@ def test_a_rewritten_snapshot_holds_only_its_own_rows(tmp_path): def test_the_history_key_crosses_the_file_and_a_rewrite_replaces_it(tmp_path): path = tmp_path / "run.h5" saved_with(path, march(history_key="adams-pec2/3")) - snapshot = resume(path).march + snapshot = read_resume_state(path).march assert snapshot is not None and snapshot.history_key == "adams-pec2/3" saved_with(path, march(history_key="adams-pec2/3"), march()) - snapshot = resume(path).march + snapshot = read_resume_state(path).march assert snapshot is not None and snapshot.history_key == "adams" @@ -519,7 +521,7 @@ def test_the_collar_flag_crosses_the_file(tmp_path, quiet): # returns to its stable step (SEP 39 R9), so a resume carries it exactly. path = tmp_path / "run.h5" saved_with(path, march(collar_was_quiet=quiet)) - snapshot = resume(path).march + snapshot = read_resume_state(path).march assert snapshot is not None assert snapshot.collar_was_quiet is quiet @@ -529,7 +531,7 @@ def test_a_snapshot_taken_elsewhere_is_not_returned(tmp_path): # snapshot's own rewrite was not -- describes another state. path = tmp_path / "run.h5" saved_with(path, march(z=0.2, positions=np.array([0.15, 0.2]))) - assert resume(path).march is None + assert read_resume_state(path).march is None @pytest.mark.parametrize( @@ -552,7 +554,7 @@ def test_an_unreadable_snapshot_is_ignored_with_a_warning( with h5py.File(path, "a") as file: damage(file["march_snapshot"]) with caplog.at_level(logging.WARNING, logger="solprop.output.hdf5"): - state = resume(path) + state = read_resume_state(path) assert state.march is None assert state.plane.z == 0.25 assert "ignoring the unreadable march snapshot" in caplog.text @@ -565,7 +567,7 @@ def test_a_kept_history_is_set_aside_on_request(build_simulation, tmp_path, capl whole, part = tmp_path / "whole.h5", tmp_path / "part.h5" soliton(build_simulation, "numpy_ref")().run(whole, progress="none") run_until(soliton(build_simulation, "numpy_ref")(), part, after=2) - assert resume(part).march is not None + assert read_resume_state(part).march is not None afresh = soliton(build_simulation, "numpy_ref", resume_history=False)() with caplog.at_level(logging.INFO, logger="solprop.driver"): afresh.run(part, resume=True, progress="none") @@ -595,7 +597,7 @@ def test_rows_that_do_not_fit_the_store_start_the_history_afresh( store = np.asarray(rows["store"]) del rows["store"] rows["store"] = store[:-1] - assert resume(part).march is not None + assert read_resume_state(part).march is not None with pytest.warns( SolpropWarning, match="the Adams history starts afresh: the snapshot's 'store'" ): diff --git a/tests/driver/test_run.py b/tests/driver/test_run.py index d849a75b2..66445e400 100644 --- a/tests/driver/test_run.py +++ b/tests/driver/test_run.py @@ -174,9 +174,6 @@ def metadata(self) -> dict[str, object]: def memory_ledger(self): return {} - def available_device_memory(self): - return None - def close(self): pass diff --git a/tests/driver/test_runner.py b/tests/driver/test_runner.py index 03a668a81..b750d0420 100644 --- a/tests/driver/test_runner.py +++ b/tests/driver/test_runner.py @@ -693,7 +693,9 @@ def test_a_runner_carries_a_replaced_realisation_of_its_noise_model(): kept = stored(runner.run(field, progress="none")) assert_within(reused["field"], fresh["field"], replay_bound(simulation)) # The kept realisation is the constructed one: another draw, another field. - assert not np.allclose(kept["field"], fresh["field"]) + assert not np.allclose( + kept["field"], fresh["field"], atol=1e-5 * np.max(np.abs(fresh["field"])) + ) def test_a_runner_runs_an_input_without_noise_when_it_has_none(): diff --git a/tests/driver/test_save_planes.py b/tests/driver/test_save_planes.py index 52c3f7ebc..30585051e 100644 --- a/tests/driver/test_save_planes.py +++ b/tests/driver/test_save_planes.py @@ -25,7 +25,7 @@ from solprop.exceptions import DriverError from solprop.grid import EnvelopeGrid from solprop.log import NullReporter -from solprop.output.hdf5 import resume +from solprop.output.hdf5 import read_resume_state from solprop.recipe import Recipe, resume_file from solprop.stats import StatsSpec from solprop.stepper import FixedSchedule, LowStorageRungeKutta, Multistep, RungeKutta @@ -476,7 +476,7 @@ def resumable(**keywords) -> Simulation: def ends_complete(path) -> None: """Assert a file holds its whole run, ending at the grid's length.""" - state = resume(path) + state = read_resume_state(path) assert state.plane.z == LENGTH assert state.n_saved == 5 assert state.checkpoint is None @@ -487,7 +487,7 @@ def test_an_interrupted_file_resumes_to_the_declared_end(tmp_path): path = tmp_path / "run.h5" with pytest.raises(CrashError): resumable().run(path, progress=Interrupt(2)) - assert resume(path).plane.z < LENGTH + assert read_resume_state(path).plane.z < LENGTH resumable().run(path, resume=True, progress="none") ends_complete(path) @@ -509,7 +509,7 @@ def fail_at_the_end(self, spec, z): patch.setattr(NumpyWorkspace, "stats", fail_at_the_end) with pytest.raises(CrashError): resumable().run(path, progress="none") - stopped = resume(path) + stopped = read_resume_state(path) # The march reached the end; its last plane was never saved. assert stopped.checkpoint is not None and stopped.n_saved < 5 resumable().run(path, resume=True, progress="none") diff --git a/tests/driver/test_scan_derived_noise.py b/tests/driver/test_scan_derived_noise.py index 43a2e2451..c19b20206 100644 --- a/tests/driver/test_scan_derived_noise.py +++ b/tests/driver/test_scan_derived_noise.py @@ -413,8 +413,10 @@ def test_a_derived_run_resumes_from_its_file_after_a_new_draw(tmp_path): # A new draw: the same call in a new process. again = fibre().with_input(field) assert drawn(again).seed != seed + # Refused as another run unless the resume draws again from the recorded seed, + # which it does on a copy: the caller keeps its own draw. again.run(path, resume=True, progress="none") - assert drawn(again).seed == seed + assert drawn(again).seed != seed def test_an_explicit_realisation_is_still_refused_by_a_resume(tmp_path): diff --git a/tests/driver/test_scan_queue.py b/tests/driver/test_scan_queue.py index 0e7239da2..03e1b8542 100644 --- a/tests/driver/test_scan_queue.py +++ b/tests/driver/test_scan_queue.py @@ -32,6 +32,7 @@ from solprop.exceptions import DriverError, ExecutorError, OutputError from solprop.output.hdf5 import _dataset from solprop.output.metadata import _example_metadata +from solprop.output.records import RecipeFile, RecipeRecord from solprop.output.scan import PointResult from solprop.output.serialisation import RECORD_ARRAY_LIMIT @@ -77,16 +78,16 @@ def publish(queue, claimed, work=None): @pytest.mark.parametrize( - "options", + ("options", "message"), [ - {"stale_age": 0.0}, - {"stale_age": float("nan")}, - {"chunk": (1, 1)}, - {"chunk": (0, 0)}, + ({"stale_age": 0.0}, "stale_age must be positive and finite"), + ({"stale_age": float("nan")}, "stale_age must be positive and finite"), + ({"chunk": (1, 1)}, "chunk must satisfy"), + ({"chunk": (0, 0)}, "chunk must satisfy"), ], ) -def test_queue_refuses_invalid_lease_and_chunk(options): - with pytest.raises(DriverError): +def test_queue_refuses_invalid_lease_and_chunk(options, message): + with pytest.raises(DriverError, match=message): Queue(None, **options) @@ -375,6 +376,38 @@ def test_collection_rejects_modified_artifact(tmp_path): collect(path, tmp_path / "scan.h5") +RECIPE = RecipeRecord( + 1, + "[recipe]\nformat = 1\n", + "[recipe]\nformat = 1\nseed = 3\n", + {"data-0.npy": RecipeFile("data.npy", "0" * 64, b"\x00\x01")}, +) + + +def test_a_queue_scan_file_records_the_recipe_the_scan_was_built_from(tmp_path): + # The chunk holds no point, so the scan runs no worker: what is checked is the + # recipe's path from `run_scan` through the queue into the collected file. + output = run_scan( + Scan("recipe", power=[1.0]), + build_point, + executor=Queue(tmp_path / "queue", pool=Pool(workers=1), chunk=(1, 2)), + output=tmp_path / "scan.h5", + progress="none", + recipe=RECIPE, + ) + assert output.recipe == RECIPE + # Recorded once: a second scan of the queue keeps the first recipe. + output = run_scan( + Scan("recipe", power=[1.0]), + build_point, + executor=Queue(tmp_path / "queue", pool=Pool(workers=1), chunk=(1, 2)), + output=tmp_path / "scan.h5", + progress="none", + recipe=dataclasses.replace(RECIPE, authored="[recipe]\nformat = 1\n# edited\n"), + ) + assert output.recipe == RECIPE + + def test_queue_refuses_different_scan_manifest(tmp_path): _, queue = prepare(tmp_path, size=1) with pytest.raises(OutputError, match="manifest"): diff --git a/tests/driver/test_scan_resources.py b/tests/driver/test_scan_resources.py index 7eecce651..56f256503 100644 --- a/tests/driver/test_scan_resources.py +++ b/tests/driver/test_scan_resources.py @@ -265,8 +265,10 @@ def test_worker_reports_exception_and_closes_pipe(): def test_worker_failure_without_scan_failure_contract_propagates(): error = pool._WorkerError("lost worker") - with pytest.raises(DriverError, match="lost worker"): + # A crashed worker is a failure of the environment, not a refused argument. + with pytest.raises(ExecutorError, match="lost worker") as raised: pool._failed_work(abs, 1, error) + assert not isinstance(raised.value, ValueError) @pytest.mark.parametrize("broken", [False, True]) @@ -373,6 +375,20 @@ def test_pool_replaces_crashed_worker_and_keeps_pending_points(monkeypatch): assert output[0][1] != output[2][1] +class ExitingWork: + """Point work with no ``failure`` hook whose worker process exits abruptly.""" + + def __call__(self, point): + os._exit(23) + + +def test_a_crashed_worker_without_a_failure_hook_is_an_executor_error(monkeypatch): + monkeypatch.setattr(pool.Pool, "_admit", lambda *args: ((0,), 1)) + with pytest.raises(ExecutorError, match="exited without") as raised: + list(pool.Pool(pin=False).run([0], ExitingWork())) + assert not isinstance(raised.value, ValueError) + + def test_pool_does_not_spawn_more_workers_than_points(monkeypatch): monkeypatch.setattr(pool.Pool, "_admit", lambda *args: ((0, 1, 2), 3)) assert len(list(pool.Pool(pin=False).run([0], EchoWork()))) == 1 @@ -398,7 +414,7 @@ def stop(process, connection): def test_receive_propagates_worker_traceback(): parent, child = multiprocessing.Pipe() child.send((False, "worker traceback")) - with pytest.raises(DriverError, match="worker traceback"): + with pytest.raises(ExecutorError, match="worker traceback"): pool._receive(cast(Connection, parent)) parent.close() child.close() diff --git a/tests/driver/test_scan_slurm.py b/tests/driver/test_scan_slurm.py index a0de4f013..826723f2d 100644 --- a/tests/driver/test_scan_slurm.py +++ b/tests/driver/test_scan_slurm.py @@ -23,6 +23,7 @@ from solprop.driver.executors.slurm import Slurm from solprop.driver.scan import Scan, run_scan from solprop.exceptions import DriverError, ExecutorError +from solprop.output.records import RecipeFile, RecipeRecord from solprop.processing.scans import ScanOutput from solprop.scan import current_executor, main @@ -144,16 +145,17 @@ def run(arguments, **options): @pytest.mark.parametrize( - "options", + ("options", "message"), [ - {"ntasks": 0}, - {"mem": "0"}, - {"instances": 2}, - {"partition": "bad\n#SBATCH --exclusive"}, + ({"ntasks": 0}, "task, CPU and thread counts must be positive"), + ({"mem": "0"}, "mem must be a positive integer"), + ({"instances": 2}, "cannot fit the requested instances"), + ({"partition": "bad\n#SBATCH --exclusive"}, "must not contain line breaks"), + ({"stale_age": 0.0}, "stale_age must be positive and finite"), ], ) -def test_slurm_refuses_invalid_resources(options): - with pytest.raises(DriverError): +def test_slurm_refuses_invalid_resources(options, message): + with pytest.raises(DriverError, match=message): Slurm("script.py", **options) @@ -259,6 +261,27 @@ def test_cli_rejects_conflicting_or_malformed_routes(arguments): main(["scan.py", *arguments]) +def test_cli_stale_age_reaches_every_queue_and_is_refused_without_one( + tmp_path, monkeypatch +): + captured = [] + monkeypatch.setattr( + "solprop.scan.runpy.run_path", + lambda *a, **k: captured.append(current_executor()), + ) + assert main(["scan.py", "--queue", str(tmp_path / "q"), "--stale-age", "30"]) == 0 + assert isinstance(captured[0], Queue) + assert captured[0].stale_age == 30.0 + # A Slurm submission hands its lease to the controllers its tasks start. + emitted = tmp_path / "job.sh" + assert main(["scan.py", "--emit-slurm", str(emitted), "--stale-age", "30"]) == 0 + assert "--stale-age 30.0" in emitted.read_text(encoding="utf-8") + with pytest.raises(SystemExit): + main(["scan.py", "--stale-age", "30"]) + with pytest.raises(SystemExit): + main(["scan.py", "--workers", "2", "--stale-age", "30"]) + + def test_cli_chunk_binds_global_partition_and_restores_context(monkeypatch): previous = sys.argv captured = [] @@ -319,7 +342,13 @@ def test_slurm_prepares_worker_chunk_and_drains_inner_queue(tmp_path, monkeypatc Queue, "run", lambda self, points, work: iter([work(p) for p in points]) ) policy = Slurm( - "scan.py", ntasks=3, instances=2, cpus_per_task=4, mode="chunk", gres="gpu:2" + "scan.py", + ntasks=3, + instances=2, + cpus_per_task=4, + mode="chunk", + gres="gpu:2", + stale_age=30.0, ) request = ScanRequest(Scan("tiny", x=[1]), {}, tmp_path / "scan.h5", abs) policy.validate(abs) @@ -327,6 +356,7 @@ def test_slurm_prepares_worker_chunk_and_drains_inner_queue(tmp_path, monkeypatc assert prepared == [request] assert policy._queue is not None assert policy._queue.chunk == (3, 6) + assert policy._queue.stale_age == 30.0 assert policy._queue.pool.workers == 1 assert policy._queue.pool.memory_limit == 2 * 1024**3 assert list(policy.run([-2], abs)) == [2] @@ -355,6 +385,36 @@ def test_slurm_submission_route_collects_pending_manifest(tmp_path, monkeypatch) assert policy._queue.chunk is None +def test_a_slurm_scan_file_records_the_recipe_the_scan_was_built_from( + tmp_path, monkeypatch +): + # A task's in-process body: its chunk holds no point, so the scan runs no worker, + # and what is checked is the recipe's path through the Slurm executor's inner + # queue into the file the task writes and the one `collect` writes. + recipe = RecipeRecord( + 1, + "[recipe]\nformat = 1\n", + "[recipe]\nformat = 1\nseed = 3\n", + {"data-0.npy": RecipeFile("data.npy", "0" * 64, b"\x00\x01")}, + ) + monkeypatch.setenv("SOLPROP_SLURM_WORKER", "1") + monkeypatch.setenv("SLURM_ARRAY_TASK_ID", "2") + queue = tmp_path / "queue" + policy = Slurm(tmp_path / "scan.py", ntasks=2, mode="chunk", queue_path=queue) + output = run_scan( + Scan("recipe", power=[1.0]), + build, + executor=policy, + output=tmp_path / "scan.h5", + progress="none", + recipe=recipe, + ) + assert output.recipe == recipe + collected = tmp_path / "collected.h5" + assert main(["collect", str(queue), "--output", str(collected)]) == 0 + assert ScanOutput(collected).recipe == recipe + + def test_cli_help_documents_the_collect_mode(capsys): with pytest.raises(SystemExit) as stopped: main(["--help"]) @@ -366,6 +426,15 @@ def test_cli_help_documents_the_collect_mode(capsys): assert "collect QUEUE --output OUT.h5" in capsys.readouterr().out +def test_cli_help_explains_every_option(): + from solprop.scan import _parser # noqa: PLC0415 - the parser the help prints + + unexplained = [ + action.dest for action in _parser()._actions if not (action.help or "").strip() + ] + assert unexplained == [] + + def test_slurm_production_guard_refuses_unknown_mode_without_session_hook(): with pytest.raises(DriverError, match="mode must be"): inspect.unwrap(Slurm.__init__)(Slurm.__new__(Slurm), "scan.py", mode="unknown") diff --git a/tests/driver/test_scan_slurm/test_slurm_script_snapshot_chunk_.sh b/tests/driver/test_scan_slurm/test_slurm_script_snapshot_chunk_.sh index 692a01477..08253a200 100644 --- a/tests/driver/test_scan_slurm/test_slurm_script_snapshot_chunk_.sh +++ b/tests/driver/test_scan_slurm/test_slurm_script_snapshot_chunk_.sh @@ -25,7 +25,7 @@ for (( instance=0; instance<2; instance++ )); do export MKL_NUM_THREADS=2 export VECLIB_MAXIMUM_THREADS=2 export SOLPROP_NATIVE_WAIT_REQUEST=passive - exec /python -m solprop.scan '/shared/scan/scan '"'"'quoted'"'"'.py' --queue '/shared/scan/point queue' --threads 2 --memory-limit 6442450944 --workers 1 --fresh --chunk "$(( (SLURM_ARRAY_TASK_ID - 1) * 2 + instance ))/6" + exec /python -m solprop.scan '/shared/scan/scan '"'"'quoted'"'"'.py' --queue '/shared/scan/point queue' --threads 2 --memory-limit 6442450944 --stale-age 600.0 --workers 1 --fresh --chunk "$(( (SLURM_ARRAY_TASK_ID - 1) * 2 + instance ))/6" ) & pids+=("$!") done diff --git a/tests/driver/test_scan_slurm/test_slurm_script_snapshot_queue_.sh b/tests/driver/test_scan_slurm/test_slurm_script_snapshot_queue_.sh index 9adf30b86..8c3ef85b3 100644 --- a/tests/driver/test_scan_slurm/test_slurm_script_snapshot_queue_.sh +++ b/tests/driver/test_scan_slurm/test_slurm_script_snapshot_queue_.sh @@ -25,7 +25,7 @@ for (( instance=0; instance<2; instance++ )); do export MKL_NUM_THREADS=2 export VECLIB_MAXIMUM_THREADS=2 export SOLPROP_NATIVE_WAIT_REQUEST=passive - exec /python -m solprop.scan '/shared/scan/scan '"'"'quoted'"'"'.py' --queue '/shared/scan/point queue' --threads 2 --memory-limit 6442450944 --workers 1 --fresh + exec /python -m solprop.scan '/shared/scan/scan '"'"'quoted'"'"'.py' --queue '/shared/scan/point queue' --threads 2 --memory-limit 6442450944 --stale-age 600.0 --workers 1 --fresh ) & pids+=("$!") done diff --git a/tests/driver/test_scan_slurm/test_slurm_single_instance_gpu_snapshot_pins_one_worker.sh b/tests/driver/test_scan_slurm/test_slurm_single_instance_gpu_snapshot_pins_one_worker.sh index ebf13cef9..9780724c9 100644 --- a/tests/driver/test_scan_slurm/test_slurm_single_instance_gpu_snapshot_pins_one_worker.sh +++ b/tests/driver/test_scan_slurm/test_slurm_single_instance_gpu_snapshot_pins_one_worker.sh @@ -21,7 +21,7 @@ for (( instance=0; instance<1; instance++ )); do export MKL_NUM_THREADS=2 export VECLIB_MAXIMUM_THREADS=2 export SOLPROP_NATIVE_WAIT_REQUEST=passive - exec /python -m solprop.scan /shared/scan/single.py --queue '/shared/scan/single queue' --threads 2 --memory-limit 4294967296 --workers 1 + exec /python -m solprop.scan /shared/scan/single.py --queue '/shared/scan/single queue' --threads 2 --memory-limit 4294967296 --stale-age 600.0 --workers 1 ) & pids+=("$!") done diff --git a/tests/driver/test_scan_stop_progress.py b/tests/driver/test_scan_stop_progress.py index 6a79a07ec..5e588905a 100644 --- a/tests/driver/test_scan_stop_progress.py +++ b/tests/driver/test_scan_stop_progress.py @@ -26,7 +26,7 @@ from solprop.driver.executors.pool import PlaneScalars, Pool, _Channel, _WorkerReporter from solprop.driver.scan import Scan, run_scan from solprop.driver.simulation import Simulation -from solprop.exceptions import DriverError, ExecutorError, StopRequested +from solprop.exceptions import DriverError, ExecutorError, RunTerminated, StopRequested from solprop.grid import EnvelopeGrid from solprop.log import NullReporter, NullScanReporter, PlaneSummary, ScanReporter from solprop.stepper import FixedSchedule, Multistep @@ -73,6 +73,13 @@ def build_point(point): return _fibre(point.values["power"], STEPS, len(PLANES)) +def interrupted_point(point): + """Interrupt a point of negative power in its worker, as Ctrl-C there would.""" + if point.values["power"] < 0: + raise KeyboardInterrupt + return build_point(point) + + def slow_point(point): """A point long enough that a stop sent after its first plane reaches it running. @@ -410,6 +417,66 @@ def test_pool_stop_message_stops_the_point_in_flight(tmp_path): assert error.flag is flag +@pytest.mark.medium +@pytest.mark.parametrize( + ("powers", "statuses"), + [([-1.0, 2.0], ["todo", "done"]), ([1.0, -2.0], ["done", "todo"])], + ids=["probed", "running"], +) +def test_an_interrupt_in_a_pool_worker_stops_its_point_rather_than_failing_it( + tmp_path, powers, statuses +): + # The first point is probed for memory in a worker before any runs. + scan = Scan("pool_interrupt", power=powers) + reporter = Recorder(watch=False) + output = run_scan( + scan, + interrupted_point, + output=tmp_path / "scan.h5", + executor=Pool(workers=1, pin=False), + progress=reporter, + ) + # Not committed as a failure: given back, so a rerun computes it; the scan goes on. + assert output.status.tolist() == statuses + assert sorted(reporter.finished()) == [ + (index, "stopped" if status == "todo" else status) + for index, status in enumerate(statuses) + ] + + +@pytest.mark.parametrize( + "interruption", + [KeyboardInterrupt(), StopRequested(threading.Event()), RunTerminated(15)], + ids=["keyboard", "stop", "sigterm"], +) +def test_a_worker_reports_an_interrupted_point_apart_from_a_failure(interruption): + def interrupted(point): + raise interruption + + parent, child = mp.Pipe() + parent.send(("run", 7)) + pool._serve(cast(Connection, child), interrupted, ()) + tag, text = parent.recv() + assert tag == pool.INTERRUPTED + assert type(interruption).__name__ in text + assert child.closed + parent.close() + + +def test_an_interrupted_worker_s_point_is_stopped_by_the_work_s_hook(): + error = pool._WorkerInterruptedError( + "scan worker was interrupted: KeyboardInterrupt" + ) + work = _Work(build_point, _Options((), "none", (), "all"), "interrupted") + job = _Job(Scan("interrupted", power=[1.0]).point(0)) + result = pool._interrupted_work(work, job, error) + assert isinstance(result, type(work.stopped(job))) + assert result.status == "stopped" + # Work without the hook raises it, as a crash without a failure hook does. + with pytest.raises(ExecutorError, match="interrupted: KeyboardInterrupt"): + pool._interrupted_work(abs, 1, error) + + @pytest.mark.skipif( sys.platform == "win32", reason="the Queue and Slurm executors are POSIX only" ) diff --git a/tests/driver/test_scan_worker_validation.py b/tests/driver/test_scan_worker_validation.py index 3c0a22559..00ae5e815 100644 --- a/tests/driver/test_scan_worker_validation.py +++ b/tests/driver/test_scan_worker_validation.py @@ -184,7 +184,7 @@ def test_worker_refuses_cached_configuration_mismatch(point): def test_uninstrumented_retention_validation_rejects_unknown_fields(): with pytest.raises(DriverError, match="fields must be"): - _scan_run._validate_options("unknown", (), "none", 10.0, ()) + _scan_run._validate_options("unknown", (), "none", ()) def test_probe_does_not_charge_noise_or_periodic_retention_when_disabled(point): @@ -217,7 +217,8 @@ def incomplete(*args, **kwargs): run_scan( scan, lambda point: simulation, output=destination, progress="none" ) - assert scans.ScanOutput(destination).status.tolist() == ["running"] + # The aborted scan gives its claim back: a rerun computes the point. + assert scans.ScanOutput(destination).status.tolist() == ["todo"] def test_execution_provenance_handles_uninspectable_builder(tmp_path, monkeypatch): diff --git a/tests/driver/test_scans.py b/tests/driver/test_scans.py index e26d2d7b2..560f1a980 100644 --- a/tests/driver/test_scans.py +++ b/tests/driver/test_scans.py @@ -8,6 +8,7 @@ import logging import math import os +import re import time from collections.abc import Mapping from typing import cast @@ -24,6 +25,7 @@ simulation_bound, ) from solprop import _process +from solprop.driver import _scan_run from solprop.driver._scan_context import _EXECUTOR from solprop.driver._scan_model import name_seed from solprop.driver.executors import Local, pool @@ -35,6 +37,7 @@ from solprop.noise import input_noise from solprop.output._scan_lock import lock_path from solprop.output.hdf5 import _dataset, _group +from solprop.output.scan import ScanWriter from solprop.processing import scans from solprop.pulses import SechPulse from solprop.scan import main @@ -115,23 +118,58 @@ def test_scan_order_global_subsets_and_seed_independence(): assert [p.seed for p in explicit.points()] == [7, 8] +def test_derived_point_seeds_follow_the_documented_rule(): + # Literals computed once from the documented derivations: a scan's base seed, or the + # little-endian first eight bytes of SHA-256 of its name, as the root entropy of + # SeedSequence([root, global_index]).generate_state(1, dtype=uint64)[0]. + assert [name_seed("unseeded", index) for index in (0, 1)] == [ + 13766556482837212248, + 10884373728482101469, + ] + assert [p.seed for p in Scan("s", base_seed=91, x=[0, 1]).points()] == [ + 15497448034978523998, + 1624429969735552845, + ] + + +@pytest.mark.parametrize( + ("values", "row"), + [ + ([1.0, 2.5], "2 values, 1 to 2.5"), + (["He", "Ar"], "2 values, 'He' to 'Ar'"), + ([], "no values"), + ([{"gas": "He"}], "1 values, {'gas': 'He'} to {'gas': 'He'}"), + ], +) +def test_a_printed_scan_describes_each_axis_whatever_its_kind(values, row): + lines = str(Scan("scan", power=values)).splitlines() + key, value = lines[1].split(":", 1) + assert (key.strip(), value.strip()) == ("power", row) + + @pytest.mark.parametrize( - "call", + ("call", "message"), [ - lambda: Scan("bad/name"), - lambda: Scan("scan", power=[[1, 2]]), - lambda: Scan("scan", seed=[-1]), - lambda: Scan("scan", base_seed=-1), - lambda: Scan("scan", power=[1]).point(1), - lambda: Scan("scan", power=[1]).chunk(1, 1), - lambda: Scan("scan", power=[1]).subset([0, 0]), - lambda: Scan("scan", power=[1]).subset([0]).add("extra", [1]), - lambda: Scan("scan", power=[1]).add("power", [2]), - lambda: Scan("scan").add("", [1]), + (lambda: Scan("bad/name"), "no path separators"), + (lambda: Scan("scan", power=[[1, 2]]), "must be one-dimensional"), + (lambda: Scan("scan", seed=[-1]), "seed values must be non-negative"), + (lambda: Scan("scan", base_seed=-1), "base_seed must be a non-negative"), + (lambda: Scan("scan", power=[1]).point(1), "outside scan size 1"), + (lambda: Scan("scan", power=[1]).chunk(1, 1), "chunk requires n > 0"), + (lambda: Scan("scan", power=[1]).subset([0, 0]), "must be unique members"), + ( + lambda: Scan("scan", power=[1]).subset([0]).add("extra", [1]), + "cannot add variables to a selected scan", + ), + ( + lambda: Scan("scan", power=[1]).add("power", [2]), + "repeated scan variable 'power'", + ), + (lambda: Scan("scan").add("", [1]), "repeated scan variable ''"), ], ) -def test_scan_invalid_declarations(call): - with pytest.raises(DriverError): +def test_scan_invalid_declarations(call, message): + with pytest.raises(DriverError, match=re.escape(message)): call() @@ -355,8 +393,9 @@ def test_periodic_statistics_equal_single_run(tmp_path): ) -def test_scan_reclaims_stale_running_and_leaves_recent_claim(tmp_path): - +def test_scan_reclaims_a_running_point_whatever_its_age(tmp_path): + # The controller holds the file's lock for its whole session, so a `running` + # mark it finds was left by a controller that has gone, however recent. scan = Scan("scan", power=[1.0, 2.0]) path = tmp_path / "scan.h5" output = run_scan(scan.subset([0]), build_point, output=path, progress="none") @@ -364,13 +403,86 @@ def test_scan_reclaims_stale_running_and_leaves_recent_claim(tmp_path): _dataset(file, "points/status")[1] = "running" _dataset(file, "points/updated")[1] = time.time() run_scan(scan, build_point, output=path, progress="none") - assert output.status.tolist() == ["done", "running"] - with h5py.File(path, "a") as file: - _dataset(file, "points/updated")[1] = 0.0 + assert output.status.tolist() == ["done", "done"] + + +class ClaimThenFail: + """An executor that claims every point and then fails before running any.""" + + def run(self, points, work): + claimed = list(points) + assert claimed + raise RuntimeError("deliberate executor failure") + yield # a generator, as an executor's run is + + +class ClaimThenReturn: + """An executor that claims every point and then ends without running any.""" + + def run(self, points, work): + claimed = list(points) + assert claimed + return + yield # a generator, as an executor's run is + + +def test_a_failed_executor_gives_its_claimed_points_back(tmp_path): + scan = Scan("scan", power=[1.0, 2.0]) + path = tmp_path / "scan.h5" + with pytest.raises(RuntimeError, match="deliberate executor failure"): + run_scan( + scan, build_point, output=path, executor=ClaimThenFail(), progress="none" + ) + output = scans.ScanOutput(path) + assert output.status.tolist() == ["todo", "todo"] run_scan(scan, build_point, output=path, progress="none") assert output.status.tolist() == ["done", "done"] +@pytest.mark.parametrize( + ("executor", "raised"), + [ + (ClaimThenFail(), (RuntimeError, "deliberate executor failure")), + (ClaimThenReturn(), (OSError, "deliberate write failure")), + ], + ids=["failing", "ending"], +) +def test_a_failing_release_still_closes_the_writer( + tmp_path, monkeypatch, caplog, executor, raised +): + """Giving the claims back writes to the file; when that fails too, the writer is + still closed, so its lock is released. A failing scan reports its own error and + logs the release's; a scan that ended reports the release's.""" + closed = [] + close = ScanWriter.close + + def recording_close(self, **keywords): + closed.append(self.path) + close(self, **keywords) + + def failing_release(writer, index, claim): + raise OSError("deliberate write failure") + + monkeypatch.setattr(ScanWriter, "close", recording_close) + monkeypatch.setattr(_scan_run, "_release", failing_release) + path = tmp_path / "scan.h5" + with ( + caplog.at_level(logging.ERROR, logger="solprop.driver._scan_run"), + pytest.raises(raised[0], match=raised[1]), + ): + run_scan( + Scan("scan", power=[1.0, 2.0]), + build_point, + output=path, + executor=executor, + progress="none", + ) + assert closed == [path] + # The release's own error is logged when the scan's replaces it, not lost. + logged = "deliberate write failure" in caplog.text + assert logged == isinstance(executor, ClaimThenFail) + + def test_resume_builder_failure_keeps_the_completed_point_and_its_arrays( tmp_path, caplog ): @@ -412,17 +524,22 @@ def test_pool_rejects_unpickleable_builder_before_output(tmp_path): @pytest.mark.parametrize( - "controls", + ("controls", "message"), [ - {"fields": "planes"}, - {"fields": "none", "field_planes": [0]}, - {"stale_age": 0.0}, - {"stats": "energy"}, - {"reductions": [scans.peak_power(), scans.peak_power()]}, + ({"fields": "planes"}, "field_planes is required exactly when"), + ( + {"fields": "none", "field_planes": [0]}, + "field_planes is required exactly when", + ), + ({"stats": "energy"}, "stats must be all, none or a sequence of names"), + ( + {"reductions": [scans.peak_power(), scans.peak_power()]}, + "reduction names must be unique", + ), ], ) -def test_scan_rejects_invalid_retention(tmp_path, controls): - with pytest.raises(DriverError): +def test_scan_rejects_invalid_retention(tmp_path, controls, message): + with pytest.raises(DriverError, match=message): run_scan( Scan("scan", power=[1.0]), build_point, diff --git a/tests/driver/test_sep12_sep14_integration.py b/tests/driver/test_sep12_sep14_integration.py index a7bc4cf76..95c960481 100644 --- a/tests/driver/test_sep12_sep14_integration.py +++ b/tests/driver/test_sep12_sep14_integration.py @@ -35,7 +35,7 @@ TDSEGasResponse, TDSESampling, ) -from solprop.output import MemoryOutput, open_file, resume +from solprop.output import MemoryOutput, open_file, read_resume_state from solprop.stats import StatsSpec from solprop.stepper.multistep import Multistep from solprop.translate.routes import tdse_descriptor @@ -241,7 +241,7 @@ def test_interior_natural_save_resumes_without_resetting_atomic_budget( path = tmp_path / "natural-atomic.h5" with pytest.raises(ResponseBudgetError): simulation.run(path, progress="none") - first = resume(path) + first = read_resume_state(path) assert first.checkpoint is not None and first.checkpoint.landed assert first.checkpoint.next_save_index == 0 assert first.n_saved == 2 @@ -256,7 +256,7 @@ def test_interior_natural_save_resumes_without_resetting_atomic_budget( with pytest.raises(ResponseBudgetError): simulation.run(path, resume=True, progress="none") - second = resume(path) + second = read_resume_state(path) assert len(bindings) == 2 and bindings[1].purposes == [] assert second.outcome is not None assert second.outcome.atomic_calls == first.outcome.atomic_calls @@ -278,7 +278,7 @@ def test_interior_natural_save_resumes_without_resetting_atomic_budget( simulation.settings, tdse_execution=TDSEExecution(max_atomic_calls=20) ) simulation.run(path, resume=True, progress="none") - final = resume(path) + final = read_resume_state(path) assert final.checkpoint is None assert final.plane.z == simulation.grid.length assert final.outcome is not None and final.outcome.status == "complete" diff --git a/tests/driver/test_simulation.py b/tests/driver/test_simulation.py index d0792cc9c..d210f87df 100644 --- a/tests/driver/test_simulation.py +++ b/tests/driver/test_simulation.py @@ -8,6 +8,7 @@ import dataclasses import math import pickle +import re import subprocess import sys import warnings @@ -132,6 +133,21 @@ def test_settings_assigned_after_the_first_translation_are_refused( assert simulation.settings is settings +def test_the_execution_settings_change_after_translation_and_the_refusal_names_them( + build_simulation, +): + simulation = build_simulation(n_save=2) + simulation.translate() + simulation.settings = dataclasses.replace(simulation.settings, node_budget=2**20) + assert simulation.settings.node_budget == 2**20 + allowed = ( + "only backend, node_budget, resume_history, tdse_execution, fields, " + "field_planes and boundary_check may change after translation" + ) + with pytest.raises(DriverError, match=re.escape(allowed)): + simulation.settings = dataclasses.replace(simulation.settings, dz_max=1e-4) + + @pytest.mark.parametrize("name", sorted(simulation_module._FIXED_INPUTS)) def test_assigning_what_a_simulation_is_built_from_is_refused(build_simulation, name): """The input and the record are built from these at construction, so a new diff --git a/tests/driver/test_snapshot_integrity.py b/tests/driver/test_snapshot_integrity.py index 456d0fc85..04a35396c 100644 --- a/tests/driver/test_snapshot_integrity.py +++ b/tests/driver/test_snapshot_integrity.py @@ -6,6 +6,7 @@ import hashlib import json +import re from typing import Any import h5py @@ -46,26 +47,29 @@ def pair(fake, tmp_path): return next(controller._directory.glob("snapshot-*")) +# Each row names the message of the check it guards, so a row fails when its own check +# goes rather than passing on a later one. An archive with no sessions left is refused +# by the identity check, which needs a session to compare the run's UUID with. @pytest.mark.parametrize( - "change", + ("change", "message"), [ - "omitted", - "relative", - "filename", - "uuid", - "sessions", - "session_index", - "session_uuid", - "closed", - "counters", - "configuration", - "provider", - "evaluations", - "decision", - "incomplete", + ("omitted", "snapshot omits the referenced TDSE archive"), + ("relative", "requires a relative TDSE archive reference"), + ("filename", "archive filename does not match the optical reference"), + ("uuid", "archive UUID mismatch"), + ("sessions", "archive UUID mismatch"), + ("session_index", "archive session mismatch"), + ("session_uuid", "archive session mismatch"), + ("closed", "archive session mismatch"), + ("counters", "archive counters mismatch"), + ("configuration", "configuration/provider identity mismatch"), + ("provider", "configuration/provider identity mismatch"), + ("evaluations", "incomplete or mismatched evaluations/trials"), + ("decision", "incomplete or mismatched evaluations/trials"), + ("incomplete", "incomplete or mismatched evaluations/trials"), ], ) -def test_mixed_pair_is_rejected_even_with_recomputed_checksums(pair, change): +def test_mixed_pair_is_rejected_even_with_recomputed_checksums(pair, change, message): manifest_path = pair / "manifest.json" manifest = json.loads(manifest_path.read_text(encoding="utf-8")) optical, archive = [pair / row["path"] for row in manifest["files"]] @@ -89,7 +93,7 @@ def reference(outcome): ) manifest_path.chmod(0o600) manifest_path.write_text(json.dumps(manifest), encoding="utf-8") - with pytest.raises(OutputError): + with pytest.raises(OutputError, match=re.escape(message)): read_snapshot(pair) diff --git a/tests/driver/test_snapshots.py b/tests/driver/test_snapshots.py index e35974703..a0f79ba53 100644 --- a/tests/driver/test_snapshots.py +++ b/tests/driver/test_snapshots.py @@ -35,9 +35,9 @@ TDSEArchive, open_file, open_tdse_archive, + read_resume_state, read_snapshot, restore_snapshot, - resume, ) from solprop.output import snapshots as module from solprop.output.store import PlaneStore @@ -181,7 +181,7 @@ def watched(*args): def _verify_tdse_generation(generation, destination, run_uuid, startup, caplog): info = read_snapshot(generation) - state = resume(info.files.output) + state = read_resume_state(info.files.output) assert state.outcome is not None assert state.outcome.status == "running" and state.march is not None assert state.plane.z == state.march.z == info.z @@ -211,7 +211,7 @@ def _verify_tdse_generation(generation, destination, run_uuid, startup, caplog): tdse_archive=restored.tdse_archive, ) assert "continuing the Adams history" in caplog.text - after = resume(restored.output) + after = read_resume_state(restored.output) assert after.outcome is not None assert after.outcome.status == "complete" # The pressure kink restarts both histories once; restoration adds no startup. @@ -243,11 +243,11 @@ def test_ordinary_snapshot_resumes_in_a_fresh_process(backend, tmp_path): """ import sys from tests.driver.test_snapshots import ordinary -from solprop.output import restore_snapshot, resume +from solprop.output import restore_snapshot, read_resume_state files = restore_snapshot(sys.argv[1], sys.argv[2]) -before = resume(files.output) +before = read_resume_state(files.output) ordinary(sys.argv[3]).run(files.output, resume=True, progress="none") -after = resume(files.output) +after = read_resume_state(files.output) assert after.outcome.status == "complete" assert (after.outcome.logical_calls.get("startup", 0) == before.outcome.logical_calls.get("startup", 0)) @@ -279,7 +279,9 @@ def test_snapshot_requires_history_even_above_the_automatic_limit( assert controller.last_result.disposition == "published" assert controller.last_result.generation is not None assert ( - resume(read_snapshot(controller.last_result.generation).files.output).march + read_resume_state( + read_snapshot(controller.last_result.generation).files.output + ).march is not None ) @@ -319,7 +321,7 @@ def test_snapshots_do_not_reset_cumulative_atomic_budget(fake, tmp_path): tdse_archive=TDSEArchive(tmp_path / "run.tdse.h5"), progress=Requests(controller), ) - state = resume(tmp_path / "run.h5") + state = read_resume_state(tmp_path / "run.h5") assert state.outcome is not None assert state.outcome.status == "budget_exhausted" assert plain(state.outcome.atomic_calls)["attempted"] == 30 @@ -330,7 +332,7 @@ def test_snapshots_do_not_reset_cumulative_atomic_budget(fake, tmp_path): resume=True, tdse_archive=TDSEArchive(tmp_path / "run.tdse.h5"), ) - state = resume(tmp_path / "run.h5") + state = read_resume_state(tmp_path / "run.h5") assert state.outcome is not None assert plain(state.outcome.atomic_calls)["attempted"] == 30 @@ -493,7 +495,7 @@ def adams(**keywords): fields = [] for index, generation in enumerate(generations): files = restore_snapshot(generation, tmp_path / f"restore-{index}") - march = resume(files.output).march + march = read_resume_state(files.output).march assert march is not None and march.rows["store"].any() with caplog.at_level(logging.INFO, logger="solprop.driver"): final = _run(adams(), files.output, resume=True) @@ -554,7 +556,7 @@ def step(self, z, dz, accepted): with h5py.File(path, "r+") as file: del file["meta/outcome"] del file["terminal_checkpoint"] - assert resume(path).outcome is None + assert read_resume_state(path).outcome is None controller = SnapshotController(tmp_path / "snapshots") controller.request() _run(ordinary(), path, resume=True, snapshots=controller) @@ -568,7 +570,7 @@ def step(self, z, dz, accepted): def _history(path): """Return a closed file's whole step history: starts, lengths and acceptance.""" - history = resume(path).history + history = read_resume_state(path).history return history.z, history.h, history.accepted @@ -619,7 +621,7 @@ def test_snapshots_without_step_planes_resume_from_a_running_checkpoint(tmp_path running = 0 for index, generation in enumerate(generations): files = restore_snapshot(generation, tmp_path / f"restore-{index}") - state = resume(files.output) + state = read_resume_state(files.output) if state.checkpoint is not None: running += 1 assert state.checkpoint.landed @@ -652,7 +654,7 @@ def test_a_resume_from_a_running_checkpoint_keeps_the_history_once(tmp_path): _run(ordinary(step_planes=0), working, snapshots=controller) (generation,) = controller._directory.glob("snapshot-*") files = restore_snapshot(generation, tmp_path / "restored") - state = resume(files.output) + state = read_resume_state(files.output) assert state.checkpoint is not None before = state.history.n_steps assert before >= 1 @@ -666,7 +668,7 @@ def test_a_resume_from_a_running_checkpoint_keeps_the_history_once(tmp_path): def _assert_checkpoint_holds_every_attempt(path): """Assert a file's terminal checkpoint carries every attempt since the launch.""" - state = resume(path) + state = read_resume_state(path) assert state.checkpoint is not None assert state.outcome is not None and state.outcome.status == "failed" history = state.history @@ -722,7 +724,7 @@ def step(self, z, dz, accepted): ordinary(step_planes=0).run(path, snapshots=controller, progress=Interrupt()) assert len(list(controller._directory.glob("snapshot-*"))) == 1 _assert_checkpoint_holds_every_attempt(path) - assert resume(path).history.accepted.sum() >= 2 + assert read_resume_state(path).history.accepted.sum() >= 2 _run(ordinary(step_planes=0), path, resume=True) assert_contiguous(path, 0.001) @@ -819,7 +821,7 @@ def test_dense_snapshots_resume_without_losing_or_repeating_a_plane( fields = [live[-1]] for index, generation in enumerate(generations): files = restore_snapshot(generation, tmp_path / f"restore-{index}") - state = resume(files.output) + state = read_resume_state(files.output) # Every snapshot follows an interpolated plane, so each is a running checkpoint # at an accepted endpoint past every plane saved before it. assert state.checkpoint is not None and state.checkpoint.landed diff --git a/tests/driver/test_source_worker.py b/tests/driver/test_source_worker.py index d268a3869..4172a3030 100644 --- a/tests/driver/test_source_worker.py +++ b/tests/driver/test_source_worker.py @@ -164,6 +164,24 @@ def test_the_worker_environment_drops_native_s_own_wait_settings_only(): assert kept["GOMP_SPINCOUNT"] == "5" and "KMP_BLOCKTIME" not in kept +@pytest.mark.skipif(sys.flags.safe_path, reason="no script directory is on the path") +def test_the_worker_import_path_leaves_out_a_script_s_own_directory( + monkeypatch, tmp_path +): + # A script's directory may hold a module named like a standard-library one, which + # the worker's -P keeps off its path; handing it over in PYTHONPATH would undo that. + script = tmp_path / "script.py" + script.write_text("", encoding="utf-8") + site = str(tmp_path / "site-packages") + monkeypatch.setattr(sys, "argv", [str(script)]) + monkeypatch.setattr(sys, "path", [str(tmp_path), site]) + assert worker_environment({}, {})["PYTHONPATH"] == site + # Run without a script (``python -c``), the path is handed over whole. + monkeypatch.setattr(sys, "argv", ["-c"]) + expected = os.pathsep.join([str(tmp_path), site]) + assert worker_environment({}, {})["PYTHONPATH"] == expected + + @pytest.mark.medium def test_the_native_wait_settings_are_solprop_native_s_own(monkeypatch): """The worker removes exactly what solprop-native sets (ADR-071).""" diff --git a/tests/driver/test_step_planes.py b/tests/driver/test_step_planes.py index 5afccb211..b8c97e32d 100644 --- a/tests/driver/test_step_planes.py +++ b/tests/driver/test_step_planes.py @@ -22,10 +22,9 @@ from march_bounds import TIGHTER, assert_in_envelope from solprop.backends import available from solprop.driver import Simulation -from solprop.driver.resume import _interpolated from solprop.exceptions import TranslationError from solprop.log import NullReporter -from solprop.output.hdf5 import resume +from solprop.output.hdf5 import read_resume_state from solprop.stepper import FixedSchedule, RungeKutta from solprop.stepper.multistep import Multistep @@ -175,10 +174,10 @@ def test_a_run_stopped_on_a_saved_step_resumes(tmp_path): whole = soliton(step_planes=1).run(progress="none") with pytest.raises(RuntimeError, match="stopped"): soliton(step_planes=1).run(path, progress=Stop(5)) - state = resume(path) - assert not _interpolated(state) + state = read_resume_state(path) + assert not state.interpolated soliton(step_planes=1).run(path, resume=True, progress="none") - finished = resume(path) + finished = read_resume_state(path) assert finished.plane.z == pytest.approx(0.012, rel=1e-12) # A fresh start of the controller: the same requested planes to the tolerance. final = np.asarray(whole.fields(convention="fft")[-1]) diff --git a/tests/driver/test_stop.py b/tests/driver/test_stop.py index 119d614ce..bdd01bfb8 100644 --- a/tests/driver/test_stop.py +++ b/tests/driver/test_stop.py @@ -19,6 +19,7 @@ from solprop.grid import EnvelopeGrid from solprop.log import NullReporter from solprop.output.hdf5 import open_file +from solprop.output.memory import MemoryOutput from solprop.stepper import FixedSchedule, LowStorageRungeKutta, Multistep, RungeKutta pytestmark = pytest.mark.filterwarnings("ignore::solprop.exceptions.BoundaryWarning") @@ -330,3 +331,21 @@ def step(self, z, dz, accepted): _scheduled(build_simulation).run( tmp_path / "foreign.h5", progress=Foreign(), stop=threading.Event() ) + + +class FailingClose(MemoryOutput): + """An in-memory output whose close fails, after it has finished the run.""" + + def close(self): + super().close() + raise OSError("deliberate close failure") + + +def test_a_close_failure_after_the_run_s_own_stop_is_raised(build_simulation): + # The stop is not an error, but a resource the stopped run could not close is. + flag = threading.Event() + flag.set() + output = FailingClose() + with pytest.raises(OSError, match="deliberate close failure"): + _scheduled(build_simulation).run(output, stop=flag) + assert output.n_saved == 1 diff --git a/tests/driver/test_taper_coupling.py b/tests/driver/test_taper_coupling.py index fdfbd8707..50c20632b 100644 --- a/tests/driver/test_taper_coupling.py +++ b/tests/driver/test_taper_coupling.py @@ -16,6 +16,7 @@ import itertools import math +import re import warnings from typing import cast @@ -554,6 +555,21 @@ def test_a_lossy_block_over_a_long_step_is_refused_naming_the_opt_out(): assert varying(dz_max=1e-2, schedule=None).translate().linear.coupled_flow +def test_the_conditioning_refusal_names_the_largest_step_it_admits(): + """The bound is ``exp(dz_max spread)``, so the cap it names is exact: admitted.""" + with pytest.raises(TranslationError) as refusal: + varying(dz_max=0.1, schedule=None).translate() + found = re.search(r"dz_max of at most ([0-9.e+-]+) m", str(refusal.value)) + assert found is not None, str(refusal.value) + cap = float(found.group(1)) + # Below the refused step, and above the 1e-2 m the test above admits. + assert 1e-2 <= cap < 0.1 + assert varying(dz_max=cap, schedule=None).translate().linear.coupled_flow + # Three significant digits, rounded down: one more unit in the last is refused. + with pytest.raises(TranslationError, match="inverse conditioning reaches"): + varying(dz_max=cap * 1.01, schedule=None).translate() + + def test_a_second_field_component_beside_the_coupling_is_refused(): """The flow contracts the channel axis alone: two state components are refused.""" simulation = lossless() diff --git a/tests/driver/test_tdse_archive_run.py b/tests/driver/test_tdse_archive_run.py index 6bbf70ba7..aa567cbc8 100644 --- a/tests/driver/test_tdse_archive_run.py +++ b/tests/driver/test_tdse_archive_run.py @@ -48,7 +48,7 @@ TDSEArchive, open_file, open_tdse_archive, - resume, + read_resume_state, ) from solprop.output import tdse_archive as archive_module from solprop.output.tdse_archive import TDSE_ARCHIVE_SCHEMA @@ -191,7 +191,7 @@ def test_the_optical_file_records_the_archive_and_reads_without_it(fake, tmp_pat assert record["run_uuid"] == run_uuid assert record["path"] == "../side/run.tdse.h5" assert saved.n_saved > 2 and np.all(np.isfinite(saved.fields(convention="fft"))) - final = resume(optical) + final = read_resume_state(optical) assert final.outcome is not None and final.outcome.status == "complete" closing = plain(final.outcome.execution)["tdse"]["archive"] assert closing["run_uuid"] == run_uuid and closing["evaluations"] > 0 @@ -205,7 +205,7 @@ def test_a_resume_appends_a_session_under_the_same_run_uuid(fake, tmp_path): sidecar = tmp_path / "run.tdse.h5" with pytest.raises(ResponseBudgetError): _run(_limited(30), optical, tdse_archive=TDSEArchive(sidecar)) - stopped = resume(optical) + stopped = read_resume_state(optical) assert stopped.outcome is not None and stopped.outcome.status == "budget_exhausted" with open_tdse_archive(sidecar) as reader: first_count = len(list(reader.evaluations())) @@ -227,7 +227,7 @@ def test_a_resume_appends_a_session_under_the_same_run_uuid(fake, tmp_path): assert all(item.role != "diagnostic" for item in resumed) # A fresh startup restarts the history after the resume. assert resumed[0].role == "startup" and resumed[0].trial == 0 - final = resume(optical) + final = read_resume_state(optical) assert final.outcome is not None and final.outcome.status == "complete" assert plain(final.outcome.execution)["tdse"]["archive"]["session"] == 1 @@ -241,7 +241,7 @@ def test_an_archive_first_requested_by_a_resume_starts_its_own_file(fake, tmp_pa with open_tdse_archive(sidecar) as reader: assert [session.kind for session in reader.sessions] == ["resume"] run_uuid = reader.run_uuid - final = resume(optical) + final = read_resume_state(optical) assert final.outcome is not None # The resumed execution's record names the archive it started. assert plain(final.outcome.execution)["tdse"]["archive"]["run_uuid"] == run_uuid @@ -271,10 +271,15 @@ def test_an_existing_unrelated_file_is_refused_before_any_atomic_work( assert not optical.exists() -def test_archive_requests_the_run_cannot_honour_are_refused(fake, tmp_path): +def test_archive_requests_the_run_cannot_honour_are_refused( + fake, tmp_path, monkeypatch +): optical = tmp_path / "run.h5" with pytest.raises(DriverError, match="must differ from the optical"): _run(natural_simulation(), optical, tdse_archive=TDSEArchive(optical)) + # The refusal is the run's own, so the suite's runtime type check is set aside on + # the two methods the argument passes through. + monkeypatch.setattr(Simulation, "_execute", inspect.unwrap(Simulation._execute)) with pytest.raises(DriverError, match="TDSEArchive"): inspect.unwrap(Simulation._run)( natural_simulation(), progress="none", tdse_archive="x.h5" @@ -317,7 +322,7 @@ def failing(self, group, raw, schema, where): _run(natural_simulation(), optical, tdse_archive=TDSEArchive(sidecar)) # The failing write followed the provider call it records; nothing came after. assert len(fake.calls) == written[-1] - stopped = resume(optical) + stopped = read_resume_state(optical) assert stopped.outcome is not None and stopped.outcome.status == "failed" assert "TDSEArchiveError" in stopped.outcome.message assert stopped.checkpoint is not None or stopped.n_saved >= 1 diff --git a/tests/driver/test_tdse_binding.py b/tests/driver/test_tdse_binding.py index a390c9c3a..5b7f37b45 100644 --- a/tests/driver/test_tdse_binding.py +++ b/tests/driver/test_tdse_binding.py @@ -536,8 +536,11 @@ def test_binding_module_import_does_not_load_optional_engine(): def test_binding_rejects_unsupported_interpreter_before_native_import(monkeypatch): monkeypatch.setattr(_pyroraptor.sys, "version_info", (3, 15, 0)) source_channel.in_process(monkeypatch) - with pytest.raises(BackendError, match=r"Python 3\.14"): + with pytest.raises( + BackendError, match=r"supports Python 3\.14 only, and this is Python 3\.15" + ) as refusal: tdse.basis_from_preset("helium", "production") + assert "pinned" not in str(refusal.value) def test_binding_without_distribution_metadata_still_records_native_identity( diff --git a/tests/driver/test_tdse_entry.py b/tests/driver/test_tdse_entry.py index bf4b22610..9676bbaac 100644 --- a/tests/driver/test_tdse_entry.py +++ b/tests/driver/test_tdse_entry.py @@ -21,7 +21,6 @@ assert_record_numbers, record_skeleton, skeleton_hash, - with_former_names, ) from solprop.driver import Simulation, prop_capillary from solprop.driver import tdse as runtime @@ -229,18 +228,15 @@ def test_tdse_output_defaults_and_their_explicit_overrides(): assert SimulationSettings.__dataclass_fields__["step_planes"].default == 0 -# Computed on the base commit of SEP 20 Phase 1: a rate-based capillary call without -# `tdse` builds this exact configuration, responses, itinerary and statistics. A change -# of optmat's models would legitimately move it, as optmat 0.10's versioned equations -# of state did; recompute it there, not here. Until SEP 25 one SHA-256 pinned the whole -# record, last bits of its derived numbers included, which another platform's libm and -# FFT move. Its structure is still hashed -# exactly; its numbers are stored beside this test (recorded from the state the -# former digest certified) and compared within a bound (tests/record_numbers.py). -_UNCHANGED = "fa82edecbf9b7c1b03cac3e0229915882eb133035b98d541e14cde448a1840ca" +# A rate-based capillary call without `tdse` builds this configuration, responses, +# itinerary and statistics. Its structure is identity metadata and is hashed exactly; +# its numbers, whose last bits another platform's libm and FFT move, are stored beside +# this test and compared within a bound (tests/record_numbers.py). A change of optmat's +# models legitimately moves them: recompute them there, not here. +_CAPILLARY_DEFAULTS = "e164082efb1559372f4bb2aa1999e7c95654289315b35413d508a2ddb5140381" -def test_without_tdse_a_representative_call_is_unchanged(): +def test_a_capillary_call_without_tdse_builds_its_recorded_configuration(): with warnings.catch_warnings(): warnings.simplefilter("ignore", MaterialRangeWarning) simulation = Simulation.from_capillary( @@ -269,14 +265,14 @@ def test_without_tdse_a_representative_call_is_unchanged(): "tdse_execution": simulation.settings.tdse_execution, } skeleton, numbers, floors = record_skeleton( - with_former_names(json.loads(json.dumps(record, sort_keys=True, default=repr))) + json.loads(json.dumps(record, sort_keys=True, default=repr)) ) - assert skeleton_hash(skeleton) == _UNCHANGED + assert skeleton_hash(skeleton) == _CAPILLARY_DEFAULTS assert_record_numbers( numbers, floors, Path(__file__).with_suffix("") - / "test_without_tdse_a_representative_call_is_unchanged.npz", + / "test_a_capillary_call_without_tdse_builds_its_recorded_configuration.npz", ) assert simulation.settings.step_planes == 0 assert len(np.asarray(simulation.settings.save_planes)) == 200 diff --git a/tests/driver/test_tdse_entry/test_without_tdse_a_representative_call_is_unchanged.npz b/tests/driver/test_tdse_entry/test_a_capillary_call_without_tdse_builds_its_recorded_configuration.npz similarity index 100% rename from tests/driver/test_tdse_entry/test_without_tdse_a_representative_call_is_unchanged.npz rename to tests/driver/test_tdse_entry/test_a_capillary_call_without_tdse_builds_its_recorded_configuration.npz diff --git a/tests/driver/test_tdse_gated_derivative_run.py b/tests/driver/test_tdse_gated_derivative_run.py index 65fed1bad..50cff97ed 100644 --- a/tests/driver/test_tdse_gated_derivative_run.py +++ b/tests/driver/test_tdse_gated_derivative_run.py @@ -45,7 +45,7 @@ TDSEGasResponse, TDSESampling, ) -from solprop.output import open_file, resume +from solprop.output import open_file, read_resume_state from solprop.stats import StatsSpec from solprop.stepper.multistep import Multistep from solprop.translate.routes import tdse_descriptor @@ -159,7 +159,7 @@ def test_sae_run_records_certificate_round_trips_and_resumes( path = tmp_path / "held.h5" with pytest.raises(ResponseBudgetError): simulation.run(path, progress="none") - first = resume(path) + first = read_resume_state(path) assert first.outcome is not None and first.outcome.status == "budget_exhausted" with open_file(path) as saved: assert saved.metadata is not None @@ -177,7 +177,7 @@ def test_sae_run_records_certificate_round_trips_and_resumes( simulation.settings, tdse_execution=TDSEExecution(max_atomic_calls=1000) ) simulation.run(path, resume=True, progress="none") - final = resume(path) + final = read_resume_state(path) assert final.outcome is not None and final.outcome.status == "complete" with open_file(path) as saved: assert saved.metadata is not None @@ -331,7 +331,7 @@ def test_hacc_run_round_trips_and_resumes(fake, tmp_path, window): simulation.settings, tdse_execution=TDSEExecution(max_atomic_calls=1000) ) _quiet(simulation, path, resume=True) - final = resume(path) + final = read_resume_state(path) assert final.outcome is not None and final.outcome.status == "complete" with open_file(path) as saved: assert saved.metadata is not None diff --git a/tests/driver/test_tdse_hacc_run.py b/tests/driver/test_tdse_hacc_run.py index f2cc8bf46..24c9785ed 100644 --- a/tests/driver/test_tdse_hacc_run.py +++ b/tests/driver/test_tdse_hacc_run.py @@ -39,7 +39,7 @@ TDSEUnqualifiedModelWarning, ) from solprop.nonlinear.tdse import TDSEConsistency, TDSEExecution -from solprop.output import MemoryOutput, open_file, resume +from solprop.output import MemoryOutput, open_file, read_resume_state from solprop.output.metadata import SCHEMA_VERSION from solprop.stats import StatsSpec @@ -112,7 +112,7 @@ def test_hacc_run_records_model_window_consistency_and_ledger(fake, cache, windo simulation = _simulation(atomic_window=window) output = _run(simulation) assert output.metadata is not None - assert output.metadata.schema_version == SCHEMA_VERSION == 4 + assert output.metadata.schema_version == SCHEMA_VERSION == 3 descriptor = json.loads(plain(output.metadata.tdse)["configuration_json"]) assert descriptor["schema"] == "solprop.tdse-descriptor.v5" assert descriptor["response"]["model"] == "hacc" @@ -189,7 +189,7 @@ def test_checkpoint_and_resume_keep_identities_and_never_repeat_the_check( simulation.settings = dataclasses.replace(simulation.settings, resume_history=False) with pytest.raises(ResponseBudgetError): _run(simulation, path) - first = resume(path) + first = read_resume_state(path) assert first.outcome is not None and first.outcome.status == "budget_exhausted" assert first.outcome.atomic_calls["diagnostic_calls"] == 1 with open_file(path) as saved: @@ -200,7 +200,7 @@ def test_checkpoint_and_resume_keep_identities_and_never_repeat_the_check( simulation.settings, tdse_execution=TDSEExecution(max_atomic_calls=1000) ) _run(simulation, path, resume=True) - final = resume(path) + final = read_resume_state(path) assert final.outcome is not None and final.outcome.status == "complete" with open_file(path) as saved: assert saved.metadata is not None @@ -235,7 +235,7 @@ def test_a_resume_without_the_cached_check_restores_its_accounting_first( simulation.settings = dataclasses.replace(simulation.settings, resume_history=False) with pytest.raises(ResponseBudgetError): _run(simulation, path) - first = resume(path) + first = read_resume_state(path) assert first.outcome is not None attempted = int(cast("int", first.outcome.atomic_calls["attempted"])) for entry in cache.glob("*.json"): @@ -244,7 +244,7 @@ def test_a_resume_without_the_cached_check_restores_its_accounting_first( simulation.settings, tdse_execution=TDSEExecution(max_atomic_calls=1000) ) _run(simulation, path, resume=True) - final = resume(path) + final = read_resume_state(path) assert final.outcome is not None and final.outcome.status == "complete" assert final.outcome.atomic_calls["diagnostic_calls"] == 2 assert int(cast("int", final.outcome.atomic_calls["attempted"])) > attempted diff --git a/tests/driver/test_tdse_natural_output.py b/tests/driver/test_tdse_natural_output.py index 43b0d6346..199d8d7f1 100644 --- a/tests/driver/test_tdse_natural_output.py +++ b/tests/driver/test_tdse_natural_output.py @@ -29,7 +29,7 @@ ) from solprop.log import NullReporter from solprop.nonlinear.tdse import TDSEExecution -from solprop.output.hdf5 import open_file, resume +from solprop.output.hdf5 import open_file, read_resume_state from solprop.stats import StatsSpec from solprop.stepper import PIController @@ -203,13 +203,13 @@ def test_a_callback_interruption_resumes_from_its_saved_endpoint(fake, tmp_path) _run(_simulation(), path, progress=_Stop(5)) with open_file(path) as saved: z_stopped = np.asarray(saved["z"]).copy() - stopped = resume(path) + stopped = read_resume_state(path) # The entrance is saved before the first callback, then five accepted steps. assert stopped.n_saved == 6 assert stopped.outcome is not None calls_at_stop = plain(stopped.outcome.atomic_calls)["attempted"] _run(_simulation(), path, resume=True) - finished = resume(path) + finished = read_resume_state(path) assert finished.plane.z == _LENGTH assert finished.outcome is not None and finished.outcome.status == "complete" with open_file(path) as saved: diff --git a/tests/driver/test_tdse_worker.py b/tests/driver/test_tdse_worker.py index fbaa7c064..fe72653b6 100644 --- a/tests/driver/test_tdse_worker.py +++ b/tests/driver/test_tdse_worker.py @@ -32,7 +32,7 @@ TDSEUnqualifiedModelWarning, ) from solprop.nonlinear.tdse import TDSEExecution -from solprop.output import open_file, resume +from solprop.output import open_file, read_resume_state DEADLINE = 10.0 """A test-harness bound on a cancellation; the production code has none.""" @@ -272,7 +272,7 @@ def test_a_run_stopped_during_an_atomic_call_checkpoints_its_last_step( with warnings.catch_warnings(): warnings.simplefilter("ignore", TDSEDomainWarning) simulation.run(path, progress="none", stop=flag) - stopped = resume(path) + stopped = read_resume_state(path) assert stopped.outcome is not None # As any stopped run: ended before its length, with a terminal checkpoint. assert stopped.outcome.status == "failed" diff --git a/tests/driver/test_temperature_paths.py b/tests/driver/test_temperature_paths.py index 75b756278..3a9ef7cb6 100644 --- a/tests/driver/test_temperature_paths.py +++ b/tests/driver/test_temperature_paths.py @@ -226,7 +226,7 @@ def test_three_populations_on_the_native_z_table_with_each_march(integrator): def test_the_run_records_the_temperature_path(): metadata = build(PAIR, WARM).metadata() configuration = cast("dict", serialise(metadata.configuration)) - assert metadata.schema_version == 4 + assert metadata.schema_version == 3 # The constructor's record keeps the path as the dataclass it is, and the # medium's record samples it with its breakpoints, as it does a density. assert configuration["capillary"]["temperature"] == { diff --git a/tests/driver/test_vector_raman_output.py b/tests/driver/test_vector_raman_output.py index 5e723b566..a478aeff6 100644 --- a/tests/driver/test_vector_raman_output.py +++ b/tests/driver/test_vector_raman_output.py @@ -16,7 +16,7 @@ ) from solprop.driver import Simulation, SimulationSettings from solprop.noise import input_noise, modified_noise -from solprop.output.hdf5 import resume +from solprop.output.hdf5 import read_resume_state from solprop.stats import StatsSpec from vector_raman_cases import raman_response, vector_translation @@ -84,7 +84,7 @@ def simulation(): else: # The same stored realisation carried by one march: its rounding budget. assert_matched(actual, expected, march, what=key) - metadata = resume(part).metadata - assert metadata.schema_version == 4 + metadata = read_resume_state(part).metadata + assert metadata.schema_version == 3 record = repr(metadata.configuration) assert "tensor_terms" in record and "rank2" in record and "isotropic" in record diff --git a/tests/driver/test_vincetti.py b/tests/driver/test_vincetti.py index 922723986..50a900605 100644 --- a/tests/driver/test_vincetti.py +++ b/tests/driver/test_vincetti.py @@ -24,7 +24,7 @@ from solprop.modes.base import alpha, beta, beta1, zdw from solprop.modes.quadrature import mode_matrix, transverse_quadrature from solprop.output import open_file -from solprop.output.hdf5 import resume +from solprop.output.hdf5 import read_resume_state from solprop.output.records import ModeRecord from solprop.physdata import Component, Mixture, Species, TabulatedSusceptibility from solprop.profiles import Constant @@ -353,7 +353,7 @@ def test_argon_kerr_readback_and_resume(tmp_path): output=path, progress=Interrupt(), ) - continued = resume(path).march is not None + continued = read_resume_state(path).march is not None # No range warning: optmat's models are qualified here (SEP 3, Phase 4a). with nullcontext(): prop_capillary( diff --git a/tests/modes/test_antiresonant.py b/tests/modes/test_antiresonant.py index 04cadd072..ae9561d8b 100644 --- a/tests/modes/test_antiresonant.py +++ b/tests/modes/test_antiresonant.py @@ -27,13 +27,13 @@ ) from solprop.modes.antiresonant import ( AREA_FACTOR, - CONVENTIONS, LEGACY_CONVENTIONS, MAX_TERMS, RADIUS_COEFFICIENT, ) from solprop.modes.base import alpha, beta2, db_per_m, loss_length, transmission from solprop.modes.protocol import ParameterisedMode +from solprop.physdata import Mixture from solprop.profiles import Linear GEOMETRIES = [ @@ -41,7 +41,6 @@ (5e-6, 80e-9, 1e-6, 10), (core_radius_from_gap(10e-6, n_tubes=8, gap=5e-6), 1e-6, 10e-6, 8), ] -LEGACY_RADIUS_COEFFICIENT = LEGACY_CONVENTIONS.radius_coefficient class LunaFormMode(VincettiMode): @@ -78,12 +77,38 @@ def test_luna_regression(): # the convention (c alpha/omega there, not c alpha/(2 omega)), so it is halved. assert result.real == pytest.approx(0.9998598623672965, rel=1e-13) assert result.imag == pytest.approx(3.4579455755137454e-8 / 2, rel=1e-12) - # Evacuated, so only the radius coefficient separates the production form: it - # gives Re n_eff = 0.9998591986525931 here, 6.64e-7 below Luna, and the same - # imaginary part. The difference is the closed form checked below. + # Evacuated, the three gas-index choices are identities and both forms carry the + # printed radius coefficient, so the production form gives Luna's value to the + # same rounding bound. production = replace(make_mode(GEOMETRIES[2]), cladding=1.44).neff(omega)[0] assert production.imag == result.imag - assert -7e-7 < production.real - result.real < -6e-7 + assert production.real == pytest.approx(0.9998598623672965, rel=1e-13) + + +def test_effective_radius_uses_the_printed_rosa_2021_coefficient(): + # Rosa, Melli and Vincetti (2021) eq. 10 prints the bracket 3 + 2 * 10 + # wavelength / R_co, a coefficient of 20. + assert RADIUS_COEFFICIENT == 20 + radius, wall, outer, count = GEOMETRIES[0] + mode = make_mode() + wavelength = np.array([800e-9, 1030e-9]) + omega = 2 * math.pi * C / wavelength + fit = mode._spectral_model(mode.sampled_terms(omega), radius, 0.0) + frequency = 2 * wall / wavelength * math.sqrt(1.45**2 - 1) + gap = mode.lattice.gap(radius) + expected = (1.027 + 1e-3 * (frequency + 2 / frequency**4)) * np.sqrt( + radius**2 + + count + / math.pi + * 3 + / 64 + * outer**2 + * (1 + (3 + 20 * wavelength / radius) * gap / outer) + ) + # A few roundings of the same arithmetic; a coefficient of 10 moves R_eff by 0.5 %. + np.testing.assert_allclose( + fit.effective_radius.value, expected, rtol=16 * np.finfo(float).eps, atol=0 + ) @given(st.floats(1e-6, 100e-6), st.floats(0, 10e-6), st.integers(3, 20)) @@ -227,7 +252,7 @@ def test_symbolic_derivative(case): values, derivative = mode._model_values(terms, case["geometry"][0], 1.0) # Sympy differentiates the independent expression of the production form, # including all material slopes. The 1e-10 bound is declared in advance; - # measured worst 1.07e-12 on the derivative and 5.0e-11 on the value, the + # measured worst 1.07e-12 on the derivative and 1.9e-11 on the value, the # latter at a near-zero refractivity where the gas square root's rounding # dominates (hence the absolute allowance). np.testing.assert_allclose( @@ -243,7 +268,7 @@ def test_symbolic_derivative(case): * (mode.u_nm * wavelength) ** 2 / np.real(fit.decrement.value - fit.correction.value) ) - # Measured worst 5.7e-13. + # Measured worst 5.4e-13. np.testing.assert_allclose(area, case["effective_area"], rtol=1e-10, atol=0) @@ -378,12 +403,13 @@ def test_luna_witness(case): def test_production_form_against_luna_form(): - """The five conventions change the fits by their closed forms, and only those. + """The four conventions change the fits by their closed forms, and only those. - The dispersion width is common to both forms. Evacuated, the gas index is unity - and the three gas-index choices are identities, so the radius coefficient is the - whole difference; filled, each choice moves its own term by the amount its - definition says (``docs/guide/waveguides/modes.md``, "The five conventions"). + The dispersion width and the radius coefficient are common to both forms. + Evacuated, the gas index is unity and the three gas-index choices are identities, + so the forms agree; filled, each choice moves its own term by the amount its + definition says (``docs/guide/waveguides/antiresonant.md``, "The four + conventions"). """ lattice = TubeLattice(180e-9, 9e-6, 6) radius, tube_index = 15e-6, 1.45 @@ -394,57 +420,31 @@ def test_production_form_against_luna_form(): def prefactor(frequency): return 1.027 + 0.001 * (frequency + 2 / frequency**4) - # Evacuated: equal to rounding but for the radius coefficient, whose effect on - # R_eff^2 is the coefficient difference times its own term. The rounding is the - # complex square root of n_t^2 - n_g^2 with n_g = 1 + 0j against the real - # square root of n_t^2 - 1: measured 4 ulps on the refractivity. + # Evacuated: equal to rounding. The rounding is the complex square root of + # n_t^2 - n_g^2 with n_g = 1 + 0j against the real square root of n_t^2 - 1: + # measured 4 ulps on the refractivity. mode = VincettiMode(radius, lattice=lattice, cladding=tube_index) terms = mode.sampled_terms(omega) luna = mode._spectral_model(terms, radius, 0.0, LEGACY_CONVENTIONS) production = mode._spectral_model(terms, radius, 0.0) - luna_coefficient = mode._spectral_model( - terms, radius, 0.0, replace(CONVENTIONS, radius_coefficient=20.0) - ) for name in ("refractivity", "effective_radius", "correction", "decrement"): for part in ("value", "slope"): expected = getattr(getattr(luna, name), part) # The correction's slope crosses zero, so the floor is relative to # the largest element rather than to each. np.testing.assert_allclose( - getattr(getattr(luna_coefficient, name), part), + getattr(getattr(production, name), part), expected, rtol=8 * eps, atol=8 * eps * float(np.max(np.abs(expected))), ) np.testing.assert_allclose( mode.effective_area(omega, conventions=LEGACY_CONVENTIONS), - mode.effective_area( - omega, conventions=replace(CONVENTIONS, radius_coefficient=20.0) - ), + mode.effective_area(omega), rtol=8 * eps, atol=0, ) frequency = 2 * lattice.wall_thickness / wavelength * math.sqrt(tube_index**2 - 1) - expected = ( - prefactor(frequency) ** 2 - * lattice.n_tubes - / math.pi - * 3 - / 64 - * lattice.tube_radius**2 - * (RADIUS_COEFFICIENT - LEGACY_RADIUS_COEFFICIENT) - * wavelength - / radius - * lattice.gap(radius) - / lattice.tube_radius - ) - # The difference of squares is 0.9 % of R_eff^2, so its rounding is 1e-13. - np.testing.assert_allclose( - production.effective_radius.value**2 - luna.effective_radius.value**2, - expected, - rtol=1e-12, - atol=0, - ) # Argon at 30 bar, one choice at a time from Luna's form. mode = VincettiMode(radius, "Ar", 30.0, lattice=lattice, cladding=tube_index) @@ -500,7 +500,7 @@ def prefactor(frequency): filled_loss = np.imag(filled.refractivity.value) assert np.max(np.abs(filled_loss / np.imag(luna.refractivity.value) - 1)) > 1e-3 assert np.max(np.abs(filled.correction.value / luna.correction.value - 1)) > 1e-3 - # All five together differ from Luna by more than rounding in every piece. + # All four together differ from Luna by more than rounding in every piece. production = mode._spectral_model(terms, *scalars) production_index = np.real(production.refractivity.value) assert np.max(np.abs(production_index - np.real(luna.refractivity.value))) > 1e-6 @@ -646,6 +646,8 @@ def test_invalid_samples_and_geometry(): "N=6, Ar 1 bar, loss=model)" ) assert "Ar 2 bar" in repr(make_mode(gas="Ar", pressure=Linear(2.0, 3.0, 1.0))) + mixed = make_mode(mixture=Mixture.fill({"He": 0.25, "Ar": 0.75}, 2.0)) + assert repr(mixed).endswith("N=6, He+Ar 2 bar, loss=model)") def test_tube_count_warning_is_per_construction(caplog): diff --git a/tests/modes/test_base.py b/tests/modes/test_base.py index c8f7fca56..2a25e7e22 100644 --- a/tests/modes/test_base.py +++ b/tests/modes/test_base.py @@ -10,8 +10,8 @@ from witness_materials import borzsonyi from solprop.constants import C -from solprop.exceptions import MaterialRangeWarning, ModeError -from solprop.modes import MarcatiliMode +from solprop.exceptions import MaterialRangeWarning, ModeError, NoZeroDispersionError +from solprop.modes import MarcatiliMode, StepIndexMode from solprop.modes.base import ( BETA2_RELATIVE_STEP, aeff, @@ -25,6 +25,7 @@ transmission, zdw, ) +from solprop.nonlinear.gnlse import SpecifiedMode from solprop.physdata.glasses import fused_silica from solprop.profiles import Linear, PressureGradient @@ -211,8 +212,208 @@ def test_zdw_refuses_a_bad_window(mode, wavelength_range): zdw(mode, wavelength_limits=wavelength_range) -def test_the_default_window_is_lunas(): - """Kept for comparability; it does make the material models warn, honestly.""" +@pytest.mark.parametrize("near", [0.0, -800e-9, math.inf, math.nan]) +def test_zdw_refuses_a_bad_reference_wavelength(mode, near): + with pytest.raises(ModeError, match="near must be a positive"): + zdw(mode, wavelength_limits=(150e-9, 900e-9), near=near) + + +def two_zero_mode(): + """``beta2 = -1e-26 + 1e-54 (omega - 2e15)^2`` s^2/m: zeros at 1.9e15 and 2.1e15.""" + omega0 = 2e15 + return SpecifiedMode.from_taylor( + [omega0 / C, 1.0 / C, -1e-26, 0.0, 2e-54], omega0, aeff=1e-10 + ) + + +TWO_ZERO_WINDOW = (2.0 * math.pi * C / 2.2e15, 2.0 * math.pi * C / 1.8e15) + + +@pytest.mark.parametrize("knot", [100, 255, 256, 300]) +def test_zdw_finds_a_zero_that_falls_exactly_on_a_sample(knot): + """``beta2 = 1e-41 (omega - 2^51)`` s^2/m, with its zero on a sample of the search. + + Powers of two make the sample and the differenced ``beta2`` there exact, so the + products of neighbouring signs are zero on both sides and not negative. + """ + omega0, spacing, samples = 2.0**51, 2.0**40, 512 + mode = SpecifiedMode.from_taylor( + [omega0 / C, 1.0 / C, 0.0, 1e-41], omega0, aeff=1e-10 + ) + lower = omega0 - knot * spacing + upper = omega0 + (samples - 1 - knot) * spacing + limits = (2.0 * math.pi * C / upper, 2.0 * math.pi * C / lower) + # The search's own grid, from the limits as it converts them. + grid = np.linspace( + 2.0 * math.pi * C / limits[1], 2.0 * math.pi * C / limits[0], samples + ) + assert grid[knot] == omega0 + assert beta2(mode, grid)[knot] == 0.0 + found = zdw(mode, wavelength_limits=limits) + assert found == pytest.approx(2.0 * math.pi * C / omega0, rel=1e-12) + + +def test_zdw_does_not_take_a_touch_of_zero_for_a_sign_change(): + """``beta2 = 1e-54 (omega - 2e15)^2`` touches zero and keeps its sign.""" + omega0 = 2e15 + mode = SpecifiedMode.from_taylor( + [omega0 / C, 1.0 / C, 0.0, 0.0, 2e-54], omega0, aeff=1e-10 + ) + with pytest.raises(NoZeroDispersionError, match="does not change sign"): + zdw(mode, wavelength_limits=TWO_ZERO_WINDOW) + + +def test_zdw_names_every_zero_when_the_window_holds_several(): + # The ends of the window have one sign, and both zeros are real. + with pytest.raises(ModeError, match=r"2 zeros .* 897\.0, 991\.4 nm"): + zdw(two_zero_mode(), wavelength_limits=TWO_ZERO_WINDOW) + + +@pytest.mark.parametrize(("near", "omega"), [(900e-9, 2.1e15), (1000e-9, 1.9e15)]) +def test_zdw_returns_the_zero_nearest_a_reference(near, omega): + found = zdw(two_zero_mode(), wavelength_limits=TWO_ZERO_WINDOW, near=near) + # beta1 is a cubic, so the Richardson difference is exact but for rounding (1e-37 + # s^2/m against a slope of 2e-40 s^3/m per rad/s): the root to 1e-12, read at 1e-9. + assert found == pytest.approx(2.0 * math.pi * C / omega, rel=1e-9) + + +def krypton(): + """A 14 um capillary at 15 bar of krypton: its resonances near 120 nm flip the + sign of the differenced ``beta2`` sixteen times between 100 and 124 nm.""" + return MarcatiliMode(14e-6, "Kr", 15.0) + + +GAS_WINDOW = (100e-9, 3e-6) +"""A window reaching below the gas lines, the default before the noble gases' lines +were left out of it.""" + + +@pytest.mark.parametrize("near", [800e-9, 200e-9]) +def test_zdw_finds_a_zero_past_the_sign_changes_of_a_gas_resonance(near): + with warnings.catch_warnings(): + warnings.simplefilter("ignore", MaterialRangeWarning) + found = zdw(krypton(), wavelength_limits=GAS_WINDOW, near=near) + # The single zero of the qualified band (125 nm up), searched there alone. + reference = zdw(krypton(), wavelength_limits=(125e-9, 3e-6)) + # Other samples, so other brackets: both stop on the noise of the differenced + # beta2 (5e-9, BETA2_RELATIVE_STEP). + assert found == pytest.approx(reference, rel=1e-8) + assert reference == pytest.approx(770.5167e-9, rel=1e-6) + + +def test_zdw_does_not_cross_a_gas_line_to_a_nearer_zero(): + # From 150 nm, krypton's own zero at 108.9 nm (between its 104 and 116.5 nm + # lines) is nearer in frequency than 770.5 nm, but the 116.5 and 123.6 nm lines + # lie between: their group delay diverges or drops to the evanescent floor. + with warnings.catch_warnings(): + warnings.simplefilter("ignore", MaterialRangeWarning) + found = zdw(krypton(), wavelength_limits=GAS_WINDOW, near=150e-9) + # The noise of the differenced beta2, as above. + assert found == pytest.approx(770.5167e-9, rel=1e-6) + + +@pytest.mark.parametrize( + ("near", "expected"), + [(123.47e-9, 119.8786e-9), (124e-9, 770.5167e-9)], + ids=["on", "beside"], +) +def test_zdw_from_a_reference_on_a_gas_line_is_blocked_on_neither_side(near, expected): + # Krypton's 123.6 nm line changes sign between the samples at 123.33 and 123.62 nm + # (512 over GAS_WINDOW). A reference between them is on neither side of the line, + # so it blocks neither: the zero at 119.9 nm, between the 116.5 and 123.6 nm lines, + # is the nearest. From 124 nm the line lies between, and the answer is 770.5 nm. + with warnings.catch_warnings(): + warnings.simplefilter("ignore", MaterialRangeWarning) + found = zdw(krypton(), wavelength_limits=GAS_WINDOW, near=near) + # The noise of the differenced beta2, as above. + assert found == pytest.approx(expected, rel=1e-6) + + +@pytest.mark.parametrize( + ("radius", "pressure", "near", "expected"), + [ + # The zero at 105.9 nm lies past argon's 106.7 nm line from 120 nm. + (14e-6, 15.0, 120e-9, 644.0787e-9), + # Without a reference: the 105.9 nm zero beside the lines is clustered with + # their sign changes, so it is no zero-dispersion point. + (125e-6, 1.0, None, 967.8074e-9), + ], +) +def test_zdw_of_an_argon_capillary_is_its_zero_above_the_lines( + radius, pressure, near, expected +): + mode = MarcatiliMode(radius, "Ar", pressure) + with warnings.catch_warnings(): + warnings.simplefilter("ignore", MaterialRangeWarning) + found = zdw(mode, wavelength_limits=GAS_WINDOW, near=near) + # The noise of the differenced beta2 (5e-9) and the 7 digits pinned. + assert found == pytest.approx(expected, rel=1e-6) + + +def test_zdw_does_not_report_a_resonance_artefact_as_a_zero(): + # 121-125 nm holds the floored plateau above krypton's 123.6 nm line, where the + # differenced beta2 changes sign while the group delay is constant. + with warnings.catch_warnings(): + warnings.simplefilter("ignore", MaterialRangeWarning) + with pytest.raises(NoZeroDispersionError, match="none is a zero"): + zdw(krypton(), wavelength_limits=(121e-9, 125e-9)) + + +def silica_fibre(): + """A standard single-mode fibre: 4.1 um core radius, NA 0.12, on optmat's silica, + whose OH absorption bands flip the sign of beta2 four times between 1.36 and + 1.40 um and twice near 2.7 um.""" + return StepIndexMode.from_numerical_aperture( + 4.1e-6, 0.12, profile_wavelength=1.3e-6 + ) + + +FIBRE_ZDW = 1295.83467e-9 +"""The fibre's zero-dispersion wavelength, m.""" + + +@pytest.mark.medium +@pytest.mark.parametrize( + ("window", "near"), + [ + ((100e-9, 3e-6), 1550e-9), + ((700e-9, 2.5e-6), 1550e-9), + ((1e-6, 2e-6), 1550e-9), + (None, 1030e-9), + (None, 800e-9), + ((150e-9, 2.5e-6), None), + ], +) +def test_zdw_of_a_silica_fibre_does_not_depend_on_the_window(window, near): + """The OH band at 1.38 um lies between a 1550 nm pump and the 1.3 um zero: its + clustered zeros are passed over, and it does not block the search like a line.""" + limits = {} if window is None else {"wavelength_limits": window} + found = zdw(silica_fibre(), near=near, **limits) + # Other windows, so other brackets: each stops on the noise of the differenced + # beta2 (5e-9); they agree to 2e-10, and with the 9 digits pinned to 1e-9. + assert found == pytest.approx(FIBRE_ZDW, rel=1e-8) + + +@pytest.mark.medium +def test_a_plain_zdw_of_a_silica_fibre_names_its_zeros_above_the_ultraviolet(): + """Not silica's zeros in the vacuum ultraviolet, where a lossless solve takes it + as transparent: the default window starts above them. Past the OH band at 2.7 um, + beta2 is normal from 2.85 to 2.91 um, a regime 2 % wide.""" + with pytest.raises( + ModeError, match=r"3 zeros over 150-3000 nm, at 1295\.8, 2846\.1, 2906\.9 nm" + ): + zdw(silica_fibre()) + + +@pytest.mark.medium +def test_zdw_passes_over_the_clustered_zeros_of_an_absorption_band(): + # beta2 changes sign four times here, through the OH overtone of the silica. + with pytest.raises(NoZeroDispersionError, match=r"4 times .* none is a zero"): + zdw(silica_fibre(), wavelength_limits=(1.36e-6, 1.40e-6)) + + +def test_the_default_window_finds_lunas_helium_zero(): + """The default window starts at 150 nm, not Luna's 100 nm; the answer is Luna's.""" # Luna's mode, with every input stated (``docs/dev/testing.md``): the cladding and # the temperature are solprop's own, deliberately -- optmat's silica and 293.15 K # against Luna's table and 294 K -- and the 1 nm gate absorbs both. @@ -228,7 +429,7 @@ def test_the_default_window_is_lunas(): ) with warnings.catch_warnings(): warnings.simplefilter("ignore", MaterialRangeWarning) - # Deliberately the default window: that it is Luna's is what is tested. + # Deliberately the default window. wavelength = zdw(mode) # Luna test_capillary.jl asserts |zdw(MarcatiliMode(125e-6, :HeB, 0.4)) - 379 nm| # < 1 nm for the same model and the same helium source, Börzsönyi's (:HeB), @@ -237,6 +438,15 @@ def test_the_default_window_is_lunas(): assert abs(wavelength * 1e9 - 379.0) < 1.0 +def test_the_default_window_leaves_out_the_gas_lines(): + """A plain call on krypton is not refused for the gas's own zeros near 110 nm.""" + with warnings.catch_warnings(): + warnings.simplefilter("ignore", MaterialRangeWarning) + found = zdw(krypton()) + # The noise of the differenced beta2, as above. + assert found == pytest.approx(770.5167e-9, rel=1e-6) + + # ------------------------------------------------------- loss-derived quantities diff --git a/tests/modes/test_capillary.py b/tests/modes/test_capillary.py index 0402cb442..9bd4f9eeb 100644 --- a/tests/modes/test_capillary.py +++ b/tests/modes/test_capillary.py @@ -367,6 +367,24 @@ def test_an_alpha_callable_replaces_the_model_loss_with_an_absolute_alpha(): ) +@pytest.mark.parametrize("output", [-0.5, np.nan, np.inf]) +def test_an_alpha_callable_returning_gain_or_nan_is_refused(output): + """As the step-index modes refuse it: NaN would propagate and -0.5 is gain.""" + + def curve(omega): + return np.full_like(omega, output) + + mode = MarcatiliMode(125e-6, "He", 1.0, alpha=curve) + with pytest.raises(ModeError, match="alpha callable"): + mode.neff(omega_of(np.array([800e-9]))) + + +def test_an_alpha_callable_of_the_wrong_shape_is_refused(): + mode = MarcatiliMode(125e-6, "He", 1.0, alpha=lambda omega: np.array([1.0, 2.0])) + with pytest.raises(ModeError, match="alpha callable"): + mode.neff(omega_of(np.array([800e-9]))) + + @pytest.mark.parametrize("model", MODELS) def test_a_constant_alpha_is_a_flat_curve(model): omega = omega_of(np.linspace(400e-9, 1000e-9, 16)) diff --git a/tests/modes/test_collection.py b/tests/modes/test_collection.py index 95dce80e5..e6d5b0904 100644 --- a/tests/modes/test_collection.py +++ b/tests/modes/test_collection.py @@ -20,6 +20,7 @@ ) from solprop.modes.quadrature import mode_matrix, transverse_quadrature from solprop.modes.slab import SlabMode +from solprop.modes.stepindex import StepIndexMode from solprop.profiles import Linear RADIUS = 125e-6 @@ -300,14 +301,14 @@ def test_a_collection_is_an_ordered_sequence(): lambda: overlap( MarcatiliMode(RADIUS, "He", 1.0), MarcatiliMode(2 * RADIUS, "He", 1.0) ), - "needs one cross-section", + "share a cross-section", ), (lambda: overlap(DummyMode(), DummyMode()), "provides no normalisation"), ( lambda: orthonormality( [MarcatiliMode(RADIUS, "He", 1.0), MarcatiliMode(2 * RADIUS, "He", 1.0)] ), - "needs one cross-section", + "share a cross-section", ), (lambda: orthonormality([]), "at least one mode"), (lambda: polarisation_pairs([DummyMode()]), "orthogonal polarisation"), @@ -349,7 +350,7 @@ def test_a_collection_catches_a_disagreement_that_only_appears_along_z(): ] ) assert collection.dimlimits(0.0)[2][0] == pytest.approx(RADIUS) - with pytest.raises(ModeError, match="disagree about the cross-section"): + with pytest.raises(ModeError, match="share a cross-section at z = 1 m"): collection.dimlimits(1.0) @@ -460,3 +461,53 @@ def test_he1m_matches_the_modes_built_by_hand(): omega = np.array([2.356e15]) for one, other in zip(got, by_hand, strict=True): np.testing.assert_array_equal(one.neff(omega), other.neff(omega)) + + +# ----------------------------------------------------- step-index channels of one guide + + +def stepindex_pair(numerical_aperture=False): + """HE11 and HE12 of one fibre: each bounds the cladding at its own outer radius.""" + if numerical_aperture: + return [ + StepIndexMode.from_numerical_aperture( + 10e-6, 0.12, m=m, profile_wavelength=1e-6 + ) + for m in (1, 2) + ] + return [ + StepIndexMode(10e-6, core=1.46, cladding=1.44, m=m, profile_wavelength=1e-6) + for m in (1, 2) + ] + + +@pytest.mark.parametrize("numerical_aperture", [False, True]) +def test_step_index_channels_of_one_guide_form_a_collection(numerical_aperture): + modes = stepindex_pair(numerical_aperture) + assert modes[0].dimlimits()[2][0] != modes[1].dimlimits()[2][0] + assert modes[0].same_guide(modes[1]) + collection = ModeCollection(modes) + # The widest disc, over which both channels' fields are exact. + widest = max(mode.dimlimits()[2][0] for mode in modes) + assert collection.dimlimits()[2][0] == widest + + +def test_step_index_channels_of_one_guide_have_overlaps_on_the_widest_disc(): + modes = stepindex_pair() + got = ModeCollection(modes).orthonormality() + # Each channel normalised to itself, to the integration tolerance (1e-12); the + # off-diagonal is the vector modes' small non-orthogonality (step-index guide). + np.testing.assert_allclose(np.diag(got), 1.0, rtol=0.0, atol=1e-10) + assert got[0, 1] == got[1, 0] + assert 0.0 < abs(got[0, 1]) < 1e-2 + assert overlap(modes[0], modes[1]) == pytest.approx(got[0, 1], abs=1e-12) + rule = transverse_quadrature(modes, n_r=48) + assert mode_matrix(modes, rule, components=("x",)).synthesis.shape[1] == 2 + + +def test_step_index_channels_of_different_guides_are_refused(): + first = StepIndexMode(10e-6, core=1.46, cladding=1.44, profile_wavelength=1e-6) + other = StepIndexMode(10e-6, core=1.46, cladding=1.43, m=2, profile_wavelength=1e-6) + assert not first.same_guide(other) + with pytest.raises(ModeError, match="share a cross-section"): + ModeCollection([first, other]) diff --git a/tests/modes/test_fill.py b/tests/modes/test_fill.py index 639597b0a..088f2512a 100644 --- a/tests/modes/test_fill.py +++ b/tests/modes/test_fill.py @@ -9,7 +9,14 @@ from witness_materials import ermolov_helium, kingston_argon from solprop.exceptions import ModeError -from solprop.modes import MarcatiliMode, TubeLattice, VincettiMode +from solprop.modes import ( + MarcatiliMode, + ModeCollection, + RectMode, + SlabMode, + TubeLattice, + VincettiMode, +) from solprop.modes.fill import GasFillMixin from solprop.physdata import Mixture from solprop.profiles import Linear, PressureGradient @@ -65,3 +72,35 @@ def test_fill_rejects_invalid_loss_and_freezes_single_species_density(): frozen = filled.at_parameters({"density": 1e25}) assert frozen.mixture is not None assert float(frozen.mixture.components[0].density(np.asarray([0.0]))[0]) == 1e25 + + +@pytest.mark.parametrize( + "build", + [ + lambda: MarcatiliMode(125e-6, "He"), + lambda: VincettiMode(15e-6, "Ar", lattice=TubeLattice(180e-9, 10.38e-6, 6)), + lambda: RectMode(125e-6, 50e-6, "Ar"), + lambda: SlabMode(63.5e-6, "Ar"), + lambda: ModeCollection.he1m(125e-6, "He", count=2), + lambda: ModeCollection.slab(63.5e-6, "Ar", orders=(1, 3)), + ], + ids=["marcatili", "vincetti", "rect", "slab", "he1m", "slab-set"], +) +def test_a_gas_fill_without_its_pressure_is_refused(build): + with pytest.raises(ModeError, match="a gas fill needs its pressure") as caught: + build() + assert caught.value.parameter == "pressure" + + +def test_a_guide_without_a_gas_is_evacuated_and_takes_no_pressure(): + for mode in ( + MarcatiliMode(125e-6), + RectMode(125e-6, 50e-6), + SlabMode(63.5e-6), + MarcatiliMode(125e-6, mixture=Mixture.fill({"He": 1.0}, 2.0)), + ): + assert mode.gas is None and mode.pressure == 0.0 + assert float(MarcatiliMode(125e-6).density(np.asarray([0.0]))[0]) == 0.0 + # A mixture still refuses a pressure of its own beside it. + with pytest.raises(ModeError, match="mixture carries its gas, pressure"): + MarcatiliMode(125e-6, pressure=2.0, mixture=Mixture.fill({"He": 1.0}, 2.0)) diff --git a/tests/modes/test_modal_tables.py b/tests/modes/test_modal_tables.py index 07057b69f..2877b30fc 100644 --- a/tests/modes/test_modal_tables.py +++ b/tests/modes/test_modal_tables.py @@ -1165,8 +1165,11 @@ def test_a_declared_basis_transforms_the_reference_and_composes_its_gauge(): assert turned.basis is basis assert composed_gauge("g", None) == "g" # The declared basis leaves the sampled Gram defect exactly where it was: the - # spectral norm is unitarily invariant. - assert turned.gram_defect == pytest.approx(plain.gram_defect, rel=1e-12) + # spectral norm is unitarily invariant. G - I is formed from entries near one, so + # the defect carries their absolute rounding, a few eps, not a relative one. + assert turned.gram_defect == pytest.approx( + plain.gram_defect, rel=1e-12, abs=8 * EPS + ) def test_a_declared_basis_puts_a_held_out_solve_in_the_same_coordinates(): diff --git a/tests/modes/test_quadrature.py b/tests/modes/test_quadrature.py index 4722e1aee..5f3cd1fa4 100644 --- a/tests/modes/test_quadrature.py +++ b/tests/modes/test_quadrature.py @@ -101,7 +101,8 @@ def test_the_kronrod_extension_is_a_proper_embedded_pair(n): np.testing.assert_allclose(nodes[1::2], gauss_nodes, rtol=0.0, atol=1e-14) np.testing.assert_allclose(coarse[1::2], gauss_weights, rtol=0.0, atol=0.0) np.testing.assert_array_equal(coarse[0::2], 0.0) - assert float(weights.sum()) == pytest.approx(2.0, rel=1e-15) + # A sum of 2n + 1 positive weights: twice Higham's gamma_{2n+1} of the summation. + assert float(weights.sum()) == pytest.approx(2.0, rel=nodes.size * EPS) assert float(coarse.sum()) == pytest.approx(2.0, rel=1e-14) diff --git a/tests/modes/test_rectangular.py b/tests/modes/test_rectangular.py index ca0e82e7b..89b125d60 100644 --- a/tests/modes/test_rectangular.py +++ b/tests/modes/test_rectangular.py @@ -20,7 +20,7 @@ from witness_materials import borzsonyi from solprop.constants import EPS0, C -from solprop.exceptions import GrazingIncidenceWarning, MaterialRangeWarning, ModeError +from solprop.exceptions import GrazingIncidenceWarning, ModeError from solprop.modes import ModeCollection, RectMode from solprop.modes.base import beta, db_per_m, zdw from solprop.modes.quadrature import ( @@ -221,8 +221,9 @@ def test_rectangular_fem_checked_values_from_luna_test_file(): susceptibility=borzsonyi("Ar"), temperature=293.15, ) - with pytest.warns(MaterialRangeWarning, match="borzsonyi"): - wavelength = zdw(filled, wavelength_limits=(400e-9, 800e-9)) + # The window reaches below the fit's range, but the search probes it silently and + # the zero itself lies inside the range, so nothing warns. + wavelength = zdw(filled, wavelength_limits=(400e-9, 800e-9)) assert abs(wavelength - 563.5e-9) < 1e-9 diff --git a/tests/modes/test_species_absorption.py b/tests/modes/test_species_absorption.py index 6600d5eee..845ebab90 100644 --- a/tests/modes/test_species_absorption.py +++ b/tests/modes/test_species_absorption.py @@ -56,6 +56,21 @@ def test_a_single_gas_and_vacuum_have_one_zero_absorption_row(): ) +def test_an_absorbing_single_gas_law_is_refused_attribution(monkeypatch): + omega = np.array([2 * np.pi * C / 800e-9]) + mode = MarcatiliMode(30e-6, "He", 1.0) + assert mode.susceptibility is not None + monkeypatch.setattr( + type(mode.susceptibility), "absorbing", property(lambda self: True) + ) + with pytest.raises(ModeError, match="component of a Mixture"): + mode.absorption_by_species(omega) + # With the loss removed there is nothing to attribute. + np.testing.assert_array_equal( + replace(mode, loss_scale=0.0).absorption_by_species(omega), np.zeros((1, 1)) + ) + + def test_zero_population_contributes_no_attributed_loss(): mixture, grid, mode, _, _ = mixture_case() mixture = mixture.with_densities({label: Constant(0) for label in mixture.labels}) diff --git a/tests/modes/test_stepindex.py b/tests/modes/test_stepindex.py index 8af4af32f..0277d436f 100644 --- a/tests/modes/test_stepindex.py +++ b/tests/modes/test_stepindex.py @@ -312,6 +312,26 @@ def test_stepindex_taper_freezing_and_na_constructor(): assert_allclose(na.neff(omega), direct.neff(omega), rtol=0, atol=0) +def test_aperture_channels_are_one_guide_by_cladding_and_aperture(): + # Each from_numerical_aperture call builds its own core index; channels of one + # fibre compare equal, and hash alike, by cladding law and aperture, not identity. + one, two = ( + StepIndexMode.from_numerical_aperture(10e-6, 0.12, m=m, profile_wavelength=1e-6) + for m in (1, 2) + ) + wider = StepIndexMode.from_numerical_aperture(10e-6, 0.13, profile_wavelength=1e-6) + assert one._core is not two._core + assert one.same_guide(two) + assert not one.same_guide(wider) + assert len({one._core, two._core, wider._core}) == 2 + # A core given as a glass law is another guide, whatever its index there. + glass = StepIndexMode( + 10e-6, core=fused_silica(), cladding=1.40, profile_wavelength=1e-6 + ) + assert not one.same_guide(glass) + assert not glass.same_guide(one) + + def test_stepindex_mpmath_witness(): rows = json.loads( (Path(__file__).parents[1] / "data/symbolic_stepindex.json").read_text() diff --git a/tests/modes/test_tabulated.py b/tests/modes/test_tabulated.py index 415b3a1ee..dc4de1d65 100644 --- a/tests/modes/test_tabulated.py +++ b/tests/modes/test_tabulated.py @@ -373,7 +373,7 @@ def test_filled_mode_refuses_varying_material_and_has_no_attribution(): np.testing.assert_array_equal( mixed.absorption_by_species(np.array([2e15])), np.zeros((2, 1)) ) - assert "Mixture" in repr(mixed) + assert "Ar+Ne 1 bar" in repr(mixed) def test_table_modes_never_evaluate_silica(monkeypatch): diff --git a/tests/modes/test_vincetti_fem.py b/tests/modes/test_vincetti_fem.py index 0efd04317..474ad4864 100644 --- a/tests/modes/test_vincetti_fem.py +++ b/tests/modes/test_vincetti_fem.py @@ -194,34 +194,34 @@ def test_materials_match_the_reference_run(vacuum, argon, caplog): def test_vacuum_index_within_measured_residuals(vacuum): away = vacuum.away - # All 79 rows: RMSE 7.528e-6 measured; the lower bound catches a + # All 79 rows: RMSE 8.671e-6 measured; the lower bound catches a # degenerate comparison such as the model compared with itself. - assert 3.7e-6 < vacuum.rmse(np.ones_like(away)) < 8.7e-6 - # 59 away rows: RMSE 7.449e-6; the residual relative to the FEM's own waveguide - # decrement has median 2.93 %, p90 11.7 % and max 25.6 %. + assert 3.7e-6 < vacuum.rmse(np.ones_like(away)) < 1.0e-5 + # 59 away rows: RMSE 8.943e-6; the residual relative to the FEM's own waveguide + # decrement has median 3.45 %, p90 11.5 % and max 25.2 %. relative = np.abs(vacuum.residual / (vacuum.gas_index - vacuum.fem_index))[away] - assert vacuum.rmse(away) < 8.6e-6 - assert float(np.median(relative)) < 0.034 - assert float(np.quantile(relative, 0.9)) < 0.135 - assert float(np.max(relative)) < 0.295 - # 20 near rows: RMSE 7.758e-6; the narrower printed dispersion width 0.003 would + assert vacuum.rmse(away) < 1.03e-5 + assert float(np.median(relative)) < 0.040 + assert float(np.quantile(relative, 0.9)) < 0.133 + assert float(np.max(relative)) < 0.291 + # 20 near rows: RMSE 7.811e-6; the narrower printed dispersion width 0.003 would # give 2.5e-5 here. - assert vacuum.rmse(~away) < 8.9e-6 + assert vacuum.rmse(~away) < 9.0e-6 def test_argon_index_within_measured_residuals(argon): away = argon.away - # 14 away rows: RMSE 4.452e-6 and median 0.71 % of the decrement. + # 14 away rows: RMSE 4.470e-6 and median 0.50 % of the decrement. relative = np.abs(argon.residual / (argon.gas_index - argon.fem_index))[away] - assert 2.2e-6 < argon.rmse(away) < 5.1e-6 - assert float(np.median(relative)) < 0.0082 + assert 2.2e-6 < argon.rmse(away) < 5.2e-6 + assert float(np.median(relative)) < 0.0057 def test_gas_differential_within_measured_residual(vacuum, argon): # The change of the FEM index from vacuum to 10 bar, against the model's own # change at the same wavelengths, removes the fixed vacuum-model bias. Nine # argon rows at 690-946 nm; the vacuum FEM refractivity is a cubic spline over - # its rows at 500 nm and above (a quartic agrees to 1e-16). Measured 7.22e-8 + # its rows at 500 nm and above (a quartic agrees to 1e-16). Measured 8.12e-8 # with the single-power decrement, 4.60e-7 with the legacy 1/n_g^2. keep = argon.wavelength > DIFFERENTIAL_ARGON_ABOVE assert int(keep.sum()) == 9 @@ -233,7 +233,7 @@ def test_gas_differential_within_measured_residual(vacuum, argon): error = (argon.index[keep] - model_vacuum[keep]) - ( argon.fem_index[keep] - fem_vacuum ) - assert 3.6e-8 < float(np.max(np.abs(error))) < 8.3e-8 + assert 3.6e-8 < float(np.max(np.abs(error))) < 9.4e-8 # The FEM area itself is fill independent to 1e-4 at these rows (n_g^2 - 1 is # 5.3e-3), which is what the area's 1/n_g prefactor preserves. fem_vacuum_area = InterpolatedUnivariateSpline( @@ -263,9 +263,9 @@ def test_loss_within_measured_ratios(vacuum, argon): def test_area_within_measured_residuals(vacuum, argon): - # Away rows: the fitted area's median residual is 2.48 % in vacuum and 1.16 % in - # argon, its maximum 27.9 % / 26.9 % at the band edges. - for evaluation, median, worst in ((vacuum, 0.0285, 0.32), (argon, 0.0134, 0.31)): + # Away rows: the fitted area's median residual is 3.10 % in vacuum and 0.33 % in + # argon, its maximum 28.7 % / 27.7 % at the band edges. + for evaluation, median, worst in ((vacuum, 0.036, 0.33), (argon, 0.0038, 0.32)): away = evaluation.away residual = np.abs(evaluation.area[away] / evaluation.fem_area[away] - 1) assert float(np.median(residual)) < median @@ -274,9 +274,9 @@ def test_area_within_measured_residuals(vacuum, argon): def test_first_band_beta2_discrepancy_is_recorded(vacuum): # The FEM's own beta_2 in the first band, three-point second differences of - # beta = omega n / c on the raw rows, is more negative than the model's by 1 % - # at 607 nm, 18 % at 782 nm, 48 % at 913 nm and 70 % at 1013 nm (-1268 against - # -744 fs^2/m): the curvature of the fit's U-shaped index residual on this + # beta = omega n / c on the raw rows, is more negative than the model's by 3 % + # at 607 nm, 20 % at 782 nm, 49 % at 913 nm and 70 % at 1013 nm (-1268 against + # -745 fs^2/m): the curvature of the fit's U-shaped index residual on this # t/r = 0.017 fibre. Measured worst 0.703; the lower bound records the # finding, so a smaller number is an improvement to record there, not a # regression. diff --git a/tests/modes/test_wall_operator.py b/tests/modes/test_wall_operator.py index 46999e8c3..b1a9df31d 100644 --- a/tests/modes/test_wall_operator.py +++ b/tests/modes/test_wall_operator.py @@ -111,7 +111,7 @@ def test_the_trace_vector_is_the_basis_derivative_at_the_wall(): / step for zero in zeros ] - assert np.allclose(operator.trace_vector, np.array(measured), rtol=1e-4) + assert np.allclose(operator.trace_vector, np.array(measured), rtol=1e-4, atol=0.0) @pytest.mark.parametrize("count", [10, 20, 40]) @@ -574,7 +574,7 @@ def test_the_amplitude_map_is_one_positive_scale_for_every_channel(): for mode in modes ] expected = radius * math.sqrt(math.pi * EPS0 * C) - assert np.allclose(np.array(ratios, dtype=float), expected, rtol=1e-14) + assert np.allclose(np.array(ratios, dtype=float), expected, rtol=1e-14, atol=0.0) def test_the_square_root_and_paraxial_generators_agree_where_the_model_is_valid(): diff --git a/tests/nonlinear/test_ionisation.py b/tests/nonlinear/test_ionisation.py index 855803a2e..516ede7b8 100644 --- a/tests/nonlinear/test_ionisation.py +++ b/tests/nonlinear/test_ionisation.py @@ -220,8 +220,11 @@ def test_pre_ionisation_sits_inside_the_exponential(): preionised = ionisation_fraction(rate, field, dt, preionisation=0.4) assert preionised[0] == pytest.approx(0.4) assert np.all(preionised <= 1.0) - # Every atom already ionised is one the pulse cannot ionise again. - assert np.allclose(1.0 - preionised, 0.6 * (1.0 - plain)) + # Every atom already ionised is one the pulse cannot ionise again. Where the + # fractions reach one, 1 - f keeps the absolute rounding of f, a few eps. + assert np.allclose( + 1.0 - preionised, 0.6 * (1.0 - plain), atol=4 * np.finfo(float).eps + ) assert np.all(ionisation_fraction(rate, field, dt, preionisation=1.0) == 1.0) @@ -238,7 +241,7 @@ def test_no_field_ionises_nothing(): @pytest.mark.parametrize("bad", [0.0, -1.0, math.inf, math.nan]) def test_a_non_positive_wavelength_is_rejected(bad): - with pytest.raises(MaterialError, match="wavelength must be positive"): + with pytest.raises(MaterialError, match="wavelength must be finite and positive"): keldysh(Gas.He, bad, 1e10) @@ -261,7 +264,7 @@ def test_a_non_finite_field_is_rejected(bad): @pytest.mark.parametrize("bad", [0.0, -1.0, math.inf, math.nan]) def test_a_non_positive_time_step_is_rejected(bad): - with pytest.raises(MaterialError, match="dt must be positive"): + with pytest.raises(MaterialError, match="dt must be finite and positive"): ionisation_fraction(adk_oracle("He"), np.zeros(4), bad) diff --git a/tests/nonlinear/test_optmat_raman.py b/tests/nonlinear/test_optmat_raman.py index 2426ed270..679620b9d 100644 --- a/tests/nonlinear/test_optmat_raman.py +++ b/tests/nonlinear/test_optmat_raman.py @@ -915,7 +915,7 @@ def test_optmats_tracker_ids_are_dropped_from_a_range_warning_and_its_record(): text = "of N2 Q (100-300 K): their mixing is not modelled" with warnings.catch_warnings(record=True) as caught: warnings.simplefilter("always") - warnings.warn(f"{text} (TC-527, TC-688)", ModelRangeWarning, stacklevel=1) + warnings.warn(f"{text} (TC-1, TC-2)", ModelRangeWarning, stacklevel=1) with ( bridge.material_context() as log, pytest.warns(MaterialRangeWarning) as raised, diff --git a/tests/nonlinear/test_optmat_rates.py b/tests/nonlinear/test_optmat_rates.py index 7ac96f9e8..52fbea4f3 100644 --- a/tests/nonlinear/test_optmat_rates.py +++ b/tests/nonlinear/test_optmat_rates.py @@ -12,6 +12,7 @@ import dataclasses import math +import re import warnings from functools import partial from typing import Any, cast @@ -130,7 +131,7 @@ def test_optmats_tracker_ids_are_dropped_from_a_rate_range_warning(): text = "below 350 nm (the carrier) the rate is extrapolated" with warnings.catch_warnings(record=True) as caught: warnings.simplefilter("always") - warnings.warn(f"{text} (TC-831)", ModelRangeWarning, stacklevel=1) + warnings.warn(f"{text} (TC-1)", ModelRangeWarning, stacklevel=1) with ( _optmat.material_context() as log, pytest.warns(MaterialRangeWarning) as raised, @@ -159,6 +160,22 @@ def test_the_ceiling_clips_and_a_field_must_be_finite(): rate(np.array([1e10, np.nan])) +def test_a_nan_rate_from_optmat_is_refused_and_an_infinite_one_clipped(monkeypatch): + rate = OptmatRate("Ar", WAVELENGTH, maximum=1e10) + field = 0.5 * rate.maximum_field + + def raw(self: OptmatRate, fields: np.ndarray) -> np.ndarray: + return np.full_like(fields, value) + + monkeypatch.setattr(OptmatRate, "_raw", raw) + value = math.inf + assert float(rate(field)) == 1e10 + value = math.nan + expected = rf"Ar: optmat's rate nan at {re.escape(f'{field:.4g}')} V/m" + with pytest.raises(MaterialError, match=expected): + rate(np.array([0.0, field])) + + def test_a_rate_table_reproduces_the_direct_rate_and_holds_above_the_maximum(): rate = OptmatRate("Ar", WAVELENGTH) table = build_rate_table(rate, (1e8, 30 * rate.maximum_field), use_cache=False) @@ -535,7 +552,7 @@ def test_construction_refuses_what_optmat_does_not_serve(): ): with pytest.raises(MaterialError, match=keyword): OptmatRate("Ar", WAVELENGTH, **cast("Any", {keyword: value})) - with pytest.raises(MaterialError, match="wavelength must be positive"): + with pytest.raises(MaterialError, match="wavelength must be finite and positive"): OptmatRate("Ar", True) for span in ((1e9, 1e8), (0.0, 1e9), (1e9, math.inf)): with pytest.raises(MaterialError, match="field_range"): diff --git a/tests/nonlinear/test_raman.py b/tests/nonlinear/test_raman.py index dde02a517..780f0073d 100644 --- a/tests/nonlinear/test_raman.py +++ b/tests/nonlinear/test_raman.py @@ -986,7 +986,7 @@ def test_the_response_cannot_follow_the_third_harmonic_beat(): # The two field-grid drives differ by the 2 omega0 beat, which for a 1030 nm # carrier is at 3.7e15 rad/s -- ten times the highest Raman line. The response is # a resonant low pass, so it filters the beat out almost entirely and the two - # forms give nearly the same polarisation. Measured: 2.4e-4 of the peak. This is + # forms give nearly the same polarisation. Measured: 4.5e-4 of the peak. This is # why the thg switch matters much less for Raman than for Kerr, and why the # difference must nevertheless not be exactly zero. _, _, field, _ = parity_signals() diff --git a/tests/nonlinear/test_responses.py b/tests/nonlinear/test_responses.py index 3dff9ef46..974a69a4b 100644 --- a/tests/nonlinear/test_responses.py +++ b/tests/nonlinear/test_responses.py @@ -246,7 +246,7 @@ def test_envelope_response_radiates_the_third_harmonic_only_when_declared( def test_thg_carrier_is_the_squared_carrier(): t = np.linspace(-1e-14, 1e-14, 33) omega0 = 1.8e15 - assert np.allclose(thg_carrier(omega0, t), np.exp(1j * omega0 * t) ** 2) + assert np.allclose(thg_carrier(omega0, t), np.exp(1j * omega0 * t) ** 2, atol=0.0) def test_thg_carrier_rejects_a_non_positive_frequency(): diff --git a/tests/nonlinear/test_silica_tensor_raman.py b/tests/nonlinear/test_silica_tensor_raman.py index 09d6dfba6..2be63acee 100644 --- a/tests/nonlinear/test_silica_tensor_raman.py +++ b/tests/nonlinear/test_silica_tensor_raman.py @@ -179,7 +179,7 @@ def test_the_vibrational_shape_is_the_existing_damped_oscillator(response, delay def test_the_seam_kernels_integrate_to_five_sixths_and_one_sixth(response): - """The A2 companion's 5/6 and 1/6, and not the paper's own 3/4 and 1/4. + """The seam's 5/6 and 1/6, derived below, and not the paper's own 3/4 and 1/4. ``r_trace = a + b/3`` and ``r_rank = 2 b/3`` come from matching ``a tr(Q) E + b Q E`` to the trace and ``T(Q) = (3 Q - tr(Q) I)/2`` channels the @@ -392,7 +392,7 @@ def undamped(self, t): numpy.ndarray The kernel, 1/s. """ - assert np.allclose(t, delays) + assert np.allclose(t, delays, atol=0.0) return self.values total = np.zeros_like(field) diff --git a/tests/output/test_callback.py b/tests/output/test_callback.py index 44114b8bc..8cef54750 100644 --- a/tests/output/test_callback.py +++ b/tests/output/test_callback.py @@ -39,8 +39,8 @@ CallbackOutput, MemoryOutput, check_cache, + read_resume_state, resumability, - resume, serialisation, ) from solprop.output.metadata import PEAK_FIELDS_ANNOTATION, _example_metadata @@ -569,10 +569,10 @@ def test_a_resume_is_refused_by_name(choice): ("reader", "name"), [ (lambda handler: check_cache(handler, _example_metadata()), "check_cache"), - (resume, "resume"), + (read_resume_state, "read_resume_state"), (resumability, "resumability"), ], - ids=["check_cache", "resume", "resumability"], + ids=["check_cache", "read_resume_state", "resumability"], ) @pytest.mark.parametrize("build", [opened, MemoryOutput], ids=["callback", "memory"]) def test_a_check_against_a_handler_is_refused_by_name(reader, name, build): diff --git a/tests/output/test_checkpoints.py b/tests/output/test_checkpoints.py index a42b3937d..ee6595c25 100644 --- a/tests/output/test_checkpoints.py +++ b/tests/output/test_checkpoints.py @@ -23,7 +23,7 @@ SavedPlane, StepHistory, open_file, - resume, + read_resume_state, ) from solprop.output.hdf5 import _dataset, _write_checkpoint from solprop.output.metadata import _example_metadata @@ -100,7 +100,7 @@ def test_memory_checkpoint_round_trip_preserves_counts_and_fft(metadata, tmp_pat assert_array_equal( stored.terminal_checkpoint.plane.field, checkpoint.plane.field ) - state = resume(path) + state = read_resume_state(path) assert state.n_saved == 1 assert state.plane.z == 0.25 assert state.checkpoint is not None and state.checkpoint.next_save_index == 0 @@ -123,7 +123,7 @@ def test_checkpoint_history_moves_to_next_regular_save_once(metadata, tmp_path): assert_array_equal(stored["step_history/counts"], [0, 2]) assert_array_equal(stored["step_stats/step"], [0, 1]) assert_array_equal(stored["step_history/z"], [0.125, 0.375]) - assert resume(path).history.n_steps == 2 + assert read_resume_state(path).history.n_steps == 2 def test_second_stop_retains_previous_unsaved_attempts(metadata, tmp_path): @@ -136,7 +136,7 @@ def test_second_stop_retains_previous_unsaved_attempts(metadata, tmp_path): RunOutcome("failed", 0.375), TerminalCheckpoint(plane(metadata, 0.375, history=True), 0), ) - state = resume(path) + state = read_resume_state(path) assert state.n_saved == 1 and state.history.n_steps == 2 assert_array_equal(state.plane.step_stats.step, [0, 1]) @@ -144,7 +144,7 @@ def test_second_stop_retains_previous_unsaved_attempts(metadata, tmp_path): def test_checkpoint_can_exist_before_first_regular_save(metadata, tmp_path): path = tmp_path / "entrance-failure.h5" stopped(metadata, path, 0.0) - state = resume(path) + state = read_resume_state(path) assert state.n_saved == 0 and state.plane.z == 0.0 assert state.checkpoint is not None @@ -197,7 +197,7 @@ def test_checkpoint_validation_preserves_interpolated_classification( RunOutcome("failed", 0.1), TerminalCheckpoint(plane(metadata, 0.1), 0, landed=False), ) - state = resume(path) + state = read_resume_state(path) assert state.checkpoint is not None and not state.checkpoint.landed assert state.n_saved == 0 and state.plane.z == 0.1 assert state.outcome is not None and state.outcome.z == state.plane.z @@ -206,7 +206,7 @@ def test_checkpoint_validation_preserves_interpolated_classification( file["terminal_checkpoint"].attrs["landed"] = True del file["meta/outcome"] with pytest.raises(OutputError, match="matching execution outcome"): - resume(path) + read_resume_state(path) def test_execution_records_own_json_values_and_keep_resume_history(metadata, tmp_path): @@ -308,6 +308,31 @@ def test_an_outcome_dataset_of_another_type_is_replaced_and_reads_back( assert handler.outcome.message == "replaced" +@pytest.mark.parametrize( + ("text", "reason"), + [("[1, 2]", "it is not a JSON object"), ("{not json", "Expecting property name")], + ids=["array", "malformed"], +) +def test_an_unreadable_outcome_is_refused_naming_the_file( + metadata, tmp_path, text, reason +): + # A file whose execution status is valid JSON of another kind, or not JSON at all, + # cannot say how its run ended: reading it to resume is refused, not guessed. + path = tmp_path / "broken.h5" + with HDF5Output(path) as handler: + handler.open(metadata) + handler.save(plane(metadata, 0.0)) + handler.record_outcome(RunOutcome("running", 0.0)) + with h5py.File(path, "r+") as file: + del file["meta/outcome"] + file.create_dataset("meta/outcome", data=text, dtype=h5py.string_dtype()) + with pytest.raises(OutputError) as refusal: + read_resume_state(path) + message = str(refusal.value) + assert message.startswith(f"{path}: cannot read the execution status it records: ") + assert reason in message + + @pytest.mark.parametrize("z", [-1.0, np.nan, np.inf]) def test_outcome_and_metadata_refuse_invalid_launch_positions(metadata, z): with pytest.raises(OutputError, match="finite and nonnegative"): @@ -377,7 +402,7 @@ def test_checkpoint_roundtrip_retains_available_statistics_and_noise( handler.record_outcome( RunOutcome("failed", saved.z), TerminalCheckpoint(saved, 0) ) - restored = resume(path).plane + restored = read_resume_state(path).plane assert_array_equal(restored.noise_phase, saved.noise_phase) assert_array_equal(restored.stats["energy"], saved.stats["energy"]) @@ -401,7 +426,7 @@ def test_read_refuses_malformed_checkpoint_scalar_attributes( with h5py.File(path, "r+") as stored: stored["terminal_checkpoint"].attrs[name] = value with pytest.raises(OutputError, match="typed scalars"): - resume(path) + read_resume_state(path) def test_new_checkpoint_replaces_an_interrupted_staging_group(metadata, tmp_path): @@ -415,7 +440,7 @@ def test_new_checkpoint_replaces_an_interrupted_staging_group(metadata, tmp_path handler.record_outcome( RunOutcome("failed", 0.1), TerminalCheckpoint(plane(metadata, 0.1), 0) ) - assert resume(path).plane.z == 0.1 + assert read_resume_state(path).plane.z == 0.1 with h5py.File(path) as stored: assert "_terminal_checkpoint_writing" not in stored @@ -426,7 +451,7 @@ def test_resume_refuses_checkpoint_older_than_last_regular_save(metadata, tmp_pa with h5py.File(path, "r+") as stored: stored["terminal_checkpoint"].attrs["z"] = 0.1 with pytest.raises(OutputError, match="precedes the last saved plane"): - resume(path) + read_resume_state(path) def test_storage_hook_can_clear_checkpoint_without_rewriting_outcome( @@ -489,7 +514,7 @@ def test_a_running_checkpoint_is_superseded_by_the_next_plane( if store == "hdf5": with h5py.File(tmp_path / "r.h5", "r") as file: assert "terminal_checkpoint" not in file - assert resume(tmp_path / "r.h5").plane.z == 0.375 + assert read_resume_state(tmp_path / "r.h5").plane.z == 0.375 def test_a_resume_from_a_running_checkpoint_neither_repeats_nor_loses_attempts( @@ -501,7 +526,7 @@ def test_a_resume_from_a_running_checkpoint_neither_repeats_nor_loses_attempts( handler.save(plane(metadata, 0.0)) handler.record_outcome(*_running(metadata, 0.125, [0.0])) # A snapshot copy, or a run killed after its running checkpoint. - state = resume(path) + state = read_resume_state(path) assert state.checkpoint is not None and state.plane.z == 0.125 assert_array_equal(state.history.z, [0.0]) with HDF5Output(path, append=True) as handler: @@ -544,7 +569,7 @@ def test_a_failure_without_a_checkpoint_falls_back_to_the_running_one( dataclasses.replace(held.plane), held.next_save_index, held.landed ) handler.record_outcome(RunOutcome("failed", 0.25, "abandoned"), held) - state = resume(path) + state = read_resume_state(path) assert state.outcome is not None and state.outcome.status == "failed" assert state.checkpoint is not None and state.plane.z == 0.25 assert_array_equal(state.history.z, [0.0, 0.125]) @@ -559,7 +584,7 @@ def test_a_closing_outcome_without_a_checkpoint_still_clears_the_running_one( handler.save(plane(metadata, 0.0)) handler.record_outcome(*_running(metadata, 0.125, [0.0])) handler.record_outcome(RunOutcome("failed", 0.0, "no state")) - assert resume(path).checkpoint is None + assert read_resume_state(path).checkpoint is None def _stale_running_file(metadata, path, *, window): @@ -602,7 +627,7 @@ def test_a_stale_running_checkpoint_is_ignored_rather_than_refused( path = tmp_path / "stale.h5" _stale_running_file(metadata, path, window=window) with caplog.at_level(logging.INFO, logger="solprop.output.hdf5"): - state = resume(path) + state = read_resume_state(path) assert "ignoring the checkpoint" in caplog.text assert state.checkpoint is None last = 0.25 if window == "append" else 0.0 @@ -637,4 +662,4 @@ def test_a_closing_record_disagreeing_with_its_checkpoint_is_refused( assert kept is not None assert kept.plane.z == 0.375 with pytest.raises(OutputError, match="no matching execution outcome"): - resume(path) + read_resume_state(path) diff --git a/tests/output/test_field_retention.py b/tests/output/test_field_retention.py index e677b1819..3a501c40d 100644 --- a/tests/output/test_field_retention.py +++ b/tests/output/test_field_retention.py @@ -21,7 +21,7 @@ from solprop import fourier from solprop.exceptions import DriverError, OutputError from solprop.output import HDF5Output, MemoryOutput, Output, open_file -from solprop.output.hdf5 import resume +from solprop.output.hdf5 import read_resume_state from solprop.output.metadata import _example_metadata from solprop.output.records import RunOutcome, SavedPlane, TerminalCheckpoint from solprop.output.serialisation import ( @@ -307,7 +307,7 @@ def test_a_field_free_file_resumes_only_from_its_checkpoint(tmp_path, metadata): written.retain(resolved, (1, 1, metadata.grid.n_omega)) for plane in planes(metadata, resolved)[:3]: written.save(plane) - state = resume(path) + state = read_resume_state(path) assert state.n_saved == 3 and state.plane.field is None assert state.plane.z == pytest.approx(0.2) with HDF5Output(path, append=True) as again: @@ -320,7 +320,7 @@ def test_a_field_free_file_resumes_only_from_its_checkpoint(tmp_path, metadata): SavedPlane(z=0.25, field=field(metadata, 9.0)), 3, landed=True ) again.record_outcome(RunOutcome("failed", 0.25), checkpoint) - state = resume(path) + state = read_resume_state(path) assert state.checkpoint is not None and state.plane.field is not None assert np.array_equal(state.plane.field, field(metadata, 9.0)) diff --git a/tests/output/test_flow_resume.py b/tests/output/test_flow_resume.py index a7d2064a6..828448c7d 100644 --- a/tests/output/test_flow_resume.py +++ b/tests/output/test_flow_resume.py @@ -53,7 +53,7 @@ from solprop.driver import Simulation from solprop.exceptions import GrazingIncidenceWarning, MaterialRangeWarning from solprop.modes import CoherentWall -from solprop.output.hdf5 import resume +from solprop.output.hdf5 import read_resume_state from solprop.stepper import FixedSchedule pytestmark = [ @@ -167,7 +167,7 @@ def interrupted(build, tmp_path, *, planes): # Stopped at the plane after the entrance: the rest comes from the resume. assert stored(part)["z"].size == planes - 1 build().run(part, resume=True, progress="none") - whole_state, resumed_state = resume(whole), resume(part) + whole_state, resumed_state = read_resume_state(whole), read_resume_state(part) first, second = whole_state.metadata, resumed_state.metadata whole_outcome, resumed_outcome = whole_state.outcome, resumed_state.outcome assert whole_outcome is not None and resumed_outcome is not None diff --git a/tests/output/test_handlers.py b/tests/output/test_handlers.py index aa55ebf3d..bd43cfd70 100644 --- a/tests/output/test_handlers.py +++ b/tests/output/test_handlers.py @@ -6,6 +6,7 @@ import dataclasses import json +import re import signal import subprocess import sys @@ -27,7 +28,7 @@ Output, check_cache, open_file, - resume, + read_resume_state, ) from solprop.output import hdf5 as hdf5_module from solprop.output.hdf5 import COMPRESSIONS @@ -37,6 +38,8 @@ HISTORY_FIELDS, GridRecord, NoiseRecord, + RecipeRecord, + RunOutcome, SavedPlane, StepHistory, StepLimits, @@ -437,6 +440,51 @@ def test_open_file_reads_a_finished_run_through_the_protocol(grid, metadata, tmp assert np.array_equal(stored["field"], memory["field"]) +def _restamp_outcome(path, change): + """Rewrite a file's stored execution status as `change` edits its JSON.""" + with h5py.File(path, "r+") as file: + record = json.loads(item(file, "meta", "outcome")[()].decode("utf-8")) + change(record) + del file["meta/outcome"] + file.create_dataset( + "meta/outcome", data=json.dumps(record), dtype=h5py.string_dtype() + ) + + +def test_an_outcome_from_another_build_reads_tolerantly(grid, metadata, tmp_path): + # As the record does: an entry this build lacks is dropped, an absent one defaults. + path = tmp_path / "run.h5" + with HDF5Output(path) as handler: + run_into(handler, grid, metadata, 1) + handler.record_outcome(RunOutcome("complete", 0.25, message="done")) + + def change(record): + record["entry_of_a_later_build"] = 1 + del record["message"] + + _restamp_outcome(path, change) + with open_file(path) as stored: + assert stored.outcome == RunOutcome("complete", 0.25) + + +def test_an_unreadable_outcome_is_refused_by_name_and_releases_the_file( + grid, metadata, tmp_path +): + path = tmp_path / "run.h5" + with HDF5Output(path) as handler: + run_into(handler, grid, metadata, 1) + handler.record_outcome(RunOutcome("complete", 0.25)) + _restamp_outcome(path, lambda record: record.pop("status")) + with pytest.raises( + OutputError, match=rf"{re.escape(str(path))}: .*outcome\.status" + ) as refused: + open_file(path) + # Closed by the refusal itself: the traceback still holds the half-built + # handler, so collecting it is not what releases the file. + assert refused.tb is not None + assert str(path) not in _open_paths() + + def test_open_file_refuses_what_is_not_a_run(tmp_path): with pytest.raises(OutputError, match="cannot read"): open_file(tmp_path / "missing.h5") @@ -456,7 +504,7 @@ def test_the_noise_realisation_travels_in_the_metadata(grid, schedule, tmp_path) handler = HDF5Output(tmp_path / "run.h5") run_into(handler, grid, metadata, 1) handler.close() - stored = resume(tmp_path / "run.h5").metadata.noise + stored = read_resume_state(tmp_path / "run.h5").metadata.noise assert stored is not None assert stored.spectral_convention == "fft" assert np.array_equal(stored.spectrum, realisation.spectrum) @@ -651,6 +699,31 @@ def test_a_closed_file_handler_names_a_missing_file(grid, metadata, tmp_path): handler["field"] +@pytest.mark.parametrize("change", ["another run", "a continuation"]) +def test_a_closed_file_handler_refuses_a_file_that_changed( + grid, metadata, schedule, tmp_path, change +): + # A second run into the same path, or a continuation of the run there, leaves a + # file the closed handler's counts and record no longer describe. + path = tmp_path / "run.h5" + first = HDF5Output(path) + run_into(first, grid, metadata, 2) + first.close() + if change == "another run": + other = make_metadata(grid, schedule, configuration={"gamma": 0.22}) + with HDF5Output(path) as second: + run_into(second, grid, other, 3) + else: + with HDF5Output(path, append=True) as second: + second.open(metadata) + second.save(make_plane(grid, 2)) + with pytest.raises(OutputError, match=rf"{re.escape(str(path))} has changed"): + first["field"] + # The file itself reads, through a handler of its own. + with hdf5_module.open_file(path) as current: + assert current.n_saved == 3 + + def test_a_suspended_file_handler_refuses_to_read(grid, metadata, tmp_path): handler = HDF5Output(tmp_path / "run.h5") run_into(handler, grid, metadata, 1) @@ -754,7 +827,7 @@ def test_a_different_run_is_refused_unless_forced(grid, schedule, tmp_path): assert handler.metadata is two handler.save(make_plane(grid, 0)) handler.close() - assert resume(tmp_path / "run.h5").metadata.configuration_hash() == ( + assert read_resume_state(tmp_path / "run.h5").metadata.configuration_hash() == ( two.configuration_hash() ) @@ -858,7 +931,7 @@ def test_resume_restores_the_last_plane_the_schedule_and_the_history( handler = HDF5Output(tmp_path / "run.h5") planes = run_into(handler, grid, metadata, 4, with_noise=True) handler.close() - state = resume(tmp_path / "run.h5") + state = read_resume_state(tmp_path / "run.h5") assert state.n_saved == 4 assert state.plane.z == pytest.approx(planes[-1].z) # The field comes back through the inverse of the storage boundary, which is exact. @@ -877,7 +950,7 @@ def test_resume_refuses_a_file_with_no_plane(metadata, tmp_path): handler.open(metadata) handler.close() with pytest.raises(OutputError, match="holds no saved plane"): - resume(tmp_path / "run.h5") + read_resume_state(tmp_path / "run.h5") # ------------------------------------------------------------------------ append @@ -905,7 +978,7 @@ def test_an_appending_handler_continues_the_file_where_it_stopped( assert again["step_history/counts"].tolist() == [1, 2, 3, 1] again.close() - state = resume(path) + state = read_resume_state(path) assert state.n_saved == 4 assert np.array_equal(kept(state.plane.field), kept(later[-1].field)) assert state.history.n_steps == sum( @@ -932,7 +1005,7 @@ def test_an_appending_handler_refuses_a_different_run(grid, schedule, tmp_path): again.open(make_metadata(grid, schedule, configuration={"gamma": 0.22})) again.close() # The refusal left the file as it was. - assert resume(path).n_saved == 1 + assert read_resume_state(path).n_saved == 1 def test_an_appending_handler_needs_a_file_to_append_to(metadata, tmp_path): @@ -978,7 +1051,7 @@ def test_an_appending_handler_accepts_a_file_with_metadata_but_no_plane( assert again.n_saved == 0 again.save(make_plane(grid, 0)) again.close() - assert resume(path).n_saved == 1 + assert read_resume_state(path).n_saved == 1 # ------------------------------------------------------------------------ to_file @@ -1006,6 +1079,16 @@ def test_to_file_writes_what_the_file_handler_would_have(grid, metadata, tmp_pat assert item(one, "meta/json")[()] == item(two, "meta/json")[()] +def test_to_file_keeps_the_recipe_the_run_was_built_from(grid, metadata, tmp_path): + # The recipe is what resumes the file and what rebuilds its planes' modes. + record = RecipeRecord(1, 'route = "gnlse"\n', 'route = "gnlse"\nseed = "7"\n') + memory = MemoryOutput() + run_into(memory, grid, metadata, 2) + memory.record_recipe(record) + memory.to_file(tmp_path / "run.h5") + assert hdf5_module.open_file(tmp_path / "run.h5").recipe == record + + def test_to_file_passes_its_compression_through(grid, metadata, tmp_path): memory = MemoryOutput() run_into(memory, grid, metadata, 2) @@ -1060,9 +1143,9 @@ def test_the_backend_group_survives_both_handlers(tmp_path, grid, schedule): """ record = BackendRecord.from_metadata( { - "backend": "numba_cpu", + "backend": "native", "propagator_mode": "recompute", - "numba_threads": 4, + "thread_count": 4, "plan_flag": "measure", "wisdom_digest": "0" * 16, } @@ -1079,30 +1162,30 @@ def test_the_backend_group_survives_both_handlers(tmp_path, grid, schedule): assert record is not None stored = record.backend assert stored is not None - assert stored.name == "numba_cpu" + assert stored.name == "native" assert stored.propagator_mode == "recompute" - assert stored.settings["numba_threads"] == 4 + assert stored.settings["thread_count"] == 4 assert stored.settings["wisdom_digest"] == "0" * 16 with h5py.File(path, "r") as file: - assert file.attrs["backend"] == "numba_cpu" + assert file.attrs["backend"] == "native" -def test_a_file_recording_a_removed_backend_still_opens_and_resumes( +def test_a_backend_name_this_build_does_not_know_is_read_not_refused( tmp_path, grid, schedule ): - """A recorded name is not a request: old output keeps the name it was written with. + """A recorded name is not a request: a file keeps the name it was written with. - Hand-built, as 0.2.0 wrote a file with ``mlx`` before SEP 47 retired it; the name - is refused where a run asks for it (``tests/backends/test_registry.py``), never - where a file is read. + An unknown name is refused where a run asks for it + (``tests/backends/test_registry.py``), never where a file is read, so a file written + by a build with another backend opens and resumes here. """ - name, settings = "mlx", {"device": "gpu", "fused": True} + name, settings = "elsewhere", {"device": "gpu", "fused": True} assert name not in BACKEND_NAMES record = BackendRecord.from_metadata( {"backend": name, "propagator_mode": "recompute", **settings} ) metadata = dataclasses.replace(make_metadata(grid, schedule), backend=record) - path = tmp_path / "old.h5" + path = tmp_path / "elsewhere.h5" with HDF5Output(path) as handler: handler.open(metadata) handler.save(make_plane(grid, 0)) @@ -1117,10 +1200,10 @@ def test_a_file_recording_a_removed_backend_still_opens_and_resumes( assert written.name == name assert dict(written.settings) == settings assert name in repr(stored) - # The resume key holds the problem and the state: the old file is the same run. + # The resume key holds the problem and the state: the file is the same run. assert check_cache(path, metadata) assert check_cache(path, make_metadata(grid, schedule)) - assert resume(path).plane.z == make_plane(grid, 0).z + assert read_resume_state(path).plane.z == make_plane(grid, 0).z def test_the_backend_group_is_outside_the_resume_key(grid, schedule): @@ -1303,7 +1386,7 @@ def test_an_appending_handler_continues_the_channel_where_it_stopped( handler.open(metadata) for plane in first: handler.save(plane) - state = hdf5_module.resume(path) + state = hdf5_module.read_resume_state(path) # The last plane comes back with its own rows, not the whole run's. assert state.plane.step_stats.n_rows == first[-1].step_stats.n_rows np.testing.assert_array_equal(state.plane.step_stats.z, first[-1].step_stats.z) @@ -1343,9 +1426,9 @@ def test_a_plane_whose_channel_changes_its_statistics_is_refused(grid, metadata) def test_a_run_record_declares_the_current_output_schema(metadata): - """Schema 4 is schema 1, the first released layout, plus three changes.""" - assert SCHEMA_VERSION == 4 - assert metadata.schema_version == 4 + """Schema 3 is schema 1, the first released layout, plus three changes.""" + assert SCHEMA_VERSION == 3 + assert metadata.schema_version == 3 def test_five_columns_continue_as_before(grid, metadata, tmp_path): @@ -1355,15 +1438,21 @@ def test_five_columns_continue_as_before(grid, metadata, tmp_path): with HDF5Output(path) as handler: handler.open(metadata) handler.save(plane) - assert hdf5_module.resume(path).n_saved == 1 + assert hdf5_module.read_resume_state(path).n_saved == 1 assert hdf5_module.check_cache(path, metadata) -@pytest.mark.parametrize("declared", [1, 10, 28, SCHEMA_VERSION + 1]) +@pytest.mark.parametrize( + "declared", + [1, 2, 10, 28, SCHEMA_VERSION + 1], + ids=["0.1.0", "0.2.0", "ten", "last", "later"], +) def test_a_file_of_another_output_schema_is_refused_by_name( grid, metadata, tmp_path, declared ): - """A development file or one from a later release is not read, at any door. + """A released file, a development file or one from a later release is not read. + + Every door refuses it: reading, resuming, the cache check and appending. The file is a current one whose record is restamped with another version, so the refusal is the version's and not that of some field the layout lacks. @@ -1381,11 +1470,21 @@ def test_a_file_of_another_output_schema_is_refused_by_name( "meta/json", data=json.dumps(document), dtype=h5py.string_dtype() ) file.attrs["schema_version"] = declared - refusal = rf"schema_version {declared}.*reads output schema 4 only" + # Every door names the file, and the refusal the release that wrote a released one. + refusal = ( + rf"^{re.escape(str(path))}: this record declares output schema_version " + rf"{declared}.*reads output schema 3 only.*" + + ( + rf"; output schema {declared} is solprop 0\.{declared}\.x's: read it with " + "that release$" + if declared in {1, 2} + else "; read it with the solprop version that wrote it$" + ) + ) with pytest.raises(OutputError, match=refusal): hdf5_module.open_file(path) with pytest.raises(OutputError, match=refusal): - hdf5_module.resume(path) + hdf5_module.read_resume_state(path) with pytest.raises(OutputError, match=refusal): hdf5_module.check_cache(path, metadata) continued = HDF5Output(path, append=True) diff --git a/tests/output/test_material_resume.py b/tests/output/test_material_resume.py index 1a11b0cf5..4b21fc00c 100644 --- a/tests/output/test_material_resume.py +++ b/tests/output/test_material_resume.py @@ -23,7 +23,7 @@ from solprop.exceptions import OutputError from solprop.grid import FieldGrid from solprop.output import HDF5Output, MemoryOutput, open_file -from solprop.output.hdf5 import check_cache, resume +from solprop.output.hdf5 import check_cache, read_resume_state from solprop.output.metadata import SCHEMA_VERSION, RunMetadata from solprop.output.records import SavedPlane from solprop.output.scan import PointResult, ScanWriter @@ -77,7 +77,7 @@ def selected(): def test_the_current_schema_carries_the_manifest_through_memory_and_json(selected): - assert SCHEMA_VERSION == 4 == selected.schema_version + assert SCHEMA_VERSION == 3 == selected.schema_version memory = MemoryOutput() memory.open(selected) stored: Any = memory.metadata @@ -95,7 +95,7 @@ def test_the_manifest_round_trips_through_hdf5_and_resumes(tmp_path, selected): path = written(tmp_path / "run.h5", selected) stored: Any = open_file(path).metadata assert stored.materials == selected.materials - assert resume(path).metadata.materials == selected.materials + assert read_resume_state(path).metadata.materials == selected.materials assert check_cache(path, selected) # An identical manifest rebuilt in the same process resumes too. assert check_cache(path, metadata()) diff --git a/tests/output/test_modal_resume.py b/tests/output/test_modal_resume.py index 4a586c98e..20a8a6515 100644 --- a/tests/output/test_modal_resume.py +++ b/tests/output/test_modal_resume.py @@ -36,7 +36,7 @@ from solprop.modes.protocol import ChannelLabel from solprop.modes.tables import DEFAULT_GRAM_ATOL from solprop.output import HDF5Output -from solprop.output.hdf5 import check_cache, open_file, resume +from solprop.output.hdf5 import check_cache, open_file, read_resume_state from solprop.output.memory import MemoryOutput from solprop.output.metadata import SCHEMA_VERSION, RunMetadata, _example_metadata from solprop.output.records import ModeRecord, SavedPlane @@ -142,8 +142,8 @@ def written(guide, grid, tmp_path_factory): def test_the_record_carries_every_modal_identity(written, guide): """Labels, tables, metric, responses, guide, frame, band, noise and accessors.""" - stored = resume(written).metadata - assert stored.schema_version == SCHEMA_VERSION == 4 + stored = read_resume_state(written).metadata + assert stored.schema_version == SCHEMA_VERSION == 3 modal = stored.modal assert modal is not None assert set(modal) == { @@ -190,7 +190,7 @@ def test_the_measured_entries_of_the_key_are_quantised_and_the_declared_are_not( declared `chi3`, a radius and a knot enter exactly, because a caller who changes one means to. """ - stored = resume(written).metadata + stored = read_resume_state(written).metadata measured = { "modal.metric.defect": at(stored.modal, "metric", "defect"), "modal.guide.sampling.profile_error": at( @@ -225,7 +225,7 @@ def test_the_measured_entries_of_the_key_are_quantised_and_the_declared_are_not( def test_the_labels_round_trip_through_the_file(written): """`ChannelLabel.as_mapping` out, `ChannelLabel.from_mapping` back.""" - stored = resume(written).metadata + stored = read_resume_state(written).metadata labels = [ ChannelLabel.from_mapping(dict(one.label)) for one in stored.modes @@ -238,7 +238,7 @@ def test_the_labels_round_trip_through_the_file(written): def test_the_whole_record_survives_json_and_hashes_the_same(written): """A record read back from the file hashes to the digest the file was stamped.""" - stored = resume(written).metadata + stored = read_resume_state(written).metadata again = RunMetadata.from_json(stored.to_json()) assert again.modal == stored.modal assert [one.label for one in again.modes] == [one.label for one in stored.modes] @@ -255,7 +255,7 @@ def test_the_printed_block_prints_every_modal_identity_field_with_its_value(writ 412-character JSON document on this one-channel fixture and filled the row with the opening of a serialised mapping before. """ - stored = resume(written).metadata + stored = read_resume_state(written).metadata block = str(stored) modal = stored.modal assert modal is not None @@ -278,7 +278,7 @@ def test_the_printed_block_prints_every_modal_identity_field_with_its_value(writ assert value in block, (line, value) # The long `model_id` itself is on the record, and not in the printed row. assert str(at(modal, "tables", "model_id")) not in block - assert "schema 4" in block + assert "schema 3" in block # Twelve rows for thirteen fields: the basis row carries `n_components` too. printed = {key for key, _ in stored._describe()[1]} assert len(printed & MODAL_ROWS) == len(MODAL_ROWS) @@ -313,7 +313,7 @@ def test_the_printed_block_survives_a_record_it_cannot_read( says so rather than raising while a reader is trying to find out what the file is. Nothing here is a route solprop writes -- it is what a reader survives. """ - stored = resume(written).metadata + stored = read_resume_state(written).metadata modal = dict(cast("dict[str, object]", stored.modal)) modal[entry] = value assert expected in str(dataclasses.replace(stored, modal=modal)) @@ -351,7 +351,7 @@ def test_the_published_accessor_list_is_recorded_and_hashed(written): whose list differs, shorter or longer, has another configuration hash, and the difference is named by the list. """ - stored = resume(written).metadata + stored = read_resume_state(written).metadata assert stored.modal is not None published = at(stored.modal, "accessors") assert published == sorted(GENERAL_MODAL_ACCESSORS) @@ -372,7 +372,7 @@ def test_a_file_with_another_accessor_list_is_refused(written, tmp_path): Shorter, longer or absent, the list is compared as every other hashed entry is, and the refusal names it. """ - metadata = resume(written).metadata + metadata = read_resume_state(written).metadata assert metadata.modal is not None published = at(metadata.modal, "accessors") assert check_cache(_written_with(tmp_path / "same.h5", metadata), metadata) is True @@ -484,7 +484,10 @@ def test_the_same_schedule_resumes_onto_the_same_march(guide, grid, tmp_path): exact=("z", "step_history/z", "step_history/h"), ) # And the resumed file still says which guide produced it. - assert resume(part).metadata.modal == resume(whole).metadata.modal + assert ( + read_resume_state(part).metadata.modal + == read_resume_state(whole).metadata.modal + ) @pytest.mark.parametrize( @@ -495,7 +498,7 @@ def test_a_changed_guide_table_or_material_refuses_by_the_field_that_moved( guide, grid, written, what, field ): """A resume names the mismatching field, not "the hash does not agree".""" - stored = resume(written).metadata + stored = read_resume_state(written).metadata if what == "radius": other = general_guide(grid=grid, radius=1.6e-6) elif what == "chi3": @@ -510,7 +513,7 @@ def test_a_changed_guide_table_or_material_refuses_by_the_field_that_moved( def test_a_reordered_mode_axis_is_a_different_run(grid): - """The reviewer's trap: the same two channels, declared the other way round.""" + """The same two channels declared the other way round are a different run.""" one = general_guide( descriptors=(("HE", 1, 1, "even"), ("HE", 1, 1, "odd")), blocks=((0, 1),), @@ -565,7 +568,7 @@ def test_the_noise_realisation_is_recorded_and_reconstructed_on_resume( path = tmp_path / "noisy.h5" simulation = build(guide, grid, noise="input", seed=17) simulation.run(path, progress="none") - stored = resume(path).metadata + stored = read_resume_state(path).metadata assert stored.noise is not None assert stored.noise.seed == 17 assert at(stored.modal, "noise_reference_basis") == "orthonormal true power" @@ -590,7 +593,7 @@ def test_the_memory_handler_writes_the_same_file_afterwards(guide, grid, tmp_pat output = cast("MemoryOutput", build(guide, grid).run(progress="none")) path = tmp_path / "from_memory.h5" output.to_file(path) - stored = resume(path) + stored = read_resume_state(path) assert stored.metadata.modal is not None last = output.planes()[-1].field assert stored.plane.field is not None and last is not None @@ -617,8 +620,8 @@ def test_a_scan_point_writes_its_spool_and_reads_the_identity_back( build(guide, grid).run(capture, progress="none") results = capture.results() assert float(results["reduced/spooled_flux"]) > 0.0 - stored = resume(capture.custom_path).metadata - assert stored.schema_version == SCHEMA_VERSION == 4 + stored = read_resume_state(capture.custom_path).metadata + assert stored.schema_version == SCHEMA_VERSION == 3 assert stored.modal is not None assert at(stored.modal, "basis") == "general_modal" assert [one.label for one in stored.modes] != [None] @@ -671,7 +674,7 @@ def test_a_file_in_one_basis_refuses_to_resume_in_another(grid, basis_pair, tmp_ """Four independent paths, each naming itself; the digest moves with them.""" path = tmp_path / "circular.h5" build(basis_pair["circular"], grid).run(path, progress="none") - stored = resume(path).metadata + stored = read_resume_state(path).metadata other = build(basis_pair["plain"], grid).metadata() changed = stored.differences(other) for field in ( @@ -696,7 +699,7 @@ def test_a_file_without_a_basis_refuses_to_resume_with_one(grid, basis_pair, tmp """ path = tmp_path / "plain.h5" build(basis_pair["plain"], grid).run(path, progress="none") - stored = resume(path).metadata + stored = read_resume_state(path).metadata other = build(basis_pair["circular"], grid).metadata() changed = stored.differences(other) assert any(one.startswith("modal.metric.gauge_id") for one in changed), changed diff --git a/tests/output/test_power_convention.py b/tests/output/test_power_convention.py index a6de8b3af..75124a5c4 100644 --- a/tests/output/test_power_convention.py +++ b/tests/output/test_power_convention.py @@ -11,7 +11,7 @@ from solprop.exceptions import GridError from solprop.fourier import power_amplitude from solprop.output import HDF5Output -from solprop.output.hdf5 import check_cache, resume +from solprop.output.hdf5 import check_cache, read_resume_state from solprop.output.metadata import _example_metadata from solprop.output.records import SavedPlane @@ -30,7 +30,10 @@ def test_the_hash_and_field_attribute_record_the_power_convention(tmp_path): with h5py.File(path) as file: assert file["field"].attrs["power_convention"] == "poynting" assert check_cache(path, metadata) - assert resume(path).metadata.configuration_hash() == metadata.configuration_hash() + assert ( + read_resume_state(path).metadata.configuration_hash() + == metadata.configuration_hash() + ) def test_power_amplitude_roundtrip_and_exact_unit_override(): diff --git a/tests/output/test_preallocation.py b/tests/output/test_preallocation.py index 587204031..3342e8412 100644 --- a/tests/output/test_preallocation.py +++ b/tests/output/test_preallocation.py @@ -24,7 +24,7 @@ from solprop.driver import Simulation from solprop.driver.estimate import _catalogued_entries, plane_bytes from solprop.grid import EnvelopeGrid -from solprop.output import HDF5Output, MemoryOutput, open_file, resume +from solprop.output import HDF5Output, MemoryOutput, open_file, read_resume_state from solprop.output.metadata import RunMetadata from solprop.output.records import ( GridRecord, @@ -281,7 +281,7 @@ def test_an_interrupted_file_reads_resumes_and_continues_exactly( assert_identical( stored(file), stored(write(MemoryOutput(), metadata, planes[:5])) ) - state = resume(path) + state = read_resume_state(path) assert state.n_saved == 5 assert state.plane.z == planes[4].z np.testing.assert_array_equal(state.plane.field, planes[4].field) @@ -340,7 +340,7 @@ def test_a_hard_stop_part_way_through_a_plane_loses_only_that_plane(metadata, tm assert file.n_saved == 3 np.testing.assert_array_equal(file["z"], [0.0, 0.1, 0.2]) np.testing.assert_array_equal(file["stats/energy"][:, 0], [0.0, 1.0, 2.0]) - assert resume(path).plane.z == 0.2 + assert read_resume_state(path).plane.z == 0.2 # ------------------------------------------------------------- memory admission diff --git a/tests/output/test_recipe_group.py b/tests/output/test_recipe_group.py index f63669ffb..b37bb6e25 100644 --- a/tests/output/test_recipe_group.py +++ b/tests/output/test_recipe_group.py @@ -4,7 +4,10 @@ """The recipe group of an output file round-trips its texts and data files (SEP 41).""" +import hashlib + import h5py +import numpy as np from solprop.output.hdf5 import read_recipe, write_recipe from solprop.output.records import RecipeFile, RecipeRecord @@ -28,3 +31,43 @@ def test_a_recipe_and_its_files_read_back_as_written(tmp_path): write_recipe(file, record) with h5py.File(tmp_path / "run.h5", "r") as file: assert read_recipe(file) == record + + +def _dataset(group: h5py.Group, name: str) -> h5py.Dataset: + found = group[name] + assert isinstance(found, h5py.Dataset) + return found + + +def test_the_recipe_group_has_its_documented_layout_and_digests(tmp_path): + # Read with h5py alone, so the layout of docs/guide/results/output.md is pinned + # independently of solprop's own reader. + authored, resolved = 'route = "gnlse"\n', 'route = "gnlse"\nseed = "7"\n' + data = b"\x93NUMPY\x00\x01" + record = RecipeRecord( + 1, + authored, + resolved, + {"spectrum-0.npy": RecipeFile("spectrum.npy", "ab" * 32, data)}, + ) + with h5py.File(tmp_path / "run.h5", "w") as file: + write_recipe(file, record) + with h5py.File(tmp_path / "run.h5", "r") as file: + group = file["recipe"] + assert isinstance(group, h5py.Group) + assert set(group) == {"authored", "resolved", "files"} + texts = { + name: str(_dataset(group, name).asstr()[()]) + for name in ("authored", "resolved") + } + assert texts == {"authored": authored, "resolved": resolved} + assert group.attrs["format"] == 1 + for name, text in texts.items(): + digest = hashlib.sha256(text.encode("utf-8")).hexdigest() + assert group.attrs[f"{name}_sha256"] == digest + entry = _dataset(group, "files/spectrum-0.npy") + assert np.asarray(entry[()], dtype=np.uint8).tobytes() == data + assert (entry.attrs["path"], entry.attrs["sha256"]) == ( + "spectrum.npy", + "ab" * 32, + ) diff --git a/tests/output/test_scan.py b/tests/output/test_scan.py index d50ea872c..e26f4d3e9 100644 --- a/tests/output/test_scan.py +++ b/tests/output/test_scan.py @@ -8,6 +8,7 @@ import json import logging import os +import re import sys import threading import time @@ -188,11 +189,18 @@ def test_scan_bad_payload_never_publishes_done(tmp_path, changes): writer.close() -@pytest.mark.parametrize("status,index", [("unknown", 0), ("done", -1), ("done", 1)]) -def test_scan_writer_refuses_invalid_publication(tmp_path, status, index): +@pytest.mark.parametrize( + "status,index,message", + [ + ("unknown", 0, "invalid point status 'unknown'"), + ("done", -1, "result index is outside the scan"), + ("done", 1, "result index is outside the scan"), + ], +) +def test_scan_writer_refuses_invalid_publication(tmp_path, status, index, message): writer = ScanWriter(tmp_path / "scan.h5", Scan("scan", x=[1]), {}) try: - with pytest.raises(OutputError): + with pytest.raises(OutputError, match=message): writer.commit(dataclasses.replace(result(index), status=status)) assert writer.state(0)[0] == "todo" finally: @@ -277,16 +285,22 @@ def _declare_schema(path, index, version): group.attrs["metadata_refs"] = json.dumps(references) -def test_scan_of_another_output_schema_is_refused_by_every_route(tmp_path): - # A 0.1.0 scan: the same container, records declaring output schema 1. +@pytest.mark.parametrize("declared", [1, 2], ids=["0.1.0", "0.2.0"]) +def test_scan_of_another_output_schema_is_refused_by_every_route(tmp_path, declared): + # A released scan: the same container, records declaring the output schema 0.1.0 + # or 0.2.0 wrote, and a refusal naming the release to read it with. path = tmp_path / "scan.h5" scan = Scan("scan", x=[1, 2, 3]) writer = ScanWriter(path, scan, {}) writer.commit(result(0)) writer.commit(dataclasses.replace(result(1), status="failed", arrays={})) writer.close() - _declare_schema(path, 1, 1) - refusal = "scan point 1: this record declares output schema_version 1, and this" + _declare_schema(path, 1, declared) + refusal = ( + rf"{re.escape(str(path))}, scan point 1: this record declares output " + rf"schema_version {declared}, and this.*; output schema {declared} is solprop " + rf"0\.{declared}\.x's: read it with that release$" + ) with pytest.raises(OutputError, match=refusal): ScanOutput(path) with pytest.raises(OutputError, match=refusal): @@ -298,7 +312,7 @@ def test_scan_of_another_output_schema_is_refused_by_every_route(tmp_path): status = np.asarray(_dataset(file, "points/status").asstr()[...]) assert status.tolist() == ["done", "failed", "todo"] # The point of this release's schema is still read alone. - assert cast(Mapping, read_point(path, 0)["metadata"])["schema_version"] == 4 + assert cast(Mapping, read_point(path, 0)["metadata"])["schema_version"] == 3 def test_scan_of_this_output_schema_reads_as_before(tmp_path): diff --git a/tests/output/test_scan_artifacts.py b/tests/output/test_scan_artifacts.py index c95bdba37..8008798ae 100644 --- a/tests/output/test_scan_artifacts.py +++ b/tests/output/test_scan_artifacts.py @@ -21,14 +21,20 @@ @pytest.mark.parametrize( - "payload", - [PointResult(0, "running"), PointResult(0, "failed", arrays={"z": np.zeros(1)})], + ("payload", "message"), + [ + (PointResult(0, "running"), "only completed or failed results"), + ( + PointResult(0, "failed", arrays={"z": np.zeros(1)}), + "failed artifacts must not retain numerical arrays", + ), + ], ) def test_artifact_write_refuses_incomplete_or_failed_numerical_payload( - tmp_path, payload + tmp_path, payload, message ): path = tmp_path / "point.h5" - with pytest.raises(OutputError): + with pytest.raises(OutputError, match=message): write_artifact(path, payload, {"scan": "identity"}) assert not path.exists() diff --git a/tests/output/test_schema.py b/tests/output/test_schema.py index d0f017186..050703635 100644 --- a/tests/output/test_schema.py +++ b/tests/output/test_schema.py @@ -547,29 +547,37 @@ def test_metadata_hash_changes_with_any_physics_field( def test_the_output_schema_is_the_current_one(envelope_grid, stepper): - assert SCHEMA_VERSION == 4 + assert SCHEMA_VERSION == 3 metadata = make_metadata(envelope_grid, stepper) - assert metadata.schema_version == 4 - assert metadata.hashed()["schema_version"] == 4 - assert json.loads(metadata.to_json())["schema_version"] == 4 + assert metadata.schema_version == 3 + assert metadata.hashed()["schema_version"] == 3 + assert json.loads(metadata.to_json())["schema_version"] == 3 @pytest.mark.parametrize( "declared", - [0, 1, 10, 28, SCHEMA_VERSION + 1, True], - ids=["zero", "released", "ten", "last", "later", "bool"], + [0, 1, 2, 10, 28, SCHEMA_VERSION + 1, True], + ids=["zero", "0.1.0", "0.2.0", "ten", "last", "later", "bool"], ) def test_a_record_of_another_output_schema_is_refused_by_name( envelope_grid, stepper, declared ): - # One rule for every case (ADR-058): 0.1.0 wrote schema 1 and development versions - # wrote schemas up to 28, which this release does not read, and a later release's - # file is not read either. A boolean is not an integer, whatever it equals. + # One rule for every case (ADR-058): 0.1.0 wrote schema 1, 0.2.0 schema 2 and + # development versions schemas up to 28, which this release does not read, and a + # later release's file is not read either. The refusal names the release that wrote + # a released schema. A boolean is not an integer, whatever it equals. + remedy = { + 1: r"output schema 1 is solprop 0\.1\.x's: read it with that release", + 2: r"output schema 2 is solprop 0\.2\.x's: read it with that release", + }.get( + declared if type(declared) is int else -1, + "read it with the solprop version that wrote it", + ) refusal = ( rf"schema_version {re.escape(repr(declared))}, and this release of solprop " - r"reads output schema 4 only: .*earlier release.*development version.*" + r"reads output schema 3 only: .*earlier release.*development version.*" r"later release.*" - r"solprop version that wrote it" + rf"; {remedy}$" ) with pytest.raises(OutputError, match=refusal): make_metadata(envelope_grid, stepper, schema_version=declared) @@ -1032,7 +1040,7 @@ def test_raman_tensor_identity_survives_metadata_round_trip_and_controls_resume( assert original.configuration_hash() != other.configuration_hash() with pytest.raises(OutputError, match=r"configuration\.raman"): resolve_metadata_write(restored, other) - assert original.schema_version == 4 + assert original.schema_version == 3 def test_spatial_metadata_names_its_flux_model(envelope_grid, stepper): diff --git a/tests/output/test_snapshot_failures.py b/tests/output/test_snapshot_failures.py index b6eb194a0..c50472584 100644 --- a/tests/output/test_snapshot_failures.py +++ b/tests/output/test_snapshot_failures.py @@ -21,9 +21,9 @@ from solprop.output import ( HDF5Output, _writer_lock, + read_resume_state, read_snapshot, restore_snapshot, - resume, ) from solprop.output import snapshots as module @@ -170,7 +170,7 @@ def test_checkpoint_validation_is_independent_of_checksums( generation, monkeypatch, change ): info = read_snapshot(generation) - original = resume(info.files.output) + original = read_resume_state(info.files.output) assert original.outcome is not None if change == "outcome": state = dataclasses.replace(original, outcome=None) @@ -197,7 +197,7 @@ def test_checkpoint_validation_is_independent_of_checksums( marker["next_save_index"] = -1 del file[key] file.create_dataset(key, data=json.dumps(marker)) - monkeypatch.setattr(module, "resume", lambda path: state) + monkeypatch.setattr(module, "read_resume_state", lambda path: state) records = module._file_records( json.loads((generation / "manifest.json").read_text(encoding="utf-8")) ) @@ -339,7 +339,7 @@ def test_missing_backend_history_stops_clearly(working): keeper.keep(0.125, required=True) keeper._save = lambda state: None keeper._snapshot = lambda: None - keeper._snapshot_nbytes = lambda z: None + keeper._snapshot_nbytes = lambda: None with pytest.raises(OutputError, match="accepted endpoint"): keeper.keep(0.125, required=True) # Each refusal is recorded as what was persisted there. diff --git a/tests/output/test_snapshots.py b/tests/output/test_snapshots.py index 4da05f5e5..ab059ea2c 100644 --- a/tests/output/test_snapshots.py +++ b/tests/output/test_snapshots.py @@ -14,7 +14,7 @@ import numpy as np import pytest -from solprop.exceptions import OutputError +from solprop.exceptions import OutputError, OutputRequestError from solprop.output import ( HDF5Output, RunOutcome, @@ -67,13 +67,13 @@ def generation(working): @pytest.mark.parametrize("interval", [0, -1, float("inf"), float("nan"), True]) def test_invalid_interval_is_refused(tmp_path, interval): - with pytest.raises(OutputError, match="interval"): + with pytest.raises(OutputRequestError, match="interval"): SnapshotController(tmp_path, interval_seconds=interval) @pytest.mark.parametrize("capacity", [0, -1, True, 1.5]) def test_invalid_capacity_is_refused(tmp_path, capacity): - with pytest.raises(OutputError, match="max_snapshots"): + with pytest.raises(OutputRequestError, match="max_snapshots"): inspect.unwrap(SnapshotController.__init__)( SnapshotController.__new__(SnapshotController), tmp_path, @@ -315,21 +315,25 @@ def test_reopen_requires_a_suspended_writer(working): working[0].reopen() +# Each change with the refusal of the check it breaks: read_snapshot turns every +# failure into an OutputError, so a case refused by another check would pass unmatched. @pytest.mark.parametrize( - "change", + ("change", "message"), [ - "missing", - "schema", - "checksum", - "identity", - "escape", - "roles", - "duplicate", - "object", - "files", + ("missing", r"cannot verify snapshot .*manifest\.json"), + ("schema", "unsupported snapshot manifest schema"), + ("checksum", "snapshot checksum mismatch"), + ("identity", "manifest and checkpoint identities disagree"), + ("escape", "invalid snapshot file record"), + ("roles", "roles must be optical, then optional archive"), + ("duplicate", "files must have distinct paths"), + ("object", "manifest requires an object"), + ("files", "must contain an optical file and optional archive"), ], ) -def test_read_refuses_incomplete_corrupt_and_mismatched_generations(generation, change): +def test_read_refuses_incomplete_corrupt_and_mismatched_generations( + generation, change, message +): path = generation / "manifest.json" manifest = json.loads(path.read_text(encoding="utf-8")) path.chmod(0o600) @@ -353,7 +357,7 @@ def test_read_refuses_incomplete_corrupt_and_mismatched_generations(generation, else: manifest["files"] = [] path.write_text(json.dumps(manifest), encoding="utf-8") - with pytest.raises(OutputError): + with pytest.raises(OutputError, match=message): read_snapshot(generation) @@ -379,6 +383,32 @@ def test_manifest_with_a_symlink_is_refused(generation, tmp_path): read_snapshot(generation) +def test_a_manifest_path_through_a_linked_directory_is_refused(generation, tmp_path): + """A path with no ``..`` that resolves outside its generation escapes it. + + The copy outside has the recorded size and checksum, so only the check that the + resolved path stays inside the generation refuses it. + """ + info = read_snapshot(generation) + name = info.files.output.name + outside = tmp_path / "outside" + outside.mkdir() + shutil.copyfile(info.files.output, outside / name) + generation.chmod(0o700) # published read-only + try: + (generation / "linked").symlink_to(outside, target_is_directory=True) + except OSError as error: + # Windows creates symlinks only with Developer Mode or elevation. + pytest.skip(f"this account cannot create symlinks: {error}") + path = generation / "manifest.json" + manifest = json.loads(path.read_text(encoding="utf-8")) + manifest["files"][0]["path"] = f"linked/{name}" + path.chmod(0o600) + path.write_text(json.dumps(manifest), encoding="utf-8") + with pytest.raises(OutputError, match="snapshot file escapes its generation"): + read_snapshot(generation) + + def test_restore_failure_removes_only_its_staging(generation, tmp_path, monkeypatch): def fail(*args): raise OSError("restore copy failed") diff --git a/tests/output/test_tdse_archive.py b/tests/output/test_tdse_archive.py index 189a748be..37aff2ba4 100644 --- a/tests/output/test_tdse_archive.py +++ b/tests/output/test_tdse_archive.py @@ -38,7 +38,7 @@ writer, ) -from solprop.exceptions import OutputError, TDSEArchiveError +from solprop.exceptions import OutputError, OutputRequestError, TDSEArchiveError from solprop.output import TDSEArchive, open_tdse_archive from solprop.output.tdse_archive import ( ARCHIVE_METADATA_CACHE_BYTES, @@ -73,11 +73,11 @@ def test_the_request_adopts_a_path_and_validates_its_selection(): # checks are what a production caller meets. init = inspect.unwrap(TDSEArchive.__init__) blank = object.__new__(TDSEArchive) - with pytest.raises(TypeError, match="path or a string"): + with pytest.raises(OutputRequestError, match="path or a string"): init(blank, 3) - with pytest.raises(ValueError, match="empty"): + with pytest.raises(OutputRequestError, match="empty"): TDSEArchive("") - with pytest.raises(ValueError, match="'full' or 'required'"): + with pytest.raises(OutputRequestError, match="'full' or 'required'"): init(blank, "a.h5", outputs="all") with pytest.raises(TypeError): TDSEArchive("a.h5", "full") # pyright: ignore[reportCallIssue] - keyword only diff --git a/tests/parity_ladder.py b/tests/parity_ladder.py index 41bbf43bc..05d8fd07d 100644 --- a/tests/parity_ladder.py +++ b/tests/parity_ladder.py @@ -151,7 +151,9 @@ class Row: statistic, read at the end of the row's schedule and compared absolutely, to its bound. ``switch_off`` returns the problem with the row's term off: the guard that the term moves every field rung's reference by more than :data:`DETECTION` bounds, - or by a rung's own ``detection``. ``floor`` builds a row whose own native + or by a rung's own ``detection``. It switches off every response only where the + problem holds one (:func:`responses_held`), since otherwise any one of them could + clear the guard for the term the row claims. ``floor`` builds a row whose own native disagreement at the same rung is added to the bound (a term beside the row's that is known to disagree by more than the row's own budget). ``source_z`` is where the source is evaluated, m. @@ -759,6 +761,11 @@ def _check(native_class: type, row: Row) -> list[Reading]: floor = None if row.floor is None else row.floor() scale = None if row.scale is None else row.scale(built) off = dataclasses.replace(built, problem=row.switch_off(built.problem)) + held = responses_held(built.problem) + assert responses_held(off.problem) or len(held) < 2, ( + f"the guard switches off every response, and the problem holds {held}: any " + "one of them could satisfy it, so a row switches off the response it claims" + ) field_bounds: dict[str, float] = {} observed: dict[str, tuple[Mapping[str, Any], Mapping[str, Any]]] = {} readings: list[Reading] = [] @@ -867,6 +874,22 @@ def _every_statistic( return readings +def responses_held(problem: PropagationProblem) -> tuple[str, ...]: + """Return the response leaves `problem` compiles, by name, in a fixed order. + + A leaf switched off by zeroing its coefficients is still held; one removed is not. + """ + responses = problem.responses + held = { + "kerr": responses.kerr_coefficients is not None, + "dispersive kerr": responses.dispersive_kerr is not None, + "raman": bool(responses.raman_terms), + "plasma": bool(responses.plasma_channels), + "envelope plasma": responses.envelope_plasma is not None, + } + return tuple(name for name, present in held.items() if present) + + def _check_declarations(row: Row) -> None: """Assert the row states its claim and declares its guards completely.""" assert row.why.strip(), "the row states no claim (`why`)" diff --git a/tests/physdata/test_equation_of_state.py b/tests/physdata/test_equation_of_state.py index ec5cdc820..ae833f701 100644 --- a/tests/physdata/test_equation_of_state.py +++ b/tests/physdata/test_equation_of_state.py @@ -124,21 +124,31 @@ def test_unknown_gas_is_rejected(func): func("Argon", 1.0) -@pytest.mark.parametrize( - ("func", "bad"), [(density, -1e-12), (pressure, -1.0), (ideal_gas_density, -1.0)] -) -def test_negative_argument_is_rejected(func, bad): - with pytest.raises(MaterialError, match="must not be negative"): - func(bad) if func is ideal_gas_density else func(Gas.Ar, bad) - - -@pytest.mark.parametrize("temperature", [0.0, -1.0]) -def test_non_positive_temperature_is_rejected(temperature): - with pytest.raises(MaterialError, match="temperature must be positive"): - density(Gas.Ar, 1.0, temperature) - with pytest.raises(MaterialError, match="temperature must be positive"): - pressure(Gas.Ar, 1e25, temperature) - with pytest.raises(MaterialError, match="temperature must be positive"): +@pytest.mark.parametrize("bad", [-1e-12, np.nan, np.inf, -np.inf]) +@pytest.mark.parametrize("ideal", [False, True]) +def test_a_non_finite_or_negative_state_is_rejected_on_either_path(bad, ideal): + # The ideal law would return NaN or infinity; both paths refuse alike. + with pytest.raises(MaterialError, match="pressure must be finite and non-negative"): + density(Gas.Ar, bad, ideal=ideal) + with pytest.raises( + MaterialError, match="number density must be finite and non-negative" + ): + pressure(Gas.Ar, bad * 1e37, ideal=ideal) + with pytest.raises(MaterialError, match="temperature must be finite and positive"): + density(Gas.Ar, 1.0, bad, ideal=ideal) + with pytest.raises(MaterialError, match="temperature must be finite and positive"): + pressure(Gas.Ar, 1e25, bad, ideal=ideal) + + +@pytest.mark.parametrize("bad", [-1.0, np.nan, np.inf]) +def test_ideal_gas_density_rejects_a_non_finite_or_negative_pressure(bad): + with pytest.raises(MaterialError, match="pressure must be finite and non-negative"): + ideal_gas_density(bad) + + +@pytest.mark.parametrize("temperature", [0.0, -1.0, np.nan, np.inf]) +def test_a_non_positive_or_non_finite_temperature_is_rejected(temperature): + with pytest.raises(MaterialError, match="temperature must be finite and positive"): ideal_gas_density(1.0, temperature) diff --git a/tests/physdata/test_luna_reference.py b/tests/physdata/test_luna_reference.py index db96042ca..fe11a3150 100644 --- a/tests/physdata/test_luna_reference.py +++ b/tests/physdata/test_luna_reference.py @@ -148,7 +148,7 @@ def test_helium_differs_from_luna_by_exactly_the_reference_state(): ours, _ = susceptibility(HE_ERMOLOV, omega_for(key)) theirs = stored("refractive_index", key) ** 2 - 1.0 expected = HE_ERMOLOV.reference_density / density(Gas.He, 1.0, 273.15, **REAL_GAS) - assert np.allclose(theirs / ours, expected, rtol=1e-9) + assert np.allclose(theirs / ours, expected, rtol=1e-9, atol=0.0) assert expected == pytest.approx(1.01324, rel=1e-4) @@ -167,7 +167,7 @@ def test_quanfu_he_models_differ_from_luna_by_the_missing_square(gas): theirs = stored("refractive_index", key) ratio = (theirs**2 - 1.0) / ours expected = (1.0 + published) / (published * (2.0 + published)) - assert np.allclose(ratio, expected, rtol=1e-9) + assert np.allclose(ratio, expected, rtol=1e-9, atol=0.0) assert np.all(expected > 500.0) # And the visible consequence: Luna reports a glass-like index for a gas. assert np.all(theirs > 1.4) diff --git a/tests/physdata/test_material_manifest.py b/tests/physdata/test_material_manifest.py index 0fd31ef15..3889aaecf 100644 --- a/tests/physdata/test_material_manifest.py +++ b/tests/physdata/test_material_manifest.py @@ -50,7 +50,7 @@ def manifest(**changes) -> Any: "transparency": {"largest_dropped_absorption": 1.0}, }, ), - "policies": {"electronic": "recommended", "energy_loss": "peak-weighted"}, + "policies": {"electronic": "recommended", "raman_shift": None}, "dilute_scaling": ({"label": "Ar", "relative_error": -2e-4},), "ranges": ({"material": "Ar", "outside": ["80 nm to 107.5 nm"]},), "citations": ({"object": "SellmeierGlass", "name": "x", "citation": "y"},), @@ -153,7 +153,7 @@ def test_a_solids_measured_transparency_is_recorded_but_not_hashed(): [ {"optmat_version": "0.1.2"}, {"records": (record_of(ARGON),)}, - {"policies": {"electronic": "carrier-kerr", "energy_loss": "peak-weighted"}}, + {"policies": {"electronic": "carrier-kerr", "raman_shift": None}}, {"compositions": ({"name": "dry air (N2, O2)"},)}, ], ids=["version", "identity", "policy", "composition"], diff --git a/tests/physdata/test_optmat_bridge.py b/tests/physdata/test_optmat_bridge.py index 53d8f5567..cd31c3ea7 100644 --- a/tests/physdata/test_optmat_bridge.py +++ b/tests/physdata/test_optmat_bridge.py @@ -5,9 +5,11 @@ """The optmat bridge: records, units, the warning and error policy, lazy import.""" import math +import re import subprocess import sys import warnings +from typing import cast import numpy as np import pytest @@ -17,19 +19,24 @@ from optmat.gas.models.registry import default_model, model from optmat.gas.transport import transport_model +from solprop.capabilities import species from solprop.constants import BAR, C from solprop.exceptions import ( MaterialError, MaterialRangeWarning, MaterialStatusWarning, ) -from solprop.physdata import _optmat +from solprop.nonlinear.optmat_raman import gas_raman, raman_status +from solprop.nonlinear.optmat_rates import OptmatRate +from solprop.physdata import Gas, _optmat, glass, glass_names +from solprop.physdata.glasses import OptmatGlass from solprop.physdata.selection import ( DiluteScalingCheck, MaterialRecord, MaterialSelection, _choice, ) +from solprop.physdata.species import default_species ARGON = default_model("Ar") @@ -78,8 +85,16 @@ def test_selection_defaults_and_validation(): "recommended", ) assert selection.ionisation == "recommended" - assert selection.energy_loss == "peak-weighted" assert selection.raman_shift is None + # The record holds the selection's six choices and nothing else. + assert set(selection.to_dict()) == { + "linear", + "electronic", + "raman", + "ionisation", + "carrier_wavelength", + "raman_shift", + } assert MaterialSelection(linear=" fit/Ar ").linear == "fit/Ar" assert MaterialSelection(linear=ARGON).linear is ARGON assert MaterialSelection(carrier_wavelength=800e-9).carrier_wavelength == 800e-9 @@ -92,7 +107,6 @@ def test_selection_defaults_and_validation(): ({"linear": ""}, "empty string"), ({"raman": 3}, "optmat model object, got int"), ({"electronic": "full"}, "electronic must be one of"), - ({"energy_loss": "mean"}, "energy_loss must be one of"), ({"raman_shift": "always"}, "raman_shift must be one of"), ({"carrier_wavelength": -1e-6}, "carrier_wavelength"), ({"carrier_wavelength": math.inf}, "carrier_wavelength"), @@ -267,11 +281,15 @@ def test_translated_converts_optmat_warnings(message, category, expected, match) @pytest.mark.parametrize( ("message", "expected"), [ - ("capped at the Doppler widths (TC-688)", "capped at the Doppler widths"), - ("not modelled (TC-527, TC-688)", "not modelled"), + ("capped at the Doppler widths (TC-1)", "capped at the Doppler widths"), + ("not modelled (TC-1, TC-23)", "not modelled"), ("between (TC-1) words", "between words"), + ("test it against (TC-1, TC-2).", "test it against."), + ("(a declared stopgap, TC-1)", "(a declared stopgap)"), + ("(the guide; TC-1, TC-2)", "(the guide)"), + ("(TC-1, TC-2; a source)", "(a source)"), # Parentheses that are not tracker ids stay. - ("of H2 Q (100-300 K) (TC-688)", "of H2 Q (100-300 K)"), + ("of H2 Q (100-300 K) (TC-1)", "of H2 Q (100-300 K)"), ("the HOMO (HOMO-1) orbital", "the HOMO (HOMO-1) orbital"), ("no ids here", "no ids here"), ], @@ -281,12 +299,68 @@ def test_optmat_text_drops_only_optmats_tracker_ids(message, expected): assert _optmat.optmat_text(ModelRangeWarning(message)) == expected +_REGISTER_ID = re.compile(r"[A-Z]{2,}-\d+") +"""What a development-register id looks like: ``TC-1``.""" + +_CITED_NAMES = frozenset({"CIPM-2007", "TIE-29"}) +"""Published names that look like register ids: an air standard, a Schott note.""" + + +def _default_material_reasons() -> list[str]: + """Return the status reasons of every built-in gas's and glass's default models. + + Each gas's linear, equation-of-state, transport and Kerr models, its recommended + ionisation rate (and the reason of each rate model the capabilities list), its + Raman response where optmat has one, and every glass. + """ + records: list[MaterialRecord] = [] + listed: list[str] = [] + for gas in Gas: + records.extend(default_species(gas).material_records) + if gas is not Gas.Air: + records.extend(OptmatRate(gas.value, 800e-9).material_records) + listed.extend(form.reason for form in species(gas).ionisation) + status = raman_status(gas.value) + if status in {"validated", "provisional"}: + policy = "recommended" if status == "validated" else status + selection = MaterialSelection(raman=policy) + records.extend( + gas_raman( + gas.value, selection=selection, density=2.5e25, wavelength=800e-9 + ).material_records + ) + for name in glass_names(): + try: + material = glass(name) + except MaterialError: # a uniaxial crystal names its ray + material = glass(name, axis="o") + records.extend(cast("OptmatGlass", material).material_records) + return [*(record.status_reason for record in records), *listed] + + +def test_no_default_material_passes_on_optmats_tracker_ids(): + # optmat's status reasons cite its development tracker, which a solprop user + # cannot look up (issue #166): neither a record nor a status warning keeps them. + with warnings.catch_warnings(record=True) as caught: + warnings.simplefilter("always") + with _optmat.material_context(): + reasons = _default_material_reasons() + texts = [*reasons, *(str(one.message) for one in caught)] + # Non-vacuity: the defaults have reasons, and some warn on their status. + assert len(reasons) > 50 + assert sum(bool(reason) for reason in reasons) > 20 + assert any(issubclass(one.category, MaterialStatusWarning) for one in caught) + found = {match for text in texts for match in _REGISTER_ID.findall(text)} + assert found - _CITED_NAMES == set() + assert not [text for text in texts if ".)" in text] + + def test_translated_drops_optmats_tracker_ids(): with ( pytest.warns(MaterialRangeWarning) as raised, _optmat.translated(ARGON, "polarizability", material="Ar"), ): - warnings.warn("outside (TC-688)", ModelRangeWarning, stacklevel=1) + warnings.warn("outside (TC-1)", ModelRangeWarning, stacklevel=1) (message,) = [str(w.message) for w in raised] assert message.endswith("optmat: outside") diff --git a/tests/physdata/test_optmat_transport.py b/tests/physdata/test_optmat_transport.py index 0bc5b6818..c0a38a258 100644 --- a/tests/physdata/test_optmat_transport.py +++ b/tests/physdata/test_optmat_transport.py @@ -104,7 +104,8 @@ def test_air_mass_is_the_pseudo_pure_equations_own(): throughput, pressure = 1e-6, 2.0 density = air.density(pressure, 294.0) expected = throughput * density * air.molar_mass / N_A / (pressure * 1e5) - assert mass_flow(chosen, throughput, pressure) == pytest.approx(expected, rel=1e-14) + flow = mass_flow(chosen, throughput, pressure, temperature=294.0) + assert flow == pytest.approx(expected, rel=1e-14) def test_temperature_range_is_optmats_and_refused_outside(): diff --git a/tests/physdata/test_sellmeier.py b/tests/physdata/test_sellmeier.py index af89950bc..e61f40ea0 100644 --- a/tests/physdata/test_sellmeier.py +++ b/tests/physdata/test_sellmeier.py @@ -115,10 +115,12 @@ def test_refractive_index_minus_one_avoids_the_cancellation(gas): # ~1e-4 quantity formed from a number near 1, so they agree only to ~1e-12. assert direct == pytest.approx(naive, rel=1e-11) # The direct form is the one that stays exact as the pressure falls: at 1e-6 bar - # n - 1 is ~1e-10 and the subtraction would keep about six figures. + # n - 1 is ~1e-10 and the subtraction would keep about six figures. The density + # scales the susceptibility n^2 - 1 = (n - 1)(n + 1), not n - 1, which departs from + # proportion by chi/4 (3.5e-4 for SF6 at 1 bar). tiny = float(refractive_index_minus_one(gas, omega, pressure=1e-6)) - assert tiny == pytest.approx( - direct * density(gas, 1e-6) / density(gas, 1.0), rel=1e-9 + assert tiny * (tiny + 2.0) == pytest.approx( + direct * (direct + 2.0) * density(gas, 1e-6) / density(gas, 1.0), rel=1e-13 ) diff --git a/tests/physdata/test_transport.py b/tests/physdata/test_transport.py index f34618022..099137613 100644 --- a/tests/physdata/test_transport.py +++ b/tests/physdata/test_transport.py @@ -17,7 +17,7 @@ from solprop.constants import BAR, K_B, N_A, ROOM_TEMPERATURE from solprop.exceptions import MaterialError -from solprop.physdata import Gas, IdealGas, Species, gamma, species +from solprop.physdata import Gas, IdealGas, Mixture, Species, gamma, species from solprop.physdata.transport import ( heat_capacity_ratio, mean_free_path, @@ -151,13 +151,18 @@ def test_a_custom_species_is_refused_by_name(): ("fractions", "message"), [ ({"N2": 0.5, "O2": 0.4}, "sum to one"), - ({"N2": 1.2, "O2": -0.2}, "not negative"), - ({}, "sum to one"), + # Off by more than the rounding of two entries and their sum (4 eps): the + # rule a mixture's fill applies, so a flow and a fill accept the same sets. + ({"N2": 0.5, "O2": 0.5 + 1e-13}, "sum to one"), + ({"N2": 1.2, "O2": -0.2}, "non-negative"), + ({}, "non-empty"), ], ) def test_invalid_fractions_are_refused(fractions, message): with pytest.raises(MaterialError, match=message): viscosity(fractions, 294.0) + with pytest.raises(MaterialError, match=message): + Mixture.fill(fractions, 1.0) def test_an_unknown_gas_is_refused(): @@ -178,6 +183,18 @@ def test_a_real_gas_sound_speed_of_a_mixture_is_refused(): sound_speed({"N2": 0.5, "O2": 0.5}, 1.0, 294.0) +def test_a_real_gas_sound_speed_checks_only_the_equation_of_state(): + # Methane's transport model is provisional and declared for 95 K to 600 K; its + # equation of state is declared for 90.69 K to 625 K, and is all this value uses. + # Warnings are errors in the suite, so the first call also says that none is raised. + assert sound_speed("CH4", 1.0, ROOM_TEMPERATURE) > 0.0 + assert sound_speed("CH4", 1.0, 610.0) > sound_speed("CH4", 1.0, 590.0) + with pytest.raises(MaterialError, match="equation of state"): + sound_speed("CH4", 1.0, 700.0) + with pytest.raises(MaterialError, match="temperature"): + sound_speed("CH4", 1.0, math.nan) + + def test_every_transport_function_defaults_to_room_temperature(): # One argument order with the rest of physdata: (gas, pressure, temperature), the # temperature defaulting to 293.15 K. Identical calls, so exact equality. diff --git a/tests/plotting/test_propagation.py b/tests/plotting/test_propagation.py index bf678cb73..47005fdff 100644 --- a/tests/plotting/test_propagation.py +++ b/tests/plotting/test_propagation.py @@ -6,6 +6,7 @@ import matplotlib.pyplot as plt import numpy as np import pytest +from matplotlib.collections import QuadMesh from solprop._validation import choice from solprop.constants import C @@ -140,6 +141,37 @@ def test_prop_2d_puts_the_peak_at_zero_decibels(single): assert mesh.get_clim() == (-60.0, 0.0) +CARRIER = 800e-9 +"""The example run's carrier wavelength, m.""" + + +@pytest.mark.parametrize( + ("axis", "carrier"), + [ + ("wavelength", CARRIER * 1e9), + ("f", C / CARRIER * 1e-15), + ("omega", 2.0 * np.pi * C / CARRIER * 1e-15), + ], +) +def test_prop_2d_draws_the_light_where_its_spectrum_is(single, axis, carrier): + ax = propagation.prop_2d(single, axis)[0].axes[0] + mesh = ax.collections[0] + assert isinstance(mesh, QuadMesh) + edges = np.asarray(mesh.get_coordinates())[0, :, 0] + centres = 0.5 * (edges[:-1] + edges[1:]) + decibels = np.asarray(mesh.get_array()).reshape(-1, centres.size) + spacing = float(np.max(np.abs(np.diff(centres)))) + low, high = ax.get_xlim() + # The carrier sits far from the middle of the drawn band, so a map drawn + # mirrored would put the light at low + high - carrier, tens of bins away. + assert low < carrier < high + assert abs(low + high - 2.0 * carrier) > 10.0 * spacing + # Pure dispersion leaves the spectrum as launched: on every plane the brightest + # bin is the carrier's, to within the coarsest bin of the axis. + brightest = centres[np.argmax(decibels, axis=1)] + assert np.all(np.abs(brightest - carrier) <= spacing) + + def test_prop_2d_honours_the_decibel_floor(single): figures = propagation.prop_2d(single, db_min=-30.0) assert figures[0].axes[0].collections[0].get_clim() == (-30.0, 0.0) @@ -299,6 +331,19 @@ def test_energy_draws_a_conversion_efficiency_axis(single): assert values[-1] == pytest.approx(values[0], rel=1e-9) +def test_energy_draws_the_run_s_energy_in_microjoules(single): + figure = propagation.plot_energy(single) + left, right = figure.axes + z, values = (np.asarray(data, dtype=float) for data in left.lines[0].get_data()) + assert left.get_ylabel() == "Energy (uJ)" + assert np.array_equal(z, single["z"] * 100.0) # cm, a plain scaling + # The example launches 1 uJ and only disperses it, so every plane holds 1 uJ: a + # sum over a few hundred bins, read back to a few eps (2e-16 measured). + np.testing.assert_allclose(values, 1.0, rtol=1e-12, atol=0.0) + # And 1 uJ on the left is 100 % on the right. + assert right.get_ylim()[1] / left.get_ylim()[1] == pytest.approx(100.0, rel=1e-9) + + def test_energy_scales_the_efficiency_by_the_input(single): figure = propagation.plot_energy(single) left, right = figure.axes @@ -331,6 +376,27 @@ def test_a_scalar_position_and_a_sequence_agree(single): assert propagation._plane_indices(single, None) == [single.n_saved - 1] +@pytest.mark.parametrize("plot", ["time_1d", "spec_1d"]) +def test_a_slice_selects_planes_by_index_as_by_position(single, plot): + draw = getattr(propagation, plot) + by_index = draw(single, plane=[0, -1]).axes[0].lines + by_position = draw(single, [0.0, 0.1]).axes[0].lines + assert [line.get_label() for line in by_index] == [ + line.get_label() for line in by_position + ] + for one, other in zip(by_index, by_position, strict=True): + # The same plane read twice; a logarithmic slice masks its zeros as NaN. + drawn = np.asarray(one.get_ydata()) + assert np.array_equal(drawn, np.asarray(other.get_ydata()), equal_nan=True) + assert len(draw(single, plane=2).axes[0].lines) == 1 + + +@pytest.mark.parametrize("plot", ["time_1d", "spec_1d"]) +def test_a_slice_refuses_a_plane_and_a_position_together(single, plot): + with pytest.raises(ProcessingError, match="not both"): + getattr(propagation, plot)(single, 0.05, plane=2) + + def test_a_two_mode_run_labels_its_sum(): output = example_output(n_modes=2) assert propagation._drawn_labels(output, 2, None) == ["mode 1", "mode 2"] diff --git a/tests/plotting/test_spectrograms.py b/tests/plotting/test_spectrograms.py index 26f1ea1db..3d49ac630 100644 --- a/tests/plotting/test_spectrograms.py +++ b/tests/plotting/test_spectrograms.py @@ -98,6 +98,20 @@ def test_a_spectrogram_defaults_to_the_end_of_the_run(single): assert np.array_equal(np.asarray(end), np.asarray(last)) +def test_a_spectrogram_selects_a_plane_by_index_as_by_position(single): + by_index = spectrogram(single, plane=2).axes[0].collections[0].get_array() + by_position = spectrogram(single, 0.05).axes[0].collections[0].get_array() + assert np.array_equal(np.asarray(by_index), np.asarray(by_position)) + first = spectrogram(single, plane=0).axes[0].collections[0].get_array() + # A different plane draws a different map, so the index is not ignored. + assert not np.array_equal(np.asarray(first), np.asarray(by_index)) + + +def test_a_spectrogram_refuses_a_plane_and_a_position_together(single): + with pytest.raises(ProcessingError, match="not both"): + spectrogram(single, 0.05, plane=2) + + def test_a_spectrogram_draws_into_a_given_axis(single): figure, ax = plt.subplots() assert spectrogram(single, 0.0, ax=ax) is figure diff --git a/tests/processing/test_axes.py b/tests/processing/test_axes.py index cce608357..dd02a1026 100644 --- a/tests/processing/test_axes.py +++ b/tests/processing/test_axes.py @@ -94,12 +94,12 @@ def test_spectral_axis_carries_the_jacobian_of_each_abscissa(): assert np.array_equal(x, omega) assert np.array_equal(jacobian, np.ones_like(omega)) x, jacobian = axes.spectral_axis(omega, "f") - assert np.allclose(x, omega / (2 * np.pi), rtol=1e-15) - assert np.allclose(jacobian, 2 * np.pi, rtol=1e-15) + assert np.allclose(x, omega / (2 * np.pi), rtol=1e-15, atol=0.0) + assert np.allclose(jacobian, 2 * np.pi, rtol=1e-15, atol=0.0) x, jacobian = axes.spectral_axis(omega, "wavelength") # The wavelength Jacobian is 2 pi c / lambda^2, which is omega^2 / (2 pi c); the two # forms agree to round-off, which is what this checks. - assert np.allclose(jacobian, 2 * np.pi * 299792458.0 / x**2, rtol=1e-14) + assert np.allclose(jacobian, 2 * np.pi * 299792458.0 / x**2, rtol=1e-14, atol=0.0) def test_spectral_axis_refuses_a_wavelength_at_zero_frequency(): diff --git a/tests/processing/test_coherence.py b/tests/processing/test_coherence.py index 34fbac6f2..047e6796a 100644 --- a/tests/processing/test_coherence.py +++ b/tests/processing/test_coherence.py @@ -31,7 +31,7 @@ def test_two_known_realisations_match_the_definition(): # With two realisations the definition is |2 Re(E1* E2)| / (|E1|^2 + |E2|^2), which # is 1 where they agree and 1 where they are exactly out of phase: the modulus of # the cross term, not its sign, is what g12 reports. - assert np.allclose(coherence.g12(np.stack([first, second])), [1.0, 1.0]) + assert np.allclose(coherence.g12(np.stack([first, second])), [1.0, 1.0], atol=0.0) third = np.array([1.0 + 0.0j, 1.0j]) # Orthogonal phasors have no cross term at all. assert coherence.g12(np.stack([first, third]))[1] == pytest.approx(0.0, abs=1e-15) diff --git a/tests/processing/test_compression.py b/tests/processing/test_compression.py index 77da5c914..7e9de4def 100644 --- a/tests/processing/test_compression.py +++ b/tests/processing/test_compression.py @@ -15,7 +15,7 @@ from solprop import fourier from solprop.constants import C -from solprop.exceptions import ProcessingError +from solprop.exceptions import ModeError, ProcessingError from solprop.optics import ChirpedMirror, Material, TaylorPhase, stored_factor from solprop.output import MemoryOutput from solprop.physdata import calcium_fluoride @@ -193,9 +193,12 @@ def test_a_multimode_output_is_compressed_on_its_summed_power(): # the chirp found is the same and the summed power grows with every mode added. assert together.coefficients[2] == pytest.approx(alone.coefficients[2], rel=1e-6) assert alone.peak_power_limit < pair.peak_power_limit < together.peak_power_limit - with pytest.raises(ProcessingError, match="does not select"): + # As every processing reader refuses a mode the run does not have. + with pytest.raises(ModeError, match="mode 5 is out of range for a run of 3"): compression.compress_taylor(run, modes=5) - with pytest.raises(ProcessingError, match="does not select"): + with pytest.raises(ModeError, match="mode -4 is out of range for a run of 3"): + compression.compress_taylor(run, modes=[0, -4]) + with pytest.raises(ModeError, match="selects no mode"): compression.compress_taylor(run, modes=[]) diff --git a/tests/processing/test_fields.py b/tests/processing/test_fields.py index aedcb2f67..4495ee148 100644 --- a/tests/processing/test_fields.py +++ b/tests/processing/test_fields.py @@ -7,6 +7,7 @@ from solprop import fourier, stats from solprop._validation import choice +from solprop.constants import C from solprop.exceptions import ModeError, OutputError, ProcessingError from solprop.output import MemoryOutput from solprop.processing import axes, fields @@ -57,13 +58,16 @@ def test_the_convention_switch_is_the_exact_conjugation(output, grid): @pytest.mark.parametrize("axis", ["omega", "f", "wavelength"]) def test_the_spectral_density_integrates_to_the_energy(output, grid, axis): - _, density = fields.get_spectral_density(output, axis, plane=0, modes="sum") - omega = grid.omega[axes._keep_index(grid, "active")] - _, jacobian = axes.spectral_axis(omega, axis) - weights = grid.d_omega / jacobian - if axis == "wavelength": - weights = weights[::-1] - total = float(np.sum(density * weights)) + x, density = fields.get_spectral_density(output, axis, plane=0, modes="sum") + # Each bin's width on the returned abscissa, derived here rather than taken from + # the accessor's own Jacobian: d omega, d omega / (2 pi), and |d lambda| = + # lambda^2 d omega / (2 pi c) at the bin's own wavelength. + widths = { + "omega": np.full_like(x, grid.d_omega), + "f": np.full_like(x, grid.d_omega / (2.0 * np.pi)), + "wavelength": x**2 * grid.d_omega / (2.0 * np.pi * C), + }[axis] + total = float(np.sum(density * widths)) expected = float(np.sum(stats.energy(grid, output.fields("fft")[0]))) # The change of variable is exact bin by bin, so the only differences are the energy # outside the active band, which the collar has driven to zero, and the order of the @@ -167,7 +171,7 @@ def test_a_modal_sum_adds_the_densities(synthetic): output = synthetic.build_run("envelope", n_modes=2) _, each = fields.get_spectral_density(output, "omega", plane=0) _, total = fields.get_spectral_density(output, "omega", plane=0, modes="sum") - assert np.allclose(total, each.sum(axis=0), rtol=1e-15) + assert np.allclose(total, each.sum(axis=0), rtol=1e-15, atol=0.0) def test_the_real_field_is_the_real_part_of_the_analytic_signal(output): @@ -182,20 +186,26 @@ def test_the_envelope_is_the_analytic_signal_without_its_carrier(output, grid): t, analytic = fields.get_field(output, plane=0, kind="analytic") _, envelope = fields.get_field(output, plane=0, kind="envelope") # In the optics convention the carrier is exp(+i omega0 t) (conventions.md 2). - assert np.allclose(envelope, analytic * np.exp(1j * grid.omega0 * t), rtol=1e-12) + assert np.allclose( + envelope, analytic * np.exp(1j * grid.omega0 * t), rtol=1e-12, atol=0.0 + ) def test_the_power_is_the_modulus_squared_of_the_analytic_signal(output): _, analytic = fields.get_field(output, plane=0, kind="analytic") _, power = fields.get_power(output, plane=0) - assert np.allclose(power, np.abs(analytic) ** 2, rtol=1e-14) + assert np.allclose(power, np.abs(analytic) ** 2, rtol=1e-14, atol=0.0) def test_oversampling_refines_the_axis_and_keeps_the_energy(output, grid): t_one, power_one = fields.get_power(output, plane=0) t_four, power_four = fields.get_power(output, plane=0, oversampling=4) assert t_four.size == 4 * t_one.size - assert np.isclose(t_four[1] - t_four[0], (t_one[1] - t_one[0]) / 4, rtol=1e-14) + # Differences of axis values about a thousand spacings from zero keep their + # rounding, |t| / dt eps ~ 2e-13 of the spacing (measured 1.1e-13). + assert np.isclose( + t_four[1] - t_four[0], (t_one[1] - t_one[0]) / 4, rtol=1e-12, atol=0.0 + ) energy_one = float(np.sum(power_one)) * float(t_one[1] - t_one[0]) energy_four = float(np.sum(power_four)) * float(t_four[1] - t_four[0]) # Zero-padding in frequency is exact interpolation of a band-limited trace, so the @@ -283,8 +293,8 @@ def test_a_spectrogram_on_wavelength_is_a_density_per_metre(output): by_lam = np.trapezoid(per_m, lam, axis=0) by_omega = np.trapezoid(per_rad, omega, axis=0) bright = by_f > 1e-3 * by_f.max() - assert np.allclose(by_lam[bright], by_f[bright], rtol=2e-2) - assert np.allclose(by_omega, by_f, rtol=1e-9) + assert np.allclose(by_lam[bright], by_f[bright], rtol=2e-2, atol=0.0) + assert np.allclose(by_omega, by_f, rtol=1e-9, atol=0.0) def test_a_spectrogram_takes_a_time_range_a_gate_and_a_band(output): @@ -300,6 +310,30 @@ def test_a_spectrogram_takes_a_time_range_a_gate_and_a_band(output): assert values.max() > 0.0 +def test_the_default_gate_is_a_twentieth_of_the_range_within_the_window(): + t = np.linspace(-1e-12, 1e-12, 401) + # Each a twentieth of the range clipped to the window: exact up to one rounding + # of the span's subtraction and division. + assert fields.default_gate_fwhm(t) == pytest.approx(1e-13, rel=1e-15) + assert fields.default_gate_fwhm(t, (-1e-9, 1e-9)) == pytest.approx(1e-13, rel=1e-15) + assert fields.default_gate_fwhm(t, (4e-13, 0.0)) == pytest.approx(2e-14, rel=1e-15) + with pytest.raises(ProcessingError, match="holds no gate position"): + fields.default_gate_fwhm(t, (2e-12, 3e-12)) + # The spectrogram's own default is that gate. + field = np.cos(2.4e15 * t) * np.exp(-((t / 3e-14) ** 2)) + wide = (-1e-9, 1e-9) + by_default = fields.field_spectrogram(t, field, time_range=wide, positions=16) + given = fields.field_spectrogram( + t, + field, + time_range=wide, + gate_fwhm=fields.default_gate_fwhm(t, wide), + positions=16, + ) + assert by_default[2].max() > 0.0 + assert np.array_equal(by_default[2], given[2]) # the same computation, bit for bit + + def test_a_spectrogram_refuses_what_it_cannot_draw(output, synthetic): multimode = synthetic.build_run(n_modes=2) with pytest.raises(ModeError, match="name a single mode"): diff --git a/tests/processing/test_mixtures.py b/tests/processing/test_mixtures.py index 6348e5956..23dfeaf59 100644 --- a/tests/processing/test_mixtures.py +++ b/tests/processing/test_mixtures.py @@ -201,7 +201,7 @@ def test_saved_record_contains_ordered_species_and_complete_optics(case, outputs simulation, _ = case memory, reloaded = outputs for output in (memory, reloaded): - assert output.metadata.schema_version == 4 + assert output.metadata.schema_version == 3 material = output.metadata.configuration["medium"] assert material["labels"] == ["population-0", "population-1"] assert ( diff --git a/tests/processing/test_modal_metrics.py b/tests/processing/test_modal_metrics.py index 0483b05ab..0c739e614 100644 --- a/tests/processing/test_modal_metrics.py +++ b/tests/processing/test_modal_metrics.py @@ -183,7 +183,7 @@ def test_the_reconstruction_carries_si_units_and_three_components( def test_the_coefficient_dual_recovers_the_amplitudes_it_synthesised( run, tables, grid, record_property ): - """The round trip of A2 companion section 4, to the rounding budget above.""" + """The coefficient dual inverts the synthesis, to the rounding budget above.""" stored = np.sum(run.fields("fft")[-1], axis=1) reference = tables.electric[0] magnetic = tables.magnetic[0] @@ -267,7 +267,7 @@ def _cross_frequency_bound(run, tables): def test_the_reconstructed_peak_is_the_statistic_plus_the_cross_frequency_term( run, tables, guide, record_property ): - """The distinction A2 companion section 6 insists on, measured. + """Same-frequency flux against the physical cross-section flux, measured. The run statistic ``analytic_flux`` is the peak of the **same-frequency** diagonal, which is what a modal state can say on its own; the reconstruction @@ -372,10 +372,9 @@ def test_the_instantaneous_flux_averages_to_the_analytic_one( def test_a_coordinate_intensity_is_not_the_physical_one(pair_guide, grid): """Two channels launched together interfere, and coordinate powers do not add. - The distinction A2 companion section 6 insists on: the sum over channels of - the per-coordinate flux densities is the physical density only where the - channels do not interfere. Here they do, at the same nodes, so the difference - is a measurable fraction of the total and is **not** clipped away. + The sum over channels of the per-coordinate flux densities is the physical + density only where the channels do not interfere. Here they do, at the same nodes, + so the difference is a measurable fraction of the total and is **not** clipped away. """ route = route_for(pair_guide, grid) simulation = Simulation.from_waveguide( @@ -456,7 +455,7 @@ def test_a_record_built_without_labels_says_so(): def test_an_ordinary_run_is_refused_every_general_accessor(tables, guide): - """The reviewer's trap: an old file asked for a reconstruction.""" + """A file of a run on no general guide is refused every reconstruction.""" ordinary = example_output() for accessor in ( electric_field, @@ -756,7 +755,7 @@ def test_a_gas_or_spatial_name_is_refused_for_its_own_reason(name): A plasma density, a gas pressure and a beam radius are unavailable on a guide because it has no fill and no transverse grid, not because its coordinate powers do not add up. The gate names that reason and offers no replacement from the - flux family (A2 companion section 6). + flux family. """ message = refusal_for("general_modal", [name]) assert message is not None diff --git a/tests/processing/test_scan_reductions.py b/tests/processing/test_scan_reductions.py index 7b9ac77b9..863231bdd 100644 --- a/tests/processing/test_scan_reductions.py +++ b/tests/processing/test_scan_reductions.py @@ -20,6 +20,7 @@ from solprop.output.metadata import _example_metadata from solprop.output.records import GridRecord, SavedPlane from solprop.output.scan import PointResult, ScanWriter +from solprop.output.store import FieldRetention from solprop.processing import scans from solprop.processing.axes import grid_from_record from solprop.processing.fields import get_spectral_density @@ -57,6 +58,26 @@ def test_spatial_reductions_retain_existing_statistics(): np.testing.assert_array_equal(value, output[f"stats/{reducer.name}"][-1]) +def test_field_reduction_reads_a_run_that_kept_its_field_on_some_planes(): + metadata = _example_metadata() + shape = (1, 1, grid_from_record(metadata.grid).n_omega) + rng = np.random.default_rng(3) + first, kept = (rng.standard_normal(shape) + 0j for _ in range(2)) + with MemoryOutput() as full, MemoryOutput() as output: + full.open(metadata) + full.save(SavedPlane(z=0.0, field=first)) + full.save(SavedPlane(z=0.1, field=kept)) + output.open(metadata) + output.retain(FieldRetention("planes", (1,)), shape) + output.save(SavedPlane(z=0.0, field=None)) + output.save(SavedPlane(z=0.1, field=kept)) + # The same plane stored the same way: equality is the contract. + expected = full.fields()[1] + assert np.max(np.abs(expected)) > 0.0 + np.testing.assert_array_equal(scans.field_at_plane(1)(output), expected) + np.testing.assert_array_equal(scans.field_at_plane()(output), expected) + + @pytest.mark.parametrize( "factory, bounds", [ diff --git a/tests/processing/test_spectra.py b/tests/processing/test_spectra.py index 5be2029f2..c4d119a50 100644 --- a/tests/processing/test_spectra.py +++ b/tests/processing/test_spectra.py @@ -11,6 +11,7 @@ from solprop.grid import EnvelopeGrid from solprop.processing import spectra from solprop.processing._examples import example_output +from solprop.processing.axes import grid_of from solprop.processing.time import energy @@ -180,6 +181,33 @@ def test_an_accessor_takes_a_passband(): assert 0.0 < red < total +def test_a_passband_keeps_the_energy_of_its_own_side(): + # A band on the red side of the example's 800 nm spectrum, off its centre, with + # the default edges. Its window is zero beyond an edge's width outside the band, so + # a window on the wrong side fails; and the band's share of the energy is the + # window-squared share of |E|^2 (Parseval, on an envelope grid), summed here + # directly, so a window applied twice fails in the tapers. The two sides differ by + # the round-off of the reductions. + output = example_output() + grid = grid_of(output) + limits = (C / 850e-9, C / 810e-9) + low, high = 2.0 * np.pi * limits[0], 2.0 * np.pi * limits[1] + edge = min(spectra.DEFAULT_BANDPASS_BINS * grid.d_omega, 0.25 * (high - low)) + window = spectra.bandpass(grid, limits, axis="f") + outside = (grid.omega < low - edge) | (grid.omega > high + edge) + assert np.all(window[outside] == 0.0) + assert float(window.max()) == 1.0 + spectrum = np.abs(output.fields("fft")[0, 0, 0]) ** 2 + share = float(np.sum(window**2 * spectrum) / np.sum(spectrum)) + band = spectra.Passband(limits, "f") + inside = float(energy(output, plane=0, bandpass=band)) + total = float(energy(output, plane=0)) + assert inside / total == pytest.approx(share, rel=1e-13) + tapered = (window > 0.0) & (window < 1.0) + in_tapers = float(np.sum(window[tapered] ** 2 * spectrum[tapered])) + assert in_tapers > 0.1 * share * float(np.sum(spectrum)) + + def test_specres_preserves_the_integral(): x = np.linspace(400e-9, 1200e-9, 4001) density = gaussian(x, 800e-9, 20e-9) @@ -211,7 +239,9 @@ def test_specres_accepts_an_explicit_measure(): given_x, given_smooth = spectra.specres(x, density, 60e-9, weights=weights) # On a uniform axis the central differences are the spacing, so the two agree. assert np.array_equal(default_x, given_x) - assert np.allclose(default_smooth, given_smooth, rtol=1e-14) + # To the spacings' own rounding: linspace's differ by 5e-13 of their mean here + # (measured 7e-14 apart, the far tails included). + assert np.allclose(default_smooth, given_smooth, rtol=1e-12, atol=0.0) def test_specres_smooths_every_trace_of_a_stack(): diff --git a/tests/processing/test_time.py b/tests/processing/test_time.py index 583b15044..6bab0c6b1 100644 --- a/tests/processing/test_time.py +++ b/tests/processing/test_time.py @@ -101,12 +101,12 @@ def test_the_duration_follows_the_dispersion_law(output, synthetic): # The closed form of a Gaussian under pure group-velocity dispersion; the sampled # trace resolves the width with dt/tau of a few per cent, so the crossing is found # to second order in that. - assert np.allclose(widths, expected, rtol=2e-3) + assert np.allclose(widths, expected, rtol=2e-3, atol=0.0) def test_energy_is_conserved_by_pure_dispersion(output): values = time.energy(output) - assert np.allclose(values, values[0], rtol=1e-12) + assert np.allclose(values, values[0], rtol=1e-12, atol=0.0) def test_the_peak_power_falls_as_the_pulse_broadens(output): @@ -130,6 +130,25 @@ def test_a_bandpass_reduces_the_energy(output, grid): assert 0.1 * total < inside < 0.9 * total +def test_a_bandpass_weights_each_bin_s_energy_by_the_window_squared(output, grid): + # An off-centre band on the 800 nm pulse's red side, with the default edges, so a + # good part of the band's energy sits in the tapers. The window multiplies the + # field and the energy is a fixed multiple of the summed |E|^2 (Parseval; the + # zero-frequency and Nyquist bins it weights apart on a field grid hold nothing of + # this pulse), so the band's share of the energy is the window-squared share of + # |E|^2, summed here directly. A window applied twice, or on the wrong side, + # misses by far more than the round-off of the two reductions. + window = spectra.bandpass(grid, (810e-9, 850e-9)) + spectrum = np.abs(output.fields("fft")[0, 0, 0]) ** 2 + share = float(np.sum(window**2 * spectrum) / np.sum(spectrum)) + total = float(time.energy(output, plane=0)) + inside = float(time.energy(output, plane=0, bandpass=window)) + assert inside / total == pytest.approx(share, rel=1e-13) + tapered = (window > 0.0) & (window < 1.0) + in_tapers = float(np.sum(window[tapered] ** 2 * spectrum[tapered])) + assert in_tapers > 0.1 * share * float(np.sum(spectrum)) + + def test_a_bandpass_window_must_fit_the_grid(output, grid): with pytest.raises(ProcessingError, match="one value per stored bin"): time.energy(output, plane=0, bandpass=np.ones(3)) @@ -196,9 +215,10 @@ def test_the_intensity_autocorrelation_of_a_gaussian_is_wider_by_root_two(output def test_the_coherence_time_of_a_gaussian_spectrum(output, synthetic): measured = float(time.coherence_time(output, plane=0)) - # For a transform-limited Gaussian the field autocorrelation has the width of the - # pulse, so its squared modulus is narrower by sqrt(2). - assert measured == pytest.approx(synthetic.fwhm / np.sqrt(2), rel=5e-3) + # For a transform-limited Gaussian of intensity FWHM tau the field autocorrelation + # is exp(-ln 2 d^2 / tau^2), of FWHM 2 tau, so its squared modulus has FWHM + # sqrt(2) tau. + assert measured == pytest.approx(synthetic.fwhm * np.sqrt(2), rel=5e-3) @pytest.mark.parametrize( diff --git a/tests/recipe/test_metadata.py b/tests/recipe/test_metadata.py index c0f04dec9..4eedacb99 100644 --- a/tests/recipe/test_metadata.py +++ b/tests/recipe/test_metadata.py @@ -193,7 +193,8 @@ def test_the_capillary_s_rules_follow_the_envelope_and_the_tdse(): assert _resolve(table, "thg", {}).value is True assert _resolve(table, "plasma", {"envelope": True}).value is False assert _resolve(table, "step_planes", {"tdse": object()}).value == 1 - assert _resolve(table, "pressure", {}).value == 1.0 + # A gas fill needs its pressure, so no rule supplies one. + assert table["pressure"].resolver is None assert _resolve(table, "dz_max", {"length": 0.4}).value == 0.2 assert _resolve(table, "dz_init", {}).value is None assert _resolve(table, "raman", {}).value is None diff --git a/tests/recipe/test_preview.py b/tests/recipe/test_preview.py index ba9504c2b..fd6f87bad 100644 --- a/tests/recipe/test_preview.py +++ b/tests/recipe/test_preview.py @@ -13,6 +13,7 @@ from solprop.modes.base import beta1, beta2, beta3, zdw from solprop.recipe import Recipe, RecipeError from solprop.recipe.preview import _phase_matching, _pump +from solprop.stats.evaluation import _zdw_or_nan from solprop.tools import ( lambda_rdw_all, nonlinear_coefficient, @@ -150,6 +151,56 @@ def test_a_mode_without_a_zero_in_the_band_has_none(): assert preview.modes[0].zdw is None +def _krypton_capillary(): + """A krypton capillary whose band reaches its own zero at 108.9 nm.""" + document = Recipe.example("rdw").to_dict() + document["build"].update( + radius="14 um", + gas="Kr", + pressure="15 bar", + wavelength_limits=["100 nm", "2000 nm"], + modes=1, + ) + return document + + +def _silica_strand(): + """A 0.6 um silica strand in air, with zeros at 588.3 and 1496.9 nm in band.""" + document = Recipe.example("step_index_fibre").to_dict() + document["build"].update( + fibre={ + "type": "StepIndexMode", + "radius": "0.6 um", + "profile_wavelength": "800 nm", + }, + wavelength="800 nm", + wavelength_limits=["450 nm", "1600 nm"], + trange="0.5 ps", + ) + return document + + +@pytest.mark.parametrize( + "document", + [ + pytest.param(_krypton_capillary, marks=pytest.mark.medium), + # A step-index fibre is solved point by point: a minute under the type hooks. + pytest.param(_silica_strand, marks=pytest.mark.slow), + ], +) +def test_the_mode_preview_shows_the_zero_the_statistic_records(document): + """Of several zeros in the band, the one nearest the reference, as a run records.""" + recipe = Recipe.from_dict(document()) + preview = recipe.modes() + simulation = recipe.build() + recorded = _zdw_or_nan(list(simulation.modes), 0.0, simulation.grid) + assert preview.modes[0].zdw is not None + # The preview's window ends at the outermost in-band bins, the statistic's at the + # band's limits: other brackets, each stopping on the noise of the differenced + # beta2 (5e-9, BETA2_RELATIVE_STEP). + assert preview.modes[0].zdw == pytest.approx(recorded[0], rel=1e-8) + + def test_each_mode_is_phase_matched_to_the_launch_soliton(): recipe = Recipe.example("rdw") preview = recipe.modes() diff --git a/tests/recipe/test_recipe.py b/tests/recipe/test_recipe.py index 9220e8460..a9125b98a 100644 --- a/tests/recipe/test_recipe.py +++ b/tests/recipe/test_recipe.py @@ -243,8 +243,8 @@ def test_a_registered_object_is_built_from_its_table(): { "type": "PressureGradient.two_point", "length": "1 m", - "start_bar": 1.2, - "end_bar": "0 bar", + "start_pressure": 1.2, + "end_pressure": "0 bar", }, "PressureGradient", ), @@ -628,7 +628,9 @@ def test_the_command_line_checks_exports_and_runs(tmp_path, capsys): path.write_text(GNLSE) assert main(["check", str(path)]) == 0 assert "builds" in capsys.readouterr().out - assert main(["export", str(path), "--python"]) == 0 + assert main(["export", str(path)]) == 0 + assert "prop_gnlse(" in capsys.readouterr().out + assert main(["export", str(path), "--form", "python"]) == 0 assert "prop_gnlse(" in capsys.readouterr().out assert ( main(["run", str(path), "-o", str(tmp_path / "out.h5"), "--progress", "none"]) @@ -649,6 +651,17 @@ def test_the_command_line_forwards_scan(monkeypatch): assert calls == [["script.py", "--local"]] +def test_a_failed_scan_command_reports_one_line_and_exits_two(tmp_path, capsys): + # As every other command does: no traceback, the message and exit status 2. + missing = tmp_path / "missing.py" + assert main(["scan", str(missing), "--local"]) == 2 + error = capsys.readouterr().err + assert error.startswith("solprop: ") + # The message quotes the path as the operating system reports it. + assert missing.name in error + assert "Traceback" not in error + + def test_a_mode_takes_its_geometry_and_not_the_fill_the_route_sets(): with pytest.raises(RecipeError, match="expected one of") as caught: build_object( diff --git a/tests/recipe/test_recipe_scan.py b/tests/recipe/test_recipe_scan.py index 5a0b980ab..1bc31eaa3 100644 --- a/tests/recipe/test_recipe_scan.py +++ b/tests/recipe/test_recipe_scan.py @@ -92,7 +92,9 @@ def test_a_range_is_spaced_as_asked(spacing, expected): }, } ).scan() - assert np.allclose(scan.scan.variables["peak_power"], expected, rtol=1e-15) + assert np.allclose( + scan.scan.variables["peak_power"], expected, rtol=1e-15, atol=0.0 + ) def test_a_scan_without_a_name_or_table_or_with_a_wrong_path_is_refused(): diff --git a/tests/recipe/test_resume_file.py b/tests/recipe/test_resume_file.py index 566914995..ada0f2d05 100644 --- a/tests/recipe/test_resume_file.py +++ b/tests/recipe/test_resume_file.py @@ -161,14 +161,20 @@ def failed(*args, **kwargs): assert not resumable_module._writer_alive(directory / "file.h5") -def test_a_file_of_another_schema_is_named(tmp_path): +@pytest.mark.parametrize("declared", [1, 2], ids=["0.1.0", "0.2.0"]) +def test_a_file_of_another_schema_is_named(tmp_path, declared): + # A file 0.1.0 or 0.2.0 wrote is not resumed, and the answer names its release. path = tmp_path / "old.h5" _stopped(path) with h5py.File(path, "r+") as file: - file.attrs["schema_version"] = 1 + file.attrs["schema_version"] = declared answer = resumability(path) assert not answer.resumable - assert answer.reason is not None and "output schema 1" in answer.reason + assert answer.reason == ( + f"the file is of output schema {declared}, and this solprop reads 3 only; " + f"output schema {declared} is solprop 0.{declared}.x's: read it with that " + "release" + ) def test_a_failure_before_any_plane_leaves_nothing_to_continue(tmp_path): @@ -250,14 +256,14 @@ def test_a_last_plane_without_a_field_and_no_checkpoint_cannot_continue( ): path = tmp_path / "fieldless.h5" _stopped(path) - original = resumable_module.resume + original = resumable_module.read_resume_state def fieldless(where): state = original(where) plane = dataclasses.replace(state.plane, field=None, noise_phase=None) return dataclasses.replace(state, plane=plane, checkpoint=None) - monkeypatch.setattr(resumable_module, "resume", fieldless) + monkeypatch.setattr(resumable_module, "read_resume_state", fieldless) answer = resumability(path) assert not answer.resumable assert answer.reason == ( diff --git a/tests/record_numbers.py b/tests/record_numbers.py index 816e3f080..94e42bf04 100644 --- a/tests/record_numbers.py +++ b/tests/record_numbers.py @@ -15,7 +15,6 @@ import hashlib import json from pathlib import Path -from typing import cast import numpy as np @@ -106,92 +105,3 @@ def assert_record_numbers(numbers, floors, stored: Path) -> None: limit = RECORD_RTOL * np.abs(expected[finite]) + floors[finite] outside = np.abs(numbers[finite] - expected[finite]) > limit assert not outside.any(), f"{int(outside.sum())} numbers outside their bound" - - -def without_sep21_absorber( - record: dict, *, bare: bool = False, spatial: bool = False -) -> dict: - """Return a hashed record as it was before SEP 21 recorded its absorber. - - SEP 21 records ``Absorber.spatial``, and a later change ``Absorber.user_rate``; the - projection drops both. A run that declared - no absorber recorded ``None`` before and now records the bare boundaries that stand - for it (``tests/legacy_geometry.py``); with `bare` the projection restores ``None``. - A spatial run that named no collar scheme now records ``"split_step"``, its route's - default; with `spatial` the projection restores the former ``"nonlinear"``. - - Parameters - ---------- - record : dict - A record from ``RunMetadata.hashed``. - bare : bool, optional - Whether the run's absorber stands for the former ``None``. - spatial : bool, optional - Whether the run is a spatial one that named no collar scheme. - - Returns - ------- - dict - The projected record; `record` is not modified. - """ - configuration = dict(record["configuration"]) - collar = configuration.get("absorber") - if bare: - configuration["absorber"] = None - elif isinstance(collar, dict): - configuration["absorber"] = { - key: value - for key, value in collar.items() - if key not in ("spatial", "user_rate") - } - if spatial and configuration.get("absorber_scheme") == "split_step": - configuration["absorber_scheme"] = "nonlinear" - return {**record, "configuration": configuration} - - -def with_former_names(value: object) -> object: - """Return a record with the names that later renames changed restored. - - A reference state's ``pressure`` was ``pressure_bar``, and a hollow mode's - ``alpha`` and ``loss_scale`` were one ``loss``: the model's own loss, which these - records' modes declare, was ``loss=True``. A recorded pulse's Taylor coefficients, - ``phases``, were its ``phase``. - - Parameters - ---------- - value : object - A record, or any part of one, as JSON-like values. - - Returns - ------- - object - The projected record; `value` is not modified. - """ - if isinstance(value, list): - return [with_former_names(item) for item in value] - if not isinstance(value, dict): - return value - if "alpha" in value and "loss_scale" in value: - assert value["alpha"] is None and value["loss_scale"] == 1.0 - value = { - key: child - for key, child in value.items() - if key not in ("alpha", "loss_scale") - } | {"loss": True} - pulse = value.get("pulse") - if isinstance(pulse, dict) and "phases" in pulse: - value = value | { - "pulse": { - ("phase" if name == "phases" else name): item - for name, item in cast("dict[str, object]", pulse).items() - } - } - if "reference_state" in value and isinstance(value["reference_state"], dict): - state = value["reference_state"] - value = value | { - "reference_state": { - ("pressure_bar" if name == "pressure" else name): item - for name, item in state.items() - } - } - return {key: with_former_names(child) for key, child in value.items()} diff --git a/tests/service/conftest.py b/tests/service/conftest.py index 32d5f467c..5e2be5a14 100644 --- a/tests/service/conftest.py +++ b/tests/service/conftest.py @@ -2,9 +2,18 @@ # # SPDX-License-Identifier: GPL-3.0-or-later -"""Fixtures of the service's tests: one finished run, made once per session.""" +"""Fixtures of the service's tests: one finished run, made once per session. +No test reaches a real Slurm, wherever the suite runs: the ``SLURM_*`` variables of an +enclosing job are removed, and the Slurm commands found first on ``PATH`` are ones that +refuse, so no test can ask a real scheduler anything (or cancel the job the suite +itself runs in). A test that fakes Slurm puts its own commands before them. +""" + +import os import shutil +import stat +import sys import warnings from pathlib import Path @@ -13,6 +22,32 @@ from service.cases import MULTIMODE, STATS, TINY from solprop.recipe import Recipe +_SLURM_COMMANDS = ("sacct", "salloc", "sbatch", "scancel", "sinfo", "squeue", "srun") + + +@pytest.fixture(scope="session") +def _no_slurm_bin(tmp_path_factory: pytest.TempPathFactory) -> Path: + """Return a folder of Slurm commands that refuse, each saying so.""" + folder = tmp_path_factory.mktemp("no-slurm") + for name in _SLURM_COMMANDS: + path = folder / name + path.write_text( + f'#!/bin/sh\necho "{name}: the service tests reach no real Slurm" >&2\n' + "exit 1\n", + encoding="utf-8", + ) + path.chmod(path.stat().st_mode | stat.S_IEXEC) + return folder + + +@pytest.fixture(autouse=True) +def _no_real_slurm(_no_slurm_bin: Path, monkeypatch: pytest.MonkeyPatch) -> None: + """Keep every test away from the Slurm of the machine the suite runs on.""" + for name in [name for name in os.environ if name.startswith("SLURM_")]: + monkeypatch.delenv(name) + if sys.platform != "win32": + monkeypatch.setenv("PATH", f"{_no_slurm_bin}{os.pathsep}{os.environ['PATH']}") + @pytest.fixture(scope="session") def finished_run(tmp_path_factory: pytest.TempPathFactory) -> Path: diff --git a/tests/service/test_agent.py b/tests/service/test_agent.py index 920183d0b..90b56b305 100644 --- a/tests/service/test_agent.py +++ b/tests/service/test_agent.py @@ -264,6 +264,42 @@ def test_a_session_that_cannot_start_is_retried(monkeypatch: pytest.MonkeyPatch) broken.close() +def test_a_missing_python_is_refused_and_a_passing_not_found_retried( + monkeypatch: pytest.MonkeyPatch, +): + monkeypatch.setattr(machines, "RECONNECT_PAUSES", (0.01,)) + + def session_saying(text: str): + command = [sys.executable, "-c", f"import sys; sys.exit({text!r})"] + return lambda machine: (command, dict(os.environ)) + + # The shell's word that the machine's Python is not there: refused for good. + missing = Window() + absent = Connection( + Machine("lab", "me@lab", python="~/env/bin/python"), + missing.on_frame, + missing.on_state, + command=session_saying("bash: /home/me/env/bin/python: No such file"), + ) + absent.open() + missing.wait(lambda: "refused" in missing.kinds()) + assert "has no solprop at ~/env/bin/python" in str(dict(missing.states)["refused"]) + absent.close() + # Any other file not found, as a network filesystem may say in passing: retried. + passing = Window() + flaky = Connection( + Machine("lab", "me@lab", python="~/env/bin/python"), + passing.on_frame, + passing.on_state, + command=session_saying("OSError: [Errno 2] No such file: '/nfs/me/x'"), + ) + flaky.open() + passing.wait(lambda: passing.kinds().count("down") >= 2) + assert "refused" not in passing.kinds() + assert "/nfs/me/x" in str(dict(passing.states)["down"]) + flaky.close() + + def test_a_helper_that_says_something_else_is_refused(): window = Window() command = [ @@ -342,7 +378,8 @@ def test_the_ssh_command_and_its_environment(): askpass="/opt/askpass", ) assert command[0] == "ssh" and command[command.index("-p") :][:2] == ["-p", "2222"] - assert command[-1] == "exec ~/env/bin/python -m solprop.service.agent" + assert command[-3:-1] == ["--", "me@lab"] # a host is never read as an option + assert command[-1] == 'exec "$HOME"/env/bin/python -m solprop.service.agent' assert environment["SSH_ASKPASS"] == "/opt/askpass" assert environment["SSH_ASKPASS_REQUIRE"] == "force" local, _ = agent_command(Machine(LOCAL)) @@ -356,6 +393,38 @@ def test_the_ssh_command_and_its_environment(): assert Machine.from_value(value) == machine +@pytest.mark.parametrize( + ("python", "remote"), + [ + ("~/my envs/bin/python", "\"$HOME\"'/my envs/bin/python'"), + ("~", '"$HOME"'), + ("/opt/a b/python", "'/opt/a b/python'"), + ("python3", "python3"), + ("/env/bin/python; rm -rf ~", "'/env/bin/python; rm -rf ~'"), + ], +) +def test_the_helper_s_python_is_quoted_for_the_remote_shell(python, remote): + if sys.platform == "win32": + pytest.skip("the remote shell is POSIX; the check runs it here") + import subprocess # noqa: PLC0415 - only here + + command, _ = agent_command(Machine("lab", "-oProxyCommand=x", python=python)) + assert command[-3:] == [ + "--", + "-oProxyCommand=x", + f"exec {remote} -m solprop.service.agent", + ] + # The remote shell reads it back as the one path given, with ~ expanded. + said = subprocess.run( + ["sh", "-c", f"printf %s {remote}"], + capture_output=True, + text=True, + check=True, + env={**os.environ, "HOME": "/home/me"}, + ).stdout + assert said == python.replace("~", "/home/me", 1 if python.startswith("~") else 0) + + def test_hosts_are_read_from_the_ssh_configuration_and_its_includes(tmp_path: Path): (tmp_path / "lab.conf").write_text("Host lab-1 lab-2\n", encoding="utf-8") config = tmp_path / "config" @@ -424,7 +493,8 @@ def test_a_direct_run_is_cancelled_by_its_signal(tmp_path: Path): sleeper = subprocess.Popen([sys.executable, "-c", "import time; time.sleep(60)"]) try: - job = Job("r1", "direct", socket.gethostname(), sleeper.pid, None, None, 0.0) + stamp = process_stamp(sleeper.pid) + job = Job("r1", "direct", socket.gethostname(), sleeper.pid, stamp, None, 0.0) write_job(tmp_path, job) Agent(io.BytesIO()).cancel({"folder": str(tmp_path)}) assert sleeper.wait(timeout=WAIT) != 0 @@ -444,19 +514,144 @@ def test_a_direct_run_is_cancelled_by_its_signal(tmp_path: Path): sleeper.wait() +@pytest.mark.parametrize("recorded", ["job", "submitted"]) +def test_a_process_whose_start_was_not_recorded_is_not_signalled( + tmp_path: Path, recorded: str +): + """Its number may belong to another process by now: Kill refuses, saying why.""" + import subprocess # noqa: PLC0415 - only here + + from solprop.service.launch import SUBMITTED # noqa: PLC0415 - only here + from solprop.service.record import Job, write_job, write_json # noqa: PLC0415 + + here = socket.gethostname() + # This stands in for a later process that has the run's number. + sleeper = subprocess.Popen([sys.executable, "-c", "import time; time.sleep(60)"]) + try: + if recorded == "job": + write_job(tmp_path, Job("r1", "direct", here, sleeper.pid, None, None, 0)) + else: + write_json( + tmp_path / SUBMITTED, + {"launcher": "direct", "host": here, "pid": sleeper.pid, "stamp": None}, + ) + with pytest.raises(ServiceError, match="its start was not recorded"): + Agent(io.BytesIO()).cancel({"folder": str(tmp_path), "force": True}) + assert sleeper.poll() is None # not signalled + finally: + sleeper.kill() + sleeper.wait() + + +def _recording_scancel(tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> Path: + """Put a ``scancel`` first on the path that records its arguments; return where.""" + if sys.platform == "win32": + pytest.skip("Slurm is faked with POSIX shell scripts") + bin_ = tmp_path / "bin" + bin_.mkdir() + calls = tmp_path / "scancel-calls" + (bin_ / "scancel").write_text( + f'#!/bin/sh\necho "$*" >> "{calls}"\n', encoding="utf-8" + ) + (bin_ / "scancel").chmod(0o755) + monkeypatch.setenv("PATH", f"{bin_}{os.pathsep}{os.environ['PATH']}") + return calls + + +@pytest.mark.medium +def test_a_direct_run_inside_an_allocation_is_cancelled_by_its_signal_alone( + tmp_path: Path, monkeypatch: pytest.MonkeyPatch +): + """A run started directly is no Slurm job, though the helper sits in one.""" + calls = _recording_scancel(tmp_path, monkeypatch) + monkeypatch.setenv("SLURM_JOB_ID", "4242") # the allocation, not the run's + from solprop.service.record import read_events # noqa: PLC0415 - only here + + # Long enough (several seconds) to be cancelled well before its end. + slow = TINY.replace('length = "5 cm"', 'length = "200 cm"').replace( + "n_save = 6", "n_save = 200" + ) + workspace = tmp_path / "runs" + folder = workspace / "r1" + helper = Agent(io.BytesIO()) + spec = spec_value(RunSpec("r1", str(folder), recipe=slow)) + helper.start({"spec": spec, "launcher": "direct"}) + + def summary() -> dict[str, Any]: + return helper.list_runs({"workspace": str(workspace)})[0] + + def marching() -> bool: # a row recorded: SIGTERM now leaves it stopped + events = read_events(folder)[0] if (folder / "events.bin").exists() else [] + return any(event.kind == "row" for event in events) + + deadline = time.monotonic() + WAIT + while not marching(): + assert time.monotonic() < deadline + time.sleep(0.05) + assert summary()["state"] == "running" and summary()["slurm_job"] is None + helper.cancel({"folder": str(folder)}) + deadline = time.monotonic() + WAIT + while summary()["state"] in {"running", "starting"}: + assert time.monotonic() < deadline + time.sleep(0.05) + assert summary()["state"] == "stopped" # its process had SIGTERM + assert not calls.exists() + helper.close() + + +@pytest.mark.parametrize("submitted", [True, False]) +def test_a_direct_run_s_record_naming_an_allocation_is_cancelled_by_its_signal( + tmp_path: Path, monkeypatch: pytest.MonkeyPatch, submitted: bool +): + """Only the job solprop submitted a run as is cancelled, whatever ``job.json`` says. + + A run started directly inside an allocation could record that allocation as its + job, with or without the starter's ``submitted.json``. + """ + import subprocess # noqa: PLC0415 - only here + + from solprop.service.launch import SUBMITTED # noqa: PLC0415 - only here + from solprop.service.record import ( # noqa: PLC0415 - only here + Job, + process_stamp, + write_job, + write_json, + ) + + calls = _recording_scancel(tmp_path, monkeypatch) + here = socket.gethostname() + sleeper = subprocess.Popen([sys.executable, "-c", "import time; time.sleep(60)"]) + try: + stamp = process_stamp(sleeper.pid) + if submitted: + write_json( + tmp_path / SUBMITTED, + {"launcher": "direct", "host": here, "pid": sleeper.pid}, + ) + write_job(tmp_path, Job("r1", "slurm", here, sleeper.pid, stamp, "4242", 0.0)) + Agent(io.BytesIO()).cancel({"folder": str(tmp_path)}) + assert sleeper.wait(timeout=WAIT) != 0 + assert not calls.exists() + finally: + sleeper.kill() + sleeper.wait() + + def test_slurm_runs_through_the_helper(tmp_path: Path, monkeypatch): if sys.platform == "win32": pytest.skip("Slurm is faked with POSIX shell scripts") bin_ = tmp_path / "bin" bin_.mkdir() + cancelled = tmp_path / "cancelled" for name, script in ( ("sbatch", 'echo "77"\n'), ("squeue", 'echo "77|PENDING|Resources"\n'), - ("scancel", "exit 0\n"), + ("scancel", f'echo "$*" >> "{cancelled}"\n'), ): (bin_ / name).write_text("#!/bin/sh\n" + script, encoding="utf-8") (bin_ / name).chmod(0o755) monkeypatch.setenv("PATH", f"{bin_}{os.pathsep}{os.environ['PATH']}") + monkeypatch.setenv("SLURM_JOB_ID", "4242") # the helper sits in an allocation helper = Agent(io.BytesIO()) folder = tmp_path / "runs" / "s1" spec = spec_value(RunSpec("s1", str(folder), recipe=TINY)) @@ -467,12 +662,177 @@ def test_slurm_runs_through_the_helper(tmp_path: Path, monkeypatch): listed = helper.list_runs({"workspace": str(tmp_path / "runs")}) assert listed[0]["detail"] == "Resources" helper.cancel({"folder": str(folder)}) + assert cancelled.read_text(encoding="utf-8").splitlines() == ["77"] with pytest.raises(ServiceError, match="is queued"): helper.remove({"folder": str(folder)}) with pytest.raises(ServiceError, match="no launcher"): helper.start({"spec": spec, "launcher": "nowhere"}) +def _queued_long_ago(folder: Path) -> None: + """Make a folder whose Slurm job was submitted well beyond the staleness window.""" + from solprop.service.launch import SUBMITTED # noqa: PLC0415 - only here + from solprop.service.record import write_json # noqa: PLC0415 - only here + from solprop.service.runs import STALE # noqa: PLC0415 - only here + + folder.mkdir(parents=True) + (folder / "run.h5").write_bytes(b"earlier part") + (folder / "spec.json").write_text("{}", encoding="utf-8") + submitted = time.time() - 10 * STALE + write_json( + folder / SUBMITTED, + {"launcher": "slurm", "slurm_job": "77", "submitted": submitted}, + ) + + +def _slurm_bin(tmp_path: Path, monkeypatch: pytest.MonkeyPatch, **scripts: str) -> Path: + """Put fake Slurm commands first on the path; return where ``sbatch`` records.""" + if sys.platform == "win32": + pytest.skip("Slurm is faked with POSIX shell scripts") + bin_ = tmp_path / "bin" + bin_.mkdir() + submitted = tmp_path / "sbatch-calls" + scripts.setdefault("sbatch", f'echo "$*" >> "{submitted}"\necho 78\n') + for name, script in scripts.items(): + (bin_ / name).write_text("#!/bin/sh\n" + script, encoding="utf-8") + (bin_ / name).chmod(0o755) + monkeypatch.setenv("PATH", f"{bin_}{os.pathsep}{os.environ['PATH']}") + return submitted + + +def test_a_slurm_run_queued_long_is_neither_continued_nor_removed( + tmp_path: Path, monkeypatch: pytest.MonkeyPatch +): + submitted = _slurm_bin(tmp_path, monkeypatch, squeue='echo "77|PENDING|Priority"\n') + folder = tmp_path / "runs" / "s1" + _queued_long_ago(folder) + helper = Agent(io.BytesIO()) + spec = spec_value(RunSpec("s1", str(folder), resume=True)) + with pytest.raises(ServiceError, match="s1 is queued: continue it once it ends"): + helper.start({"spec": spec, "launcher": "slurm"}) + assert (folder / "spec.json").read_text(encoding="utf-8") == "{}" + assert not submitted.exists() # no second job on the folder + with pytest.raises(ServiceError, match="s1 is queued: stop or cancel it first"): + helper.remove({"folder": str(folder)}) + assert folder.exists() + + +def test_a_slurm_run_the_scheduler_cannot_be_asked_about_is_left_alone( + tmp_path: Path, monkeypatch: pytest.MonkeyPatch +): + down = 'echo "slurm_load_jobs error: Unable to contact slurm controller" >&2\n' + submitted = _slurm_bin( + tmp_path, monkeypatch, squeue=down + "exit 1\n", sacct=down + "exit 1\n" + ) + folder = tmp_path / "runs" / "s1" + _queued_long_ago(folder) + helper = Agent(io.BytesIO()) + spec = spec_value(RunSpec("s1", str(folder), resume=True)) + with pytest.raises(ServiceError, match=r"s1 is not continued: .*slurm controller"): + helper.start({"spec": spec, "launcher": "slurm"}) + assert not submitted.exists() + with pytest.raises(ServiceError, match=r"s1 is not removed: .*slurm controller"): + helper.remove({"folder": str(folder)}) + assert folder.exists() + + +def test_a_slurm_run_whose_job_has_gone_is_continued_and_removed( + tmp_path: Path, monkeypatch: pytest.MonkeyPatch +): + submitted = _slurm_bin( + tmp_path, + monkeypatch, + squeue='echo "slurm_load_jobs error: Invalid job id specified" >&2\nexit 1\n', + sacct='echo "77|TIMEOUT"\necho "78|CANCELLED by 1234"\n', + ) + folder = tmp_path / "runs" / "s1" + _queued_long_ago(folder) + helper = Agent(io.BytesIO()) + spec = spec_value(RunSpec("s1", str(folder), resume=True)) + summary = helper.start({"spec": spec, "launcher": "slurm"}) + assert summary["slurm_job"] == "78" and submitted.exists() + # The continuation's job, cancelled in the queue, has gone too. + helper.remove({"folder": str(folder)}) + assert not folder.exists() + + +@pytest.mark.parametrize( + ("launcher", "resume", "refused"), + [ + ("direct", True, "could not be started"), + ("slurm", True, "Slurm refused the job"), + # A new run is refused the folder before anything is set aside. + ("direct", False, "already holds a run"), + ], + ids=["continued-direct", "continued-slurm", "new"], +) +def test_a_start_that_cannot_be_launched_leaves_the_run_as_it_was( + tmp_path: Path, + monkeypatch: pytest.MonkeyPatch, + launcher: str, + resume: bool, + refused: str, +): + from solprop.service.launch import SUBMITTED # noqa: PLC0415 - only here + from solprop.service.messages import Event # noqa: PLC0415 - only here + from solprop.service.record import ( # noqa: PLC0415 - only here + EventLog, + Job, + read_events, + write_json, + ) + from solprop.service.runs import summarise # noqa: PLC0415 - only here + + _slurm_bin( + tmp_path, + monkeypatch, + sbatch='echo "sbatch: error: invalid partition specified: x" >&2\nexit 1\n', + ) + folder = tmp_path / "runs" / "r1" + folder.mkdir(parents=True) + # A run that was stopped cleanly, its process gone. + here = socket.gethostname() + write_json(folder / SUBMITTED, {"launcher": "direct", "host": here, "pid": 0}) + log = EventLog(folder, "r1", job=lambda: Job.here("r1", "direct")) + log.put(Event("r1", "stopped", {"path": "run.h5", "message": "by its stop flag"})) + log.close() + (folder / "run.h5").write_bytes(b"earlier part") + before = summarise(folder) + assert (before["state"], before["detail"]) == ("stopped", "by its stop flag") + helper = Agent(io.BytesIO()) + run = ( + RunSpec("r1", str(folder), resume=True) + if resume + else RunSpec("r1", str(folder), recipe=TINY) + ) + spec = spec_value(run) + with pytest.raises(ServiceError, match=refused): + helper.start( + {"spec": spec, "launcher": launcher, "python": str(tmp_path / "none")} + ) + after = summarise(folder) + assert (after["state"], after["detail"]) == ("stopped", "by its stop flag") + assert (after["started"], after["ended"]) == (before["started"], before["ended"]) + assert [e.kind for e in read_events(folder)[0]] == ["stopped"] + + +def test_a_run_that_has_not_ended_is_not_continued(tmp_path: Path): + from solprop.service.record import Job, process_stamp, write_job # noqa: PLC0415 + + folder = tmp_path / "r1" + folder.mkdir() + # This process stands in for the run's own, alive and recorded, with no ending. + pid = os.getpid() + here = socket.gethostname() + write_job(folder, Job("r1", "direct", here, pid, process_stamp(pid), None, 0.0)) + (folder / "run.h5").write_bytes(b"") + helper = Agent(io.BytesIO()) + spec = spec_value(RunSpec("r1", str(folder), resume=True)) + with pytest.raises(ServiceError, match="r1 is running: continue it once it ends"): + helper.start({"spec": spec, "launcher": "direct"}) + assert (folder / "job.json").exists() # its record is not set aside + + def test_the_hosted_kernel_in_this_process(monkeypatch): output = io.BytesIO() helper = Agent(output) @@ -706,9 +1066,98 @@ def test_a_followed_run_that_goes_without_an_ending_is_said_lost( (event,) = frames[-1]["events"] assert event["kind"] == "lost" and event["run_id"] == "gone" assert "before it started" in event["data"]["message"] + assert event["data"]["output"] is None # no results file to open helper.close() +def test_a_continued_run_still_starting_is_followed_and_cancelled( + tmp_path: Path, monkeypatch: pytest.MonkeyPatch +): + import subprocess # noqa: PLC0415 - only here + + from solprop.service.launch import SUBMITTED, prepare # noqa: PLC0415 + from solprop.service.record import ( # noqa: PLC0415 - only here + Job, + process_stamp, + write_job, + write_json, + ) + + monkeypatch.setattr(agent, "LIVENESS_PERIOD", 0.0) + here = socket.gethostname() + folder = tmp_path / "r1" + folder.mkdir() + # The earlier part ended, its process gone; the folder is continued. + write_job(folder, Job("r1", "direct", here, 0, None, None, 0.0, ended=1.0)) + (folder / "run.h5").write_bytes(b"") + prepare(RunSpec("r1", str(folder), resume=True)) + # Started (this sleeper stands in for the new part's process), not yet recorded. + sleeper = subprocess.Popen([sys.executable, "-c", "import time; time.sleep(60)"]) + try: + write_json( + folder / SUBMITTED, + { + "launcher": "direct", + "host": here, + "pid": sleeper.pid, + "stamp": process_stamp(sleeper.pid), + }, + ) + output = io.BytesIO() + helper = Agent(output) + helper.follow({"folder": str(folder), "offset": 0, "period": 0.02}) + time.sleep(0.3) + assert b"lost" not in output.getvalue() + helper.cancel({"folder": str(folder)}) + assert sleeper.wait(timeout=WAIT) != 0 + helper.close() + finally: + sleeper.kill() + sleeper.wait() + + +def test_a_followed_queued_slurm_run_asks_the_scheduler_seldom( + tmp_path: Path, monkeypatch: pytest.MonkeyPatch +): + from solprop.service.launch import SUBMITTED # noqa: PLC0415 - only here + from solprop.service.record import write_json # noqa: PLC0415 - only here + + if sys.platform == "win32": + pytest.skip("Slurm is faked with POSIX shell scripts") + bin_ = tmp_path / "bin" + bin_.mkdir() + calls = tmp_path / "calls" + (bin_ / "squeue").write_text( + f'#!/bin/sh\necho x >> "{calls}"\necho "77|PENDING|Priority"\n', + encoding="utf-8", + ) + (bin_ / "squeue").chmod(0o755) + monkeypatch.setenv("PATH", f"{bin_}{os.pathsep}{os.environ['PATH']}") + monkeypatch.setattr(agent, "LIVENESS_PERIOD", 0.0) + folder = tmp_path / "s1" + folder.mkdir() + write_json( + folder / SUBMITTED, + {"launcher": "slurm", "slurm_job": "77", "submitted": time.time()}, + ) + + def asked(period: float) -> int: + """Return how often following the queued job for 0.5 s asked squeue.""" + monkeypatch.setattr(agent, "SLURM_LIVENESS_PERIOD", period) + calls.unlink(missing_ok=True) + output = io.BytesIO() + helper = Agent(output) + helper.follow({"folder": str(folder), "offset": 0, "period": 0.02}) + time.sleep(0.5) + helper.close() + time.sleep(0.1) # the follow's last check ends + assert b"lost" not in output.getvalue() + return len(calls.read_text().splitlines()) if calls.exists() else 0 + + assert asked(agent.SLURM_LIVENESS_PERIOD) == 0 + assert asked(0.0) >= 3 # asked on every quiet read: what a short period costs + + def test_a_folder_held_open_is_removed_once_let_go( tmp_path: Path, monkeypatch: pytest.MonkeyPatch ): @@ -811,3 +1260,30 @@ def test_a_followed_run_gone_before_recording_its_ending_has_it_sent( (sent,) = [f for f in answers(output) if f.get("kind") == "events"] assert [e["kind"] for e in sent["events"]] == ["stopped"] helper.close() + + +def test_a_followed_run_whose_ending_reached_only_its_summary_is_ended( + tmp_path: Path, monkeypatch: pytest.MonkeyPatch +): + from solprop.service.record import EVENTS, STATUS, write_json # noqa: PLC0415 + + monkeypatch.setattr(agent, "LIVENESS_PERIOD", 0.0) + folder = tmp_path / "r1" + folder.mkdir() + # The record could not take the terminal event (a full disk), the summary could. + frame = {"run_id": "r1", "kind": "row", "data": {"index": 0}} + (folder / EVENTS).write_bytes(encode(frame)) + ending = {"kind": "stopped", "data": {"path": "run.h5", "message": "stop flag"}} + write_json(folder / STATUS, {"run_id": "r1", "ending": ending}) + output = io.BytesIO() + helper = Agent(output) + helper.follow({"folder": str(folder), "offset": 0, "period": 0.02}) + deadline = time.monotonic() + 10 + while b"stopped" not in output.getvalue(): + assert time.monotonic() < deadline + time.sleep(0.02) + sent = [f for f in answers(output) if f.get("kind") == "events"] + events = [event for frame in sent for event in frame["events"]] + assert [e["kind"] for e in events] == ["row", "stopped"] + assert events[-1] == {"run_id": "r1", **ending} + helper.close() diff --git a/tests/service/test_design.py b/tests/service/test_design.py index 28b59c43d..d7df8d1f7 100644 --- a/tests/service/test_design.py +++ b/tests/service/test_design.py @@ -38,6 +38,41 @@ def ask(kind: str, payload: Mapping[str, object]) -> Any: return handlers.HANDLERS[kind](payload) +@pytest.mark.medium +def test_the_modes_of_a_setup_are_plain_arrays(): + four_modes = """\ +[recipe] +format = 1 +route = "capillary" + +[build] +radius = "125 um" +length = "1 m" +gas = "He" +pressure = "1 bar" +modes = 4 +wavelength = "800 nm" +fwhm = "10 fs" +energy = "100 uJ" +wavelength_limits = ["150 nm", "4 um"] +trange = "400 fs" +""" + reply = ask("modes", {"text": four_modes}) + assert reply["pump"] == pytest.approx(800e-9) and reply["sweep"] is None + (only,) = reply["sets"] + assert only["value"] is None and only["z"] == 0.0 + labels = [mode["label"] for mode in only["modes"]] + assert labels == [f"HE1,{m}:even" for m in range(1, 5)] + first = only["modes"][0] + names = ("neff_minus_one", "beta1", "beta2", "beta3", "alpha", "gamma") + for name in (*names, "phase_mismatch"): + assert first[name].shape == only["omega"].shape + assert 4e-7 < first["zdw"] < 6e-7 and first["aeff"] > 0 + # Each mode's wave phase-matched to the soliton in the first: bluer in higher ones. + rdw = [mode["rdw"][0] for mode in only["modes"][:3]] + assert rdw == sorted(rdw, reverse=True) and 1.5e-7 < rdw[-1] < rdw[0] < 2.1e-7 + + def test_a_sweep_gives_one_mode_set_per_value_and_says_which_fail(): payload = { "text": TINY, @@ -75,7 +110,7 @@ def test_a_route_without_modes_or_a_pump_says_so(): assert ask("modes", {"text": unsolvable})["pump"] is None -def test_pins_are_described_and_their_roots_found(): +def test_pins_are_described_and_solved(): assert set(ask("pin_targets", {"route": "capillary"})["pressure"][0]) == { "target", "stage", @@ -85,14 +120,11 @@ def test_pins_are_described_and_their_roots_found(): by_name = {entry["name"]: entry for entry in description["parameters"]} assert [pin["target"] for pin in by_name["energy"]["pins"]] == ["soliton_order"] assert by_name["gas"]["pins"] == [] - found = ask("pin_roots", {"text": PINNED, "path": "pressure"}) - assert len(found["roots"]) >= 1 and found["attainable"] is None - none = ask( - "pin_roots", {"text": PINNED.replace('"500 nm"', '"50 nm"'), "path": "pressure"} - ) - assert none["roots"] == [] and "wavelength" in none["quantity"] + assert "pin_roots" not in handlers.HANDLERS # roots are not offered + found = Recipe.loads(PINNED).pin_roots("pressure") summary = ask("summarise", {"text": PINNED}) - assert summary["pinned"]["pressure"] == pytest.approx(found["roots"][0]) + # The chosen root of the same target, each solved to the root finder's tolerance. + assert summary["pinned"]["pressure"] == pytest.approx(found.roots[0], rel=1e-6) def test_a_multimode_run_with_a_launch_streams_rows(tmp_path: Path): diff --git a/tests/service/test_launch.py b/tests/service/test_launch.py index a5f46ae8d..ce203ebc4 100644 --- a/tests/service/test_launch.py +++ b/tests/service/test_launch.py @@ -85,6 +85,11 @@ def test_a_prepared_folder_holds_the_spec_and_refuses_a_second_run(tmp_path): (folder / "run.h5").write_bytes(b"") with pytest.raises(ServiceError, match="already holds a run"): prepare(spec) + # A scan's folder too: a new start would append to its record. + scan = RunSpec("s1", str(tmp_path / "s1"), recipe=TINY) + (prepare(scan) / "scan.h5").write_bytes(b"") + with pytest.raises(ServiceError, match="already holds a run"): + prepare(scan) def test_the_batch_script_asks_for_what_the_template_says(tmp_path): @@ -114,7 +119,7 @@ def test_the_batch_script_asks_for_what_the_template_says(tmp_path): ): assert wanted in lines assert "#SBATCH --job-name=solprop-a_run" in lines - assert lines[-1].startswith("exec /env/bin/python -m solprop.service.job '") + assert lines[-1].startswith("exec /env/bin/python -m solprop.service.job --slurm '") assert resources.brief == "gpu · 8 CPUs · 16G · gpu:1 · 1-00:00:00" plain = slurm_script(tmp_path, "python", SlurmResources()) assert "export SOLPROP_THREADS=${SLURM_CPUS_PER_TASK:-1}" in plain @@ -279,6 +284,7 @@ def test_a_direct_run_stops_on_its_stop_file(tmp_path): def test_the_job_command_needs_a_folder_with_a_spec(tmp_path, capsys): assert job_main([]) == 2 + assert job_main(["--slurm"]) == 2 assert job_main([str(tmp_path)]) == 2 assert "no run to start" in capsys.readouterr().err (tmp_path / SPEC).write_text('{"run_id": "r1", "nonsense": 1}', encoding="utf-8") @@ -289,13 +295,30 @@ def test_the_job_command_runs_in_this_process(tmp_path, monkeypatch): folder = prepare(RunSpec("r1", str(tmp_path / "r1"), recipe=TINY, threads=1)) monkeypatch.setenv("SLURM_JOB_ID", "77") monkeypatch.setenv("SOLPROP_THREADS", "2") # restored after the test - assert job_main([str(folder)]) == 0 + assert job_main(["--slurm", str(folder)]) == 0 assert os.environ["SOLPROP_THREADS"] == "1" job = json.loads((folder / JOB).read_text(encoding="utf-8")) assert (job["launcher"], job["slurm_job"]) == ("slurm", "77") assert summarise(folder)["state"] == "finished" +def test_a_job_started_inside_an_allocation_is_not_that_allocation( + tmp_path, monkeypatch +): + """Only the batch script solprop submits makes a run its Slurm job's own.""" + from solprop.service import run as run_module # noqa: PLC0415 - only here + + seen = [] + monkeypatch.setattr(run_module, "execute", seen.append) + monkeypatch.setenv("SLURM_JOB_ID", "77") + folder = prepare(RunSpec("r1", str(tmp_path / "r1"), recipe=TINY)) + assert job_main([str(folder)]) == 0 + assert job_main(["--slurm", str(folder)]) == 0 + assert [spec.launcher for spec in seen] == ["direct", "slurm"] + assert Job.here("r1", "direct").slurm_job is None + assert Job.here("r1", "slurm").slurm_job == "77" + + def test_a_start_that_fails_says_why(tmp_path, monkeypatch): folder = prepare(RunSpec("r1", str(tmp_path / "r1"), recipe=TINY)) with pytest.raises(ServiceError, match=r"could not be started \(status 1\): "): @@ -406,6 +429,111 @@ def test_a_scan_as_a_job_runs_its_points_in_a_pool(tmp_path): assert (summary["points"], summary["done"]) == (2, 2) +def test_a_stop_pressed_before_a_new_run_starts_is_obeyed(tmp_path): + from solprop.service import run as run_module # noqa: PLC0415 - only here + + folder = tmp_path / "r1" + folder.mkdir() + request_stop(folder) # a stop file left over in the folder before the run + spec = RunSpec("r1", str(folder), recipe=TINY) + prepare(spec) + assert not summarise(folder)["stopping"] + request_stop(folder) # Stop pressed while the job waits in the queue + run_module.execute(spec) + (ending,) = [e for e in read_events(folder)[0] if e.terminal] + assert ending.kind == "stopped" + assert ending.data["message"] == "stopped before it started" + assert not (folder / "run.h5").exists() + assert ending.data["output"] is None # nothing written to open + assert summarise(folder)["state"] == "stopped" + + +def test_a_scan_stopped_before_it_starts_ends_as_a_scan(tmp_path): + from solprop.service import run as run_module # noqa: PLC0415 - only here + + scan = TINY + '\n[scan]\nname = "pressure"\npressure = ["0.5 bar", "1 bar"]\n' + folder = tmp_path / "s1" + spec = RunSpec("s1", str(folder), recipe=scan) + prepare(spec) + request_stop(folder) # Stop pressed while the scan waits in the queue + run_module.execute(spec) + (ending,) = [e for e in read_events(folder)[0] if e.terminal] + assert ending.kind == "stopped" and ending.data["scan"] is True + assert ending.data["path"] == str(folder / "scan.h5") + assert ending.data["output"] is None + summary = summarise(folder) + assert (summary["state"], summary["scan"]) == ("stopped", True) + + +def test_a_recipe_that_is_not_toml_fails_as_a_plain_run(tmp_path): + from solprop.service import run as run_module # noqa: PLC0415 - only here + + folder = tmp_path / "r1" + spec = RunSpec("r1", str(folder), recipe='[scan\nname = "pressure"\n') + prepare(spec) + run_module.execute(spec) + (ending,) = [e for e in read_events(folder)[0] if e.terminal] + # Not a scan, since it cannot be read as one: its ending names the run's file. + assert ending.kind == "failed" and "scan" not in ending.data + assert ending.data["path"] == str(folder / "run.h5") + assert ending.data["output"] is None + assert summarise(folder)["state"] == "failed" + + +def test_a_stop_pressed_before_a_continued_run_starts_is_obeyed(tmp_path): + from solprop.service import run as run_module # noqa: PLC0415 - only here + + folder = prepare(RunSpec("r1", str(tmp_path / "r1"), recipe=TINY)) + (folder / "run.h5").write_bytes(b"earlier part") + write_job(folder, Job("r1", "direct", socket.gethostname(), 0, None, None, 0.0)) + (folder / "events.bin").write_bytes(b"") + request_stop(folder) # how the earlier part was stopped + spec = RunSpec("r1", str(folder), resume=True) + prepare(spec) + request_stop(folder) # Stop pressed while the continuation is starting + run_module.execute(spec) + (ending,) = [e for e in read_events(folder)[0] if e.terminal] + assert ending.kind == "stopped" + assert (folder / "run.h5").read_bytes() == b"earlier part" + + +def test_a_run_continued_by_hand_sets_aside_its_earlier_record_and_stop(tmp_path): + from solprop.service import run as run_module # noqa: PLC0415 - only here + + folder = prepare(RunSpec("r1", str(tmp_path / "r1"), recipe=TINY)) + (folder / "run.h5").write_bytes(b"") + write_job(folder, Job("r1", "direct", socket.gethostname(), 0, None, None, 0.0)) + (folder / "events.bin").write_bytes(b"") + request_stop(folder) # how the earlier part was stopped + # No launcher prepared it: the job itself finds the earlier part's record. + run_module.execute(RunSpec("r1", str(folder), resume=True)) + assert (folder / "events-1.bin").exists() and (folder / "job-1.json").exists() + (ending,) = [e for e in read_events(folder)[0] if e.terminal] + assert ending.kind == "failed" # it went on, and found no file to continue + + +def test_a_continued_direct_run_is_starting_until_its_new_process_records_itself( + tmp_path, +): + from solprop.service import run as run_module # noqa: PLC0415 - only here + + folder = tmp_path / "r1" + run_module.execute(RunSpec("r1", str(folder), recipe=TINY)) + assert summarise(folder)["state"] == "finished" + prepare(RunSpec("r1", str(folder), resume=True)) + # As start_direct records it: the new part's process (this one stands in for it) + # has started and not yet written its job.json. + here = socket.gethostname() + write_json( + folder / SUBMITTED, + {"launcher": "direct", "host": here, "pid": os.getpid(), "submitted": 1.0}, + ) + found = summarise(folder) + assert found["state"] == "starting" + assert (found["started"], found["ended"]) == (None, None) + assert json.loads((folder / "job-1.json").read_text(encoding="utf-8"))["ended"] + + def test_a_continued_run_s_folder_starts_a_new_record(tmp_path): folder = prepare(RunSpec("r1", str(tmp_path / "r1"), recipe=TINY)) (folder / "events.bin").write_bytes(b"old") diff --git a/tests/service/test_light.py b/tests/service/test_light.py index 4dafef39f..2e3557f3f 100644 --- a/tests/service/test_light.py +++ b/tests/service/test_light.py @@ -10,7 +10,7 @@ from solprop.grid import EnvelopeGrid from solprop.service.messages import PROTOCOL, Event, Reply, Request from solprop.service.reduce import Display, Reducer, bin_max -from solprop.service.states import ACTIVE, ExecutionState, advance +from solprop.service.states import ACTIVE, ExecutionState, advance, failure_advice # ---------------------------------------------------------------------- messages @@ -94,6 +94,23 @@ def test_the_state_machine_follows_a_run(): assert advance(ExecutionState.RUNNING, "lost") == ExecutionState.LOST assert advance(ExecutionState.STARTING, "failed") == ExecutionState.FAILED assert ExecutionState.COMPLETE not in ACTIVE + assert ExecutionState.LOST == "lost" + + +@pytest.mark.parametrize( + ("message", "said", "hinted"), + [ + ("out of memory", "(out of memory)", True), + ("timeout", "(timeout)", False), + ("it ended before it started", "(it ended before it started)", False), + ("", "ended without recording how.", False), + ], +) +def test_a_lost_run_is_explained_by_its_reason(message, said, hinted): + advice = failure_advice("lost", message) + assert advice.startswith("The run's process ended without recording how") + assert said in advice + assert ("LowStorageRungeKutta" in advice) == hinted # ---------------------------------------------------------------------- workspace diff --git a/tests/service/test_postprocess.py b/tests/service/test_postprocess.py index 4531ccb13..1b7eeb519 100644 --- a/tests/service/test_postprocess.py +++ b/tests/service/test_postprocess.py @@ -108,7 +108,7 @@ def test_fixed_elements_are_applied_in_order(run: str): assert pulses["limit"]["peak"] >= pulses["before"]["peak"] * 0.999 assert math.isclose(found["wavelength"], 8e-7, rel_tol=1e-3) empty = chain(run) # no elements: after is before - assert np.allclose(empty["after"], empty["before"]) + assert np.allclose(empty["after"], empty["before"], atol=0.0) def test_an_auto_stage_finds_what_the_compressor_finds_on_the_file(run: str): diff --git a/tests/service/test_record.py b/tests/service/test_record.py index 134485a77..cc0f3b586 100644 --- a/tests/service/test_record.py +++ b/tests/service/test_record.py @@ -119,6 +119,64 @@ def test_an_event_that_cannot_be_written_costs_the_record_not_the_run(tmp_path): assert [event.kind for event in read_events(tmp_path)[0]] == ["finished"] +class ShortWriteOnce: + """A record's stream whose second write stops halfway, as a disk filling up.""" + + def __init__(self, stream) -> None: + self.stream = stream + self.writes = 0 + + def write(self, data: bytes) -> int: + self.writes += 1 + if self.writes == 2: + self.stream.write(data[: len(data) // 2]) + self.stream.flush() + raise OSError(28, "No space left on device") + return self.stream.write(data) + + def flush(self) -> None: + self.stream.flush() + + def close(self) -> None: + self.stream.close() + + +def test_a_write_cut_short_leaves_no_part_of_a_frame_in_the_record(tmp_path): + log = EventLog(tmp_path, "r1") + log._stream = ShortWriteOnce(log._stream) # pyright: ignore[reportAttributeAccessIssue] + for index in range(3): + log.put(Event("r1", "row", {"index": index})) + log.put(Event("r1", "finished", {})) + log.close() + events = read_events(tmp_path)[0] + assert [(e.kind, e.data.get("index")) for e in events] == [ + ("row", 0), + ("row", 2), + ("finished", None), + ] + + +def test_a_record_that_cannot_be_cut_back_keeps_no_more_events(tmp_path, monkeypatch): + def refused(path, length): + raise OSError(30, "Read-only file system") + + log = EventLog(tmp_path, "r1") + log._stream = ShortWriteOnce(log._stream) # pyright: ignore[reportAttributeAccessIssue] + monkeypatch.setattr(record.os, "truncate", refused) + for index in range(3): + log.put(Event("r1", "row", {"index": index})) + log.put(Event("r1", "finished", {})) + log.close() + events, offset = read_events(tmp_path) + # Nothing follows the part of a frame: the reader stops before it. The summary + # counts only the rows kept, and still records the run's ending. + assert [(e.kind, e.data.get("index")) for e in events] == [("row", 0)] + assert offset < (tmp_path / EVENTS).stat().st_size + status = read_status(tmp_path) + assert status is not None and status["rows"] == 1 + assert status["ending"]["kind"] == "finished" + + def test_the_job_record_round_trips_and_a_torn_one_reads_as_none(tmp_path): assert read_job(tmp_path) is None job = Job.here("r1", "direct", threads=4) @@ -194,7 +252,7 @@ def test_a_continued_run_sets_its_earlier_records_aside(tmp_path): request_stop(tmp_path) set_aside(tmp_path) names = sorted(path.name for path in tmp_path.iterdir()) - assert names == ["events-1.bin", "events-2.bin"] + assert names == ["events-1.bin", "events-2.bin", "status-1.json", "status-2.json"] def test_a_run_tied_to_a_window_stops_when_the_window_goes(tmp_path, monkeypatch): diff --git a/tests/service/test_reduce.py b/tests/service/test_reduce.py new file mode 100644 index 000000000..1c228be0f --- /dev/null +++ b/tests/service/test_reduce.py @@ -0,0 +1,22 @@ +# SPDX-FileCopyrightText: 2026 John C. Travers and contributors +# +# SPDX-License-Identifier: GPL-3.0-or-later + +"""Reducing what a run records to what the front end shows.""" + +import numpy as np + +from solprop.service.reduce import stats_row + + +def test_stats_row_totals_numbers_and_skips_the_rest(): + row = stats_row( + { + "energy": np.array([[1.0, 2.0]]), + "zdw": float("nan"), + "label": object(), + "count": 3, + } + ) + # Sums of a few small integers in binary64: exact. + assert row == {"energy": 3.0, "count": 3.0} diff --git a/tests/service/test_results.py b/tests/service/test_results.py index a920f9aeb..f796cceaf 100644 --- a/tests/service/test_results.py +++ b/tests/service/test_results.py @@ -16,7 +16,7 @@ from service.cases import STATS from solprop.exceptions import SolpropError from solprop.output import open_file -from solprop.processing import get_power +from solprop.processing import energy, fwhm_t, get_power from solprop.recipe import Recipe from solprop.service import handlers, results from solprop.service.reduce import TIME_OVERSAMPLING @@ -81,7 +81,7 @@ def test_the_spectrogram_and_figures(run: str, tmp_path: Path, monkeypatch): assert found["values"].shape == (found["x"].size, found["t"].size) assert found["mode"] == 0 and found["axis"] == "wavelength" # a sum: the first assert 1e-7 < found["x"][0] < found["x"][-1] < 1e-5 # the recipe's window, even - assert np.allclose(np.diff(found["x"]), found["x"][1] - found["x"][0]) + assert np.allclose(np.diff(found["x"]), found["x"][1] - found["x"][0], atol=0.0) narrow = { "path": run, "index": 2, @@ -97,10 +97,14 @@ def test_the_spectrogram_and_figures(run: str, tmp_path: Path, monkeypatch): # On frequency the map starts at the transform's lowest, not the window's. assert gated["x"][0] < 1e14 < gated["x"][-1] assert np.all(np.abs(gated["t"]) <= 5e-14) + import matplotlib.pyplot as plt # noqa: PLC0415 - only here + + before = plt.get_fignums() for kind in ("prop_2d", "spec_1d", "time_1d", "spectrogram", "plot_stats"): file = tmp_path / f"{kind}.png" written = ask("result_figure", {"path": run, "file": str(file), "plot": kind}) assert all(Path(path).stat().st_size > 1000 for path in written) + assert plt.get_fignums() == before # drawn, written and let go with pytest.raises(ValueError, match="no plot"): ask( "result_figure", {"path": run, "file": str(tmp_path / "x.png"), "plot": "x"} @@ -113,10 +117,35 @@ def test_the_spectrogram_and_figures(run: str, tmp_path: Path, monkeypatch): assert [Path(path).name for path in many] == ["stats-1.pdf", "stats-2.pdf"] +def test_a_spectrogram_reports_the_gate_solprop_used(run: str): + from solprop.processing import ( # noqa: PLC0415 - only here + get_spectrogram, + grid_of, + real_field_oversampling, + time_axis, + ) + + wide = [-1e-9, 1e-9] # far wider than the time window: the gate's range is clipped + found = ask("spectrogram", {"path": run, "index": 2, "time_range": wide}) + with open_file(run) as handler: + grid = grid_of(handler) + times = time_axis(grid, real_field_oversampling(grid)) + _, _, values = get_spectrogram( + handler, "wavelength", plane=2, modes=0, gate_fwhm=found["gate_fwhm"] + ) + _, _, by_default = get_spectrogram( + handler, "wavelength", plane=2, modes=0, time_range=(wide[0], wide[1]) + ) + window = float(times[-1] - times[0]) + assert found["gate_fwhm"] == pytest.approx(window / 20.0, rel=1e-12) # rounding + assert by_default.max() > 0.0 + assert np.array_equal(values, by_default) # the gate reported is the one used + + def test_a_file_says_its_planes_positions_and_modes(run: str, monkeypatch): described = ask("describe_output", {"path": run}) assert described["labels"] == ["HE1,1:even", "HE1,2:even"] - assert np.allclose(described["z"], [0.0, 0.025, 0.05]) + assert np.allclose(described["z"], [0.0, 0.025, 0.05], atol=0.0) def refuse(_handler: object) -> None: raise SolpropError("no modes") @@ -259,6 +288,31 @@ def test_a_plane_gives_its_energy_and_a_band_its_share(finished_run: Path) -> No assert drawn[0] == pytest.approx(t[0]) and drawn[-1] >= t[-1] +def test_a_plane_reads_out_its_own_energy_and_width(finished_run: Path) -> None: + with open_file(str(finished_run)) as handler: + last = int(np.asarray(handler["z"]).size) - 1 + expected = { + index: ( + float(energy(handler, plane=index, modes="sum")), + float(fwhm_t(handler, plane=index, modes="sum")), + ) + for index in (0, last) + } + # The fill's loss takes 0.7 % of the energy by the last plane and the width moves + # by 3 %, so a read-out of the wrong plane cannot pass. + assert expected[last][0] < 0.995 * expected[0][0] + assert abs(expected[last][1] / expected[0][1] - 1.0) > 0.01 + path = str(finished_run) + for index, (plane_energy, width) in expected.items(): + found: dict[str, Any] = results.plane({"path": path, "index": index}) + # The same reductions of the same stored plane: equal to their rounding. + assert found["energy"] == pytest.approx(plane_energy, rel=1e-12) + assert found["fwhm"] == pytest.approx(width, rel=1e-12) + # The recipe launches 100 uJ, and the entrance plane holds it (to 1e-8 measured; + # 1e-6 leaves room for that and is far tighter than a wrong plane or unit). + assert expected[0][0] == pytest.approx(100e-6, rel=1e-6) + + def test_run_health_says_how_the_run_went(finished_run: Path) -> None: health: dict[str, Any] = results.run_health({"path": str(finished_run)}) assert health["status"] == "complete" diff --git a/tests/service/test_scan_reductions.py b/tests/service/test_scan_reductions.py index b5cf107fc..455161c94 100644 --- a/tests/service/test_scan_reductions.py +++ b/tests/service/test_scan_reductions.py @@ -72,7 +72,7 @@ def test_each_reduction_is_recorded_at_every_point(recorded: str) -> None: def test_the_axes_are_even_and_cover_the_run_s_window() -> None: recipe = Recipe.loads(TINY) wavelength = reduction_axis(recipe, "spectrum") - assert np.allclose(np.diff(wavelength), np.diff(wavelength)[0]) + assert np.allclose(np.diff(wavelength), np.diff(wavelength)[0], atol=0.0) assert wavelength[0] < 800e-9 < wavelength[-1] t = reduction_axis(recipe, "pulse") assert t[0] < 0 < t[-1] @@ -97,7 +97,7 @@ def test_a_point_of_a_gradient_reads_back_in_its_unit(tmp_path: Path) -> None: assert axis["unit"] == "bar" -def test_a_range_is_written_as_numbers_and_reductions_reach_the_worker( +def test_a_range_is_written_as_numbers_and_reductions_reach_the_scan( tmp_path: Path, ) -> None: text = TINY + ( @@ -111,10 +111,19 @@ def test_a_range_is_written_as_numbers_and_reductions_reach_the_worker( reductions=({"kind": "peak_power_in_band", "band": [600e-9, 900e-9]},), ) collector = Collector(spec).start() - collector.collect(until="point", then="stop") + collector.collect() started = next(e.data for e in collector.events if e.kind == "scan_started") assert started["values"] == [["5e-05", "0.0001"]] assert _point_value("x") == "x" + final = collector.events[-1].data + found: Any = results.scan_overview({"path": final["path"]}) + peak = found["results"]["reduced/peak_power_in_band"]["values"] + # A 10 fs Gaussian of 50 uJ peaks at 0.94 E / fwhm = 4.7 GW over its whole band; + # 600-900 nm holds most of it (4.56 GW measured). + assert peak.shape == (2,) and 4.0e9 < peak[0] < 4.7e9 + # Twice the energy, twice the peak power: the short fill barely reshapes the + # pulse (2.0001 measured), far from what a reading of the wrong point would give. + assert peak[1] / peak[0] == pytest.approx(2.0, rel=1e-2) def test_a_beam_s_scan_is_refused_the_readers_of_a_guided_run() -> None: diff --git a/tests/service/test_service.py b/tests/service/test_service.py index 39cd9d60d..408227eaa 100644 --- a/tests/service/test_service.py +++ b/tests/service/test_service.py @@ -100,6 +100,29 @@ def test_serve_imports_solprops_handlers_when_given_none( assert os.environ["SOLPROP_THREADS"] == kernel.KERNEL_THREADS +def test_serve_keeps_its_own_budget_and_a_file_only_plot_backend( + monkeypatch: pytest.MonkeyPatch, +): + import os # noqa: PLC0415 - only here + + import matplotlib # noqa: PLC0415 - only here + + window, child = pipe() + window.close() + monkeypatch.setenv("SOLPROP_THREADS", "64") + monkeypatch.delenv(kernel.RUN_THREADS, raising=False) + backend = matplotlib.get_backend() + matplotlib.use("svg") + try: + kernel.serve(child, {}) + assert matplotlib.get_backend().lower() == "agg" + finally: + matplotlib.use(backend) + # The window's budget is kept for runs; the kernel's own is its two threads. + assert os.environ[kernel.RUN_THREADS] == "64" + assert os.environ["SOLPROP_THREADS"] == kernel.KERNEL_THREADS + + # ---------------------------------------------------------------------- handlers diff --git a/tests/service/test_waveguide.py b/tests/service/test_waveguide.py index 2dbea3110..07437b608 100644 --- a/tests/service/test_waveguide.py +++ b/tests/service/test_waveguide.py @@ -130,7 +130,11 @@ def test_a_pulse_changes_the_phase_mismatch() -> None: given: dict[str, Any] = waveguide_curves( {**CAPILLARY, "quantity": "mismatch", "pulse": True} ) - assert not np.allclose(bare["curves"][0]["y"], given["curves"][0]["y"]) + assert not np.allclose( + bare["curves"][0]["y"], + given["curves"][0]["y"], + atol=1e-5 * np.max(np.abs(bare["curves"][0]["y"])), + ) def test_numbers_need_no_pulse() -> None: diff --git a/tests/sessions/test_conformance.py b/tests/sessions/test_conformance.py index 90800b038..c6903e78e 100644 --- a/tests/sessions/test_conformance.py +++ b/tests/sessions/test_conformance.py @@ -644,7 +644,6 @@ def test_a_wide_or_off_route_coupled_flow_keeps_the_contract(start, executor, ki # 17-channel block is long, and its repeatability is the suite's other tests'. repeated = executor.deterministic and executor.name.startswith("native") runs = [] - # Either build steps both natively, so a HostMarchWarning stays an error. for _ in range(2 if repeated else 1): started = start(problem, request, context=context) runs.append(drive(started, export=IDENTITY)) diff --git a/tests/sessions/test_native_session_carrier_table.py b/tests/sessions/test_native_session_carrier_table.py index a3c30e748..3c05df4e0 100644 --- a/tests/sessions/test_native_session_carrier_table.py +++ b/tests/sessions/test_native_session_carrier_table.py @@ -10,7 +10,7 @@ imaginary part as a scalar Chebyshev table of its own and read it with the Clenshaw helper solprop's tables use, so the shift the native march forms is the one solprop's march formed on the host. Before, the backend stepped such a run with its Python march -(a ``HostMarchWarning``) and the session left it to the transitional bridge. +and the session left it to the transitional bridge. The case is a capillary of three gases on independent density ramps, which takes the z table for both the operator and the prefactor. It is held to ``numpy_ref``: on the diff --git a/tests/sessions/test_native_session_statistics.py b/tests/sessions/test_native_session_statistics.py index 072ae3889..3d4b9fdec 100644 --- a/tests/sessions/test_native_session_statistics.py +++ b/tests/sessions/test_native_session_statistics.py @@ -645,7 +645,7 @@ def test_a_general_modal_basis_s_flux_statistics_are_native(): """The metric's root, lowered once, whitens the columns natively.""" from modal_provider_cases import GENERAL_Z_END, general_case # noqa: PLC0415 from solprop.pulses import GaussianPulse # noqa: PLC0415 - from solprop.stats import _whitened # noqa: PLC0415 + from solprop.stats.definitions import _whitened # noqa: PLC0415 from solprop.translate.coupled import metric_at # noqa: PLC0415 case = general_case( diff --git a/tests/sessions/test_start.py b/tests/sessions/test_start.py index 66cb1d817..4bd6ee646 100644 --- a/tests/sessions/test_start.py +++ b/tests/sessions/test_start.py @@ -4,8 +4,8 @@ """A session's fresh start, :meth:`~solprop.backends.session.Start.entrance`. -A session starts one trajectory (SEP 47 section 5.1); the entrance of a problem whose -initial state carries several members is refused rather than silently truncated. +A session starts one trajectory (SEP 47 section 5.1) from the problem's launch state, +with its launch plane still owed. """ import numpy as np diff --git a/tests/stepper/test_controller.py b/tests/stepper/test_controller.py index 3bc082190..d34eb12ff 100644 --- a/tests/stepper/test_controller.py +++ b/tests/stepper/test_controller.py @@ -117,6 +117,18 @@ def test_the_integral_term_actually_changes_the_factor(): assert control.propose([0.5, 0.5]) != pytest.approx(control.propose([0.1, 0.5])) +def test_the_factor_is_the_pi_law_of_the_current_and_previous_norms(): + control = make_controller(lag=0) + # safety * current**-beta1 * previous**-beta2 with the shipped gains for an + # order-four estimator (safety 0.8, beta1 0.12, beta2 -0.04), current 0.5 and + # previous 0.25: inside the clamps, so the law itself. Two powers and two products, + # each within one rounding, so 4u = 4.4e-16 of the value; a flipped exponent moves + # it by 12 %. + assert (control.safety, control.beta1, control.beta2) == (0.8, 0.12, -0.04) + expected = 0.8 * 2.0**0.12 * 4.0**-0.04 + assert control.propose([0.25, 0.5]) == pytest.approx(expected, rel=1e-15) + + def test_a_non_usable_previous_norm_falls_back_to_the_set_point(): control = make_controller(lag=0) at_set_point = control.propose([1.0, 0.5]) diff --git a/tests/test_adiabatic.py b/tests/test_adiabatic.py index f4e630d8e..a84fffc28 100644 --- a/tests/test_adiabatic.py +++ b/tests/test_adiabatic.py @@ -231,13 +231,18 @@ def test_an_abrupt_step_attains_the_reflection_bound(contrast): exact_reflection, exact_forward = fresnel_step(K0, K0 * math.sqrt(1 + contrast)) # A step's reflectance is the Fresnel value, which is tanh^2(Lambda) exactly: # the bound is attained, within the certificate's and the closed form's - # rounding. + # rounding. The closed form's k1 - k0 cancels to contrast/2 of k, which leaves + # 2 eps / contrast in the ratio and twice that in its square (5.5e-13 for the gas + # step); 8 eps / contrast keeps a margin of two. + closed_form = 8 * EPS / contrast assert admission.reflection == pytest.approx( - exact_reflection, rel=CERTIFICATE_ROUNDING + exact_reflection, rel=CERTIFICATE_ROUNDING + closed_form ) # The witness's jump transfer is exact; its integration of the flat pieces is # a phase only, so it reproduces the closed form to rounding. - assert wave.reflectance == pytest.approx(exact_reflection, rel=64 * EPS) + assert wave.reflectance == pytest.approx( + exact_reflection, rel=64 * EPS + closed_form + ) assert wave.forward_error == pytest.approx(exact_forward, rel=1e-12) assert_bounds_hold(admission, wave) diff --git a/tests/test_api_reference.py b/tests/test_api_reference.py new file mode 100644 index 000000000..e307b10b3 --- /dev/null +++ b/tests/test_api_reference.py @@ -0,0 +1,133 @@ +# SPDX-FileCopyrightText: 2026 John C. Travers and contributors +# +# SPDX-License-Identifier: GPL-3.0-or-later + +"""The API reference documents every public name, and only public names. + +The reference is one recursive autosummary whose module template decides what each +page documents. A name it leaves out raises no Sphinx warning, so a hole in the +reference is invisible to the docs build. This file renders the template for every +page, with the context the build gives it, reads the autodoc directives it writes, and +compares the objects they document with every public module's ``__all__``. +""" + +import importlib.util +import re +import sys +from pathlib import Path +from types import ModuleType, SimpleNamespace + +import pytest + +# The lowest-dependency lane installs no documentation tools. +AutosummaryRenderer = pytest.importorskip( + "sphinx.ext.autosummary.generate" +).AutosummaryRenderer + +DOCS = Path(__file__).resolve().parents[1] / "docs" +spec = importlib.util.spec_from_file_location("api_surface", DOCS / "api_surface.py") +assert spec is not None and spec.loader is not None +api_surface = importlib.util.module_from_spec(spec) +sys.modules[spec.name] = api_surface +spec.loader.exec_module(api_surface) + +DIRECTIVE = re.compile(r"^\.\. (auto\w+):: (\S+)$") + + +@pytest.fixture(scope="module") +def pages(): + """Return each page's module and the reStructuredText the template writes for it.""" + session_loaded = "solprop.sol" in sys.modules + modules = list(api_surface.public_modules()) + if not session_loaded: + # Importing the session namespace installs its logging and warning filter; + # the suite tests the library's defaults (conftest.py says why). + sys.modules["solprop.sol"].end_session() + renderer = AutosummaryRenderer( + SimpleNamespace( # pyright: ignore[reportArgumentType] - the renderer reads these + srcdir=DOCS, + config=SimpleNamespace(templates_path=["_templates"]), + translator=None, + ) + ) + members = api_surface.package_members() + rendered = [] + for module in modules: + submodules = sorted( + leaf + for parent, _, leaf in (other.__name__.rpartition(".") for other in modules) + if parent == module.__name__ + ) + context = { + "fullname": module.__name__, + "modules": submodules, + "package_members": members, + "attributes": [], + "functions": [], + "classes": [], + "exceptions": [], + } + rendered.append((module, renderer.render("autosummary/module.rst", context))) + return rendered + + +def _documented(module: ModuleType, text: str) -> list[tuple[str, object]]: + """The names and objects one rendered page documents.""" + lines = text.splitlines() + documented = [] + for index, line in enumerate(lines): + match = DIRECTIVE.match(line.strip()) + if match is None: + continue + directive, target = match.groups() + if directive == "automodule": + options = [] + for option in lines[index + 1 :]: + if not option.strip().startswith(":"): + break + options.append(option.strip()) + if ":no-members:" not in options: + documented += [(name, getattr(module, name)) for name in module.__all__] + elif directive != "autosummary": + home, name = target.rsplit(".", 1) + documented.append((name, getattr(sys.modules[home], name))) + return documented + + +def test_the_reference_documents_exactly_the_public_names(pages): + public = { + api_surface.object_key(name, getattr(module, name)): f"{module.__name__}.{name}" + for module, _ in pages + for name in getattr(module, "__all__", ()) + # A module's page is its own documentation; `__version__` is metadata. + if not isinstance(getattr(module, name), ModuleType) + and not name.startswith("__") + } + documented = { + api_surface.object_key(name, value): name + for module, text in pages + for name, value in _documented(module, text) + } + assert len(public) > 1000 # the walk found the package's surface + assert len(documented) > 1000 + missing = sorted(public[key] for key in public.keys() - documented.keys()) + assert missing == [], "public names the API reference does not document" + extra = sorted(documented[key] for key in documented.keys() - public.keys()) + assert extra == [], "names the API reference documents that no __all__ exports" + + +def test_a_package_page_documents_the_names_only_it_can(pages): + """The package pages that own names write them; the rest stay module lists.""" + text = {module.__name__: text for module, text in pages} + assert ( + ".. autofunction:: solprop.calibration.calibrate" in text["solprop.calibration"] + ) + assert ( + ".. autoclass:: solprop.driver.executors.Executor" + in text["solprop.driver.executors"] + ) + assert ( + ".. autofunction:: solprop.processing.example_output" + in text["solprop.processing"] + ) + assert ".. autoclass::" not in text["solprop.modes"] diff --git a/tests/test_beam_alignment.py b/tests/test_beam_alignment.py index 0c87bb67f..f50d1cf45 100644 --- a/tests/test_beam_alignment.py +++ b/tests/test_beam_alignment.py @@ -76,7 +76,7 @@ def test_every_frequency_of_a_tilted_beam_leaves_at_the_one_angle(): centroid = (space.k_x @ power[:, carried]) / np.sum(power[:, carried], axis=0) # Towards +x is the spectrum's -k_x side, as Alignment's tilt has it. angle = np.arcsin(-centroid / wavenumber) - assert np.allclose(angle, tilt, rtol=1e-3) + assert np.allclose(angle, tilt, rtol=1e-3, atol=0.0) @pytest.mark.parametrize( diff --git a/tests/test_benchmark_cases.py b/tests/test_benchmark_cases.py index d0386b479..0bff725ce 100644 --- a/tests/test_benchmark_cases.py +++ b/tests/test_benchmark_cases.py @@ -96,6 +96,9 @@ def test_fixed_step_cases_run_their_schedule_and_refuse_overrides(): assert len(schedule.steps) == 4 np.testing.assert_allclose(schedule.edges[-1], case.length, rtol=1e-12) assert simulation.settings.fields == "planes" + # Four steps are timed, not the route's default statistics at the observed plane. + assert simulation.settings.stats is not None + assert simulation.settings.stats.names == () @pytest.mark.parametrize( diff --git a/tests/test_benchmark_exercises.py b/tests/test_benchmark_exercises.py index 1b676a232..2496be3e0 100644 --- a/tests/test_benchmark_exercises.py +++ b/tests/test_benchmark_exercises.py @@ -79,6 +79,9 @@ def test_repeats_of_an_input_noise_run_reach_the_same_field(): assert result["repeat_difference"] <= 1e-12 +# The purpose-built smoke case (a 1e-4 m fibre on 192 points, "for testing the +# runner; not a workload") stays medium, as testing.md section 2 allows: it is not a +# registered benchmark workload, so these test the worker's logic, not a case. @pytest.mark.medium def test_each_repeat_checks_the_boundaries_with_a_monitor_of_its_own(monkeypatch): # What a user runs: Simulation.run attaches a fresh boundary monitor to every run. @@ -96,6 +99,9 @@ def recording(*args, **kwargs): assert monitors[0] is not monitors[1] +# The purpose-built smoke case (a 1e-4 m fibre on 192 points, "for testing the +# runner; not a workload") stays medium, as testing.md section 2 allows: it is not a +# registered benchmark workload, so these test the worker's logic, not a case. @pytest.mark.medium def test_each_repeat_counts_its_own_source_evaluations(): # The run's session loads the launch, which resets the backend's counters: each diff --git a/tests/test_benchmark_sessions.py b/tests/test_benchmark_sessions.py index 065de7b91..fd2e5eb40 100644 --- a/tests/test_benchmark_sessions.py +++ b/tests/test_benchmark_sessions.py @@ -19,8 +19,6 @@ from benchmarks.registry import CASES, Case, select from benchmarks.worker import measure -from solprop.exceptions import HostMarchWarning - backend = pytest.importorskip("solprop_native.backend") _counters = pytest.importorskip("solprop_native._counters") NativeBackend = backend.NativeBackend @@ -247,10 +245,9 @@ def test_a_narrow_and_a_wide_flow_march_natively(tmp_path): # Both keep the wall tutorials' walk-off absorber and its warning. Either build # steps a block of any width on the native Adams march, in the native session # (SEP 47 phase 4). - with warnings.catch_warnings(record=True) as caught: - warnings.simplefilter("always") + with warnings.catch_warnings(): + warnings.simplefilter("ignore") _, _, narrow = counted("taper_flow_4", tmp_path, fraction=1.0) _, _, wide = counted("taper_flow_17", tmp_path / "wide", fraction=1.0) - assert HostMarchWarning not in {type(item.message) for item in caught} for counts in (narrow, wide): assert counts["march_calls"].get("session_adams", 0) > 0 diff --git a/tests/test_boundaries.py b/tests/test_boundaries.py index 136f6c89c..e29c5ed3d 100644 --- a/tests/test_boundaries.py +++ b/tests/test_boundaries.py @@ -18,12 +18,9 @@ Absorber, SpatialAbsorber, absorber, - apply_band_mask, - apply_split_step, collar_rate, custom_absorber, nonlinear_absorber_term, - split_step_factor, temporal_collar_rate, warn_walkoff, ) @@ -80,7 +77,7 @@ def test_the_rate_reproduces_the_collar_over_one_reference_length(): alpha = collar_rate(window, length) # Nothing here is near the cap, so the round trip is exact to the rounding of a # logarithm and an exponential: a few units in the last place. - assert np.allclose(np.exp(-alpha * length / 2.0), window, rtol=8 * EPS) + assert np.allclose(np.exp(-alpha * length / 2.0), window, rtol=8 * EPS, atol=0.0) def test_the_rate_is_exactly_zero_in_the_flat_region(): @@ -118,50 +115,6 @@ def test_a_profile_outside_the_unit_interval_is_rejected(bad): collar_rate(bad, 0.1) -# ------------------------------------------------------------- rate semantics - - -@pytest.mark.parametrize("n_steps", [1, 10, 100, 1000]) -def test_the_absorption_depends_on_the_distance_and_not_on_the_subdivision(n_steps): - # The property the whole scheme exists for. A fixed profile multiplied in once per - # accepted step would give a total of W^n with n set by rtol. - alpha = collar_rate(np.array([1.0, 0.9, 0.5, 1e-3]), 0.075) - total = 0.3 - rng = np.random.default_rng(20260905) - steps = rng.random(n_steps) - steps *= total / steps.sum() - product = np.ones_like(alpha) - for step in steps: - product = product * split_step_factor(alpha, float(step)) - once = split_step_factor(alpha, total) - # n multiplications of doubles, each with half an ulp of rounding, give at worst - # n * eps; at n = 1000 that is 2e-13. - assert np.allclose(product, once, rtol=n_steps * EPS) - - -def test_the_split_factor_is_the_field_factor_not_the_power_factor(): - # alpha is a power coefficient, so the field carries alpha/2. Getting this wrong - # would make the temporal absorber twice as strong as the spectral one built from - # the same profile. - alpha = collar_rate(np.array([0.5]), 0.075) - factor = float(split_step_factor(alpha, 0.075)[0]) - assert factor == pytest.approx(0.5, rel=8 * EPS) - assert factor**2 == pytest.approx(math.exp(-float(alpha[0]) * 0.075), rel=8 * EPS) - - -def test_a_zero_step_leaves_the_field_alone(): - alpha = collar_rate(np.array([1.0, 0.5]), 0.075) - field = np.array([[1.0 + 2.0j, 3.0 - 1.0j]]) - # An explicitly exact no-op: a zero step multiplies by exp(0) = 1. - assert np.array_equal(apply_split_step(field, alpha, 0.0), field) - - -@pytest.mark.parametrize("bad", [-1e-3, math.inf, math.nan]) -def test_a_bad_step_is_rejected(bad): - with pytest.raises(GridError, match="step must be non-negative"): - split_step_factor(collar_rate(np.array([0.5]), 0.075), bad) - - # ------------------------------------------- the two ADR-025 applications @@ -175,7 +128,7 @@ def test_the_two_temporal_applications_agree_to_first_order_in_the_step(): field = np.array([1.0, 1.0, 1.0]) def deviation(step): - exact = apply_split_step(field, alpha, step) + exact = field * np.exp(-0.5 * alpha * step) euler = field + step * nonlinear_absorber_term(field, alpha) return float(np.max(np.abs(exact - euler))) @@ -192,33 +145,16 @@ def test_the_in_term_is_the_derivative_of_the_split_factor(): alpha = collar_rate(np.array([0.9, 0.5]), 0.075) field = np.array([2.0 + 1.0j, -1.0 + 0.5j]) step = 1e-9 - numerical = (apply_split_step(field, alpha, step) - field) / step - assert np.allclose(numerical, nonlinear_absorber_term(field, alpha), rtol=1e-6) + numerical = (field * np.exp(-0.5 * alpha * step) - field) / step + assert np.allclose( + numerical, nonlinear_absorber_term(field, alpha), rtol=1e-6, atol=0.0 + ) -def test_both_applications_broadcast_over_the_leading_axes(): +def test_the_in_term_broadcasts_over_the_leading_axes(): alpha = collar_rate(np.linspace(0.2, 1.0, 8), 0.075) field = np.ones((2, 3, 8), dtype=complex) - assert apply_split_step(field, alpha, 0.01).shape == (2, 3, 8) assert nonlinear_absorber_term(field, alpha).shape == (2, 3, 8) - assert np.allclose( - apply_split_step(field, alpha, 0.01)[0, 0], split_step_factor(alpha, 0.01) - ) - - -# ---------------------------------------------------------------- the hard mask - - -def test_the_hard_band_mask_is_idempotent(): - # Why it stays a per-step 0/1 multiply rather than becoming a rate: applying it any - # number of times gives the same answer, exactly (a hard mask, a structural zero). - rng = np.random.default_rng(11) - spectrum = rng.normal(size=(2, 16)) + 1j * rng.normal(size=(2, 16)) - mask = rng.random(16) > 0.4 - once = apply_band_mask(spectrum, mask) - assert np.array_equal(apply_band_mask(once, mask), once) - assert np.array_equal(once[:, ~mask], np.zeros((2, int(np.sum(~mask))))) - assert np.array_equal(once[:, mask], spectrum[:, mask]) # ------------------------------------------------------------- from a grid @@ -236,8 +172,14 @@ def test_the_absorber_reproduces_the_collars_over_one_reference_length( # is deliberately zeroed rather than capped. The temporal rates are not the # logarithm; the tests below say what they are. unclamped = (window > math.exp(-MAX_ALPHA_LENGTH / 2.0)) & (rate > 0.0) + # exp(log(W)) carries the logarithm's rounding times |log W|, its condition + # number: 24 eps at W = 2e-13, deep in the collar. + kept = window[unclamped] assert np.allclose( - np.exp(-rate[unclamped] * length / 2.0), window[unclamped], rtol=8 * EPS + np.exp(-rate[unclamped] * length / 2.0), + kept, + rtol=(8 + np.abs(np.log(kept))) * EPS, + atol=0.0, ) @@ -885,3 +827,26 @@ def test_the_split_scheme_removes_the_same_light(): def test_the_temporal_profile_rejects_a_bad_reference_length(bad): with pytest.raises(GridError, match="reference_length must be positive"): temporal_collar_rate(np.array([0.0]), Collar(-2.0, -1.0, 1.0, 2.0), bad) + + +def test_the_walk_off_warning_names_the_line_outside_solprop(field_grid): + # The route calls warn_walkoff from inside the package; the warning must still name + # the user's line, not the route's. The call is compiled as if it sat in a package + # module, so a fixed stacklevel would stop there. + import inspect # noqa: PLC0415 + from pathlib import Path # noqa: PLC0415 + + import solprop # noqa: PLC0415 + + package = Path(solprop.__file__).resolve().parent + frame = compile( + "warn_walkoff(grid, 2e-12)", + str(package / "driver" / "routes" / "caller.py"), + "exec", + ) + # The session's jaxtyping hook wraps every solprop function in a frame of its own, + # outside the package, where the walk would stop; a user's session has none. + namespace = {"warn_walkoff": inspect.unwrap(warn_walkoff), "grid": field_grid} + with pytest.warns(SolpropWarning, match="wrapping around") as caught: + exec(frame, namespace) + assert [w.filename for w in caught] == [__file__] diff --git a/tests/test_check_skips.py b/tests/test_check_skips.py index 2845c79f5..e14693f19 100644 --- a/tests/test_check_skips.py +++ b/tests/test_check_skips.py @@ -39,9 +39,9 @@ def test_an_expected_reason_and_a_pass_are_clean(tmp_path, capsys): assert "0 unexpected" in capsys.readouterr().out -def test_a_commit_hash_varies_and_nothing_else_does(tmp_path): - good = skip("93e8ee6a2376 is not in this checkout (squashed or rebased)") - bad = skip("93e8ee6a is not in this checkout (squashed or rebased)") +def test_a_pattern_s_variable_part_varies_and_nothing_else_does(tmp_path): + good = skip("the scripted executor does not run a multistep march") + bad = skip("the scripted executor cannot run a multistep march") path = junit(tmp_path, ("good", good), ("bad", bad)) assert [name for name, _ in check_skips.unexpected_skips(path)] == [ "tests.test_x::test_bad" diff --git a/tests/test_ci_changes.py b/tests/test_ci_changes.py index 32e20322b..4d65a9566 100644 --- a/tests/test_ci_changes.py +++ b/tests/test_ci_changes.py @@ -2,7 +2,7 @@ # # SPDX-License-Identifier: GPL-3.0-or-later -"""The CI change filter that decides whether the device compilation lanes run.""" +"""The CI change filter that decides which lanes run and whether the device lanes do.""" import os import subprocess @@ -39,6 +39,40 @@ def _device(directory: Path, changed: str | None, *, pipefail: bool) -> str: return output.read_text(encoding="utf-8") +def _lanes(directory: Path, changed: str) -> str: + """Run the workflow's lane choice on a change list; return the lanes it picks.""" + workflow = WORKFLOW.read_text(encoding="utf-8") + start = workflow.index(" if ! grep -qvE '^docs/") + end = workflow.index("\n fi\n", start) + len("\n fi\n") + (directory / "changed.txt").write_text(changed, encoding="utf-8") + script = f'lanes=full\n{textwrap.dedent(workflow[start:end])}echo "$lanes"\n' + result = subprocess.run( + ["bash", "-e", "-o", "pipefail", "-c", script], + cwd=directory, + check=True, + capture_output=True, + text=True, + ) + return result.stdout.strip() + + +@pytest.mark.parametrize( + "changed,expected", + [ + ("docs/index.md\nREADME.md\n", "docs"), + ("gui/src/solprop_gui/app.py\ndocs/guide/index.md\n", "gui"), + # The front end's tests read its chapter of the user guide. + ("docs/guide/front-end/index.md\n", "gui"), + # solprop's release tests read the front end's project table. + ("gui/pyproject.toml\n", "full"), + ("gui/src/solprop_gui/app.py\ngui/pyproject.toml\n", "full"), + ("src/solprop/grid.py\ndocs/index.md\n", "full"), + ], +) +def test_lane_filter_runs_the_tests_that_read_each_change(tmp_path, changed, expected): + assert _lanes(tmp_path, changed) == expected + + @pytest.mark.parametrize("pipefail", [False, True]) def test_device_filter_selects_native_change_first_in_large_list(tmp_path, pipefail): # The match comes first and the list is long enough that a reader stopping at it diff --git a/tests/test_convergence_records.py b/tests/test_convergence_records.py index 7c32817d8..441dada12 100644 --- a/tests/test_convergence_records.py +++ b/tests/test_convergence_records.py @@ -9,9 +9,10 @@ write the records: * the files parse and describe what they claim to describe; -* every row names a commit on this tree's own line of history, and a test that still - exists -- so a renamed writer or a row from an abandoned branch is caught here rather - than surviving as a number on the accuracy page that nothing reproduces; +* every row names a commit on this tree's own line of history (or one of the commits + measured before its public history began), and a test that still exists -- so a + renamed writer or a row from an abandoned branch is caught here rather than + surviving as a number on the accuracy page that nothing reproduces; * the write gate refuses everything it is supposed to refuse. """ @@ -137,13 +138,43 @@ def test_the_file_on_disk_is_formatted_the_way_the_writer_writes_it(stored): # -------------------------------------------------------------- the provenance +# The commits the stored records were measured at before this repository's public +# history begins: no clone of it holds them, so they cannot be placed on its line of +# history. A record measured again is stamped with a commit that can, and its old +# commit then leaves this list, which may only shrink. +BEFORE_PUBLIC_HISTORY = frozenset( + { + "0d140a277a5a471c564adf45b006ebac7cd88339", + "0d44e0148cd90feeded94dfbc67aaf0dc8fa4755", + "14a9ea96faa85dc5386b2709765642ee30242fe2", + "14d18f3f9fd5ab97e01683c062a609a728b67963", + "182f7ac7bcd0047fce324394eff16528a98da60f", + "2005f96d77c2d7d508cf21dc443fb41794aa8aac", + "30d03b4a456303e6935a1040e310d9d286008c3f", + "5577d091f899d40ab10ea23ad2006c75f79fca4e", + "6665cc804ce844c951e357f041a8c0b666f376c2", + "678b8d0c84ac3c88a15c0ea199b8989c3915fd34", + "782cb766d03477a59cb94507a355a2ebbe2a17f8", + "7fc63c9186a39331811f099607000cb9687bd0ea", + "92e9b576671a0ea28731e47a9989e95bb433b7c7", + "93e8ee6a2376b69d02db74dceaea4abf05a91699", + "9bc569d1378dea180158480752beb35e1f98c1cf", + "adcdaccc60133bd34435a71a4713964279551fc0", + "b2b2e0da16c94ebd50f31c77931888944b1456e1", + "b71045467c6c14c5c790a12431896c1cef98e799", + "c3c8cbc73c4abf921306ac688a955884de83fe4e", + "d9f9f413f83207d1466bfeb0de8402fe589057cd", + } +) + + def test_every_recorded_commit_is_on_this_tree_s_line_of_history(stored): """A row measured on an unrelated branch is a number nothing here reproduces. Asserted both ways round rather than "is an ancestor of HEAD": under ``git bisect`` HEAD legitimately predates the record, and on a pull request HEAD is a merge commit the record is an ancestor of. What it still rejects is a record from a branch this - one never touched. + one never touched, or from one squashed or rebased away. """ if git("rev-parse", "HEAD") is None: pytest.skip("not a git checkout") @@ -152,16 +183,26 @@ def test_every_recorded_commit_is_on_this_tree_s_line_of_history(stored): for write in stored["writes"]: commit = write["commit"] assert commit is not None, stored["study"] + if commit in BEFORE_PUBLIC_HISTORY: + continue present = subprocess.run( ["git", "-C", str(cr.REPO), "cat-file", "-e", f"{commit}^{{commit}}"], capture_output=True, check=False, ) - if present.returncode != 0: - pytest.skip(f"{commit[:12]} is not in this checkout (squashed or rebased)") + assert present.returncode == 0, ( + f"{stored['study']}: {commit[:12]} is not in this checkout" + ) assert _related(commit, "HEAD"), f"{stored['study']}: {commit[:12]}" +def test_the_list_of_commits_before_the_public_history_only_shrinks(): + recorded = { + write["commit"] for study in cr.studies() for write in cr.load(study)["writes"] + } + assert recorded >= BEFORE_PUBLIC_HISTORY, sorted(BEFORE_PUBLIC_HISTORY - recorded) + + def _related(one, other): def ancestor(first, second): return ( diff --git a/tests/test_decisions.py b/tests/test_decisions.py new file mode 100644 index 000000000..e9b266a11 --- /dev/null +++ b/tests/test_decisions.py @@ -0,0 +1,65 @@ +# SPDX-FileCopyrightText: 2026 John C. Travers and contributors +# +# SPDX-License-Identifier: GPL-3.0-or-later + +"""Keep the decision log's amendments visible from both records. + +``docs/dev/decisions.md`` says that where a later record changes part of an earlier +one, both say so. When a record's status says it amends or supersedes another, the +earlier record's status, or its ``Now:`` line, must name the later one, so a reader of +the earlier record learns it no longer stands alone. +""" + +import re +from pathlib import Path + +DECISIONS = Path(__file__).resolve().parents[1] / "docs" / "dev" / "decisions.md" +RECORD = re.compile(r"^## (ADR-\d{3}) — ", re.MULTILINE) +# The later record's own claim: "amends ADR-033", "supersedes the interval cap of +# ADR-004 ...", up to the clause's end. +CLAIM = re.compile(r"\b(?:amends|supersedes)\b([^;]*)") + + +def _field(body: str, name: str) -> str: + """Return a record's bullet `name` as one line, or an empty string.""" + found = re.search( + rf"^- \*\*{name}:\*\*(.*?)(?=^- \*\*|\Z)", body, flags=re.MULTILINE | re.DOTALL + ) + return " ".join(found.group(1).split()) if found else "" + + +def _records() -> dict[str, str]: + """Return each record's body by its number.""" + parts = RECORD.split(DECISIONS.read_text(encoding="utf-8")) + return dict(zip(parts[1::2], parts[2::2], strict=True)) + + +def _claims(records: dict[str, str]) -> list[tuple[str, str]]: + """Return ``(later, earlier)`` for every amendment a record's status claims.""" + found = [] + for later, body in records.items(): + for claim in CLAIM.finditer(_field(body, "Status")): + clause = claim.group(1).split(". ")[0] + found += [ + (later, earlier) + for earlier in re.findall(r"ADR-\d{3}", clause) + if earlier != later + ] + return found + + +def test_an_amended_record_names_the_record_that_amends_it(): + records = _records() + claims = _claims(records) + # The log holds more than twenty such claims; finding none would mean the parser, + # not the log, had changed. + assert len(claims) > 20, claims + unknown = sorted({earlier for _, earlier in claims} - records.keys()) + assert not unknown, f"amendments of records the log does not hold: {unknown}" + missing = [ + f"{later} amends or supersedes {earlier}, whose status does not name it" + for later, earlier in claims + if later + not in _field(records[earlier], "Status") + _field(records[earlier], "Now") + ] + assert not missing, "\n".join(missing) diff --git a/tests/test_display.py b/tests/test_display.py index 0de89ecd4..ca19f66c8 100644 --- a/tests/test_display.py +++ b/tests/test_display.py @@ -10,7 +10,6 @@ import warnings from dataclasses import replace from pathlib import Path -from typing import Any import numpy as np import pytest @@ -20,8 +19,6 @@ assert_record_numbers, record_skeleton, skeleton_hash, - with_former_names, - without_sep21_absorber, ) from solprop import _display, tools from solprop.coupling import AdmissionItem, CouplingReport @@ -56,7 +53,7 @@ from solprop.modes.tables import sample_modal_table from solprop.nonlinear.raman import SilicaTensorResponse from solprop.optics import Chain, ChirpedMirror, Material, TaylorPhase -from solprop.output.hdf5 import open_file, resume +from solprop.output.hdf5 import open_file, read_resume_state from solprop.output.records import StepHistory from solprop.physdata import Mixture, calcium_fluoride, species from solprop.physdata.mixtures import Component @@ -397,7 +394,7 @@ def build_examples(folder): "SimulationSettings": sim.settings, "MemoryOutput": run, "HDF5Output": open_file(folder / "run.h5"), - "ResumeState": resume(folder / "run.h5"), + "ResumeState": read_resume_state(folder / "run.h5"), "ScanOutput": scan_output(folder / "scan.h5"), "RunMetadata": run.metadata, "SavedPlane": plane, @@ -597,14 +594,16 @@ def test_the_reprs_that_existed_keep_their_text(examples): assert repr(examples["VincettiMode"]) == ( "VincettiMode(HE11, a=15 um, t=180 nm, r_ext=9 um, N=6, Ar 1 bar, loss=model)" ) - assert repr(examples["IndexTable"]) == "IndexTable(64 rows, 400-2000 nm, loss=log)" + assert repr(examples["IndexTable"]) == ( + "IndexTable(64 rows, 400-2000 nm, loss_interpolation=log)" + ) assert repr(examples["TabulatedMode"]) == ( - "TabulatedMode(HE11, a=15 um, None, pressure=0.0, " - "IndexTable(64 rows, 400-2000 nm, loss=log))" + "TabulatedMode(HE11, a=15 um, evacuated, loss=model, " + "IndexTable(64 rows, 400-2000 nm, loss_interpolation=log))" ) assert repr(examples["TabulatedHollowMode"]) == ( - "TabulatedHollowMode(HE11, a=15 um, Ar, pressure=1.0, " - "IndexTable(64 rows, 400-2000 nm, loss=log))" + "TabulatedHollowMode(HE11, a=15 um, Ar 1 bar, loss=model, " + "IndexTable(64 rows, 400-2000 nm, loss_interpolation=log))" ) assert repr(MarcatiliMode(50e-6)) == ( "MarcatiliMode(HE11, a=50 um, evacuated, model=full, loss=model)" @@ -642,65 +641,25 @@ def without_optmat_release(value: object, *, materials: bool = False) -> object: return value -RUN_RECORD_SKELETON = "2634b5a114d9ccfbb2c40a2d945c95f7ec2b22c28755da6798a831ac735fb975" -"""The structure of the example run's record, as the projection below takes it.""" - - -def test_the_run_record_is_what_it_was_before_the_printing(examples): - # The run record, without what an optmat release writes into it, is what it was - # when the printing was added, less what was added to the record since, which - # the projection here takes back out: the launch position, the TDSE descriptor, - # the transverse quadrature, the norm's region in the controller, the - # interaction formulation's name in an Adams method's representation, the - # held-current identity, whose record and hash - # separation have their own held-source contract test, the absorber's spatial - # flag (SEP 21), and the names later renames changed (with_former_names). - # Every built-in material is optmat's since SEP 3, so the manifest is never - # empty here. - # - # Since the pin to optmat 0.8.0 the optmat version, the citations and the - # manifest's model digests are neutralised (without_optmat_release), so that only a - # change to solprop's record, or to a number in it, fails here. The record was a - # single SHA-256 literal until SEP 25; that hash also covered the last bits of its - # derived numbers, which a platform's libm moves. Its structure is still hashed - # exactly (identity metadata); its numbers are stored beside this test and - # compared to RECORD_RTOL. +RUN_RECORD_SKELETON = "980bd76c7bf1793a20b6e1c15151ecd88c357847c09fab9c6f165ac70ce8a4c4" +"""The structure of the example run's record, without what an optmat release writes.""" + + +def test_the_run_record_keeps_its_structure_and_numbers(examples): + # The run record, less what an optmat release writes into it + # (without_optmat_release), is pinned in two parts: its structure is identity + # metadata and is hashed exactly; its numbers, whose last bits a platform's libm + # moves, are stored beside this test and compared to RECORD_RTOL. Every built-in + # material is optmat's, so the manifest is never empty here. metadata = quiet(examples["Simulation"].metadata) assert not metadata.materials.empty - hashed: dict[str, Any] = metadata.hashed() - # Output schemas 2 and 3 change only `DataPulse` and a march snapshot, which this - # run does not hold. - hashed["schema_version"] = 1 - for later in ("initial_z", "tdse", "quadrature"): - del hashed[later] - hashed["configuration"] = { - key: value - for key, value in hashed["configuration"].items() - if key != "plasma_source" - } - # A pulse's Taylor coefficients were its `phase` field before they took the - # drivers' name. - pulse = dict(hashed["configuration"]["pulse"]) - pulse = {("phase" if key == "phases" else key): item for key, item in pulse.items()} - hashed["configuration"]["pulse"] = pulse - stepper = dict(hashed["stepper"]) - stepper["controller"] = { - key: value for key, value in stepper["controller"].items() if key != "region" - } - if isinstance(stepper["method"], str): - stepper["method"] = stepper["method"].replace( - ", formulation='interaction'", "", 1 - ) - hashed["stepper"] = stepper - skeleton, values, floor = record_skeleton( - with_former_names(without_optmat_release(without_sep21_absorber(hashed))) - ) + skeleton, values, floor = record_skeleton(without_optmat_release(metadata.hashed())) assert skeleton_hash(skeleton) == RUN_RECORD_SKELETON assert_record_numbers( values, floor, Path(__file__).with_suffix("") - / "test_the_run_record_is_what_it_was_before_the_printing.npz", + / "test_the_run_record_keeps_its_structure_and_numbers.npz", ) @@ -708,7 +667,7 @@ def test_the_run_record_names_its_power_convention(examples): # The amplitude label is part of what a file means, so the block prints it beside # the spectral convention and the output schema. metadata = quiet(examples["Simulation"].metadata) - assert "optics spectra, poynting amplitudes, schema 4" in str(metadata) + assert "optics spectra, poynting amplitudes, schema 3" in str(metadata) def test_a_mode_built_over_a_mixture_names_its_fill(): @@ -772,7 +731,7 @@ def test_an_hdf5_output_says_what_state_its_file_is_in(tmp_path): assert "closed, read-only" in repr(handler) # A closed handler still reads its file, one read at a time. assert "0 m to 100 mm" in str(handler) - state = resume(path) + state = read_resume_state(path) assert repr(state).startswith("ResumeState(5 planes saved") assert "last plane" in str(state) path.unlink() diff --git a/tests/test_display/test_the_run_record_is_what_it_was_before_the_printing.npz b/tests/test_display/test_the_run_record_is_what_it_was_before_the_printing.npz deleted file mode 100644 index 26e5d1d55..000000000 Binary files a/tests/test_display/test_the_run_record_is_what_it_was_before_the_printing.npz and /dev/null differ diff --git a/tests/test_display/test_the_run_record_keeps_its_structure_and_numbers.npz b/tests/test_display/test_the_run_record_keeps_its_structure_and_numbers.npz new file mode 100644 index 000000000..da4088ee1 Binary files /dev/null and b/tests/test_display/test_the_run_record_keeps_its_structure_and_numbers.npz differ diff --git a/tests/test_far_field_statistics.py b/tests/test_far_field_statistics.py index 116d7427c..60c5e37be 100644 --- a/tests/test_far_field_statistics.py +++ b/tests/test_far_field_statistics.py @@ -252,7 +252,10 @@ def test_profile_and_correction_refusals(): # check is what a caller outside it meets. with pytest.raises(OutputError, match="unknown aperture profile"): check_aperture_profile("square") - with pytest.raises(OutputError, match="unknown aperture weighting"): + # The choices of a spec's apertures are refused as a malformed spec. + with pytest.raises(ProcessingError, match="unknown aperture profile"): + check_aperture_choices("square", "amplitude") + with pytest.raises(ProcessingError, match="unknown aperture weighting"): check_aperture_choices("tanh", "intensity") check_aperture_choices("hard", "amplitude") with pytest.raises(OutputError, match="half-width"): @@ -806,11 +809,11 @@ def test_a_slit_on_a_line_and_its_refusals(grid): assert_within(values["aperture_spectrum"][0], values["beam_spectrum"], 1e-12) assert_within(values["region_spectrum"][0], values["beam_spectrum"], gamma(256)) off_axis = ApertureSet(centres=[[0.0, 1e-3]], diameters=[1e-3], distances=[0.25]) - with pytest.raises(OutputError, match="y centre must be zero"): + with pytest.raises(ProcessingError, match="y centre must be zero"): aperture_tables( StatsSpec(names=("aperture_spectrum",), apertures=off_axis), grid, space ) - with pytest.raises(OutputError, match="would select nothing"): + with pytest.raises(ProcessingError, match="would select nothing"): aperture_tables( StatsSpec( names=("region_spectrum",), @@ -873,7 +876,7 @@ def apertures(**changes): ], ) def test_an_aperture_set_refuses_by_name(changes, message): - with pytest.raises(OutputError, match=message): + with pytest.raises(ProcessingError, match=message): apertures(**changes) @@ -1571,12 +1574,12 @@ def half_plane_options(**changes): ], ) def test_a_shaped_set_refuses_by_name(options, message): - with pytest.raises(OutputError, match=message): + with pytest.raises(ProcessingError, match=message): ApertureSet(**options) def test_a_mixed_set_refuses_an_edge_on_a_hard_row_and_a_circle_without_a_diameter(): - with pytest.raises(OutputError, match="give zero on its row"): + with pytest.raises(ProcessingError, match="give zero on its row"): ApertureSet( centres=[[0.0, 0.0]] * 2, diameters=[1e-3] * 2, @@ -1584,14 +1587,14 @@ def test_a_mixed_set_refuses_an_edge_on_a_hard_row_and_a_circle_without_a_diamet edges=[1e-4, 1e-4], profiles=("hard", "rcos"), ) - with pytest.raises(OutputError, match="positive"): + with pytest.raises(ProcessingError, match="positive"): ApertureSet( centres=[[0.0, 0.0]] * 2, diameters=[0.0, 0.0], distances=[DISTANCE] * 2, shapes=("circle", "half_plane_x_ge"), ) - with pytest.raises(OutputError, match="needs edges"): + with pytest.raises(ProcessingError, match="needs edges"): ApertureSet( centres=[[0.0, 0.0]] * 2, diameters=[1e-3] * 2, @@ -1675,5 +1678,5 @@ def test_line_routes_refuse_what_has_no_meaning_uniform_in_y(grid, shape, extent names=("aperture_spectrum",), apertures=set_of((shape,), [[0.0, 0.0]], extents=extents), ) - with pytest.raises(OutputError, match="has no meaning there"): + with pytest.raises(ProcessingError, match="has no meaning there"): aperture_tables(spec, grid, space) diff --git a/tests/test_gasflow.py b/tests/test_gasflow.py index 1b2cb2e16..ad512754c 100644 --- a/tests/test_gasflow.py +++ b/tests/test_gasflow.py @@ -491,7 +491,7 @@ def test_the_throughput_is_the_poiseuille_law(): assert taper == pytest.approx(expected, rel=1e-12) with pytest.raises(TranslationError, match="length"): throughput("N2", 1e-4, 0.0, 1.0, 0.0) - with pytest.raises(TranslationError, match="start_bar"): + with pytest.raises(TranslationError, match="start_pressure"): throughput("N2", 1e-4, 1.0, -1.0, 0.0) diff --git a/tests/test_geometry_figures.py b/tests/test_geometry_figures.py index 7819e2d14..9fe0db665 100644 --- a/tests/test_geometry_figures.py +++ b/tests/test_geometry_figures.py @@ -13,11 +13,10 @@ shown. All three are checked here, in the fast lane. The script keeps the page's section headings beside the figures as data, together with -the sections a later slice will fill (``PENDING``) and the ones that are about every -decomposition (``UNFIGURED``), so a new section on the page has to be declared in one of -the three. The redraw comparison is skipped when the drawing library is absent -- it is -a dev-group dependency -- and the page checks are not, because they need only the -committed files and the script's data. +the ones that are about every decomposition (``UNFIGURED``), so a new section on the +page has to be declared in one of the two. The redraw comparison is skipped when the +drawing library is absent -- it is a dev-group dependency -- and the page checks are +not, because they need only the committed files and the script's data. The script is loaded by path, as `tests/test_structure_figures.py` loads the structure figures' script. @@ -57,9 +56,9 @@ def page_sections() -> dict[str, str]: def test_every_section_of_the_page_is_declared_by_the_script(): - """A section is a figure's, a later slice's, or about every decomposition.""" + """A section is a figure's, or about every decomposition.""" declared = {figure.section for figure in geometries.FIGURES.values()} - declared |= set(geometries.PENDING) | set(geometries.UNFIGURED) + declared |= set(geometries.UNFIGURED) assert set(page_sections()) == declared @@ -77,19 +76,12 @@ def test_every_figure_is_shown_in_its_own_section_and_only_there(name): assert elsewhere == [] -@pytest.mark.parametrize("heading", [*geometries.PENDING, *geometries.UNFIGURED]) +@pytest.mark.parametrize("heading", geometries.UNFIGURED) def test_sections_without_a_figure_show_none(heading): - """A placeholder gains its figure with its slice, and moves into FIGURES then.""" + """A section about every decomposition shows no decomposition's figure.""" assert SHOWN.findall(page_sections()[heading]) == [] -def test_the_placeholders_name_the_slice_that_fills_them(): - """A placeholder says which slice replaces it, as the script declares.""" - sections = page_sections() - for heading, slice_name in geometries.PENDING.items(): - assert slice_name in sections[heading] - - def test_every_committed_svg_is_a_figure_the_script_draws(): """No orphan SVG beside the script, and none missing.""" committed = {path.stem for path in FIGURES.glob("*.svg")} diff --git a/tests/test_grid.py b/tests/test_grid.py index 302765984..96223ba4b 100644 --- a/tests/test_grid.py +++ b/tests/test_grid.py @@ -524,6 +524,36 @@ def test_from_limits_rejects_bad_keywords(factory, keywords, message): factory.from_limits(**RDW, **keywords) +@pytest.mark.parametrize("ffac", [2.0, 2.1, 2.19]) +def test_a_field_grid_refuses_an_ffac_that_leaves_its_nyquist_bin_live(ffac): + # Below 2.2 the fine Nyquist frequency, ffac omega_max / 2, falls short of the + # collar's foot at 1.1 omega_max, so the coarse Nyquist bin would keep field. + with pytest.raises(GridError, match=r"ffac must be at least 2\.2") as caught: + FieldGrid.from_limits(**RDW, ffac=ffac) + assert caught.value.parameter == "ffac" + assert "Nyquist" in str(caught.value) + + +@pytest.mark.parametrize( + ("limits", "trange"), + [ + (RDW["wavelength_limits"], RDW["trange"]), + # Limits where, at ffac = 2.2, rounding leaves the fine Nyquist frequency an + # ulp below 1.1 omega_max, so the taper there would be about 1e-305, not zero. + ((90e-9, 1e-6), 1e-12), + ((100e-9, 2e-6), 40e-15), + ], +) +def test_the_smallest_admitted_ffac_zeroes_both_end_bins(limits, trange): + grid = FieldGrid.from_limits(1.0, 800e-9, limits, trange, ffac=2.2) + assert grid.n_t == grid.n_to # the coarse grid is the whole fine grid + # Exactly zero, as every Fourier identity on the stored spectrum assumes. + assert grid.omega_window[0] == 0.0 + assert grid.omega_window[-1] == 0.0 + assert not grid.active_mask[0] + assert not grid.active_mask[-1] + + @pytest.mark.parametrize("factory", [FieldGrid, EnvelopeGrid]) @pytest.mark.parametrize( ("limits", "message"), @@ -572,6 +602,21 @@ def test_validate_catches_a_corrupted_grid(changes, message): corrupt(grid, **changes).validate() +@pytest.mark.parametrize("end", ["zero frequency", "Nyquist"]) +def test_validate_catches_a_collar_that_leaves_an_end_bin_live(end): + grid = FieldGrid.from_limits(1.0, 800e-9, (400e-9, 2e-6), 40e-15) + collar = grid.omega_collar + if end == "Nyquist": + wider = dataclasses.replace(collar, zero_high=1.1 * grid.omega[-1]) + else: + wider = dataclasses.replace(collar, zero_low=-collar.one_low) + # dataclasses.replace rebuilds the grid without validating it. + rebuilt = dataclasses.replace(grid, omega_collar=wider) + assert rebuilt.omega_window[0 if end == "zero frequency" else -1] > 0.0 + with pytest.raises(GridError, match=f"vanish at the {end} bin"): + rebuilt.validate() + + def test_validate_catches_a_fine_grid_that_is_not_a_multiple_of_the_coarse_one(): grid = FieldGrid.from_limits(1.0, 800e-9, (400e-9, 2e-6), 40e-15) shrunk = grid.n_to - 2 # still even and consistent, but no longer a multiple of n_t @@ -628,7 +673,7 @@ def test_the_base_grid_has_no_layout_of_its_own(): wavelength_low=st.floats(min_value=90e-9, max_value=700e-9), span=st.floats(min_value=2.0, max_value=40.0), trange=st.floats(min_value=20e-15, max_value=800e-15), - ffac=st.sampled_from([2.0, 4.0, 6.0]), + ffac=st.floats(min_value=2.2, max_value=6.0), fft_size=st.sampled_from(["pow2", "smooth"]), collar_fraction=st.floats(min_value=0.01, max_value=0.45), ) @@ -659,10 +704,15 @@ def test_every_grid_satisfies_its_invariants( assert grid.t_collar.width_low > 0.0 assert grid.t_collar.width_high > 0.0 # The coarse grid reaches the apodised window edge, or as near it as the fine grid - # allows: at ffac = 2 the fine Nyquist is omega_max itself, below the collar's foot. + # allows. reach = min(grid.omega_max_window, grid.omega_fine.max()) assert grid.omega.max() >= reach - grid.d_omega assert grid.active_mask.any() + if factory is FieldGrid: + # A field grid's end bins carry no field: its Nyquist bin is at or past the + # collar's foot. + assert grid.omega[-1] >= grid.omega_max_window + assert grid.omega_window[0] == grid.omega_window[-1] == 0.0 @given( diff --git a/tests/test_identity.py b/tests/test_identity.py index 410d70a59..f5b3bfea4 100644 --- a/tests/test_identity.py +++ b/tests/test_identity.py @@ -61,7 +61,7 @@ def test_a_numpy_scalar_is_written_as_the_number_it_holds(): [ ( "metadata", - "2b40497b0568b50ed1e22618abcda633424df5e851ab5a5fe0ba435932066848", + "7cf89527a88bf97f031f79b4447ec19cb89639e78db71e9c930b8fbd7717d8fe", ), ("scan", "80f9c7ee2c67bb3246215ab42ce1d49fa0cb9f93e774cd9b2d543229b4ae335b"), ("basis", "d7b11decb56fec6a504280a7c9e26f83c5f33d84fa111aa9a9b27f9e87481587"), diff --git a/tests/test_log.py b/tests/test_log.py index 5292f461c..d56601500 100644 --- a/tests/test_log.py +++ b/tests/test_log.py @@ -822,3 +822,41 @@ def test_an_echoed_line_goes_to_standard_error_without_a_stream(capsys): reporter = BarReporter(logger=logger, clock=Clock()) reporter.summary("Starting propagation") assert capsys.readouterr().err == "Starting propagation\n" + + +def test_a_refused_progress_setting_is_a_solprop_error(): + from solprop.exceptions import DriverError # noqa: PLC0415 + + # Past the session's annotation check, as production calls them. + with pytest.raises(DriverError, match="progress must be one of"): + unwrap(set_default_progress)("loud") + with pytest.raises(DriverError, match="progress must be one of"): + unwrap(default_reporter)(choice="loud") + with pytest.raises(DriverError, match="positive and finite"): + BarReporter(file=io.StringIO(), period=0.0) + + +def test_the_log_file_is_written_as_utf8(tmp_path, monkeypatch): + # Asked for by name: under Python's UTF-8 mode the locale default would hide it. + asked = {} + + class Recording(logging.FileHandler): + def __init__(self, *args, **kwargs): + asked.update(kwargs) + super().__init__(*args, **kwargs) + + monkeypatch.setattr(logging, "FileHandler", Recording) + package = logging.getLogger("solprop") + previous_handlers, previous_level = package.handlers[:], package.level + package.handlers = [] + try: + configure_logging(file=tmp_path / "log.txt") + (handler,) = package.handlers + assert isinstance(handler, Recording) + assert asked.get("encoding") == "utf-8" + assert handler.encoding == "utf-8" + finally: + for handler in package.handlers: + handler.close() + package.handlers = previous_handlers + package.setLevel(previous_level) diff --git a/tests/test_monitor.py b/tests/test_monitor.py index 461dcb73a..c07d05ff7 100644 --- a/tests/test_monitor.py +++ b/tests/test_monitor.py @@ -46,7 +46,7 @@ ) from solprop.nonlinear.responses import KerrResponse from solprop.output import MemoryOutput, open_file, records -from solprop.output.hdf5 import resume +from solprop.output.hdf5 import read_resume_state from solprop.output.records import RunOutcome, TerminalCheckpoint from solprop.output.scan import read_point from solprop.output.store import CheckpointOutput, Output, PlaneStore @@ -491,7 +491,7 @@ def plane(self, z: float, summary: object) -> None: def _file_record(path: Path) -> tuple[dict[str, Any], int]: """Return a run file's monitor record and how many executions it holds.""" - outcome = resume(path).outcome + outcome = read_resume_state(path).outcome record = _monitor_record(outcome) assert outcome is not None and record is not None return record, len(outcome.previous_executions) + 1 @@ -586,11 +586,17 @@ def test_a_running_record_restores_the_totals_without_rows() -> None: for name, value in first.summary().items() if name not in ("planes", "resumed_at") } + # The earlier execution's worst guard occupancies, far above the resumed + # state's (about 1e-33 in each guard): the record keeps them, not the state's. running |= { "removed_fraction": 0.25, "removed_signed": 0.25, "raw_removed_fraction": 0.25, "steps": 7, + "guard_low_max": 0.03, + "guard_high_max": 0.04, + "guard_low_at": 0.2, + "guard_high_at": 0.4, } monitor = BoundaryMonitor.build(grid, None, BoundaryCheck()) monitor.resume(running, plane=False) @@ -599,41 +605,17 @@ def test_a_running_record_restores_the_totals_without_rows() -> None: assert summary["launch_energy"] == first.summary()["launch_energy"] assert summary["removed_fraction"] == 0.25 assert summary["steps"] == 7 + # Copied numbers, compared exactly. + assert summary["guard_low_max"] == 0.03 + assert summary["guard_high_max"] == 0.04 + assert summary["guard_low_at"] == 0.2 + assert summary["guard_high_at"] == 0.4 assert summary["resumed_at"] == [0.5] planes = summary["planes"] assert isinstance(planes, dict) assert planes["z"] == [] -def test_a_record_from_before_the_signed_removal_still_resumes() -> None: - # A record that predates `removed_signed` and `floor_removed_fraction` gives the - # floor's expectation back as the raw removal less the reported one. - grid, spectrum = _two_pulses(0.0, 0.95) - first = BoundaryMonitor.build(grid, None, BoundaryCheck()) - first.launch(first.energies(spectrum), 0.0) - old = { - name: value - for name, value in first.summary().items() - if name - not in ( - "planes", - "removed_signed", - "floor_removed_fraction", - "quiet_checks", - "collar_quiet", - "unwatched", - ) - } - old |= {"removed_fraction": 0.25, "raw_removed_fraction": 0.25} - monitor = BoundaryMonitor.build(grid, None, BoundaryCheck()) - monitor.resume(old, plane=False) - monitor.launch(monitor.energies(spectrum), 0.5) - summary = monitor.summary() - assert summary["removed_fraction"] == 0.25 - assert summary["floor_removed_fraction"] == 0.0 - assert summary["unwatched"] == [] - - def test_a_resume_lists_the_stretches_run_without_a_monitor() -> None: # An execution with `boundary_check=None` between two watched ones: the totals # continue from before it, and its stretch is listed as unknown. @@ -1350,7 +1332,7 @@ def build(check: BoundaryCheck | None) -> Simulation: build(None).run(path, resume=True, progress=_CrashAtPlane(3)) build(_RELAXED).run(path, resume=True, progress="none") record, executions = _file_record(path) - outcome = resume(path).outcome + outcome = read_resume_state(path).outcome assert outcome is not None first_end, middle_end = ( float(cast("float", one["z"])) for one in outcome.previous_executions diff --git a/tests/test_noise.py b/tests/test_noise.py index f908839c8..674dc5ac3 100644 --- a/tests/test_noise.py +++ b/tests/test_noise.py @@ -137,7 +137,7 @@ def test_the_modulus_is_the_same_for_every_realisation(grid_name, request): # Only the phase is random (conventions.md section 4), so two realisations differ # in phase and agree bin for bin in modulus, to the round-off of one exponential. assert_allclose(np.abs(first), np.abs(second), rtol=8 * EPS, atol=0.0) - assert not np.allclose(np.angle(first), np.angle(second)) + assert not np.allclose(np.angle(first), np.angle(second), atol=0.0) @pytest.mark.parametrize("grid_name", GRIDS) @@ -177,7 +177,7 @@ def test_modes_and_polarisations_are_independent(grid_name, request): phases = np.angle(realisation.spectrum[..., active]).reshape(6, -1) for i in range(6): for j in range(i + 1, 6): - assert not np.allclose(phases[i], phases[j]) + assert not np.allclose(phases[i], phases[j], atol=0.0) correlation = float(np.corrcoef(np.cos(phases[i]), np.cos(phases[j]))[0, 1]) # Independent draws over n bins have a sample correlation of order # 1/sqrt(n); with more than a thousand active bins, 0.2 is many standard diff --git a/tests/test_optics.py b/tests/test_optics.py index 187050d5c..e925ac2d7 100644 --- a/tests/test_optics.py +++ b/tests/test_optics.py @@ -13,7 +13,7 @@ import numpy as np import pytest -from solprop import fourier, optics, pulses +from solprop import optics from solprop.constants import C from solprop.exceptions import MaterialError, MaterialRangeWarning from solprop.optics import Chain, ChirpedMirror, Material, TaylorPhase, stored_factor @@ -193,28 +193,6 @@ def test_a_chirp_built_into_a_pulse_is_removed_by_the_opposite_taylor_phase(): ) -def test_the_pulse_phase_factor_is_what_it_was(): - coefficients, delay = np.array([0.3, 0.0, 250e-30, -4000e-45]), 12e-15 - for kind in ("field", "envelope"): - grid = example_grid(kind) - # The loop the builders carried before the formula moved to solprop.optics. - detuning = grid.omega - OMEGA0 - phase = grid.omega * delay - for order, coefficient in enumerate(coefficients): - phase = phase + coefficient * detuning**order / math.factorial(order) - expected = fourier.to_internal(np.exp(1j * phase)) - # The same sum of five terms, in whatever order the helper forms it: a few - # roundings of the largest phase (16 eps of it), then one complex exponential - # of unit modulus (a few ulps), compared absolutely, the peak being one. - bound = 16 * np.finfo(float).eps * float(np.max(np.abs(phase))) - np.testing.assert_allclose( - pulses._phase_factor(grid, coefficients, delay, OMEGA0), - expected, - rtol=0, - atol=bound + 8 * np.finfo(float).eps, - ) - - def test_stored_factor_is_the_conjugate_on_the_active_band_and_one_elsewhere(): grid = example_grid("field") element = TaylorPhase((0.2, 1e-15, 80e-30), WAVELENGTH) @@ -291,8 +269,11 @@ def test_the_group_delay_at_the_reference_is_zero_and_the_gdd_is_silicas(): # A central difference of a phase whose third derivative is ~1e-43 s^3/mm: the # residual delay is step^2/6 of that, 1e-19 s, against a group delay of 5e-12 s. assert abs(delay) < 1e-18 - # 36.16 fs^2/mm, the textbook figure for fused silica at 800 nm. - assert gdd == pytest.approx(36.16e-30, rel=1e-3) + # The textbook 36.16 fs^2/mm for fused silica at 800 nm is Malitson's expansion + # taken as it is published, relative to air in air wavelengths. Made absolute in + # standard air (Peck and Reeder 1972), as optmat makes it, the same expansion gives + # 36.23 fs^2/mm. + assert gdd == pytest.approx(36.23e-30, rel=1e-3) infrared = 2.0 * math.pi * C / 1550e-9 assert phase_derivatives(Material(silica, 1e-3, 1550e-9), infrared, step)[1] < 0.0 @@ -354,23 +335,46 @@ def test_a_glass_name_is_resolved_and_a_range_is_still_warned_about(): @pytest.mark.parametrize( - "build", + ("build", "message"), [ - lambda: Material(WINDOW, math.inf), - lambda: Material(WINDOW, 1e-3, -800e-9), - lambda: Material("Ar", 1.0), - lambda: Material(WINDOW, 1e-3, pressure=1.0), - lambda: Material(WINDOW, 1e-3, temperature=500.0), - lambda: Material("SiO2", 1e-3, temperature=500.0), - lambda: Material( - Mixture.fill({"Ar": 1.0}, 1.0, temperature=350.0), 1.0, temperature=500.0 + (lambda: Material(WINDOW, math.inf), "thickness must be finite"), + ( + lambda: Material(WINDOW, 1e-3, -800e-9), + "reference wavelength must be positive", + ), + (lambda: Material("Ar", 1.0), "needs its pressure in bar"), + ( + lambda: Material(WINDOW, 1e-3, pressure=1.0), + "pressure is for a built-in gas only", + ), + ( + lambda: Material(WINDOW, 1e-3, temperature=500.0), + "temperature is for a built-in gas only", + ), + ( + lambda: Material("SiO2", 1e-3, temperature=500.0), + "temperature is for a built-in gas only", + ), + ( + lambda: Material( + Mixture.fill({"Ar": 1.0}, 1.0, temperature=350.0), + 1.0, + temperature=500.0, + ), + "temperature is for a built-in gas only", + ), + ( + lambda: TaylorPhase((0.0, math.nan), WAVELENGTH), + "Taylor coefficients must be finite", + ), + ( + lambda: TaylorPhase((0.0,), 0.0), + "reference wavelength must be positive", ), - lambda: TaylorPhase((0.0, math.nan), WAVELENGTH), - lambda: TaylorPhase((0.0,), 0.0), ], ) -def test_unusable_elements_are_refused(build): - with pytest.raises(MaterialError): +def test_unusable_elements_are_refused(build, message): + with pytest.raises(MaterialError, match=message): build() @@ -537,49 +541,70 @@ def test_a_shipped_set_has_a_band_a_name_and_a_physical_reflectivity(name): @pytest.mark.parametrize( - "build", + ("build", "message"), [ - lambda: ChirpedMirror.lookup("HD60"), - lambda: ChirpedMirror( - np.array([4.0, 3.0, 2.0, 1.0]) * 1e15, - np.zeros(4), - np.empty(0), - np.empty(0), - (600e-9, 650e-9, 950e-9, 1000e-9), + (lambda: ChirpedMirror.lookup("HD60"), "unknown chirped mirror 'HD60'"), + ( + lambda: ChirpedMirror( + np.array([4.0, 3.0, 2.0, 1.0]) * 1e15, + np.zeros(4), + np.empty(0), + np.empty(0), + (600e-9, 650e-9, 950e-9, 1000e-9), + ), + "at least four phase samples on an ascending frequency axis", + ), + ( + lambda: synthetic(group_delay=np.zeros(801)), + "exactly one of gdd and group_delay", ), - lambda: synthetic(group_delay=np.zeros(801)), - lambda: ChirpedMirror.from_data( - np.linspace(600e-9, 1000e-9, 11), - None, - reference_wavelength=WAVELENGTH, - band=(650e-9, 950e-9), + ( + lambda: ChirpedMirror.from_data( + np.linspace(600e-9, 1000e-9, 11), + None, + reference_wavelength=WAVELENGTH, + band=(650e-9, 950e-9), + ), + "exactly one of gdd and group_delay", + ), + ( + lambda: synthetic(reflectivity=np.full(801, 1.2)), + r"power reflectivity lies outside \[0, 1\]", ), - lambda: synthetic(reflectivity=np.full(801, 1.2)), - lambda: ChirpedMirror.from_data( - np.array([700e-9, 800e-9, 750e-9, 900e-9, 950e-9]), - None, - gdd=np.zeros(5), - reference_wavelength=WAVELENGTH, - band=(720e-9, 900e-9), + ( + lambda: ChirpedMirror.from_data( + np.array([700e-9, 800e-9, 750e-9, 900e-9, 950e-9]), + None, + gdd=np.zeros(5), + reference_wavelength=WAVELENGTH, + band=(720e-9, 900e-9), + ), + "wavelength axis must be positive and monotonic", ), - lambda: ChirpedMirror.from_data( - np.linspace(700e-9, 900e-9, 3), - None, - gdd=np.zeros(3), - reference_wavelength=WAVELENGTH, - band=(720e-9, 880e-9), + ( + lambda: ChirpedMirror.from_data( + np.linspace(700e-9, 900e-9, 3), + None, + gdd=np.zeros(3), + reference_wavelength=WAVELENGTH, + band=(720e-9, 880e-9), + ), + "3 dispersion samples cannot carry a fit of order 5", ), - lambda: ChirpedMirror.from_data( - np.linspace(700e-9, 900e-9, 9), - np.full(8, 0.9), - gdd=np.zeros(9), - reference_wavelength=WAVELENGTH, - band=(720e-9, 880e-9), + ( + lambda: ChirpedMirror.from_data( + np.linspace(700e-9, 900e-9, 9), + np.full(8, 0.9), + gdd=np.zeros(9), + reference_wavelength=WAVELENGTH, + band=(720e-9, 880e-9), + ), + "data column and its wavelength axis differ in length", ), ], ) -def test_unusable_mirror_data_are_refused(build): - with pytest.raises(MaterialError): +def test_unusable_mirror_data_are_refused(build, message): + with pytest.raises(MaterialError, match=message): build() diff --git a/tests/test_optics_pairs.py b/tests/test_optics_pairs.py index 37f877e96..c0634ba3e 100644 --- a/tests/test_optics_pairs.py +++ b/tests/test_optics_pairs.py @@ -353,21 +353,21 @@ def test_pair_phase_frame_is_order_independent(pair): @pytest.mark.parametrize( - "bad", + ("bad", "message"), [ - np.array([np.nan]), - np.array([np.inf]), - np.array([1 + 1j]), - np.ones((1, 1)), - np.array(1.0), - ["bad"], + (np.array([np.nan]), "must be finite and one-dimensional"), + (np.array([np.inf]), "must be finite and one-dimensional"), + (np.array([1 + 1j]), "angular frequencies must be real"), + (np.ones((1, 1)), "must be finite and one-dimensional"), + (np.array(1.0), "must be finite and one-dimensional"), + (["bad"], "angular frequencies must be a real array"), ], ) @pytest.mark.parametrize("pair", [grating(), prism()]) -def test_pair_frequency_domain_errors(pair, bad): - with pytest.raises(MaterialError): +def test_pair_frequency_domain_errors(pair, bad, message): + with pytest.raises(MaterialError, match=message): pair(bad) - with pytest.raises(MaterialError): + with pytest.raises(MaterialError, match=message): pair.phase(bad) @@ -395,20 +395,20 @@ def test_fixed_band_selects_without_tracing_outside(pair): @pytest.mark.parametrize( - "settings", + ("settings", "message"), [ - {"line_density": 0.0}, - {"line_density": math.inf}, - {"order": 0}, - {"order": True}, - {"separation": -1.0}, - {"separation": math.nan}, - {"incidence_angle": math.pi / 2}, - {"incidence_angle": math.nan}, + ({"line_density": 0.0}, "line_density must be finite and positive"), + ({"line_density": math.inf}, "line_density must be finite and positive"), + ({"order": 0}, "order must be a nonzero signed integer"), + ({"order": True}, "order must be a nonzero signed integer"), + ({"separation": -1.0}, "separation must be finite and nonnegative"), + ({"separation": math.nan}, "separation must be finite and nonnegative"), + ({"incidence_angle": math.pi / 2}, "incidence_angle must lie strictly"), + ({"incidence_angle": math.nan}, "incidence_angle must lie strictly"), ], ) -def test_grating_parameter_errors(settings): - with pytest.raises(MaterialError): +def test_grating_parameter_errors(settings, message): + with pytest.raises(MaterialError, match=message): grating(**settings) @@ -430,20 +430,23 @@ def test_grating_order_boundaries_and_endpoint_checks(): @pytest.mark.parametrize( - "settings", + ("settings", "message"), [ - {"separation": -1.0}, - {"insertion": -1.0}, - {"first_face_distance": 0.0}, - {"first_face_distance": math.inf}, - {"apex_angle": math.pi}, - {"apex_angle": math.nan}, - {"incidence_angle": 0.0}, - {"incidence_angle": math.pi / 2}, + ({"separation": -1.0}, "separation must be finite and nonnegative"), + ({"insertion": -1.0}, "insertion must be finite and nonnegative"), + ({"first_face_distance": 0.0}, "first_face_distance must be positive"), + ({"first_face_distance": math.inf}, "first_face_distance must be finite"), + ({"apex_angle": math.pi}, "apex_angle must lie strictly between zero and pi"), + ({"apex_angle": math.nan}, "apex_angle must lie strictly between zero and pi"), + ({"incidence_angle": 0.0}, "incidence_angle must lie strictly between zero"), + ( + {"incidence_angle": math.pi / 2}, + "incidence_angle must lie strictly between zero", + ), ], ) -def test_prism_geometry_parameter_errors(settings): - with pytest.raises(MaterialError): +def test_prism_geometry_parameter_errors(settings, message): + with pytest.raises(MaterialError, match=message): replace(prism().geometry, **settings) diff --git a/tests/test_package.py b/tests/test_package.py index 4d1535183..fbcf85828 100644 --- a/tests/test_package.py +++ b/tests/test_package.py @@ -58,13 +58,12 @@ def test_top_level_import_does_not_load_heavy_modules(): assert out.stdout.strip() == "[]" -def test_no_removed_device_backend_survives_in_the_package_or_its_imports(): - # The in-tree device backend has been removed. The check is by substring rather - # than by the deleted name so that it also catches a reintroduction under a - # neighbouring spelling, and the import runs in a subprocess because what matters - # is what importing the seam pulls in -- no device runtime, ever. The subprocess - # measures what the import *adds*, because an interpreter may already carry an - # unrelated redirector module installed by a wheel this package never asked for. +def test_importing_the_backends_starts_no_device_runtime(): + # No backend module or attribute is a device backend, and importing the seam pulls + # in no device runtime. The check is by substring, so it catches any spelling. The + # import runs in a subprocess, which measures what the import *adds*, because an + # interpreter may already carry an unrelated redirector module installed by a + # wheel this package never asked for. on_disk = [module.name for module in pkgutil.iter_modules(backends.__path__)] assert on_disk and not [name for name in on_disk if "cuda" in name.lower()] assert not [name for name in dir(backends) if "cuda" in name.lower()] @@ -134,6 +133,9 @@ def test_exception_hierarchy_roots_at_solprop_error(): assert issubclass(exceptions.BackendError, RuntimeError) # A scan executor or its machine failing is a runtime failure, not a refusal. assert issubclass(exceptions.ExecutorError, RuntimeError) + # A refused argument to an output request is a refused value, not a failed write. + assert issubclass(exceptions.OutputRequestError, ValueError) + assert not issubclass(exceptions.OutputRequestError, exceptions.OutputError) def test_warning_hierarchy_roots_at_solprop_warning(): diff --git a/tests/test_profiles.py b/tests/test_profiles.py index f409bfa3b..507ca3679 100644 --- a/tests/test_profiles.py +++ b/tests/test_profiles.py @@ -527,11 +527,13 @@ def test_a_fill_into_the_vacuum_floor_never_drops_below_it(): @settings(max_examples=200, deadline=None) @given( length=st.floats(min_value=1e-3, max_value=10.0), - start_bar=st.floats(min_value=0.0, max_value=50.0), - end_bar=st.floats(min_value=0.0, max_value=50.0), + start_pressure=st.floats(min_value=0.0, max_value=50.0), + end_pressure=st.floats(min_value=0.0, max_value=50.0), fraction=st.floats(min_value=0.0, max_value=1.0), ) -def test_a_fill_is_monotone_bounded_and_finite(length, start_bar, end_bar, fraction): +def test_a_fill_is_monotone_bounded_and_finite( + length, start_pressure, end_pressure, fraction +): """No fill in the supported range produces a non-physical pressure or slope. A pressure below about 1e-154 bar squares to zero, which would collapse the @@ -540,12 +542,14 @@ def test_a_fill_is_monotone_bounded_and_finite(length, start_bar, end_bar, fract highest pressure squares to a subnormal but whose floored end squares to zero, so the slope at the entrance was infinite; the guard is now ``MIN_STAGE_PRESSURE``. """ - highest = max(start_bar, end_bar) + highest = max(start_pressure, end_pressure) if highest < MIN_STAGE_PRESSURE: - with pytest.raises(TranslationError): - PressureGradient.two_point(length, start_bar, end_bar) + # Both refusals, an all-zero fill and one too small to square, name the stage + # pressure. + with pytest.raises(TranslationError, match="stage pressure"): + PressureGradient.two_point(length, start_pressure, end_pressure) return - fill = PressureGradient.two_point(length, start_bar, end_bar) + fill = PressureGradient.two_point(length, start_pressure, end_pressure) z = np.array([fraction * length]) value = float(fill(z)[0]) lower, upper = float(np.min(fill.pressures)), float(np.max(fill.pressures)) diff --git a/tests/test_pulses.py b/tests/test_pulses.py index 9a6de8e30..7f100806a 100644 --- a/tests/test_pulses.py +++ b/tests/test_pulses.py @@ -15,6 +15,7 @@ from hypothesis import strategies as st from numpy.testing import assert_allclose +from runtime_types import unchecked from solprop import _process, fourier from solprop.constants import C from solprop.exceptions import PulseError @@ -369,6 +370,40 @@ def test_a_taylor_phase_gives_the_group_delay_it_asks_for(grid_name, request): assert_allclose(measured, gdd, rtol=5e-3, atol=0.0) +@pytest.mark.parametrize("grid_name", GRIDS) +def test_third_and_fourth_order_phases_give_the_group_delay_they_ask_for( + grid_name, request +): + grid = request.getfixturevalue(grid_name) + # About 0.2 ps of group delay at the band's edge from each term: well inside the + # 2 ps window, and under a radian of phase between neighbouring bins to unwrap. + tod, fod = 20000e-45, 3e5 * 1e-60 + spectrum = GaussianPulse( + wavelength=WAVELENGTH, + fwhm=FWHM, + energy=ENERGY, + phases=(0.0, 0.0, 0.0, tod, fod), + ).build(grid)[0, 0] + optics = fourier.spectrum_to_optics(spectrum, kind=grid.kind) + band = np.abs(spectrum) > 0.05 * np.abs(spectrum).max() + order = np.argsort(grid.omega[band]) + omega = grid.omega[band][order] + delay = np.gradient(np.unwrap(np.angle(optics[band][order])), omega)[1:-1] + detuning = omega[1:-1] - 2.0 * np.pi * C / WAVELENGTH + reach = float(np.max(np.abs(detuning))) + cubic = np.polynomial.Polynomial.fit( + detuning / reach, delay, 3, domain=[-1, 1], window=[-1, 1] + ).coef + # The group delay of c3 x^3/3! + c4 x^4/4! is c3 x^2/2 + c4 x^3/6. A central + # difference of a quartic phase is exact in those two coefficients (its error + # adds only h^2 c3/6 and h^2 c4 x/6), so the fit recovers them to rounding: a few + # eps of 20 rad of phase over 2h ~ 5e12 rad/s is ~1e-27 s, under 1e-14 of the + # 0.3 ps delay at the edge (1e-15 measured); 1e-10 leaves the fit's conditioning + # ample room and is far below the factor 6 or 24 of a wrong factorial. + assert_allclose(cubic[2], tod / 2 * reach**2, rtol=1e-10, atol=0.0) + assert_allclose(cubic[3], fod / 6 * reach**3, rtol=1e-10, atol=0.0) + + @pytest.mark.parametrize("grid_name", GRIDS) def test_the_spectrum_helpers_round_trip_a_built_pulse(grid_name, request): grid = request.getfixturevalue(grid_name) @@ -1315,3 +1350,73 @@ def test_a_large_launch_is_the_same_on_any_number_of_threads( budget = dataclasses.replace(_process.thread_budget(), threads=workers) monkeypatch.setattr(_process, "thread_budget", lambda: budget) assert pulse.build(grid, space, medium=medium).tobytes() == serial.tobytes() + + +@pytest.mark.parametrize("m", [1.5, True, 2.0], ids=["fraction", "bool", "float"]) +def test_a_gaussian_pulse_refuses_an_order_that_is_not_an_integer(m): + # The same integer check as SpatialPulse's, naming the same parameter. The test + # session's annotation check would refuse a float before the constructor's own + # check runs; a user's session has none, so the constructor is called past it. + pulse = object.__new__(GaussianPulse) + with pytest.raises(PulseError, match="m must be a super-Gaussian order") as caught: + unchecked(GaussianPulse.__init__)( + pulse, wavelength=WAVELENGTH, fwhm=FWHM, energy=ENERGY, m=m + ) + assert caught.value.parameter == "m" + + +@pytest.mark.parametrize("kind", ["temporal", "spatial"]) +def test_a_numpy_integer_is_a_super_gaussian_order(kind): + """An order from ``np.arange`` is taken, and kept as a Python int.""" + from solprop.pulses import SpatialPulse # noqa: PLC0415 + + # The test session's annotation check refuses a NumPy integer for `int`; a user's + # session has none, so the constructor is called past it. + pulse = object.__new__(GaussianPulse) + unchecked(GaussianPulse.__init__)( + pulse, wavelength=WAVELENGTH, fwhm=FWHM, energy=ENERGY, m=np.int64(2) + ) + if kind == "spatial": + temporal, pulse = pulse, object.__new__(SpatialPulse) + unchecked(SpatialPulse.__init__)(pulse, temporal, 1e-3, m=np.int64(2)) + assert type(pulse.m) is int + assert pulse.m == 2 + + +def test_a_pulse_sum_refuses_a_beam_as_a_temporal_member(): + from solprop.pulses import PulseSum, SpatialPulse, SpatialPulseSum # noqa: PLC0415 + + temporal = GaussianPulse(wavelength=WAVELENGTH, fwhm=FWHM, energy=ENERGY) + beam = SpatialPulse(temporal, 1e-3) + for member in (beam, SpatialPulseSum((beam,))): + with pytest.raises(PulseError, match="member 1 of the PulseSum is a"): + PulseSum((temporal, member)) # pyright: ignore[reportArgumentType] + + +def test_a_spatial_pulse_refuses_a_beam_as_its_temporal_pulse(): + from solprop.pulses import SpatialPulse, SpatialPulseSum # noqa: PLC0415 + + temporal = GaussianPulse(wavelength=WAVELENGTH, fwhm=FWHM, energy=ENERGY) + beam = SpatialPulse(temporal, 1e-3) + for inner in (beam, SpatialPulseSum((beam,))): + with pytest.raises(PulseError, match="temporal pulse") as caught: + SpatialPulse(inner, 1e-3) # pyright: ignore[reportArgumentType] + assert caught.value.parameter == "temporal" + + +def test_a_planar_launch_is_described_by_its_real_keywords(): + # The keyword is waist, as PlanarPulse(temporal, waist, waist_x=...) takes it. + from solprop.modes import PlanarGrid, SlabMode # noqa: PLC0415 + from solprop.pulses import PlanarPulse, SpatialPulse # noqa: PLC0415 + from solprop.spatial import SpatialMedium # noqa: PLC0415 + + temporal = GaussianPulse(wavelength=WAVELENGTH, fwhm=FWHM, energy=ENERGY) + planar = PlanarPulse(temporal, 400e-6, waist_x=40e-6) + assert "waist=400 um" in repr(planar) + assert "waist_y" not in repr(planar) + grid = EnvelopeGrid.from_limits(1e-4, WAVELENGTH, LIMITS, TRANGE) + space = PlanarGrid([SlabMode(63.5e-6, "Ar", 1.0)], 1e-3, 8) + with pytest.raises(PulseError, match=r"PlanarPulse\(temporal, waist, waist_x="): + SpatialPulse(temporal, 400e-6).build( + grid, space, medium=SpatialMedium("Ar", 1.0) + ) diff --git a/tests/test_seps.py b/tests/test_seps.py index 1b07245ad..672d6afa2 100644 --- a/tests/test_seps.py +++ b/tests/test_seps.py @@ -2,15 +2,19 @@ # # SPDX-License-Identifier: GPL-3.0-or-later -"""Keep the enhancement proposals consistent with their index, folders and roadmap. +"""Keep the enhancement proposals consistent with their index and folders. Each SEP under ``docs/dev/seps/`` carries its status in its header table, and the -status decides where the SEP lives (the open folder or ``archive/``), how the index -lists it and whether the roadmap links it (SEP 0, ``docs/dev/seps/sep-0000-process.md``, -section 4). These tests check that the four agree, that every header is complete, that +status decides where the SEP lives (the open folder or ``archive/``) and how the index +lists it: in its open or archived table, an archived SEP by its file on GitHub, since +the archive is not built into the manual (SEP 0, ``docs/dev/seps/sep-0000-process.md``, +section 4). These tests check that the three agree, that every header is complete, that the review status agrees with the recorded reviewers and that nothing is accepted -without a human and an AI review (SEP 0 section 6, *Review*), and that no SEP refers to -local files or to the private development archive: a SEP stands alone (SEP 0 section 7). +without a human and an AI review (SEP 0 section 6, *Review*), that the numbers leave +no unrecorded gap, that a decided SEP records its resolution and a final one its manual +pages, that a supersession is named from both ends, and that no SEP, nor the decision +log, the benchmark record or a changelog fragment, refers to local files, to the +private development archive or to its identifiers: a SEP stands alone (SEP 0 section 7). What a SEP says is for review; only its structure is checked here. """ @@ -22,7 +26,8 @@ DOCS = Path(__file__).resolve().parents[1] / "docs" SEPS = DOCS / "dev" / "seps" ARCHIVE = SEPS / "archive" -ROADMAP = DOCS / "dev" / "roadmap.md" +# Where the index links an archived SEP: its file on GitHub, on main. +GITHUB_SEPS = "https://github.com/LupoLab/solprop/blob/main/docs/dev/seps/" FIELDS = ( "SEP", @@ -59,16 +64,37 @@ DATE = re.compile(r"\d{4}-\d{2}-\d{2}") REVIEWER = re.compile(r"(.+?) \((human|AI)\)") INDEX_ROW = re.compile( - r"^\| \[(\d+)\]\(((?:archive/)?sep-[^)]+\.md)\) \| (.+?) \| (.+?) \| (.+?) \|$", + r"^\| \[(\d+)\]\(([^)]*sep-[^)]+\.md)\) \| (.+?) \| (.+?) \| (.+?) \|$", re.MULTILINE, ) -ROADMAP_LINK = re.compile(r"\(seps/((?:archive/)?sep-\d{4}-[^)#]+\.md)") # Absolute or home-relative paths, and links to development records that are not part of # the public tree (an old repository-root dev/ directory). LOCAL_REFERENCE = re.compile( r"/Users/|/home/|file://|~/|[A-Za-z]:\\|(?<![\w/])dev/(?:briefs|reports)/|(?:\.\./){3}dev/" ) +# Development-register identifiers, the private development archive's name and the +# project's own names for its machines, none of which a reader of the public tree can +# look up (AGENTS.md, "The public tree stands alone"). +PRIVATE_IDENTIFIER = re.compile( + r"\b(?:TC|LB|SF)-\d+|solprop-dev|\bDMOG\b|\bdmog\b|\bhwlx\b|\bHWLX\b|\bjt52\b" +) +# The records beside the SEPs where such identifiers have occurred. +RECORDS = [ + DOCS / "dev" / "decisions.md", + DOCS / "dev" / "benchmarks.md", + *sorted((DOCS.parent / "changelog.d").glob("*.md")), +] +# A number left out of the sequence is recorded in the index as reserved. +RESERVED = re.compile(r"SEP (\d+) is reserved") +# Statuses that follow a decision, which **Resolution** records (SEP 0 section 6). +DECIDED_STATUSES = frozenset( + {"Accepted", "In progress", "Final", "Withdrawn", "Rejected"} +) +# A link to a SEP, or to a decision record, in a Supersedes or Superseded-by field. +SEP_LINK = re.compile(r"\[SEP (\d+)\]\(([^)]+)\)") +ADR_LINK = re.compile(r"\[(ADR-\d{3})\]\(([^)]+)\)") + def header(page: Path) -> dict[str, str]: """Return the fields of a SEP's header table.""" @@ -170,13 +196,16 @@ def test_sep_numbers_are_unique(): assert len(numbers) == len(set(numbers)) -def test_the_index_lists_every_sep_with_its_header(): - rows = { - path: (int(number), title, status, kind) - for number, path, title, status, kind in INDEX_ROW.findall( - (SEPS / "index.md").read_text() - ) +def index_rows(text: str) -> dict[str, tuple[int, str, str, str]]: + """Return an index table's rows by the SEP's path relative to ``docs/dev/seps``.""" + return { + link.removeprefix(GITHUB_SEPS): (int(number), title, status, kind) + for number, link, title, status, kind in INDEX_ROW.findall(text) } + + +def test_the_index_lists_every_sep_with_its_header(): + rows = index_rows((SEPS / "index.md").read_text()) assert sorted(rows) == sorted(IDS) for page in SEP_FILES: fields = header(page) @@ -188,25 +217,29 @@ def test_the_index_lists_every_sep_with_its_header(): ), relative(page) +def test_the_index_links_an_archived_sep_on_github_and_an_open_one_here(): + links = [link for _, link, *_ in INDEX_ROW.findall((SEPS / "index.md").read_text())] + assert len(links) == len(SEP_FILES) + for link in links: + if "archive/" in link: + assert link.startswith(f"{GITHUB_SEPS}archive/"), link + else: + assert FILENAME.fullmatch(link), link + + @pytest.mark.parametrize( ("section", "statuses"), - [ - ("Accepted enhancement proposals", {"Accepted", "In progress"}), - ("Draft enhancement proposals", {"Draft"}), - ], + [("Open", OPEN_STATUSES), ("Archived", ARCHIVED_STATUSES)], ) -def test_the_roadmap_links_exactly_the_seps_with_each_status(section, statuses): - text = ROADMAP.read_text() - accepted = text.index("\n## Accepted enhancement proposals\n") - drafts = text.index("\n## Draft enhancement proposals\n") - assert accepted < drafts +def test_each_index_table_lists_exactly_the_seps_with_its_statuses(section, statuses): + text = (SEPS / "index.md").read_text() start = text.index(f"\n## {section}\n") end = text.find("\n## ", start + 1) - linked = set(ROADMAP_LINK.findall(text[start:end])) + listed = set(index_rows(text[start : end if end != -1 else None])) expected = { relative(page) for page in SEP_FILES if header(page)["Status"] in statuses } - assert linked == expected + assert listed == expected @pytest.mark.parametrize( @@ -225,3 +258,100 @@ def test_the_template_carries_every_header_field_and_part(): assert [part for part in PARTS if part not in text] == [] assert header(template)["Status"] == "Draft" assert header(template)["Review status"] == "Not reviewed" + + +@pytest.mark.xfail( + strict=True, + reason="SEP 50 is in no file and the index records no reservation for it; " + "recording what became of it is the maintainers' decision", +) +def test_sep_numbers_leave_no_unrecorded_gap(): + numbers = {int(header(page)["SEP"]) for page in SEP_FILES} + reserved = {int(n) for n in RESERVED.findall((SEPS / "index.md").read_text())} + missing = set(range(max(numbers) + 1)) - numbers - reserved + assert not missing, f"numbers neither used nor recorded as reserved: {missing}" + + +# Defects these checks found in the proposals, each a strict expected failure until the +# maintainers decide its fix. +KNOWN = { + ( + "manual pages", + "sep-0025-rounding-level-reproducibility.md", + ): "SEP 25 is Final with no Manual pages; whether a testing-policy change names " + "any is the maintainers' decision", + ( + "supersession", + "sep-0033-single-precision-mlx.md", + ): "SEP 33 is superseded by ADR-077, whose entry does not name SEP 33", +} + + +def _cases(check: str) -> list: + """Return every SEP as a parameter, a strict expected failure where `KNOWN` says.""" + return [ + pytest.param( + page, + id=relative(page), + marks=[pytest.mark.xfail(strict=True, reason=KNOWN[check, page.name])] + if (check, page.name) in KNOWN + else [], + ) + for page in SEP_FILES + ] + + +@pytest.mark.parametrize("page", _cases("manual pages")) +def test_a_decided_sep_records_its_resolution_and_a_final_one_its_pages(page): + fields = header(page) + if fields["Status"] in DECIDED_STATUSES: + assert fields["Resolution"] not in ("", "—"), "the decision is not recorded" + if fields["Status"] == "Final": + assert fields["Manual pages"] not in ("", "—"), "no manual pages are named" + + +@pytest.mark.parametrize("page", _cases("supersession")) +def test_a_supersession_names_a_sep_that_names_it_back(page): + fields = header(page) + by_number = {int(header(other)["SEP"]): other for other in SEP_FILES} + for field, reverse in ( + ("Supersedes", "Superseded-by"), + ("Superseded-by", "Supersedes"), + ): + for number, link in SEP_LINK.findall(fields[field]): + target = (page.parent / link).resolve() + assert target == by_number[int(number)].resolve(), (field, link) + assert f"[SEP {fields['SEP']}]" in header(target)[reverse], ( + f"SEP {number} does not name SEP {fields['SEP']} in its {reverse}" + ) + # A decision record that replaces a SEP names it in its own entry. + for record, link in ADR_LINK.findall(fields[field]): + text = (page.parent / link).resolve().read_text(encoding="utf-8") + entry = text.split(f"\n## {record} — ", 1) + assert len(entry) == 2, f"{link} holds no {record}" + assert f"SEP {fields['SEP']}" in entry[1].split("\n## ", 1)[0], ( + f"{record} does not name SEP {fields['SEP']}" + ) + + +@pytest.mark.parametrize( + "page", + [ + *SEP_FILES, + SEPS / "index.md", + SEPS / "template.md", + ARCHIVE / "index.md", + *RECORDS, + ], + ids=[ + *IDS, + "index.md", + "template.md", + "archive/index.md", + *[str(record.relative_to(DOCS.parent)) for record in RECORDS], + ], +) +def test_no_page_names_a_private_identifier(page): + text = page.read_text(encoding="utf-8") + assert PRIVATE_IDENTIFIER.findall(text) == [] + assert LOCAL_REFERENCE.findall(text) == [] diff --git a/tests/test_sol.py b/tests/test_sol.py index ad8bf9529..75224c36d 100644 --- a/tests/test_sol.py +++ b/tests/test_sol.py @@ -165,7 +165,6 @@ "as_profile", }, } -RENAMED = {("plotting", "energy"): "plot_energy", ("plotting", "stats"): "plot_stats"} HOMES = { "plotting": plotting, "processing": processing, @@ -233,9 +232,8 @@ def test_nothing_public_in_a_home_module_is_forgotten(home): if name in EXCLUDED[home]: assert name not in sol.__all__, f"{home}.{name} is excluded and exported" continue - exported = RENAMED.get((home, name), name) - assert exported in sol.__all__, f"{home}.{name} is missing from solprop.sol" - assert getattr(sol, exported) is getattr(module, name) + assert name in sol.__all__, f"{home}.{name} is missing from solprop.sol" + assert getattr(sol, name) is getattr(module, name) def test_the_exclusions_name_things_that_exist(): diff --git a/tests/test_soliton_content.py b/tests/test_soliton_content.py index bf50ba8c2..68e9bfb9d 100644 --- a/tests/test_soliton_content.py +++ b/tests/test_soliton_content.py @@ -223,18 +223,18 @@ def test_the_inner_diameter_ratio_uses_the_inner_resonator_diameter(): @pytest.mark.parametrize( - "radius, wall, ratio, count", + "radius, wall, ratio, count, message", [ - (-1, 1e-7, 0.6, 6), - (20e-6, -1e-7, 0.6, 6), - (20e-6, 1e-7, 0, 6), - (20e-6, 1e-7, 1.2, 6), - (20e-6, 1e-7, 0.6, 2), - (20e-6, 1e-7, math.nan, 6), + (-1, 1e-7, 0.6, 6, "core_radius must be finite and positive"), + (20e-6, -1e-7, 0.6, 6, "wall_thickness must be finite and positive"), + (20e-6, 1e-7, 0, 6, "inner_diameter_ratio must be finite and positive"), + (20e-6, 1e-7, 1.2, 6, "tube gap must be nonnegative and finite"), + (20e-6, 1e-7, 0.6, 2, "n_tubes must be an integer >= 3"), + (20e-6, 1e-7, math.nan, 6, "inner_diameter_ratio must be finite and positive"), ], ) -def test_invalid_diameter_geometry_is_rejected(radius, wall, ratio, count): - with pytest.raises(ModeError): +def test_invalid_diameter_geometry_is_rejected(radius, wall, ratio, count, message): + with pytest.raises(ModeError, match=message): TubeLattice.from_inner_diameter_ratio( radius, wall_thickness=wall, inner_diameter_ratio=ratio, n_tubes=count ) diff --git a/tests/test_spatial_absorber.py b/tests/test_spatial_absorber.py index 6caa996a1..30647a71a 100644 --- a/tests/test_spatial_absorber.py +++ b/tests/test_spatial_absorber.py @@ -124,15 +124,6 @@ def test_the_safety_ramp_s_strength_and_its_floor() -> None: ) -def test_the_ramp_s_strength_does_not_depend_on_the_run_length() -> None: - # Section 4.4: nothing in the design takes L; the length is the collar's width or - # the requested size. - k = _suite_band() - assert safety_ramp_strength(6e5, k, 300e-6) == safety_ramp_strength(6e5, k, 300e-6) - kappa_p = 3 * math.sqrt(2) / 100e-6 - assert collar_strength(kappa_p, k, 300e-6) == collar_strength(kappa_p, k, 300e-6) - - def test_the_crossing_limit() -> None: k = np.array([K800]) kappa_p, width = 1e5, 300e-6 diff --git a/tests/test_spatial_boundaries.py b/tests/test_spatial_boundaries.py index e01cb9717..0b22269e8 100644 --- a/tests/test_spatial_boundaries.py +++ b/tests/test_spatial_boundaries.py @@ -39,20 +39,23 @@ def case(): @pytest.mark.parametrize( - "changes", + ("changes", "message"), [ - {"waist": 0.0}, - {"m": 0}, - {"m": True}, - {"propz": np.inf}, - {"jones": ()}, - {"jones": (0j,)}, - {"jones": (complex(np.nan),)}, - {"jones": (1j, 1j, 1j)}, + ({"waist": 0.0}, "waist must be finite and positive"), + ({"m": 0}, "m must be a super-Gaussian order of at least 1"), + ({"m": True}, "m must be a super-Gaussian order of at least 1"), + ({"propz": np.inf}, "propz must be finite"), + ({"jones": ()}, "jones must contain one or two finite components"), + ({"jones": (0j,)}, "jones must contain one or two finite components"), + ( + {"jones": (complex(np.nan),)}, + "jones must contain one or two finite components", + ), + ({"jones": (1j, 1j, 1j)}, "jones must contain one or two finite components"), ], ) -def test_spatial_pulse_rejects_invalid_specification(case, changes): - with pytest.raises(PulseError): +def test_spatial_pulse_rejects_invalid_specification(case, changes, message): + with pytest.raises(PulseError, match=message): dataclasses.replace(case[2], **changes) @@ -94,8 +97,18 @@ def build(self, grid): ) -@pytest.mark.parametrize("which", ["space_only", "medium_only", "modes", "pulse_only"]) -def test_simulation_constructor_rejects_incomplete_spatial_context(case, which): +@pytest.mark.parametrize( + ("which", "message"), + [ + ("space_only", "spatial_grid and medium must be supplied together"), + ("medium_only", "spatial_grid and medium must be supplied together"), + ("modes", "spatial propagation requires an empty mode sequence"), + ("pulse_only", "a SpatialPulse requires spatial_grid and medium"), + ], +) +def test_simulation_constructor_rejects_incomplete_spatial_context( + case, which, message +): grid, space, pulse, settings = case options = {"spatial_grid": space, "medium": SpatialMedium()} modes = () @@ -107,7 +120,7 @@ def test_simulation_constructor_rejects_incomplete_spatial_context(case, which): options = {} else: modes = (object(),) - with pytest.raises(DriverError): + with pytest.raises(DriverError, match=message): inspect.unwrap(Simulation.__init__)( object.__new__(Simulation), grid, @@ -137,7 +150,7 @@ def test_direct_spatial_constructor_derives_a_default_frame(case): @pytest.mark.parametrize( ("changes", "refusal"), [ - ({"schema_version": 5}, "reads output schema 4 only"), + ({"schema_version": 5}, "reads output schema 3 only"), ({"spatial": None}, "requires a spatial geometry record"), ], ) diff --git a/tests/test_spatial_flux.py b/tests/test_spatial_flux.py index a27abf7c3..30fd440aa 100644 --- a/tests/test_spatial_flux.py +++ b/tests/test_spatial_flux.py @@ -107,7 +107,10 @@ def test_energy_fluence_and_power_agree() -> None: assert np.sum(power) * grid.dt == pytest.approx(energy, rel=1e-12) assert grid.dt * np.sum(intensity, axis=-1) == pytest.approx(fluence, rel=1e-10) axis = np.sum(on_axis_spectrum(spectrum, flux)) * grid.d_omega - assert axis == pytest.approx(fluence[0], rel=1e-3) # first node off axis + # The first node is off axis, where the beam's fluence exp(-2 r^2 / w^2) is 7e-3 + # below its value on axis; corrected for that, the two agree to 3e-9. + on_axis = fluence[0] * np.exp(2.0 * (space.r[0] / 2e-4) ** 2) + assert axis == pytest.approx(on_axis, rel=1e-6) def test_oversampled_power_and_intensity_lie_on_the_fine_time_axis() -> None: diff --git a/tests/test_spatial_medium.py b/tests/test_spatial_medium.py index 59da29afc..02129914b 100644 --- a/tests/test_spatial_medium.py +++ b/tests/test_spatial_medium.py @@ -77,7 +77,7 @@ def test_evanescent_prefactor_and_attenuation_cap_have_the_literal_limits(grid): @pytest.mark.parametrize("material", ["Ar", "silica"]) def test_bulk_material_derivative_uses_the_existing_analytic_models(material): model = fused_silica() if material == "silica" else material - medium = SpatialMedium(model) + medium = SpatialMedium(model) if material == "silica" else SpatialMedium(model, 1.0) omega = 2 * np.pi * C / np.array([700e-9, 800e-9, 950e-9]) if material == "silica": expected = model.index(omega) @@ -107,6 +107,7 @@ def test_bulk_material_derivative_uses_the_existing_analytic_models(material): ({"temperature": 0}, "temperature"), ({"temperature": np.nan}, "temperature"), ({"pressure": 2}, "pressure"), + ({"material": "Ar"}, "a gas fill needs its pressure"), ({"material": "Ar", "pressure": -1}, "pressure"), ({"material": "Ar", "pressure": Linear(1, -1, 1)}, "pressure"), ], @@ -121,8 +122,8 @@ def test_spatial_medium_refuses_a_temperature_other_than_its_mixtures(): # Not given, or given as the mixture's own: the mixture's temperature. assert SpatialMedium(mixture).temperature == 300.0 assert SpatialMedium(mixture, temperature=300.0).temperature == 300.0 - assert SpatialMedium("Ar").temperature == ROOM_TEMPERATURE - assert SpatialMedium("Ar", temperature=250.0).temperature == 250.0 + assert SpatialMedium("Ar", 1.0).temperature == ROOM_TEMPERATURE + assert SpatialMedium("Ar", 1.0, temperature=250.0).temperature == 250.0 with pytest.raises(MaterialError, match=r"own temperature \(300 K\).*omit"): SpatialMedium(mixture, temperature=ROOM_TEMPERATURE) @@ -178,5 +179,5 @@ def test_nonfinite_material_index_is_rejected_at_the_spatial_boundary(monkeypatc def test_explicit_gas_susceptibility_is_preserved(): susceptibility = susceptibility_for("Ar") - medium = SpatialMedium("Ar", susceptibility=susceptibility) + medium = SpatialMedium("Ar", 1.0, susceptibility=susceptibility) assert medium.susceptibility is susceptibility diff --git a/tests/test_spatial_statistics.py b/tests/test_spatial_statistics.py index 13e2322a8..9070596f1 100644 --- a/tests/test_spatial_statistics.py +++ b/tests/test_spatial_statistics.py @@ -14,6 +14,7 @@ from numpy.testing import assert_allclose from scipy.special import j0 +from builders import live_nyquist from hankel_oracles import gamma, gaussian_bound from solprop.constants import EPS0, C from solprop.exceptions import GridError, OutputError @@ -27,8 +28,10 @@ SpatialMedium, beam_radius, fwhm_r, + node_spectrum, on_axis_intensity, on_axis_spectrum, + on_axis_trace, radial_fluence_widths, spatial_energy, spatial_fluence, @@ -138,6 +141,46 @@ def test_bessel_energy_and_on_axis_spectral_fluence(grid, bessel_case): ) +def test_the_spectral_fluences_integrate_exactly_with_live_end_bins(): + """The densities weigh the end bins as the analytic signal does, a quarter of 4. + + Both end bins carry field here; DC has no admittance, so the Nyquist bin, made + active by widening the collar past it, is the one that tells the weights apart. + """ + grid = live_nyquist(FieldGrid.from_limits(1e-3, 800e-9, (600e-9, 1.2e-6), 150e-15)) + assert grid.active_mask[-1] + space = RadialGrid(6e-4, 16) + flux = _vacuum(grid, space) + rng = np.random.default_rng(155) + shape = (space.n_r, 2, grid.n_omega) + state = rng.standard_normal(shape) + 1j * rng.standard_normal(shape) + # The end bins of a real field are real. + state[..., [0, -1]] = np.real(state[..., [0, -1]]) + d_omega = grid.d_omega + + nodes = node_spectrum(state, flux) + fluence = spatial_fluence(state, flux) + # Each node's sum runs over n_pol n_omega products of a transverse synthesis of + # n_r columns, in any order: a few units per term of the summed magnitudes. + bound = gamma(16 * (2 * grid.n_omega + space.n_r)) * float( + np.max(np.abs(nodes).sum(axis=1)) * d_omega + ) + assert_allclose(nodes.sum(axis=1) * d_omega, fluence, rtol=0, atol=bound) + # Non-vacuous: weighing the Nyquist bin as an interior one, 4 for 1, moves the sum + # by three times its term, far beyond the bound. + assert 3 * np.max(np.abs(nodes[:, -1])) * d_omega > 1e3 * bound + + axis = on_axis_spectrum(state, flux) + # The time integral of the on-axis flux: temporal Parseval with the analytic + # signal's exact weights, an independent route to the on-axis fluence. + expected = float(np.sum(on_axis_trace(state, flux)) * grid.dt) + bound = gamma( + 16 * (2 * grid.n_omega + space.n_r) + 64 * int(np.log2(grid.n_t)) + ) * float(np.sum(np.abs(axis)) * d_omega) + assert abs(float(axis.sum()) * d_omega - expected) <= bound + assert 3 * abs(axis[-1]) * d_omega > 1e3 * bound + + def test_gaussian_inverse_against_the_dual_hankel_remainder(grid): space = RadialGrid(6e-4, 64) waist = 1e-4 diff --git a/tests/test_stats.py b/tests/test_stats.py index 05a0f791a..07c6a9fc0 100644 --- a/tests/test_stats.py +++ b/tests/test_stats.py @@ -16,7 +16,7 @@ from solprop.constants import C from solprop.exceptions import ModeError, OutputError, ProcessingError, SolpropWarning from solprop.grid import EnvelopeGrid, FieldGrid -from solprop.modes import MarcatiliMode +from solprop.modes import MarcatiliMode, StepIndexMode from solprop.output.records import SavedPlane from solprop.profiles import Constant, PressureGradient from solprop.pulses import GaussianPulse @@ -39,6 +39,7 @@ profile_value, zdw, ) +from solprop.stats.definitions import _whitened WAVELENGTH = 800e-9 FWHM = 30e-15 @@ -337,9 +338,9 @@ def test_inband_wavelengths_are_the_grid_limits(envelope_grid): def test_zdw_finds_the_zero_of_the_group_velocity_dispersion(capillary): value = zdw([capillary], 0.0, wavelength_limits=(150e-9, 900e-9)) assert value.shape == (1,) - # The same root the mode's own accessor reports; see tests/modes/test_base.py. - # 376.4 nm on optmat's helium since SEP 3's Phase 4a (364.8 nm on the registry's), - # at 294 K; 376.7 nm since the default temperature became 293.15 K. + # The same root the mode's own accessor reports (tests/modes/test_base.py): the + # zero of the group-velocity dispersion of this capillary on optmat's helium at + # 0.4 bar and the default 293.15 K. assert_allclose(value[0], 376.7e-9, rtol=1e-4) @@ -360,6 +361,32 @@ def test_collect_records_nan_when_the_band_holds_no_zero(capillary): assert np.isnan(values["zdw"]).all() +def test_collect_records_a_zero_past_the_sign_changes_of_a_gas_resonance(): + """Krypton's lines near 120 nm flip the sign of beta_2 in the band, many times.""" + grid = EnvelopeGrid.from_limits(1.0, 800e-9, (110e-9, 2e-6), 1e-12) + field = gaussian(grid, energy_j=ENERGY) + krypton = MarcatiliMode(14e-6, "Kr", 15.0) + values = collect(StatsSpec(names=("zdw",)), grid, plane_of(field), modes=[krypton]) + # The zero nearest the grid's 800 nm reference, the capillary's only one above the + # lines; the noise of the differenced beta_2 (5e-9) sets the tolerance. + assert_allclose(values["zdw"], [770.5167e-9], rtol=1e-6) + + +@pytest.mark.medium +def test_collect_records_a_telecom_fibres_zero_past_the_oh_band(): + """Silica's OH band at 1.38 um flips beta_2's sign between a 1550 nm reference + and the fibre's 1.3 um zero, and does not block the search.""" + grid = EnvelopeGrid.from_limits(1.0, 1550e-9, (1e-6, 2e-6), 1e-12) + field = gaussian(grid, energy_j=ENERGY) + fibre = StepIndexMode.from_numerical_aperture( + 4.1e-6, 0.12, profile_wavelength=1.3e-6 + ) + values = collect(StatsSpec(names=("zdw",)), grid, plane_of(field), modes=[fibre]) + # The fibre's zero on any window that holds it (tests/modes/test_base.py), to + # the noise of the differenced beta_2 (5e-9). + assert_allclose(values["zdw"], [1295.8347e-9], rtol=1e-6) + + def test_collect_records_each_modes_zero_on_its_own(capillary): """One mode with no zero in the band leaves the other's value in place.""" grid = EnvelopeGrid.from_limits(1.0, 400e-9, (250e-9, 1.2e-6), 1e-12) @@ -649,19 +676,10 @@ def two_channel(grid): @pytest.mark.parametrize("name", sorted(METRIC_WEIGHTED_STATISTICS)) -def test_no_metric_is_the_identity_and_is_what_it_was(field_grid, name): - """`metric=None` is the fast path and changes no existing number. - - The default is ``metric=None``, so both calls run one computation: an explicitly - exact no-op, compared exactly. - """ +def test_the_identity_metric_is_the_default_s_number(field_grid, name): + """An identity metric weighs every channel as ``metric=None``, the default, does.""" field = two_channel(field_grid) function = getattr(stats, name) - assert np.array_equal( - np.asarray(function(field_grid, field)), - np.asarray(function(field_grid, field, metric=None)), - equal_nan=True, - ) identity = np.broadcast_to( np.eye(2, dtype=complex)[:, :, None], (2, 2, field_grid.n_omega) ).copy() @@ -703,7 +721,7 @@ def test_the_metric_weighted_energy_is_the_quadratic_form(field_grid): def test_the_whitening_is_the_positive_definite_square_root(field_grid): field = two_channel(field_grid) metric = metric_of(2, field_grid.n_omega) - whitened = stats._whitened(field, metric) + whitened = _whitened(field, metric) assert_allclose( np.einsum("mpk,mpk->k", whitened.conj(), whitened).real, np.einsum("mpk,mnk,npk->k", field.conj(), metric, field).real, diff --git a/tests/test_structure_figures.py b/tests/test_structure_figures.py index 7a82a1009..89947864e 100644 --- a/tests/test_structure_figures.py +++ b/tests/test_structure_figures.py @@ -42,6 +42,7 @@ FIGURES = ROOT / "docs" / "dev" / "figures" PACKAGE = ROOT / "src" / "solprop" PAGE = ROOT / "docs" / "dev" / "structure.md" +CONTRACT = ROOT / "docs" / "dev" / "kernel-contract.md" spec = importlib.util.spec_from_file_location("structure_figures", FIGURES / "build.py") assert spec is not None and spec.loader is not None @@ -107,11 +108,44 @@ def test_every_contract_section_names_fields_of_the_problem(section): def test_the_contract_figure_covers_every_field(): - """Between them the eight sections account for all ten fields.""" + """Between them the eight sections account for every field.""" drawn = {name for section in build.CONTRACT_SECTIONS for name in section.fields} assert drawn == {field.name for field in dataclasses.fields(PropagationProblem)} +def _section_case(section): + """Return a section as a parameter, a strict expected failure where one is known.""" + marks = ( + [ + pytest.mark.xfail( + strict=True, + reason="figure 3 titles section 5 'responses and the prefactor'; the " + "contract's heading is 'Responses (the compiled nonlinear term)'", + ) + ] + if section.number == 5 + else [] + ) + return pytest.param(section, id=str(section.number), marks=marks) + + +@pytest.mark.parametrize( + "section", [_section_case(section) for section in build.CONTRACT_SECTIONS] +) +def test_every_contract_section_is_titled_as_the_contract_heads_it(section): + """Figure 3's section number and title are a ``## N.`` heading of the contract.""" + headings = dict( + re.findall(r"^## (\d+)\. (.+)$", CONTRACT.read_text(), flags=re.MULTILINE) + ) + assert section.title.casefold() == headings[str(section.number)].casefold() + + +def test_the_figure_script_names_no_retired_part(): + """The removed step driver and the retired backends appear nowhere in the script.""" + text = (FIGURES / "build.py").read_text(encoding="utf-8") + assert re.findall(r"StepDriver|numba|mlx", text, flags=re.IGNORECASE) == [] + + @pytest.mark.parametrize("section", build.CONTRACT_SECTIONS) def test_every_contract_section_names_members_of_the_request(section): """The run's policy a section documents is reached from `RunRequest` as named.""" diff --git a/tests/test_tolerance_defaults.py b/tests/test_tolerance_defaults.py new file mode 100644 index 000000000..5daa4ac00 --- /dev/null +++ b/tests/test_tolerance_defaults.py @@ -0,0 +1,79 @@ +# SPDX-FileCopyrightText: 2026 John C. Travers and contributors +# +# SPDX-License-Identifier: GPL-3.0-or-later + +"""No comparison in the test trees takes a default absolute tolerance on SI values. + +``pytest.approx`` and NumPy's ``allclose``/``isclose`` keep an absolute tolerance beside +the relative one (1e-12 and 1e-8), and many of the suite's quantities are far smaller: +times of 1e-15 s, nonlinear indices of 1e-25 m^2/W, energies of 1e-16 J. Under such a +default the comparison accepts any result. ``tests/conftest.py`` gives +``pytest.approx`` no absolute tolerance when a test gives ``rel=`` alone or compares +with a nonzero number bare, and every NumPy comparison states its ``atol`` +(``docs/dev/testing.md`` section 3). +``numpy.testing.assert_allclose`` and ``math.isclose`` default to no absolute tolerance +and need no rule. +""" + +import ast +from pathlib import Path + +import pytest + +ROOT = Path(__file__).resolve().parents[1] +TREES = ("tests", "native/tests", "gui/tests") +"""The test trees, relative to the repository root.""" + +NUMPY_NAMES = {"np", "numpy"} +COMPARISONS = {"allclose", "isclose"} +ATOL_POSITION = 3 +"""``allclose(a, b, rtol, atol)``: a fourth positional argument is the ``atol``.""" + + +def numpy_comparisons() -> tuple[int, list[str]]: + """Return how many NumPy comparisons the test trees hold, and those with no atol.""" + seen = 0 + missing = [] + for tree in TREES: + for path in sorted((ROOT / tree).rglob("*.py")): + module = ast.parse(path.read_text(encoding="utf-8"), filename=str(path)) + for node in ast.walk(module): + if not ( + isinstance(node, ast.Call) + and isinstance(node.func, ast.Attribute) + and node.func.attr in COMPARISONS + and isinstance(node.func.value, ast.Name) + and node.func.value.id in NUMPY_NAMES + ): + continue + seen += 1 + keywords = {keyword.arg for keyword in node.keywords} + if "atol" not in keywords and len(node.args) <= ATOL_POSITION: + where = path.relative_to(ROOT).as_posix() + missing.append(f"{where}:{node.lineno}: {ast.unparse(node.func)}") + return seen, missing + + +def test_every_numpy_comparison_states_its_absolute_tolerance(): + seen, missing = numpy_comparisons() + # The scan finds the comparisons it is about; an empty scan would pass vacuously. + assert seen > 50 + assert not missing, ( + "np.allclose/np.isclose default to atol=1e-8, which accepts any result on " + "small SI values; give each an explicit atol (0.0 for a relative comparison):\n" + + "\n".join(missing) + ) + + +def test_a_relative_approx_has_no_absolute_tolerance(): + # The helium n2 of 3.6e-25 m^2/W at 2 %: pytest's own default absolute tolerance of + # 1e-12 would accept 5.45e-25, and any other value of that size. + assert pytest.approx(3.6e-25, rel=0.02) == 3.6e-25 * 1.019 + assert pytest.approx(3.6e-25, rel=0.02) != 5.45e-25 + # A bare approx of a nonzero number keeps pytest's relative 1e-6 and nothing else. + assert pytest.approx(1e-13) == 1e-13 * (1 + 5e-7) + assert pytest.approx(1e-13) != -1e-13 + # A bare approx of zero keeps pytest's defaults, and an absolute tolerance the test + # gives is kept. + assert pytest.approx(0.0) == 1e-13 + assert pytest.approx(0.0, rel=1e-6, abs=1e-20) == 1e-21 diff --git a/tests/test_tools.py b/tests/test_tools.py index a351fe66d..d09c31ae6 100644 --- a/tests/test_tools.py +++ b/tests/test_tools.py @@ -6,6 +6,7 @@ import json import math +import re import warnings from dataclasses import replace from pathlib import Path @@ -244,24 +245,45 @@ def test_the_critical_power_is_the_package_townes_power_times_the_index(): @pytest.mark.parametrize( - "call", + ("call", "message"), [ - lambda: choice("lorentz", "shape", get_args(tools.PulseShape), ToolsError), - lambda: tools.pulse_width(0.0), - lambda: tools.pulse_peak_power(-1.0, 10e-15), - lambda: tools.dispersion_length(10e-15, 0.0), - lambda: tools.dispersion_length(10e-15, math.nan), - lambda: tools.nonlinear_length(1.0, 0.0), - lambda: tools.nonlinear_coefficient(helium(), -1.0, PUMP), - lambda: tools.intensity_to_field(-1.0), - lambda: tools.self_focusing_power(PUMP, 1.0, 0.0), - lambda: tools.capillary_params( - -1e-6, "He", 1.0, energy=1e-6, fwhm=1e-14, wavelength=PUMP + ( + lambda: choice("lorentz", "shape", get_args(tools.PulseShape), ToolsError), + "shape must be 'sech' or 'gauss'", + ), + (lambda: tools.pulse_width(0.0), "fwhm must be finite and positive"), + ( + lambda: tools.pulse_peak_power(-1.0, 10e-15), + "energy must be finite and positive", + ), + ( + lambda: tools.dispersion_length(10e-15, 0.0), + "beta2 must be finite and non-zero", + ), + ( + lambda: tools.dispersion_length(10e-15, math.nan), + "beta2 must be finite and non-zero", + ), + (lambda: tools.nonlinear_length(1.0, 0.0), "gamma must be finite and positive"), + ( + lambda: tools.nonlinear_coefficient(helium(), -1.0, PUMP), + "n2 must be finite and not negative", + ), + (lambda: tools.intensity_to_field(-1.0), "intensity must not be negative"), + ( + lambda: tools.self_focusing_power(PUMP, 1.0, 0.0), + "n2 must be finite and positive", + ), + ( + lambda: tools.capillary_params( + -1e-6, "He", 1.0, energy=1e-6, fwhm=1e-14, wavelength=PUMP + ), + "radius must be finite and positive", ), ], ) -def test_unusable_numbers_are_refused_by_name(call): - with pytest.raises(ToolsError): +def test_unusable_numbers_are_refused_by_name(call, message): + with pytest.raises(ToolsError, match=re.escape(message)): call() @@ -842,7 +864,7 @@ def test_a_sign_change_across_samples_that_are_not_finite_is_not_a_zero(): grid = np.linspace( 2.0 * math.pi * C / tools_waveguide._ZDW_RANGE[1], 2.0 * math.pi * C / tools_waveguide._ZDW_RANGE[0], - tools_waveguide._ZDW_SAMPLES, + base._ZDW_SAMPLES, ) centre = 0.5 * (grid[20] + grid[21]) @@ -861,6 +883,47 @@ def delay(w): assert math.isnan(tools_waveguide._zdw_near(mode, OMEGA0, 0.0)) +def test_the_floored_plateau_beside_a_resonance_is_not_a_zero(): + # Above krypton's 123.6 nm line the index sits on the evanescent floor, the group + # delay is constant, and the differenced beta2 crosses zero at 123.57 nm; the + # physical zero of this capillary is at 770.5 nm. + mode = MarcatiliMode(14e-6, "Kr", 15.0) + found = tools_waveguide._zdw_near(mode, 2.0 * math.pi * C / 200e-9, 0.0) + # The noise of the differenced beta2 (5e-9, modes.base) sets the tolerance. + assert found == pytest.approx(770.5167e-9, rel=1e-6) + + +def test_a_stencil_reaching_a_line_is_not_a_zero(): + # From a 120 nm pump the nearest sign change in argon at 15 bar lies at 106.826 nm, + # half a beta2 step from the 106.666 nm line, where the group delay rises without + # an extremum. The line bounds the pump's side, whose zero is at 644.1 nm. + mode = MarcatiliMode(14e-6, "Ar", 15.0) + found = tools_waveguide._zdw_near(mode, 2.0 * math.pi * C / 120e-9, 0.0) + reference = base.zdw(mode, wavelength_limits=(200e-9, 3e-6)) + # Other samples, so other brackets: both stop on the noise of the differenced + # beta2 (5e-9, modes.base). + assert found == pytest.approx(reference, rel=1e-8) + assert reference == pytest.approx(644.0787e-9, rel=1e-6) + + +def test_the_zero_between_two_lines_is_found_from_a_pump_between_them(): + # Krypton's 116.5 and 123.6 nm lines bound a band holding a pump at 120 nm, and a + # zero of the gas's own dispersion at 119.88 nm, outside the fit's qualified range. + mode = MarcatiliMode(14e-6, "Kr", 15.0) + with pytest.warns(MaterialRangeWarning, match="Kr"): + found = tools_waveguide._zdw_near(mode, 2.0 * math.pi * C / 120e-9, 0.0) + with warnings.catch_warnings(): + warnings.simplefilter("ignore", MaterialRangeWarning) + omega = 2.0 * math.pi * C / found + # 2001 samples of the analytic delay across the beta2 stencil. + offsets = np.linspace(-base.BETA2_RELATIVE_STEP, base.BETA2_RELATIVE_STEP, 2001) + delay = base.beta1(mode, omega * (1.0 + offsets), 0.0) + assert found == pytest.approx(119.8786e-9, rel=1e-6) + # An extremum of the delay, at the centre to ten samples of 3e-6 relative. + extremum = np.argmin(delay) if delay[0] > delay[1000] else np.argmax(delay) + assert abs(int(extremum) - 1000) <= 10 + + @pytest.mark.parametrize( ("gas", "radius", "pressure"), [ @@ -1226,7 +1289,7 @@ def test_the_nearest_zero_is_found_without_refining_every_resonance(monkeypatch) mode = Recipe.example("antiresonant_fibre").build().modes[0] pump = 2.0 * math.pi * C / 800e-9 - refine = tools_waveguide._refine_zero + refine = base._refine_zero calls = [] def counted(*args): @@ -1234,14 +1297,14 @@ def counted(*args): calls.append(root) return root - monkeypatch.setattr(tools_waveguide, "_refine_zero", counted) + monkeypatch.setattr(base, "_refine_zero", counted) found = tools_waveguide._zdw_near(mode, pump, 0.0) assert len(calls) <= 4 # What refining every change would have reported. grid = np.linspace( 2.0 * math.pi * C / tools_waveguide._ZDW_RANGE[1], 2.0 * math.pi * C / tools_waveguide._ZDW_RANGE[0], - tools_waveguide._ZDW_SAMPLES, + base._ZDW_SAMPLES, ) with tools_waveguide._probing(), np.errstate(divide="ignore", invalid="ignore"): sampled = base.beta2(mode, grid, 0.0) diff --git a/tests/test_transverse_monitor.py b/tests/test_transverse_monitor.py index 68515ceb6..97bdb3c86 100644 --- a/tests/test_transverse_monitor.py +++ b/tests/test_transverse_monitor.py @@ -29,7 +29,7 @@ from solprop.log import NullReporter from solprop.modes import PlanarGrid, SlabMode from solprop.monitor import BoundaryCheck -from solprop.output.hdf5 import resume +from solprop.output.hdf5 import read_resume_state from solprop.output.store import PlaneStore from solprop.translate.transverse import _nodes_window from solprop.transverse_monitor import BACKSTOP_READS, TransverseEdge, _row_energy @@ -280,7 +280,7 @@ def build() -> Simulation: with warnings.catch_warnings(): warnings.simplefilter("ignore", BoundaryWarning) build().run(path, resume=True, progress="none") - outcome = resume(path).outcome + outcome = read_resume_state(path).outcome assert outcome is not None resumed = cast("dict[str, Any]", outcome.execution["boundary_monitor"])[ "transverse" diff --git a/tests/test_transverse_resolution.py b/tests/test_transverse_resolution.py index 289aeb2cf..ad2f3d5f0 100644 --- a/tests/test_transverse_resolution.py +++ b/tests/test_transverse_resolution.py @@ -24,6 +24,7 @@ from solprop.pulses import GaussianPulse, SpatialPulse from solprop.spatial import SpatialDispersion, SpatialMedium from solprop.stepper import PIController, RungeKutta +from solprop.translate.problem import LOG_DBL_MAX from solprop.translate.routes import transverse_of from solprop.translate.transverse import band_wavenumbers, resolve_transverse @@ -91,6 +92,24 @@ def test_the_default_is_the_safety_ramp_alone(route: str) -> None: assert np.array_equal(ramp, design.ramp_rate) +@pytest.mark.parametrize("length", [LENGTH, 1.0]) +def test_the_safety_ramp_alone_holds_the_longest_step_to_its_exponent_budget( + length: float, +) -> None: + # With no collar, nothing else holds an adaptive run's longest step: the ramp's + # inverse factor exp(alpha_s h / 2) stays within half binary64's range only if + # h <= log(DBL_MAX) / alpha_s, about 7 mm here, whatever the run's length. + simulation = suite(0.0, None, length=length) + design = transverse_of(simulation.translate().route) + assert design is not None and not design.has_collar + budget = LOG_DBL_MAX / design.ramp_strength + assert budget < LENGTH # the clamp binds on the requested dz_max = length + stepper = simulation.run_request().stepper + # Exact: the clamp is a min() of the requested step and the budget. + assert stepper.dz_max == budget + assert stepper.dz_init <= budget + + def test_the_radial_ramp_rides_the_dense_operator_exactly() -> None: # The radial operator is diagonal in k_r, so the ramp enters it as -alpha_s / 2 # on each column's real part, inside the active band, and nowhere else. diff --git a/tests/translate/test_compiled_responses.py b/tests/translate/test_compiled_responses.py index dd42ab659..b4fe131ae 100644 --- a/tests/translate/test_compiled_responses.py +++ b/tests/translate/test_compiled_responses.py @@ -168,6 +168,17 @@ def test_the_prefactor_is_the_mode_averaged_one_times_the_crop_scale( assert compiled.prefactor_value_shape == (1, 1, envelope_grid.n_omega) +def test_an_oversampled_grid_crops_the_prefactor_by_its_crop_scale(field_grid, mode): + # The field grid pads its spectrum twice over, so its crop scale is 1/2, not 1: a + # prefactor that dropped it would be twice the expected one. + assert field_grid.crop_scale == 0.5 + compiled = compile_for(field_grid, mode, [KerrResponse(chi3=1e-52, thg=True)]) + expected = mode_average_prefactor(mode, field_grid) * 0.5 + assert compiled.prefactor_constant is not None + # A product with an exact power of two, so exact. + assert np.array_equal(compiled.prefactor_constant[0, 0], expected) + + def test_the_multimode_prefactor_leaves_the_area_to_the_transform(envelope_grid, mode): compiled = compile_for(envelope_grid, mode, mode_averaged=False) expected = uppe_prefactor(mode, envelope_grid) * envelope_grid.crop_scale diff --git a/tests/translate/test_dispersive_kerr_terms.py b/tests/translate/test_dispersive_kerr_terms.py index 5e2acc0b5..3cff0beea 100644 --- a/tests/translate/test_dispersive_kerr_terms.py +++ b/tests/translate/test_dispersive_kerr_terms.py @@ -532,3 +532,18 @@ def test_a_problem_without_the_leaf_adds_no_node_buffers(field_grid, mode): assert compiled.dispersive_kerr is None assert dispersive_node_buffers(compiled, spatial=False) == 0 assert dispersive_node_buffers(compiled, spatial=True) == 0 + + +def test_the_dispersive_leaf_refuses_responses_that_disagree_on_thg(): + """One leaf has one sector, so its responses must agree on ``thg`` as it says.""" + from solprop.translate.linop import profile_table # noqa: PLC0415 + from solprop.translate.responses import dispersive_terms # noqa: PLC0415 + + grid = FieldGrid.from_limits(1.0, 800e-9, (400e-9, 2e-6), 200e-15) + table = profile_table(Constant(1e25), 0.0, 1.0) + responses = [ + DispersiveKerrResponse(HELIUM, "symmetric", species="He"), + DispersiveKerrResponse(ARGON, "symmetric", thg=False, species="Ar"), + ] + with pytest.raises(TranslationError, match="must agree on thg"): + dispersive_terms(responses, ["He", "Ar"], [table, table], grid) diff --git a/tests/translate/test_envelope_plasma_compilation.py b/tests/translate/test_envelope_plasma_compilation.py index dadd86b40..6a66cfb79 100644 --- a/tests/translate/test_envelope_plasma_compilation.py +++ b/tests/translate/test_envelope_plasma_compilation.py @@ -22,6 +22,7 @@ from solprop.nonlinear.optmat_rates import OptmatRate from solprop.nonlinear.responses import KerrResponse from solprop.profiles import Constant +from solprop.translate import envelope_plasma from solprop.translate.envelope_plasma import ( AngularRule, CycleIntegralData, @@ -125,7 +126,12 @@ def test_envelope_plasma_contract_fields_are_frozen(): def test_cycle_data_are_validated_owned_readonly_and_cached(cycle): - assert cycle is build_cycle_integrals( + # Built again here, not compared with the module's fixture: the memo is bounded, + # and other tests may have pushed the fixture's entry out. + again = build_cycle_integrals( + EnvelopePlasmaResponse("Ar", adk_oracle("Ar")), (1e9, 1e11) + ) + assert again is build_cycle_integrals( EnvelopePlasmaResponse("Ar", adk_oracle("Ar")), (1e9, 1e11) ) assert cycle.rate.field_min < 1e9 @@ -254,6 +260,18 @@ def test_rate_model_identity_changes_cycle_cache(): assert first.identity != second.identity +def test_the_cycle_memo_keeps_only_the_newest_entries(monkeypatch): + """An energy scan builds one cycle per field range; the memo is bounded.""" + monkeypatch.setattr(envelope_plasma, "_CYCLES", {}) + monkeypatch.setattr(envelope_plasma, "_CYCLES_KEPT", 1) + response = EnvelopePlasmaResponse("Ar", adk_oracle("Ar")) + first = build_cycle_integrals(response, (1e9, 1e11)) + second = build_cycle_integrals(response, (1e9, 2e11)) + assert first.identity != second.identity + assert list(envelope_plasma._CYCLES) == [second.identity] + assert build_cycle_integrals(response, (1e9, 2e11)) is second + + def test_invalid_cycle_data_and_domains_fail(cycle): with pytest.raises(TranslationError, match="unvalidated"): replace(cycle, moment_rtol=1e-3) diff --git a/tests/translate/test_ionisation_tables.py b/tests/translate/test_ionisation_tables.py index 6ad1e9bef..3366b927a 100644 --- a/tests/translate/test_ionisation_tables.py +++ b/tests/translate/test_ionisation_tables.py @@ -268,7 +268,7 @@ def test_a_built_table_is_frozen_before_anyone_holds_it(use_cache): def test_the_knots_are_uniform_in_the_logarithm_of_the_field(): table = build_rate_table(adk_oracle(Gas.Ar), default_range(Gas.Ar)) spacing = np.diff(table.log_field) - assert np.allclose(spacing, table.d_log_field, rtol=1e-12) + assert np.allclose(spacing, table.d_log_field, rtol=1e-12, atol=0.0) assert table.field[0] == pytest.approx(table.field_min, rel=1e-12) assert table.field[-1] == pytest.approx(table.field_max, rel=1e-12) assert table.n_knots == table.coefficients.shape[1] + 1 diff --git a/tests/translate/test_linop.py b/tests/translate/test_linop.py index 566be46a8..45caaaf1e 100644 --- a/tests/translate/test_linop.py +++ b/tests/translate/test_linop.py @@ -890,7 +890,7 @@ def test_a_taper_and_a_gradient_expand_in_both_parameters(field_grid): ) -def test_the_expansion_is_smaller_and_faster_to_evaluate_than_the_z_table( +def test_the_expansion_is_smaller_than_the_z_table( field_grid, gradient_mode, gradient_table ): """The point of the representation, on the case that motivated it. diff --git a/tests/translate/test_masks.py b/tests/translate/test_masks.py index 3ca48ae9f..7c1be3503 100644 --- a/tests/translate/test_masks.py +++ b/tests/translate/test_masks.py @@ -118,6 +118,21 @@ def test_the_in_band_region_is_inside_the_active_band(grid): ) +@pytest.mark.parametrize( + ("region", "mask"), [("active", "active_mask"), ("band", "inband_mask")] +) +def test_the_norm_mask_is_the_region_s_mask(grid, region, mask): + masks = build_masks(grid, region=region) + np.testing.assert_array_equal(masks.norm_mask, getattr(masks, mask)) + + +def test_an_unknown_norm_region_is_refused(grid): + with pytest.raises( + TranslationError, match=r"region 'inband' is not 'active' or 'band'" + ): + build_masks(grid, region="inband") + + # ------------------------------------------------------------------ temporal absorber diff --git a/tests/translate/test_modal.py b/tests/translate/test_modal.py index d45f1a5b8..566aabc98 100644 --- a/tests/translate/test_modal.py +++ b/tests/translate/test_modal.py @@ -175,6 +175,42 @@ def test_the_synthesis_carries_the_conversion_and_the_pad_scale( assert soliton_problem.transform.projection_coarse.tolist() == [[1.0]] +def test_a_grid_that_pads_carries_both_scales_into_the_compiled_term(): + """On the soliton's grid resolving the third harmonic the field is padded twice + over, so the pad and crop scales are 2 and 1/2 rather than 1, and dropping either + from the synthesis or the prefactor moves the compiled term off the scaffold.""" + grid = EnvelopeGrid.from_limits(1.0, WAVELENGTH, (500e-9, 2e-6), 4e-12, thg=True) + assert (grid.pad_scale, grid.crop_scale) == (2.0, 0.5) + gnlse = problem_from( + [0.0, 0.0, BETA2], omega_ref=grid.omega0, gamma=GAMMA, shock=False + ) + peak = abs(BETA2) / (GAMMA * TAU0**2) + soliton = SechPulse(wavelength=WAVELENGTH, width=TAU0, peak_power=peak).build(grid) + problem = assemble( + grid, + gnlse.mode, + [gnlse.kerr], + soliton, + controller=PIController(rtol=1e-8, atol=1e-14), + save_planes=[1.0], + dz_max=0.05, + dz_init=1e-4, + density=1.0, + shock=False, + prefactor_index=1.0, + ).problem + # One exact doubling of the conversion. + assert float(problem.transform.synthesis[0, 0]) == sqrtw_to_vm(gnlse.aeff) * 2.0 + state = soliton[0, 0] * grid.active_mask + reference = scaffold_nonlinear(gnlse, grid, state) + compiled = compiled_nonlinear(problem, state, window=False)[0] + scale = float(np.max(np.abs(reference))) + # As for the unpadded grid: the round-off of one extra multiplication over a + # reduction of length n_to, Higham's n*eps = 9216 * 2.2e-16 = 2.0e-12 of the + # largest term. A dropped scale is an error of order one. + assert float(np.max(np.abs(compiled - reference))) < 2e-12 * scale + + def test_a_constant_effective_area_needs_no_taper_table(soliton_problem, gnlse): assert soliton_problem.transform.taper_scale is None assert float(soliton_problem.transform.aeff(0.5)) == pytest.approx(gnlse.aeff) diff --git a/tests/translate/test_modal_path.py b/tests/translate/test_modal_path.py index 8109aaeea..667700650 100644 --- a/tests/translate/test_modal_path.py +++ b/tests/translate/test_modal_path.py @@ -607,4 +607,5 @@ def test_the_reference_s_maps_refuse_weights_that_do_not_match_them(moving_table + tables.synthesis[0, 2] - tables.synthesis[0, 3] + tables.synthesis[0, 4], + atol=1e-12 * np.max(np.abs(tables.synthesis)), ) diff --git a/tests/translate/test_plasma_integration.py b/tests/translate/test_plasma_integration.py index 2f08c7139..39adcead6 100644 --- a/tests/translate/test_plasma_integration.py +++ b/tests/translate/test_plasma_integration.py @@ -243,9 +243,9 @@ def test_mixed_rules_in_one_problem_are_refused_by_name(): def test_a_band_edge_at_nyquist_is_refused(): - """``ffac = 2`` puts 1.1 omega_max above the fine grid's Nyquist frequency.""" + """``ffac = 2.2``, the least on a field grid, puts 1.1 omega_max at Nyquist.""" with pytest.raises(TranslationError, match="Nyquist"): - design_running_integral(ladder_grid(2.0), "band") + design_running_integral(ladder_grid(2.2), "band") def test_an_ill_conditioned_fit_is_refused(monkeypatch): diff --git a/tests/translate/test_problem.py b/tests/translate/test_problem.py index fe88ded4f..f20648f65 100644 --- a/tests/translate/test_problem.py +++ b/tests/translate/test_problem.py @@ -267,7 +267,7 @@ def test_every_page_states_the_schema_the_code_writes(): is not a statement of the current one; the SEP records are history throughout. The kernel contract no longer has a number (ADR-068): it names the last one as history. """ - assert OUTPUT_SCHEMA_VERSION == 4 + assert OUTPUT_SCHEMA_VERSION == 3 stated: dict[str, list[str]] = {} for page in sorted(DOCS.rglob("*.md")): name = page.relative_to(DOCS).as_posix() @@ -1672,3 +1672,37 @@ def test_validate_pairs_the_plane_measure_with_spatial_geometry( ), radial_request, ) + + +def test_every_table_along_z_is_named_by_its_own_leaf(): + """A span refusal names the leaf a reader can find on the problem. + + A pressure gradient carries both the operator and the prefactor as parameter + expansions, so every optional weight table is present. + """ + from solprop.translate.problem import _walk_tables # noqa: PLC0415 + + grid = FieldGrid.from_limits(0.2, 800e-9, (200e-9, 4e-6), 100e-15) + mode = MarcatiliMode( + 125e-6, "He", PressureGradient.two_point(0.2, 2.0, 0.2), cladding=1.45 + ) + start = GaussianPulse(wavelength=800e-9, fwhm=10e-15, energy=1e-6).build(grid) + problem, _ = assemble( + grid, + mode, + [KerrResponse(chi3=2.2e-52, thg=True)], + start, + controller=PIController(rtol=1e-8, atol=1e-14), + save_planes=[0.1, 0.2], + dz_max=0.01, + dz_init=1e-4, + ) + assert problem.responses.prefactor_expansion is not None + for name, table in _walk_tables(problem): + found: object = problem + for part in name.split("."): + attribute, _, index = part.partition("[") + found = getattr(found, attribute) + if index: + found = found[int(index.rstrip("]"))] # pyright: ignore[reportIndexIssue] + assert found is table, name diff --git a/tests/translate/test_raman_kernels.py b/tests/translate/test_raman_kernels.py index a1a2eee71..7325e470a 100644 --- a/tests/translate/test_raman_kernels.py +++ b/tests/translate/test_raman_kernels.py @@ -103,7 +103,10 @@ def test_the_taper_edge_has_the_collars_own_width(grid): delays = delays_of(grid) span = float(delays[-1]) started = delays[taper < 1.0][0] - assert span - started == pytest.approx(grid.t_collar.width_high, rel=1e-3) + # A Planck edge rounds to one until exp(zeta) passes eps/2, over its first + # 1/37 or so (3.0 % here, with the sampling), so the first sample below one lies + # that far inside the edge. + assert span - started == pytest.approx(grid.t_collar.width_high, rel=5e-2) def test_a_collar_wider_than_the_response_span_is_refused(grid): diff --git a/tests/translate/test_tdse_admission.py b/tests/translate/test_tdse_admission.py index 018a559e3..ded22264d 100644 --- a/tests/translate/test_tdse_admission.py +++ b/tests/translate/test_tdse_admission.py @@ -221,14 +221,23 @@ def test_seam_rejects_a_changed_current_sign_or_crop_factor( ) -@pytest.mark.parametrize("flag", ["has_plasma", "has_raman", "mode_averaged"]) +@pytest.mark.parametrize( + ("flag", "reason"), + [ + ("has_plasma", "a plasma response"), + ("has_raman", "a Raman response"), + ("mode_averaged", "a mode-averaged transform"), + ], +) def test_seam_rejects_unsupported_flags_before_atomic_setup( - admitted, flag, admitted_request + admitted, flag, reason, admitted_request ): damaged = dataclasses.replace( admitted, flags=dataclasses.replace(admitted.flags, **{flag: True}) ) - with pytest.raises(TranslationError, match="scalar resolved modal Adams"): + with pytest.raises( + TranslationError, match=f"scalar resolved modal Adams route, not {reason}$" + ): validate_run(damaged, admitted_request) @@ -253,13 +262,19 @@ def test_seam_admits_the_input_draw_and_rejects_the_modified_one( if model == "input": validate_run(noisy, admitted_request) return - with pytest.raises(TranslationError, match="scalar resolved modal Adams"): + with pytest.raises( + TranslationError, match=r"Adams route, not the 'modified' noise model$" + ): validate_run(noisy, admitted_request) -@pytest.mark.parametrize("interpolate", [False, True], ids=["no-adams", "dense"]) +@pytest.mark.parametrize( + ("interpolate", "reason"), + [(False, "a method other than Adams"), (True, "interpolated save planes")], + ids=["no-adams", "dense"], +) def test_seam_requires_adams_and_landed_save_planes( - admitted, interpolate, admitted_request + admitted, interpolate, reason, admitted_request ): damaged, damaged_request = ( admitted, @@ -273,7 +288,7 @@ def test_seam_requires_adams_and_landed_save_planes( ) ), ) - with pytest.raises(TranslationError, match="scalar resolved modal Adams"): + with pytest.raises(TranslationError, match=f"Adams route, not {reason}"): validate_run(damaged, damaged_request) @@ -282,7 +297,11 @@ def test_seam_refuses_split_step_absorption(admitted, admitted_request): admitted, responses=dataclasses.replace(admitted.responses, absorber_scheme="split_step"), ) - with pytest.raises(TranslationError, match="scalar resolved modal Adams"): + with pytest.raises( + TranslationError, + match=r"Adams route, not the 'split_step' absorber scheme \(it takes the " + "in-stage 'nonlinear' one\\)$", + ): validate_run(damaged, admitted_request) diff --git a/uv.lock b/uv.lock index 486050bc5..859346faf 100644 --- a/uv.lock +++ b/uv.lock @@ -1681,6 +1681,7 @@ gui-test = [{ name = "pytest-qt", specifier = ">=4.5" }] name = "solprop-gui" source = { editable = "gui" } dependencies = [ + { name = "numpy" }, { name = "pyqtgraph" }, { name = "pyside6-essentials" }, { name = "solprop" }, @@ -1688,6 +1689,7 @@ dependencies = [ [package.metadata] requires-dist = [ + { name = "numpy", specifier = ">=2.5" }, { name = "pyqtgraph", specifier = ">=0.14" }, { name = "pyside6-essentials", specifier = ">=6.10.1" }, { name = "solprop", editable = "." },