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

edit_models(configuration: dict) → None

Updates multiple parameter values for multiple models in the simulation configuration.

Parameters:

configuration (dict) – Dictionary with model names as keys and parameter dictionaries as values. Example: {‘model1’: {‘param1’: val1}, ‘model2’: {‘param2’: val2}}

Returns:

Updates the configuration in place

Return type:

None

Raises:

KeyError – If any model name or parameter is not found in configuration

run()

Runs a simulation scenario

set_model_param(model_name: str, parameter: str, value) → None

Sets a parameter value for a specific model in the simulation configuration.

Parameters:

• model_name (str) – Name of the model to modify

• parameter (str) – Name of the parameter to set

• value (any) – New value for the parameter

Returns:

Updates the configuration in place

Return type:

None

Raises:

KeyError – If model_name or parameter is not found in configuration

set_model_parameters(model_name: str, params: dict) → None

Sets multiple parameter values for a specific model in the simulation configuration.

Parameters:

• model_name (str) – Name of the model to modify

• params (dict) – Dictionary of parameter names and their new values to set

Returns:

Updates the configuration in place

Return type:

None

Raises:

KeyError – If model_name or any parameter is not found in configuration

set_model_state(model_name: str, state: str, value) → None

Sets a state value for a specific model in the simulation configuration.

Parameters:

• model_name (str) – Name of the model to modify

• state (str) – Name of the state to set

• value (any) – New value for the state

Returns:

Updates the configuration in place

Return type:

None

Raises:

KeyError – If model_name or state is not found in configuration

set_scenario_param(parameter: str, value) → None

Sets a parameter value in the scenario section of the simulation configuration.

Parameters:

• parameter (str) – Name of the parameter to set

• value (any) – New value for the parameter

Returns:

Updates the configuration in place

Return type:

None

Raises:

KeyError – If parameter is not found in scenario configuration

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, start_time: str) → 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.

• start_time (str) – The start time of the simulation as an ISO 8601 time stamp.

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