# SPDX-FileCopyrightText: 2026 John C. Travers and contributors
#
# SPDX-License-Identifier: GPL-3.0-or-later
"""Grid data, masks, absorber rates and the noise field, in the kernel's layout.
Everything a backend needs to know about the frequency axis and the time window, read
from :class:`solprop.grid.TimeGrid`, :class:`solprop.boundaries.Absorber` and
:class:`solprop.noise.NoiseRealisation` rather than recomputed, so a mask can never
disagree with the grid that produced it; nothing here computes physics.
- :class:`Grids` (:func:`build_masks`): section 2 of ``docs/dev/kernel-contract.md``,
field for field -- the band masks, the spectral and temporal windows, the
oversampling crop index and its two scale factors.
- :func:`temporal_rates`: the temporal absorber rates of the chosen
:data:`AbsorberScheme` (section 5, stored by :mod:`solprop.translate.responses`).
- :func:`noise_spectrum`: the shot-noise realisation in the canonical state layout
(section 6, stored by :mod:`solprop.translate.problem`).
"""
import logging
from dataclasses import dataclass
from typing import Literal
import numpy as np
from jaxtyping import Bool, Complex, Float, Int
from solprop._ownership import frozen_copy, hold
from solprop.boundaries import Absorber
from solprop.exceptions import TranslationError
from solprop.grid import TimeGrid
from solprop.noise import NoiseRealisation
from solprop.nonlinear.responses import thg_carrier
__all__ = [
"DEFAULT_ABSORBER_SCHEME",
"AbsorberScheme",
"Grids",
"build_masks",
"noise_spectrum",
"temporal_rates",
]
logger = logging.getLogger(__name__)
AbsorberScheme = Literal["split_step", "nonlinear"]
"""How the temporal absorber is applied (see ``docs/dev/decisions.md``).
``"split_step"`` multiplies the modal time-domain field by ``exp(-alpha(t) h / 2)`` once
per accepted step; ``"nonlinear"`` adds ``-alpha(t) E(t) / 2`` inside every stage
evaluation.
Both are exact *as a rate* in the sense that the factors telescope, but they are not
equally accurate, and a comparison on a soliton launched into its own temporal collar
measured the difference: the
split factor is a **Lie splitting** of a term that does not commute with the linear
flow, so it caps the observed order of the whole scheme at **one** wherever the collar
does any work, and the energy it removes drifts with the step count at the same order.
The in-stage term keeps the scheme's own order and its absorbed energy is step-count
independent to twelve digits. Because the split factor degrades the observed order,
the in-stage term is the default of the modal routes whatever it costs. The spatial
routes (radial, Cartesian, line and planar) default to the split factor
(:data:`solprop.driver.defaults.ROUTE_DEFAULTS`); a run with interpolated planes that
names no scheme takes the in-stage term on every route.
"""
DEFAULT_ABSORBER_SCHEME: AbsorberScheme = "nonlinear"
"""The modal routes' default scheme, chosen on accuracy (see :data:`AbsorberScheme`)."""
[docs]
@dataclass(frozen=True, eq=False)
class Grids:
"""The frequency axis, the masks and the oversampling data a kernel needs.
Section 2 of the kernel contract. The arrays are read-only, C-contiguous copies, so
a backend may hold them for the life of a run without defensive copying. Equality is
by identity: comparing whole axes elementwise is never what a caller means.
The shape annotations give each array its own axis name, because
``__post_init__`` is what enforces their agreement and that check must stay
reachable in production, where no runtime type checker runs.
Attributes
----------
omega : numpy.ndarray
Coarse angular frequency axis, rad/s, shape ``(n_omega,)``. Non-negative and
increasing on a field grid, in FFT order about ``omega0`` on an envelope grid.
omega0 : float
Reference angular frequency, rad/s.
dt : float
Coarse sample spacing, s.
dt_fine : float
Fine sample spacing, s.
n_t : int
Coarse number of time samples.
n_to : int
Fine number of time samples.
ffac : float
Oversampling factor of the fine grid.
crop_index : numpy.ndarray
Position of each coarse bin in the fine spectrum, ``numpy.intp``, shape
``(n_omega,)``.
pad_scale : float
Factor applied when padding the coarse spectrum out, ``n_to / n_t``.
crop_scale : float
Factor applied when cropping back, ``n_t/n_to``.
inband_mask : numpy.ndarray
Boolean, shape ``(n_omega,)``: the bins inside the requested wavelength limits.
active_mask : numpy.ndarray
Boolean, shape ``(n_omega,)``: ``omega_min/2 < omega < 1.1 omega_max``. The
linear operator and the prefactor are zero outside it and the
hard band mask removes the state there once per accepted step.
norm_mask : numpy.ndarray
Boolean, shape ``(n_omega,)``: the bins the error norm scores, the
controller's ``region`` -- ``active_mask`` by default, or ``inband_mask``.
omega_window : numpy.ndarray
The taper applied to the nonlinear polarisation in the spectral collar, shape
``(n_omega,)``: the grid's collar profile in ``[0, 1]`` when the polarisation
taper is on, and all ones when it is off, which is the default. The rate
absorber on the field is inside the linear operator either way; this taper is
an option, off by default, because it sets a floor of the size of the field's
content in the collar.
t_window_fine : numpy.ndarray
Temporal collar profile in ``[0, 1]``, shape ``(n_to,)``, applied inside the
response pass.
t_window_fine_derivative : numpy.ndarray
Analytic time derivative of the fine collar, in s^-1, shape ``(n_to,)``.
The field plasma uses it to hold the current at the collar (SEP 27).
carrier_2w0 : numpy.ndarray or None
``exp(2 i omega_0 t)`` on the fine time axis, complex128, shape ``(n_to,)``,
present exactly when a third-harmonic Kerr term is compiled on an envelope grid
and ``None`` otherwise. That term sits an offset ``2 omega_0`` from the carrier
the envelope is written against, so the response pass needs the factor; it is
built here from :func:`solprop.nonlinear.responses.thg_carrier` and the grid's
own fine time axis, because a backend that built it from ``omega0``, ``n_to``
and ``dt_fine`` would be carrying a piece of physics
(``docs/dev/architecture.md`` section 3).
Raises
------
TranslationError
If an array length disagrees with ``n_omega`` or ``n_to``, or a size or scale is
not positive.
Examples
--------
>>> from solprop.grid import EnvelopeGrid
>>> from solprop.translate.masks import build_masks
>>> grid = EnvelopeGrid.from_limits(1.0, 835e-9, (500e-9, 2e-6), 4e-12)
>>> masks = build_masks(grid)
>>> masks.omega.shape == (grid.n_omega,), masks.pad_scale
(True, 1.0)
"""
omega: Float[np.ndarray, " n_omega"]
omega0: float
dt: float
dt_fine: float
n_t: int
n_to: int
ffac: float
crop_index: Int[np.ndarray, " n_crop"]
pad_scale: float
crop_scale: float
inband_mask: Bool[np.ndarray, " n_inband"]
active_mask: Bool[np.ndarray, " n_active"]
norm_mask: Bool[np.ndarray, " n_norm"]
omega_window: Float[np.ndarray, " n_window"]
t_window_fine: Float[np.ndarray, " n_to_window"]
t_window_fine_derivative: Float[np.ndarray, " n_to_derivative"]
carrier_2w0: Complex[np.ndarray, " n_to_carrier"] | None = None
def __post_init__(self) -> None:
"""Adopt read-only copies and check the sizes the annotations cannot.
Raises
------
TranslationError
Naming the offending field.
"""
for name, dtype in (
("omega", np.float64),
("crop_index", np.intp),
("inband_mask", np.bool_),
("active_mask", np.bool_),
("norm_mask", np.bool_),
("omega_window", np.float64),
("t_window_fine", np.float64),
("t_window_fine_derivative", np.float64),
):
# At least one-dimensional, as numpy.ascontiguousarray made them.
values = frozen_copy(np.atleast_1d(getattr(self, name)), dtype)
object.__setattr__(self, name, values)
if self.carrier_2w0 is not None:
carrier = frozen_copy(np.atleast_1d(self.carrier_2w0), np.complex128)
object.__setattr__(self, "carrier_2w0", carrier)
n_omega = self.omega.size
for name in (
"crop_index",
"inband_mask",
"active_mask",
"norm_mask",
"omega_window",
):
if getattr(self, name).size != n_omega:
msg = (
f"{name} has {getattr(self, name).size} entries, expected "
f"{n_omega} to match omega"
)
raise TranslationError(msg)
for name in ("t_window_fine", "t_window_fine_derivative", "carrier_2w0"):
fine = getattr(self, name)
if fine is not None and fine.size != self.n_to:
msg = (
f"{name} has {fine.size} entries, expected {self.n_to} to match "
"n_to"
)
raise TranslationError(msg)
if min(self.n_t, self.n_to) < 1 or self.n_to % self.n_t:
msg = (
f"n_to ({self.n_to}) must be a positive multiple of n_t ({self.n_t}), "
"so that the coarse time samples coincide with fine ones"
)
raise TranslationError(msg)
if not (self.pad_scale > 0.0 and self.crop_scale > 0.0 and self.ffac >= 1.0):
msg = (
f"pad_scale ({self.pad_scale!r}), crop_scale ({self.crop_scale!r}) and "
f"ffac ({self.ffac!r}) must be positive"
)
raise TranslationError(msg)
[docs]
@property
def n_omega(self) -> int: # numpydoc ignore=RT01
"""Number of coarse spectral bins.
Examples
--------
>>> from solprop.grid import EnvelopeGrid
>>> from solprop.translate.masks import build_masks
>>> grid = EnvelopeGrid.from_limits(1.0, 835e-9, (500e-9, 2e-6), 4e-12)
>>> build_masks(grid).n_omega == grid.n_omega
True
"""
return int(self.omega.size)
[docs]
def build_masks(
grid: TimeGrid,
*,
polarisation_taper: bool = False,
harmonic_carrier: bool = False,
region: str = "active",
) -> Grids:
"""Collect a grid's axis, masks and oversampling data for the kernel contract.
Every value is read from `grid`; nothing is recomputed, so the seam and the grid can
never disagree. The one choice made here is whether the spectral collar tapers the
nonlinear polarisation: off by default, because the rate absorber already acts on
the field and the taper costs a systematic error of the size of the field's content
in the collar (2.3e-6 on the recurrence of an N = 6 soliton against 2.7e-7
without it).
Parameters
----------
grid : solprop.grid.TimeGrid
The field or envelope grid the run propagates on.
polarisation_taper : bool, optional
Whether ``omega_window`` carries the grid's collar profile or all ones.
Default ``False``.
harmonic_carrier : bool, optional
Whether to carry ``exp(2 i omega_0 t)`` on the fine time axis, which an
envelope grid's third-harmonic Kerr term needs and nothing else does. Default
``False``. :func:`solprop.translate.assembly.assemble` passes the compiled Kerr
term's own answer, so the field is present exactly when the term is.
region : str, optional
The bins the error norm scores, the controller's ``region``: ``"active"`` (the
default) or ``"band"``.
Returns
-------
Grids
Section 2 of the kernel contract, with read-only arrays.
Examples
--------
>>> import numpy as np
>>> from solprop.grid import FieldGrid
>>> from solprop.translate.masks import build_masks
>>> grid = FieldGrid.from_limits(1.0, 800e-9, (200e-9, 4e-6), 200e-15)
>>> masks = build_masks(grid)
>>> bool(np.array_equal(masks.active_mask, grid.active_mask))
True
>>> masks.crop_index.flags.writeable
False
>>> bool(np.all(masks.omega_window == 1.0))
True
>>> taper = build_masks(grid, polarisation_taper=True).omega_window
>>> bool(np.array_equal(taper, grid.omega_window))
True
>>> masks.carrier_2w0 is None
True
"""
# The grid evaluates its masks and windows afresh at every access, so each is
# this group's own: held in place rather than copied again by the group. The
# frequency axis is the grid's, which it already holds.
window = hold(
grid.omega_window if polarisation_taper else np.ones_like(grid.omega_window)
)
carrier = hold(thg_carrier(grid.omega0, grid.t_fine)) if harmonic_carrier else None
active, inband = hold(grid.active_mask), hold(grid.inband_mask)
masks = Grids(
omega=grid.omega,
omega0=grid.omega0,
dt=grid.dt,
dt_fine=grid.dt_fine,
n_t=grid.n_t,
n_to=grid.n_to,
ffac=grid.ffac,
crop_index=hold(grid.crop_index),
pad_scale=grid.pad_scale,
crop_scale=grid.crop_scale,
inband_mask=inband,
active_mask=active,
norm_mask=active if region == "active" else inband,
omega_window=window,
t_window_fine=hold(grid.t_window_fine),
t_window_fine_derivative=hold(grid.t_collar.window_derivative(grid.t_fine)),
carrier_2w0=carrier,
)
logger.debug(
"masks: n_omega %d, n_t %d, n_to %d (ffac %.3g), %d active bins, %d in band, "
"harmonic carrier %s",
masks.n_omega,
masks.n_t,
masks.n_to,
masks.ffac,
int(np.count_nonzero(masks.active_mask)),
int(np.count_nonzero(masks.inband_mask)),
"carried" if masks.carrier_2w0 is not None else "absent",
)
return masks
[docs]
def temporal_rates(
absorber: Absorber | None, *, scheme: str = DEFAULT_ABSORBER_SCHEME
) -> tuple[
Float[np.ndarray, " n_t"] | None,
Float[np.ndarray, " n_to"] | None,
]:
"""Return the coarse and fine temporal absorber rates the chosen scheme needs.
The temporal collar cannot be folded into the cumulative linear operator, because it
is not diagonal in ``omega``. It crosses the seam as the bounded profile
of :func:`solprop.boundaries.temporal_collar_rate` on both time axes, and `scheme`
records which of
the two exact applications of the rate the backend is to use: the per-accepted-step
factor ``exp(-alpha h / 2)`` on the coarse axis, or the term ``-alpha E / 2`` inside
the nonlinear evaluation on the fine axis. Both rates are carried whichever is
chosen, so switching schemes is not a retranslation.
A collar whose temporal rates are all zero, however it was built (a spectral-only
collar from ``absorber(grid, temporal=False)``, or a hand-built one), crosses the
seam as **no** temporal absorber under either scheme (SEP 22): the kernels then
compile no in-stage term and no split pass, recycle the first-same-as-last stage,
and the scheme, still recorded, applies to nothing. Under the in-stage scheme the
result is exactly the zero rate's, which only added zeros; under the split it
differs by the transverse transform pair the zero factor cost, at rounding.
Parameters
----------
absorber : solprop.boundaries.Absorber or None
The collar rates from :func:`solprop.boundaries.absorber`. ``None`` means no
temporal absorber.
scheme : {'split_step', 'nonlinear'}, optional
Which application of the rate the backend will use. Default
:data:`DEFAULT_ABSORBER_SCHEME`, ``'nonlinear'``.
Annotated as a plain string rather than :data:`AbsorberScheme` for the reason
given in ``solprop.fourier._check_kind``: this is the run-time guard, and
the test session's ``beartype`` hook would otherwise reject a bad value first,
leaving the guard unreachable.
Returns
-------
tuple
``(coarse, fine)``: rates in 1/m of shapes ``(n_t,)`` and ``(n_to,)``, or
``(None, None)`` when `absorber` is ``None`` or its temporal rates are all
zero.
Raises
------
TranslationError
If `scheme` is not one of the two schemes.
Examples
--------
>>> from solprop.boundaries import absorber
>>> from solprop.grid import EnvelopeGrid
>>> from solprop.translate.masks import temporal_rates
>>> grid = EnvelopeGrid.from_limits(1.0, 835e-9, (500e-9, 2e-6), 4e-12)
>>> coarse, fine = temporal_rates(absorber(grid))
>>> coarse.shape == (grid.n_t,), fine.shape == (grid.n_to,)
(True, True)
>>> temporal_rates(None)
(None, None)
>>> temporal_rates(absorber(grid, temporal=False))
(None, None)
"""
if scheme not in ("split_step", "nonlinear"):
msg = f"absorber scheme must be 'split_step' or 'nonlinear', got {scheme!r}"
raise TranslationError(msg)
if absorber is None:
return None, None
if not np.any(absorber.temporal_rate) and not np.any(absorber.temporal_rate_fine):
logger.debug(
"temporal absorber (%s): every rate is zero, so no temporal pass is "
"compiled",
scheme,
)
return None, None
coarse = frozen_copy(absorber.temporal_rate, np.float64)
fine = frozen_copy(absorber.temporal_rate_fine, np.float64)
logger.debug(
"temporal absorber (%s): peak rate %.6e 1/m over %d coarse and %d fine samples",
scheme,
float(coarse.max(initial=0.0)),
coarse.size,
fine.size,
)
return coarse, fine
[docs]
def noise_spectrum(
noise: NoiseRealisation, shape: tuple[int, int, int]
) -> Complex[np.ndarray, "n_modes n_pol n_omega"]:
"""Put a shot-noise realisation into the canonical state layout.
The realisation is drawn as ``(n_modes, n_pol, n_omega)``
(:mod:`solprop.noise`), the layout of the state (``conventions.md`` section 6). A
realisation with one mode or one polarisation is broadcast over the requested
shape, so that it stays reproducible from its seed.
Parameters
----------
noise : solprop.noise.NoiseRealisation
The realisation, in the internal FFT convention.
shape : tuple of int
Target ``(n_modes, n_pol, n_omega)``.
Returns
-------
numpy.ndarray
Read-only complex128 array of the requested shape.
Raises
------
TranslationError
If the realisation cannot be broadcast onto `shape`.
Examples
--------
>>> import numpy as np
>>> from solprop.grid import EnvelopeGrid
>>> from solprop.noise import modified_noise
>>> from solprop.translate.masks import noise_spectrum
>>> grid = EnvelopeGrid.from_limits(1.0, 835e-9, (500e-9, 2e-6), 4e-12)
>>> draw = modified_noise(grid, np.random.default_rng(7))
>>> noise_spectrum(draw, (1, 1, grid.n_omega)).shape
(1, 1, 3072)
"""
try:
values = np.broadcast_to(noise.spectrum, shape)
except ValueError as error:
msg = (
f"noise0: a realisation of shape {noise.spectrum.shape} does not fit the "
f"state shape {shape}"
)
raise TranslationError(msg) from error
return frozen_copy(values, np.complex128)