The PyPSA-to-GEMS Converter is an open-source & standalone python package that enables the conversion of studies conducted in PyPSA into the GEMS format: it exports a PyPSA Network as a GEMS folder. This converter is based on the representation of the PyPSA models of components as a GEMS library of models: pypsa_models.yml.
- Conversion of linear optimal power flow & economical dispatch studies
- Conversion of two-stage stochastic optimization studies
- How the Converter Works
- Input and Output of the Converter
- Current Limitations of the Converter
- Step-by-Step Guide: Manually Executing a Simulation in GEMS Modeler
- Comparing Results Between GEMS Modeler and PyPSA
The PyPSA to GEMS Converter transforms PyPSA Network into a GEMS study folder, through the following steps.
The converter first validates that the PyPSA network meets the requirements for conversion.
It performs necessary preprocessing steps such as normalizing component names, handling missing attributes, and ensuring data consistency.
This stage ensures the input PyPSA model is compatible with the conversion process.
The converter identifies and extracts all relevant components from the PyPSA network, including both static (constant) and dynamic (time-dependent) parameters.
It maps PyPSA-specific parameter names to their GEMS equivalents and organizes the data for conversion.
For parameters that vary over time, the converter extracts time series data and writes them to separate data files (CSV or TSV format).
The converter handles both deterministic studies (single time series) and stochastic studies (multiple scenarios), maintaining the temporal structure of the original PyPSA model.
Each PyPSA component is transformed into its corresponding GEMS representation.
The converter creates GEMS components with appropriate parameters, distinguishing between constant values and time-dependent references.
Connections between components (such as generators and loads connected to buses) are established through GEMS port connections.
If the PyPSA model includes global constraints (such as CO₂ emission limits), the converter identifies these and creates corresponding GEMS constraint components, linking them to the relevant system components.
Finally, the converter generates the complete GEMS study structure.
Input:
The converter requires the following inputs:
- PyPSA network object
The fully defined PyPSA network that will be converted into a GEMS-compatible study. - Logger
Used for debugging and tracing the conversion process. Logs can help identify configuration issues or data inconsistencies during conversion. - Output path
The directory where the generated GEMS study will be created. - Time series file format
Format used for exported time-dependent data (e.g. csv, tsv).
The converter generates a structured GEMS study directory at the provided output path.
The directory layout follows the conventions expected by the GEMS modeler:
study_directory/
└── systems/
└── system_name/
└── input/
├── optim-config.yml--------> Benders decomposition parameters, used by the modeler to generate MPS files
├── system.yml -------------> Main system description
├── parameters.yml----------> Solver and simulation parameters
├── model-libraries/
│ └── pypsa_models.yml---> Model library definitions
└── data-series/ ----------> Time and/or scenarion dependent parameters
└── ...We explicit here the current limitation of the PyPSA-to-GEMS converter, that are related to the current state of development of the converter. We foresee no limitations in terms of the expressiveness of the GEMS modelling language.
- Lines (not implemented)
- Transformers (not implemented)
active = 1- All generators are included in the optimization.marginal_cost_quadratic = 0- Only linear generation costs are supported.committable = False- Unit commitment (on/off decisions) is not supported.
active = 1- All loads are fixed and always active.
active = 1- All links are always active.
active = 1- All storage units are included in the optimization.sign = 1- Storage operates with positive dispatch direction.cyclic_state_of_charge = 1- End state of charge must equal the initial state.marginal_cost_quadratic = 0- Only linear storage costs are supported.
active = 1- All stores are included in the optimization.sign = 1- Store energy flows are positive.e_cyclic = 1- End energy level must equal the initial level.marginal_cost_quadratic = 0- Only linear storage costs are supported.
type = primary_energy- Only primary energy constraints are supported.carrier.co2_emissions- CO₂ accounting must be defined at the carrier level.- Supported senses:
<=,==
- Build or load a PyPSA network
# Setup
logger = logging.getLogger(__name__)
study_dir = Path("tmp/my_study") # Absolute path to the GEMS study directory
# Option A: build the network in code
network = Network()
network.add("Bus", "bus1", v_nom=1)
network.add("Load", "load1", bus="bus1", p_set=[10, 20, 30])
network.add("Generator", "gen1", bus="bus1", p_nom=100, marginal_cost=50)
# Option B: load the network from a file
network = Network("simple_network.nc") # Absolute path to the PyPSA file- Convert the PyPSA network to a GEMS study
# Convert PyPSA network to GEMS
converter = PyPSAStudyConverter(
pypsa_network=network,
logger=logger,
study_dir=study_dir,
series_file_format=".tsv", # Supported formats: .tsv, .csv
).to_gems_study()- Run the GEMS(Antares) optimization
# Path to the Antares modeler binary
modeler_bin = Path("antares-9.3.5-Ubuntu-22.04/bin/antares-modeler")
# Run the optimization
subprocess.run([
str(modeler_bin),
str(study_dir / "systems")
])If you want to see detailed statistics and a comparison between Antares Modeler and PyPSA study optimization, you can check the full analysis here: