diff --git a/docs/source/_static/example_capacity_yield.png b/docs/source/_static/example_capacity_yield.png new file mode 100644 index 0000000..50bfa4b Binary files /dev/null and b/docs/source/_static/example_capacity_yield.png differ diff --git a/docs/source/getting_started.rst b/docs/source/getting_started.rst index 6b709cd..fa13d8c 100644 --- a/docs/source/getting_started.rst +++ b/docs/source/getting_started.rst @@ -66,14 +66,17 @@ 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 ------------------------------------ +--- With the example data downloaded, a simple configuration can be run: @@ -87,3 +90,53 @@ 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! + +Use `GLORY` Modules +------------------- + +Instead of running the entire model, one can choose to run certain modules. + +To generate a capacity-yield curve and a supply curve with discrete points for a single basin, users can easily instantiate the `glory.SupplyCurve()` object by providing the configuration object. The `glory.SupplyCurve()` will then undertake the process of identifying reservoir storage capacity expansion pathways and calculating the optimized water yield at each storage capacity point. The example below uses California River basin (basin ID is 217) for time step 2020. + +.. code-block:: python + + import glory + + # indicate the path to the config file + config = glory.ConfigReader(config_file=config_file) + + # demand_gcam and capacity_gcam is set to None because the model is not linked with GCAM in this example + sc = glory.SupplyCurve(config=config, + basin_id=217, + period=2020, + demand_gcam=None, + capacity_gcam=None) + + # Check the capacity-yield curve + sc.capacity_yield + + # check the supply curve + sc.supply_curve + +One can effortlessly apply the `glory.lp_model()` function to execute a linear programming model that determines the optimized water yield for a given reservoir storage capacity. Below is an example with arbitrary numbers. Please not that volumetric units should be consistent across variables. + +.. code-block:: python + + import numpy as np + + lp = glory.lp_model(K=1, # set storage capacity as 1 km3 + Smin=0, # minimum storage + Ig=5, # annual inflow in volume + Eg=3, # annual reservoir surface evaporation in volume + f={i+1: num for i, num in enumerate(np.random.dirichlet(np.ones(12), size=1)[0])}, # dictionary: monthly profile for demand + p={i+1: num for i, num in enumerate(np.random.dirichlet(np.ones(12), size=1)[0])}, # dictionary: monthly profile for inflow + z={i+1: num for i, num in enumerate(np.random.dirichlet(np.ones(12), size=1)[0])}, # dictionary: monthly profile for reservoir surface evaporation + m=0.1, # percentage of water reuse + solver='glpk') + + # view the solution + lp.display() + +This will return a `pyomo `_ object. To display the linear programming solution for each variable, use `lp.display()`. diff --git a/docs/source/user_guide.rst b/docs/source/user_guide.rst index 587ad07..bcab2a7 100644 --- a/docs/source/user_guide.rst +++ b/docs/source/user_guide.rst @@ -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. @@ -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 @@ -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 @@ -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 @@ -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 @@ -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 @@ -109,8 +162,8 @@ Basin Slope slope Average basin slope \- =============== ===================== ====== -Reservoir Data -^^^^^^^^^^^^^^ +reservoir +^^^^^^^^^ =================== ========================================================================= ====== Variable Name Description Unit @@ -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 \ No newline at end of file diff --git a/glory/data/read_data.py b/glory/data/read_data.py index dcc8cab..959f6cb 100644 --- a/glory/data/read_data.py +++ b/glory/data/read_data.py @@ -144,10 +144,11 @@ def load_basin_mapping(f_basin_country, f_basin_region, header_num=7): """ Mapping different formats of basin names. - :param fn: string for full file path - :param header_num: integer for numbers of rows to skip until the header + :param f_basin_country: string for full file path to basin-country mapping file + :param f_basin_region: string for full file path to basin-region mapping file + :param header_num: integer for numbers of rows to skip until the header - :return: dataframe + :return: dataframe """ # load basin mapping data @@ -174,8 +175,6 @@ def get_demand_profile(self): """ Calculate total demand profile with historical sectoral profile and sectoral demand. - :param data_type: string for input demand data. 'hist' or 'gcam' - :return: dictionary """ diff --git a/glory/method/lp.py b/glory/method/lp.py index 95bc454..40cbcb4 100644 --- a/glory/method/lp.py +++ b/glory/method/lp.py @@ -12,7 +12,7 @@ """ import pandas as pd -from pyomo.environ import * +import pyomo.environ as pyo def lp_model(K, Smin, Ig, Eg, f, p, z, m, solver='glpk'): @@ -26,49 +26,49 @@ def lp_model(K, Smin, Ig, Eg, f, p, z, m, solver='glpk'): :param f: dictionary for demand fraction profile :param p: dictionary for inflow fraction profile :param z: dictionary for evaporation fraction profile - :param m: float for fraction of flow released from distributed reservoirs + :param m: float for fraction of flow released from distributed reservoirs that’s reusable in the river system :return: array for capacity - yield curve """ # Linear Programming Model for Water Storage - model = ConcreteModel() + model = pyo.ConcreteModel() # Set model time periods TimePeriods = [1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12] LastTimePeriod = 12 # Define variables - model.Y = Var(within=NonNegativeReals, initialize=0) - model.S = Var(TimePeriods, within=NonNegativeReals) - model.R = Var(TimePeriods, within=NonNegativeReals) - model.X = Var(TimePeriods, within=NonNegativeReals) - model.RF = Var(TimePeriods, within=NonNegativeReals) + model.Y = pyo.Var(within=pyo.NonNegativeReals, initialize=0) + model.S = pyo.Var(TimePeriods, within=pyo.NonNegativeReals) + model.R = pyo.Var(TimePeriods, within=pyo.NonNegativeReals) + model.X = pyo.Var(TimePeriods, within=pyo.NonNegativeReals) + model.RF = pyo.Var(TimePeriods, within=pyo.NonNegativeReals) # Define parameters - model.K = Param(initialize=K, within=NonNegativeReals) + model.K = pyo.Param(initialize=K, within=pyo.NonNegativeReals) - model.f = Param(TimePeriods, initialize=f, within=PercentFraction) - model.p = Param(TimePeriods, initialize=p, within=PercentFraction) - model.z = Param(TimePeriods, initialize=z, within=PercentFraction) + model.f = pyo.Param(TimePeriods, initialize=f, within=pyo.PercentFraction) + model.p = pyo.Param(TimePeriods, initialize=p, within=pyo.PercentFraction) + model.z = pyo.Param(TimePeriods, initialize=z, within=pyo.PercentFraction) # Define inflow def Inflow_init(model, t): return max(model.p[t] * (Ig), 0) - model.I = Param(TimePeriods, initialize=Inflow_init) + model.I = pyo.Param(TimePeriods, initialize=Inflow_init, within=pyo.NonNegativeReals) # Define evaporation def Evap_init(model, t): return max(model.z[t] * (Eg), 0) - model.E = Param(TimePeriods, rule=Evap_init) + model.E = pyo.Param(TimePeriods, rule=Evap_init, within=pyo.NonNegativeReals) # Define environmental flow def EnvFlow_init(model, t): return 0.1 * model.I[t] - model.EF = Param(TimePeriods, rule=EnvFlow_init) + model.EF = pyo.Param(TimePeriods, rule=EnvFlow_init, within=pyo.NonNegativeReals) # Constraints ---------------------------------------------- # Define mass balance constraint @@ -80,35 +80,36 @@ def Mass_rule(model, t): return model.S[t + 1] == model.S[t] + model.I[t] - model.E[t] - model.EF[t] - model.R[t] + model.RF[t] - \ model.X[t] - model.Mass = Constraint(TimePeriods, rule=Mass_rule) + model.Mass = pyo.Constraint(TimePeriods, rule=Mass_rule) # Define storage constraint def Storage_rule(model, t): return (Smin, model.S[t], model.K) - model.Storage = Constraint(TimePeriods, rule=Storage_rule) + model.Storage = pyo.Constraint(TimePeriods, rule=Storage_rule) # Define release constraint def Release_rule(model, t): return model.R[t] >= model.f[t] * model.Y - model.Release = Constraint(TimePeriods, rule=Release_rule) + model.Release = pyo.Constraint(TimePeriods, rule=Release_rule) # Define return flow constraint def ReturnFlow_rule(model, t): return model.RF[t] == m * (model.R[t] + model.EF[t]) - model.ReturnFlow = Constraint(TimePeriods, rule=ReturnFlow_rule) + model.ReturnFlow = pyo.Constraint(TimePeriods, rule=ReturnFlow_rule) # Objective ---------------------------------------------- - model.obj = Objective(expr=model.Y, sense=maximize) + model.obj = pyo.Objective(expr=model.Y, sense=pyo.maximize) # Solve the problem - opt = SolverFactory(solver) + opt = pyo.SolverFactory(solver) opt.solve(model, tee=False) return model + def lp_solution(model, K, basin_id, period): """ @@ -120,13 +121,13 @@ def lp_solution(model, K, basin_id, period): """ # retrieve values of optimal model variables - I = [value(model.I[key]) for key in model.I] - E = [value(model.E[key]) for key in model.E] - R = [value(model.R[key]) for key in model.R] - EF = [value(model.EF[key]) for key in model.EF] - RF = [value(model.RF[key]) for key in model.RF] - X = [value(model.X[key]) for key in model.X] - S = [value(model.S[key]) for key in model.S] + I = [pyo.value(model.I[key]) for key in model.I] + E = [pyo.value(model.E[key]) for key in model.E] + R = [pyo.value(model.R[key]) for key in model.R] + EF = [pyo.value(model.EF[key]) for key in model.EF] + RF = [pyo.value(model.RF[key]) for key in model.RF] + X = [pyo.value(model.X[key]) for key in model.X] + S = [pyo.value(model.S[key]) for key in model.S] # create data frame df = pd.DataFrame( diff --git a/paper/paper.bib b/paper/paper.bib index 6c22cde..1b24e1e 100644 --- a/paper/paper.bib +++ b/paper/paper.bib @@ -21,7 +21,6 @@ @article{Reed_2022 url = {https://agupubs.onlinelibrary.wiley.com/doi/abs/10.1029/2021EF002621}, eprint = {https://agupubs.onlinelibrary.wiley.com/doi/pdf/10.1029/2021EF002621}, note = {e2021EF002621 2021EF002621}, -abstract = {Abstract The field of MultiSector Dynamics (MSD) explores the dynamics and co-evolutionary pathways of human and Earth systems with a focus on critical goods, services, and amenities delivered to people through interdependent sectors. This commentary lays out core definitions and concepts, identifies MSD science questions in the context of the current state of knowledge, and describes ongoing activities to expand capacities for open science, leverage revolutions in data and computing, and grow and diversify the MSD workforce. Central to our vision is the ambition of advancing the next generation of complex adaptive human-Earth systems science to better address interconnected risks, increase resilience, and improve sustainability. This will require convergent research and the integration of ideas and methods from multiple disciplines. Understanding the tradeoffs, synergies, and complexities that exist in coupled human-Earth systems is particularly important in the context of energy transitions and increased future shocks.}, year = {2022} } @@ -35,8 +34,7 @@ @article{Bell_2014 doi = {https://doi.org/10.1016/j.eneco.2013.12.016}, url = {https://www.sciencedirect.com/science/article/pii/S0140988313002995}, author = {Andrew Bell and Tingju Zhu and Hua Xie and Claudia Ringler}, -keywords = {Integrated assessment models, Water resources modeling}, -abstract = {Water plays a major role in the climate system and in mediating impacts of climate variability and change on all sectors of the economy. The incorporation of water resources modeling into integrated assessment models (IAMs) to study climate–hydrology processes, related water impacts and adaptation options is thus an area of interest, yet it poses a number of methodological challenges. In particular, models of economic activity, climate, water availability and use, and adaptation are developed at differing temporal and spatial scales and with different goals. This makes their integration highly complex and computationally demanding. In this review we highlight a set of modeling challenges in water resource systems, describe the state of the art of approaches to integrating water resources modeling with IAMs and economic modeling, and identify constraints and opportunities moving forward in the development of water resources modeling within the IAM frameworks.} +keywords = {Integrated assessment models, Water resources modeling} } @article{Vanderkelen_2021, @@ -50,7 +48,6 @@ @article{Vanderkelen_2021 url = {https://agupubs.onlinelibrary.wiley.com/doi/abs/10.1029/2020JD034485}, eprint = {https://agupubs.onlinelibrary.wiley.com/doi/pdf/10.1029/2020JD034485}, note = {e2020JD034485 2020JD034485}, -abstract = {Abstract Reservoir expansion over the last century has largely affected downstream flow characteristics. Yet very little is known about the impacts of reservoir expansion on the climate. Here, we implement reservoir construction in the Community Land Model by enabling dynamical lake area changes, while conserving mass and energy. Transient global lake and reservoir extent are prescribed from the HydroLAKES and Global Reservoir and Dam databases. Land-only simulations covering the 20th century with reservoir expansion enabled, highlight increases in terrestrial water storage and decreases in albedo matching the increase in open water area. The comparison of coupled simulations including and excluding reservoirs shows only limited influence of reservoirs on global temperatures and the surface energy balance, but demonstrates substantial responses locally, in particular where reservoirs make up a large fraction of the grid cell. In those locations, reservoirs dampen the diurnal temperature range by up to −1.5 K (for reservoirs covering >15\% of the grid cell), reduce temperature extremes, and moderate the seasonal temperature cycle. This study provides a first step towards a coupled representation of reservoirs in Earth System Models.}, year = {2021} } @@ -64,8 +61,7 @@ @article{Rising_2020 doi = {https://doi.org/10.1016/j.wasec.2019.100056}, url = {https://www.sciencedirect.com/science/article/pii/S2468312419300215}, author = {James Rising}, -keywords = {Water-energy-food nexus, Optimization, Integrated assessment models}, -abstract = {Studying trade-offs in the long-term development of water-energy-food systems requires a new family of hydroeconomic optimization models. This article reviews the central considerations behind these models, highlighting the importance of water infrastructure, the foundations of a theory of decision-making, and the handling of uncertainty. Integrated assessment models (IAMs), used in climate change policy research, provide insights that can support this development. In particular, IAM approaches to intertemporal decision-making and economic valuation can improve existing models. At the same time, IAMs have weaknesses identified elsewhere and can benefit from the development of hydroeconomic models, which have complementary strengths.} +keywords = {Water-energy-food nexus, Optimization, Integrated assessment models} } @article{Sen_2021, @@ -77,4 +73,134 @@ @article{Sen_2021 year={2021}, publisher={Springer}, doi={https://doi.org/10.1007/s11269-021-02925-0} +} + +@article{Calvin_2019, +AUTHOR = {Calvin, K. and Patel, P. and Clarke, L. and Asrar, G. and Bond-Lamberty, B. and Cui, R. Y. and Di Vittorio, A. and Dorheim, K. and Edmonds, J. and Hartin, C. and Hejazi, M. and Horowitz, R. and Iyer, G. and Kyle, P. and Kim, S. and Link, R. and McJeon, H. and Smith, S. J. and Snyder, A. and Waldhoff, S. and Wise, M.}, +TITLE = {GCAM v5.1: representing the linkages between energy, water, land, climate, +and economic systems}, +JOURNAL = {Geoscientific Model Development}, +VOLUME = {12}, +YEAR = {2019}, +NUMBER = {2}, +PAGES = {677--698}, +URL = {https://gmd.copernicus.org/articles/12/677/2019/}, +DOI = {10.5194/gmd-12-677-2019} +} + +@article{Abeshu_2023, +AUTHOR = {Abeshu, G. W. and Tian, F. and Wild, T. and Zhao, M. and Turner, S. and Chowdhury, A. F. M. K. and Vernon, C. R. and Hu, H. and Zhuang, Y. and Hejazi, M. and Li, H.-Y.}, +TITLE = {Enhancing the representation of water management in global hydrological models}, +JOURNAL = {Geoscientific Model Development}, +VOLUME = {16}, +YEAR = {2023}, +NUMBER = {18}, +PAGES = {5449--5472}, +URL = {https://gmd.copernicus.org/articles/16/5449/2023/}, +DOI = {10.5194/gmd-16-5449-2023} +} + +@article{Wild_2021, +title = {An open source reservoir and sediment simulation framework for identifying and evaluating siting, design, and operation alternatives}, +journal = {Environmental Modelling & Software}, +volume = {136}, +pages = {104947}, +year = {2021}, +issn = {1364-8152}, +doi = {https://doi.org/10.1016/j.envsoft.2020.104947}, +url = {https://www.sciencedirect.com/science/article/pii/S1364815220310045}, +author = {Thomas B. Wild and Abigail N. Birnbaum and Patrick M. Reed and Daniel P. Loucks} +} + +@article{Schmitt_2022, +author = {Rafael J. P. Schmitt and Lorenzo Rosa and Gretchen C. Daily }, +title = {Global expansion of sustainable irrigation limited by water storage}, +journal = {Proceedings of the National Academy of Sciences}, +volume = {119}, +number = {47}, +pages = {e2214291119}, +year = {2022}, +doi = {10.1073/pnas.2214291119}, +URL = {https://www.pnas.org/doi/abs/10.1073/pnas.2214291119}, +eprint = {https://www.pnas.org/doi/pdf/10.1073/pnas.2214291119} +} + +@article{Kim_2016, +title={Balancing global water availability and use at basin scale in an integrated assessment model}, +author={Kim, Son H and Hejazi, Mohamad and Liu, Lu and Calvin, Katherine and Clarke, Leon and Edmonds, Jae and Kyle, Page and Patel, Pralit and Wise, Marshall and Davies, Evan}, +journal={Climatic change}, +volume={136}, +number={2}, +pages={217--231}, +year={2016}, +doi={10.1007/s10584-016-1604-6}, +url={https://doi.org/10.1007/s10584-016-1604-6}, +publisher={Springer} +} + +@article{Liu_2018, +doi = {10.1088/1748-9326/aab2b5}, +url = {https://dx.doi.org/10.1088/1748-9326/aab2b5}, +year = {2018}, +month = {apr}, +publisher = {IOP Publishing}, +volume = {13}, +number = {4}, +pages = {044026}, +author = {Lu Liu and Simon Parkinson and Matthew Gidden and Edward Byers and Yusuke Satoh and Keywan Riahi and Barton Forman}, +title = {Quantifying the potential for reservoirs to secure future surface water yields in the world’s largest river basins}, +journal = {Environmental Research Letters} +} + +@article{Strzepek_2013, + title={Modeling water resource systems within the framework of the MIT Integrated Global System Model: IGSM-WRS}, + author={Strzepek, Kenneth and Schlosser, Adam and Gueneau, Arthur and Gao, Xiang and Blanc, {\'E}lodie and Fant, Charles and Rasheed, Bilhuda and Jacoby, Henry D}, + journal={Journal of Advances in Modeling Earth Systems}, + volume={5}, + number={3}, + pages={638--653}, + year={2013}, + doi={10.1002/jame.20044}, + url={https://doi.org/10.1002/jame.20044}, + publisher={Wiley Online Library} +} + +@article{Graham_2018, + title={Water sector assumptions for the shared socioeconomic pathways in an integrated modeling framework}, + author={Graham, Neal T and Davies, Evan GR and Hejazi, Mohamad I and Calvin, Katherine and Kim, Son H and Helinski, Lauren and Miralles-Wilhelm, Fernando R and Clarke, Leon and Kyle, Page and Patel, Pralit and others}, + journal={Water Resources Research}, + volume={54}, + number={9}, + pages={6423--6440}, + year={2018}, + doi={10.1029/2018WR023452}, + url={https://doi.org/10.1029/2018WR023452}, + publisher={Wiley Online Library} +} + +@article{Harou_2009, +title = {Hydro-economic models: Concepts, design, applications, and future prospects}, +journal = {Journal of Hydrology}, +volume = {375}, +number = {3}, +pages = {627-643}, +year = {2009}, +issn = {0022-1694}, +doi = {https://doi.org/10.1016/j.jhydrol.2009.06.037}, +url = {https://www.sciencedirect.com/science/article/pii/S0022169409003588}, +author = {Julien J. Harou and Manuel Pulido-Velazquez and David E. Rosenberg and Josué Medellín-Azuara and Jay R. Lund and Richard E. Howitt}, +keywords = {Hydro-economic models, Integrated water resource management (IWRM), Systems analysis, Water value, Water demand} +} + +@article{Kahil_2018, +title={A continental-scale hydroeconomic model for integrating water-energy-land nexus solutions}, +author={Kahil, Taher and Parkinson, Simon and Satoh, Yusuke and Greve, Peter and Burek, Peter and Veldkamp, Ted IE and Burtscher, Robert and Byers, Edward and Djilali, Ned and Fischer, Guenther and others}, +journal={Water resources research}, +volume={54}, +number={10}, +pages={7511--7533}, +year={2018}, +doi = {10.1029/2017WR022478}, +url = {https://doi.org/10.1029/2017WR022478}, +publisher={Wiley Online Library} } \ No newline at end of file diff --git a/paper/paper.md b/paper/paper.md index 6eb46d3..5cf46f6 100644 --- a/paper/paper.md +++ b/paper/paper.md @@ -32,44 +32,35 @@ balance that accounts for the sub-annual timing of streamflow (i.e., reservoir i and spills. Other constraints include the sub-annual timing of water demands, and the suitability of riverine corridors for reservoir construction. The result of the optimization is a single capacity-yield curve for each of 235 global river basins that describes the annual volumetric water yield that can be obtained through incremental increases in a basin's total reservoir storage capacity. The model's focus on maximizing yield makes it more amenable to the study of irrigation and water supply reservoir potential. -Next, the model converts each capacity-yield curve into a supply cost curve by converting each level of reservoir storage volume on the curve into a levelized cost, taking into account physiographically specific reservoir construction costs and other specifications (e.g., average reservoir size). -On their own, capacity-yield and cost curves are useful for various analyses of water resources systems (https://iopscience.iop.org/article/10.1088/1748-9326/aab2b5/meta), -including continental to global scale economic analyses of reservoir storage expansion. Additionally, GLORY's cost curves are are designed to be used in hydro-economic or -coupled human-Earth systems assessments that require as input an economic valuation of the cost of water supply to explore multi-sector dynamic ([@Reed_2022]) interactions. -For example, `GLORY` can be used to produce surface water cost curve inputs (https://gmd.copernicus.org/preprints/gmd-2023-204/) for the Global Change Analysis Model (GCAM), -which can in turn be used to explore the future co-evolution of energy, water, and land systems under global change (CALVIN ET AL). - - - +Next, the model converts each capacity-yield curve into a supply cost curve by converting each level of reservoir storage capacity volume on the curve into a levelized cost of water supply, taking into account physiographically specific reservoir construction costs and other specifications (e.g., reservoir size). +On their own, capacity-yield and cost curves are useful for various analyses of water resources systems [@Liu_2018], +including continental to global scale economic analyses of reservoir storage expansion. Additionally, `GLORY`'s cost curves are designed to be used in hydro-economic or +coupled human-Earth systems assessments that require as input an economic valuation of the cost of water supply to explore multi-sector dynamic [@Reed_2022] interactions. +For example, `GLORY` can be used to produce surface water cost curve inputs [@Zhao_2024] for the Global Change Analysis Model (`GCAM`), +which can in turn be used to explore the future co-evolution of energy, water, and land systems under global change [@Calvin_2019]. ![The GLORY model workflow showing the input data requirements and the steps of modeling capacity-yield relationships and supply curves. \label{fig:1}](workflow.png) # Statement of Need Extensive research literature is devoted to advancing methods for modeling the physical (as opposed to economic) characteristics of reservoirs, from models that operate at the scale of individual reservoirs -or systems of reservoirs (https://doi.org/10.1016/j.envsoft.2020.104947) to global hydrology models (Abeshu et al., GMD, 2023). These efforts have focused primarily -on modeling the operations of existing reservoir fleets to meet various objectives. There is growing interest in understanding the future role reservoirs could play in meeting water demands (https://www.pnas.org/doi/abs/10.1073/pnas.2214291119), -but there is a gap in economics-based modeling methods and software to support analyses of future expansion of dam and reservoir infrastructure ([@Vanderkelen_2021, https://gmd.copernicus.org/preprints/gmd-2023-204/)]. -Hydro-economic and global multi-sector dynamic models (e.g., GCAM) are designed to explore (at global scale) future multi-sector water demands under global change (e.g., socioeconomic and climate change), and the competition between surface water reservoirs and other -sources of water supply (e.g., groundwater) to meet those demands. However, these global integrated multi-sector models often require regionally differentiated cost curves that describe the cost to supply increasing quantities of surface water [CITE A GCAM WATER PAPER, BUT ALSO CAN WE CITE ANY NON-GCAM PAPERS HERE?]. -`GLORY` fills a gap by providing these cost curves. `GLORY` was recently coupled with GCAM to create a more dynamic representation of water storage than the model's existing representation of surface water supply cost (https://link.springer.com/article/10.1007/s10584-016-1604-6). -Finally, the model produces capacity-yield curves that are also useful continental-to-global scale analyses of reservoir storage and yield potential (https://iopscience.iop.org/article/10.1088/1748-9326/aab2b5/meta). +or systems of reservoirs [@Wild_2021] to global hydrology models [@Abeshu_2023]. These efforts have focused primarily +on modeling the operations of existing reservoir fleets to meet various objectives. There is growing interest in understanding the future role reservoirs could play in meeting water demands [@Sen_2021; @Schmitt_2022], +but there is a gap in economics-based modeling methods and software to support analyses of future expansion of dam and reservoir infrastructure [@Vanderkelen_2021; @Zhao_2024]. +Hydro-economic and global multi-sector dynamic models (e.g., `GCAM`) are designed to explore (at global scale) future multi-sector water demands under global change (e.g., socioeconomic and climate change), and the competition between surface water reservoirs and other +sources of water supply (e.g., groundwater) to meet those demands [@Rising_2020]. However, these global integrated multi-sector models often require regionally differentiated cost curves that describe the cost to supply increasing quantities of surface water [@Harou_2009; @Strzepek_2013; @Kim_2016; @Graham_2018]. +`GLORY` fills a gap by providing these cost curves. `GLORY` was recently coupled with `GCAM` to create a more dynamic representation of water storage than the model's existing representation of surface water supply cost [@Kim_2016]. +Finally, the model produces capacity-yield curves that are also useful continental-to-global scale analyses of reservoir storage and yield potential [@Liu_2018]. - - - - +# State of the Field +The field of hydro-economic modeling has seen limited application at the global scale. One notable exception is the Global Hydro-economic Model (`ECHO`) [@Kahil_2018], which aims to inform cost-effective and sustainable water policies by minimizing total water management costs across the water, land, and energy sectors. However, `ECHO` does not offer comparable functionality in terms of the hydro-economic aspects of reservoirs across their full exploitable potential on a global scale. In contrast, the `GLORY` model provides unique functionalities that streamline workflows by integrating information on climate, hydrology, water demand, reservoir exploitable potential, and physiography to estimate the water availability and prices of water supply from reservoirs. These capabilities enable `GLORY` to complement models like `ECHO` or other multisector dynamics models like `GCAM`, enhancing their hydro-economic analyses within an integrated context. # Design and Functionality -The `GLORY` model is designed to integrate complex processes of estimating reservoir water yield and cost into a pipeline. `GLORY` utilizes human-readable YAML file for easy model configuration. It can be applied to analyze either global basins or a subset of basins and periods of interest. Instead of relying on the default basin delineation, users can also switch to customized geographical boundaries, given the relevant data is available. The modular design of `GLORY` offers users the flexibility to use individual module or the entire model, depending on their interest in the water management or the economic of water supply. - -Here we briefly demonstrate how to use glory to achieve different outcomes. One can effortlessly apply the `glory::lp_model()` function to execute a linear programing model that determines the optimized water yield for a given reservoir storage capacity. To generate a capacity-yield curve and a supply curve with discrete points for a single basin (e.g., Figure 2), users can easily instantiate the `glory::SupplyCurve()` object by providing the configuration object. The `glory::SupplyCurve()` will then undertake the process of identifying reservoir storage capacity expansion pathways and calculating the optimized water yield at each storage capacity point. To apply `GLORY` to multiple basins, simply indicate the basin IDs in the configuration file and run `GLORY` model using `glory::run_model()`. Figure 2 shows an example output of capacity-yield curve and supply curve for Pacific Northwest basin. The detailed documentation on how to use `glory` can be accessed at [glory documentation](https://jgcri.github.io/glory/index.html). +The `GLORY` model is designed to integrate complex processes of estimating reservoir water yield and cost into a pipeline. `GLORY` utilizes human-readable YAML file for easy model configuration. It can be applied to analyze either global basins or a subset of basins and periods of interest. Instead of relying on the default basin delineation, users can also switch to customized geographical boundaries, given the relevant data is available. The modular design of `GLORY` offers users the flexibility to use individual module or the entire model, depending on their interest in the water management or the economics of water supply. - - - +Here we briefly demonstrate how to use `GLORY` to achieve different outcomes. One can effortlessly apply the `glory.lp_model()` function to execute a linear programing model that determines the optimized water yield for a given reservoir storage capacity. To generate a capacity-yield curve and a supply curve with discrete points for a single basin (e.g., Figure 2), users can easily instantiate the `glory.SupplyCurve()` object by providing the configuration object. The `glory.SupplyCurve()` will then undertake the process of identifying reservoir storage capacity expansion pathways and calculating the optimized water yield at each storage capacity point. To apply `GLORY` to multiple basins, simply indicate the basin IDs in the configuration file and run `GLORY` model using `glory.run_model()`. Figure 2 shows an example output of capacity-yield curve and supply curve for Pacific Northwest basin. The water supply curve has been widely used in `GCAM` to inform the water management cost to supply water in the economic market. The detailed documentation on how to use `glory` can be accessed at [glory documentation](https://jgcri.github.io/glory/index.html). -![The GLORY model workflow showing the input data requirements and the steps of modeling capacity-yield relationships and supply curves. \label{fig:2}](curve_pnw.png) +![The example diagnostic output from `GLORY` model for the capacity-yield curve (top) and water supply curve (bottom) for the Pacific Northwest basin. \label{fig:2}](curve_pnw.png) # Acknowledgements This research was supported by the U.S. Department of Energy, Office of Science, as part of research in MultiSector Dynamics, Earth and Environmental System Modeling Program.