solprop.tools.design#

Design solvers: the parameter of a guide or fill that meets a design target.

solve_parameter() brackets every root of a target’s residual over a parameter; radius_zdw(), pressure_zdw() and pressure_rdw() are its capillary forms.

Module Attributes

`DesignTarget`	A target of `solve_parameter()`.
`RootChoice`	Which of several roots: the lowest, the highest, or an index into them.
`DesignBuild`	A builder: a trial value of the parameter to a mode, or to a mode and the fill's nonlinear coefficient in rad/(W m) (`nonlinear_coefficient()`).

Functions

`pressure_rdw`(radius, gas, target_wavelength, ...)	Return the pressure that phase matches a dispersive wave at a target wavelength.
`pressure_zdw`(radius, gas, zdw_wavelength, *)	Return the pressure that puts the zero-dispersion point at a wavelength.
`radius_zdw`(gas, pressure, zdw_wavelength, *)	Return the core radius that puts a capillary's zero dispersion at a wavelength.
`solve_parameter`(build, search, target, *[, z])	Return every value of a guide or fill parameter that meets a design target.

Classes

`DesignRoots`(roots, search, target, builds, ...)	Every root of a design target over a parameter's search range.
`RDW`(pump, rdw[, peak_power, fwhm, shape, ...])	Target a resonant dispersive wave phase matched at a wavelength.
`SolitonOrder`(order, pulse)	Target a conventional soliton order for a fixed pulse.
`ZDW`(wavelength)	Target a zero-dispersion wavelength: \(\beta_2 = 0\) at a wavelength.

solprop.tools.design.DesignBuild#

A builder: a trial value of the parameter to a mode, or to a mode and the fill’s nonlinear coefficient in rad/(W m) (nonlinear_coefficient()).

alias of Callable[[float], Mode | tuple[Mode, float]]

class solprop.tools.design.DesignRoots(roots, search, target, builds, quantity, attainable=None)[source]#

Bases: object

Every root of a design target over a parameter’s search range.

Iterating gives the roots, and its length is their number.

Attributes:

rootstuple of float: The values of the parameter that meet the target, ascending, in the parameter’s unit; empty when none does.
searchtuple of float: The search range, (low, high).
targetZDW, RDW or SolitonOrder: The target.
buildsint: How many times the builder was called, the search’s cost.
quantitystr: What attainable measures, with its unit: the zero-dispersion wavelength nearest the target’s (m), the phase-matched wavelength nearest the target’s (m), or the soliton order.
attainabletuple of float or None: When there is no root, the smallest and largest quantity on a coarser grid of the search range (17 linear and, where low > 0, 17 logarithmic values, the ends included), where it is defined: a mode with no zero dispersion in 100 nm to 3 um, or with no phase-matched wavelength in the RDW window or no soliton, has none. None when there are roots, or no value defines it.

Examples

>>> from solprop.tools import DesignRoots, ZDW
>>> roots = DesignRoots((1.0, 2.0), (0.5, 3.0), ZDW(5e-7), 260,
...                     "zero-dispersion wavelength in m")
>>> len(roots), roots.pick("highest"), roots.pick(0)
(2, 2.0, 1.0)

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

builds: int#

pick(root='lowest')[source]#

Return one root.

Parameters:

root{‘lowest’, ‘highest’} or int, optional: The lowest or highest root, or an index into the ascending roots (negative from the end, as a sequence’s).

Returns:

float: The root, in the parameter’s unit.

Raises:

ToolsError: If there is no root, naming the attainable range, or the index is out of range, naming the roots.

Examples

>>> from solprop.tools import DesignRoots, ZDW
>>> DesignRoots((1.0, 2.0), (0.5, 3.0), ZDW(5e-7), 260, "").pick(-1)
2.0

quantity: str#

roots: tuple[float, ...]#

search: tuple[float, float]#

target: ZDW | RDW | SolitonOrder#

solprop.tools.design.DesignTarget = solprop.tools.design.ZDW | solprop.tools.design.RDW | solprop.tools.design.SolitonOrder#: A target of solve_parameter().

