# SPDX-FileCopyrightText: 2026 John C. Travers and contributors
#
# SPDX-License-Identifier: GPL-3.0-or-later
r"""Ordered, validated sets of modes, and the overlaps between them.
:class:`ModeCollection` is the set of modes a multimode run propagates through one
transverse rule and one pair of transform matrices: ordered, because the kernel's mode
axis is, and validated once to share a cross-section. It reports whether the azimuthal
coordinate has to be resolved and to what order, and expands a spatial set into its
polarisation partners (:func:`polarisation_pairs`). :func:`transverse_measure` names
the measure a set is integrated over.
:func:`orthonormality` integrates the whole matrix in one pass, adaptively in the
first coordinate with :func:`scipy.integrate.quad_vec` and on a rule refined to
convergence in the second, and :func:`overlap` is its entry for one pair --
deliberately *not* on the fixed rule whose orthonormality they check. They use the
package normalisation (``docs/dev/conventions.md`` section 4),
:math:`\langle m_1|m_2\rangle = \tfrac12\sqrt{\varepsilon_0/\mu_0}\int e_1^*\cdot
e_2\,\mathrm{d}A / \sqrt{N_1N_2}`, so a mode overlaps itself by one. The manual page is
``docs/guide/waveguides/mode-sets.md``.
"""
import logging
from collections.abc import Iterator, Sequence
from dataclasses import dataclass
from typing import cast
import numpy as np
from jaxtyping import Float
from scipy.integrate import quad_vec
from solprop._display import Displayed
from solprop.constants import EPS0, C
from solprop.exceptions import ModeError
from solprop.modes.antiresonant import TubeLattice, VincettiMode
from solprop.modes.capillary import (
MarcatiliMode,
MarcatiliModel,
ModeKind,
)
from solprop.modes.fill import LossFunction
from solprop.modes.protocol import (
ChannelLabel,
CrossSection,
Mode,
TransverseMeasure,
)
from solprop.modes.quadrature import _normalisation, _shared_limits
from solprop.modes.slab import SlabMode, SlabPolarisation
from solprop.physdata.gases import Gas
from solprop.physdata.glasses import GlassIndex
from solprop.physdata.mixtures import Mixture
from solprop.physdata.sellmeier import GasSusceptibility
from solprop.profiles import ZProfile
__all__ = [
"ModeCollection",
"orthonormality",
"overlap",
"polarisation_pairs",
"transverse_measure",
]
logger = logging.getLogger(__name__)
_GRAM_TOLERANCE = 1e-12
"""Absolute tolerance on each normalised overlap of :func:`orthonormality`: of the
adaptive integral in the first coordinate, and of the change on doubling the rule in
the second. Far below the driver's acceptance of a set (1e-6)."""
_FIRST_NODES = 16
"""Fewest nodes of the second coordinate's rule before the first doubling; a polar set
starts above its products' highest harmonic (:func:`_first_nodes`)."""
_MAX_NODES = 1024
"""Most nodes of the second coordinate's rule, or four times the first rule if that is
more: a set that needs more is refused."""
[docs]
def overlap(first: Mode, second: Mode, z: float = 0.0) -> float:
"""Return the normalised overlap integral of two modes.
Parameters
----------
first, second : Mode
The modes, which must share a cross-section.
z : float, optional
Position along the waveguide, m.
Returns
-------
float
``1`` for a mode with itself and ``0`` for an orthogonal pair: the
off-diagonal entry of the pair's :func:`orthonormality`, to about ``1e-12``.
Integrated adaptively, not on the transform's fixed rule, so that the rule
can be checked against it.
Raises
------
ModeError
If the modes do not share a cross-section, either has no closed-form
normalisation, or the integration does not converge.
Examples
--------
>>> from solprop.modes import MarcatiliMode
>>> from solprop.modes.collection import overlap
>>> mode = MarcatiliMode(125e-6, "He", 1.0)
>>> f"{overlap(mode, mode):.9f}"
'1.000000000'
"""
return float(orthonormality([first, second], z)[0, 1])
[docs]
def orthonormality(
modes: Sequence[Mode], z: float = 0.0
) -> Float[np.ndarray, "n_modes n_modes"]:
"""Return the matrix of normalised overlaps of a mode set.
Parameters
----------
modes : sequence of Mode
The modes, non-empty.
z : float, optional
Position along the waveguide, m.
Returns
-------
numpy.ndarray
Shape ``(n_modes, n_modes)``, symmetric, the identity for an orthonormal set;
each entry the :func:`overlap` of its pair to about ``1e-12``.
Raises
------
ModeError
If `modes` is empty, the modes do not share a cross-section or one has no
closed-form normalisation, or the integration does not converge in either
coordinate.
Notes
-----
Every entry is integrated in one pass: adaptively in the first coordinate (``r`` or
``x``) with :func:`scipy.integrate.quad_vec`, whose error control covers the whole
matrix, and in the second on an offset periodic trapezoid (polar) or a
Gauss--Legendre rule (Cartesian), doubled until no entry changes by more than
``1e-12``: from 16 nodes, or for a polar set from above twice its highest azimuthal
order, so that no product's harmonic aliases alike in two rules. Each mode's field
is evaluated once per node, not once per pair, so a set of 48 modes takes seconds
rather than the minutes of :func:`overlap` pair by pair. A slab set integrates over
x alone, per metre of y.
Examples
--------
>>> import numpy as np
>>> from solprop.modes import MarcatiliMode
>>> from solprop.modes.collection import orthonormality
>>> modes = [MarcatiliMode(125e-6, "He", 1.0, m=m) for m in (1, 2)]
>>> bool(np.max(np.abs(orthonormality(modes) - np.eye(2))) < 1e-9)
True
"""
if not modes:
raise ModeError("orthonormality needs at least one mode")
kind, lower, upper = _shared_limits(modes, z)
# Each mode's share of the overlap's normalisation, inside the integrand: the
# integrals are then of order one, as the absolute tolerance assumes.
scale = np.sqrt(0.5 * EPS0 * C / np.array([_normalisation(m, z) for m in modes]))
first = (lower[0], upper[0])
if kind == "slab":
# Uniform in y: one node at y = 0 of unit weight, per metre of y as N is.
return _gram(modes, scale, first, (np.zeros(1), np.ones(1)), z=z, polar=False)
nodes = _first_nodes(modes) if kind == "polar" else _FIRST_NODES
# Every set is allowed at least two doublings, so that convergence is shown on
# three rules even where a polar set's first rule reaches the cap.
most = max(_MAX_NODES, 4 * nodes)
previous = None
while nodes <= most:
rule = _second_rule(kind, (lower[1], upper[1]), nodes)
matrix = _gram(modes, scale, first, rule, z=z, polar=kind == "polar")
if (
previous is not None
and np.max(np.abs(matrix - previous)) <= _GRAM_TOLERANCE
):
return matrix
previous = matrix
nodes *= 2
raise ModeError(
f"the overlaps of this {kind} mode set did not converge in the second "
f"coordinate with {most} nodes"
)
def _first_nodes(modes: Sequence[Mode]) -> int:
"""Return the polar rule's first node count, above every product's harmonics.
A pair's product reaches azimuthal degree ``h_a + h_b``, and the offset periodic
trapezoid of N nodes integrates degree k exactly unless N divides k. Started at
or below the degree, two consecutive rules can alias a harmonic alike -- 16 and 32
nodes both read ``cos(64 theta)`` as +1 at every node -- and agree on a wrong
value. The first rule is therefore the smallest power of two above twice the
set's highest order, and at least :data:`_FIRST_NODES`.
"""
degree = 2 * max(mode.azimuthal_order for mode in modes)
nodes = _FIRST_NODES
while nodes <= degree:
nodes *= 2
return nodes
def _second_rule(
kind: CrossSection, limits: tuple[float, float], nodes: int
) -> tuple[Float[np.ndarray, " n_nodes"], Float[np.ndarray, " n_nodes"]]:
"""Return the nodes and weights of the rule in the second coordinate.
Polar: the offset periodic trapezoid over the full circle, exact for trigonometric
polynomials below degree `nodes`; its offset keeps nodes off the axes, where
products such as ``E_x E_y`` vanish (:mod:`solprop.modes.quadrature`). Cartesian:
Gauss--Legendre over the y limits.
"""
low, high = limits
if kind == "polar":
step = (high - low) / nodes
return low + step * (np.arange(nodes) + 0.5), np.full(nodes, step)
x, weights = np.polynomial.legendre.leggauss(nodes)
half = 0.5 * (high - low)
return low + half * (x + 1.0), half * weights
def _gram(
modes: Sequence[Mode],
scale: Float[np.ndarray, " n_modes"],
limits: tuple[float, float],
rule: tuple[Float[np.ndarray, " n_nodes"], Float[np.ndarray, " n_nodes"]],
*,
z: float,
polar: bool,
) -> Float[np.ndarray, "n_modes n_modes"]:
"""Return the normalised overlap matrix on one rule in the second coordinate.
- ``scale``: each mode's ``sqrt(eps0 c / (2 N))``: two scaled fields' product
integrates over the area to the dimensionless overlap.
- ``limits``: the first coordinate's range, m.
- ``polar``: whether the first coordinate is a radius; its Jacobian r is folded in.
"""
second, weights = rule
def _line(first: float) -> Float[np.ndarray, "n_modes n_modes"]:
"""Return the matrix integrand at one value of the first coordinate."""
points = np.column_stack((np.full(second.size, first), second))
fields = np.stack([mode.field(points, z) for mode in modes])
fields = fields * scale[:, None, None]
matrix = np.einsum("mpc,p,npc->mn", fields, weights, fields)
return matrix * first if polar else matrix
matrix, _, info = quad_vec(
_line,
limits[0],
limits[1],
epsabs=_GRAM_TOLERANCE,
epsrel=0.0,
norm="max",
full_output=True,
)
# quad_vec returns its best estimate without a warning when it stops short of the
# tolerance; an unconverged matrix must not pass as an orthonormality check.
if info.status != 0:
raise ModeError(
"the overlaps of this mode set did not converge in the first coordinate: "
f"{info.message}"
)
matrix = np.asarray(matrix)
# Symmetric by construction up to the summation order; made exactly so.
return 0.5 * (matrix + matrix.T)
[docs]
def transverse_measure(modes: Sequence[Mode]) -> TransverseMeasure:
"""Return what a mode set's transverse integrals measure, refusing a mixture.
Parameters
----------
modes : sequence of Mode
The modes, non-empty. Each reports the optional ``transverse_measure``
trait by name; a mode without it takes the measure of the mode it was
built from -- a :class:`solprop.nonlinear.gnlse.SpecifiedMode` made
from a slab mode keeps its source's per-unit-width normalisation and
area -- and measures an area when there is none.
Returns
-------
str
``"area"`` or ``"per_unit_width"``
(:data:`solprop.modes.protocol.TransverseMeasure`).
Raises
------
ModeError
If the set is empty, or mixes a per-unit-width mode with an area mode, whose
powers would be in W/m and W in one state.
Examples
--------
>>> from solprop.modes import MarcatiliMode, SlabMode
>>> from solprop.modes.collection import transverse_measure
>>> transverse_measure([MarcatiliMode(125e-6)])
'area'
>>> transverse_measure([SlabMode(50e-6)])
'per_unit_width'
"""
if not modes:
raise ModeError("a transverse measure needs at least one mode")
measures: list[TransverseMeasure] = [_measure_of(mode) for mode in modes]
for index, measure in enumerate(measures[1:], start=1):
if measure != measures[0]:
raise ModeError(
f"mode {index} ({type(modes[index]).__name__}) measures "
f"{measure!r} but mode 0 ({type(modes[0]).__name__}) measures "
f"{measures[0]!r}: a mode uniform in y carries a power per metre "
"of y and an area mode a power, and one state cannot hold both"
)
return measures[0]
def _measure_of(mode: Mode) -> TransverseMeasure:
"""Return one mode's transverse measure, following the modes it was built from.
The chain is the one :func:`solprop.translate.modal._radius_kinks` walks: a
specified mode keeps its source in its dispersion's ``mode``, and its area --
``aeff()`` of that source unless one was declared -- is in the source's units.
- Returns: the first declared ``transverse_measure`` along the chain, else
``"area"``.
"""
one: object = mode
while one is not None:
declared = getattr(one, "transverse_measure", None)
if declared is not None:
return cast("TransverseMeasure", declared)
one = getattr(getattr(one, "dispersion", None), "mode", None)
return "area"
[docs]
def polarisation_pairs(modes: Sequence[Mode]) -> tuple[Mode, ...]:
"""Expand a mode set so that each degenerate mode carries both polarisations.
A vector run propagates the two orthogonal polarisation states of a hybrid mode as
two entries on the mode axis. The order is fixed and is the obvious one -- each
mode immediately followed by its partner -- because the mode axis of the kernel
state is positional and a reordering would be silent.
A mode with no degenerate partner, such as ``TE_0m`` or ``TM_0m``, is carried once.
Parameters
----------
modes : sequence of Mode
The spatial modes.
Returns
-------
tuple of Mode
The expanded set.
Raises
------
ModeError
If a mode cannot say whether it has a partner.
Examples
--------
>>> from solprop.modes import MarcatiliMode
>>> from solprop.modes.collection import polarisation_pairs
>>> pairs = polarisation_pairs([MarcatiliMode(125e-6, "He", 1.0)])
>>> len(pairs), f"{pairs[1].phi:.4f}"
(2, '1.5708')
"""
expanded: list[Mode] = []
missing = object()
for mode in modes:
partner: Mode | None = getattr(mode, "orthogonal_polarisation", missing) # type: ignore[assignment] - checked immediately below
if partner is missing:
raise ModeError(
f"{type(mode).__name__} does not report an orthogonal polarisation, "
"so a vector mode set cannot be built from it"
)
expanded.append(mode)
if partner is not None:
expanded.append(partner)
return tuple(expanded)
[docs]
@dataclass(frozen=True, eq=False)
class ModeCollection(Displayed, Sequence[Mode]):
"""An ordered set of modes sharing one cross-section.
Validated once, at construction: the mode axis of the kernel state is positional,
and one transform matrix serves the whole set, so a set whose members disagree
about the geometry is not a set.
Attributes
----------
modes : sequence of Mode
The modes, in the order the mode axis will carry them. Any sequence is
accepted and is stored as a tuple, so a collection cannot be changed after it
has been validated.
"""
modes: Sequence[Mode]
def __post_init__(self) -> None:
"""Check that the set is non-empty and shares a cross-section.
Raises
------
ModeError
If the set is empty, mixes a per-unit-width (slab) mode with an area
mode, or the cross-sections disagree at ``z = 0``.
"""
object.__setattr__(self, "modes", tuple(self.modes))
if not self.modes:
raise ModeError("a mode collection needs at least one mode")
transverse_measure(self.modes)
self._validate_channels()
limits = _shared_limits(self.modes, 0.0)
logger.debug(
"mode collection of %d modes, %s, azimuthal order %d, full rule %s",
len(self.modes),
limits[0],
self.azimuthal_order,
self.needs_full_rule,
)
def _validate_channels(self) -> None:
"""Reject two members that name the same physical channel.
Uniqueness is on the members' own :class:`ChannelLabel`, for every family:
the label is what the mode axis carries and what the run record persists,
so two members sharing one is two rows for one channel.
"""
seen: set[ChannelLabel] = set()
for mode in self.modes:
label = mode.channel_label
if label in seen:
raise ModeError(
f"duplicate physical channel {label.display_label}: two members "
"name the same channel, and an axially symmetric TE/TM channel "
"has no parity partner to tell two of them apart"
)
seen.add(label)
[docs]
@property
def channel_labels(self) -> tuple[ChannelLabel, ...]: # numpydoc ignore=RT01
"""Each member's physical label, in the order of the mode axis.
The members' own :attr:`solprop.modes.protocol.Mode.channel_label`, in
order. A label a family does not have is ``None``, never a string
standing for one: an axially symmetric TE0m or TM0m channel has no
parity partner, so its parity is ``None``, exactly as its handedness is.
The run record persists these labels.
Examples
--------
>>> from solprop.modes import MarcatiliMode
>>> from solprop.modes.collection import ModeCollection
>>> modes = ModeCollection([MarcatiliMode(125e-6, "He", 1.0)])
>>> [label.display_label for label in modes.channel_labels]
['HE1,1:even']
"""
return tuple(mode.channel_label for mode in self.modes)
[docs]
@classmethod
def with_polarisations(cls, modes: Sequence[Mode]) -> "ModeCollection":
"""Build a collection carrying both polarisations of every degenerate mode.
Parameters
----------
modes : sequence of Mode
The spatial modes.
Returns
-------
ModeCollection
The expanded set, in the fixed order of :func:`polarisation_pairs`.
Examples
--------
>>> from solprop.modes import MarcatiliMode
>>> from solprop.modes.collection import ModeCollection
>>> modes = [MarcatiliMode(125e-6, "He", 1.0, m=m) for m in (1, 2)]
>>> len(ModeCollection.with_polarisations(modes))
4
"""
return cls(polarisation_pairs(modes))
[docs]
@classmethod
def he1m(
cls,
radius: float | ZProfile,
gas: Gas | str | None = None,
pressure: float | ZProfile | None = None,
*,
count: int = 1,
model: MarcatiliModel = "full",
alpha: float | LossFunction | None = None,
loss_scale: float = 1.0,
cladding: GlassIndex | complex | None = None,
temperature: float | ZProfile | None = None,
susceptibility: GasSusceptibility | None = None,
mixture: Mixture | None = None,
) -> "ModeCollection":
"""Build the first `count` HE_1m modes of one gas-filled capillary.
The linearly polarised hybrid modes of a hollow capillary, in the order of
their radial index. They share a cross-section by construction, their
azimuthal order is zero, so no azimuthal quadrature is needed, and they are
the set a capillary run uses unless told otherwise.
Every keyword after `count` is
:class:`~solprop.modes.capillary.MarcatiliMode`'s own and is given to each
mode unchanged, so a set can carry a test-only cladding or gas susceptibility
the way a single mode can.
Parameters
----------
radius : float or ZProfile
Core radius, m, constant or along z.
gas : Gas, str or None, optional
Filling gas; None for vacuum or an explicit mixture.
pressure : float, ZProfile or None, optional
Fill pressure, bar, constant or along z; required beside `gas`, and
``None`` without one.
count : int, optional
How many modes, at least one; the modes are HE_11 to HE_1count.
model : {'full', 'reduced'}, optional
Which Marcatili model the modes use.
alpha : float, callable or None, optional
Absolute power attenuation in 1/m replacing the model's loss.
loss_scale : float, optional
Factor on the model's own loss; 0 is lossless.
cladding : GlassIndex, complex or None, optional
The cladding index; ``None`` is the package default silica.
temperature : float, ZProfile or None, optional
Gas temperature, K, or a path of it along z; ``None`` is room
temperature, or the mixture's own.
susceptibility : GasSusceptibility or None, optional
A susceptibility to use in place of the built-in gas's.
mixture : Mixture or None, optional
Ordered species and density paths; owns the gas and susceptibility.
Returns
-------
ModeCollection
The validated set, in radial order.
Raises
------
ModeError
If `count` is below one or the modes are invalid.
Examples
--------
>>> from solprop.modes import ModeCollection
>>> modes = ModeCollection.he1m(125e-6, "He", 0.8, count=4)
>>> len(modes), modes[3].m, modes.azimuthal_order
(4, 4, 0)
"""
if count < 1:
raise ModeError(
f"a capillary mode set needs at least one mode, got {count}"
)
return cls(
[
MarcatiliMode(
radius,
gas,
pressure,
kind="HE",
n=1,
m=m,
model=model,
alpha=alpha,
loss_scale=loss_scale,
cladding=cladding,
temperature=temperature,
susceptibility=susceptibility,
mixture=mixture,
)
for m in range(1, count + 1)
]
)
[docs]
@classmethod
def slab(
cls,
half_gap: float | ZProfile,
gas: Gas | str | None = None,
pressure: float | ZProfile | None = None,
*,
orders: Sequence[int] = (1,),
polarisation: SlabPolarisation = "te",
alpha: float | LossFunction | None = None,
loss_scale: float = 1.0,
cladding: GlassIndex | complex | None = None,
temperature: float | ZProfile | None = None,
susceptibility: GasSusceptibility | None = None,
mixture: Mixture | None = None,
) -> "ModeCollection":
"""Build the given orders of one hollow planar guide, uniform in y.
A centred, symmetric launch couples only to odd orders, so the set a
compressor run wants is usually ``(1, 3, 5)``; an offset or tilted launch
needs the even ones too. Every keyword after `orders` is
:class:`~solprop.modes.slab.SlabMode`'s own and is given to each mode
unchanged. For TE and TM rows in one set, build the two polarisations and
pass them to the constructor, or use :meth:`with_polarisations`: each is a
distinct mode with its own row.
Parameters
----------
half_gap : float or ZProfile
Half the plate separation in m, constant or along z.
gas : Gas, str or None, optional
Filling gas; None for vacuum or an explicit mixture.
pressure : float, ZProfile or None, optional
Gas pressure in bar, constant or along z; required beside `gas`, and
``None`` without one.
orders : sequence of int, optional
Mode orders ``p >= 1``, non-empty and without repeats, in state order;
default the lowest order alone.
polarisation : {'te', 'tm'}, optional
``"te"`` (E along y, the default) or ``"tm"`` (E along x), for every
order.
alpha : float, callable or None, optional
Absolute power attenuation in 1/m replacing the model's loss.
loss_scale : float, optional
Factor on the model's own loss; 0 is lossless.
cladding : GlassIndex, complex or None, optional
Plate index; None selects the default silica.
temperature : float, ZProfile or None, optional
Gas temperature in K, or a path of it along z; ``None`` is room
temperature, or the mixture's own.
susceptibility : GasSusceptibility or None, optional
Explicit gas susceptibility.
mixture : Mixture or None, optional
Ordered species and density paths; owns the gas and susceptibility.
Returns
-------
ModeCollection
The validated set, in the order given.
Raises
------
ModeError
If `orders` is empty, repeats an order, or describes an invalid mode.
Examples
--------
>>> from solprop.modes import ModeCollection
>>> modes = ModeCollection.slab(63.5e-6, "Ar", 1.0, orders=(1, 3, 5))
>>> [label.display_label for label in modes.channel_labels]
['TE1', 'TE3', 'TE5']
>>> modes.transverse_measure, modes.needs_full_rule
('per_unit_width', False)
"""
if not orders:
raise ModeError("a slab mode set needs at least one order")
return cls(
tuple(
SlabMode(
half_gap,
gas,
pressure,
order=order,
polarisation=polarisation,
alpha=alpha,
loss_scale=loss_scale,
cladding=cladding,
temperature=temperature,
susceptibility=susceptibility,
mixture=mixture,
)
for order in orders
)
)
[docs]
@classmethod
def vincetti(
cls,
radius: float | ZProfile,
gas: Gas | str | None = None,
pressure: float | ZProfile | None = None,
*,
count: int = 1,
lattice: TubeLattice,
alpha: float | LossFunction | None = None,
loss_scale: float = 1.0,
cladding: GlassIndex | complex | None = None,
temperature: float | ZProfile | None = None,
susceptibility: GasSusceptibility | None = None,
mixture: Mixture | None = None,
) -> "ModeCollection":
"""Build the first `count` HE_1m modes of a tube-lattice fibre.
The field and transverse quadrature remain Marcatili's. Corrections and
loss are fundamental-mode fits; higher radial orders log that limitation.
Parameters
----------
radius : float or ZProfile
Positive core radius in m, constant or along z.
gas : Gas, str or None, optional
Filling gas; None for vacuum or an explicit mixture.
pressure : float, ZProfile or None, optional
Gas pressure in bar, constant or along z; required beside `gas`, and
``None`` without one.
count : int, optional
Number of modes, at least one, in radial order.
lattice : TubeLattice
Tube geometry shared by all modes.
alpha : float, callable or None, optional
Absolute power attenuation in 1/m replacing the model's loss.
loss_scale : float, optional
Factor on the model's own loss; 0 is lossless.
cladding : GlassIndex, complex or None, optional
Tube index; None selects the default silica.
temperature : float, ZProfile or None, optional
Gas temperature in K, or a path of it along z; ``None`` is room
temperature, or the mixture's own.
susceptibility : GasSusceptibility or None, optional
Explicit gas susceptibility.
mixture : Mixture or None, optional
Ordered species and density paths; owns the gas and susceptibility.
Returns
-------
ModeCollection
Validated modes sharing the tube geometry and cross-section.
Raises
------
ModeError
If the mode count or geometry is invalid.
"""
if count < 1:
raise ModeError(f"a Vincetti mode set needs at least one mode, got {count}")
return cls(
tuple(
VincettiMode(
radius,
gas,
pressure,
m=index + 1,
lattice=lattice,
alpha=alpha,
loss_scale=loss_scale,
cladding=cladding,
temperature=temperature,
susceptibility=susceptibility,
mixture=mixture,
)
for index in range(count)
)
)
[docs]
@classmethod
def marcatili(
cls,
radius: float | ZProfile,
gas: Gas | str | None = None,
pressure: float | ZProfile | None = None,
*,
kinds: Sequence[ModeKind],
n: Sequence[int],
m: Sequence[int],
model: MarcatiliModel = "full",
alpha: float | LossFunction | None = None,
loss_scale: float = 1.0,
cladding: GlassIndex | complex | None = None,
temperature: float | ZProfile | None = None,
susceptibility: GasSusceptibility | None = None,
mixture: Mixture | None = None,
) -> "ModeCollection":
"""Build an ordered mixture of hybrid and transverse capillary modes.
Parameters
----------
radius : float or ZProfile
Core radius, m, constant or along z.
gas : Gas, str or None, optional
Filling gas; None for vacuum or an explicit mixture.
pressure : float, ZProfile or None, optional
Fill pressure, bar, constant or along z; required beside `gas`, and
``None`` without one.
kinds : sequence of {'HE', 'TE', 'TM'}
Family of each mode, non-empty.
n : sequence of int
Azimuthal indices, one per family; nonzero for HE and zero for TE/TM.
m : sequence of int
Positive radial indices, one per family.
model : {'full', 'reduced'}, optional
Marcatili approximation used by every mode.
alpha : float, callable or None, optional
Absolute power attenuation in 1/m replacing the model's loss.
loss_scale : float, optional
Factor on the model's own loss; 0 is lossless.
cladding : GlassIndex, complex or None, optional
Cladding index; ``None`` selects the package default silica.
temperature : float, ZProfile or None, optional
Gas temperature, K, positive, or a path of it along z; ``None`` is
room temperature, or the mixture's own.
susceptibility : GasSusceptibility or None, optional
Explicit susceptibility in place of the selected fit.
mixture : Mixture or None, optional
Ordered species and density paths; owns the gas and susceptibility.
Returns
-------
ModeCollection
Modes in the input order, all with ``phi = 0``. Use
:meth:`with_polarisations` to add degenerate partners.
Raises
------
ModeError
If the index sequences are empty, have different lengths, or describe
an invalid mode.
Examples
--------
>>> from solprop.modes import ModeCollection
>>> modes = ModeCollection.marcatili(
... 125e-6, "He", 1.0, kinds=["HE", "HE", "TM"], n=[1, 2, 0], m=[1, 1, 1]
... )
>>> len(modes), modes.azimuthal_order
(3, 1)
"""
if not kinds or len(kinds) != len(n) or len(kinds) != len(m):
raise ModeError(
"kinds, n and m must be non-empty sequences of equal length"
)
return cls(
tuple(
MarcatiliMode(
radius,
gas,
pressure,
kind=kind,
n=azimuthal,
m=radial,
model=model,
alpha=alpha,
loss_scale=loss_scale,
cladding=cladding,
temperature=temperature,
susceptibility=susceptibility,
mixture=mixture,
)
for kind, azimuthal, radial in zip(kinds, n, m, strict=True)
)
)
def __repr__(self) -> str:
"""Return a one-line description: how many modes, and the first of them.
Returns
-------
str
For example ``ModeCollection(4 modes: MarcatiliMode(HE11, ...), ...)``.
"""
count = len(self.modes)
rest = ", ..." if count > 1 else ""
return (
f"ModeCollection({count} mode{'s' * (count != 1)}: {self.modes[0]!r}{rest})"
)
def _describe(self) -> tuple[str, list[tuple[str, object]]]:
"""Return the title and rows of the printed block.
- Returns: the title and ``(key, value)`` rows.
"""
count = len(self.modes)
return f"ModeCollection: {count} mode{'s' * (count != 1)}", [
(str(index), repr(mode)) for index, mode in enumerate(self.modes)
]
def __len__(self) -> int:
"""Return the number of modes.
Returns
-------
int
The size of the mode axis this set implies.
"""
return len(self.modes)
def __getitem__(self, index: int) -> Mode: # type: ignore[override] - positional only; see below
"""Return one mode.
Narrower than :meth:`collections.abc.Sequence.__getitem__`, which also accepts a
slice, because the runtime type checker of the test session enforces the
annotation and a slice would then return a sequence where a mode is declared.
The mode axis is addressed by position everywhere in the package, so nothing
slices a collection.
Parameters
----------
index : int
Position on the mode axis.
Returns
-------
Mode
The mode.
"""
return self.modes[index]
def __iter__(self) -> Iterator[Mode]:
"""Iterate over the modes in order.
Returns
-------
collections.abc.Iterator
The modes.
"""
return iter(self.modes)
[docs]
def dimlimits(
self, z: float = 0.0
) -> tuple[CrossSection, tuple[float, ...], tuple[float, ...]]:
"""Return the cross-section the whole set shares.
Parameters
----------
z : float, optional
Position along the waveguide, m.
Returns
-------
tuple
As :meth:`solprop.modes.protocol.Mode.dimlimits`.
Raises
------
ModeError
If the modes disagree at this position, which a taper of one mode but not
another would cause.
Examples
--------
>>> from solprop.modes import MarcatiliMode
>>> from solprop.modes.collection import ModeCollection
>>> ModeCollection([MarcatiliMode(125e-6, "He", 1.0)]).dimlimits()[0]
'polar'
"""
return _shared_limits(self.modes, z)
[docs]
@property
def azimuthal_order(self) -> int: # numpydoc ignore=RT01
"""Highest azimuthal order in the set.
The bound that fixes how many azimuthal nodes a quartic product needs,
``n_theta >= 4 h + 1``.
"""
return max(mode.azimuthal_order for mode in self.modes)
[docs]
@property
def needs_full_rule(self) -> bool: # numpydoc ignore=RT01
"""Whether the azimuthal coordinate has to be resolved.
``False`` for a set whose products are azimuthally symmetric -- any set of
``HE_1m`` modes -- which then needs the radial rule alone, and for a slab
set, which is uniform in y; ``True`` otherwise.
"""
kind = self.dimlimits()[0]
if kind == "slab":
return False
return self.azimuthal_order > 0 or kind == "cartesian"
[docs]
@property
def transverse_measure(self) -> TransverseMeasure: # numpydoc ignore=RT01
"""What the set's transverse integrals measure.
``"per_unit_width"`` for a slab set, whose powers are W/m and energies
J/m, and ``"area"`` otherwise (:func:`transverse_measure`).
"""
return transverse_measure(self.modes)
[docs]
@property
def z_constant(self) -> bool: # numpydoc ignore=RT01
"""Whether nothing in the set varies along z.
``True`` only when every mode says so.
"""
return all(mode.z_constant for mode in self.modes)
[docs]
@property
def scale_invariant(self) -> bool: # numpydoc ignore=RT01
"""Whether every mode rescales with the core radius.
``True`` when the transform may rescale its matrices along a taper rather
than rebuilding them.
"""
return all(mode.scale_invariant for mode in self.modes)
[docs]
def orthonormality(self, z: float = 0.0) -> Float[np.ndarray, "n_modes n_modes"]:
"""Return the matrix of normalised overlaps of the set.
Parameters
----------
z : float, optional
Position along the waveguide, m.
Returns
-------
numpy.ndarray
Shape ``(n_modes, n_modes)``; the identity for an orthonormal set.
Examples
--------
>>> import numpy as np
>>> from solprop.modes import MarcatiliMode
>>> from solprop.modes.collection import ModeCollection
>>> modes = ModeCollection(
... [MarcatiliMode(125e-6, "He", 1.0, m=m) for m in (1, 2)]
... )
>>> bool(np.max(np.abs(modes.orthonormality() - np.eye(2))) < 1e-9)
True
"""
return orthonormality(self.modes, z)