: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:attribute:: eid :value: "'hdf5db'" .. py:attribute:: sid :value: 'None' .. py:attribute:: step_size :value: 'None' .. py:attribute:: duration :value: 'None' .. py:attribute:: ds_size :value: 'None' .. py:attribute:: series_path :value: 'None' .. py:attribute:: series_path_repl :value: 'None' .. py:attribute:: db :value: 'None' .. py:attribute:: rels :value: 'None' .. py:attribute:: series :value: 'None' .. py:attribute:: buf_size :value: 'None' .. py:attribute:: dataset_opts .. py:attribute:: config :value: 'None' .. py:attribute:: scenario_config :value: 'None' .. py:attribute:: db_structure :value: 'None' .. py:attribute:: eid_path .. py:attribute:: data_buf .. py:method:: init(sid: str, scenario_config: dict, db_structure: dict = None, delimiter: str = '@', additional_groups: dict = None, series_path: tuple = (None, None)) -> dict Initialize HDF5 Database Entity. :param sid: string id of the entity to be created :type sid: str :param scenario_config: configurations of the simulation :type scenario_config: dict :param db_structure: configuration of order of the series in the resulting database. If not given a default structure is used. :type db_structure: dict :param delimiter: symbol to separate nested data recieved from HEMS simulator. This should be a character that is not otherwise used in the names and paths. :type delimiter: str :param additional_groups: additional groupings not defined in the model config If not given all unmatched components are stored in a ``misc`` grouping. Nested dictionaries and arrays as values are permissible. Assignment of a component to one of these groups is only possible if it is not already assigned to another group provided in db_structure. In that case, assignment is determined by component eid string including one of the lowest level strings (group names) provided here OR matching the regular expression, if the lowest level strings are regexes. Additionally, names defined first have priority. An example of this is as follows: {"E1": ["S1", "S2"], "E2": "S3", "E3": {"T1":"S8", "T2":[r'^ABC\-(.*)', "S9"]}} :type additional_groups: 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: dict .. py:method:: create(num: int, model: str, filename: str, buf_size: int = 1000, dataset_opts: dict = None) -> dict 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 OR 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. .. py:method:: step(time: int, inputs: dict) -> int 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 :raises ValueError: When ``len(inputs) != 1``. :returns: next timestep (when orchestrator calls again) :rtype: int .. py:method:: _store_relations() -> Generator[dict, None, None] Queries the relations graph and stores it in the database. .. py:method:: _create_dataset(src_id: str, attr: str, dtype: type, ds_size: int, buf: dict, buf_size: int, delimiter: str = None) -> None 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 :param delimiter: symbol to separate nested data recieved from HEMS simulator :type delimiter: str :returns: Nothing is returned :rtype: None .. py:method:: _get_group_generic(eid: str, supergroup: h5py.Group, group_name: str = None) -> h5py.Group Generic method for creating and/or finding a group within a supergroup. :param eid: entity id corresponding to the group to be found/created :type eid: str :param supergroup: the supergroup where the search/creation occurs :type supergroup: Group :param group_name: group name in case different name is preferred :type group_name: str :returns: the resulting group :rtype: Group .. py:method:: _get_group_default(eid: str) -> h5py.Group Get or create group for entity ``eid`` based on the default structure. :param eid: entity identification string :type eid: str :raises ValueError: if the given eid format does not match the predefined pattern :returns: hdf5 file group element for data to be stored into :rtype: Group .. py:method:: _create_groups_preset(supergroup: h5py.Group, config: dict, dictionary: dict = None) Recursive method to create groups based on a preset dictionary. :param supergroup: supergroup where creation occurs. Initial input is where all the series are stored. :type supergroup: Group :param config: the configuration dictionary. :type config: dict :param dictionary: if provided, the given dictionary is updated with pairs of group names and Group objects for the groups at the lowest level. :type dictionary: dict .. py:method:: _find_group_preset(eid: str, supergroup: h5py.Group) -> h5py.Group Recursive method to find a group within a supergroup. :param eid: entity id corresponding to the group to be found :type eid: str :param supergroup: the supergroup where the search occurs :type supergroup: Group :raises ValueError: if the given eid format does not match the predefined pattern :returns: the resulting group OR ``None`` if it doesn't exist :rtype: Group .. py:method:: _get_group_additional(eid: str) -> h5py.Group Get or create group for entity ``eid`` in a group among those added in addition to model config, if applicable. :param eid: entity id corresponding to the group to be found :type eid: str :returns: the first possible group OR ``None`` if it isn't applicable :rtype: Group .. py:method:: _store_dict(dictionary: dict, group: h5py.Group, dataset_name: str) 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(data: any, group: h5py.Group, dataset_name: str) 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: str) -> str 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