solprop.driver.interface#

The keyword interface: one call from GNLSE coefficients to a written run.

prop_gnlse() builds the grid, the dispersion-specified fibre, the input pulse, the noise realisation and the numerical settings from keywords, hands them to solprop.driver.simulation.Simulation.from_gnlse(), runs it and returns the output handler it wrote. prop_capillary() and prop_waveguide() do the same for a gas-filled capillary and for any other modal waveguide.

The step controls rtol, atol, dz_init and dz_max are keywords of every interface. raman defaults to false, and the whole of gamma then acts as Kerr; the Raman share is taken from gamma only when the Raman response is on. What a run was asked for is recorded as structured metadata.

The manual page is docs/guide/setup/running.md.

Functions

`prop_capillary`(radius, length, gas[, ...])	Propagate a pulse through a gas-filled hollow capillary.
`prop_free`(grid, space, medium, responses, ...)	Propagate a beam in free space and return its saved output.
`prop_gnlse`(gamma, length[, betas, ...])	Propagate a pulse through a GNLSE fibre and return the output it was written to.
`prop_planar`(grid, space, responses, initial, ...)	Propagate a beam in a hollow planar guide, resolved in y, and return its output.
`prop_waveguide`(modes, length[, gas, ...])	Propagate a pulse through a gas-filled waveguide mode set, or through a guide.

solprop.driver.interface.prop_capillary(radius, length, gas, pressure=None, *, pressure_floor=None, vacuum_end=None, wavelength, wavelength_limits=None, trange=None, grid=None, envelope=False, fwhm=None, width=None, shape='gauss', energy=None, peak_power=None, phases=(), pulses=None, launch=None, modes=1, mode_average=False, lattice=None, wall=None, taper_coupling=True, model='full', loss=True, cladding=None, susceptibility=None, temperature=None, kerr=True, thg=None, plasma=None, preionisation=None, plasma_integration=None, raman=None, n_r=None, n_theta=None, radial_rule='gauss_kronrod', ionisation_field_range=None, 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), noise='default', seed=None, rtol=None, atol=1e-10, dz_max=None, dz_init=None, schedule=None, integrator=None, interpolate_planes=False, step_planes=None, save_planes=None, n_save=None, stats=None, polarisation_taper=False, node_budget=None, backend='auto', polarisation=None, materials=None, tdse=None, tdse_execution=None, output=None, snapshots=None, resume=False, progress=None, progress_period=10.0, tdse_archive=None)[source]#

Propagate a pulse through a gas-filled hollow capillary.

The mode set, the fixed transverse quadrature, the pressure and density paths, the Kerr and plasma responses, the input pulse and the numerics are all built from keywords, and the run goes into memory or into a file. It is solprop.driver.simulation.Simulation.from_capillary() followed by solprop.driver.simulation.Simulation.run(); docs/guide/setup/running.md has the discussion.

What differs from prop_gnlse() is the physics, not the machinery: a field grid rather than an envelope one, a set of modes on a shared transverse quadrature rather than one mode-averaged effective area (unless mode_average asks for that area), a gas whose density varies along z and carries both the dispersion and the nonlinearity, and a plasma response whose ionisation rate is tabulated once over the fields the run will reach.

The step control is reached through rtol, atol, dz_max and dz_init, and the default step caps are relative to the capillary length rather than absolute. The path is scalar: polarisation and the vector route are refused by name.

Its keywords are from_capillary()’s, then the run controls of run().

Parameters:

