PyPSA-Earth

An Open Optimisation Model of the Earth Energy System.
https://github.com/pypsa-meets-earth/pypsa-earth

Category: Energy Systems
Sub Category: Global and Regional Energy System Models

Keywords

energy-system-model energy-system-planning investment-optimization operational-optimization power-system-model power-system-planning pypsa-africa pypsa-earth python scenario-analysis

Keywords from Contributors

energy-system pypsa power-systems renewable-energy energy-model climate-change power-systems-analysis optimisation powerflow optimal-power-flow

Last synced: about 8 hours ago
JSON representation

Repository metadata

PyPSA-Earth: A flexible Python-based open optimisation model to study energy system futures around the world.

README.md

PyPSA-Earth. A Flexible Python-based Open Optimisation Model to Study Energy System Futures around the World.

Development Status: Stable and Active

Test workflows
Documentation Status
Size
License: AGPL v3
REUSE status
Code style: black
pre-commit.ci status
Discord
Google Drive
DOI

PyPSA-Earth: A Global Sector-Coupled Open-Source Multi-Energy System Model

PyPSA-Earth is the first open-source global cross-sectoral energy system model with high spatial and temporal resolution. The workflow provide capabilities for modelling the energy systems of any country in the world, enabling large-scale collaboration and transparent analysis for an inclusive and sustainable energy future. PyPSA-Earth is suitable for both operational studies and capacity expansion studies. Its sector-coupled modeling capabilities enable features for the detailed optimization of multi-energy systems, covering electricity, heating, transport, industry, hydrogen and more.

All the data needed for a simulation are automatically and flexibly retrieved from open sources. This includes, in particular, energy demand across sectors, generation capacities, medium- to high-voltage networks, and renewable energy potentials. Custom datasets can also be integrated as needed, and kept private if required. At the same time, PyPSA-Earth-Status provides functionality to share regional insights. If you are willing to contribute your regional expertise, feel free to open an issue there.

PyPSA-Earth is capable of providing the modelling evidence needed to translate the implications of energy scenarios into actionable regional strategies. By making this tool openly available, we aim to foster collaboration, innovation, and informed decision-making to support sustainable and efficient energy solutions worldwide.

Details on the model are available in the following academic publications:

  • power model M. Parzen et all. "PyPSA-Earth: A new global open energy system optimization model demonstrated in Africa", Applied Energy, 341, 2023. https://doi.org/10.1016/j.apenergy.2023.121096
  • sector-coupled model H. Abdel-Khalek et al. "PyPSA-Earth sector-coupled: A global open-source multi-energy system model showcased for hydrogen applications in countries of the Global South", Applied Energy, 383, 2025. https://doi.org/10.1016/j.apenergy.2025.125316

PyPSA meets Earth is an independent research initiative developing a powerful energy system model for Earth. We work on open data, open source modelling, open source solver support and open communities. Stay tuned and join our mission - We look for users, co-developers and leaders!

The diagram below depicts one representative clustered node for the sector-coupled model with its generation, storage and conversion technologies.

Livetracker. Most popular global models:

How to get involved

There are multiple ways to get involved and learn more about our work:

  1. Join our forum and communication platform on PyPSA-meets-Earth Discord Server
  2. Chat on Discord with us in the following open meetings:
    • General initiative meeting for project news and high-level code updates. Held every fourth Thursday 16-17:00 (UK time) and is a perfect place to meet the community and get a high-level update on PyPSA ecosystem relevant for PyPSA-Earth developments.
    • Weekly developers meetings
      • Eastern-Hemisphere friendly Morning meeting every Thursday at 09:00 (UK time).
      • Western-Hemisphere friendly Evening meeting every Thursday 16:00 (UK time). Every forth Thursday is replaced by the General initiative meeting which has a more high-level perspective, but you can also join to discuss more particular questions.
  3. Look at public materials at google Drive to share to minutes, presentations, lists and documents. Feel gree to get a look!
  4. Notify your interest to on-demand meetings:
    • On-demand meetings
      • Demand creation and prediction meeting
      • AI asset detection meeting
      • Outreach meeting for planning, discussing events, workshops, communication, community activities
  5. Join us and propose your stream.

Installation

  1. Open your terminal at a location where you want to install pypsa-earth. Type the following in your terminal to download the package from GitHub:

       .../some/path/without/spaces % git clone https://github.com/pypsa-meets-earth/pypsa-earth.git
    
  2. The python package requirements are curated in the envs/environment.yaml file.
    The environment can be installed using:

    .../pypsa-earth % conda env create -f envs/environment.yaml

If the above takes longer than 30min, you might want to try mamba for faster installation:

    (base) conda install -c conda-forge mamba

    .../pypsa-earth % mamba env create -f envs/environment.yaml
  1. For running the optimization one has to install the solver. We can recommend the open source HiGHs solver which installation manual is given here.

  2. To use jupyter lab (new jupyter notebooks) continue with the ipython kernel installation and test if your jupyter lab works:

       .../pypsa-earth % ipython kernel install --user --name=pypsa-earth
       .../pypsa-earth % jupyter lab
    
  3. Verify or install a java redistribution from the official website or equivalent.
    To verify the successful installation the following code can be tested from bash:

       .../pypsa-earth % java -version
    

    The expected output should resemble the following:

       java version "1.8.0_341"
       Java(TM) SE Runtime Environment (build 1.8.0_341-b10)
       Java HotSpot(TM) 64-Bit Server VM (build 25.341-b10, mixed mode)
    

