Installation

$ pip install mosaik-householdsim

Tests

You can run the tests with:

$ git clone https://gitlab.com/mosaik/mosaik-householdsim
$ cd mosaik-householdsim
$ uv run pytest

Documentation

This simulator consists of a model (mosaik_components/household/model.py) and the mosaik API implementation (mosaik_components/household/mosaik.py).

Start it in your mosaik simulation using this Python import string:

mosaik_components.household:Simulator

(the legacy version householdsim.mosaik:HouseholdSim also still works).

The model processes the data from a .data file, optionally gzipped. See the Data format section below for details. Basically, the file contains a number of load profiles for a given period of time. It also contains ID lists that describe which load profile belongs to which node ID in a power grid. The first entry in an ID list relates to the first entry of the profiles list, the second entry in the ID list to the second load profile and so on. If the number of entries in the ID list is larger than the number of load profiles, we start again with the first load profile.

Internally, the model works with minute. Since mosaik allows to set the time resolution in the scenario (seconds as default), the mosaik API implementation converts between them.

Usually, residual load profiles have a resolution of 15 minutes. It is no problem for this simulator to step in 1 minute steps, though.

Data format

The data files used by this simulator use a custom format; essentially a CSV file with some header information. See tests/data/test.data for an example. The file consists of 4 sections, each beginning with a header line, # meta, # id_lists, # attrs, and # profiles, in this order. These section must contain the following:

# meta: A single line of JSON which is an object with the keys

• unit (specifying the physical unit of values used),

• resolution (the resolution of the data in the later profiles in minutes),

• start_date (the start date of the simulation in the format YYYY-MM-DD HH:mm, optionally with seconds as well)

• num_profiles (the number of different profiles)

# id_lists: A JSON object (this time potentially over multiple lines). Each entry maps a grid name to a list of node IDs. The grid name will be given when creating the ResidentialLoads entity in the simulator to select which node ID list to use for the simulation. The ResidentialLoads entity will have one House child entity for each node ID in the list. The houses will use the profiles listed in the next two sections, going from left to right and repeating the profiles cyclically if necessary.

# attrs: Two lines of comma-separated values. The first column must contains num_hh and num_residents, respectively After that, there must be num_profiles columns of integers (where num_profiles is from the meta section). This information is not actually used, currently. (But it needs to be present.)

# profiles: The actual profiles as CSV. The first column is a datetime in the format YYYY-MM-DD HH:mm (plus optional seconds). Then there must be num_profiles columns holding the actual data as floats. The values will be returned as-is, or multiplied by -1 if the simulator is started with pos_loads=False.