Source code for solprop.translate.modal_path

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

r"""Expand what a run reads of a moving guide's sampled path, along z.

A moving guide is sampled in :mod:`solprop.modes.path`: a
:class:`~solprop.modes.path.ModalPathTable` of snapshots at each section's
Chebyshev-Lobatto points, in the provider's own gauge. This module turns that path
into what the seam carries. :func:`path_transform_tables` builds the flat
:class:`~solprop.translate.modal_tables.ModalTransformTables` record whose synthesis
and projection maps are Chebyshev coefficients along z per section
(:func:`section_coefficients`); a stage combines them with :func:`transform_weights`
over the section :func:`transform_section` picks. :func:`path_connections` measures
the moving-basis connection at every sampled position, and :func:`in_frequency`
carries knot values onto a run's frequency bins with the tables' own cubic.
"""

import logging
from collections.abc import Sequence

import numpy as np
from jaxtyping import Complex, Float
from numpy.polynomial import chebyshev as chebyshev_basis
from numpy.typing import ArrayLike
from scipy.interpolate import CubicSpline

from solprop.exceptions import ModeError
from solprop.modes.connection import ModalConnection, band_connection
from solprop.modes.path import ModalPathTable
from solprop.modes.quadrature import lobatto_coefficients
from solprop.modes.vector import ChannelBasis, ModalProvider
from solprop.translate.chebyshev import EDGE_SLACK_FRACTION
from solprop.translate.modal_tables import (
    ModalTransformTables,
    coordinate_dual,
    projection_map,
)

__all__ = [
    "in_frequency",
    "path_connections",
    "path_transform_tables",
    "section_coefficients",
    "transform_section",
    "transform_weights",
]

logger = logging.getLogger(__name__)


