Source code for solprop.modes.vector

# SPDX-FileCopyrightText: 2026 John C. Travers and contributors
#
# SPDX-License-Identifier: GPL-3.0-or-later

"""Represent internal-convention Maxwell samples on physical area quadrature.

The records every vector modal provider and table shares: :class:`ModalNodeRule`
(Cartesian nodes, area weights and material regions; :func:`radial_node_rule` builds
the interface-split polar one), :class:`ModalSample` (one
frequency and position's E/H, generator and flux metric), the
:class:`ModalProvider` protocol that produces them, and :func:`flux_product`, the
Hermitian Poynting product. :class:`ChannelBasis` declares a unitary change of a
guide's degenerate channel coordinates (:func:`circular_pair`, read against
:func:`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.
"""

from collections.abc import Mapping, Sequence
from dataclasses import dataclass
from typing import Protocol, runtime_checkable

import numpy as np
from jaxtyping import Bool, Complex, Float, Int32

from solprop._display import Displayed, engineering, line
from solprop.exceptions import ModeError
from solprop.modes.material import JsonValue, MaterialRegion
from solprop.modes.protocol import ChannelLabel
from solprop.modes.quadrature import quadrature_rule

__all__ = [
    "BASIS_UNITARY_ATOL",
    "ChannelBasis",
    "ModalNodeRule",
    "ModalProvider",
    "ModalSample",
    "circular_pair",
    "flux_product",
    "provider_channels",
    "radial_node_rule",
]

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.** :func:`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 :func:`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.
"""


[docs] @dataclass(frozen=True, eq=False) class ModalNodeRule(Displayed): """Own Cartesian quadrature nodes and their material regions. Attributes ---------- xy : numpy.ndarray Finite Cartesian positions in m, shape (n_nodes_xy, 2). weights : numpy.ndarray Positive area weights in m², shape (n_nodes_weights,). region_index : numpy.ndarray Non-negative int32 region indices, shape (n_nodes_region_index,). identity : collections.abc.Mapping Serializable construction and tail-certificate metadata. """ xy: Float[np.ndarray, "n_nodes_xy 2"] weights: Float[np.ndarray, " n_nodes_weights"] region_index: Int32[np.ndarray, " n_nodes_region_index"] identity: Mapping[str, JsonValue] def __repr__(self) -> str: """Return a one-line description: the node and region counts. Returns ------- str For example ``ModalNodeRule(60 nodes, 2 regions)``. """ return line( "ModalNodeRule", [ ("", f"{len(self.weights)} nodes"), ("", f"{len(set(self.region_index.tolist()))} regions"), ], ) 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. """ return "ModalNodeRule: Cartesian nodes with declared material ownership", [ ("nodes", len(self.weights)), ("regions", len(set(self.region_index.tolist()))), ("identity", ", ".join(sorted(self.identity)) or "none"), ] def __post_init__(self) -> None: """Copy, validate and freeze the physical node arrays. Raises ------ ModeError If arrays disagree in shape, contain invalid values or have no nodes. """ xy = np.array(self.xy, dtype=np.float64, copy=True) weights = np.array(self.weights, dtype=np.float64, copy=True) regions = np.array(self.region_index, copy=True) if xy.ndim != 2 or xy.shape[1] != 2 or not xy.shape[0]: raise ModeError("xy must contain at least one Cartesian pair") if weights.shape != (len(xy),) or regions.shape != weights.shape: raise ModeError("node coordinates, weights and regions must agree") if not np.all(np.isfinite(xy)) or not np.all(np.isfinite(weights)): raise ModeError("node coordinates and weights must be finite") if np.any(weights <= 0): raise ModeError("area weights must be positive") if regions.dtype != np.int32 or np.any(regions < 0): raise ModeError("region_index must contain non-negative int32 indices") for name, value in ( ("xy", xy), ("weights", weights), ("region_index", regions), ): value.setflags(write=False) object.__setattr__(self, name, value) object.__setattr__(self, "identity", dict(self.identity))
[docs] def radial_node_rule( interfaces: Sequence[float], outer_radius: float, *, n_r: int, n_theta: int, ) -> ModalNodeRule: """Build interface-split Cartesian nodes from the existing polar panel rule. Parameters ---------- interfaces : sequence of float Strictly increasing positive material radii in m, inside outer_radius. outer_radius : float Positive finite truncation radius in m; tail certification is separate. n_r : int At least two Gauss nodes in each radial panel. n_theta : int 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. """ if not np.isfinite(outer_radius) or outer_radius <= 0: raise ModeError("outer_radius must be positive and finite") rule = quadrature_rule( "polar", full=True, n_r=n_r, n_theta=n_theta, breaks=tuple(float(r / outer_radius) for r in interfaces), ) limits = ("polar", (0.0, 0.0), (outer_radius, 2 * np.pi)) polar = rule.nodes(limits) xy = np.column_stack( (polar[:, 0] * np.cos(polar[:, 1]), polar[:, 0] * np.sin(polar[:, 1])) ) return ModalNodeRule( xy, rule.weights(limits), np.searchsorted(interfaces, polar[:, 0], side="left").astype(np.int32), { "interfaces": list(interfaces), "outer_radius": outer_radius, "n_r": n_r, "n_theta": n_theta, }, )
[docs] @dataclass(frozen=True, eq=False) class ModalSample(Displayed): """Own a full Maxwell mode set in the internal FFT convention. Attributes ---------- omega : float Positive angular frequency in rad/s. z : float Finite longitudinal position in m. electric : numpy.ndarray E in V/m per sqrt(W), shape (n_nodes_electric, 3, n_modes_electric). magnetic : numpy.ndarray H in A/m per sqrt(W), shape (n_nodes_magnetic, 3, n_modes_magnetic). generator : numpy.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 :class:`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`` (:mod:`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_metric : numpy.ndarray Dimensionless positive Hermitian flux, shape (n_modes_flux_out, n_modes_flux_in). boundary_residual : numpy.ndarray Non-negative scaled boundary defects, shape (n_modes_boundary_residual,). valid : numpy.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_electric : numpy.ndarray or None Reciprocal E, shape (n_nodes_backward_electric, 3, n_modes_backward_electric). backward_magnetic : numpy.ndarray or None Reciprocal H, shape (n_nodes_backward_magnetic, 3, n_modes_backward_magnetic). reciprocal_gram : numpy.ndarray or None Dimensionless reciprocal flux, shape (n_modes_reciprocal_out, n_modes_reciprocal_in). gauge_id : str Non-empty phase and coordinate convention identifier. physical_id : str Non-empty physical provider identifier. """ omega: float z: float electric: Complex[np.ndarray, "n_nodes_electric 3 n_modes_electric"] magnetic: Complex[np.ndarray, "n_nodes_magnetic 3 n_modes_magnetic"] generator: Complex[np.ndarray, "n_modes_generator_out n_modes_generator_in"] flux_metric: Complex[np.ndarray, "n_modes_flux_out n_modes_flux_in"] boundary_residual: Float[np.ndarray, " n_modes_boundary_residual"] valid: Bool[np.ndarray, " n_modes_valid"] backward_electric: ( Complex[np.ndarray, "n_nodes_backward_electric 3 n_modes_backward_electric"] | None ) backward_magnetic: ( Complex[np.ndarray, "n_nodes_backward_magnetic 3 n_modes_backward_magnetic"] | None ) reciprocal_gram: ( Complex[np.ndarray, "n_modes_reciprocal_out n_modes_reciprocal_in"] | None ) gauge_id: str physical_id: str def __repr__(self) -> str: """Return a one-line description: the extents and the sampled shape. Returns ------- str For example ``ModalSample(1 channel, 60 nodes, 2.256e+15 rad/s, 0 m)``. """ nodes, _, modes = np.shape(self.electric) return line( "ModalSample", [ ("", f"{modes} channel{'' if modes == 1 else 's'}"), ("", f"{nodes} nodes"), ("", f"{float(self.omega):.4e} rad/s"), ("", engineering(float(self.z), "m")), ], ) 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. """ nodes, _, modes = np.shape(self.electric) return "ModalSample: internal-convention E/H on physical nodes", [ ("omega", f"{float(self.omega):.6e} rad/s"), ("z", engineering(float(self.z), "m")), ("channels", modes), ("nodes", nodes), ("gauge", self.gauge_id), # The identity is a JSON document; the block's own column cut shows its # head, which is where the channels and the model are. ("provider", self.physical_id), ("residual", f"{float(np.max(self.boundary_residual)):.3e} largest"), ("reciprocal", "yes" if self.reciprocal_gram is not None else "no"), ] def __post_init__(self) -> None: """Validate extents, finite data and positive physical flux in production. Raises ------ ModeError If metadata, shapes, reciprocal data or the flux metric are invalid. """ if not np.isfinite(self.omega) or self.omega <= 0 or not np.isfinite(self.z): raise ModeError("omega must be positive and z finite") if not self.gauge_id or not self.physical_id: raise ModeError("physical_id and gauge_id must be non-empty") reciprocal = ( self.backward_electric, self.backward_magnetic, self.reciprocal_gram, ) if any(value is None for value in reciprocal) and not all( value is None for value in reciprocal ): raise ModeError( "backward fields and reciprocal Gram must be supplied together" ) # Coerce before inspecting, as ModalNodeRule does: a list or a nested # sequence has no ndim, and reading one raises AttributeError instead of # the ModeError a public boundary owes its caller. electric = np.array(self.electric, dtype=np.complex128, copy=True) if electric.ndim != 3 or electric.shape[1] != 3: raise ModeError("electric must have three Cartesian components") nodes, _, modes = electric.shape if not nodes or not modes: raise ModeError("a modal sample needs nodes and modes") shapes = { "electric": (nodes, 3, modes), "magnetic": (nodes, 3, modes), "generator": (modes, modes), "flux_metric": (modes, modes), "boundary_residual": (modes,), "valid": (modes,), "backward_electric": (nodes, 3, modes), "backward_magnetic": (nodes, 3, modes), "reciprocal_gram": (modes, modes), } if np.asarray(self.valid).dtype != np.bool_: raise ModeError("valid must be a boolean mask") for name, shape in shapes.items(): value = electric if name == "electric" else getattr(self, name) if value is None: continue dtype = ( np.bool_ if name == "valid" else np.float64 if name == "boundary_residual" else np.complex128 ) array = np.array(value, dtype=dtype, copy=True) if array.shape != shape or not np.all(np.isfinite(array)): raise ModeError(f"{name} must have finite values and shape {shape}") array.setflags(write=False) object.__setattr__(self, name, array) if np.any(self.boundary_residual < 0): raise ModeError("boundary residuals must be non-negative") self._validate_flux(modes) def _validate_flux(self, modes: int) -> None: """Require positive Hermitian flux and a nonsingular reciprocal pairing. - ``modes``: validated positive channel count, dimensionless. """ tolerance = 64 * modes * np.finfo(float).eps * np.linalg.norm(self.flux_metric) if np.linalg.norm(self.flux_metric - self.flux_metric.conj().T) > tolerance: raise ModeError("flux_metric must be Hermitian") if np.linalg.eigvalsh(self.flux_metric)[0] <= 0: raise ModeError("flux_metric must be positive definite") if ( self.reciprocal_gram is not None and np.linalg.matrix_rank(self.reciprocal_gram) < modes ): raise ModeError("reciprocal_gram must be nonsingular")
[docs] @runtime_checkable class ModalProvider(Protocol): """Supply internal-convention full-vector modes on common physical nodes. **The generator is unframed.** :attr:`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. """
[docs] def node_rule( self, omega: float, z: float = 0.0, *, n_r: int | None = None, n_theta: int | None = None, ) -> ModalNodeRule: """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 ---------- omega : float Positive angular frequency in rad/s, inside :attr:`omega_domain`. z : float, optional Position in m inside :attr:`z_domain`. n_r : int 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_theta : int 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. """ ...
[docs] def solve(self, omega: float, z: float, *, nodes: ModalNodeRule) -> ModalSample: """Evaluate the modes at one frequency and longitudinal position. Parameters ---------- omega : float Positive angular frequency in rad/s within omega_domain. z : float Longitudinal coordinate in m within z_domain. nodes : ModalNodeRule 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``. """ ...
[docs] @property def regions(self) -> tuple[MaterialRegion, ...]: # numpydoc ignore=RT01 """Ordered material-region records.""" ...
[docs] @property def z_breakpoints(self) -> tuple[float, ...]: # numpydoc ignore=RT01 """Physical path breakpoints, m.""" ...
[docs] @property def omega_domain(self) -> tuple[float, float]: # numpydoc ignore=RT01 """Declared angular-frequency interval, rad/s.""" ...
[docs] @property def z_domain(self) -> tuple[float, float]: # numpydoc ignore=RT01 """Declared longitudinal interval, m.""" ...
[docs] @property def identity(self) -> Mapping[str, JsonValue]: # numpydoc ignore=RT01 """Physical identity, including ``spectral_convention='internal'``.""" ...
[docs] def flux_product( electric: Complex[np.ndarray, "n_nodes 3 n_modes"], magnetic: Complex[np.ndarray, "n_nodes 3 n_modes"], weights: Float[np.ndarray, " n_nodes"], ) -> Complex[np.ndarray, "n_modes n_modes"]: """Integrate the Hermitian Poynting product. Parameters ---------- electric : numpy.ndarray E in V/m per sqrt(W), shape (n_nodes, 3, n_modes). magnetic : numpy.ndarray H in A/m per sqrt(W), shape (n_nodes, 3, n_modes). weights : numpy.ndarray Area weights in m², shape (n_nodes,). Returns ------- numpy.ndarray Dimensionless Hermitian flux metric, shape (n_modes, n_modes). """ cross = np.einsum("qm,qn,q->mn", magnetic[:, 1].conj(), electric[:, 0], weights) cross -= np.einsum("qm,qn,q->mn", magnetic[:, 0].conj(), electric[:, 1], weights) return (cross + cross.conj().T) / 4
[docs] @dataclass(frozen=True, eq=False) class ChannelBasis(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 :class:`~solprop.modes.protocol.ChannelLabel` defines. Any unitary combination of an **exactly degenerate** block is as good a basis, and one of them -- the circular pair of :func:`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 (:func:`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 ---------- transform : numpy.ndarray The unitary ``U``, shape (n_modes, n_modes), dimensionless. It is the identity outside `blocks`, and unitary to ``BASIS_UNITARY_ATOL``. blocks : tuple 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. labels : tuple 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_id : str 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'] """ transform: Complex[np.ndarray, "n_modes_basis_out n_modes_basis_in"] blocks: tuple[tuple[int, ...], ...] labels: tuple[ChannelLabel, ...] gauge_id: str def __repr__(self) -> str: """Return a one-line description, never the matrix. Returns ------- str For example ``ChannelBasis(circular(0,1), 2 channels, 1 block)``. """ blocks = len(self.blocks) return line( "ChannelBasis", [ ("", self.gauge_id), ( "", f"{len(self.labels)} channel{'' if len(self.labels) == 1 else 's'}", ), ("", f"{blocks} block{'' if blocks == 1 else 's'}"), ], ) 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. """ return "ChannelBasis: a declared unitary change of a guide's channel basis", [ ("gauge", self.gauge_id), ("channels", ", ".join(label.display_label for label in self.labels)), ("blocks", ", ".join(str(list(block)) for block in self.blocks)), ("unitary defect", f"{self.unitary_defect:.3e}"), ] def __post_init__(self) -> None: """Copy, validate and freeze the matrix, and check the blocks and labels. Raises ------ solprop.exceptions.ModeError Naming what is out of range. """ matrix = np.array(self.transform, dtype=np.complex128, order="C", copy=True) if ( matrix.ndim != 2 or matrix.shape[0] != matrix.shape[1] or not matrix.shape[0] or not np.all(np.isfinite(matrix)) ): raise ModeError( "a channel basis transform must be a finite non-empty square " f"matrix, got shape {matrix.shape}" ) matrix.setflags(write=False) object.__setattr__(self, "transform", matrix) object.__setattr__( self, "blocks", tuple(tuple(int(one) for one in block) for block in self.blocks), ) object.__setattr__(self, "labels", tuple(self.labels)) if not self.gauge_id: raise ModeError("a channel basis needs a non-empty gauge_id") count = matrix.shape[0] if len(self.labels) != count: raise ModeError( f"a channel basis needs one label per channel: the transform is " f"{count} wide and {len(self.labels)} label(s) were given" ) self._check_blocks(count) defect = self.unitary_defect if not (defect <= BASIS_UNITARY_ATOL): raise ModeError( f"a declared change of basis must be unitary: this one is " f"{defect:.4g} from it, above the {BASIS_UNITARY_ATOL:.4g} budget. " "A nonunitary transform is a leaky or skewed basis whose flux " "metric is genuinely off the identity and whose flow is a coupled " "matrix exponential; neither has been measured in this package, and " "the coupled flow carries a unitary change of basis only" ) def _check_blocks(self, count: int) -> None: """Require disjoint valid blocks and a matrix that is the identity outside.""" seen: set[int] = set() membership = np.full(count, -1, dtype=int) for position, block in enumerate(self.blocks): if ( len(block) < 2 or len(set(block)) != len(block) or any(not 0 <= one < count for one in block) or seen.intersection(block) ): raise ModeError( "a channel basis acts inside disjoint blocks of at least two " f"distinct channels of the {count} it describes, got " f"{[list(one) for one in self.blocks]}" ) seen.update(block) membership[list(block)] = position # Outside a declared block the transform must be the identity: that is what # makes "this basis mixes only these channels" a checkable statement, and it # is what the exact-degeneracy gate on each block is then enough to cover. same = membership[:, None] == membership[None, :] allowed = same & (membership[:, None] >= 0) outside = self.transform - np.eye(count) if np.any(outside[~allowed] != 0.0): raise ModeError( "a channel basis transform must be the identity outside its " f"declared blocks {[list(one) for one in self.blocks]}: it mixes " "channels this guide has not declared degenerate, and the exact " "degeneracy that keeps the generator diagonal is checked per block" )
[docs] @property def unitary_defect(self) -> float: # numpydoc ignore=RT01 """``norm(U.H U - I, 2)``, how far the declaration is from unitary.""" matrix = self.transform product = matrix.conj().T @ matrix return float(np.linalg.norm(product - np.eye(len(matrix)), ord=2))
[docs] @property def identity(self) -> Mapping[str, JsonValue]: # numpydoc ignore=RT01 """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 (:meth:`solprop.modes.guide.ModalSampling.identity`). JSON-serialisable scalars and lists of scalars, stable across processes. """ return { "gauge_id": self.gauge_id, "blocks": [[int(one) for one in block] for block in self.blocks], # The two parts by name, as lists of floats: a complex number has no # JSON form, and a pair of real matrices is what survives a round trip. "transform_real": [ [float(one) for one in row] for row in np.real(self.transform) ], "transform_imag": [ [float(one) for one in row] for row in np.imag(self.transform) ], "labels": [dict(label.as_mapping()) for label in self.labels], }
[docs] def provider_channels(provider: ModalProvider) -> tuple[ChannelLabel, ...]: """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 :class:`~solprop.modes.protocol.ChannelLabel` objects for a caller that has to name one -- to declare a change of basis over a pair, most of all. Parameters ---------- provider : solprop.modes.vector.ModalProvider A provider that names its channels. Returns ------- tuple One label per channel. Raises ------ ModeError If the provider names no channels. """ declared = provider.identity.get("channels") if not isinstance(declared, list) or not declared: raise ModeError( "this provider names no channels, so its labels cannot be read; " f"{type(provider).__name__} declares none" ) labels = [] for mapping in declared: if not isinstance(mapping, dict): raise ModeError("a declared channel must be a label mapping") labels.append(ChannelLabel.from_mapping(mapping)) return tuple(labels)
[docs] def circular_pair(labels: Sequence[ChannelLabel], block: Sequence[int]) -> ChannelBasis: """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** (:class:`~solprop.modes.protocol.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 :mod:`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 ---------- labels : collections.abc.Sequence Every channel's label, in the guide's own row order. block : collections.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' """ indices = [int(one) for one in block] if len(indices) != 2 or len(set(indices)) != 2: raise ModeError( f"a circular pair is exactly two distinct channels, got {list(block)}" ) if any(not 0 <= one < len(labels) for one in indices): raise ModeError( f"circular pair {indices} is outside the {len(labels)} channel(s) given" ) even, odd = (labels[one] for one in indices) if (even.parity, odd.parity) != ("even", "odd") or ( even.family, even.azimuthal_order, even.radial_order, ) != (odd.family, odd.azimuthal_order, odd.radial_order): raise ModeError( "a circular pair is the even and the odd parity of one family, in that " f"order: got {even.display_label!r} ({even.parity}) and " f"{odd.display_label!r} ({odd.parity})" ) root = 1.0 / np.sqrt(2.0) matrix = np.eye(len(labels), dtype=np.complex128) matrix[np.ix_(indices, indices)] = np.array( [[root, root], [-1j * root, 1j * root]], dtype=np.complex128 ) base = even.display_label.removesuffix(":even") turned = [ ChannelLabel( even.family, even.azimuthal_order, even.radial_order, None, hand, f"{base}:{hand}", ) for hand in ("left", "right") ] relabelled = list(labels) for position, label in zip(indices, turned, strict=True): relabelled[position] = label low, high = sorted(indices) return ChannelBasis( matrix, ((indices[0], indices[1]),), tuple(relabelled), f"circular({low},{high})", )