solprop.modes.collection#

Ordered, validated sets of modes, and the overlaps between them.

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 (polarisation_pairs()). transverse_measure() names the measure a set is integrated over.

overlap() integrates adaptively (scipy.integrate.dblquad(), or scipy.integrate.quad() over x alone, per metre of y, for a slab set), and orthonormality() integrates the whole matrix in one pass, adaptively in the first coordinate with scipy.integrate.quad_vec() and on a rule refined to convergence in the second – both deliberately not on the fixed rule whose orthonormality they check. They use the package normalisation (docs/dev/conventions.md section 4), \(\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.

Functions

orthonormality(modes[, z])

Return the matrix of normalised overlaps of a mode set.

overlap(first, second[, z])

Return the normalised overlap integral of two modes.

polarisation_pairs(modes)

Expand a mode set so that each degenerate mode carries both polarisations.

transverse_measure(modes)

Return what a mode set's transverse integrals measure, refusing a mixture.

Classes

ModeCollection(modes)

An ordered set of modes sharing one cross-section.

class solprop.modes.collection.ModeCollection(modes)[source]#

Bases: 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:
modessequence 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.

property azimuthal_order: int[source]#

Highest azimuthal order in the set.

The bound that fixes how many azimuthal nodes a quartic product needs, n_theta >= 4 h + 1.

property channel_labels: tuple[ChannelLabel, ...][source]#

Each member’s physical label, in the order of the mode axis.

The members’ own 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']
dimlimits(z=0.0)[source]#

Return the cross-section the whole set shares.

Parameters:
zfloat, optional

Position along the waveguide, m.

Returns:
tuple

As 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'
classmethod he1m(radius, gas=None, pressure=0.0, *, count=1, model='full', alpha=None, loss_scale=1.0, cladding=None, temperature=None, susceptibility=None, mixture=None)[source]#

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 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:
radiusfloat or ZProfile

Core radius, m, constant or along z.

gasGas, str or None, optional

Filling gas; None for vacuum or an explicit mixture.

pressurefloat or ZProfile, optional

Fill pressure, bar, constant or along z; default zero.

countint, 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.

alphafloat, callable or None, optional

Absolute power attenuation in 1/m replacing the model’s loss.

loss_scalefloat, optional

Factor on the model’s own loss; 0 is lossless.

claddingGlassIndex, complex or None, optional

The cladding index; None is the package default silica.

temperaturefloat, ZProfile or None, optional

Gas temperature, K, or a path of it along z; None is room temperature, or the mixture’s own.

susceptibilityGasSusceptibility or None, optional

A susceptibility to use in place of the built-in gas’s.

mixtureMixture 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)
classmethod marcatili(radius, gas=None, pressure=0.0, *, kinds, n, m, model='full', alpha=None, loss_scale=1.0, cladding=None, temperature=None, susceptibility=None, mixture=None)[source]#

Build an ordered mixture of hybrid and transverse capillary modes.

Parameters:
radiusfloat or ZProfile

Core radius, m, constant or along z.

gasGas, str or None, optional

Filling gas; None for vacuum or an explicit mixture.

pressurefloat or ZProfile, optional

Fill pressure, bar, constant or along z; default zero.

kindssequence of {‘HE’, ‘TE’, ‘TM’}

Family of each mode, non-empty.

nsequence of int

Azimuthal indices, one per family; nonzero for HE and zero for TE/TM.

msequence of int

Positive radial indices, one per family.

model{‘full’, ‘reduced’}, optional

Marcatili approximation used by every mode.

alphafloat, callable or None, optional

Absolute power attenuation in 1/m replacing the model’s loss.

loss_scalefloat, optional

Factor on the model’s own loss; 0 is lossless.

claddingGlassIndex, complex or None, optional

Cladding index; None selects the package default silica.

temperaturefloat, ZProfile or None, optional

Gas temperature, K, positive, or a path of it along z; None is room temperature, or the mixture’s own.

susceptibilityGasSusceptibility or None, optional

Explicit susceptibility in place of the selected fit.

mixtureMixture 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 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)
modes: Sequence[Mode]#
property needs_full_rule: bool[source]#

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.