radiusfloat or solprop.profiles.ZProfile: Core radius, m, constant or along z.
lengthfloat: Capillary length, m.
gasGas, str, Mapping or Mixture: Built-in gas, mole fractions keyed by species name, or ordered populations carrying their own density paths. A mapping uses total pressure.
pressurefloat, sequence, ZProfile or None, optional: None uses one bar for a gas or fractions. Omit pressure beside a Mixture; every explicit pressure is refused because it already carries its paths. Fill pressure in bar: a number for a constant fill, a pair (p_in, p_out) for the steady-flow gradient of solprop.profiles.PressureGradient.two_point(), or (z, p) with the positions and the pressures there for solprop.profiles.PressureGradient.from_stages().
pressure_floorfloat or None, optional: Lowest pressure the fill is allowed to reach, bar; None takes solprop.profiles.DEFAULT_PRESSURE_FLOOR_FRACTION of the highest stage pressure. With vacuum_end="floor", pass 0.0 for a true vacuum end, which warns, because dp/dz diverges there. Refused beside a constant pressure or a pressure profile, which have no end to apply it to.
vacuum_end{‘choked’, ‘floor’} or None, optional: How a pressure gradient’s outer end below its choked pressure is treated. None (the default) means "choked" for a circular hollow guide: the fill follows the bore (Pennetta et al. 2019, eq. 6) and an end exhausting into vacuum takes the choked pressure of the flow (solprop.gasflow.steady_fill()), with a warning if the flow is not laminar. "floor" concerns the ends only: it keeps the declared end pressures, raised only to pressure_floor, for a comparison with a model that imposes them, while a taper’s fill still follows the bore (on a uniform bore, bitwise the uniform law). Refused beside a constant pressure, a pressure profile or a Mixture, which have no end to choke, and on the general route. Every mode declaring core_radius – every MarcatiliMode subclass, a TabulatedMode built from arrays included – is taken as a circular bore of that radius; a rectangular guide keeps the uniform law.
wavelengthfloat: Reference wavelength, m, and the pulse’s centre wavelength.
wavelength_limitstuple of float or None, optional: Shortest and longest wavelength of the frequency window, m. Required unless grid is given.
trangefloat or None, optional: Requested width of the time window, s. Required unless grid is given.
gridsolprop.grid.TimeGrid or None, optional: A grid of one’s own, instead of the three keywords above; the only way to reach dt, ffac or the transform size.
envelopebool, optional: Propagate an envelope. Plasma is off by default; explicit plasma=True selects cycle averaging of instantaneous rates. Plasma forbids THG.
fwhmfloat or None, optional: Pulse duration at half maximum, s.
widthfloat or None, optional: Natural width of a sech pulse, s; give this or fwhm.
shape{‘gauss’, ‘sech’}, optional: Transform-limited shape of the input.
energyfloat or None, optional: Pulse energy, J. Give this or peak_power.
peak_powerfloat or None, optional: Peak power, W, realised after the spectral phases.
phasessequence of float, optional: Taylor spectral phases about wavelength, optics convention: CEP in rad, group delay in s, GDD in s^2, and so on.
pulsessequence of solprop.pulses.Pulse or None, optional: Several pulses launched together, for two-colour and multi-colour inputs: each a solprop.pulses object with its own wavelength, duration, energy or peak power, phase and delay; the input is the sum of their fields (PulseSum). Replaces the single-pulse keywords fwhm, width, shape, energy, peak_power and phases, which must then be left unset; wavelength still sets the grid’s reference wavelength.
launchmapping, sequence of mapping, or None, optional: Launch the input into chosen modes (SEP 41, S5): a mapping from a mode’s display label or index to its share, or to {"share": s, "phase": phi} with the phase in radians (optics convention), as {"HE1,1": 0.9, "HE1,2": {"share": 0.1, "phase": 1.57}}; or a list of such mappings, one for each pulse in pulses. A label may leave out a parity the set carries once ("HE1,1" for "HE1,1:even"). The shares are energy fractions, normalised to one for each pulse, and the launch is recorded as configuration["modal_launch"] (docs/guide/setup/pulses.md). None, the default, puts the input in the first mode.
modesint or sequence of Mode, optional: How many HE_1m modes to propagate, or the mode set itself. A set is checked for orthonormality. Supplied sets may include TabulatedHollowMode or TabulatedMode with their own tables. A supplied set carries its own geometry: radius must agree with every mode’s core radius along the run, and a model, loss or cladding declared away from its default must be every mode’s own, or the call is refused by name rather than the argument ignored.
mode_averagebool, optional: Propagate the one mode mode-averaged, as a uniform disc of its effective area, instead of resolving it on the transverse rule, as Luna.jl’s default does (docs/guide/waveguides/mode-averaging.md). The plasma then sees the area-mean field, below the on-axis one (HE_11’s axis intensity is 1.768 times P/A_eff), and peak_intensity stays on the axis. False, the default, resolves the mode. Refused beside more than one mode and beside n_r, n_theta or a radial_rule.
latticeTubeLattice or None, optional: Tube geometry for an integer mode count, selecting Vincetti modes. Refused with supplied modes, which carry their own geometry, and with model="reduced". None selects ordinary capillary modes.
wallsolprop.modes.CoherentWall or None, optional: Declare the scalar coherent wall block: the outgoing Robin boundary condition condensed onto the retained basis, which couples every HE_1m channel to every other with a definite phase instead of giving each its own Marcatili attenuation. It needs the contiguous set HE_11 to HE_1N – or, with impedance="te_tm", one azimuthal order – on a constant or a varying guide, and a scalar run; it carries the default "input" noise and refuses "modified". numpy_ref and native execute it; every other mode set or geometry is refused by name. None, the default, carries no wall: the modes keep their own Marcatili loss, and a multimode taper its taper coupling (below).
taper_couplingbool, optional: On a multimode capillary whose radius varies along z, carry the taper coupling – the connection <psi_m|d_z psi_n> that moves power between the HE_1m channels as the bore changes – lossless or not. True, the default; False is the explicit opt-out to the adiabatic route, on which each channel follows its local mode and exchanges no power. It is refused beside wall, which always carries the connection, and has no effect on one channel, a constant bore (a pressure gradient included, which does not change the modes’ shape) or a set that is not the contiguous HE_11 to HE_1N block (docs/guide/waveguides/capillaries.md, “Tapers”).
model{‘full’, ‘reduced’}, optional: Which Marcatili model the modes use; beside a supplied set, refused unless it is the default or the modes’ own.
lossbool, float or callable, optional: Propagation loss of the modes; beside a supplied set, refused unless it is the default or the modes’ own.
claddingGlassIndex, complex or None, optional: Cladding index; None is the package’s cited silica. Beside a supplied set, refused unless it is the default or the modes’ own.
susceptibilityGasSusceptibility or None, optional: A gas susceptibility replacing the one gas selects, for a comparison against another code’s refractive data. Refused for a fraction mapping or an existing mixture, which own their species models.
temperaturefloat, ZProfile or None, optional: Gas temperature, K, or a path of it along z in m. Sets the density the pressure path maps to, so it changes both the dispersion and the nonlinearity. A path also weights a steady-flow gradient by the gas’s eta(T) T (docs/guide/waveguides/profiles.md), makes a shared mixture’s populations independent parameters, and holds the rotational Raman populations at one reference temperature with a RamanTemperatureWarning (solprop.nonlinear.mixtures.raman_temperature()). A constant path is the number, bit for bit. None (the default) is 293.15 K. A Mixture owns its temperature: beside one, a temperature must be omitted or be the mixture’s own (the same number or path object), and any other is refused by name.
kerrbool, optional: Include the Kerr response.
thgbool or None, optional: Include third-harmonic generation in the Kerr term; None takes not envelope.
plasmabool, IonisationRate, Mapping or None, optional: Include photoionisation. None takes not envelope. True selects optmat’s recommended rate model of each built-in gas (SEP 3, D1; OptmatRate, or the model the selection’s ionisation names), for a single gas and for every component of a mixture; a custom species needs its own rate. A rate object is used as given; a mapping selects a rate or switch per component label, and omitted labels are off.
preionisationfloat, ZProfile, Mapping or None, optional: Initial ionised fraction in [0, 1], globally or per label: a number, or a path along z in m giving the fraction ionised before the pulse arrives at each position. None and omitted mapping labels retain the component’s existing declaration.
plasma_integration{‘band’, ‘trapezoid’} or None, optional: How the field-grid plasma forms its population and free-current integrals (SEP 18): 'band' filters each integrand with taps designed for the grid, exact to a certified 1e-5 across the active band; 'trapezoid' is the plain cumulative trapezoid, short by up to 11 % per integral at the top of the default active band, which the frozen witness comparisons use. None takes PlasmaResponse’s default. Refused with envelope plasma, whose currents are converted exactly, and when the plasma is off.
ramanbool, sequence of str, Mapping or None, optional: None (the default) turns the Raman response on for every species whose optmat response is curated – N2, O2, H2, D2, CH4 and SF6 – leaves an atom without one, and warns (solprop.exceptions.SolpropWarning) for a molecule whose response is provisional (N2O, unless the selection’s raman is "provisional") rather than leaving it out silently; with kerr=False the default is off. False disables it; True selects the available models of a mixture and is refused by name for a single gas without data; explicit labels or MolecularOptions select components and terms, and a named unavailable model fails explicitly.
n_rint or None, optional: Radial nodes of the fixed rule. None takes default_radial_order() of the mode count.
n_thetaint or None, optional: Azimuthal nodes. Refused for a set of purely radial modes, which need none.
radial_rulestr, optional: The radial rule family (SEP 19): "gauss_kronrod" (the default), whose embedded Gauss subset is the quadrature alarm’s error estimate; "gauss", with no alarm; or "field_scale" and "field_scale_radau", Gaussian in the HE_11 field scale for expensive responses, which need exactly one Marcatili HE_11 mode and have no alarm (docs/guide/waveguides/radial-quadrature.md).
ionisation_field_rangetuple of float or None, optional: Field amplitudes in V/m the rate table must cover. None derives them from the input’s peak field over the axis and the transverse nodes; see solprop.driver.inputs.default_field_range().
absorbersolprop.boundaries.Absorber, False or None, optional: The collar rates; None builds the default collar of the grid, and False switches both soft collars, temporal and spectral, off and keeps the hard band mask (solprop.boundaries.no_absorber(); SEP 21).
absorber_scheme{‘nonlinear’, ‘split_step’} or None, optional: How the temporal collar is applied (ADR-025): inside every stage, the default, or once per accepted step. The low-call Adams methods of SEP 13 step much further with 'split_step', whose first-order splitting error stays inside the collar.
boundary_checksolprop.monitor.BoundaryCheck or None, optional: How the run watches its time window’s edges (SEP 21): the default warns, then stops, when light above the shot-noise floor reaches them; None watches nothing, for a window kept narrow on purpose.
noise{‘default’, None, ‘input’, ‘modified’}, optional: Which shot-noise model to carry. "default", the default, resolves to "input" wherever the run can carry noise, and records the resolution (SEP 37).
seedint or None, optional: Entropy of the noise generator.
rtolfloat or None, optional: Relative step tolerance; the default is CAPILLARY_RTOL, the capillary default. Calibrate it for a production run (docs/dev/stepper.md section 3).
atolfloat, optional: Absolute step tolerance, in the square root of watts; 1e-10 by default (WAVEGUIDE_ATOL).
dz_maxfloat or None, optional: Cap on the step, m; None takes half the capillary.
dz_initfloat or None, optional: First step, m; None takes length * 1e-4.
schedulesolprop.stepper.schedule.FixedSchedule or None, optional: A fixed schedule to replay instead of stepping adaptively.
integratorMultistep, RungeKutta or LowStorageRungeKutta, optional: The method that steps the run (docs/guide/numerics/choosing-a-stepper.md). None, the default, takes Multistep(): the low-call exponential Adams method, one response evaluation per step. RungeKutta() is the interaction-picture DOPRI5 march, for a cheap response or a state too large for the Adams history; it is also faster on a long run with Raman or plasma (SEP 37). LowStorageRungeKutta() replays schedule in three registers (SEP 24).
interpolate_planesbool, optional: Observe the save planes inside accepted steps instead of landing on them (SEP 14): through the Adams march’s own polynomial, or DOPRI5’s continuous extension with RungeKutta(). Default False.
step_planesint or None, optional: Also save the end of every step_planes-th accepted step, the march’s own positions, beside the requested planes (SEP 14); 0 saves the requested planes only. None, the default, is 0, or 1 with a tdse response, which saves every accepted step without imposing a landing (SEP 20 section 5.8).
save_planessequence of float or None, optional: Positions to save at, m. Give this or n_save.
n_saveint or None, optional: How many planes to save, counting z = 0.
statssolprop.stats.StatsSpec or None, optional: Which statistics to record; None takes solprop.stats.default_spec() with the profiles, for a multimode run or, under mode_average=True, a mode-averaged one without the quadrature estimate, plus every statistic only a backend can compute.
polarisation_taperbool, optional: Whether the spectral collar tapers the nonlinear polarisation as well as absorbing the field through the linear operator. Default False: 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).
node_budgetint or None, optional: Bytes of node-chunk buffers the response pass may hold, an execution setting; None, the default, leaves the backend’s automatic choice.
backendstr, optional: Registry name, or "auto" (the default) for native, which refuses if it isn’t installed or this processor is below its baseline. There is no fallback, and import or construction errors stay visible.
polarisationstr, float or None, optional: Refused; this path is scalar.
materialssolprop.physdata.selection.MaterialSelection or None, optional: Take the run’s built-in materials from optmat under this selection: a gas or fraction mapping of built-in gases, "air" and Gas.Air resolve through solprop.physdata.species() and solprop.physdata.mixtures.Mixture.air() with it, and the default cladding (cladding=None with a numbered mode set) is optmat’s recommended silica. A supplied mixture, mode set, cladding or susceptibility is taken as it is. The run records its material manifest. None (the default) is MaterialSelection().
tdsesolprop.nonlinear.tdse.TDSEGasResponse or None, optional: A helium TDSE response, SAE or haCC, used as the complete electronic response of the fill instead of the Kerr, plasma and Raman responses (SEP 20 section 5.2); plasma, raman, preionisation, plasma_integration, ionisation_field_range and thg must then be left unset and kerr true. backend="auto" resolves to "numpy_ref", the only backend that executes it; statistics default to those the route defines; omitted save_planes and n_save save only the final position beside every accepted step. An atomic window whose duration is unresolved takes trange. None keeps the rate-based responses.
tdse_executionsolprop.nonlinear.tdse.TDSEExecution or None, optional: Atomic runtime resources of tdse: device, memory limit, rows per call and call cap. None beside tdse takes TDSEExecution(); refused without tdse.
outputsolprop.output.store.Output or pathlib.Path or str or None, optional: Where the run goes: a handler, a path to stream an HDF5 file to, or None for a solprop.output.memory.MemoryOutput.
snapshotssolprop.output.SnapshotController or None, optional: Immutable local checkpoints at committed accepted steps; requires HDF5, all fields and non-interpolated observations.
resumebool or {‘interpolated’}, optional: Continue the file at output when its record and this run’s have one configuration hash; otherwise it is refused, naming what changed. Only a path can be resumed. "interpolated" also continues from a plane interpolated inside a step (solprop.driver.simulation.Simulation.run()).
progressProgressReporter, {‘auto’, ‘bar’, ‘log’, ‘none’} or None, optional: Where progress goes; None takes the process default: a bar on a terminal or in a notebook, log lines otherwise (solprop.driver.run.run_problem()).
progress_periodfloat, optional: Seconds between the default reporter’s periodic lines, s; 0 leaves only the plane and closing lines. Ignored when progress is given.
tdse_archivesolprop.output.TDSEArchive or None, optional: Archive every raw provider evaluation of tdse in a separate HDF5 file (run()); refused without tdse.

