Release of VIC 4.1.1
***** Description of changes from VIC 4.1.0 beta r5 to VIC 4.1.1 *****
New Features:
Modified reporting of aerodynamic resistance in output files.
Files Affected:
full_energy.c
func_canopy_energy_bal.c
func_surf_energy_bal.c
output_list_utils.c
put_data.c
surface_fluxes.c
vicNl_def.h
wetland_energy.c
Description:
Replaced the existing variables aero_resist_used and Ra_used with
arrays of two elements each; [0] corresponds to surface values
(bare soil or non-overstory veg; with snow or snow-free) and [1]
corresponds to overstory or non-overstory veg. For non-overstory
veg, elements [0] and [1] are the same.
Added the following output variables to store the average aerodynamic
conductance and resistance of the grid cell corresponding to elements
[0] and [1], respectively: OUT_AERO_COND1, OUT_AERO_COND2,
OUT_AERO_RESIST1, and OUT_AERO_RESIST2. Changed the computation
of OUT_AERO_COND and OUT_AERO_RESIST to be "scene" values, i.e.
veg tiles containing overstory contribute their overstory (element
[1]) values, and non-overstory veg tiles contribute their surface
(element [0]) values. Earlier versions of VIC simply output the
values of AERO_COND and AERO_RESIST computed latest during the time
step (whether from surface or overstory).
Added AERO_RESIST_CANSNOW option.
Files Affected:
display_current_settings.c
func_canopy_energy_bal.c
get_global_param.c
global.param.sample
initialize_global.c
vicNl_def.h
Description:
This option allows the user to control how aerodynamic resistances
in the overstory are corrected for the presence of snow in the canopy.
Possible values are:
AR_406: Multiply aerodynamic resistance by 10 for latent heat
calculation but NOT for sensible heat, and do NOT apply
stability correction, as in VIC 4.0.6 and earlier.
Additionally, use surface aero_resist for ET when no
no snow in canopy.
AR_406_LS: Multiply aerodynamic resistance by 10 for both latent
and sensible calculations, but do NOT apply stability
correction. Additionally, use surface aero_resist for
ET when no no snow in canopy.
AR_406_FULL: Multiply aerodynamic resistance by 10 for both latent
and sensible calculations, but do NOT apply stability
correction. Always use canopy aero_resist for ET.
AR_410: Apply stability correction but do not multiply by 10, as in
VIC 4.1.0. Always use canopy aero_resist for ET.
AR_COMBO: Apply stability correction and multiply resulting resistance
by 10. Always use canopy aero_resist for ET.
VIC 4.1.0 differed from VIC 4.0.6 (and earlier) in the computation
of aerodynamic resistances in snow-filled canopy. This new option
allows backwards-compatibility with both of these model versions, as
well as the new "AR_406_LS", "406_FULL" and "AR_COMBO" options, for
comparison. The default is set to AR_410.
Reinstated the COMPUTE_TREELINE option, with option to supply the average July
air temperature.
Files Affected:
compute_treeline.c
display_current_settings.c
get_global_param.c
global.param.sample
initialize_atmos.c
initialize_global.c
read_snowband.c
read_soilparam_arc.c
read_soilparam.c
read_vegparam.c
user_def.h
vicNl.c
vicNl.h
vicNl_def.h
Description:
COMPUTE_TREELINE:
This option revives the treeline elevation computation that is a
current feature of VIC 4.0.x. If set to TRUE this flag will
force the VIC model to compute the elevation of the tree line,
based on elevation at which the average annual July air temperature
is at or below 10C. All snowbands above this evelation are then
assumed to be above the treeline, and vegetation types with
overstory are removed from the snow band average variables. If no
non-overstory vegetation types exist in an above-treeline band,
the band will be treated as if it consists of a default vegetation
type, specified by the user.
To use this option, insert the following line into the global
parameter file:
COMPUTE_TREELINE n
where n is the id number of the desired default vegetation type to use
when no non-overstory vegetation types exist in the band. To specify
bare soil, set n to a negative number.
To deactivate treeline calculation, change the line in the global
parameter file to
COMPUTE_TREELINE FALSE
or remove the line from the global control file.
WARNING #1: Since the model does not store default root zone
distributions, the default vegetation type will use the
values from the last defined vegetation type for the current
grid cell (i.e. veg type N-1, prior to the addition of the
new vegetation type).
WARNING #2: If you are using GLOBAL_LAI, than the LAI and
dew storage terms for the default vegetation type will be set
to the values used by the last occurrence of the default
vegetation type.
JULY_TAVG_SUPPLIED:
The default behavior of VIC is to compute the average July temperature
from the meteorological input forcings, over the time span of the
simulation. One drawback to this behavior is that, for short
simulations over different periods of time, the average July
temperature can vary enough to change which elevation bands are
considered to be above the treeline.
Therefore, if desired, the user can specify the average July
temperature for each grid cell by taking the following 2 steps:
1. Add each grid cell's average July air temperature to the soil
parameter file, as the final field on each line.
2. Set JULY_AVGT_SUPPLIED = TRUE in the global parameter file
The JULY_AVG_SUPPLIED option is ignored if COMPUTE_TREELINE is FALSE.
Added OUT_VPD output variable.
Files Affected:
output_list_utils.c
put_data.c
vicNl_def.h
write_forcing_file.c
Description:
Added the output variable OUT_VPD to track vapor pressure deficit.
Added OUT_ASAT output variable.
Files Affected:
full_energy.c
output_list_utils.c
put_data.c
runoff.c
surface_fluxes.c
vicNl_def.h
vicNl.h
wetland_energy.c
Description:
Added the output variable OUT_ASAT to track saturated area.
New MIN_LIQ option, with fixes to min_liq formulation.
Files Affected:
arno_evap.c
display_current_settings.c
frozen_soil.c
get_global_param.c
global.param.sample
initialize_global.c
initialize_model_state.c
initialize_soil.c
lakes.eb.c
runoff.c
soil_conduction.c
vicNl_def.h
vicNl.h
Description:
Made use of min_liq (instead of residual moisture) optional, via
options.MIN_LIQ. If MIN_LIQ is FALSE (or omitted) in global
parameter file, all equations that depend on liquid soil moisture
use residual moisture as their absolute minimum liquid water
content. If MIN_LIQ is TRUE, all of these equations use min_liq
as their absolute minimum liquid water content. Min_liq is
computed in soil_conduction.c as residual moisture multiplied
by the max_unfrozen_water content at the current temperature.
Made min_liq formulation more consistent across the model code.
Added min_liq to the layer_struct so that this temperature-dependent
quantity can be computed once per time step and communicated to all
functions that look at soil moisture. TJB
New PLAPSE option, which lapses air pressure (and density) by grid cell average elevation.
Files Affected:
display_current_settings.c
global.param.sample
initialize_atmos.c
initialize_global.c
vicNl_def.h
Description:
Previously, when air pressure was not supplied in the input forcings,
VIC would set it equal to a constant 95.5 kPa. Now, if options.PLAPSE
is TRUE, and if air pressure is not supplied, VIC computes it by
lapsing sea level pressure by grid cell average elevation. Air
density is handled the same way. TJB
New GRND_FLUX_TYPE option, with fixes to deltaH and fusion equations.
Files Affected:
display_current_settings.c
func_surf_energy_bal.c
get_global_param.c
global.param.sample
initialize_global.c
surface_fluxes.c
vicNl_def.h
Description:
Corrected deltaH and fusion terms of surface energy balance, by taking
surf_atten into account, as in Liang et al 1999. Added GRND_FLUX_TYPE
option, to allow backwards compatibility with versions 4.0.6 and
4.1.0.
Possible values are:
GF_406: use (flawed) formulas for ground flux, deltaH, and fusion
from VIC 4.0.6 and earlier
GF_410: use formulas from VIC 4.1.0 (ground flux is correct,
but deltaH and fusion ignore surf_atten)
GF_FULL: use correct ground flux formula from VIC 4.1.0 and
also take surf_atten into account in deltaH and fusion
GF_FULL is the default value.
Added validation of Campbell's expt and bubble pressure.
Files Affected:
read_soilparam.c
Description:
Previously, VIC did not check to see if "nodata" values such as -9999
were supplied in the soil parameter file for the Campbell's expt and
bubble pressure parameters. These values would produce "nan" in
computations of soil hydraulic conductivity and soil ice content. This
is especially insidious in the case of bubble pressure, as it is not
needed for the water balance mode, and therefore users often set it to
"nodata" values for water balance mode runs. Subsequently using such a
soil parameter file for a full-energy balance or frozen soil simulation
would cause the model to crash without the cause being clear. Now, the
validation in read_soilparam() prevents this case.
Note: read_soilparam_arc() computes these quantities internally and
already validates their values.
Added TFALLBACK option, to continue with previous temperature when energy
balance iteration fails to converge.
Files Affected:
calc_atmos_energy_bal.c
calc_surf_energy_bal.c
dist_prec.c
display_current_settings.c
frozen_soil.c
func_surf_energy_bal.c
get_global_param.c
global.param.sample
ice_melt.c
initialize_global.c
initialize_lake.c
initialize_model_state.c
lakes.eb.c
output_list_utils.c
put_data.c
root_brent.c
snow_intercept.c
snow_melt.c
solve_snow.c
surface_fluxes.c
vicNl_def.h
vicNl.h
Description:
Added options.TFALLBACK, which can take the following values:
TRUE: If energy balance solution fails to converge, use previous
T value and continue
FALSE: If energy balance solution fails to converge, report an
error
Default = TRUE.
Currently, the following temperature variables are affected by the
TFALLBACK option:
snow.surf_temp : snow pack surface temperature
energy.T[] : soil T profile nodes
energy.Tsurf : surface temperature
energy.Tcanopy : temperature of canopy air
energy.Tfoliage : temperature of canopy snow
For each grid cell, for each of the above variables, VIC will count
the number of instances when the previous step's T was used. These
totals will be reported at the end of the grid cell's simulation.
In addition, VIC tracks occurrences of T fallbacks through time via
"flag" variables. For each T variable, there is a corresponding T
fallback flag, which is set to 1 if, in a given time step, the
previous step's T was used in that time step, and 0 otherwise. This
holds for each veg tile / elevation band combination in the grid cell.
These time series of occurrences of T fallbacks can be reported in
output files via the following 4 new output variables:
OUT_SOILT_FLAG = array of flags, one for each soil T node
OUT_SURFT_FLAG = flag for Tsurf
OUT_SNOWT_FLAG = flag for snow.surf_temp
OUT_TCAN_FLAG = flag for Tcanopy
OUT_TFOL_FLAG = flag for Tfoliage
Each of these contain the AVERAGE over the entire grid cell and over
the output time interval (if aggregating temporally) of the flag
values. Thus, these are NOT integers but fractions ranging from 0 to
1.
Additionally modified root_brent to continue attempting to bracket
root if one bound encounters undefined values/ERROR code from target
function.
Added computation of 6 types of potential evaporation.
Files Affected:
arno_evap.c
CalcAerodynamic.c
canopy_evap.c
compute_pot_evap.c (new)
full_energy.c
global.h
initialize_lake.c
initialize_model_state.c
lakes.eb.c
Makefile
output_list_utils.c
penman.c
put_data.c
read_soilparam_arc.c
read_soilparam.c
read_veglib.c
read_vegparam.c
surface_fluxes.c
vicNl.c
vicNl_def.h
vicNl.h
wetland_energy.c
Description:
Added computation of potential evaporation for 6 different reference
land cover types, along with new output variables for reporting them:
OUT_PET_SATSOIL = pot evap from saturated soil
OUT_PET_H2OSURF = pot evap from open water surface
OUT_PET_SHORT = pot evap from short reference crop (clipped grass)
OUT_PET_TALL = pot evap from tall reference crop (alfalfa)
OUT_PET_NATVEG = pot evap from current vegetation with canopy
resistance computed in the usual manner except
for the absence of water limitation
OUT_PET_VEGNOCR = pot evap from current vegetation with canopy
resistance set to 0
Four "default" veg library classes were created (defined in global.h)
so that veg characteristics for these landcover types (such as
roughness length, etc) are present regardless of the contents of the
externally-supplied vegetation library. As a result, bare soil no
longer is treated as an exception within the code, but as a legitimate
class having its own area fraction Cv, etc. This simplifies some of
the loops in the code.
In order to compute potential evaporation for these different cases,
several different aerodynamic resistances also needed to be computed.
Rather than store all of these in the cell_data structure, the
"aero_resist" array of the cell_data structure was removed and
the previously-named "aero_resist_used" array was renamed to
"aero_resist". Now, the pre-stability-correction values of
aero_resist are stored in a temporary internal array and not reported.
Finally, computation of canopy resistance was moved out of penman()
and into a separate function calc_rc() within the same file.
Simplified argument lists of runoff() and surface_fluxes().
Files Affected:
full_energy.c
runoff.c
surface_fluxes.c
vicNl.h
wetland_energy.c
Description:
Simplified the argument lists of runoff() and surface_fluxes() by
replacing explicit references to individual cell_data variables by
a single reference to the cell_data structure.
Wetland portion of lake/wetland tile is now simulated in full_energy().
Files Affected:
free_dist_prcp.c
frozen_soil.c
full_energy.c
initialize_lake.c
initialize_model_state.c
initialize_soil.c
LAKE.h
lakes.eb.c
make_dist_prcp.c
Makefile
put_data.c
read_initial_model_state.c
read_lakeparam.c
read_soilparam.c
read_soilparam_arc.c
read_vegparam.c
soil_conduction.c
vicNl.c
vicNl_def.h
vicNl.h
wetland_energy.c (removed)
write_model_state.c
Description:
In previous versions of 4.1.x, the wetland portion of the lake/wetland
tile was stored in the (N+1)st vegetation tile, and processed in the
` function wetland_energy(), which was an almost exact duplicate of
full_energy(). This created several difficulties, including a) potential
conflicts with the COMPUTE_TREELINE option, b) conflicts with the new
implementation of bare soil and potential evap, c) hard-coding of
wetland vegetation to be equal to the grid cell's first listed cover
type, and d) general complexities in maintaining the code/adding new
features.
Now, the wetland portion of the lake/wetland tile must be listed in
the vegetation parameter file in the same was as all other veg cover
types. Similarly, the wetland portion of the lake/wetland tile is
processed in full_energy() in the exact same way as all other tiles.
Wetland_energy() has been removed. Lakemain() has also been removed,
as the calls to lake-specific functions are now executed directly from
full_energy(). To make all of this happen, the index of the veg tile
containing the lake/wetland must be indicated in the lake parameter
file (thus, the lake parameter file must contain an additional
value for each grid cell).
Users may now specify any type of desired vegetation to fill the
wetland portion of the lake/wetland tile, simply by listing the
desired veg cover in the veg param file and placing the index of this
tile in the lake parameter file. The user is also free now to create
a new wetland vegetation class in the vegetation library.
State files now contain data for 0-area bands.
Files Affected:
read_initial_model_state.c
write_model_state.c
Description:
In order to ensure that the value of Nbands saved in the state file
accurately accounted for the number of bands whose states are stored
in the state file, changed VIC to read/write data for all bands,
whether or not their area is 0.
Bug Fixes:
Fixed conflict between PRT_SNOW_BAND option and flexible output configuration.
Files Affected:
global.param.sample
parse_output_info.c
put_data.c
vicNl_def.h
Description:
The PRT_SNOW_BAND option exists for backwards-compatibility with older
versions of VIC. If the user is using the default output cofiguration,
and PRT_SNOW_BAND is set to TRUE, it creates "snowband" output files.
However, this was not made clear in the documentation; it is possible
to specify output files containing the snow-band-specific values of
variables without setting PRT_SNOW_BAND to TRUE. However, put_data()
contained logic that only allowed it to record snow-band-specific
quantities if PRT_SNOW_BAND is TRUE, even if the user had specified
snow-band-specific output variables in the output files.
Therefore, the logic checking the value of PRT_SNOW_BAND was removed
from put_data(). Additionally, if the user has specified N_OUTFILES
in the global parameter file, PRT_SNOW_BAND will now be set to FALSE
by parse_output_info(), just to make sure that PRT_SNOW_BAND only
applies to the default output case. Documentation in
global.param.sample and vicNl_def.h has been updated to reflect this
behavior. TJB
Fixed problems in soil temperature solution due to use of dz_node.
Files Affected:
calc_surf_energy_bal.c
frozen_soil.c
func_surf_energy_bal.c
initialize_model_state.c
lakes.eb.c
soil_conduction.c
vicNl.h
wetland_energy.c
Description:
The addition of the EXCESS_ICE option introduced a new variable,
Zsum_node, to the soil thermal solution code. This conflicted with
the existing variable dz_sum. Therefore, dz_sum has been replaced
by Zsum_node in several functions. KAC via TJB
Fixed problem of errors from put_data() not being caught.
Files Affected:
dist_prec.c
Description:
Modified routine to store put_data() error in ErrorFlag2 and
return a single ERROR value if an error occurs. KAC via TJB
Fixed uninitialized value errors in parse_output_info.c.
Files Affected:
parse_output_info.c
Description:
Added default values for format, typestr, and multstr, so that they
can be omitted from global param file. TJB
Fixed inability to read tabs in soil/veg parameter files.
Files Affected:
read_soilparam.c
read_vegparam.c
Description:
At some point in earlier versions, the functions that read soil/veg
parameter files were modified to use the "strtok" function, and as a
result, VIC lost the ability to understand tabs as field separators
in these files. This ability has now been restored. TJB
Fixed bugs in snow bands implementation.
Files Affected:
output_list_utils.c
read_snowband.c
read_vegparam.c
vicNl.c
vicNl.h
vicNl_def.h
Description:
Some snowband-specific output variables had an incorrect number of
elements allocated in output_list_utils.c. This has been fixed. In
addition, added BandElev[] array to soil_con_struct. Also added logic
to ensure that grid-cell-average elevation (from soil parameter file)
matches the average of the band elevations. Also added allocation of
extra veg tile for the case of a band being above the treeline in the
COMPUTE_TREELINE case. TJB
Removed special logic for longwave in water balance mode
Files Affected:
func_surf_energy_bal.c
intialize_atmos.c
initialize_model_state.c
Description:
In the 4.0.x branch of VIC, net longwave radiation was stored in the
atmos.longwave variable for the case of water balance mode. This
required that special logic be inserted into various parts of the
code wherever the longwave variable was used. In 4.1.x, new features
were added and several different types of longwave flux were added.
None of these new fluxes took the water-balance case into account, and
as a result, the water balance case was handled incorrectly. Now the
special handling of the water balance case has been removed; atmos.longwave
always contains incoming longwave. This also simplifies the code.
TJB
VIC now can understand indented comment lines in the global parameter file
Files Affected:
get_global_param.c
Description:
Previously, VIC only understood a line to be a comment if it began
with a '#' character at the very beginning of the line, i.e. no
leading white space such as spaces or tabs. Now, any line whose first
non-whitespace character is '#' is considered to be a comment.
Miscellaneous fixes to snow albedo aging scheme
Files Affected:
initialize_snow.c
SnowPackEnergyBalance.c
snow_melt.c
solve_snow.c
Description:
Previously, VIC's last_snow counter, which keeps track of the number
of time steps since the last fresh snowfall, and which is used to
compute the snow albedo, was not reset to 0 at the proper times. This
has been fixed, along with its initialization.
Fixed errors in summing output variables
Files Affected:
dist_prec.c
full_energy.c
initialize_lake.c
initialize_model_state.c
initialize_snow.c
LAKE.h
lakes.eb.c
put_data.c
read_initial_model_state.c
read_snowband.c
read_soilparam_arc.c
read_soilparam.c
vicNl.c
vicNl_def.h
vicNl.h
write_model_state.c
Description:
Previously, many lake water and energy budget terms were lumped into
the wetland soil, snow, and energy structures. This often led to
water/energy balance errors both internally and in summing these terms
for output. To solve this problem, new cell, snow, and energy
structures were added to the lake_var structure. These structures
allow all lake water and energy budget terms to be tracked
independently of the wetland.
In addition, previously, the initial computation of water/energy
storages for use in the water/energy balance checks was done in
vicNl(). This logic was not in sync with the computations in put_data().
Therefore the logic was replaced with an initial call to put_data()
(using rec= -Nrecs). Within put_data(), two new functions were
created to help ensure that summing was consistent among upland veg
tiles, wetland, and lake: collect_wb_terms() and collect_eb_terms().
Finally, another source of errors arose from the allocation and
initialization of snowband parameters in read_snowband(). These
terms were only initialized in read_snowband(), but were in some cases
used in put_data() for the non-snowband case. Therefore, we have
moved the allocation/initialization of these terms to read_soilparam()
and read_soilparam_arc(). These parameters are further modified in
read_snowband(), as necessary.
Added error messages for case when LAI==0 and overstory==1.
Files Affected:
read_veglib.c
read_vegparam.c
Description:
Added error messages for case when LAI==0 and overstory==1. Without
this check, a user could specify LAI of 0 for an overstory type (e.g.
a deciduous tree). Unforutunately, the model code assumes that the
overstory itself always contains some minimum LAI (perhaps assuming
that the LAI contains stem area as well?), and in some cases divides
by the LAI. If LAI ever is 0 for an overstory type, this will lead
to nan values in evap, soil moisture, canopy storage, etc.