class solprop.tools.design.RDW(pump, rdw, peak_power=None, fwhm=None, shape='sech', nonlinear_phase='largest')[source]#

Bases: object

Target a resonant dispersive wave phase matched at a wavelength.

The residual solve_parameter() brackets is phase_mismatch() of the trial mode at rdw, in 1/m, exactly as pressure_rdw() evaluates it: with peak_power the soliton’s nonlinear wavenumber is included, with the trial mode’s own nonlinear coefficient, and with the largest constituent (fwhm given) a trial value in normal dispersion or below the first soliton threshold has no residual and cannot bracket a root.

Attributes:

pumpfloat: Wavelength of the soliton, m, > 0.
rdwfloat: Wavelength the dispersive wave should have, m, > 0 and not the pump’s.
peak_powerfloat or None: Input peak power in W for the nonlinear term; None is the linear condition. With it, the builder returns (mode, gamma).
fwhmfloat or None: Input power FWHM in s; required with peak_power for the default phase.
shape{‘sech’, ‘gauss’}: Unchirped input shape for the largest constituent.
nonlinear_phase{‘largest’, ‘supplied_power’, ‘linear’}: The nonlinear phase model, as phase_mismatch() takes it.

Raises:

ToolsError: If a wavelength is not positive, the two are equal, or the pulse numbers are incomplete or contradictory for the phase model.

Examples

>>> from solprop.tools import RDW
>>> RDW(800e-9, 200e-9, peak_power=2e9, fwhm=10e-15).nonlinear_phase
'largest'

fwhm: float | None = None#

nonlinear_phase: Literal['largest', 'supplied_power', 'linear'] = 'largest'#

peak_power: float | None = None#

pump: float#

rdw: float#

shape: Literal['sech', 'gauss'] = 'sech'#

solprop.tools.design.RootChoice = typing.Literal['lowest', 'highest'] | int#: Which of several roots: the lowest, the highest, or an index into them.

class solprop.tools.design.SolitonOrder(order, pulse)[source]#

Bases: object

Target a conventional soliton order for a fixed pulse.

The residual solve_parameter() brackets is soliton_order() of the pulse in the trial mode, with the trial mode’s own nonlinear coefficient, minus order: a guide or fill parameter is solved for, the pulse is held. The order is the conventional measure on either side of a zero-dispersion point, so a search across one may find a root on each side. The opposite question, the pulse that has an order on a given mode, is closed form: soliton_peak_power() and pulse_energy().

Attributes:

orderfloat: Conventional soliton order, > 0.
pulseGaussianPulse or SechPulse: The pulse: its wavelength is the pump, its FWHM and its energy or peak power are held, and its class sets the shape. An ordinary Gaussian (m = 1) with no spectral phase beyond a carrier-envelope phase and a delay.

Raises:

ToolsError: If the order is not positive, the Gaussian is super-Gaussian, or the pulse is chirped.

Examples

>>> from solprop.pulses import SechPulse
>>> from solprop.tools import SolitonOrder
>>> target = SolitonOrder(3.0, SechPulse(wavelength=800e-9, fwhm=10e-15,
...                                      energy=100e-6))
>>> f"{target.peak_power / 1e9:.3f} GW"
'8.814 GW'

property fwhm: float[source]#

The pulse’s full width at half maximum of the power, s.

A SechPulse given its natural width converts it.

order: float#

property peak_power: float[source]#

The pulse’s peak power, W.

The pulse’s own, or that of its energy (pulse_peak_power()).

pulse: GaussianPulse | SechPulse#

property shape: Literal['sech', 'gauss'][source]#

Pulse shape the design numbers use.

"gauss" for a GaussianPulse, "sech" for a SechPulse.

class solprop.tools.design.ZDW(wavelength)[source]#

Bases: object

Target a zero-dispersion wavelength: \(\beta_2 = 0\) at a wavelength.

