:py:mod:`eelib.data.database.hdf5`
==================================

.. py:module:: eelib.data.database.hdf5

.. autoapi-nested-parse::

   Interface for the event-based HDF5 database.

   Within this interface mosaik functionalities are used.
   Copyright (c) LGPL

   | Author: elenia@TUBS
   | Copyright 2024 elenia
   | This file is part of eELib, which is free software under the terms of the GNU GPL Version 3.



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

Classes
~~~~~~~

.. autoapisummary::

   eelib.data.database.hdf5.Hdf5Database




Attributes
~~~~~~~~~~

.. autoapisummary::

   eelib.data.database.hdf5.meta


.. py:data:: meta

   

.. py:class:: Hdf5Database


   Bases: :py:obj:`mosaik_api.Simulator`

   HDF5 Database class
   Inherits mosaik simulator class for management.

   .. py:method:: init(sid, time_resolution, scenario_config, series_path=(None, None))

      Initialize HDF5 Database Entity.

      :param sid: string id of the entity to be created
      :type sid: str
      :param time_resolution: timely resolution of the simulation scenario
      :type time_resolution: float
      :param scenario_config: configurations of the simulation
      :type scenario_config: dict
      :param series_path: path for the series to be stored. Defaults to (None, None).
      :type series_path: tuple

      :returns: meta description of the simulator
      :rtype: meta


   .. py:method:: create(num, model, filename, buf_size=1000, dataset_opts=None)

      Creates instances of the HDF5 output database.

      :param num: Number of hdf5 db models to be created
      :type num: int
      :param model: Description of the created hdf5 db entity
      :type model: str
      :param filename: Directory of the hdf5 file
      :type filename: str
      :param buf_size: Number of elements to be stored before writing into DB. Defaults to 1000
      :type buf_size: int
      :param dataset_opts: Potential set of options for the dataset. Defaults to None.
      :type dataset_opts: dict

      :raises ValueError: Error if more than one hdf5 DB is to be created
      :raises ValueError: Error if an unknown model type (not Database) is given

      :returns: discription of the hdf5 DB entity with ID, type and relations
      :rtype: dict


   .. py:method:: setup_done()

      Check if setup of the DB is done.

      :Yields: *list* -- related entity for the simulator (given by mosaik)


   .. py:method:: step(time, inputs, max_advance)

      Performs simulation step saving/buffering data and storing it into the DB.
      Core function of mosaik.

      :param time: current simulation time (given by mosaik)
      :type time: int
      :param inputs: allocation of return values to specific models
      :type inputs: dict
      :param max_advance: simulation time until the simulator can safely advance it's
                          internal time without causing any causality errors.
      :type max_advance: int

      :returns: next time step (when orchestrator calls again)
      :rtype: int


   .. py:method:: _store_relations()

      Query relations graph and store it in the database.

      :Yields: *list* -- related entities of simulator (given by mosaik)


   .. py:method:: _create_dataset(src_id, attr, dtype, ds_size, buf, buf_size)

      Create a dataset for the attribute ``attr`` of entity ``src_id``. The dataset will use
      the type ``dtype`` and will have the size ``ds_size``. Also initialize the buffer ``buf``
      with size ``buf_size``.

      :param src_id: entity for the dataset to be stored in hdf5 file
      :type src_id: str
      :param attr: attribute to be saved
      :type attr: str
      :param dtype: Type of the attribute
      :type dtype: type
      :param ds_size: number of data elements to be stored
      :type ds_size: int
      :param buf: storing of buffered elements within a list
      :type buf: dict
      :param buf_size: number of elements to be buffered before storing
      :type buf_size: int


   .. py:method:: _get_group(eid)

      Get or create group for entity ``eid``.

      :param eid: entity identification string
      :type eid: str

      :returns: hdf5 file group element for data to be stored into
      :rtype: Group


   .. py:method:: _get_supergroup(eid)

      Get or create supergroup for entity ``eid`` using ``pattern``.

      :param eid: entity identification string
      :type eid: str

      :raises ValueError: Error if entity ID was not given in correct format

      :returns: supergroup for the data to be stored into
      :rtype: SuperGroup


   .. py:method:: _store_dict(group, dictionary, dataset_name)

      Store a dictionary as a dataset in a given group.

      :param dictionary: dictionary to be stored
      :type dictionary: dict
      :param group: the group to store the data in
      :type group: Group
      :param dataset_name: the name of the dataset
      :type dataset_name: str


   .. py:method:: _store_json(group, data, dataset_name)

      Store json-like data as a dataset in a given group.

      :param data: data to be stored
      :type data: Any
      :param group: the group to store the data in
      :type group: Group
      :param dataset_name: the name of the dataset
      :type dataset_name: str


   .. py:method:: _get_entity_path(eid)

      Get the database path to a searched entity by its ID.

      :param eid: identification number of the entity to be searched
      :type eid: str

      :returns: path to the entity
      :rtype: str