Source code for solprop.stats.spec

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

"""The request a run records statistics by: :class:`StatsSpec` and its apertures.

- :class:`StatsSpec`: the names, the between-planes subset, the energy windows and the
  far-field regions and apertures, checked against the catalogue on construction.
- :class:`ApertureSet`, :data:`ApertureWeighting`, :func:`check_aperture_choices` and
  the limits :data:`MAX_APERTURES` and :data:`MAX_REGIONS` (SEP 23).
- :func:`far_field_tables`: the far-field statistics' tables of a spec on Cartesian
  columns, which every backend and the saved-plane statistics share.
"""

import math
import warnings
from collections.abc import Sequence
from dataclasses import dataclass, field
from typing import Literal

import numpy as np
from jaxtyping import Complex, Float

from solprop.exceptions import ApertureEdgeWarning, OutputError, ProcessingError
from solprop.spatial import (
    ApertureOutline,
    ApertureProfile,
    ApertureShape,
    ApertureTables,
    aperture_outline,
    aperture_scale,
    check_aperture_profile,
    check_aperture_shape,
)
from solprop.stats.catalogue import CATALOGUE

__all__ = [
    "MAX_APERTURES",
    "MAX_REGIONS",
    "ApertureSet",
    "ApertureWeighting",
    "StatsSpec",
    "check_aperture_choices",
    "far_field_tables",
]


ApertureWeighting = Literal["amplitude", "quadrature"]
"""How an aperture's profile weights the collected spectrum (SEP 23 section 4.5)."""

MAX_APERTURES = 16
"""The most apertures one :class:`ApertureSet` carries."""

MAX_REGIONS = 16
"""The most rows :attr:`StatsSpec.spectral_regions` carries."""


def _aperture_array(
    values: object, shape: tuple[int, ...] | None, name: str
) -> np.ndarray:
    """Own a finite float64 copy of one aperture table, read-only.

    - ``shape``: the shape it must have; ``None`` asks for any flat vector.
    - Returns: a read-only, C-contiguous float64 copy.
    """
    stated = "a flat vector" if shape is None else f"shape {shape}"
    try:
        array = np.array(values, dtype=np.float64, order="C", copy=True)
    except (TypeError, ValueError) as error:
        msg = f"ApertureSet.{name} must be numeric, {stated}"
        raise OutputError(msg) from error
    fits = array.ndim == 1 if shape is None else array.shape == shape
    if not fits or not np.all(np.isfinite(array)):
        msg = f"ApertureSet.{name} must be finite, {stated}, got {array.shape}"
        raise OutputError(msg)
    array.setflags(write=False)
    return array


