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.
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, and 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),
\(\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
|
Return the matrix of normalised overlaps of a mode set. |
|
Return the normalised overlap integral of two modes. |
|
Expand a mode set so that each degenerate mode carries both polarisations. |
|
Return what a mode set's transverse integrals measure, refusing a mixture. |
Classes
|
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 isNone, never a string standing for one: an axially symmetric TE0m or TM0m channel has no parity partner, so its parity isNone, 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:
- 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=None, *, 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, ZProfile or None, optional
Fill pressure, bar, constant or along z; required beside gas, and
Nonewithout one.- 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;
Noneis the package default silica.- temperaturefloat, ZProfile or None, optional
Gas temperature, K, or a path of it along z;
Noneis 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=None, *, 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, ZProfile or None, optional
Fill pressure, bar, constant or along z; required beside gas, and
Nonewithout one.- 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;
Noneselects the package default silica.- temperaturefloat, ZProfile or None, optional
Gas temperature, K, positive, or a path of it along z;
Noneis 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. Usewith_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)
- property needs_full_rule: bool[source]#
Whether the azimuthal coordinate has to be resolved.
Falsefor a set whose products are azimuthally symmetric – any set ofHE_1mmodes – which then needs the radial rule alone, and for a slab set, which is uniform in y;Trueotherwise.
- 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.
Truewhen the transform may rescale its matrices along a taper rather than rebuilding them.
- classmethod slab(half_gap, gas=None, pressure=None, *, 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 isSlabMode’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 usewith_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, ZProfile or None, optional
Gas pressure in bar, constant or along z; required beside gas, and
Nonewithout one.- 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;
Noneis 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=None, *, 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, ZProfile or None, optional
Gas pressure in bar, constant or along z; required beside gas, and
Nonewithout one.- 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;
Noneis 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
- 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 theoverlap()of its pair to about1e-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 (
rorx) withscipy.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 than1e-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 ofoverlap()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
1for a mode with itself and0for an orthogonal pair: the off-diagonal entry of the pair’sorthonormality(), to about1e-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'
- 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_0morTM_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.
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_measuretrait by name; a mode without it takes the measure of the mode it was built from – asolprop.nonlinear.gnlse.SpecifiedModemade 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'