Source code for solprop.tools.soliton

# SPDX-FileCopyrightText: 2026 John C. Travers and contributors
#
# SPDX-License-Identifier: GPL-3.0-or-later


"""Soliton numbers: dispersion and nonlinear lengths, orders and constituents.

The closed forms of a pulse in a mode of given dispersion and nonlinear coefficient
(:func:`dispersion_length`, :func:`nonlinear_length`, :func:`soliton_order`,
:func:`soliton_peak_power`, :func:`fission_length`), the soliton content of an unchirped
input (:func:`soliton_content`, :class:`SolitonContent`), and the fill's nonlinear
coefficient (:func:`nonlinear_coefficient`).
"""

import math
from dataclasses import dataclass

import numpy as np
from jaxtyping import Float
from scipy.integrate import solve_ivp
from scipy.optimize import brentq
from scipy.special import erfcinv

from solprop._validation import positive
from solprop.constants import C
from solprop.exceptions import (
    ToolsError,
)
from solprop.modes import base
from solprop.modes.protocol import Mode
from solprop.tools.pulse import PulseShape, _omega, pulse_width

__all__ = [
    "SolitonContent",
    "dispersion_length",
    "fission_length",
    "nonlinear_coefficient",
    "nonlinear_length",
    "soliton_content",
    "soliton_order",
    "soliton_peak_power",
]


