User’s guide

The following content will give you all information you need to couple SIMONA with mosaik.

Why is simosaik needed?

Mosaik and SIMONA are written in different programming languages that cannot be connected directly. Therefore, in order to couple SIMONA with mosaik, simosaik is used.

Simosaik uses the following APIs:

  • mosaik-java-api: The API used by mosaik, to add simulators written in java.

  • simonaAPI: The API used by SIMONA, to add external simulations.

To connect these two APIs, we created simoasik. During the co-simulation simosaik is treated like every other simulator by mosaik, while SIMONA on the other hand, sees simosaik as an external simulation.

To exchange data between mosaik and SIMONA, simosaik translates all supported information into the corresponding data format used by either mosaik or SIMONA. Simosaik also handles the synchronisation of both mosaik and SIMONA during the co-simulation.

Selecting the versions of the APIs

Simosaik comes with a version of the simonaAPI and a version of the mosaik-api-java included. To update these to a newer version go to the build.gradle file.

Steps to set up the connection

This section will give you a step-by-step instruction on how to set up the coupling.

Step 1:
The first step is to create a fat JAR (java archive) file. One simple way to do this, is to run the shadowJar task of this gradle project.

Step 2:
Since mosaik is responsible for starting the co-simulation, we also need an executable fat JAR file for SIMONA. This can be done by running the shadowJar task in the SIMONA project.

Step 3:
Add the following statement to your mosaik simulation configuration:

'SimonaPowerGrid': {
   'cmd': 'java -cp path/to/simonaJar edu.ie3.simona.main.RunSimonaStandalone --config=path/to/simona/configuration/file --ext-address=%(addr)s',
   "auto_terminate": False,
}

Step 4:
Add the following configuration to the SIMONA config file:

  • simona.input.extSimDir = "path/to/simosaikJar"

Step 5:
To start the SIMONA simulator, you need to call the start method of the mosaik world:

world.start('SimonaPowerGrid', models=[...], step_size=ticks, send_unchanged_results=False, last_tick=LAST_TICK, debug=False)

There are some parameters that can be used to tailor the behavior of the simulation.

  • models: Definition of available models (see: here)

  • step_size: The regular step size of the simulation. If you are using energy management models, SIMONA may be called with steps in between the regular steps.

  • send_unchanged_results: To specify, if SIMONA should send results that have not been changed since the last request.

  • last_tick: The last tick of the mosaik simulation.

  • debug: If true additional information is logged to the console and file output.

Configure SIMONA models

Simosaik can provide different models and combinations of models to mosaik. In order to specify the models that are available to mosaik, you need to add the models argument with a list of selected models to the world.start method:

world.start('SimonaPowerGrid', models=["p"])

An overview of the available models can be found here. Each model has a list of attributes that can be used by mosaik. An overview of all available attributes with their units and values can be found here.

Creating mosaik entities

To create mosaik entities from the SIMONA model, you need to pass the number of entities to create.

simonaActivePowerEntities = simonaSimulation.ActivePower.create(2)

SIMONA will use the mapping from Universally Unique Identifier (UUID) to id that is present in the SIMONA input data. To override this mapping or to specify, which SIMONA models will exchange data with mosaik, you can add the use parameter:

simonaActivePowerEntities = simonaSimulation.ActivePower.create(2, use=active_power_mapping)

The use parameter takes either a list of mosaik eid that have to match the ids in the SIMONA input files or a mapping from SIMONA Universally Unique Identifier (UUID) to mosaik eid. With the second option, you can map your own id to a SIMONA UUID.

An example for a mapping:

active_power_mapping = {
    "4dca3b1d-5d24-444a-b4df-f4fa23b9ef1b": "Load_Node_1",
    "9c5991bc-24df-496b-b4ce-5ec27657454c": "Load_Node_2"
}

The number of entries in the mapping must match the number of entities that is parsed as an argument.