Source code for solprop.modes.base

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

r"""Derived quantities of any mode: beta, alpha, group delay, dispersion, ZDW.

Everything here is a function of a :class:`~solprop.modes.protocol.Mode`, not a method
on one, so a new mode family gets them for nothing: the propagation constant and
power loss (:func:`beta`, :func:`alpha`, :func:`loss_length`, :func:`db_per_m`,
:func:`transmission`), the dispersion orders (:func:`beta1`, :func:`beta2`,
:func:`beta3`), the zero-dispersion wavelength (:func:`zdw`, a sampled search of
``beta_2``'s sign) and the effective area (:func:`aeff`). The conversions are the
package's (``docs/dev/conventions.md`` section 2):
:math:`\beta = (\omega/c)\,\mathrm{Re}\,n_{\rm eff}` and
:math:`\alpha = (2\omega/c)\,\mathrm{Im}\,n_{\rm eff}`, so a positive imaginary
index is loss and ``alpha`` is a power loss coefficient per metre.

:func:`beta1` is **analytic**, straight from the mode's ``dneff_domega``, because the
co-moving frame rides on it (``docs/dev/stepper.md`` section 5); :func:`beta2` and
:func:`beta3` are Richardson differences of that analytic ``beta1``, with steps
:data:`BETA2_RELATIVE_STEP` and :data:`BETA3_RELATIVE_STEP`. Their accuracy is in
``docs/guide/waveguides/capillary-model.md``, section "The frequency derivative".
"""

import logging
import math
import warnings
from typing import Final

import numpy as np
from jaxtyping import Float
from scipy.integrate import quad_vec

from solprop.constants import C
from solprop.exceptions import (
    DiluteScalingWarning,
    MaterialRangeWarning,
    ModeError,
    NoZeroDispersionError,
)
from solprop.modes.protocol import Mode

__all__ = [
    "BETA2_RELATIVE_STEP",
    "BETA3_RELATIVE_STEP",
    "aeff",
    "alpha",
    "beta",
    "beta1",
    "beta2",
    "beta3",
    "db_per_m",
    "loss_length",
    "transmission",
    "zdw",
]

logger = logging.getLogger(__name__)

BETA2_RELATIVE_STEP: Final = 3e-3
"""Relative frequency step of the Richardson difference behind :func:`beta2`.

Larger than a finite difference usually wants, and deliberately so. ``beta_1`` is of
order ``1/c`` while its variation over the step is ``beta_2 h``, which for a capillary
is nine orders smaller, so the rounding error of the difference is ``eps beta_1 / h``
-- it *falls* as the step grows. Truncation, ``(h^2/6) beta_4``, rises. Measured
against the closed-form second derivative of an evacuated capillary
(``tests/modes/test_base.py``), the two cross near a relative step of 3e-3, where the
result is good to 5e-9; at 1e-4 it is 1.6e-7 and at 1e-5 it is 2.3e-6.

That is three orders better than differencing ``beta`` itself, and it is
enough: nothing in the solver consumes ``beta_2``. The co-moving frame uses ``beta_1``,
which is analytic. Making this analytic too needs the second derivative of the gas
susceptibility, which is not part of the material interface.
"""

BETA3_RELATIVE_STEP: Final = 4e-3
"""Relative frequency step of the Richardson second difference behind :func:`beta3`.

A second difference divides the rounding of ``beta_1`` by the step squared, while the
truncation grows with the structure the fill puts into ``beta_1``, and the two pull
the step opposite ways. Against the closed form of an evacuated capillary
(``tests/modes/test_base.py``), which has little structure, the error is 3.8e-6 at a
relative step of 3e-3, 1.5e-6 at 4e-3 and 4.8e-7 at 8e-3. A helium-filled capillary
(125 um, one bar, 400 nm to 2 um) has more: there, steps of 3e-3 and 5e-3 agree with
4e-3 to 1.5e-5 of the largest value, while a step of 2e-2 is off by 4e-4.
"""