[docs] def dispersion_length(fwhm: float, beta2: float, shape: PulseShape = "sech") -> float: r"""Return the dispersion length :math:`L_D = \tau_0^2/|\beta_2|`. Parameters ---------- fwhm : float Full width at half maximum of the power in s, > 0. beta2 : float Group-velocity dispersion in s^2/m, non-zero. shape : {'sech', 'gauss'}, optional The pulse shape; see :func:`~solprop.tools.pulse.pulse_width`. Default ``"sech"``, unlike the ``"gauss"`` default of :func:`~solprop.driver.interface.prop_capillary` and :func:`~solprop.driver.interface.prop_gnlse`. 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' """ if not math.isfinite(beta2) or beta2 == 0.0: raise ToolsError(f"beta2 must be finite and non-zero, got {beta2!r}") return pulse_width(fwhm, shape) ** 2 / abs(beta2)
[docs] def nonlinear_length(peak_power: float, gamma: float) -> float: r"""Return the nonlinear length :math:`L_{NL} = 1/(\gamma P_0)`. Parameters ---------- peak_power : float Peak power in W, > 0. gamma : float 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 """ return 1.0 / ( positive(gamma, "gamma", ToolsError) * positive(peak_power, "peak_power", ToolsError) )
[docs] def soliton_order( peak_power: float, fwhm: float, gamma: float, beta2: float, shape: PulseShape = "sech", ) -> float: r"""Return the soliton order :math:`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_power : float Peak power in W, > 0. fwhm : float Full width at half maximum of the power in s, > 0. gamma : float Nonlinear coefficient in rad/(W m), > 0. beta2 : float Group-velocity dispersion in s^2/m, non-zero. shape : {'sech', 'gauss'}, optional The pulse shape, used for the width **throughout**. Default ``"sech"``, unlike the ``"gauss"`` default of :func:`~solprop.driver.interface.prop_capillary` and :func:`~solprop.driver.interface.prop_gnlse`. 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' """ return math.sqrt( dispersion_length(fwhm, beta2, shape) / nonlinear_length(peak_power, gamma) )
[docs] def soliton_peak_power( order: float, fwhm: float, gamma: float, beta2: float, shape: PulseShape = "sech", ) -> float: r"""Return the peak power that gives a soliton order. The inverse of :func:`soliton_order` at fixed dispersion, nonlinear coefficient and width: :math:`N^2 = \gamma P_0\tau_0^2/|\beta_2|` is linear in the peak power, so :math:`P_0 = N^2|\beta_2|/(\gamma\tau_0^2)`. :func:`~solprop.tools.pulse.pulse_energy` turns it into an energy. On a mode, take `beta2` from :func:`solprop.modes.base.beta2` at the pump and `gamma` from :func:`nonlinear_coefficient`, both at the launch position. Parameters ---------- order : float Conventional soliton order, > 0. fwhm : float Full width at half maximum of the power in s, > 0. gamma : float Nonlinear coefficient in rad/(W m), > 0. beta2 : float Group-velocity dispersion in s^2/m, non-zero. shape : {'sech', 'gauss'}, optional The pulse shape, used for the width. Default ``"sech"``, unlike the ``"gauss"`` default of :func:`~solprop.driver.interface.prop_capillary` and :func:`~solprop.driver.interface.prop_gnlse`. Returns ------- float Peak power in W. Raises ------ ToolsError If a quantity is not positive, the dispersion is zero, or the shape is unknown. Examples -------- >>> from solprop.tools import soliton_order, soliton_peak_power >>> power = soliton_peak_power(2.0, 10e-15, 1e-9, -8e-30) >>> f"{power / 1e9:.4f} {soliton_order(power, 10e-15, 1e-9, -8e-30):.4f}" '0.9943 2.0000' """ return positive(order, "order", ToolsError) ** 2 / ( positive(gamma, "gamma", ToolsError) * dispersion_length(fwhm, beta2, shape) )
[docs] @dataclass(frozen=True) class SolitonContent: """Describe the discrete soliton content of an unchirped single-lobe pulse. Attributes ---------- area_order : float Dimensionless field area divided by pi, not the conventional soliton order. count : int Number of strictly positive discrete eigenvalues; zero at first threshold. largest_eigenvalue : float 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_power : float or None Peak power of the largest constituent in W, or None if count is zero. largest_width : float or None Natural sech width of that constituent in s, or None if count is zero. largest_nonlinear_wavenumber : float 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_peak_power: float | None largest_width: float | None largest_nonlinear_wavenumber: float | None
def _scattering_angle( x: float, theta: Float[np.ndarray, " n_components"], order: float, eta: float ) -> list[float]: """Evaluate the real Zakharov-Shabat phase equation for a Gaussian.""" return [-order * math.exp(-x * x / 2.0) - eta * math.sin(2 * theta[0])] def _gaussian_eigenvalue(order: float) -> float: """Solve the half-line scattering problem for the largest Gaussian eigenvalue. - ``order``: conventional soliton order, above the first Gaussian threshold. """ # The omitted field area is <= 1e-13. Moving the boundary with the amplitude # avoids assuming that the Gaussian tail is negligible for every input N. extent = math.sqrt(2.0) * float(erfcinv(1e-13 / (order * math.sqrt(math.pi / 2.0)))) def residual(eta: float) -> float: """Return the ground-state symmetry residual at the pulse centre.""" if eta == 0.0: # The exact area protects the first threshold from tail truncation. return math.pi / 4.0 - order * math.sqrt(math.pi / 2.0) solution = solve_ivp( _scattering_angle, (-extent, 0.0), [0.0], method="DOP853", args=(order, eta), rtol=1e-11, atol=1e-13, ) if not solution.success: raise ToolsError( f"Gaussian scattering integration failed: {solution.message}" ) return float(solution.y[0, -1]) + math.pi / 4.0 # The ground-state angle crosses -pi/4 once for 0 < eta < max(q). # Unlike shooting the amplitudes, this does not overflow in the tails. try: return float(brentq(residual, 0.0, order, xtol=1e-13, rtol=1e-11)) except (ValueError, RuntimeError) as error: raise ToolsError(f"Gaussian eigenvalue refinement failed: {error}") from error
[docs] def soliton_content( peak_power: float, fwhm: float, gamma: float, beta2: float, shape: PulseShape = "sech", ) -> SolitonContent: r"""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 :func:`soliton_order` remains a separate design parameter. Parameters ---------- peak_power : float Input peak power in W, finite and positive. fwhm : float Input power FWHM in s, finite and positive. gamma : float Nonlinear coefficient in rad/(W m), finite and positive. beta2 : float 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). Default ``"sech"``, unlike the ``"gauss"`` default of :func:`~solprop.driver.interface.prop_capillary` and :func:`~solprop.driver.interface.prop_gnlse`. 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. """ if not math.isfinite(beta2) or beta2 >= 0.0: raise ToolsError( "soliton content requires finite anomalous dispersion (beta2 < 0)" ) order = soliton_order(peak_power, fwhm, gamma, beta2, shape) area_order = order if shape == "sech" else math.sqrt(2.0 / math.pi) * order if not math.isfinite(area_order): raise ToolsError("the normalised pulse area must be finite") # Strictly positive eigenvalues only: at a half-integer area the new state is # at zero and is not a square-integrable soliton (Klaus-Shaw threshold). count = max(0, math.ceil(area_order - 0.5)) if count == 0: return SolitonContent(area_order, 0, None, None, None, None) eta = order - 0.5 if shape == "sech" else _gaussian_eigenvalue(order) if eta <= 0.0: raise ToolsError( "the positive Gaussian eigenvalue is too close to threshold to resolve" ) power = peak_power * (2.0 * eta / order) ** 2 width = pulse_width(fwhm, shape) / (2.0 * eta) return SolitonContent(area_order, count, eta, power, width, 0.5 * gamma * power)
[docs] def fission_length( peak_power: float, fwhm: float, gamma: float, beta2: float, shape: PulseShape = "sech", ) -> float: r"""Return the soliton fission length :math:`L_{\rm fiss} = L_D/N`. Parameters ---------- peak_power : float Peak power in W, > 0. fwhm : float Full width at half maximum of the power in s, > 0. gamma : float Nonlinear coefficient in rad/(W m), > 0. beta2 : float Group-velocity dispersion in s^2/m, non-zero. shape : {'sech', 'gauss'}, optional The pulse shape; see :func:`~solprop.tools.pulse.pulse_width`. Default ``"sech"``, unlike the ``"gauss"`` default of :func:`~solprop.driver.interface.prop_capillary` and :func:`~solprop.driver.interface.prop_gnlse`. 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' """ order = soliton_order(peak_power, fwhm, gamma, beta2, shape) return dispersion_length(fwhm, beta2, shape) / order
[docs] def nonlinear_coefficient( mode: Mode, n2: float, wavelength: float, z: float = 0.0 ) -> float: r"""Return the nonlinear coefficient :math:`\gamma = n_2\omega/(cA_{\rm eff})`. Parameters ---------- mode : Mode The mode, for its effective area. n2 : float Nonlinear index of the fill in m^2/W, >= 0. wavelength : float Vacuum wavelength in m, > 0. z : float, 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' """ if not math.isfinite(n2) or n2 < 0.0: raise ToolsError(f"n2 must be finite and not negative, got {n2!r}") return n2 * _omega(wavelength) / (C * base.aeff(mode, z))
def _area_per_order(shape: PulseShape) -> float: """Return the pulse area over pi per unit conventional soliton order.""" return 1.0 if shape == "sech" else math.sqrt(2.0 / math.pi) def _gaussian_order(eigenvalue: float) -> float: """Return the conventional order whose Gaussian has a given largest eigenvalue. - ``eigenvalue``: target imaginary part of the largest Zakharov-Shabat eigenvalue, > 0. """ threshold = 0.5 / _area_per_order("gauss") def residual(order: float) -> float: """Return the largest eigenvalue at an order less the target.""" # At and below the first threshold there is no bound state: the eigenvalue # that appears there starts from zero. if order <= threshold: return -eigenvalue return _gaussian_eigenvalue(order) - eigenvalue # N - eta of the Gaussian falls from sqrt(pi/8) = 0.627 at the first threshold # towards 1/2 as N grows (0.579 at N = 1, 0.506 at N = 10, measured with # _gaussian_eigenvalue), so the root lies between eta + 1/2 and eta + 0.627. The # upper end carries a margin; brentq refuses a bracket that does not hold the root. low = max(threshold, eigenvalue + 0.5) high = eigenvalue + 0.7 try: return float(brentq(residual, low, high, xtol=1e-12, rtol=1e-11)) except ValueError as error: raise ToolsError( f"no Gaussian soliton order between {low:.6g} and {high:.6g} has a largest " f"eigenvalue of {eigenvalue:.6g}: {error}" ) from error