Input files¶

Study structure¶

Like the Antares solver, the Antares modeler input is a directory, that should be organized by the user as follows:

root directory with any name
- input: a directory that contains all input files
  - model-libraries: a directory that contains all model libraries needed by the study
  - data-series: a directory that contains all data series needed by the study
    - Contains modeler-scenariobuilder.dat file, which is used to map scenarios to data series
  - system.yml: the system file describing the simulated energy system
- parameters.yml: the parameters file

Note that Antares will automatically create an output directory to write the modeler outputs.

Model libraries¶

The model libraries directory shall contain all the model library files needed to run the study.
A model library is a collection of models that are published together in one source.
The study can rely on only one library, or can mix models from different libraries.

Currently, Antares modeler supports libraries that are each defined in a single yml file.

The header of the yml file must contain exactly one "library" key at the root level.
The library object contains one id, one description, one port-types collection, and one models collection.
Unless stated otherwise, all listed fields are mandatory.

ID & description¶

Example:

library:
  id: my_library_id
  description: my library is great!

id: the unique ID for you library. Beware that if you are using many libraries in your study, every library must have a unique ID. This ID will be used inside the system description file in order to reference the library's objects. It must respect these rules.
description (optional): a free description of your library. Has no effect on the simulation.

Port types¶

The port-types collection lists the possible types of ports inside the library, that can be used by models/components to communicate with each-other.
This field is optional: you can develop a library with no ports, even though this would have limited interest (the models would not be able to communicate with each-other).
Example:

port-types:
- id: dc_port
  description: A port which transfers power flow value
  fields:
  - id: flow
- id: ac_port
  description: A port which transfers power flow and voltage angle values
  fields:
  - id: flow
  - id: angle

id: the ID for the port type. Must be unique inside the scope of the library, and respect these rules.
description (optional): a free description of your port type. Has no effect on the simulation.
fields: a collection of coherent fields that transit through this port type. A field holds a single floating number.
- id: the ID of the field. Must be unique in the scope of the port type, and respect these rules.
area-connection (optional): used only for hybrid (solver x modeler) studies, ignored by antares-modeler. For more information on hybrid studies, see the relevant documentation.

Models¶

The models collection lists all the models that can be instantiated using your library.
Example:

models:
- id: generator_dc
  description: A simple DC model of a generator
  parameters:
  - id: min_active_power_setpoint
    time-dependent: false
    scenario-dependent: false
  - id: max_active_power_setpoint
    time-dependent: true
    scenario-dependent: true
  - id: proportional_cost
    time-dependent: false
    scenario-dependent: true

  variables:
  - id: is_on
    variable-type: boolean
    lower-bound: 0
    upper-bound: 1
    time-dependent: true
    scenario-dependent: true
  - id: active_power
    variable-type: continuous
    lower-bound: 0
    upper-bound: max_active_power_setpoint

  constraints:
  - id: respect_min_p
    expression: active_power >= is_on * min_active_power_setpoint

  objective-contributions:
  - id: objective
    expression: active_power * proportional_cost

  ports:
  - id: injection
    type: dc_port

  port-field-definitions:
  - port: injection
    field: flow
    definition: active_power

  extra-outputs:
  - id: total_cost_in_millions
    expression: sum(active_power * proportional_cost) / 1000000

- id: node
  description: A balance node with injections (productions and loads)
  ports:
  - id: injections
    type: dc_port
  binding-constraints:
  - id: balance
    expression: sum_connections(injections.flow) = 0

