# SPDX-FileCopyrightText: 2026 John C. Travers and contributors
#
# SPDX-License-Identifier: GPL-3.0-or-later
"""The lazy view of a saved plane that a plane observer is shown (SEP 41, S3).
A reporter that defines ``observe_plane`` (:class:`~solprop.log.ProgressReporter`) is
shown each saved plane as a :class:`PlaneView`, through a run's :class:`PlaneWatch`:
the plane's position, statistics row and basis at once, and its field, spectrum, power
and spectral density only on request, computed by the same :mod:`solprop.processing`
functions that read a file, so what an observer draws is what the file holds. On a
device a plane whose field the output does not keep is fetched only when asked for,
and the fetch is counted in the run's resources. The manual page is
``docs/guide/performance/progress.md`` ("Watching each saved plane").
"""
import logging
import time
import warnings
from collections.abc import Callable, Mapping
from typing import TYPE_CHECKING, Any, Final
import numpy as np
from solprop._host import ObserverSpend
from solprop.exceptions import DriverError, SolpropWarning
from solprop.log import ProgressReporter
from solprop.output.capability import (
BasisCapability,
Quantity,
capability_of,
quantities,
)
from solprop.output.memory import MemoryOutput
from solprop.output.metadata import RunMetadata
from solprop.output.records import SavedPlane, StoredField
from solprop.processing import fields, planes
if TYPE_CHECKING:
from solprop.coupling.plane import FieldPlane
__all__ = ["PlaneView", "PlaneWatch"]
logger = logging.getLogger(__name__)
_EXPIRED: Final = (
"this plane view was valid only during observe_plane: copy what you keep"
)
[docs]
class PlaneView:
"""One saved plane, as a plane observer sees it; valid only during the call.
Parameters
----------
plane : solprop.output.records.SavedPlane
The plane as committed, its field ``None`` where the output keeps none.
index : int
Its index among the saved planes.
metadata : solprop.output.metadata.RunMetadata
The run's record.
fetch : callable or None
Returns the plane's field where it was not kept; ``None`` where it was.
spend : solprop._host.ObserverSpend
The run's observer ledger, which counts the fetches.
stored : solprop.output.records.StoredField or None, optional
The kept field as the output stored it, where it was exported straight into
the output (SEP 47 section 5.4) and the plane carries none: the view reads
that, with no fetch.
Attributes
----------
z : float
The plane's position, m.
index : int
Its index among the saved planes.
stats : collections.abc.Mapping
Its statistics row, by name.
"""
def __init__(
self,
plane: SavedPlane,
index: int,
metadata: RunMetadata,
fetch: Callable[[], np.ndarray] | None,
spend: ObserverSpend,
*,
stored: StoredField | None = None,
) -> None:
"""Hold the plane; compute nothing yet."""
self.z = float(plane.z)
self.index = index
self.stats: Mapping[str, np.ndarray] = dict(plane.stats)
self._plane = plane
self._metadata = metadata
self._fetch = fetch
self._spend = spend
self._stored = stored
self._output: MemoryOutput | None = None
self._open = True
[docs]
@property
def basis(self) -> BasisCapability: # numpydoc ignore=RT01
"""The run's basis.
The basis capability its record declares.
"""
return capability_of(self._metadata)
[docs]
@property
def quantities(self) -> dict[str, Quantity]: # numpydoc ignore=RT01
"""What the plane's derived quantities are.
Whether its power, energy, density and field are physical fluxes, as
:func:`solprop.capabilities.output` states them; a spatial plane has only
its field.
"""
return quantities(self._metadata, self.basis)
def _reader(self) -> MemoryOutput:
"""Return the plane as a one-plane output, fetching its field once if needed."""
if not self._open:
raise DriverError(_EXPIRED)
if self._output is None:
plane = self._plane
if self._stored is not None:
output = MemoryOutput()
output.open(self._metadata)
# A copy of what the output stored, into the view's own room.
output.save_exported(plane, self._stored)
self._output = output
return output
if plane.field is None and self._fetch is not None:
self._spend.transfers += 1
plane = SavedPlane(
z=plane.z,
field=self._fetch(),
stats=plane.stats,
noise_phase=plane.noise_phase,
)
output = MemoryOutput()
output.open(self._metadata)
output.save(plane)
self._output = output
return self._output
[docs]
def spectrum(self, **keywords: Any) -> tuple[np.ndarray, np.ndarray]:
"""Return the plane's spectrum, as the processing function returns it.
The function is :func:`solprop.processing.fields.get_spectrum`.
Parameters
----------
**keywords : Any
Its keywords, the plane excepted.
Returns
-------
tuple
The angular frequency axis and the spectrum.
"""
return fields.get_spectrum(self._reader(), plane=0, **keywords)
[docs]
def field(self, **keywords: Any) -> tuple[np.ndarray, np.ndarray]:
"""Return the plane's field in time, as the processing function returns it.
The function is :func:`solprop.processing.fields.get_field`.
Parameters
----------
**keywords : Any
Its keywords, the plane excepted.
Returns
-------
tuple
The time axis and the field.
"""
return fields.get_field(self._reader(), plane=0, **keywords)
[docs]
def power(self, **keywords: Any) -> tuple[np.ndarray, np.ndarray]:
"""Return the plane's power in time, as the processing function returns it.
The function is :func:`solprop.processing.fields.get_power`.
Parameters
----------
**keywords : Any
Its keywords, the plane excepted.
Returns
-------
tuple
The time axis and the power, W.
Raises
------
solprop.exceptions.OutputError
On a spatial run, whose columns the function would read as modes:
:func:`solprop.spatial.spatial_power` is the beam's power.
"""
return fields.get_power(self._reader(), plane=0, **keywords)
[docs]
def spectral_density(self, **keywords: Any) -> tuple[np.ndarray, np.ndarray]:
"""Return the plane's spectral density, as the processing function does.
Parameters
----------
**keywords : Any
The keywords of :func:`solprop.processing.fields.get_spectral_density`, the
plane excepted.
Returns
-------
tuple
The axis and the density.
Raises
------
solprop.exceptions.OutputError
On a spatial run, whose columns the function would read as modes.
"""
return fields.get_spectral_density(self._reader(), plane=0, **keywords)
[docs]
def stored(self) -> np.ndarray:
"""Return the plane's stored spectrum, as a file holds it.
The raw forward DFT in the internal convention, shape
``(n_modes, n_pol, n_omega)`` -- what ``output.fields("fft")`` returns for the
plane, and what the functionals of :mod:`solprop.spatial` (``spatial_power``,
``spatial_fluence`` and the rest) take with the run's ``SpatialFlux``, which is
how a spatial run's plane is measured while it runs.
Returns
-------
numpy.ndarray
A copy of the stored spectrum.
"""
return np.array(self._reader().fields("fft")[0])
[docs]
def field_plane(self) -> "FieldPlane":
"""Return the plane as :func:`solprop.processing.planes.field_plane` reads it.
Its ``spectral_energy`` is a spatial plane's energy per frequency bin, where
:meth:`spectral_density` refuses the columns of a spatial run.
Returns
-------
solprop.coupling.FieldPlane
The plane.
Raises
------
solprop.exceptions.OutputError
For a run :func:`~solprop.processing.planes.field_plane` refuses (a hybrid
planar run, the modified noise model).
"""
return planes.field_plane(self._reader(), 0)
def _close(self) -> None:
"""End the view's validity and let its arrays go."""
self._open = False
self._output = None
[docs]
class PlaneWatch:
"""Show a run's saved planes to its reporter, when it defines ``observe_plane``.
Parameters
----------
reporter : solprop.log.ProgressReporter
The run's reporter; only one that defines ``observe_plane`` is shown planes.
metadata : solprop.output.metadata.RunMetadata
The run's record.
fetch : callable
Returns the field at the current plane, for a plane the output keeps none of.
spend : solprop._host.ObserverSpend
The run's observer ledger.
"""
def __init__(
self,
reporter: ProgressReporter,
metadata: RunMetadata,
fetch: Callable[[], np.ndarray],
spend: ObserverSpend,
) -> None:
"""Hold the observer, or nothing for a reporter that is not one."""
self._observe: Callable[[float, PlaneView], None] | None = getattr(
reporter, "observe_plane", None
)
self._metadata = metadata
self._fetch = fetch
self._spend = spend
[docs]
def show(
self, plane: SavedPlane, index: int, stored: StoredField | None = None
) -> None:
"""Show one committed plane, detaching an observer that fails.
Parameters
----------
plane : solprop.output.records.SavedPlane
The plane as committed.
index : int
Its index among the saved planes.
stored : solprop.output.records.StoredField or None, optional
Its kept field as the output stored it, where it was exported straight
into the output and the plane carries none.
Warns
-----
SolpropWarning
When the observer raised, which then sees no more planes in this run.
"""
observe = self._observe
if observe is None:
return
view = PlaneView(
plane,
index,
self._metadata,
self._fetch if plane.field is None and stored is None else None,
self._spend,
stored=stored,
)
started = time.perf_counter()
try:
observe(plane.z, view)
except Exception as error:
# Not a stop, an interrupt or a signal: those are BaseExceptions and stop
# the run as they would anywhere.
self._observe = None
logger.exception("the plane observer failed at z = %.6e m", plane.z)
msg = (
f"the plane observer raised {type(error).__name__}: {error}; it is "
"shown no more planes in this run, which continues"
)
warnings.warn(msg, SolpropWarning, stacklevel=2)
finally:
view._close()
self._spend.calls += 1
self._spend.seconds += time.perf_counter() - started