Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
20 commits
Select commit Hold shift + click to select a range
43723ab
docs: start implementing SEP 51 [skip ci]
jtravs Nov 15, 2026
bbad74f
Resolve save planes over the run's interval at adoption (SEP 51)
jtravs Nov 16, 2026
8e3d0e1
State a keyword route's length once: length, grid or both (SEP 51)
jtravs Nov 16, 2026
9e3c33c
Give recipes SEP 51's planes: n_save in settings, refusals as RecipeE…
jtravs Nov 16, 2026
1d7f1e8
Fit tests and benchmark windows to runs that end at their length
jtravs Nov 16, 2026
7e2d25f
Test SEP 51's rule and type the now-optional save planes
jtravs Nov 16, 2026
8dae78d
Document SEP 51 phase 1 and report it in Part II
jtravs Nov 16, 2026
44e7a92
docs: word SEP 51's interim deviation without a role name [skip ci]
jtravs Nov 16, 2026
a7431a6
Fit three more tests to SEP 51: refusal messages, a listed entrance, …
jtravs Nov 16, 2026
97d5b31
Test resume to the declared end, replay drift and resolved defaults (…
jtravs Nov 16, 2026
c30700d
Give the sheets SEP 51's two forms of saved planes
jtravs Nov 16, 2026
c16904c
Document the sheets' two forms of saved planes
jtravs Nov 16, 2026
28daf46
Point the recipes page at RecipeError where the API documents it
jtravs Nov 16, 2026
becfc92
Report SEP 51's phase 2 in Part II
jtravs Nov 16, 2026
9774812
docs: SEP 51 is Final
jtravs Nov 16, 2026
9ea7415
List SEP 51's refusal rules and fit the remaining runs to their length
jtravs Nov 16, 2026
e4e35f8
Run three tutorials on grids of the length they propagate
jtravs Nov 16, 2026
690bca2
Drop an interior-launch check that adoption makes unreachable; cover …
jtravs Nov 16, 2026
e0e1a97
Give the scaffold's n_save SEP 51's meaning; poll the heartbeat test
jtravs Nov 16, 2026
13b9f21
Read the corpus case's length from save planes typed as optional
jtravs Nov 16, 2026
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
89 changes: 81 additions & 8 deletions benchmarks/builders.py
Original file line number Diff line number Diff line change
Expand Up @@ -28,6 +28,7 @@
"soliton",
"spatial",
"spatial_grids",
"window",
]

