solprop.modes.vector#

Represent internal-convention Maxwell samples on physical area quadrature.

The records every vector modal provider and table shares: ModalNodeRule (Cartesian nodes, area weights and material regions; radial_node_rule() builds the interface-split polar one), ModalSample (one frequency and position’s E/H, generator and flux metric), the ModalProvider protocol that produces them, and flux_product(), the Hermitian Poynting product. ChannelBasis declares a unitary change of a guide’s degenerate channel coordinates (circular_pair(), read against provider_channels()), unitary to BASIS_UNITARY_ATOL. These physics records do not extend the propagation kernel contract. Bound, lossless modes use the Hermitian Poynting product and true-power amplitudes.

Module Attributes

BASIS_UNITARY_ATOL

Largest norm(U.H U - I, 2) a declared change of basis is still called unitary.

Functions

circular_pair(labels, block)

Declare the circular partners of one exactly degenerate parity pair.

flux_product(electric, magnetic, weights)

Integrate the Hermitian Poynting product.

provider_channels(provider)

Return a provider's declared channels as labels, in its own order.

radial_node_rule(interfaces, outer_radius, ...)

Build interface-split Cartesian nodes from the existing polar panel rule.

Classes

ChannelBasis(transform, blocks, labels, gauge_id)

Declare the unitary coordinates a guide's degenerate channels are given in.

ModalNodeRule(xy, weights, region_index, ...)

Own Cartesian quadrature nodes and their material regions.

ModalProvider(*args, **kwargs)

Supply internal-convention full-vector modes on common physical nodes.

ModalSample(omega, z, electric, magnetic, ...)

Own a full Maxwell mode set in the internal FFT convention.

solprop.modes.vector.BASIS_UNITARY_ATOL = 1e-12#

Largest norm(U.H U - I, 2) a declared change of basis is still called unitary.

Dimensionless. A declared transform is admitted only where it is a unitary change of coordinates of an exactly degenerate block: the flux metric then transforms as W' = U.H W U, which is the identity wherever W was, and the generator U.H diag(beta) U stays diagonal. A nonunitary transform does neither – it is a leaky or skewed basis whose metric is genuinely off the identity and whose flow is a matrix exponential – and nothing in this package has measured one, so it is refused here rather than approximated.

The number. circular_pair()’s matrix has entries +-1/sqrt(2) and +-i/sqrt(2); 1/sqrt(2) is exact to a half ulp and the products that form U.H U cancel to the last bit, so its measured defect is at the 1e-16 level. A budget of 1e-12 is four orders above that – room for a matrix assembled from measured numbers rather than from a literal – and twelve orders below any departure a reader would call a different basis.

The room is real, because every later gate honours this budget. A transform that is unitary only to E moves a knot’s measured norm(W - I, 2) by norm(E + E.H, 2), which is this defect and not the metric’s, so the per-knot invariance check of solprop.modes.tables.apply_channel_basis() takes this constant as its floor rather than the rounding of its own product (2.8e-14 for two channels, which would refuse a declaration that had just passed here). The four orders are therefore the room a declaration actually has, not the room it has until the next gate.

class solprop.modes.vector.ChannelBasis(transform, blocks, labels, gauge_id)[source]#

Bases: Displayed

Declare the unitary coordinates a guide’s degenerate channels are given in.

A guide’s channels arrive in whatever basis its provider solved them in, which for an azimuthally degenerate family is the real parity pair: the cos and sin patterns ChannelLabel defines. Any unitary combination of an exactly degenerate block is as good a basis, and one of them – the circular pair of circular_pair() – diagonalises the isotropic Kerr tensor’s polarisation dependence. This record is the declaration of that choice: the matrix, the blocks it acts inside, the labels the transformed channels carry and the identity a file records and a resume compares.

The transform acts on the reference, not on the state. With e the provider’s nodal field rows and U this matrix, the declared basis is e' = e U, so a physical field whose reference-basis amplitudes are c has declared-basis amplitudes d = U.H c: the columns of U are the new basis vectors written in the old one. Every derived object follows from that one rule – W' = U.H W U, G' = U.H G U, Q' = U.H Q, S' = S U – and the noise draw made in the reference basis reaches the declared one as U.H times itself.

Whether a block is degenerate is decided where the table is built, not here (solprop.modes.tables.apply_channel_basis()): U.H diag(beta) U is diagonal when the block’s propagation constants are equal and is a coupled matrix flow, linear.coupled_flow, when they are not.

