solprop.stats.evaluation#
Evaluate a StatsSpec on a saved plane.
collect(): every statistic a spec names, from one saved plane, through the reference definitions, the catalogue and the spatial measures ofsolprop.spatial.default_spec(): the statistics a route records unless told otherwise.WEIGHT_DEPENDENT_STATISTICS, whose values depend on the modal power weight, andweight_refusal_for(), why a general statistic cannot be formed under one.
Module Attributes
Names whose value depends on the modal power weight, so a backend evaluates it. |
Functions
|
Evaluate every statistic a spec asks for at one saved plane. |
|
Return the statistics a run of the given kind records unless told otherwise. |
|
Return why a general statistic cannot be formed under this weight, or |
- 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.mdsection 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,pressureandcore_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_spectrumandbeam_spectrumneed a Cartesian grid or a line (SEP 23), and are formed in one pass bysolprop.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 inMETRIC_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 fromsolprop.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
shapefield of itsStatDefinition.
- 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_poweramong 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 offy = 0or a region excludingkappa_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()andanalytic_flux()evaluate the identity-metric, unit-weight arithmetic, which is what the general modal route certifies before it will run (linear.power_weightis 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
Nonewhen 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