solprop.processing.planes#

Read one saved plane of a run: a coherent field plane (SEP 31), or a fluence map.

fluence_map() lays a spatial plane’s fluence out on its transverse axes. field_plane() turns a stored plane into a solprop.coupling.plane.FieldPlane: its native coefficients exactly as stored, the reference rebuilt from the run’s plane-reference record, the medium’s metric at the plane’s own position, the path certificate and the provenance. It is the extraction half of plane exchange; the manual page is docs/guide/workflows/coupling.md.

A file records what it can: the frame integral, the spatial plane measure and the identities of a general guide’s reference, not the reference’s arrays. A general modal plane’s physical E/H and a dense basis Gram are therefore read with the simulation that ran it (source=), checked against the file’s identities first through solprop.processing.modal.

Module Attributes

PLANE_TOLERANCE

Relative distance, of the larger of 1 m and abs(z), within which a z names a plane.

Functions

`field_plane`(output[, plane, z, source])	Read one saved plane of a run as a `FieldPlane`.
`fluence_map`(output[, plane, z])	Lay one saved plane's fluence out on the run's transverse axes.

Classes

FluenceMap(fluence, axes, axis_names, z)

Hold one saved plane's fluence laid out on its transverse axes.

class solprop.processing.planes.FluenceMap(fluence, axes, axis_names, z)[source]#

Bases: object

Hold one saved plane’s fluence laid out on its transverse axes.

Attributes:

fluencenumpy.ndarray: Signed fluence in J/m^2 (J/m^2 per unit y width on a line), the same quantity as solprop.spatial.spatial_fluence(): broadband or absorbing fields can give a negative local value. Its shape is (n_r,), (n_x,) or (n_y, n_x), the axes of axes in order.
axestuple of numpy.ndarray: The node positions in m: (r,), (x,) or (y, x).
axis_namestuple of str: The names of axes: ('r',), ('x',) or ('y', 'x').
zfloat: Position of the plane in m.

axes: tuple[Float[ndarray, '_axis'], ...]#

axis_names: tuple[str, ...]#

fluence: Float[ndarray, '*_axes']#

z: float#

solprop.processing.planes.PLANE_TOLERANCE = 1e-09#

Relative distance, of the larger of 1 m and abs(z), within which a z names a plane.

A requested position names a stored plane only if it is that plane to well within a step; a nearby physical plane that was not stored is refused, not substituted.

solprop.processing.planes.field_plane(output, plane=-1, *, z=None, source=None)[source]#

Read one saved plane of a run as a FieldPlane.

The samples are the stored optics-convention spectrum, unchanged. The reference is rebuilt from the run’s plane-reference record (SEP 31) at the plane’s stored position; the metric is the run’s own at that position – the axial admittance of a spatial plane (SEP 34), the identity for ordinary true-power coefficients, a general basis’s Gram; the path certificate is the AdiabaticAdmission the spatial record rebuilds. Radial, Cartesian, ordinary modal and general modal runs are read; a hybrid planar run is refused by name, and so is a run with the modified noise model, whose auxiliary noise phase is not reconstructed into the plane.

Parameters:

outputsolprop.output.schema.Output: An opened memory or HDF5 output whose record carries its plane reference.
planeint, optional: Index of the saved plane, negative from the end; default the last.
zfloat or None, optional: Position of the plane instead, m; it must be a stored plane’s to PLANE_TOLERANCE. A nearby plane is never substituted.
sourcesolprop.driver.Simulation or None, optional: The simulation that wrote the output, for what the file deliberately does not embed: a general guide’s E/H reference and a dense Gram, checked against the file’s identities; a spatial run’s medium, or an ordinary mode set’s scalar profiles (ScalarModeBasis, for a capillary’s HE1m or a step-index fibre’s HE1m modes), checked by configuration hash. Not needed otherwise.

Returns:

solprop.coupling.FieldPlane: The plane.

Raises:

ProcessingError: If the output holds no record or no plane reference, both plane and z are given, the selection names no stored plane, the run is planar or used the modified noise model, or source is not the run that wrote it.

Examples

>>> from solprop.driver import Simulation
>>> from solprop.processing import field_plane
>>> simulation = Simulation.from_gnlse(
...     0.11, 0.01, [0.0, 0.0, -1.183e-26], wavelength=835e-9,
...     wavelength_limits=(500e-9, 2e-6), trange=1.2e-12,
...     width=100e-15, peak_power=9.8, shape="sech", n_save=3,
... )
>>> plane = field_plane(simulation.run())
>>> plane.kind, plane.geometry.z, plane.units
('modal', 0.01, 'sqrt(W)')

solprop.processing.planes.fluence_map(output, plane=-1, *, z=None)[source]#

Lay one saved plane’s fluence out on the run’s transverse axes.

Read from the record alone, in any bulk medium, so a file written by a script is read like one written from a recipe; only the selected plane is read. A hybrid planar file is refused by spatial_grid_of().

Parameters:

outputsolprop.output.schema.Output: An opened memory or HDF5 output of a spatial run.
planeint, optional: Index of the saved plane, negative from the end; default the last.
zfloat or None, optional: Position of the plane instead, m; it must be a stored plane’s to PLANE_TOLERANCE. A nearby plane is never substituted.

Returns:

FluenceMap: The fluence with its axes: (r,), (x,) or (y, x).

Raises:

ProcessingError: If the run has no transverse grid, the plane is not stored, the record carries no plane measure, or the run is a hybrid planar file.

Examples

>>> from solprop.driver import Simulation, SimulationSettings
>>> from solprop.grid import EnvelopeGrid, RadialGrid
>>> from solprop.pulses import GaussianPulse, SpatialPulse
>>> from solprop.spatial import SpatialMedium
>>> from solprop.stepper import PIController
>>> simulation = Simulation.from_radial(
...     EnvelopeGrid.from_limits(1e-3, 800e-9, (600e-9, 1.2e-6), 400e-15),
...     RadialGrid(1e-3, 16),
...     SpatialMedium(),
...     [],
...     SpatialPulse(
...         GaussianPulse(wavelength=800e-9, fwhm=30e-15, energy=1e-9), 1e-4
...     ),
...     settings=SimulationSettings(
...         controller=PIController(rtol=1e-6, atol=1e-12),
...         save_planes=[1e-3],
...         dz_init=1e-3,
...         dz_max=1e-3,
...         backend="numpy_ref",
...         spatial_absorber=False,
...     ),
...     noise=None,
... )
>>> beam = fluence_map(simulation.run(progress="none"))
>>> beam.axis_names, beam.fluence.shape, beam.z
(('r',), (16,), 0.001)