solprop.driver.defaults#

The route defaults: one table, and the pure functions that resolve a default.

Each interface (prop_gnlse, prop_capillary, prop_waveguide, prop_radial, prop_free and prop_planar, and their Simulation.from_* constructors) steps with its own integrator and tolerances, carries its own noise and applies the temporal collar in its own scheme, each qualified separately (SEP 37, SEP 21). This module holds those choices in one frozen table, ROUTE_DEFAULTS, and resolves them in one place, so that the constructors, the metadata a front end reads (SEP 41) and the tests cannot disagree. The guide’s table of the defaults is docs/guide/numerics/choosing-a-stepper.md.

A default is resolved once, when the settings are built, and the choice is recorded (solprop.output.schema.NoiseResolution for the noise, solprop.output.schema.DefaultsResolution for the rest), so a run that took a default says so in its summary and its record.

Layer D of docs/dev/architecture.md section 3, beside the constructors that read it.

Module Attributes

`DEFAULT_RTOL`	Relative tolerance a GNLSE run asks for unless told otherwise.
`DEFAULT_ATOL`	Absolute tolerance, in the square root of watts, of the same default.
`CAPILLARY_RTOL`	Relative tolerance a capillary run asks for unless told otherwise.
`WAVEGUIDE_RTOL`	Relative tolerance a modal waveguide run asks for unless told otherwise.
`WAVEGUIDE_ATOL`	Absolute tolerance of a capillary or modal waveguide run, in sqrt(W).
`SPATIAL_RTOL`	Relative tolerance of the controller a radial or planar run takes by default.
`SPATIAL_ATOL`	Absolute tolerance of the same default controller: none, as the suite runs it.
`FREE_RTOL`	Relative tolerance of the controller a Cartesian or line run takes by default.
`FREE_ATOL`	Absolute tolerance of the same default controller.
`SINGLE_PRECISION_NOISE`	Why a default resolves to no noise under `precision="single"` (SEP 37).
`PLANAR_NOISE`	Why a planar run carries no noise (SEP 37).
`SLAB_NOISE`	Why a waveguide run of slab modes carries no noise, as the planar grid does not.
`FREE_NOISE`	Why a default resolves to no noise on the free-space interface (SEP 37).
`TDSE_NOISE`	Why a default resolves to no noise beside the TDSE response (SEP 37).
`INTERIOR_LAUNCH_NOISE`	Why a default noise is dropped at an interior launch (SEP 37).
`NoiseModel`	Which shot-noise model a run carries; `None` carries none.
`RouteName`	A row of `ROUTE_DEFAULTS`.
`NoisePolicy`	What a route's `noise="default"` does.
`ROUTE_DEFAULTS`	The defaults of every route, keyed by `RouteName`.

Functions

`default_controller`(route, precision)	Return the step controller a route takes when given no tolerances.
`default_integrator`(route, precision)	Return the integrator a route steps with when none is named.
`default_rtol`(route, precision)	Return a route's default relative tolerance in the run's precision.
`default_scheme`(route, *, interpolate_planes)	Return how a route applies its temporal collar when no scheme is named.
`resolve_noise`(route, noise, seed, precision)	Resolve a constructor's `noise` keyword into the model a run carries (SEP 37).
`route_defaults`(route)	Return a route's row of `ROUTE_DEFAULTS`.
`rtol_in_precision`(rtol, precision)	Return a binary64 default tolerance as the run's precision takes it.

Classes

RouteDefaults(integrator, rtol, atol, noise, ...)

One route's defaults: how it steps, what noise it carries, how its collar acts.

solprop.driver.defaults.CAPILLARY_RTOL = 1e-06#

Relative tolerance a capillary run asks for unless told otherwise.

The default of from_capillary() and prop_capillary() with their default Multistep(). SEP 37’s convergence protocol on the benchmark suite’s rdw case passes it, and a noisy comb-to-continuum check needs it with this integrator (1e-5 fails the coherence budget there). It is a starting point, not a guarantee: a production run should calibrate it (docs/dev/stepper.md section 3).

solprop.driver.defaults.DEFAULT_ATOL = 1e-14#: Absolute tolerance, in the square root of watts, of the same default.

solprop.driver.defaults.DEFAULT_RTOL = 1e-07#

Relative tolerance a GNLSE run asks for unless told otherwise.

