solprop.driver.settings#

How a run is stepped, what it records and which backend executes it.

SimulationSettings and the checks that admit it, and the settings defaults a keyword route applies: its save planes, its controller and its absorbing boundaries (SEP 21). The manual page is docs/guide/setup/running.md.

Module Attributes

`LOOSE_ADAMS_RTOL`	The `rtol` from which an adaptive Adams run is warned on.
`DEFAULT_N_SAVE`	Planes a GNLSE run stores, counting the one at `z = 0`.
`NoiseSetting`	What a constructor's `noise` keyword takes (SEP 37).
`LOW_STORAGE_BACKENDS`	The backends that execute `LowStorageRungeKutta`.

Functions

`default_collar`(grid)	Return a route's default absorbing boundaries on a grid (SEP 21).
`keyword_settings`(route, length, *, rtol, ...)	Return the settings a keyword route builds: its controller and its steps.

Classes

SimulationSettings([controller, dz_min, ...])

How a run is stepped, what it records and which backend executes it.

solprop.driver.settings.DEFAULT_N_SAVE = 201#: Planes a GNLSE run stores, counting the one at z = 0.

solprop.driver.settings.LOOSE_ADAMS_RTOL = 0.05#

The rtol from which an adaptive Adams run is warned on.

An error of five per cent or more allowed per step compounds through the method’s history, and its predictor-corrector estimate is unreliable there (docs/guide/numerics/choosing-a-stepper.md).

solprop.driver.settings.LOW_STORAGE_BACKENDS = ('native', 'numpy_ref')#

The backends that execute LowStorageRungeKutta.

numpy_ref from SEP 24’s phase 1 and solprop-native from phase 3, on every route the translation admits the march on; backend="auto" resolves as for every other integrator (solprop.backends.registry.resolve_name(): the native backend).

solprop.driver.settings.NoiseSetting = typing.Literal['default', 'input', 'modified'] | None#

What a constructor’s noise keyword takes (SEP 37).

A model, None for a noiseless run, or "default", the keyword’s default, which resolves to "input" wherever the run can carry noise and to none where it cannot, recording which in the run’s NoiseResolution.

class solprop.driver.settings.SimulationSettings(controller=None, *, save_planes, dz_max, dz_init, dz_min=None, stretch=None, auto_init=False, interval_cap=None, interpolate_planes=False, step_planes=0, schedule=None, propagator_mode='auto', density=None, shock=True, prefactor_index=None, absorber=None, absorber_scheme=None, quadrature=None, components=None, ionisation_field_range=None, node_budget=None, stats=None, polarisation_taper=False, backend='auto', integrator=None, resume_history=None, tdse_execution=None, fields='all', field_planes=(), evanescent_rate=None, spatial_absorber=None, adiabatic_accuracy=None, boundary_check=BoundaryCheck(guard_fraction=0.05, budget=0.001, stop_factor=10.0, quiet_collar=False, transverse_budget=None), _default_integrator=None, _route=None, _default_controller=None)[source]#

Bases: Displayed

How a run is stepped, what it records and which backend executes it.

Everything that is not a physics object, in one group, so that a simulation can be constructed from the physics and this. Equality is by identity (eq=False) because save_planes is an array.

Attributes:

