update paper based on feedback from #39

paper/paper.bib

@@ -31,6 +31,35 @@ @misc{doecode_10475
   month = {apr}
 }
 
+@misc{statemod,
+  title = {StateMod-15.00.14},
+  author = { Colorado's Decision Support Systems (CDSS)},
+  url = {https://github.com/OpenCDSS/cdss-app-statemod-fortran},
+  howpublished = {[Computer Software]},
+  year = {2018},
+  month = {jun}
+}
+
+@misc{glofrim,
+  title = {GLOFRIM v2.1 (Version v2.1)},
+  author = {Jannis Hoch, Dirk Eilander, Hiroaki Ikeuchi, Hessel Winsemius, & Fedor Baart},
+  url = {https://github.com/openearth/glofrim/tree/v2.1},
+  doi = {10.5281/zenodo.4304656},
+  howpublished = {[Computer Software]},
+  year = {2020},
+  month = {dec}
+}
+
+@misc{modflow,
+  title = {MODFLOW 6 Modular Hydrologic Model version 6.2.1},
+  author = {Langevin, C.D., Hughes, J.D., Banta, E.R., Provost, A.M., Niswonger, R.G., and Panday, Sorab},
+  url = {https://doi.org/10.5066/F76Q1VQV},
+  doi = {10.5066/F76Q1VQV},
+  howpublished = {[Computer Software]},
+  year = {2021},
+  month = {feb}
+}
+
 @article{peckham2013component,
   title = {A component-based approach to integrated modeling in the geosciences: The design of CSDMS},
   author = {Peckham, Scott D and Hutton, Eric WH and Norris, Boyana},
@@ -118,20 +147,6 @@ @article{reservoirs
   doi = {10.5194/hess-24-1275-2020}
 }
 
-@article{voisin2017conus,
-  author = {Voisin, Nathalie and Hejazi, Mohamad I. and Leung, L. Ruby and Liu, Lu and Huang, Maoyi and Li, Hong-Yi and Tesfa, Teklu},
-  title = {Effects of spatially distributed sectoral water management on the redistribution of water resources in an integrated water model},
-  journal = {Water Resources Research},
-  volume = {53},
-  number = {5},
-  pages = {4253-4270},
-  keywords = {earth system model, integrated assessment model, withdrawals and consumptive use, sectoral water management, groundwater/surface water allocation},
-  doi = {10.1002/2016WR019767},
-  url = {https://agupubs.onlinelibrary.wiley.com/doi/abs/10.1002/2016WR019767},
-  eprint = {https://agupubs.onlinelibrary.wiley.com/doi/pdf/10.1002/2016WR019767},
-  year = {2017}
-}
-
 @Article{hess-19-3239-2015,
   AUTHOR = {Chaney, N. W. and Herman, J. D. and Reed, P. M. and Wood, E. F.},
   TITLE = {Flood and drought hydrologic monitoring: the role of model parameter uncertainty},
@@ -143,3 +158,18 @@ @Article{hess-19-3239-2015
   URL = {https://hess.copernicus.org/articles/19/3239/2015/},
   DOI = {10.5194/hess-19-3239-2015}
 }
+
+@article{https://doi.org/10.1029/2018MS001583,
+  author = {Lawrence, David M. and Fisher, Rosie A. and Koven, Charles D. and Oleson, Keith W. and Swenson, Sean C. and Bonan, Gordon and Collier, Nathan and Ghimire, Bardan and van Kampenhout, Leo and Kennedy, Daniel and Kluzek, Erik and Lawrence, Peter J. and Li, Fang and Li, Hongyi and Lombardozzi, Danica and Riley, William J. and Sacks, William J. and Shi, Mingjie and Vertenstein, Mariana and Wieder, William R. and Xu, Chonggang and Ali, Ashehad A. and Badger, Andrew M. and Bisht, Gautam and van den Broeke, Michiel and Brunke, Michael A. and Burns, Sean P. and Buzan, Jonathan and Clark, Martyn and Craig, Anthony and Dahlin, Kyla and Drewniak, Beth and Fisher, Joshua B. and Flanner, Mark and Fox, Andrew M. and Gentine, Pierre and Hoffman, Forrest and Keppel-Aleks, Gretchen and Knox, Ryan and Kumar, Sanjiv and Lenaerts, Jan and Leung, L. Ruby and Lipscomb, William H. and Lu, Yaqiong and Pandey, Ashutosh and Pelletier, Jon D. and Perket, Justin and Randerson, James T. and Ricciuto, Daniel M. and Sanderson, Benjamin M. and Slater, Andrew and Subin, Zachary M. and Tang, Jinyun and Thomas, R. Quinn and Val Martin, Maria and Zeng, Xubin},
+  title = {The Community Land Model Version 5: Description of New Features, Benchmarking, and Impact of Forcing Uncertainty},
+  journal = {Journal of Advances in Modeling Earth Systems},
+  volume = {11},
+  number = {12},
+  pages = {4245-4287},
+  keywords = {global land model, Earth System Modeling, carbon and nitrogen cycling, hydrology, benchmarking},
+  doi = {https://doi.org/10.1029/2018MS001583},
+  url = {https://agupubs.onlinelibrary.wiley.com/doi/abs/10.1029/2018MS001583},
+  eprint = {https://agupubs.onlinelibrary.wiley.com/doi/pdf/10.1029/2018MS001583},
+  abstract = {Abstract The Community Land Model (CLM) is the land component of the Community Earth System Model (CESM) and is used in several global and regional modeling systems. In this paper, we introduce model developments included in CLM version 5 (CLM5), which is the default land component for CESM2. We assess an ensemble of simulations, including prescribed and prognostic vegetation state, multiple forcing data sets, and CLM4, CLM4.5, and CLM5, against a range of metrics including from the International Land Model Benchmarking (ILAMBv2) package. CLM5 includes new and updated processes and parameterizations: (1) dynamic land units, (2) updated parameterizations and structure for hydrology and snow (spatially explicit soil depth, dry surface layer, revised groundwater scheme, revised canopy interception and canopy snow processes, updated fresh snow density, simple firn model, and Model for Scale Adaptive River Transport), (3) plant hydraulics and hydraulic redistribution, (4) revised nitrogen cycling (flexible leaf stoichiometry, leaf N optimization for photosynthesis, and carbon costs for plant nitrogen uptake), (5) global crop model with six crop types and time-evolving irrigated areas and fertilization rates, (6) updated urban building energy, (7) carbon isotopes, and (8) updated stomatal physiology. New optional features include demographically structured dynamic vegetation model (Functionally Assembled Terrestrial Ecosystem Simulator), ozone damage to plants, and fire trace gas emissions coupling to the atmosphere. Conclusive establishment of improvement or degradation of individual variables or metrics is challenged by forcing uncertainty, parametric uncertainty, and model structural complexity, but the multivariate metrics presented here suggest a general broad improvement from CLM4 to CLM5.},
+  year = {2019}
+}

paper/paper.md

@@ -36,20 +36,19 @@ bibliography: paper.bib
 `mosartwmpy` is a Python implementation of the Model for Scale Adaptive River Transport with Water Management (MOSART-WM). This new version retains the functionality of the legacy model (written in FORTRAN) while providing new features to enhance user experience and extensibility. MOSART is a large-scale river-routing model used to study riverine dynamics of water, energy, and biogeochemistry cycles across local, regional, and global scales [@li2013physically]. The WM component introduced by @voisin2013improved represents river regulation through reservoir storage and release operations, diversions from reservoir releases, and allocation to sectoral water demands. Each reservoir release is independently calibrated using long-term mean monthly inflow into the reservoir, long-term mean monthly demand associated with this reservoir, and reservoir goals (flood control, irrigation, recreation, etc.). Generic monthly pre-release rules and storage targets are set up for individual reservoirs; however, those releases are updated annually for inter-annual variability (dry or wet year) and daily for environmental constraints such as flow minimum release and minimum/maximum storage levels. The WM model allows an evaluation of the impact of water management over multiple river basins at once (global, continental scales) and with consistent representation of human operations over the full domain.
 
 # Statement of Need
-MOSART-WM is often utilized as the hydrological component in a larger suite of earth-science models, such as in @doecode_10475. In this context, MOSART-WM is quite efficient and streamlined when running on a supported High-Performance Computing (HPC) cluster. However, learning how to use, extend, and test a tightly-coupled codebase written with domain knowledge implied in a lower-level programming language may greatly increase the turnaround time and error rate for setting up and executing novel experiments. Broadening the code’s accessibility using a programming language such as Python, which in 2020 was the second most utilized language on GitHub [@octoverse_2020], provides a more accessible option to learn and contribute to the science on most computational platforms.
+MOSART-WM is often utilized as the hydrological component in a larger suite of earth-science models, such as in @doecode_10475. In this context, MOSART-WM is quite efficient and streamlined when running on a supported High-Performance Computing (HPC) cluster. However, learning how to use, extend, and test a complex codebase written with domain knowledge implied in a lower-level programming language may greatly increase the turnaround time and error rate for setting up and executing novel experiments. Broadening the code’s accessibility using a programming language such as Python, which in 2020 was the second most utilized language on GitHub [@octoverse_2020], provides a more accessible option to learn and contribute to the science on most computational platforms.
 
-`mosartwmpy` was designed to bridge the gap between the domain scientist who wants a performant software that can still be extended for future research needs, and the new user who may not have expertise within the hydrologic sciences but wishes to integrate the process into their own workflow or quickly become capable in conducting hands-on experimentation for educational purposes. A refactor of MOSART-WM in Python ameliorates the steep learning curve of the FORTRAN version by providing an easy to learn, use, and modify interface. `mosartwmpy` was also built with interoperability in mind by implementing the Community Surface Dynamics Modeling System (CSDMS) Basic Model Interface (BMI) [@peckham2013component; @hutton2020basic], which offers a familiar set of controls for operating and coupling the model. `mosartwmpy` can be accessed on GitHub (https://github.com/IMMM-SFA/mosartwmpy), and a walkthrough of key functionality and use can be found here: [tutorial](https://mosartwmpy.readthedocs.io/en/latest/). Model results have been validated against historical simulations [@https://doi.org/10.1029/2020WR027902], and a validation utility is included with the code.
+`mosartwmpy` was designed to bridge the gap between the domain scientist who wants a performant software that can still be extended for future research needs, and the new user who may not have expertise within the hydrologic sciences but wishes to integrate the process into their own workflow or quickly become capable in conducting hands-on experimentation for educational purposes. A refactor of MOSART-WM in Python ameliorates the steep learning curve of the FORTRAN version by providing an easy to learn, use, and modify interface. `mosartwmpy` was also built with interoperability in mind by implementing the Community Surface Dynamics Modeling System (CSDMS) Basic Model Interface (BMI) [@peckham2013component; @hutton2020basic], which offers a familiar set of controls for operating the model. By leveraging the BMI, `mosartwmpy` can be readily coupled with other earth system models to perform cross-domain experiments.
 
-# Functionality and limitations
-`mosartwmpy` replicates the entirety of the physics found in MOSART-WM. Inputs consist of channel and reservoir geometry, spatially distributed runoff (i.e., excess water on and below the ground that can move on a 2D plane as driven by topology or hydraulic gradient), and spatially distributed water demand. The hillslope and subsurface runoff populate the local streams and river channels, which generally flow toward the oceans (as in \autoref{fig:flow}). In many locations along the main channels, reservoirs collect and store water, releasing portions of the storage downstream over time for various societal uses (i.e. hydroelectricity, drinking water, flood control, and irrigation). Water is also consumed directly from the channels and tributaries for irrigation or non-irrigation uses.
+The target audience for `mosartwmpy` is the data scientist or hydrologist who wishes to rapidly prototype, test, and develop novel modeling capabilities relating to reservoirs and water demand. `mosartwmpy` can be accessed on GitHub (https://github.com/IMMM-SFA/mosartwmpy), and a walkthrough of key functionality and use can be found here: [tutorial](https://mosartwmpy.readthedocs.io/en/latest/). Model results have been validated against historical simulations [@https://doi.org/10.1029/2020WR027902], and a validation utility is included with the code.
 
-![River basin flow over the continental United States as output from `mosartwmpy`.\label{fig:flow}](figure_1.png){ width=75% }
-
-In the 1/8 degree continental United States (CONUS) configuration of `mosartwmpy` [@voisin2017conus], the hillslope routing is set to a default one-hour resolution. To ensure numerical stability in the routing process while allowing rivers to travel across multiple grid cell within one time step, sub time steps are applied for resolving the channel flow accounting for reservoir regulation and water withdrawals. The reservoir extraction is performed at a 20-minute resolution, and the channel flow at resolutions ranging from 12 minutes to half a minute based on the complexity of the grid cell.
+# State of the field
+In addition to `mosartwmpy`'s ancestor MOSART-WM, several other models are commonly used in hydrologic modeling, each excelling at different processes. The Community Land Model (CLM) [@https://doi.org/10.1029/2018MS001583] focuses on the traditional water cycle (i.e. precipitation, evaporation) as well as plant and soil chemistry; runoff output from CLM can be used as input for `mosartwmpy`. StateMod [@statemod] focuses on water allocation based on legal constraints (water rights) as well as supply and demand. MODFLOW [@modflow] focuses on solving for complex groundwater flow properties on three-dimensional grids. GLOFRIM [@glofrim] focuses on providing a framework to couple models implementing the BMI across multi-scale grids, for instance by coupling a meteorological model to a water cycle model to river routing model to hydrodynamic model. In this context, `mosartwmpy` focuses on the interactions between river routing, reservoir management, and water demand.
 
-Any spatial or simulated variable can be written to an output file in NetCDF format at predetermined intervals, typically averaged to daily values. The model can also save its current state as a compressed restart file, allowing the simulation to be regularly checkpointed.
+# Functionality
+Model input for `mosartwmpy` consists of channel and reservoir geometry, groundwater and subsurface runoff (i.e. rain and ice melt), and water demand. The runoff populates the local streams and river channels, which generally flow toward the oceans (as in \autoref{fig:flow}). In many locations along the main channels, reservoirs collect and store water, releasing portions of the storage downstream over time for various societal uses (i.e. hydroelectricity, drinking water, flood control, and irrigation). Water is also consumed directly from the channels and tributaries for irrigation or non-irrigation uses.
 
-Currently, a 1/8 degree CONUS simulation can efficiently scale across eight CPUs using C-bindings to parallelize the vectorized calculations; limitations in the Python vector math implementations restrict  performance boosts of additional processors. Further enhancement is required to match the speeds obtainable in the Fortran version of MOSART-WM, which can effectively scale across a greater number of CPUs by distributing cell-by-cell scalar calculations. As a sample benchmark, a one-year simulation using MOSART-WM on a 24-CPU node of an institutional supercomputer can be performed in about half an hour; whereas the same simulation using `mosartwmpy` on a personal 6-CPU laptop can be performed in about five hours.
+![River basin flow over the continental United States as output from `mosartwmpy`.\label{fig:flow}](figure_1.png){ width=75% }
 
 # Ongoing Research
 As open-source software, `mosartwmpy` promotes collaborative and community model development to meet scientific objectives. Two examples of the potential to extend this codebase are currently underway as a part of the U.S. DOE’s Department of Energy’s Integrated Multisector Multiscale Modeling (IM3) basic research project: an Agent Based Model (ABM) for more accurately simulating irrigation demand based on the economics of various crop types [@abm; @Yoone2020431118], and an improved reservoir operations module for more accurately simulating reservoir release based on data-driven harmonic functions [@reservoirs]. Future planned experiments will study the uncertainty characterization and quantification [@hess-19-3239-2015] of the model based on perturbations in key parameters.