forked from pacificclimate/VIC
-
Notifications
You must be signed in to change notification settings - Fork 0
/
USAGE_NOTES.txt
214 lines (166 loc) · 12.7 KB
/
USAGE_NOTES.txt
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
VIC Glacier - Usage Notes
----------------------------------------------------------------------------------
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
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:
Table 1.1: Default Forcing Variable Mappings
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.
2. Generating Disaggregated Forcings (OUTPUT_FORCE=TRUE)
----------------------------------------------------------------------------------
In order to run VIC in meteorological disaggregation mode, i.e. to generate your own hourly forcing file, make the following changes to the global parameters file:
2.1
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).
2.2
Change TIME_STEP to 1 (hourly), rather than 24, to indicate that the simulation will be run at hourly time steps.
For example:
########################################################################
# 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
...
GLACIER_ID 22
GLACIER_ACCUM_START_YEAR 1970
GLACIER_ACCUM_START_MONTH 10
GLACIER_ACCUM_START_DAY 1
GLACIER_ACCUM_INTERVAL 1
OUTPUT_FORCE TRUE # indicates to VIC that it should only generate hourly forcing data, then exit (no hydrological simulation is executed)
2.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
2.4
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), being by default at hourly time steps, can be used as inputs to VIC in normal simulation run mode (OUTPUT_FORCE=FALSE).
To support reading of hourly disaggregated forcings into VIC, make the following modifications to the global parameter file:
3.1
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
3.2
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)
3.3
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
# ...