id: an ID for the model. Must be unique inside the scope of the library, and respect these rules.
description (optional): a free description of the model. Has no effect on the simulation.
parameters (optional): a collection of parameters for the model. The values for these parameters will be set in the system file.
- id: an ID for the parameter. Must be unique inside the scope of the model, and respect these rules.
- time-dependent (optional): true or false, indicates whether the parameter depends on time or is constant across the whole simulation horizon. Defaults to true.
- scenario-dependent (optional): true or false, indicates whether the parameter changes depending on the simulated scenario, or is the same for all scenarios. Defaults to true.
variables (optional): a collection of optimization variables that are defined for this model
- id: an ID for the variable. Must be unique inside the scope of the model, and respect these rules.
- variable-type: continuous, integer, or binary
- lower-bound (optional): an expression representing the lower bound of the variable. The expression inside the parentheses must evaluate to a scalar. and/or parameters only. If missing, defaults to -inf for continuous and integer types, or 0 for binary.
- upper-bound (optional): an expression representing the upper bound of the variable. The expression inside the parentheses must evaluate to a scalar. and/or parameters only. If missing, defaults to +inf for continuous and integer types, or 1 for binary.
- time-dependent (optional): true or false, indicates whether the variable depends on time or is constant across the whole simulation horizon. Defaults to true.
- scenario-dependent (optional): true or false, indicates whether the parameter changes depending on the simulated scenario, or is the same for all scenarios. Defaults to true.
constraints (optional): a collection of "internal" optimization constraints set by the model
- id: an ID for the constraint. Must be unique inside the scope of the model, and respect these rules.
- expression: an expression representing the constraint. Can use scalars, parameters, internal variables, time and scenario operators. Must contain exactly one comparison operator (=, <=, or >=).
binding-constraints (optional): a collection of "external" optimization constraints set by the model, that use ports. While these have no real difference with "internal constraints", it is best practice to separate internal and external constraints in order to make the model more readable.
- id: an ID for the constraint. Must be unique inside the scope of the model, and respect these rules.
- expression: an expression representing the constraint. Can use scalars, parameters, internal variables, ports, and time, scenario, and port operators.
objective-contributions (optional): an collection of contributions to the objective function
- id: an ID for the objective contribution. Must be unique inside the scope of the model, and respect these rules.
- expression: an expression representing the (additive) participation of the model to the optimization objective. Note that minimization is implied. The expression can use scalars, parameters and variables of the model.
ports (optional): a collection of ports exposed by the model, either as input or output
- id: an ID for the port. Must be unique in the scope of the model, and respect these rules.
- type: the type of the port. Must refer to the ID of a port type defined in the port types section.
port-field-definitions (optional): a collection of definitions for ports output by this model. Note that if the model is to define a port, then it must define all fields of this port.
- port: the ID of a port exposed by the model (defined in the ports section above)
- field: the field to define (refers to a field ID defined in the port type)
- definition: an expression representing the definition of the field. Can use scalars, parameters, and variables of the model.
extra-outputs (optional): a collection of outputs relevant to the model, that can be computed after optimization (i.e. using the optimal values of the variables). The values of these extra outputs will appear in the output files along with variable and port values.
- id: an ID for the extra-output. Must be unique inside the scope of the model, and respect these rules.
- expression: the expression of the output. Can use all operators, as long as the expression can be evaluated after optimization. Note that using an output's id in another output's expression is not allowed.

Expressions¶

An expression is a human-readable equation that allows a large flexibility in defining objects of optimization.

System file¶

The system file describes the energy system that is to be simulated, by listing the components and the port connections.
Currently, Antares modeler supports importing the system from a yaml file.

The header of the yml file must contain exactly one "system" key at the root level.
The system object contains one id, one description, one model-libraries collection, one components collection.
Unless stated otherwise, all listed fields are mandatory.

ID, description, and model libraries¶

Example:

system:
  id: my_system
  description: my system is even greater!
  model-libraries: my_library_id, my_other_library_id

id: an ID for your system. Has no effect on the simulation.
description (optional): a free description of your system. Has no effect on the simulation.
model-libraries (optional): a collection of model libraries needed for your system. If provided, must contain at least one element, and refer to IDs of model libraries found in the input/model-libraries directory. Beware that the ID of the library is one defined in its header, not the name of the file.

Components¶

The components section lists all the components of your simulated system.
Example:

