Getting Started

This page gives an overview of OSeMOSYS Global’s workflow and the configuration options available to the user. It assumes the reader has successfully followed the installation instructions.

Project Overview

OSeMOSYS Global is an open-source, open-data model generator for creating user-configurable electricity system models. This includes creating interconnected models for both the entire globe and for any geographically diverse subset of the globe. To manage the data pipeline we use the workflow management tool snakemake. A high-level overview of OSeMOSYS Global’s snakemake workflow is shown below. The green boxes highlight where the user interfaces with the model, while the blue boxes highlight automated actions that run behind the scenes.

Repository Structure

Upon cloning OSeMOSYS Global, the directory will look similar to tree structure shown below. Highlighted are the directories where the user is expected to interface with OSeMOSYS Global. Specifically, config/config.yaml holds general configuration options, resources/custom_nodes/ holds data that the user can update to calibrate models or perform more indepth scenario analysis, finally, results/<scenario>/ will hold all result data from a scenario run. Each of these sectors is described in detail below.

osemosys_global
├── docs/                      
├── config/           
│   ├── config.yaml     # General configuration options 
├── resources/       
│   ├── custom/         # User defined data 
│   ├── default/        # Default data (DO NOT CHANGE)
├── results/            # Appears after running 
│   ├── scenario_name/  # Holds model data for your scenario
├── workflow/                         
└── ...

Configuration File

OSeMOSYS Global is a configurable model generator, allowing for full user flexibility in determining the time slice structure and geographic scope of the model and datasets. These configuration options are stored in the config/config.yaml file. An overview of the configuration file options are given below.

Top Level Options

Top level options include parameters that do not directly modify the underlying model data.

Option	Type	Restrictions	Description	Example
scenario	str	alpha-numeric	Name of Scenario	MyScenario
solver	str	One of {‘cbc’,’cplex’,’gurobi’}	Solver to use	cbc

Temporal Options

OSeMOSYS Global’s temporal structure uses a representative day approach. The minimum resolution is representing each year as a single timeslice. The maximum resolution is representing each month as an averaged 24hr day (ie. 12x24=288 timeslices). The temporal scope is between 2015 and 2100.

Option	Type	Restrictions	Description	Example
startYear	int	>=2015	First Modelled Year (inclusive)	2020
endYear	int	<=2100	Last Modelled Year (inclusive)	2050
daytype	bool		(Placeholder)	False
dayparts	dict[str,list[int]]	>=1,<=25	Hours to include in each represnetative day	D1: [1, 25]
seasons	dict[str,list[int]]	>=1,<=12	Months to include in each represnetative day	S1: [1,2,3,4,5,6,7,8,9,10,11,12]
timeshift	int	>=-11,<=12	Shifts plots from UTC for a timezone

Spatial Options

OSeMOSYS Global can natively model 164 countries seperated by 265 nodes. Users can select choose to model the entire global, or any number of countries within the world. Furthermore, functionality exists to add/remove to/from the default spatial resolution.

Option	Type	Restrictions	Description	Example
geographic_scope	list[str]	Three letter country code from here	Countries to include in model	[‘BTN’,’IND’]
nodes_to_add	list[str]	‘AAAXX’ where AAA is a 3-letter country code and XX is a 2-letter sub-national node code	Defines new nodes to add to the model	IDNSM
nodes_to_remove	list[str]	‘AAAXX’ where AAA is a 3-letter country code and XX is a 2-letter sub-national node code	Defines nodes to remove from base model	BTNXX

Generator Options

OSeMOSYS Global will automatically aggregate and ingest geo-located powerplants from global datasets, including associated techno-economic parameters. Options to add to this compiled dataset can eaisly be done. Furthermore, modelling assumptions, such as reserve margins, can be modified through the configuration file.

