Metadata-Version: 2.4
Name: mosaik-householdsim
Version: 2.2.0
Summary: A simple mosaik simulator for household profiles
Author: Stefan Scherfke
Author-email: Stefan Scherfke <mosaik@offis.de>
License-Expression: MIT
Classifier: Development Status :: 5 - Production/Stable
Classifier: Environment :: Console
Classifier: Intended Audience :: Science/Research
Classifier: Natural Language :: English
Classifier: Operating System :: OS Independent
Classifier: Topic :: Scientific/Engineering
Requires-Dist: arrow>=1.4.0
Requires-Dist: mosaik-api-v3>=3.0.16
Requires-Python: >=3.8
Description-Content-Type: text/x-rst

HouseholdSim
============

This is pseudo simulator to serve residual load profiles to mosaik.


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