The Variable Infiltration Capacity (VIC) Macroscale Hydrologic Model

PCIC's heavily modified local version of VIC, which adds support for glacier mass balance calculation and output.

Fixes since last release:

• Enables the use of multithreading on capable machines for regular run (OUTPUT_FORCE=FALSE) mode.
• Converts generation of meteorological forcings (OUTPUT_FORCE=TRUE) mode to cell-major, avoiding out-of-memory errors for large domains.

This document summarizes the changes in how the VIC Glacier release is invoked -- specifically changes to the global parameter file that the user needs to know about -- which has diverged somewhat from the original UW version.

Users can read the particular section pertaining to their current needs, or follow through this document from start to finish as an instructive example of how to carry out the following workflow:

1. read in forcing variables from a daily aggregated NetCDF forcing file, with standard variable names (with/without legacy type and multiplier parameters), and/or with custom names mapped to standard names

2. generate an hourly disaggregated forcing file, with/without custom output variable names

3. feed a previously generated hourly disaggregated forcing file into a VIC hydrological simulation

4. use parallelization to speed up hydrological simulation on multiprocessor machines

5. other parameters to be aware of

  Some of the global parameter file snippets included show the new parameters related to glacier mass balance accumulation, which are fairly self-explanatory.  To include additional available glacier-related variables in the NetCDF output of your hydrological simulation, add them to the Output Variables section of the global parameter file in the same way as other VIC variables.  Documentation on the specifics of these output variables will be made available soon.

1. Reading in Standard and Custom Name-mapped Forcing File Variables

Users can now specify the variable names VIC should expect to see in a provided NetCDF forcing file (in case these are different from the 'standard' VIC input variable names).  This applies to the read-in of both standard daily forcings and hourly disaggregated forcings (generated by VIC).  This accomplished by using the following format for these particular parameters in the in the Forcing Files and Parameters section:

########################################################################
# Forcing Files and Parameters
########################################################################
#    ...
#    FORCING1    /path/to/forcing/file.nc
#    FORCE_FORMAT     NETCDF
#    FORCE_ENDIAN     LITTLE    
#    N_TYPES     <number of forcing variables>
#

To provide legacy VIC forcings with integer types and scaling multipliers, and no input forcing variable name mapping:

#    FORCE_TYPE      <standard VIC varname>     <type>     <multiplier>
#e.g. FORCE_TYPE    PREC    UNSIGNED    40

Or, to provide legacy VIC forcings as above, along with input forcing variable name mapping:

#    FORCE_TYPE      <standard VIC varname>     <type>     <multiplier>     <varname in forcing file>
#e.g. FORCE_TYPE    TMIN    SIGNED    100    tasmin

Or, to provide new VIC forcings (of float type by default), and no input forcing variable name mapping (this is likely the default case):

#    FORCE_TYPE      <standard VIC varname>
#e.g. FORCE_TYPE    TMAX

Or, to provide new VIC forcings (of float type by default) with input forcing variable name mapping:

#    FORCE_TYPE      <standard VIC varname>     <varname in forcing file>
#e.g. FORCE_TYPE      AIR_TEMP     ta

  The default mappings within VIC of <standard VIC varname> to expected <varname in forcing file> variable names are as follows in Table 1.1:

• Default values marked with an asterisk (*) are the standard set of daily forcings provided in forcings_v2_1950-2006.nc. 

2. Generating Disaggregated Forcings (OUTPUT_FORCE=TRUE)

In order to run VIC in meteorological disaggregation mode, for instance to generate your own hourly forcing file, make the following changes to the global parameters file: 

Move the OUTPUT_FORCE line to the bottom of the Simulation Parameters section and set it to TRUE  (Note: old global files will have OUTPUT_FORCE located in the Output Files and Parameters section; cut and paste it from there to the end of Simulation Parameters, as the order that VIC reads global parameters now matters).

Set TIME_STEP to the simulation time step length (in hours), and set OUT_STEP to generate X-hourly output forcings (i.e. generate forcing data at X-hour steps, where X must be evenly divisible by 24, i.e. 1/3/4/6/8/12 hour output OUT_STEP values are all valid).

Take advantage of time-chunked writes to speed up execution by reducing the number of write-to-disk operations in meteorological disaggregation mode. VIC does this by buffering the output data for DISAGG_WRITE_CHUNK_SIZE time records between writes to disk. The optimal value for this parameter will depend on the available RAM of the host machine, but values up to 10,000 have been successfully tested on desktop machines. VIC runs in a 'cell-major' looping style when in meteorological disaggregation mode, meaning that it loads input forcings and generates & writes out the output forcings for one cell at a time (freeing memory allocated to input forcings at the end of processing each cell). In other words, the maximum value for DISAGG_WRITE_CHUNK_SIZE will have to be balanced with the RAM required by the total number of time records' worth of input forcings loaded per cell for the particular run, determined by the range specified by the parameters START_YEAR & END_YEAR and the input forcings time step size FORCE_DT. Note, however, that the domain size (number of grid cells) has no effect on the total RAM requirements when running VIC in meteorological disaggregation mode, as cells are processed one at a time.

