VIC Model Output Formatting
How to control the contents of VIC output files
These instructions apply to VIC model versions 4.0.6 and later. In earlier versions of VIC, the user has little control over the contents of VIC output files without changing the VIC source code.
Contents
- Specifying Output Files and Variables
- Specifying Units
- Specifying Output Time Step
- Optional Output File Headers
Specifying Output Files and Variables
In earlier versions of VIC, the set of output files and their contents were hard-coded. A few settings in user_def.h (OPTIMIZE and LDAS_OUTPUT) allowed the user to change the contents of the output files, but this has not been enough to accomodate the various needs of users. Users inevitably have had to modify write_data.c to produce the type of output they want, and when VIC is updated, they must merge their changes into the new version of the code.
VIC 4.0.6 (and later) now allows the user to specify exactly which output files to create and which variables to store in each file. This way, users can save space by only writing those variables that are useful, and will be less likely to need to maintain a private version of the code to do this.
Main points:
- Output file names and contents can be specified in the global param file (see below).
- If you do not specify file names and contents in the global param file, VIC will produce the same set of output files that it has produced in earlier versions, namely "fluxes" and "snow" files, plus "fdepth" files if FROZEN_SOIL is TRUE and "snowband" files if PRT_SNOW_BAND is TRUE. These files will have the same contents and format as in earlier versions.
- The OPTIMIZE and LDAS_OUTPUT options have been removed. These output configurations can be selected with the proper set of instructions in the global param file. (see the output.*.template files included in this distribution for more information.)
- If you do specify the file names and contents in the global param file, PRT_SNOW_BAND will have no effect.
To specify file names and contents in the global param file, one should use the following format:
(typical global param file contents here...) # Output File Contents N_OUTFILES n_outfiles OUTFILE prefix nvars OUTVAR varname [format type multiplier] OUTVAR varname [format type multiplier] OUTVAR varname [format type multiplier] OUTFILE prefix
where
n_outfiles = number of output files prefix = name of the output file, NOT including latitude and longitude nvars = number of variables in the output file varname = name of the variable (this must be one of the output variable names listed in vicNl_def.h.) format, type, and multiplier are optional. For a given variable, you can specify either NONE of these, or ALL of these. If these are omitted, the default values will be used. format = (for ascii output files) fprintf format string, e.g. %.4f = floating point with 4 decimal places %.7e = scientific notation w/ 7 decimal places * = use the default format for this variable type = (for binary output files) data type code. Must be one of: OUT_TYPE_DOUBLE = double-precision floating point OUT_TYPE_FLOAT = single-precision floating point OUT_TYPE_INT = integer OUT_TYPE_USINT = unsigned short integer OUT_TYPE_SINT = short integer OUT_TYPE_CHAR = char * = use the default type multiplier = (for binary output files) factor to multiply the data by before writing, to increase precision. * = use the default multiplier for this variable
Here's an example. To specify 2 output files, named "wbal" and "ebal", and containing water balance and energy balance terms, respectively, you could do something like this:
N_OUTFILES 2 OUTFILE wbal 6 OUTVAR OUT_PREC OUTVAR OUT_EVAP OUTVAR OUT_RUNOFF OUTVAR OUT_BASEFLOW OUTVAR OUT_SWE OUTVAR OUT_SOIL_MOIST OUTFILE ebal 7 OUTVAR OUT_NET_SHORT OUTVAR OUT_NET_LONG OUTVAR OUT_LATENT OUTVAR OUT_SENSIBLE OUTVAR OUT_GRND_FLUX OUTVAR OUT_SNOW_FLUX OUTVAR OUT_ALBEDO
Since no format, type, or multiplier were specified for any variables, VIC will use the default format, type, and multiplier for the variables.
If you wanted scientific notation with 10 significant digits for ALBEDO, you could do the following:
OUTVAR OUT_ALBEDO %.9e * *
Note that even if you only want to specify the format, you must supply a value in the type and multiplier columns as well. This can be "*" to indicate the default value. Similarly, if you only want to specify the type (e.g. as a double), you would need to do something like:
OUTVAR OUT_ALBEDO * OUT_TYPE_DOUBLE *
Date variables:
For typical output files, the date is always written at the beginning of each record. This will consist of the following columns:
year month day hour
For daily output timestep, "hour" is not written.
If BINARY_OUTPUT is TRUE, these will all be written as type int (OUT_TYPE_INT).
If OUTPUT_FORCE is TRUE, the date will NOT be written.
Multiple-valued variables:
Since variables like SOIL_MOIST have 1 value per soil layer, these variables will be written to multiple columns in the output file, one column per soil layer. Other multiple-valued variables are treated similarly.
Snow band output:
To specify writing the values of variables in each snow band, append "_BAND" to the variable name (this only works for some variables - see the list in vicNl_def.h). If you specify these variables, the value of the variable in each band will be written, one band per column. For example, for a cell having 2 snow bands:
OUTVAR OUT_SWE_BAND OUTVAR OUT_ALBEDO_BAND
will result in an output file containing:
year month day (hour) swe[0] swe[1] albedo[0] albedo[1]
Specifying Units
The user now has some control over the units of the input and output variables. The standard VIC units for moisture fluxes are total mm over the output time interval, and degrees C for temperatures. However, other land surface schemes and circulation or climate models tend to use mm/s for moisture fluxes and degrees K for temperatures.
Now there are options in the global parameter file that allow you to specify whether to use traditional VIC units or the mm/s and K convention for input or output variables. The option names are "ALMA_INPUT" and "ALMA_OUTPUT", named after the ALMA convention used in the PILPS-2e experiment.
ALMA INPUT:
VIC now accepts the following new ALMA-compliant input forcings in addition to the forcings that it already accepts:
SNOWF snowfall rate (kg/m^2s) RAINF rainfall rate (kg/m^2s) CRAINF convective rainfall rate (kg/m^2s) LSRAINF large scale rainfall rate (kg/m^2s) QAIR specific humidity (kg/kg) WIND_E zonal wind speed (m/s) WIND_N meridional wind speed (m/s) TAIR air temperature per time step (K) PSURF atmospheric pressure (Pa)
When giving VIC ALMA-compliant input files, you must be sure to use the names given above in the forcing section of your global parameter file.
Instead of the existing PREC (precipitation per timestep in mm), you can now specify SNOWF and RAINF (snowfall and rainfall rates, both in mm/s). VIC will simply add these two quantities together, multiply by the forcing interval, and treat their sum the same way it treats PREC.
An alternative to supplying RAINF is to supply CRAINF (convective rainfall rate, mm/s) and LSRAINF (large-scale rainfall rate, mm/s). VIC will add these two quantities together to get RAINF.
Instead of the existing WIND, alternatively you can specify WIND_E and WIND_N (zonal and meridional wind speed, m/s). VIC will simply compute WIND = sqrt(WIND_E**2+WIND_N**2).
TAIR has units of K, while the existing AIR_TEMP is in C. Similarly, PSURF is in Pa, while PRESSURE is in kPa. VIC will convert these to AIR_TEMP and PRESSURE after reading them in.
More information is available on ALMA forcing variables at: http://www.lmd.jussieu.fr/~polcher/ALMA/convention_input_3.html
ALMA OUTPUT:
If the user sets ALMA_OUTPUT=TRUE in the global parameter file, then VIC will convert its output variables to ALMA-compliant forms. The majority of the changes are changes of units. Moisture fluxes are changed from VIC's standard (mm accumulated over the time step) to the average flux rate (mm/s). Temperatures are converted from C to K.
More information on ALMA output variables is available at: http://www.lmd.jussieu.fr/~polcher/ALMA/convention_output_3.html.
In addition, several more variables have been added to the list of available output variables. See vicNl_def.h for the complete list of available output variables.
Specifying Output Time Step
VIC can now aggregate the output variables to a user-defined output interval, via the OUT_STEP setting in the global parameter file. Currently, the largest output interval allowed is 24 hours, so this option is only useful for simulations running at sub-daily time steps.
Optional Output File Headers
Now VIC provides an option to insert descriptive headers into its output files, via the PRT_HEADER option in the global parameter file. If this is set to TRUE, VIC will insert a short header into its output files, describing the time step, start date/time, variables and units included in the file.
For ascii files, the output header has the following format:
# NRECS: (nrecs) # DT: (dt) # STARTDATE: yyyy-mm-dd hh:00:00 # ALMA_OUTPUT: (0 or 1) # NVARS: (Nvars) # VARNAME VARNAME VARNAME ...
where
nrecs = Number of records in the file dt = Time step length in hours start date = Date and time of first record of file ALMA_OUTPUT = Indicates units of the variables; 0 = standard VIC units; 1 = ALMA units Nvars = Number of variables in the file, including date fields
For binary files, the output header has the following format:
// Data Stored As Comment // // Identifier (unsigned short)*4 0xFFFF, repeated 4 times // Nbytes (unsigned short)*1 Number of bytes in the header, // INCLUDING THE IDENTIFIER // // Part 1: Global Attributes // Nbytes1 (unsigned short)*1 Number of bytes in part 1 // nrecs (int)*1 Number of records in the file // dt (int)*1 Time step length in hours // startyear (int)*1 Year of first record // startmonth (int)*1 Month of first record // startday (int)*1 Day of first record // starthour (int)*1 Hour of first record // ALMA_OUTPUT (char)*1 0 = standard VIC units; 1 = ALMA units // Nvars (char)*1 Number of variables in the file, // including date fields // // Part 2: Variables // Nbytes2 (unsigned short)*1 Number of bytes in part 2 // For each variable, the following fields: { len varname type mult } // len (char)*1 Number of characters in varname // varname (char)*len Variable name // type (char)*1 Code identifying variable type // mult (float)*1 Multiplier for variable
To accomodate input forcing files that might have been produced via VIC's OUTPUT_FORCE option, and therefore could contain a header, read_atmos_data.c has been modified to detect and skip headers that follow the formats outlined above.
VIC Administrator Last modified: Thu Aug 20 13:56:14 PDT 2009