oasislmf.execution.resource_monitor
===================================

.. py:module:: oasislmf.execution.resource_monitor

.. autoapi-nested-parse::

   Resource monitor for pytools processes during model runs.

   Uses ``psutil`` to poll all active pytools processes at a configurable
   interval, capturing CPU%, cumulative CPU time (user + system), RSS,
   USS (private memory), and PSS (proportional memory, Linux only).
   Writes raw data to CSV and optionally generates a markdown report with
   plots (requires matplotlib).

   USS (Unique Set Size) is the primary memory metric — it represents memory
   private to each process and avoids the double-counting problem that RSS has
   with shared memory and memory-mapped files.

   CPU time (user + system) from ``psutil.Process.cpu_times()`` gives the
   actual processor time consumed, equivalent to TIME+ in ``top``.



Attributes
----------

.. autoapisummary::

   oasislmf.execution.resource_monitor.logger
   oasislmf.execution.resource_monitor.MONITORED_TOOLS
   oasislmf.execution.resource_monitor.CSV_HEADER
   oasislmf.execution.resource_monitor.TOOL_COLORS


Classes
-------

.. autoapisummary::

   oasislmf.execution.resource_monitor.ResourceMonitor


Module Contents
---------------

.. py:data:: logger

.. py:data:: MONITORED_TOOLS

.. py:data:: CSV_HEADER
   :value: ['timestamp', 'tool', 'pid', 'cpu_pct', 'cpu_user_s', 'cpu_sys_s', 'rss_kb', 'uss_kb', 'pss_kb']


.. py:data:: TOOL_COLORS

.. py:class:: ResourceMonitor(output_dir, poll_interval=1.0)

   Daemon-thread based resource monitor for pytools processes.

   Args:
       output_dir (str): Directory to write resource_monitor.csv into.
       poll_interval (float): Seconds between polls (default 1.0).


   .. py:attribute:: output_dir


   .. py:attribute:: poll_interval


   .. py:method:: start(bash_pid)

      Start the monitor in a daemon thread.

      Args:
          bash_pid (int): PID of the bash process running the kernel script.



   .. py:method:: stop()

      Signal the monitor to stop, wait for the thread, generate report.