# 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
`.`. Input names
use here must also appear as *inputs* in
the models section. | | |
| `to` | destination of the connection declared as
`.`. 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
`.`, 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.
```yaml
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](https://illuminator-team.github.io/Illuminator/user/connections.html) documentation page.