ISPyPSA

An open-source capacity expansion modelling tool based on the methodology and assumptions used by the Australian Energy Market Operator (AEMO) to produce their Integrated System Plan (ISP). Built on PyPSA.

This README is a quick reference. For detailed instructions, tutorials, and API documentation, see the full documentation:

• Getting Started - Installation and first model run
• Configuration Reference - All configuration options
• CLI Guide - Command line interface details
• API Reference - Python API for custom workflows
• Workflow Overview - How the modelling pipeline works

Installation

pip install ispypsa

Or with uv:

uv add ispypsa

Quick Start

1. Download the example config and edit paths for your environment
2. Run:

# Download ISP workbook and trace data
ispypsa config=ispypsa_config.yaml download_workbook
ispypsa config=ispypsa_config.yaml download_trace_data

# Run complete workflow (capacity expansion + operational model)
ispypsa config=ispypsa_config.yaml

CLI Reference

Task	Description
download_workbook	Download IASR Excel workbook
download_trace_data	Download wind/solar/demand traces
cache_required_iasr_workbook_tables	Extract workbook data to CSV cache
create_ispypsa_inputs	Generate ISPyPSA input tables
create_pypsa_friendly_inputs	Convert to PyPSA format
create_and_run_capacity_expansion_model	Build and solve capacity expansion
create_and_run_operational_model	Build and solve operational model
create_capacity_expansion_plots	Generate result plots
create_operational_plots	Generate operational plots
list	Show available tasks

Common Options

# Override config values on command line
ispypsa config=config.yaml create_plots=True create_and_run_capacity_expansion_model

# Skip optimisation (build network only)
ispypsa config=config.yaml run_optimisation=False create_and_run_capacity_expansion_model

# Force re-run even if up-to-date
ispypsa config=config.yaml -a create_ispypsa_inputs

Output Structure

<run_directory>/
└── <ispypsa_run_name>/
   ├── ispypsa_inputs/
   │   ├── build_costs.csv
   │   └── ...
   ├── pypsa_friendly/
   │   ├── buses.csv
   │   ├── ...
   │   ├── capacity_expansion_timeseries/
   │   │   ├── demand_traces/
   │   │   │   ├── CNSW.parquet
   │   │   │   └── ...
   │   │   ├── solar_traces/
   │   │   │   ├── Bomen Solar Farm.parquet
   │   │   │   └── ...
   │   │   └── wind_traces/
   │   │       ├── Ararat Wind Farm.parquet
   │   │       └── ...
   │   └── operational_timeseries/
   │       └── (same structure as capacity_expansion_timeseries)
   └── outputs/
       ├── capacity_expansion.nc
       ├── capacity_expansion_results_viewer.html
       ├── capacity_expansion_tables
       │   └── ...
       ├── capacity_expansion_plots
       │   └── ...
       ├── operational.nc
       ├── operational_results_viewer.html
       ├── operational_tables
       │   └── ...
       └── operational_plots
           └── ...

Related Projects

• isp-workbook-parser - Extract data from IASR workbooks
• isp-trace-parser - Process wind/solar/demand trace data

Contributing

Interested in contributing to the source code or adding table configurations? Check out the contributing instructions, which also includes steps to install ispypsa for development.

Please note that this project is released with a Code of Conduct. By contributing to this project, you agree to abide by its terms.

License

ispypsa was created as a part of the OpenISP project. It is licensed under the terms of GNU GPL-3.0-or-later licences.