perun.data_model.data
=====================

.. py:module:: perun.data_model.data

.. autoapi-nested-parse::

   Storage Module.



Attributes
----------

.. autoapisummary::

   perun.data_model.data.log


Classes
-------

.. autoapisummary::

   perun.data_model.data.NodeType
   perun.data_model.data.MetricType
   perun.data_model.data.AggregateType
   perun.data_model.data.Metric
   perun.data_model.data.Stats
   perun.data_model.data.RawData
   perun.data_model.data.LocalRegions
   perun.data_model.data.Region
   perun.data_model.data.DataNode


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

.. py:data:: log

.. py:class:: NodeType(*args, **kwds)

   Bases: :py:obj:`enum.Enum`


   DataNode type enum.


   .. py:attribute:: APP


   .. py:attribute:: MULTI_RUN


   .. py:attribute:: RUN


   .. py:attribute:: NODE


   .. py:attribute:: DEVICE_GROUP


   .. py:attribute:: SENSOR


.. py:class:: MetricType

   Bases: :py:obj:`str`, :py:obj:`enum.Enum`


   Metric Type enum.


   .. py:attribute:: RUNTIME
      :value: 'runtime'



   .. py:attribute:: POWER
      :value: 'power'



   .. py:attribute:: CPU_POWER
      :value: 'cpu_power'



   .. py:attribute:: GPU_POWER
      :value: 'gpu_power'



   .. py:attribute:: DRAM_POWER
      :value: 'dram_power'



   .. py:attribute:: OTHER_POWER
      :value: 'other_power'



   .. py:attribute:: CPU_UTIL
      :value: 'cpu_util'



   .. py:attribute:: GPU_UTIL
      :value: 'gpu_util'



   .. py:attribute:: OTHER_UTIL
      :value: 'other_util'



   .. py:attribute:: DRAM_MEM
      :value: 'dram_mem'



   .. py:attribute:: GPU_MEM
      :value: 'gpu_mem'



   .. py:attribute:: NET_READ
      :value: 'net_read'



   .. py:attribute:: NET_WRITE
      :value: 'net_write'



   .. py:attribute:: DISK_READ
      :value: 'disk_read'



   .. py:attribute:: DISK_WRITE
      :value: 'disk_write'



   .. py:attribute:: ENERGY
      :value: 'energy'



   .. py:attribute:: CPU_ENERGY
      :value: 'cpu_energy'



   .. py:attribute:: GPU_ENERGY
      :value: 'gpu_energy'



   .. py:attribute:: DRAM_ENERGY
      :value: 'dram_energy'



   .. py:attribute:: OTHER_ENERGY
      :value: 'other_energy'



   .. py:attribute:: OTHER_MEM
      :value: 'other_memory'



   .. py:attribute:: CPU_CLOCK
      :value: 'cpu_clock'



   .. py:attribute:: GPU_CLOCK
      :value: 'gpu_clock'



   .. py:attribute:: N_RUNS
      :value: 'n_runs'



   .. py:attribute:: MONEY
      :value: 'money'



   .. py:attribute:: CO2
      :value: 'co2'



   .. py:method:: fromString(value: str) -> MetricType

      Create MetricType from string.

      :param value: MetricType value.
      :type value: str

      :returns: MetricType object.
      :rtype: MetricType



.. py:class:: AggregateType

   Bases: :py:obj:`str`, :py:obj:`enum.Enum`


   Types of data aggregation.


   .. py:attribute:: SUM
      :value: 'sum'



   .. py:attribute:: MEAN
      :value: 'mean'



   .. py:attribute:: MAX
      :value: 'max'



   .. py:attribute:: MIN
      :value: 'min'



.. py:class:: Metric

   Struct with resulting metrics and the metadata.


   .. py:attribute:: type
      :type:  MetricType


   .. py:attribute:: value
      :type:  perun.data_model.measurement_type.Number


   .. py:attribute:: metric_md
      :type:  perun.data_model.measurement_type.MetricMetaData


   .. py:attribute:: agg
      :type:  AggregateType


   .. py:method:: fromDict(metricDict: dict[str, Any]) -> Metric
      :classmethod:


      Create RawData object from a dictionary.



   .. py:method:: copy() -> Metric

      Create copy metric object.

      :returns: Copy of object.
      :rtype: _type_



