The Variable Infiltration Capacity (VIC) model is a macroscale semi-distributed hydrologic model. VIC development began in the early 1990s and the model has since been used extensively for basin- to global-scale applications that include hydrologic dataset construction, trend analysis of hydrologic fluxes and states, data evaluation and assimilation, forecasting, coupled climate modeling, and climate change impact assessment. Ongoing operational applications of the VIC model include the University of Washington's drought monitoring and forecasting systems and NASA's Land Data Assimilation System. This paper documents the development of VIC version 5 (VIC-5), which includes a major reconfiguration of the legacy VIC source code to support a wider range of modern hydrologic modeling applications. The VIC source code has been moved to a public GitHub repository to encourage participation by the broader user and developer communities. The reconfiguration has separated the core physics of the model from the driver source code, whereby the latter is responsible for memory allocation, preprocessing and post-processing, and input–output (I–O). VIC-5 includes four drivers that use the same core physics modules, but which allow for different methods for accessing this core to enable different model applications. Finally, VIC-5 is distributed with robust test infrastructure, components of which routinely run during development using cloud-hosted continuous integration. The work described here provides an example to the model development community for extending the life of a legacy model that is being used extensively. The development and release of VIC-5 represents a significant step forward for the VIC user community in terms of support for existing and new model applications, reproducibility, and scientific robustness.
The Variable Infiltration Capacity (VIC) model
Examples of VIC applications.
Although the motivation for the development of VIC, as documented in the
original VIC publication
Because VIC was traditionally operated as a stand-alone land surface scheme,
there were no requirements for the model code to communicate with other model
components in a coupled environment. In other words, there was no requirement
for the model to “play well with others”. Instead, the model
run-time environment focused on simplicity with the goal that VIC could run
without the need for specific machine architectures, compilers, or third-party
libraries. Model development prior to version 5 did not follow a well-defined
development track and was directed primarily by the needs of specific model
experiments. Relatively little attention was paid to improvements of the
model infrastructure, which had remained essentially unchanged since its
initial release in the early 1990s, including input–output (I–O) formats. As
a consequence, model implementation typically required extensive preprocessing and
post-processing, including reformatting and processing of model input and
output files. The few VIC applications within multi-model frameworks
Although the ability to run MHMs such as VIC in uncoupled mode has been one
of their strengths, earth system science has reached a point at which the
inability of some MHMs to be used in both coupled and uncoupled mode is a
serious shortcoming. While a few previous efforts have been made to couple
VIC to both atmospheric and fully coupled earth system models
Interest in and advocacy for the use of established software development
methods has grown in recent years in the fields of hydrology and the earth
sciences to promote reproducibility of model and analysis results
This paper documents the development of VIC version 5, hereafter referred to
as VIC-5, a new major release of the VIC model. The motivation for the
development of VIC-5 is to extend the usefulness of VIC by adding the
necessary infrastructure to allow the model to operate in a number of coupled
and uncoupled modes, while relying on the same underlying physics
implementations, and to ensure that upgrades to the physics routines are
automatically available to all model configurations. In this paper we
describe the software, infrastructure, and associated improvements in VIC-5
and provide baseline model diagnostics in terms of computational performance.
The initial VIC-5 release does not add new or improved physical process
representations compared to the last release of the VIC-4 development track
(version 4.2.d). Instead, the development of VIC-5 focused on reconfiguring
the legacy VIC source code to support a wider range of modeling applications,
to better integrate VIC with other applications, and to enhance
reproducibility and source code maintenance. Therefore, this paper does not
attempt to provide a scientific benchmarking of the VIC model. We have,
however, provided a summary table of the key improvements to the VIC model
since the original
This paper is organized as follows. Section
Although VIC was originally intended to function as a land surface component
in ESMs
While VIC's original infrastructure may have made coupling within ESMs
difficult, it also contributed to the model's wide uptake throughout the
hydrologic modeling community. Previous versions of VIC were very portable,
required no third-party libraries, were easy to run in single-point mode for
testing or comparison with point observations, and were trivial to
parallelize across many processors and machines by manually subdividing the
domain and running each sub-domain on a separate processor. It was this
simple infrastructure, combined with the inclusion of built-in convenience
tools such as the meteorological variable disaggregator based on the Mountain
Climate Simulator (MT-CLIM) algorithms
The VIC-5 release includes a complete refactor of the model source code. The
design goals of the refactor included the following:
separation of the model physical core from the driver code; multiple model drivers to support a range of modeling applications; parallel processing to facilitate efficient large domain simulations; machine-independent and self-documenting I–O formats such as NetCDF; model extensions framework to facilitate coupling of sub-model components; comprehensive test suite to guide future model use and development; source code availability and version control via an online platform to
enable community participation in model maintenance and development and to
promote transparency; and improved model documentation.
The implementation details for each of these topics are discussed in the
following sections.
The reconfigured VIC-5 source code structure. The “physical core” includes the scientific modules of VIC (e.g., routines that simulate the fluxes and states of the model) and is used by each of the four drivers. The remainder of the VIC source code structure is considered driver-level code. Each driver uses components of the shared driver to minimize code duplication at the driver level. Likewise, the shared image driver includes source code that is used by both the image and CESM drivers (e.g., MPI and NetCDF utilities). Finally, the “extensions” constitute optional and driver-specific sub-models.
A practical motivating factor in the development of VIC-5 was to enable
coupling of VIC within the Regional Arctic System Model (RASM;
The most significant change in the model reconfiguration was the separation
of the physical model core from the model drivers, which are responsible for
memory allocation, preprocessing and post-processing, and input and output (I–O). The
VIC-5 source code structure is depicted in Fig. The The The CESM driver couples VIC to the Community Earth System Model's
(CESM; The
Additionally, VIC includes a set of general “shared driver utilities” that may be used by the individual drivers. These utilities perform driver-level tasks, such as logging and allocating memory, that are shared among all drivers. Grouping these common utilities eliminated the duplication of source code among the individual drivers.
In VIC-5, we have introduced a model extensions framework to facilitate the
coupling of sub-model components. Previous versions of VIC have added
extended functionality to the model such as streamflow routing
The updated model configuration facilitates the direct coupling of new and
existing subcomponents to VIC. Many of the previously developed sub-model
components required information from neighboring grid cells or upstream
processes (e.g., reservoir operations, irrigation). Leveraging the new
functionality within the image driver, VIC is now able to provide
information on storages and states from anywhere in the model domain to these
sub-models. As of VIC version 5.1, only the streamflow routing extension,
which couples the RVIC streamflow routing model
A key concept in the design of the VIC extensions framework is to allow for modular use and development of specific extensions. Therefore, each extension is enabled via compile-time options with the requirement that the model be able to run with or without the extension turned on. When turned off, each extension provides stub or no operation functions that allow the model to run without impacting the simulation. When turned on, each extension may use or modify state and flux variables from the core VIC model.
The VIC model does not include horizontal exchange between grid cells. In the
past, this feature has allowed users to manually parallelize their VIC
applications by running VIC simulations for different grid cells on separate
cores or computers (a technique referred to as
Because VIC model grid cells do not exchange water or energy with their neighbors, each grid cell can be modeled independently. Our MPI parallelization strategy is to use MPI only to facilitate I–O operations. Thus, all I–O is performed by the master process. Inputs are read and scattered to the individual processors, while outputs are gathered and written out by the master process. The default domain decomposition uses a simple round-robin approach in which each grid cell in the model domain is sequentially distributed to another processor. For example, in the case of four MPI processes and 20 model grid cells, the first MPI process would handle grid cells 1, 5, 9, 13, and 17; the second would handle 2, 6, 10, 14, and 18 and so forth. In practice, this ensures a similar computational load for each MPI process for the most common VIC spatial configuration (a regular 2-D grid).
We have also implemented an alternative parallelization strategy using OpenMP threading that may be used for concurrent simulation of multiple grid cells within a node or process. As opposed to the full MPI parallelization, OpenMP avoids some of the overhead inherent in MPI (e.g., communication, data transfer). On some machines, the use of hyper-threading with OpenMP may result in better scaling than with MPI. Finally, the addition of OpenMP allows for hybrid OpenMP-MPI parallelism wherein OpenMP and MPI are used in concert. This advanced form of parallelism utilizes MPI for inter-node communication and OpenMP for shared-memory threading on-node.
The image and CESM drivers use Unidata's NetCDF library for
all I–O related to input parameters, meteorological forcings, and model
output. NetCDF is a software library that reads and writes self-describing
array-oriented scientific data with its metadata. It has been widely adopted
among the geo-scientific modeling community and provides a convenient
self-describing machine-independent data format. Interfaces to the NetCDF
library are available in many scripting languages including Python, R,
Matlab, and Julia. Output files from the image and CESM
drivers are formatted such that they meet the NetCDF Climate and Forecast
(CF) metadata conventions version 1.6
All drivers share a common logging module that greatly improves VIC's ability to self-document each model experiment. This logging module records the model version, input files, model settings, and performance statistics from key parts of the model source code. The verbosity of the logging module is controlled by a compile-time option. During model development, the logging module also facilitates debugging by providing full stack traces and line numbers when the model exits unexpectedly. When using MPI for parallelization, the logging module provides MPI task granularity when logging messages.
The classic driver continues to support the legacy ASCII and raw binary input and output file formats. We have also added additional metadata to the header of the ASCII file format but it has basically remained the same since VIC-4.
VIC previously included a meteorological forcing processor that made use of the MT-CLIM algorithms to estimate radiation and humidity from daily inputs of precipitation and temperature and which created sub-daily forcings from daily inputs. In VIC-5, this forcing processor has been removed from the model to facilitate a number of key enhancements that are described below.
A result of this change is that the input forcings must now have the same
time step length as the model simulation. Consequently, for offline
simulations based on widely used gridded daily observations
VIC-5 has also eliminated all hard-coded model parameters (e.g., emissivity of
snow and the temperature lapse rate) from the body of the source code and
collected physical constants into a single header file. Users may now specify
an optional “parameters” configuration file to override default model
constants that were previously hard-coded values. These changes follow a push
in the hydrologic modeling community for hydrologic models to expose constant
parameters
VIC-5 introduces a comprehensive test suite, now distributed with the model
source code. The VIC test suite was designed to serve three primary purposes:
(1) automated diagnostics and benchmarking of model performance, following
The test suite is made up of seven components.
The
Example summary figure from the VIC-5 SNOTEL science tests.
Panels
Example summary output from the VIC-5 science testing package
comparing the annual cycle of latent heat
Beginning in 2013, the VIC source code has been publicly available on GitHub
(
We have adopted the widely used “GitFlow” branching model and workflow for managing the VIC Git repository. The workflow provides guidance for managing development branches and releases. Key features of the workflow are the separation of the master branch from development, feature, support, and bug-fix branches. This workflow is described in detail as part of VIC's online documentation.
Finally, VIC has adopted the semantic versioning system
As part of the development of VIC-5, we have implemented an updated,
comprehensive documentation website for VIC (
Summary of tests and datasets.
Hardware used in VIC image driver parallel scaling performance tests.
The science, release, and performance tests described above were performed
prior to the release of VIC-5. The tests were used to evaluate the final
model version and were archived for future comparisons during the model
development process. This section, along with Table
The scientific verification of the VIC-5 release included point comparisons
of VIC simulations with 66 AmeriFlux sites
We have designed a series of release tests that may be used to benchmark the
VIC model during the development and release process. The release tests are
continental-scale domain simulations performed using typical model settings.
The specifics of the release test simulations for the VIC-5 release are
described in Table
We tested the parallel scaling performance of the image driver using
a series of model simulations on the 50 km near an equal-area pan-Arctic domain
used as the standard configuration in RASM. This model domain is shown in
Fig.
The 50 km near the equal-area Regional Arctic System Model (RASM)
domain. The model domain is comprised of 25 996 grid cells. Shading denotes
mean annual evapotranspiration from a test simulation run with model
configuration (B) as described in Sect.
Model throughput for the two model configurations described in
Sect.
The inclusion of a comprehensive science testing framework within the VIC-5
repository, as introduced in Sect.
Improving the scaling performance of VIC-5 by adding parallel processing
functionality enables VIC-5 to be used for more computationally expensive
applications, such as high-resolution modeling studies, sensitivity analyses,
and coupled earth system models (e.g., RASM) that have shorter coupling
intervals (e.g., 20 min) than the time steps that have traditionally been used
in VIC (hourly to daily). Figure
We also evaluated the scaling performance of the hybrid OpenMP-MPI
parallelization in VIC and found that these simulations do not perform as
well as the pure MPI implementation. Figure
Additional performance enhancement in the scaling of the VIC image and
CESM drivers will likely occur through the application of parallel
I–O. Collective parallel reading and writing of NetCDF files, made possible
through the NetCDF-4 and HDF5 libraries, is expected to dramatically reduce
the amount of data passed via MPI processes. For computers with
high-performance parallel disk systems, parallel I–O should allow the model to
scale well beyond the limits shown in Fig.
The VIC model continues to serve a broad
user community. The VIC users email listserve
(
Beginning in 2014, the VIC model has been licensed with the open-source GNU
General Public License version 2. The motivation behind making the model
source code completely open source was to encourage participation by the
model user and development community at large and to increase scientific
transparency in the model development and application process
The development of VIC-5 focused on refactoring the legacy source code to support a range of modern modeling applications. While the release of VIC-5 does not modify existing or add new process representations, it does modernize the supporting infrastructure in the model while preserving legacy functionality. The incorporation of state-of-the-art software engineering tools, such as GitHub and continuous integration, will facilitate the ongoing development and maintenance of the model by the broader VIC developer community.
We expect VIC-5's infrastructure improvements, combined with a suite of modern software tools, will help guide future VIC development and enable new applications of the model. For example, the enhancements related to high-performance computing will enable the application of the VIC model across larger, higher-resolution domains or for larger sensitivity experiments. Moreover, the improvements to the development process that were part of the path to VIC-5 represent a key component of the long-term sustainability of the model source code and the continued availability of the model as a tool for the modeling community.
Appendix
Since the original release of the VIC model and the original publication of
Summary of major VIC developments present in VIC-5, focusing on
improved process representations, and the model versions that were added
since the original publication of
Name: VIC.5.0.1 Persistent identifier:
License: GNU General Public License version 2 (GPL-2.0) Publisher: Zenodo Version published: 5.0.1 Date published: 1 February 2017
Name: GitHub Identifier: License: GNU General Public License version 2 (GPL-2.0) Date published: 1 February 2018
Name: ReadTheDocs Identifier: License: GNU General Public License, version 2 (GPL-2.0) Date published: 1 February 2017
JH, BN, and TB performed the majority of the source code reconfiguration. BN provided overall oversight. JH designed the experiments with help from YM and DG to carry them out. JH and BN prepared the paper with contributions from all coauthors.
The authors declare that they have no conflict of interest.
This research was supported in part by United States Department of Energy (DOE) grants DE-FG02-07ER64460 and DE-SC0006856 to the University of Washington and grant 1216037 from the National Science Foundation's Science, Engineering, and Education for Sustainability (SEES) program. Supercomputing resources were provided through the United States Department of Defense (DoD) High Performance Computing Modernization Program (HPCMP) at the Army Engineer Research and Development Center (ERDC) and the Air Force Research Laboratory (AFRL). We thank Anthony Craig for his feedback during the design and implementation of the image and CESM drivers. We also thank Wietse Franssen and Iwan Supit for their contributions to the streamflow routing extension. Edited by: Jeffrey Neal Reviewed by: Thorsten Wagener and two anonymous referees