Set by SEP 37’s convergence protocol on the supercontinuum of Dudley, Genty and Coen (the benchmark suite’s gnlse_raman_shock): the loosest of three levels a decade apart at which the ensemble-mean spectrum stays within 0.5 dB above -40 dB of its peak and the coherence within 0.02, over paired seeds, with the default RungeKutta(). A noiseless soliton-recurrence study asks for its own, tighter value.

solprop.driver.defaults.FREE_ATOL = 0.0#: Absolute tolerance of the same default controller.

solprop.driver.defaults.FREE_NOISE = 'a Cartesian or line run carries no noise by default: it is slow, and rarely about noise sensitivity'#: Why a default resolves to no noise on the free-space interface (SEP 37).

solprop.driver.defaults.FREE_RTOL = 0.0001#

Relative tolerance of the controller a Cartesian or line run takes by default.

With the default RungeKutta() (SEP 37): the Adams history’s memory rules the multistep method out for a large transverse state. On a self-focusing Kerr beam the spectrum stays within 0.002 dB of a tight reference even at 1e-3; 1e-4 cuts the field error by 2.5 times for a sixth more steps. Applies only where the caller’s SimulationSettings gives no controller.

solprop.driver.defaults.INTERIOR_LAUNCH_NOISE = 'an interior launch takes its spectrum as given, which may already carry a draw'#: Why a default noise is dropped at an interior launch (SEP 37).

solprop.driver.defaults.NoiseModel#

Which shot-noise model a run carries; None carries none.

The two models are described in docs/guide/media/noise.md.

alias of Literal[‘input’, ‘modified’]

solprop.driver.defaults.NoisePolicy#

What a route’s noise="default" does.

"input" draws the one-photon-per-mode seed. "quiet" takes none by default, for the row’s reason, and accepts an explicit model. "unmeasured" takes none and refuses an explicit model, because no photon measure is declared for the representation.

alias of Literal[‘input’, ‘quiet’, ‘unmeasured’]

solprop.driver.defaults.PLANAR_NOISE = 'the hybrid planar grid carries no noise: no photon measure is declared'#: Why a planar run carries no noise (SEP 37).

solprop.driver.defaults.ROUTE_DEFAULTS: Mapping[str, RouteDefaults] = mappingproxy({'gnlse': RouteDefaults(integrator='RungeKutta', rtol=1e-07, atol=1e-14, noise='input', noise_reason=None, absorber_scheme='nonlinear'), 'capillary': RouteDefaults(integrator='Multistep', rtol=1e-06, atol=1e-10, noise='input', noise_reason=None, absorber_scheme='nonlinear'), 'capillary tdse': RouteDefaults(integrator='Multistep', rtol=1e-06, atol=1e-10, noise='quiet', noise_reason='a TDSE run carries no noise by default: it is expensive, rarely repeated as an ensemble, and its checks are coherent', absorber_scheme='nonlinear'), 'waveguide': RouteDefaults(integrator='RungeKutta', rtol=1e-05, atol=1e-10, noise='input', noise_reason=None, absorber_scheme='nonlinear'), 'waveguide slab': RouteDefaults(integrator='RungeKutta', rtol=1e-05, atol=1e-10, noise='unmeasured', noise_reason='a slab mode set carries no noise: no photon measure is declared for its amplitudes per unit width', absorber_scheme='nonlinear'), 'radial': RouteDefaults(integrator='Multistep', rtol=1e-05, atol=0.0, noise='input', noise_reason=None, absorber_scheme='split_step'), 'free': RouteDefaults(integrator='RungeKutta', rtol=0.0001, atol=0.0, noise='quiet', noise_reason='a Cartesian or line run carries no noise by default: it is slow, and rarely about noise sensitivity', absorber_scheme='split_step'), 'planar': RouteDefaults(integrator='Multistep', rtol=1e-05, atol=0.0, noise='unmeasured', noise_reason='the hybrid planar grid carries no noise: no photon measure is declared', absorber_scheme='split_step')})#

The defaults of every route, keyed by RouteName.

The binary64 tolerances and integrators were qualified per route by SEP 37’s convergence protocol and are deliberately not aligned (SEP 41, Q3); the collar schemes are SEP 21’s.

class solprop.driver.defaults.RouteDefaults(integrator, rtol, atol, noise, noise_reason, absorber_scheme)[source]#

Bases: object

One route’s defaults: how it steps, what noise it carries, how its collar acts.

Attributes:

