solprop.tools#

Design calculators: soliton numbers and dispersive-wave phase matching.

The numbers a person works out before a run. For a pulse of energy \(E\) and full width at half maximum \(\tau_{\rm fwhm}\) in a mode with group-velocity dispersion \(\beta_2\), effective area \(A_{\rm eff}\) and a fill of nonlinear index \(n_2\),

\[\gamma = \frac{n_2\omega_0}{cA_{\rm eff}},\quad L_D = \frac{\tau_0^2}{|\beta_2|},\quad L_{NL} = \frac{1}{\gamma P_0},\quad N = \sqrt{L_D/L_{NL}},\quad L_{\rm fiss} = L_D/N,\]

with the natural width \(\tau_0\) and the peak power \(P_0\) of the chosen pulse shape (pulse_width(), pulse_peak_power()). One shape runs through the whole chain, so the Gaussian numbers are never computed with a sech width.

A dispersive wave is phase matched to a soliton at the frequencies where

\[\Delta\beta(\omega) = \beta_{\rm dw}(\omega) - \beta_{\rm s}(\omega_0) - \beta_{1,\rm s}(\omega_0)(\omega-\omega_0) - k_{\rm NL}\]

vanishes (phase_mismatch()). The last term is the soliton’s nonlinear wavenumber and uses the largest unchirped constituent when pulse data are given (soliton_content()). Without pulse data the condition is linear. docs/guide/workflows/design-tools.md derives both and says what the nonlinear term assumes.

Everything is SI except pressure, which is in bar as at the rest of the user interface (docs/dev/conventions.md section 1).

Module Attributes

`PulseShape`	The two pulse shapes the design numbers are defined for.
`NonlinearPhase`	Choose the constituent, supplied-power or linear RDW phase model.
`Fill`	A fill as the run interfaces accept it: a species, mole fractions or a mixture.

Functions

