Source code for solprop.backends.numpy_ref.statistics

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

"""The statistics the reference forms itself, from a committed state (SEP 9, SEP 19).

:class:`ReferenceStatistics` answers :meth:`NumpyWorkspace.stats
<solprop.backends.numpy_ref.workspace.NumpyWorkspace.stats>`. The statistics of the
saved field are :func:`solprop.stats.collect`'s (or, on a spatial geometry,
:func:`solprop.backends.spatial.collect_spatial`'s), with the Poynting weight and the
basis metric at the plane; the ones a saved plane does not carry are formed here: the
electron density and peak ionisation rate at the densest node, the species and
mixture populations, the plasma integration diagnostics (SEP 18), the peak on-axis
intensity and the four on-axis plasma statistics, which scan the field synthesised on
the axis unless a quadrature node sits there. :meth:`ReferenceStatistics.node_fields`
is the one definition of the node fields every population scan reads, the fields the
stage's response pass evaluates.
"""

import dataclasses
from collections.abc import Iterator, Mapping, Sequence

import numpy as np
from jaxtyping import Complex, Float, Inexact, Num

from solprop.backends.numpy_ref.passes.plasma import (
    envelope_populations,
    ionisation_rate,
    plasma_channel_fractions,
    plasma_integration_diagnostics,
    plasma_integration_statistics,
    plasma_scan,
)
from solprop.backends.numpy_ref.passes.transforms import synthesise, to_time
from solprop.backends.populations import (
    axis_node,
    axis_refusal,
    axis_row_matrix,
    axis_statistics,
    population_statistics,
)
from solprop.backends.spatial import FarFieldTables, collect_spatial, slab_synthesis
from solprop.constants import EPS0, C
from solprop.exceptions import BackendError
from solprop.fourier import GridKind
from solprop.grid import TimeGrid
from solprop.modes.protocol import Mode
from solprop.modes.quadrature import mode_matrix, on_axis_rule
from solprop.output.capability import (
    declared_capability,
    refusal_for,
    withheld_accessors,
)
from solprop.output.records import SavedPlane
from solprop.profiles import ZProfile
from solprop.stats import (
    _POYNTING_STATISTICS,
    CATALOGUE,
    METRIC_WEIGHTED_STATISTICS,
    ON_AXIS_PLASMA_STATISTICS,
    PLASMA_INTEGRATION_STATISTICS,
    WEIGHT_DEPENDENT_STATISTICS,
    StatsSpec,
    _poynting_statistics,
    analytic_field,
    collect,
    weight_refusal_for,
)
from solprop.translate.coupled import metric_at
from solprop.translate.linop import power_weight_at
from solprop.translate.problem import PropagationProblem
from solprop.translate.routes import flux_of
from solprop.translate.run_request import RunRequest

__all__ = ["ReferenceStatistics"]


