Library File

A library file defines a library of two collections of abstract objects:

Models - Contains the mathematical formulation for component type
Ports Types - Describe the kinds of connections models can have

The library file is a YAML file with a single root key, library. Under this root, the library’s identifier, an optional description, and the collections of port-types and models are defined. All fields, unless explicitly marked as optional, must be present for the library to be considered valid. The following example illustrates the structure of a simple library file:

library:

  id: example_library
  description: "Example model library"

  port-types:
    - id: flow_port
      description: "Power flow port"
      fields:
        - id: flow

  models:
    - id: bus
      description: "A simple balance node model"
      ports:
        - id: balance_port
          type: flow_port
      binding-constraints:
        - id: balance
          expression: sum_connections(flow_port.flow) = 0

In this example, one port type flow_port and one model bus are defined. The model contains a port named balance_port of type flow_port, along with a binding constraint equation that enforces First Kirchhoff Law.

The equation sum_connections(injection.flow) = 0 follows the GEMS Mathematical Expression Syntax.

Rules for id naming

All id's 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

Collections and key fields in library file

Every library file must begin with the following header with optional description and version:

library:
  id: example_library
  description: "Example model library"
  version: "1.0.0"

Element	Type	Description
`id`	String	A unique identifier for the library. This `id` is used by system files to reference models from this library. It must be unique across all libraries that are used to build a system and must follow standard naming rules.
`description`	String	(Optional) A human-readable description of the library’s content or purpose.
`version`	String	(Optional) A version string for the library (e.g. `"1.0.0"`). Should be bumped whenever the library changes; see the corresponding `CHANGELOG` file.

Port Types

The port-types collection defines the set of port types available within a library. These port types can be used by models/components to communicate with each other by exchanging linear expressions.

This collection is optional. A library may define no port types, although such a library has limited practical use, as its models cannot interact through ports. Alternatively, a library may rely on port types defined in another library, enabling reuse and interoperability across libraries.

port-types:
    - id: flow_port
      description: "Power flow port"
      fields:
        - id: flow
    - id: example_port
      fields:
        - id: field_1
        - id: field_2

Element	Type	Description
`port-types`	List	A list of port type definitions that models can use for connecting to other models.
`id`	String	Unique `id` for the port type within this library. Must follow the naming rules and must not conflict with other port type `id`s in the same library.
`description`	String	(Optional) A human-readable description of the port type’s purpose.
`fields`	List	A list of fields carried by this port. Each field has an `id` (unique within the port type) that identifies a scalar floating-point quantity exchanged through the port (e.g. a power flow value).

Models

The models collection defines all model types that can be instantiated within a system. In the following YAML file, two models are defined: bus and storage.

  models:
    - id: bus
      parameters:
        - id: spillage_cost
          time-dependent: false
          scenario-dependent: false
        - id: unsupplied_energy_cost
          time-dependent: false
          scenario-dependent: false
      variables:
        - id: spillage
          lower-bound: 0
          variable-type: continuous
        - id: unsupplied_energy
          lower-bound: 0
          variable-type: continuous
      ports:
        - id: balance_port
          type: flow
      binding-constraints:
        - id: balance
          expression: sum_connections(balance_port.flow) = spillage - unsupplied_energy
      objective-contributions:
        - id: objective
          expression: sum(spillage_cost * spillage + unsupplied_energy_cost * unsupplied_energy)
      extra-outputs:
        - id: marginal_price
          expression: dual(balance)

    - id: storage
      parameters:
        - id: reservoir_capacity
          time-dependent: false
          scenario-dependent: false
        - id: injection_nominal_capacity
          time-dependent: false
          scenario-dependent: false
        - id: withdrawal_nominal_capacity
          time-dependent: false
          scenario-dependent: false
        - id: efficiency_injection
          time-dependent: false
          scenario-dependent: false
        - id: efficiency_withdrawal
          time-dependent: false
          scenario-dependent: false
        - id: initial_level
          time-dependent: false
          scenario-dependent: true
      variables:
        - id: p_injection
          lower-bound: 0
          upper-bound: injection_nominal_capacity
          variable-type: continuous
        - id: p_withdrawal
          lower-bound: 0
          upper-bound: withdrawal_nominal_capacity
          variable-type: continuous
        - id: level
          lower-bound: 0
          upper-bound: reservoir_capacity
          variable-type: continuous
      ports:
        - id: injection_port
          type: flow
      port-field-definitions:
        - port: injection_port
          field: flow
          definition: p_withdrawal - p_injection
      constraints:
        - id: initial_level_constraint
          expression: level[0] = initial_level * reservoir_capacity
        - id: level_dynamic_constraint
          expression: level[t+1] = level + efficiency_injection * p_injection - efficiency_withdrawal * p_withdrawal

A model is an abstract object, that will be instantiated once or several times in a system and is defined by:

Unique Identifier and Description

Element	Type	Description
`id`	String	A unique identifier for the model within a library. Must follow the naming rules. System files reference the model by combining the library `id` and the model `id`.
`description`	String	(Optional) Text description of the model.

Parameters