Option	Type	Units	Restrictions	Description	Example
no_invest_technologies	list[str]		Three letter code of technology defined here	Technologies that can not be invested in	COA
user_defined_capacity	dict[str,list[float]]		Must follow power generation naming convention here	Defines custom power generation capacity	PWRCOAINDWE01: [8, 2000, 2025, 5, 1100, 35]
–capacity	float	GW	>=0	Existing capacity	8
–build_year	float	year	>=0	Year that existing capacity was built	2000
–first_year_of_expansion	float	year	>=startYear	First year that the generator can be expanded	2025
–build_rate_per_year	float	GW	>=0	Absolute value that the line can be expanded year over year	5
–capex_cost	float	$/MW/KM	>=0	Capital cost of powerplant	1100
–efficiency	float	%	>=0,<=100	Efficiency of powerplant	35
reserve_margin	dict[str,list[float | int]]			Global reserve margin over yearly intervals	RM1: [10, 2025, 2029]
–percentage	float	%	>=0,<=100	Reserve margin	10
–start_year	int	year	>=first modeled year	Year to start specified reserve margin at (inclusive)	2025
–end_year	int	year	>=start_year	Year to end specified reserve margin at (inclusive)	2029
reserve_margin_technologies	dict[str,float]		Three letter code of technology defined here	Percentage of capacity that can contribute to reserve margin	BIO : 90
–percentage	float	%	>=0,<=100	Share of capacity that can contribute to the reserve margin	90
min_generation_factors	dict[str,list[float | str | int]]			Minimum utilization of a given technology	OCG1: [50, ‘IND’, 2021]
–value	float	%	>=0,<=100	Minimum yearly utilization rate from the technology	50
–country	str		Three letter country code within geographic scope	Country to apply min genertaion factor to	IND
–year	int	year	>=startYear,<=endYear	Year to apply minimum utilization to	2025
max_availability_factors	list[str | int | float]			Maximum yearly utilization rate of a given technology	[‘INDWE’, ‘COA’, 2023, 2050, 50]
–country/node	str		country (3 letter) or node (5 letter) code within geographic scope	Country/node to apply factor to	INDWE
–technology	str		Three letter code of technology defined here	Technology to apply factor to	COA
–start_year	int	year	>=first modelled year	Year to start applying factor at (inclusive)	2023
–end_year	int	year	>=start_year	Year to end applying factor at (inclusive)	2050
–value	float	%	>=0,<=100	Maximum yearly availabiliy factor	50

Transmission Options

OSeMOSYS Global interfaces with the Gloabl Transmission Database to ingest exising and planned transmission lines. Users can add to this dataset and modify assumptions applied to transmission lines.

Option	Type	Units	Restrictions	Description	Example
crossborderTrade	bool			Include transmission	TRUE
transmission_existing	bool			Include existing transmission from GTB	TRUE
transmission_planned	bool			Include planned transmission from GTB	TRUE
transmission_parameters	dict[str,list[float]]		Must define values for ‘HVAC’,’HVDC’,’HVDC_subsea’	Parameters to attach to all transmission lines of that type	HVAC: [779, 95400, 6.75, 0, 3.5, 4]
–Line CAPEX	float	$/MW/KM	>=0	Capital cost of transmission lines	779
–Converter pair CAPEX	float	$/MW	>=0	Capital cost of coverters	95400
–Line Losses	float	%/1000km	>=0,<=100	Losses in line	6.75
–AC/DC Converter pair losses	float	%	>=0,<=100	Losses due to converter	0
–Fixed O&M costs	float	% of CAPEX/yr	>=0	Fixed operational cost	3.5
–Variable O&M costs	float	$/MWh	>=0	Variable operational and maintenance cost	4
user_defined_capacity_transmission	dict[str,list[str | float]]			Defines custom transmission lines in the model	trn1: [TRNINDEAINDNE, 5, 1975, 2025, 2030, 2, 350, 13, 4, 95]
–technology	str		Must follow naming conventions here	Name of tranmsmission line	TRNINDEAINDNE
–capacity	float	MW	>=0	Existing capacity	5
–build_year	float	year	>=0	Year that existing capacity was built
–first_year_of_expansion	float	year	>=first modeled year	First year that the line can be expanded	2025
–final_year_of_expansion	float	year	>=first_year_of_expansion	Last year that the line can be expanded	2030
–build_rate_per_year	float	MW	>=0	Absolute value that the line can be expanded year year	2
–capex_cost	float	$/MW/km	>=0	Capital cost of transmission lines	350
–annual_fixed_O&M_cost	float	% of CAPEX/yr	>=0	Fixed operational cost	13
–variable_O&M_cost	float	$/MWh	>=0	Variable operational and maintenance cost	4
–efficiency	float	%	>=0,<=100	Efficiency of the line	95