controllersolprop.stepper.controller.PIController or None: Tolerances, safety and gains; the tolerances and the norm choice live here and nowhere else (docs/dev/kernel-contract.md section 7). None, the default, takes the route’s from ROUTE_DEFAULTS (SEP 37) when an interface builds the run: the SPATIAL_RTOL and SPATIAL_ATOL of from_free() on a radial grid and of from_planar(), the FREE_RTOL and FREE_ATOL of from_free() on a Cartesian or line grid. An explicit controller always wins, and a default copied into another route takes that route’s default. The other fields are keyword-only.
save_planesnumpy.ndarray: Positions to save at, m, increasing and positive, shape (n_z,). The plane at z = 0 is saved as well and is not listed here. A sequence is adopted as a read-only float64 array, so that two runs specified the same way record the same planes whichever type they passed and therefore hash alike.
dz_maxfloat: Cap on the controller’s proposal, m.
dz_initfloat: First step, m.
dz_minfloat or None: Floor on the proposal, m; None takes solprop.stepper.controller.default_dz_min() of the run length. A proposal below it raises rather than being clamped silently.
stretchfloat or None: Landing stretch factor; None takes solprop.translate.problem.DEFAULT_STRETCH.
auto_initbool: Whether the start-up rule takes the step after the first from the first step’s own error estimate, rather than growing from dz_init at the growth cap (SEP 14). The convenience constructors set it when no dz_init is given. It is off for a coupled flow and a reject-free controller.
interval_capbool or None: Whether a step is capped at the width of its operator-table interval. None caps it only for a coupled flow or a reject-free controller (SEP 14).
interpolate_planesbool: Observe the save planes inside accepted steps instead of landing on them (SEP 14 phase 3): through the Adams march’s own polynomial or, with RungeKutta(), DOPRI5’s continuous extension. Every plane but the run’s end and a hard kink is then interpolated. Refused beside a coupled flow, the per-step temporal collar and the modified noise.
step_planesint: A positive k also saves the end of every k-th accepted step, the march’s own positions, beside the requested planes (SEP 14 phase 3); 0 saves the requested planes only. Not in scans.
integratorMultistep, RungeKutta, LowStorageRungeKutta or None: The method that steps the run (docs/guide/numerics/choosing-a-stepper.md). None, the default, takes Multistep(), or RungeKutta() where the interface’s builder sets it (from_gnlse(), from_waveguide() and from_free(); docs/guide/numerics/choosing-a-stepper.md); the stored value is the resolved method. Multistep() is the low-call exponential Adams method, which numpy_ref and native execute for supported configurations; RungeKutta() is the interaction-picture DOPRI5 march, which every backend executes and which holds a third of the Adams history’s memory. LowStorageRungeKutta() replays schedule with RK4 in three registers and no error estimate (SEP 24); every backend executes it (LOW_STORAGE_BACKENDS), and "auto" resolves as for any integrator.
schedulesolprop.stepper.schedule.FixedSchedule or None: A fixed schedule to replay instead of stepping adaptively (docs/dev/stepper.md section 8). Its edges must contain every save plane, which solprop.stepper.schedule.FixedSchedule.uniform() guarantees.
propagator_mode{‘auto’, ‘tabulate’, ‘recompute’}: Whether the backend tabulates the stage propagators (docs/dev/kernel-contract.md).
densitysolprop.profiles.ZProfile or float or None: Number density along z in m^-3 that multiplies the compiled responses; None takes the mode’s own path. The GNLSE passes 1.0 (docs/guide/waveguides/gnlse.md). Refused beside a mixture and beside a gas medium, which carry their own.
shockbool: Keep the omega dependence of the normalisation prefactor, which is the optical shock term.
prefactor_indexfloat or None: Use this constant in the prefactor and power weight; None uses Re n_eff. The GNLSE passes 1.0, leaving its power normalisation and Phi unchanged.
absorber_scheme{‘nonlinear’, ‘split_step’} or None: How the temporal collar is applied (docs/guide/numerics/boundaries.md). None, the default, is the route’s: "split_step" on the radial, free-space and planar routes unless planes are interpolated (SEP 21), and "nonlinear" elsewhere. "nonlinear" adds -alpha(t) E(t) / 2 inside every stage; "split_step" multiplies the accepted state by exp(-alpha(t) h / 2) once per step, a Lie splitting, first order wherever the collar does any work and unconditionally stable.
absorbersolprop.boundaries.Absorber or None: The collar rates. Its spectral part folds into the linear operator and its temporal part crosses the seam as a rate (docs/guide/numerics/boundaries.md).
quadraturesolprop.modes.quadrature.TransverseQuadrature or None: The fixed transverse rule a multimode run integrates the nonlinear polarisation on (docs/guide/waveguides/mode-sets.md). None builds the mode-averaged single-node transform, which needs exactly one mode.
componentssequence of str or None: Which transverse Cartesian components the multimode transform resolves at each node, a non-empty subset of ("x", "y"); None takes the union of the modes’ nonzero components at the entrance (("x",) for HE_1m modes at phi = 0; docs/dev/conventions.md section 5). Refused without a quadrature.
ionisation_field_rangetuple of float or None: Lowest and highest field amplitude in V/m the compiled ionisation-rate table has to cover. Required beside a plasma response whose rate is not already a table; the table holds its last value above the upper limit, so one set too low is a silent clip.
node_budgetint or None: Bytes of node-chunk buffers a response pass may hold (docs/dev/architecture.md section 13). An execution setting, outside the resume key: the backend plans its node chunk from it when it is prepared, and it may change after translation. None, the default, leaves the choice to the backend, which takes 1 GiB on a free-space, line or planar grid and 64 MiB otherwise (DEFAULT_SPATIAL_NODE_BUDGET, DEFAULT_NODE_BUDGET); an explicit budget is authoritative.
statssolprop.stats.StatsSpec or None: Which statistics to collect at every saved plane; None collects none.
polarisation_taperbool: Whether the spectral collar tapers the nonlinear polarisation as well as absorbing the field through the linear operator. Default False, which is solprop.translate.problem.assemble()’s: the taper costs a systematic error of the size of the field’s content in the collar, and the rate absorber acts either way (docs/guide/numerics/boundaries.md).
backendstr: Registry name of the backend to execute the run. The default "auto" resolves to "native" at settings construction, and refuses if it isn’t installed or this processor is below its baseline. The stored name is concrete, including in scan workers. A backend’s import or construction errors never trigger a fallback.
resume_historybool or None: Whether the output keeps the Adams march’s state at every save plane and terminal checkpoint, so that a resume continues the history – its samples, its order and its proposed step – as the uninterrupted run would, instead of starting it afresh at order one. None, the default, keeps it while it is at most solprop.translate.run_request.MARCH_SNAPSHOT_AUTO_BYTES; it is outside the resume key. Every backend’s fused and exponential Adams engines, the native backend’s resident one included, export and install their history.
fields{‘all’, ‘planes’, ‘none’}: Which saved planes keep their field (SEP 22): every one, the default; those of field_planes; or none, for a run wanted as statistics alone. A plane without its field stores no field and no noise phase, and an in-memory output is allocated for the kept fields only; the march is the same. A terminal checkpoint carries the field anyway, so a stopped run resumes, but a file whose last regular plane kept no field resumes only from one. Outside the resume key, like resume_history: it changes what is kept, not what is computed. In a scan, run_scan()’s own fields decide, and a builder that sets this is refused. Beside LowStorageRungeKutta(), a step abandoned in flight leaves no checkpoint, so a file resumes from the last plane that kept its field.
field_planessequence of int: Saved-plane indices for fields='planes', the entrance as 0 and negative from the end; empty otherwise. Refused beside step_planes, whose plane count is not known in advance.
evanescent_ratefloat or None: The spatial operator’s evanescent field attenuation cap in m^-1, positive and finite (SEP 22 section 4.4). None, the default, keeps solprop.spatial.EVANESCENT_RATE; solprop.spatial.physical_evanescent_rate() gives the rate at which the grid’s non-propagating content decays physically. Refused without a spatial grid; a replayed step it would overflow is refused at translation.
spatial_absorbersolprop.boundaries.SpatialAbsorber, False or None: The transverse boundary of a free-space run (SEP 40). None, the default, is SpatialAbsorber(real_space=False): a wall or a wrap at the grid’s outer size and a safety ramp on its outer wavenumbers, folded into the operator as an exact diagonal rate. A SpatialAbsorber asks for a real-space collar too, in the room the grid has outside its requested size (collar_fraction). False carries no ramp either; the boundary monitor still runs. A specification is refused on modal runs.
adiabatic_accuracysolprop.adiabatic.AdiabaticAccuracy or None: The forward-field and reflected-energy budgets a radial medium varying along z must meet (SEP 34 section 4.5). None, the default, is AdiabaticAccuracy(), both 1e-4; a path exceeding them is refused.
tdse_executionsolprop.nonlinear.tdse.TDSEExecution or None: Explicit atomic runtime resources for a TDSE response. Requires an explicit backend="numpy_ref" and a Multistep integrator. Execution resources are outside the scientific resume identity; attempted-call budgets are cumulative.
boundary_checksolprop.monitor.BoundaryCheck or None: How the run watches its time window’s edges (SEP 21): guard and collar occupancy at the launch and every committed step, a warning and then a stop when light reaches the edge, and the energy the temporal collar removed at the end. The default BoundaryCheck warns at a field-error budget of 1e-3 and stops at ten times it; None watches nothing.

