Skip to content

GEMS Framework Introduction

The GEMS framework provides a declarative way to describe energy systems - and more generally, graph-based optimization problems - in a clear, stand-alone, solver-independent, and reproducible manner.

Rather than writing imperative code, users define a study through structured configuration files, mathematical expressions, and well-defined concepts that together allow GEMS to:

  • interpret a system as a connected graph of components,
  • construct the corresponding optimization problem,
  • solve it with a selected solver,
  • and expose results in consistent output formats.

From a documentation perspective, the User Guide is organized into four complementary sections, each serving a distinct purpose:

This separation is fundamental to understanding how GEMS systems are written, interpreted, validated, and analysed.

Mathematical Syntax

The GEMS Framework Mathematical Syntax represents a set of rules for creating mathematical expressions which will be used in building an optimization problem.

It defines:

  • Arithmetic and comparison operators
  • Linear expressions involving parameters, variables, and port fields, constraints and objective function
  • Time and scenario operators
  • Aggregation operators
  • Linearity rules
  • Additional Operators

Mathematical syntax is solver-agnostic and intentionally restricted to ensure that all optimization problems - representing systems - remain linear (LP/MILP) and unambiguous.

Mathematical syntax focuses exclusively on equations and rules. It does not describe where parameters and variables come from or how components are wired together as a system.

See: Mathematical Syntax and Rules

File Structure

The GEMS Framework File Structure defines how components are declared, structured, and connected to form a system, and how these systems can be translated as optimization problems, using YAML files.

It specifies:

  • How models and ports are defined in libraries
  • How variables, parameters, ports, constraints and objective function are declared in a model
  • How components are instantiated
  • How parameters are defined in a component
  • How to use ports to connect components to form a system graph
  • How optimization options are configured
  • (When applicable) How to create Business View configuration file

These rules govern the structure and semantics of all GEMS YAML files.

See: File Structure

Theoretical Concepts

The Theoretical Concepts section explains the core ideas behind how GEMS represents a system and builds an optimization problem.

It introduces:

  • The distinction between models (templates) and components (instances)
  • How constraints and objectives are assembled into a global optimization problem
  • How time and scenarios unfold into a larger deterministic or stochastic formulation
  • (When applicable) concepts behind two-stage stochastic modelling

This section is conceptual: it explains why the file structure and syntax are designed the way they are.

See: Theoretical Concepts

Outputs

The Outputs section describes what GEMS produces after interpretation and solving, and how to consume results.

It covers:

  • The Simulation Table (standard structured results)
  • The exported optimization problem
  • Business View: configured aggregations and indicators for analysis/reporting

Outputs depend on the selected interpreter and run configuration, but the documentation provides a consistent way to locate and interpret results.

See: Outputs and Result Formats