if TYPE_CHECKING:
Expand Down Expand Up @@ -550,6 +551,66 @@ def _fibre_or_capillary(
raise SuiteError(f"unknown builder {builder}")


def window(simulation: Simulation, stop: float, **settings: Any) -> Simulation:
"""Return a case run to `stop`, m, with `settings` replaced.

A run ends at its grid's length (SEP 51), so a shortened run (``ab --length``) is
the case rebuilt on its grid cut at `stop`, with everything the whole length set
carried over unchanged: the absorber's rates, the default steps and the profiles
already in the case's settings and simulation. At the case's own length the
settings are replaced on the case itself.

Parameters
----------
simulation : solprop.driver.Simulation
The whole case, untranslated.
stop : float
Where the run ends, m, at most the case's length.
**settings : Any
Fields of :class:`~solprop.driver.SimulationSettings` to replace.

Returns
-------
solprop.driver.Simulation
The case, untranslated.

Raises
------
SuiteError
When a shortened case was already translated, as a coupled launch is.
"""
from solprop.driver import Simulation # noqa: PLC0415

if stop >= simulation.grid.length:
simulation.settings = dataclasses.replace(simulation.settings, **settings)
return simulation
if simulation._problem is not None:
msg = "this case is translated at construction and runs only its whole length"
raise SuiteError(msg)
whole = simulation._base_grid
return Simulation(
dataclasses.replace(whole, length=stop),
simulation.modes,
simulation.responses,
simulation.initial,
settings=dataclasses.replace(
simulation.settings, **({"save_planes": []} | settings)
),
noise=simulation.noise,
noise_resolution=simulation.noise_resolution,
profiles=simulation.profiles,
configuration=simulation.configuration,
spatial_grid=simulation.spatial_grid,
medium=simulation.medium,
frame=simulation.frame,
general=simulation.general,
guide=simulation.guide,
wall=simulation.wall,
taper_coupling=simulation.taper_coupling,
materials=simulation.materials,
)


def build(configuration: Record) -> Simulation:
"""Build a case for the configured backend, stepper and observations.

Expand Down Expand Up @@ -580,7 +641,6 @@ def build(configuration: Record) -> Simulation:
options = variant(configuration)
if case.builder in ("kerr", "spatial"):
settings = SimulationSettings(
save_planes=itinerary,
dz_max=case.length,
dz_init=case.length * 1e-4,
auto_init=True,
Expand All @@ -590,18 +650,29 @@ def build(configuration: Record) -> Simulation:
field_planes=observed["field_planes"],
node_budget=_node_budget(),
)
replay: dict[str, Any] = {}
if case.step is not None:
settings = dataclasses.replace(
settings,
integrator=LowStorageRungeKutta(scheme="rk4ip"),
schedule=FixedSchedule(
np.diff(np.linspace(0.0, stop, max(1, round(stop / case.step)) + 1))
np.diff(
np.linspace(
0.0, case.length, max(1, round(case.length / case.step)) + 1
)
)
),
propagator_mode="tabulate",
)
if case.builder == "kerr":
return kerr(case.name, settings, options["fft_size"])
return spatial(case.name, settings, options)
replay["schedule"] = FixedSchedule(
np.diff(np.linspace(0.0, stop, max(1, round(stop / case.step)) + 1))
)
whole = (
kerr(case.name, settings, options["fft_size"])
if case.builder == "kerr"
else spatial(case.name, settings, options)
)
return window(whole, stop, save_planes=itinerary, **replay)
if case.builder == "exercise":
from benchmarks.exercises import exercise # noqa: PLC0415

Expand All @@ -615,7 +686,10 @@ def build(configuration: Record) -> Simulation:
simulation = advanced(case.name, case.length, options)
if case.name == "grin_nonlinear":
# Translated at construction (its launch is coupled): only the backend
# and the field retention may still change.
# and the field retention may still change, so it runs whole.
if stop < case.length:
msg = "grin_nonlinear couples its launch at construction; run it whole"
raise SuiteError(msg)
simulation.settings = dataclasses.replace(
simulation.settings,
backend=configuration["backend"],
Expand All @@ -628,5 +702,4 @@ def build(configuration: Record) -> Simulation:
if chosen is not None:
observed["integrator"] = chosen
observed["node_budget"] = _node_budget() # None: the translation's default
simulation.settings = dataclasses.replace(simulation.settings, **observed)
return simulation
return window(simulation, stop, **observed)
6 changes: 6 additions & 0 deletions benchmarks/guides.py
Original file line number Diff line number Diff line change
Expand Up @@ -11,6 +11,7 @@

from __future__ import annotations

import dataclasses
from collections.abc import Mapping
from dataclasses import dataclass
from types import MappingProxyType
Expand All @@ -26,6 +27,7 @@
from solprop.constants import C
from solprop.coupling import CouplingModel
from solprop.driver import Simulation
from solprop.driver.settings import default_collar
from solprop.grid import FieldGrid
from solprop.modes import (
CoherentWall,
Expand Down Expand Up @@ -308,11 +310,15 @@ def grin(
q = float(grid.omega[centre]) / C * radius * 1.45
beta = np.sqrt(q * q - 2 * q * np.sqrt(2 * contrast) * np.array([1, 3])) / radius
length = float(2 * np.pi / (beta[0] - beta[1]))
# A run ends at its grid's length (SEP 51): the millimetre grid the guide was
# sampled for is cut at the beat length, and keeps the collar the millimetre gave.
whole, grid = grid, dataclasses.replace(grid, length=length)
simulation = Simulation.from_waveguide(
(),
length,
provider=guide,
grid=grid,
absorber=default_collar(whole),
wavelength=wavelength,
fwhm=40e-15,
energy=1e-15,
Expand Down
11 changes: 7 additions & 4 deletions benchmarks/sessions.py
Original file line number Diff line number Diff line change
Expand Up @@ -34,7 +34,7 @@

import numpy as np

from benchmarks.builders import SOLITON_PEAK, SOLITON_WIDTH, soliton
from benchmarks.builders import SOLITON_PEAK, SOLITON_WIDTH, soliton, window
from benchmarks.records import Record, SuiteError
from benchmarks.registry import CASES
from solprop.driver import Simulation
Expand Down Expand Up @@ -100,13 +100,16 @@ def fibre(
extra["integrator"] = Multistep() if name.endswith("adams") else RungeKutta()
if case.snapshots is not None:
extra["step_planes"] = 1
replay: dict[str, Any] = {}
if case.step is not None:
extra["schedule"] = FixedSchedule.uniform(
replay["schedule"] = FixedSchedule.uniform(
0.0, stop, case.step, save_planes=itinerary
)
# The in-stage collar is stable only up to 0.42 mm steps on this window.
extra["absorber_scheme"] = "split_step"
return soliton(case.length, options, save_planes=itinerary, **extra)
# The case over its length, then run to `stop` on its grid cut there (SEP 51).
whole = soliton(case.length, options, **extra)
return window(whole, stop, save_planes=itinerary, **replay)


class _Steps(NullReporter):
Expand Down Expand Up @@ -238,7 +241,7 @@ def repetition(
record = {
"accepted": sum(run.accepted for run in watch.runs),
"rejected": sum(run.rejected for run in watch.runs),
"z": float(simulation.settings.save_planes[-1]),
"z": float(np.asarray(simulation.settings.save_planes)[-1]),
"runs": len(SCALES),
"finite": None if None in finite else all(finite),
}
Expand Down
3 changes: 3 additions & 0 deletions changelog.d/533-save-planes-count.fixed.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,3 @@
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).
4 changes: 4 additions & 0 deletions changelog.d/856-scaffold-n-save.changed.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,4 @@
`solprop.driver.scaffold.propagate_fixed_rk4`'s `n_save` now means what it means on every
`Simulation` route: the number of evenly spaced saved planes over `[0, z_end]`, both ends
included, at least 2 (default 2). `n_steps` must be a multiple of `n_save - 1`. A call
that passed `n_save=4` now passes `n_save=5` for the same planes (#856).
26 changes: 26 additions & 0 deletions changelog.d/sep-0051-save-planes.changed.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,26 @@
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.
`length` is optional on the keyword routes; given beside `grid=`, the two must agree, and
a call with neither is refused (`prop_capillary` and `from_capillary` therefore refuse a
missing `gas` themselves). `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`.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Original file line number Diff line number Diff line change
Expand Up @@ -54,6 +54,22 @@
"name": "CouplingModel"
}
],
"DEFAULT_BOUNDARY_N": [
{
"is_class": false,
"is_explicit": false,
"module": "builtins",
"module_short": "builtins",
"name": "int"
},
{
"is_class": false,
"is_explicit": false,
"module": "solprop.boundaries",
"module_short": "solprop.boundaries",
"name": "DEFAULT_BOUNDARY_N"
}
],
"EPS0": [
{
"is_class": false,
Expand Down Expand Up @@ -665,6 +681,22 @@
"name": "Simulation"
}
],
"absorber": [
{
"is_class": false,
"is_explicit": false,
"module": "builtins",
"module_short": "builtins",
"name": "function"
},
{
"is_class": false,
"is_explicit": false,
"module": "solprop.boundaries",
"module_short": "solprop.boundaries",
"name": "absorber"
}
],
"admittance": [
{
"is_class": false,
Expand Down Expand Up @@ -841,6 +873,22 @@
"name": "Displayed.with_input"
}
],
"capillary_grid": [
{
"is_class": false,
"is_explicit": false,
"module": "solprop.grid",
"module_short": "solprop.grid",
"name": "EnvelopeGrid"
},
{
"is_class": false,
"is_explicit": false,
"module": "solprop",
"module_short": "solprop",
"name": "EnvelopeGrid"
}
],
"carrier": [
{
"is_class": false,
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -15,7 +15,7 @@
},
"outputs": [],
"source": [
"import math\nimport time\n\nimport matplotlib.pyplot as plt\nimport numpy as np\nfrom scipy.special import j0, jn_zeros\n\nfrom solprop import fourier\nfrom solprop.constants import EPS0, C\nfrom solprop.coupling import CouplingModel, couple\nfrom solprop.driver import Simulation, SimulationSettings\nfrom solprop.grid import EnvelopeGrid, RadialGrid\nfrom solprop.modes.capillary import MarcatiliMode\nfrom solprop.nonlinear.optmat_rates import OptmatRate\nfrom solprop.nonlinear.responses import KerrResponse\nfrom solprop.physdata import chi3, gamma3, refractive_index\nfrom solprop.physdata.species import species\nfrom solprop.processing import field_plane, get_spectral_density\nfrom solprop.pulses import GaussianPulse, SpatialPulse\nfrom solprop.spatial import SpatialMedium, critical_power\nfrom solprop.stats import StatsSpec\nfrom solprop.stepper import PIController\n\nstarted = time.perf_counter()"
"import math\nimport time\n\nimport matplotlib.pyplot as plt\nimport numpy as np\nfrom scipy.special import j0, jn_zeros\n\nfrom solprop import fourier\nfrom solprop.boundaries import DEFAULT_BOUNDARY_N, absorber\nfrom solprop.constants import EPS0, C\nfrom solprop.coupling import CouplingModel, couple\nfrom solprop.driver import Simulation, SimulationSettings\nfrom solprop.grid import EnvelopeGrid, RadialGrid\nfrom solprop.modes.capillary import MarcatiliMode\nfrom solprop.nonlinear.optmat_rates import OptmatRate\nfrom solprop.nonlinear.responses import KerrResponse\nfrom solprop.physdata import chi3, gamma3, refractive_index\nfrom solprop.physdata.species import species\nfrom solprop.processing import field_plane, get_spectral_density\nfrom solprop.pulses import GaussianPulse, SpatialPulse\nfrom solprop.spatial import SpatialMedium, critical_power\nfrom solprop.stats import StatsSpec\nfrom solprop.stepper import PIController\n\nstarted = time.perf_counter()"
]
},
{
Expand Down Expand Up @@ -123,7 +123,7 @@
},
"outputs": [],
"source": [
"capillary = Simulation.from_capillary(\n RADIUS,\n LENGTH,\n \"Ar\",\n PRESSURE,\n wavelength=WAVELENGTH,\n grid=grid,\n envelope=True,\n fwhm=FWHM,\n energy=energy,\n modes=8,\n kerr=True,\n thg=False,\n plasma=False,\n raman=False,\n noise=None,\n n_save=21,\n)\nport = capillary.input_port()\nmodel = CouplingModel(\"scalar_paraxial\", model_error=0.05)\ncoupled = {name: couple(plane, port, model=model) for name, plane in planes.items()}\nshares = {\n name: np.sum(weights * np.abs(result.launch.samples[:, 0, :]) ** 2, axis=1)\n / result.report.incident_energy\n for name, result in coupled.items()\n}\nprint(coupled[\"Kerr\"].report)\nfor name, result in coupled.items():\n report = result.report\n print(\n f\"{name:>6}: s11 = {shares[name][0]:.5f}, s12 = {shares[name][1]:.5f}, \"\n f\"s13 = {shares[name][2]:.2e}; launched {report.efficiency:.5f} \"\n f\"of {report.incident_energy * 1e6:.3f} uJ; budget {report.budget:.3f}\"\n )\ndelta = shares[\"Kerr\"] - shares[\"linear\"]\nprint(f\"change: ds11 = {delta[0]:+.3e}, ds12 = {delta[1]:+.3e}, ds13 = {delta[2]:+.2e}\")"
"# The capillary's grid samples as the gap's does -- a launch is bound to its\n# lattice -- and is built for the capillary's own 5 mm, since a run ends at its\n# grid's length; its collar keeps the rate the gap's 20 mm grid gives.\ncapillary_grid = EnvelopeGrid.from_limits(\n LENGTH, WAVELENGTH, (500e-9, 1.4e-6), 300e-15, thg=False\n)\ncapillary = Simulation.from_capillary(\n RADIUS,\n LENGTH,\n \"Ar\",\n PRESSURE,\n wavelength=WAVELENGTH,\n grid=capillary_grid,\n absorber=absorber(capillary_grid, boundary_length=GAP / DEFAULT_BOUNDARY_N),\n envelope=True,\n fwhm=FWHM,\n energy=energy,\n modes=8,\n kerr=True,\n thg=False,\n plasma=False,\n raman=False,\n noise=None,\n n_save=21,\n)\nport = capillary.input_port()\nmodel = CouplingModel(\"scalar_paraxial\", model_error=0.05)\ncoupled = {name: couple(plane, port, model=model) for name, plane in planes.items()}\nshares = {\n name: np.sum(weights * np.abs(result.launch.samples[:, 0, :]) ** 2, axis=1)\n / result.report.incident_energy\n for name, result in coupled.items()\n}\nprint(coupled[\"Kerr\"].report)\nfor name, result in coupled.items():\n report = result.report\n print(\n f\"{name:>6}: s11 = {shares[name][0]:.5f}, s12 = {shares[name][1]:.5f}, \"\n f\"s13 = {shares[name][2]:.2e}; launched {report.efficiency:.5f} \"\n f\"of {report.incident_energy * 1e6:.3f} uJ; budget {report.budget:.3f}\"\n )\ndelta = shares[\"Kerr\"] - shares[\"linear\"]\nprint(f\"change: ds11 = {delta[0]:+.3e}, ds12 = {delta[1]:+.3e}, ds13 = {delta[2]:+.2e}\")"
]
},
{
Expand Down Expand Up @@ -247,7 +247,7 @@
"name": "python",
"nbconvert_exporter": "python",
"pygments_lexer": "ipython3",
"version": "3.14.5"
"version": "3.14.7"
}
},
"nbformat": 4,
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -41,6 +41,7 @@
from scipy.special import j0, jn_zeros

from solprop import fourier
from solprop.boundaries import DEFAULT_BOUNDARY_N, absorber
from solprop.constants import EPS0, C
from solprop.coupling import CouplingModel, couple
from solprop.driver import Simulation, SimulationSettings
Expand Down Expand Up @@ -276,13 +277,20 @@
# mode *m*, in its native true-power metric, over the incident energy of the
# whole entrance plane in the coupling's common measure.

# The capillary's grid samples as the gap's does -- a launch is bound to its
# lattice -- and is built for the capillary's own 5 mm, since a run ends at its
# grid's length; its collar keeps the rate the gap's 20 mm grid gives.
capillary_grid = EnvelopeGrid.from_limits(
LENGTH, WAVELENGTH, (500e-9, 1.4e-6), 300e-15, thg=False
)
capillary = Simulation.from_capillary(
RADIUS,
LENGTH,
"Ar",
PRESSURE,
wavelength=WAVELENGTH,
grid=grid,
grid=capillary_grid,
absorber=absorber(capillary_grid, boundary_length=GAP / DEFAULT_BOUNDARY_N),
envelope=True,
fwhm=FWHM,
energy=energy,
Expand Down
Original file line number Diff line number Diff line change
@@ -1 +1 @@
9e4fe96e839f0bc0b4f86df05a6d4597
af0e3d832e983700d7024ab3a450eb75
Loading
Loading