Engine API

The simulation engine provides a wrapper around Mosaik simulation to simplify the process of creating and running simulations.

Python Interface

class illuminator.engine.Simulation(config_file: str)

Bases: object

A simplified interface to run simulations with Illuminator.

property config: dict

Returns the configuration file for the simulation.

run()

Runs a simulation scenario

Utility Functions

illuminator.engine.apply_default_values(config_simulation: dict) → dict

Applies Illuminator default values to the configuration if they are not specified.

Parameters:

config_simulation (dict) – valid Illuminator’s simulation configuration

Returns:

Illuminator’s simulation configuration with default values applied.

Return type:

dict

illuminator.engine.build_connections(world: mosaik.scenario.World, model_entities: dict[mosaik.scenario.Entity], connections: list[dict], models: list[dict]) → mosaik.scenario.World

Connects the model entities in the Mosaik world based on the connections specified in the YAML configuration file.

Parameters:

  • world (mosaik.World) – The Mosaik world object.

  • model_entities (dict) – A dictionary of model entities created for the Mosaik world.

  • connections (list) – A list of connections to be established between the model entities.

  • models (list) – The models involved in the connections based on the configuration file.

Returns:

The Mosaik world object with the connections established.

Return type:

mosaik.World

illuminator.engine.compute_mosaik_end_time(start_time: str, end_time: str, time_resolution: int = 900) → int

Computes the number to time steps for a Mosaik simulation given the start and end timestamps, and a time resolution. Values are approximated to the lowest interger.

Parameters:

  • start_time (str) – Start time as ISO 8601 time stamp. Example: ‘2012-01-01 00:00:00’.

  • end_time (str) – Start time as ISO 8601 time stamp. Example: ‘2012-01-01 00:00:00’.

  • time_resolution (number of seconds that correspond to one mosaik time step in this situation. Default is 900 secondd (15 min).)

illuminator.engine.connect_monitor(world: mosaik.scenario.World, model_entities: dict[mosaik.scenario.Entity], monitor: mosaik.scenario.Entity, monitor_config: dict) → mosaik.scenario.World

Connects model entities to the monitor in the Mosaik world.

Parameters:

  • world (mosaik.World) – The Mosaik world object.

  • model_entities (dict) – A dictionary of model entities created for the Mosaik world.

  • monitor (mosaik.Entity) – The monitor entity in the Mosaik world.

  • monitor_config (dict) – The configuration for the monitor.

Returns:

The Mosaik world object with model entities connected to the monitor.

Return type:

mosaik.World

illuminator.engine.create_world(sim_config: dict, time_resolution: int) → mosaik.scenario.World

Creates a Mosaik world object based on the simulation configuration.

Parameters:

  • sim_config (dict) – The simulation configuration for the Mosaik world.

  • time_resolution (int) – The time resolution of the simulation in seconds.

Returns:

The Mosaik world object.

Return type:

mosaik.World

illuminator.engine.generate_mosaik_configuration(config_simulation: dict, collector: str = None) → dict

Returns a configuration for the Mosaik simulator based on the Illuminators simulation definition.

Parameters:

  • config_simulation (dict) – valid Illuminator’s simulation configuration

  • collector (str) – command and path to a custom collector. If None the default collector is used. Example: ‘%(python)s Illuminator_Engine/collector.py %(addr)s’

Returns:

Mosaik’s world simulator configuration. Example:

{
    'Collector': {
        'cmd': '%(python)s Illuminator_Engine/collector.py %(addr)s'
    },
    'Model1': {
        'python': 'illuminator.models:Model1'
    },
    'Model2': {
        'python': 'illuminator.models:Model2'
    }
}

Return type:

dict