Returns:

solprop.output.store.Output: The handler the run wrote, closed. A MemoryOutput stays readable; read a file back with solprop.output.hdf5.open_file().

Raises:

DriverError: If a keyword is missing, inconsistent, or names something this path does not carry.
OutputError: If a resume is asked for against a file whose configuration hash differs (solprop.driver.simulation.Simulation.run()).

Examples

A short helium capillary with a pressure gradient, two modes and no plasma, run into memory. The window a capillary needs is wider than the band any gas index is fitted over, so the run reports the extrapolation once per model and the example silences it:

>>> import warnings
>>> from solprop.driver import prop_capillary
>>> from solprop.exceptions import MaterialRangeWarning
>>> with warnings.catch_warnings():
...     warnings.simplefilter("ignore", MaterialRangeWarning)
...     output = prop_capillary(
...         125e-6, 0.02, "He", (2.0, 1.0), wavelength=800e-9,
...         wavelength_limits=(300e-9, 3e-6), trange=100e-15,
...         fwhm=10e-15, energy=5e-6, modes=2, plasma=False,
...         n_r=16, n_save=2, rtol=1e-8,
...     )
>>> output["field"].shape[1:]
(2, 1, 193)

The pressure the run saw is recorded beside the field, and it falls along the capillary:

>>> pressure = output["stats/pressure"]
>>> bool(pressure[-1] < pressure[0])
True

solprop.driver.interface.prop_free(grid, space, medium, responses, initial, *, settings, frame=None, noise='default', seed=None, materials=None, 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, output=None, snapshots=None, resume=False, progress=None, progress_period=10.0)[source]#

Propagate a beam in free space and return its saved output.

On a solprop.grid.RadialGrid the beam is cylindrically symmetric; on a solprop.grid.FreeGrid it is resolved on Cartesian axes; a solprop.grid.LineGrid propagates a beam uniform in y, whose output’s energies and powers are then per metre of y (J/m, W/m), and processing and plotting label them so.

Its keywords are from_free()’s, then the run controls of run().

Parameters:

