Simulation Configuration File

Simulation scenarios for the Illuminator are defined using configuration files written in YAML. The structure of a configuration must be as in the example below.

A simulation file has four main sections:

scenario: defines metadata and global variable for the simulation.
models: defines which models are included in the simulation.
connections: defines how the models in the models section must be connected for a particular simulation.
monitor: defines which inputs, outputs, and states of a particular model must be monitored and logged during simulation.

Hierarchy of Illuminator scenario space. Scenarios include models, models include attributes, attributes consist of inputs, outputs, states and parameters.

Note

If you are familiar with mosaik, you are probably familiar with its attributes. Illuminator Attributes are not related to mosaik attributes, the Illuminator User Documentation keeps the connection to mosaik as opaque as possible.

Simulation yaml file fields

A description of each keyword and their default values can be found in the table below.

Keyword	Description	Optional	Default
scenario:	a set of global values for a simulation.
`name`	A name for the simulation, internally this name will be asssigned to what the Mosaik World created during runtime.
`start_time`	start time for the simulation. Must be a timestamp in ISO 8601 format
`end_time`	end time for the simulation. Must be a timestamp in ISO 8601 format.
`time_resolution`	number of seconds between simulation steps	☑	900 (15 min)
models:	a list of models for the simulation
`name`	a name for the model. Must be unique for each simulation
`type`	type of model. This must correspond with the name of the model registered in the Illuminator.
`inputs`	a set of input-names and initial values for the model. The model type determines which names and values are applicable to each model, and they must be declared accordingly. Inputs are optional		If the value is set to `null`, the default value will be used. See the respective model type for details.
`outputs`	a set of output-names and initial values for the model. Similar to inputs valid names and values for each model are determined by the model type. See the respective model type for details.		If the value is set to `null`, the default value will be used.
`parameters`	a set of name-value pairs for the model. Parameters declared constants for a model during runtime.	☑	If ommited, the default values will be used. See the respective model type for details.
`states`	a set of name-value pairs considered as states for the model. The values modify the internal initial values of a state.	☑	If ommited, the default values will be used. See the respective model type for details.
`triggers`	names of inputs, output or states that are use as triggers for a particular model. Triggers can only be declared by models that implement the event-based paradigm. See the respective model type to know if it accepts triggers.	☑
`connect`	to declare in which client a model runs when using a Raspberry Pi cluster.	☑
`ip`	Ip of the client manchine that will run the model. Only IP version 4 format.
`port`	TCP port to use to connect to the client machine	☑
connections:	how models connect to each other.
`from`	origin of the connection declared as `<model-name>.<output-name>`. Input names use here must also appear as inputs in the models section.
`to`	destination of the connection declared as `<model-name>.<input-name>`. Output names use here must also appear as outputs in the models section.
monitor:
`file`	path to a CSV file to store results of the simulation. File will be created if necessary.	☑	a `out.csv` file saved to the current directory
`items`	a list of which inputs, outputs or states of models that most be monitored during runtime. Items must be declared as `<model-name>.<name>`, where name is an input, output or stated clared in the models section. No duplicated values are allowed

Example

The following is an example to explain the basic format of a configuration file.

Optinal keywords can be ommitted, in those cases the defaults will be used.

scenario:
  name: "WindTest" # in mosaik so called world
  start_time: '2012-01-01 00:00:00' # ISO 8601 start time of the simulation
  end_time: '2012-01-01 01:00:00' # ISO 8601 end time of the simulation 
  time_resolution: 900 # time step in seconds (optional). Defaults to 15 minutes (900 s)
models: # list of models for the energy network
- name: CSVB # name for the model (must be unique)
  type: CSV # type of the model registered in the Illuminator
  parameters: # a CSV model must have a start time and a file as its parameters
    start: '2012-01-01 00:00:00' # ISO 8601 start time of the simulation
    file_path: './examples/wind_test.csv' # path to the file with the data
    delimiter: ','
    date_format: 'YYYY-MM-DD HH:mm:ss'

- name: Wind1
  type: Wind # models can reuse the same type
  parameters:
    p_rated: 73548  # Rated power output (kW) of the wind turbine at the rated wind speed and above.
    u_rated: 100  # Rated wind speed (m/s) where the wind turbine reaches its maximum power output.
    u_cutin: 1  # Cut-in wind speed (m/s) below which the wind turbine does not generate power.
    u_cutout: 1000  # Cut-out wind speed (m/s) above which the wind turbine stops generating power to prevent damage.
    cp: 0.40  # Coefficient of performance of the wind turbine, typically around 0.40 and never more than 0.59.
    diameter: 30  # Diameter of the wind turbine rotor (m), used in calculating the swept area for wind power production.
    output_type: 'power'  # Output type of the wind generation, either 'power' (kW) or 'energy' (kWh).
  inputs:
    u: 0  # Wind speed (m/s) at a specific height used to calculate the wind power generation.
  outputs:
    wind_gen: 0  # Generated wind power output (kW) or energy (kWh) based on the chosen output type (power or energy).
    u: 0  # Adjusted wind speed (m/s) at 25m height after converting from the original height (e.g., 100m or 60m).

connections:
- from: CSVB.u
  to: Wind1.u

monitor:
  file: './out_Wind.csv'
  items:
  - Wind1.wind_gen
  - Wind1.u

The layout is more clearly presented below. We connect the example yaml to the hierarchy we previously introduced.

Correlation between introduced scenario hierarchy and example yaml file, the file is also structured mostly hierarchically.

To see more on Illuminator connections, and understand the difference between data and physical connections, consult the Connections documentation page.