solprop.processing.planes#

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

A file records the identities of a general guide’s reference, not its arrays, so a general modal plane’s physical E/H and a dense basis Gram are read with the simulation that ran it (source=), checked against the file through solprop.processing.modal. It records no basis identity: a plane’s is derived when it is read, an ordinary mode set’s from the source’s modes or, when coupling first reads it, the recorded recipe’s. The manual page is docs/guide/workflows/coupling.md.

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=None, *, 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. The basis is derived here, since a file records none (of_run()): a spatial or general modal one from the file, an ordinary mode set’s from its modes at the plane – the source’s, or those the output’s recorded recipe rebuilds, built only when the identity is first read, which only coupling does – and unknown (None) for a run from a script read without its source, which same_basis then refuses to copy. 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.store.Output

An opened memory or HDF5 output whose record carries its plane reference.

planeint or None, 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. Refused beside a plane.

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 basis and 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.

solprop.recipe.RecipeError

If the recipe the output records no longer builds its simulation.

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)')
>>> plane.basis.identity is None  # a run from a script, read without its source
True
solprop.processing.planes.fluence_map(output, plane=None, *, 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.store.Output

An opened memory or HDF5 output of a spatial run.

planeint or None, 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. Refused beside a plane.

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 or is named both by index and by position, 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_free(
...     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)