Running the model in previous versions

The model can be run in previous versions by checking out the respective tag. For instance, to run the model in version 0.6.0, which is the last version before the recent PyPSA update, the following command can be used:

git checkout v0.6.0

After checking out the tag, the model can be run as usual. Please make sure to use the environment built for the respective version.

Test run on tutorial

  • In the folder open a terminal/command window to be located at this path ~/pypsa-earth/

  • Activate the environment conda activate pypsa-earth

  • Rename config.tutorial.yaml to config.yaml. For instance in Linux:

    mv config.tutorial.yaml config.yaml
    
  • Run a dryrun of the Snakemake workflow by typing simply in the terminal:

    snakemake -j 1 solve_all_networks -n
    

    Remove the -n to do a real run. Follow the tutorial of PyPSA-Eur 1 and 2 on YouTube to continue with an analysis.

Training

  • We recently updated some hackathon material for PyPSA-Earth. The hackathon contains jupyter notebooks with exercises. After going through the 1 day theoretical and practical material you should have a suitable coding setup and feel confident about contributing.
  • The get a general feeling about the PyPSA functionality, we further recommend going through the PyPSA and Atlite examples.

Questions and Issues

  • We are happy to answer questions and help with issues if they are public. Through being public the wider community can benefit from the raised points. Some tips. Bugs and feature requests should be raised in the GitHub Issues. General workflow or user questions as well as discussion points should be posted at the GitHub Discussions tab. Happy coding.

Documentation

The documentation is available here: documentation.

Collaborators

Citation (CITATION.cff)

# SPDX-FileCopyrightText:  PyPSA-Earth and PyPSA-Eur Authors
# SPDX-License-Identifier: AGPL-3.0-or-later

title: PyPSA-Earth. A new global open energy system optimization model demonstrated in Africa
abstract: This repository contains the source code of the paper PyPSA-Earth. A new global open energy system optimization model demonstrated in Africa by Maximilian Parzen, Hazem Abdel-Khalek, Ekaterina Fedotova, Matin Mahmood, Martha Maria Frysztacki, Johannes Hampp, Lukas Franken, Leon Schumm, Fabian Neumann, Davide Poli, Aristides Kiprakis and Davide Fioriti, from Applied Energy
doi: 10.1016/j.apenergy.2023.121096
repository-code: https://github.com/pypsa-meets-earth/pypsa-earth
version: 1.0.0
date-released: 2023-04-18
message: If you use this software in your work, please cite it using the following metadata.
authors:
  - given-names: Maximilian
    family-names: Parzen
    orcid: https://orcid.org/0000-0002-4390-0063
  - given-names: Hazem
    family-names: Abdel-Khalek
  - given-names: Ekaterina
    family-names: Fedotova
    orcid: https://orcid.org/0000-0002-5590-9591
  - given-names: Matin
    family-names: Mahmood
  - given-names: Martha Maria
    family-names: Frysztacki
    orcid: https://orcid.org/0000-0002-0788-1328
  - given-names: Johannes
    family-names: Hampp
    orcid: https://orcid.org/0000-0002-1776-116X
  - given-names: Lukas
    family-names: Franken
  - given-names: Leon
    family-names: Schumm
  - given-names: Fabian
    family-names: Neumann
    orcid: https://orcid.org/0000-0002-6604-5450
  - given-names: Davide
    family-names: Poli
    orcid: https://orcid.org/0000-0002-5045-9034
  - given-names: Aristides
    family-names: Kiprakis
  - given-names: Davide
    family-names: Fioriti
    orcid: https://orcid.org/0000-0001-5491-7912
cff-version: 1.2.0

Owner metadata


GitHub Events

Total
Last Year

Committers metadata

Last synced: 11 days ago

Total Commits: 4,886
Total Committers: 72
Avg Commits per committer: 67.861
Development Distribution Score (DDS): 0.792

Commits in past year: 755
Committers in past year: 31
Avg Commits per committer in past year: 24.355
Development Distribution Score (DDS) in past year: 0.86

Name Email Commits
davide-f f****s@g****m 1017
ekatef e****a@g****m 737
Max Parzen m****n@e****k 525
pre-commit-ci[bot] 6****] 513
Hazem-IEG h****k@i****e 412
energyls l****m@o****e 297
Restyled.io c****s@r****o 288
Emmanuel Bolarinwa g****a@g****m 130
yerbol-akhmetov y****3@g****m 123
github-actions[bot] 4****] 79
Fabian f****f@g****e 70
mnm-matin m****9@g****m 67
DeniseGiub d****o@s****t 63
contrib-readme-bot c****n@n****m 62
Eddy-JV e****t@g****m 54
Thomas Kouroughli t****u@i****m 42
Anton Achhammer a****r@o****e 40
Hazem 8****G 31
virio-andreyana a****o@g****m 30
drifter089 a****7@g****m 27
GridGrapher 1****r 25
Fabrizio Finozzi 1****a 22
glenkiely-ieg 9****g 17
Eric Nitschke e****e@t****e 15
cpschau c****s@i****e 15
giacfalk g****a@g****m 12
carlosfv c****2@h****m 11
martha.mf m****i@k****u 11
ljansen l****n@i****e 11
Emre-Yorat89 y****e@g****m 9
and 42 more...