Raises:

DriverError: If the save planes are empty, not increasing, or not positive. The same check runs again in solprop.translate.problem.assemble(); here it fires before a run has built anything. Also if the field retention is not valid, asks for fields='planes' beside step_planes.

Examples

>>> from solprop.driver import SimulationSettings
>>> from solprop.stepper import PIController
>>> settings = SimulationSettings(
...     controller=PIController(rtol=1e-8, atol=1e-14),
...     save_planes=[0.5, 1.0], dz_max=0.1, dz_init=1e-3,
...     backend="numpy_ref",
... )
>>> settings.save_planes.tolist(), settings.backend
([0.5, 1.0], 'numpy_ref')

absorber: Absorber | None = None#

absorber_scheme: Literal['split_step', 'nonlinear'] | None = None#

property absorber_scheme_named: bool[source]#

Whether the caller named the collar scheme, rather than taking the route’s.

False when absorber_scheme is the route’s default.

adiabatic_accuracy: AdiabaticAccuracy | None = None#

auto_init: bool = False#

backend: str = 'auto'#

boundary_check: BoundaryCheck | None = BoundaryCheck(guard_fraction=0.05, budget=0.001, stop_factor=10.0, quiet_collar=False, transverse_budget=None)#

components: Sequence[str] | None = None#

