solprop.driver.simulation#

The simulation object: physics objects in, a written, resumable run out.

A Simulation holds what a run is made of – the grid, the modes, the responses, the input, the noise and the numerical settings – translates it once into a solprop.translate.problem.PropagationProblem, and can then be run as often as one likes, into memory or into a file. It owns three things the loop of solprop.driver.run does not: the translation and its cache, the solprop.output.metadata.RunMetadata that says what produced a file, and the resume decision.

Resume. Given a path, a run checks the file that is already there with solprop.output.hdf5.check_cache(): the digest covers the grid, the modes, the whole serialised configuration, the noise and the stepper settings, so a file written for a different run is refused by name rather than continued from someone else’s state. If it passes, the last plane comes back through solprop.output.hdf5.resume(), the backend is loaded at that plane’s position, and the run carries on into the same file with HDF5Output(path, append=True).

Layer D of docs/dev/architecture.md section 3: this module imports the physics, the translation, the backends and the output layer, and nothing imports it. The manual page is docs/guide/setup/running.md.

Classes

Simulation(grid, modes, responses, initial, ...)

A run that can be translated once and executed many times.

class solprop.driver.simulation.Simulation(grid, modes, responses, initial, *, settings, initial_z=0.0, noise=None, noise_resolution=None, profiles=None, configuration=None, spatial_grid=None, medium=None, frame=None, general=None, guide=None, wall=None, taper_coupling=True, materials=None)[source]#

Bases: Displayed

A run that can be translated once and executed many times.

Construct it from the physics objects and a SimulationSettings, or through from_gnlse() for a GNLSE fibre. translate() assembles the kernel problem and caches it, so a second run() – into another handler, or resuming a file – reuses it. settings may be replaced until that first translation; after it only its backend may change.

Parameters:

gridsolprop.grid.TimeGrid: The field or envelope grid.
modessolprop.modes.protocol.Mode or sequence of Mode: The mode, or the ordered set of a multimode problem.
responsescollections.abc.Sequence: The declared nonlinear responses, as solprop.translate.responses.compile_responses() takes them.
initialsolprop.pulses.Pulse or solprop.pulses.SpatialPulse or numpy.ndarray: The input: a solprop.pulses.Pulse – anything with a build(grid) method – or an already-built spectrum of shape (n_modes, n_pol, n_omega) in the square root of watts and the internal convention. A pulse is the better choice: it is a small specification, while a built array is recorded in the metadata as itself. An array is copied here, so that changing the caller’s array afterwards changes neither the run nor its record: once in complex128, which runs, and, for another dtype, once more as given, which is recorded; Simulation.initial is a read-only view of the copy as given. A broadcast view (numpy.broadcast_to()) copies only the block it repeats. On a free-space or spatial route the translated problem holds the same complex128 copy rather than another; on a modal route it holds the launch converted to its internal amplitude beside the simulation’s copy, two states in all.
settingsSimulationSettings: How to step it, what to record and which backend to use.
initial_zfloat, optional: Absolute position of an array input, m, default zero. Every requested save plane must follow it. An interior launch keeps the original profiles and propagation frame; it requires a modal array input, no noise and no fixed step schedule.
noisesolprop.noise.NoiseRealisation or None, optional: A shot-noise realisation to carry along the run (docs/guide/media/noise.md).
noise_resolutionsolprop.output.records.NoiseResolution or None, optional: How the noise model was chosen, as the constructors record it (SEP 37); None records the realisation as asked for explicitly.
profilescollections.abc.Mapping, optional: The z-profiles keyed by statistic name, for the density, pressure and core_radius statistics. Passed to the backend, which computes them.
configurationcollections.abc.Mapping, optional: Extra provenance to record beside what the simulation can see for itself, such as the coefficients a mapping came from.
spatial_gridRadialGrid, FreeGrid, PlanarGrid or None, optional: Transverse grid for spatial propagation; use an empty mode sequence (a solprop.modes.slab.PlanarGrid carries its own slab modes).
mediumsolprop.spatial.SpatialMedium or None, optional: Bulk material, required with a spatial grid.
framesolprop.linear.Frame or None, optional: Propagation frame. None uses the grid and responses’ normal default.
generalsolprop.translate.general.GeneralModalRoute or None, optional: The seam leaves of one general modal guide. Built by from_waveguide() from a provider=; with it the run takes the general modal route, whose responses are the guide’s material regions’ and whose declared responses must therefore be empty.
guidesolprop.modes.guide.ModalGuide or None, optional: The general modal guide general was built from, kept so that the run’s material manifest finds what its regions hold (their laws and delayed responses); it enters no translation. Set by from_waveguide().
wallsolprop.modes.capillary.CoherentWall or None, optional: The declaration of a coherent wall block. Built by from_capillary() from a wall=; with it the mode set must be the contiguous HE_11 to HE_1N block – or, with impedance="te_tm", one azimuthal order – on a constant or a varying guide, the cumulative operator carries the mode-independent carrier alone and the modal part of the flow becomes linear.coupled_flow, which numpy_ref and native execute.
taper_couplingbool, optional: Carry the taper coupling of a multimode capillary whose radius varies along z: the connection <psi_m|d_z psi_n> between the HE_1m channels, lossless or not, in a coupled flow beside each channel’s own propagation constant. True, the default; False is the explicit opt-out to the adiabatic route, on which each channel follows its local mode and no power is exchanged. No effect on a set the coupling does not apply to (solprop.modes.capillary.taper_coupling_block()); False beside a wall is refused, because the wall carries its connection.
materialssolprop.physdata.selection.MaterialSelection or None, optional: The material selection the run was built with, recorded in its material manifest with every optmat-backed object the run carries. The objects themselves are taken as they are: the from_* constructors resolve the built-in materials under the selection. None records none.

