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:
-
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
-
generate an hourly disaggregated forcing file, with/without custom output variable names
-
feed a previously generated hourly disaggregated forcing file into a VIC hydrological simulation
-
use parallelization to speed up hydrological simulation on multiprocessor machines
-
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.
- 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:
| standard VIC varname | expected input forcing variable name | variable description | |
|---|---|---|---|
| AIR_TEMP | tas | air temperature | |
| ALBEDO | ALBEDO | surface albedo | |
| CHANNEL_IN | CHANNEL_IN | incoming channel flow | |
| CAT_M | CAT_M | atmospheric CO2 mixing ratio | |
| CRAINF | CRAINF | convective rainfall | |
| CSNOWF | CSNOWF | convective snowfall | |
| DENSITY | DENSITY | atmospheric density | |
| FDIR | FDIR | fraction of incoming shortwave that is direct | |
| LONGWAVE | rlds | incoming longwave radiation | |
| LSRAINF | LSRAINF | large-scale rainfall | |
| LSSNOWF | LSSNOWF | large-scale snowfall | |
| PREC | pr | total precipitation | * |
| PRESSURE | ps | atmospheric pressure | |
| QAIR | huss | specific humidity | |
| RAINF | RAINF | rainfall | |
| REL_HUMID | rhs | relative humidity | |
| SHORTWAVE | rsds | incoming shortwave radiation | |
| SNOWF | prs | snowfall | |
| TMAX | tasmax | maximum daily air temperature | * |
| TMIN | tasmin | minimum daily air temperature | * |
| TSKC | clt | cloud cover | |
| VEGCOVER | VEGCOVER | partial vegetation cover fraction | |
| VP | VP | atmospheric vapor pressures | |
| WIND | wind | wind speed | * |
| WIND_E | uas | east component of wind speed | |
| WIND_N | vas | north component of wind speed |
- Default values marked with an asterisk (*) are the standard set of daily forcings provided in forcings_v2_1950-2006.nc.
- 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.
- 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
# ...
- 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.
- 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:
-
The original VIC v4.1.2 linear partitioning between MAX_SNOW_TEMP and MIN_RAIN_TEMP.
TEMP_TH_TYPE VIC_412
-
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.