integrator{‘Multistep’, ‘RungeKutta’}: The method a binary64 run steps with when none is named. Single precision always takes RungeKutta() (SEP 33).
rtolfloat: The binary64 relative tolerance; default_rtol() gives it in single precision.
atolfloat: The absolute tolerance, in the route’s field unit.
noise{‘input’, ‘quiet’, ‘unmeasured’}: What noise="default" resolves to (NoisePolicy).
noise_reasonstr or None: Why the default carries no noise; None where it carries the input noise.
absorber_scheme{‘nonlinear’, ‘split_step’}: How the temporal collar is applied when no scheme is named and planes are not interpolated; an interpolated run takes "nonlinear" (SEP 21).

Examples

>>> from solprop.driver.defaults import ROUTE_DEFAULTS
>>> ROUTE_DEFAULTS["capillary"].integrator, ROUTE_DEFAULTS["capillary"].rtol
('Multistep', 1e-06)

absorber_scheme: Literal['split_step', 'nonlinear']#

atol: float#

integrator: Literal['Multistep', 'RungeKutta']#

noise: Literal['input', 'quiet', 'unmeasured']#

noise_reason: str | None#

rtol: float#

solprop.driver.defaults.RouteName#

A row of ROUTE_DEFAULTS.

The six interfaces, with two variants whose noise differs: a capillary beside the TDSE response, and a waveguide of slab modes. The Cartesian and line grids share free.

alias of Literal[‘gnlse’, ‘capillary’, ‘capillary tdse’, ‘waveguide’, ‘waveguide slab’, ‘radial’, ‘free’, ‘planar’]

solprop.driver.defaults.SINGLE_PRECISION_NOISE = 'single precision carries no noise: binary32 rounding swamps a one-photon seed'#: Why a default resolves to no noise under precision="single" (SEP 37).

solprop.driver.defaults.SLAB_NOISE = 'a slab mode set carries no noise: no photon measure is declared for its amplitudes per unit width'#

Why a waveguide run of slab modes carries no noise, as the planar grid does not.

A slab amplitude is in sqrt(W/m), and the one-photon draw is defined per mode in sqrt(W); one photon per metre of width is a convention no derivation has fixed for these modes (the line grid declares its own), so a default resolves to none and an explicit model is refused.

solprop.driver.defaults.SPATIAL_ATOL = 0.0#: Absolute tolerance of the same default controller: none, as the suite runs it.

solprop.driver.defaults.SPATIAL_RTOL = 1e-05#

Relative tolerance of the controller a radial or planar run takes by default.

Set by SEP 37’s convergence protocol on the benchmark suite’s radial_filament_256 and planar cases. It applies only where the caller’s SimulationSettings gives no controller.

solprop.driver.defaults.TDSE_NOISE = 'a TDSE run carries no noise by default: it is expensive, rarely repeated as an ensemble, and its checks are coherent'#: Why a default resolves to no noise beside the TDSE response (SEP 37).

solprop.driver.defaults.WAVEGUIDE_ATOL = 1e-10#

Absolute tolerance of a capillary or modal waveguide run, in sqrt(W).

The companion of CAPILLARY_RTOL and WAVEGUIDE_RTOL. It was never binding in SEP 37’s measurements.

solprop.driver.defaults.WAVEGUIDE_RTOL = 1e-05#

Relative tolerance a modal waveguide run asks for unless told otherwise.

The default of from_waveguide() and prop_waveguide() with their default RungeKutta(), set by SEP 37’s convergence protocol on the benchmark suite’s grin_nonlinear window. A starting point, not a guarantee: a production run should calibrate it.

solprop.driver.defaults.default_controller(route, precision)[source]#

Return the step controller a route takes when given no tolerances.

Parameters:

routestr: A RouteName.
precision{‘double’, ‘single’}: The run’s precision.

Returns:

solprop.stepper.controller.PIController: default_rtol() and the route’s atol, at the controller’s own gains.

Examples

>>> from solprop.driver.defaults import default_controller
>>> controller = default_controller("radial", "double")
>>> controller.rtol, controller.atol
(1e-05, 0.0)

solprop.driver.defaults.default_integrator(route, precision)[source]#

Return the integrator a route steps with when none is named.

Parameters:

routestr or None: A RouteName, or None for settings built by hand, which step with Multistep().
precision{‘double’, ‘single’}: The run’s precision. Single precision refuses the Adams method until its survival is established (SEP 33, Q2), so it always takes RungeKutta().

