solprop.stats.evaluation#

Evaluate a StatsSpec on a saved plane.

Module Attributes

WEIGHT_DEPENDENT_STATISTICS

Names whose value depends on the modal power weight, so a backend evaluates it.

Functions

collect(spec, grid, plane, *[, modes, ...])

Evaluate every statistic a spec asks for at one saved plane.

default_spec(kind, *[, with_profiles, with_zdw])

Return the statistics a run of the given kind records unless told otherwise.

weight_refusal_for(names, weight)

Return why a general statistic cannot be formed under this weight, or None.

solprop.stats.evaluation.WEIGHT_DEPENDENT_STATISTICS = frozenset({'analytic_flux', 'energy', 'energy_window', 'fwhm_t', 'fwhm_t_outer', 'omega0', 'peak_intensity', 'peak_power', 'peak_power_total', 'peak_power_window', 'physical_energy', 'spectral_flux'})#

Names whose value depends on the modal power weight, so a backend evaluates it.

solprop.stats.evaluation.collect(spec, grid, plane, *, modes=None, profiles=None, flux=None, metric=None)[source]#

Evaluate every statistic a spec asks for at one saved plane.

Each statistic uses its named public array function and deterministic reductions. For saved true-power modal amplitudes, temporal array functions use |b(t)|². Backend run statistics use analytic Poynting flux: their time integrals agree, but broadband peaks and widths can differ (docs/dev/conventions.md section 4).

Parameters:
specStatsSpec

Which statistics to evaluate, and the windows they need.

gridsolprop.grid.TimeGrid

The grid the plane’s field lives on.

planesolprop.output.records.SavedPlane

The plane, whose field is in the internal FFT convention.

modescollections.abc.Sequence, optional

The propagated modes, in state order. Needed by zdw.

profilescollections.abc.Mapping, optional

The z-profiles, keyed by statistic name. Needed by density, pressure and core_radius.

fluxsolprop.spatial.SpatialFlux or None, optional

The plane’s measure for a radial or Cartesian spectrum, resolved at the plane’s own position (and jump side) in its medium: every spatial statistic is that medium’s axial Poynting flux (SEP 34), and widths use the signed time-integrated fluence. The far-field statistics aperture_spectrum, aperture_on_axis_spectrum, region_spectrum and beam_spectrum need a Cartesian grid or a line (SEP 23), and are formed in one pass by solprop.spatial.aperture_statistics(), the function a run uses.

metricnumpy.ndarray or None, optional

The basis flux metric W(omega) at this plane, shape (n_modes, n_modes, n_omega), for the names in METRIC_WEIGHTED_STATISTICS; None, the default, is the identity and every statistic is then bitwise what it was. A caller that holds a general modal problem gets it from solprop.translate.coupled.metric_at().

Returns:
dict

The value of each requested statistic, keyed by name, always as a NumPy array and zero-dimensional for a scalar. The shape of each is the shape field of its StatDefinition.

Raises:
OutputError

If a statistic’s dependency is missing – no windows for a windowed statistic, no modes for zdw, or no profile for a profile statistic – or if it is one a backend owns, which this function cannot form from a saved plane (absorbed_power among them, refused by name because a plane does not carry the linear operator’s rates); if a far-field statistic is asked of a radial grid, or of a line with an aperture off y = 0 or a region excluding kappa_y = 0; or if the plane kept no field (SEP 22).

Examples

>>> import numpy as np
>>> from solprop.grid import EnvelopeGrid
>>> from solprop.output.records import SavedPlane
>>> from solprop.pulses import GaussianPulse
>>> from solprop.stats import collect, default_spec
>>> grid = EnvelopeGrid.from_limits(1.0, 800e-9, (400e-9, 2e-6), 1e-12)
>>> built = GaussianPulse(wavelength=800e-9, fwhm=30e-15, energy=1e-6).build(grid)
>>> plane = SavedPlane(z=0.0, field=built)
>>> values = collect(default_spec("mode_averaged"), grid, plane)
>>> sorted(values)
['energy', 'fwhm_t', 'fwhm_t_outer', 'omega0', 'peak_power']
>>> values["energy"].shape, values["fwhm_t"].shape
((1, 1), ())
solprop.stats.evaluation.default_spec(kind, *, with_profiles=False, with_zdw=False)[source]#

Return the statistics a run of the given kind records unless told otherwise.

The field statistics every run wants, plus – for a multimode run, where the modes peak at different positions in time – the peak of the total power. The z-profile statistics and the zero-dispersion wavelength are opt-in: the first needs profiles the driver may not have, and the second is a root search per mode per plane.

Parameters:
kind{‘mode_averaged’, ‘multimode’, ‘radial’, ‘free’}

Which transform the run uses.

with_profilesbool, optional

Whether to record the gas density, the pressure and the core radius for modal runs, or only the gas density for spatial runs.

with_zdwbool, optional

Whether to record the zero-dispersion wavelength of each mode. Spatial runs reject this option because they carry no modal dispersion.

Returns:
StatsSpec

The spec, with no energy windows; add those for the run’s bands of interest.

Examples

>>> from solprop.stats import default_spec
>>> default_spec("mode_averaged").names
('omega0', 'energy', 'peak_power', 'fwhm_t', 'fwhm_t_outer')
>>> "peak_power_total" in default_spec("multimode").names
True
solprop.stats.evaluation.weight_refusal_for(names, weight)[source]#

Return why a general statistic cannot be formed under this weight, or None.

physical_energy(), spectral_flux() and analytic_flux() evaluate the identity-metric, unit-weight arithmetic, which is what the general modal route certifies before it will run (linear.power_weight is the constant one there). This is unreachable today: no route carries both a modal table and a non-constant weight, and the translation layer refuses to build one. It is written because the failure would be silent rather than loud if a later change loosened either side – the three names are outside the set a backend routes through the weighted Poynting pass, so they would be answered from the unweighted field.

Parameters:
namescollections.abc.Sequence

The statistic names asked for.

weightnumpy.ndarray

The modal power weight at this plane, shape (n_modes, n_pol, n_omega).

Returns:
str or None

The refusal, or None when no general statistic is asked for or the weight is the constant one.

Examples

>>> import numpy as np
>>> from solprop.stats import weight_refusal_for
>>> weight_refusal_for(["physical_energy"], np.ones((1, 1, 4))) is None
True
>>> weight_refusal_for(["energy"], np.full((1, 1, 4), 2.0)) is None
True