OSeMOSYS global

OSeMOSYS Global is an open-source, open-data model generator for creating global energy system models. It can be used to create inter-connected energy systems models for both the entire globe and for any geographically diverse subset of the globe. Compared to other existing global models, OSeMOSYS Global creates a full energy system representation, allows for full user flexibility in determining the modelling detail and geographic scope, and is built using the fully open-source OSeMOSYS energy system model.

Table of Contents

• Documentation
• Installation
• Getting Started
• Contributing
• Support + Feedback
• Dependencies
• License
• Citing

Documentation

TBD

Installation

1. Install GLPK

2. Install CBC

3. Install miniconda

4. Clone the git repository.

    ~/osemosys_global$ git clone --recurse-submodules https://github.com/OSeMOSYS/osemosys_global.git 

   If the repository was cloned without the --recurse-submodules flag, run the commands

   ~/osemosys_global$ git submodule init
   ~/osemosys_global$ git submodule update 

5. Create a conda environment from the supplied environment file

   (base) ~/osemosys_global$ conda env create -f workflow/envs/osemosys-global.yaml    

6. Activate the new osemosys-global environment

   (base) ~/osemosys_global$ conda activate osemosys-global

   (osemosys-global) ~/osemosys_global$ 

Troubleshooting

1. Verify that GLPK is installed by running the command glpsol.

   (osemosys-global) ~/osemosys_global$ glpsol

   GLPSOL: GLPK LP/MIP Solver, v4.65
   No input problem file specified; try glpsol --help

2. Verify that CBC is installed by running the command cbc

   (osemosys-global) ~/osemosys_global$ cbc

   Welcome to the CBC MILP Solver 
   Version: 2.10.3 
   Build Date: Mar 24 2020 
   
   CoinSolver takes input from arguments ( - switches to stdin)
   Enter ? for list of commands or help
   Coin:

   Quit the solver with the command quit

3. Verify that Conda is installed by running the command conda info

   (osemosys-global) ~/osemosys_global$ conda info

Getting Started

Flowchart

A high level overview of OSeMOSYS Global is shown below. The green boxes highlight where the user interfaces with the model. The red boxes highlight automated actions that run behind the scenes.

flowchart LR
    db[(Raw Data)]-->scripts(Data Processing Scripts)
    config(Configuration File)-->scripts
    scripts-->df(Data File)
    df-->sol(Solver)
    ose(OSeMOSYS File)-->sol
    sol-->res(Results)

    style db stroke:#f66
    style scripts stroke:#f66
    style df stroke:#f66
    style ose stroke:#f66
    style sol stroke:#f66
    style config stroke:#66ff66
    style res stroke:#66ff66

Loading

Directory Structure

The main components of the directory that the user will interface with are highlighted below. It follows the recommended snakemake directory structure.

osemosys_global
├── config                        # User configurable setup files
│   ├── config.yaml               
├── resources                      
├── resutls                       # Will appear after running 
│   ├── data                      
│   ├── figs                      # Global demand projection figures 
│   ├── scenario_name             # Repeted folder for each scenario run
│   │   ├── data/                 # Scenario input CSV data
│   │   ├── figures/              # Scenario result figures
│   │   ├── results/              # Scenario result CSV data
│   │   ├── scenario_name.txt     # Scenario data file
├── workflow                         
└── ...

Configuration File

Numerous parameters have been exposed to the user to control the model. These parameters are stored in the osemosys_global/config/config.yaml file.

Examples

Run the Workflow with Default Settings

1. Run the command snakemake -c

   (osemosys-global) ~/osemosys_global$ snakemake -c

2. View system level results in the results/India/figures folder

Run a scenario for Bangladesh, Bhutan, India, and Nepal (BBIN) with trade and an emission penalty of $25/Tonne

1. Change the scenario name in config/config.yaml

   scenario: 'BBIN'

2. Change the geographic scope in config/config.yaml

   geographic_scope:
   - 'IND'
   - 'BGD'
   - 'BTN'
   - 'NPL'

3. Update the crossborderTrade parameter in config/config.yaml

   crossborderTrade: True

4. Change the emission penalty in config/config.yaml

   emission_penalty: 25 

5. Run the command snakemake -c

   (osemosys-global) ~/osemosys_global$ snakemake -c

6. View system level and country results in the results/BBIN/figures folder

Run a World scenario from 2020 to 2040 graphing results at a system level only

1. Change the scenario name in config/config.yaml

   scenario: 'WORLD'

2. Delete everything under the geographic scope in config/config.yaml

   geographic_scope:

3. Change the startYear and endYear parameters in config/config.yaml

   startYear: 2020
   endYear: 2040

4. Set the results to only graph at a system level in config/config.yaml

   results_by_country: False

5. Run the command snakemake -c (This scenarion will take ~7hrs to run on a high performance computer)

   (osemosys-global) ~/osemosys_global$ snakemake -c

6. View system level results in the results/WORLD/figures folder

Contributing

We appreciate feedback and contribution to this repo! Please see our contribution guide for information on how to conribute.

Support + Feedback

We encourage community memebers to ask questions and report any issues they encounter.

• For asking general usage questions, please use the commuity fourm.
• For reporting code and data issues, please use the appropiate issue template

Dependencies

OSeMOSYS Global relies on numerous open-source community supported tools. Below is a list on the heavily used packages that we hope you investigate further for yourself!

• Python is used for all data processing
• Anaconda and Miniconda are used to manage Python packages
• Snakemake is a Python based workflow management tool
• otoole is a Python based command line interface used generate OSeMOSYS input and output datafiles
• Pandas is a Python package used to transform and analyze data
• Plotly is a Python package for data visualization
• GLPK is used to create linear programming data files
• CBC is a linear programming and mixed integer program solver

License

OSeMOSYS Global is liscenced under a MIT liscence. Please see our LICENSE doc for more information.

Citing

TBD