Source code for solprop.driver.estimate

# SPDX-FileCopyrightText: 2026 John C. Travers and contributors
#
# SPDX-License-Identifier: GPL-3.0-or-later

"""What a run will cost, before it runs (SEP 41, S11).

:func:`estimate` returns a :class:`RunEstimate`: a translated simulation's grid, the
persistent memory its constructed backend holds, the size of its output, the cost of
one right-hand-side evaluation on the chosen backend timed after an untimed warm-up,
and its integrator's calls per step. It does not predict the number of adaptive steps,
which depends on the physics. :func:`output_bytes` sizes the output from
:func:`plane_bytes`, one saved plane in memory, and :func:`field_bytes`, the part of it
a plane that keeps no field does not hold. The manual page is
``docs/guide/setup/running.md`` ("What a run will cost").
"""

import math
import statistics
import time
from collections.abc import Callable, Mapping
from dataclasses import dataclass
from typing import TYPE_CHECKING, Final

from solprop.backends.protocol import Backend
from solprop.backends.registry import select
from solprop.backends.session import Start
from solprop.driver.run import field_retention
from solprop.exceptions import DriverError
from solprop.grid import FreeGrid, RadialGrid
from solprop.modes.slab import PlanarGrid
from solprop.stats import CATALOGUE, StatsSpec
from solprop.stepper import LowStorageRungeKutta, Multistep
from solprop.translate.problem import PropagationProblem
from solprop.translate.run_request import RunRequest

if TYPE_CHECKING:
    from solprop.driver.simulation import Simulation

__all__ = ["RunEstimate", "estimate", "field_bytes", "output_bytes", "plane_bytes"]

_REPEATS: Final = 3
"""Timed trial steps, after the warm-up; the median is reported."""

_COUNTED_PER_PLANE: Final = 3
"""Eight-byte entries a memory store keeps per plane beside the arrays: ``z`` and
the two per-plane counts."""


