tracmass.RunMonitor#

class tracmass.RunMonitor(backend='print', logger=None, max_table_rows=10)[source]#

Bases: object

Monitor for time_dependent() runs.

Receives structured events from the integration loop and renders them via the chosen backend. Use as a context manager so the "rich" backend can properly start and stop its live display.

Parameters:

  • backend ({"print", "log", "rich"}) – Output backend. "print" reproduces the original stdout output. "log" emits logging records. "rich" shows a live terminal dashboard.

  • logger (logging.Logger, optional) – Logger used by the "log" backend. Defaults to the "tracmass" logger.

  • max_table_rows (int, optional) – Maximum number of window rows shown in the "rich" table at any one time. Older rows scroll out of view. Default 10.

Examples

>>> with tracmass.RunMonitor(backend="rich") as mon:
...     result = tracmass.time_dependent(state, grid, fluxes,
...                                      n_windows=50, monitor=mon)

>>> # Plain print (default when monitor is not supplied):
>>> result = tracmass.time_dependent(state, grid, fluxes, n_windows=50)
__init__(backend='print', logger=None, max_table_rows=10)[source]#
Parameters:
Return type:

None

Methods

__init__([backend, logger, max_table_rows])

on_run_end()

Called once after the integration loop finishes.

on_run_start(n_windows, n_particles)

Called once before the integration loop begins.

on_window_end(win, dtm, n_active_before, ...)

Called at the end of each window after advection and reactivation.

on_window_start(win, n_active, dtm)

Called at the start of each window, before I/O and advection.
on_run_start(n_windows, n_particles)[source]#

Called once before the integration loop begins.

Parameters:

  • n_windows (int) – Total number of GCM windows to integrate.

  • n_particles (int) – Initial number of particles.

Return type:

None

on_window_start(win, n_active, dtm)[source]#

Called at the start of each window, before I/O and advection.

Parameters:

  • win (int) – Zero-based window index.

  • n_active (int) – Number of active particles entering this window.

  • dtm (pandas.Timestamp) – Timestamp of the current GCM time window.

Return type:

None

on_window_end(win, dtm, n_active_before, n_active_after, n_stopped, reason_tally, n_sub, limit_hit, t_io, t_jax, t_py)[source]#

Called at the end of each window after advection and reactivation.

Parameters:

  • win (int) – Zero-based window index.

  • dtm (pandas.Timestamp) – Timestamp of the window just completed.

  • n_active_before (int) – Active count at window entry.

  • n_active_after (int) – Active count after advection + reactivation.

  • n_stopped (int) – Particles permanently deactivated this window.

  • reason_tally (dict[str, int]) – Counts per deactivation reason name.

  • n_sub (int) – Number of sub-cycles executed.

  • limit_hit (bool) – Whether the sub-cycle limit was reached.

  • t_io (float) – Wall time spent in I/O (Dask/Zarr reads), seconds.

  • t_jax (float) – Wall time spent in JAX advection (device_put + while_loop), seconds.

  • t_py (float) – Wall time spent in Python overhead (reactivation, GC, flux swap), seconds.

Return type:

None

on_run_end()[source]#

Called once after the integration loop finishes.

Return type:

None