solprop.output.callback#

The output handler that gives each plane to a callable and keeps nothing.

The handler for a scan that reduces each plane to a few numbers: the callable is the body of what would otherwise be a hand loop over the backend. The plane reaches it as the run made it, with no copy and no conversion, so the handler costs no volume of its own.

It is an Output and a RetainingOutput, and deliberately neither a PlaneStore nor a CheckpointOutput. A store’s readers have nothing to read here, and its save path converts each field into a new volume. A checkpoint promises a state that resume=True can continue, and with no file there is nothing to continue, so a run neither fetches a terminal field for this handler nor says that one was written.

The manual page is docs/guide/setup/running.md.

Classes

CallbackOutput(receive)

Give each saved plane to a callable, and keep nothing.

class solprop.output.callback.CallbackOutput(receive)[source]#

Bases: object

Give each saved plane to a callable, and keep nothing.

The callable is given the run’s own SavedPlane, not a copy. Its arrays are read-only and nothing writes to them again, so the callable may keep any of them, at the cost of what it keeps; a plane it reduces and lets go costs one field volume on the host while it is held, the one the observation crossed with. The field is as a backend produces it: in the internal FFT convention, in the square root of watts. A reduction of the squared modulus does not depend on the convention, and solprop.fourier.spectrum_to_optics() gives the form a file stores, in a second volume.

The run’s fields setting (SimulationSettings) decides what a plane carries. With fields="none", what a reduction of statistics wants, every plane has field=None and noise_phase=None beside its position, its statistics and its step history, and no field leaves the backend. With fields="planes" the planes it does not name are those; with the default "all" every plane carries its field.

What it cannot do, it refuses by name. Reading anything back (handler[key], fields()) raises OutputError, and a handler that has served a run refuses another, which would continue it. A resume needs a file (check_cache(), resume(), resume=True), as does a TDSE run’s ledger. A stopped run returns the handler with no state written.

A run with an optmat ionisation rate reads its peak rates back from its output to report the peak field and warn past the rate’s range (MaterialRangeWarning). This handler stores no statistic, so that report and warning do not happen: read the rate in the callable.

Parameters:

receivecollections.abc.Callable: Called once per saved plane, the entrance first, with the plane. What it returns is ignored; what it raises stops the run and propagates, and that plane is not counted.

Raises:

OutputError: If receive is not callable.

Examples

>>> import dataclasses
>>> from solprop.driver import Simulation
>>> from solprop.output import CallbackOutput
>>> 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, rtol=1e-6,
... )
>>> simulation.settings = dataclasses.replace(simulation.settings, fields="none")
>>> kept = []
>>> handler = CallbackOutput(lambda plane: kept.append((plane.z, plane.field)))
>>> simulation.run(handler, progress="none") is handler
True
>>> kept
[(0.0, None), (0.005, None), (0.01, None)]
>>> "z" in handler, handler
(False, CallbackOutput(3 planes, closed))

close()[source]#

Finish the run. Calling it twice is harmless.

fields(convention='optics')[source]#

Refuse to read the fields back.

Parameters:

convention{‘optics’, ‘fft’}, optional: The convention that was asked for.

Raises:

OutputError: Always.

property metadata: RunMetadata | None[source]#

Return the record of the run, or None before it is opened.

Returns:

RunMetadata or None: What produced the planes.

property n_saved: int[source]#

Return how many planes the callable has taken.

Returns:

int: The number of planes.

open(metadata, *, force=False)[source]#

Begin a run, holding its record.

Parameters:

metadataRunMetadata: The record of the run about to start.
forcebool, optional: Whether to replace a different record held already (resolve_metadata_write()).

Raises:

OutputError: If the handler has served a run already, or a different record is held and force is false.

retain(retention, field_shape)[source]#

Accept the run’s field rule: there is no storage for it to size.

Declares RetainingOutput, which is what admits field-free planes. The rule reaches the callable as each plane’s field.

Parameters:

retentionFieldRetention: Which planes keep their field.
field_shapetuple of int: (n_modes, n_pol, n_omega) of the run’s state.

save(plane)[source]#

Give one plane to the callable, and count it once the callable has returned.

Parameters:

planeSavedPlane: The plane, handed on as it is.

Raises:

OutputError: If the handler is closed or was never opened.

property stat_names: tuple[str, ...][source]#

Return the statistics stored at every plane: none.

Returns:

tuple of str: Empty, so that nothing asks to read one back.

property step_stat_names: tuple[str, ...][source]#

Return the statistics stored between planes: none.

Returns:

tuple of str: Empty.