solprop.output.capability#

What a stored basis admits: the accessor gate of the run record.

A run’s record names the capability of its mode axis (BasisCapability: an ordinary orthogonal modal basis, a general modal guide, or a spatial beam), and every accessor that capability does not admit is refused by name rather than redefined.

The four doors the gate is applied at, and what each capability admits, are in docs/guide/results/statistics.md (“Which names a basis admits”).

Module Attributes

BasisCapability

Which kind of basis a run's mode axis is, and so which accessors it admits.

CAPABILITIES

Every declared basis capability, in the order the manual lists them.

ACCESSOR_WHITELIST

Which statistics and accessors each capability admits.

COLUMN_READINGS

The readers that take each column of a file's mode axis for a modal amplitude.

QuantityKind

Whether a derived quantity is a physical flux, or a quantity of the coordinates.

Functions

capability_of(metadata)

Return the capability a stored record declares.

compression_refusal(basis)

Return why the compressors refuse a basis, or None when they admit it.

declared_capability(*, general_modal, spatial)

Return the capability a translated problem declares.

quantities(metadata, basis)

Return what each derived quantity of a stored record is on its basis.

reading_refusal(metadata, name, *[, recorded])

Return why a reader of a stored record refuses it, or None.

refusal_for(capability, names, *[, withheld])

Return why the first inadmissible accessor is inadmissible, or None.

spatial_field_unit(metadata)

Return the unit of a spatial record's stored field.

withheld_accessors(*, general_modal, ...)

Return the names a problem withholds beyond its basis's whitelist.

withheld_from(metadata)

Return the names a stored record withholds beyond its basis's whitelist.

Classes

Quantity(kind, unit)

What a derived quantity of a file is.