Storage Options

OSeMOSYS Global interfaces with the DOE Gloabl Energy Storage Database to ingest exising and planned storage units. Users can add to this dataset and modify assumptions applied to storage units.

Option	Type	Unit	Restrictions	Description	Example
storage_existing	bool			Include existing storage from DOE	TRUE
storage_planned	bool			Include planned storage from DOE	TRUE
storage_parameters	dict[str,list[float]]		Must define values for short and long duration storage (‘SDS’,’LDS’)	Parameters to attach to all storage objectes of that type	SDS: [1938, 44.25, 0, 85, 4]
–capex_cost	float	$/kW	>=0	Capital cost of storage	1938
–annual_fixed_O&M_cost	float	$/kW	>=0	Annual fixed operating cost	44.25
–variable_O&M_cost	float	$/MWh	>=0	Variable operating cost	0
–roundtrip_efficiency	float	%	>=0,<=100	Roundtrip efficiency	85
–duration	float	hours	>=0	Hours of storage (ie. duration = storage capacity (GWh)/Power rating (GW))	4
user_defined_capacity_storage	dict[str,list[str | float]]			Defines custom storage in the model	sto1: [PWRSDSINDWE01, 2, 2010, 2025, 3, 1800, 40, 0, 87]
–technology	str		Must follow naming conventions here	Name of storage	PWRSDSINDWE01
–capacity	float	GW	>=0	Existing capacity	2
–build_year	float	year	>=0	Year that existing capacity was built
–first_year_of_expansion	float	year	>=first modeled year	First year that the storage can be expanded	2010
–final_year_of_expansion	float	year	>=first_year_of_expansion	Last year that the storage can be expanded	2025
–build_rate_per_year	float	GW	>=0	Absolute value that the storage can be expanded year year	3
–capex_cost	float	$/kW	>=0	Capital cost of the storage	1800
–annual_fixed_O&M_cost	float	$/kW	>=0	Fixed operational cost of storage	40
–variable_O&M_cost	float	$/MWh	>=0	Variable operational and maintenance cost of storage	0
–roundtrip_efficiency	float	%	>=0,<=100	Roundtrip efficiency of the storage	87

Policy Options

A core function of energy planning models is expoloring the impacts of different policy. This section describes the configuration options available to model different policies.

Option	Type	Units	Restrictions	Description	Example
emission_penalty	list[str | int | float]			Country level emission penalty	[‘CO2’,’IND’,2020,2050,2.1]
–emission	str		Must be ‘CO2’	Name of emission	CO2
–country	str		Three letter country code within geographic scope	Country to apply emission penalty to	IND
–start_year	int	year	>=first modelled year	First year to apply emission penalty to (inclusive)	2020
–end_year	int	year	>=start_year	Last year to apply emission penalty to (inclusive)	2050
–value	float	M$/MT	>=0	Emission penalty	2.1
emission_limit	list[str | int | float]			Country level emission limit	[‘CO2’,’IND’,LINEAR,2040,10]
–emission	str		Must be ‘CO2’	Name of emission	CO2
–country	str		Three letter country code within geographic scope	Country to apply emission penalty to	IND
–method	str		Must be one of [‘POINT’, ‘LINEAR’]	Point emission target or a linear reducing emission target	LINEAR
–year	int	year	>=first modelled year	Year to apply target to	2040
–value	float	MT	>=0	Emission limit	10
fossil_capacity_targets	list[str | int | float]			Capacity targets to apply to fossil fuel generators	[‘BTNXX’, ‘COA’, 2030, 2050, ‘ABS’, 1]
–node	str		Five letter node code within geographic scope	Node to apply capacity target to	BTNXX
–technology	str		Three letter technology code of fossil generator defined here	Technology to apply target to	COA
–start_year	int	year	>=first modelled year	Year to start capacity constraint at (inclusive)	2030
–end_year	int	year	>=start_year	Year to end capacity constraint at (inclusive)	2050
–sense	str		Must be one of [‘MIN’, ‘MAX’, ‘ABS]	Set a minimum, maximum, or fixed capacity limit	ABS
–value	float	GW	>=0	Capacity limit	1
re_targets	dict[str,list[str | list[str] | int | float]]			Renewable energy targets	TO1: [‘INDSO’, [‘WOF’,’WON’], ‘PCT’, 2025, 2045, 15]
–country/node	str		country (3 letter) or node (5 letter) code within geographic scope	Country/node to apply factor to	INDWE
–technologies	list[str]		Three letter technology code of renewable generator defined here	technologies to apply target to	[‘WOF’,’WON’]
–sense	str		Must be one of [‘PCT’, ‘ABS’]	Set a percent generation target OR a absolute capacity limit	PCT
–start_year	int	year	>=first modelled year	Year to start constraint at (inclusive)	2030
–end_year	int	year	>=start_year	Year to end constraint at (inclusive)	2050
–value	float	% or GW	>=0 (Capacity) | >=0,<=100 (Generation)	Absolute capacity limit or minimum generation percentage	15

