# SEP 51 — One rule for the saved planes and the end of a run | | | |---|---| | **SEP** | 51 | | **Title** | One rule for the saved planes and the end of a run | | **Author** | John Travers | | **Drafting agent** | Opus 5.5 (2026-11-15) | | **Status** | Final | | **Review status** | Reviewed | | **Reviewers** | John Travers (human); GPT-6 (AI) | | **Type** | Change | | **Created** | 2026-11-15 | | **Resolution** | Accepted 2026-11-15 by John Travers in [PR #847](https://github.com/LupoLab/solprop/pull/847), after the GPT-6 review, decisions D1–D8 and the revision that answered R1–R10. | | **Requires** | — | | **Supersedes** | — | | **Superseded-by** | — | | **Implementation** | Opus 5.5 (AI), for John Travers. Phases 1 and 2 on `feature/sep-0051-save-planes`, [PR #851](https://github.com/LupoLab/solprop/pull/851) | | **Manual pages** | `guide/setup/running.md`, `guide/setup/recipes.md`, `guide/free-space/beams.md` | ## Part I — Proposal ### 1. Abstract Today a run's saved planes are written three different ways, depending on whether it is started from a keyword interface, from objects or from a recipe, and the end of the run is the last saved plane, never the length the run was set up for. This SEP gives every route one length and one pair of plane selectors. The length is stated once, as `length` or as `grid.length`, and it is both the upper limit and the end: every run marches from its entrance, `initial_z`, to its length, and always records both. `n_save` is a count of evenly spaced observations over that interval, both ends included, and `save_planes` is a list of positions inside it; a run takes one or the other, never both. Success means one placement rule in one helper, the same refusals on every route, recipe, Python export and front-end sheet, and, for every run that already ends at its length, the same numbers on `numpy_ref` and on the native CPU build. Backwards compatibility of configuration hashes, old recipes and old output files is not a requirement (§9). ### 2. Motivation and scope The trigger was [#533](https://github.com/LupoLab/solprop/issues/533). A recipe with `save_planes = 80` in an object route's `[build.settings]` passes `Recipe.check()` and is read as one plane at 80 m. The run then marches until something unrelated stops it. Investigating it showed that no route ties the run's end to its length: - On a **keyword route**, `length` builds the grid and sets the default steps. The run still ends at the last of the explicit `save_planes`, and positions beyond `length` are accepted. With `length = 1 mm`, `save_planes=[0.5 mm]` stops at 0.5 mm, and `[0.5 mm, 2 mm]` runs to 2 mm on a grid sized for 1 mm. A keyword route given both `length` and `grid=` keeps the grid without comparing the two. - On an **object route**, `grid.length` sizes the collar, the window and the default absorber rates, but the run ends at the last save plane, whatever `grid.length` says. In scope: - the meaning of `length`, `n_save`, `save_planes` and the run's end on every route that runs: the keyword interfaces, `Simulation(...)`, `Simulation.from_free`, `Simulation.from_planar`, recipes, scans and the front end; - interior launches, replay schedules, settings replacement, resume and the resolved recipe, as far as they read the planes or the end; - the refusals and their messages, and the migration; - how the end reaches the backends. Not in scope: - continuing a finished run to a longer length ([#141](https://github.com/LupoLab/solprop/issues/141)); - `fields=` and `field_planes=` on the `prop_*` functions ([#311](https://github.com/LupoLab/solprop/issues/311)), whose retention policy the observations here obey unchanged; - any change to stepping, tolerances or physics defaults; - `FixedSchedule`'s own construction (`FixedSchedule.uniform` and replay), which keeps its interface; only how its start and end relate to the run's interval is settled here; - replay for interior launches, which stays refused. ### 3. Context **Every way save planes are given today:** | Where | Count | Positions | End of the run | Beyond the length | |---|---|---|---|---| | Keyword routes (`prop_gnlse`, `prop_capillary`, `prop_waveguide`, `Simulation.from_gnlse`/`from_capillary`/`from_waveguide`, the general modal route) | `n_save`, counting `z = 0`; default `DEFAULT_N_SAVE = 201` | `save_planes`, m, `z = 0` implicit; exclusive with `n_save` | last plane: `length` for a count, the last position otherwise | accepted | | Object routes (`Simulation(...)`, `from_free` radial and Cartesian, `from_planar`) | none | `SimulationSettings.save_planes`, required | last plane; `grid.length` is not consulted | accepted | | Recipes, keyword routes | `n_save` | `save_planes` (resolvable to positions) | as the keyword route | accepted | | Recipes, object routes | none; `save_planes = 80` passes `check()` and is read as one plane at 80 m (#533) | `[build.settings] save_planes` | as the object route | accepted | | Front end, "Saved planes" | keyword sheets write `n_save`, counting the entrance | object sheets expand a count that **leaves out** the entrance into a list over `grid.length` (`even_planes` in `gui/src/solprop_gui/classes/problem.py`), and rewrite the list when the length changes | as the route | — | | TDSE capillary (`tdse=`) | given neither, the run saves the entrance and the end (`n_save = 2`) and every natural step (`step_planes = 1`) | as the keyword route | as the keyword route | accepted | **The length on keyword routes.** `length` is a required parameter, and `grid=` is an optional one. `_gnlse_grid` (`src/solprop/driver/routes/gnlse.py`) and `_capillary_grid` (`src/solprop/driver/routes/hollow.py`, shared by the general modal route) return a supplied grid without comparing its length with `length`. **What depends on the length.** Besides the end, `grid.length` sets the default absorber reference length, `grid.length / boundary_N` (`_reference_length` in `src/solprop/boundaries.py`), so the default spectral and temporal absorber rates scale inversely with it unless `boundary_length` is given. Keyword routes also derive default steps and longitudinal profiles from `length`. **Related mechanisms that read the planes:** - **`step_planes = k`** also saves the end of every `k`-th accepted step, beside the requested planes. - **`fields` and `field_planes`** decide which observations keep a stored field: `fields="none"` keeps statistics and step history only, `fields="planes"` keeps fields at the observation indices in `field_planes` (the entrance is 0 and negative indices count from the end), and `fields="all"` keeps them everywhere. `field_planes` is refused beside `step_planes`. - **`interpolate_planes`** observes planes inside steps, except the run's end and the hard kinks. - **`FixedSchedule`** has its own `z_start` and `z_end`, and its save planes must lie in `[z_start, z_end]`. A schedule that ends before the last plane fails at run time ("the replayed schedule ends at … and cannot reach …"). One that ends after it is accepted, and its tail is never run. `replay_tolerance` (`src/solprop/stepper/schedule.py`) already bounds how far a replayed edge may sit from a target: `LANDING_ULPS = 8` or the step count, whichever is larger, in ulps, because a sum of `n` rounded steps drifts by about `n` ulps. - **Landing.** The marches land on a target within `LANDING_ULPS` ulps of it. - **Interior launches.** `Simulation(initial_z=...)` already requires `initial_z < grid.length` and every plane to follow it, and refuses a fixed schedule (`src/solprop/driver/inputs.py`). `Simulation.with_input(..., initial_z=z)` keeps the *remaining* planes, those beyond `z`. - **Settings replacement.** The `Simulation.settings` setter accepts new settings before translation, and afterwards only a change of execution resources. It compares settings to protect a translated request and to decide whether an attached recipe still describes the run. - **Resume and the configuration hash.** The configuration records the positions (`configuration["save_planes"]`), so a count and the same positions hash alike. `driver/resume.py` distinguishes the requested planes from the last committed plane and a terminal checkpoint. `recipe.resume_file` rebuilds the recipe before the resume gate, and `output.hdf5.check_cache` compares the hash before opening a file for append. - **The resolved recipe.** `recipe/provenance.py:resolved_document` writes a keyword route's resolved planes and drops its top-level `n_save`, but leaves a nested `[build.settings]` table as written. - **Scans** count `len(settings.save_planes) + 1` planes per point. **The seam.** `assemble` (`src/solprop/translate/assembly.py`) "covers `[initial_z, max(save_planes)]`". `StepperSettings.z_end` (`src/solprop/translate/problem.py`) is `max(save_planes)`. No run end separate from the planes crosses the seam, in `RunRequest` or in `PropagationProblem`. **Issues and pull requests:** this SEP fixes [#533](https://github.com/LupoLab/solprop/issues/533) and is tracked by [#846](https://github.com/LupoLab/solprop/issues/846). It supersedes the narrow draft fix in [PR #843](https://github.com/LupoLab/solprop/pull/843), which checked object-route positions against `grid.length` and read an integer as a count; that pull request closes in favour of this SEP's implementation. It borders on [#141](https://github.com/LupoLab/solprop/issues/141), which continues a finished run, and [#311](https://github.com/LupoLab/solprop/issues/311), which concerns `prop_*` and `field_planes`; it changes neither. ### 4. Theory None. No equation, approximation or default of the physics changes. What changes is which positions are observed and how far a run goes. The run's length is a setup input with numerical consequences (the default absorber rates, and a keyword route's default steps and profiles, §3), so a test or example whose length is *changed* to fit the new rule changes numerically. §7 and Q7 treat that as a deliberate, qualified change, never as a neutral migration. ### 5. Proposed interface The maintainer's decisions D1–D8 (Part III) settle every choice below; the questions they answer are recorded in §12. **5.1 The length, stated once (D2).** On every keyword route, `length` becomes optional and keyword-only, and the same rule holds for a recipe's keyword-route parameters: | Supplied | Resolution | |---|---| | `length`, without `grid` | Build the grid with that length. | | `grid`, without `length` | Take the length from `grid.length`. | | Both | Require agreement under §5.4, then use `grid.length`; refuse a mismatch, naming both values. | | Neither | Refuse: "a length or a grid is required". | All length-dependent setup (the grid, default steps, profiles, the absorber's default reference length and the run's end) uses that one value. A supplied grid is never altered or rebuilt, and no conflict is settled silently. On an object route the length is `grid.length`. **5.2 The interval and its endpoints (D1).** Every run marches over `[initial_z, length]`. `initial_z` is 0 unless an interior launch sets it; `length` is the absolute end coordinate, so the distance propagated is `length - initial_z`. The entrance and the end are always observations: the entrance is observation index 0 and the end is index −1. An observation is a position where the run records its state; it does not imply a stored field. Every observation, the two endpoints included, obeys `fields` and `field_planes` unchanged, so `fields="none"` keeps statistics and step history only, and `fields="planes"` keeps fields only at the selected indices. Terminal checkpoints are separate and keep their restart policy. **5.3 The selectors (D3, D6, D8).** Every route takes the same two parameters, which are mutually exclusive: - `n_save=N`: an integer `N ≥ 2`. A fresh request places exactly `N` evenly spaced observations over `[initial_z, length]`, both endpoints included. - `save_planes`: a sequence of positions in m, finite and strictly increasing, inside `[initial_z, length]`. The entrance and the end are added when absent; either may be listed, and each appears once (§5.4). `save_planes=[]` requests only the two endpoints. Given neither, a run takes its route's default count: `DEFAULT_N_SAVE = 201` in general, and `n_save = 2` with `step_planes = 1` on the TDSE capillary (D6). Explicit settings take precedence over a route default. `step_planes` adds its natural-step observations to the requested ones, so the recorded count can exceed `n_save`. `SimulationSettings` gains `n_save`, and its `save_planes` becomes optional. **5.4 Endpoint rounding (D5).** A supplied position within `LANDING_ULPS` ulps of the end (the marches' existing landing tolerance) is the end, and becomes exactly `length`; the same holds at the entrance. Interior positions keep their supplied values. After normalization, one observation remains at each endpoint, and a position beyond the end or before the entrance is refused. When both `length` and `grid` are given, they agree when they are within the same `LANDING_ULPS` ulps, and `grid.length` is then the canonical value. For example, `0.1 + 0.2` and `np.nextafter(0.3, 0.0)` are both the end of a run of length `0.3`, and `0.31` is refused. **5.5 Refusals.** Every refusal is a `DriverError` in Python and a `RecipeError` in a recipe, with one message naming the fix: | Input | Message names | |---|---| | `save_planes=80` (a bare integer) | "pass `n_save=80`" | | `save_planes=0.25` (a lone float) | "pass `[0.25]`, or `n_save`" | | both `n_save` and `save_planes` | "give one of `n_save` and `save_planes`" | | `n_save` below 2, non-integral, or boolean | "`n_save` is an integer of at least 2" | | a non-finite, unsorted or repeated position | the offending position | | a position before the entrance or beyond the end | the position, the interval and "raise `length` (or `grid.length`)" | | `length` and `grid.length` that disagree | both values | | neither `length` nor `grid` on a keyword route | "a length or a grid is required" | | a replay schedule that does not cover the interval | the schedule's start or end and the run's (§5.7) | The integer form leaves the `save_planes` metadata, and `n_save` joins the object routes' settings metadata, so `Recipe.check()` refuses `save_planes = 80` with the same message. **5.6 Resolution and adoption (D3; R5).** Settings do not know the run's interval, so a count, an explicit list or the default is resolved where a simulation adopts settings and the interval is known. *Adoption* is every place settings meet a run: the `Simulation` constructor, the keyword builders, the `settings` setter, and the `with_*` methods, scans and reseeds that copy settings into a new run. At every adoption: 1. the settings are validated against the receiving run, whether they hold a count, a list or resolved positions; 2. they are resolved into the positions that follow the entrance and end exactly at `length`, and `n_save` becomes `None`; 3. comparisons (the setter's protection of a translated request, and of an attached recipe) are made on the resolved settings, so a count and its own positions compare equal. Resolution is idempotent: resolving resolved positions against the same run returns them unchanged, because the end is already present and normalization never adds a second one. Settings reused on a run with another length are validated afresh, as explicit positions: a position beyond the new end is refused, and a shorter list gains the new end. To carry a *count* to another run, pass the authored settings, or `dataclasses.replace(settings, n_save=N, save_planes=None)`; the message for "both given" says so. After translation the setter still refuses any change to the planes. `Simulation.with_input(..., initial_z=z)` does not request a new count. It keeps the already resolved observations beyond `z`, which always include the end, and records the new entrance at `z` (D3). One private helper holds the placement, normalization and refusal rules; the keyword routes' `_save_planes` in `src/solprop/driver/settings.py` becomes it. **5.7 Replay schedules (D4).** On routes that support replay, a `FixedSchedule`'s start must agree with the entrance under §5.4's tight rule, and its end with `length` within `replay_tolerance`, which allows the step sum's accumulated rounding. A shorter or longer schedule is refused at adoption, before execution; a longer tail is never ignored and the steps are never adjusted to fit. Interior launches keep refusing replay. **5.8 How the seam carries the end.** The driver guarantees that the last resolved position *is* `length`, so `StepperSettings.z_end = max(save_planes)` is the run's end with no new field. `assemble` and below keep their meaning, and `RunRequest`, `PropagationProblem` and the frozen tables of `tests/backends/test_driver.py` are unchanged. A caller of `assemble` directly, below the driver, still ends at its last plane, so a deliberately short test may live there. **5.9 Recipes, export, provenance and resume (R6, R7).** - *Authored text.* Recipes and the Python export keep what the author wrote: `n_save`, `save_planes`, `length` or `grid`, or neither selector. - *The resolved recipe* (`Recipe.from_output(..., resolved=True)`) rebuilds the same run without depending on defaults. It writes only the canonical resolved positions, ending at the length, at the level the route reads them (top level on a keyword route, `[build.settings]` on an object route), and drops `n_save`. A route default, the TDSE `n_save = 2` and `step_planes = 1` included, is written out resolved, so a later change of a default does not change the rebuilt configuration hash. - *Resume* continues a file to its *declared* end, the last requested position in `configuration["save_planes"]`, which equals `grid.length` for every file written under this SEP. That is distinct from the last committed plane and from a terminal checkpoint: an interrupted file, or one that holds a terminal checkpoint, resumes as today. No compatibility path is kept for files written before this SEP; they meet the existing hash refusal. **5.10 The front end (D7).** Object and keyword sheets offer two modes for the saved planes: "Evenly spaced" edits `n_save`, counting both endpoints, and "Explicit positions" edits `save_planes`. Switching modes replaces the other selector in one undoable edit, so a document never holds both. A length change redistributes a count automatically. Explicit positions stay as entered: the automatic end follows the new length, and a position beyond a shortened length is a validation error shown on the field. A loaded document opens in the mode of the selector it holds; an arbitrary list is never shown as, or replaced by, its count. ```text Simulation.from_free(grid, space, medium, responses, beam, settings=SimulationSettings(n_save=81)) # 81 observations over [0, grid.length] SimulationSettings(save_planes=[0.05]) # grid.length = 0.1: entrance, 0.05 m and the end SimulationSettings(save_planes=[]) # entrance and end only Simulation(..., initial_z=0.04, settings=SimulationSettings(n_save=4)) # grid.length = 0.1: 0.04, 0.06, 0.08, 0.1 m SimulationSettings(save_planes=80) -> DriverError: "... pass n_save=80" SimulationSettings(save_planes=[0.3]) -> DriverError at adoption: "0.3 m is beyond the end, grid.length = 0.25 m; ..." prop_gnlse(..., length=1e-3, grid=grid) -> DriverError if grid.length = 1e-4: names both ``` ```text [build.settings] type = "SimulationSettings" n_save = 81 # was a list of 80 positions in the filament recipe ``` ### 6. Implementation strategies - **Layer.** The driver and the recipe layer, plus the front end. The physics and backend layers are untouched, and so is the seam (§5.8). - **Where the rules apply.** One helper places, normalizes and refuses; one adoption function calls it for every adoption in §5.6, so no route has its own copy. The keyword routes resolve `length` against `grid` (§5.1) before anything that depends on the length, then build their `Simulation` through the same adoption. - **Replay** is checked in the same adoption function, with `replay_tolerance` for the end and the tight rule for the start. - **Resume** reads the declared end from the stored configuration in `driver/resume.py`, and the recipe-driven path reaches the same gate. - **Backends.** Nothing backend-specific. `numpy_ref` and the native CPU build run the same requests as today for every run that already ends at its length from `z = 0`. - **Cost estimate** (`poe size`): | | Added | Removed | |---|---|---| | Code | about 250 lines: the helper and refusals, adoption in the setter and `with_*`, `n_save` on settings, `length`/`grid` resolution, replay checks, the resolved recipe, the front-end modes | about 60 lines: the front end's plane rewriting and list expansion, the routes' private length handling | | Docstrings | about 100 lines | — | | Tests | about 450 lines: the refusal table, the rounding cases, count/positions parity, the end rule and interior launches per route, adoption and reuse, replay, resume, the resolved recipe, the front-end modes | — | Separately, an estimated 10–30 existing tests, snippets and examples need edits (Q7). - **Dependencies:** none. ### 7. Verification and validation - **Refusals.** Every row of §5.5's table, on every route kind, in Python and in a recipe, with its message. - **Endpoint rounding.** Positions one representable value below, equal to and above the end (`np.nextafter(0.3, 0.0)`, `0.3`, `0.1 + 0.2`) and just beyond `LANDING_ULPS`; `length` and `grid.length` agreeing within and outside the bound; and resolving twice, which adds no plane. - **Parity.** `n_save=N` and the positions it resolves to give identical settings, hash and output. This is an exact structural check, since both resolve to the same array; it says nothing about an independently written decimal list (R9). - **End rule.** Per route kind, the first observation is the entrance, the last equals the length, and the count is as specified. Direct interior launches with `n_save`, on and off the lattice of a zero-based count; `with_input(initial_z=…)` keeping the remaining observations and the end; `save_planes=[]`; listed endpoints appearing once. - **Adoption.** Construction, replacement through the setter, repeated adoption, reuse of resolved settings at another length, the count/list switch, and the existing refusal to change a translated run's planes. - **Replay.** `FixedSchedule.uniform` and `from_history` schedules whose sums drift below and above the length within `replay_tolerance` are accepted; genuinely shorter and longer schedules, and a start that is not the entrance, are refused before execution. - **Resume and provenance.** Interrupted, terminally checkpointed and completed files resume to the declared end, directly and through `recipe.resume_file`. Resolved recipes round-trip through `Recipe.from_output(..., resolved=True)` for a count, explicit positions, neither selector and the TDSE default, and the rebuilt hash does not change when a default count is changed. - **Unchanged numbers.** For runs that already end at their length from `z = 0`, the request is bit-identical on its frozen fields, and a short run (about ten steps) per route kind on `numpy_ref` and native CPU matches its pre-change output within the rounding budget of SEP 25. Identical numbers are not identical hashes: hash preservation is not required (§9). - **Changed numbers.** A test or example whose length or planes change is a deliberate change, recorded and re-qualified on `numpy_ref` and native CPU (Q7). - **Front end.** Both modes, the switch as one undoable edit, length changes in each mode, uniform and non-uniform loaded lists, save and reload. ### 8. Documentation - **Manual pages:** - `guide/setup/running.md`: the length stated once, the interval, the two selectors, the endpoints and endpoint rounding; - `guide/setup/recipes.md`, including the resolved recipe; - the free-space and planar pages that use the `np.linspace(0, length, N)[1:]` idiom, which becomes `n_save` where natural; - the front end's page on saved planes and its two modes. - **Docstrings:** `SimulationSettings`, `Simulation` and its `settings` setter, `with_input`, `from_free`, `from_planar`, the keyword interfaces (`length` and `grid`), and the recipe metadata. - **Changelog:** a `.changed` fragment with the migration (Q7), and a `.fixed` fragment for #533. - **Examples:** the filament and crossing-beam recipes and galleries may switch to `n_save`. A converted example is a migration whose positions, and so whose hash, may differ in the last bit; an edited gallery is regenerated under the documentation policy. ### 9. Compatibility and impact This is a breaking change to the public interface, and backwards compatibility is not a requirement (maintainer, Part III): pre-change configuration hashes, old recipes and old output files do not constrain it. Newly created runs must still reproduce their recorded configuration, and numerical correctness and rounding bounds still hold. Every break is either refused with a message naming the fix or listed in the changelog (Q7). The output schema, the kernel contract and the frozen seam tables are unchanged. Validated results are unchanged wherever a run already ends at its length; where a test's length or planes are changed instead, its numbers change deliberately (§4). No deliberate difference from Luna.jl is introduced. ### 10. Alternatives considered - **Keep positions as the end, and only check against `grid.length`.** This was the first fix for #533 (PR #843). The maintainer rejected it because two conventions would remain. - **Read an integer `save_planes` as a count.** This overloads one name with two meanings, and the keyword routes already spell the count `n_save`. - **Make the run end a separate field of the seam,** so positions short of the length need not save the end. This needs a seam change with frozen tables; recording the end always (D1) makes it unnecessary. - **Refuse positions that do not end at the length.** Rejected for D1: the end is added, as the entrance is. - **Count `n_save` over `[0, length]` and filter for interior launches.** This was the draft's rule and R4's recommendation; D3 counts over the launched interval instead, so a count always means that many observations. - **Prefer one of `length` and `grid` when both are given.** Rejected for D2: a conflict is refused, never settled silently. - **A fixed "few ulps" allowance for a replay's end.** It refuses valid schedules whose step sums drift (R2); D4 uses `replay_tolerance`. ### 11. Phases 1. **Driver and recipes.** - Survey first: run the affected test modules with an instrumented adoption, to count every run whose end moves, whose positions are refused, and whose keyword route passes both `length` and `grid` (Q7). - Deliverables: the helper, adoption, `n_save` on settings, `length`/`grid` resolution, the refusals, the end rule on every route, replay, resume, the recipe metadata, export and resolved recipe, the tests and edits, the manual pages and the changelog. - Verify: §7 on `numpy_ref` and the native CPU build. 2. **Front end.** - Deliverables: the two modes on every sheet, with the list rewriting removed; the front-end gate. Both phases are small, and may merge as one pull request. ### 12. Open questions None remain. The draft's questions were settled by the maintainer after the AI review (D1–D8, Part III): - **Q1 — positions short of the length:** the end is always recorded, appended when absent (D1). - **Q2 — positions beyond the length:** refused on every route, after endpoint rounding (D1, D5). - **Q3 — a replay schedule's ends:** both must cover the interval; the end within `replay_tolerance` (D4). - **Q4 — the TDSE default:** kept as a route default, `n_save = 2` and `step_planes = 1` (D6). - **Q5 — `step_planes` and `field_planes`:** unchanged; observations obey the retention policy, and `-1` is always the end (D1, D6). - **Q6 — resume, interior launches and `with_*`:** counts are over the launched interval (D3); `with_input` keeps the resolved remaining observations (D3); resume reads the declared end, and no legacy path is kept (compatibility constraint). - **Q7 — migration and blast radius:** below. **Q7 — Migration and blast radius.** The breaks, each with its message: 1. `save_planes=N` as a bare integer: refused, "pass `n_save=N`", in Python and in recipes. 2. `save_planes=x` as a lone float: refused, "pass `[x]`, or `n_save`". 3. A position before the entrance or beyond the end: refused, naming the interval. 4. Positions short of the length: the run now continues to the length and records it. This raises no error and is listed in the changelog. Indices counted from the end (`field_planes=[-1, …]`) then point to different planes. 5. A replay schedule that does not cover the interval: refused. 6. `length` is keyword-only and optional on keyword routes; a positional `length` fails with Python's own error, and `length` with a disagreeing `grid` is refused. 7. `n_save` with an interior launch counts over `[initial_z, length]`. 8. The front end's object sheets: "Saved planes" becomes a mode. A saved document holds the expanded list, so it opens as "Explicit positions", unchanged. A count entered as 80 on an object sheet today gave 81 observations with the entrance; the same planes are now "Evenly spaced" with `n_save = 81`. *Blast radius, from a static survey of the tree at 2026-11-15:* - **Object-route files.** About 117 files build an object-route simulation with save planes: 84 in tests, 15 in the manual and galleries, 4 in benchmarks and 3 in the package. - **Unchanged.** About half write the end as the length symbolically (`[grid.length]`, `[LENGTH]`, `[length]`, a `linspace` ending at the length). Most of the rest write a literal equal to the grid's literal length. - **Flagged.** A pattern scan flags 11 files as possible mismatches. A manual check confirmed two: - `tests/backends/test_far_field_statistics.py`: planes at 0.1 mm on a 1 mm grid, so the run would end later; - `tests/driver/test_initial_z_and_checkpoint.py`: a plane at 1 mm on a 0.1 mm grid, which would be refused. The others depend on fixtures, construct settings without running them, or call `assemble` below the driver, which is unaffected. - **Recipe examples.** None of the nine object-route example recipes is affected: each ends at its `grid.length`. Neither is any gallery script found. - **Keyword routes.** Explicit positions short of `length`, positional `length` and `length` beside `grid=` are counted in phase 1. **How a flagged test is fixed (R3).** Shortening a grid is not neutral: it raises the default absorber rates in proportion, and on a keyword route it can change the default steps and profiles. A fix therefore first asks what the test means: - *A deliberately short window of a longer setup* keeps its length and physics: it keeps the original grid and records the end, or pins `boundary_length` (and any step or profile choice) to the original values before shortening the grid, or moves below the driver to `assemble`, which still ends at its last plane. - *A mismatched setup* is corrected to the intended length, and its numerical change is recorded and re-qualified. Replacing the planes by `n_save` extends a short run; it never preserves the short window. ### 13. References None beyond solprop's own documentation and issues, cited where used. ## Part II — Implementation record ### Phase 1 — Driver and recipes **Scope.** 2026-11-16; Opus 5.5 (AI) for John Travers; branch `feature/sep-0051-save-planes`, commits from `e8de3270` (the helper and adoption) to the commit that appends this report. The front end (§5.10, phase 2) is untouched. **Survey (§11), before any call site was edited.** An instrumented `Simulation.settings` setter and the two grid helpers recorded, for every run the default test lane builds, what the new rule would do. The lane was cancelled from outside at 91 % (twice; the numbers are of the second run); the slow lane and `native/tests` were not run. | What the rule changes | Count | |---|---| | The run's end moves later (last plane before `grid.length`) | 371 adoptions, 189 tests, 52 call sites in 25 files | | A plane beyond the end, refused | 1 (`tests/output/test_record_arrays.py`, a `length` of 1 cm on a 10 µm grid) | | A plane before an interior launch, refused | 1 (already a refusal test) | | A replay schedule not covering the run, refused | 92 adoptions, 32 tests, 16 sites in 10 files | | A replay start that is not the entrance | 0 | | A plane normalized onto the end | 0 | | A keyword call with both `length` and `grid` | 2199 calls at 224 sites; 43 calls at 13 sites disagree | A static scan of the tree (Python files and the Python blocks of Markdown pages) found 509 keyword-route calls that pass `length` positionally, in 227 hand-written files (150 test files, 43 gallery scripts, 12 guide pages, 12 native tests, 5 benchmarks, the README, two package files and one design page), and 185 call sites passing `length` beside `grid=`. That count is what decided the first deviation below. **Delivered.** - `src/solprop/driver/settings.py`: `SimulationSettings.n_save`, an optional `save_planes`, and four private helpers: `_selectors` (the refusals that need no interval), `_observation_planes` (placement, endpoint normalization within `LANDING_ULPS` ulps of each endpoint, the interval refusals; it replaces `_save_planes`), `_run_length` (the length/grid table of §5.1) and `_adopted` (the entrance check, the replay check of §5.7 with `replay_tolerance`, and resolution). - `src/solprop/driver/simulation.py`: the `settings` setter adopts every settings object through `_adopted` before any comparison, so the constructor, the keyword builders, `with_input`, `with_mixture` and anything else that builds a `Simulation` share one rule; `length` is optional on `from_gnlse`, `from_capillary` and `from_waveguide` and resolved by `_run_length` before anything uses it; the keyword routes pass `n_save` and `save_planes` through unresolved. `src/solprop/driver/interface.py`: the same signatures on `prop_*`. `src/solprop/driver/routes/general.py`: the general modal route's tables span `grid.length`, the run's end. - `src/solprop/recipe/`: the settings metadata drops the integer form of `save_planes` and gains `n_save`; `refuse_plane_count` refuses `save_planes = N` with "write `n_save = N`" on every route; `plane_parameter` turns the driver's refusals of the planes, the length and replay into a `RecipeError` naming the keyword, in `build_object` and `Recipe.build`; a keyword-route recipe with neither `length` nor `grid` is refused before the route is called; `resolved_document` writes the resolved positions in `[build.settings]` on an object route (and at the top level otherwise) and drops `n_save`. - `benchmarks/builders.py`: `window`, which runs a case to a shorter stop (`ab --length`) by rebuilding it on its grid cut at the stop, carrying the whole case's collar, steps and profiles; `benchmarks/sessions.py` and the linear GRIN case use it or cut their own grid. - Tests: `tests/driver/test_save_planes.py` (the refusal table, placement and endpoints, the rounding cases, count/positions parity of planes and hash, interior launches on and off a zero-based lattice, `with_input`, setter replacement and reuse at other lengths, the length/grid table on all three keyword routes, replay drift and refusals) and `tests/recipe/test_save_planes.py` (refusals as `RecipeError` with their paths on object and keyword routes, `n_save` in settings, the resolved recipe for a count, a list, a short list and no selector, and its independence of the default count). `tests/builders.py` gains `grid_at` and `held_collar`. - Pages: `docs/guide/setup/running.md` (a section on the length and the saved planes), `docs/guide/setup/recipes.md` (the settings' selectors and the resolved recipe), `docs/guide/free-space/beams.md` (the `linspace` idiom becomes `n_save`); docstrings of `SimulationSettings`, `Simulation`, its setter, `with_input`, `from_free`, `from_planar` and the keyword routes. Changelog: `changelog.d/sep-0051-save-planes.changed.md` (the migration) and `changelog.d/533-save-planes-count.fixed.md`. **Existing tests changed (Q7's closing paragraph).** No tolerance was changed. - *A short window of a longer grid, physics kept* (the grid cut at the run's end with `grid_at`, the collar the longer grid gave with `held_collar` or by building it on the longer grid, and a length-derived default step pinned where one applied): the sixth-order soliton of `tests/driver/test_prop_gnlse.py`; the general modal fixtures of `test_general_modal.py`, `test_modal_metrics.py`, `test_modal_resume.py`, `test_material_manifest.py`, `test_modal_launch.py` (also `dz_max`) and `test_route_keywords.py`; the far-field cases of `test_far_field_statistics.py` and `test_native_far_field.py`; two planar-hybrid runs; `tests/record_routes.py`. - *A `length` that disagreed with `grid`* (the run's own end kept, the grid built there, the collar pinned): `tests/backends/adams_source_cases.py` (the Adams source ladder), the general entry point of `tests/backends/general_rows.py`, the native noisy-run reference of `test_native_session_history.py`, the two capillary receivers of `tests/coupling/test_workflows.py`, the wide case of `tests/coupled_flow_cases.py` (its collar was already pinned), `test_vector_coupling.py` and the linear GRIN benchmark. - *Construction or refusal only, shortened freely*: three cases of `test_simulation.py`, `test_backend_default.py`, `test_record_arrays.py`, one refusal of `test_coherent_capillary.py`, `tests/translate/test_routes.py` and two far-field geometry refusals. - *Replay*: the dispersive capillary's one-step row now records its whole replayed schedule (the rung takes the first step alone, so the step is unchanged); `tests/sessions/test_group.py`'s schedule past the last plane, which existed to test the ignored tail, is now a refusal test. - *Messages and harness*: `tests/recipe/test_pins.py` (the refusal of a recipe with neither length nor grid), `tests/test_benchmark_cases.py` and `tests/test_benchmark_guides.py` (a shortened case's grid is cut at its stop, with the whole case's collar and steps). **Deviations from the proposal.** 1. *`length` is optional but stays positional-or-keyword* (§5.1, Q7 item 6). Making it keyword-only would edit about 509 calls in 227 files and regenerate 43 galleries. The maintainer accepted this deviation on 2026-11-16, so the positional form stays. Because Python allows no required parameter after an optional one, `from_capillary`'s and `prop_capillary`'s `gas` now defaults to `None` and is refused when omitted. A hazard for the keyword-only form: with `length` keyword-only, the next positional parameter (`betas` on the GNLSE routes, `gas` on the capillary and waveguide routes) takes the freed slot, so `from_capillary(r, 0.2, "Ar")` would bind `0.2` to `gas` instead of failing with Python's own error; a guaranteed failure would need those parameters keyword-only as well. 2. *A recipe with neither `length` nor `grid`* is refused by the recipe before the route is called, as "a length or a grid is required" against `length`, rather than by the route; otherwise a recipe with pins reported it against the pinned keyword. 3. *A recipe's integer `save_planes`* says "write `n_save = 80`", the recipe's spelling, where Python says "pass `n_save=80`". 4. *Endpoint slack* is `LANDING_ULPS` ulps of the endpoint itself (§5.4, D5), so at an entrance of zero it is exact; the replay check is skipped for an interior launch, which the existing rule refuses with its own message. **Decisions.** - Resolution returns the same settings object when they are already resolved for the run, so a repeated adoption is free and a translated run's settings compare by identity. - The default count is read when the planes are resolved, not when the helper is defined, so the resolved-recipe test can change it. - The benchmark harness rebuilds a shortened case rather than running the whole one, and refuses to shorten `grin_nonlinear`, which is translated at construction. **Verification.** `numpy_ref` and the native CPU build on the Xeon, eight logical CPUs, one thread per worker. Passing: the 29 modules the survey flagged and every module edited, the two new modules, `tests/recipe`, the resume and scan modules of `tests/driver`, `tests/test_guide_snippets.py`, and the doctests of the edited source modules, `tests/backends/test_parity_catalogue.py` (737 tests with `test_coherent_capillary.py`), and the 15 modules touched only to satisfy the type checker. Repository-wide `ruff check`, `ruff format --check` and `basedpyright` (0 errors) pass; numpydoc, codespell, `reuse` and `tests/test_seps.py` pass on the touched files. Not run locally: the full default lane, the slow lane, the coverage lane, `native/tests`, the front-end gate and the galleries; CI is the gate. **Sources checked.** None needed: no constant, coefficient or citation was transcribed. **Limitations.** - The survey covers 91 % of the default lane. - Other setup depends on `grid.length` besides the default absorber, and is not pinned when a test's grid is cut: `LossPolicy.limit(grid.length)` clamps a mode's attenuation (`src/solprop/linear.py`), the boundary monitor's quiet-window spacing is `grid.length / CHECKS`, and the walk-off warning integrates over `grid.length`. None of the changed tests moved; §3 does not list them. - `test_modal_launch.py`'s general runs keep the default first step, which is a fraction of the length and refined by the start-up rule; their checks are of the launch. - A recipe cannot hold a TDSE response (`tdse` has no recipe form), so the TDSE capillary's resolved recipe is checked at construction, through `resolved_document`, not round-tripped through `Recipe.from_output`. Added after review: `tests/driver/test_save_planes.py` resumes an interrupted file, one holding a terminal checkpoint and a completed one to the length, directly and through `recipe.resume_file`, and replays `from_history` and `uniform` schedules drifting below and above the length; `tests/recipe/test_save_planes.py` rebuilds a run from its file's resolved recipe with `DEFAULT_N_SAVE` changed, keeping its hash. **Open questions.** - Q8: keyword-only `length` (deviation 1), with the slide of `betas`/`gas` into its slot. Settled by the maintainer: `length` stays positional-or-keyword. - Q9: `driver/scaffold.py`'s fixed-step tool had its own `n_save`, which did not count the entrance. Settled by the maintainer: it now takes SEP 51's meaning, evenly spaced planes over `[0, z_end]` with both ends counted, at least 2. - Q10: whether the loss clamp and the monitor spacing should follow a pinned reference length, as the absorber's does. Owner: an issue. **Cost** (`git diff --numstat` against `094a7fb8`): package code and docstrings +473 −113 lines (`src/`), benchmarks +94 −12, tests +758 −121 (of which 507 in the two new modules and 29 in `tests/builders.py`), manual pages +72 −2. The proposal estimated about 250 code lines, 100 docstring lines and 450 test lines, and 10–30 edited tests; about 45 existing test and benchmark files were edited, about a third of them only to wrap a now-optional `save_planes` for the type checker. **Handoff.** Phase 2 (§5.10) needs the object sheets to stop expanding a count into a list over `grid.length`: the settings metadata now offers `n_save` beside `save_planes` (an array only), and the resolved planes always end at the length. ### Phase 2 — Front end **Scope.** 2026-11-16; Opus 5.5 (AI) for John Travers; branch `feature/sep-0051-gui`, on phase 1, commits from `3646b0e5` (the sheets) to the commit that appends this report; carried onto `feature/sep-0051-save-planes` as `d3702160` to `e410e79f`. **Delivered.** - `gui/src/solprop_gui/classes/problem.py`: `Field.positions` replaces `planes_over` and `moves_planes`. A saved-planes row reads the positions a recipe lists, or else its count, and never turns a list into its count; its change writes a list as the positions and anything else as the count, and unsets the other selector in the same change. `even_planes` and the length row's rewriting of the list are removed. `sheet_paths` and `other_keywords` count the positions as the row's, so the keyword routes' `save_planes` leaves Advanced. - `gui/src/solprop_gui/classes/catalog.py`: every class's "Saved planes" row is `n_save` with `positions="save_planes"`, at the top level on the keyword routes and in `settings` on the object routes; the object sheets' length rows no longer move planes. - `gui/src/solprop_gui/ui/fields.py`: a row may name its forms (`mode_titles`); its picker then shows them on a sheet, its text editor shows only what no other editor holds, and leaving the text as shown writes nothing, so switching forms never replaces a value by itself. `ParameterRow.current_mode` is new. - `gui/src/solprop_gui/ui/sheet.py`: the row offers "Evenly spaced" (the count's integer form) and "Explicit positions" (the positions' array form, as inline TOML). One value typed as positions is a list of one. An issue on the positions shows at the row. - Tests: `gui/tests/test_classes.py` (both forms on every class, at the route's level; a uniform and a non-uniform loaded list shown as lists; each form replacing the other, and clearing both; a length change moving the length alone; a count on the filament built by solprop, ending at the shortened length, and a position beyond it refused at `settings.save_planes`). `gui/tests/test_ui_workflow.py` (the keyword sheet: it opens on its count; a length change keeps the count; switching forms writes nothing until an entry; the entry replaces the count in one undoable edit, undone and redone; a lone position; a position beyond a shortened length shown at the row and the Ready line; save and reopen on the positions; back to a count; a non-uniform list opening as itself; and the filament's object sheet opening its listed planes as explicit positions, replaced by a count and restored by one undo). Every step checks that the recipe never holds both selectors. - Pages: `docs/guide/front-end/first-run.md` (the row's two forms), `docs/dev/gui/design.md` (W3's rows and the numerics line), and a front-end sentence in `changelog.d/sep-0051-save-planes.changed.md`. **Deviations from the proposal.** None in behaviour. One reading of §5.10: switching the picker shows the other form's editor, empty, and the first entry there is the one undoable edit that writes it and removes the other selector. A switch alone writes nothing, because a count has no positions to show and a list has no count (D7), so neither can be written for the user. **Verification.** On the Xeon, through Slurm, one thread per worker: `ruff format`, `ruff check`, codespell on the touched files, `poe gui-types` (0 errors) and `poe gui-docstrings` pass; `tests/test_classes.py` and the doctests of `solprop_gui.classes` and `ui/fields.py` (91 passed); the whole front-end suite without coverage, 440 passed: 433 in one run, and the seven that start a run passed when rerun with the Slurm job's environment unset (inside a Slurm job, a run's worker records itself as a Slurm job, which the window then cannot follow; they fail the same way on phase 1's commit). `tests/test_seps.py`, `poe changelog-check` and the Sphinx build (`-W -n`) pass; the build first failed on a cross-reference phase 1 added to `guide/setup/recipes.md` (`solprop.recipe.RecipeError`, documented as `solprop.recipe.errors.RecipeError`), corrected in its own commit. Not run locally: `gui-test` with coverage (the 100 % bar on `classes`), which CI runs. **Sources checked.** None needed. **Limitations.** The positions are typed as inline TOML (`["5 cm", "10 cm"]`), as Advanced edits them; a friendlier list editor is not part of this phase. Advanced's `settings` editor on the object routes still shows `n_save` and `save_planes` side by side, so a recipe edited there can hold both, which solprop's check refuses at the row. **Cost** (`git diff --numstat` against `ccadb278`): front-end code +133 −88 (`classes` +47 −68), tests +206 −20, pages +17 −2 and the changelog +5. The proposal estimated about 60 lines removed plus the new field and its tests. ## Part III — History - 2026-11-15: Drafted, after the investigation of #533 found that no route ties the run's end to its length. Tracking issue: [#846](https://github.com/LupoLab/solprop/issues/846). - 2026-11-15: GPT-6 completed an AI review of Part I at PR #847, commit `4d9af1fc480399c7f8e28814a16f32ca2e257f03`. Findings and questions follow; Part I is unchanged. - 2026-11-15: John Travers reviewed the proposal and recorded decisions D1–D8. The drafting agent revised Part I to match and responded to R1–R10. - 2026-11-15: Accepted by John Travers in PR #847. Part I is frozen. - 2026-11-15: Implementation started on `feature/sep-0051-save-planes`. - 2026-11-16: Phase 1 (driver and recipes) reported in Part II, with an interim deviation on keyword-only `length` pending with the maintainer. - 2026-11-16: Phase 2 (front end) reported in Part II, on `feature/sep-0051-gui`. - 2026-11-16: Final. Both phases are reported in Part II and merge in PR #851. Open questions moved to issues: keyword-only `length` ([#857](https://github.com/LupoLab/solprop/issues/857)), the fixed-step scaffold's `n_save` ([#856](https://github.com/LupoLab/solprop/issues/856)) and further length-dependent defaults ([#855](https://github.com/LupoLab/solprop/issues/855)). - 2026-11-16: The maintainer settled Q8 (`length` stays positional-or-keyword) and Q9 (the scaffold's `n_save` takes SEP 51's meaning, in PR #851). ### AI review — 2026-11-15 Reviewer: **GPT-6 (AI), acting as reviewer only.** Read all of Part I, the PR discussion, #533 and #846, and the relevant driver, translation, schedule, resume, recipe and front-end code at the commit above. Also read the overlapping draft [PR #843](https://github.com/LupoLab/solprop/pull/843), which #846 says this work will supersede. That relationship should be recorded in the proposal's context. The shared count/positions interface and the proposed Q1 A, Q2 A and Q4 A choices are reasonable. The points below need answers before acceptance; this review does not resolve the maintainer's open questions. Priorities are **High** for conflicts that can change a run or reject an existing valid one, and **Medium** for missing contracts or qualification. Small construction and arithmetic probes were run on this tree; their results are stated below. No propagation was run, and no native or GPU numerical qualification is claimed. 1. **R1 — High: settle the length when a keyword route receives a grid (§§3, 5.1, 6, 7; Q2).** The statement that a keyword route's `length` and `grid.length` are the same because the route builds the grid has an existing exception: the public `grid=` keyword. `_gnlse_grid` in `src/solprop/driver/routes/gnlse.py` and `_capillary_grid` in `src/solprop/driver/routes/hollow.py` return a supplied grid without comparing its length. A construction probe of `Simulation.from_gnlse` with `length=1e-4`, a grid of length `1e-3`, and `n_save=2` retained that grid and placed the last plane at `1e-4` m. Running the proposed resolver first against the keyword length and then against the adopted grid can therefore append a different end, or refuse a run the keyword resolver accepted. **Question and recommendation:** must the two lengths agree when `grid=` is supplied? Recommend an early refusal naming both values, with an explicit rounding policy and migration guidance; do not silently choose an end or rebuild the grid. Add this break to Q7 and cover supplied grids in Python and recipes, including the general modal path that shares `_capillary_grid`. 2. **R2 — High: use the existing accumulated-rounding bound for a replay's end (§§7, 9; Q3).** A fixed allowance of "a few ulps of the length" rejects valid schedules whose steps accumulate rounding error. The probe `FixedSchedule(np.full(160, 1e-3 / 160))` ended 12 ulps below `1e-3` m; 1,000 equal steps ended 70 ulps above it. Both are admitted by the existing `replay_tolerance` in `src/solprop/stepper/schedule.py`, which accounts for the step count. This conflicts with the promise to keep valid runs that already reach their length unchanged. **Recommendation:** state the endpoint comparison in terms of the existing replay bound, or derive and qualify a replacement before acceptance. Keep the start comparison distinct: it has no accumulated step sum. Require acceptance tests for rounding drift on both sides, `uniform` and `from_history`, and refusal tests for a genuinely shorter or longer schedule outside that bound. Explain where the check lives without changing the promised semantics of direct `assemble` callers. 3. **R3 — High: changing the grid length is not a neutral migration (§§4, 7, 9; Q7's final paragraph).** The proposed migration says that a fix never changes a physics setting and can simply set the grid's length to the intended end. However, `_reference_length` in `src/solprop/boundaries.py` defaults to `grid.length / boundary_N`; both spectral and temporal rates depend inversely on that length. A probe shortening an otherwise identical grid from `1e-3` to `1e-4` m increased its default nonzero rates by a factor of ten, to rounding. A keyword route can also derive steps and longitudinal profiles from its length. These changes can alter results within the retained short window, even though no propagation equation is being redesigned. **Recommendation:** distinguish a deliberate correction of a mismatched setup from preservation of an existing scientific test. For the latter, preserve the original absorber rates and relevant profile/step choices explicitly, or retain a deliberately short test below the driver where appropriate. Record any intentional numerical change and qualify it. Merely replacing the planes by `n_save` extends the run; it does not preserve the original short window. 4. **R4 — Medium: define counts for a directly constructed interior launch (§§5.1–5.2, 7; Q6).** The proposal requires planes after the launch, but defines `n_save` over `[0, length]`, including zero. Q6 explains filtering for `with_input`, not construction with `initial_z > 0`. On a 1 mm grid with `initial_z=0.4 mm`, a five-plane lattice from zero contains `0.25 mm`; passing that lattice to today's constructor raises the documented initial-position error. Filtering it gives four saved planes including the actual entrance; redistributing five planes over the remaining interval gives five at different positions. Applying the default count also needs a decision. **Question and recommendation:** does the count describe the whole zero-based lattice or the actual launched run? To retain the stated zero-based rule, recommend resolving the lattice and retaining only positions beyond the launch, documenting the resulting count and actual entrance. Keep an explicit position at or before the launch a named refusal. Test both direct construction and `with_input`, with an on-lattice and an off-lattice launch. Also state whether today's refusal of fixed schedules for interior launches remains: Q3's start-equals-launch condition must not imply new support. 5. **R5 — Medium: cover settings replacement and reuse in the adoption contract (§§5–7).** Section 6 names the constructor and keyword builders, then says already resolved settings pass through unchanged. The public `Simulation.settings` setter also accepts replacement settings before translation, and settings can be reused with another grid. A resolver only called by the constructor would leave `n_save` unresolved on replacement; treating a resolved array as exempt from validation could retain the wrong end on another grid. The setter also compares settings to protect a translated request and to decide whether its attached recipe is still valid. **Recommendation:** define adoption to include the setter and validate the resolved positions against the receiving run every time. Resolve before comparing settings, so an equivalent count and explicit array remain equivalent after translation. Document how to replace a resolved selection with a count without accidentally supplying both, and test replacement, repeated adoption, reuse at a different length and the existing prohibition on changing a translated run's schedule. 6. **R6 — Medium: distinguish the declared end from the last committed plane when refusing legacy resume (§§7–9; Q6).** An interrupted valid file normally has its last committed plane before `grid.length`. Q6's "file ... whose last plane is not its `grid.length`" must mean the last *requested* position in `configuration["save_planes"]`, not the last row of `z` or a terminal checkpoint. `driver/resume.py` already distinguishes those states. In addition, `recipe.resume_file` rebuilds the recipe before the resume gate, and `output.hdf5.check_cache` checks the hash before opening for append. Appending an endpoint during rebuilding will otherwise produce the generic hash mismatch instead of the migration message promised here. **Recommendation:** specify the stored metadata used for this decision and where each resume entry point makes it. Preserve interrupted and checkpointed files whose declared end already equals the length. Test legacy ends both below and above the length, ordinary interrupted files, completed files and recipe-driven resume. Describe `with_input` recovery as a new run into a new output, with its launch and restart limitations, rather than an in-place continuation of the old file. 7. **R7 — Medium: separate authored recipes from resolved provenance (§§5.4, 6–9).** "Recipes and the Python export write ... as given" is suitable for authored text. The resolved recipe has a different promise: it rebuilds the same run, independently of omitted defaults. Today `recipe/provenance.py:resolved_document` writes resolved keyword-route planes and removes top-level `n_save`; it does not resolve nested `[build.settings]` fields. Once both object-route selectors can be omitted, leaving that table untouched leaves its plane choice dependent on a future default. Writing both a count and positions would instead fail exclusivity. **Recommendation:** explicitly retain authored syntax and export behavior, while the resolved record writes only the canonical positions, including the end, at the correct level for every route. Add round trips through `Recipe.from_output(..., resolved=True)` and `resume_file`, for a count, explicit positions and both selectors omitted; include the TDSE default if Q4 A is adopted. Require the rebuilt configuration hash to remain the same when the ambient default count changes. 8. **R8 — Medium: define how the GUI preserves existing explicit positions (§§5.4, 8, 11; Q7.6).** Changing an object sheet's field to `settings.n_save` does not by itself migrate a loaded recipe that still holds `settings.save_planes`. Writing the count without removing the list supplies both; replacing an arbitrary list by its count silently redistributes its observations. A length edit also needs a stated behavior for an explicit list after the automatic rewriting is removed. Q7.6's count description is ambiguous: the probe `even_planes(80, 0.25)` gives 81 total planes today, whereas entering `n_save=80` gives 80. Preserving that old list means displaying 81 as the total, not reusing its old displayed value of 80. **Recommendation:** describe loading and editing both forms, preserving explicit positions until the user chooses a count, and removing the other selector in the same edit. Test nonuniform and uniform legacy lists, count/list switches, length changes, save/reload and undo. State the two count cases separately in the migration text. 9. **R9 — Medium: do not promise exact identity when converting existing lists to counts (§§7–9).** The structural parity test is valid when explicit positions are the resolver's exact array. It does not prove that independently written decimal lists have that array. Comparing the filament recipe's 80 centimetre positions, read with its actual quantity decoder, with `np.linspace(0.0, 0.25, 81)[1:]` changed 30 coordinates; the maximum difference was `2.7755575615628914e-17` m. Those are small numerical differences, but the positions enter `configuration_hash`, so converting the example can invalidate resume identity even though its endpoint is unchanged. **Recommendation:** retain existing lists where identity is promised, or explicitly qualify an example conversion as a migration and test its new numerical result separately. Do not round all positions to force matching hashes. Regenerate any edited gallery as required by the repository's documentation policy, and distinguish unchanged numerical results from unchanged requests and hashes. 10. **R10 — Medium: specify endpoint equality before implementing automatic appending (§§5–7; Q1–Q2).** The proposal requires the final plane to equal the length but does not say how independently calculated positions are compared. For example, `0.1 + 0.2` is one representable value above `0.3`, and `np.nextafter(0.3, 0.0)` is one below it. A strict upper-bound check rejects the first; unconditional appending leaves two almost coincident observations for the second. The marches already use a landing tolerance, so this affects whether two requested planes mean distinct observations, their indices and the recorded hash. **Question and recommendation:** choose and document strict comparison or a bounded endpoint normalization, including whether near-end duplicates are refused or retained. If normalization is chosen, account for its identity impact rather than claiming every existing request is unchanged. Add tests immediately below, equal to and above the endpoint, and ensure that applying the resolver twice cannot append another plane. Complete the refusal table with non-finite positions, empty inputs and non-integral or boolean counts, so the shared rule has named errors in both Python and recipes. ### Maintainer decisions following AI review — 2026-11-15 John Travers adopted the decisions below in discussion with the AI reviewer. They are recorded here for the drafting agent to reconcile into Part I; the reviewer has not edited the proposal. The design choices raised in this review discussion are settled below. The drafting agent must still revise the proposal and respond to the review; these decisions do not constitute acceptance of the SEP. **Compatibility constraint.** Backwards compatibility is explicitly not a requirement. Preserving pre-change configuration hashes, converting old recipes or supporting old output files must not constrain the design. Newly created runs must still reproduce their recorded configuration, and numerical correctness and rounding bounds remain requirements. In particular, R9's preservation of old hashes is no longer an acceptance condition; R3's warning that changing the grid length changes absorber rates remains relevant when correcting scientific tests. 1. **D1 — Always record the actual entrance and the end as observation planes (Q1, Q2, Q5; R6, R8, R10).** The entrance is `initial_z`, and the end is the resolved `length`. Both are automatic; append the end when an explicit position list omits it. Refuse requested positions outside the propagation interval, applying the rounding policy in D5. An observation does not require a stored field. Every observation, including both endpoints, obeys the existing `fields` and `field_planes` policy: `fields="none"` keeps statistics and step history without storing plane fields, `fields="planes"` keeps fields only at the selected observation indices, and `fields="all"` keeps them at every observation. The mandatory endpoints never override field retention. Terminal checkpoints are separate and retain their existing restart policy. 2. **D2 — Specify the length once; permit an explicit consistency check (R1; §§5–6).** Make `length` optional and keyword-only on the keyword routes, with the same resolution rule in recipes: | Supplied | Resolution | |---|---| | `length`, without `grid` | Build the grid with that length. | | `grid`, without `length` | Take the run's end from `grid.length`. | | Both | Require agreement and refuse a mismatch, naming both values. | | Neither | Refuse, explaining that a length or a grid is required. | All length-dependent setup uses that one resolved value. Do not silently alter a supplied grid or choose between conflicting lengths. The numerical allowance for agreement is the endpoint rounding policy in D5. 3. **D3 — Count the observations over the actual launched interval (R4; §§5.1–5.2; Q6).** A fresh `n_save=N` request, with `N >= 2`, places exactly `N` evenly spaced observations over `[initial_z, length]`, including both endpoints. The entrance is observation index 0. `length` remains the absolute end coordinate; the distance propagated is `length - initial_z`. This supersedes the draft's zero-based count and R4's recommendation to filter a newly requested count's zero-based lattice. An existing simulation advanced with `with_input(..., initial_z=z)` instead retains its already resolved future observations, with the new entrance recorded at `z`; it has not requested a new count or a redistribution of the existing positions. 4. **D4 — A replay schedule covers the run's interval (Q3; R2).** On routes that support replay, require the schedule's start and end to agree with the actual entrance and resolved end. Refuse genuinely shorter or longer schedules before execution; neither ignore a longer tail nor modify the steps to fit the interval. Use the existing `replay_tolerance` for the end comparison, allowing the rounding error accumulated by the step sum. The start comparison has no accumulated sum and uses the tight endpoint agreement rule. This decision does not introduce replay support for interior launches where it is currently refused. 5. **D5 — Normalize endpoint rounding, with one canonical end (R1, R10).** Normalize a supplied position within the existing landing tolerance of the end to that exact end: eight representable floating-point increments at the endpoint (`LANDING_ULPS`). Keep one endpoint observation after normalization, and refuse positions genuinely beyond the end. Ordinary interior positions retain their supplied values. Apply the same tight agreement rule when both `length` and `grid` are given; after they agree, `grid.length` is the canonical value used throughout setup. This settles the outstanding rounding policy in D1 and D2. A replay's end retains the separate accumulated-rounding allowance in D4. 6. **D6 — Retain the TDSE observation defaults (Q4–Q5).** When neither `n_save` nor `save_planes` is supplied, a TDSE run requests `n_save=2`, its entrance and end. Its default `step_planes=1` additionally records every accepted natural step. Explicit user settings take precedence. Avoid adding intermediate landing positions solely for output by default, since they can require extra expensive atomic-response work. The count `n_save` describes the evenly spaced requested observations; `step_planes` adds observations, so the total recorded count can be larger. All of these observations obey the field-retention policy in D1. 7. **D7 — Expose counts and explicit positions as distinct GUI modes (R8).** Offer "Evenly spaced" and "Explicit positions" modes. The first edits `n_save`; the second edits `save_planes`. Switching modes replaces the other selector in one undoable edit, so a document never acquires both selectors through a mode switch. A length change redistributes count-based observations automatically. Explicitly requested coordinates remain unchanged: the automatic end follows the new length, and an explicit position beyond a shortened length produces a clear validation error. Do not represent an arbitrary explicit list merely by its count or silently redistribute its observations. 8. **D8 — Accept an empty position list and explicitly listed endpoints (R4, R10).** `save_planes=[]` requests no additional positions, so only the automatic entrance and end are requested. An explicit list may include `initial_z` and `length`; each endpoint appears once, with the endpoint normalization in D5. This supersedes R4's recommendation to refuse an explicit position equal to the launch. Positions before the launch remain outside the interval and are refused. Non-finite values, unsorted positions and repeated interior positions remain errors. Omitting both selectors takes the route's default count; an explicitly empty list instead requests only the endpoints. If enabled, `step_planes` adds its observations as in D6. **Remaining work from the review.** No further maintainer choice is required by the findings above. The drafting agent must reconcile Part I with D1–D8 and the compatibility constraint, and respond to R1–R10 point by point. The following remain implementation and verification requirements: - Apply the same resolution and validation when constructing a simulation, replacing its settings or adopting settings from another simulation (R5). - Preserve authored recipe choices while storing resolved positions and defaults that reproduce a newly created run, including nested object-route settings (R7). No preservation of pre-change hashes is required (R9). - Distinguish a run's declared end from its last committed plane or checkpoint when resuming a newly written interrupted file (R6). No compatibility path for old files is required. - Update scientific tests and examples deliberately, accounting for the effect of a changed grid length on absorber rates and other derived settings (R3), and qualify the new behavior on the reference and native CPU backends. ### Response to review — 2026-11-15 Part I was revised to reconcile D1–D8 and the compatibility constraint, and to answer R1–R10 point by point. The maintainer's review, recorded as the decisions above, is added to **Reviewers**, and **Review status** becomes `Reviewed`. - **R1 (keyword route given a grid):** taken, as D2. §3 records that `_gnlse_grid` and `_capillary_grid` (and the general modal route through it) keep a supplied grid unchecked. §5.1 makes `length` optional and keyword-only, with the four-row resolution table; a disagreement is refused naming both values, under §5.4's rounding rule, and a grid is never rebuilt. Python and recipes share the rule (§5.1, §5.5). Q7 item 6 lists the break, and phase 1 counts the affected calls. - **R2 (replay end):** taken, as D4. §5.7 compares the end with `replay_tolerance` and the start with the tight rule; §3 cites the existing bound and its drift argument. The check is at adoption, so direct `assemble` callers keep their meaning (§5.8). §7 adds drift on both sides for `uniform` and `from_history`, and refusals outside the bound. §10 records the rejected fixed allowance. - **R3 (changing a grid's length is not neutral):** taken. §3 states what depends on the length, §4 says a changed length is a numerical change, and Q7's closing paragraph replaces "a fix never changes a physics setting" with two cases: a deliberately short window keeps its physics (keep the grid, pin `boundary_length` and step or profile choices, or move below the driver), and a mismatched setup is corrected and re-qualified. §7 adds "Changed numbers". - **R4 (counts with an interior launch):** superseded by D3. §5.3 counts `n_save` over `[initial_z, length]`, both endpoints included, with an example in §5.10's listing; the filtering recommendation is not taken (§10). Per D8, an explicit position equal to the launch is accepted and kept once; positions before it are refused (§§5.3–5.5). `with_input` keeps the resolved remaining observations (§5.6). §5.7 and §2 state that replay for interior launches stays refused. §7 tests direct construction on and off a zero-based lattice, and `with_input`. - **R5 (settings replacement and reuse):** taken. §5.6 defines adoption to include the setter, `with_*`, scans and reseeds; validates against the receiving run every time; resolves before comparing; makes resolution idempotent; explains reuse at another length and how to pass a count without supplying both. The refusal to change a translated run's planes stays. §7 tests each. - **R6 (declared end on resume):** taken in part. §5.9 resumes to the declared end, the last requested position in `configuration["save_planes"]`, distinct from the last committed plane and a terminal checkpoint, through both `driver/resume.py` and `recipe.resume_file` (§6). The legacy-file refusal and its message are dropped: under the compatibility constraint no path for pre-SEP files is kept, and they meet the existing hash refusal. `with_input` recovery is therefore not described. - **R7 (authored recipes versus resolved provenance):** taken. §5.9 keeps authored text and export as written, and makes the resolved recipe write only canonical positions at the route's level, nested `[build.settings]` included, with defaults (the TDSE default too) written out. §7 adds the round trips and the default-change hash check. - **R8 (front end):** taken, as D7. §5.10 defines the two modes, the switch as one undoable edit, length changes in each mode and loading. Q7 item 8 separates the two count cases (a legacy object-sheet count of 80 is `n_save = 81`). §7 lists the front-end tests. - **R9 (converted lists are not identical):** taken, within the compatibility constraint. §7 limits structural parity to the resolver's own array and separates unchanged numbers from unchanged hashes; §8 treats a converted example as a migration and requires regenerated galleries. Hash preservation is no longer required, so lists are not kept for identity's sake and nothing is rounded to force a match. - **R10 (endpoint equality):** taken, as D5 and D8. §5.4 normalizes within `LANDING_ULPS` ulps of either endpoint, keeps one endpoint observation and refuses positions genuinely outside, with the `0.1 + 0.2` and `np.nextafter` cases. §5.5 completes the refusal table (non-finite, unsorted, repeated, non-integral and boolean counts); an empty list is accepted as endpoints only (D8). §7 tests below, at, above and just outside the bound, and that resolving twice adds no plane.