GMPA - STEVFNs modelling

This is the STEVFNs model generator fork from the original STEVFNs model containing modelling details used in the Global Mitigation Potential Atlas (GMPA).

This repository has shifted package management to use uv, so base setup will differ from the current (as of July 2026) original repository until changes are pushed upstream.

To set up case studies and run different tests, you need to clone this repository as instructed, and follow the setup instructions that follow.

Set up and first run

0. Requirements

Important

The following should be installed before continuing

1. This project has shifted reliance on conda package managers to uv for simpler cross-OS collaboration and quicker setup. For more details on uv and follow installation instructions, see Astral's uv documentation

2. Install git: For detailed documentation on git, see git's installation page

1. Clone

In your terminal, navigate to a local directory where you will want to keep the STEVFNs repository folder. Once there, run

git clone https://github.com/m-sgstyb/stevfns-gmpa.git

This should take a minute or two and will create a stevfns-gmpa folder in that directory with all the files from the main branch in the repository.

2. Create your local branch

To avoid editing directly in the main branch, create your own local branch to test the model and run your own case studies. Choose a branch name, such as "my-test" or "custom-runs": from your command line replace <branch-name> in the following prompt with your chosen name and, run

git checkout -b <branch-name>

If named "my-test", the command is

git checkout -b my-test

This will create a new branch where you can start testing the model and creating your own case studies

3. Set up required: virtual environment

This project relies on Python dependencies that are stored in pyproject.toml file. To automatically create a virtual environment and install required dependencies there, run

uv sync

Note

You should have installed uv as instructed in step 0. for this to work

4. Quick run pre-defined test-collab case study

The repository natively includes some input data and a case study defined for a two-country collaboration. This is located in Case_Study/test-collab.

To run this case, from the repository root in your terminal, run

uv run python run_cases.py --name test-collab

Your terminal should quickly solve and display something like this:

--- Running: test-collab with clarabel solver ---

========================== Building ==========================
Time taken to build network =  0.6059021949768066 s

================== Updating for Scenario BAU ==================

Time taken to update network =  0.011281967163085938 s
----------------- Scenario BAU Main Results ----------------------

Time taken to solve problem =  0.8200230598449707 s
optimal
Total cost to satisfy all demand =  101.25240164207851  Billion USD
Total emissions =  10.66361512 MtCO2e
------------------  All Scenarios Run  ------------------------
 Time to build network, run all scenarios, export and plot data 0.02396846612294515 min

All case studies completed successfully.

Note

A plot window will open after the run completes. Close it to view other result plots and return control to your terminal.

Once you have been able to run the pre-defined minimal case study, you can create your own and run the model.

Custom Case Studies

1. Create a Case Study folder

In Data/Case_Study, create a new folder with your case study name. If you have selected a country, for example Indonesia, this may be something representative like id-test, or if you want multiple countries for collaboration, it could be id-sg-collab. Think of names that are simple but descriptive.

Note

Case Study folder naming convention

For CLI ergonomics and visual separation, we recommend adhering to kebab-case (words separated by dashes) convention for naming new case study folders:

• lower case only: try not to use capital leters ( use id-sg-collab instead of ID-SG-Collab)
• avoid spaces or underscores

Necessary details

---

A case study needs four basic parts before it can be run:

1. Network_Structure.csv file: defines in which locations and which technologies will be modelled
2. At least one scenario folder (appropriately named) with: a. Asset_Paramters.csv b. Location_Parameters.csv c. System_Parameters.csv

For your initial test, System_Parameters.csv and Location_Parameters.csv can be copied from test-collab case study scenario. These include all the locations where asset data is readily available in the repository so you can use without additional data collection, as well as pre-determined system details (1-hour timesteps, 30-year project and 5% discount rates).

Network_Structure.csv

---

The Network_Structure.csv file defines where and which assets may be installed by the model.

Asset_Number	Asset_Class	Location_1	Location_2	Start_Time	End_Time	Period	Transport_Time
0	EL_Demand	0	0	0	192	1	0
1	RE_PV_Openfield_Lim	0	0	0	192	1	0

• Asset_Number: This should be a continuous list starting at 0

• Asset_Class: This column should contain the asset name from the technologies or parts of the system that you want in the model, for example this table includes electricity demand and openfield PV

• Location_1: This is where the asset will be located.

