# 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.
## Example
The following is an example to explain the basic format of a configuration file.
A description of each keyword and their default values can be found in the table below.
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
```
| 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 | | |