controller: PIController | None = None#

controller_defaulted = False#

defaults_resolution()[source]#

Return which stepping choices took the route’s default (#87, SEP 41).

Returns:

solprop.output.records.DefaultsResolution: The route, and which of the integrator, the relative tolerance and the collar scheme came from its row of the defaults table.

Examples

>>> from solprop.driver import SimulationSettings
>>> settings = SimulationSettings(
...     save_planes=[1.0], dz_max=0.1, dz_init=0.01, backend="numpy_ref"
... )
>>> settings.defaults_resolution()
DefaultsResolution(route=None, defaulted=('integrator', 'absorber_scheme'))

density: ZProfile | float | None = None#

dz_init: float#

dz_max: float#

dz_min: float | None = None#

evanescent_rate: float | None = None#

execution_options()[source]#

Return the execution options a backend is prepared with (SEP 47).

The node budget is an execution choice, not part of the scientific problem: the translation records none, and the backend plans its node chunk from it when it is prepared (solprop.backends.node_chunk.plan_node_chunk()).

Returns:

solprop.backends.session.ExecutionOptions: The explicit node_budget, or the backend’s automatic choice.

Examples

>>> from solprop.driver import SimulationSettings
>>> settings = SimulationSettings(
...     save_planes=[1.0], dz_max=0.1, dz_init=0.01, node_budget=2**26
... )
>>> settings.execution_options().node_budget
67108864

field_planes: Sequence[int] = ()#

fields: Literal['none', 'planes', 'all'] = 'all'#

integrator: Multistep | RungeKutta | LowStorageRungeKutta | None = None#

integrator_named = False#

interpolate_planes: bool = False#

interval_cap: bool | None = None#

ionisation_field_range: tuple[float, float] | None = None#

node_budget: int | SupportsIndex | None = None#

polarisation_taper: bool = False#

prefactor_index: float | None = None#

propagator_mode: Literal['auto', 'tabulate', 'recompute'] = 'auto'#

quadrature: TransverseQuadrature | None = None#

resume_history: bool | None = None#

save_planes: Float[ndarray, 'n_z'] | Sequence[float]#

schedule: FixedSchedule | None = None#

shock: bool = True#

spatial_absorber: SpatialAbsorber | Literal[False] | None = None#

stats: StatsSpec | None = None#

step_planes: int = 0#

stretch: float | None = None#

tdse_execution: TDSEExecution | None = None#

with_boundaries(grid, *, absorber=None, absorber_scheme=None, boundary_check=BoundaryCheck(guard_fraction=0.05, budget=0.001, stop_factor=10.0, quiet_collar=False, transverse_budget=None), spatial_absorber=None)[source]#

Return these settings with a spatial constructor’s boundary keywords applied.

Each keyword may be given here or in the settings, not both (SEP 21 section 5, SEP 40); its default leaves the settings’ own.

Parameters:

gridsolprop.grid.TimeGrid: The run’s time grid, which sizes a collar switched off.
absorbersolprop.boundaries.Absorber, False or None, optional: The temporal and spectral collar. False zeroes the rates of the settings’ absorber and keeps its lengths, or without one builds the hard band mask alone.
absorber_scheme{‘nonlinear’, ‘split_step’} or None, optional: How the temporal collar is applied.
boundary_checksolprop.monitor.BoundaryCheck or None, optional: How the run watches its time window’s edges; None watches nothing.
spatial_absorbersolprop.boundaries.SpatialAbsorber, False or None, optional: The transverse boundary.

Returns:

SimulationSettings: The settings, replaced where a keyword applies.

Raises:

DriverError: If a keyword is given beside settings that declare their own, or absorber=False beside a scheme.

Examples

>>> from solprop.driver import SimulationSettings
>>> from solprop.grid import EnvelopeGrid
>>> grid = EnvelopeGrid.from_limits(0.01, 835e-9, (500e-9, 2e-6), 1e-12)
>>> settings = SimulationSettings(save_planes=[1.0], dz_max=0.1, dz_init=0.01)
>>> settings.with_boundaries(grid, boundary_check=None).boundary_check is None
True

solprop.driver.settings.default_collar(grid)[source]#

Return a route’s default absorbing boundaries on a grid (SEP 21).

solprop.boundaries.absorber() at its defaults, spectral-only when the grid leaves too little room outside the request for a temporal collar to taper (collar_fraction=0 and no rounding slack).

Parameters:

gridTimeGrid: The run’s grid.

Returns:

Absorber: The default collar.

Examples

>>> from solprop.driver.settings import default_collar
>>> from solprop.grid import FieldGrid
>>> grid = FieldGrid.from_limits(1.5, 800e-9, (90e-9, 4e-6), 400e-15)
>>> default_collar(grid).temporal
True

solprop.driver.settings.keyword_settings(route, length, *, rtol, atol, dz_max, dz_init, **fields)[source]#

Return the settings a keyword route builds: its controller and its steps.

Parameters:

routestr: The row of ROUTE_DEFAULTS the route reads.
lengthfloat: The guide’s length, m, which the default steps are fractions of.
rtolfloat or None: The caller’s relative tolerance, which is never raised silently; None takes the route’s (default_rtol()), and the settings record that the controller is the default.
atolfloat: The absolute tolerance, in the route’s field unit.
dz_max, dz_initfloat or None: The largest and the first step, m; None takes default_step(), and a first step so chosen is refined by the start-up rule.
**fieldsAny: Every other field of SimulationSettings.

Returns:

SimulationSettings: The settings.

Examples

>>> from solprop.driver.settings import keyword_settings
>>> settings = keyword_settings(
...     "gnlse", 0.4, rtol=None, atol=1e-14, dz_max=None, dz_init=None,
...     save_planes=[0.4],
... )
>>> settings.controller.rtol, settings.dz_max, settings.controller_defaulted
(1e-07, 0.2, True)