Paper revisions

CITATION.cff

@@ -0,0 +1,13 @@
+cff-version: "0.1.0"
+authors:
+- family-names: Zhao
+  given-names: Mengqi
+  orcid: "0000-0001-5385-2758"
+- family-names: Wild
+  given-names: Thomas B.
+  orcid: "0000-0002-6045-7729"
+- family-names: Vernon
+  given-names: Chris R.
+  orcid: "0000-0002-3406-6214"
+message: If you use this software, please cite as the following:
+title: "GLORY: a python package for global reservoir water yield and cost estimation"

CODE_OF_CONDUCT.md

@@ -0,0 +1,43 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in our
+community a harassment-free experience for everyone, regardless of age, body
+size, visible or invisible disability, ethnicity, sex characteristics, gender
+identity and expression, level of experience, education, socio-economic status,
+nationality, personal appearance, race, religion, or sexual identity and
+orientation.
+
+We pledge to act and interact in ways that contribute to an open, welcoming,
+diverse, inclusive, and healthy community.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment for our
+community include:
+
+* Demonstrating empathy and kindness toward other people
+* Being respectful of differing opinions, viewpoints, and experiences
+* Giving and gracefully accepting constructive feedback
+* Accepting responsibility and apologizing to those affected by our mistakes,
+and learning from the experience
+* Focusing on what is best not just for us as individuals, but for the overall
+community
+
+Examples of unacceptable behavior include:
+
+* The use of sexualized language or imagery, and sexual attention or
+advances of any kind
+* Trolling, insulting or derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information, such as a physical or email
+address, without their explicit permission
+* Other conduct which could reasonably be considered inappropriate in a
+professional setting
+
+
+## Attribution
+
+This Code of Conduct is adapted from the
+[Contributor Covenant](https://www.contributor-covenant.org/version/2/0/code_of_conduct.html).

CONTRIBUTING.md

@@ -0,0 +1,38 @@
+# How to contribute
+
+We welcome third-party patches, which are essential for advancing the science and architecture of GLORY.
+But there are a few guidelines that we ask contributors to follow, guidelines that ease the maintainers' organizational and logistical duties, while encouraging development by others. All contributors agree to abide by the code of conduct.
+
+## Getting Started
+
+* Make sure you have a [GitHub account](https://github.com/signup/free).
+* **Open an issue** describing your proposed change or work (after making sure one does not already exist).
+  * Clearly describe the issue including steps to reproduce when it is a bug.
+  * Discuss how your change will affect GLORY, and thus whether it's MAJOR, MINOR, or a PATCH.
+  * Interact with the project maintainers to refine/change/prioritize your issue and identify what branch will be targeted (see below).
+* Trivial changes to comments or documentation do not require creating a new issue.
+
+## Making Changes
+
+* **Start your work on the correct branch**.
+  * The active development branch will be titled dev
+  * If your change is a PATCH, it will typically be based on the current dev branch; if MINOR, the next minor release branch; if MAJOR, the next major release branch. For example, as of this writing there are branches `dev`, `rc1.2` and `rc2.0`, corresponding to the PATCH-MINOR-MAJOR start points respectively.
+  * We will never accept pull requests to the `main` branch.
+* Check for unnecessary whitespace with `git diff --check` before committing.
+* Make sure your commit messages are descriptive but succinct, describing what was changed and why, and **reference the relevant issue number**. Make commits of logical units.
+* Make sure you have added the necessary tests for your changes. Tests should be included in the root `tests` directory and are facilitated using `pytest` which is installed with the development version of GLORY.  See more info on using `pytest` here:  https://docs.pytest.org/en/7.4.x/contents.html
+* Run _all_ the tests to assure nothing else was accidentally broken.
+
+## Submitting Changes
+
+* Submit a pull request.
+* **Your pull request should include one of the following two statements**:
+   * You own the copyright on the code being contributed, and you hereby grant PNNL unlimited license to use this code in this version or any future version of GLORY. You reserve all other rights to the code.
+   * Somebody else owns the copyright on the code being contributed (e.g., your employer because you did it as part of your work for them); you are authorized by that owner to grant PNNL an unlimited license to use this code in this version or any future version of GLORY, and you hereby do so. All other rights to the code are reserved by the copyright owner.
+* The core team looks at Pull Requests on a regular basis, and will respond as soon as possible.
+
+
+# Additional Resources
+
+* [General GitHub documentation](http://help.github.com/)
+* [GitHub pull request documentation](http://help.github.com/send-pull-requests/)

DISCLAIMER

@@ -0,0 +1,17 @@
+GLORY
+
+Copyright (c) 2022-current, Battelle Memorial Institute
+
+Open source under license BSD 3-Clause
+
+Open Source Disclaimer:
+
+This material was prepared as an account of work sponsored by an agency of the United States Government.  Neither the United States Government nor the United States Department of Energy, nor Battelle, nor any of their employees, nor any jurisdiction or organization that has cooperated in the development of these materials, makes any warranty, express or implied, or assumes any legal liability or responsibility for the accuracy, completeness, or usefulness or any information, apparatus, product, software, or process disclosed, or represents that its use would not infringe privately owned rights.
+Reference herein to any specific commercial product, process, or service by trade name, trademark, manufacturer, or otherwise does not necessarily constitute or imply its endorsement, recommendation, or favoring by the United States Government or any agency thereof, or Battelle Memorial Institute. The views and opinions of authors expressed herein do not necessarily state or reflect those of the United States Government or any agency thereof.
+
+PACIFIC NORTHWEST NATIONAL LABORATORY
+operated by
+BATTELLE
+for the
+UNITED STATES DEPARTMENT OF ENERGY
+under Contract DE-AC05-76RL01830

paper/paper.md

@@ -1,5 +1,5 @@
 ---
-title: '`GLORY`: a python package for global reservoir water yield and cost estimation'
+title: 'GLORY: a Python package for global reservoir water yield and cost estimation'
 tags:
   - Python
   - global reservoir water yield
@@ -19,13 +19,13 @@ affiliations:
    index: 1
  - name: Joint Global Change Research Institute, College Park, MD, USA
    index: 2
-date: December 2023
+date: June 2024
 bibliography: paper.bib
 ---
 
 # Summary
 The `GLORY` (GLObal Reservoir Yield) model is an open-source Python package designed to estimate the economic costs associated with supplying 
-increasing levels of water yield from reservoir storage across the world's large river basins (Figure 1). For each river basin, the model first uses linear
+increasing levels of water yield from reservoir storage across the world's large river basins (\autoref{fig:workflow}). For each river basin, the model first uses linear
 programming to optimize a reservoir release strategy designed to maximize the annual basin-wide volumetric yield of water that can be achieved
 for increasing levels of reservoir storage capacity, subject to geophysical constraints. For example, the model conducts a monthly time-step reservoir water 
 balance that accounts for the sub-annual timing of streamflow (i.e., reservoir inflows), surface water evaporation, reservoir release, environmental flows, return flows, 
@@ -39,7 +39,7 @@ coupled human-Earth systems assessments that require as input an economic valuat
 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)
+![The GLORY model workflow showing the input data requirements and the steps of modeling capacity-yield relationships and supply curves. \label{fig:workflow}](workflow.png)
 
 
 # Statement of Need
@@ -58,9 +58,9 @@ The field of hydro-economic modeling has seen limited application at the global
 # 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 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).
+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 the `GLORY` model using `glory.run_model()`. \autoref{fig:curve} shows an example output of capacity-yield curve and supply curve for Pacific Northwest basin in the United States. 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 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)
+![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:curve}](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.

setup.py

@@ -16,10 +16,10 @@ def readme():
     version=version,
     packages=find_packages(),
     url='https://github.com/JGCRI/glory',
-    license='BSD-2-Clause',
+    license='BSD-3-Clause',
     author='Mengqi Zhao',
     author_email='mengqi.zhao@pnnl.gov',
-    description='A python package for the Global Reservoir Yield (GLORY) model.',
+    description='A python package for estimating global reservoir yield and costs for water supply.',
     long_description=readme(),
     long_description_content_type="text/markdown",
     python_requires='>=3.9',