User Defined Data

Often it may be easier to modify/update data through tabular format. In these instances users can update any of the data found in the resources/data/custom folder. Moreover, if custom nodes are defined, you must update this data. More explanation can be found on the Examples page. Here we describe how to format each user defined data csv file.

RE Potentials

Renewable Energy potentials allow you to define maximum installable capacity limits for renewable technologies at a per node level. This can be used, for example, to limit renewable installations due to land restrictions. The following information must be provided:

• Fuel Type: Energy carrier of the technology to limit.

• Node: Node to apply the limit to. (Note: the header says “CUSTOM_NODE”, but this can be applied to any default or custom node.)

• Capacity: Maximum installable capacity in GW.

An example limiting onshore wind (WON) capacity to 20GW in Canada (CAN) British Columbia (BC) is given below. This would be added to the file resources/data/custom/RE_potentials.csv.

FUEL_TYPE	CUSTOM_NODE	CAPACITY
WON	CANBC	20

RE Profiles

Renewable Energy potentials allow you to define capacity factors at a per node level. This can be used, for example, if you have a custom solar profile you wish to ingest into the model.

For Solar PV (SPV), Onshore Wind (WON), Offshore Wind (WOF), and Concentrated Solar Power (CSP), the profiles can be defined at a per-hour level. The following information must be provided:

• Datetime: Hour of year to apply profile to.

• Node: Node to apply the profile to.

• Value: Rated capacity factor as a percentage.

An example defining onshore wind (WON) capacity factors in Canada (CAN) British Columbia (BC) and Alberta (AB) is given below. This would be added to the file resources/data/custom/RE_profiles_WON.csv.

Datetime	CANBC	CANAB
01/01/2015 0:00	21.5	32.4
01/01/2015 0:00	22.1	32
01/01/2015 0:00	22.5	32.6
…	…	…
31/12/2015 22:00	11.2	35
31/12/2015 23:00	9.8	35.8

For Hydro (HYD), the profiles can be defined at a per-month level.

• Month: Month of the year.

• Node: Node to apply the profile to.

• Value: Rated availability factor as a percentage.

An example defining Hydro capacity factors in Canada (CAN) British Columbia (BC) and Alberta (AB) is given below. This would be added to the file resources/data/custom/RE_profiles_HYD.csv.

NAME	M1	M2	M3	M4	M5	M6	M7	M8	M9	M10	M11	M12
CANBC	45.6	45.8	46.8	52.4	66.3	80	80	80	80	56.9	46.4	45.7
CANAB	32.6	40.2	44.9	49.2	55.3	73.2	76.7	79	79	60.4	51.1	45.4

Residual Capacity

Residual capacity allows the user to inject exisitng capascity into the system. This is useful as global datasets may not capture smaller projects at individual nodes. This can be done for generation technologies, storage technologies, and transmission technologies. The following information must be provided:

• Fuel: Energy carrier of the residual capacity. (Generation Technologies)

• Technology: Technology of the residual capacity. (Storage and Transmission Technologies)

• Node: Node to apply the capacity to. (Note: the header says “CUSTOM_NODE”, but this can be applied to any default or custom node.)