Raises:

DriverError: If initial is neither an array nor something with a build method.

Examples

>>> from solprop.driver import Simulation, SimulationSettings
>>> from solprop.grid import EnvelopeGrid
>>> from solprop.nonlinear.gnlse import problem_from
>>> from solprop.pulses import SechPulse
>>> from solprop.stepper import PIController
>>> grid = EnvelopeGrid.from_limits(0.01, 835e-9, (500e-9, 2e-6), 1.2e-12)
>>> gnlse = problem_from([0.0, 0.0, -1.183e-26], omega_ref=grid.omega0, gamma=0.11,
...                      shock=False)
>>> simulation = Simulation(
...     grid, gnlse.mode, [gnlse.kerr],
...     SechPulse(wavelength=835e-9, width=100e-15, peak_power=9.8),
...     settings=SimulationSettings(
...         controller=PIController(rtol=1e-6, atol=1e-16),
...         save_planes=[0.01], dz_max=0.01, dz_init=1e-3,
...         density=1.0, shock=False, prefactor_index=1.0,
...     ),
... )
>>> handler = simulation.run()
>>> handler.n_saved, simulation.translate().shape
(2, (1, 1, 1024))

calibrate(budget=60.0)[source]#

Refine the native backend’s settings for this simulation (SEP 46 stage 2).

Fresh native workspaces of this simulation’s translated problem are built in this process under candidate settings and timed by trial steps along its length; the settings that win, stay accurate and validate together are stored under its execution descriptor, and every later run or scan point of the same execution applies them. The simulation itself is not changed. Running solprop calibrate first gives the machine profile this refines (solprop.calibration).

Parameters:

budgetfloat, optional: The deadline, in seconds.

Returns:

solprop.calibration.refine.RefinementReport: What was kept and whether it was stored.

estimate()[source]#

Estimate what the run would cost, without running it (SEP 41, S11).

The grid, the persistent memory the constructed backend holds, the output’s size, the cost of one right-hand-side evaluation on the backend, timed after an untimed warm-up that takes compilation and planning, and the integrator’s calls per step (solprop.driver.estimate). It constructs the backend, so a run that doesn’t fit in memory fails here as the run would.

Returns:

solprop.driver.estimate.RunEstimate: The estimate.

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

Build a simulation of a pulse in a gas-filled hollow waveguide.

The constructor solprop.driver.interface.prop_capillary() calls. The mode set is the first modes HE_1m modes of the capillary unless a set is given; the transverse integral is a fixed quadrature rule (docs/guide/waveguides/mode-sets.md); the gas density along z is the pressure path through the equation of state, and the same path sets the modes’ core index, so a gradient fill disperses and broadens consistently.

See docs/guide/setup/running.md for the discussion and a worked example.

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.

Returns:

Simulation: The simulation, ready to translate and run.

Raises:

DriverError: If a keyword is missing, inconsistent, or names something this path does not carry.