solprop.output.capability.ACCESSOR_WHITELIST: Mapping[Literal['modal', 'general_modal', 'spatial'], frozenset[str] | None] = {'general_modal': 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'}), 'modal': None, 'spatial': None}#

Which statistics and accessors each capability admits.

None means “every name this run has always had, and no general one”.

An orthogonal modal run and a spatial run keep every statistic they have always had – this table never narrows an existing route’s statistics – and refuse the ten names of _GENERAL_ONLY, which need a certified flux metric and a stored E/H reference they do not carry. A general modal run admits exactly its own list, plus the basis-independent step diagnostics section 6 allows.

The table is read at every door, so it speaks of statistic names, and on a spatial run those are the physical flux the run recorded. What it does not cover is the processing readers that take each column of a file’s mode axis for a modal amplitude: on a spatial file those are refused at the processing door by COLUMN_READINGS, not here, because energy the statistic is admitted where energy the reader of the stored columns is not.

solprop.output.capability.BasisCapability#

Which kind of basis a run’s mode axis is, and so which accessors it admits.

alias of Literal[‘modal’, ‘general_modal’, ‘spatial’]

solprop.output.capability.CAPABILITIES: tuple[Literal['modal', 'general_modal', 'spatial'], ...] = ('modal', 'general_modal', 'spatial')#

Every declared basis capability, in the order the manual lists them.

solprop.output.capability.COLUMN_READINGS: Mapping[str, str] = mappingproxy({'energy': 'use solprop.spatial.spatial_energy{slab}', 'peak_power': 'use the largest value of solprop.spatial.spatial_power', 'get_power': 'use solprop.spatial.spatial_power', 'get_spectral_density': '{spectrum}', 'fwhm_t': 'use solprop.processing.fwhm of solprop.spatial.spatial_power', 'fwhm_f': '{spectrum}', 'time_bandwidth': 'use solprop.processing.fwhm of solprop.spatial.spatial_power for the duration; for the bandwidth, {spectrum}', 'arrival_time': 'use solprop.processing.moment of solprop.spatial.spatial_power', 'field_autocorrelation': 'use solprop.spatial.spatial_energy for its value at zero delay', 'intensity_autocorrelation': 'use solprop.spatial.spatial_power', 'coherence_time': 'it is the width of the transform of a spectrum: {spectrum}', 'prop_2d': 'use solprop.spatial.spatial_power at each saved plane for the temporal map; for the spectral map, {spectrum}', 'time_1d': "use solprop.spatial.spatial_power for the power; get_field reads a column's field, in the file's own units", 'spec_1d': '{spectrum}', 'plot_energy': "use the run's stats/energy, which is the beam's energy at each plane"})#

The readers that take each column of a file’s mode axis for a modal amplitude.

Each of the processing and plotting readers named here forms |a|^2 of a column in the square root of watts and sums it over polarisation and, on request, over columns. This is the one list of what a spatial file refuses. The value of each entry is what to use instead, a functional of solprop.spatial on a saved plane and its SpatialFlux; {spectrum} and {slab} stand for the route’s own spectral functional and slab-mode energy, which reading_refusal() fills in, so that the advice names only what works on the file’s route. On a modal or general modal file these readers are what they always were.

class solprop.output.capability.Quantity(kind, unit)[source]#

Bases: object

What a derived quantity of a file is.

Attributes:
kind{‘physical’, ‘coordinate’}

A physical flux, which sums to the pulse’s power and energy, or a quantity of the basis’s coordinates, which does not on a basis with cross terms.

unitstr

Its unit.

kind: Literal['physical', 'coordinate']#
unit: str#
solprop.output.capability.QuantityKind#

Whether a derived quantity is a physical flux, or a quantity of the coordinates.

alias of Literal[‘physical’, ‘coordinate’]

solprop.output.capability.capability_of(metadata)[source]#

Return the capability a stored record declares.

A record whose modal identity declares the general modal basis is a general modal run; a radial or Cartesian run is spatial; everything else – including a record that carries no modal identity at all, and a capillary carrying a coherent wall block, whose identity declares the same orthogonal HE_1m basis it always had – is the ordinary modal basis. It is keyed on modal["basis"] rather than on the identity being present at all because a second route (a capillary with a coherent wall) carries an identity of its own, and a coupled flow through a basis does not change the basis; a general modal record declares "general_modal" there, so nothing already stored reads differently.

Parameters:
metadatasolprop.output.metadata.RunMetadata

The record read back from a handler.

Returns:
str

One of CAPABILITIES.

Examples

>>> from solprop.output.capability import capability_of
>>> from solprop.output.metadata import _example_metadata
>>> capability_of(_example_metadata())
'modal'
solprop.output.capability.compression_refusal(basis)[source]#

Return why the compressors refuse a basis, or None when they admit it.

Every compressor’s objective sums |a|^2 over the selected modes and polarisations, which is the physical power only on an orthogonal modal basis. A general modal or spatial run’s coordinates are not that, so it is refused by name rather than optimised on a quantity that is not a power.

Parameters:
basis{‘modal’, ‘general_modal’, ‘spatial’}

The output’s basis, from capability_of().

Returns:
str or None

The refusal, or None on an orthogonal modal basis.

Examples

>>> from solprop.output.capability import compression_refusal
>>> compression_refusal("modal") is None
True
>>> compression_refusal("spatial")[:47]
'compression requires orthogonal modal power amp'
solprop.output.capability.declared_capability(*, general_modal, spatial)[source]#

Return the capability a translated problem declares.

The problem-side companion of capability_of(), for the two places that hold a problem rather than a record: the run loop’s statistics admission and the reference backend’s own stats.

Parameters:
general_modalbool

Whether transform.modal_tables is set, which is what makes a run a general modal one.

spatialbool

Whether transform.geometry is set, which is what makes it a radial or Cartesian beam.

Returns:
str

One of CAPABILITIES.

Examples

>>> from solprop.output.capability import declared_capability
>>> declared_capability(general_modal=True, spatial=False)
'general_modal'
>>> declared_capability(general_modal=False, spatial=False)
'modal'
solprop.output.capability.quantities(metadata, basis)[source]#

Return what each derived quantity of a stored record is on its basis.

On an orthogonal modal basis the power, energy, spectral density and field are physical; on a general one they are coordinate quantities (whose physical energy is solprop.processing.modal.physical_energy()). On a spatial grid there is only the field, per transverse column in its route’s stored unit: the readers that would give the power, energy and spectral density read the columns as modes and refuse the file (reading_refusal()).

Parameters:
metadatasolprop.output.metadata.RunMetadata

The stored record, which gives a spatial route’s field unit.

basis{‘modal’, ‘general_modal’, ‘spatial’}

The record’s basis, from capability_of().

Returns:
dict

Quantity by name: power (W), energy (J), spectral_density (J s/rad) and field (sqrt(W)) on a modal basis; field alone on a spatial one.

Examples

>>> from solprop.output.capability import quantities
>>> from solprop.output.metadata import _example_metadata
>>> quantities(_example_metadata(), "general_modal")["energy"]
Quantity(kind='coordinate', unit='J')
solprop.output.capability.reading_refusal(metadata, name, *, recorded=())[source]#

Return why a reader of a stored record refuses it, or None.

The processing door of the gate, for the readers that see only the stored record: on a spatial record a reader of COLUMN_READINGS is refused, because it would read each transverse column as a modal amplitude in sqrt(W); otherwise a name ACCESSOR_WHITELIST speaks of is asked of refusal_for(), with the names the record withholds. A reader of no such name – a trace, a density, a plot – is admitted on every modal basis, as it always was.

Parameters:
metadatasolprop.output.metadata.RunMetadata

The stored record.

namestr

The reader or accessor asked for, which the refusal names.

recordedcollections.abc.Sequence, optional

The statistics the file holds. A spatial refusal points to those of them that measure the beam, and to none the run did not record.

Returns:
str or None

The refusal, or None when the record admits name.

Examples

>>> from dataclasses import replace
>>> from solprop.output.capability import reading_refusal
>>> from solprop.output.metadata import _example_metadata
>>> reading_refusal(_example_metadata(), "get_power") is None
True
>>> radial = replace(
...     _example_metadata(),
...     simulation_kind="radial",
...     spatial={"geometry": "radial", "flux_model": "scalar-axial-admittance"},
... )
>>> reading_refusal(radial, "get_power", recorded=["energy"])[:44]
'get_power measures modal amplitudes and this'
solprop.output.capability.refusal_for(capability, names, *, withheld=())[source]#

Return why the first inadmissible accessor is inadmissible, or None.

The one text both doors use, so that a name refused at admission and the same name refused in processing say the same thing. The message names the basis and the replacement, and never redefines the old name.

Each name is refused for its own reason. A per-channel power name is refused because a general basis’s coordinate quantities are not additive; a gas or spatial name is refused because this guide has no gas fill and no transverse geometry, which is not a statement about the basis at all; and a basis-independent step diagnostic is admitted here whatever the basis, so that whoever owns its real reason is the one that refuses it.

Parameters:
capability{‘modal’, ‘general_modal’, ‘spatial’}

What the run’s basis is, from capability_of() or declared_capability().

namescollections.abc.Sequence

The accessor or statistic names asked for, in the order they were asked.

withheldcollections.abc.Sequence, optional

Names the basis admits in general but this run does not publish: a declared basis of a split block executes through a coupled flow whose channels beat, so a per-channel propagation constant is the block’s mean and zdw from it is a number that propagates nothing. The route withholds the name from its record and every door refuses it by name.

Returns:
str or None

The refusal, or None when every name is admitted.

Examples

>>> from solprop.output.capability import refusal_for
>>> refusal_for("general_modal", ["peak_power"])[:34]
'peak_power is unavailable for this'
>>> refusal_for("modal", ["energy"]) is None
True
>>> refusal_for("general_modal", ["quadrature_error"]) is None
True
>>> refusal_for("general_modal", ["zdw"], withheld=("zdw",))[:30]
'zdw is unavailable for this ru'
solprop.output.capability.spatial_field_unit(metadata)[source]#

Return the unit of a spatial record’s stored field.

Parameters:
metadatasolprop.output.metadata.RunMetadata

The record of a spatial run (radial, free or slab).

Returns:
str

"V m" for a radial Hankel spectrum, "V/m" for a Cartesian or line field, "sqrt(W/m)" for a planar slab amplitude per y frequency.

solprop.output.capability.withheld_accessors(*, general_modal, coupled_flow)[source]#

Return the names a problem withholds beyond its basis’s whitelist.

A general modal problem carrying linear.coupled_flow executes a declared basis of a split block, whose per-channel propagation constant is the block’s mean, so it withholds solprop.stats.catalogue.WITHHELD_WITH_A_FLOW; every other problem withholds nothing. The two execution doors pass this to refusal_for(), and the route leaves the same names out of the record’s published list so that the file doors agree (withheld_from()).

Parameters:
general_modalbool

Whether transform.modal_tables is set.

coupled_flowbool

Whether linear.coupled_flow is set.

Returns:
tuple of str

The withheld names, sorted; empty for every problem without a split block.

Examples

>>> from solprop.output.capability import withheld_accessors
>>> withheld_accessors(general_modal=True, coupled_flow=True)
('zdw',)
>>> withheld_accessors(general_modal=False, coupled_flow=True)
()
solprop.output.capability.withheld_from(metadata)[source]#

Return the names a stored record withholds beyond its basis’s whitelist.

The file doors’ half of withheld_accessors(): a general modal record whose published accessors list leaves out a name of solprop.stats.catalogue.WITHHELD_WITH_A_FLOW was written by a split-block route, and the name is refused from the file exactly as it was from the run. A record of any other basis, or one with no published list, withholds nothing.

Parameters:
metadatasolprop.output.metadata.RunMetadata

The stored record.

Returns:
tuple of str

The withheld names, sorted.