eelib.data.database.hdf5

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

Hdf5Database

HDF5 Database class

Attributes

meta

meta
class Hdf5Database

Bases: mosaik_api.Simulator

HDF5 Database class Inherits mosaik simulator class for management.

eid = "'hdf5db'"
sid = 'None'
step_size = 'None'
duration = 'None'
ds_size = 'None'
series_path = 'None'
series_path_repl = 'None'
db = 'None'
rels = 'None'
series = 'None'
buf_size = 'None'
dataset_opts
config = 'None'
scenario_config = 'None'
db_structure = 'None'
eid_path
data_buf
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.

Parameters:

  • sid (str) – string id of the entity to be created

  • scenario_config (dict) – configurations of the simulation

  • db_structure (dict) – configuration of order of the series in the resulting database. If not given a default structure is used.

  • delimiter (str) – symbol to separate nested data recieved from HEMS simulator. This should be a character that is not otherwise used in the names and paths.

  • additional_groups (dict) – 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”]}}

  • series_path (tuple) – path for the series to be stored. Defaults to (None, None)

Returns:

meta description of the simulator

Return type:

dict

create(num: int, model: str, filename: str, buf_size: int = 1000, dataset_opts: dict = None) → dict

Creates instances of the HDF5 output database.

Parameters:

  • num (int) – Number of hdf5 db models to be created

  • model (str) – Description of the created hdf5 db entity

  • filename (str) – Directory of the hdf5 file

  • buf_size (int) – Number of elements to be stored before writing into DB. Defaults to 1000

  • dataset_opts (dict) – Potential set of options for the dataset. Defaults to None.

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

Return type:

dict

setup_done()

Check if setup of the DB is done.

step(time: int, inputs: dict) → int

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

Parameters:

  • time (int) – current simulation time (given by mosaik)

  • inputs (dict) – allocation of return values to specific models

Raises:

ValueError – When len(inputs) != 1.

Returns:

next timestep (when orchestrator calls again)

Return type:

int

_store_relations() → Generator[dict, None, None]

Queries the relations graph and stores it in the database.

_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.

Parameters:

  • src_id (str) – entity for the dataset to be stored in hdf5 file

  • attr (str) – attribute to be saved

  • dtype (type) – Type of the attribute

  • ds_size (int) – number of data elements to be stored

  • buf (dict) – storing of buffered elements within a list

  • buf_size (int) – number of elements to be buffered before storing

  • delimiter (str) – symbol to separate nested data recieved from HEMS simulator

Returns:

Nothing is returned

Return type:

None

_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.

Parameters:

  • eid (str) – entity id corresponding to the group to be found/created

  • supergroup (Group) – the supergroup where the search/creation occurs

  • group_name (str) – group name in case different name is preferred

Returns:

the resulting group

Return type:

Group

_get_group_default(eid: str) → h5py.Group

Get or create group for entity eid based on the default structure.

Parameters:

eid (str) – entity identification string

Raises:

ValueError – if the given eid format does not match the predefined pattern

Returns:

hdf5 file group element for data to be stored into

Return type:

Group

_create_groups_preset(supergroup: h5py.Group, config: dict, dictionary: dict = None)

Recursive method to create groups based on a preset dictionary.

Parameters:

  • supergroup (Group) – supergroup where creation occurs. Initial input is where all the series are stored.

  • config (dict) – the configuration dictionary.

  • dictionary (dict) – if provided, the given dictionary is updated with pairs of group names and Group objects for the groups at the lowest level.

_find_group_preset(eid: str, supergroup: h5py.Group) → h5py.Group

Recursive method to find a group within a supergroup.

Parameters:

  • eid (str) – entity id corresponding to the group to be found

  • supergroup (Group) – the supergroup where the search occurs

Raises:

ValueError – if the given eid format does not match the predefined pattern

Returns:

the resulting group OR None if it doesn’t exist

Return type:

Group

_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.

Parameters:

eid (str) – entity id corresponding to the group to be found

Returns:

the first possible group OR None if it isn’t applicable

Return type:

Group

_store_dict(dictionary: dict, group: h5py.Group, dataset_name: str)

Store a dictionary as a dataset in a given group.

Parameters:

  • dictionary (dict) – dictionary to be stored

  • group (Group) – the group to store the data in

  • dataset_name (str) – the name of the dataset

_store_json(data: any, group: h5py.Group, dataset_name: str)

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

Parameters:

  • data (any) – data to be stored

  • group (Group) – the group to store the data in

  • dataset_name (str) – the name of the dataset

_get_entity_path(eid: str) → str

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

Parameters:

eid (str) – identification number of the entity to be searched

Returns:

path to the entity

Return type:

str