gridsolprop.grid.TimeGrid: Field or envelope time grid, in SI units.
spacesolprop.grid.RadialGrid, solprop.grid.FreeGrid or solprop.grid.LineGrid: Radial nodes, outer radius and spatial collar; or Cartesian axes, area measure and spatial collar.
mediumsolprop.spatial.SpatialMedium: Homogeneous transverse material. Its gas density may vary along z on a radial grid; on a Cartesian or line grid it must be constant.
responsescollections.abc.Sequence: Existing Kerr, plasma or explicitly declared Raman response objects.
initialSpatialPulse, SpatialPulseSum or numpy.ndarray: Beam specification or internal spectrum of shape (n_columns, n_pol, n_omega): a Hankel spectrum in V m, n_r columns, on a radial grid; a Cartesian DFT spectrum in V/m, n_x*n_y columns, otherwise.
settingsSimulationSettings: Step tolerances, positive save positions in m, statistics and backend. Absolute tolerance has the input spectrum’s units.
framesolprop.linear.Frame or None, optional: Moving frame. None uses the declared responses’ THG choice.
noise{‘default’, None, ‘input’, ‘modified’}, optional: One photon per transverse column, polarisation and active bin. "default", the default, resolves to "input" on a radial grid; on a Cartesian or line grid it resolves to no noise and records why (FREE_NOISE, SEP 37), so pass "input" or "modified" there for a noise model.
seedint or None, optional: Random generator seed; None draws and records system entropy.
materialssolprop.physdata.selection.MaterialSelection or None, optional: Take the medium’s gas from optmat under this selection: a SpatialMedium naming a built-in gas becomes the one-population Mixture of that gas under the selection at the same pressure and temperature (a supplied susceptibility is kept). A mixture, glass or constant index is taken as it is. An optmat rate’s energy per event is bound to the input’s peak field (SEP 3, Q14); every response, a KerrResponse included, is the caller’s (gamma3("Ar", wavelength=...) is optmat’s coefficient at a carrier). The run records its material manifest. None (the default) is MaterialSelection().
absorbersolprop.boundaries.Absorber, False or None, optional: Overrides settings’ absorber, which must then declare none. False switches the temporal and spectral collars off and keeps the hard band mask; the transverse collars keep their own settings (SEP 21 section 5).
absorber_scheme{‘nonlinear’, ‘split_step’} or None, optional: Overrides settings’ temporal scheme, which must then be the default.
boundary_checksolprop.monitor.BoundaryCheck or None, optional: How the run watches its time window’s edges (SEP 21), when settings name the default check: the default warns, then stops, when light above the shot-noise floor reaches them; None watches nothing. Refused beside settings that name another check.
spatial_absorbersolprop.boundaries.SpatialAbsorber, False or None, optional: The transverse boundary (SEP 40), when settings declare none: None keeps the settings’ own, by default the safety ramp alone; a SpatialAbsorber asks for a designed collar in the grid’s room outside its requested size; False carries no ramp.
outputsolprop.output.store.Output or pathlib.Path or str or None, optional: Where the run goes: a handler, a path to stream an HDF5 file to, or None for a solprop.output.memory.MemoryOutput.
snapshotssolprop.output.SnapshotController or None, optional: Immutable local checkpoints at committed accepted steps; requires HDF5, all fields and non-interpolated observations.
resumebool or {‘interpolated’}, optional: Continue the file at output when its record and this run’s have one configuration hash; otherwise it is refused, naming what changed. Only a path can be resumed. "interpolated" also continues from a plane interpolated inside a step (solprop.driver.simulation.Simulation.run()).
progressProgressReporter, {‘auto’, ‘bar’, ‘log’, ‘none’} or None, optional: Where progress goes; None takes the process default: a bar on a terminal or in a notebook, log lines otherwise (solprop.driver.run.run_problem()).
progress_periodfloat, optional: Seconds between the default reporter’s periodic lines, s; 0 leaves only the plane and closing lines. Ignored when progress is given.

Returns:

solprop.output.store.Output: Saved fields, metadata, statistics and step history.

solprop.driver.interface.prop_gnlse(gamma, length, betas=None, *, wavelength, wavelength_limits=None, trange=None, grid=None, beta=None, fibre=None, n2=None, fwhm=None, width=None, shape='gauss', energy=None, peak_power=None, phases=(), pulses=None, loss_db_per_m=None, shock=True, raman=False, raman_fraction=None, noise='default', seed=None, rtol=None, atol=1e-14, dz_max=None, dz_init=None, schedule=None, integrator=None, interpolate_planes=False, step_planes=None, save_planes=None, n_save=None, stats=None, polarisation_taper=False, 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), backend='auto', materials=None, output=None, snapshots=None, resume=False, progress=None, progress_period=10.0)[source]#

Propagate a pulse through a GNLSE fibre and return the output it was written to.

The fibre is its dispersion and its nonlinear coefficient: beta(omega) as Taylor coefficients about wavelength or as data, gamma in 1/(W m), and a power loss in dB/m. The mapping onto solprop’s physics is solprop.nonlinear.gnlse.problem_from() – n2 = gamma A_eff / k_0, chi3 = (4/3) n2 eps_0 c, an effective index of one in the normalisation prefactor and the shock term as that prefactor’s omega dependence (docs/guide/waveguides/gnlse.md). The run is an ordinary mode-averaged envelope propagation; there is no separate GNLSE solver.

Units are SI throughout (docs/dev/conventions.md section 1) and the spectral phase is in the optics convention, as is every spectrum the output stores (docs/dev/conventions.md section 2).

Its keywords are from_gnlse()’s, then the run controls of run().

Parameters:

