Metadata-Version: 2.4
Name: ISPyPSA
Version: 0.1.3b1
Summary: An open-source capacity expansion model based on the methodology and datasets used by the Australian Energy Market Operator (AEMO) in their Integrated System Plan (ISP).
Author-email: prakaa <abiprakash007@gmail.com>, nick-gorman <n.gorman305@gmail.com>, dylanjmcconnell <dylan.mcconnell@unsw.edu.au>
License-File: LICENSE
Requires-Python: <3.14,>=3.11
Requires-Dist: doit>=0.36.0
Requires-Dist: isp-trace-parser>=2.0.3
Requires-Dist: isp-workbook-parser>=2.6.0
Requires-Dist: mkdocs-material>=9.6.18
Requires-Dist: mkdocs>=1.6.1
Requires-Dist: numpy>=2.0.0
Requires-Dist: pandas<3.0.0,>=2.2.2
Requires-Dist: plotly>=6.5.0
Requires-Dist: pyarrow>=18.0.0
Requires-Dist: pygal>=3.0.5
Requires-Dist: pypsa==0.34.1
Requires-Dist: pyyaml>=6.0.2
Requires-Dist: requests>=2.32.3
Requires-Dist: thefuzz>=0.22.1
Requires-Dist: tqdm>=4.67.1
Requires-Dist: xmltodict>=0.13.0
Provides-Extra: solvers
Requires-Dist: linopy>=0.4.4; extra == 'solvers'
Description-Content-Type: text/markdown

# ISPyPSA
[![Continuous Integration and Deployment](https://github.com/Open-ISP/ISPyPSA/actions/workflows/cicd.yml/badge.svg)](https://github.com/Open-ISP/ISPyPSA/actions/workflows/cicd.yml)
[![codecov](https://codecov.io/gh/Open-ISP/ISPyPSA/graph/badge.svg?token=rcEXuQgfOJ)](https://codecov.io/gh/Open-ISP/ISPyPSA)
[![pre-commit.ci status](https://results.pre-commit.ci/badge/github/Open-ISP/ISPyPSA/main.svg)](https://results.pre-commit.ci/latest/github/Open-ISP/ISPyPSA/main)
[![UV](https://camo.githubusercontent.com/4ab8b0cb96c66d58f1763826bbaa0002c7e4aea0c91721bdda3395b986fe30f2/68747470733a2f2f696d672e736869656c64732e696f2f656e64706f696e743f75726c3d68747470733a2f2f7261772e67697468756275736572636f6e74656e742e636f6d2f61737472616c2d73682f75762f6d61696e2f6173736574732f62616467652f76302e6a736f6e)](https://github.com/astral-sh/uv)

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](https://github.com/pypsa/pypsa).

**This README is a quick reference.** For detailed instructions, tutorials, and API documentation, see the [full documentation](https://open-isp.github.io/ISPyPSA/):

- [Getting Started](https://open-isp.github.io/ISPyPSA/getting_started/) - Installation and first model run
- [Configuration Reference](https://open-isp.github.io/ISPyPSA/config/) - All configuration options
- [CLI Guide](https://open-isp.github.io/ISPyPSA/cli/) - Command line interface details
- [API Reference](https://open-isp.github.io/ISPyPSA/api/) - Python API for custom workflows
- [Workflow Overview](https://open-isp.github.io/ISPyPSA/workflow/) - How the modelling pipeline works

## Installation

```bash
pip install ispypsa
```

Or with uv:

```bash
uv add ispypsa
```

## Quick Start

1. Download the [example config](ispypsa_config.yaml) and edit paths for your environment
2. Run:

```bash
# 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

```bash
# 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](https://github.com/Open-ISP/isp-workbook-parser) - Extract data from IASR workbooks
- [isp-trace-parser](https://github.com/Open-ISP/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](./CONTRIBUTING.md), which also includes steps to install `ispypsa` for development.

Please note that this project is released with a [Code of Conduct](./CONDUCT.md). By contributing to this project, you agree to abide by its terms.

## License

`ispypsa` was created as a part of the [OpenISP project](https://github.com/Open-ISP). It is licensed under the terms of [GNU GPL-3.0-or-later](LICENSE) licences.
