add pointers to VIC-5 paper in the VIC documentation

solomonsg · Aug 30, 2018 · 40e02a4 · 40e02a4
1 parent 5a22e90
commit 40e02a4
Show file tree

Hide file tree

Showing 4 changed files with 16 additions and 6 deletions.
diff --git a/docs/Documentation/References.md b/docs/Documentation/References.md
@@ -1,9 +1,13 @@
 # VIC Model References
 
-## Primary Historical Reference
+### Primary Historical Reference
 
 Liang, X., D. P. Lettenmaier, E. F. Wood, and S. J. Burges (1994), A simple hydrologically based model of land surface water and energy fluxes for general circulation models, _J. Geophys. Res._, **99**(D7), 14415–14428, [doi:10.1029/94JD00483](http://dx.doi.org/10.1029/94JD00483).
 
+### Primary Reference for VIC-5
+
+Hamman, J. J., Nijssen, B., Bohn, T. J., Gergel, D. R., and Mao, Y.: The Variable Infiltration Capacity model version 5 (VIC-5): infrastructure improvements for new applications and reproducibility, _Geosci. Model Dev._, *11*, 3481-3496, https://doi.org/10.5194/gmd-11-3481-2018, 2018.
+
 ### Other Historical References
 
 Adam, J.C., and D.P. Lettenmaier, 2008: Application of new precipitation and reconstructed streamflow products to streamflow trend attribution in Northern Eurasia, _J. Climate_, **21**(8), 1807-1828.

diff --git a/docs/Overview/ModelOverview.md b/docs/Overview/ModelOverview.md
@@ -1,5 +1,8 @@
 # VIC Model Overview
 
+!!! note
+    You are viewing the documentation for VIC version 5 (VIC-5). Relative to VIC-4, this version includes many infrastructure improvements. Those enhancements are described in [Hamman et al, 2018](https://doi.org/10.5194/gmd-11-3481-2018).
+
 ## Main Features
 
 The VIC model ([Liang et al., 1994](../Documentation/References.md#primary-historical-reference)) is a large-scale, semi-distributed hydrologic model.  As such, it shares several basic features with the other land surface models (LSMs) that are commonly coupled to global circulation models (GCMs):

diff --git a/docs/index.md b/docs/index.md
@@ -3,7 +3,10 @@
 [![Build Status](https://travis-ci.org/UW-Hydro/VIC.png?branch=develop)](https://travis-ci.org/UW-Hydro/VIC) [![VIC Users Listserve](https://img.shields.io/badge/VIC%20Users%20Listserve-Active-blue.svg)](https://mailman.u.washington.edu/mailman/listinfo/vic_users) [![Join the chat at https://gitter.im/UW-Hydro/VIC](https://badges.gitter.im/Join%20Chat.svg)](https://gitter.im/UW-Hydro/VIC?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge) [![GitHub license](https://img.shields.io/badge/license-GPLv2-blue.svg)](https://raw.githubusercontent.com/UW-Hydro/VIC/master/LICENSE.txt) [![Documentation Status](https://readthedocs.org/projects/vic/badge/?version=latest)](http://vic.readthedocs.org/en/latest/)
 [![DOI](https://zenodo.org/badge/7766/UW-Hydro/VIC.svg)](https://zenodo.org/badge/latestdoi/7766/UW-Hydro/VIC)
 
-VIC ([Liang et al., 1994](Documentation/References.md)) is a macroscale hydrologic model that solves full water and energy balances, originally developed by Xu Liang at the University of Washington.  VIC is a research model and in its various forms it has been applied to most of the major river basins around the world, as well as [globally](links.md). The VIC model is distributed under the [GNU GPL v2.0](http://www.gnu.org/licenses/gpl-2.0.html) license. If you make use of this model, please acknowledge the appropriate references listed on the [references](Documentation/References.md) page. These should include [Liang et al., 1994](Documentation/References.md) plus any references relevant to the features you are using, which are cited in the feature descriptions on the [Model Overview](Overview/ModelOverview.md) page.
+!!! note
+    You are viewing the documentation for VIC version 5 (VIC-5). Relative to VIC-4, this version includes many infrastructure improvements. Those enhancements are described in [Hamman et al, 2018](https://doi.org/10.5194/gmd-11-3481-2018).
+
+VIC ([Liang et al., 1994](Documentation/References.md)) is a macroscale hydrologic model that solves full water and energy balances, originally developed by Xu Liang at the University of Washington.  VIC is a research model and in its various forms it has been applied to most of the major river basins around the world, as well as [globally](links.md). The VIC model is distributed under the [GNU GPL v2.0](http://www.gnu.org/licenses/gpl-2.0.html) license. If you make use of this model, please acknowledge the appropriate references listed on the [references](Documentation/References.md) page. These should include [Liang et al., 1994](Documentation/References.md), [Hamman et al., 2018](Documentation/References.md) for VIC-5, and any references relevant to the features you are using, which are cited in the feature descriptions on the [Model Overview](Overview/ModelOverview.md) page.
 
 Development and maintenance of the current official version of the VIC model is led by the [UW Hydro | Computational Hydrology group](http://uw-hydro.github.io/) in the [Department of Civil and Environmental Engineering](http://www.ce.washington.edu) at the [University of Washington](http://www.washington.edu). Every new application addresses new problems and conditions that the model may not currently be able to handle, and as such the model is always under development. The VIC model is an open source development project, which means that contributions are welcome, including to the VIC documentation.
 

diff --git a/readme.md b/readme.md
@@ -2,8 +2,8 @@
 
 | VIC Links & Badges              |                                                                             |
 |------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
-| VIC Documentation      | [![Documentation Status](https://readthedocs.org/projects/vic/badge/?version=latest)](http://vic.readthedocs.org/en/latest/)                                                                             |
-| Travis Build           | [![Build Status](https://travis-ci.org/UW-Hydro/VIC.png)](https://travis-ci.org/UW-Hydro/VIC)                                                                                             |
+| VIC Documentation      | [![Documentation Status](https://readthedocs.org/projects/vic/badge/?version=latest]](http://vic.readthedocs.org/en/latest/)                                                                             |
+| Travis Build           | [![Build Status](https://travis-ci.org/UW-Hydro/VIC.png)](https://travis-ci.org/UW-Hydro/VIC)                                                                                                            |
 | VIC Users Listserve    | [![VIC Users Listserve](https://img.shields.io/badge/VIC%20Users%20Listserve-Active-blue.svg)](https://mailman.u.washington.edu/mailman/listinfo/vic_users)                                              |
 | Developers Gitter Room | [![Join the chat at https://gitter.im/UW-Hydro/VIC](https://badges.gitter.im/Join%20Chat.svg)](https://gitter.im/UW-Hydro/VIC?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge) |
 | License                | [![GitHub license](https://img.shields.io/badge/license-GPLv2-blue.svg)](https://raw.githubusercontent.com/UW-Hydro/VIC/master/LICENSE.txt)                                                              |
@@ -15,7 +15,7 @@ This repository serves as the public source code repository of the **Variable In
 
 The Variable Infiltration Capacity (VIC) macroscale hydrological model (MHM) has been developed over the last two decades at the [University of Washington](http://uw-hydro.github.io/) and [Princeton University](http://hydrology.princeton.edu) in collaboration with a large number of other researchers around the globe. Development and maintenance of the official version of the VIC model is currently coordinated by the [UW Hydro | Computational Hydrology group](http://www.hydro.washington.edu) in the [Department of Civil and Environmental Engineering](http://www.ce.washington.edu) at the [University of Washington](http://www.washington.edu). All development activity is coordinated via the [VIC github page](https://github.com/UW-Hydro/VIC), where you can also find all archived, current, beta, and development versions of the model.
 
-A skeletal first version of the VIC model was introduced to the community by [Wood et al. [1992]](http://dx.doi.org/10.1029/91JD01786) and a greatly expanded version, from which current variations evolved, is described by [Liang et al. [1994]](http://dx.doi.org/10.1029/94jd00483). As compared to other MHMs, VIC’s distinguishing hydrological features are its representation of subgrid variability in soil storage capacity as a spatial probability distribution to which surface runoff is related, and its parameterization of base flow, which occurs from a lower soil moisture zone as a nonlinear recession. Movement of moisture between the soil layers is modeled as gravity drainage, with the unsaturated hydraulic conductivity a function of the degree of saturation of the soil. Spatial variability in soil properties, at scales smaller than the grid scale, is represented statistically, without assigning infiltration parameters to specific subgrid locations. Over time, many additional features and representations of physical processes have been added to the model. VIC has been used in a large number of regional and continental scale (even global) hydrological studies. A selection of VIC applications can be found on the [VIC references page](http://vic.readthedocs.org/en/latest/Documentation/References/).
+A skeletal first version of the VIC model was introduced to the community by [Wood et al. [1992]](http://dx.doi.org/10.1029/91JD01786) and a greatly expanded version, from which current variations evolved, is described by [Liang et al. [1994]](http://dx.doi.org/10.1029/94jd00483). As compared to other MHMs, VIC’s distinguishing hydrological features are its representation of subgrid variability in soil storage capacity as a spatial probability distribution to which surface runoff is related, and its parameterization of base flow, which occurs from a lower soil moisture zone as a nonlinear recession. Movement of moisture between the soil layers is modeled as gravity drainage, with the unsaturated hydraulic conductivity a function of the degree of saturation of the soil. Spatial variability in soil properties, at scales smaller than the grid scale, is represented statistically, without assigning infiltration parameters to specific subgrid locations. Over time, many additional features and representations of physical processes have been added to the model. VIC has been used in a large number of regional and continental scale (even global) hydrological studies. In 2016, VIC version 5 was released. This was a major update to the VIC source code focusing mainly on infrastructure improvements. The development of VIC-5 is detailed in [Hamman et al. 2018](https://doi.org/10.5194/gmd-11-3481-2018). A selection of VIC applications can be found on the [VIC references page](http://vic.readthedocs.org/en/latest/Documentation/References/).
 
 Every new application addresses new problems and conditions that the model may not currently be able to handle, and as such the model is always under development. The VIC model is an open source development project, which means that contributions are welcome, including to the VIC documentation.
 
@@ -25,4 +25,4 @@ VIC is a research model developed by graduate students, post-docs and research s
 
 While we would like to hear about your particular application (especially a copy of any published paper), we cannot give you individual support in setting up and running the model. The [VIC documentation website](http://vic.readthedocs.org) includes reasonably complete instructions on how to run the model, as well as the opportunity to sign up for the VIC Users Email List. The [VIC listserve](https://mailman.u.washington.edu/mailman/listinfo/vic_users) should be used for questions about model setup and application. It is basically VIC users helping other VIC users. All other exchanges about VIC source code are managed through the [VIC github page](https://github.com/UW-Hydro/VIC).
 
-If you make use of this model, please acknowledge [Liang et al. [1994]](http://dx.doi.org/10.1029/94jd00483) plus any other references appropriate to the features you used that are cited in the [model overview](http://vic.readthedocs.org/en/latest/Overview/ModelOverview/).
+If you make use of this model, please acknowledge [Liang et al. [1994]](http://dx.doi.org/10.1029/94jd00483) and [Hamman et al. [2018]](https://doi.org/10.5194/gmd-11-3481-2018) plus any other references appropriate to the features you used that are cited in the [model overview](http://vic.readthedocs.org/en/latest/Overview/ModelOverview/).