gammafloat or None: Nonlinear coefficient in 1/(W m), positive for a self-focusing medium.
lengthfloat: Fibre length, m, positive.
betasarray_like, optional: Taylor coefficients of beta about wavelength, beta_0, beta_1, ..., in s^n/m. beta_0 and beta_1 only fix the frame and change no physics. Give exactly one of this, beta or fibre.
wavelengthfloat: Reference wavelength, m, positive: the gamma mapping’s reference, the centre of the Taylor expansion, the grid’s reference and the pulse’s centre wavelength.
wavelength_limitstuple of float, optional: Shortest and longest wavelength of the frequency window, m, increasing and positive. Required unless grid is given.
trangefloat, optional: Extent of the time window, s. Required unless grid is given.
gridsolprop.grid.TimeGrid, optional: An envelope grid to propagate on instead of building one from length, wavelength, wavelength_limits and trange. This is the way to choose the sample spacing, the oversampling factor or the transform size. A field grid is refused: the GNLSE mapping is the envelope Kerr response.
betatuple or callable, optional: The propagation constant as data instead of a series: a pair of arrays (omega, beta) in rad/s and 1/m with strictly increasing frequencies, or a callable of omega which is sampled on the grid’s active band. Either is interpolated by a cubic spline and differentiated exactly in the spline basis (solprop.nonlinear.gnlse.TabulatedDispersion); evaluation outside the data raises rather than extrapolating.
fibreMode or IndexTable, optional: Whole dispersion and loss instead of betas or beta. A mode goes through solprop.nonlinear.gnlse.SpecifiedMode.from_mode(), so one whose geometry moves along z – a tapered mode, a moving guide’s provider channel, a SpecifiedMode with dispersion and area paths – hands over its dispersion and its area along z; only the fixed-step scaffold requires a z-constant fibre. Its fill, if present, is ignored as a nonlinear material because the GNLSE uses gamma or n2. The mode supplies only dispersion, loss and area; use from_capillary() for its material responses. A table’s area is evaluated at wavelength, and so is a provider channel’s, by a fresh solve there (along the path of a moving guide); without an area column a table requires gamma and uses the 1 m^2 convention.
n2float or str, optional: Nonlinear index in m^2/W, requiring fibre and gamma=None. Exactly one of gamma and n2 is required. The mapping is gamma = n2 omega0 / (c A_eff), with unit prefactor index. Under materials, "recommended" takes optmat’s silica bundle’s total n2 (kerr/SiO2) at wavelength.
fwhmfloat, optional: Intensity full width at half maximum of the input pulse, s. Give this or, for a sech pulse, width.
widthfloat, optional: Natural width of a sech**2 input, s, which is fwhm / (2 ln(1 + sqrt(2))). Only for shape="sech".
shape{‘gauss’, ‘sech’}, optional: Shape of the input pulse.
energyfloat, optional: Pulse energy, J. Give this or peak_power.
peak_powerfloat, optional: Peak power, W, realised after the spectral phase is applied.
phasesarray_like, optional: Optics-convention spectral phase as Taylor coefficients about wavelength: [CEP (rad), group delay (s), GDD (s**2), TOD (s**3), ...].
pulsessequence of solprop.pulses.Pulse or None, optional: Several pulses launched together, for two-colour and multi-colour inputs: each a solprop.pulses object with its own wavelength, duration, energy or peak power, phase and delay; the input is the sum of their fields (PulseSum). Replaces the single-pulse keywords fwhm, width, shape, energy, peak_power and phases, which must then be left unset; wavelength still sets the grid’s reference wavelength.
loss_db_per_mfloat or None, optional: Omitted means zero loss on the coefficient routes. Refused beside fibre, which carries its own loss. Power loss in dB/m; negative values describe gain. Converted by solprop.nonlinear.gnlse.attenuation_from_db().
shockbool, optional: Keep the omega dependence of the normalisation prefactor, which is the optical shock term. Default True.
ramanbool, optional: Whether a fused-silica Raman response takes raman_fraction of gamma, the rest staying with the Kerr term (solprop.nonlinear.gnlse.raman_susceptibility()). Default False, which gives the whole of gamma to the Kerr term.
raman_fractionfloat or None, optional: Share of gamma held back from the Kerr term, between 0 and 1. Omitted, it is the silica bundle’s own f_R with raman true – 0.2188 for optmat’s default (SEP 3, D4) – and 0 with it false. Given, it is held back whatever raman is, so a pair of runs with the same fraction that switches only raman isolates the delayed response.
noise{‘default’, None, ‘input’, ‘modified’}, optional: Which shot-noise model to carry: 'input' adds one photon per bin to the input field once, 'modified' keeps the realisation apart and injects it at every stage, advanced by the unitary part of the linear operator (docs/guide/media/noise.md). "default", the default, resolves to "input" wherever the run can carry noise, and records the resolution (SEP 37).
seedint, optional: Entropy of the generator the realisation is drawn from. Recorded in the output, so a run is reproducible; None draws from the operating system and records what it drew.
rtolfloat or None, optional: Relative tolerance of the step controller, dimensionless and positive. None takes DEFAULT_RTOL, 1e-7. The map from this local tolerance to the global error at the output is problem dependent and misses by one to three orders either way, so calibrate rather than assume (docs/dev/stepper.md section 3).
atolfloat, optional: Absolute tolerance, in the square root of watts, non-negative; 1e-14 by default (DEFAULT_ATOL).
dz_maxfloat, optional: Cap on the controller’s step proposal, m; None uses half the length.
dz_initfloat, optional: First step, m; None uses a ten-thousandth of the length.
schedulesolprop.stepper.schedule.FixedSchedule, optional: A fixed schedule to replay instead of stepping adaptively, which makes a run bit-identical on re-running (docs/dev/stepper.md section 8). Its edges must contain every save plane, which solprop.stepper.schedule.FixedSchedule.uniform() guarantees.
integratorMultistep, RungeKutta or LowStorageRungeKutta, optional: The method that steps the run (docs/guide/numerics/choosing-a-stepper.md). None, the default, takes RungeKutta(), the interaction-picture DOPRI5 march, which SEP 37 measured fastest at matched accuracy on the GNLSE (with noise all the more). Multistep() is the low-call exponential Adams method, one response evaluation per step, for an expensive response. LowStorageRungeKutta() replays schedule in three registers (SEP 24).
interpolate_planesbool, optional: Observe the save planes inside accepted steps instead of landing on them (SEP 14): through the Adams march’s own polynomial, or DOPRI5’s continuous extension with RungeKutta(). Default False.
step_planesint or None, optional: Also save the end of every step_planes-th accepted step, the march’s own positions, beside the requested planes (SEP 14); None, the default, and 0 save the requested planes only.
save_planesarray_like, optional: Positions along the fibre to save at, m, increasing and positive; the plane at z = 0 is saved as well. Give this or n_save.
n_saveint, optional: Number of planes to store, counting the one at z = 0, spread evenly over the fibre. Default 201.
statssolprop.stats.StatsSpec, optional: Which statistics to record at every plane; None records solprop.stats.default_spec() of a mode-averaged run. A periodic subset is also recorded between the planes.
polarisation_taperbool, optional: Whether the spectral collar tapers the nonlinear polarisation as well as absorbing the field through the linear operator. Default False: 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).
absorbersolprop.boundaries.Absorber, False or None, optional: The collar rates; None builds the default collar of the grid (default_collar()), and False switches both soft collars off and keeps the hard band mask (solprop.boundaries.no_absorber()).
absorber_scheme{‘nonlinear’, ‘split_step’} or None, optional: How a temporal collar is applied (ADR-025); None is the default, inside every stage.
boundary_checksolprop.monitor.BoundaryCheck or None, optional: How the run watches its time window’s edges (SEP 21): the default warns, then stops, when light above the shot-noise floor reaches them; None watches nothing, for a window kept narrow on purpose.
backendstr, optional: Registry name, or "auto" (the default) for native, which refuses if it isn’t installed or this processor is below its baseline. There is no fallback, and import or construction errors stay visible. solprop.backends.registry.available() lists what can be used.
materialssolprop.physdata.selection.MaterialSelection or None, optional: Take fused silica’s nonlinear response from optmat’s silica bundle under this selection: with raman on, an omitted fraction is the bundle’s f_R and the response its sampled shape, and n2="recommended" is its total n2. The fibre’s dispersion and a given gamma or n2 are the caller’s. The run records its material manifest, with the held-back fraction and its origin. None (the default) is MaterialSelection(), optmat’s recommended models.
outputsolprop.output.store.Output or pathlib.Path or str or None, optional: Where the run goes: a handler, a path to stream an HDF5 file to, or None for a solprop.output.memory.MemoryOutput.
snapshotssolprop.output.SnapshotController or None, optional: Immutable local checkpoints at committed accepted steps; requires HDF5, all fields and non-interpolated observations.
resumebool or {‘interpolated’}, optional: Continue the file at output when its record and this run’s have one configuration hash; otherwise it is refused, naming what changed. Only a path can be resumed. "interpolated" also continues from a plane interpolated inside a step (solprop.driver.simulation.Simulation.run()).
progressProgressReporter, {‘auto’, ‘bar’, ‘log’, ‘none’} or None, optional: Where progress goes; None takes the process default: a bar on a terminal or in a notebook, log lines otherwise (solprop.driver.run.run_problem()).
progress_periodfloat, optional: Seconds between the default reporter’s periodic lines, s; 0 leaves only the plane and closing lines. Ignored when progress is given.

Returns:

solprop.output.store.Output: The handler the run was written to, closed. A solprop.output.memory.MemoryOutput stays readable; read an HDF5 file back with solprop.output.hdf5.open_file().

Raises:

DriverError: If the fibre, the grid, the input, the noise model or the save planes are specified in a way this interface does not accept; the message names what is wrong.
OutputError: If a resume is asked for against a file whose configuration hash differs; the message names what changed.

Examples

A third-order soliton over a hundredth of its period, saved to memory:

>>> import numpy as np
>>> from solprop.driver import prop_gnlse
>>> beta2, gamma, tau0 = -11.83e-27, 0.11, 100e-15
>>> peak = 9 * abs(beta2) / (gamma * tau0**2)
>>> handler = prop_gnlse(
...     gamma, 1.57e-3, [0.0, 0.0, beta2], wavelength=835e-9,
...     wavelength_limits=(500e-9, 2e-6), trange=2e-12,
...     width=tau0, peak_power=peak, shape="sech", shock=False,
...     n_save=3, rtol=1e-8, noise=None,
... )
>>> handler.n_saved, handler["z"].tolist()
(3, [0.0, 0.000785, 0.00157])

The fibre is lossless and the window holds the soliton’s tails clear of the collar, so without shot noise (part of which the collar would absorb) the energy statistic is the same at every plane:

>>> energy = handler["stats/energy"][:, 0, 0]
>>> bool(abs(energy[-1] / energy[0] - 1.0) < 1e-8)
True