`capillary_design`(radius, gas, *, ...[, ...])	Return the pressure and energy that give a capillary a soliton design.
`capillary_params`(radius, gas[, pressure, ...])	Return the design numbers of a pulse in a gas-filled capillary.
`dispersion_length`(fwhm, beta2[, shape])	Return the dispersion length \(L_D = \tau_0^2/\|\beta_2\|\).
`field_to_intensity`(field)	Return the intensity of a field amplitude, \(I = \epsilon_0 c E^2/2\).
`fission_length`(peak_power, fwhm, gamma, beta2)	Return the soliton fission length \(L_{\rm fiss} = L_D/N\).
`gas_ratio`(gas_a, gas_b, wavelength, *[, ...])	Return the ratios of bulk dispersion and Kerr response of two gases.
`intensity_to_field`(intensity)	Return the field amplitude of an intensity, \(E = \sqrt{2I/\epsilon_0 c}\).
`lambda_rdw`(mode, wavelength, *[, ...])	Return the phase-matched dispersive-wave wavelength nearest the pump.
`lambda_rdw_all`(mode, wavelength, *[, ...])	Return every phase-matched wavelength in a window, shortest first.
`nonlinear_coefficient`(mode, n2, wavelength)	Return the nonlinear coefficient \(\gamma = n_2\omega/(cA_{\rm eff})\).
`nonlinear_length`(peak_power, gamma)	Return the nonlinear length \(L_{NL} = 1/(\gamma P_0)\).
`phase_mismatch`(mode, omega, wavelength, *[, ...])	Return the phase mismatch between a soliton and a dispersive wave.
`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.
`pulse_peak_power`(energy, fwhm[, shape])	Return the peak power of a pulse of given energy, duration and shape.
`pulse_width`(fwhm[, shape])	Return the natural width of a pulse from its full width at half maximum.
`self_focusing_power`(wavelength, index, n2)	Return the critical power for self-focusing, as physical power.
`soliton_content`(peak_power, fwhm, gamma, beta2)	Calculate the soliton count and largest constituent of an unchirped pulse.
`soliton_order`(peak_power, fwhm, gamma, beta2)	Return the soliton order \(N = \sqrt{L_D/L_{NL}}\).
`soliton_params`(mode, gas[, pressure, shape, ...])	Return the design numbers of a pulse in any mode.

Classes

`GasRatio`(beta2, chi3)	Ratios of the bulk dispersion and the Kerr response of two gases.
`SolitonContent`(area_order, count, ...)	Describe the discrete soliton content of an unchirped single-lobe pulse.
`SolitonParams`(energy, fwhm, width, omega, ...)	The design numbers of one pulse in one mode and one fill.

solprop.tools.Fill = solprop.physdata.gases.Gas | str | collections.abc.Mapping[str, float] | solprop.physdata.mixtures.Mixture#: A fill as the run interfaces accept it: a species, mole fractions or a mixture.

class solprop.tools.GasRatio(beta2, chi3)[source]#

Bases: object

Ratios of the bulk dispersion and the Kerr response of two gases.

Attributes:

beta2float: Ratio of the bulk group-velocity dispersions, first gas over second.
chi3float: Ratio of the third-order susceptibilities, first gas over second.

beta2: float#

chi3: float#

solprop.tools.NonlinearPhase#

Choose the constituent, supplied-power or linear RDW phase model.

alias of Literal[‘largest’, ‘supplied_power’, ‘linear’]

solprop.tools.PulseShape#

The two pulse shapes the design numbers are defined for.

alias of Literal[‘sech’, ‘gauss’]

class solprop.tools.SolitonContent(area_order, count, largest_eigenvalue, largest_peak_power, largest_width, largest_nonlinear_wavenumber)[source]#

Bases: object

Describe the discrete soliton content of an unchirped single-lobe pulse.

Attributes:

area_orderfloat: Dimensionless field area divided by pi, not the conventional soliton order.
countint: Number of strictly positive discrete eigenvalues; zero at first threshold.
largest_eigenvaluefloat or None: Imaginary part of the largest Zakharov-Shabat eigenvalue, dimensionless with time scaled by the input shape’s natural width. None if count is zero.
largest_peak_powerfloat or None: Peak power of the largest constituent in W, or None if count is zero.
largest_widthfloat or None: Natural sech width of that constituent in s, or None if count is zero.
largest_nonlinear_wavenumberfloat or None: Positive optics-convention phase rate in 1/m, or None if count is zero.

area_order: float#

count: int#

largest_eigenvalue: float | None#

largest_nonlinear_wavenumber: float | None#

largest_peak_power: float | None#

largest_width: float | None#

class solprop.tools.SolitonParams(energy, fwhm, width, omega, wavelength, gas, pressure, temperature, shape, peak_power, beta2, density, index, n2, gamma, soliton_order, soliton_content, intensity, peak_intensity, critical_power, dispersion_length, nonlinear_length, fission_length, zdw, loss_length, effective_area, mode)[source]#

Bases: Displayed

The design numbers of one pulse in one mode and one fill.

Attributes:

energyfloat: Pulse energy in J.
fwhmfloat: Full width at half maximum of the power in s.
widthfloat: Natural width tau0 of the shape in s (pulse_width()).
omegafloat: Angular frequency of the pump in rad/s.
wavelengthfloat: Vacuum wavelength of the pump in m.
gasstr: The fill’s species labels, joined by +.
pressurefloat: Total pressure at the position in bar; NaN for a mixture of independent populations, which has no single pressure.
temperaturefloat: Fill temperature in K.
shape{‘sech’, ‘gauss’}: "sech" or "gauss".
peak_powerfloat: Peak power in W.
beta2float: Group-velocity dispersion of the mode at the pump in s^2/m.
densityfloat: Total number density of the fill in m^-3.
indexfloat: Linear refractive index of the fill at the pump.
n2float: Nonlinear index of the fill in m^2/W.
gammafloat: Nonlinear coefficient in rad/(W m).
soliton_orderfloat: sqrt(L_D / L_NL).
soliton_contentSolitonContent or None: Unchirped NLSE constituent count and largest soliton; None for normal GVD.
intensityfloat: Mode-averaged intensity peak_power / effective_area in W/m^2.
peak_intensityfloat: On-axis intensity of the mode at the peak power in W/m^2: what a run’s peak_intensity statistic reports at its first plane. For the fundamental of a capillary it is 1.77 times intensity. NaN for a mode without a transverse profile (a dispersion-specified one).
critical_powerfloat: Self-focusing power in W (self_focusing_power()).
dispersion_lengthfloat: In m.
nonlinear_lengthfloat: In m.
fission_lengthfloat: In m.
zdwfloat: Zero-dispersion wavelength in m within 100 nm to 3 um, or NaN when the dispersion does not change sign there. No second, guess-seeded search is tried.
loss_lengthfloat: The 1/e power loss length of the mode at the pump in m.
effective_areafloat: In m^2.
modeMode: The mode.

beta2: float#

critical_power: float#

density: float#

dispersion_length: float#

effective_area: float#

energy: float#

fission_length: float#

fwhm: float#

gamma: float#

gas: str#

index: float#

intensity: float#

loss_length: float#

mode: Mode#

n2: float#

nonlinear_length: float#

omega: float#

peak_intensity: float#

peak_power: float#

pressure: float#

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

soliton_content: SolitonContent | None#

soliton_order: float#

temperature: float#

wavelength: float#

width: float#

zdw: float#

solprop.tools.capillary_design(radius, gas, *, zdw_wavelength, fwhm, wavelength, soliton_order=None, soliton_count=None, largest_eigenvalue=None, shape='sech', temperature=293.15, m=1, model='full', loss=True, cladding=None, materials=None, pressure_max=100.0)[source]#

Return the pressure and energy that give a capillary a soliton design.

The inverse of capillary_params(): the pressure puts the zero-dispersion point at zdw_wavelength (pressure_zdw()), and the energy then gives the pulse one soliton target. At that pressure \(\beta_2\) and \(\gamma\) do not depend on the energy and \(N^2 = \gamma P_0\tau_0^2/|\beta_2|\), so the peak power is \(P_0 = N^2|\beta_2|/(\gamma\tau_0^2)\). Give exactly one target:

soliton_order, the conventional \(N\);
soliton_count, a number \(M\) of solitons in the scattering content (soliton_content()): the pulse area is set to \(M\pi\), the middle of the band of areas with \(M\) solitons, which is \(N = M\) for sech and \(N = M\sqrt{\pi/2}\) for a Gaussian;
largest_eigenvalue, the \(\eta\) of the largest constituent, which fixes its width \(\tau_0/(2\eta)\): \(N = \eta + 1/2\) for sech, and a root of the Gaussian scattering problem otherwise.

Parameters:

radiusfloat: Core radius in m, > 0.
gasGas or str: A single built-in gas, as pressure_zdw() takes it.
zdw_wavelengthfloat: Wavelength at which the dispersion should vanish, m.
fwhmfloat: Full width at half maximum of the power in s, > 0.
wavelengthfloat: Pump wavelength in m, > 0.
soliton_orderfloat or None, optional: Target conventional soliton order, > 0.
soliton_countint or None, optional: Target number of solitons, >= 1.
largest_eigenvaluefloat or None, optional: Target imaginary part of the largest Zakharov-Shabat eigenvalue, dimensionless with time in units of the shape’s natural width, > 0.
shape{‘sech’, ‘gauss’}, optional: The pulse shape, used for the width, the peak power and the content.
temperaturefloat, optional: Fill temperature in K.
mint, optional: Radial index of the HE_1m mode.
model{‘full’, ‘reduced’}, optional: Marcatili model.
lossbool, float or callable, optional: Loss policy of the mode in the returned numbers.
claddingGlassIndex, complex or None, optional: Cladding index; None is fused silica.
materialsMaterialSelection or None, optional: Design under this selection, as capillary_params() and pressure_zdw() do. None is MaterialSelection().
pressure_maxfloat, optional: Upper end of the pressure bracket in bar.

Returns:

SolitonParams: The numbers at the designed pressure and energy, with the mode; the pressure is .pressure (bar) and the energy .energy (J).

Raises:

ToolsError: If not exactly one target is given or it is out of range, no pressure in the bracket gives the zero-dispersion point, or a content target is asked of a pump in normal dispersion.

Examples

>>> from solprop.tools import capillary_design
>>> p = capillary_design(125e-6, "Ar", zdw_wavelength=500e-9, fwhm=10e-15,
...                      wavelength=800e-9, soliton_order=3.0, cladding=1.45)
>>> f"{p.pressure:.4f} bar {p.energy * 1e6:.1f} uJ N = {p.soliton_order:.3f}"
'0.0664 bar 100.5 uJ N = 3.000'
>>> g = capillary_design(125e-6, "Ar", zdw_wavelength=500e-9, fwhm=10e-15,
...                      wavelength=800e-9, soliton_count=2, shape="gauss",
...                      cladding=1.45)
>>> f"{g.soliton_order:.4f} {g.soliton_content.count}"
'2.5066 2'

solprop.tools.capillary_params(radius, gas, pressure=None, *, energy, fwhm, wavelength, shape='sech', temperature=None, n=1, m=1, kind='HE', model='full', loss=True, cladding=None, materials=None)[source]#

Return the design numbers of a pulse in a gas-filled capillary.

Builds the mode as solprop.driver.interface.prop_capillary() does for the same arguments – a MarcatiliMode over the fill’s mixture – and hands it to soliton_params().

Parameters:

radiusfloat: Core radius in m, > 0.
gasGas, str, Mapping or Mixture: The fill, as prop_capillary takes it.
pressurefloat or None, optional: Total pressure in bar; None is one bar. For a gradient, evaluate at the pressure of the position of interest.
energyfloat: Pulse energy in J, > 0.
fwhmfloat: Full width at half maximum of the power in s, > 0.
wavelengthfloat: Pump wavelength in m, > 0.
shape{‘sech’, ‘gauss’}, optional: The pulse shape.
temperaturefloat or None, optional: Fill temperature in K; None is room temperature, or the mixture’s own beside a Mixture, which refuses any other.
nint, optional: Azimuthal mode index.
mint, optional: Radial mode index, >= 1.
kind{‘HE’, ‘TE’, ‘TM’}, optional: Mode family.
model{‘full’, ‘reduced’}, optional: Marcatili model.
lossbool, float or callable, optional: Loss policy of the mode.
claddingGlassIndex, complex or None, optional: Cladding index; None is fused silica.
materialsMaterialSelection or None, optional: Build the capillary as prop_capillary does under the same materials=: the fill from optmat (index, density and Kerr coefficient at wavelength) and cladding=None as optmat’s recommended fused silica. None is MaterialSelection().

Returns:

SolitonParams: The numbers, with the mode that was built.

Examples

>>> from solprop.tools import capillary_params
>>> p = capillary_params(125e-6, "He", 0.4, energy=300e-6, fwhm=10e-15,
...                      wavelength=800e-9, model="reduced", cladding=1.45)
>>> f"{p.gamma:.3e} {p.intensity:.3e}"
'4.884e-11 1.130e+18'

solprop.tools.dispersion_length(fwhm, beta2, shape='sech')[source]#

Return the dispersion length \(L_D = \tau_0^2/|\beta_2|\).

Parameters:

fwhmfloat: Full width at half maximum of the power in s, > 0.
beta2float: Group-velocity dispersion in s^2/m, non-zero.
shape{‘sech’, ‘gauss’}, optional: The pulse shape; see pulse_width().

Returns:

float: Dispersion length in m.

Raises:

ToolsError: If the dispersion is zero or not finite, or the width is not positive.

Examples

>>> from solprop.tools import dispersion_length
>>> f"{dispersion_length(10e-15, -8e-30):.3f}"
'4.023'

solprop.tools.field_to_intensity(field)[source]#

Return the intensity of a field amplitude, \(I = \epsilon_0 c E^2/2\).

Parameters:

fieldfloat: Field amplitude in V/m.

Returns:

float: Intensity in W/m^2.

Examples

>>> from solprop.tools import field_to_intensity
>>> f"{field_to_intensity(1e10):.4e}"
'1.3272e+17'

solprop.tools.fission_length(peak_power, fwhm, gamma, beta2, shape='sech')[source]#

Return the soliton fission length \(L_{\rm fiss} = L_D/N\).

Parameters:

peak_powerfloat: Peak power in W, > 0.
fwhmfloat: Full width at half maximum of the power in s, > 0.
gammafloat: Nonlinear coefficient in rad/(W m), > 0.
beta2float: Group-velocity dispersion in s^2/m, non-zero.
shape{‘sech’, ‘gauss’}, optional: The pulse shape; see pulse_width().

Returns:

float: Fission length in m, the geometric mean of the two lengths.

Examples

>>> from solprop.tools import fission_length
>>> f"{fission_length(1e9, 10e-15, 1e-9, -8e-30):.4f}"
'2.0057'

solprop.tools.gas_ratio(gas_a, gas_b, wavelength, *, pressure=1.0, temperature=293.15, materials=None)[source]#

Return the ratios of bulk dispersion and Kerr response of two gases.

The bulk (unguided) dispersion of each gas, not a mode’s: it answers “how much more pressure of B matches A”, which is a property of the gases alone.

Parameters:

gas_aGas or str: The numerator’s species.
gas_bGas or str: The denominator’s species.
wavelengthfloat: Wavelength in m at which the dispersions are compared, > 0.
pressurefloat, optional: Pressure of both gases in bar, > 0.
temperaturefloat, optional: Temperature of both in K.
materialsMaterialSelection or None, optional: Take both gases from optmat under this selection, as a run’s materials= does: their index, their density and their Kerr coefficient at wavelength; "air" is nitrogen and oxygen. None is MaterialSelection().

Returns:

GasRatio: Named beta2 and chi3 ratios.

Raises:

ToolsError: If the selection names a carrier other than wavelength, or a gas has no Kerr data under it.

Examples

>>> from solprop.tools import gas_ratio
>>> ratio = gas_ratio("Ar", "He", 800e-9)
>>> f"{ratio.beta2:.1f} {ratio.chi3:.1f}"
'18.6 28.4'

solprop.tools.intensity_to_field(intensity)[source]#

Return the field amplitude of an intensity, \(E = \sqrt{2I/\epsilon_0 c}\).

Parameters:

intensityfloat: Intensity in W/m^2, >= 0.

Returns:

float: Field amplitude in V/m.

Raises:

ToolsError: If the intensity is negative.

Examples

>>> from solprop.tools import field_to_intensity, intensity_to_field
>>> f"{intensity_to_field(field_to_intensity(1e10)):.6e}"
'1.000000e+10'

solprop.tools.lambda_rdw(mode, wavelength, *, soliton_mode=None, z=0.0, peak_power=None, gamma=None, fwhm=None, shape='sech', nonlinear_phase='largest', wavelength_limits=None)[source]#

Return the phase-matched dispersive-wave wavelength nearest the pump.

Parameters:

modeMode: The mode the dispersive wave is emitted into.
wavelengthfloat: Wavelength of the soliton in m, > 0.
soliton_modeMode or None, optional: The soliton’s mode; None is mode.
zfloat, optional: Position along the waveguide, m.
peak_powerfloat or None, optional: Peak power in W for the nonlinear term; see phase_mismatch().
gammafloat or None, optional: Nonlinear coefficient in rad/(W m) for the nonlinear term.
fwhmfloat or None, optional: Input power FWHM in s, positive; required with power for the default phase.
shape{‘sech’, ‘gauss’}, optional: Unchirped input shape for the largest constituent.
nonlinear_phase{‘largest’, ‘supplied_power’, ‘linear’}, optional: Default uses the largest constituent. Supplied power uses gamma P0/2 and requires omitting fwhm. Linear requires omitting all pulse numbers. Without pulse numbers the default is also linear.
wavelength_limitstuple of float or None, optional: Window searched, m; None is 100 nm to 0.9 of the pump wavelength.

Returns:

float: The longest root inside the window in m, which with the default window is the short-wavelength dispersive wave nearest the pump. lambda_rdw_all() returns all of them.

Raises:

ToolsError: If the window holds no root, rather than returning a missing value that would propagate silently.

Examples

>>> from solprop.modes import MarcatiliMode
>>> from solprop.tools import lambda_rdw
>>> mode = MarcatiliMode(125e-6, "He", 1.0, cladding=1.45)
>>> f"{lambda_rdw(mode, 800e-9) * 1e9:.1f}"
'200.1'

solprop.tools.lambda_rdw_all(mode, wavelength, *, soliton_mode=None, z=0.0, peak_power=None, gamma=None, fwhm=None, shape='sech', nonlinear_phase='largest', wavelength_limits=None)[source]#

Return every phase-matched wavelength in a window, shortest first.

Parameters:

modeMode: The mode the dispersive wave is emitted into.
wavelengthfloat: Wavelength of the soliton in m, > 0.
soliton_modeMode or None, optional: The soliton’s mode; None is mode.
zfloat, optional: Position along the waveguide, m.
peak_powerfloat or None, optional: Peak power in W for the nonlinear term; see phase_mismatch().
gammafloat or None, optional: Nonlinear coefficient in rad/(W m) for the nonlinear term.
fwhmfloat or None, optional: Input power FWHM in s, positive; required with power for the default phase.
shape{‘sech’, ‘gauss’}, optional: Unchirped input shape for the largest constituent.
nonlinear_phase{‘largest’, ‘supplied_power’, ‘linear’}, optional: Default uses the largest constituent. Supplied power uses gamma P0/2 and requires omitting fwhm. Linear requires omitting all pulse numbers. Without pulse numbers the default is also linear.
wavelength_limitstuple of float or None, optional: Shortest and longest wavelength searched, m. None is 100 nm to 0.9 of the pump wavelength, which keeps the double root at the pump out.

Returns:

tuple of float: The roots in m, ascending; empty when there is none. The mismatch is sampled on 2048 frequencies across the window, each sign change is refined with Brent’s method, and roots closer than one sample are not separated.

Raises:

ToolsError: If the window is not positive and ordered.

Examples

>>> from solprop.modes import MarcatiliMode
>>> from solprop.tools import lambda_rdw_all
>>> mode = MarcatiliMode(125e-6, "He", 1.0, cladding=1.45)
>>> [f"{root * 1e9:.0f}" for root in lambda_rdw_all(mode, 800e-9)]
['200']

solprop.tools.nonlinear_coefficient(mode, n2, wavelength, z=0.0)[source]#

Return the nonlinear coefficient \(\gamma = n_2\omega/(cA_{\rm eff})\).

Parameters:

modeMode: The mode, for its effective area.
n2float: Nonlinear index of the fill in m^2/W, >= 0.
wavelengthfloat: Vacuum wavelength in m, > 0.
zfloat, optional: Position along the waveguide, m.

Returns:

float: Nonlinear coefficient in rad/(W m).

Raises:

ToolsError: If the nonlinear index is negative or not finite.

Examples

>>> from solprop.modes import MarcatiliMode
>>> from solprop.tools import nonlinear_coefficient
>>> mode = MarcatiliMode(125e-6, "He", 1.0)
>>> f"{nonlinear_coefficient(mode, 3.55e-25, 800e-9):.4e}"
'1.1919e-10'

solprop.tools.nonlinear_length(peak_power, gamma)[source]#

Return the nonlinear length \(L_{NL} = 1/(\gamma P_0)\).

Parameters:

peak_powerfloat: Peak power in W, > 0.
gammafloat: Nonlinear coefficient in rad/(W m), > 0.

Returns:

float: Nonlinear length in m.

Raises:

ToolsError: If either quantity is not positive.

Examples

>>> from solprop.tools import nonlinear_length
>>> nonlinear_length(1e9, 1e-9)
1.0

solprop.tools.phase_mismatch(mode, omega, wavelength, *, soliton_mode=None, z=0.0, peak_power=None, gamma=None, fwhm=None, shape='sech', nonlinear_phase='largest')[source]#

Return the phase mismatch between a soliton and a dispersive wave.

\[\Delta\beta(\omega) = \beta_{\rm dw}(\omega) - \beta_{\rm s}(\omega_0) - \beta_{1,\rm s}(\omega_0)(\omega-\omega_0) - k_{\rm NL} .\]

Parameters:

modeMode: The mode the dispersive wave is emitted into.
omeganumpy.ndarray: Angular frequencies in rad/s, shape (n_omega,).
wavelengthfloat: Wavelength of the soliton in m, > 0.
soliton_modeMode or None, optional: The mode the soliton travels in; None is mode. A different one gives intermodal phase matching.
zfloat, optional: Position along the waveguide, m.
peak_powerfloat or None, optional: Input peak power in W. With gamma and fwhm, adds the soliton’s nonlinear wavenumber; both None (the default) gives the linear condition.
gammafloat or None, optional: Nonlinear coefficient of the soliton’s mode in rad/(W m) (nonlinear_coefficient()).
fwhmfloat or None, optional: Input power FWHM in s, positive; required with power for the default phase.
shape{‘sech’, ‘gauss’}, optional: Unchirped input shape for the largest constituent.
nonlinear_phase{‘largest’, ‘supplied_power’, ‘linear’}, optional: Default uses the largest constituent. Supplied power uses gamma P0/2 and requires omitting fwhm. Linear requires omitting all pulse numbers. Without pulse numbers the default is also linear.

Returns:

numpy.ndarray: Mismatch in 1/m, shape (n_omega,). It vanishes at the pump in the linear case, with zero slope there.

Raises:

ToolsError: If pulse arguments are incomplete or contradictory, or the largest constituent does not exist in anomalous dispersion.

Notes

The default nonlinear term is gamma times the largest constituent’s power / 2 (soliton_content()). The supplied-power option treats the quoted power as a fundamental soliton, advancing as exp(i gamma P0 z / 2) (Akhmediev and Karlsson, Phys. Rev. A 51, 2602 (1995)). Both are local estimates; loss, higher-order dispersion, Raman, chirp and plasma evolution are not included.

Examples

>>> import numpy as np
>>> from solprop.modes import MarcatiliMode
>>> from solprop.tools import phase_mismatch
>>> mode = MarcatiliMode(125e-6, "He", 1.0)
>>> pump = 2 * np.pi * 299792458.0 / 800e-9
>>> abs(float(phase_mismatch(mode, np.array([pump]), 800e-9)[0])) < 1e-6
True

solprop.tools.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.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.pulse_peak_power(energy, fwhm, shape='sech')[source]#

Return the peak power of a pulse of given energy, duration and shape.

Parameters:

energyfloat: Pulse energy in J, > 0.
fwhmfloat: Full width at half maximum of the power in s, > 0.
shape{‘sech’, ‘gauss’}, optional: The pulse shape; see pulse_width().

Returns:

float: Peak power in W: \(E/(2\tau_0)\) for sech and \(E/(\sqrt\pi\,\tau_0)\) for a Gaussian, the integrals of the two shapes.

Raises:

ToolsError: If the shape is unknown or a quantity is not positive.

Examples

>>> from solprop.tools import pulse_peak_power
>>> f"{pulse_peak_power(1e-3, 10e-15) / 1e9:.3f}"
'88.137'
>>> f"{pulse_peak_power(1e-3, 10e-15, 'gauss') / 1e9:.3f}"
'93.944'

solprop.tools.pulse_width(fwhm, shape='sech')[source]#

Return the natural width of a pulse from its full width at half maximum.

Parameters:

fwhmfloat: Full width at half maximum of the power in s, > 0.
shape{‘sech’, ‘gauss’}, optional: "sech" for \(P\propto{\rm sech}^2(t/\tau_0)\), "gauss" for \(P\propto\exp(-t^2/\tau_0^2)\).

Returns:

float: \(\tau_0\) in s: fwhm / (2 ln(1 + sqrt 2)) or fwhm / (2 sqrt(ln 2)).

Raises:

ToolsError: If the shape is unknown or the width is not positive.

Examples

>>> from solprop.tools import pulse_width
>>> f"{pulse_width(10e-15) * 1e15:.4f}"
'5.6730'
>>> f"{pulse_width(10e-15, 'gauss') * 1e15:.4f}"
'6.0056'

solprop.tools.self_focusing_power(wavelength, index, n2)[source]#

Return the critical power for self-focusing, as physical power.

\(P_{\rm cr} = 1.86226\,\lambda^2/(4\pi n_0 n_2)\), the Townes power of Fibich and Gaeta (Opt. Lett. 25, 335 (2000)). It is solprop.spatial.critical_power() – the package’s one Townes constant – at the linear index, both measuring the physical axial power in the medium (SEP 34). The paper prints the constant as 1.86225; the computed value is 1.8622555, of which 1.86226 is the rounding.

Parameters:

wavelengthfloat: Vacuum wavelength in m, > 0.
indexfloat: Linear refractive index \(n_0\), > 0.
n2float: Nonlinear index in m^2/W, > 0.

Returns:

float: Critical power in W.

Examples

>>> from solprop.tools import self_focusing_power
>>> f"{self_focusing_power(800e-9, 1.0, 3.55e-25) / 1e9:.2f}"
'267.17'

solprop.tools.soliton_content(peak_power, fwhm, gamma, beta2, shape='sech')[source]#

Calculate the soliton count and largest constituent of an unchirped pulse.

This is the scattering content of the lossless cubic focusing NLSE, not a prediction of fission dynamics with higher-order dispersion, Raman or plasma. The conventional soliton_order() remains a separate design parameter.

Parameters:

peak_powerfloat: Input peak power in W, finite and positive.
fwhmfloat: Input power FWHM in s, finite and positive.
gammafloat: Nonlinear coefficient in rad/(W m), finite and positive.
beta2float: Anomalous group-velocity dispersion in s^2/m, finite and negative.
shape{‘sech’, ‘gauss’}, optional: Unchirped input field shape; the Gaussian power is exp(-t^2/tau0^2).

Returns:

SolitonContent: Analytic count and largest constituent. The sech eigenvalue is analytic; the Gaussian eigenvalue is numerical, with dimensionless absolute accuracy about 1e-10 away from thresholds. Relative accuracy degrades at threshold.

Raises:

ToolsError: If inputs are invalid, dispersion is not anomalous, or scattering fails.

References

[1]

Klaus and Shaw, SIAM J. Math. Anal. 34, 759 (2003), doi:10.1137/S0036141002403067.

[2]

Kim, Lee and Lyng, arXiv:1310.4145, sections 1-2.

solprop.tools.soliton_order(peak_power, fwhm, gamma, beta2, shape='sech')[source]#

Return the soliton order \(N = \sqrt{L_D/L_{NL}}\).

The number is defined for either sign of the dispersion; it is a soliton order in the physical sense only where beta2 < 0.

Parameters:

peak_powerfloat: Peak power in W, > 0.
fwhmfloat: Full width at half maximum of the power in s, > 0.
gammafloat: Nonlinear coefficient in rad/(W m), > 0.
beta2float: Group-velocity dispersion in s^2/m, non-zero.
shape{‘sech’, ‘gauss’}, optional: The pulse shape, used for the width throughout.

Returns:

float: The soliton order, dimensionless.

Examples

>>> from solprop.tools import soliton_order
>>> f"{soliton_order(1e9, 10e-15, 1e-9, -8e-30):.4f}"
'2.0057'

solprop.tools.soliton_params(mode, gas, pressure=None, *, energy, fwhm, wavelength, shape='sech', temperature=None, z=0.0, materials=None)[source]#

Return the design numbers of a pulse in any mode.

The mode supplies the dispersion, the area and the loss; the fill supplies the nonlinear index. They are separate arguments because a mode need not know its fill’s Kerr response (a tabulated mode does not), and the caller is trusted to give the fill the mode was built with – capillary_params() does both.

Parameters:

modeMode: Any mode: a capillary, an antiresonant or tabulated fibre, a rectangular guide.
gasGas, str, Mapping or Mixture: The fill: a registry species, "air", mole fractions, or a mixture. A mixture of species selected from optmat takes their Kerr coefficients at wavelength, the carrier.
pressurefloat or None, optional: Total pressure in bar; None is one bar, and is required beside a Mixture.
energyfloat: Pulse energy in J, > 0.
fwhmfloat: Full width at half maximum of the power in s, > 0.
wavelengthfloat: Pump wavelength in m, > 0.
shape{‘sech’, ‘gauss’}, optional: The pulse shape, used consistently for the width and the peak power.
temperaturefloat or None, optional: Fill temperature in K; None is room temperature, or the mixture’s own beside a Mixture, which refuses any other.
zfloat, optional: Position along the waveguide at which everything is evaluated, m.
materialsMaterialSelection or None, optional: Resolve a named fill from optmat under this selection, as a run’s materials= does: its index, density and Kerr coefficient at wavelength. None is MaterialSelection(); a Mixture is taken as it is. The mode is the caller’s either way.

Returns:

SolitonParams: The numbers, with the mode.

Raises:

ToolsError: If a quantity is not positive, the shape is unknown, the mode has no dispersion at the pump, a component of the fill has no Kerr data, the selection names a carrier other than wavelength, or a pressure or a temperature other than its own is given beside a Mixture.

Examples

>>> from solprop.modes import MarcatiliMode
>>> from solprop.tools import soliton_params
>>> mode = MarcatiliMode(125e-6, "He", 0.4, model="reduced", cladding=1.45)
>>> p = soliton_params(mode, "He", 0.4, energy=300e-6, fwhm=10e-15,
...                    wavelength=800e-9)
>>> f"{p.soliton_order:.2f} {p.fission_length:.2f}"
'2.26 1.75'