_DECIBEL_PER_NEPER: Final = 10.0 / math.log(10.0)
"""Conversion from a power loss coefficient in 1/m to dB/m."""

_ZDW_SAMPLES: Final = 512
"""Samples, evenly spaced in frequency, on which :func:`zdw` reads the sign of
``beta_2``: 2.3e13 rad/s apart across its default window."""

_ZDW_REFINE_ROUNDS: Final = 5
"""Rounds of array samples that refine a sign change of the dispersion. Five take a
bracket of 2.3e13 rad/s to 2.2e7 rad/s, where interpolating linearly reaches the noise
of the differenced ``beta2``."""

_ZDW_REFINE_SAMPLES: Final = 17
"""Samples of each refinement round: 16 intervals, so each round narrows 16-fold. A
mode solved point by point (a step-index fibre) pays per sample, so fewer samples in
more rounds reach the same bracket for less."""

_ZDW_STENCIL_RATIO: Final = (2.0, 8.0)
"""Bounds on the rise of ``beta1`` from a candidate zero at a full step of the
``beta2`` stencil over its rise at a half step, on each side. A resolved extremum
gives 4; see :func:`_is_zero`."""

_ZDW_LINE_SPREAD: Final = 0.1
"""Spread of ``beta1`` across the ``beta2`` stencil, as a fraction of its value at the
change, beyond which a sign change that is not a zero is a line (:func:`_is_line`).
At a gas line the group delay diverges or drops to the evanescent floor, and every
such change of krypton and argon fills spreads by 1 or more; a smooth feature
spreads by far less: 1e-4 at silica's OH overtone near 1.38 um, 2e-2 at its
fundamental near 2.7 um, 6e-3 at an antiresonant wall's resonance. A tenth is five
times the largest smooth spread and a tenth of the smallest at a line."""

_ZDW_ISOLATION: Final = 1.5e-2
"""Relative frequency distance on each side of a zero of ``beta2`` over which it must
be the only sign change to be a zero-dispersion point (:func:`_is_isolated`): the
narrowest dispersion regime :func:`zdw` resolves, five times the ``beta2`` stencil.
Narrower regimes are the fine structure of an absorption band, whose zeros come in
clusters: fused silica's OH bands (optmat's ``fit/SiO2``) give zeros 0.2-0.8 % apart
near 1.38 um and 0.9 % apart near 2.2 and 2.7 um. An antiresonant wall's resonance
is broader: the normal dispersion beside it, which bounds the band's zeros, spans
2.1-2.4 % before the resonance's inner zeros, which are 0.5-2.5 % apart. A standard
fibre's zero near 1.3 um lies 5.5 % from the nearest other sign change."""

_ZDW_ISOLATION_SAMPLES: Final = 32
"""Samples of ``beta1`` on each side of a zero across :data:`_ZDW_ISOLATION`: 4.7e-4
apart in relative frequency, finer than the ``beta2`` stencil. Beside a standard
fibre's zero ``beta1`` changes by 1.7e-17 s/m between samples, a million times its
noise."""


def _as_omega(omega: Float[np.ndarray, " n_omega"]) -> Float[np.ndarray, " n_omega"]:
    """Validate an angular-frequency argument for a derived quantity.

    - ``omega``: angular frequencies in rad/s, shape ``(n_omega,)``.
    """
    values = np.asarray(omega, dtype=float)
    if not np.all(np.isfinite(values)):
        raise ModeError("angular frequency must be finite")
    return values