• Location_2: This is equal to Location_1 if the asset is only in one location. For collaboration/linking assets, for example HVDC cables or ammonia shipping that connect two locations and can trade, Location_2 must be different to Location_1. (See the full Network_Structure.csv in test-collab)

• Start_Time: This is the timestep where the model will start sampling profile data from (demand or capacity factor profiles). Default is 0

• End_Time: End_Time - Start_Time determines how many timesteps will be sampled in total from profile assets, and therefore how many total timesteps will be modelled. In this example, 192 - 0 = 192. This is equivalent to sampling 8 days out of a year, which will be sampled from input profiles evenly throught the annual profile to capture seasonal differences.

• Period: This is how often the source is delivered (in this case, 1 hour as the smallest timestep in the model). For example, fuel shipping may only be dispatched every certain amount of days. For ammonia transport for example, ships do not depart every hour, so this parameter would be higher (See the full Network_Structure.csv in test-collab for NH3_Transport).

• Transport_Time: This is the time it takes to transport energy from one location to another. We assume electricity can be instantaneously generated and delivered. For ammonia transport for example, it takes a long time (magnitude of days) from the shipping to get from one point to another (See the full Network_Structure.csv in test-collab for NH3_Transport).

Technology selection

---

For your first model, choose a few assets from the following list to build a network.

1. BESS
2. EL_Demand
3. EL_Transport (HVDC cables)
4. EL_to_HTH
5. EL_to_NH3
6. FF_to_HTH
7. NH3_Storage
8. NH3_Transport
9. NH3_to_EL
10. NH3_to_HTH
11. PP_CO2
12. RE_PV_Openfield_Lim
13. RE_PV_Rooftop_Lim
14. RE_Wind_Offshore_Lim (any or several of the 0-9 types of this asset)
15. RE_Wind_Onshore_Lim (any or several of the 0-9 types of this asset)

These assets currently have data availability for all the locations in the Location_Parameters.csv found in the included test scenario folder, so can be immediately used under those assumptions.

If you want to use another available asset in the src/assets folder, check their parameters.csv file to check what data is available and can be run as-is.

Otherwise, data collection and definition will be required.

scenario_folder/Asset_Parameters.csv

---

The first four columns of the Asset_Paramters.csv should be exactly the same as the Network_Structure.csv.

Asset_Number	Asset_Class	Location_1	Location_2	Asset_Type
0	EL_Demand	0	0	0
1	RE_PV_Openfield_Lim	0	0	0

The fifth column determines which asset type should be considered for installation in that location. This value should match the parameters relevant to your scenario from the src/assets/<asset_name>/parameters.csv file.

For example, for RE_PV_Openfield_Lim asset, the first row would look like this.

Type	sizing_constant	sizing_constant_unit	lifespan	lifespan_unit	RE_type	set_size	set_number	maximum_size	maximum_size_unit	location_name
0	0.51	G$/GWp	262800	h	PVOUT	24	0	0.35339	GWp	SGP

In this case, the Type 0 open field PV asset is for Singapore (see location_name column). Therefore, it would follow that Location_1 and Location_2 columns from this case study network structure would correspond to the location for Singapore. Because the data already comes from pre-defined Location_Parameters.csv, this was intentional.

If you look at the Location_Parameters.csv from the test-collab case study, scenario BAU, you'll see row 0 for locations has the coordinates for SG. These coordinates have two purposes in the model setup:

1. Estimate distances between locations, "as the bird flies" for the estimation of shipping and HVDC transport distances
2. To find the correct capacity factor profiles for PV and Wind asset types, as these have a conventional naming format related to their coordinates.

Note

The capacity factor profiles will not necessarily correspond to the actual lat-lon values, they may be country averages to represent country potentials or other assumptions. For the data currently in the repository, these represent country averages obtained through a modelling pipleine from GLAES/RESkit

scenario_folder/Location_Parameters.csv

---

This file defines the coordinates for locations and their abbreviation for ease of use. Currently, as GMPA models country-level, these are alpha-2 ISO 3166 country codes.

scenario_folder/System_Parameters.csv

---

This file defines system-wide parameters, project lifetime in hours, discount rate for NPV cost calculations, and the timestep size.

2. Run your custom case study

Once your case study has its necessary file tree in place, run it the same way as the pre-fdefined example, using your case study folder's name :

uv run python run_cases.py --name <your-case-study-name>

For example, if you created id-sg-collab:

uv run python run_cases.py --name id-sg-collab