PyPSA-Earth

PyPSA-Earth provides three main scripts for visualizing and analyzing results, which are typically invoked via Snakemake rules rather than manual Python execution:

• plot_network.py (Rule: plot_network): Renders geographic maps of solved networks.
• make_summary.py (Rule: make_summary): Aggregates optimization results into .csv summary tables.
• plot_summary.py (Rule: plot_summary): Generates charts from the generated cost and energy summary tables.

PyPSA-Earth organizes its workflow into several distinct rule categories that guide the user from data acquisition to model solving and visualization. The workflow typically follows this progression:

1. Download & Filter: Acquiring raw spatial data, building shapes, and retrieving data bundles or emissions.
2. Populate Data: Generating specific model inputs such as cutouts, demand profiles, renewable profiles, and CO2 emissions.
3. Create Network: Constructing the base network, adding electricity components, and performing network simplification or clustering.
4. Solving: Running the optimization model to solve the network.
5. Visualization: Plotting the results.

Customizing a PyPSA-Earth model to solve specific energy study problems involves four main stages:

1. Basic Setup: Customizing the default configuration file to specify your country or region of interest and enabling necessary data downloads.
2. Running Models: Using the Snakemake workflow management tool to execute the model, selecting an appropriate solver, and verifying optimization success.
3. Validation: Validating the obtained data through simulation procedures and comparing results against reference data sources.
4. Copernicus Data Integration: Accessing the Copernicus Climate Data Store (CDS) to build custom cutouts, which requires registration and setting up the CDS API key.

PyPSA-Earth is an open-source, global, cross-sectoral energy system model designed with high spatial and temporal resolution. It is suitable for both operational studies and capacity expansion studies.

Key capabilities include:

• Sector-coupled modeling: Optimization of multi-energy systems including electricity, heating, transport, industry, hydrogen, and more.
• Global scope: Ability to model energy systems for any country in the world.
• High resolution: High spatial and temporal resolution for detailed analysis.
• Versatility: Supports both operational and capacity expansion modeling workflows.

The PyPSA-meets-Earth initiative is a collection of interconnected repositories designed for global energy system modeling and infrastructure data processing. Depending on your modeling needs, you may need to use different components of the ecosystem:

• PyPSA Earth: The core model for power or sector-coupled system modeling applicable to any country.
• PyPSA Distribution: An optimization model specifically for micro-grids and distribution grids, featuring automated extraction of grid topology and electricity load profiles.
• Earth OSM: A toolset for downloading, pre-processing, and exporting energy-relevant infrastructure data from OpenStreetMap (OSM).
• PyPSA Earth Status: A tool for validating PyPSA networks against real-world energy system data using a reproducible workflow.

The PyPSA-Earth API is organized into functional categories that cover the entire modeling workflow, from data acquisition to simulation and analysis. Use the following categories to find specific scripts and tools:

• Data Download & Preparation: Scripts for downloading and preparing input data.
• Shape & Region Building: Scripts for building geographic shapes and regions.
• Resource Preparation: Scripts for preparing renewable resources and power plants.
• Network Building: Scripts for building the electricity network.
• Solving: Scripts for solving the optimization problem.
• Sector-Coupling: Scripts for sector-coupling features (heat, transport, industry).
• Analysis & Utilities: Helper scripts and analysis tools.
• Monte Carlo: Monte Carlo simulation scripts.

The repository is organized into the following directories:

• data: Input data that is not produced by any snakemake rule.
• scripts: Python scripts executed by the snakemake rules.
• resources: Intermediate workflow results used by subsequent rules.
• networks: Intermediate, unsolved stages of the PyPSA network.
• results: Solved PyPSA network data, summary files, and plots.
• benchmarks: snakemake benchmark files.
• logs: Log files (solver output, console output, and memory logger output).
• envs: Conda environment files for running the workflow.

In the PyPSA-Earth Snakemake workflow, the prepare_network rule is a critical intermediate step. It sits between the cluster_network step and the solve_network step. Its primary role is to process and format the clustered network data so that it is ready to be passed into the optimization solver.

Workflow Order:

1. cluster_network (Pre-requisite)
2. prepare_network (Current step)
3. solve_network (Downstream step)

Generation data is assembled through two primary Snakemake rules before the network is simplified or solved. This process determines which power plants are included in the model.

1. build_powerplants: This rule pulls data from the powerplantmatching database for the specified countries. It applies the powerplants_filter and can optionally merge or replace this data with a custom CSV file located at data/custom_powerplants.csv. The output is a single row per plant written to resources/[COUNTRY]/powerplants.csv.
2. add_electricity: This rule reads the generated powerplants.csv and attaches both demand and generator data to create the network file: networks/[COUNTRY]/elec.nc.

Sensitivity analysis is a post-optimization process. Unlike stochastic optimization (which includes uncertainty during the optimization), sensitivity analysis involves:

1. Solving a deterministic model first.
2. Varying one or more parameters (e.g., changing fuel cost $c_{\text{gas}}$ from 50 to 100 €/MWh).
3. Observing how the optimal solution (e.g., optimal capacities) changes in response to those variations.

The build_co2_emissions rule processes EDGAR fossil CO2 emissions data to prepare it for the automatic electricity-sector CO2 limit.

It works by reading the EDGAR Excel workbook (retrieved via retrieve_emissions), identifying the fossil CO2 emissions sheet, and filtering the data specifically for Public electricity and heat production. The result is a cleaned CSV file containing country identifiers and yearly emission values.

Activation: This rule is automatically active when electricity.automatic_emission is enabled in your configuration.