How mosaik communicates with a simulator

This section provides a general overview which API calls exists and when mosaik calls them. The following sections will go into more detail.

When the connection between a simulator and mosaik is established, mosaik will first call init(), optionally passing some global parameters to the simulator. The simulators returns some meta data describing itself.

Following this, mosaik may call create() multiple times in order to instantiate one of the models that the simulator implements. The return value contains information describing the entities created.

The end of create phase and the beginning of the step (or simulation) phase is marked by a call to setup_done(). At this point, all entities are created and all relations between them are established.

When the simulation has been started, mosaik repeatedly calls step(). This allows the simulator to step forward in time. It returns the time at which it wants to perform its next step.

Finally, mosaik sends a stop() message to every simulator to request its shut-down.

The following figure depicts the sequence of these messages:

Main sequence diagram for the mosaik API.

After create() or step() have been called, there may be an arbitrary amount of get_data() calls where mosaik requests the current values of some entities’ attributes:

Sequence diagram for the get_data() API call.

These methods are usually sufficient to connect simple simulators to mosaik. However, control strategies, visualizations or database adapters may need to actively query mosaik for additional data.

Thus, while a simulator is executing a simulation step, it may make asynchronous requests to mosaik. It can collect information about the simulated topology (get_related_entities()), request a new step for itself (set_event()), get the current simulation progress (get_progress()), query other entities for data (get_data()) and set data for other entities (set_data()).

Sequence diagram for asynchronous requests made by a simulator.

The next two sections explain the low-level API and the Python high-level API in more detail. The last section, High-level APIs in other languages, presents APIs available for other popular programming languages.