• Year: Year to add residual capacity to.

• Capacity: Residual capacity to inject into the system.

An example of adding an additional 1 GW of residual Hydro (HYD) capacity in Canada (CAN) British Columbia (BC) in 2023 is given below. This would be added to the file resources/data/custom/residual_capacity.csv.

CUSTOM_NODE	FUEL_TYPE	START_YEAR	END_YEAR	CAPACITY
CANBC	HYD	2023	2023	1

When adding residual transmission and storage capacity, ensure you follow the pre-defined naming conventions described here. For example, adding an additional 1 GW transmission line between Canada (CAN) British Columbia (BC) and Alberta (AB) in 2023 is given below. This would be added to the file resources/data/custom/transmission_build_rates.csv.

TRANSMISSION	START_YEAR	END_YEAR	MAX_BUILD
TRNCANBCCANAB	2023	2023	1

Build Rates

Limiting the amount of capacity that can be built is often needed to control over-expansion of a single technology. Build rates can be applied to generation technologies, storage technologies, and transmission technologies. The following information must be provided:

• Fuel: Energy carrier of the residual capacity. (Generation Technologies)

• Technology: Technology of the residual capacity. (Storage and Transmission Technologies)

• Node: Node to apply the capacity to. (Note: the header says “CUSTOM_NODE”, but this can be applied to any default or custom node.)

• Start Year: First year to apply expansion limit to

• End Year: Last year to apply expansion limit to

• Capacity: Capacity expansion limit.

An example of limiting the amount of new Hydro (HYD) capacity allowed in Canada (CAN) British Columbia (BC) to 2GW between 2025 and 2050 is given below. This would be added to the file resources/data/custom/residual_capacity.csv.

CUSTOM_NODE	FUEL_TYPE	START_YEAR	END_YEAR	CAPACITY
CANBC	HYD	2025	2050	2

When adding transmission and storage capacity build limits, ensure you follow the pre-defined naming conventions described here. For example, limiting transmission line expansion between Canada (CAN) British Columbia (BC) and Alberta (AB) to 2GW between 2025 and 2050 is given below. This would be added to the file resources/data/custom/transmission_build_rates.csv.

TRANSMISSION	START_YEAR	END_YEAR	MAX_BUILD
TRNCANBCCANAB	2023	2023	1

Demand

Both the yearly annual demand demand profile at each node can be modified. The user is free to update either or both of these parameters. THis can be useful for calibrating a model, or adjusting loads based on proprietary demand projections.

To update the annual demand, the following information is needed:

• Node: Node to apply the demand to. (Note: the header says “CUSTOM_NODE”, but this can be applied to any default or custom node.)

• Year: Year to apply the demand to.

• Value: Annual demand in PJ.

An example of updating the annual demand in Canada (CAN) British Columbia (BC) is given below. This would be added to the file resources/data/custom/specified_annual_demand.csv.

CUSTOM_NODE	YEAR	VALUE
CANBC	2024	10.5
CANBC	2024	10.8
…	…	…
CANBC	2049	17.9
CANBC	2050	18.1

To update the demand profile, the following information is needed:

• Month: Month of datetime to apply profile to.

• Day: Day of datetime to apply profile to.

• Hour: Hour of datetime to apply profile to.

• Node: Node to apply the profile to.

• Value: Fractional hourly load profile value.

An example of updating the annual demand in Canada (CAN) British Columbia (BC) and Alberta (AB) is given below. This would be added to the file resources/data/custom/specified_demand_profile.csv.

Month	Day	Hour	CANBC	CANAB
1	1	0	0.00009	0.00010
1	1	1	0.00009	0.00010
1	1	2	0.00010	0.00011
…	…	…
12	31	22	0.00010	0.00011
12	31	23	0.00009	0.00011

Warning

The demand profile for each node over the year must sum up to 1.0

Primary Fuel Limits and Prices

Primary fuels, for example Coal (COA), Gas (Gas), and Oil (Oil), can be mined domestically or purchased from the international markets. Users are free to modify the primary fuel reserves in each country (not node!) and the price to import fuel from the interational markets.

To update domestic fuel resource limits, the following information is needed:

• Fuel: Primary fuel type