orthonormality(z=0.0)[source]#

Return the matrix of normalised overlaps of the set.

Parameters:
zfloat, 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
property scale_invariant: bool[source]#

Whether every mode rescales with the core radius.

True when the transform may rescale its matrices along a taper rather than rebuilding them.

classmethod slab(half_gap, gas=None, pressure=0.0, *, orders=(1,), polarisation='te', alpha=None, loss_scale=1.0, cladding=None, temperature=None, susceptibility=None, mixture=None)[source]#

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 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 with_polarisations(): each is a distinct mode with its own row.

Parameters:
half_gapfloat or ZProfile

Half the plate separation in m, constant or along z.

gasGas, str or None, optional

Filling gas; None for vacuum or an explicit mixture.

pressurefloat or ZProfile, optional

Gas pressure in bar, constant or along z; default zero.

orderssequence 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.

alphafloat, callable or None, optional

Absolute power attenuation in 1/m replacing the model’s loss.

loss_scalefloat, optional

Factor on the model’s own loss; 0 is lossless.

claddingGlassIndex, complex or None, optional

Plate index; None selects the default silica.

temperaturefloat, ZProfile or None, optional

Gas temperature in K, or a path of it along z; None is room temperature, or the mixture’s own.

susceptibilityGasSusceptibility or None, optional

Explicit gas susceptibility.

mixtureMixture 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)
property transverse_measure: Literal['area', 'per_unit_width'][source]#

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 (transverse_measure()).

classmethod vincetti(radius, gas=None, pressure=0.0, *, count=1, lattice, alpha=None, loss_scale=1.0, cladding=None, temperature=None, susceptibility=None, mixture=None)[source]#

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:
radiusfloat or ZProfile

Positive core radius in m, constant or along z.

gasGas, str or None, optional

Filling gas; None for vacuum or an explicit mixture.

pressurefloat or ZProfile, optional

Gas pressure in bar, constant or along z; default zero.

countint, optional

Number of modes, at least one, in radial order.

latticeTubeLattice

Tube geometry shared by all modes.

alphafloat, callable or None, optional

Absolute power attenuation in 1/m replacing the model’s loss.

loss_scalefloat, optional

Factor on the model’s own loss; 0 is lossless.

claddingGlassIndex, complex or None, optional

Tube index; None selects the default silica.

temperaturefloat, ZProfile or None, optional

Gas temperature in K, or a path of it along z; None is room temperature, or the mixture’s own.

susceptibilityGasSusceptibility or None, optional

Explicit gas susceptibility.

mixtureMixture 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.

classmethod with_polarisations(modes)[source]#

Build a collection carrying both polarisations of every degenerate mode.

Parameters:
modessequence of Mode

The spatial modes.

Returns:
ModeCollection

The expanded set, in the fixed order of 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
property z_constant: bool[source]#

Whether nothing in the set varies along z.

True only when every mode says so.

solprop.modes.collection.orthonormality(modes, z=0.0)[source]#

Return the matrix of normalised overlaps of a mode set.

Parameters:
modessequence of Mode

The modes, non-empty.

zfloat, optional

Position along the waveguide, m.

Returns:
numpy.ndarray

Shape (n_modes, n_modes), symmetric, the identity for an orthonormal set; each entry the 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 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 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
solprop.modes.collection.overlap(first, second, z=0.0)[source]#

Return the normalised overlap integral of two modes.

Parameters:
first, secondMode

The modes, which must share a cross-section.

zfloat, optional

Position along the waveguide, m.

Returns:
float

1 for a mode with itself and 0 for an orthogonal pair. 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, or either has no closed-form normalisation.

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'
solprop.modes.collection.polarisation_pairs(modes)[source]#

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:
modessequence of Mode

The spatial modes.

Returns:
tuple of Mode

The expanded set.

Raises:
ModeError

If a mode cannot say whether it has a partner, which every ported mode can.

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')
solprop.modes.collection.transverse_measure(modes)[source]#

Return what a mode set’s transverse integrals measure, refusing a mixture.

Parameters:
modessequence 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 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" (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'