Attributes:
transformnumpy.ndarray

The unitary U, shape (n_modes, n_modes), dimensionless. It is the identity outside blocks, and unitary to BASIS_UNITARY_ATOL.

blockstuple of tuple of int

Disjoint channel-index blocks U acts inside, each with at least two members. They must be blocks the guide declared degenerate.

labelstuple of ChannelLabel

One label per channel of the declared basis, in row order: the provider’s own outside the blocks and the transformed ones inside them.

gauge_idstr

Non-empty identity of this declaration, composed into the tables’ and the metric’s gauge_id so that a run in one basis cannot resume in another.

Raises:
solprop.exceptions.ModeError

If the matrix is not square, finite, unitary or block-diagonal on blocks, if the blocks are not disjoint valid sets of at least two channels, if the label count disagrees with the matrix, or if the identity is empty.

Examples

>>> from solprop.modes.guide import circular_pair
>>> from solprop.modes.protocol import ChannelLabel
>>> pair = (
...     ChannelLabel("HE", 1, 1, "even", None, "HE1,1:even"),
...     ChannelLabel("HE", 1, 1, "odd", None, "HE1,1:odd"),
... )
>>> basis = circular_pair(pair, (0, 1))
>>> basis.gauge_id
'circular(0,1)'
>>> [label.display_label for label in basis.labels]
['HE1,1:left', 'HE1,1:right']
blocks: tuple[tuple[int, ...], ...]#
gauge_id: str#
property identity: Mapping[str, JsonValue][source]#

What a run records of this declaration, and a resume compares.

The matrix enters by value: two different unitary transforms of the same block are two different bases, and the block list alone does not tell them apart. Its entries are declared numbers, not measurements, so they enter exactly, as a declared chi3 or a knot does (solprop.modes.guide.ModalSampling.identity()).

JSON-serialisable scalars and lists of scalars, stable across processes.

labels: tuple[ChannelLabel, ...]#
transform: Complex[ndarray, 'n_modes_basis_out n_modes_basis_in']#
property unitary_defect: float[source]#

norm(U.H U - I, 2), how far the declaration is from unitary.

class solprop.modes.vector.ModalNodeRule(xy, weights, region_index, identity)[source]#

Bases: Displayed

Own Cartesian quadrature nodes and their material regions.

Attributes:
xynumpy.ndarray

Finite Cartesian positions in m, shape (n_nodes_xy, 2).

weightsnumpy.ndarray

Positive area weights in m², shape (n_nodes_weights,).

region_indexnumpy.ndarray

Non-negative int32 region indices, shape (n_nodes_region_index,).

identitycollections.abc.Mapping

Serializable construction and tail-certificate metadata.

identity: Mapping[str, JsonValue]#
region_index: Int32[ndarray, 'n_nodes_region_index']#
weights: Float[ndarray, 'n_nodes_weights']#
xy: Float[ndarray, 'n_nodes_xy 2']#
class solprop.modes.vector.ModalProvider(*args, **kwargs)[source]#

Bases: Protocol

Supply internal-convention full-vector modes on common physical nodes.

The generator is unframed. ModalSample.generator carries the absolute propagation constants, -i diag(beta) for a diagonal provider, not a co-moving generator: the frame is subtracted exactly once, by the translation layer’s one shared frame for the whole mode set (a per-mode frame destroys walk-off; see docs/dev/decisions.md). A provider that removed a frame of its own would have it removed twice.

property identity: Mapping[str, JsonValue][source]#

Physical identity, including spectral_convention='internal'.

node_rule(omega, z=0.0, *, n_r=None, n_theta=None)[source]#

Build the physical quadrature this provider’s fields are resolved on.

One signature for every provider: the rule depends on the frequency, because a bound field’s extent does, and on the position, because the geometry may. An implementation that does not resolve its domain in frequency still takes the argument and uses it to certify the power its rule discards.

Parameters:
omegafloat

Positive angular frequency in rad/s, inside omega_domain.

zfloat, optional

Position in m inside z_domain.

n_rint or None, optional

Radial Gauss nodes per panel, at least two; None asks for the count the implementation’s own geometry needs, which is the one a caller that must not invent a resolution wants. This protocol declares no number of its own: it has no geometry to choose one from.

n_thetaint or None, optional

Angular nodes; None lets the implementation choose the count its channels’ azimuthal orders require.

Returns:
ModalNodeRule

Nodes with declared material ownership and a tail certificate in the identity.

property omega_domain: tuple[float, float][source]#

Declared angular-frequency interval, rad/s.

property regions: tuple[MaterialRegion, ...][source]#

Ordered material-region records.

solve(omega, z, *, nodes)[source]#

Evaluate the modes at one frequency and longitudinal position.

Parameters:
omegafloat

Positive angular frequency in rad/s within omega_domain.

zfloat

Longitudinal coordinate in m within z_domain.

nodesModalNodeRule

Physical quadrature with declared region ownership.

Returns:
ModalSample

Three-component E/H, generator and physical diagnostics. An implementation refuses an unsupported channel by name; it does not return a sample whose valid mask is partly False.

property z_breakpoints: tuple[float, ...][source]#

Physical path breakpoints, m.

property z_domain: tuple[float, float][source]#

Declared longitudinal interval, m.

class solprop.modes.vector.ModalSample(omega, z, electric, magnetic, generator, flux_metric, boundary_residual, valid, backward_electric, backward_magnetic, reciprocal_gram, gauge_id, physical_id)[source]#

Bases: Displayed

Own a full Maxwell mode set in the internal FFT convention.

Attributes:
omegafloat

Positive angular frequency in rad/s.

zfloat

Finite longitudinal position in m.

electricnumpy.ndarray

E in V/m per sqrt(W), shape (n_nodes_electric, 3, n_modes_electric).

magneticnumpy.ndarray

H in A/m per sqrt(W), shape (n_nodes_magnetic, 3, n_modes_magnetic).

generatornumpy.ndarray

Internal generator in 1/m, square (n_modes_generator_out, n_modes_generator_in). Unframed: it carries the absolute propagation constants, and the co-moving frame is subtracted once by the translation layer (see ModalProvider). It is in the internal convention of docs/dev/conventions.md section 2, so a diagonal entry is G_cc = -i (omega/c) conj(n_eff): its imaginary part is -beta and its real part is -alpha/2. A passive channel therefore has Re G_cc <= 0, and Re G_cc > 0 is gain. This is the same sign convention the linear operator has, exp(G z) for a forward amplitude. It is not the optical convention of an IndexTable (solprop.modes.tabulated), which stores n_eff with Im n_eff > 0 for loss; the bridge between the two conjugates, as every optics/internal boundary does.

flux_metricnumpy.ndarray

Dimensionless positive Hermitian flux, shape (n_modes_flux_out, n_modes_flux_in).

boundary_residualnumpy.ndarray

Non-negative scaled boundary defects, shape (n_modes_boundary_residual,).

validnumpy.ndarray

Validity mask, shape (n_modes_valid,). Every provider in this package refuses an unsupported channel by name rather than masking it, so a returned sample has this mask all True; tracking refuses a sample that does not. The field exists so that a future provider which can genuinely return a partial set has somewhere to say so.

backward_electricnumpy.ndarray or None

Reciprocal E, shape (n_nodes_backward_electric, 3, n_modes_backward_electric).

backward_magneticnumpy.ndarray or None

Reciprocal H, shape (n_nodes_backward_magnetic, 3, n_modes_backward_magnetic).

reciprocal_gramnumpy.ndarray or None

Dimensionless reciprocal flux, shape (n_modes_reciprocal_out, n_modes_reciprocal_in).

gauge_idstr

Non-empty phase and coordinate convention identifier.

physical_idstr

Non-empty physical provider identifier.

backward_electric: Complex[ndarray, 'n_nodes_backward_electric 3 n_modes_backward_electric'] | None#
backward_magnetic: Complex[ndarray, 'n_nodes_backward_magnetic 3 n_modes_backward_magnetic'] | None#
boundary_residual: Float[ndarray, 'n_modes_boundary_residual']#
electric: Complex[ndarray, 'n_nodes_electric 3 n_modes_electric']#
flux_metric: Complex[ndarray, 'n_modes_flux_out n_modes_flux_in']#
gauge_id: str#
generator: Complex[ndarray, 'n_modes_generator_out n_modes_generator_in']#
magnetic: Complex[ndarray, 'n_nodes_magnetic 3 n_modes_magnetic']#
omega: float#
physical_id: str#
reciprocal_gram: Complex[ndarray, 'n_modes_reciprocal_out n_modes_reciprocal_in'] | None#
valid: Bool[ndarray, 'n_modes_valid']#
z: float#
solprop.modes.vector.circular_pair(labels, block)[source]#