• Country: Country to apply the limit to. Note: this is the 3 letter country code without the 2 letter node code!

• Year: Year to apply limit to. The resource limits applied here are not cululative

• Value: Yearly resource limit in PJ

An example applying coal and gas resources limits to Canada is given in the example below. This would be added to the file resources/data/custom/fuel_limmits.csv.

FUEL	COUNTRY	VALUE	YEAR
GAS	CAN	2000	2024
GAS	COA	1500	2024
GAS	CAN	2000	2025
GAS	COA	1500	2025

If domestic fuel reserves are exhausted, fuel can be purchased and imported from the international market. The price to purchase fuels can be customized by the user. To do this, the following information is needed:

• Fuel: Primary fuel type

• Country: Country to apply the limit to. Note: this is the 3 letter country code without the 2 letter node code!

• Year: Year to apply limit to. The resource limits applied here are not cululative

• Value: Cost of fuel in $M/PJ

Note

Additionally, you can input the cost in other units (for example, $/MMBTU and include a conversion ratio as an energy content to convert to $M/PJ).

An example assigning gas and coal costs for Canada to import is given below. This would be added to the file resources/data/custom/fuel_prices.csv.

FUEL	COUNTRY	UNIT	ENERGY_CONTENT	2020	2025	2030	2040	2050
GAS	CAN	$M/PJ	1	7.5	7.5	7.5	7.5	7.5
COA	CAN	$M/PJ	1	4.68	4.68	4.68	4.68	4.68
BIO	CAN	$M/PJ	1	8	8	8	8	8
URN	CAN	$M/PJ	1	12	12	12	12	12

Warning

You must define the costs over the years 2020, 2025, 2030, 2040, and 2050 as this matches the forcast years from the World Bank Commodity Markets. Intermediate values are interpoloated.

Availability Factors

Global level availability factors for each technology can be set in the file resources/data/custom/availability_factors.csv. These file comes autopopulated with defaults. An example of how to set 90% availability factors for Coal (COA), Combined Cycle Gas (CCG) and Solar (SPV) is given below.

technology	value
COA	0.9
CCG	0.9
SPV	0.9

Operational Life

Global level operational lives for each technology can be set in the file resources/data/custom/operational_life.csv. This file comes autopopulated with defaults. An example of how to set operational lives for Coal (COA), Combined Cycle Gas (CCG) and Solar (SPV) is given below.

tech	years
COA	30
CCG	30
SPV	20

Custom Nodes

When working with custom nodes you will need to define the centerpoints of the node locations. This is needed to calculate distances between nodes for transmission line expansion. This can be done in the file resources/data/custom/centerpoints.csv. For example, adding a new node to represent Washington State (WA) in the United States (USA) is shown below. In this case, we position the node location close to Seattle, the major demand center in Washington.

region	lat	log
USAWA	47.594396616	-122.35969011

In addition to the centerpoints, user defined data for demand, capacity, and renewable profiles (among others) must also be added. See the examples page for more information.

Units

Unless otherwise specified, all results will follow the units given in the table below.

Type	Unit
Energy	PJ
Capacity	GW
Cost	$M
Emissions	MT

Data Sources

OSeMOSYS Global compiles data from an array of datasources. Listed below are the main sources used when running OSeMOSYS Global without any modifications.

Component	Source	Notes
Powerplant Capacity	PLEXOS World
Electricity Demand Timeseries	PLEXOS World
Electricity Demand Projections	Ember | PLEXOS World | IAMC
Transmission Capacity	Global Transmission Database	Existing and Planned
Powerplant Capital Costs	IEA World Energy Outlook
Powerplant Fixed Costs	IEA World Energy Outlook
Fuel Costs	World Bank Commodity Markets
Powerplant Lifetimes	NREL Annual Technology Baseline
Emission Factors	Environmental Protection Agency
Solar Timeseries	Pietzcker et al.
Wind Timeseries	Eurek et al.
Hydro Timeseries	Gernaat et al.
Storage Capacity	DOE Global Energy Storage Database	Existing and Planned
Emission Validation	Ember | ClimateWatch
Generation Validation	Ember | IRENA | EIA
Capacity Validation	Ember | IRENA | EIA