Examples

>>> from solprop.driver import Simulation
>>> simulation = Simulation.from_capillary(
...     125e-6, 0.1, "He", (0.8, 0.1), wavelength=800e-9,
...     wavelength_limits=(150e-9, 2e-6), trange=200e-15,
...     fwhm=10e-15, energy=100e-6, modes=2, n_save=3,
... )
>>> len(simulation.modes), simulation.settings.quadrature.n_nodes
(2, 33)
>>> sorted(simulation.profiles)
['core_radius', 'density', 'pressure']

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

Build a free-space propagation of physical fields, radial or Cartesian.

The transverse grid chooses the transform: a solprop.grid.RadialGrid propagates a cylindrically symmetric beam with the scalar QDHT, a solprop.grid.FreeGrid a beam on Cartesian axes with transverse FFTs, and a solprop.grid.LineGrid the same transform with one y column: the beam is uniform in y, the run records transverse_measure = "per_unit_width", and its energies and powers are per metre of y.

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.

Returns:

Simulation: Cached translation and the ordinary resumable execution interface.

Raises:

DriverError: If a noise seed is given without noise, the input shape is invalid, or the density varies along z on a Cartesian or line grid.

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

Build a simulation of a GNLSE fibre from its coefficients.

The constructor solprop.driver.interface.prop_gnlse() calls, with these keywords and its run controls. The GNLSE is not a separate solver path: it is the mode-averaged envelope problem with a dispersion-specified mode, density = 1, prefactor_index = 1 and the shock term supplied by the prefactor’s omega dependence (docs/guide/waveguides/gnlse.md).

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.

Returns:

Simulation: Ready to run().

Raises:

DriverError: If the fibre, the grid, the input or the save planes are specified in a way this interface does not accept; the message names what is wrong.

Examples

>>> from solprop.driver import Simulation
>>> simulation = Simulation.from_gnlse(
...     0.11, 0.01, [0.0, 0.0, -1.183e-26], wavelength=835e-9,
...     wavelength_limits=(500e-9, 2e-6), trange=1e-12,
...     width=100e-15, peak_power=9.8, shape="sech", n_save=3,
... )
>>> simulation.settings.save_planes.tolist()
[0.005, 0.01]

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

Build a hybrid planar propagation: slab modes in x, an FFT in y.

The hollow planar guide resolved in both transverse directions: the slab modes of space in x and its periodic y axis, exact (non-paraxial) in y, so whole-beam self-focusing and the modulational instability in y – which a slab uniform in y cannot show – are in the model. The fill is the modes’ own, as a bulk medium; it and the gap must be constant along z. The geometry integrates over y, so energies are in J and powers in W. The collar in y absorbs only when settings declares an absorber, as for from_free().

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.

Returns:

Simulation: Cached translation and the ordinary resumable execution interface.

Raises:

DriverError: If the fill varies along z or is a mixture, the input is neither a solprop.pulses.PlanarPulse nor a spectrum of the planar shape.

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

Build a pulse simulation in a waveguide: a gas-filled mode set, or a guide.

Without `provider` this is the gas-filled route: modes keep their geometry, cladding and loss and receive the declared fill, their nonzero field components determine the transverse quadrature layout, and rectangular polarisation partners are separate rows with separate operators. A hollow planar set (SlabMode) is uniform in y and runs per unit width: energy is J/m, peak_power W/m, and the run records transverse_measure = "per_unit_width". Step-index fibres use prop_gnlse(fibre=...) instead.

With `provider` this is the general modal route (docs/guide/waveguides/general-modal.md): a guide that solves its own three-component E and H at quadrature nodes, whose material regions own their responses and whose channels are Poynting-normalised, so that a channel amplitude is a true-power amplitude by construction. It is qualified on numpy_ref and the native CPU backend, a declared split block’s coupled flow included, and propagates constant geometry on a field grid. Every gas keyword is refused by name beside a provider, because a guide’s materials are its regions’ and not a fill.

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().

Returns:

Simulation: A configured simulation, ready to translate or run.

Raises:

DriverError: If the modes cannot bind a gas mixture, a gas keyword is given beside a provider, a general-guide keyword is given without one, or any supplied setting is invalid.

input_port(z=None)[source]#

Return what this simulation can receive at its entrance (SEP 31).