The residual solve_parameter() brackets is \(\beta_2\) of the trial mode at wavelength, in s^2/m.

Attributes:

wavelengthfloat: Wavelength at which the dispersion should vanish, m, > 0.

Raises:

ToolsError: If the wavelength is not finite and positive.

Examples

>>> from solprop.tools import ZDW
>>> ZDW(500e-9)
ZDW(wavelength=5e-07)

wavelength: float#

solprop.tools.design.pressure_rdw(radius, gas, target_wavelength, wavelength, *, pressure_max=100.0, peak_power=None, fwhm=None, shape='sech', nonlinear_phase='largest', lattice=None, pressure_limits=None, temperature=293.15, m=1, model='full', cladding=None, materials=None)[source]#

Return the pressure that phase matches a dispersive wave at a target wavelength.

Parameters:

radiusfloat: Core radius in m, > 0.
gasGas or str: A single built-in gas.
target_wavelengthfloat: Wavelength the dispersive wave should have, m.
wavelengthfloat: Pump wavelength in m.
pressure_maxfloat, optional: Upper end of the pressure bracket in bar; the lower end is 1e-6 bar.
peak_powerfloat or None, optional: Peak power in W. When given, the soliton’s nonlinear wavenumber is included and its nonlinear coefficient follows the pressure.
fwhmfloat or None, optional: Positive input power FWHM in s, required with power for the default phase.
shape{‘sech’, ‘gauss’}, optional: Unchirped input shape.
nonlinear_phase{‘largest’, ‘supplied_power’, ‘linear’}, optional: Largest constituent by default; supplied power preserves gamma P0/2 without fwhm. Linear requires omitting pulse numbers.
latticeTubeLattice or None, optional: Tube geometry for VincettiMode; None builds a Marcatili capillary.
pressure_limitstuple of float or None, optional: Positive ordered search range in bar, within (1e-6, pressure_max). None uses that whole range. Searches 129 logarithmic and 129 linear samples, refining admissible sign changes; sub-grid root pairs or valid intervals can be missed. Narrow the range to resolve them.
temperaturefloat, optional: Fill temperature in K.
mint, optional: Radial index of the HE_1m mode.
model{‘full’, ‘reduced’}, optional: Marcatili model.
claddingGlassIndex, complex or None, optional: Cladding index; None is fused silica.
materialsMaterialSelection or None, optional: Design the capillary prop_capillary builds under the same materials=: the gas from optmat (index, density, and the Kerr coefficient at wavelength for the nonlinear phase) and cladding=None as optmat’s recommended fused silica. None is MaterialSelection().

Returns:

float: Pressure in bar.

Raises:

ToolsError: If no pressure in the bracket matches, or the selection names a carrier other than wavelength.

Examples

>>> from solprop.tools import pressure_rdw
>>> f"{pressure_rdw(125e-6, 'He', 199.75e-9, 800e-9, cladding=1.45):.2f}"
'1.00'

solprop.tools.design.pressure_zdw(radius, gas, zdw_wavelength, *, pressure_max=100.0, temperature=293.15, m=1, model='full', cladding=None, materials=None)[source]#

Return the pressure that puts the zero-dispersion point at a wavelength.

Parameters:

radiusfloat: Core radius in m, > 0.
gasGas or str: A single built-in gas.
zdw_wavelengthfloat: Wavelength at which the dispersion should vanish, m.
pressure_maxfloat, optional: Upper end of the pressure bracket in bar; the lower end is 1e-6 bar.
temperaturefloat, optional: Fill temperature in K.
mint, optional: Radial index of the HE_1m mode.
model{‘full’, ‘reduced’}, optional: Marcatili model.
claddingGlassIndex, complex or None, optional: Cladding index; None is fused silica.
materialsMaterialSelection or None, optional: Design the capillary prop_capillary builds under the same materials=: the gas’s index and density from optmat and cladding=None as optmat’s recommended fused silica. None is MaterialSelection().

Returns:

float: Pressure in bar.

Raises:

ToolsError: If no pressure in the bracket does.

Examples