For example, to run at 1-hour time steps (from an hourly input forcings file) and output 3-hourly forcings, writing to disk on every 10,000th time step:

########################################################################
# Simulation Parameters
########################################################################
TIME_STEP       1
SNOW_STEP       1
STARTYEAR       1960     # year to begin generating forcings for (this will be the start year in the output file)
END_YEAR        1995     # last year to generate forcings for 
...
OUTPUT_FORCE    TRUE     # indicates to VIC that it should only generate forcing data, then exit
DISAGG_WRITE_CHUNK_SIZE	10000	# write 10,000 time records to disk at a time

########################################################################
# Output Files and Parameters
########################################################################
RESULT_DIR      /path/to/output/forcing/file
NETCDF_OUTPUT_FILENAME  output_forcing_filename.nc
OUT_STEP        3

In the Output Files and Parameters section, specify where you want the disaggregated forcings output file to be written, and optionally, the NETCDF_OUTPUT_FILENAME to give it in that location (if this parameter is not provided, the default filename will be results.nc).  Specify the output time step size, OUT_STEP, as 1 for hourly, or 3 if you want output in 3-hour intervals, etc. (if this is left as 0, VIC will default to using the value given for the TIME_STEP parameter).

For example:

########################################################################
# Output Files and Parameters
########################################################################
RESULT_DIR /path/to/my/generated/disaggregated/forcing/file
NETCDF_OUTPUT_FILENAME hourly_disagg_forcings.nc
OUT_STEP 1

The standard set of output variables in disaggregated forcings output mode are PREC, AIR_TEMP, SHORTWAVE, LONGWAVE, DENSITY, PRESSURE, VP, and WIND. This is equivalent to providing the following in the global file:

########################################################################
# Output Files and Parameters
########################################################################
OUTVAR     OUT_PREC
OUTVAR     OUT_AIR_TEMP
OUTVAR     OUT_SHORTWAVE
OUTVAR     OUT_LONGWAVE
OUTVAR     OUT_DENSITY
OUTVAR     OUT_PRESSURE
OUTVAR     OUT_VP
OUTVAR     OUT_WIND

(i.e. If no OUTVAR entries are provided in the global file, these are the variables that will be generated)

Optionally, provide mapping of output forcing variable names.  If no mapped name is provided, the <standard VIC varname> format will be used for the NetCDF variable name (e.g. OUT_WIND in the following example will result in the NetCDF variable name WIND in the output disaggregated forcings file).  Note that N_OUTFILES, OUTFILE, and the <prefix> value given are all ignored if the output file format is set to NetCDF, but <nvars> still must be set correctly to the number of variables to be written (i.e. the number of OUTVAR lines to follow).  These mapped forcings output variable names will be those that VIC will have to read in when you use the hourly forcings NetCDF file later as input to your simulation.  If you choose the default mapping given in Table 1.1, VIC will recognize these as valid forcing inputs.  If not, you will have to set the input forcing mappings accordingly, as shown in Section 3.2 (in this example, my_shortwave_varname would not be recognized by default as a valid forcing variable).

For example:

########################################################################
# Output Variables
#
# Format:
#
# N_OUTFILES <n_outfiles>
# OUTFILE <prefix> <nvars>
# OUTVAR <varname> [<output_varname>]
# OUTVAR <varname> [<output_varname>]
# OUTVAR <varname> [<output_varname>]
#########################################################################

For example:

# OUTFILE    cell    8 
# OUTVAR    OUT_PREC    pr
# OUTVAR    OUT_AIR_TEMP    ta
# OUTVAR    OUT_SHORTWAVE    my_shortwave_varname
# OUTVAR    OUT_LONGWAVE    rlds
# OUTVAR    OUT_DENSITY    DENSITY  
# OUTVAR    OUT_PRESSURE    ps
# OUTVAR    OUT_VP    VP
# OUTVAR    OUT_WIND  # providing no mapping here will result in the standard VIC name "WIND" being used as the variable name in the output NetCDF. Note that the default forcing variable name VIC expects to read in is "wind". More on how to deal with this is given in Section 3.2.

3. Feeding Hourly Disaggregated Forcings into VIC

Time-major NetCDF forcing files generated by VIC in meteorological disaggregator mode (OUTPUT_FORCE=TRUE) can be used as inputs to VIC in normal hydrological simulation mode (OUTPUT_FORCE=FALSE).

To support reading of disaggregated forcings into VIC, make modifications to the global parameter file as detailed in the following subsections:

In the Simulation Parameters section, declare the TIME_STEP (hourly forcings means hourly simulation time step, thus TIME_STEP=1) and start/end years of the simulation to be run, and provide the OUTPUT_FORCE (set to FALSE) parameter at the end of this section (Note: old global files will have OUTPUT_FORCE in the Output Files and Parameters section; cut and paste it from there to the end of Simulation Parameters, as the order that VIC reads global parameters now matters).

For example:

########################################################################
# Simulation Parameters
########################################################################
TIME_STEP       1
SNOW_STEP       1
STARTYEAR       1965     # simulation start year, the year to begin reading forcings from. 
ENDYEAR        1995     # year to stop simulation. 
...
GLACIER_ID      22
GLACIER_ACCUM_START_YEAR        1970
GLACIER_ACCUM_START_MONTH       10
GLACIER_ACCUM_START_DAY         1
GLACIER_ACCUM_INTERVAL          1
OUTPUT_FORCE    FALSE    # run VIC in regular hydrological simulation mode

In the Forcing Files and Parameters section, provide the path to the hourly disaggregated forcings NetCDF input file that will be loaded (FORCING1), specify the number of forcing variables (N_TYPES) and the particular ones that will be loaded (FORCE_TYPE).  VIC only outputs forcing variables in floating point, so no multiplier or scale factor is included on the FORCE_TYPE lines.  Specify the time step of the forcings (FORCE_DT=1 for hourly forcings), as well as the first year of the time series data existing within the disaggregated forcing file (FORCEYEAR), so that VIC knows how far to index into the file to get to the start date of your simulation.

For example:

########################################################################
# Forcing Files and Parameters
########################################################################
...
FORCING1        /path/to/my/generated/disaggregated/forcing/file/hourly_disagg_forcings.nc
N_TYPES         8
FORCE_TYPE      PREC   # VIC will try to load "pr" forcing variable, as per Table 1.1
FORCE_TYPE      AIR_TEMP  # VIC will try to load "tas" forcing variable, as per Table 1.1
FORCE_TYPE      SHORTWAVE    my_shortwave_varname  # for this example, in Section 2.4, we had mapped the disaggregated SHORTWAVE forcing variable to be called my_shortwave_varname in the NetCDF file
FORCE_TYPE      LONGWAVE  # VIC will try to load "rlds" forcing variable, as per Table 1.1
FORCE_TYPE      DENSITY   # VIC will try to load "DENSITY" forcing variable, as per Table 1.1
FORCE_TYPE      PRESSURE  # VIC will try to load "ps" forcing variable, as per Table 1.1
FORCE_TYPE      VP  # VIC will try to load "VP" forcing variable, as per Table 1.1
FORCE_TYPE      WIND    WIND  # for this example, in Section 2.4, we had mapped the disaggregated WIND forcing variable to be called "WIND" in the NetCDF file, so this is what VIC will try to load
FORCE_DT        1
FORCEYEAR       1960      # start year of the time series data in the supplied disaggregated forcings file (which can be at any point in time before, or exactly at, the start date of your simulation)

In the Output Files and Parameters section, declare the time step of the model run output (OUT_STEP).  You probably want daily aggregated outputs, i.e. OUT_STEP=24 (which also keeps file sizes down):

########################################################################
# Output Files and Parameters
########################################################################
# RESULT_DIR /path/to/my/vic/run/results
# NETCDF_OUTPUT_FILENAME my_simulation_results.nc    # optional, otherwise VIC will name it results.nc
# OUT_STEP 24
# ...

4. Using parallelization to speed up hydrological simulation on multiprocessor machines

VIC uses the OpenMP library to take advantage of multiprocessor machine architectures to speed up hydrological simulation (OUTPUT_FORCE=FALSE). To use this functionality, add the PARALLEL_THREADS parameter to the global file (it makes sense to put it in the "Simulation Parameter" section), followed by the number of processors available for VIC to use, e.g.

PARALLEL_THREADS  2

would allow the use of 2 CPUs, if available. Note that VIC will not know whether these are real CPUs or just virtual cores from CPU hyperthreading, so it is up to you to make sure you set this parameter appropriately to the number of actual CPUs.

5. Other parameters to be aware of

The following parameters need to be included in your global file going forward:

####TEMP_TH_TYPE

Determines the precipitation partitioning algorithm to use. The options are:

1. The original VIC v4.1.2 linear partitioning between MAX_SNOW_TEMP and MIN_RAIN_TEMP.

   TEMP_TH_TYPE VIC_412

2. S-shaped curve with two parameters, the temperature at which 50% of precipitation occurs as snow (TT) and the temperature range over which mixed precipitation occurs (TR). This algorithm follows Kienzle (2008).

   TEMP_TH_TYPE KIENZLE

####JULY_TAVG_SUPPLIED (TRUE/FALSE)

If TRUE and COMPUTE_TREELINE is also true, then average July air temperature will be read from soil file and used in calculating treeline.