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:
-
Mathematical Syntax — rules for writing mathematical expressions
-
File Structure — rules for writing GEMS YAML files and how they reference each other
-
Theoretical Concepts — core ideas behind the system representation and optimization formulation
-
Outputs — produced result formats and how to interpret them
This separation is fundamental to understanding how GEMS systems are written, interpreted, validated, and analysed.
Mathematical Syntax
The GEMS Framework Mathematical Syntax represents 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 governs 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 hypergraph representation of a system (components + ports + connections)
- 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.