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
Largest |
Functions
|
Declare the circular partners of one exactly degenerate parity pair. |
|
Integrate the Hermitian Poynting product. |
|
Return a provider's declared channels as labels, in its own order. |
|
Build interface-split Cartesian nodes from the existing polar panel rule. |
Classes
|
Declare the unitary coordinates a guide's degenerate channels are given in. |
|
Own Cartesian quadrature nodes and their material regions. |
|
Supply internal-convention full-vector modes on common physical nodes. |
|
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 whereverWwas, and the generatorU.H diag(beta) Ustays 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 formU.H Ucancel 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
Emoves a knot’s measurednorm(W - I, 2)bynorm(E + E.H, 2), which is this defect and not the metric’s, so the per-knot invariance check ofsolprop.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:
DisplayedDeclare 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
cosandsinpatternsChannelLabeldefines. Any unitary combination of an exactly degenerate block is as good a basis, and one of them – the circular pair ofcircular_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
ethe provider’s nodal field rows andUthis matrix, the declared basis ise' = e U, so a physical field whose reference-basis amplitudes arechas declared-basis amplitudesd = U.H c: the columns ofUare 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 asU.Htimes 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) Uis 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 toBASIS_UNITARY_ATOL.- blockstuple of tuple of int
Disjoint channel-index blocks
Uacts 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_idso 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']
- 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
chi3or 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']#
- class solprop.modes.vector.ModalNodeRule(xy, weights, region_index, identity)[source]#
Bases:
DisplayedOwn 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.
- 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:
ProtocolSupply internal-convention full-vector modes on common physical nodes.
The generator is unframed.
ModalSample.generatorcarries 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;
Noneasks 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;
Nonelets 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 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
validmask is partlyFalse.
- 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:
DisplayedOwn 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 ofdocs/dev/conventions.mdsection 2, so a diagonal entry isG_cc = -i (omega/c) conj(n_eff): its imaginary part is-betaand its real part is-alpha/2. A passive channel therefore hasRe G_cc <= 0, andRe G_cc > 0is 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 anIndexTable(solprop.modes.tabulated), which storesn_effwithIm n_eff > 0for 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']#
- generator: Complex[ndarray, 'n_modes_generator_out n_modes_generator_in']#
- magnetic: Complex[ndarray, 'n_nodes_magnetic 3 n_modes_magnetic']#
- valid: Bool[ndarray, 'n_modes_valid']#
- 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/sinpair 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 nodeE . Evanishes, so(E . E) E*drops out ofP = eps0 chi3 (2 |E|^2 E + (E . E) E*) / 4and 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 forn = 1is 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 ofdocs/dev/conventions.mdsection 2, whose plane wave isexp(i(omega t - beta z)), so the physical transverse field of a channel with nodal rows(e_even, e_odd)and amplitude one isRe[(e_even + a e_odd) exp(i omega t)]. Witha = -ithat 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), whichsolprop.polarisationrecords as positive StokesV. Soe_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 andblock[1]the right one. The order is not free –block[0]must be the even member andblock[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 intoChannelLabelobjects 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.