>>> from solprop.tools import pressure_zdw
>>> f"{pressure_zdw(125e-6, 'Ar', 500e-9, cladding=1.45):.3f}"
'0.066'

solprop.tools.design.radius_zdw(gas, pressure, zdw_wavelength, *, radius_limits=(5e-06, 0.001), temperature=293.15, m=1, model='full', cladding=None, materials=None, root='lowest')[source]#

Return the core radius that puts a capillary’s zero dispersion at a wavelength.

The radius counterpart of pressure_zdw(), through solve_parameter(): the capillary is built once at pressure and re-evaluated at each trial radius.

Parameters:

gasGas or str: A single built-in gas.
pressurefloat: Fill pressure in bar, > 0.
zdw_wavelengthfloat: Wavelength at which the dispersion should vanish, m.
radius_limitstuple of float, optional: Positive ordered search range of the core radius, m.
temperaturefloat, optional: Fill temperature in K.
mint, optional: Radial index of the HE_1m mode.
model{‘full’, ‘reduced’}, optional: Marcatili model.
claddingGlassIndex, complex or None, optional: Cladding index; None is fused silica.
materialsMaterialSelection or None, optional: Design the capillary prop_capillary builds under the same materials=, as pressure_zdw() does. None is MaterialSelection().
root{‘lowest’, ‘highest’} or int, optional: Which root, should there be several (DesignRoots.pick).

Returns:

float: Core radius in m.

Raises:

ToolsError: If the radius limits are not positive and ordered, the pressure is not positive, or no radius in the range gives the zero (naming the range of zero-dispersion wavelengths it does give).

Examples

>>> from solprop.tools import radius_zdw
>>> f"{radius_zdw('He', 1.0, 400e-9, cladding=1.45) * 1e6:.2f} um"
'89.49 um'

solprop.tools.design.solve_parameter(build, search, target, *, z=0.0)[source]#

Return every value of a guide or fill parameter that meets a design target.

The general form of pressure_zdw(), pressure_rdw() and radius_zdw(), for any mode and any parameter: a radius, a pressure, a core size or a wall thickness. The target’s residual is sampled over search on 129 linear values and, where low > 0, 129 logarithmic ones (as pressure_rdw() samples pressure); each sign change between two samples is refined with Brent’s method to a relative tolerance of 2e-12; and a refined change is kept as a root only where the residual has fallen to a thousandth of its value at the bracket’s ends, which discards a change through a pole (a wall resonance, where it diverges instead). Roots closer together than one sample are not separated: narrow search to resolve them.

Parameters:

buildcallable: build(value) returns the mode at a trial value of the parameter, or (mode, gamma) with the fill’s nonlinear coefficient in rad/(W m) (nonlinear_coefficient()), which an RDW target with a peak power and a soliton-order target need: a mode need not know its fill’s Kerr response.
searchtuple of float: Finite ordered range of the parameter, (low, high), in its unit.
targetZDW, RDW or SolitonOrder: What the parameter should achieve.
zfloat, optional: Position along the waveguide at which each mode is evaluated, m: the launch position.

Returns:

DesignRoots: Every root, ascending, with the attainable range of the target’s quantity when there is none; .pick(root) chooses one.

Raises:

ToolsError: If the range or position is not finite or not ordered, the builder returns something other than a mode (and a coefficient where one is needed), a residual is not finite, or a refinement crosses a no-soliton region.

Examples

The radius of a helium capillary at 1 bar with its zero dispersion at 400 nm, re-evaluating one mode at each trial radius:

>>> from solprop.modes import MarcatiliMode
>>> from solprop.tools import ZDW, solve_parameter
>>> mode = MarcatiliMode(125e-6, "He", 1.0, cladding=1.45)
>>> roots = solve_parameter(
...     lambda radius: mode.at_parameters({"core_radius": radius}),
...     (20e-6, 500e-6),
...     ZDW(400e-9),
... )
>>> [f"{radius * 1e6:.2f} um" for radius in roots]
['89.49 um']