From f7274c7dac59af8c72a7ff27dfbb5020c047f6c0 Mon Sep 17 00:00:00 2001 From: trevorb1 Date: Tue, 18 Feb 2025 11:16:29 -0800 Subject: [PATCH] example page added --- docs/api/osemosys_global.emissions.rst | 71 ++++ docs/api/osemosys_global.powerplant.rst | 159 ++++++++ docs/api/osemosys_global.reserves.rst | 55 +++ docs/api/osemosys_global.rst | 104 ++---- docs/api/osemosys_global.storage.rst | 119 ++++++ docs/api/osemosys_global.summary.rst | 71 ++++ docs/api/osemosys_global.transmission.rst | 103 ++++++ docs/api/osemosys_global.validation.rst | 55 +++ docs/api/osemosys_global.visualisation.rst | 8 + docs/conf.py | 2 +- docs/examples.md | 398 ++++++++++++++++++++ docs/getting-started.md | 399 --------------------- docs/index.md | 1 + 13 files changed, 1061 insertions(+), 484 deletions(-) create mode 100644 docs/api/osemosys_global.emissions.rst create mode 100644 docs/api/osemosys_global.powerplant.rst create mode 100644 docs/api/osemosys_global.reserves.rst create mode 100644 docs/api/osemosys_global.storage.rst create mode 100644 docs/api/osemosys_global.summary.rst create mode 100644 docs/api/osemosys_global.transmission.rst create mode 100644 docs/api/osemosys_global.validation.rst create mode 100644 docs/examples.md diff --git a/docs/api/osemosys_global.emissions.rst b/docs/api/osemosys_global.emissions.rst new file mode 100644 index 00000000..219cf081 --- /dev/null +++ b/docs/api/osemosys_global.emissions.rst @@ -0,0 +1,71 @@ +osemosys\_global.emissions namespace +==================================== + +.. py:module:: osemosys_global.emissions + +Submodules +---------- + +osemosys\_global.emissions.constants module +------------------------------------------- + +.. automodule:: osemosys_global.emissions.constants + :members: + :undoc-members: + :show-inheritance: + +osemosys\_global.emissions.data module +-------------------------------------- + +.. automodule:: osemosys_global.emissions.data + :members: + :undoc-members: + :show-inheritance: + +osemosys\_global.emissions.emission\_activity\_ratio module +----------------------------------------------------------- + +.. automodule:: osemosys_global.emissions.emission_activity_ratio + :members: + :undoc-members: + :show-inheritance: + +osemosys\_global.emissions.emission\_limit module +------------------------------------------------- + +.. automodule:: osemosys_global.emissions.emission_limit + :members: + :undoc-members: + :show-inheritance: + +osemosys\_global.emissions.emission\_penalty module +--------------------------------------------------- + +.. automodule:: osemosys_global.emissions.emission_penalty + :members: + :undoc-members: + :show-inheritance: + +osemosys\_global.emissions.main module +-------------------------------------- + +.. automodule:: osemosys_global.emissions.main + :members: + :undoc-members: + :show-inheritance: + +osemosys\_global.emissions.read module +-------------------------------------- + +.. automodule:: osemosys_global.emissions.read + :members: + :undoc-members: + :show-inheritance: + +osemosys\_global.emissions.sets module +-------------------------------------- + +.. automodule:: osemosys_global.emissions.sets + :members: + :undoc-members: + :show-inheritance: diff --git a/docs/api/osemosys_global.powerplant.rst b/docs/api/osemosys_global.powerplant.rst new file mode 100644 index 00000000..c0f4d603 --- /dev/null +++ b/docs/api/osemosys_global.powerplant.rst @@ -0,0 +1,159 @@ +osemosys\_global.powerplant namespace +===================================== + +.. py:module:: osemosys_global.powerplant + +Submodules +---------- + +osemosys\_global.powerplant.GEM\_unused module +---------------------------------------------- + +.. automodule:: osemosys_global.powerplant.GEM_unused + :members: + :undoc-members: + :show-inheritance: + +osemosys\_global.powerplant.activity module +------------------------------------------- + +.. automodule:: osemosys_global.powerplant.activity + :members: + :undoc-members: + :show-inheritance: + +osemosys\_global.powerplant.availability module +----------------------------------------------- + +.. automodule:: osemosys_global.powerplant.availability + :members: + :undoc-members: + :show-inheritance: + +osemosys\_global.powerplant.backstop module +------------------------------------------- + +.. automodule:: osemosys_global.powerplant.backstop + :members: + :undoc-members: + :show-inheritance: + +osemosys\_global.powerplant.calibration module +---------------------------------------------- + +.. automodule:: osemosys_global.powerplant.calibration + :members: + :undoc-members: + :show-inheritance: + +osemosys\_global.powerplant.constants module +-------------------------------------------- + +.. automodule:: osemosys_global.powerplant.constants + :members: + :undoc-members: + :show-inheritance: + +osemosys\_global.powerplant.costs module +---------------------------------------- + +.. automodule:: osemosys_global.powerplant.costs + :members: + :undoc-members: + :show-inheritance: + +osemosys\_global.powerplant.data module +--------------------------------------- + +.. automodule:: osemosys_global.powerplant.data + :members: + :undoc-members: + :show-inheritance: + +osemosys\_global.powerplant.fuel\_limits module +----------------------------------------------- + +.. automodule:: osemosys_global.powerplant.fuel_limits + :members: + :undoc-members: + :show-inheritance: + +osemosys\_global.powerplant.investment\_constraints module +---------------------------------------------------------- + +.. automodule:: osemosys_global.powerplant.investment_constraints + :members: + :undoc-members: + :show-inheritance: + +osemosys\_global.powerplant.main module +--------------------------------------- + +.. automodule:: osemosys_global.powerplant.main + :members: + :undoc-members: + :show-inheritance: + +osemosys\_global.powerplant.operational\_life module +---------------------------------------------------- + +.. automodule:: osemosys_global.powerplant.operational_life + :members: + :undoc-members: + :show-inheritance: + +osemosys\_global.powerplant.read module +--------------------------------------- + +.. automodule:: osemosys_global.powerplant.read + :members: + :undoc-members: + :show-inheritance: + +osemosys\_global.powerplant.renewable\_targets module +----------------------------------------------------- + +.. automodule:: osemosys_global.powerplant.renewable_targets + :members: + :undoc-members: + :show-inheritance: + +osemosys\_global.powerplant.residual\_capacity module +----------------------------------------------------- + +.. automodule:: osemosys_global.powerplant.residual_capacity + :members: + :undoc-members: + :show-inheritance: + +osemosys\_global.powerplant.sets module +--------------------------------------- + +.. automodule:: osemosys_global.powerplant.sets + :members: + :undoc-members: + :show-inheritance: + +osemosys\_global.powerplant.user\_defined\_capacity module +---------------------------------------------------------- + +.. automodule:: osemosys_global.powerplant.user_defined_capacity + :members: + :undoc-members: + :show-inheritance: + +osemosys\_global.powerplant.utils module +---------------------------------------- + +.. automodule:: osemosys_global.powerplant.utils + :members: + :undoc-members: + :show-inheritance: + +osemosys\_global.powerplant.variable\_costs module +-------------------------------------------------- + +.. automodule:: osemosys_global.powerplant.variable_costs + :members: + :undoc-members: + :show-inheritance: diff --git a/docs/api/osemosys_global.reserves.rst b/docs/api/osemosys_global.reserves.rst new file mode 100644 index 00000000..62c73b77 --- /dev/null +++ b/docs/api/osemosys_global.reserves.rst @@ -0,0 +1,55 @@ +osemosys\_global.reserves namespace +=================================== + +.. py:module:: osemosys_global.reserves + +Submodules +---------- + +osemosys\_global.reserves.data module +------------------------------------- + +.. automodule:: osemosys_global.reserves.data + :members: + :undoc-members: + :show-inheritance: + +osemosys\_global.reserves.main module +------------------------------------- + +.. automodule:: osemosys_global.reserves.main + :members: + :undoc-members: + :show-inheritance: + +osemosys\_global.reserves.read module +------------------------------------- + +.. automodule:: osemosys_global.reserves.read + :members: + :undoc-members: + :show-inheritance: + +osemosys\_global.reserves.reserve\_margin module +------------------------------------------------ + +.. automodule:: osemosys_global.reserves.reserve_margin + :members: + :undoc-members: + :show-inheritance: + +osemosys\_global.reserves.reserve\_margin\_tag\_fuel module +----------------------------------------------------------- + +.. automodule:: osemosys_global.reserves.reserve_margin_tag_fuel + :members: + :undoc-members: + :show-inheritance: + +osemosys\_global.reserves.reserve\_margin\_tag\_technology module +----------------------------------------------------------------- + +.. automodule:: osemosys_global.reserves.reserve_margin_tag_technology + :members: + :undoc-members: + :show-inheritance: diff --git a/docs/api/osemosys_global.rst b/docs/api/osemosys_global.rst index ceb782b6..32061865 100644 --- a/docs/api/osemosys_global.rst +++ b/docs/api/osemosys_global.rst @@ -8,6 +8,14 @@ Subpackages :maxdepth: 4 osemosys_global.dashboard + osemosys_global.demand + osemosys_global.emissions + osemosys_global.powerplant + osemosys_global.reserves + osemosys_global.storage + osemosys_global.summary + osemosys_global.transmission + osemosys_global.validation osemosys_global.visualisation Submodules @@ -21,10 +29,10 @@ osemosys\_global.TS\_data module :undoc-members: :show-inheritance: -osemosys\_global.configuration module -------------------------------------- +osemosys\_global.check\_backstop module +--------------------------------------- -.. automodule:: osemosys_global.configuration +.. automodule:: osemosys_global.check_backstop :members: :undoc-members: :show-inheritance: @@ -37,26 +45,26 @@ osemosys\_global.constants module :undoc-members: :show-inheritance: -osemosys\_global.demand\_projection module ------------------------------------------- +osemosys\_global.create\_missing\_csvs module +--------------------------------------------- -.. automodule:: osemosys_global.demand_projection +.. automodule:: osemosys_global.create_missing_csvs :members: :undoc-members: :show-inheritance: -osemosys\_global.emissions module ---------------------------------- +osemosys\_global.custom module +------------------------------ -.. automodule:: osemosys_global.emissions +.. automodule:: osemosys_global.custom :members: :undoc-members: :show-inheritance: -osemosys\_global.file\_check module ------------------------------------ +osemosys\_global.external\_files module +--------------------------------------- -.. automodule:: osemosys_global.file_check +.. automodule:: osemosys_global.external_files :members: :undoc-members: :show-inheritance: @@ -69,54 +77,6 @@ osemosys\_global.geographic\_filter module :undoc-members: :show-inheritance: -osemosys\_global.max\_capacity module -------------------------------------- - -.. automodule:: osemosys_global.max_capacity - :members: - :undoc-members: - :show-inheritance: - -osemosys\_global.node\_mapping module -------------------------------------- - -.. automodule:: osemosys_global.node_mapping - :members: - :undoc-members: - :show-inheritance: - -osemosys\_global.powerplant\_data module ----------------------------------------- - -.. automodule:: osemosys_global.powerplant_data - :members: - :undoc-members: - :show-inheritance: - -osemosys\_global.summarise\_results module ------------------------------------------- - -.. automodule:: osemosys_global.summarise_results - :members: - :undoc-members: - :show-inheritance: - -osemosys\_global.trade\_flows module ------------------------------------- - -.. automodule:: osemosys_global.trade_flows - :members: - :undoc-members: - :show-inheritance: - -osemosys\_global.user\_defined\_capacity module ------------------------------------------------ - -.. automodule:: osemosys_global.user_defined_capacity - :members: - :undoc-members: - :show-inheritance: - osemosys\_global.utils module ----------------------------- @@ -125,30 +85,6 @@ osemosys\_global.utils module :undoc-members: :show-inheritance: -osemosys\_global.variablecosts module -------------------------------------- - -.. automodule:: osemosys_global.variablecosts - :members: - :undoc-members: - :show-inheritance: - -osemosys\_global.visualisation module -------------------------------------- - -.. automodule:: osemosys_global.visualisation - :members: - :undoc-members: - :show-inheritance: - -osemosys\_global.visualise module ---------------------------------- - -.. automodule:: osemosys_global.visualise - :members: - :undoc-members: - :show-inheritance: - Module contents --------------- diff --git a/docs/api/osemosys_global.storage.rst b/docs/api/osemosys_global.storage.rst new file mode 100644 index 00000000..2a260d0e --- /dev/null +++ b/docs/api/osemosys_global.storage.rst @@ -0,0 +1,119 @@ +osemosys\_global.storage namespace +================================== + +.. py:module:: osemosys_global.storage + +Submodules +---------- + +osemosys\_global.storage.activity module +---------------------------------------- + +.. automodule:: osemosys_global.storage.activity + :members: + :undoc-members: + :show-inheritance: + +osemosys\_global.storage.constants module +----------------------------------------- + +.. automodule:: osemosys_global.storage.constants + :members: + :undoc-members: + :show-inheritance: + +osemosys\_global.storage.costs module +------------------------------------- + +.. automodule:: osemosys_global.storage.costs + :members: + :undoc-members: + :show-inheritance: + +osemosys\_global.storage.data module +------------------------------------ + +.. automodule:: osemosys_global.storage.data + :members: + :undoc-members: + :show-inheritance: + +osemosys\_global.storage.investment\_constraints module +------------------------------------------------------- + +.. automodule:: osemosys_global.storage.investment_constraints + :members: + :undoc-members: + :show-inheritance: + +osemosys\_global.storage.main module +------------------------------------ + +.. automodule:: osemosys_global.storage.main + :members: + :undoc-members: + :show-inheritance: + +osemosys\_global.storage.operational\_life module +------------------------------------------------- + +.. automodule:: osemosys_global.storage.operational_life + :members: + :undoc-members: + :show-inheritance: + +osemosys\_global.storage.read module +------------------------------------ + +.. automodule:: osemosys_global.storage.read + :members: + :undoc-members: + :show-inheritance: + +osemosys\_global.storage.residual\_capacity module +-------------------------------------------------- + +.. automodule:: osemosys_global.storage.residual_capacity + :members: + :undoc-members: + :show-inheritance: + +osemosys\_global.storage.sets module +------------------------------------ + +.. automodule:: osemosys_global.storage.sets + :members: + :undoc-members: + :show-inheritance: + +osemosys\_global.storage.storage\_level module +---------------------------------------------- + +.. automodule:: osemosys_global.storage.storage_level + :members: + :undoc-members: + :show-inheritance: + +osemosys\_global.storage.technology\_to\_from\_storage module +------------------------------------------------------------- + +.. automodule:: osemosys_global.storage.technology_to_from_storage + :members: + :undoc-members: + :show-inheritance: + +osemosys\_global.storage.user\_defined\_capacity module +------------------------------------------------------- + +.. automodule:: osemosys_global.storage.user_defined_capacity + :members: + :undoc-members: + :show-inheritance: + +osemosys\_global.storage.utils module +------------------------------------- + +.. automodule:: osemosys_global.storage.utils + :members: + :undoc-members: + :show-inheritance: diff --git a/docs/api/osemosys_global.summary.rst b/docs/api/osemosys_global.summary.rst new file mode 100644 index 00000000..14575d3d --- /dev/null +++ b/docs/api/osemosys_global.summary.rst @@ -0,0 +1,71 @@ +osemosys\_global.summary namespace +================================== + +.. py:module:: osemosys_global.summary + +Submodules +---------- + +osemosys\_global.summary.capacity module +---------------------------------------- + +.. automodule:: osemosys_global.summary.capacity + :members: + :undoc-members: + :show-inheritance: + +osemosys\_global.summary.carbon\_intensity module +------------------------------------------------- + +.. automodule:: osemosys_global.summary.carbon_intensity + :members: + :undoc-members: + :show-inheritance: + +osemosys\_global.summary.constants module +----------------------------------------- + +.. automodule:: osemosys_global.summary.constants + :members: + :undoc-members: + :show-inheritance: + +osemosys\_global.summary.costs module +------------------------------------- + +.. automodule:: osemosys_global.summary.costs + :members: + :undoc-members: + :show-inheritance: + +osemosys\_global.summary.gen\_shares module +------------------------------------------- + +.. automodule:: osemosys_global.summary.gen_shares + :members: + :undoc-members: + :show-inheritance: + +osemosys\_global.summary.headline module +---------------------------------------- + +.. automodule:: osemosys_global.summary.headline + :members: + :undoc-members: + :show-inheritance: + +osemosys\_global.summary.summarise\_results module +-------------------------------------------------- + +.. automodule:: osemosys_global.summary.summarise_results + :members: + :undoc-members: + :show-inheritance: + +osemosys\_global.summary.trade\_flows module +-------------------------------------------- + +.. automodule:: osemosys_global.summary.trade_flows + :members: + :undoc-members: + :show-inheritance: diff --git a/docs/api/osemosys_global.transmission.rst b/docs/api/osemosys_global.transmission.rst new file mode 100644 index 00000000..90c136f0 --- /dev/null +++ b/docs/api/osemosys_global.transmission.rst @@ -0,0 +1,103 @@ +osemosys\_global.transmission namespace +======================================= + +.. py:module:: osemosys_global.transmission + +Submodules +---------- + +osemosys\_global.transmission.activity module +--------------------------------------------- + +.. automodule:: osemosys_global.transmission.activity + :members: + :undoc-members: + :show-inheritance: + +osemosys\_global.transmission.constants module +---------------------------------------------- + +.. automodule:: osemosys_global.transmission.constants + :members: + :undoc-members: + :show-inheritance: + +osemosys\_global.transmission.costs module +------------------------------------------ + +.. automodule:: osemosys_global.transmission.costs + :members: + :undoc-members: + :show-inheritance: + +osemosys\_global.transmission.data module +----------------------------------------- + +.. automodule:: osemosys_global.transmission.data + :members: + :undoc-members: + :show-inheritance: + +osemosys\_global.transmission.investment\_constraints module +------------------------------------------------------------ + +.. automodule:: osemosys_global.transmission.investment_constraints + :members: + :undoc-members: + :show-inheritance: + +osemosys\_global.transmission.main module +----------------------------------------- + +.. automodule:: osemosys_global.transmission.main + :members: + :undoc-members: + :show-inheritance: + +osemosys\_global.transmission.operational\_life module +------------------------------------------------------ + +.. automodule:: osemosys_global.transmission.operational_life + :members: + :undoc-members: + :show-inheritance: + +osemosys\_global.transmission.read module +----------------------------------------- + +.. automodule:: osemosys_global.transmission.read + :members: + :undoc-members: + :show-inheritance: + +osemosys\_global.transmission.residual\_capacity module +------------------------------------------------------- + +.. automodule:: osemosys_global.transmission.residual_capacity + :members: + :undoc-members: + :show-inheritance: + +osemosys\_global.transmission.sets module +----------------------------------------- + +.. automodule:: osemosys_global.transmission.sets + :members: + :undoc-members: + :show-inheritance: + +osemosys\_global.transmission.user\_defined\_capacity module +------------------------------------------------------------ + +.. automodule:: osemosys_global.transmission.user_defined_capacity + :members: + :undoc-members: + :show-inheritance: + +osemosys\_global.transmission.utils module +------------------------------------------ + +.. automodule:: osemosys_global.transmission.utils + :members: + :undoc-members: + :show-inheritance: diff --git a/docs/api/osemosys_global.validation.rst b/docs/api/osemosys_global.validation.rst new file mode 100644 index 00000000..8b220542 --- /dev/null +++ b/docs/api/osemosys_global.validation.rst @@ -0,0 +1,55 @@ +osemosys\_global.validation namespace +===================================== + +.. py:module:: osemosys_global.validation + +Submodules +---------- + +osemosys\_global.validation.climate\_watch module +------------------------------------------------- + +.. automodule:: osemosys_global.validation.climate_watch + :members: + :undoc-members: + :show-inheritance: + +osemosys\_global.validation.eia module +-------------------------------------- + +.. automodule:: osemosys_global.validation.eia + :members: + :undoc-members: + :show-inheritance: + +osemosys\_global.validation.ember module +---------------------------------------- + +.. automodule:: osemosys_global.validation.ember + :members: + :undoc-members: + :show-inheritance: + +osemosys\_global.validation.irena module +---------------------------------------- + +.. automodule:: osemosys_global.validation.irena + :members: + :undoc-members: + :show-inheritance: + +osemosys\_global.validation.main module +--------------------------------------- + +.. automodule:: osemosys_global.validation.main + :members: + :undoc-members: + :show-inheritance: + +osemosys\_global.validation.utils module +---------------------------------------- + +.. automodule:: osemosys_global.validation.utils + :members: + :undoc-members: + :show-inheritance: diff --git a/docs/api/osemosys_global.visualisation.rst b/docs/api/osemosys_global.visualisation.rst index d7007307..3392a7b6 100644 --- a/docs/api/osemosys_global.visualisation.rst +++ b/docs/api/osemosys_global.visualisation.rst @@ -28,6 +28,14 @@ osemosys\_global.visualisation.utils module :undoc-members: :show-inheritance: +osemosys\_global.visualisation.visualise module +----------------------------------------------- + +.. automodule:: osemosys_global.visualisation.visualise + :members: + :undoc-members: + :show-inheritance: + Module contents --------------- diff --git a/docs/conf.py b/docs/conf.py index fe9f0f20..827ca5e8 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -119,7 +119,7 @@ # General information about the project. project = "OSeMOSYS Global" -copyright = "2022, osemosys" +copyright = "2025, osemosys" # copyright = f"{datetime.datetime.today().year}, {author}" diff --git a/docs/examples.md b/docs/examples.md new file mode 100644 index 00000000..5ddf5591 --- /dev/null +++ b/docs/examples.md @@ -0,0 +1,398 @@ +# Examples + +Below are some simple examples you can follow to understand how OSeMOSYS Global +works. + +:::{caution} +Before running any examples, ensure you first follow our +[installation instructions](installation.md#installation) and perform the +following two steps. + +1. Navigate to the root OSeMOSYS Global directory in the command line + + ```bash + (base) $ cd ~/osemosys_global + + (base) ~/osemosys_global$ + ``` + +2. Activate the `osemosys-global` conda environment + + ```bash + (base) ~/osemosys_global$ conda activate osemosys-global + + (osemosys-global) ~/osemosys_global$ + ``` +::: + +:::{warning} +If you installed CPLEX or Gurobi instead of CBC, you must first change this in +the configuration file at `config/config.yaml` +::: + +## Example 1 + +**Goal**: Run the workflow with default settings. This will produce a model +of India from 2015 to 2050 with 8 time slices per year, and solve it using CBC. + +1. Run the command `snakemake -j6`. The time to build and solve the model will +vary depending on your computer, but in general, this example will finish +within minutes . + + ```bash + (osemosys-global) ~/osemosys_global$ snakemake -j6 + ``` + + :::{tip} + The `-j6` command will instruct Snakemake to use six cores. + If your want to restrict this, change the number after the `-j` to + specify the number of cores. For example, the command `snakemake -j2` will + run the workflow using 2 cores. See + [snakemake's documentation](https://snakemake.readthedocs.io/en/stable/executing/cli.html#useful-command-line-arguments) + for more information. + ::: + +2. Navigate to the newly created `results/` folder. All available automatically +generated results are summarized below. + + ``` bash + osemosys_global + ├── resutls # Will appear after running the workflow + │ ├── data # Global CSV OSeMOSYS data + │ ├── figs + │ │ ├── ... # Global demand projections + │ ├── india # Name of scenario + │ │ ├── data/ # Scenario input CSV data + │ │ ├── figures + │ │ │ ├── GenerationAnnual.html + │ │ │ ├── GenerationHourly.html + │ │ │ ├── TotalCapacityAnnual.html + │ │ │ ├── TransmissionCapacity2050.jpg + │ │ │ ├── TransmissionFlow2050.jpg + │ │ ├── result_summaries + │ │ │ ├── Capacities.csv + │ │ │ ├── Generation_By_Node.csv + │ │ │ ├── Generation.csv + │ │ │ ├── Metrics.csv + │ │ │ ├── TradeFlows.csv + │ │ ├── results/ # Scenario result CSV data + │ │ ├── india.txt # Scenario OSeMOSYS data file + └── ... + ``` + + | File | Description | + |---------|-------------| + | `GenerationAnnual.html` | Plot of system level annual generation by technology | + | `GenerationHourly.html` | Plot of system level technology generation by timeslice | + | `TotalCapacityAnnual.html` | Plot of system level annual capacity by technology | + | `Capacities.csv` | Table of nodal level annual capacity by technology | + | `Generation_By_Node.csv` | Table of nodal level technology generation by timeslice | + | `Generation.csv` | Table of system level technology generation by timeslice | + | `Metrics.csv` | Table of system level cost and emission statistics | + | `TradeFlows.csv` | Table of nodal level electricity trade by timeslice | + | `TransmissionCapacityXXXX.jpg` | Transmission capacity plot for last year of model | + | `TransmissionFlowXXXX.jpg` | Transmission flow plot for last year of model | + +3. View system level capacity and generation results. + + :::{caution} + These results are used to showcase the capabilities of OSeMOSYS Global. The + actual energy supply mix results may need further analysis, such as removing + technology bias though implementing resource limits on nuclear. + ::: + + ![Example-1.1](_static/example_1.1.png "Example-1.1") + ![Example-1.2](_static/example_1.2.png "Example-1.2") + + :::{tip} + These plots are interactive! Howver over the bars to view values, or + double click on a power plant in the legend to single it out. + ::: + +4. View demand projections results for Asia in the file +`results/figs/Demand projection Asia.jpg`. Grey dots represent historical +country level values for countries in Asia and the coloured dots show projected +values. + + ![Example-1.3](_static/example_1.3.png "Example-1.3") + +## Example 2 + +**Goal**: Modify the geographic scope, temporal settings, and emission penalty +of the model. + +The goal of this scenario will be to change the geographic scope to add +Bangladesh, Bhutan, and Nepal to the model. Moreover, we will change the model +horizon to be from 2020-2040 and increase the number of time slices per year +from 8 to 18. Finally, we will ensure cross border trade is allowed, set the +emission penalty to $50/T, and create country level result plots. + +1. Navigate to and open the file `config/config.yaml` + +2. Change the scenario name to BBIN (**B**angladesh, **B**hutan, **I**ndia, +and **N**epal) + + ```yaml + scenario: 'BBIN' + ``` + +3. Change the geographic scope to include the mentioned countries. + + ```yaml + geographic_scope: + - 'IND' + - 'BGD' + - 'BTN' + - 'NPL' + ``` + +4. Change the model horizon to be from 2020 to 2040. Both numbers are inclusive. + + ```yaml + startYear: 2020 + endYear: 2040 + ``` + +5. Change the number of day parts to represent three even 8 hour segments per +day. The start number is inclusive, while the end number is exclusive. + + ```yaml + dayparts: + D1: [0, 8] + D2: [8, 16] + D3: [16, 24] + ``` + +6. Change the number of seasons to represent 6 equally spaced days. Both numbers +are inclusive. + + ```yaml + seasons: + S1: [1, 2] + S2: [3, 4] + S3: [5, 6] + S4: [7, 8] + S5: [9, 10] + S6: [11, 12] + ``` + + :::{tip} + A timeslice strucutre of 6 seasons and 3 dayparts will result in a model + with 18 timeslices per year; 6 representative days each with 3 timeslices. + + See the [OSeMOSYS documentation](https://osemosys.readthedocs.io/en/latest/index.html) + has more information on the OSeMOSYS timeslice parameters. + ::: + +6. Ensure the `crossborderTrade` parameter is set to `True` + + ```yaml + crossborderTrade: True + ``` + +7. Change the emission penalty to `50` $/T + + ```yaml + emission_penalty: + - ["CO2", "IND", 2020, 2040, 50] + - ["CO2", "BGD", 2020, 2040, 50] + - ["CO2", "BTN", 2020, 2040, 50] + - ["CO2", "NPL", 2020, 2040, 50] + ``` + +8. Run the command `snakemake -j6` + + ```bash + (osemosys-global) ~/osemosys_global$ snakemake -j6 + ``` + + :::{tip} + If you run into any issues with the workflow, run the command + `snakemake clean -c`. This will delete any auto generated files and + bring you back to a clean start. + ::: + +9. Navigate to the `results/` folder to view results from this model run. + + Notice how under `figures/`, there is now a folder for each country. By + setting the `crossborderTrade` parameter to be true, we tell the + workflow to create out both system level and country level plots. + + ``` bash + osemosys_global + ├── resutls + │ ├── data # Global CSV OSeMOSYS data + │ ├── figs + │ │ ├── ... # Global demand projections + │ ├── india + │ ├── BBIN # Name of scenario + │ │ ├── data/ # Scenario input CSV data + │ │ ├── figures + │ │ │ ├── BTN + │ │ │ │ ├── GenerationAnnual.html + │ │ │ │ ├── TotalCapacityAnnual.html + │ │ │ ├── BGD + │ │ │ │ ├── GenerationAnnual.html + │ │ │ │ ├── TotalCapacityAnnual.html + │ │ │ ├── IND + │ │ │ │ ├── GenerationAnnual.html + │ │ │ │ ├── TotalCapacityAnnual.html + │ │ │ ├── NPL + │ │ │ │ ├── GenerationAnnual.html + │ │ │ │ ├── TotalCapacityAnnual.html + │ │ │ ├── GenerationAnnual.html + │ │ │ ├── GenerationHourly.html + │ │ │ ├── TotalCapacityAnnual.html + │ │ │ ├── TransmissionCapacity2040.jpg + │ │ │ ├── TransmissionFlow2040.jpg + │ │ ├── result_summaries # Auto generated result tables + │ │ ├── results/ # Scenario result CSV data + │ │ ├── BBIN.txt # Scenario OSeMOSYS data file + └── ... + ``` + + :::{note} + If you don't change clean the model results, the previous scenario + results are saved as long as you change the scenario name. + ::: + +10. View system level 2040 hourly generation results by viewing the file +`results/BBIN/figures/GenerationHourly.html` + + :::{caution} + These results are used to showcase the capabilities of OSeMOSYS Global. The + actual energy supply mix results may need further analysis, such as removing + technology bias though implementing resource limits on nuclear. + ::: + + ![Example-2](_static/example_2.png "Example-2") + +3. View system level metrics for this model run by looking at the file +`results/BBIN/result_summaries/Metrics.csv` + + | Metric | Unit | Value | + |---------------------|---------------------------|-------| + | Emissions | Million tonnes of CO2-eq. | 1221 | + | RE Share | % | 10 | + | Total System Cost | Billion $ | 1544 | + | Cost of electricity | $/MWh | 20 | + | Fossil fuel share | % | 4 | + + +## Example 3 + +**Goal**: Rerun the BBIN example with new interconnectors. + +The goal of this scenario will be to rerun the BBIN scenario +([example 2](#example-2)), except we will tell the model to install three new +electricity interconnectors. In 2025 we will install a 3GW interconnector +between India and Nepal. Then in 2030 we will install a 1GW and 750MW +interconnector between India and Bhutan and India and Bangladesh respectively. + +1. Change the scenario name + + ```yaml + scenario: 'BBIN_Interconnector' + ``` + +2. Configure the new interconnectors + + ```yaml + user_defined_capacity: + TRNINDNONPLXX: [3, 2025] + TRNINDNEBTNXX: [1, 2030] + TRNINDEABGDXX: [0.75, 2030] + ``` + + :::{note} + The last two letters in the region (ie. `NO`, `NE`, and `EA` for India, or + `XX` for Nepal, Bhutan and Bangladesh) represent the node in each region. + See our [model structure](./model-structure.md#spatial-codes) + document for more information on this. + ::: + +3. View the trade capacity plot in 2040 by looking at the file +`results/BBIN_interconnector/figures/TransmissionCapacity2040.jpg` + + + +4. View the trade flow plot in 2040 by looking at the file +`results/BBIN_interconnector/figures/TransmissionFlow2040.jpg` + + + + +## Example 4 + +**Goal**: Run a World Example + +The goal of this scenario is to run a World scenario from 2015 to 2050 with +8 time slices, solve it using CPLEX, and graphing results at a system level only + +1. Change the scenario name + + ```yaml + scenario: 'WORLD' + ``` + +2. Delete everything under the geographic scope + + ```yaml + geographic_scope: + ``` + + :::{caution} + Do **NOT** delete the `geographic_scope:` keyword + ::: + +3. Change the model horizon to be from 2015 to 2050. Both numbers are inclusive. + + ```yaml + startYear: 2015 + endYear: 2050 + ``` + +4. Reset the temporal parameters back to defaults. + + ```yaml + dayparts: + D1: [0, 12] + D2: [12, 24] + + seasons: + S1: [12, 1, 2] + S2: [3, 4, 5] + S3: [6, 7, 8] + S4: [9, 10, 11] + ``` + +5. Remove the time shift to set to UTC time. + + ```yaml + timeshift: 0 + ``` + +6. Set the results to only graph at a system level + + ```yaml + results_by_country: False + ``` + +7. Set the solver to `CPLEX` + + ```yaml + solver: 'cplex' + ``` + +8. Run the command `snakemake -j6` + + :::{warning} + This scenario will take multiple hours to run using a commercial solver + (Gurobi or CPLEX) on a high performance computer. + ::: + + ```bash + (osemosys-global) ~/osemosys_global$ snakemake -j6 + ``` + +8. View system level results in the `results/WORLD/figures` folder \ No newline at end of file diff --git a/docs/getting-started.md b/docs/getting-started.md index f6169dce..3f73d87c 100644 --- a/docs/getting-started.md +++ b/docs/getting-started.md @@ -56,405 +56,6 @@ Our [model structure](./model-structure.md) document for full details on technology and commodity names ::: -## Examples - -Below are some simple examples you can follow to understand how OSeMOSYS Global -works. - -:::{caution} -Before running any examples, ensure you first follow our -[installation instructions](installation.md#installation) and perform the -following two steps. - -1. Navigate to the root OSeMOSYS Global directory in the command line - - ```bash - (base) $ cd ~/osemosys_global - - (base) ~/osemosys_global$ - ``` - -2. Activate the `osemosys-global` conda environment - - ```bash - (base) ~/osemosys_global$ conda activate osemosys-global - - (osemosys-global) ~/osemosys_global$ - ``` -::: - -:::{warning} -If you installed CPLEX or Gurobi instead of CBC, you must first change this in -the configuration file at `config/config.yaml` -::: - -### Example 1 - -**Goal**: Run the workflow with default settings. This will produce a model -of India from 2015 to 2050 with 8 time slices per year, and solve it using CBC. - -1. Run the command `snakemake -j6`. The time to build and solve the model will -vary depending on your computer, but in general, this example will finish -within minutes . - - ```bash - (osemosys-global) ~/osemosys_global$ snakemake -j6 - ``` - - :::{tip} - The `-j6` command will instruct Snakemake to use six cores. - If your want to restrict this, change the number after the `-j` to - specify the number of cores. For example, the command `snakemake -j2` will - run the workflow using 2 cores. See - [snakemake's documentation](https://snakemake.readthedocs.io/en/stable/executing/cli.html#useful-command-line-arguments) - for more information. - ::: - -2. Navigate to the newly created `results/` folder. All available automatically -generated results are summarized below. - - ``` bash - osemosys_global - ├── resutls # Will appear after running the workflow - │ ├── data # Global CSV OSeMOSYS data - │ ├── figs - │ │ ├── ... # Global demand projections - │ ├── india # Name of scenario - │ │ ├── data/ # Scenario input CSV data - │ │ ├── figures - │ │ │ ├── GenerationAnnual.html - │ │ │ ├── GenerationHourly.html - │ │ │ ├── TotalCapacityAnnual.html - │ │ │ ├── TransmissionCapacity2050.jpg - │ │ │ ├── TransmissionFlow2050.jpg - │ │ ├── result_summaries - │ │ │ ├── Capacities.csv - │ │ │ ├── Generation_By_Node.csv - │ │ │ ├── Generation.csv - │ │ │ ├── Metrics.csv - │ │ │ ├── TradeFlows.csv - │ │ ├── results/ # Scenario result CSV data - │ │ ├── india.txt # Scenario OSeMOSYS data file - └── ... - ``` - - | File | Description | - |---------|-------------| - | `GenerationAnnual.html` | Plot of system level annual generation by technology | - | `GenerationHourly.html` | Plot of system level technology generation by timeslice | - | `TotalCapacityAnnual.html` | Plot of system level annual capacity by technology | - | `Capacities.csv` | Table of nodal level annual capacity by technology | - | `Generation_By_Node.csv` | Table of nodal level technology generation by timeslice | - | `Generation.csv` | Table of system level technology generation by timeslice | - | `Metrics.csv` | Table of system level cost and emission statistics | - | `TradeFlows.csv` | Table of nodal level electricity trade by timeslice | - | `TransmissionCapacityXXXX.jpg` | Transmission capacity plot for last year of model | - | `TransmissionFlowXXXX.jpg` | Transmission flow plot for last year of model | - -3. View system level capacity and generation results. - - :::{caution} - These results are used to showcase the capabilities of OSeMOSYS Global. The - actual energy supply mix results may need further analysis, such as removing - technology bias though implementing resource limits on nuclear. - ::: - - ![Example-1.1](_static/example_1.1.png "Example-1.1") - ![Example-1.2](_static/example_1.2.png "Example-1.2") - - :::{tip} - These plots are interactive! Howver over the bars to view values, or - double click on a power plant in the legend to single it out. - ::: - -4. View demand projections results for Asia in the file -`results/figs/Demand projection Asia.jpg`. Grey dots represent historical -country level values for countries in Asia and the coloured dots show projected -values. - - ![Example-1.3](_static/example_1.3.png "Example-1.3") - -### Example 2 - -**Goal**: Modify the geographic scope, temporal settings, and emission penalty -of the model. - -The goal of this scenario will be to change the geographic scope to add -Bangladesh, Bhutan, and Nepal to the model. Moreover, we will change the model -horizon to be from 2020-2040 and increase the number of time slices per year -from 8 to 18. Finally, we will ensure cross border trade is allowed, set the -emission penalty to $50/T, and create country level result plots. - -1. Navigate to and open the file `config/config.yaml` - -2. Change the scenario name to BBIN (**B**angladesh, **B**hutan, **I**ndia, -and **N**epal) - - ```yaml - scenario: 'BBIN' - ``` - -3. Change the geographic scope to include the mentioned countries. - - ```yaml - geographic_scope: - - 'IND' - - 'BGD' - - 'BTN' - - 'NPL' - ``` - -4. Change the model horizon to be from 2020 to 2040. Both numbers are inclusive. - - ```yaml - startYear: 2020 - endYear: 2040 - ``` - -5. Change the number of day parts to represent three even 8 hour segments per -day. The start number is inclusive, while the end number is exclusive. - - ```yaml - dayparts: - D1: [0, 8] - D2: [8, 16] - D3: [16, 24] - ``` - -6. Change the number of seasons to represent 6 equally spaced days. Both numbers -are inclusive. - - ```yaml - seasons: - S1: [1, 2] - S2: [3, 4] - S3: [5, 6] - S4: [7, 8] - S5: [9, 10] - S6: [11, 12] - ``` - - :::{tip} - A timeslice strucutre of 6 seasons and 3 dayparts will result in a model - with 18 timeslices per year; 6 representative days each with 3 timeslices. - - See the [OSeMOSYS documentation](https://osemosys.readthedocs.io/en/latest/index.html) - has more information on the OSeMOSYS timeslice parameters. - ::: - -6. Ensure the `crossborderTrade` parameter is set to `True` - - ```yaml - crossborderTrade: True - ``` - -7. Change the emission penalty to `50` $/T - - ```yaml - emission_penalty: - - ["CO2", "IND", 2020, 2040, 50] - - ["CO2", "BGD", 2020, 2040, 50] - - ["CO2", "BTN", 2020, 2040, 50] - - ["CO2", "NPL", 2020, 2040, 50] - ``` - -8. Run the command `snakemake -j6` - - ```bash - (osemosys-global) ~/osemosys_global$ snakemake -j6 - ``` - - :::{tip} - If you run into any issues with the workflow, run the command - `snakemake clean -c`. This will delete any auto generated files and - bring you back to a clean start. - ::: - -9. Navigate to the `results/` folder to view results from this model run. - - Notice how under `figures/`, there is now a folder for each country. By - setting the `crossborderTrade` parameter to be true, we tell the - workflow to create out both system level and country level plots. - - ``` bash - osemosys_global - ├── resutls - │ ├── data # Global CSV OSeMOSYS data - │ ├── figs - │ │ ├── ... # Global demand projections - │ ├── india - │ ├── BBIN # Name of scenario - │ │ ├── data/ # Scenario input CSV data - │ │ ├── figures - │ │ │ ├── BTN - │ │ │ │ ├── GenerationAnnual.html - │ │ │ │ ├── TotalCapacityAnnual.html - │ │ │ ├── BGD - │ │ │ │ ├── GenerationAnnual.html - │ │ │ │ ├── TotalCapacityAnnual.html - │ │ │ ├── IND - │ │ │ │ ├── GenerationAnnual.html - │ │ │ │ ├── TotalCapacityAnnual.html - │ │ │ ├── NPL - │ │ │ │ ├── GenerationAnnual.html - │ │ │ │ ├── TotalCapacityAnnual.html - │ │ │ ├── GenerationAnnual.html - │ │ │ ├── GenerationHourly.html - │ │ │ ├── TotalCapacityAnnual.html - │ │ │ ├── TransmissionCapacity2040.jpg - │ │ │ ├── TransmissionFlow2040.jpg - │ │ ├── result_summaries # Auto generated result tables - │ │ ├── results/ # Scenario result CSV data - │ │ ├── BBIN.txt # Scenario OSeMOSYS data file - └── ... - ``` - - :::{note} - If you don't change clean the model results, the previous scenario - results are saved as long as you change the scenario name. - ::: - -10. View system level 2040 hourly generation results by viewing the file -`results/BBIN/figures/GenerationHourly.html` - - :::{caution} - These results are used to showcase the capabilities of OSeMOSYS Global. The - actual energy supply mix results may need further analysis, such as removing - technology bias though implementing resource limits on nuclear. - ::: - - ![Example-2](_static/example_2.png "Example-2") - -3. View system level metrics for this model run by looking at the file -`results/BBIN/result_summaries/Metrics.csv` - - | Metric | Unit | Value | - |---------------------|---------------------------|-------| - | Emissions | Million tonnes of CO2-eq. | 1221 | - | RE Share | % | 10 | - | Total System Cost | Billion $ | 1544 | - | Cost of electricity | $/MWh | 20 | - | Fossil fuel share | % | 4 | - - -### Example 3 - -**Goal**: Rerun the BBIN example with new interconnectors. - -The goal of this scenario will be to rerun the BBIN scenario -([example 2](#example-2)), except we will tell the model to install three new -electricity interconnectors. In 2025 we will install a 3GW interconnector -between India and Nepal. Then in 2030 we will install a 1GW and 750MW -interconnector between India and Bhutan and India and Bangladesh respectively. - -1. Change the scenario name - - ```yaml - scenario: 'BBIN_Interconnector' - ``` - -2. Configure the new interconnectors - - ```yaml - user_defined_capacity: - TRNINDNONPLXX: [3, 2025] - TRNINDNEBTNXX: [1, 2030] - TRNINDEABGDXX: [0.75, 2030] - ``` - - :::{note} - The last two letters in the region (ie. `NO`, `NE`, and `EA` for India, or - `XX` for Nepal, Bhutan and Bangladesh) represent the node in each region. - See our [model structure](./model-structure.md#spatial-codes) - document for more information on this. - ::: - -3. View the trade capacity plot in 2040 by looking at the file -`results/BBIN_interconnector/figures/TransmissionCapacity2040.jpg` - - - -4. View the trade flow plot in 2040 by looking at the file -`results/BBIN_interconnector/figures/TransmissionFlow2040.jpg` - - - - -### Example 4 - -**Goal**: Run a World Example - -The goal of this scenario is to run a World scenario from 2015 to 2050 with -8 time slices, solve it using CPLEX, and graphing results at a system level only - -1. Change the scenario name - - ```yaml - scenario: 'WORLD' - ``` - -2. Delete everything under the geographic scope - - ```yaml - geographic_scope: - ``` - - :::{caution} - Do **NOT** delete the `geographic_scope:` keyword - ::: - -3. Change the model horizon to be from 2015 to 2050. Both numbers are inclusive. - - ```yaml - startYear: 2015 - endYear: 2050 - ``` - -4. Reset the temporal parameters back to defaults. - - ```yaml - dayparts: - D1: [0, 12] - D2: [12, 24] - - seasons: - S1: [12, 1, 2] - S2: [3, 4, 5] - S3: [6, 7, 8] - S4: [9, 10, 11] - ``` - -5. Remove the time shift to set to UTC time. - - ```yaml - timeshift: 0 - ``` - -6. Set the results to only graph at a system level - - ```yaml - results_by_country: False - ``` - -7. Set the solver to `CPLEX` - - ```yaml - solver: 'cplex' - ``` - -8. Run the command `snakemake -j6` - - :::{warning} - This scenario will take multiple hours to run using a commercial solver - (Gurobi or CPLEX) on a high performance computer. - ::: - - ```bash - (osemosys-global) ~/osemosys_global$ snakemake -j6 - ``` - -8. View system level results in the `results/WORLD/figures` folder - ## Feedback If you are experiencing issues running any of the examples, please submit a diff --git a/docs/index.md b/docs/index.md index 62515844..98606b31 100644 --- a/docs/index.md +++ b/docs/index.md @@ -17,6 +17,7 @@ energy system model. installation getting-started +examples contributing model-structure advanced-functionality