solprop.processing.scans#

Read collected scans and declare reductions evaluated inside workers.

All numerical definitions come from the ordinary output processing functions. Missing points are masked, never presented as successful zero-valued results.

Functions

`beam_radius`([plane])	Retain the existing spatial beam-radius statistic.
`custom`(name, fn, shape, units[, dtype, ...])	Wrap a custom output calculation with an explicit storage contract.
`energy_in_band`(lambda_min, lambda_max[, plane])	Measure total energy in a hard spectral band using the discrete functional.
`energy_in_window`(t0, t1[, plane])	Measure total energy in a closed time window on the saved time grid.
`field_at_plane`([plane])	Retain a saved spectral field in the optics convention.
`mode_energies`([plane])	Measure each mode's energy summed over polarisation.
`on_axis_intensity`([plane])	Retain the existing spatial on-axis intensity statistic.
`open`(path)	Open a collected scan reader.
`peak_power`([plane])	Measure the peak of the total power across all modes.
`spectrum_in_band`(lambda_min, lambda_max[, plane])	Retain the total spectral energy density inside a wavelength band.

Classes

`Reduction`(args, *kwargs)	Declare a worker-side calculation and its storage contract.
`ScanOutput`(path)	Read a collected scan without keeping a file handle open.

class solprop.processing.scans.Reduction(*args, **kwargs)[source]#

Bases: Protocol

Declare a worker-side calculation and its storage contract.

Attributes:

namestr: Return the unique result name.
dtypenumpy.dtype: Return the exact result dtype.
unitsstr: Return the physical units.

property dtype: dtype[source]#

Return the exact result dtype.

Returns:

object: Result of the declared operation.

property name: str[source]#

Return the unique result name.

Returns:

object: Result of the declared operation.

shape(metadata)[source]#

Declare the result dimensions.

Parameters:

metadataRunMetadata: The point’s complete run record.

Returns:

tuple of int: Non-negative result extents, without the scan axis.

property units: str[source]#

Return the physical units.

Returns:

object: Result of the declared operation.

class solprop.processing.scans.ScanOutput(path)[source]#

Bases: Displayed

Read a collected scan without keeping a file handle open.

Parameters:

pathpathlib.Path or str: Existing scan file.

Attributes:

pathpathlib.Path: Collected file path.

as_grid(name)[source]#

Reshape a uniform result over the declared variable axes.

Parameters:

namestr: Result path such as ‘reduced/energy_in_band’ or ‘stats/energy’.

Returns:

numpy.ma.MaskedArray: Scan shape followed by result axes; non-done points are masked.

Raises:

ProcessingError: If there are no successful values or their layouts differ.

property layouts: Mapping[str, tuple[int, ...]][source]#

Return known layout identifiers and their completed global points.

Returns:

collections.abc.Mapping: Layout digest to global indices; also works before consolidation.

point(index)[source]#

Read one point’s arrays and provenance.

Parameters:

indexint: Global point index.

Returns:

collections.abc.Mapping: Status, error, metadata and result groups for a completed point.

Raises:

ProcessingError: If the global index is out of range.

property shape: tuple[int, ...][source]#

Return the Cartesian axis lengths.

Returns:

tuple of int: Complete scan shape.

spectrum_wavelength(index=None)[source]#

Return the wavelength abscissa of the spectrum_in_band reduction.

The abscissa is rebuilt from a point’s recorded grid and the reduction’s recorded band, by the function that declares the reduction’s shape, so it matches the last axis of as_grid("reduced/spectrum_in_band") sample for sample.

Parameters:

indexint or None, optional: Global index of a completed point whose abscissa is wanted. None returns the one abscissa shared by every completed point.

Returns:

numpy.ndarray: Wavelengths, ascending, m, shape (n_x,).

Raises:

ProcessingError: If no completed point holds the reduction, the index is out of range or the point does not hold it, or completed points have different abscissae.

property status: ndarray[source]#

Return point statuses in global-index order.

Returns:

numpy.ndarray: Strings todo, running, done or failed, shape (n_points,).

where(**values)[source]#

Find global indices whose variable values match exactly.

Parameters:

**valuesobject: Variable names and scalar values in the original axis units.