solprop.driver.interface.prop_planar(grid, space, responses, initial, *, settings, frame=None, materials=None, 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, output=None, snapshots=None, resume=False, progress=None, progress_period=10.0)[source]#

Propagate a beam in a hollow planar guide, resolved in y, and return its output.

The hybrid planar transform: the slab modes of space in x and a periodic, collared y axis (docs/guide/waveguides/planar.md, “Resolving y”). Diffraction uses the represented angular-spectrum operator. The run integrates over y, so its energies are in J and its powers in W. Constant gap and constant fill only. numpy_ref and native CPU execute the geometry.

Its keywords are from_planar()’s, then the run controls of run().

Parameters:

gridsolprop.grid.TimeGrid: Field or envelope time grid, in SI units.
spacesolprop.modes.slab.PlanarGrid: The slab modes (one gap, one polarisation family, one constant fill) and the y axis with its collar.
responsescollections.abc.Sequence: Existing Kerr, plasma or explicitly declared Raman response objects, scaled by the fill’s number density.
initialsolprop.pulses.PlanarPulse or numpy.ndarray: The astigmatic launch, or an internal (p, k_y) spectrum of slab amplitudes in sqrt(W/m), shape (n_p*n_y, 1, n_omega), the mode index fastest. Any other pulse is refused by name.
settingsSimulationSettings: Step tolerances, positive save positions in m, statistics and backend. Absolute tolerance has the input spectrum’s units, sqrt(W/m).
framesolprop.linear.Frame or None, optional: Moving frame. None uses the declared responses’ THG choice, following the first mode at k_y = 0 as the modal route does.
materialssolprop.physdata.selection.MaterialSelection or None, optional: Take the slab modes’ built-in materials from optmat under this selection and record it in the run’s manifest: a fill of a built-in gas with its default susceptibility takes the selection’s single-species susceptibility (no mixture is needed), and a slab without a declared cladding takes optmat’s recommended fused silica (SEP 3, Q5). A supplied susceptibility or cladding is taken as it is. An optmat rate’s energy per event is bound to the input’s peak field (SEP 3, Q14), and the input is checked against each rate. None (the default) is MaterialSelection().
absorbersolprop.boundaries.Absorber, False or None, optional: Overrides settings’ absorber, which must then declare none. False switches the temporal and spectral collars off and keeps the hard band mask; the transverse collars keep their own settings (SEP 21 section 5).
absorber_scheme{‘nonlinear’, ‘split_step’} or None, optional: Overrides settings’ temporal scheme, which must then be the default.
boundary_checksolprop.monitor.BoundaryCheck or None, optional: How the run watches its time window’s edges (SEP 21), when settings name the default check: the default warns, then stops, when light above the shot-noise floor reaches them; None watches nothing. Refused beside settings that name another check.
spatial_absorbersolprop.boundaries.SpatialAbsorber, False or None, optional: The transverse boundary (SEP 40), when settings declare none: None keeps the settings’ own, by default the safety ramp alone; a SpatialAbsorber asks for a designed collar in the grid’s room outside its requested size; False carries no ramp.
outputsolprop.output.store.Output or pathlib.Path or str or None, optional: Where the run goes: a handler, a path to stream an HDF5 file to, or None for a solprop.output.memory.MemoryOutput.
snapshotssolprop.output.SnapshotController or None, optional: Immutable local checkpoints at committed accepted steps; requires HDF5, all fields and non-interpolated observations.
resumebool or {‘interpolated’}, optional: Continue the file at output when its record and this run’s have one configuration hash; otherwise it is refused, naming what changed. Only a path can be resumed. "interpolated" also continues from a plane interpolated inside a step (solprop.driver.simulation.Simulation.run()).
progressProgressReporter, {‘auto’, ‘bar’, ‘log’, ‘none’} or None, optional: Where progress goes; None takes the process default: a bar on a terminal or in a notebook, log lines otherwise (solprop.driver.run.run_problem()).
progress_periodfloat, optional: Seconds between the default reporter’s periodic lines, s; 0 leaves only the plane and closing lines. Ignored when progress is given.

Returns:

solprop.output.store.Output: Saved fields, metadata, statistics and step history.

solprop.driver.interface.prop_waveguide(modes, length, gas=None, pressure=None, *, provider=None, channel=None, incident=None, coupling=None, kerr_form='real', observable_rtol=None, observable_atol=None, pressure_floor=None, vacuum_end=None, wavelength, wavelength_limits=None, trange=None, grid=None, envelope=False, fwhm=None, width=None, shape='gauss', energy=None, peak_power=None, phases=(), pulses=None, launch=None, susceptibility=None, temperature=None, kerr=True, thg=None, plasma=None, preionisation=None, plasma_integration=None, raman=None, mode_average=False, n_r=None, n_theta=None, radial_rule='gauss_kronrod', ionisation_field_range=None, 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), noise='default', seed=None, rtol=None, atol=1e-10, dz_max=None, dz_init=None, schedule=None, integrator=None, interpolate_planes=False, step_planes=None, save_planes=None, n_save=None, stats=None, polarisation_taper=False, node_budget=None, backend='auto', polarisation=None, taper_coupling=True, materials=None, output=None, snapshots=None, resume=False, progress=None, progress_period=10.0)[source]#

Propagate a pulse through a gas-filled waveguide mode set, or through a guide.

Build with from_waveguide() and run to the requested output. Without provider this is the gas-filled route: rectangular polarisation partners carry distinct operator rows, a hollow planar set (SlabMode) runs per unit width – energy in J/m, peak_power in W/m, and the recorded powers and energies likewise – and step-index fibres use prop_gnlse(fibre=...) instead. With provider it is the general modal route (docs/guide/waveguides/general-modal.md), on a field grid, on every backend (Kokkos on CPUs and GPUs), with HDF5 output.

Its keywords are from_waveguide()’s, then the run controls of run().

Parameters:

