solprop.stats.catalogue#
The catalogue of plane statistics: one StatDefinition per name.
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:
GENERAL_MODAL_ACCESSORS,WITHHELD_WITH_A_FLOW,ACCESSOR_ADVICE,METRIC_WEIGHTED_STATISTICS,PROFILE_STATISTICS,ON_AXIS_PLASMA_STATISTICSandPLASMA_INTEGRATION_STATISTICS.
Module Attributes
Every statistic solprop knows about, keyed by name. |
|
Every accessor a three-component general modal basis admits, by name. |
|
The general-basis accessors a route withholds when its block couples, by name. |
|
What to use instead of each per-channel name on a general modal basis. |
|
Statistics whose value depends on the basis's flux metric, by name. |
|
Statistics that read a |
|
The plasma statistics evaluated on the waveguide's axis (SEP 19, section 5.2). |
|
The field plasma column's run-time integration diagnostics (SEP 18, section 4.5). |
- solprop.stats.catalogue.ACCESSOR_ADVICE: Mapping[str, str] = {'energy': 'physical_energy, which integrates the same-frequency metric product', 'energy_window': 'physical_energy with an explicit band, or the reconstructed E/H of a saved plane', 'peak_intensity': 'analytic_flux or reconstructed E/H with an explicit detector definition', 'peak_power': 'analytic_flux or reconstructed E/H with an explicit detector definition', 'peak_power_total': 'analytic_flux or reconstructed E/H with an explicit detector definition', 'peak_power_window': 'analytic_flux or reconstructed E/H with an explicit detector definition'}#
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
solprop.output.capability: a general modal basis hasphysical_energy,analytic_fluxand the reconstruction accessors, and nothing else of that family.
- solprop.stats.catalogue.CATALOGUE: Mapping[str, StatDefinition] = {'absorbed_power': 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, metric=False, weight=None, profile=False, plasma=None, general='medium', advice=None), 'analytic_flux': StatDefinition(name='analytic_flux', summary='Peak total analytic Poynting flux of a general modal basis.', shape='()', units='W', requires=(), backend=False, between_planes=True, metric=True, weight='unit', profile=False, plasma=None, general='admitted', advice=None), 'aperture_on_axis_spectrum': 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'), backend=False, between_planes=False, metric=False, weight=None, profile=False, plasma=None, general='medium', advice=None), 'aperture_spectrum': 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'), backend=False, between_planes=False, metric=False, weight=None, profile=False, plasma=None, general='medium', advice=None), 'beam_radius': StatDefinition(name='beam_radius', summary='Fluence second-moment and 1/e^2 radii; NaN if undefined.', shape='(2,)', units='m', requires=('spatial_geometry',), backend=False, between_planes=False, metric=False, weight=None, profile=False, plasma=None, general='medium', advice=None), 'beam_spectrum': StatDefinition(name='beam_spectrum', summary='Whole-beam spectral energy density.', shape='(n_omega,)', units='J/(rad/s)', requires=('spatial_geometry',), backend=False, between_planes=False, metric=False, weight=None, profile=False, plasma=None, general='medium', advice=None), 'core_radius': StatDefinition(name='core_radius', summary='Core radius of the waveguide at the plane.', shape='()', units='m', requires=('core_radius',), backend=False, between_planes=True, metric=False, weight=None, profile=True, plasma=None, general='medium', advice=None), 'density': StatDefinition(name='density', summary='Number density of the filling gas at the plane.', shape='()', units='1/m^3', requires=('density',), backend=False, between_planes=True, metric=False, weight=None, profile=True, plasma=None, general='medium', advice=None), 'electron_density': StatDefinition(name='electron_density', summary='Free-electron density left behind by the pulse.', shape='()', units='1/m^3', requires=(), backend=True, between_planes=True, metric=False, weight=None, profile=False, plasma=None, general='medium', advice=None), 'energy': StatDefinition(name='energy', summary='Modal column energies or whole spatial beam energy.', shape='(n_modes, n_pol); () for spatial beams', units='J', requires=(), backend=False, between_planes=True, metric=False, weight='poynting', profile=False, plasma=None, general=None, advice='physical_energy, which integrates the same-frequency metric product'), 'energy_window': StatDefinition(name='energy_window', summary='Pulse energy inside each spectral window.', shape='(n_windows, n_modes, n_pol)', units='J', requires=('windows',), backend=False, between_planes=True, metric=False, weight='poynting', profile=False, plasma=None, general=None, advice='physical_energy with an explicit band, or the reconstructed E/H of a saved plane'), 'fwhm_r': StatDefinition(name='fwhm_r', summary='Central fluence FWHM; NaN if undefined.', shape='()', units='m', requires=('spatial_geometry',), backend=False, between_planes=False, metric=False, weight=None, profile=False, plasma=None, general='medium', advice=None), 'fwhm_t': StatDefinition(name='fwhm_t', summary='Central half-maximum width of the total Poynting power.', shape='()', units='s', requires=(), backend=False, between_planes=True, metric=True, weight='poynting', profile=False, plasma=None, general='admitted', advice=None), 'fwhm_t_outer': StatDefinition(name='fwhm_t_outer', summary='Total extent of Poynting power above half its maximum.', shape='()', units='s', requires=(), backend=False, between_planes=True, metric=True, weight='poynting', profile=False, plasma=None, general='admitted', advice=None), 'omega0': StatDefinition(name='omega0', summary='Centroid of the spectral energy density.', shape='(n_modes, n_pol)', units='rad/s', requires=(), backend=False, between_planes=True, metric=True, weight='poynting', profile=False, plasma=None, general='admitted', advice=None), 'on_axis_electron_density': StatDefinition(name='on_axis_electron_density', summary='Free-electron density left behind on the axis.', shape='()', units='1/m^3', requires=(), backend=True, between_planes=False, metric=False, weight=None, profile=False, plasma='on_axis', general=None, advice=None), 'on_axis_intensity': StatDefinition(name='on_axis_intensity', summary='Largest intensity in time on the spatial beam axis.', shape='()', units='W/m^2', requires=('spatial_geometry',), backend=False, between_planes=True, metric=False, weight=None, profile=False, plasma=None, general='medium', advice=None), 'on_axis_peak_ionisation_rate': StatDefinition(name='on_axis_peak_ionisation_rate', summary='Peak rate on the axis; cycle-averaged for envelopes.', shape='()', units='1/s', requires=(), backend=True, between_planes=False, metric=False, weight=None, profile=False, plasma='on_axis', general=None, advice=None), 'on_axis_species_electron_density': StatDefinition(name='on_axis_species_electron_density', summary="Each species' electron density left behind on the axis.", shape='(n_species,)', units='1/m^3', requires=(), backend=True, between_planes=False, metric=False, weight=None, profile=False, plasma='on_axis', general=None, advice=None), 'on_axis_species_peak_ionisation_rate': 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', requires=(), backend=True, between_planes=False, metric=False, weight=None, profile=False, plasma='on_axis', general=None, advice=None), 'on_axis_spectrum': 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',), backend=False, between_planes=False, metric=False, weight=None, profile=False, plasma=None, general='medium', advice=None), 'peak_intensity': StatDefinition(name='peak_intensity', summary='Spatial vacuum intensity; modal on-axis analytic Poynting flux.', shape='()', units='W/m^2', requires=(), backend=True, between_planes=True, metric=False, weight='poynting', profile=False, plasma=None, general=None, advice='analytic_flux or reconstructed E/H with an explicit detector definition'), 'peak_ionisation_rate': StatDefinition(name='peak_ionisation_rate', summary='Peak ionisation rate; cycle-averaged for envelopes.', shape='()', units='1/s', requires=(), backend=True, between_planes=True, metric=False, weight=None, profile=False, plasma=None, general='medium', advice=None), 'peak_power': StatDefinition(name='peak_power', summary='Peak analytic Poynting power of each mode during a run.', shape='(n_modes,)', units='W', requires=(), backend=False, between_planes=True, metric=False, weight='poynting', profile=False, plasma=None, general=None, advice='analytic_flux or reconstructed E/H with an explicit detector definition'), 'peak_power_total': StatDefinition(name='peak_power_total', summary='Peak total analytic Poynting power during a run.', shape='()', units='W', requires=(), backend=False, between_planes=True, metric=False, weight='poynting', profile=False, plasma=None, general=None, advice='analytic_flux or reconstructed E/H with an explicit detector definition'), 'peak_power_window': StatDefinition(name='peak_power_window', summary='Peak analytic Poynting power per mode and spectral window.', shape='(n_windows, n_modes)', units='W', requires=('windows',), backend=False, between_planes=True, metric=False, weight='poynting', profile=False, plasma=None, general=None, advice='analytic_flux or reconstructed E/H with an explicit detector definition'), 'physical_energy': StatDefinition(name='physical_energy', summary='Physical energy of a general modal basis, metric-weighted.', shape='()', units='J', requires=(), backend=False, between_planes=True, metric=True, weight='unit', profile=False, plasma=None, general='admitted', advice=None), 'plasma_boundary_level': StatDefinition(name='plasma_boundary_level', summary='Free-current integrand at the window start, relative to its peak.', shape='()', units='1', requires=(), backend=True, between_planes=False, metric=False, weight=None, profile=False, plasma='integration', general='medium', advice=None), 'plasma_undershoot': StatDefinition(name='plasma_undershoot', summary="Largest exposure undershoot of the plasma column's band integral.", shape='()', units='1', requires=(), backend=True, between_planes=False, metric=False, weight=None, profile=False, plasma='integration', general='medium', advice=None), 'plasma_work_defect': StatDefinition(name='plasma_work_defect', summary='Loss-current work against the ionisation it paid, relative.', shape='()', units='1', requires=(), backend=True, between_planes=False, metric=False, weight=None, profile=False, plasma='integration', general='medium', advice=None), 'pressure': StatDefinition(name='pressure', summary='Pressure of the filling gas at the plane.', shape='()', units='bar', requires=('pressure',), backend=False, between_planes=True, metric=False, weight=None, profile=True, plasma=None, general='medium', advice=None), 'quadrature_error': StatDefinition(name='quadrature_error', summary='Relative error of the transverse quadrature on the polarisation.', shape='()', units='1', requires=(), backend=True, between_planes=True, metric=False, weight=None, profile=False, plasma=None, general='diagnostic', advice=None), 'region_spectrum': 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'), backend=False, between_planes=False, metric=False, weight=None, profile=False, plasma=None, general='medium', advice=None), 'species_density': StatDefinition(name='species_density', summary='Component number densities at this plane.', shape='(n_species,)', units='1/m^3', requires=(), backend=True, between_planes=False, metric=False, weight=None, profile=False, plasma=None, general='medium', advice=None), 'species_electron_density': StatDefinition(name='species_electron_density', summary='Species electron densities at the densest total-electron node.', shape='(n_species,)', units='1/m^3', requires=(), backend=True, between_planes=True, metric=False, weight=None, profile=False, plasma=None, general='medium', advice=None), 'species_ionisation': StatDefinition(name='species_ionisation', summary='Final ionised fraction of each species at every node.', shape='(n_species, n_nodes)', units='1', requires=(), backend=True, between_planes=True, metric=False, weight=None, profile=False, plasma=None, general='medium', advice=None), 'species_ionisation_energy': StatDefinition(name='species_ionisation_energy', summary='Final ionised inventory energy per propagation length.', shape='(n_species,)', units='J/m', requires=(), backend=True, between_planes=False, metric=False, weight=None, profile=False, plasma=None, general='medium', advice=None), 'species_peak_ionisation_rate': StatDefinition(name='species_peak_ionisation_rate', summary='Species peak rate over all nodes; cycle-averaged for envelopes.', shape='(n_species,)', units='1/s', requires=(), backend=True, between_planes=False, metric=False, weight=None, profile=False, plasma=None, general='medium', advice=None), 'spectral_flux': StatDefinition(name='spectral_flux', summary="Spectral density of a general modal basis's physical energy.", shape='(n_omega,)', units='J/(rad/s)', requires=(), backend=False, between_planes=False, metric=True, weight='unit', profile=False, plasma=None, general='admitted', advice=None), 'zdw': StatDefinition(name='zdw', summary='Zero-dispersion wavelength of each mode at the plane.', shape='(n_modes,)', units='m', requires=('modes',), backend=False, between_planes=False, metric=False, weight=None, profile=False, plasma=None, general='no_flow', advice=None)}#
Every statistic solprop knows about, keyed by name.
- solprop.stats.catalogue.GENERAL_MODAL_ACCESSORS: frozenset[str] = frozenset({'analytic_flux', 'channel_labels', 'coordinate_intensity', 'electric_field', 'fwhm_t', 'fwhm_t_outer', 'instantaneous_flux', 'magnetic_field', 'omega0', 'physical_energy', 'plane_nodes', 'reconstructed_flux', 'spectral_flux', 'zdw'})#
Every accessor a three-component general modal basis admits, by name.
The sets live here, beside the catalogue whose names they select from, and
solprop.output.capabilityimports them to build the gate: they are a statement about statistics, and keeping them here is what letssolprop.translate.generalrecord the list a file publishes without a translation module importing an output one.omega0,fwhm_tandfwhm_t_outerare functionals of the same-frequency fluxa.H W aand take the basis metric (solprop.stats.catalogue.METRIC_WEIGHTED_STATISTICS), so they are exact on a declared basis as well as on the identity one;zdwis 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 (WITHHELD_WITH_A_FLOW).spectral_fluxis 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 isn_omegawide per plane where the other five are scalars (omega0one per channel), so a run asks for it by name.Two names of
solprop.processing.modalare deliberately absent.quadrature_erroris 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_amplitudestakes two arrays and a table rather than an opened handler, so no door ever asks the gate about it; it is insolprop.output.capability._GENERAL_ONLYall the same, so that the one direction that could be reached – an ordinary run asked for it – would be refused for the right reason.
- solprop.stats.catalogue.METRIC_WEIGHTED_STATISTICS: frozenset[str] = frozenset({'analytic_flux', 'fwhm_t', 'fwhm_t_outer', 'omega0', 'physical_energy', 'spectral_flux'})#
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 basisWis 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 (collect()) and one that cannot must refuse rather than answer (solprop.processing.modal).zdwis 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.
- solprop.stats.catalogue.ON_AXIS_PLASMA_STATISTICS: tuple[str, ...] = ('on_axis_electron_density', 'on_axis_peak_ionisation_rate', 'on_axis_species_electron_density', 'on_axis_species_peak_ionisation_rate')#
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_densityis 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.
- solprop.stats.catalogue.PLASMA_INTEGRATION_STATISTICS: tuple[str, ...] = ('plasma_undershoot', 'plasma_work_defect', 'plasma_boundary_level')#
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 defectmax |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 the2Ksamples the filter reads past the window’s start against its largest anywhere.
- solprop.stats.catalogue.PROFILE_STATISTICS: tuple[str, ...] = ('density', 'pressure', 'core_radius')#
Statistics that read a
solprop.profiles.ZProfileat the plane’s position.
- class solprop.stats.catalogue.StatDefinition(name, summary, shape, units, requires=(), backend=False, between_planes=False, evaluate=None, metric=False, weight=None, profile=False, plasma=None, general=None, advice=None)[source]#
Bases:
objectWhat one statistic is called, what it returns and what it needs.
- Attributes:
- namestr
Key the statistic is stored under.
- summarystr
One line saying what the number is, used by the manual page.
- shapestr
Shape of the value in the standard axis names,
'()'for a scalar.- unitsstr
SI units of the value.
- requirestuple
What
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.- backendbool
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.
collect()refuses them by name rather than pulling the state back across the seam to reconstruct them.- between_planesbool
Whether a backend can also evaluate it between save planes, from what an accepted step already leaves behind, for the periodic channel of
periodic. What disqualifies a statistic is cost per step, not difficulty:zdwneeds a root search per mode, and paying that on every step would cost a large share of the step;peak_intensityis in the subset because its on-axis matrix is built once and rescaled rather than rebuilt.StatsSpecrefuses a periodic name without it, by name.- evaluatecollections.abc.Callable or None
The function
collect()forms it with from a saved plane’s field: called(grid, field), with the spec’s windows when it requires them, or withmetric=when it is metric-weighted;Nonefor one formed otherwise.- metricbool
Whether its value depends on the basis’s flux metric (
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 (weight_refusal_for()).- profilebool
Whether it reads the z-profile of its own name (
PROFILE_STATISTICS).- plasma{‘on_axis’, ‘integration’} or None
Its family of plasma statistics (
ON_AXIS_PLASMA_STATISTICS,PLASMA_INTEGRATION_STATISTICS).- general{‘admitted’, ‘no_flow’, ‘diagnostic’, ‘medium’} or None
How a general modal basis treats it: admitted, admitted unless the block couples (
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.- advicestr or None
What to use instead on a general modal basis (
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)
- solprop.stats.catalogue.WITHHELD_WITH_A_FLOW: frozenset[str] = frozenset({'zdw'})#
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:zdwfrom 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 withsolprop.output.capability.refusal_for()’swithheld.