[docs] def section_coefficients( values: Complex[np.ndarray, " n_intervals n_positions *value"], ) -> Complex[np.ndarray, " n_intervals n_deg *value"]: """Return the Chebyshev coefficients along z of values sampled per section. Parameters ---------- values : numpy.ndarray Samples at each section's Chebyshev-Lobatto points, increasing, shape ``(n_intervals, degree + 1, *value_shape)``. Returns ------- numpy.ndarray The coefficients :func:`numpy.polynomial.chebyshev.chebval` evaluates on ``x = (2 z - lo - hi)/(hi - lo)``, same shape. Examples -------- >>> import numpy as np >>> from solprop.translate.modal_path import section_coefficients >>> section_coefficients(np.array([[[1.0 + 0j], [1.0 + 0j]]])).round(12).tolist() [[[(1+0j)], [0j]]] """ return np.stack([lobatto_coefficients(one) for one in np.asarray(values)])
[docs] def transform_section(tables: ModalTransformTables, z: float) -> int: """Return the section of a record's maps a position lies in. The maps are **continuous** across a section edge -- the fields at a node are, even at a kink of the geometry, where only their slope jumps -- so which side a position on an edge reads changes the value by the representation error alone and no one-sided rule is needed, unlike the coupled flow's (:func:`solprop.translate.coupled.flow_weights`). A position within ``1e-10`` of the span of an interior edge takes the section starting there, as :func:`solprop.translate.coupled.flow_section` does, and one a rounding outside the span the nearest end's. Parameters ---------- tables : solprop.translate.modal_tables.ModalTransformTables The record. z : float Position in m. Returns ------- int The section index, in ``[0, n_intervals)``. """ edges = tables.z_edges slack = EDGE_SLACK_FRACTION * float(edges[-1] - edges[0]) raw = int(np.searchsorted(edges, float(z) + slack, side="right")) - 1 return min(max(raw, 0), edges.size - 2)
[docs] def transform_weights( tables: ModalTransformTables | None, z: float ) -> Float[np.ndarray, " n_transform_terms"] | None: """Return the weights that combine a record's moving maps at one position. The stage-bundle row of kernel schema 14 (:attr:`solprop.translate.stage.StageScalars.transform_weights`): a backend evaluates ``S(z) = sum_j w_j S_j`` and ``Q(z) = sum_j w_j Q_j`` over the maps' ``(n_intervals, n_deg)`` coefficient axes **flattened**, exactly as it evaluates ``dPhi`` over its terms. Every weight outside the section containing `z` (:func:`transform_section`) is zero, so no section's expansion is extrapolated. ``None`` where there is nothing to combine: no record, a record carrying no maps, or maps of **one** coefficient -- one interval of degree zero, a constant geometry -- whose one term is the map itself. That keeps the stage bundle of every problem whose maps do not move unchanged. Parameters ---------- tables : solprop.translate.modal_tables.ModalTransformTables or None The record, or ``None``. z : float Position in m. Returns ------- numpy.ndarray or None Float64, shape ``(n_intervals * n_deg,)``, or ``None``. Examples -------- >>> from solprop.translate.modal_path import transform_weights >>> transform_weights(None, 0.5) is None True """ if tables is None or tables.synthesis is None: return None intervals, degrees = (int(one) for one in tables.synthesis.shape[:2]) if intervals * degrees == 1: return None index = transform_section(tables, z) lo, hi = float(tables.z_edges[index]), float(tables.z_edges[index + 1]) weights = np.zeros((intervals, degrees), dtype=np.float64) weights[index] = chebyshev_basis.chebvander( (2.0 * float(z) - lo - hi) / (hi - lo), degrees - 1 )[0] return weights.reshape(-1)
[docs] def path_transform_tables( sampled: ModalPathTable, omega: Float[np.ndarray, " n_omega"], *, z_end: float, profile_error: ArrayLike | float, omega_fine: ArrayLike | None = None, policy_id: str = "dense-knots-cubic-frequency-chebyshev-z", ) -> ModalTransformTables: """Build the flat seam record of a moving guide, its maps expanded along z. The moving counterpart of :func:`solprop.translate.modal_tables.modal_transform_tables`. At every sampled position of every section the path covers up to `z_end`, the snapshot is evaluated on the run's coarse grid exactly as a snapshot record's is -- ``S`` the stored electric profile, ``Q = W^-1 conj(e) w / 4`` with **that position's** area weights -- and each section's samples become Chebyshev coefficients along z (:func:`section_coefficients`), which is the ``(n_intervals, n_deg)`` layout the record's maps have always had. The dense reference, its partners, the coordinate dual, the node positions and the weights are stored at the section edges, which are the record's ``z_edges``; the region index is the path's one per node. Outside the band the maps are explicitly zero, as a snapshot's are. Parameters ---------- sampled : solprop.modes.path.ModalPathTable The sampled path. omega : numpy.ndarray Coarse angular frequencies in rad/s, shape (n_omega,), increasing. z_end : float Where the run ends, m; the record keeps every section up to the one that contains it, so it covers the run and nothing is extrapolated. profile_error : array_like or float Declared non-negative profile error per section and coarse frequency, or one value for all. omega_fine : array_like or None, optional Fine angular frequencies in rad/s; ``None`` uses the coarse grid. policy_id : str, optional Identity of the numeric policy the record was built under. Returns ------- solprop.translate.modal_tables.ModalTransformTables The record, with maps of ``n_intervals`` sections and ``degree + 1`` coefficients each. Raises ------ solprop.exceptions.ModeError If the path does not reach `z_end`, or the record does not validate. """ end = float(z_end) path = sampled.path edges = path.z_edges if not edges[0] <= 0.0 < end <= edges[-1]: raise ModeError( f"a moving guide's path covers [{float(edges[0]):.6g}, " f"{float(edges[-1]):.6g}] m and the run [0, {end:.6g}] m: the geometry is " "declared over the provider's own z domain, and a run past its end would " "hold the last position's modes over the rest in silence" ) kept = int(np.searchsorted(edges, end, side="left")) kept = max(kept, 1) coarse = np.ascontiguousarray(omega, dtype=np.float64) fine = coarse if omega_fine is None else np.ascontiguousarray(omega_fine, float) first = sampled.tables[0] reference = first.samples[0][0] modes = int(reference.electric.shape[2]) nodes = int(first.nodes.weights.size) inside = (first.omega[0] <= coarse) & (coarse <= first.omega[-1]) inside_fine = (first.omega[0] <= fine) & (fine <= first.omega[-1]) width = path.degree + 1 synthesis = np.zeros((kept, width, nodes, 3, modes, coarse.size), np.complex128) projection = np.zeros((kept, width, modes, nodes, 3, coarse.size), np.complex128) for section in range(kept): for position, table in enumerate(sampled.section_tables(section)): weights = table.nodes.weights for column in np.flatnonzero(inside): sample = table.evaluate(float(coarse[column]), float(table.z[0])) synthesis[section, position, :, :, :, column] = sample.electric projection[section, position, :, :, :, column] = projection_map( sample, weights ) synthesis = section_coefficients(synthesis) projection = section_coefficients(projection) ends = [sampled.section_tables(index)[0] for index in range(kept)] ends.append(sampled.section_tables(kept - 1)[-1]) reciprocal = reference.reciprocal_gram is not None shape = (len(ends), nodes, 3, modes, coarse.size) electric = np.zeros(shape, np.complex128) magnetic = np.zeros(shape, np.complex128) backward = [ np.zeros(shape, np.complex128) if reciprocal else None for _ in range(2) ] gram = ( np.zeros((len(ends), modes, modes, coarse.size), np.complex128) if reciprocal else None ) dual = np.zeros((len(ends), modes, nodes, 6, coarse.size), np.complex128) for row, table in enumerate(ends): for column in np.flatnonzero(inside): sample = table.evaluate(float(coarse[column]), float(table.z[0])) electric[row, :, :, :, column] = sample.electric magnetic[row, :, :, :, column] = sample.magnetic dual[row, :, :, :, column] = coordinate_dual(sample, table.nodes.weights) if backward[0] is not None and backward[1] is not None: backward[0][row, :, :, :, column] = sample.backward_electric backward[1][row, :, :, :, column] = sample.backward_magnetic if gram is not None: gram[row, :, :, column] = sample.reciprocal_gram logger.debug( "moving modal transform tables: %d channels on %d nodes, %d section(s) at " "degree %d, %d of %d coarse frequencies inside the band", modes, nodes, kept, path.degree, int(np.count_nonzero(inside)), coarse.size, ) return ModalTransformTables( coarse, fine, edges[: kept + 1], synthesis, projection, electric, magnetic, backward[0], backward[1], gram, dual, np.stack([table.nodes.xy for table in ends]), np.stack([table.nodes.weights for table in ends]), first.nodes.region_index, -1j * coarse, np.broadcast_to(inside_fine, (len(ends), modes, fine.size)), np.broadcast_to( np.asarray(profile_error, dtype=np.float64), (kept, coarse.size) ), None, reference.gauge_id, reference.physical_id, policy_id, )
[docs] def path_connections( sampled: ModalPathTable, provider: ModalProvider, *, sections: int | None = None, degenerate_blocks: Sequence[Sequence[int]] = (), basis: ChannelBasis | None = None, n_r: int | None = None, n_theta: int | None = None, ) -> tuple[tuple[ModalConnection, ...], ...]: """Measure the moving-basis connection at every sampled position of a path. :func:`solprop.modes.connection.band_connection` at each position and every frequency knot, in the provider's own gauge with the declared basis applied, which is the gauge the path's snapshots are in (:func:`~solprop.modes.path.path_snapshot`). A position on a section's **end** is measured one ulp inside it, so that its stencil is taken on that section's own side of an edge: at a kink of the geometry the slope jumps and the connection with it, and the section that closes there must read its own one-sided limit (the rule of the coupled flow's :func:`solprop.translate.coupled.flow_weights`, applied where it is sampled). Parameters ---------- sampled : solprop.modes.path.ModalPathTable The sampled path. provider : solprop.modes.vector.ModalProvider The moving guide. sections : int or None, optional How many of the path's sections to measure, from the first; ``None`` measures them all. degenerate_blocks : sequence of sequence of int, optional The declared degenerate blocks. basis : solprop.modes.guide.ChannelBasis or None, optional The declared constant unitary change of the channel coordinates. n_r, n_theta : int or None, optional The resolution each stencil position's rule is asked for. Returns ------- tuple Per position of the measured sections, section by section, one :class:`~solprop.modes.connection.ModalConnection` per frequency knot. """ path = sampled.path count = path.n_intervals if sections is None else int(sections) width = path.degree + 1 result: list[tuple[ModalConnection, ...]] = [] for index in range(count): lo, hi = float(path.z_edges[index]), float(path.z_edges[index + 1]) inset = float(np.spacing(max(abs(lo), abs(hi), hi - lo))) for position, table in enumerate(sampled.section_tables(index)): z = float(table.z[0]) if position == 0: z = lo + inset elif position == width - 1: z = hi - inset result.append( band_connection( provider, table.omega, z, degenerate_blocks=degenerate_blocks, basis=basis, n_r=n_r, n_theta=n_theta, ) ) return tuple(result)
[docs] def in_frequency( knots: Float[np.ndarray, " n_knots"], values: Complex[np.ndarray, " n_knots *value"], omega: Float[np.ndarray, " n_omega"], inside: np.ndarray, ) -> Complex[np.ndarray, "*value n_omega"]: """Return knot values interpolated onto a run's bins, zero outside the band. The same not-a-knot cubic in frequency the dense tables interpolate their fields with (:class:`solprop.modes.tables.DenseModalTable`), so a connection and the maps it is propagated beside are carried onto the run's grid alike. Parameters ---------- knots : numpy.ndarray The knots in rad/s, increasing, shape (n_knots,). values : numpy.ndarray Values at the knots, knot axis first. omega : numpy.ndarray The run's coarse bins in rad/s, shape (n_omega,). inside : numpy.ndarray Which bins lie inside the knots, bool, shape (n_omega,). Returns ------- numpy.ndarray The values with the frequency axis **last**, zero outside `inside`. """ spline = CubicSpline(knots, values, axis=0, extrapolate=False) result = np.zeros((*np.shape(values)[1:], np.size(omega)), dtype=np.complex128) if np.any(inside): result[..., inside] = np.moveaxis(spline(np.asarray(omega)[inside]), 0, -1) return result