components:
- id: generator1
  model: my_lib_id.dc_generator
  scenario-group: thermal_group
  parameters:
  - id: min_active_power_setpoint
    time-dependent: false
    scenario-dependent: false
    value: 100
  - id: max_active_power_setpoint
    time-dependent: true
    scenario-dependent: true
    value: generator1_max_p
  - id: proportional_cost
    time-dependent: false
    scenario-dependent: true
    value: generator1_cost
- id: generator2
  model: my_lib_id.dc_generator
  scenario-group: hydro_group
  parameters:
  - id: min_active_power_setpoint
    time-dependent: false
    scenario-dependent: false
    value: 20
  - id: max_active_power_setpoint
    time-dependent: true
    scenario-dependent: false
    value: generator2_max_p
  - id: proportional_cost
    time-dependent: false
    scenario-dependent: false
    value: 0.5
- id: node1
  model: my_lib_id.node

id: an ID for the component. Must be unique in the scope of the system, and respect these rules.
model: the ID of the model to use for the component, composed as "library_id.model_id", where "library_id" is the ID of the model library (must be listed in the required model libraries), and "model_id" is the ID of the model as it is defined inside the model library.
scenario-group (only needed if the model has scenario-dependent parameters): the ID of the scenario group this component belongs to. Must be correctly configured in the scenario builder, and respect these rules. Default value is "" (empty string).
parameters (not needed if model has no parameters): a collection of values for the model's parameters. Note that all the parameters of the model should have their values assigned by the component.
- id: the ID of the parameter, as defined by the model
- time-dependent: true or false, indicates whether the parameter depends on time or is constant across the whole simulation horizon. If the model parameter is not time-dependent, this can't be set to true.
- scenario-dependent: true or false, indicates whether the parameter changes depending on the simulated scenario, or is the same for all scenarios. If the model parameter is not scenario-dependent, this can't be set to true.
- value: the value of the parameter:
  - If the parameter is constant, then this is a numerical value (using a data-series ID is not allowed in this case)
  - If the parameter is time-dependent, then this is the ID of a time-dependent data serie
  - If the parameter is scenario-dependent, then this is the ID of a scenario-dependent data serie
  - If the parameter is time and scenario-dependent, then this is the ID of a time-and-scenario-dependent data serie
  Note that using an expression is not allowed (e.g. neither 3 * 4, nor 6 * some_time_series).

Port connections¶

The connections section lists the port connections between components.
Example:

connections:
- component1: generator1
  port1: injection
  component2: node1
  port2: injections
- component1: generator2
  port1: injection
  component2: node1
  port2: injections

component1, component2: the IDs of the components to connect together
port1, port2: the IDs of the respective ports to connect (as defined by the two models). Note that exactly one of the two models must define the port (in the "port-field-definition" section).

Area connections¶

The area-connections section is used only for hybrid (solver x modeler) studies, and is ignored by antares-modeler.
For more information on hybrid studies, see the relevant documentation.

Optim-config file¶

The optim-config.yml file is an optional configuration file used in hybrid studies to specify the optimization resolution mode. When present, it should be placed in the input/ directory alongside other modeler files.

Resolution mode¶

The resolution-mode field specifies the optimization resolution mode to use. This field is optional and defaults to sequential-subproblems if not specified.

Available values:

sequential-subproblems (default): Each Monte-Carlo year is optimized separately. This mode does not support scenario-independent variables.
benders-decomposition: Uses Benders decomposition method to solve the optimization problem. This mode is designed for investment studies and allows the use of scenario-independent variables in the master problem.

Example:

resolution-mode: benders-decomposition

Model decomposition configuration¶

The models section allows you to explicitly configure where model elements (variables, constraints, objective contributions) appear in the optimization hierarchy (master, subproblems, or master-and-subproblems). This overrides the default behavior determined by variable and parameter properties (such as scenario-dependent flags).

Example:

models:
  - id: lib_thermal_invest.thermal_candidate
    model-decomposition:
      variables:
        - id: nb_units
          location: master
        - id: pmax_cluster
          location: master-and-subproblems
      constraints:
        - id: constr1
          location: master
      objective-contributions:
        - id: invest_objective
          location: master
        - id: operational_objective
          location: subproblems