[docs] def check_aperture_choices(profile: object, weighting: object) -> None: """Refuse, by name, an aperture profile or weighting that does not exist. The check :class:`ApertureSet` makes of its two choices. It takes any object, because a caller outside the test session's runtime type checker can pass anything. Parameters ---------- profile : object The edge profile asked for. weighting : object The weighting asked for. Raises ------ OutputError If either is not one of its choices. Examples -------- >>> from solprop.stats import check_aperture_choices >>> check_aperture_choices("tanh", "quadrature") is None True """ check_aperture_profile(profile) if weighting not in ("amplitude", "quadrature"): msg = ( f"unknown aperture weighting {weighting!r}; choose 'amplitude' or " "'quadrature'" ) raise OutputError(msg)
def _off_axis(shape: str) -> int: """Return the index of the coordinate a half-plane does not depend on.""" return 1 if shape.startswith("half_plane_x") else 0
[docs] @dataclass(frozen=True, eq=False) class ApertureSet: """Apertures in a far-field or Fourier plane behind a free-space run. The tables of ``aperture_spectrum`` and ``aperture_on_axis_spectrum`` (SEP 23): each aperture collects the light whose paraxial image ``x = z c kappa / omega`` falls inside it, a chromatic weight on the stored transverse spectrum. Every position is physical: a beam travelling towards positive x lands at positive x. Circles by default; `shapes` asks for an ellipse, a rectangle or a half-plane on any row. Equality is by identity; the arrays are owned read-only copies. Attributes ---------- centres : numpy.ndarray Aperture centres ``(x, y)`` in the mask plane, in m, shape ``(n_apertures, 2)``. A half-plane has an edge rather than a centre: its row holds the edge's position on the axis it names and zero on the other. diameters : numpy.ndarray Diameters in m, shape ``(n_apertures,)``: finite and positive on a circle's row, zero on any other. On a line a circle is a slit of this full width along x. distances : numpy.ndarray Distance from the exit face to the mask plane, or a lens's focal length for a Fourier plane, in m, finite and positive, shape ``(n_apertures,)``. edges : numpy.ndarray or None Edge widths ``w`` in m for ``tanh`` and ``rcos``, orders ``n >= 2`` for ``supergauss``, zero for a ``hard`` row beside others, shape ``(n_apertures,)``; ``None`` when every row is ``hard``, and only then. An ellipse's edge width is in its circular frame: ``w a/sqrt(a b)`` along x and ``w b/sqrt(a b)`` along y, in m. profile : {'hard', 'tanh', 'rcos', 'supergauss'} The edge profile the set shares (:func:`solprop.spatial.aperture_profile`). The default is ``hard``. weighting : {'amplitude', 'quadrature'} ``amplitude`` (the default) models a mask of amplitude transmission ``W`` and weights the collected spectrum by ``W**2``; ``quadrature`` uses a smooth profile once, at the corrected diameter, as a quadrature weight for a hard hole. Quadrature is refused with ``supergauss``. labels : tuple of str One unique non-empty label per aperture, recorded with the run's configuration; ``None`` (the default) labels them ``"0"``, ``"1"``, ... shapes : tuple of str or None Each row's outline, one of :data:`solprop.spatial.APERTURE_SHAPES`: ``circle``, ``ellipse``, ``rectangle``, or a half-plane named for the side it keeps, ``half_plane_x_ge`` (``x >= X``), ``half_plane_x_lt`` (``x < X``), ``half_plane_y_ge`` and ``half_plane_y_lt``. ``None`` (the default) is a circle on every row, and all circles are stored as ``None``. A set of unset shapes, profiles and extents records and hashes as it did before they existed. profiles : tuple of str or None Each row's edge profile, for a set that mixes them; ``profile`` is then left at its default, and rows that all agree are stored as that ``profile``. extents : numpy.ndarray or None Full widths ``(D_x, D_y)`` in m, shape ``(n_apertures, 2)``: finite and positive on the row of an ellipse or a rectangle, zero on any other; ``None`` when no row needs them, and only then. Raises ------ OutputError If there are no apertures or more than :data:`~solprop.stats.spec.MAX_APERTURES`; an array is not finite or not of its stated shape; a diameter, an extent or a distance breaks its rule above; a half-plane's centre is off the axis it names; an edge is missing, given for a ``hard`` set or row, or out of its range (with ``D`` a circle's diameter, ``sqrt(D_x D_y)`` of an ellipse and the smaller of a rectangle's widths: ``0 < w <= D/4`` for ``rcos`` and for ``tanh`` under amplitude weighting, ``0 < w <= D/8`` for ``tanh`` under quadrature weighting, ``D/10`` on a rectangle; ``w > 0`` on a half-plane; ``n >= 2`` for ``supergauss``); quadrature weighting or a half-plane is asked of ``supergauss``; ``profile`` is given beside `profiles`; an aperture reaches the paraxial disc's edge, ``|X| + D/2 (+ w for rcos) >= z`` (a half-plane's edge must lie inside it); or the labels are not unique non-empty strings, one per aperture. Warns ----- solprop.exceptions.ApertureEdgeWarning Once per set, for ``tanh`` under amplitude weighting with ``r/w < 4`` (``w > D/8``): the profile slopes at its centre, so a bright beam there is collected with a lattice error near ``1e-5``. The set is built as asked; ``rcos`` is the recommended smooth profile. Examples -------- >>> from solprop.stats import ApertureSet >>> holes = ApertureSet( ... centres=[[4e-3, 4e-3], [-4e-3, -4e-3]], ... diameters=[1.5e-3, 1.5e-3], ... distances=[0.25, 0.25], ... edges=[40e-6, 40e-6], ... profile="tanh", ... weighting="quadrature", ... labels=("probe", "signal"), ... ) >>> holes.n_apertures, holes.labels (2, ('probe', 'signal')) A knife edge at a fixed position in the plane, beside an apodised hole: >>> mixed = ApertureSet( ... centres=[[2e-3, 0.0], [-4e-3, 0.0]], ... diameters=[0.0, 1.5e-3], ... distances=[0.25, 0.25], ... edges=[0.0, 40e-6], ... shapes=("half_plane_x_ge", "circle"), ... profiles=("hard", "rcos"), ... ) >>> mixed.row_shapes ('half_plane_x_ge', 'circle') """ centres: Sequence[Sequence[float]] | np.ndarray diameters: Sequence[float] | np.ndarray distances: Sequence[float] | np.ndarray edges: Sequence[float] | np.ndarray | None = None profile: ApertureProfile = "hard" weighting: ApertureWeighting = "amplitude" labels: tuple[str, ...] | None = None shapes: tuple[ApertureShape, ...] | None = None profiles: tuple[ApertureProfile, ...] | None = None extents: Sequence[Sequence[float]] | np.ndarray | None = None def __post_init__(self) -> None: """Own the tables and check them against the list of SEP 23 section 5. Raises ------ OutputError Naming the field and the rule it breaks. """ diameters = _aperture_array(self.diameters, None, "diameters") count = diameters.size if not 1 <= count <= MAX_APERTURES: msg = f"an ApertureSet holds 1 to {MAX_APERTURES} apertures, got {count}" raise OutputError(msg) object.__setattr__(self, "diameters", diameters) object.__setattr__( self, "centres", _aperture_array(self.centres, (count, 2), "centres") ) object.__setattr__( self, "distances", _aperture_array(self.distances, (count,), "distances") ) check_aperture_choices(self.profile, self.weighting) self._adopt_rows(count) self._check_outlines(count) if np.any(np.asarray(self.distances) <= 0): msg = "every aperture diameter and distance must be positive" raise OutputError(msg) self._check_edges(count) self._check_paraxial() labels = ( tuple(str(index) for index in range(count)) if self.labels is None else tuple(self.labels) ) if ( len(labels) != count or any(not isinstance(label, str) or not label for label in labels) or len(set(labels)) != count ): msg = f"ApertureSet.labels must be {count} unique non-empty strings" raise OutputError(msg) object.__setattr__(self, "labels", labels) def _adopt_rows(self, count: int) -> None: """Check the per-row choices and store rows that say nothing new as unset. All circles are stored as no `shapes`, and rows of one profile as that `profile`, so that one request has one record. """ if self.shapes is not None: shapes = tuple(self.shapes) if len(shapes) != count: msg = f"ApertureSet.shapes must hold {count}, got {len(shapes)}" raise OutputError(msg) for shape in shapes: check_aperture_shape(shape) object.__setattr__( self, "shapes", None if set(shapes) == {"circle"} else shapes ) if self.profiles is None: return profiles = tuple(self.profiles) if len(profiles) != count: msg = ( f"ApertureSet.profiles must hold {count} profiles, got {len(profiles)}" ) raise OutputError(msg) for profile in profiles: check_aperture_profile(profile) if self.profile != "hard": msg = ( "give the set's edge profile or a profile per row, not both; pass " "profile or profiles" ) raise OutputError(msg) one = set(profiles) object.__setattr__(self, "profile", profiles[0] if len(one) == 1 else "hard") object.__setattr__(self, "profiles", None if len(one) == 1 else profiles) def _check_outlines(self, count: int) -> None: """Own the extents and check each row's measures against its shape.""" shapes = self.row_shapes circle = np.array([shape == "circle" for shape in shapes]) sized = np.array([shape in ("ellipse", "rectangle") for shape in shapes]) diameters = np.asarray(self.diameters) if np.any(diameters[circle] <= 0): msg = "every aperture diameter and distance must be positive" raise OutputError(msg) if np.any(diameters[~circle] != 0): msg = "a diameter is a circle's; give zero on every row of another shape" raise OutputError(msg) if self.extents is None: if np.any(sized): msg = "an ellipse or a rectangle needs extents, (D_x, D_y) per aperture" raise OutputError(msg) else: extents = _aperture_array(self.extents, (count, 2), "extents") object.__setattr__(self, "extents", extents) if not np.any(sized): msg = ( "extents are an ellipse's or a rectangle's, and would be silently " "unused here; pass extents=None" ) raise OutputError(msg) if np.any(extents[sized] <= 0) or np.any(extents[~sized] != 0): msg = ( "ApertureSet.extents must be positive on the row of an ellipse or " "a rectangle and zero on any other" ) raise OutputError(msg) centres = np.asarray(self.centres) for row, shape in enumerate(shapes): if shape.startswith("half_plane") and centres[row, _off_axis(shape)] != 0: msg = ( f"aperture {row}, a half-plane, has an edge on one axis only; its " "centre on the other must be zero" ) raise OutputError(msg) def _edge_measures(self) -> Float[np.ndarray, " n_apertures"]: """Return the width each row's edge width is measured against. - Returns: a circle's diameter, ``sqrt(D_x D_y)`` of an ellipse (the diameter of its circular frame), the smaller of a rectangle's widths, and zero on a half-plane, which has none, in m, shape ``(n_apertures,)``. """ measures = np.array(np.asarray(self.diameters)) if self.extents is not None: extents = np.asarray(self.extents) for row, shape in enumerate(self.row_shapes): if shape == "ellipse": measures[row] = math.sqrt(extents[row, 0] * extents[row, 1]) elif shape == "rectangle": measures[row] = np.min(extents[row]) return measures def _check_edges(self, count: int) -> None: """Own the edge table and check it against the profiles and the weighting.""" kinds = self.row_profiles smooth = [kind for kind in kinds if kind != "hard"] if not smooth: if self.edges is not None: msg = ( "a hard aperture has no edge, and an edge given beside it would " "be silently unused; pass edges=None" ) raise OutputError(msg) return if self.edges is None: msg = f"a {smooth[0]} aperture needs edges, one per aperture" raise OutputError(msg) edges = _aperture_array(self.edges, (count,), "edges") object.__setattr__(self, "edges", edges) rows = np.array(kinds) if np.any(edges[rows == "hard"] != 0): msg = ( "a hard aperture has no edge, and an edge given beside it would be " "silently unused; give zero on its row" ) raise OutputError(msg) for kind in dict.fromkeys(smooth): if kind == "supergauss": self._check_orders(edges, rows == kind) else: self._check_widths(kind, edges, rows == kind) def _check_orders( self, edges: Float[np.ndarray, " n_apertures"], rows: np.ndarray ) -> None: """Check the rows with a supergauss profile.""" if self.weighting == "quadrature": msg = ( "quadrature weighting needs a symmetric edge, and a supergauss " "profile has none; use amplitude weighting" ) raise OutputError(msg) if any( shape.startswith("half_plane") for shape, row in zip(self.row_shapes, rows, strict=True) if row ): msg = ( "a supergauss profile falls from a centre, and a half-plane has none; " "use a hard, tanh or rcos edge" ) raise OutputError(msg) if np.any(edges[rows] < 2): msg = "every supergauss order must be at least 2" raise OutputError(msg) def _check_widths( self, kind: str, edges: Float[np.ndarray, " n_apertures"], rows: np.ndarray ) -> None: """Check the rows with one symmetric edge profile. - ``kind``: the profile, ``tanh`` or ``rcos``. """ shapes = self.row_shapes half_plane = np.array([shape.startswith("half_plane") for shape in shapes]) rectangle = np.array([shape == "rectangle" for shape in shapes]) tail = kind == "tanh" and self.weighting == "quadrature" measures = self._edge_measures() for chosen, fraction in ( (rows & ~half_plane & ~rectangle, 8 if tail else 4), # Two tails, each (w/2a) exp(-2a/w) of a width: D/10 keeps their sum below # the 2e-5 that D/8 keeps a circle's (SEP 23 section 4.5). (rows & rectangle, 10 if tail else 4), ): if np.any(edges[chosen] <= 0) or np.any( edges[chosen] > measures[chosen] / fraction ): msg = ( f"a {kind} aperture under {self.weighting} weighting needs " f"0 < w <= D/{fraction} for every aperture" ) raise OutputError(msg) if np.any(edges[rows & half_plane] <= 0): msg = f"a {kind} half-plane needs a positive edge width" raise OutputError(msg) if kind == "tanh" and self.weighting == "amplitude": # tanh is not flat at its centre: W'(0) = -sech^2(r/w) / 2w, so for # r/w < 4 a bright beam there converges only at third order in the mask # plane's spacing (about 1e-5 of the collected energy at r/w = 2). At # r/w >= 4 the slope is 0.02 of that and the error near 2e-7. wide = np.flatnonzero(rows & ~half_plane & (measures / 2 < 4 * edges)) if wide.size: warnings.warn( f"tanh apertures {wide.tolist()} under amplitude weighting have " "r/w < 4: the profile slopes at its centre, so light there is " "collected with a lattice error near 1e-5; rcos is flat inside " "r - w and is preferred (or w <= D/8)", ApertureEdgeWarning, stacklevel=5, ) def _check_paraxial(self) -> None: """Check that every aperture lies inside the paraxial disc ``|x| < z``. A half-plane reaches the disc's edge by its nature, and the columns there carry zero weight (SEP 23 section 4.2); its edge must lie inside the disc, or it would select all of the disc or nothing. """ centres = np.asarray(self.centres) reach = np.array( [ self._reach(row, shape, centres[row]) for row, shape in enumerate(self.row_shapes) ] ) outside = np.flatnonzero(reach >= np.asarray(self.distances)) if outside.size: msg = ( f"apertures {outside.tolist()} reach the paraxial disc's edge, " "|X| + D/2 (+ w for rcos) >= z; a component there cannot leave the " "exit face (SEP 23 section 4.2)" ) raise OutputError(msg) def _reach(self, row: int, shape: str, centre: Float[np.ndarray, " 2"]) -> float: """Return how far from the origin a row's outline reaches in the mask plane. - ``centre``: its centre, m. - Returns: the reach in m. A raised cosine's reaches its edge width further out; the unbounded ``tanh`` and ``supergauss`` tails are zeroed at the disc's edge. """ width = ( float(np.asarray(self.edges)[row]) if self.row_profiles[row] == "rcos" else 0.0 ) if shape.startswith("half_plane"): return float(abs(centre[1 - _off_axis(shape)])) + width if shape == "circle": return ( float(np.hypot(centre[0], centre[1])) + float(np.asarray(self.diameters)[row]) / 2 + width ) half_x, half_y = 0.5 * np.asarray(self.extents)[row] if shape == "rectangle": return float( np.hypot( abs(centre[0]) + half_x + width, abs(centre[1]) + half_y + width ) ) # The ellipse's semi-axes grow by w/sqrt(a b) of themselves in its frame. grown = max(half_x, half_y) * (1.0 + width / math.sqrt(half_x * half_y)) return float(np.hypot(centre[0], centre[1])) + float(grown)
[docs] @property def row_shapes(self) -> tuple[ApertureShape, ...]: # numpydoc ignore=RT01 """Every row's outline. One of :data:`solprop.spatial.APERTURE_SHAPES` per aperture. """ if self.shapes is None: return ("circle",) * int(np.asarray(self.diameters).size) return self.shapes
[docs] @property def row_profiles(self) -> tuple[ApertureProfile, ...]: # numpydoc ignore=RT01 """Every row's edge profile. One of :data:`solprop.spatial.APERTURE_PROFILES` per aperture. """ if self.profiles is None: return (self.profile,) * int(np.asarray(self.diameters).size) return self.profiles
[docs] @property def n_apertures(self) -> int: # numpydoc ignore=RT01 """How many apertures the set holds.""" return int(np.asarray(self.diameters).size)
[docs] def same_as(self, other: "ApertureSet | None") -> bool: """Return whether another set describes the same apertures, entry for entry. Parameters ---------- other : ApertureSet or None The set to compare. Returns ------- bool True when every table, each row's shape and profile, the weighting and the labels agree exactly: a structural comparison of two requests. """ if other is None: return False tables = ("centres", "diameters", "distances") return ( all( np.array_equal(np.asarray(getattr(self, name)), getattr(other, name)) for name in tables ) and all( (mine is None) == (theirs is None) and ( mine is None or np.array_equal(np.asarray(mine), np.asarray(theirs)) ) for mine, theirs in ( (self.edges, other.edges), (self.extents, other.extents), ) ) and (self.row_shapes, self.row_profiles, self.weighting, self.labels) == (other.row_shapes, other.row_profiles, other.weighting, other.labels) )
def _no_windows() -> Float[np.ndarray, "n_windows 2"]: """Return the empty window list a spec defaults to.""" return np.empty((0, 2)) def _no_regions() -> Float[np.ndarray, "n_regions 4"]: """Return the empty region table a spec defaults to.""" return np.empty((0, 4)) _APERTURE_NAMES = frozenset( name for name, entry in CATALOGUE.items() if "apertures" in entry.requires ) """The statistics that read :attr:`StatsSpec.apertures`."""
[docs] @dataclass(frozen=True, eq=False) class StatsSpec: """Which statistics a run asks for, and the windows and period they need. This is the object of the kernel contract §8: the translation layer carries it into a backend, the driver hands it to :func:`~solprop.stats.collect`, and both read the same names. Equality is by identity (``eq=False``) because ``energy_windows`` is an array. Attributes ---------- names : tuple Statistics to evaluate at every saved plane, in the order they are evaluated. Every name must be in :data:`~solprop.stats.catalogue.CATALOGUE` and must be implemented. energy_windows : numpy.ndarray Spectral windows, shape ``(n_windows, 2)``, rad/s, each row ``(lo, hi)`` with ``lo < hi``. Infinite edges are allowed, so that a pair of windows can tile the whole axis. Required by ``energy_window`` and ``peak_power_window``. periodic : tuple The subset of ``names`` a backend also evaluates between planes, for step-level diagnostics. Must be a subset of ``names``, and every entry must carry :attr:`~solprop.stats.StatDefinition.between_planes`: a statistic whose cost is only bearable once per plane is refused here rather than made the run's per-step cost. period : int How many accepted steps apart the periodic subset is evaluated, at least 1. apertures : ApertureSet or None Far-field apertures, required by ``aperture_spectrum`` and ``aperture_on_axis_spectrum`` (SEP 23). ``None`` by default, and then left out of the run's configuration record, so every earlier record keeps its hash. spectral_regions : numpy.ndarray Boxes of physical transverse wavevector in rad/m, shape ``(n_regions, 4)``, rows ``(kx_lo, kx_hi, ky_lo, ky_hi)``, each a half-open box ``[lo, hi)`` on both axes, at most :data:`~solprop.stats.spec.MAX_REGIONS` rows, infinite edges allowed. Required by ``region_spectrum``. Empty by default, and then left out of the configuration record. Raises ------ ProcessingError If a name is unknown, reserved or repeated; if a window or a region is malformed; if ``periodic`` is not a subset of ``names`` or names a statistic no backend evaluates between planes; if ``period`` is below 1; or if a name needs a far-field table the spec does not carry. Examples -------- >>> import numpy as np >>> from solprop.stats import StatsSpec >>> spec = StatsSpec( ... names=("energy", "energy_window"), ... energy_windows=np.array([[2.0e15, 3.0e15]]), ... ) >>> spec.n_windows 1 """ names: tuple[str, ...] = () energy_windows: Float[np.ndarray, "n_windows 2"] = field( default_factory=_no_windows ) periodic: tuple[str, ...] = () period: int = 1 apertures: ApertureSet | None = None spectral_regions: Float[np.ndarray, "n_regions 4"] = field( default_factory=_no_regions ) def __post_init__(self) -> None: """Check the names, the tables and the period, and freeze the tables. Raises ------ ProcessingError If a name is unknown, reserved or repeated; if a window or a region is malformed; if ``periodic`` is not a subset of ``names`` or names a statistic no backend evaluates between planes; if ``period`` is below 1; or if a name needs a far-field table the spec does not carry. """ object.__setattr__(self, "names", tuple(self.names)) object.__setattr__(self, "periodic", tuple(self.periodic)) _check_names(self.names) extra = sorted(set(self.periodic) - set(self.names)) if extra: msg = f"the periodic subset asks for statistics the run does not: {extra}" raise ProcessingError(msg) _check_between_planes(self.periodic) if self.period < 1: msg = f"the statistics period must be at least 1, got {self.period}" raise ProcessingError(msg) windows = np.array(self.energy_windows, dtype=np.float64, copy=True) _check_windows(windows) windows.setflags(write=False) object.__setattr__(self, "energy_windows", windows) regions = np.array(self.spectral_regions, dtype=np.float64, copy=True) _check_regions(regions) regions.setflags(write=False) object.__setattr__(self, "spectral_regions", regions) missing = ( sorted(set(self.names) & _APERTURE_NAMES) if self.apertures is None else [] ) if "region_spectrum" in self.names and self.n_regions == 0: missing.append("region_spectrum") if missing: msg = ( f"the statistics {missing} need a far-field table this spec does not " "carry: apertures=ApertureSet(...) for the aperture spectra, " "spectral_regions for region_spectrum" ) raise ProcessingError(msg)
[docs] @property def n_apertures(self) -> int: # numpydoc ignore=RT01 """How many far-field apertures the spec carries. The apertures of :attr:`apertures`, or zero without them. """ return 0 if self.apertures is None else self.apertures.n_apertures
[docs] @property def n_regions(self) -> int: # numpydoc ignore=RT01 """How many regions of transverse wavevector the spec carries. The rows of :attr:`spectral_regions`. """ return int(self.spectral_regions.shape[0])
[docs] @property def n_windows(self) -> int: # numpydoc ignore=RT01 """How many spectral windows the spec carries.""" return int(self.energy_windows.shape[0])
def _check_names(names: Sequence[str]) -> None: """Check that every requested statistic exists and appears once.""" unknown = sorted(set(names) - set(CATALOGUE)) if unknown: msg = f"unknown statistics {unknown}; the catalogue holds {sorted(CATALOGUE)}" raise ProcessingError(msg) repeated = sorted({name for name in names if list(names).count(name) > 1}) if repeated: msg = f"each statistic may be asked for once; these repeat: {repeated}" raise ProcessingError(msg) def _check_between_planes(names: Sequence[str]) -> None: """Check that every periodic statistic is one a backend evaluates between planes. The refusal is by name and at construction because evaluating them anyway can cost a fifth of a step: ``zdw`` is a root search per mode and does not belong on every accepted step. """ refused = sorted(name for name in names if not CATALOGUE[name].between_planes) if refused: available = sorted( name for name, entry in CATALOGUE.items() if entry.between_planes ) msg = ( f"the statistics {refused} cannot be evaluated between save planes, only " f"at them; the periodic subset may name {available}" ) raise ProcessingError(msg) def _check_windows(windows: Float[np.ndarray, "n_windows 2"]) -> None: """Check that every spectral window is a properly ordered pair. - ``windows``: window edges, shape ``(n_windows, 2)``, rad/s. """ if np.isnan(windows).any(): msg = "energy_windows must not hold a NaN edge" raise ProcessingError(msg) bad = np.flatnonzero(windows[:, 0] >= windows[:, 1]) if bad.size: msg = ( f"every energy window needs lo < hi; rows {bad.tolist()} do not: " f"{windows[bad].tolist()}" ) raise ProcessingError(msg) def _check_regions(regions: Float[np.ndarray, "n_regions 4"]) -> None: """Check that every region of transverse wavevector is a properly ordered box. - ``regions``: region edges, shape ``(n_regions, 4)``, rad/m. """ if regions.shape[0] > MAX_REGIONS: msg = ( f"spectral_regions holds at most {MAX_REGIONS} rows, got {regions.shape[0]}" ) raise ProcessingError(msg) if np.isnan(regions).any(): msg = "spectral_regions must not hold a NaN edge" raise ProcessingError(msg) bad = np.flatnonzero( (regions[:, 0] >= regions[:, 1]) | (regions[:, 2] >= regions[:, 3]) ) if bad.size: msg = ( f"every spectral region needs lo < hi on both axes; rows {bad.tolist()} " f"do not: {regions[bad].tolist()}" ) raise ProcessingError(msg)
[docs] def far_field_tables( spec: StatsSpec, omega: Float[np.ndarray, " n_omega"], *, k_x: Float[np.ndarray, " n_kx"], k_y: Float[np.ndarray, " n_ky"], weights: Float[np.ndarray, " n_weights"], on_axis: Complex[np.ndarray, " n_axis_weights"], ) -> ApertureTables: """Form the far-field statistics' tables of a spec on Cartesian columns (SEP 23 §6). The per-aperture constants -- each row's outline of :func:`solprop.spatial.aperture_outline`, whose half-width under quadrature weighting is the corrected ``D_q/2`` of a circle or an ellipse (unchanged on a line, whose edges are straight, and on the straight edges of a rectangle or a half-plane) -- and the scale table of :func:`solprop.spatial.aperture_scale`, with the columns' axes, weights and on-axis vector and the spec's regions. On a line every column has ``kappa_y = 0`` and the light is uniform in y, so a rectangle has no y edges to meet: it is a slit of its x width, the row a circle of that diameter forms. Every backend reaches this through :func:`solprop.translate.spatial.aperture_tables` at construction and :func:`solprop.stats.collect` calls it for a saved plane, so all of them use the same scale to the bit. Parameters ---------- spec : solprop.stats.StatsSpec The request and its far-field tables. omega : numpy.ndarray Physical frequency axis in rad/s, shape ``(n_omega,)``. k_x, k_y : numpy.ndarray The stored transverse wavevector axes in rad/m, in FFT order; ``k_y`` has one entry, zero, on a line uniform in y. weights : numpy.ndarray Parseval weights of the stored columns, shape ``(n_x*n_y,)``. on_axis : numpy.ndarray On-axis reconstruction weights of the columns, complex, shape ``(n_x*n_y,)``. Returns ------- solprop.spatial.ApertureTables The tables. Raises ------ OutputError On a line, for an aperture whose centre is off ``y = 0``, a half-plane bounded in y or an ellipse, which have no meaning uniform in y, or a region whose ``kappa_y`` interval excludes zero, which would select nothing. """ apertures = spec.apertures regions = spec.spectral_regions line = k_y.size == 1 if line: if apertures is not None and np.any(np.asarray(apertures.centres)[:, 1] != 0): msg = ( "on a line uniform in y an aperture is a slit along x, so its y centre " "must be zero" ) raise OutputError(msg) if apertures is not None: _refuse_off_line(apertures) excluded = np.flatnonzero(~((regions[:, 2] <= 0) & (regions[:, 3] > 0))) if excluded.size: msg = ( "on a line every column has kappa_y = 0, so regions " f"{excluded.tolist()}, whose kappa_y interval excludes zero, would " "select nothing" ) raise OutputError(msg) if apertures is None: empty = np.empty(0) return ApertureTables( k_x=k_x, k_y=k_y, weights=weights, on_axis=on_axis, regions=regions, centres=np.empty((0, 2)), half_widths=empty, edges=empty, distances=empty, scale=np.empty((0, omega.size)), ) outlines = _outlines(apertures, line=line) distances = np.asarray(apertures.distances) return ApertureTables( k_x=k_x, k_y=k_y, weights=weights, on_axis=on_axis, regions=regions, centres=np.asarray(apertures.centres), half_widths=np.array([one.half_width for one in outlines]), edges=np.array([one.edge for one in outlines]), distances=distances, scale=aperture_scale(distances, omega), profiles=tuple(one.kind for one in outlines), exponent=1 if apertures.weighting == "quadrature" else 2, shapes=tuple(one.shape for one in outlines), half_heights=np.array([one.half_height for one in outlines]), stretches=np.array([one.stretch for one in outlines]), )
def _refuse_off_line(apertures: ApertureSet) -> None: """Refuse the outlines a line uniform in y gives no meaning.""" for row, shape in enumerate(apertures.row_shapes): if shape == "ellipse" or shape.startswith("half_plane_y"): msg = ( f"on a line every column has kappa_y = 0 and the light is uniform in " f"y, so aperture {row}, a {shape}, has no meaning there; a line takes " "a circle or a rectangle, each a slit along x, or a half-plane bounded " "in x" ) raise OutputError(msg) def _outlines(apertures: ApertureSet, *, line: bool) -> list[ApertureOutline]: """Return each row's outline on a plane or a line.""" count = apertures.n_apertures diameters = np.asarray(apertures.diameters) edges = np.zeros(count) if apertures.edges is None else np.asarray(apertures.edges) extents = ( np.zeros((count, 2)) if apertures.extents is None else np.asarray(apertures.extents) ) corrected = apertures.weighting == "quadrature" and not line outlines = [] for row in range(count): shape = apertures.row_shapes[row] diameter, extent = float(diameters[row]), extents[row] if line and shape == "rectangle": # sqrt(x*x) is |x| in correctly rounded arithmetic, so the slit decides a # hard edge as a circle of this diameter does (SEP 23 section 4.10). shape, diameter = "circle", float(extent[0]) outlines.append( aperture_outline( shape, diameter, (float(extent[0]), float(extent[1])), float(edges[row]), apertures.row_profiles[row], corrected=corrected, ) ) return outlines