Getting started

Installation

New to Python / need help setting up your environment?

Unsure?

We recommend using the uv software to install and run Python for ISPyPSA.

Install uv by following the instructions here
Using the command line install Python 3.12
```
uv python install 3.12
```
Using the command line create a new directory setup as a uv managed project
```
uv init new-ispypsa-project
```
In the new directory use the command line to install ISPyPSA for the project. Any additional Python packages you wish to use can be installed using the same commands.
```
uv add ISPyPSA
uv sync
```
Any scripts you run inside the new directory using uv run will automatically use the packages you've installed for the project.
```
uv run main.py
```

I know Python!

pip install or a python package manager can install ISPyPSA

pip install ispypsa

Running your first model

Create a new directory for storing your ispypsa model files, or if you followed the uv install process just use the new-ispypsa-project directory you created.
Download the default example config file and place in the new directory.

⬇ Download ispypsa_config.yaml
Edit the yaml config file so that the paths section matches your environment:
- parsed_traces_directory: Base directory where trace data will be downloaded. Choose a directory on a drive with at least 30 GB of free space.
- workbook_path: Path where the ISP Excel workbook file will be downloaded (must end with .xlsx). You need to give a complete file path and name, not just a path to a directory.
- parsed_workbook_cache: Where extracted workbook data should be cached. This could be anywhere but a subdirectory in your new directory is a good idea.
- run_directory: Base directory where all model inputs and outputs will be stored. This could be anywhere but a subdirectory in your new directory is a good idea.
The top of your yaml file should look something like this:
```
 # ===== Path configuration =============================================================

 paths:
   # The run directory where all inputs and outputs will be stored
   run_directory: "ispypsa_runs"

   # The name of the ISPyPSA model run
   # This name is used to select the output folder within `ispypsa_runs`
   ispypsa_run_name: example_model_run

   # The path to the folder containing parsed demand, wind and solar traces.
   parsed_traces_directory: "data/trace_data"

   # The path to the ISP workbook Excel file
   workbook_path: "data/2024-isp-inputs-and-assumptions-workbook.xlsx"

   # The path to the workbook table cache directory
   parsed_workbook_cache: "data/workbook_table_cache"
```

Relative paths

In this example the paths in the config should be relative to the directory where you will use the command line to run the model. If you are using a new uv project then this will be the directory you just created, and data, data/trace_data, data/workbook_table_cache, and ispypsa_runs should be new directories you have created.

Using the command line inside the project/environment where ispypsa is installed download the ISP workbook:
uvplain python
uv run ispypsa config=ispypsa_config.yaml download_workbook
ispypsa config=ispypsa_config.yaml download_workbook
This will download the workbook to the path specified in your config file (paths.workbook_path). The workbook version is automatically determined from your config (iasr_workbook_version).
Using the command line inside the project/environment where ispypsa is installed download the trace data:
uvplain python
uv run ispypsa config=ispypsa_config.yaml download_trace_data
ispypsa config=ispypsa_config.yaml download_trace_data
This will download trace data to your configured directory (paths.parsed_traces_directory). By default, the example dataset is downloaded, which is a smaller subset suitable for testing. The dataset type can be configured in your config file (trace_data.dataset_type) or overridden on the command line:
uvplain python
# Download the full dataset instead of example uv run ispypsa config=ispypsa_config.yaml trace_dataset_type=full download_trace_data
# Download the full dataset instead of example ispypsa config=ispypsa_config.yaml trace_dataset_type=full download_trace_data

Using the command line inside the project/environment where ispypsa is installed run the complete modeling workflow to test everything works correctly:

uvplain python

uv run ispypsa config=ispypsa_config.yaml

ispypsa config=ispypsa_config.yaml

Once the model run finishes you should have the following directory 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

The previous model run used the default inputs for the ISP scenario specified in the yaml file. To run model with different inputs you can edit the csv files in <run_directory>/<ispypsa_run_name>/ispypsa_inputs/. To rerun the model with the new inputs, use the same commands as before to rerun the model. By default, ispypsa will detect that the inputs have changed and rerun only modelling workflow steps which depend on the changed inputs, but not workflow steps used to create the ispypsa input files.
uvplain python
uv run ispypsa config=ispypsa_config.yaml
ispypsa config=ispypsa_config.yaml
If you want to create the ispypsa inputs, so you can edit them, but not run the complete model, use the following command:
uvplain python
uv run ispypsa config=ispypsa_config.yaml create_ispypsa_inputs
ispypsa config=ispypsa_config.yaml create_ispypsa_inputs

Mastering the ispypsa command line tool (CLI)

This example has shown you how to start using ISPyPSA through its command line interface or CLI. To view the complete CLI documentation go to CLI

The API alternative

The alternative to using the CLI is to use the API, which offers more control than the CLI but takes a little extra work. To view the complete API documentation go to API

Understanding what's happening under the hood!

When ISPyPSA is run from the command line the workflow executed is the same as in example_workflow.py. If you want to understand the workflow by tracing the API calls you can follow along in example_workflow.py script. Alternatively, the Workflow section provides a high level explanation.