# SPDX-FileCopyrightText: 2026 John C. Travers and contributors
#
# SPDX-License-Identifier: GPL-3.0-or-later
"""The catalogue of plane statistics: one :class:`StatDefinition` per name.
- :data:`CATALOGUE`: every statistic solprop knows, keyed by name, with its shape,
unit, requirements, weighting and reference evaluator.
- The name sets derived from it, which the spec, the backends, the output capability
and the general modal route read: :data:`GENERAL_MODAL_ACCESSORS`,
:data:`WITHHELD_WITH_A_FLOW`, :data:`ACCESSOR_ADVICE`,
:data:`METRIC_WEIGHTED_STATISTICS`, :data:`PROFILE_STATISTICS`,
:data:`ON_AXIS_PLASMA_STATISTICS` and :data:`PLASMA_INTEGRATION_STATISTICS`.
"""
from collections.abc import Callable, Mapping
from dataclasses import dataclass, field
from typing import Literal
import numpy as np
from solprop.stats.definitions import (
analytic_flux,
energy,
energy_window,
fwhm_t,
fwhm_t_outer,
omega0,
peak_power,
peak_power_total,
peak_power_window,
physical_energy,
spectral_flux,
)
__all__ = [
"ACCESSOR_ADVICE",
"CATALOGUE",
"GENERAL_MODAL_ACCESSORS",
"METRIC_WEIGHTED_STATISTICS",
"ON_AXIS_PLASMA_STATISTICS",
"PLASMA_INTEGRATION_STATISTICS",
"PROFILE_STATISTICS",
"WITHHELD_WITH_A_FLOW",
"StatDefinition",
]
[docs]
@dataclass(frozen=True)
class StatDefinition:
"""What one statistic is called, what it returns and what it needs.
Attributes
----------
name : str
Key the statistic is stored under.
summary : str
One line saying what the number is, used by the manual page.
shape : str
Shape of the value in the standard axis names, ``'()'`` for a scalar.
units : str
SI units of the value.
requires : tuple
What :func:`~solprop.stats.collect` must be given for this statistic:
``'windows'``, ``'modes'``, the name of a z-profile, ``'spatial_geometry'``, the
far-field tables ``'apertures'`` and ``'regions'`` of the spec, or
``'separable_operator'``, the run's linear operator, which only a backend holds.
backend : bool
Whether only a backend can compute it. These are the statistics of quantities
the saved field does not carry -- the electron density, the ionisation rate, the
on-axis intensity, the quadrature error -- which a backend forms from its own
buffers in one pass. :func:`~solprop.stats.collect` refuses them by name rather
than pulling the state back across the seam to reconstruct them.
between_planes : bool
Whether a backend can also evaluate it *between* save planes, from what an
accepted step already leaves behind, for the periodic channel of
:attr:`~solprop.stats.StatsSpec.periodic`. What disqualifies a statistic is cost
per step, not difficulty: ``zdw`` needs a root search per mode, and paying that
on every step would cost a large share of the step; ``peak_intensity`` is in the
subset because its on-axis matrix is built once and rescaled rather than
rebuilt. :class:`~solprop.stats.StatsSpec` refuses a periodic name without it,
by name.
evaluate : collections.abc.Callable or None
The function :func:`~solprop.stats.collect` forms it with from a saved plane's
field: called ``(grid, field)``, with the spec's windows when it requires them,
or with ``metric=`` when it is metric-weighted; ``None`` for one formed
otherwise.
metric : bool
Whether its value depends on the basis's flux metric
(:data:`~solprop.stats.catalogue.METRIC_WEIGHTED_STATISTICS`).
weight : {'poynting', 'unit'} or None
How it depends on the modal power weight: ``'poynting'`` for one a backend forms
in its weighted Poynting pass, ``'unit'`` for a general modal statistic valid
only under the constant weight (:func:`~solprop.stats.weight_refusal_for`).
profile : bool
Whether it reads the z-profile of its own name
(:data:`~solprop.stats.catalogue.PROFILE_STATISTICS`).
plasma : {'on_axis', 'integration'} or None
Its family of plasma statistics
(:data:`~solprop.stats.catalogue.ON_AXIS_PLASMA_STATISTICS`,
:data:`~solprop.stats.catalogue.PLASMA_INTEGRATION_STATISTICS`).
general : {'admitted', 'no_flow', 'diagnostic', 'medium'} or None
How a general modal basis treats it: admitted, admitted unless the block couples
(:data:`~solprop.stats.catalogue.WITHHELD_WITH_A_FLOW`), a step diagnostic the
basis does not decide, refused because the guide has no gas fill or spatial
geometry, or (``None``) refused because of the basis.
advice : str or None
What to use instead on a general modal basis
(:data:`~solprop.stats.catalogue.ACCESSOR_ADVICE`).
Examples
--------
>>> from solprop.stats import CATALOGUE
>>> CATALOGUE["energy"].units, CATALOGUE["energy"].shape
('J', '(n_modes, n_pol); () for spatial beams')
>>> CATALOGUE["electron_density"].backend
True
>>> CATALOGUE["energy"].between_planes, CATALOGUE["zdw"].between_planes
(True, False)
"""
name: str
summary: str
shape: str
units: str
requires: tuple[str, ...] = ()
backend: bool = False
between_planes: bool = False
evaluate: Callable[..., np.ndarray] | None = field(
default=None, repr=False, compare=False
)
metric: bool = False
weight: Literal["poynting", "unit"] | None = None
profile: bool = False
plasma: Literal["on_axis", "integration"] | None = None
general: Literal["admitted", "no_flow", "diagnostic", "medium"] | None = None
advice: str | None = None
_DETECTOR_ADVICE = (
"analytic_flux or reconstructed E/H with an explicit detector definition"
)
"""What replaces a peak power or intensity on a general modal basis."""
def _catalogue() -> dict[str, StatDefinition]:
"""Return the fixed catalogue of statistics, keyed by name."""
entries = (
StatDefinition(
name="omega0",
summary="Centroid of the spectral energy density.",
shape="(n_modes, n_pol)",
units="rad/s",
between_planes=True,
evaluate=omega0,
metric=True,
weight="poynting",
general="admitted",
),
StatDefinition(
name="energy",
summary="Modal column energies or whole spatial beam energy.",
shape="(n_modes, n_pol); () for spatial beams",
units="J",
between_planes=True,
evaluate=energy,
weight="poynting",
advice=(
"physical_energy, which integrates the same-frequency metric product"
),
),
StatDefinition(
name="energy_window",
summary="Pulse energy inside each spectral window.",
shape="(n_windows, n_modes, n_pol)",
units="J",
requires=("windows",),
between_planes=True,
evaluate=energy_window,
weight="poynting",
advice=(
"physical_energy with an explicit band, or the reconstructed E/H of a "
"saved plane"
),
),
StatDefinition(
name="peak_power",
summary="Peak analytic Poynting power of each mode during a run.",
shape="(n_modes,)",
units="W",
between_planes=True,
evaluate=peak_power,
weight="poynting",
advice=_DETECTOR_ADVICE,
),
StatDefinition(
name="peak_power_window",
summary="Peak analytic Poynting power per mode and spectral window.",
shape="(n_windows, n_modes)",
units="W",
requires=("windows",),
between_planes=True,
evaluate=peak_power_window,
weight="poynting",
advice=_DETECTOR_ADVICE,
),
StatDefinition(
name="peak_power_total",
summary="Peak total analytic Poynting power during a run.",
shape="()",
units="W",
between_planes=True,
evaluate=peak_power_total,
weight="poynting",
advice=_DETECTOR_ADVICE,
),
StatDefinition(
name="physical_energy",
summary="Physical energy of a general modal basis, metric-weighted.",
shape="()",
units="J",
between_planes=True,
evaluate=physical_energy,
metric=True,
weight="unit",
general="admitted",
),
StatDefinition(
name="spectral_flux",
summary="Spectral density of a general modal basis's physical energy.",
shape="(n_omega,)",
units="J/(rad/s)",
evaluate=spectral_flux,
metric=True,
weight="unit",
general="admitted",
),
StatDefinition(
name="analytic_flux",
summary="Peak total analytic Poynting flux of a general modal basis.",
shape="()",
units="W",
between_planes=True,
evaluate=analytic_flux,
metric=True,
weight="unit",
general="admitted",
),
StatDefinition(
name="fwhm_t",
summary="Central half-maximum width of the total Poynting power.",
shape="()",
units="s",
between_planes=True,
evaluate=fwhm_t,
metric=True,
weight="poynting",
general="admitted",
),
StatDefinition(
name="fwhm_t_outer",
summary="Total extent of Poynting power above half its maximum.",
shape="()",
units="s",
between_planes=True,
evaluate=fwhm_t_outer,
metric=True,
weight="poynting",
general="admitted",
),
StatDefinition(
name="density",
summary="Number density of the filling gas at the plane.",
shape="()",
units="1/m^3",
requires=("density",),
between_planes=True,
profile=True,
general="medium",
),
StatDefinition(
name="pressure",
summary="Pressure of the filling gas at the plane.",
shape="()",
units="bar",
requires=("pressure",),
between_planes=True,
profile=True,
general="medium",
),
StatDefinition(
name="core_radius",
summary="Core radius of the waveguide at the plane.",
shape="()",
units="m",
requires=("core_radius",),
between_planes=True,
profile=True,
general="medium",
),
StatDefinition(
name="zdw",
summary="Zero-dispersion wavelength of each mode at the plane.",
shape="(n_modes,)",
units="m",
requires=("modes",),
general="no_flow",
),
StatDefinition(
name="species_ionisation",
summary="Final ionised fraction of each species at every node.",
shape="(n_species, n_nodes)",
units="1",
backend=True,
between_planes=True,
general="medium",
),
StatDefinition(
name="species_electron_density",
summary="Species electron densities at the densest total-electron node.",
shape="(n_species,)",
units="1/m^3",
backend=True,
between_planes=True,
general="medium",
),
StatDefinition(
name="species_peak_ionisation_rate",
summary="Species peak rate over all nodes; cycle-averaged for envelopes.",
shape="(n_species,)",
units="1/s",
backend=True,
between_planes=False,
general="medium",
),
StatDefinition(
name="species_density",
summary="Component number densities at this plane.",
shape="(n_species,)",
units="1/m^3",
backend=True,
between_planes=False,
general="medium",
),
StatDefinition(
name="species_ionisation_energy",
summary="Final ionised inventory energy per propagation length.",
shape="(n_species,)",
units="J/m",
backend=True,
between_planes=False,
general="medium",
),
StatDefinition(
name="electron_density",
summary="Free-electron density left behind by the pulse.",
shape="()",
units="1/m^3",
backend=True,
between_planes=True,
general="medium",
),
StatDefinition(
name="peak_ionisation_rate",
summary="Peak ionisation rate; cycle-averaged for envelopes.",
shape="()",
units="1/s",
backend=True,
between_planes=True,
general="medium",
),
StatDefinition(
name="on_axis_electron_density",
summary="Free-electron density left behind on the axis.",
shape="()",
units="1/m^3",
backend=True,
between_planes=False,
plasma="on_axis",
),
StatDefinition(
name="on_axis_peak_ionisation_rate",
summary="Peak rate on the axis; cycle-averaged for envelopes.",
shape="()",
units="1/s",
backend=True,
between_planes=False,
plasma="on_axis",
),
StatDefinition(
name="on_axis_species_electron_density",
summary="Each species' electron density left behind on the axis.",
shape="(n_species,)",
units="1/m^3",
backend=True,
between_planes=False,
plasma="on_axis",
),
StatDefinition(
name="on_axis_species_peak_ionisation_rate",
summary="Species peak rate on the axis; cycle-averaged for envelopes.",
shape="(n_species,)",
units="1/s",
backend=True,
between_planes=False,
plasma="on_axis",
),
StatDefinition(
name="plasma_undershoot",
summary="Largest exposure undershoot of the plasma column's band integral.",
shape="()",
units="1",
backend=True,
between_planes=False,
plasma="integration",
general="medium",
),
StatDefinition(
name="plasma_work_defect",
summary="Loss-current work against the ionisation it paid, relative.",
shape="()",
units="1",
backend=True,
between_planes=False,
plasma="integration",
general="medium",
),
StatDefinition(
name="plasma_boundary_level",
summary="Free-current integrand at the window start, relative to its peak.",
shape="()",
units="1",
backend=True,
between_planes=False,
plasma="integration",
general="medium",
),
StatDefinition(
name="peak_intensity",
summary="Spatial vacuum intensity; modal on-axis analytic Poynting flux.",
shape="()",
units="W/m^2",
backend=True,
between_planes=True,
weight="poynting",
advice=_DETECTOR_ADVICE,
),
StatDefinition(
name="fwhm_r",
summary="Central fluence FWHM; NaN if undefined.",
shape="()",
units="m",
requires=("spatial_geometry",),
general="medium",
),
StatDefinition(
name="on_axis_intensity",
summary="Largest intensity in time on the spatial beam axis.",
shape="()",
units="W/m^2",
requires=("spatial_geometry",),
between_planes=True,
general="medium",
),
StatDefinition(
name="on_axis_spectrum",
summary="On-axis spectral fluence density summed over polarisation.",
shape="(n_omega,)",
units="J s/m^2",
requires=("spatial_geometry",),
general="medium",
),
StatDefinition(
name="beam_radius",
summary="Fluence second-moment and 1/e^2 radii; NaN if undefined.",
shape="(2,)",
units="m",
requires=("spatial_geometry",),
general="medium",
),
StatDefinition(
name="aperture_spectrum",
summary="Spectrum collected through each far-field aperture.",
shape="(n_apertures, n_omega)",
units="J/(rad/s)",
requires=("apertures", "spatial_geometry"),
general="medium",
),
StatDefinition(
name="aperture_on_axis_spectrum",
summary="On-axis spectral fluence behind each aperture in a Fourier plane.",
shape="(n_apertures, n_omega)",
units="J s/m^2",
requires=("apertures", "spatial_geometry"),
general="medium",
),
StatDefinition(
name="region_spectrum",
summary="Spectrum in each box of transverse wavevector.",
shape="(n_regions, n_omega)",
units="J/(rad/s)",
requires=("regions", "spatial_geometry"),
general="medium",
),
StatDefinition(
name="beam_spectrum",
summary="Whole-beam spectral energy density.",
shape="(n_omega,)",
units="J/(rad/s)",
requires=("spatial_geometry",),
general="medium",
),
StatDefinition(
name="absorbed_power",
summary="Energy per metre each absorbing channel of the operator removes.",
shape="(5,)",
units="J/m",
requires=("spatial_geometry", "separable_operator"),
backend=True,
between_planes=True,
general="medium",
),
StatDefinition(
name="quadrature_error",
summary="Relative error of the transverse quadrature on the polarisation.",
shape="()",
units="1",
backend=True,
between_planes=True,
general="diagnostic",
),
)
return {entry.name: entry for entry in entries}
CATALOGUE: Mapping[str, StatDefinition] = _catalogue()
"""Every statistic solprop knows about, keyed by name."""
GENERAL_MODAL_ACCESSORS: frozenset[str] = frozenset(
name
for name, entry in CATALOGUE.items()
if entry.general in ("admitted", "no_flow")
) | frozenset(
# Processing accessors of the general basis (solprop.processing.modal).
(
"reconstructed_flux",
"channel_labels",
"coordinate_intensity",
"instantaneous_flux",
"electric_field",
"magnetic_field",
"plane_nodes",
)
)
"""Every accessor a three-component general modal basis admits, by name.
The sets live here, beside the catalogue whose names they select from, and
:mod:`solprop.output.capability` imports them to build the gate: they are a statement
about statistics, and keeping them here is what lets
:mod:`solprop.translate.general` record the list a file publishes without a
translation module importing an output one.
``omega0``, ``fwhm_t`` and ``fwhm_t_outer`` are functionals of the same-frequency flux
``a.H W a`` and take the basis metric
(:data:`solprop.stats.catalogue.METRIC_WEIGHTED_STATISTICS`), so they are exact on a
declared basis as well as on the identity one; ``zdw`` is a property of the channels'
propagation constants and of no basis at all -- until a declared basis couples channels
whose propagation constants differ, when the block executes through a coupled flow and
each channel's constant is the block's mean; the route then withholds it
(:data:`WITHHELD_WITH_A_FLOW`).
``spectral_flux`` is the one array of the family -- the same flux as a density in
frequency rather than integrated. It
is **admitted but not a default** of the route: it is ``n_omega`` wide per plane where
the other five are scalars (``omega0`` one per channel), so a run asks for it by name.
Two names of :mod:`solprop.processing.modal` are deliberately absent.
``quadrature_error`` is refused separately, by the driver, because what disqualifies
it is the absent embedded coarse rule and not the basis -- a general guide's node rule
has no embedded pair to difference, so such a run has no transverse-resolution alarm,
which is a known limitation -- and it sits
inside the run's resume key, so publishing it here would promise a statistic the
same record refuses. ``channel_amplitudes`` takes two arrays and a table rather than
an opened handler, so no door ever asks the gate about it; it is in
``solprop.output.capability._GENERAL_ONLY`` all the same, so that the one
direction that could be reached -- an ordinary run asked for it -- would be refused
for the right reason.
"""
WITHHELD_WITH_A_FLOW: frozenset[str] = frozenset(
name for name, entry in CATALOGUE.items() if entry.general == "no_flow"
)
"""The general-basis accessors a route withholds when its block couples, by name.
A declared change of basis over channels whose propagation constants differ executes
through ``linear.coupled_flow``, and the per-channel propagation constant the
statistics would read is then the block's mean: ``zdw`` from it is a number that
propagates nothing. The route leaves these names out of the record's published list and
every accessor door refuses them with :func:`solprop.output.capability.refusal_for`'s
``withheld``.
"""
ACCESSOR_ADVICE: Mapping[str, str] = {
name: entry.advice for name, entry in CATALOGUE.items() if entry.advice is not None
}
"""What to use instead of each per-channel name on a general modal basis.
A name with no entry here gets the generic advice of
:mod:`solprop.output.capability`: a general modal basis has ``physical_energy``,
``analytic_flux`` and the reconstruction accessors, and nothing else of that family.
"""
_GAS_OR_SPATIAL_NAMES: frozenset[str] = frozenset(
name for name, entry in CATALOGUE.items() if entry.general == "medium"
)
"""Names a general modal guide fails for a reason that is not its basis at all.
A plasma density, a gas pressure and a beam radius are unavailable because this guide
has no gas fill and no spatial geometry, not because its coordinate powers do not add
up; advising a reader to use ``analytic_flux`` instead of ``electron_density`` would
be nonsense. The gate names that reason instead.
"""
_STEP_DIAGNOSTICS: frozenset[str] = frozenset(
name for name, entry in CATALOGUE.items() if entry.general == "diagnostic"
)
"""Diagnostics of the step, which are the same quantity in any basis.
Basis-independent step diagnostics are admitted on a general basis, so the gate never
refuses one: whoever owns the real reason refuses it
instead. ``quadrature_error`` is refused on a general guide by the run loop, because a
provider's node rule carries no embedded coarse rule to difference --
a statement about the rule, not about the basis -- and it is deliberately not in
:data:`GENERAL_MODAL_ACCESSORS`, so no run record publishes as admitted a name the
same record's run refuses.
"""
METRIC_WEIGHTED_STATISTICS: frozenset[str] = frozenset(
name for name, entry in CATALOGUE.items() if entry.metric
)
"""Statistics whose value depends on the basis's flux metric, by name.
These are the functionals of the physical same-frequency flux
``sum_mn conj(a_m) W_mn a_n`` -- its integral (``physical_energy``), its density in
frequency (``spectral_flux``), its peak (``analytic_flux``), its two widths
(``fwhm_t``, ``fwhm_t_outer``) and the spectral centroid of its per-channel share
(``omega0``). On an orthonormal basis ``W`` is the identity and they are the unweighted
quantities they have always been, bit for bit; on a general modal basis whose Gram is
not the identity they are wrong without it, so a caller that has a metric must hand it
over (:func:`~solprop.stats.collect`) and one that cannot must refuse rather than
answer (:mod:`solprop.processing.modal`).
``zdw`` is deliberately absent: it is a property of the channels' propagation
constants and of no basis at all, and a unitary change of basis of an exactly
degenerate block leaves every one of them unchanged.
"""
PROFILE_STATISTICS: tuple[str, ...] = tuple(
name for name, entry in CATALOGUE.items() if entry.profile
)
"""Statistics that read a :class:`solprop.profiles.ZProfile` at the plane's position."""
ON_AXIS_PLASMA_STATISTICS: tuple[str, ...] = tuple(
name for name, entry in CATALOGUE.items() if entry.plasma == "on_axis"
)
"""The plasma statistics evaluated on the waveguide's axis (SEP 19, section 5.2).
Opt-in and saved-plane only. The axis field is synthesised from the mode profiles, as
for ``peak_intensity``, and its populations are scanned with exactly the rate tables,
preionisation, densities and running-integral rule of the node scan, once per
observation; a rule with a node on the axis supplies that row instead. They sit beside
the unchanged node reductions -- ``electron_density`` is the densest node's -- because a
few-node field-scale rule may have no node near the axis, and a multimode field's
largest density need not lie on it. Defined on resolved modal routes; the spatial
routes, general modal guides, the mode-averaged route and TDSE refuse them by name.
"""
PLASMA_INTEGRATION_STATISTICS: tuple[str, ...] = tuple(
name for name, entry in CATALOGUE.items() if entry.plasma == "integration"
)
"""The field plasma column's run-time integration diagnostics (SEP 18, section 4.5).
Evaluated with the other plasma statistics at each save plane. Each is a ratio of two
maxima over every sample, node and population, so that a node the field barely
ionises cannot set it: the undershoot ``max(-dS) / max(dS)`` of the exposure
increments; the work defect ``max |paid - freed| / max freed``, the loss current's work
per ionisation potential against the fraction it freed; and the boundary level, the
free-current integrand's largest magnitude in the ``2K`` samples the filter reads past
the window's start against its largest anywhere.
"""