The port is the receiving side of a transfer between simulations: its route, temporal lattice and basis with their identities, the entrance plane and the frame accumulated there, the native metric at the entrance, the reference index of its entrance medium, the coupling models it admits and what they need: an ordinary mode set’s scalar profiles, or a general guide’s E/H reference at its nodes and its regions’ contrast. A launch computed for it (solprop.coupling.coupler.couple()) is accepted by with_input(), and a launch computed for any other port is refused.

Parameters:

zfloat or None, optional: An interior entrance in m, for a modal run continued from inside its own path; None is the simulation’s launch position.

Returns:

solprop.coupling.InputPort: The port and the models it admits.

Raises:

DriverError: For a hybrid planar run, whose slab columns are not exchanged in this release, or an interior entrance outside the run.

material_manifest()[source]#

Collect the run’s material manifest: what it took from optmat, and how.

Every optmat-backed object the run carries is found where it sits – the mixture, the modes’ fills and claddings, a planar grid’s slab modes, a guide’s material regions, a bulk medium – with the selection the run was built with, the policies in force and what was measured about them: the dilute-scaling error over the run’s whole band, collars included, the loss a transparent solid dropped, and the bands outside a model’s qualified intervals that the run’s range warnings named. metadata() records it once; call it after translate() for a complete measurement. After run() it also carries the post-run diagnostic of each optmat ionisation rate (peak_fields), which the file’s record, written before the run, does not: the run writes it beside the record instead, as the output’s post-run annotation PEAK_FIELDS_ANNOTATION, outside the configuration hash.

Returns:

solprop.physdata.selection.MaterialManifest: The manifest; empty for a run that takes nothing from optmat.

Examples

>>> from solprop.driver import Simulation
>>> simulation = Simulation.from_gnlse(
...     0.11, 0.01, [0.0, 0.0, -1.183e-26], wavelength=835e-9,
...     wavelength_limits=(500e-9, 2e-6), trange=1e-12, raman=True,
...     width=100e-15, peak_power=9.8, shape="sech", n_save=3,
... )
>>> [record.name for record in simulation.material_manifest().records]
['kerr/SiO2', 'silica_raman/hollenbeck_2002', 'silica_bundle/default']

metadata()[source]#

Build the record of this run, once, and return it.

Cached because the record stamps the time it was created: two runs of the same simulation are the same run, and their files must carry the same digest.

Returns:

solprop.output.metadata.RunMetadata: What produced the run, and the key a resume is checked against.

Examples

>>> from solprop.driver import Simulation
>>> simulation = Simulation.from_gnlse(
...     0.11, 0.01, [0.0, 0.0, -1.183e-26], wavelength=835e-9,
...     wavelength_limits=(500e-9, 2e-6), trange=1e-12,
...     width=100e-15, peak_power=9.8, shape="sech", n_save=3,
... )
>>> metadata = simulation.metadata()
>>> metadata.simulation_kind, metadata.spectral_convention
('mode_averaged', 'optics')
>>> metadata.configuration_hash() == simulation.metadata().configuration_hash()
True

output_bytes()[source]#

Return the size of the run’s output, without constructing a backend.

The cheap part of estimate(), for asking as the setup changes: it times nothing and allocates no run state.

Returns:

int: Bytes, as an in-memory store holds them (an HDF5 file adds little).

Examples

>>> from solprop.recipe import Recipe
>>> simulation = Recipe.example("soliton").build()
>>> simulation.output_bytes() == simulation.estimate().output_bytes
True

run(output=None, *, progress=None, progress_period=10.0, resume=False, tdse_archive=None, snapshots=None, stop=None)[source]#

Execute the run and return the handler it was written to.

Parameters:

