plexos-to-pypsa-converter 0.1.0

PLEXOS-to-PyPSA Converter

PLEXOS-to-PyPSA Converter

Convert PLEXOS input models to PyPSA networks for optimization and analysis.

This tool converts PLEXOS input XML files and their associated data into PyPSA networks that you can solve, analyze, and visualize.

Key Features

• Automated workflow - One-line conversion from PLEXOS XML to solved PyPSA network
• Flexible demand strategies - Per-node, aggregate, or target node assignment
• Rich analysis tools - Built-in NetworkAnalyzer with generation, capacity, and energy balance plots
• Interactive notebooks - Example Jupyter notebooks

Requirements

• Python: 3.11 or 3.12
• PyPSA: Version <1.0 (specifically >=0.34, <1.0)

Installation

Install from PyPI

pip install plexos-to-pypsa-converter

Development Install

git clone https://github.com/open-energy-transition/plexos-to-pypsa-converter.git
cd plexos-to-pypsa-converter
pip install -e .

Optional: System Dependencies

Some models use RAR archives and require unrar:

# macOS
brew install rar

This is only needed for RAR-based models like plexos-world-spatial.

Usage

Once installed (whether from PyPI or this repository), the converter is available as the plexos_to_pypsa_converter package. You can call it from any location.

Quick Start with Example Models

The easiest way to get started is with the high-level workflow API:

from plexos_to_pypsa_converter.workflow import run_model_workflow

# Run the workflow: download → convert → save
network, setup_summary = run_model_workflow("caiso-irp23")

# Solve a specific year (multi-period models)
network, setup_summary = run_model_workflow(
    "aemo-2024-isp-progressive-change",
    solve=True,
    optimize__year=2025
)

# Also add the solve/optimize step
network, setup_summary = run_model_workflow("caiso-irp23", solve=True)

By running `run_model_workflow(), this automatically:

1. Downloads the model data (if the data does not exist locally)
2. Converts PLEXOS XML to CSV files (using plexos-coad)
3. Creates the PyPSA network with topology/components
4. Adds other features, such as renewable profiles, retirements, generator outages, and slack generators
5. Optionally solves the optimization problem (when solve=True)
6. Saves results to NetCDF format

Interactive Notebooks

For interactive analysis and visualization, check out the example notebooks:

You can view a version of the results analysis for the caiso-irp23 model here.

The current existing notebooks are:

• CAISO IRP23:

  • src/plexos_to_pypsa_converter/examples/caiso_irp23/caiso_solve.ipynb (to convert and solve the caiso-irp23 model)
  • src/plexos_to_pypsa_converter/examples/caiso_irp23/caiso_analysis.ipynb (to visualize the caiso-irp23 model's results after solving)

• AEMO 2024 Progressive Change:

  • src/plexos_to_pypsa_converter/examples/aemo_2024_prog/aemo_solve.ipynb (to convert and solve the aemo-2024-isp-progressive-change model)
  • src/plexos_to_pypsa_converter/examples/aemo_2024_prog/aemo_analysis.ipynb (to visualize the aemo-2024-isp-progressive-change model's results after solving)

These notebooks show how to:

• Convert and solve PLEXOS models
• Generate network statistics
• Create plots for simple analysis and validation
• Export results for further analysis

Note that you have to run the {}_solve.ipynb notebooks before you are able to run the {}_analysis.ipynb notebooks.

Advanced: Custom Workflows

The default workflow steps for each model is specified in src/db/registry.py. However, you can customize the workflow steps to skip some steps. For example, to skip saving the network and to save under a custom filename:

from plexos_to_pypsa_converter.db.registry import MODEL_REGISTRY
from plexos_to_pypsa_converter.workflow import run_model_workflow

# Modify workflow (e.g., skip automatic save)
default_workflow = MODEL_REGISTRY["caiso-irp23"]["processing_workflow"]
custom_workflow = default_workflow.copy()
custom_workflow["steps"] = [
    step for step in default_workflow["steps"]
    if step["name"] != "save_network"
]

# Run with custom workflow
network, setup_summary = run_model_workflow(
    "caiso-irp23",
    workflow_overrides=custom_workflow,
    demand_assignment_strategy="aggregate_node"
)

# Save with custom filename
network.export_to_netcdf("my_custom_output.nc")

Supported Models

The following PLEXOS models are supported or in development:

Model Name	Source	Status	Download
AEMO 2024 ISP - Green Energy Exports	AEMO	🔴 Not yet converted	Download
AEMO 2024 ISP - Progressive Change	AEMO	🟡 In-progress	Download
AEMO 2024 ISP - Step Change	AEMO	🔴 Not yet converted	Download
CAISO IRP 2023 Stochastic (25 MMT)	CAISO	🟡 In-progress	Download
CAISO 2025 Summer Assessment	CAISO	🔴 Not yet converted	Download
NREL Extended IEEE 118-bus	NREL	🔴 Not yet converted	Download
SEM 2024-2032 Validation Model	SEM	🟡 In-progress	Download
European Power & Gas Model	UCC	🟡 In-progress	Download
PLEXOS-World 2015 Gold V1.1	UCC	🔴 Not yet converted	Download
PLEXOS-World Spatial Resolution	UCC	🔴 Not yet converted	Download
MESSAGEix-GLOBIOM-EN-NPi2020-500-Soft-Link	UCC	🟡 In-progress	Download

Status Legend:

• 🟢 Converted - Model successfully converted to PyPSA network
• 🟡 In-progress - Conversion currently underway
• 🔴 Not yet converted - Planned for future conversion

Model × Feature Coverage

The heatmap shows conversion status of different features across all models.

What Gets Converted

The converter handles these PLEXOS components:

Core Components:

• Buses/nodes and network topology
• Generators (thermal, hydro, renewables)
• Loads with flexible assignment strategies
• Transmission lines and links
• Storage units (batteries, pumped hydro)

Advanced Features:

• Forced retirements and capacity additions
• Generator outages and maintenance schedules

Architecture

The converter uses a CSV-based approach to take the PLEXOS model properties and turn them into PyPSA networks:

1. Download - Automatically fetch model data from source URLs
2. CSV Export - Convert PLEXOS XML to structured CSV files using COAD
3. Network Creation - Build PyPSA network from CSV data; Add outages, add slack generators, validate constraints
4. Optimization - Solve using PyPSA's optimization
5. Analysis - Generate plots and statistics with NetworkAnalyzer

Contribute

Report bugs on GitHub Issues.