Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -187,7 +187,7 @@ to it; a function that departs from it says so in the first line of its docstrin
| Linear operator (internal) | `D = −i(β − β₀ − β₁(ω − ω₀)) − α/2`, `Im n_eff > 0` is loss |
| Amplitudes | interface modal amplitude `b = sqrt(Re n_eff) a` in true √W; the internal `a` is vacuum-normalised (`conventions.md §4`) |
| Kernel state layout | `(n_modes, n_pol, n_omega)` complex128, ω contiguous, one trajectory (a group is a sequence of problems); saved fields `(n_z, n_modes, n_pol, n_omega)` |
| Axis names | `n_batch n_modes n_pol n_omega n_omega_fine n_t n_to n_nodes n_z n_intervals n_deg n_windows`, reused verbatim in annotations |
| Axis names | `n_modes n_pol n_omega n_omega_fine n_t n_to n_nodes n_z n_intervals n_deg n_windows`, reused verbatim in annotations |

## Backends, kernels and hot paths

Expand Down
1 change: 1 addition & 0 deletions changelog.d/sep-0052-run-records.changed.md
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
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`.
7 changes: 7 additions & 0 deletions changelog.d/sep-0052-snapshot-layout.breaking.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,7 @@
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 snapshot written in
the earlier layout is refused by name rather than squeezed, and 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.
9 changes: 9 additions & 0 deletions changelog.d/sep-0052-unit-axis.changed.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,9 @@
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.
3 changes: 3 additions & 0 deletions docs/conf.py
Original file line number Diff line number Diff line change
Expand Up @@ -166,6 +166,9 @@
("py:class", "solprop.transverse_monitor._EdgeTables"),
("py:class", "solprop.transverse_monitor._HostEdgeReduction"),
("py:class", "Helpers"),
# The transverse edge's verdict literal, named in a signature as the run records
# import it for type checking only (solprop.backends.records).
("py:class", "TransverseStatus"),
]
# Array annotations are written with jaxtyping on numpy arrays (ADR-018). Neither
# jaxtyping nor numpy's private typing aliases publish an inventory Sphinx can resolve,
Expand Down
4 changes: 2 additions & 2 deletions docs/dev/architecture.md
Original file line number Diff line number Diff line change
Expand Up @@ -218,7 +218,7 @@ against `src/solprop` by `tests/test_structure_figures.py`.
| `modes/` | Mode protocols and derived quantities; capillary, antiresonant, tabulated, step-index, rectangular and planar (slab, uniform in y, per unit width) modes, with `PlanarGrid` for the planar guide resolved in y; shared gas fill, quadrature and collections; full-vector modal records, material laws and regions, bound step-index and radial graded-index providers, and the guide that pairs a provider with a mode collection, and the connection of a basis that moves along z | P |
| `linear.py`, `boundaries.py`, `nonlinear/` | Linear assembly, absorbing rates, 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, sessions, the Adams call ledger both backends keep (`ledger.py`), node chunks, scalar bodies, spatial and population statistics, and the TDSE response's host source assembly (`tdse_source.py`) | B |
| `backends/` | Registry and protocols, sessions, the run records both backends read (`records.py`, SEP 52) and the engine protocols the marches call (`engines.py`), the Adams call ledger both backends keep (`ledger.py`), node chunks, scalar bodies, spatial and population statistics, and the TDSE response's host source assembly (`tdse_source.py`) | B |
| `backends/numpy_ref/` | Reference execution, its Adams kernels and tables (`multistep.py`) and its on-axis scan (`populations.py`) | B |
| `backends/host/` | The reference's own step driver, Adams and low-storage marches and run session ([SEP 47](seps/archive/sep-0047-run-ownership.md) phase 2); the parts the Python sessions compose are in `backends/session_core.py` | B |
| `stepper/`, `log.py`, `stats.py` | Tableaux, controllers, schedules, progress reporters and statistics specifications | D |
Expand Down Expand Up @@ -495,7 +495,7 @@ checks. What it computes, once per problem:

| product | from | representation |
|---|---|---|
| Φ table | `linear.py` + `ZProfile`s | piecewise Chebyshev in z, coefficients `(n_intervals, n_deg, 1, n_modes, n_pol, n_omega)` as in `kernel-contract.md` §3, breakpoints, hard kinks; constant-D fast path (degree 1: one interval, or one per stretch between the kinks of a response path) |
| Φ table | `linear.py` + `ZProfile`s | piecewise Chebyshev in z, coefficients `(n_intervals, n_deg, n_modes, n_pol, n_omega)` as in `kernel-contract.md` §3, breakpoints, hard kinks; constant-D fast path (degree 1: one interval, or one per stretch between the kinks of a response path) |
| unitary phase for noise | Im Φ | same table, imaginary part |
| quadrature | `modes/quadrature.py` | nodes, weights, coarse weights, synthesis and projection matrices; taper scaling rule |
| response spec | `nonlinear/responses.py` | compiled ordering of the fused pass, coefficients, ionisation-rate spline tables (log-spaced, converged, clip limits), Raman kernels on the doubled grid in the frequency domain, normalisation prefactors |
Expand Down
4 changes: 2 additions & 2 deletions docs/dev/backends.md
Original file line number Diff line number Diff line change
Expand Up @@ -452,8 +452,8 @@ It consumes the contract only through `linop.delta_phi`, `linop.unitary_phase`,
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; a transform and a state that
would both carry the transverse components; and a batch axis above one.
problem; general z-dependent response data; 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
6.4e-16 for a z-varying one and independent of the step count; P1 order 5.10 and 5.82 over
Expand Down
6 changes: 3 additions & 3 deletions docs/dev/conventions.md
Original file line number Diff line number Diff line change
Expand Up @@ -335,8 +335,9 @@ Cartesian one).
## 6. Array layout and axis names

Kernel state and canonical storage: `(n_modes, n_pol, n_omega)` complex128, ω
contiguous (C order): one trajectory. A backend may hold its state privately with a leading axis of one (the native build's four-axis
layout), and a march snapshot's file keeps that axis. Every backend computes in binary64
contiguous (C order): one trajectory, with no leading axis of one anywhere: not in a
backend's state, the operator's value tables (§3 of the kernel contract), the memory
ledgers or a march snapshot's stored state (SEP 52). Every backend computes in binary64
(ADR-077). Saved fields: `(n_z, n_modes, n_pol, n_omega)`; a scan stores each point separately.
Space-domain buffers: `(n_nodes_chunk, n_pol, n_to)`. Convenience accessors
may squeeze trivial axes; the seam and the files never do.
Expand All @@ -345,7 +346,6 @@ Standard axis names, reused verbatim in every jaxtyping annotation and docstring

| name | meaning |
|---|---|
| `n_batch` | the leading axis of one of a backend's private state layout, the operator's value tables (§3 of the kernel contract) and a march snapshot's stored state; never part of a single trajectory's seam |
| `n_modes` | modes (1 for mode-averaged) |
| `n_pol` | polarisation components of the kernel state (1 or 2) |
| `n_components` | Cartesian components of a local physical field (1, 2 or 3); a general modal guide carries `n_pol = 1` and `n_components = 3` |
Expand Down
5 changes: 4 additions & 1 deletion docs/dev/decisions.md
Original file line number Diff line number Diff line change
Expand Up @@ -72,7 +72,10 @@ it is qualified, [backends.md](backends.md); for the current seam,

- **Status:** accepted; amended by [SEP 47](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
`(n_modes, n_pol, n_omega)` and a group is a sequence of member problems; and by
[SEP 52](seps/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
- **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.
Expand Down
2 changes: 2 additions & 0 deletions docs/dev/figures/build.py
Original file line number Diff line number Diff line change
Expand Up @@ -722,6 +722,8 @@ class Layer(NamedTuple):
(
"protocol",
"registry",
"records",
"engines",
"spatial",
"populations",
"tdse_source",
Expand Down
Loading
Loading