[docs] @dataclass(frozen=True) class RunEstimate: """A run's cost, as far as it is known before the run. Attributes ---------- shape : tuple of int The state's shape: modes or transverse columns, polarisations and frequencies. n_planes : int The planes the run saves, the entrance included. memory : int The persistent memory the constructed backend holds, its ledger's total, bytes. output_bytes : int The output's size for the requested planes and retained fields, bytes, as an in-memory store holds it (an HDF5 file adds little). backend : str The backend the run would use. threads : object The backend's thread count, as it reports it. setup : float Seconds to build the backend and take the untimed first step: compilation and transform planning. rhs : float Seconds per right-hand-side evaluation, the median of timed trial steps divided by the tableau's stages. calls_per_step : int Right-hand-side evaluations per accepted step of the integrator: six for the Runge-Kutta march (its first stage is the last's), one for the Adams method, four for the low-storage march. total_calls : int or None Evaluations of a replayed fixed schedule, its steps times the calls per step; ``None`` for an adaptive run, whose step count the physics decides. """ shape: tuple[int, ...] n_planes: int memory: int output_bytes: int backend: str threads: object setup: float rhs: float calls_per_step: int total_calls: int | None
[docs] @property def step(self) -> float: # numpydoc ignore=RT01 """Evaluations' share of an accepted step's time, s.""" return self.rhs * self.calls_per_step
def _timed_step( backend: Backend, problem: PropagationProblem, request: RunRequest ) -> tuple[Callable[[], object], int]: """Load a run's entrance and return the step to time, and its evaluations. The step is the backend's timing probe (SEP 47 section 6.6): one trial from the entrance that commits nothing, or for the low-storage march its own step, which advances the discarded registers in place. - Returns: a callable taking one step, and the right-hand-side evaluations in it. """ integrator = request.integration.method evaluations = ( _calls_per_step(integrator) if isinstance(integrator, LowStorageRungeKutta) else len(request.integration.tableau.nodes) ) return backend.timing_probe(Start.entrance(problem)).trial, evaluations def _calls_per_step(integrator: object) -> int: """Return an integrator's right-hand-side evaluations per accepted step.""" if isinstance(integrator, Multistep): return 1 if isinstance(integrator, LowStorageRungeKutta): return 4 return 6
[docs] def estimate( simulation: "Simulation", *, repeats: int = _REPEATS, ) -> RunEstimate: """Estimate what a simulation's run would cost, without running it. Parameters ---------- simulation : solprop.driver.simulation.Simulation The simulation; it is translated if it is not already. repeats : int, optional Timed trial steps after the warm-up. Returns ------- RunEstimate The estimate. """ problem = simulation.translate() request = simulation.run_request() settings = simulation.settings n_planes = request.observation.save_planes.size + 1 size = output_bytes(simulation) integrator = request.integration.method calls = _calls_per_step(integrator) replay = request.replay total = None if replay is None else int(replay.schedule.steps.size) * calls started = time.perf_counter() backend = select( settings.backend, problem, request, grid=simulation.grid, modes=simulation.modes, profiles=simulation.profiles, options=settings.execution_options(), ) try: memory = sum(backend.memory_ledger().values()) # Bound only when a monitor attaches, which an estimate doesn't do (SEP 44). if ( settings.boundary_check is not None and simulation.medium is not None and isinstance(simulation.spatial_grid, RadialGrid | FreeGrid | PlanarGrid) ): memory += backend.edge_memory(simulation.spatial_grid) step, evaluations = _timed_step(backend, problem, request) step() setup = time.perf_counter() - started timings = [] for _ in range(max(1, repeats)): begun = time.perf_counter() step() timings.append(time.perf_counter() - begun) rhs = statistics.median(timings) / evaluations reported = backend.metadata() # Each backend names its own: native "thread_count"; numpy_ref runs on one # thread and names none. threads = next( ( reported[key] for key in ("thread_count", "threads") if reported.get(key) is not None ), 1, ) finally: backend.close() return RunEstimate( tuple(problem.shape), n_planes, memory, size, settings.backend, threads, setup, rhs, calls, total, )
[docs] def output_bytes(simulation: "Simulation") -> int: """Return the size of a run's output, without constructing a backend. Every saved plane's :func:`plane_bytes`, less the field of each plane the settings do not retain, as an in-memory store holds it (an HDF5 file adds little). Parameters ---------- simulation : solprop.driver.simulation.Simulation The simulation; it is translated if it is not already. Returns ------- int Bytes. """ problem = simulation.translate() request = simulation.run_request() settings = simulation.settings retention = field_retention(request, settings.fields, settings.field_planes) n_planes = request.observation.save_planes.size + 1 kept = sum(1 for index in range(n_planes) if retention.keeps(index)) plane = plane_bytes(problem, request.observation.stats) return n_planes * plane - (n_planes - kept) * field_bytes(problem)
[docs] def plane_bytes(problem: PropagationProblem, stats: StatsSpec) -> int: """Return the bytes one saved plane occupies in an in-memory store. The field (complex128), the noise phase (float64) when the run carries a noise model, every statistic at its catalogued shape (float64; a statistic catalogued with a smaller shape for spatial beams is counted at the modal one, an upper bound of a few entries), and the position and the two per-plane counts. Parameters ---------- problem : solprop.translate.problem.PropagationProblem The translated problem. stats : solprop.stats.StatsSpec The statistics its run collects. Returns ------- int Bytes per plane. Examples -------- >>> from solprop.driver import Simulation >>> from solprop.driver.estimate import plane_bytes >>> 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=1e-12, ... width=100e-15, peak_power=9.8, shape="sech", ... ) >>> problem = simulation.translate() >>> stats = simulation.run_request().observation.stats >>> plane_bytes(problem, stats) >= 16 * problem.shape[-1] True """ n_modes, n_pol, n_omega = problem.shape entries = n_modes * n_pol * n_omega total = 16 * entries + 8 * _COUNTED_PER_PLANE if problem.initial.noise_model != "none": total += 8 * entries sizes = { "n_modes": n_modes, "n_pol": n_pol, "n_omega": n_omega, "n_windows": stats.n_windows, "n_apertures": stats.n_apertures, "n_regions": stats.n_regions, "n_species": problem.responses.n_species, "n_nodes": problem.transform.n_nodes, } for name in stats.names: total += 8 * _catalogued_entries(CATALOGUE[name].shape, sizes) return total
[docs] def field_bytes(problem: PropagationProblem) -> int: """Return the bytes of one plane's field, and its noise phase, in a memory store. The part of :func:`plane_bytes` a plane that keeps no field does not hold (SEP 22). Parameters ---------- problem : solprop.translate.problem.PropagationProblem The translated problem. Returns ------- int Sixteen bytes per state entry, and eight more with a noise model. Examples -------- >>> from solprop.driver import Simulation >>> from solprop.driver.estimate import field_bytes >>> 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=1e-12, ... width=100e-15, peak_power=9.8, shape="sech", noise=None, ... ) >>> field_bytes(simulation.translate()) == 16 * simulation.translate().shape[-1] True """ entries = math.prod(problem.shape) return (16 + (8 if problem.initial.noise_model != "none" else 0)) * entries
def _catalogued_entries(shape: str, sizes: Mapping[str, int]) -> int: """Return how many entries a statistic of a catalogued shape holds. - ``shape``: the catalogue's shape, such as ``'(n_windows, n_modes)'``, ``'(2,)'`` or ``'()'``; an alternative after ``';'`` is ignored. - ``sizes``: the length of every axis name a catalogued shape uses. - Returns: the product of the axis lengths, one for a scalar. """ axes = shape.partition(";")[0].strip().strip("()") count = 1 for axis in (one.strip() for one in axes.split(",")): if not axis: continue if axis.isdigit(): count *= int(axis) elif axis in sizes: count *= sizes[axis] else: msg = f"no length is known for the statistics axis {axis!r} in {shape!r}" raise DriverError(msg) return count