Configuration keys:

id: Model identifier in the format library_id.model_id (referencing a model from your model libraries)
model-decomposition:
- variables (optional): Override default variable locations
- constraints (optional): Override default constraint locations
- objective-contributions (optional): Override default objective contribution locations
- Each entry requires:
  - id: Element ID as defined in the model library
  - location: One of master, subproblems, or master-and-subproblems

Location semantics:

master: Element appears only in the master problem (investment decisions)
subproblems: Element appears only in subproblems (operational decisions, per scenario)
master-and-subproblems: Element appears in both master and subproblems

For investment studies with benders-decomposition, it's common to place investment decisions in master and operational decisions in subproblems.

Out-of-bounds processing for shifted constraints¶

The out-of-bounds-processing section lets you control how time-shifted constraints are handled when a shifted term falls outside the current optimization block, for example x[t+1] on the last timestep of a block.

This configuration currently applies to constraints only.

Example:

models:
  - id: andromede.my_storage
    model-decomposition:
      constraints:
        - id: level_dynamics
          location: subproblems
    out-of-bounds-processing:
      constraints:
        - id: level_dynamics
          mode: drop

Configuration keys:

out-of-bounds-processing:
- constraints (optional): override out-of-bounds handling for specific constraints
- Each entry requires:
  - id: Constraint ID as defined in the model library
  - mode: One of cyclic or drop

Modes:

cyclic (default): shifted terms wrap around within the local block
drop: the constraint is not instantiated for timesteps where at least one shifted term falls outside the local block

Each configured constraint id must reference an existing constraint of the model.

Data series¶

The input/data-series directory contains all data-series needed by the system description to define component parameter values.

Currently, Antares modeler supports defining data-series using .csv or .tsv files. Values can be separated using either tabs or spaces, and the character . represents the floating point.

Naming¶

TSV files inside the directory should respect the "XXX.tsv" or the "XXX.csv" naming template, where "XXX" is the ID of the data-series. Thus, this ID must be unique, and is the one to be used in the system file.

Time-dependent series¶

To define a time-dependent series, define a column vector, where every timestamp is represented by a row.
Example file for a simulation with 6 timestamps:

Note that Antares modeler performs basic structural checks on data-series (consistent number of columns per row, valid numeric values), but does not validate that the data covers the full time horizon of the simulation. It is up to you to ensure the rows cover the required time steps.

Scenario-dependent series¶

To define a parameter value that changes depending on the scenario, define a row vector, where every data set is represented by a column.
You can use the scenario builder to map different scenarios to the data sets, in order to avoid duplicating data.
Example file for a simulation with 4 scenarios:

54 67.5 23.652 253

Time and scenario-dependent series¶

Use the two methods described above.
Example file for a simulation with 2 timestamps and 3 scenarios:

2345 1243 123
2378 748  0

Rules for IDs¶

All IDs in the model library and system file must respect the following:

Alphanumeric characters are allowed, as well as the underscore (_) character
All other characters are prohibited
Only lower-case is allowed

Scenario builder¶

The modeler-scenariobuilder.dat file, located in the data-series directory, is used to map scenarios to data series. This feature is optional; if the file is not present, scenario groups will not be used. Each line consists of the association of a groupe name and Monte-carlo year -referred to as year- to a data series ID -referred to as time serie number-.

Example:

thermal_group, 0 = 1
thermal_group, 1 = 5
hydro_group, 2 = 7

For thermal_group the year 0 is associated with the time serie number 1 whereas the year 1 is associated with the time serie number 5.
For hydro_group the year 2 is associated with the time serie number 7.
A year is a integer, starting at 0.
A time serie number is a integer, starting at 1, and refers to the column number in the corresponding data series file.
Group IDs refer to groups defined in the components description.

Full examples¶

You can find some simple to more complex studies in our test base here.