Declare the circular partners of one exactly degenerate parity pair.

The change of basis that turns the real cos/sin pair of an azimuthally degenerate family into its two circular partners, which is the basis an isotropic Kerr tensor is diagonal in: for a field that is circular at every node E . E vanishes, so (E . E) E* drops out of P = eps0 chi3 (2 |E|^2 E + (E . E) E*) / 4 and the self coefficient falls to two thirds of the linear one.

The convention, derived here. The even partner is the cos((n-1) theta) pattern about x, which for n = 1 is the x-polarised member, and the odd one is its quarter-turn partner about y (ChannelLabel). A provider’s fields are in the internal convention of docs/dev/conventions.md section 2, whose plane wave is exp(i(omega t - beta z)), so the physical transverse field of a channel with nodal rows (e_even, e_odd) and amplitude one is Re[(e_even + a e_odd) exp(i omega t)]. With a = -i that is (cos(omega t), sin(omega t)) in (x, y): the vector turns from x towards y, which an observer looking towards the source sees turn anticlockwise. That is positive helicity, which optics calls left circular (Jackson, Classical Electrodynamics, section 7.2), and its optics-convention Jones vector is the conjugate (1, i)/sqrt(2), which solprop.polarisation records as positive Stokes V. So

e_left  = (e_even - i e_odd)/sqrt(2), e_right = (e_even + i e_odd)/sqrt(2)

and the two columns of the returned matrix are exactly those, in that order: block[0] becomes the left channel and block[1] the right one. The order is not free – block[0] must be the even member and block[1] the odd one, and a block given the other way round is refused by name. The names left and right are a convention, fixed by the derivation above, not a derived fact.

Parameters:
labelscollections.abc.Sequence

Every channel’s label, in the guide’s own row order.

blockcollections.abc.Sequence

Exactly two channel indices, one labelled "even" and one "odd", of the same family and quantum numbers.

Returns:
ChannelBasis

The declaration, with gauge_id "circular(i,j)" for the block’s own two indices in ascending order and the two labels relabelled by handedness.

Raises:
solprop.exceptions.ModeError

If the block is not two distinct valid indices, or the two labels are not a parity pair of one family.

Examples

>>> import numpy as np
>>> from solprop.modes.guide import circular_pair
>>> from solprop.modes.protocol import ChannelLabel
>>> pair = (
...     ChannelLabel("HE", 1, 1, "even", None, "HE1,1:even"),
...     ChannelLabel("HE", 1, 1, "odd", None, "HE1,1:odd"),
... )
>>> basis = circular_pair(pair, (0, 1))
>>> bool(np.allclose(basis.transform[:, 0], [1, -1j] / np.sqrt(2)))
True
>>> basis.labels[1].handedness
'right'
solprop.modes.vector.flux_product(electric, magnetic, weights)[source]#

Integrate the Hermitian Poynting product.

Parameters:
electricnumpy.ndarray

E in V/m per sqrt(W), shape (n_nodes, 3, n_modes).

magneticnumpy.ndarray

H in A/m per sqrt(W), shape (n_nodes, 3, n_modes).

weightsnumpy.ndarray

Area weights in m², shape (n_nodes,).

Returns:
numpy.ndarray

Dimensionless Hermitian flux metric, shape (n_modes, n_modes).

solprop.modes.vector.provider_channels(provider)[source]#

Return a provider’s declared channels as labels, in its own order.

A provider publishes its channels as mappings inside identity, which is what survives JSON; this is the one place they are turned back into ChannelLabel objects for a caller that has to name one – to declare a change of basis over a pair, most of all.

Parameters:
providersolprop.modes.vector.ModalProvider

A provider that names its channels.

Returns:
tuple

One label per channel.

Raises:
ModeError

If the provider names no channels.

solprop.modes.vector.radial_node_rule(interfaces, outer_radius, *, n_r, n_theta)[source]#

Build interface-split Cartesian nodes from the existing polar panel rule.

Parameters:
interfacessequence of float

Strictly increasing positive material radii in m, inside outer_radius.

outer_radiusfloat

Positive finite truncation radius in m; tail certification is separate.

n_rint

At least two Gauss nodes in each radial panel.

n_thetaint

At least two angular nodes; caller certifies angular resolution.

Returns:
ModalNodeRule

Positive area weights and one int32 material index per node.

Raises:
ModeError

If the radius or interface arrangement is invalid.