modessequence of solprop.modes.protocol.Mode: Non-empty gas-filled mode set with a common transverse geometry. Each mode is rebound to this constructor’s fill (with_mixture): its own gas, pressure and temperature – a temperature path included – are replaced by gas, pressure and temperature, and only its geometry is kept. Beside provider it must be empty or exactly the guide’s own ordered channels: a guide supplies its channels itself, and the provider has already validated their order against its fields.
lengthfloat: Waveguide length, m.
gasGas, str, Mapping, Mixture or None: Built-in gas, mole fractions keyed by species name, or ordered populations carrying their own density paths. A mapping uses total pressure. Required without provider and refused beside one.
pressurefloat, sequence, ZProfile or None, optional: None uses one bar for a gas or fractions. Omit pressure beside a Mixture; every explicit pressure is refused because it already carries its paths. Fill pressure in bar: a number for a constant fill, a pair (p_in, p_out) for the steady-flow gradient of solprop.profiles.PressureGradient.two_point(), or (z, p) with the positions and the pressures there for solprop.profiles.PressureGradient.from_stages().
providersolprop.modes.guide.ModalGuide or None, optional: A guide built by solprop.modes.guide.ModalGuide.from_provider(), so that it carries the sampling its dense E/H reference is rebuilt from. Its knots must span the run’s whole active band, which starts at half the lowest declared frequency; a narrower guide is refused with both bands in the message.
channelint or str or None, optional: Which channel the pulse enters, by index or by display label ("HE1,1:even"); None takes the first, as a gas-filled multimode run puts a single pulse in its fundamental. The launch is the pulse’s amplitude placed in that channel unchanged – a Poynting basis needs no conversion – so the launched true-power energy is the pulse’s. Requires provider.
incidentsolprop.pulses.SpatialPulse or None, optional: An incident beam to launch instead of a named channel: the beam and its temporal pulse, whose energy or peak power is met over the whole beam in the paraxial measure of the guide’s core medium (solprop.pulses.SpatialPulse.incident()). The beam is coupled into the channels by solprop.coupling.coupler.couple() under coupling (SEP 31): it is sampled on a radial plane that resolves it, evaluated at the guide’s nodes, and its coordinates are recovered with the flux pairing and the forward closure H_t = Y0 z x E_t. The recovered amplitudes are launched as they are. Light the channels do not capture is lost, not restored: a beam much wider than the core launches a small share of its energy, and a beam the channels cannot see launches nothing, which is a valid zero launch. The coupling’s CouplingReport – incident and launched energy per frequency and in total, and its admission budget – is recorded as configuration["launch"], and the launch’s provenance as configuration["coupling"]. The beam is launched at its waist (propz=0) and centred on the guide’s axis. The pulse keywords (fwhm, width, energy, peak_power, phases, pulses and shape) are refused beside it, because the beam carries its own pulse. Requires provider and coupling, and is refused beside channel.
couplingsolprop.coupling.models.CouplingModel or None, optional: The model an incident beam is coupled under: CouplingModel("vector_paraxial", model_error=...), whose budget the guide’s contrast, closure and angular content must fit (SEP 31, section 4.3); a strongly guiding core is refused. Requires incident.
kerr_form{‘real’, ‘analytic’}, optional: Which instantaneous cubic a general modal run’s material regions respond with. "real", the default, is the real-field cubic P = eps0 chi3 (E.E) E the legacy field route evaluates, third harmonic included; "analytic" is the analytic-signal form eps0 chi3 (2 |E|^2 E + (E.E) E*) / 4, which carries the fundamental band alone and is what a comparison with an envelope route wants. The real form needs a grid with n_to >= 2 n_t, which is FieldGrid’s default ffac=6, and is refused on a narrower one. Under one of SEP 6’s dispersive electronic policies a region’s gas fill takes the dispersive cubic in the matching sector: "real" its full cubic, "analytic" its number-conserving sector. Requires provider.
observable_rtol, observable_atolfloat or None, optional: Requested accuracy of the named physical observables of a general modal run. None, the only value accepted, means the solver’s own rtol and atol: the route’s basis is orthonormal in true power, so the controller’s weighted norm on the amplitudes already is a norm on the physical channel powers. A different number is refused by name, because the separate error allocation it would ask for – over the table’s interpolation, the transverse rule and the step – is not implemented. Require provider.
pressure_floorfloat or None, optional: Lowest pressure the fill is allowed to reach, bar; None takes solprop.profiles.DEFAULT_PRESSURE_FLOOR_FRACTION of the highest stage pressure. With vacuum_end="floor", pass 0.0 for a true vacuum end, which warns, because dp/dz diverges there. Refused beside a constant pressure or a pressure profile, which have no end to apply it to.
vacuum_end{‘choked’, ‘floor’} or None, optional: How a pressure gradient’s outer end below its choked pressure is treated. None (the default) means "choked" for a circular hollow guide: the fill follows the bore (Pennetta et al. 2019, eq. 6) and an end exhausting into vacuum takes the choked pressure of the flow (solprop.gasflow.steady_fill()), with a warning if the flow is not laminar. "floor" concerns the ends only: it keeps the declared end pressures, raised only to pressure_floor, for a comparison with a model that imposes them, while a taper’s fill still follows the bore (on a uniform bore, bitwise the uniform law). Refused beside a constant pressure, a pressure profile or a Mixture, which have no end to choke, and on the general route. Every mode declaring core_radius – every MarcatiliMode subclass, a TabulatedMode built from arrays included – is taken as a circular bore of that radius; a rectangular guide keeps the uniform law.
wavelengthfloat: Reference wavelength, m, and the pulse’s centre wavelength.
wavelength_limitstuple of float or None, optional: Shortest and longest wavelength of the frequency window, m. Required unless grid is given.
trangefloat or None, optional: Requested width of the time window, s. Required unless grid is given.
gridsolprop.grid.TimeGrid or None, optional: A grid of one’s own, instead of the three keywords above; the only way to reach dt, ffac or the transform size.
envelopebool, optional: Propagate an envelope. Plasma is off by default; explicit plasma=True selects cycle averaging of instantaneous rates. Plasma forbids THG.
fwhmfloat or None, optional: Pulse duration at half maximum, s.
widthfloat or None, optional: Natural width of a sech pulse, s; give this or fwhm.
shape{‘gauss’, ‘sech’}, optional: Transform-limited shape of the input.
energyfloat or None, optional: Pulse energy, J. Give this or peak_power.
peak_powerfloat or None, optional: Peak power, W, realised after the spectral phases.
phasessequence of float, optional: Taylor spectral phases about wavelength, optics convention: CEP in rad, group delay in s, GDD in s^2, and so on.
pulsessequence of solprop.pulses.Pulse or None, optional: Several pulses launched together, for two-colour and multi-colour inputs: each a solprop.pulses object with its own wavelength, duration, energy or peak power, phase and delay; the input is the sum of their fields (PulseSum). Replaces the single-pulse keywords fwhm, width, shape, energy, peak_power and phases, which must then be left unset; wavelength still sets the grid’s reference wavelength.
launchmapping, sequence of mapping, or None, optional: Launch the input into chosen modes or channels (SEP 41, S5): a mapping from a display label or index, resolved as channel resolves it, to a share, or to {"share": s, "phase": phi} with the phase in radians (optics convention), as {"HE1,1": 0.9, "HE1,2": {"share": 0.1, "phase": 1.57}}; or a list of such mappings, one for each pulse in pulses. A label may leave out a parity the set carries once, and one that leaves a parity open between two rows is refused. On a basis whose flux metric is the identity the shares are energy fractions, normalised to one for each pulse; on a guide that declares a change of basis they are relative amplitudes squared, scaled so that the flux-metric energy is the pulse’s, a coordinate split. The launch is recorded as configuration["modal_launch"] (docs/guide/setup/pulses.md). Refused beside channel, incident and coupling. None, the default, puts the input in the first mode or in channel.
susceptibilityGasSusceptibility or None, optional: A gas susceptibility replacing the one gas selects, for a comparison against another code’s refractive data. Refused for a fraction mapping or an existing mixture, which own their species models.
temperaturefloat, ZProfile or None, optional: Gas temperature, K, or a path of it along z in m. Sets the density the pressure path maps to, so it changes both the dispersion and the nonlinearity. A path also weights a steady-flow gradient by the gas’s eta(T) T (docs/guide/waveguides/profiles.md), makes a shared mixture’s populations independent parameters, and holds the rotational Raman populations at one reference temperature with a RamanTemperatureWarning (solprop.nonlinear.mixtures.raman_temperature()). A constant path is the number, bit for bit. None (the default) is 293.15 K. A Mixture owns its temperature: beside one, a temperature must be omitted or be the mixture’s own (the same number or path object), and any other is refused by name.
kerrbool, optional: Include the Kerr response.
thgbool or None, optional: Include third-harmonic generation in the Kerr term; None takes not envelope.
plasmabool, IonisationRate, Mapping or None, optional: Include photoionisation. None takes not envelope. True selects optmat’s recommended rate model of each built-in gas (SEP 3, D1; OptmatRate, or the model the selection’s ionisation names), for a single gas and for every component of a mixture; a custom species needs its own rate. A rate object is used as given; a mapping selects a rate or switch per component label, and omitted labels are off.
preionisationfloat, ZProfile, Mapping or None, optional: Initial ionised fraction in [0, 1], globally or per label: a number, or a path along z in m giving the fraction ionised before the pulse arrives at each position. None and omitted mapping labels retain the component’s existing declaration.
plasma_integration{‘band’, ‘trapezoid’} or None, optional: How the field-grid plasma forms its population and free-current integrals (SEP 18): 'band' filters each integrand with taps designed for the grid, exact to a certified 1e-5 across the active band; 'trapezoid' is the plain cumulative trapezoid, short by up to 11 % per integral at the top of the default active band, which the frozen witness comparisons use. None takes PlasmaResponse’s default. Refused with envelope plasma, whose currents are converted exactly, and when the plasma is off.
ramanbool, sequence of str, Mapping or None, optional: None (the default) turns the Raman response on for every species whose optmat response is curated – N2, O2, H2, D2, CH4 and SF6 – leaves an atom without one, and warns (solprop.exceptions.SolpropWarning) for a molecule whose response is provisional (N2O, unless the selection’s raman is "provisional") rather than leaving it out silently; with kerr=False the default is off. False disables it; True selects the available models of a mixture and is refused by name for a single gas without data; explicit labels or MolecularOptions select components and terms, and a named unavailable model fails explicitly.
mode_averagebool, optional: Propagate the one mode mode-averaged, as a uniform disc of its effective area, instead of resolving it on the transverse rule, as Luna.jl’s default does (docs/guide/waveguides/mode-averaging.md). The plasma then sees the area-mean field, below the on-axis one (HE_11’s axis intensity is 1.768 times P/A_eff), and peak_intensity stays on the axis. False, the default, resolves the mode. Refused beside more than one mode and beside n_r, n_theta or a radial_rule. Refused beside provider.
n_rint or None, optional: Radial nodes of the fixed rule, or the x-axis nodes of a Cartesian product or slab rule. None takes default_radial_order() of the mode count, or cartesian_nodes() of the set’s highest transverse order where that is larger.
n_thetaint or None, optional: Azimuthal nodes, or the y-axis nodes of a Cartesian product rule, whose default is cartesian_nodes(). Refused for a set of purely radial modes, which need none, and for a slab set, which is uniform in y.
radial_rulestr, optional: The radial rule family (SEP 19): "gauss_kronrod" (the default), whose embedded Gauss subset is the quadrature alarm’s error estimate; "gauss", with no alarm; or "field_scale" and "field_scale_radau", Gaussian in the HE_11 field scale for expensive responses, which need exactly one Marcatili HE_11 mode and have no alarm (docs/guide/waveguides/radial-quadrature.md).
ionisation_field_rangetuple of float or None, optional: Field amplitudes in V/m the rate table must cover. None derives them from the input’s peak field over the axis and the transverse nodes; see solprop.driver.inputs.default_field_range().
absorbersolprop.boundaries.Absorber, False or None, optional: The collar rates; None builds the default collar of the grid, and False switches both soft collars, temporal and spectral, off and keeps the hard band mask (solprop.boundaries.no_absorber(); SEP 21).
absorber_scheme{‘nonlinear’, ‘split_step’} or None, optional: How the temporal collar is applied (ADR-025); None is the default, inside every stage.
boundary_checksolprop.monitor.BoundaryCheck or None, optional: How the run watches its time window’s edges (SEP 21): the default warns, then stops, when light above the shot-noise floor reaches them; None watches nothing, for a window kept narrow on purpose.
noise{‘default’, None, ‘input’, ‘modified’}, optional: Which shot-noise model to carry. "default", the default, resolves to "input" wherever the run can carry noise, and records the resolution (SEP 37).
seedint or None, optional: Entropy of the noise generator.
rtolfloat or None, optional: Relative step tolerance; the default is WAVEGUIDE_RTOL, the modal capillary default. Calibrate it for a production run (docs/dev/stepper.md section 3).
atolfloat, optional: Absolute step tolerance, in the square root of watts; 1e-10 by default (WAVEGUIDE_ATOL).
dz_maxfloat or None, optional: Cap on the step, m; None takes half the waveguide.
dz_initfloat or None, optional: First step, m; None takes length * 1e-4.
schedulesolprop.stepper.schedule.FixedSchedule or None, optional: A fixed schedule to replay instead of stepping adaptively.
integratorMultistep, RungeKutta or LowStorageRungeKutta, optional: The method that steps the run (docs/guide/numerics/choosing-a-stepper.md). None, the default, takes RungeKutta(), the interaction-picture DOPRI5 march, which SEP 37 measured fastest at matched accuracy among the methods every route of this constructor admits. Multistep() is the low-call exponential Adams method, and LowStorageRungeKutta() replays schedule in three registers.
interpolate_planesbool, optional: Observe the save planes inside accepted steps instead of landing on them (SEP 14): through the Adams march’s own polynomial, or DOPRI5’s continuous extension with RungeKutta(). Default False.
step_planesint or None, optional: Also save the end of every step_planes-th accepted step, the march’s own positions, beside the requested planes (SEP 14); None, the default, and 0 save the requested planes only.
save_planessequence of float or None, optional: Positions to save at, m. Give this or n_save.
n_saveint or None, optional: How many planes to save, counting z = 0.
statssolprop.stats.StatsSpec or None, optional: Which statistics to record; None takes solprop.stats.default_spec() with the profiles, for a multimode run or, under mode_average=True, a mode-averaged one without the quadrature estimate, plus every statistic only a backend can compute.
polarisation_taperbool, optional: Whether the spectral collar tapers the nonlinear polarisation as well as absorbing the field through the linear operator. Default False: 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).
node_budgetint or None, optional: Bytes of node-chunk buffers the response pass may hold, an execution setting; None, the default, leaves the backend’s automatic choice.
backendstr, optional: Registry name, or "auto" (the default) for native, which refuses if it isn’t installed or this processor is below its baseline. There is no fallback, and import or construction errors stay visible.
polarisationstr, float or None, optional: Refused; this path is scalar.
taper_couplingbool, optional: Carry the taper coupling of a supplied capillary set on a varying radius, as from_capillary() does; False is the opt-out to the adiabatic route. Refused as False beside a provider, whose moving guide carries its own connection.
materialssolprop.physdata.selection.MaterialSelection or None, optional: Take the fill from optmat under this selection: a gas or fraction mapping of built-in gases, "air" and Gas.Air resolve through solprop.physdata.species() and solprop.physdata.mixtures.Mixture.air() with it. The supplied modes, their claddings, a supplied mixture or susceptibility, and a provider’s material regions are taken as they are. The run records its material manifest. None (the default) is MaterialSelection().
outputsolprop.output.store.Output or pathlib.Path or str or None, optional: Where the run goes: a handler, a path to stream an HDF5 file to, or None for a solprop.output.memory.MemoryOutput.
snapshotssolprop.output.SnapshotController or None, optional: Immutable local checkpoints at committed accepted steps; requires HDF5, all fields and non-interpolated observations.
resumebool or {‘interpolated’}, optional: Continue the file at output when its record and this run’s have one configuration hash; otherwise it is refused, naming what changed. Only a path can be resumed. "interpolated" also continues from a plane interpolated inside a step (solprop.driver.simulation.Simulation.run()).
progressProgressReporter, {‘auto’, ‘bar’, ‘log’, ‘none’} or None, optional: Where progress goes; None takes the process default: a bar on a terminal or in a notebook, log lines otherwise (solprop.driver.run.run_problem()).
progress_periodfloat, optional: Seconds between the default reporter’s periodic lines, s; 0 leaves only the plane and closing lines. Ignored when progress is given.

Returns:

solprop.output.store.Output: Saved fields, metadata, statistics and step history.