# SPDX-FileCopyrightText: 2026 John C. Travers and contributors
#
# SPDX-License-Identifier: GPL-3.0-or-later
"""The stage derivative: the nonlinear source of a lab-frame field, on every route.
:class:`StageSource` is what :meth:`NumpyWorkspace.nonlinear
<solprop.backends.numpy_ref.workspace.NumpyWorkspace.nonlinear>` asks. Its
:meth:`~StageSource.evaluate` runs the passes of ``docs/dev/architecture.md`` section 8
(:mod:`solprop.backends.numpy_ref.passes`) on the route the problem takes: the modal
quadrature in node chunks, with the embedded coarse rule projected beside it and the
held plasma current assembled in frequency; the radial route's plasma, projected once in
frequency; the free and planar geometries, through transverse transforms or the slab
synthesis; the general modal guide (:mod:`~solprop.backends.numpy_ref.general_modal`);
and the bound TDSE response (:mod:`solprop.backends.tdse_source`). It adds ADR-025's
in-stage absorbers and returns the derivative in the frame its caller names.
:meth:`~StageSource.score_quadrature` turns the last accepted stage's two projections
into the quadrature alarm. :class:`SourceTables` gathers the arrays the passes read.
"""
import logging
import math
from collections.abc import Callable
from dataclasses import dataclass
import numpy as np
from jaxtyping import Complex, Float, Inexact, Num
from solprop.backends import tdse_source
from solprop.backends.node_chunk import (
NodeChunkPlan,
general_planned_chunk,
plan_node_chunk,
)
from solprop.backends.numpy_ref.general_modal import GeneralMaps, general_source
from solprop.backends.numpy_ref.passes.plasma import (
envelope_sources,
held_plasma_spectrum,
)
from solprop.backends.numpy_ref.passes.responses import (
NonlinearSources,
mixture_raman_spectrum,
nonlinear_sources,
raman_spectrum,
tensor_raman_spectrum,
)
from solprop.backends.numpy_ref.passes.stepping import absorber_term, stage_output
from solprop.backends.numpy_ref.passes.transforms import (
project,
synthesise,
to_frequency,
to_time,
)
from solprop.backends.spatial import (
radial_absorber_matrix,
slab_columns,
slab_rows,
)
from solprop.exceptions import BackendError
from solprop.fourier import GridKind
from solprop.translate.general import (
node_delayed_maps,
node_kerr_form,
node_kerr_tensor,
)
from solprop.translate.problem import PropagationProblem
from solprop.translate.routes import tdse_of
from solprop.translate.spatial import separable_values
from solprop.translate.stage import StageScalars
from solprop.translate.tdse import TDSEBinding, TDSEPurpose
__all__ = ["SourceTables", "StageSource"]
logger = logging.getLogger(__name__)
_State = Complex[np.ndarray, "n_modes n_pol n_omega"]
[docs]
class StageSource:
"""The reference's evaluation of the stage derivative, and what it keeps.
Built once by the workspace from the validated problem. It reads no state of the
run: the lab-frame field and the stage's scalars are its arguments. It keeps the
problem's tables, the last stage's projections (for the quadrature alarm), the
damped Raman kernel of the last decay rates, and, with a bound TDSE response, the
accounting of the last evaluation.
Parameters
----------
problem : solprop.translate.problem.PropagationProblem
The validated problem.
chunk_plan : solprop.backends.node_chunk.NodeChunkPlan
The node chunk the response passes hold at once.
prefactor : callable
``bundle -> prefactor``: the workspace's evaluation of the response prefactor
from a stage's scalars
(:meth:`~solprop.backends.numpy_ref.workspace.NumpyWorkspace.prefactor`).
tdse_binding : solprop.translate.tdse.TDSEBinding or None
The host response binding a TDSE problem declares; ``None`` otherwise.
Attributes
----------
collar_quiet : bool
Whether the modal stage leaves a quiet in-stage temporal collar out (SEP 21):
set by the session through the workspace, read by every stage.
"""
def __init__(
self,
problem: PropagationProblem,
*,
chunk_plan: NodeChunkPlan,
prefactor: Callable[[StageScalars], _State],
tdse_binding: TDSEBinding | None,
) -> None:
"""Gather the tables and caches the stages read."""
self._problem = problem
self._node_chunk = chunk_plan.chunk
self._prefactor = prefactor
self._tdse_binding = tdse_binding
self.collar_quiet = False
self._kind: GridKind = problem.grid_kind
self._tables = SourceTables.of(problem)
self._carrier = _harmonic_carrier(problem)
self._embedded = _embedded_projection(problem)
self._general = _general_maps(problem, chunk_plan)
self._general_responds = self._general is not None and (
bool(np.any(self._general.tensor)) or self._general.dispersive is not None
)
# ADR-025's in-stage scheme is a second term on every stage rather than a
# factor on the accepted state, so a problem that has no response at all still
# has a derivative when it is active.
self._spatial_absorber = radial_absorber_matrix(
problem.transform, problem.grids.pad_scale
)
self._in_stage_absorber = bool(self._spatial_absorber.size) or (
problem.responses.temporal_absorber_fine is not None
and problem.responses.absorber_scheme == "nonlinear"
)
geometry = problem.transform.geometry
if geometry is not None and geometry.kind in ("free", "slab"):
self._in_stage_absorber |= bool(np.any(geometry.absorber_rate))
# The last stage's projections under both rules, its bundle and its held
# streams, for the quadrature alarm.
self._last_projected: Num[np.ndarray, "n_modes n_pol n_to"] | None = None
self._last_coarse: Num[np.ndarray, "n_modes n_pol n_to"] | None = None
self._last_bundle: StageScalars | None = None
self._last_plasma: (
tuple[np.ndarray, np.ndarray, np.ndarray | None, np.ndarray | None] | None
) = None
self._last_envelope: (
tuple[np.ndarray, np.ndarray, np.ndarray | None, np.ndarray | None] | None
) = None
self._raman_rates: tuple[float, ...] | None = None
self._raman_densities: tuple[float, ...] | None = None
self._raman_kernel: Complex[np.ndarray, "... n_omega_doubled"] | None = None
self._raman_transforms = 0
self._alarm = math.nan
self._tdse_last_purpose: TDSEPurpose | None = None
self._tdse_last_z: float | None = None
self._tdse_last_projection: dict[str, object] | None = None
[docs]
@property
def alarm(self) -> float: # numpydoc ignore=RT01
"""The quadrature alarm :meth:`score_quadrature` last scored, or NaN."""
return self._alarm
[docs]
def reset_alarm(self) -> None:
"""Forget the alarm, so that the next plane reports its own."""
self._alarm = math.nan
[docs]
@property
def general(self) -> GeneralMaps | None: # numpydoc ignore=RT01
"""The general modal route's maps, or ``None`` on another route."""
return self._general
[docs]
@property
def embedded(self) -> bool: # numpydoc ignore=RT01
"""Whether the quadrature has an embedded coarse rule to score the alarm on."""
return self._embedded is not None
[docs]
@property
def spatial_absorber_bytes(self) -> int: # numpydoc ignore=RT01
"""The radial collar's matrix size, which the memory ledger names."""
return self._spatial_absorber.nbytes
[docs]
@property
def tdse_last_evaluation(self) -> dict[str, object]: # numpydoc ignore=RT01
"""The bound TDSE response's last evaluation: purpose, position, projection."""
return {
"purpose": self._tdse_last_purpose,
"z": self._tdse_last_z,
"projection": self._tdse_last_projection,
}
[docs]
def close(self) -> None:
"""Release the caches. Idempotent."""
self._raman_kernel = None
self._raman_rates = None
self._raman_densities = None
self._last_plasma = None
self._spatial_absorber = np.empty((0, 0))
[docs]
def evaluate(
self,
lab: Complex[np.ndarray, "n_modes n_pol n_omega"],
bundle: StageScalars,
inverse_propagator: Complex[np.ndarray, "n_modes n_pol n_omega"],
*,
purpose: TDSEPurpose = "predictor",
) -> Complex[np.ndarray, "n_modes n_pol n_omega"]:
"""Evaluate one stage derivative through the transform passes.
The pipeline of ``architecture.md`` section 8 for any node count: one batched
inverse transform of every modal column, then, per chunk of
the node chunk's nodes, the synthesis GEMM, the fused response pass and
the projection GEMM accumulated over the chunks, then one batched forward
transform, the crop and the prefactor. Mode-averaged propagation is the
one-node, one-column case of exactly this code.
Parameters
----------
lab : numpy.ndarray
The stage's lab-frame field, in the state's layout.
bundle : solprop.translate.stage.StageScalars
The stage's scalars.
inverse_propagator : numpy.ndarray
The factor that carries the derivative back to the step's anchor.
purpose : {'startup', 'predictor', 'corrected', 'diagnostic'}, optional
The host source's accounting label; ignored when none is bound.
Returns
-------
numpy.ndarray
The stage derivative in the anchor's frame.
"""
responses = self._problem.responses
grids = self._problem.grids
if self._tdse_binding is not None:
return self._nonlinear_tdse(lab, bundle, inverse_propagator, purpose)
if self._problem.linear.separable is not None:
geometry = self._problem.transform.geometry
evaluate = (
self._nonlinear_slab
if geometry is not None and geometry.kind == "slab"
else self._nonlinear_free
)
return evaluate(lab, bundle, inverse_propagator)
if self._general is not None:
return self._nonlinear_general(lab, bundle, inverse_propagator)
if len(responses.response_order) == 1:
# Nothing but the accumulation was compiled, so the polarisation is
# identically zero and the step is the exact linear flow. Running the
# transforms to multiply by nothing would only add round-off -- unless
# ADR-025's in-stage absorber is active, which is a term of its own and
# would otherwise be dropped from a problem that has no response at all.
if not self._in_stage_absorber:
return np.zeros_like(lab)
alone = to_time(lab, grids.crop_index, grids.n_to, kind=self._kind)
return stage_output(
np.zeros_like(lab),
np.zeros_like(lab),
self._tables.omega_window,
inverse_propagator,
self._absorber_term(alone, may_quiet=True),
)
modal_t = to_time(lab, grids.crop_index, grids.n_to, kind=self._kind)
geometry = self._problem.transform.geometry
if (
geometry is not None
and geometry.kind == "radial"
and bool(responses.plasma_channels)
):
spectrum = self._radial_plasma_spectrum(modal_t, bundle)
else:
projected, coarse = self._over_nodes(modal_t, bundle)
self._last_projected = projected
self._last_coarse = coarse
self._last_bundle = bundle
spectrum = to_frequency(projected, grids.crop_index, kind=self._kind)
if self._last_plasma is not None:
gated, edge, _, _ = self._last_plasma
spectrum += self._held_streams(gated, edge)
if responses.envelope_plasma is not None:
assert self._last_envelope is not None
drive, loss, _, _ = self._last_envelope
factors = responses.envelope_plasma.factors
spectrum += factors.drude * to_frequency(
drive, grids.crop_index, kind=self._kind
)
spectrum += factors.loss * to_frequency(
loss, grids.crop_index, kind=self._kind
)
return stage_output(
spectrum,
self._prefactor(bundle),
self._tables.omega_window,
inverse_propagator,
self._absorber_term(modal_t, may_quiet=True),
)
def _nonlinear_tdse(
self,
lab: Complex[np.ndarray, "n_modes n_pol n_omega"],
bundle: StageScalars,
inverse_propagator: Complex[np.ndarray, "n_modes n_pol n_omega"],
purpose: TDSEPurpose,
) -> Complex[np.ndarray, "n_modes n_pol n_omega"]:
"""Evaluate the declared atomic binding and combine independent P/J sources.
Steps 1 to 4 are :mod:`solprop.backends.tdse_source`'s, shared with native;
the stage output is this backend's own.
"""
problem = self._problem
grids = problem.grids
binding = self._tdse_binding
assert binding is not None and tdse_of(problem.route) is not None
modal_t = to_time(lab, grids.crop_index, grids.n_to, kind="field")
fields = tdse_source.node_fields(problem, lab, bundle)
result = binding.evaluate(
fields, z=bundle.z1, purpose=purpose, density=bundle.density
)
polarisation, current = tdse_source.atomic_sources(
fields, result, problem, bundle
)
source, projection = tdse_source.project_atomic_sources(
polarisation,
current,
result,
problem,
bundle,
self._prefactor(bundle),
edge=tdse_source.atomic_edge_source(result, problem, bundle),
)
self._tdse_last_purpose, self._tdse_last_z = purpose, bundle.z1
self._tdse_last_projection = projection
return stage_output(
source,
np.ones_like(source),
grids.omega_window,
inverse_propagator,
self._absorber_term(modal_t),
)
def _nonlinear_general(
self,
lab: Complex[np.ndarray, "n_modes n_pol n_omega"],
bundle: StageScalars,
inverse_propagator: Complex[np.ndarray, "n_modes n_pol n_omega"],
) -> Complex[np.ndarray, "n_modes n_pol n_omega"]:
"""Evaluate one stage derivative through a general modal guide's maps.
The route's own execution path, in
:mod:`solprop.backends.numpy_ref.general_modal`, beside the fused pass and
not an extension of it. The synthesis is a complex
frequency-dependent map of three Cartesian components, so it happens in the
frequency domain and the field a response sees is the analytic signal. What
is shared with the channel node pipeline is everything after the projection
-- the prefactor, which is the crop scale alone here, the spectral collar,
the in-stage absorber and the return to the interaction picture.
The quadrature alarm is not scored on this route: the general node rule has
no embedded coarse pair, and a difference that is identically zero read as
convergence would be wrong, as for any unpaired rule.
A guide with no responding region is short-circuited, as the channel node
pipeline short-circuits a problem whose `response_order` is the accumulation
alone.
"""
assert self._general is not None
grids = self._problem.grids
# A guide whose every material region is linear has an identically zero
# tensor, so the source is zero for every state and every position: the
# synthesis, the 3 x n_nodes transforms, the contraction and the projection
# would spend a tenth of a second per step producing it (measured 108 ms on
# the 288-node strand). ADR-025's in-stage absorber is a term of its own and
# is not dropped with it.
spectrum = (
general_source(
lab,
self._general,
grids.crop_index,
n_to=grids.n_to,
pad_scale=grids.pad_scale,
transform_weights=bundle.transform_weights,
dispersive_densities=bundle.dispersive_kerr_densities,
)
if self._general_responds
else np.zeros_like(lab)
)
absorber = None
if self._in_stage_absorber:
absorber = self._absorber_term(
to_time(lab, grids.crop_index, grids.n_to, kind=self._kind)
)
return stage_output(
spectrum,
self._prefactor(bundle),
grids.omega_window,
inverse_propagator,
absorber,
)
def _nonlinear_free(
self,
lab: np.ndarray,
bundle: StageScalars,
inverse_propagator: np.ndarray,
) -> np.ndarray:
"""Apply transverse FFTs before bounded temporal response transforms.
- ``lab``: Lab-frame stage spectrum.
"""
problem = self._problem
transform, grids, responses = (
problem.transform,
problem.grids,
problem.responses,
)
geometry = transform.geometry
if geometry is None:
msg = "Cartesian nonlinear evaluation requires spatial geometry"
raise BackendError(msg)
shape = (geometry.shape[1], geometry.shape[0], *lab.shape[1:])
result = np.zeros_like(lab)
if len(responses.response_order) == 1 and not self._in_stage_absorber:
return result
scratch = np.empty_like(lab)
if len(responses.response_order) > 1:
scratch.reshape(shape)[...] = np.fft.ifft2(lab.reshape(shape), axes=(0, 1))
raman = self._raman_spectrum(bundle.raman_rates, bundle.raman_densities)
for first in range(0, transform.n_nodes, self._node_chunk):
rows = slice(first, first + self._node_chunk)
field_t = grids.pad_scale * to_time(
scratch[rows], grids.crop_index, grids.n_to, kind=self._kind
)
sources = self._column_sources(field_t, bundle, raman)
polarisation_t = sources.polarisation
scratch[rows] = to_frequency(
polarisation_t, grids.crop_index, kind=self._kind
)
if sources.current is not None:
scratch[rows] += self._held_current(sources.current)
if responses.envelope_plasma is not None:
drive, loss = self._envelope_sources(field_t, bundle)
factors = responses.envelope_plasma.factors
scratch[rows] += factors.drude * to_frequency(
drive, grids.crop_index, kind=self._kind
)
scratch[rows] += factors.loss * to_frequency(
loss, grids.crop_index, kind=self._kind
)
view = scratch.reshape(shape)
view[...] = np.fft.fft2(view, axes=(0, 1))
data = problem.linear.separable
assert data is not None
for first in range(0, transform.n_nodes, self._node_chunk):
rows = slice(first, first + self._node_chunk)
_, prefactor = separable_values(data, rows)
result[rows] = prefactor * self._tables.omega_window * scratch[rows]
if self._in_stage_absorber:
# The rate is additive to the normalised material term. Reusing the
# transverse scratch avoids a second retained physical spectral volume.
scratch.reshape(shape)[...] = np.fft.ifft2(lab.reshape(shape), axes=(0, 1))
temporal = self._tables.temporal_rate
timed = temporal is not None and responses.absorber_scheme == "nonlinear"
for first in range(0, transform.n_nodes, self._node_chunk):
rows = slice(first, first + self._node_chunk)
rate = geometry.absorber_rate[rows, None, None]
if not timed:
# A rate of the node alone commutes with the temporal transforms:
# a spatial-only pass needs no temporal pair (SEP 40 section 4.7).
scratch[rows] = -0.5 * rate * scratch[rows]
continue
field_t = to_time(
scratch[rows], grids.crop_index, grids.n_to, kind=self._kind
)
scratch[rows] = to_frequency(
-0.5 * (rate + temporal) * field_t,
grids.crop_index,
kind=self._kind,
)
view = scratch.reshape(shape)
view[...] = np.fft.fft2(view, axes=(0, 1))
result += grids.active_mask * scratch
return result * inverse_propagator
def _nonlinear_slab(
self,
lab: np.ndarray,
bundle: StageScalars,
inverse_propagator: np.ndarray,
) -> np.ndarray:
"""Evaluate one hybrid planar stage: slab synthesis in x, an FFT in y.
The ``(p, k_y)`` columns go to ``(p, y)`` rows by the inverse DFT in y, and
the rows to time -- a row is a slab amplitude, whose time signal is a real
field's on a field grid -- so that, as on the modal route, only ``n_p * n_y``
temporal transforms are taken each way. In time, the slab synthesis (which
carries the pad scale) gives the field at the ``(x, y)`` nodes, the responses
are the Cartesian ones node by node, and the slab rule's dual basis projects
the polarisation back onto the rows; the rows return to frequency and to
``(p, k_y)``, and each column takes its own prefactor from the separable leaf
(kernel schema 15). The y collar's in-stage rate depends on y alone, so it
acts on the rows directly.
- ``lab``: Lab-frame stage spectrum.
"""
problem = self._problem
transform, grids, responses = (
problem.transform,
problem.grids,
problem.responses,
)
geometry = transform.geometry
assert geometry is not None
result = np.zeros_like(lab)
if len(responses.response_order) == 1 and not self._in_stage_absorber:
return result
n_x, n_y = geometry.shape
n_p = transform.synthesis.shape[1]
rows_f = slab_rows(transform, lab)
temporal = responses.temporal_absorber_fine
timed = temporal is not None and responses.absorber_scheme == "nonlinear"
rows_t = (
to_time(rows_f, grids.crop_index, grids.n_to, kind=self._kind)
if len(responses.response_order) > 1 or timed
else None
)
if len(responses.response_order) > 1:
assert rows_t is not None
raman = self._raman_spectrum(bundle.raman_rates, bundle.raman_densities)
envelope = responses.envelope_plasma is not None
plasma = bool(responses.plasma_channels)
projected = np.zeros_like(rows_t)
# The envelope plasma's Drude drive and loss current, projected as the
# polarisation is; empty unless the response is present.
drives = [
np.zeros_like(rows_t) for _ in range(2 if envelope or plasma else 0)
]
# Whole y rows at a time, as many as the node chunk holds.
block = max(1, self._node_chunk // n_x)
for first in range(0, n_y, block):
rows = slice(first * n_p, min(first + block, n_y) * n_p)
count = (rows.stop - rows.start) // n_p
field_t = np.matmul(
transform.synthesis, rows_t[rows].reshape(count, n_p, -1)
).reshape(count * n_x, *rows_t.shape[1:])
sources = self._column_sources(field_t, bundle, raman)
current = sources.current
source_rows = [sources.polarisation]
if envelope:
assert responses.envelope_plasma is not None
source_rows.extend(
envelope_sources(
field_t,
responses.envelope_plasma,
bundle,
grids.dt_fine,
grids.t_window_fine,
)
)
if current is not None:
source_rows.extend(
(
grids.t_window_fine * current,
grids.t_window_fine_derivative * current,
)
)
for target, source in zip(
(projected, *drives), source_rows, strict=True
):
target[rows] = np.matmul(
transform.projection, source.reshape(count, n_x, -1)
).reshape(count * n_p, *rows_t.shape[1:])
spectrum = to_frequency(projected, grids.crop_index, kind=self._kind)
if envelope:
assert responses.envelope_plasma is not None
factors = responses.envelope_plasma.factors
spectrum += factors.drude * to_frequency(
drives[0], grids.crop_index, kind=self._kind
)
spectrum += factors.loss * to_frequency(
drives[1], grids.crop_index, kind=self._kind
)
if plasma:
spectrum += self._held_streams(drives[0], drives[1])
columns = slab_columns(transform, spectrum)
data = problem.linear.separable
assert data is not None
for first in range(0, transform.n_modes, self._node_chunk):
rows = slice(first, first + self._node_chunk)
_, prefactor = separable_values(data, rows)
result[rows] = prefactor * grids.omega_window * columns[rows]
if self._in_stage_absorber:
result += self._slab_absorber(rows_f, rows_t)
return result * inverse_propagator
def _over_nodes(
self,
modal_t: Inexact[np.ndarray, "n_modes n_pol n_to"],
bundle: StageScalars,
) -> tuple[
Num[np.ndarray, "n_modes n_pol n_to"],
Num[np.ndarray, "n_modes_c n_pol_c n_to_c"] | None,
]:
"""Run the response pass over the quadrature in chunks and project it back.
The chunk loop of ``architecture.md`` section 13: the space-domain buffers are
sized by the node chunk's and not by the node count, so a chunk of one
and a chunk of every node differ only in round-off. The embedded coarse rule is
projected in the same loop, from the same node polarisation, because that is
what makes the quadrature alarm free: the two rules share every node the coarse
one has.
- Returns: the modal polarisation on the fine time grid, and the same under the
embedded coarse rule, or ``None`` when the quadrature has no embedded pair
and the estimate would be identically zero.
"""
responses, grids = self._problem.responses, self._problem.grids
transform = self._problem.transform
taper = bundle.taper_scale
# Once per stage rather than once per chunk: the kernel spectrum does not depend
# on the nodes, and along a gradient it is one real transform of 2 n_to against
# n_modes n_pol transforms of n_to that the stage costs anyway.
raman = self._raman_spectrum(bundle.raman_rates, bundle.raman_densities)
n_pol = transform.n_pol
projected = np.zeros(
(transform.n_modes, self._problem.shape[1], grids.n_to),
dtype=modal_t.dtype,
)
coarse = None if self._embedded is None else np.zeros_like(projected)
envelope = self._problem.responses.envelope_plasma
envelope_projected = (
None
if envelope is None
else (
np.zeros_like(projected),
np.zeros_like(projected),
None if coarse is None else np.zeros_like(coarse),
None if coarse is None else np.zeros_like(coarse),
)
)
plasma_projected = (
(
np.zeros_like(projected),
np.zeros_like(projected),
None if coarse is None else np.zeros_like(coarse),
None if coarse is None else np.zeros_like(coarse),
)
if bool(responses.plasma_channels)
else None
)
for first in range(0, transform.n_nodes, self._node_chunk):
rows = slice(first * n_pol, (first + self._node_chunk) * n_pol)
field_t = synthesise(modal_t, self._tables.synthesis[rows], taper, n_pol)
sources = self._column_sources(field_t, bundle, raman)
polarisation_t = sources.polarisation
projected = projected + project(
polarisation_t, self._tables.projection[:, rows], taper, n_pol
)
if coarse is not None and self._embedded is not None:
coarse = coarse + project(
polarisation_t, self._embedded[:, rows], taper, n_pol
)
if sources.current is not None and plasma_projected is not None:
gated, edge, coarse_gated, coarse_edge = plasma_projected
for target, reduced, window in (
(gated, coarse_gated, self._tables.t_window),
(edge, coarse_edge, self._tables.t_window_derivative),
):
current = window * sources.current
target[...] += project(
current, self._tables.projection[:, rows], taper, n_pol
)
if reduced is not None and self._embedded is not None:
reduced[...] += project(
current, self._embedded[:, rows], taper, n_pol
)
if envelope is not None and envelope_projected is not None:
drive, loss = self._envelope_sources(field_t, bundle)
full_drive, full_loss, coarse_drive, coarse_loss = envelope_projected
full_drive += project(
drive, self._tables.projection[:, rows], taper, n_pol
)
full_loss += project(
loss, self._tables.projection[:, rows], taper, n_pol
)
if (
self._embedded is not None
and coarse_drive is not None
and coarse_loss is not None
):
coarse_drive += project(
drive, self._embedded[:, rows], taper, n_pol
)
coarse_loss += project(loss, self._embedded[:, rows], taper, n_pol)
self._last_plasma = plasma_projected
self._last_envelope = envelope_projected
return projected, coarse
def _radial_plasma_spectrum(
self,
modal_t: np.ndarray,
bundle: StageScalars,
) -> np.ndarray:
"""Transform three nodal streams, combine, then project once in frequency."""
problem = self._problem
transform, grids = problem.transform, problem.grids
spectrum = np.zeros(problem.shape, dtype=np.complex128)
raman = self._raman_spectrum(bundle.raman_rates, bundle.raman_densities)
for first in range(0, transform.n_nodes, self._node_chunk):
rows = slice(
first * transform.n_pol,
(first + self._node_chunk) * transform.n_pol,
)
field = synthesise(
modal_t,
self._tables.synthesis[rows],
bundle.taper_scale,
transform.n_pol,
)
sources = self._column_sources(field, bundle, raman)
assert sources.current is not None
nodal = to_frequency(sources.polarisation, grids.crop_index, kind="field")
nodal += self._held_current(sources.current)
spectrum += project(
nodal,
self._tables.projection[:, rows],
bundle.taper_scale,
transform.n_pol,
)
return spectrum
def _column_sources(
self,
field_t: np.ndarray,
bundle: StageScalars,
raman: np.ndarray | None,
) -> NonlinearSources:
"""Evaluate one column's collared polarisation and ungated current.
- ``field_t``: physical node fields in V/m, with time last.
- ``raman``: damped Raman convolution spectrum, when required by the response.
- Returns: the collared local polarisation in C/m² and the ungated current in
A/m².
"""
grids = self._problem.grids
return nonlinear_sources(
field_t,
self._problem.responses,
self._tables.t_window,
kind=self._kind,
density=bundle.density,
preionisation=bundle.preionisation,
dt=grids.dt_fine,
carrier=self._carrier,
raman_spectrum=raman,
scalars=bundle,
)
def _held_streams(self, gated: np.ndarray, edge: np.ndarray) -> np.ndarray:
"""Transform and combine the current products in polarisation units.
- ``gated``, ``edge``: fine-time ``gJ`` and ``g'J`` rows, optionally projected
before this call.
- Returns: cropped raw-DFT polarisation-equivalent source, zero on inactive
bins.
"""
grids = self._problem.grids
return held_plasma_spectrum(
gated, edge, grids.omega, grids.crop_index, grids.active_mask
)
def _held_current(self, current: np.ndarray) -> np.ndarray:
"""Form and transform the two collared products of a nodal current.
- ``current``: the ungated nodal current in A/m², fine time last.
- Returns: cropped raw-DFT polarisation-equivalent source at the nodes.
"""
return self._held_streams(
self._tables.t_window * current, self._tables.t_window_derivative * current
)
def _envelope_sources(
self, field_t: Complex[np.ndarray, "n_nodes n_pol n_to"], bundle: StageScalars
) -> tuple[
Complex[np.ndarray, "n_nodes n_pol n_to"],
Complex[np.ndarray, "n_nodes n_pol n_to"],
]:
"""Return the envelope-grid plasma's windowed drive and loss at some nodes.
- ``field_t``: the field at the nodes, V/m.
"""
envelope = self._problem.responses.envelope_plasma
assert envelope is not None
return envelope_sources(
field_t,
envelope,
bundle,
self._problem.grids.dt_fine,
self._tables.t_window,
)
def _raman_spectrum(
self, rates: tuple[float, ...], densities: tuple[float, ...] = ()
) -> Complex[np.ndarray, "... n_omega_doubled"] | None:
"""Return the damped Raman kernel spectrum for a set of rates, anew.
Memoised on the **decay rates** rather than on the density, because the rates
are what the spectrum depends on: a glass's are zero at every density, so its
kernel is transformed once for the whole run, and a molecular gas on a gradient
presents new rates at every stage and is transformed once per stage. Only the
most recent set is kept, which is the right choice here -- a growing cache would
hold thousands of spectra and hit none.
- ``rates``: the decay rate of each term at the stage's position, s^-1, off the
bundle.
- ``densities``: component amplitude densities in m^-3, in Raman-component
order. Multiple components include every amplitude in the cache key; one keeps
density outside the convolution and retains the original arithmetic.
- Returns: the spectrum of shape ``(n_to + 1,)``, or ``None`` when no Raman
kernel was compiled.
"""
components = self._problem.responses.raman_terms
if not components:
return None
amplitudes = densities if len(components) > 1 else ()
if (
self._raman_kernel is None
or self._raman_rates != rates
or self._raman_densities != amplitudes
):
if self._problem.transform.n_pol * self._problem.shape[1] == 2:
self._raman_kernel = tensor_raman_spectrum(
components,
rates,
densities if len(components) > 1 else (1.0,),
self._problem.grids.dt_fine,
)
elif len(components) == 1:
compiled = components[0]
self._raman_kernel = raman_spectrum(
compiled.undamped,
rates,
compiled.fraction,
self._problem.grids.dt_fine,
)
else:
self._raman_kernel = mixture_raman_spectrum(
components, rates, densities, self._problem.grids.dt_fine
)
self._raman_rates = rates
self._raman_densities = amplitudes
self._raman_transforms += 1
return self._raman_kernel
def _absorber_term(
self,
modal_t: Inexact[np.ndarray, "n_modes n_pol n_to"],
*,
may_quiet: bool = False,
) -> Complex[np.ndarray, "n_modes n_pol n_omega"] | None:
"""Return the in-stage absorber's contribution, or ``None`` in the other scheme.
On the modal stage (`may_quiet`) a temporal collar alone is left out while the
boundary monitor finds it quiet (SEP 21): the term is then below
:data:`solprop.monitor.QUIET`, and its transform is the stage's largest cost
after the response's.
- Returns: the absorber's term on the coarse grid, or ``None`` when the
``"split_step"`` scheme is active and the rate is applied to the state after
the step instead.
"""
if not self._in_stage_absorber:
return None
radial = self._spatial_absorber if self._spatial_absorber.size else None
if may_quiet and self.collar_quiet and radial is None:
return None
rate = self._tables.temporal_rate
in_stage = self._problem.responses.absorber_scheme == "nonlinear"
grids = self._problem.grids
return absorber_term(
modal_t,
rate if in_stage else None,
radial,
grids.crop_index,
grids.active_mask,
kind=self._kind,
)
def _slab_absorber(
self,
rows_f: Complex[np.ndarray, "n_modes n_pol n_omega"],
rows_t: Inexact[np.ndarray, "n_modes n_pol n_to"] | None,
) -> Complex[np.ndarray, "n_modes n_pol n_omega"]:
"""Return the planar in-stage collar's term on the ``(p, k_y)`` columns.
The collar's rate depends on y alone, so it acts on the ``(p, y)`` rows. With
no temporal rate in-stage it commutes with the temporal transforms, and the
pass needs no temporal pair (SEP 40 section 4.7).
- ``rows_t``: the same rows in time; required when a temporal rate applies
in-stage.
"""
problem = self._problem
transform, grids, responses = (
problem.transform,
problem.grids,
problem.responses,
)
geometry = transform.geometry
assert geometry is not None
n_x, n_y = geometry.shape
n_p = transform.synthesis.shape[1]
rate = np.repeat(geometry.absorber_rate.reshape(n_y, n_x)[:, 0], n_p)[
:, None, None
]
temporal = responses.temporal_absorber_fine
if temporal is not None and responses.absorber_scheme == "nonlinear":
assert rows_t is not None
term = to_frequency(
-0.5 * (rate + temporal) * rows_t, grids.crop_index, kind=self._kind
)
else:
term = -0.5 * rate * rows_f
return grids.active_mask * slab_columns(transform, term)
[docs]
def score_quadrature(self) -> tuple[float, float]:
"""Score the quadrature from the last stage of an accepted step.
The relative difference between the projections of the same node polarisation
with the Kronrod rule and with its embedded Gauss subset, at the cost of one
extra forward transform per accepted step rather than a whole second evaluation
of the transform.
It is a **statistic and a warning, never a controller input**: a
quadrature too coarse for the integrand is a modelling error the step size
cannot fix, and feeding it to the controller would only shrink the step until
the run stopped.
The value is ``nan`` when the rule has no embedded pair, because the difference
is then identically zero and reading that as convergence would be wrong; and
``nan`` where the polarisation itself vanishes, at a true vacuum end, because a
relative measure of nothing says nothing. The session reports a value above
:data:`~solprop.translate.modal.QUADRATURE_ALARM` once per plane, and the
``quadrature_error`` statistic reads it.
Returns
-------
float
The alarm, dimensionless, or NaN.
float
Where the last stage was evaluated, m, or NaN without one.
"""
if (
self._last_coarse is None
or self._last_projected is None
or self._last_bundle is None
):
self._alarm = math.nan
return self._alarm, math.nan
grids = self._problem.grids
weight = self._prefactor(self._last_bundle) * self._tables.omega_window
fine = weight * to_frequency(
self._last_projected, grids.crop_index, kind=self._kind
)
coarse = weight * to_frequency(
self._last_coarse, grids.crop_index, kind=self._kind
)
if self._last_envelope is not None:
assembly = self._problem.responses.envelope_plasma
assert assembly is not None
drive, loss, coarse_drive, coarse_loss = self._last_envelope
assert coarse_drive is not None and coarse_loss is not None
for factor, full, reduced in (
(assembly.factors.drude, drive, coarse_drive),
(assembly.factors.loss, loss, coarse_loss),
):
fine += (
weight
* factor
* to_frequency(full, grids.crop_index, kind=self._kind)
)
coarse += (
weight
* factor
* to_frequency(reduced, grids.crop_index, kind=self._kind)
)
if self._last_plasma is not None:
gated, edge, coarse_gated, coarse_edge = self._last_plasma
assert coarse_gated is not None and coarse_edge is not None
fine += weight * self._held_streams(gated, edge)
coarse += weight * self._held_streams(coarse_gated, coarse_edge)
scale = float(np.linalg.norm(fine))
self._alarm = (
math.nan if scale == 0.0 else float(np.linalg.norm(coarse - fine) / scale)
)
return self._alarm, self._last_bundle.z1
[docs]
@dataclass(frozen=True)
class SourceTables:
"""The problem's tables a source evaluation multiplies by.
The arrays the passes read, gathered once from the problem.
Attributes
----------
synthesis : numpy.ndarray
``transform.synthesis``.
projection : numpy.ndarray
``transform.projection``.
t_window : numpy.ndarray
``grids.t_window_fine``.
t_window_derivative : numpy.ndarray
``grids.t_window_fine_derivative``.
omega_window : numpy.ndarray
``grids.omega_window``.
temporal_rate : numpy.ndarray or None
``responses.temporal_absorber_fine``.
"""
synthesis: Float[np.ndarray, "n_rows n_modes_s"]
projection: Float[np.ndarray, "n_modes n_columns"]
t_window: Float[np.ndarray, " n_to"]
t_window_derivative: Float[np.ndarray, " n_to"]
omega_window: Float[np.ndarray, " n_omega"]
temporal_rate: Float[np.ndarray, " n_to"] | None
[docs]
@classmethod
def of(cls, problem: PropagationProblem) -> "SourceTables":
"""Return the problem's own tables.
Parameters
----------
problem : solprop.translate.problem.PropagationProblem
The problem.
Returns
-------
SourceTables
References to its arrays, uncopied.
"""
grids = problem.grids
return cls(
problem.transform.synthesis,
problem.transform.projection,
grids.t_window_fine,
grids.t_window_fine_derivative,
grids.omega_window,
problem.responses.temporal_absorber_fine,
)
def _general_maps(
problem: PropagationProblem, plan: NodeChunkPlan | None = None
) -> GeneralMaps | None:
"""Derive the general modal route's maps, or return ``None`` for another route.
The maps are read out of the leaves once, here, because the route propagates
constant geometry: one interval of one Chebyshev degree along z, so there is
nothing to evaluate per stage. The chunk is the backend's own memory strategy
within the plan's budget, or the plan's exact chunk when one was forced.
- ``plan``: the backend's node-chunk plan; ``None`` plans the automatic one.
- Returns: the derived maps, or ``None`` when the problem carries no modal tables.
"""
tables = problem.transform.modal_tables
if tables is None:
return None
assert tables.synthesis is not None and tables.projection is not None
chunk = general_planned_chunk(
problem, plan_node_chunk(problem) if plan is None else plan
)
regional = problem.responses.regional_responses
owner, delayed_tensor, delayed_spectrum = node_delayed_maps(tables, regional)
moving = tables.synthesis.shape[0] * tables.synthesis.shape[1] > 1
maps = GeneralMaps(
tables.synthesis[0, 0],
tables.projection[0, 0],
node_kerr_tensor(tables, regional),
tables.source_frequency_factor,
chunk,
node_kerr_form(regional),
owner,
delayed_tensor,
delayed_spectrum,
# A moving guide's coefficients, flattened over (n_intervals, n_deg) in the
# order the stage bundle's transform_weights are.
tables.synthesis.reshape(-1, *tables.synthesis.shape[2:]) if moving else None,
tables.projection.reshape(-1, *tables.projection.shape[2:]) if moving else None,
problem.responses.dispersive_kerr,
None if problem.responses.dispersive_kerr is None else tables.region_index,
)
logger.debug(
"numpy_ref general modal route: %d channels on %d nodes, chunk %d, "
"%d fine bins, gauge %s, %s cubic, %d delayed term(s)",
maps.n_modes,
maps.n_nodes,
maps.node_chunk,
int(tables.omega_fine.size),
tables.gauge_id,
maps.form,
maps.n_terms,
)
return maps
def _harmonic_carrier(
problem: PropagationProblem,
) -> Complex[np.ndarray, " n_to"] | None:
"""Return ``exp(2 i omega_0 t)`` on the fine grid when the harmonic is radiated.
The envelope-grid third-harmonic term needs the carrier the coarse grid does not
resolve; it arrives as ``grids.carrier_2w0``, so that no physics is formed inside a
backend (``docs/dev/architecture.md`` section 3). The sign is the FFT convention's
(``docs/guide/media/nonlinear.md``). ``validate`` refuses a harmonic term without
the carrier, so only a hand-built problem reaches the refusal here.
- Returns: the carrier of shape ``(n_to,)``, or ``None`` when no harmonic term is
present.
"""
if not problem.responses.harmonic_carrier:
return None
if problem.grids.carrier_2w0 is None:
msg = (
"a third-harmonic Kerr term is compiled and grids.carrier_2w0 is absent; "
"the envelope's harmonic sits an offset 2 omega_0 from its carrier and the "
"response pass cannot place it without the factor"
)
raise BackendError(msg)
return problem.grids.carrier_2w0
def _embedded_projection(
problem: PropagationProblem,
) -> Float[np.ndarray, "n_modes n_columns"] | None:
"""Return the embedded coarse-rule projection, when the quadrature has one.
``transform.projection_coarse`` equals ``transform.projection`` when the rule has no
embedded pair, in which case the difference of the two projections is identically
zero and reading it as convergence would be wrong
(:class:`solprop.modes.quadrature.ModeMatrices`). The alarm reports ``nan`` there
instead, and the second projection is not computed at all.
- Returns: the coarse projection, or ``None`` when it is the fine one.
"""
transform = problem.transform
if np.array_equal(transform.projection, transform.projection_coarse):
return None
return transform.projection_coarse