Committer domains:


Issue and Pull Request metadata

Last synced: 1 day ago

Total issues: 554
Total pull requests: 919
Average time to close issues: 4 months
Average time to close pull requests: 11 days
Total issue authors: 54
Total pull request authors: 72
Average comments per issue: 2.75
Average comments per pull request: 2.41
Merged pull request: 660
Bot issues: 0
Bot pull requests: 269

Past year issues: 173
Past year pull requests: 309
Past year average time to close issues: about 1 month
Past year average time to close pull requests: 11 days
Past year issue authors: 28
Past year pull request authors: 37
Past year average comments per issue: 1.82
Past year average comments per pull request: 2.23
Past year merged pull request: 201
Past year bot issues: 0
Past year bot pull requests: 72

More stats: https://issues.ecosyste.ms/repositories/lookup?url=https://github.com/pypsa-meets-earth/pypsa-earth

Top Issue Authors

  • davide-f (171)
  • pz-max (136)
  • ekatef (63)
  • GbotemiB (27)
  • yerbol-akhmetov (18)
  • hazemakhalek (15)
  • energyLS (11)
  • doneachh (9)
  • Tomkourou (9)
  • mnm-matin (9)
  • danielelerede-oet (7)
  • bobbyxng (5)
  • euronion (5)
  • Eric-Nitschke (5)
  • carlosfv92 (4)

Top Pull Request Authors

  • davide-f (157)
  • github-actions[bot] (113)
  • ekatef (105)
  • pz-max (97)
  • restyled-io[bot] (90)
  • pre-commit-ci[bot] (64)
  • yerbol-akhmetov (41)
  • GbotemiB (30)
  • finozzifa (22)
  • Tomkourou (16)
  • danielelerede-oet (14)
  • energyLS (14)
  • doneachh (10)
  • virio-andreyana (10)
  • hazemakhalek (7)

Top Issue Labels

  • bug (205)
  • good first issue (88)
  • improvement (62)
  • help wanted (47)
  • documentation (31)
  • feature request (30)
  • high priority (7)
  • alternative_clustering (6)
  • reimplementation (5)
  • question (2)

Top Pull Request Labels

  • improvement (3)
  • dependencies (2)
  • bug (1)
  • feature request (1)
  • wontfix (1)

Package metadata

proxy.golang.org: github.com/pypsa-meets-earth/pypsa-earth


Dependencies

doc/requirements.txt pypi
  • atlite >=0.2.2
  • dask <=2021.3.1
  • descartes *
  • esy-osm-pbf *
  • esy-osmfilter *
  • memory_profiler *
  • powerplantmatching >=0.4.8
  • pycountry *
  • pypsa *
  • pyyaml *
  • rioxarray *
  • scikit-learn *
  • seaborn *
  • setuptools *
  • setuptools <58.3.0
  • sphinx *
  • sphinx_rtd_theme *
  • tables *
  • vresutils >=0.3.1
.github/workflows/ci-linux.yaml actions
  • actions/cache v2 composite
  • actions/checkout v2 composite
  • conda-incubator/setup-miniconda v2 composite
.github/workflows/ci-mac.yaml actions
  • actions/cache v2 composite
  • actions/checkout v2 composite
  • conda-incubator/setup-miniconda v2 composite
.github/workflows/ci-windows.yaml actions
  • actions/cache v2 composite
  • actions/checkout v2 composite
  • conda-incubator/setup-miniconda v2 composite
.github/workflows/main.yml actions
  • akhilmhdh/contributors-readme-action v2.3.6 composite
envs/environment.yaml conda
  • atlite
  • cartopy
  • contextily
  • country_converter
  • dask
  • descartes
  • earth-osm >=0.1.0
  • fiona !=1.8.22
  • geopandas >=0.11.0
  • geopy
  • geoviews
  • glpk
  • graphviz
  • gurobi
  • hvplot
  • ipopt <3.13.3
  • ipykernel
  • ipython
  • jupyterlab
  • lxml
  • mamba
  • matplotlib <=3.5.2
  • memory_profiler
  • netcdf4
  • networkx
  • numpy
  • openpyxl
  • pandas
  • pip
  • powerplantmatching >=0.5.7
  • pre-commit
  • py7zr
  • pydoe2
  • pyomo
  • pypsa >=0.24,<0.25
  • pytables
  • python >=3.8
  • pytz
  • rasterio !=1.2.10
  • reverse-geocode
  • rioxarray
  • ruamel.yaml <=0.17.26
  • scipy
  • seaborn
  • shapely >=2
  • snakemake-minimal
  • tqdm
  • xarray
  • xlrd

Score: -Infinity