Merge pull request #626 from UW-Hydro/release/VIC.5.0.0

Release/vic.5.0.0 --> master

Author: Joe Hamman

CONTRIBUTING.md .github.com/CONTRIBUTING.md

@@ -23,7 +23,7 @@ We expect that the user comes prepared with some understanding of the model and
 
 The VIC user and developer community is quite large and is spread all around the world.  Depending on the question or issue your facing, there are a number of avenues to get in-touch:
 
-VIC Users Listserv: [![VIC Users Listserv](https://img.shields.io/badge/VIC%20Users%20Listserve-Active-blue.svg)](https://mailman.u.washington.edu/mailman/listinfo/vic_users)
+VIC Users Listserve: [![VIC Users Listserv](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)
 

.github.com/ISSUE_TEMPLATE.md

@@ -0,0 +1,16 @@
+#### Bug Reports
+<!--- please provide the following information for bug reports --->
+
+- Version of VIC that you are using (e.g. VIC.5.0.0)
+- Name and version of the C compiler you are using
+- Operating system
+- A description of relevant model settings
+- A summary of the bug or error message you are getting
+
+#### Feature Requests
+<!--- please provide the following information for feature requests --->
+
+- Description of feature
+- Description of the problem the feature addresses
+- Will the proposed feature be backward compatible?
+- Will the proposed feature change the science results of VIC?

.github.com/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,6 @@
+- [ ] closes #xxx
+- [ ] tests passed
+- [ ] new tests added
+- [ ] science test figures
+- [ ] ran uncrustify prior to final commit
+- [ ] ReleaseNotes entry

docs/Development/Contributing.md

@@ -4,7 +4,7 @@ VIC is an [open source](open-source-philosophy.md) research model.  All developm
 
 ## Features Under Development
 
-There are currently a number of active development projects working on VIC. To see which features are slatted for future release, take a look at the issues in our [development milestones page on GitHub](https://github.com/UW-Hydro/VIC/milestones).
+There are currently a number of active development projects working on VIC. To see which features are slated for future release, take a look at the issues in our [development milestones page on GitHub](https://github.com/UW-Hydro/VIC/milestones).
 
 ## Development and Collaboration
 

docs/Development/ReleaseNotes.md

@@ -10,14 +10,16 @@ For a list of known issues and their fixes (in bug-fix updates), visit the VIC G
 
 To check which release of VIC you are running:
 
-For VIC 4, type `vicNl -v`
-For VIC 5 and later, type `vic _{classic,image}.exe -v`
+- For VIC 4, type `vicNl -v`
+- For VIC 5 and later, type `vic_{classic,image}.exe -v`
 
 ------------------------------
 
-## VIC 5.0.0 (Release Candidate 2)
+## VIC 5.0.0 [![DOI](https://zenodo.org/badge/7766/UW-Hydro/VIC.svg)](https://zenodo.org/badge/latestdoi/7766/UW-Hydro/VIC)
 
-**Release date: August 18, 2016**
+**Release date: (September 2, 2016)**
+
+Source code is available here: [![VIC.5.0.0](https://img.shields.io/badge/VIC-5.0.0-blue.svg)](https://github.com/UW-Hydro/VIC/releases/tag/VIC.5.0.0)
 
 This is a major update from VIC 4. The VIC 5.0.0 release aims to have nearly identical physics as VIC 4.2 while providing a clean, refactored code base supporting multiple drivers. There are a number of new features, bug fixes, and backward incompatible changes. See the VIC Github page for more details on the changes included in this release.
 
@@ -27,44 +29,54 @@ This is a major update from VIC 4. The VIC 5.0.0 release aims to have nearly ide
 
 	Although the physics and model behavior of VIC 5.0.0 should be nearly identical to VIC 4.2, the source code has undergone a major cleanup and reorganization. We have separated the physical core ("vic_run") from the driver source code. This work has improved the extensibility and readability of the model.
 
+
 2. Classic Driver ([GH#7](https://github.com/UW-Hydro/VIC/issues/7))
 
 	The Classic Driver provides similar functionality as VIC 4, including ASCII and binary I/O, and a time-before-space evaluation loop order. The Classic Driver is maintained for two main reasons:
 
 	1. to provide some level of backward compatibility for existing VIC users that wish to continue using VIC using a traditional approach, and,
 	2. to allow VIC to be run at individual grid cells, without requiring the infrastructure needed by the Image Driver. Documentation for the Classic Driver can be found [here](../Documentation/Drivers/Classic/ClassicDriver/).
 
+
 3. Image Driver ([GH#7](https://github.com/UW-Hydro/VIC/issues/7))
 
 	The Image Driver adds a number of features to the user interface of the VIC model. Most notably, it uses a space-before-time evaluation loop order, netCDF I/O, and parallelization using MPI.  Image Driver specific documentation can be found [here](../Documentation/Drivers/Image/ImageDriver/).
 
+
 4. Constants File ([GH#192](https://github.com/UW-Hydro/VIC/pull/173))
 
 	Earlier versions of VIC included many hard-coded parameters and constants.  We have consolidated these constants into a single structure and developed an input file that allows users to modify parameters at run-time.  See [here](../Documentation/Constants/) for more information.
 
+
 5. Logging ([GH#173](https://github.com/UW-Hydro/VIC/pull/173))
 
 	A set of logging Macros have been added to all drivers and `vic_run`. The logging level can be set in the driver `Makefile` via the `LOG_LVL` variable. The logging Macros provide the filename and line number in the source code to aid in debugging.  Additionally, when compiler support is available, a traceback is printed when VIC exits during runtime. When the `LOG_DIR` variable is provided in the global parameter file, VIC will write its log(s) to log files instead of printing to stdout.
 
+
 6. Sub-hourly Timestep ([GH#188](https://github.com/UW-Hydro/VIC/pull/188))
 
-	Previous versions of VIC were limited to a minimum timestep of one hour. The units of the VIC timestep have been changed from hours to seconds and the minimum timestep is now one second. If you intend on running VIC at a timestep less that one hour, we suggest significant testing.
+	Previous versions of VIC were limited to a minimum timestep of one hour. The units of the VIC timestep have been changed from hours to seconds and the minimum timestep is now one second. If you intend on running VIC at a timestep of less than one hour, we suggest extensive testing.
+
 
 7. Calendar Support ([GH#188](https://github.com/UW-Hydro/VIC/pull/188))
 
 	Earlier versions of VIC used the standard Gregorian calendar.  Because many modern climate models use non-standard calendars, we have implemented all [CF compliant calendars](http://www.cgd.ucar.edu/cms/eaton/netcdf/CF-20010629.htm#cal). The standard Gregorian calendar remains the VIC default. See the documentation for individual drivers for how to set the calendar option (e.g. [classic](../Documentation/Drivers/Classic/GlobalParam/#main-simulation-parameters)).
 
+
 8. Sample Datasets ([GH#387](https://github.com/UW-Hydro/VIC/pull/387))
 
 	The [VIC_sample_data](https://github.com/UW-hydro/VIC_sample_data) repository contains the necessary input datasets (forcings and parameters) to run short simulations of the VIC model for both the classic and image driver.
 
+
 9. Tests Datasets ([GH#79](https://github.com/UW-Hydro/VIC/issues/79))
 
 	See https://github.com/UW-Hydro/VIC/issues/79 for more information. A temporary location of the test data is here: ftp://ftp.hydro.washington.edu/pub/gergel/VIC5_test_data/
 
+
 10. Testing and Continuous Integration ([GH#190](https://github.com/UW-Hydro/VIC/pull/190))
 
-	A comprehensive testing platform has been implemented and is available for public use along with the VIC model. A small subset of the test platform is run on [Travis-CI](https://travis-ci.org/UW-Hydro/VIC), which facilitates continuous integration of the VIC test platform. More information on the test platform is [here](Testing.md)
+	A comprehensive testing platform has been implemented and is available for public use along with the VIC model. A small subset of the test platform is run on [Travis-CI](https://travis-ci.org/UW-Hydro/VIC), which facilitates continuous integration of the VIC test platform. More information on the test platform is [here](Testing.md).
+
 
 11. Run-time profiling and timing ([GH#442](https://github.com/UW-Hydro/VIC/pull/442))
 
@@ -134,7 +146,7 @@ This is a major update from VIC 4. The VIC 5.0.0 release aims to have nearly ide
 
 3. Removed `LONGWAVE` and `SHORTWAVE` forcing types ([GH#379](https://github.com/UW-Hydro/VIC/pull/379)).
 
-	Previous versions of VIC allowed users to specify either `LONGWAVE` or `LWDOWN` to denote the incoming longwave radiation flux and `SHORTWAVE` or `SWDOWN` to denote the incoming shorwave radiation flux. We have removed these duplicate options, standardizing on the more descriptive `LWDOWN` and `SWDOWN`.
+	Previous versions of VIC allowed users to specify either `LONGWAVE` or `LWDOWN` to denote the incoming longwave radiation flux and `SHORTWAVE` or `SWDOWN` to denote the incoming shortwave radiation flux. We have removed these duplicate options, standardizing on the more descriptive `LWDOWN` and `SWDOWN`.
 
 	Similarly, output variables `OUT_NET_LONG` and `OUT_NET_SHORT` have been replaced with `OUT_LWNET` and `OUT_SWNET`, respectively.
 
@@ -159,16 +171,16 @@ This is a major update from VIC 4. The VIC 5.0.0 release aims to have nearly ide
 3. Fix related to exact restart ([GH#481](https://github.com/UW-Hydro/VIC/pull/481), [GH#507](https://github.com/UW-Hydro/VIC/pull/507), [GH#509](https://github.com/UW-Hydro/VIC/pull/509))
 
 	Previously, VIC did not produce the same results (fluxes and states) if a simulation was separated into multiple shorter-period runs by saving the state variables and restarting. This was due to:
-		1. The MTCLIM algorithm resulted in slightly different sub-daily meteorological variable values for different lengths of forcings (MTCLIM is deprecated in the current version)
-		2. A few bugs resulting in inexact restart.
 
-	The following bugs have been fixed:
+	1. The MTCLIM algorithm resulted in slightly different sub-daily meteorological variable values for different lengths of forcings (MTCLIM is deprecated in the current version)
+
+	2. A few bugs resulting in inexact restart. The following bugs have been fixed:
 
-	- The prognostic state variable `energy.Tfoliage` (foliage temperature) is now saved to the state file
-	- Two flux variables `energy.LongUnderOut` and `energy.snow_flux` are now saved to the state file.
+		- The prognostic state variable `energy.Tfoliage` (foliage temperature) is now saved to the state file
+		- Two flux variables `energy.LongUnderOut` and `energy.snow_flux` are now saved to the state file.
 
-		!!!Note
-				This is a temporary solution to ensure exact restart. A better way of handling these two flux variables needs to be done in the future (see [GH#479](https://github.com/UW-Hydro/VIC/issues/479))
+			!!!Note
+					This is a temporary solution to ensure exact restart. A better way of handling these two flux variables needs to be done in the future (see [GH#479](https://github.com/UW-Hydro/VIC/issues/479))
 
 4. Fix for binary state file I/O ([GH#487](https://github.com/UW-Hydro/VIC/pull/487))
 
@@ -180,6 +192,25 @@ This is a major update from VIC 4. The VIC 5.0.0 release aims to have nearly ide
 
 ------------------------------
 
+## VIC 4.2.d [![DOI](https://zenodo.org/badge/doi/10.5281/zenodo.56058.svg)](http://dx.doi.org/10.5281/zenodo.56058)
+
+!!! Note "Note: Final Release of VIC 4 Development Track"
+	This is the last release of the VIC Version 4 development track.  The next release will be VIC.5.0 and will include backward incompatible changes. Future updates the VIC 4 development track will be made on the `support/VIC.4.2.d`.
+
+Source code is available here: [![VIC.4.2.d](https://img.shields.io/badge/VIC-4.2.d-blue.svg)](https://github.com/UW-Hydro/VIC/releases/tag/VIC.4.2.d)
+
+**Release date: (June 20, 2015)**
+
+This is a bugfix update from 4.2.c.
+
+#### Bug Fixes
+
+1. Fixed uninitialized `dmy_struct` when `OUTPUT_FORCE==TRUE` and `BINARY_OUTPUT==TRUE` ([GH#393](https://github.com/UW-Hydro/VIC/issues/393))
+
+1. Fixed uninitialized vegetation parameters when `VEGPARAM_LAI==FALSE` ([GH#455](https://github.com/UW-Hydro/VIC/issues/455))
+
+------------------------------
+
 ## VIC 4.2.c [![DOI](https://zenodo.org/badge/doi/10.5281/zenodo.35302.svg)](http://dx.doi.org/10.5281/zenodo.35302)
 
 Source code is available here: [![VIC.4.2.c](https://img.shields.io/badge/VIC-4.2.c-blue.svg)](https://github.com/UW-Hydro/VIC/releases/tag/VIC.4.2.c)
@@ -188,9 +219,6 @@ Source code is available here: [![VIC.4.2.c](https://img.shields.io/badge/VIC-4.
 
 This is a bugfix update from 4.2.b.
 
-!!! Note "Note: Final Release of VIC 4 Development Track"
-	This is the last release of the VIC Version 4 development track.  The next release will be VIC.5.0 and will include backward incompatible changes.
-
 #### Bug Fixes:
 
 1.  Documented how VIC 4.2 needs user to specify veg_lib and veg_param files when OUTPUT_FORCE = TRUE. ([GH#305](https://github.com/UW-Hydro/VIC/issues/305))

docs/Development/Testing.md

@@ -9,7 +9,7 @@ The VIC Test Suite includes six main test types:
     * restart:  tests that address model state and restart capability.
     * I/O:  tests that address model input and output functionality.
         *  forcings come out the way they come in
-        *  parameter files are appropriately read in allocated.
+        *  parameter files are appropriately ingested and parameter values are correctly allocated.
 3.  **science**:  tests that aim to assess the model's scientific skill.  Many of these tests are compared to observations of some kind.
 4.  **examples**:  a set of examples that users may download and run.
 5.  **release**:  longer, full domain simulations performed prior to release demonstrating model output for a final release.
@@ -18,7 +18,7 @@ The VIC Test Suite includes six main test types:
 
 The **system** and **examples** tests use the [VIC sample data repository](https://github.com/UW-Hydro/VIC_sample_data). This repository includes short (e.g. 10 days) test setups for the VIC image and classic drivers.
 
-The **science** and **release** tests are under development (as of June 2016).
+The **release** tests are under development (as of August 2016).
 
 ## Running the VIC Test Suite
 
@@ -27,30 +27,25 @@ The VIC test suite uses a set of Python utilities and libraries to execute the s
 1. Download and run the Anaconda installer: http://continuum.io/downloads
 2. Install the required dependencies:
 
-    ```Bash
-    # Create a conda virtual environment including the required dependencies
-    conda env create -n vic_test_env -f ci/requirements.yml
+        # Create a conda virtual environment including the required dependencies
+        conda env create -n vic_test_env -f ci/requirements.yml
 
-    # Active the virtual environment
-    source activate vic_test_env
+        # Activate the virtual environment
+        source activate vic_test_env
 
-    # Install the Python driver into the virtual environment
-    python ./vic/drivers/python/setup.py install
-    ```
+        # Install the Python driver into the virtual environment
+        python ./vic/drivers/python/setup.py install
 
 3. Run the test suite:
 
-    ```Bash
-    # Print the run_tests.py usage
-    ./tests/run_tests.py -h
+        # Print the run_tests.py usage
+        ./tests/run_tests.py -h
 
-    # Run the test suite for the unit and examples cases for the classic driver
-    ./tests/run_tests.py unit examples \
-        --vic_exe=vic/drivers/classic/vic_classic.exe \
-        --driver=classic \
-        --data_dir=${SAMPLES_PATH}/data \
-        --examples=./tests/examples/examples.cfg
-    ```
+        # Run the test suite for the unit and examples cases for the classic driver
+        ./tests/run_tests.py unit examples \
+            --classic=vic/drivers/classic/vic_classic.exe \
+            --data_dir=${SAMPLES_PATH}/data \
+            --examples=./tests/examples/examples.cfg
 
 ## Travis
 
@@ -59,4 +54,4 @@ VIC uses the [Travis CI](http://travis-ci.org/) continuous integration system. V
 - *Compilers*: `gcc` and `clang`
 - *Platforms*: `Linux` and `OSX`
 
-The Travis tests also run the **unit**, and **examples** tests described above.
+The Travis tests also run the **unit**, **system**, and **examples** tests described above.

docs/Development/git-workflow.md

@@ -1,8 +1,8 @@
 # Development Workflow
-The basic workflow described here follows a workflow originally outlined by Vincent Driessen.  The workflow is built around the Git version control system.  A basic description of the branching strategy and release management used by our research group is presented here.  We use a central truth repository (https://github.com/UW-Hydro/VIC) that contains our main branches.
+The basic workflow described here follows a workflow originally [outlined](http://nvie.com/posts/a-successful-git-branching-model/) by Vincent Driessen.  The workflow is built around the Git version control system.  A basic description of the branching strategy and release management used by our research group is presented here.  We use a central truth repository (https://github.com/UW-Hydro/VIC) that contains our main branches.
 
 ## Main Branches
-Both of the main branches are published on the Github page and are controlled only by those within the admin group.  The repository is organized into several branches for different purposes.  In general, any new development will wan to start with a branch from the develop branch.
+Both of the main branches are published on the Github page and are controlled only by those within the admin group.  The repository is organized into several branches for different purposes.  In general, any new development will want to start with a branch from the develop branch.
 
 **1. master**– The master branch represents the official release of the code.  This branch is updated by new releases from the develop/release branches and by hotfixes.
 

docs/Development/open-source-philosophy.md

@@ -10,7 +10,7 @@ Our rationale for moving the VIC model development to the open source community
 
 There is **no official support** for the VIC model.
 
-While you are more than welcome to use VIC in your own research endeavors, the model code comes with _**no guarantees, expressed or implied, as to suitability, completeness, accuracy, and whatever other claim you would like to make**_. In addition, the model has no graphical user interface, nor does it include a large set of analysis tools, since most people want to use their own set of tools.
+While you are more than welcome to use VIC in your own research endeavors, the model code comes with ***no guarantees, expressed or implied, as to suitability, completeness, accuracy, and whatever other claim you would like to make***. In addition, the model has no graphical user interface, nor does it include a large set of analysis tools, since most people want to use their own set of tools.
 
 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 website includes reasonably complete instructions on how to run the model, as well as the opportunity to sign up for the VIC Users Email List.