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.

init(sid, time_resolution, scenario_config, grid_model_config=None, additional_groups: dict = None, series_path=(None, None))

Initialize HDF5 Database Entity.

Parameters:

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

  • time_resolution (float) – timely resolution of the simulation scenario

  • scenario_config (dict) – configurations of the simulation

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

  • 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 grid_model_config. 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:

meta

create(num, model, filename, buf_size=1000, dataset_opts=None)

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

  • ValueError – Error 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.

Yields:

list – related entity for the simulator (given by mosaik)

step(time, inputs, max_advance)

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

  • max_advance (int) – simulation time until the simulator can safely advance it’s internal time without causing any causality errors.

Returns:

next time step (when orchestrator calls again)

Return type:

int

set_meta_data(data)

Set the meta data of the DB.

Parameters:

data (dict) – data elements to be stored (attribute with corresponding value)

set_static_data(data)

Store static (un-changeable) data into the hdf5 DB.

Parameters:

data (dict) – data elements to be stored (entity id with dict of attributes and values)

_store_relations()

Query relations graph and store it in the database.

Yields:

list – related entities of simulator (given by mosaik)

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

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

_get_group_generic(eid, supergroup)

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

Returns:

the resulting group

Return type:

Group

_get_group_default(eid)

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, config, dictionary=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, supergroup)

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)

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(group, dictionary, dataset_name)

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(group, data, dataset_name)

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)

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

_save_attrs(g, attrs)

Write an attribute with its value into the database.

Parameters:

  • g (db element) – _description_

  • attrs (dict) – data elements to be stored (attribute with corresponding value)