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_free on a radial or a Cartesian grid, 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.records.NoiseResolution for the noise, solprop.output.records.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.
`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`.
`STEP_FRACTIONS`	The step lengths a keyword route takes when none is given, as fractions of length.

Functions

`default_controller`(route)	Return the step controller a route takes when given no tolerances.
`default_integrator`(route)	Return the integrator a route steps with when none is named.
`default_rtol`(route)	Return a route's default relative tolerance.
`default_scheme`(route, *, interpolate_planes)	Return how a route applies its temporal collar when no scheme is named.
`default_step`(keyword, length)	Return a keyword route's default step length.
`describe_default`(row, keyword[, length])	Return what a route takes for a keyword it is not given, and the rule in words.
`resolve_noise`(route, noise, seed)	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`.
`route_row`(route, *[, tdse, slab])	Return the row of `ROUTE_DEFAULTS` a route's run reads.

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 run steps with when none is named.
rtolfloat: The relative tolerance.
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.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.STEP_FRACTIONS: Mapping[str, tuple[float, str]] = mappingproxy({'dz_max': (0.5, 'half the length'), 'dz_init': (0.0001, 'a ten-thousandth of the length')})#

The step lengths a keyword route takes when none is given, as fractions of length.

Relative, so that the first step and the cap scale with the guide; each with its rule in words. The same on every keyword route (from_gnlse, from_capillary and from_waveguide); the object routes take their steps in their settings.

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)[source]#

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

Parameters:

routestr: A RouteName.

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")
>>> controller.rtol, controller.atol
(1e-05, 0.0)

solprop.driver.defaults.default_integrator(route)[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().

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")).__name__
'RungeKutta'
>>> type(default_integrator("capillary")).__name__
'Multistep'
>>> type(default_integrator(None)).__name__
'Multistep'

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

Return a route’s default relative tolerance.

Parameters:

routestr: A RouteName.

Returns:

float: The default relative tolerance.

Examples

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

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.default_step(keyword, length)[source]#

Return a keyword route’s default step length.

Parameters:

keyword{‘dz_max’, ‘dz_init’}: Which step: the cap or the first.
lengthfloat: The guide’s length, m.

Returns:

float: The step, m: STEP_FRACTIONS of length.

Examples

>>> from solprop.driver.defaults import default_step
>>> default_step("dz_max", 0.4), default_step("dz_init", 1.0)
(0.2, 0.0001)

solprop.driver.defaults.describe_default(row, keyword, length=None)[source]#

Return what a route takes for a keyword it is not given, and the rule in words.

What a front end shows beside an unset keyword (SEP 41): the same table the constructors resolve from.

Parameters:

rowstr: A RouteName (route_row()).
keyword{‘rtol’, ‘integrator’, ‘noise’, ‘dz_max’, ‘dz_init’}: The keyword.
lengthfloat or None, optional: The guide’s length, m, which a step default is a fraction of; None when it is not known, and the step’s value is then None.

Returns:

tuple: The value (a tolerance, an integrator, a noise model or None, or a step in m) and its rule.

Examples

>>> from solprop.driver.defaults import describe_default
>>> describe_default("capillary", "rtol")
(1e-06, "the capillary route's default (solprop.driver.defaults.ROUTE_DEFAULTS)")
>>> describe_default("gnlse", "dz_max", 0.4)
(0.2, 'half the length')

solprop.driver.defaults.resolve_noise(route, noise, seed)[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. 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.

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)
('input', NoiseResolution(requested='default', resolved='input', reason=None))
>>> resolve_noise("free", "default", None)[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.route_row(route, *, tdse=False, slab=False)[source]#

Return the row of ROUTE_DEFAULTS a route’s run reads.

Parameters:

routestr: The route: a RouteName without its variant.
tdsebool, optional: Whether a capillary run carries the TDSE response.
slabbool, optional: Whether the mode set is a slab set, which carries no noise.

Returns:

str: "waveguide slab" for a slab set, "capillary tdse" beside a TDSE response, and route otherwise.

Examples

>>> from solprop.driver.defaults import route_row
>>> route_row("capillary", tdse=True), route_row("waveguide", slab=True)
('capillary tdse', 'waveguide slab')