solprop.processing.plane_file

Save a field plane to a file and load it back, to launch another run from it.

save_field_plane() writes what solprop.processing.planes.field_plane() reads from a run: the samples as stored, the temporal grid’s record, the basis with its identity, the reference, the geometry, the metric’s arrays, the provenance and the path certificate. load_field_plane() rebuilds the plane, which couples as the original does.

The file is one HDF5 file holding one plane, with its own PLANE_FILE_SCHEMA. A FieldPlane lives in the physics layer, which reads no files, so the file form is here and not on the class. A plane’s live medium and its resolved measure are Python objects with no file form, so a plane holding either is refused: reading a run without source= gives a plane without them. The manual page is docs/guide/workflows/coupling.md.

Module Attributes

PLANE_FILE_SCHEMA

The layout of a field-plane file this release writes and reads.

Functions

load_field_plane(path)	Read a field plane back from a file save_field_plane() wrote.
save_field_plane(plane, path)	Write a field plane to a new file, to launch another run from it.

solprop.processing.plane_file.PLANE_FILE_SCHEMA = 1

The layout of a field-plane file this release writes and reads.

solprop.processing.plane_file.load_field_plane(path)

Read a field plane back from a file save_field_plane() wrote.

The plane has what it was saved with, its samples, grid and metric to the last bit, and no medium.

Parameters:

pathpathlib.Path or str

The file.

Returns:

solprop.coupling.plane.FieldPlane

The plane.

Raises:

OutputError

If the file cannot be read, is not a field-plane file, declares a schema other than PLANE_FILE_SCHEMA, or is damaged.

solprop.processing.plane_file.save_field_plane(plane, path)

Write a field plane to a new file, to launch another run from it.

Parameters:

planesolprop.coupling.plane.FieldPlane

The plane: usually field_plane() of a run.

pathpathlib.Path or str

The file to create. An existing file is not replaced.

Raises:

ProcessingError

If the plane holds a live medium or a resolved measure, which have no file form, or is a hybrid planar plane, which is not exchanged.

OutputError

If the file exists or cannot be written.

Examples

>>> import tempfile
>>> from pathlib import Path
>>> from solprop.coupling import (
...     FieldPlane,
...     PlaneBasis,
...     PlaneGeometry,
...     basis_identity,
... )
>>> from solprop.fourier import spectrum_to_optics
>>> from solprop.grid import EnvelopeGrid
>>> from solprop.processing import load_field_plane, save_field_plane
>>> from solprop.pulses import GaussianPulse
>>> grid = EnvelopeGrid.from_limits(1e-3, 800e-9, (600e-9, 1.2e-6), 200e-15)
>>> pulse = GaussianPulse(wavelength=800e-9, fwhm=30e-15, energy=1e-6)
>>> plane = FieldPlane.from_samples(
...     spectrum_to_optics(pulse.build(grid), kind=grid.kind),
...     grid,
...     PlaneGeometry(0.0),
...     exterior="zero",
...     basis=PlaneBasis("modal", basis_identity("modal", {"modes": ["HE11"]})),
... )
>>> with tempfile.TemporaryDirectory() as folder:
...     path = Path(folder) / "plane.h5"
...     save_field_plane(plane, path)
...     bool((load_field_plane(path).samples == plane.samples).all())
True