Returns:

numpy.ndarray: Matching zero-based global indices, including unfinished points.

Raises:

ProcessingError: If a variable is unknown.

solprop.processing.scans.beam_radius(plane=-1)[source]#

Retain the existing spatial beam-radius statistic.

Parameters:

planeint, optional: Saved-plane index, negative from the end.

Returns:

Reduction: Scalar radius, m; requires the statistic in the simulation spec.

solprop.processing.scans.custom(name, fn, shape, units, dtype=<class 'numpy.float64'>, *, reads_fields=True)[source]#

Wrap a custom output calculation with an explicit storage contract.

A custom reduction is handed the point’s whole run, spooled to a temporary file. By default that run keeps every field. One that declares reads_fields=False reads statistics, positions and step histories only, and its spooled run keeps the fields the scan keeps anyway and no other (SEP 22, Q3): a field read in it is refused by name.

Parameters:

namestr: Unique nonempty dataset name without slashes.
fncallable: Worker-side function accepting a complete Output.
shapetuple of int: Non-negative result extents; () denotes a scalar.
unitsstr: Physical units, or ‘1’ for dimensionless results.
dtypenumpy.dtype or type, optional: Exact returned dtype, float64 by default.
reads_fieldsbool, optional: Whether fn reads the run’s fields; True, the safe default.

Returns:

Reduction: Validated declaration; result shape and dtype are checked at runtime.

Raises:

ProcessingError: If the name or shape is invalid.

solprop.processing.scans.energy_in_band(lambda_min, lambda_max, plane=-1)[source]#

Measure total energy in a hard spectral band using the discrete functional.

Parameters:

lambda_minfloat: Positive lower wavelength, m.
lambda_maxfloat: Upper wavelength greater than the lower bound, m.
planeint, optional: Saved-plane index, negative from the end.

Returns:

Reduction: Scalar energy, J; includes bins whose centre lies in the closed band.

solprop.processing.scans.energy_in_window(t0, t1, plane=-1)[source]#

Measure total energy in a closed time window on the saved time grid.

Parameters:

t0float: Finite lower time, s.
t1float: Finite upper time greater than t0, s.
planeint, optional: Saved-plane index, negative from the end.

Returns:

Reduction: Scalar sum of sample powers times dt, J.

solprop.processing.scans.field_at_plane(plane=-1)[source]#

Retain a saved spectral field in the optics convention.

Parameters:

planeint, optional: Saved-plane index, negative from the end.

Returns:

Reduction: Complex field with its mode, polarisation and frequency axes intact.

solprop.processing.scans.mode_energies(plane=-1)[source]#

Measure each mode’s energy summed over polarisation.

Parameters:

planeint, optional: Saved-plane index, negative from the end.

Returns:

Reduction: Mode energies, J; a single mode follows processing’s scalar convention.

solprop.processing.scans.on_axis_intensity(plane=-1)[source]#

Retain the existing spatial on-axis intensity statistic.

Parameters:

planeint, optional: Saved-plane index, negative from the end.

Returns:

Reduction: Scalar intensity, W/m²; requires the statistic in the simulation spec.

solprop.processing.scans.open(path)[source]#

Open a collected scan reader.

Parameters:

pathpathlib.Path or str: Existing collected HDF5 scan file.

Returns:

ScanOutput: Reader; each operation opens and closes its own read-only handle.

solprop.processing.scans.peak_power(plane=-1)[source]#

Measure the peak of the total power across all modes.

Parameters:

planeint, optional: Saved-plane index, negative from the end.

Returns:

Reduction: Scalar peak power, W.

solprop.processing.scans.spectrum_in_band(lambda_min, lambda_max, plane=-1)[source]#

Retain the total spectral energy density inside a wavelength band.

Parameters:

lambda_minfloat: Positive lower wavelength, m.
lambda_maxfloat: Upper wavelength greater than the lower bound, m.
planeint, optional: Saved-plane index; negative indices count from the end.

Returns:

Reduction: Spectral energy density, J/m, summed over modes, on the ascending wavelengths of the run’s active band that lie in the closed band; read the abscissa with ScanOutput.spectrum_wavelength().