Skip to content

Commit

Permalink
Update the user guide section
Browse files Browse the repository at this point in the history
  • Loading branch information
@mengqi-z
mengqi-z committed May 24, 2024
1 parent a3c451c commit f79e345
Show file tree
Hide file tree
Showing 3 changed files with 165 additions and 21 deletions.
Binary file added docs/source/_static/example_capacity_yield.png
View file
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
11 changes: 8 additions & 3 deletions docs/source/getting_started.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -66,11 +66,14 @@ Example data and configuration file can be downloaded from Zenodo through this `
# The example data will be downloaded to the cloned package folder by default.
glory.get_example_data()
# Or
Or, if the user didn't clone the ``GLORY`` package, then specify a desired download location.

# If the user didn't clone the package, then specify a desired download location.
glory.get_example_data(example_data_directory='path/to/desired/location')
.. code-block:: python
import glory
# modify example_data_directory to your own desired location
glory.get_example_data(example_data_directory='path/to/desired/location')
Run
-----------------------------------
Expand All @@ -87,3 +90,5 @@ With the example data downloaded, a simple configuration can be run:
glory.run_model(config_file=config_file)
Check your ``example\outputs`` folder for the results!
175 changes: 157 additions & 18 deletions docs/source/user_guide.rst
View file
Original file line number Diff line number Diff line change
@@ -1,10 +1,11 @@
===============
User Guide
===============

This page gives details on model settings.

Workflow Overview
-----------------
=================

The core workflow of ``GLORY`` consists of 2 stages: linear programming and supply curve construction.

Expand All @@ -14,12 +15,14 @@ The core workflow of ``GLORY`` consists of 2 stages: linear programming and supp
:align: center
:figclass: align-center

Figure 1. GLORY framework for required input data and model structure.

|
Global River Basins
-------------------
===================

The default ``GLORY`` model is operating for each of the 235 global river basins shown in the figure. Details on basin names and the corresponding basin ID can be found using ``GLORY`` functions.
The default ``GLORY`` model is operating for each of the 235 global river basins shown in Figure 2 below. Details on basin names and the corresponding basin ID can be found using ``GLORY`` functions.

.. code-block:: python
Expand All @@ -32,7 +35,7 @@ The default ``GLORY`` model is operating for each of the 235 global river basins
basin_id=83,
period=2025)
# check the global basins
# check the basin ID and basin names for global 235 basins
data.basin_name_std
Expand All @@ -42,18 +45,68 @@ The default ``GLORY`` model is operating for each of the 235 global river basins
:align: center
:figclass: align-center

Figure 2. Global 235 HUC2 basins identified by GLORY.



Reservoir Storage Capacity and Water Yield Relationships
========================================================

Reservoir annual water yield is defined as the annual volumetric quantity of water that can be released from a reservoir for downstream uses within a year. Water yield can be estimated based on a given volume of reservoir storage capacity. By estimating yields at different storage capacity level, we can obtain the capacity-yield curve. With changing patterns of intra-annual climate and demand, a reservoir with the same storage capacity can yield different amount of water annually. `GLORY` is developed to capture such variations. Figure 3 shows an example of capacity-yield curve.

.. figure:: _static/example_capacity_yield.png
:width: 90%
:alt: capacity_yield
:align: center
:figclass: align-center

Figure 3. Example of a capacity-yield curve.


Configuration File
==================

Input Data
------------------------
The configuration file uses YAML structure to set up options for running ``GLORY``. The options in this file correspond to the arguments passed to the ``GLORY`` class. Options not present in the configuration file will use the default. An overview is provided in the following table, with more details and examples below.

More details of the structure of the files or options can be found in each subsection.

======================== ======================================================================================================================================================
Option Description
======================== ======================================================================================================================================================
root Root directory for inputs and outputs
:ref:`input_files` Relative file path for each input file, including :ref:`climate`, :ref:`sectoral_demand`, :ref:`monthly_profile`, :ref:`slope`, and :ref:`reservoir`
:ref:`reference_files` Relative file path for each reference file
:ref:`scales` Choice of basin ID, GCAM period, and base year period
:ref:`parameters` Initial number of breakout segments on a capacity-yield curve. Default is 100
:ref:`lp` Choice of linear programming model solver. Default is glpk
:ref:`outputs` Choice of types of outputs to generate
======================== ======================================================================================================================================================



input_files
-----------

The input data are pre-processed data for GLORY based on various dataset including hydrology, water demand, GranD, hydroLAKES, land use land cover, population, protected areas, and slope. The followings describes the structure of the input data.

Below is an example configuration for the input files.

.. code-block:: yaml
input_files:
climate: inputs/climate_canesm5_r1i1p1f1_ssp126_2020_2050.csv
sectoral_demand: inputs/demand_hist.csv
monthly_profile: inputs/fraction_profile_canesm5_r1i1p1f1_ssp126_2020_2050.csv
slope: inputs/slope.csv
reservoir: inputs/reservoir.csv
The input data are pre-processed data for GLORY based on various dataset including hydrology , water demand, GranD, hydroLAKES, land use land cover, population, protected areas, and slope. The followings describes the structure of the input data.
.. note::
To update the data, please follow the same data format and structure for each input file.


Climate Data
^^^^^^^^^^^^
climate
^^^^^^^

=================== ======================================================================================= ==========
Variable Name Description Unit
Expand All @@ -66,20 +119,20 @@ Climate Data
=================== ======================================================================================= ==========


Water Demand Data
^^^^^^^^^^^^^^^^^
sectoral_demand
^^^^^^^^^^^^^^^

=============== =========================================================================================== ==========
Variable Name Description Unit
=============== =========================================================================================== ==========
basin_id Basin ID \-
basin_name Basin Name \-
basin_name Basin name \-
sector Demand sectors, including domestic, electric, industry, irrigation, livestock, and mining \-
demand_km3 The historical average annual water demand from the sector km\ :sup:`3`/year
=============== =========================================================================================== ==========

Profile Data
^^^^^^^^^^^^
monthly_profile
^^^^^^^^^^^^^^^

=============== ============================================================================================================== ======
Variable Name Description Unit
Expand All @@ -98,8 +151,8 @@ Profile Data
mining Monthly profile of average mining water demand over the period within the basin \-
=============== ============================================================================================================== ======

Basin Slope
^^^^^^^^^^^
slope
^^^^^

=============== ===================== ======
Variable Name Description Unit
Expand All @@ -109,8 +162,8 @@ Basin Slope
slope Average basin slope \-
=============== ===================== ======

Reservoir Data
^^^^^^^^^^^^^^
reservoir
^^^^^^^^^

=================== ========================================================================= ======
Variable Name Description Unit
Expand All @@ -125,3 +178,89 @@ Reservoir Data
c Parameter c in the area-volume relationship V=cA^b for basin reservoirs \-
=================== ========================================================================= ======


reference_files
---------------

Reference files are for mapping basin to different spatial scales. The reference files includes basin to country mapping and basin to region mapping. Below is an example configuration for the reference files.

.. code-block:: yaml
reference_files:
basin_to_country_mapping: inputs/basin_to_country_mapping.csv
basin_to_region_mapping: inputs/basin_to_region_mapping.csv
basin_to_country_mapping
^^^^^^^^^^^^^^^^^^^^^^^^
This is a default mapping file from ``gcamdata`` system.

================= ===================================================================================================================
Variable Name Description
================= ===================================================================================================================
GCAM_basin_ID Basin ID from 1 to 235
Basin_long_name Basin name with underscores. For example, Arctic_Ocean_Islands
GLU_name Basin name in GCAM's Geographic Land Unit (GLU) format. For example, Arctic_Ocean_Islands's GLU name is ArcticIsl
================= ===================================================================================================================


basin_to_region_mapping
^^^^^^^^^^^^^^^^^^^^^^^

================= ======================================================
Variable Name Description
================= ======================================================
region Region name
gcam_basin_name GCAM basin name in Geographic Land Unit (GLU) format
================= ======================================================


scales
------

Under the "scales" section, you can select the basins and time steps to include in the model. Below is an example configuration for the scales.

.. code-block:: yaml
scales:
basin_id: [167, 168] # use 'all' to select all basins. Use comma separated list to select multiple basins
gcam_period: [2025] # 5-year interval periods that >= base period. Use comma separated list to select multiple time steps
base_period: 2020 # first future period. In current GCAM, 2020 is the default fist future period
.. note::
Running all 235 basins will take a while. We recommend to start with one or two basins for testing.

parameters
----------

The ``init_segments`` parameter determines the initial number of segments on a capacity-yield curve, impacting how many points the LP model needs to solve on the capacity-year curve. Increasing the number of segments can enhance the curve's resolution and accuracy, while a lower number of segments may reduce precision. The default value is 100. Below is an example configuration for the parameters.

.. code-block:: yaml
parameters:
init_segments: 100
lp
--
The linear programming model solver used in the ``GLORY`` model. The default and recommended solver is ``glpk``. Other solvers might be available.

.. code-block:: yaml
lp:
solver: 'glpk'
outputs
-------

Configure the output directory and specify the data to be generated. Set to True to enable the output for each data item. Below is an example configuration for the outputs setup.

.. code-block:: yaml
outputs:
output_folder: outputs # relative path to the outputs folder
capacity_yield: True # capacity-yield curve at the basin level
supply_curve: True # supply curve at the basin level
lp_solution: True # the water balance solution at each storage capacity point
diagnostics: True # diagnostic figures

0 comments on commit f79e345

Please sign in to comment.