[docs] def beta( mode: Mode, omega: Float[np.ndarray, " n_omega"], z: float = 0.0 ) -> Float[np.ndarray, " n_omega"]: """Return the propagation constant of a mode. Parameters ---------- mode : Mode The mode. omega : numpy.ndarray Angular frequencies in rad/s, shape ``(n_omega,)``. z : float, optional Position along the waveguide, m. Returns ------- numpy.ndarray ``beta = omega Re(n_eff) / c`` in 1/m, shape ``(n_omega,)``. Examples -------- >>> import numpy as np >>> from solprop.modes import MarcatiliMode >>> from solprop.modes.base import beta >>> mode = MarcatiliMode(125e-6, "He", 1.0) >>> f"{beta(mode, np.array([2.356e15]))[0]:.6f}" '7858997.479689' """ values = _as_omega(omega) return np.asarray(values * np.real(mode.neff(values, z)) / C)
[docs] def alpha( mode: Mode, omega: Float[np.ndarray, " n_omega"], z: float = 0.0 ) -> Float[np.ndarray, " n_omega"]: """Return the power loss coefficient of a mode. Parameters ---------- mode : Mode The mode. omega : numpy.ndarray Angular frequencies in rad/s, shape ``(n_omega,)``. z : float, optional Position along the waveguide, m. Returns ------- numpy.ndarray ``alpha = 2 omega Im(n_eff) / c`` in 1/m, shape ``(n_omega,)``. Positive is loss, because ``Im n_eff > 0`` is. Examples -------- >>> import numpy as np >>> from solprop.modes import MarcatiliMode >>> from solprop.modes.base import alpha >>> mode = MarcatiliMode(125e-6, "He", 1.0) >>> f"{alpha(mode, np.array([2.356e15]))[0]:.6f}" '0.141459' """ values = _as_omega(omega) return np.asarray(2.0 * values * np.imag(mode.neff(values, z)) / C)
[docs] def beta1( mode: Mode, omega: Float[np.ndarray, " n_omega"], z: float = 0.0 ) -> Float[np.ndarray, " n_omega"]: """Return the group delay per unit length, analytically. Parameters ---------- mode : Mode The mode. omega : numpy.ndarray Angular frequencies in rad/s, shape ``(n_omega,)``. z : float, optional Position along the waveguide, m. Returns ------- numpy.ndarray ``beta_1 = d(beta)/d(omega) = (Re n_eff + omega d(Re n_eff)/d(omega)) / c`` in s/m, shape ``(n_omega,)``, from the mode's analytic derivative. Examples -------- >>> import numpy as np >>> from solprop.modes import MarcatiliMode >>> from solprop.modes.base import beta1 >>> mode = MarcatiliMode(125e-6, "He", 1.0) >>> f"{beta1(mode, np.array([2.356e15]))[0]:.10e}" '3.3357582351e-09' """ values = _as_omega(omega) index = np.real(mode.neff(values, z)) derivative = np.real(mode.dneff_domega(values, z)) return np.asarray((index + values * derivative) / C)
[docs] def beta2( mode: Mode, omega: Float[np.ndarray, " n_omega"], z: float = 0.0 ) -> Float[np.ndarray, " n_omega"]: """Return the group-velocity dispersion, by differencing the analytic `beta1`. Departs from the analytic derivatives elsewhere in this module, and says so: the second derivative of a gas susceptibility is not part of the material interface, so this is a Richardson-extrapolated central difference of :func:`beta1` at a relative step of :data:`BETA2_RELATIVE_STEP`, whose documentation gives the measured accuracy. Only the co-moving frame needs better -- which uses ``beta1``, not this. Parameters ---------- mode : Mode The mode. omega : numpy.ndarray Angular frequencies in rad/s, shape ``(n_omega,)``, > 0. z : float, optional Position along the waveguide, m. Returns ------- numpy.ndarray ``beta_2 = d^2(beta)/d(omega)^2`` in s^2/m, shape ``(n_omega,)``. Raises ------ ModeError If any frequency is not finite or not positive, since the step is relative. Examples -------- >>> import numpy as np >>> from solprop.modes import MarcatiliMode >>> from solprop.modes.base import beta2 >>> mode = MarcatiliMode(125e-6, "He", 1.0) >>> f"{beta2(mode, np.array([2.356e15]))[0]:.6e}" '-7.491419e-30' """ values = _as_omega(omega) if np.any(values <= 0.0): raise ModeError( "beta2 differences beta1 with a relative step, so the frequency must be " "positive" ) step = BETA2_RELATIVE_STEP * values wide = (beta1(mode, values + step, z) - beta1(mode, values - step, z)) / ( 2.0 * step ) half = step / 2.0 narrow = (beta1(mode, values + half, z) - beta1(mode, values - half, z)) / ( 2.0 * half ) return np.asarray((4.0 * narrow - wide) / 3.0)
[docs] def beta3( mode: Mode, omega: Float[np.ndarray, " n_omega"], z: float = 0.0 ) -> Float[np.ndarray, " n_omega"]: """Return the third-order dispersion, by differencing the analytic `beta1` twice. A Richardson-extrapolated second central difference of :func:`beta1` at a relative step of :data:`BETA3_RELATIVE_STEP`, for the reason :func:`beta2` gives: the material interface has no higher derivative of a gas susceptibility. Parameters ---------- mode : Mode The mode. omega : numpy.ndarray Angular frequencies in rad/s, shape ``(n_omega,)``, > 0. z : float, optional Position along the waveguide, m. Returns ------- numpy.ndarray ``beta_3 = d^3(beta)/d(omega)^3`` in s^3/m, shape ``(n_omega,)``. Raises ------ ModeError If any frequency is not finite or not positive, since the step is relative. Examples -------- >>> import numpy as np >>> from solprop.modes import MarcatiliMode >>> from solprop.modes.base import beta3 >>> mode = MarcatiliMode(125e-6, "He", 1.0) >>> f"{beta3(mode, np.array([2.356e15]))[0]:.3e}" '1.124e-44' """ values = _as_omega(omega) if np.any(values <= 0.0): raise ModeError( "beta3 differences beta1 with a relative step, so the frequency must be " "positive" ) centre = beta1(mode, values, z) step = BETA3_RELATIVE_STEP * values wide = _second_difference(mode, values, centre, step, z) narrow = _second_difference(mode, values, centre, step / 2.0, z) return np.asarray((4.0 * narrow - wide) / 3.0)
def _second_difference( mode: Mode, omega: Float[np.ndarray, " n_omega"], centre: Float[np.ndarray, " n_omega"], step: Float[np.ndarray, " n_omega"], z: float, ) -> Float[np.ndarray, " n_omega"]: """Return the central second difference of `beta1` at one step. - ``omega``: angular frequencies in rad/s. - ``centre``: ``beta1`` at `omega`, s/m. - ``step``: the step at each frequency, rad/s. - ``z``: position along the waveguide, m. - Returns: the difference, s^3/m. """ above = beta1(mode, omega + step, z) below = beta1(mode, omega - step, z) return np.asarray((above - 2.0 * centre + below) / step**2) def _refine_zero(mode: Mode, low: float, high: float, z: float) -> float: """Return a sign change of the dispersion inside a bracket, by array samples. A mode's index models evaluate an array at about the cost of one point, so each round narrows the bracket 16-fold for the cost of one Brent step, where a scalar search costs a glass model evaluation per iterate. The rounds stop short of a pole of the differenced ``beta2``, which a scalar search converges onto until the model returns NaN. - ``low``, ``high``: the bracket, rad/s, whose ends have ``beta2`` of opposite signs. - ``z``: position along the waveguide, m. - Returns: the first sign change upwards in frequency, rad/s, linearly interpolated in the last bracket; or NaN when samples that are not finite separate the signs. """ first = last = math.nan for _ in range(_ZDW_REFINE_ROUNDS): grid = np.linspace(low, high, _ZDW_REFINE_SAMPLES) sampled = beta2(mode, grid, z) crossing = np.flatnonzero(np.sign(sampled[:-1]) * np.sign(sampled[1:]) <= 0.0) if crossing.size == 0: return math.nan i = int(crossing[0]) low, high = float(grid[i]), float(grid[i + 1]) # The first change has a nonzero sample below it, so the two cannot be equal. first, last = float(sampled[i]), float(sampled[i + 1]) return low - first * (high - low) / (last - first) def _stencil_delays(mode: Mode, omega: float, z: float) -> Float[np.ndarray, " 5"]: """Return the analytic `beta1` across the stencil of `beta2` at a frequency. The five frequencies ``omega (1 + s h)`` for ``s`` in -1, -1/2, 0, 1/2, 1 and ``h`` :data:`BETA2_RELATIVE_STEP` that span the difference behind :func:`beta2`; s/m. """ offsets = BETA2_RELATIVE_STEP * np.array([-1.0, -0.5, 0.0, 0.5, 1.0]) return beta1(mode, omega * (1.0 + offsets), z) def _is_zero(delays: Float[np.ndarray, " 5"]) -> bool: """Whether a refined sign change of the differenced `beta2` is a zero of it. - ``delays``: ``beta1`` across the stencil at the change (:func:`_stencil_delays`). At a zero of ``beta_2`` that the difference resolves, ``beta1`` is strictly extremal there and its Taylor series converges across the stencil, so its rise from the centre is quadratic: four times as large at a full step as at a half step, on each side. A factor of two either way (:data:`_ZDW_STENCIL_RATIO`) admits a cubic term up to two thirds of the quadratic one at the full step. Each artefact of a resonance fails it: a pole at the change (``beta1`` diverges, its rise does not grow with the step), a stencil point on or across a line (the rise is lopsided, or one-signed through the centre so ``beta1`` is monotone), and the evanescent floor (``beta1`` constant, no rise). So does a feature narrower than the stencil. A non-finite ``beta1`` fails every comparison. """ rise = delays - delays[2] half, full = rise[[1, 3]], rise[[0, 4]] if not half[0] * half[1] > 0.0: return False ratio = full / half low, high = _ZDW_STENCIL_RATIO return bool(np.all((ratio >= low) & (ratio <= high))) def _is_line(delays: Float[np.ndarray, " 5"]) -> bool: """Whether a sign change that is not a zero lies at a line, which blocks the search. - ``delays``: ``beta1`` across the stencil at the change (:func:`_stencil_delays`). At a line the group delay is not finite, or diverges, or drops to the evanescent floor: it spreads across the stencil by more than :data:`_ZDW_LINE_SPREAD` of its value at the change. A smooth feature, the dispersion of an absorption band or of an antiresonant wall, leaves it finite and continuous, and light crosses it. """ spread = np.max(np.abs(delays - delays[2])) return not spread <= _ZDW_LINE_SPREAD * abs(float(delays[2])) def _is_isolated(mode: Mode, omega: float, z: float) -> bool: """Whether a zero of `beta2` is its only one within the resolution scale. The analytic ``beta1`` is read at :data:`_ZDW_ISOLATION_SAMPLES` frequencies on each side, out to a relative distance :data:`_ZDW_ISOLATION`, on a grid fixed relative to the zero, so the answer does not depend on the search window. The zero is isolated when ``beta1`` rises (or falls) monotonically from it on both sides: an extremum with no other sign change of ``beta_2`` beside it. A value that is not finite fails it. """ reach = _ZDW_ISOLATION * np.linspace(0.0, 1.0, _ZDW_ISOLATION_SAMPLES + 1) delays = beta1(mode, omega * (1.0 + np.concatenate([-reach[::-1], reach[1:]])), z) middle = _ZDW_ISOLATION_SAMPLES # Steps outwards from the zero on each side, all of one sign at an extremum. steps = np.concatenate([-np.diff(delays[: middle + 1]), np.diff(delays[middle:])]) return bool(np.all(steps > 0.0) or np.all(steps < 0.0)) def _zero_frequencies( mode: Mode, z: float, lower: float, upper: float, near: float | None ) -> tuple[list[float], int]: """Return the zeros of `beta2` in a frequency window, and its sign changes there. ``beta2`` is sampled at :data:`_ZDW_SAMPLES` frequencies evenly spaced across the window and each sign change is refined (:func:`_refine_zero`); a sample that is exactly zero between samples of opposite signs is a change too. A change is a zero if ``beta1`` has a resolved extremum there (:func:`_is_zero`) and no other change lies within the resolution scale (:func:`_is_isolated`). A change that is not a zero is a line if ``beta1`` is not finite or not continuous across it (:func:`_is_line`, or a bracket the refinement finds no finite change in); anything else -- an unresolved or clustered change of a smooth feature -- is passed over. With a reference frequency ``near``, the changes are taken outwards from it and only the nearest zero is returned; the changes beyond a line on that side are not taken: light at the reference cannot cross the line to reach them. A change further than the best zero so far cannot beat it, which spares the dozens an antiresonant fibre's resonances give. - ``lower``, ``upper``: the window, rad/s. - ``near``: reference frequency, rad/s, or ``None`` for every zero. - Returns: the zeros in rad/s, increasing, and the number of sign changes sampled. """ grid = np.linspace(lower, upper, _ZDW_SAMPLES) zeros: list[float] = [] # The nearest lines found below and above the reference, rad/s. below, above = -math.inf, math.inf # The window is probed, not answered: a model's range and dilute-scaling warnings # are left to the caller's evaluation at the answer. The refinement converges onto # a pole as readily as onto a zero, and a model may divide by zero exactly there. with ( warnings.catch_warnings(), np.errstate(divide="ignore", invalid="ignore"), ): warnings.simplefilter("ignore", MaterialRangeWarning) warnings.simplefilter("ignore", DiluteScalingWarning) sampled = beta2(mode, grid, z) # A sample that is exactly zero takes the sign of the last nonzero sample below # it, so a zero that falls on a sample is a change in the interval above it and # not two products of zero. One that only touches zero changes nothing. signs = np.sign(sampled) last = np.maximum.accumulate(np.where(signs != 0.0, np.arange(signs.size), 0)) signs = signs[last] changes = np.flatnonzero(signs[:-1] * signs[1:] < 0.0) if near is not None: # How near each bracket can bring a zero: 0 for one holding the reference. reach = np.maximum.reduce( [grid[changes] - near, near - grid[changes + 1], np.zeros(changes.size)] ) changes = changes[np.argsort(reach, kind="stable")] for i in changes: low, high = float(grid[i]), float(grid[i + 1]) if near is not None: best = min((abs(zero - near) for zero in zeros), default=math.inf) if max(low - near, near - high) >= best: break if high <= below or low >= above: continue root = _refine_zero(mode, low, high, z) delays = None if math.isnan(root) else _stencil_delays(mode, root, z) if delays is None or not _is_zero(delays): if near is not None and (delays is None or _is_line(delays)): if low >= near: above = low elif high <= near: below = high continue if _is_isolated(mode, root, z): zeros.append(root) if near is not None: # The nearest; of two as near, the one found first. zeros = sorted(zeros, key=lambda zero: abs(zero - near))[:1] return sorted(zeros), int(changes.size)
[docs] def zdw( mode: Mode, z: float = 0.0, *, wavelength_limits: tuple[float, float] = (150e-9, 3e-6), near: float | None = None, ) -> float: """Return the zero-dispersion wavelength of a mode. A sampled search (``docs/guide/waveguides/mode-sets.md``): ``beta_2`` is read at 512 frequencies evenly spaced across the window and each sign change is refined. A change is a **zero** when the analytic group delay ``beta_1`` has an extremum there that the difference behind ``beta_2`` resolves (its rise grows quadratically across the difference's stencil, :data:`BETA2_RELATIVE_STEP` either side) and when ``beta_1`` is monotone from it for 1.5 % in frequency on either side, so that ``beta_2`` keeps each sign that far. A change that is not a zero is a **line** when ``beta_1`` is not finite or not continuous across it -- it diverges, or drops to the evanescent floor, by more than a tenth across the stencil -- as at a gas resonance. Every other change is passed over, neither zero nor line: a change the stencil does not resolve, or one of the clustered zeros of a narrow feature that leaves ``beta_1`` finite and continuous, such as fused silica's OH absorption bands near 1.38 and 2.7 um or the inside of an antiresonant wall's resonance. So the search resolves dispersion regimes 1.5 % wide and more, and its answer does not depend on the window, as long as the window holds the zero. Two limits remain: two genuine zeros closer than 1.5 % (or a zero within 1.5 % of another sign change) are passed over, and a zero and another sign change inside one sample interval restore the sign and are both missed. Parameters ---------- mode : Mode The mode. z : float, optional Position along the waveguide, m. wavelength_limits : tuple of float, optional Shortest and longest wavelength in m to search. Defaults to 150 nm to 3 um: above the vacuum-ultraviolet lines of the noble gases (the longest, xenon's, at 147 nm) and the absorption edge of fused silica, where a lossless solve takes silica as transparent and finds zeros with no meaning. The window is probed silently; the zero found is evaluated again, so one that lies outside the validity range of a material model behind the mode warns. near : float, optional Reference wavelength in m, > 0, typically the pump's. The zero nearest it in frequency is returned, among those no line separates from it: light at the reference cannot cross a line to reach a zero beyond. ``None`` (the default) takes every zero in the window, and refuses several. Returns ------- float The wavelength in m where ``beta_2`` vanishes. Raises ------ ModeError If the range is not ordered and positive, if `near` is not a positive finite wavelength, or if the window holds several zeros and `near` is ``None``: the message lists them. NoZeroDispersionError If the search finds no zero in the window (on the side of the lines that holds `near`, when it is given): a mode with no zero-dispersion point there is a fact the caller has to see, not a missing value to propagate. Examples -------- >>> from solprop.modes import MarcatiliMode >>> from solprop.modes.base import zdw >>> mode = MarcatiliMode(125e-6, "He", 0.4, model="reduced", cladding=1.45) >>> f"{zdw(mode, wavelength_limits=(150e-9, 900e-9)) * 1e9:.1f}" '376.7' """ shortest, longest = wavelength_limits if not 0.0 < shortest < longest: raise ModeError( f"wavelength_limits must be positive and ordered, got {wavelength_limits}" ) if near is not None and not (math.isfinite(near) and near > 0.0): raise ModeError(f"near must be a positive, finite wavelength in m, got {near}") window = f"{shortest * 1e9:.4g}-{longest * 1e9:.4g} nm" zeros, changes = _zero_frequencies( mode, z, 2.0 * math.pi * C / longest, 2.0 * math.pi * C / shortest, None if near is None else 2.0 * math.pi * C / near, ) if not zeros: sampled = f"{_ZDW_SAMPLES} samples over {window}" if changes == 0: found = f"beta2 does not change sign between the {sampled}" elif near is None: found = ( f"beta2 changes sign {changes} times between the {sampled}, but none " "is a zero: each is a line, an artefact of the differenced beta2 at " "one, or one of the clustered zeros of a narrow feature" ) else: found = ( f"beta2 changes sign {changes} times between the {sampled}, but none " f"is a zero between the lines nearest {near * 1e9:.4g} nm" ) raise NoZeroDispersionError( f"{found}, so the search found no zero-dispersion wavelength there" ) if len(zeros) > 1: listed = ", ".join( f"{2.0 * math.pi * C / root * 1e9:.1f}" for root in reversed(zeros) ) raise ModeError( f"beta2 has {len(zeros)} zeros over {window}, at {listed} nm; pass near= " "a reference wavelength to choose the nearest, or narrow wavelength_limits" ) # Outside the probing, so a zero beyond a material model's range warns. beta(mode, np.array([zeros[0]]), z) return 2.0 * math.pi * C / zeros[0]
[docs] def loss_length( mode: Mode, omega: Float[np.ndarray, " n_omega"], z: float = 0.0 ) -> Float[np.ndarray, " n_omega"]: """Return the 1/e power loss length of a mode. Parameters ---------- mode : Mode The mode. omega : numpy.ndarray Angular frequencies in rad/s, shape ``(n_omega,)``. z : float, optional Position along the waveguide, m. Returns ------- numpy.ndarray ``1 / alpha`` in m, shape ``(n_omega,)``; infinite where the mode is lossless. Examples -------- >>> import numpy as np >>> from solprop.modes import MarcatiliMode >>> from solprop.modes.base import loss_length >>> mode = MarcatiliMode(125e-6, "He", 1.0) >>> f"{loss_length(mode, np.array([2.356e15]))[0]:.4f}" '7.0692' """ with np.errstate(divide="ignore"): return np.asarray(1.0 / alpha(mode, omega, z))
[docs] def db_per_m( mode: Mode, omega: Float[np.ndarray, " n_omega"], z: float = 0.0 ) -> Float[np.ndarray, " n_omega"]: """Return the loss of a mode in decibels per metre. Parameters ---------- mode : Mode The mode. omega : numpy.ndarray Angular frequencies in rad/s, shape ``(n_omega,)``. z : float, optional Position along the waveguide, m. Returns ------- numpy.ndarray ``10 alpha / ln(10)`` in dB/m, shape ``(n_omega,)``. Examples -------- >>> import numpy as np >>> from solprop.modes import MarcatiliMode >>> from solprop.modes.base import db_per_m >>> mode = MarcatiliMode(125e-6, "He", 1.0) >>> f"{db_per_m(mode, np.array([2.356e15]))[0]:.6f}" '0.614348' """ return np.asarray(_DECIBEL_PER_NEPER * alpha(mode, omega, z))
[docs] def transmission( mode: Mode, omega: Float[np.ndarray, " n_omega"], length: float, start: float = 0.0, ) -> Float[np.ndarray, " n_omega"]: """Return the power transmission of a length of waveguide. Parameters ---------- mode : Mode The mode. omega : numpy.ndarray Angular frequencies in rad/s, shape ``(n_omega,)``. length : float Length propagated in m, >= 0. start : float, optional Position the length starts at, m. Returns ------- numpy.ndarray ``exp(-int alpha dz)`` over ``[start, start + length]``, shape ``(n_omega,)``. The integral is taken numerically because a taper or a gradient makes ``alpha`` a function of position; for a uniform waveguide it is exactly ``exp(-alpha L)``. Raises ------ ModeError If `length` is negative. Examples -------- >>> import numpy as np >>> from solprop.modes import MarcatiliMode >>> from solprop.modes.base import transmission >>> mode = MarcatiliMode(125e-6, "He", 1.0) >>> f"{transmission(mode, np.array([2.356e15]), 1.0)[0]:.6f}" '0.868091' """ values = _as_omega(omega) if length < 0.0: raise ModeError(f"a propagation length must not be negative, got {length}") if length == 0.0: return np.ones_like(values) integral = quad_vec( lambda position: alpha(mode, values, position), start, start + length )[0] return np.asarray(np.exp(-integral))
[docs] def aeff(mode: Mode, z: float = 0.0) -> float: """Return the effective area of a mode. A uniform accessor beside :func:`beta` and :func:`alpha`, so that code working over a mode set never has to mix method calls with function calls. Parameters ---------- mode : Mode The mode. z : float, optional Position along the waveguide, m. Returns ------- float ``A_eff`` in m^2. Examples -------- >>> from solprop.modes import MarcatiliMode >>> from solprop.modes.base import aeff >>> f"{aeff(MarcatiliMode(75e-6, 'He', 1.0)):.6e}" '8.421575e-09' """ return mode.aeff(z)