.. py:class:: Stats

   Collects statistics based on multiple metrics of the same type.


   .. py:attribute:: type
      :type:  MetricType


   .. py:attribute:: metric_md
      :type:  perun.data_model.measurement_type.MetricMetaData


   .. py:attribute:: sum
      :type:  perun.data_model.measurement_type.Number


   .. py:attribute:: mean
      :type:  perun.data_model.measurement_type.Number


   .. py:attribute:: std
      :type:  perun.data_model.measurement_type.Number


   .. py:attribute:: max
      :type:  perun.data_model.measurement_type.Number


   .. py:attribute:: min
      :type:  perun.data_model.measurement_type.Number


   .. py:method:: fromMetrics(metrics: list[Metric]) -> Stats
      :classmethod:


      Create stats object from list of metrics with the same type.

      :param metrics: List of metrics with  the same type.
      :type metrics: list[Metric]

      :returns: Stats object.
      :rtype: Stats

      :raises Exception: If metrics are not from the same type.



   .. py:property:: value
      :type: perun.data_model.measurement_type.Number


      Value property (mean).

      For compatibility with Metric dataclass.

      :returns: Return the mean value of the stats object.
      :rtype: Number


   .. py:method:: fromDict(statsDict: dict[str, Any]) -> Stats
      :classmethod:


      Stats constructor from a dictionory.



.. py:class:: RawData

   Contains timesteps and recorded values from sensors, including information on the values.


   .. py:attribute:: timesteps
      :type:  numpy.typing.NDArray[numpy.floating]


   .. py:attribute:: values
      :type:  numpy.typing.NDArray[numpy.floating | numpy.integer]


   .. py:attribute:: t_md
      :type:  perun.data_model.measurement_type.MetricMetaData


   .. py:attribute:: v_md
      :type:  perun.data_model.measurement_type.MetricMetaData


   .. py:attribute:: alt_values
      :type:  numpy.typing.NDArray[numpy.floating | numpy.integer] | None
      :value: None



   .. py:attribute:: alt_v_md
      :type:  perun.data_model.measurement_type.MetricMetaData | None
      :value: None



   .. py:method:: fromDict(rawDataDict: dict[str, Any]) -> RawData
      :classmethod:


      Create RawData object from a dictionary.

      :param rawDataDict: Dictionary with same keys as RawData object.
      :type rawDataDict: Dict

      :returns: RawData object.
      :rtype: _type_



.. py:class:: LocalRegions

   Stores local region data while an application is being monitored.


   .. py:method:: addEvent(region_name: str) -> None

      Mark a new event for the named region.

      :param region_name: Region to mark the event from.
      :type region_name: str



   .. py:method:: isEmpty() -> bool

      Check if there are any regions marked.

      :returns: True if there are no regions marked.
      :rtype: bool



.. py:class:: Region

   Stores region data from all MPI ranks.

   For each marked region (decorated function), an numpy array with timestamps indicating function starts and ends.


   .. py:attribute:: id
      :type:  str
      :value: ''



   .. py:attribute:: raw_data
      :type:  dict[int, numpy.typing.NDArray[numpy.floating]]


   .. py:attribute:: runs_per_rank
      :type:  Stats | None
      :value: None



   .. py:attribute:: metrics
      :type:  dict[MetricType, Stats]


   .. py:attribute:: processed
      :type:  bool
      :value: False



   .. py:method:: toDict() -> dict[str, Any]

      Convert regions to a python dictionary.

      :returns: Dictionary with region data.
      :rtype: dict[str, dict[int, npt.NDArray[np.floating]]]



   .. py:method:: fromDict(regionDictionary: dict[str, Any]) -> Region
      :classmethod:


      Create Regions object from a dictionary.

      :param regionDictionary: Region dictionary.
      :type regionDictionary: dict[str, dict[int, Any]]

      :returns: Regions object.
      :rtype: Regions



.. py:class:: DataNode(id: str, type: NodeType, metadata: dict[str, Any] = {}, nodes: dict[str, Any] | None = None, metrics: dict[MetricType, Metric | Stats] | None = None, deviceType: perun.data_model.sensor.DeviceType | None = None, raw_data: RawData | None = None, regions: dict[str, Region] | None = None, processed: bool = False)

   Recursive data structure that contains all the information of a monitored application.


   .. py:attribute:: id


   .. py:attribute:: type


   .. py:attribute:: metadata
      :type:  dict[str, Any]


   .. py:attribute:: nodes
      :type:  dict[str, Any]


   .. py:attribute:: metrics
      :type:  dict[MetricType, Metric | Stats]


   .. py:attribute:: deviceType
      :type:  perun.data_model.sensor.DeviceType | None
      :value: None



   .. py:attribute:: raw_data
      :type:  RawData | None
      :value: None



   .. py:attribute:: regions
      :type:  dict[str, Region] | None
      :value: None



   .. py:attribute:: processed
      :value: False



   .. py:method:: addRegionData(localRegions: list[LocalRegions], start_time: int) -> None

      Add region information to to data node.

      :param localRegions: Gathered local regions from all MPI ranks
      :type localRegions: list[LocalRegions]
      :param start_time: 'Official' start time of the run.
      :type start_time: int



   .. py:method:: toDict(include_raw_data: bool = True) -> dict[str, Any]

      Transform object to dictionary.



   .. py:method:: fromDict(resultsDict: dict[str, Any]) -> DataNode
      :classmethod:


      Create dataNode from python dictionary.

      :param resultsDict: Dictionary with data node attributes.
      :type resultsDict: Dict

      :returns: DataNode object.
      :rtype: _type_