Returns:

Multistep or RungeKutta: A new instance, at the method’s own defaults.

Examples

>>> from solprop.driver.defaults import default_integrator
>>> type(default_integrator("gnlse", "double")).__name__
'RungeKutta'
>>> type(default_integrator("capillary", "single")).__name__
'RungeKutta'
>>> type(default_integrator(None, "double")).__name__
'Multistep'

solprop.driver.defaults.default_rtol(route, precision)[source]#

Return a route’s default relative tolerance in the run’s precision.

The one rule every route follows. Binary64 takes the route’s own. Binary32 takes the larger of it and SINGLE_RTOL_FLOOR, so it is never tighter than its binary64 twin nor than binary32 rounding can serve, and at most SINGLE_RTOL_CAP, the loosest value the single-precision survival record measured (the maintainers’ ruling of 2026-10-28).

Parameters:

routestr: A RouteName.
precision{‘double’, ‘single’}: The run’s precision.

Returns:

float: The default relative tolerance.

Examples

>>> from solprop.driver.defaults import default_rtol
>>> [default_rtol(route, "single") for route in ("gnlse", "capillary", "free")]
[1e-06, 1e-06, 1e-05]
>>> default_rtol("gnlse", "double")
1e-07

solprop.driver.defaults.default_scheme(route, *, interpolate_planes)[source]#

Return how a route applies its temporal collar when no scheme is named.

Parameters:

routestr or None: A RouteName, or None for settings built by hand, which take "nonlinear".
interpolate_planesbool: Whether planes are interpolated inside accepted steps, which the split step cannot serve: such a run takes "nonlinear" (SEP 21).

Returns:

{‘nonlinear’, ‘split_step’}: The scheme.

Examples

>>> from solprop.driver.defaults import default_scheme
>>> default_scheme("radial", interpolate_planes=False)
'split_step'
>>> default_scheme("radial", interpolate_planes=True)
'nonlinear'

solprop.driver.defaults.resolve_noise(route, noise, seed, precision)[source]#

Resolve a constructor’s noise keyword into the model a run carries (SEP 37).

"default" follows the route’s NoisePolicy: the input noise, or none for the row’s reason. Single precision carries none whatever the route, because binary32 rounding swamps a one-photon seed. A seed beside a default that resolves to none is refused rather than silently dropped, and so is a seed beside noise=None. An explicit model is refused where the route is "unmeasured" and warned on beside the TDSE response; any other value is passed through, and an unknown one is refused where it is drawn.

Parameters:

routestr: A RouteName.
noise{‘default’, None, ‘input’, ‘modified’}: The keyword as given.
seedint or None: The keyword seed as given.
precision{‘double’, ‘single’}: The run’s arithmetic.

Returns:

tuple: The model to draw, or None, and the record of how it was chosen.

Raises:

DriverError: If a seed is given and the run resolves to no noise, or a model is asked for on a route with no photon measure.

Warns:

SolpropWarning: When a TDSE run asks for a noise model explicitly.

Examples

>>> from solprop.driver.defaults import resolve_noise
>>> resolve_noise("capillary", "default", None, "double")
('input', NoiseResolution(requested='default', resolved='input', reason=None))
>>> resolve_noise("free", "default", None, "double")[1].reason[:20]
'a Cartesian or line '

solprop.driver.defaults.route_defaults(route)[source]#

Return a route’s row of ROUTE_DEFAULTS.

Parameters:

routestr: A RouteName.

Returns:

RouteDefaults: The row.

Raises:

DriverError: If route is not a row of the table.

Examples

>>> from solprop.driver.defaults import route_defaults
>>> route_defaults("free").noise_reason.startswith("a Cartesian or line run")
True

solprop.driver.defaults.rtol_in_precision(rtol, precision)[source]#

Return a binary64 default tolerance as the run’s precision takes it.

The rule default_rtol() applies to a route’s row, for any binary64 value.

Parameters:

rtolfloat: The binary64 default.
precision{‘double’, ‘single’}: The run’s precision.

Returns:

float: rtol in binary64; clamped to the single-precision floor and cap otherwise.

Examples

>>> from solprop.driver.defaults import rtol_in_precision
>>> [rtol_in_precision(rtol, "single") for rtol in (1e-8, 1e-5, 1e-3)]
[1e-06, 1e-05, 1e-05]