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 gate:
declared_capability()(of a translated problem) andcapability_of()(of a stored record) say which capability applies;ACCESSOR_WHITELISTandrefusal_for()what it admits and why not;withheld_accessors()andwithheld_from()what a run withholds beyond it. The name sets come fromsolprop.stats.catalogue, so that a translation module records them without importing an output one.The per-channel readers:
reading_refusal()refuses the processing readers and plots on a basis they do not describe, andCOLUMN_READINGSnames the readers of a spatial file’s columns as modes with the spatial functional to use instead (spatial_field_unit()gives those columns’ unit).quantities()returns aQuantityper derived quantity of a file (QuantityKind: a physical flux or a coordinate quantity, with its unit), andcompression_refusal()why the compressors refuse a basis.
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
Which kind of basis a run's mode axis is, and so which accessors it admits. |
|
Every declared basis capability, in the order the manual lists them. |
|
Which statistics and accessors each capability admits. |
|
The readers that take each column of a file's mode axis for a modal amplitude. |
|
Whether a derived quantity is a physical flux, or a quantity of the coordinates. |
Functions
|
Return the capability a stored record declares. |
|
Return why the compressors refuse a basis, or |
|
Return the capability a translated problem declares. |
|
Return what each derived quantity of a stored record is on its basis. |
|
Return why a reader of a stored record refuses it, or |
|
Return why the first inadmissible accessor is inadmissible, or |
|
Return the unit of a spatial record's stored field. |
|
Return the names a problem withholds beyond its basis's whitelist. |
|
Return the names a stored record withholds beyond its basis's whitelist. |
Classes
|
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.
Nonemeans “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, becauseenergythe statistic is admitted whereenergythe 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|^2of 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 ofsolprop.spatialon a saved plane and itsSpatialFlux;{spectrum}and{slab}stand for the route’s own spectral functional and slab-mode energy, whichreading_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:
objectWhat 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.
- 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_1mbasis it always had – is the ordinary modal basis. It is keyed onmodal["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
Nonewhen they admit it.Every compressor’s objective sums
|a|^2over 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
Noneon 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 ownstats.- Parameters:
- general_modalbool
Whether
transform.modal_tablesis set, which is what makes a run a general modal one.- spatialbool
Whether
transform.geometryis 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
Quantityby name:power(W),energy(J),spectral_density(J s/rad) andfield(sqrt(W)) on a modal basis;fieldalone 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_READINGSis refused, because it would read each transverse column as a modal amplitude in sqrt(W); otherwise a nameACCESSOR_WHITELISTspeaks of is asked ofrefusal_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
Nonewhen 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()ordeclared_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
zdwfrom 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
Nonewhen 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_flowexecutes a declared basis of a split block, whose per-channel propagation constant is the block’s mean, so it withholdssolprop.stats.catalogue.WITHHELD_WITH_A_FLOW; every other problem withholds nothing. The two execution doors pass this torefusal_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_tablesis set.- coupled_flowbool
Whether
linear.coupled_flowis 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 publishedaccessorslist leaves out a name ofsolprop.stats.catalogue.WITHHELD_WITH_A_FLOWwas 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.