[docs] class ReferenceStatistics: """The reference's statistics of a state, and the tables they read. Built once by the workspace from the validated problem and request. It holds no state of the run: :meth:`collect` is handed the committed state and the quadrature alarm, and keeps only what does not depend on them -- the far-field tables, the Poynting weight's buffer, the on-axis synthesis matrix and the axis node. Parameters ---------- problem : solprop.translate.problem.PropagationProblem The validated problem. request : solprop.translate.run_request.RunRequest Its run's request, whose statistics the far-field tables are formed for. node_chunk : int The nodes a population scan holds at once. grid : solprop.grid.TimeGrid or None The grid the state lives on, which the statistics need. modes : collections.abc.Sequence or None The propagated modes, in state order, for the on-axis statistics. profiles : collections.abc.Mapping or None The z-profiles keyed by statistic name. name : str The backend's name, for messages. Attributes ---------- axis_scans : int The on-axis plasma scans actually run (SEP 19), so that a test can see that a rule with a node on the axis supplies that row instead of a fresh scan. """ def __init__( self, problem: PropagationProblem, request: RunRequest, *, node_chunk: int, grid: TimeGrid | None, modes: Sequence[Mode] | None, profiles: Mapping[str, ZProfile] | None, name: str, ) -> None: """Form the tables; refuse a geometry the far-field statistics refuse.""" self._problem = problem self._kind: GridKind = problem.grid_kind self._node_chunk = node_chunk self._grid = grid self._modes = modes self._profiles = profiles self.name = name self._power_weight = np.empty( problem.shape if problem.transform.geometry is None else (0,) ) # Formed once, so a geometry the far-field statistics refuse is refused here, # before any step (SEP 23 section 6). self._far_field = FarFieldTables(problem, request.observation.stats) self._on_axis: Float[np.ndarray, "n_rows n_modes"] | None = None self._axis_node: int | None = None self._axis_node_known = False self.axis_scans = 0
[docs] @property def power_weight_bytes(self) -> int: # numpydoc ignore=RT01 """The Poynting weight buffer's size, which the memory ledger names.""" return self._power_weight.nbytes
[docs] def close(self) -> None: """Release the weight buffer. Idempotent.""" self._power_weight = np.empty(0)
[docs] def collect( self, spec: StatsSpec, state: Complex[np.ndarray, "n_modes n_pol n_omega"], z: float, *, alarm: float, ) -> dict[str, np.ndarray]: """Collect the requested statistics of a state at a position. The statistics of the saved field go to :func:`solprop.stats.collect`; there is exactly one definition of each in the package and that is it. The statistics :class:`solprop.stats.StatDefinition` marks ``backend`` are of quantities a saved plane does not carry -- the electron density, the peak ionisation rate, the on-axis intensity, the quadrature error -- and are formed here from the state and the workspace's tables. Parameters ---------- spec : solprop.stats.StatsSpec Which statistics and which windows. state : numpy.ndarray The committed state, shape ``(n_modes, n_pol, n_omega)``. z : float The state's position, m. alarm : float The quadrature alarm the last accepted step scored, which the ``quadrature_error`` statistic reports. Returns ------- dict Small host arrays keyed by statistic name. """ grid = self._require_grid() # Before the spatial branch: a spatial run asked for a # general name would otherwise reach `collect_spatial` and be answered from a # geometry that carries no certified metric at all. _refuse_inadmissible(self._problem, spec) if self._problem.transform.geometry is not None: response_names = ( {"electron_density", "peak_ionisation_rate", "quadrature_error"} | set(PLASMA_INTEGRATION_STATISTICS) | {name for name in CATALOGUE if name.startswith("species_")} ) spatial_spec = dataclasses.replace( spec, names=tuple(name for name in spec.names if name not in response_names), periodic=(), ) tables = self._far_field.for_spec(spatial_spec) spatial = collect_spatial( spatial_spec, grid, self._problem.transform, state, z=z, flux=flux_of(self._problem.route), profiles=self._profiles, tables=tables, operator=self._problem.linear.separable, node_chunk=self._node_chunk, ) return { name: np.array(spatial[name]) for name in spatial_spec.names } | self._backend_statistics( tuple(name for name in spec.names if name in response_names), state, z, alarm, ) # The weight is a Chebyshev evaluation per column, which is the whole of what # the Poynting weighting adds to a statistics call on a CPU (0.053 ms of # 0.056 ms on the reduced-M2 case), so a spec that asks for none of the # Poynting statistics -- a periodic plasma subset, say -- never # evaluates it. needed = bool(set(spec.names) & WEIGHT_DEPENDENT_STATISTICS) if needed: np.copyto(self._power_weight, power_weight_at(self._problem, z)) weight_refusal = weight_refusal_for(spec.names, self._power_weight) if weight_refusal is not None: raise BackendError(weight_refusal) weighted = needed and not np.all(self._power_weight == 1.0) power_names = tuple( name for name in spec.names if weighted and name in _POYNTING_STATISTICS ) axis = None if "peak_intensity" in power_names: if self._modes is None: msg = "the peak on-axis intensity needs the mode set" raise BackendError(msg) axis = self._on_axis_synthesis(self._modes, z) power_values = ( _poynting_statistics(spec, grid, state, self._power_weight, axis) if weighted else {} ) owned = tuple( name for name in spec.names if CATALOGUE[name].backend and name not in power_names ) delegated = dataclasses.replace( spec, names=tuple( name for name in spec.names if name not in owned and name not in power_names ), periodic=tuple( name for name in spec.periodic if name not in owned and name not in power_names ), ) # The basis metric at this plane: the # statistics of `METRIC_WEIGHTED_STATISTICS` are functionals of the physical # same-frequency flux `a.H W a`, and on a declared change of basis W is not # the identity. `metric_at` returns None for an identity metric, which is # the statistics' own bitwise-unchanged path, so an ordinary run pays # nothing. metric = ( metric_at(self._problem.linear.modal_metric, z) if set(delegated.names) & METRIC_WEIGHTED_STATISTICS else None ) collected = collect( delegated, grid, SavedPlane(z=z, field=state), modes=self._modes, profiles=self._profiles, metric=metric, ) values = {name: np.array(collected[name]) for name in delegated.names} values.update({name: np.array(power_values[name]) for name in power_names}) return values | self._backend_statistics(owned, state, z, alarm)
def _backend_statistics( self, names: tuple[str, ...], state: Complex[np.ndarray, "n_modes n_pol n_omega"], z: float, alarm: float, ) -> dict[str, np.ndarray]: """Share each fresh envelope population scan among the requested statistics. - ``state``: accepted state at this plane. - Returns: requested values, with no retained field cache. """ population_names = ( tuple( name for name in names if name.startswith("species_") or name in ("electron_density", "peak_ionisation_rate") ) if self._problem.responses.envelope_plasma is not None else () ) integration_names = tuple( name for name in names if name in PLASMA_INTEGRATION_STATISTICS ) axis_names = tuple(name for name in names if name in ON_AXIS_PLASMA_STATISTICS) if axis_names and not population_names: # The species statistics are the node scan of `_species_statistics` on # every route, so sharing one scan with the on-axis statistics changes # none of their values and lets a node on the axis supply its row. population_names = tuple( name for name in names if name.startswith("species_") ) # Node scans of this observation only: a rule with a node on the axis hands # its row to the on-axis statistics, and nothing outlives the call, so no # stale stage or rejected step can be reused. scans: list[tuple[np.ndarray, np.ndarray]] = [] result = { name: self._backend_stat(name, state, z, alarm) for name in names if name not in population_names and name not in integration_names and name not in axis_names } if integration_names: diagnostics = self._integration_diagnostics(state, z) result.update( {name: np.array(diagnostics[name]) for name in integration_names} ) if population_names: species = self._species_statistics(state, z, scans) result.update({name: np.array(species[name]) for name in population_names}) if axis_names: axis = self._axis_statistics(state, scans[0] if scans else None, z) result.update({name: np.array(axis[name]) for name in axis_names}) return result def _backend_stat( self, name: str, state: Complex[np.ndarray, "n_modes n_pol n_omega"], z: float, alarm: float, ) -> np.ndarray: """Compute one backend-owned statistic.""" if name == "quadrature_error": return np.full((), alarm) if name == "peak_intensity": return np.array(self._peak_intensity(state, z)) if ( name.startswith("species_") or self._problem.flags.n_channels > 1 or self._problem.responses.envelope_plasma is not None ): return np.array(self._species_statistics(state, z)[name]) return np.array( self._ionisation(state, z)[0 if name == "electron_density" else 1] ) def _species_statistics( self, field: Complex[np.ndarray, "n_modes n_pol n_omega"], z: float, scans: list[tuple[np.ndarray, np.ndarray]] | None = None, ) -> dict[str, np.ndarray]: """Evaluate independent populations on the actual nonlinear nodes. Every channel's final fraction and peak rate at every node of :meth:`node_fields`: cycle-averaged on an envelope grid, the field grid's exposure scan otherwise. - ``scans``: where to leave this observation's channel fractions and peak rates at every node, for the on-axis statistics to reuse. - Returns: the five species statistics and the two total plasma statistics. """ responses = self._problem.responses channels = responses.population_channels if not channels: empty = np.zeros((0, self._problem.transform.n_nodes)) return population_statistics(self._problem, z, empty, empty) initials = tuple(float(channel.preionisation(z)) for channel in channels) dt = self._problem.grids.dt_fine finals, peaks = [], [] for nodes in self.node_fields(field, z): if responses.envelope_plasma is not None: final, peak = envelope_populations( nodes, responses.envelope_plasma, initials, dt ) else: rates, population = plasma_channel_fractions( nodes, responses.plasma_channels, initials, dt, responses.plasma_integral, ) final, peak = population[:, :, -1], rates.max(axis=-1) finals.append(final) peaks.append(peak) fractions, largest = ( np.concatenate(finals, axis=1), np.concatenate(peaks, axis=1), ) if scans is not None: scans.append((fractions, largest)) return population_statistics(self._problem, z, fractions, largest) def _integration_diagnostics( self, field: Complex[np.ndarray, "n_modes n_pol n_omega"], z: float ) -> dict[str, np.ndarray]: """Return the plasma column's integration diagnostics at this plane (SEP 18). The undershoot of the exposure increments, the relative work defect of the loss current and the boundary level of the free-current integrand, over every node and field plasma channel (:data:`solprop.stats.PLASMA_INTEGRATION_STATISTICS`). - Returns: the three statistics, each zero-dimensional and dimensionless. """ responses = self._problem.responses channels = responses.plasma_channels if not channels: msg = ( "the plasma integration diagnostics read the field-grid plasma " "column, and this problem carries none" ) raise BackendError(msg) initial = tuple(float(channel.preionisation(z)) for channel in channels) parts = np.zeros(6) for nodes in self.node_fields(field, z): parts = np.maximum( parts, plasma_integration_diagnostics( nodes, channels, initial, self._problem.grids.dt_fine, responses.plasma_integral, ), ) undershoot, defect, boundary = plasma_integration_statistics(parts) return { "plasma_undershoot": np.asarray(undershoot), "plasma_work_defect": np.asarray(defect), "plasma_boundary_level": np.asarray(boundary), }
[docs] def node_fields( self, state: Complex[np.ndarray, "n_modes n_pol n_omega"], z: float ) -> Iterator[Num[np.ndarray, "n_nodes_chunk n_components n_to"]]: """Yield the physical field at the nodes the responses see, chunk by chunk. The fields the stage's response pass evaluates, on the fine time grid: the modal quadrature's nodes at once (``_nodes_at``), or a separable geometry's physical nodes by the node chunk -- the slab synthesis in x, which carries the pad scale, or the inverse transverse DFT followed by the pad scale. Parameters ---------- state : numpy.ndarray A state, shape ``(n_modes, n_pol, n_omega)``. z : float Its position, m. Yields ------ numpy.ndarray The field at a chunk of nodes, V/m, shape ``(n_nodes_chunk, n_components, n_to)``: real on a field grid, complex on an envelope grid. """ problem = self._problem if problem.linear.separable is None: yield self._nodes_at(state, z) return grids, transform = problem.grids, problem.transform geometry = transform.geometry assert geometry is not None slab = geometry.kind == "slab" if slab: physical = slab_synthesis(transform, state) else: nx, ny = geometry.shape physical = np.fft.ifft2( state.reshape(ny, nx, *state.shape[1:]), axes=(0, 1) ).reshape(state.shape) for first in range(0, len(physical), self._node_chunk): rows = physical[first : first + self._node_chunk] yield to_time( rows if slab else rows * grids.pad_scale, grids.crop_index, grids.n_to, kind=self._kind, )
def _ionisation( self, field: Complex[np.ndarray, "n_modes n_pol n_omega"], z: float, ) -> tuple[np.ndarray, np.ndarray]: """Return the electron density and the peak ionisation rate at this plane. Both are read at the **node of largest ionised fraction**, which is where the plasma the run carries is densest and the only node either number can honestly describe; for a mode-averaged run that is the one node. The axis is not a quadrature node at all and is not where the polarisation was evaluated, so the field is not re-synthesised there. The electron density is ``density(z)`` times the fraction at the **end** of the window: what the pulse leaves behind, not what it reaches in passing. - Returns: the electron density in m^-3 and the peak rate in s^-1, both zero-dimensional. """ responses = self._problem.responses plasma = responses.plasma_coefficients if plasma is None: msg = ( "the electron density and the peak ionisation rate need a compiled " "plasma response, and this problem declares none" ) raise BackendError(msg) largest: float | None = None peak = 0.0 for nodes in self.node_fields(field, z): rate = ionisation_rate(nodes, plasma.rate) fraction, _ = plasma_scan( nodes, rate, plasma, preionisation=float(plasma.preionisation(z)), dt=self._problem.grids.dt_fine, integral=responses.plasma_integral, ) densest = int(np.argmax(fraction[:, -1])) if largest is None or fraction[densest, -1] > largest: largest = float(fraction[densest, -1]) peak = float(np.max(rate[densest])) assert largest is not None return np.asarray(float(plasma.density(z)) * largest), np.asarray(peak) def _peak_intensity( self, field: Complex[np.ndarray, "n_modes n_pol n_omega"], z: float, ) -> np.ndarray: """Return the largest intensity on the axis of the waveguide, in W/m^2. ``eps0 c/2 max_t sum_c |E_{a,c}(0, t)|^2`` with the analytic field synthesised at ``r = 0`` from the modes' own profiles, both Cartesian components. The axis is not a quadrature node, so the mode fields are evaluated there rather than interpolated, and both components are taken so that the answer does not depend on which one the transform resolves or the state carries. One definition for every run: a mode-averaged run synthesises its one mode the same way, which is ``P / A_eff`` for a top-hat profile and the true on-axis value for a real one -- 1.77 times the average for HE_11, so ``P / A_eff`` would under-report it by that factor. The on-axis matrix is built once and rescaled with the taper (``_on_axis_synthesis``), which is what makes this statistic cheap enough for the between-planes channel. """ if self._modes is None: msg = ( "the peak on-axis intensity needs the mode set, which the kernel " "contract does not carry; construct the backend with " "NumpyRefBackend(problem, request, modes=modes)" ) raise BackendError(msg) analytic = analytic_field(self._require_grid(), field) columns = np.tensordot( self._on_axis_synthesis(self._modes, z), analytic, axes=([1], [0]) ) power = np.sum(np.abs(columns) ** 2, axis=tuple(range(columns.ndim - 1))) return np.asarray(0.5 * EPS0 * C * float(np.max(power))) def _nodes_at( self, field: Complex[np.ndarray, "n_modes n_pol n_omega"], z: float, ) -> Num[np.ndarray, "n_nodes n_components n_to"]: """Return the physical field at every quadrature node on the fine time grid. - Returns: the field in V/m, shape ``(n_nodes, n_components, n_to)``. Here ``n_components = transform.n_pol * n_pol`` counts physical components, independently of the state's polarisation axis. """ grids, transform = self._problem.grids, self._problem.transform taper = ( 1.0 if transform.taper_scale is None else float(transform.taper_scale(z)) ) modal_t = to_time(field, grids.crop_index, grids.n_to, kind=self._kind) return synthesise(modal_t, transform.synthesis, taper, transform.n_pol) def _axis_statistics( self, field: Complex[np.ndarray, "n_modes n_pol n_omega"], scan: tuple[np.ndarray, np.ndarray] | None, z: float, ) -> dict[str, np.ndarray]: """Return the four on-axis plasma statistics of the state (SEP 19). A rule with a node on the axis hands over that node's row from this observation's node scan; otherwise the axis row is scanned once (``_axis_populations``). - ``field``: the state at this plane, shape (n_modes, n_pol, n_omega). - ``scan``: this observation's channel fractions and peak rates at every node, when the node statistics already scanned them. - Returns: the four ``on_axis_*`` statistics. """ if self._modes is None: msg = ( "the on-axis plasma statistics need the mode set, which the kernel " "contract does not carry; construct the backend with " f"select({self.name!r}, problem, request, modes=modes)" ) raise BackendError(msg) if not self._axis_node_known: self._axis_node_known = True self._axis_node = axis_node( self._problem, mode_matrix( self._modes, on_axis_rule(self._modes[0].dimlimits(0.0)[0]), 0.0, components=("x", "y"), ).synthesis, ) if scan is not None and self._axis_node is not None: fractions, peaks = scan node = self._axis_node return axis_statistics(self._problem, z, fractions[:, node], peaks[:, node]) self.axis_scans += 1 fractions, peaks = self._axis_populations( field, self._on_axis_synthesis(self._modes, z), z ) return axis_statistics(self._problem, z, fractions, peaks) def _axis_populations( self, field: Complex[np.ndarray, "n_modes n_pol n_omega"], axis: Float[np.ndarray, "2 n_modes"], z: float, ) -> tuple[Float[np.ndarray, " n_channels"], Float[np.ndarray, " n_channels"]]: """Scan the field synthesised on the axis: one row, every channel (SEP 19). The axis is one row per saved plane, against every node of every stage. The field is the same as the node fields' -- the same pad scale, taper and fine grid -- with both Cartesian components of the mode profiles, as for ``peak_intensity``; when the state carries the components itself, the profile's magnitude on the axis is the scalar synthesis. The tables, preionisation and running-integral rule are the node scan's. - ``axis``: the mode set's synthesis on the axis at `z`, taper included, rows x and y (``_on_axis_synthesis``). - Returns: the final ionised fraction and the largest rate (cycle-averaged on an envelope grid) on the axis, one per channel. """ problem = self._problem responses, grids = problem.responses, problem.grids modal_t = to_time(field, grids.crop_index, grids.n_to, kind=self._kind) row: Inexact[np.ndarray, "1 n_components n_to"] = synthesise( modal_t, axis_row_matrix(problem, axis), 1.0, 2 if field.shape[1] == 1 else 1, ) preionisation = tuple( float(channel.preionisation(z)) for channel in responses.population_channels ) if responses.envelope_plasma is not None: fractions, peaks = envelope_populations( row, responses.envelope_plasma, preionisation, grids.dt_fine ) return fractions[:, 0], peaks[:, 0] rates, population = plasma_channel_fractions( row, responses.plasma_channels, preionisation, grids.dt_fine, responses.plasma_integral, ) return population[:, 0, -1], rates[:, 0].max(axis=-1) def _on_axis_synthesis( self, modes: Sequence[Mode], z: float ) -> Float[np.ndarray, "n_rows n_modes"]: """Return the mode set's synthesis matrix on the axis, at the current position. Built once at ``z = 0`` and rescaled by the transform's own taper factor: the axis is the single node ``r = 0`` of :func:`solprop.modes.quadrature.on_axis_rule`, so the law that rescales the transform's matrices -- a scale-invariant profile goes as ``1/a`` and its normalisation as ``a^2`` -- applies to it exactly, and a set that is neither constant nor scale invariant never reaches a backend (``translate.modal``). Rebuilding the matrix at every call was what kept ``peak_intensity`` out of the between-planes channel. - Returns: shape ``(n_rows, n_modes)``, one row per Cartesian component on the axis. """ if self._on_axis is None: rule = on_axis_rule(modes[0].dimlimits(0.0)[0]) matrices = mode_matrix(modes, rule, 0.0, components=("x", "y")) self._on_axis = np.ascontiguousarray(matrices.synthesis) taper = self._problem.transform.taper_scale if taper is None: return self._on_axis return self._on_axis * float(taper(z)) def _require_grid(self) -> TimeGrid: """Return the grid the state lives on, or say why statistics cannot be taken.""" if self._grid is None: msg = ( "statistics need the grid the state lives on, which the kernel " f"contract does not carry; construct the backend with select(" f"{self.name!r}, problem, request, grid=grid)" ) raise BackendError(msg) return self._grid
def _refuse_inadmissible(problem: PropagationProblem, spec: StatsSpec) -> None: """Refuse a statistic this problem's basis does not define, by name. The second door of the accessor whitelist (:mod:`solprop.output.capability`), after the run loop's own admission: a caller may build a backend and ask it for statistics directly, and a general guide's static synthesis matrix is a checked **zero** placeholder, so an on-axis intensity taken from one would be zero rather than obviously wrong. """ refusal = refusal_for( declared_capability( general_modal=problem.transform.modal_tables is not None, spatial=problem.transform.geometry is not None, ), spec.names, withheld=withheld_accessors( general_modal=problem.transform.modal_tables is not None, coupled_flow=problem.linear.coupled_flow is not None, ), ) if refusal is not None: raise BackendError(refusal) refusal = axis_refusal(problem, spec.names) if refusal is not None: raise BackendError(refusal)