solprop.driver.summary#

The block a run shows before its first step: what is about to be computed, and how.

Every route reaches solprop.driver.run.run_problem(), which builds this summary from the translated KernelProblem, the run’s RunMetadata (whose configuration holds the physics objects the problem was built from: the responses, the medium, the profiles), the backend’s own execution record and the output. It hands the text to the progress reporter, so it follows the progress choice exactly as the progress lines do, and records it on a plane store as the RUN_SUMMARY_ANNOTATION.

The rows are descriptions for a person, not a record: everything in them is also in the run’s metadata, which is what a program should read. Nothing here evaluates physics.

The manual page is docs/guide/performance/progress.md.

Functions

`memory_size`(size)	Write a memory size in binary units, as a person reads it.
`resources`(spent)	Describe what a run spent, as the line shown after its closing one.
`run_summary`(problem, metadata, *, backend, ...)	Describe a run before its first step.

Classes

RunSummary(title, rows)

What a run is about to compute, as one aligned block.

class solprop.driver.summary.RunSummary(title, rows)[source]#

Bases: Displayed

What a run is about to compute, as one aligned block.

Attributes:

titlestr: The first line: where the run starts and ends.
rowstuple of tuple of str: (key, value) pairs, one per aspect of the run, in a fixed order.

Examples

>>> from solprop.driver.summary import RunSummary
>>> print(RunSummary("Starting propagation", (("noise", "off"),)))
Starting propagation
  noise: off

record()[source]#

Return the summary as plain JSON values, for a store’s annotation.

Returns:

dict: {"title": ..., "rows": [[key, value], ...]}.

rows: tuple[tuple[str, str], ...]#

text()[source]#

Return the block, as the reporter shows it.

Returns:

str: The title and one line per row, without a trailing newline.

title: str#

solprop.driver.summary.memory_size(size)[source]#

Write a memory size in binary units, as a person reads it.

Parameters:

sizefloat: Bytes.

Returns:

str: Three significant figures and the largest binary unit below the size.

Examples

>>> from solprop.driver.summary import memory_size
>>> memory_size(137438953472), memory_size(30277632)
('128 GiB', '28.9 MiB')

solprop.driver.summary.resources(spent)[source]#

Describe what a run spent, as the line shown after its closing one.

Parameters:

spentcollections.abc.Mapping: The run’s wall_time_s, cpu_time_s and peak_rss_bytes, as the execution record holds them.

Returns:

str: The run’s wall and CPU time, and the process’s peak resident memory where the system reports it.

Examples

>>> from solprop.driver.summary import resources
>>> resources({"wall_time_s": 192.4, "cpu_time_s": 2100.0,
...            "peak_rss_bytes": 2254857830})
'resources: 0:03:12 wall, 0:35:00 CPU, process peak memory 2.1 GiB'
>>> resources({"wall_time_s": 0.132, "cpu_time_s": None, "peak_rss_bytes": None})
'resources: 0.132 s wall'

solprop.driver.summary.run_summary(problem, metadata, *, backend, execution, output, start_plane=0, z_start=0.0, boundary_check=None)[source]#

Describe a run before its first step.

Parameters:

problemsolprop.translate.problem.KernelProblem: The translated problem.
metadatasolprop.output.schema.RunMetadata: The run’s record; its configuration supplies what the problem holds only as compiled tables (the medium and the response models).
backendstr: The backend’s name.
executioncollections.abc.Mapping: The backend’s metadata(), which says how it sized its thread pools and which propagator it chose.
outputsolprop.output.schema.Output: Where the planes go.
start_planeint, optional: Index of the first save plane beyond the loaded state; above zero the run is a resume.
z_startfloat, optional: Where the run starts, m.
boundary_checksolprop.monitor.BoundaryCheck or None, optional: The thresholds the window’s edges are watched with (SEP 21); None when they are not watched.

Returns:

RunSummary: The title and the rows.

Examples

>>> from solprop.driver.simulation import metadata_for
>>> from solprop.driver.summary import run_summary
>>> from solprop.grid import EnvelopeGrid
>>> from solprop.nonlinear.gnlse import problem_from
>>> from solprop.output import MemoryOutput
>>> from solprop.pulses import SechPulse
>>> from solprop.stepper import PIController
>>> from solprop.translate.problem import assemble
>>> grid = EnvelopeGrid.from_limits(0.01, 835e-9, (500e-9, 2e-6), 1e-12)
>>> gnlse = problem_from([0.0, 0.0, -1.183e-26], omega_ref=grid.omega0,
...                      gamma=0.11, shock=False)
>>> start = SechPulse(wavelength=835e-9, width=100e-15, peak_power=9.8).build(grid)
>>> problem = assemble(grid, gnlse.mode, [gnlse.kerr], start,
...                    controller=PIController(rtol=1e-6, atol=1e-16),
...                    save_planes=[0.005, 0.01], dz_max=0.01, dz_init=1e-3,
...                    density=1.0, shock=False, prefactor_index=1.0)
>>> summary = run_summary(problem, metadata_for(problem, grid), backend="numpy_ref",
...                       execution={}, output=MemoryOutput())
>>> dict(summary.rows)["shot noise"]
'off'