# SPDX-FileCopyrightText: 2026 John C. Travers and contributors
#
# SPDX-License-Identifier: GPL-3.0-or-later
"""Sample a guide whose geometry moves along z, section by section, in its own gauge.
A solid guide's modes change *shape* along a taper, so the general route's synthesis
``S`` and projection ``Q`` move with z; this module samples that motion.
:func:`path_sections` cuts the path at its declared kinks; :func:`path_rule` and
:func:`path_snapshot` solve one position on the provider's own rule there and in its
own gauge; :func:`sample_modal_path` doubles the Chebyshev-Lobatto degree per section
(from :data:`INITIAL_PATH_DEGREE` to :data:`MAX_PATH_DEGREE`) until the expansion
reproduces held-out solves, returning a :class:`ModalPathTable`: the snapshots beside
the :class:`ModalPath` record of the sampling, which a guide keeps and a run rebuilds
the same snapshots from. What a run reads of it is built in
:mod:`solprop.translate.modal_path`.
Two invariants. The node rule **moves with the geometry**, so node ``q`` stays in one
material region and a map stored there is smooth in z; the connection's Eulerian
derivative keeps the union-split rule of
:func:`solprop.modes.connection.connection_nodes` instead. The gauge is **the
provider's own**, because the connection is measured in it, so a provider whose gauge
is discontinuous along the path is refused (:data:`GAUGE_PHASE_ATOL`). The full account
is ``docs/guide/waveguides/moving-modal.md``, section "A guide whose geometry moves
along z".
"""
import itertools
import logging
import math
from collections.abc import Mapping, Sequence
from dataclasses import dataclass
import numpy as np
from jaxtyping import Float, Inexact
from numpy.polynomial import chebyshev as chebyshev_basis
from solprop._display import Displayed, engineering, line
from solprop._ownership import frozen_copy
from solprop.exceptions import ModeError
from solprop.modes.material import JsonValue, quantised_measurement
from solprop.modes.quadrature import (
lobatto_coefficients,
lobatto_points,
refinement_points,
)
from solprop.modes.tables import (
DEFAULT_GRAM_ATOL,
MIN_OVERLAP_DOMINANCE,
DenseModalTable,
apply_channel_basis,
cross_poynting,
)
from solprop.modes.vector import (
ChannelBasis,
ModalNodeRule,
ModalProvider,
ModalSample,
flux_product,
)
__all__ = [
"GAUGE_PHASE_ATOL",
"INITIAL_PATH_DEGREE",
"MAX_PATH_DEGREE",
"PATH_RTOL_FLOOR",
"ModalPath",
"ModalPathTable",
"path_rule",
"path_sections",
"path_snapshot",
"sample_modal_path",
]
logger = logging.getLogger(__name__)
INITIAL_PATH_DEGREE = 4
"""Chebyshev degree along z a path's accuracy search starts at, per section.
Four is five solves per section before anything is measured. The search doubles from
here, and the Chebyshev-Lobatto points nest bitwise under a doubling, so no solve is
ever repeated (:func:`solprop.modes.quadrature.lobatto_points`).
"""
MAX_PATH_DEGREE = 32
"""Highest Chebyshev degree along z a path's accuracy search tries per section.
The same ceiling :data:`solprop.translate.coupled.MAX_SECTION_DEGREE` puts on a
coupled flow's sections, and for the same reason: a smooth section of a declared
taper resolves at a low degree, and a degree this high means the section spans
structure the provider should declare as a kink, or the caller should divide.
"""
PATH_RTOL_FLOOR = 1e-10
"""Smallest held-out error along z a path's accuracy search is asked to reach.
The default target is the frequency interpolation's own measured error, and a very
well sampled band can measure below what a provider's solves reproduce between two
positions: the fields at a node are a sum over a quadrature and an eigenproblem, and
their relative round-off is of order ``1e-13`` to ``1e-12``. Below this floor the
search would be doubling to resolve round-off.
"""
GAUGE_PHASE_ATOL = 1e-9
"""Largest phase, rad, between two neighbouring samples' aligned overlap.
The connection is measured in the provider's own gauge with its stencil aligned to
the centre, which removes any phase the gauge accumulates along z; the maps are
expanded in the same gauge **without** that alignment. They agree only where the
provider's gauge has no phase rate of its own, and the two qualified providers'
fields are real up to a fixed factor, so their overlaps are real to rounding. A
provider whose gauge drifts would put ``i phi'`` on the maps' diagonal and not on the
connection's, which is refused rather than propagated.
"""
def _count(name: str, value: object) -> int:
"""Return a path's positive integer declaration, refusing anything else by name."""
if isinstance(value, bool) or not isinstance(value, int) or value < 1:
raise ModeError(f"a path's {name} is a positive integer, got {value!r}")
return value
def _measure(name: str, value: float, *, positive: bool) -> float:
"""Return a path's finite budget or measurement, refusing anything else by name.
- ``positive``: whether zero is refused too, as it is for a budget.
"""
number = float(value)
if not math.isfinite(number) or number < 0.0 or (positive and number == 0.0):
raise ModeError(
f"a path's {name} is a {'positive' if positive else 'non-negative'} "
f"finite number, got {value!r}"
)
return number
[docs]
@dataclass(frozen=True, eq=False)
class ModalPath(Displayed):
"""Record how a moving guide was sampled along z, and what that measured.
The z half of a guide's sampling (:class:`~solprop.modes.guide.ModalSampling`),
filled by :meth:`~solprop.modes.guide.ModalGuide.from_provider` for a provider
whose geometry moves. The path is cut into **sections** -- the provider's declared
kink intervals, each divided `sections` times
(:func:`~solprop.modes.path.path_sections`) -- and every section is solved at the
Chebyshev-Lobatto points of one degree along z, the degree the accuracy check
demanded: doubled until the expansion reproduced a fresh solve at the points a
doubling adds to within `rtol` (:func:`~solprop.modes.path.sample_modal_path`,
whose :class:`~solprop.modes.path.ModalPathTable` holds the snapshots beside this
record). A run rebuilds the same positions from this record rather than searching
again.
Attributes
----------
z_edges : numpy.ndarray
Section edges in m, strictly increasing, shape ``(n_edges_path,)``: the
provider's z domain split at its interior breakpoints and subdivided.
degree : int
The Chebyshev degree along z every section is sampled at, positive; each
section holds ``degree + 1`` positions, its two ends included.
sections : int
How many sections each kink interval was divided into, positive.
rtol : float
The budget the degree was searched against, positive: by default the
frequency interpolation's own measured profile error, so that the sampling in
z is never the coarser of the two.
z_error : float
The measured held-out departure at the degree kept, dimensionless and
non-negative: the largest relative maximum-norm departure of E, H or the
generator from a fresh solve between the sampled positions.
gram_departure : float
The largest ``norm(W - I, 2)`` of the expanded basis at those same held-out
positions, dimensionless and non-negative.
Raises
------
ModeError
Naming the field that is out of range.
Examples
--------
>>> import numpy as np
>>> from solprop.modes.path import ModalPath
>>> path = ModalPath(np.array([0.0, 1e-3]), 2, 1, 1e-6, 3e-7, 1e-8)
>>> path.positions.round(6).tolist()
[[0.0, 0.0005, 0.001]]
>>> round(float(path.interpolate(np.array([0.0, 1.0, 2.0]), 2.5e-4)), 12)
0.5
"""
z_edges: Float[np.ndarray, " n_edges_path"]
degree: int
sections: int
rtol: float
z_error: float
gram_departure: float
def __post_init__(self) -> None:
"""Freeze the edges and check every declaration and measurement.
Raises
------
ModeError
Naming the field that is out of range.
"""
edges = frozen_copy(np.reshape(self.z_edges, -1), np.float64)
if (
edges.size < 2
or not np.all(np.isfinite(edges))
or np.any(np.diff(edges) <= 0.0)
):
raise ModeError(
"a path's section edges are at least two finite, strictly increasing "
f"positions, got {edges.tolist()}"
)
object.__setattr__(self, "z_edges", edges)
_count("degree", self.degree)
_count("sections", self.sections)
_measure("rtol", self.rtol, positive=True)
_measure("z_error", self.z_error, positive=False)
_measure("gram_departure", self.gram_departure, positive=False)
[docs]
@property
def n_intervals(self) -> int: # numpydoc ignore=RT01
"""How many sections the path is cut into."""
return int(self.z_edges.size - 1)
[docs]
@property
def positions(
self,
) -> Float[np.ndarray, "n_intervals_path n_deg_path"]: # numpydoc ignore=RT01
"""Every sampled position, section by section, m.
Shape ``(n_intervals, degree + 1)``, increasing inside a section, so a position
on an interior edge appears twice.
"""
# The same Chebyshev-Lobatto points the path was sampled at, bit for bit,
# because the run solves exactly these positions again.
return np.stack(
[
lobatto_points(self.degree, float(lo), float(hi))
for lo, hi in zip(self.z_edges[:-1], self.z_edges[1:], strict=True)
]
)
[docs]
def section(self, z: float) -> int:
"""Return the section a position lies in, clamped to the path's ends.
Parameters
----------
z : float
Position in m.
Returns
-------
int
The section index; a position on an interior edge takes the section
starting there, and one outside the path the nearest end's.
"""
raw = int(np.searchsorted(self.z_edges, float(z), side="right")) - 1
return min(max(raw, 0), self.n_intervals - 1)
[docs]
def interpolate(
self,
values: Inexact[np.ndarray, " n_positions *value"],
z: float,
) -> np.ndarray:
"""Evaluate values sampled at the path's positions at any position.
The barycentric form of the interpolating polynomial through one section's
Chebyshev-Lobatto samples -- weights ``(-1)^j``, halved at the two ends -- which
is the same polynomial the translation layer's Chebyshev coefficients carry,
evaluated stably. A position outside the path **holds** the nearest end's
value, as a :class:`~solprop.profiles.ZProfile` holds its own beyond its span:
a run's tables reach a few per cent past its end, and the geometry is not
declared there.
Parameters
----------
values : numpy.ndarray
One value per position, in :attr:`positions` order flattened, position
axis first, shape ``(n_intervals * (degree + 1), *value_shape)``.
z : float
Position in m.
Returns
-------
numpy.ndarray
The value at `z`, shape ``value_shape``.
Raises
------
ModeError
If `values` does not carry one row per position.
"""
rows = np.asarray(values)
width = self.degree + 1
if rows.shape[0] != self.n_intervals * width:
raise ModeError(
f"a path of {self.n_intervals} section(s) at degree {self.degree} "
f"interpolates one value per position, {self.n_intervals * width} in "
f"all, and got {rows.shape[0]}"
)
index = self.section(z)
lo, hi = float(self.z_edges[index]), float(self.z_edges[index + 1])
x = min(max((2.0 * float(z) - lo - hi) / (hi - lo), -1.0), 1.0)
section = rows[index * width : (index + 1) * width]
nodes = -np.cos(np.pi * np.arange(width) / self.degree)
# A position that maps onto a node to within a few ulp -- the mid-section
# node is -cos(pi/2) = -6e-17, which no position maps to exactly -- is that
# node, whose value is returned as sampled rather than through a quotient.
exact = np.flatnonzero(np.abs(nodes - x) <= 4.0 * np.finfo(float).eps)
if exact.size:
return np.asarray(section[int(exact[0])])
weights = (-1.0) ** np.arange(width)
weights[0] *= 0.5
weights[-1] *= 0.5
terms = weights / (x - nodes)
return np.asarray(np.tensordot(terms, section, axes=1) / float(np.sum(terms)))
[docs]
@property
def identity(self) -> Mapping[str, JsonValue]: # numpydoc ignore=RT01
"""What a run records of the path, and a resume compares.
The declared edges, degree, subdivision and budget exactly; the two measured
departures at :data:`~solprop.modes.material.MEASURED_DIGITS`, as every other
measured entry of a guide's identity is.
JSON-serialisable scalars and lists of scalars.
"""
return {
"z_edges": [float(one) for one in self.z_edges],
"degree": int(self.degree),
"sections": int(self.sections),
"rtol": float(self.rtol),
"z_error": quantised_measurement(self.z_error),
"gram_departure": quantised_measurement(self.gram_departure),
}
def __repr__(self) -> str:
"""Return a one-line description, never an array.
Returns
-------
str
For example ``ModalPath(1 section, degree 8, 0 to 1 mm)``.
"""
count = self.n_intervals
return line(
"ModalPath",
[
("", f"{count} section{'' if count == 1 else 's'}"),
("", f"degree {self.degree}"),
(
"",
f"{engineering(float(self.z_edges[0]), 'm')} to "
f"{engineering(float(self.z_edges[-1]), '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.
"""
return "ModalPath: how a moving guide was sampled along z", [
("sections", f"{self.n_intervals} ({self.sections} per kink interval)"),
(
"span",
f"{engineering(float(self.z_edges[0]), 'm')} to "
f"{engineering(float(self.z_edges[-1]), 'm')}",
),
("degree", self.degree),
("positions", self.n_intervals * (self.degree + 1)),
("budget", f"{self.rtol:.3e}"),
("held-out error", f"{self.z_error:.3e}"),
("gram departure", f"{self.gram_departure:.3e}"),
]
[docs]
def path_sections(
provider: ModalProvider, sections: int = 1
) -> Float[np.ndarray, " n_edges"]:
"""Return the section edges of a moving provider's path, in m.
The provider's z domain split at every declared breakpoint strictly inside it --
each a kink of the geometry, where the connection jumps with the slope -- and each
of those intervals divided into `sections` equal parts.
Parameters
----------
provider : solprop.modes.vector.ModalProvider
The guide, whose ``z_domain`` and ``z_breakpoints`` are read.
sections : int, optional
Sections per kink interval, positive; one by default.
Returns
-------
numpy.ndarray
The edges in m, strictly increasing, from the domain's start to its end.
Raises
------
solprop.exceptions.ModeError
If `sections` is not a positive integer.
Examples
--------
>>> import numpy as np
>>> from solprop.modes.graded_index import (
... GradedIndexProvider, PowerLawPermittivity,
... )
>>> from solprop.modes.material import IndexMaterial
>>> from solprop.profiles import PiecewiseLinear
>>> from solprop.modes.path import path_sections
>>> guide = GradedIndexProvider(
... permittivity=PowerLawPermittivity(IndexMaterial(1.45), 0.005),
... exterior=IndexMaterial(1.45 * np.sqrt(1 - 2 * 0.005)),
... radius=PiecewiseLinear(
... np.array([0.0, 4e-4, 1e-3]), np.array([25e-6, 24e-6, 22.5e-6])
... ),
... family="LP", count=2, elements=16, extent=2.0,
... )
>>> [round(one, 6) for one in path_sections(guide, 2).tolist()]
[0.0, 0.0002, 0.0004, 0.0007, 0.001]
"""
_count("sections", sections)
low, high = (float(one) for one in provider.z_domain)
kinks = sorted(
{low, high, *(float(one) for one in provider.z_breakpoints if low < one < high)}
)
edges = [low]
for start, end in itertools.pairwise(kinks):
edges.extend(
start + (end - start) * index / sections for index in range(1, sections)
)
edges.append(end)
return np.asarray(edges, dtype=np.float64)
[docs]
def path_rule(provider: ModalProvider, rule: ModalNodeRule, z: float) -> ModalNodeRule:
"""Return the provider's own rule at `z`, asked for exactly as `rule` was.
The frequency and the resolution are read from `rule`'s own identity, so the rule
at every position of a path is the one the provider would have built there on the
same request: its panel edges on that position's interfaces, its tail certified
there. It must keep `rule`'s structure -- the same node count and the same material
region at every node -- because node ``q`` is one moving point along the whole
path and the seam carries one region index per node.
Parameters
----------
provider : solprop.modes.vector.ModalProvider
The guide.
rule : solprop.modes.vector.ModalNodeRule
The entrance rule, whose identity names ``omega``, ``n_r`` and ``n_theta``.
z : float
Position in m inside the provider's z domain.
Returns
-------
solprop.modes.vector.ModalNodeRule
The rule at `z`.
Raises
------
solprop.exceptions.ModeError
If `rule` does not say how it was asked for, or the rule at `z` changes its
node count or any node's material region.
"""
identity = rule.identity
missing = [
name
for name in ("omega", "n_r", "n_theta")
if not isinstance(identity.get(name), int | float)
or isinstance(identity.get(name), bool)
]
if missing:
raise ModeError(
f"a moving guide asks its provider for the rule again at every position "
f"of its path, exactly as the entrance rule was asked for, and this rule's "
f"identity does not name its {missing}: pass nodes=None, or a rule "
f"{type(provider).__name__}.node_rule built"
)
omega = float(identity["omega"]) # type: ignore[arg-type]
moved = provider.node_rule(
omega,
float(z),
n_r=int(identity["n_r"]), # type: ignore[arg-type]
n_theta=int(identity["n_theta"]), # type: ignore[arg-type]
)
if moved.weights.shape != rule.weights.shape or not np.array_equal(
moved.region_index, rule.region_index
):
raise ModeError(
f"{type(provider).__name__}'s rule at z = {float(z):.6g} m has "
f"{moved.weights.size} nodes and {rule.weights.size} at the entrance, or "
"a node that changes material between the two: a moving guide's node q "
"is one point moving with the interfaces along the whole path, and the "
"seam carries one region index per node"
)
return moved
def _check_gauge(
reference: ModalSample, sample: ModalSample, nodes: ModalNodeRule, where: str
) -> None:
"""Refuse a provider whose own gauge is not continuous between two samples."""
overlap = cross_poynting(reference, sample, nodes)
diagonal = np.diag(overlap)
size = np.abs(overlap)
off = size - np.diag(np.abs(diagonal))
worst_phase = float(np.max(np.abs(np.angle(diagonal))))
if (
np.any(np.real(diagonal) < MIN_OVERLAP_DOMINANCE)
or np.any(np.max(off, axis=0) >= np.abs(diagonal))
or worst_phase > GAUGE_PHASE_ATOL
):
raise ModeError(
f"the provider's own gauge is not continuous {where}: the channels' "
f"overlaps with their neighbours are {np.round(diagonal, 6).tolist()}, "
f"largest phase {worst_phase:.3e} rad against {GAUGE_PHASE_ATOL:.1e}. A "
"moving guide is expanded in the gauge the provider returns, because its "
"connection is measured in it; a sign that flips, a channel order that "
"changes or a phase that drifts along the path would put a connection "
"in the maps the measured one does not carry"
)
[docs]
def path_snapshot(
provider: ModalProvider,
omega: Float[np.ndarray, " n_omega"],
z: float,
nodes: ModalNodeRule,
*,
degenerate_blocks: Sequence[Sequence[int]] = (),
basis: ChannelBasis | None = None,
gram_atol: float = DEFAULT_GRAM_ATOL,
) -> DenseModalTable:
"""Solve one position of a path over the band, in the provider's own gauge.
Unlike :func:`solprop.modes.tables.sample_modal_table` the knots are
**not** aligned to one another: they are kept exactly as the provider returns
them, with the gauge's continuity across the band checked instead
(:data:`GAUGE_PHASE_ATOL`), because the connection a moving guide is propagated
with is measured in that gauge. A declared `basis` is applied after, as it is
there.
Parameters
----------
provider : solprop.modes.vector.ModalProvider
The guide.
omega : numpy.ndarray
At least four increasing positive frequencies in rad/s, shape (n_omega,).
z : float
Position in m inside the provider's z domain.
nodes : solprop.modes.vector.ModalNodeRule
The rule at `z` (:func:`path_rule`).
degenerate_blocks : sequence of sequence of int, optional
The declared degenerate blocks, retained on the table.
basis : solprop.modes.guide.ChannelBasis or None, optional
A declared constant unitary change of the channel coordinates.
gram_atol : float, optional
The table's construction budget on its sampled Gram defect.
Returns
-------
solprop.modes.tables.DenseModalTable
A snapshot table at `z`.
Raises
------
solprop.exceptions.ModeError
If the provider's gauge is not continuous across the band, or on anything the
provider or the table refuses.
"""
raw: list[ModalSample] = []
for frequency in np.asarray(omega, dtype=float):
sample = provider.solve(float(frequency), float(z), nodes=nodes)
if raw:
_check_gauge(
raw[-1],
sample,
nodes,
f"between {float(raw[-1].omega):.6e} and {float(frequency):.6e} rad/s "
f"at z = {float(z):.6g} m",
)
raw.append(sample)
row = tuple(
raw if basis is None else (apply_channel_basis(one, basis) for one in raw)
)
blocks = tuple(tuple(int(one) for one in block) for block in degenerate_blocks)
return DenseModalTable(
np.asarray(omega, dtype=float),
np.array([float(z)]),
(row,),
nodes,
blocks,
gram_atol,
basis,
)
[docs]
@dataclass(frozen=True, eq=False)
class ModalPathTable(Displayed):
"""Hold a moving guide's snapshots at its path's Chebyshev-Lobatto points.
What :func:`sample_modal_path` returns: the record of how the path was sampled
and the snapshot solved at each of its positions.
Attributes
----------
path : ModalPath
How the path was sampled and what that measured: its section edges, degree,
positions and held-out departures.
tables : tuple of solprop.modes.tables.DenseModalTable
One snapshot per position of ``path.positions``, section by section and
increasing inside each, so a position on an edge between two sections appears
twice, as the end of one and the start of the next.
Raises
------
solprop.exceptions.ModeError
If the tables do not sit at the path's positions, in order.
"""
path: ModalPath
tables: tuple[DenseModalTable, ...]
def __post_init__(self) -> None:
"""Check each table sits where the path places it.
Raises
------
solprop.exceptions.ModeError
Naming the count expected.
"""
path = self.path
expected = path.positions.reshape(-1)
if len(self.tables) != expected.size or any(
float(table.z[0]) != float(position)
for table, position in zip(self.tables, expected, strict=False)
):
raise ModeError(
f"a path of {path.n_intervals} section(s) at degree {path.degree} "
f"holds one snapshot at each of its {expected.size} Chebyshev-Lobatto "
f"positions, in order; got {len(self.tables)}"
)
object.__setattr__(self, "tables", tuple(self.tables))
[docs]
def section_tables(self, index: int) -> tuple[DenseModalTable, ...]:
"""Return one section's snapshots, increasing in z.
Parameters
----------
index : int
The section, in ``[0, path.n_intervals)``.
Returns
-------
tuple of solprop.modes.tables.DenseModalTable
Its ``path.degree + 1`` snapshots.
"""
width = self.path.degree + 1
return self.tables[index * width : (index + 1) * width]
def __repr__(self) -> str:
"""Return a one-line description, never an array.
Returns
-------
str
For example ``ModalPathTable(1 section, degree 8, 9 positions)``.
"""
count = self.path.n_intervals
return line(
"ModalPathTable",
[
("", f"{count} section{'' if count == 1 else 's'}"),
("", f"degree {self.path.degree}"),
("", f"{len(self.tables)} positions"),
],
)
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.
"""
path = self.path
return "ModalPathTable: a moving guide's snapshots along z", [
("sections", path.n_intervals),
(
"span",
f"{engineering(float(path.z_edges[0]), 'm')} to "
f"{engineering(float(path.z_edges[-1]), 'm')}",
),
("degree", path.degree),
("positions", len(self.tables)),
("held-out error", f"{path.z_error:.3e}"),
("gram departure", f"{path.gram_departure:.3e}"),
]
def _stacked(
tables: Sequence[DenseModalTable],
) -> tuple[np.ndarray, np.ndarray, np.ndarray]:
"""Stack the knots' E, H and generator of several snapshots, position first.
- Returns: E and H of shape ``(n_positions, n_knots, n_nodes, 3, n_modes)`` and the
generator of shape ``(n_positions, n_knots, n_modes, n_modes)``.
"""
return tuple( # type: ignore[return-value]
np.array(
[[getattr(sample, name) for sample in table.samples[0]] for table in tables]
)
for name in ("electric", "magnetic", "generator")
)
def _relative(interpolated: np.ndarray, fresh: np.ndarray) -> float:
"""Return the relative maximum-norm departure of an interpolant from a solve.
- ``fresh``: the fresh solve's, of the same shape and not identically zero.
"""
return float(np.max(np.abs(interpolated - fresh)) / np.max(np.abs(fresh)))
def _held_out(
section: Sequence[DenseModalTable],
fresh: Sequence[DenseModalTable],
lo: float,
hi: float,
) -> tuple[float, float]:
"""Measure a section's expansion against fresh solves at the held-out points.
- ``lo``, ``hi``: the section's ends, m.
- Returns: the largest relative departure of E, H and the generator, and the largest
``norm(W - I, 2)`` of the expanded basis on the held-out rule.
"""
degree = len(section) - 1
coefficients = [lobatto_coefficients(one) for one in _stacked(section)]
held = _stacked(fresh)
error = 0.0
departure = 0.0
for index, table in enumerate(fresh):
x = (2.0 * float(table.z[0]) - lo - hi) / (hi - lo)
weights = chebyshev_basis.chebvander(x, degree)[0]
electric, magnetic, generator = (
np.tensordot(weights, one, axes=1) for one in coefficients
)
error = max(
error,
_relative(electric, held[0][index]),
_relative(magnetic, held[1][index]),
_relative(generator, held[2][index]),
)
identity = np.eye(electric.shape[-1])
for knot in range(electric.shape[0]):
metric = flux_product(electric[knot], magnetic[knot], table.nodes.weights)
departure = max(departure, float(np.linalg.norm(metric - identity, ord=2)))
return error, departure
[docs]
def sample_modal_path(
provider: ModalProvider,
omega: Float[np.ndarray, " n_omega"],
rule: ModalNodeRule,
*,
rtol: float | None = None,
sections: int | None = None,
path: ModalPath | None = None,
degenerate_blocks: Sequence[Sequence[int]] = (),
basis: ChannelBasis | None = None,
gram_atol: float = DEFAULT_GRAM_ATOL,
known: Mapping[float, DenseModalTable] | None = None,
) -> ModalPathTable:
"""Sample a moving guide along its sections, at the degree its accuracy demands.
The path is cut into sections (:func:`path_sections`), and each section is solved
at the Chebyshev-Lobatto points of a degree, starting at
:data:`INITIAL_PATH_DEGREE`, on the provider's own rule at each position
(:func:`path_rule`) and in its own gauge (:func:`path_snapshot`). The expansion
along z is then checked against **fresh** solves at the points a doubling adds,
which are the natural held-out points: they lie between every pair of the current
ones and are exactly the solves the next degree needs, so the check costs nothing
the doubling would not. The degree is doubled, for every section together because
the seam's degree axis is rectangular, until the largest relative departure of E,
H and the generator is within `rtol`; the degree then kept is the one whose error
was **measured**, not the doubled one, so that the certificate is a measurement of
what is stored.
With a qualified `path` given instead, nothing is searched or measured: the
snapshots are solved at its edges and degree, and it is carried as it stands,
which is how a run rebuilds the path its guide already qualified.
Parameters
----------
provider : solprop.modes.vector.ModalProvider
The moving guide.
omega : numpy.ndarray
The frequency knots in rad/s, shape (n_omega,), at least four.
rule : solprop.modes.vector.ModalNodeRule
The entrance rule, which every position's rule is asked for like
(:func:`path_rule`).
rtol : float or None, optional
Budget on the held-out departure, positive and finite, for a search; given
unless `path` is.
sections : int or None, optional
Sections per kink interval of a search, positive; ``None`` is one. Not given
with `path`.
path : ModalPath or None, optional
A path already qualified, which skips the search.
degenerate_blocks : sequence of sequence of int, optional
The declared degenerate blocks.
basis : solprop.modes.guide.ChannelBasis or None, optional
A declared constant unitary change of the channel coordinates.
gram_atol : float, optional
Each snapshot's construction budget on its sampled Gram defect.
known : mapping or None, optional
Snapshots already solved, keyed by position, reused rather than solved again.
Returns
-------
ModalPathTable
The path record and its snapshots.
Raises
------
solprop.exceptions.ModeError
If neither or both of a search's budget and a qualified `path` are given,
`rtol` is not positive and finite, `sections` is not a positive integer, the
held-out departure is still above `rtol` at :data:`MAX_PATH_DEGREE`, or on
anything a snapshot refuses.
"""
if (path is None) == (rtol is None) or (path is not None and sections is not None):
raise ModeError(
"a moving guide's path is either searched, within a budget rtol over its "
"sections, or rebuilt from a path already qualified: give rtol (and "
f"sections) or path, not both, got rtol={rtol!r}, sections={sections!r} "
f"and path={path!r}"
)
memo: dict[float, DenseModalTable] = dict(known or {})
def _at(position: float) -> DenseModalTable:
"""Return the snapshot at one position, solving it at most once.
- ``position``: position in m.
"""
if position not in memo:
memo[position] = path_snapshot(
provider,
omega,
position,
path_rule(provider, rule, position),
degenerate_blocks=degenerate_blocks,
basis=basis,
gram_atol=gram_atol,
)
return memo[position]
if path is None:
assert rtol is not None # the budget of a search, checked above
budget = _measure("rtol", rtol, positive=True)
count = 1 if sections is None else sections
edges = path_sections(provider, count)
spans = list(itertools.pairwise(edges))
chosen = INITIAL_PATH_DEGREE
while True:
error = departure = 0.0
for lo, hi in spans:
section = [_at(float(one)) for one in lobatto_points(chosen, lo, hi)]
fresh = [_at(float(one)) for one in refinement_points(chosen, lo, hi)]
measured_error, measured_departure = _held_out(section, fresh, lo, hi)
error = max(error, measured_error)
departure = max(departure, measured_departure)
logger.debug(
"modal path: degree %d over %d section(s), held-out error %.3e against "
"%.3e, gram departure %.3e",
chosen,
len(spans),
error,
budget,
departure,
)
if error <= budget:
break
if 2 * chosen > MAX_PATH_DEGREE:
raise ModeError(
f"a moving guide's expansion along z does not resolve: at degree "
f"{chosen} its held-out departure from a fresh solve is "
f"{error:.4g}, above the {budget:.4g} budget, and the next "
f"degree would exceed {MAX_PATH_DEGREE}. Divide the path into more "
"sections, or declare the structure as a kink of the geometry"
)
chosen *= 2
path = ModalPath(edges, chosen, count, budget, error, departure)
tables = tuple(
_at(float(one))
for lo, hi in itertools.pairwise(path.z_edges)
for one in lobatto_points(path.degree, float(lo), float(hi))
)
# Every neighbouring pair of positions, the ones given in `known` included: the
# check is an overlap per pair and costs nothing beside the solves.
for first, second in itertools.pairwise(sorted(memo)):
_check_gauge(
memo[first].samples[0][0],
memo[second].samples[0][0],
memo[second].nodes,
f"between z = {first:.6g} and {second:.6g} m",
)
return ModalPathTable(path, tables)