A list of parameters that this model takes. Each parameter defines a configurable value for the model when it’s used in a system. For each parameter user can specify specify:

Element	Type	Description
`id`	String	Unique parameter identifier within the model. Must follow the naming rules.
`time-dependent`	Boolean	`true` or `false`. If `true`, this parameter can vary over the simulation timeline (meaning it will be associated with a time series input). If `false`, it is treated as constant in time.
`scenario-dependent`	Boolean	`true` or `false`. If `true`, the parameter can have different values in different scenarios (i.e., it requires scenario-specific data). If `false`, it does not vary between scenarios.

Together, these flags define how the parameter can be provided — as a single value, a time series, scenario-based data, or a matrix. For details on how parameter data is stored and referenced, see the data-series.

Variables

A list of decision variables introduced by this model for the optimization problem. Each variable includes:

Element	Type	Description
`id`	String	Unique variable name within the model. Must follow the naming rules.
`variable-type`	Enum	The type of variable: `continuous`, `integer`, or `binary`. This determines how the solver treats the variable.
`lower-bound`	Number or Expression	(Optional) Lower bound for the variable. Can be a numeric literal or an expression using only model parameters and constants. Defaults to −∞ for `continuous`/`integer`, or `0` for `binary`.
`upper-bound`	Number or Expression	(Optional) Upper bound for the variable. Can be a numeric literal or an expression using only model parameters and constants. Defaults to +∞ for `continuous`/`integer`, or `1` for `binary`.

Any expression used for bounds must use only constants or models parameters.

For example, variable p_injection in the storage model is defined as a continuous variable with upper bound set up by parameters injection_nominal_capacity and lower bound set up by 0.

variables:
  - id: p_injection
    lower-bound: 0
    upper-bound: injection_nominal_capacity
    variable-type: continuous

Ports

A list of ports that model exposes to connect with other models. Each port has:

Element	Type	Description
`id`	String	Unique port name within the model. Must follow the naming rules.
`type`	String	The port type `id` that this port conforms to. Must match a port type defined in the port-types collection of a library included in the system.

The port type must be one of those defined in the port-types collection of a library included in the system.

Port Field Definition

A collection of definitions describing the ports emitted by a model. Each entry associates one of the model’s variables, parameters, or linear expressions with a specific field of a port. When a model defines a port, it must provide definitions for all fields of that port.

Element	Type	Description
`port`	String	The `id` of a port listed in the ports section of this model.
`field`	String	The field `id` as defined in the corresponding port type.
`definition`	Mathematical Expression	A linear expression giving the value of that port field, using the model’s variables and/or parameters.

Constraints

A list of internal constraints of a model. These are equations or inequalities that involve the model’s own variables, parameters. Each constraint has:

Element	Type	Description
`id`	String	Unique `id` for the constraint within the model. Must follow the naming rules.
`expression`	Mathematical Expression	An equation or inequality using the model’s variables and parameters.

An explicit example is provided by the storage model constraint defining the initial reservoir level:

constraints:
  - id: initial_level_constraint
    expression: level[0] = initial_level * reservoir_capacity

Constraint expression must comply with the Mathematical Expression Syntax to ensure it is interpreted correctly during model evaluation.

Binding-Constraints

A list of external constraints that involve model’s ports (i.e., constraints that will bind this model’s behavior to other models when connected).

Element	Type	Description
`id`	String	Unique `id` for the binding constraint within the model. Must follow the naming rules.
`expression`	Mathematical Expression	An equation or inequality that may use port operators to aggregate expressions from connected components.

Binding constraints are defined in the same manner as internal constraints, but they may include port operators, which aggregate linear expressions emitted through a port.

An explicit example is provided by the bus model implementing the energy balance constraint (First Kirchhoff Law):

binding-constraints:
  - id: balance
    expression: sum_connections(balance_port.flow) = spillage - unsupplied_energy

Objective Contribution

An objective contribution is a linear expression that represents a cost or penalty associated with a model component. During model assembly, all objective contributions defined across all instantiated components are automatically aggregated to form the global objective function of the optimisation problem. By convention, the optimisation problem is assumed to be a minimisation problem.

Element	Type	Description
`id`	String	Unique `id` for the objective contribution within the model. Must follow the naming rules.
`expression`	Mathematical Expression	A linear expression representing a cost or penalty term. All contributions across all components are summed to form the global minimisation objective.

objective-contributions:
  - id: objective
    expression: sum(spillage_cost * spillage + unsupplied_energy_cost * unsupplied_energy)

Note that a model may define multiple objective contributions, each identified by its own id. This enables advanced formulations such as two-stage stochastic optimisation, where different objective terms belong to different optimisation stages (e.g. investment vs. operation).

Extra Output

The extra-outputs section allows each model to define additional calculated outputs that are evaluated after optimization.

Each entry under extra-outputs must contain:

Field	Type	Description
`id`	String	Unique identifier for the extra output within the model. Must follow the naming rules.
`expression`	Mathematical Expression	A linear expression evaluated from optimal variable values after the solve. May use variables, parameters, and direct port field access (unlike constraints).

Unlike in constraints, direct port field usage is allowed in extra-outputs.