outputsolprop.output.store.Output or pathlib.Path or str or None, optional: Where the planes go: a handler, a path to write an HDF5 file at, or None for a solprop.output.memory.MemoryOutput. The handler is closed when the run ends, so a file handler is returned closed and is read back with solprop.output.hdf5.open_file(); a memory handler stays readable. A run with optmat ionisation rates then annotates it with their peak-field report (PEAK_FIELDS_ANNOTATION).
progressProgressReporter, {‘auto’, ‘bar’, ‘log’, ‘none’} or None, optional: Where progress goes; None takes the process default: a solprop.log.BarReporter on a terminal or in a notebook, a solprop.log.LogReporter otherwise (solprop.driver.run.run_problem()).
progress_periodfloat, optional: Seconds between the line reporter’s periodic lines, s; 0 leaves only the plane and closing lines. A bar has its own redraw period and a given reporter its own business.
resumebool or {‘interpolated’}, optional: Continue the file at output instead of replacing it, when its record and this run’s have one configuration hash (docs/guide/results/resuming.md, ADR-066); otherwise it is refused, naming the fields that differ. A finished file is returned. Only a path can be resumed: the driver has to open the file in append mode itself. Noise a constructor drew without a seed is drawn again from the seed the file recorded, so re-running the same call continues its file. A file whose last plane was interpolated inside a step is refused unless this is "interpolated": it then continues afresh from the interpolated field, and the position is recorded in the annotation INTERPOLATED_RESUMES_ANNOTATION.
tdse_archivesolprop.output.TDSEArchive or None, optional: Archive every raw TDSE provider evaluation of a run with a TDSE response in this separate HDF5 file (SEP 20 section 5.8); None archives nothing. It is opened and validated before any atomic work, a resume appends a new session to its own run’s archive, and the optical output records the archive’s run UUID and relative path. It changes neither the propagation nor the call ledger.
snapshotssolprop.output.SnapshotController or None, optional: Publish immutable local checkpoints without rebuilding the backend or atomic provider, each at the next accepted endpoint, after every interpolated plane its step crossed. Requires HDF5 and fields='all'. Adams history cannot be explicitly disabled. A configured archive is copied together with the optical file.
stopobject or None, optional: This run’s own stop flag: any object with an is_set() method, such as a threading.Event (SEP 41, S17). It is polled before the first step and before every trial step, so the run answers within one step or trial; on a native Multistep() march, whose trials run in native calls that cannot read it, before every call, so the run answers within 256 attempts or 0.1 s and the attempt in flight, whichever comes first. When it is set the run writes its state as for SIGTERM, tells the reporter through interrupted, and returns the handler: a requested stop is not an error. The outcome’s message says the caller’s flag stopped it, and resume=True continues the file. A front end sets it from any thread on any platform, without signals; each run polls its own.

Returns:

solprop.output.store.Output: The handler the run was written to, complete or, after stop was set, holding the state where it stopped.

Raises:

ValueError: If resume is not one of its three values.
DriverError: If a resume is asked for and output is not a path, or the file’s last plane was interpolated and resume is not "interpolated"; or tdse_archive is given without a TDSE response or at the path of the optical file.
TDSEArchiveError: If the archive’s path holds another file, or a write to it fails; the run then stops at its last optical checkpoint.
OutputError: If a file is there and its configuration hash differs; the message names what changed.

Examples

>>> from solprop.driver import Simulation
>>> simulation = Simulation.from_gnlse(
...     0.11, 0.01, [0.0, 0.0, -1.183e-26], wavelength=835e-9,
...     wavelength_limits=(500e-9, 2e-6), trange=1.2e-12,
...     width=100e-15, peak_power=9.8, shape="sech", n_save=3, rtol=1e-6,
... )
>>> handler = simulation.run()
>>> handler.n_saved, handler["z"].tolist()
(3, [0.0, 0.005, 0.01])

runner()[source]#

Return a runner that keeps this translation and one backend for many inputs.

Translates (or reuses the cached translation) and constructs the backend once; each run() then runs one input on it (SEP 22 section 5.2). Close it, or use it in a with block.

Returns:

SimulationRunner: The open runner.

Raises:

DriverError: If the run has a TDSE response.

property settings: SimulationSettings[source]#

How the run steps, records and executes; fixed once translated.

Assigning a new SimulationSettings before the first translate() (or run()) takes effect. After it the translated problem is cached, so an assignment that changes anything the translation consumed is refused, because it could no longer change the run; the backend and tdse_execution resources, which are read when the run executes, may still change.

The settings the run is, or will be, translated with.

translate()[source]#

Assemble the kernel problem, once, and return it.

Everything expensive about a run that does not depend on the state happens here (docs/dev/architecture.md section 7): the cumulative linear operator, the masks, the modal transform and the compiled responses. The result is cached, so two runs of the same simulation translate once.

Returns:

solprop.translate.problem.PropagationProblem: Validated, versioned and ready for a backend.

Examples

>>> from solprop.driver import Simulation
>>> simulation = Simulation.from_gnlse(
...     0.11, 0.01, [0.0, 0.0, -1.183e-26], wavelength=835e-9,
...     wavelength_limits=(500e-9, 2e-6), trange=1e-12,
...     width=100e-15, peak_power=9.8, shape="sech", n_save=3,
... )
>>> problem = simulation.translate()
>>> problem.shape, simulation.translate() is problem
((1, 1, 768), True)

with_input(initial, *, noise='keep', initial_z=None, configuration=None, input_identity=None)[source]#

Replace the input while sharing the translated propagation problem.

Only what changed is validated (SEP 22 section 5.2): the replaced input’s shape, dtype and one finiteness pass, and the replaced noise’s, with every other leaf of the translated problem shared by identity rather than scanned again. A new initial_z, which changes the save planes, also keeps the stepper’s checks: the launch before the first plane, and a replayed schedule containing every plane. An array input above INLINE_ARRAY_LIMIT elements is recorded by its digest (ArrayDigest), not inline, unless its identity is stated (input_identity).

Parameters:

initialPulse, SpatialPulse, numpy.ndarray or solprop.coupling.CouplingLaunch: Pulse or internal-convention spectrum on the existing grid. The built shape must match the original input, including modes and polarisation. Modal amplitudes are in sqrt(W); spatial units follow the spatial grid. An array is copied when the derived simulation is built, as by the constructor. A CouplingLaunch (SEP 31) must be bound to this simulation’s input_port() – its route, lattice, basis, entrance and metric – or it is refused whatever its shape; its entrance sets the launch position, and its provenance and inherited reference origin are recorded as configuration["coupling"].
noiseNoiseRealisation, {‘keep’} or None, optional: Keep the existing noise, replace it explicitly, or disable it with None. Noise spectra must match the existing grid and input shape. A launch carries the realised field of its source, so for a launch 'keep' means no noise: no second floor is drawn unless a realisation is given. Kept noise that was drawn without a seed can still be drawn again from the seed a resume’s file or a scan point supplies.
initial_zfloat or None, optional: Absolute launch position in metres. None retains this simulation’s launch. An explicit position keeps only existing save planes beyond it, preserving all absolute profiles, propagation tables and the frame.
configurationcollections.abc.Mapping or None, optional: Caller keys merged into the derived run’s configuration record, and so into its configuration hash: the delay of a scan, the label of an input. A key the run already records is refused.
input_identitystr or None, optional: What an array input is, stated by the caller who already knows: the record then holds this string, the dtype and the shape (StatedInput) in place of the array’s own record, and its bytes are not digested. It is not checked: two different arrays stated alike have one configuration hash, so a resume or a scan’s cache accepts one for the other. None, the default, records the array as itself or by its digest. Refused for anything but an array.

Returns:

Simulation: Translated simulation sharing all propagation tables. Metadata is rebuilt for the replacement input and noise. Existing ionisation table ranges remain in force, and so does the reference field of an optmat rate’s constant energy per event, which is the original input’s peak; use a fresh translation to change them.

Raises:

DriverError: If the new field or noise shape differs or any sample is not finite, a configuration key is one the run records itself, a launch is bound to another port or given beside an initial_z, or input_identity is empty or names anything but an array input.

Warns:

MaterialRangeWarning: Once per run, when the new input’s peak exceeds an optmat rate’s maximum field, or the input is not linearly polarised at a Keldysh parameter above one there (SEP 3, D12).

with_mixture(mixture)[source]#

Update material paths while preserving the run’s geometry and input.

Rate tables and unchanged undamped Raman kernels are shared by identity. Expansion terms are reused only for the identical sampled function with covered parameter ranges; changing fill fractions invalidates a pressure expansion. Every replacement weight and density or decay table is rebuilt.

Parameters:

mixtureMixture: New paths and populations with the same ordered labels and species data. Public capillary response selections are retained; changed temperature or Raman component options rebuild the affected molecular models.

Returns:

Simulation: A translated simulation sharing the grid, input field, noise realisation, numerical settings and transverse geometry with this one. Noise drawn without a seed can still be drawn again from the seed a resume’s file or a scan point supplies; on a spatial route, where the draw is measured by the medium’s flux, it is drawn again now from the same seed on the new medium. A realisation the caller seeded or supplied is shared unchanged.

Raises:

DriverError: If there is no mixture declaration, or labels, species or unsupported mode geometries differ.