Welcome to VOM’s documentation!

The vegetation optimality model was developed to model the water use by natural vegetation for use in hydrological models. The aim of the model is to predict vegetation water use based on meterological information, soils and topography only, without the need for prescribing site-specific vegetation properties or calibration against observed fluxes.

Quickstart

Dependencies

Before starting, make sure an appropriate fortran compiler is installed. The code has been tested and developed mainly with gfortran.

In addition, make sure the netcdf-fortran library is installed:

sudo apt install netcdf-bin libnetcdf-dev libnetcdff-dev

The VOM will by default search for the netcdf installation in usr/include.

Compiling and testing the model

To compile the model on a unix machine with the gfortran compiler, type :

make

This will create an executable file called “model.x”. Now test the model by typing:

make check

When the test is passed, the model is ready to use. The VOM_namelist contains all settings, and the model should always be run with the directory of this namelist as working directory. Input and output directories can be defined in the namelist with absolute or relative paths from the working directory.

Running the model

The executable “model.x” can be run :

./model.x

To run successfully, these input-files are needed:

vom_namelist
Contains all settings to run the VOM.
pars.txt
Contains the (optimized) vegetation parameters (only needed for single run).
dailyweather.prn
Contains the meteorological forcing.

By default, the executable looks for the vom_namelist in the current workdirectory. The default directory for the other files is /input, relative to the workdirectory. This can be changed in vom_namelist, or on the command line:

-i Inputpath to directory with dailyweather.prn, and optionally pars.txt.

-o Outputpath for all outputfiles.

-n The VOM_namelist (filename can be different)

Model modes

The model can be run in 4 different modes, defined by VOM_command in the VOM_namelist:

1 Optimize the model with the Shuffled Complex Evolution algorithm.

2 Run without optimization, based on the parameters in pars.txt.

3 Run without optimization, based on the parameters in pars.txt. Returns only NCP values as output.

4 Run the model with a set of random parameters.

VOM_namelist

The file “vom_namelist” is an input file for the VOM, containing all settings for the model runs:

Meteorological forcing

The file “dailyweather.prn” is an input file for the VOM, containing all meteorologicald data:

Dcum Day of the year Integer
Day Day of the month Integer
Month Month of the year Integer
Year Year Integer, 4 digits
T.Max Daily max. Air temp in °C Decimal, #.##
T.Min Daily min. Air temp in °C Decimal, #.##
Rain Daily rain fall in mm Decimal, #.##
Radn Global solar irradiance in MJ/m2 Decimal, #.##
VP Water vapour pressure in hPa Decimal, #.##
Pres air pressure in hPa Decimal, #.##
Ca ambient air CO2 concentration in µmol Decimal, #.##

The first line contains the variable names and is omitted when reading the file. All fields are 8 characters long and need to be filled from behind, e.g.:

NOTE: when creating your own dailyweather.prn, make sure the alignments are exactly the same as the example input I.e. in the following format: %8.0f%8.0f%8.0f%8.0f%8.2f%8.2f%8.2f%8.2f%8.2f%8.2f%8.2f

Soil data

Soil layers

Soil layer thickness is globally defined with the parameter i_delz, or in the file soilprofile.par for each soil layer separately. The sum of the soil layers need to be equal to the topographical parameter i_cz (maximum elevation). The VOM will raise a warning and correct i_cz if this is not the case. The river bed level i_zr needs to align with the soil layers. Also here, the VOM will give a warning and correct i_zr if needed.

Soil properties

Soil water retention and hydraulic conductivity parameters for 12 major soil textural groups according to [1]. Some units of the parameters (alpha and Ksat) are converted for the use in the VOM.

Texture theta-r theta-s alpha (1/m) n K-sat (m/s)
Sand 0.045 0.43 14.5 2.68 8.25*10-5
Loamy Sand 0.057 0.41 12.4 2.28 4.053*10-5
Sandy Loam 0.065 0.41 7.5 1.89 1.228*10-5
Loam 0.078 0.43 3.6 1.56 2.889*10-6
Silt 0.034 0.46 1.6 1.37 6.944*10-7
Silt Loam 0.067 0.45 2.0 1.41 1.25*10-6
Sandy Clay Loam 0.100 0.39 5.9 1.48 3.639*10-6
Clay Loam 0.095 0.41 1.9 1.31 7.222*10-7
Silty Clay Loam 0.089 0.43 1.0 1.23 1.944*10-7
Sandy Clay 0.100 0.38 2.7 1.23 3.333*10-7
Silty Clay 0.070 0.36 0.5 1.09 5.555*10-8
Clay 0.068 0.38 0.8 1.09 5.555*10-7
[1]Carsel, R.F. & R.S.Parrish (1988): Developing joint probability distributions of soil water retention characteristics.-Water Resource Research 24:755-769.

Outputfiles

Output files can by default created in plain text format, but can also be set to netcdf by changing the flag i_write_nc to .True.

results_daily.txt

The file “results_daily.txt” is an output file from VOM, containing daily weather, flux and state variable data in ascii format, e.g.:

fyear Day of the year
fmonth Month of the year
fday Day of the month
nday Day of the model
nhour Last hour of day
rain Daily rain fall in mm/d
tairmax Daily max. Air temp in °C
tairmin Daily min. Air temp in °C
par Photosynthetically active Photon Flux Density (in mol m-2 d-1)
vd Daily average atmospheric vapour deficit (in mol mol-1)
esoil Daily soil evaporation rate (m d-1)
jmax25t Electron transport capacity at 25oC by trees (in mol m-2 s-1)
jmax25g Electron transport capacity at 25oC by grasses (in mol m-2 s-1)
pc Area fraction covered by grasses and trees combined
rl Daily leaf respiration rate by trees and grasses combined (in mol m-2 d-1)
lambdat dE/dA in trees, in mol/mol
lambdag dE/dA in grasses, in mol/mol
rrt Daily root respiration rate by trees (in mol m-2 d-1)
rrg Daily root respiration rate by grasses (in mol m-2 d-1)
asst CO2 uptake rate by trees (in mol m-2 d-1)
assg CO2 uptake rate by grasses (in mol m-2 d-1)
su_avg Average soil saturation degree in the unsaturated zone at midnight (dimensionless)
zw Thickness of the saturated zone (in m)
ws Total soil water storage (in m)
spgfcf Daily seepage face flow (=subsurface runoff, in m d-1)
infx Dail infiltration excess runoff (in m d-1)
etmt Daily transpiration rate by trees (in m d-1)
etmg Daily transpiration rate by grasses (in m d-1)
su_1 Soil saturation degree in the top soil layer at midnight (dimensionless)
topt Optimal temperature for photosynthesis (in oC)
ncp_g Daily Net Carbon profit grasses (in mol m-2)
ncp_g Daily Net Carbon profit trees (in mol m-2)

results_hourly.txt

fyear Day of the year
fmonth Month of the year
fday Day of the month
nday Day of the model
nhour Hour
rain Rainfall rate in m/s
tair Air temp in °C
par Photosynthetically active Photon Flux Density (in mol m-2 s-1)
vd Atmospheric vapour deficit (in mol mol-1)
esoil Hourly soil evaporation rate (m h-1)
jmax25t Electron transport capacity at 25oC by trees (in mol m-2 s-1)
jmax25g Electron transport capacity at 25oC by grasses (in mol m-2 s-1)
pc Area fraction covered by grasses and trees combined
mqt Tissue water content in trees (in kg m-2)
rl Leaf respiration rate by trees and grasses combined (in mol m-2 s-1)
lambdat dE/dA in trees, in mol/mol
lambdag dE/dA in grasses, in mol/mol
rr Rroot respiration rate by trees and grasses combined (in mol m-2 s-1)
asst Hourly CO2 uptake rate by trees (in mol m-2 h-1)
assg Hourly CO2 uptake rate by grasses (in mol m-2 h-1)
zw Thickness of the saturated zone (in m)
ws Total soil water storage (in m)
spgfcf Hourly seepage face flow (=subsurface runoff, in m h-1)
infx Hourly infiltration excess runoff (in m h-1)
etmt Daily transpiration rate by trees (in m h-1)
etmg Daily transpiration rate by grasses (in m h-1)
su_1 Soil saturation degree in the top soil layer at midnight (dimensionless)

results_yearly.txt

nyear Year
rain Annual rainfall (mm/year)
par Photosynthetically active Photon Flux Density (in mol m-2 s-1)
srad Global solar irradiance (in MJ m-2 a-1)
vd Yearly average vapour deficit (in mol mol-1)
esoil Yearly soil evaporation rate (m/year)
etmt Yearly transpiration rate by trees (in m/year)
etmg Yearly transpiration rate by grasses (in m/year)
assg CO2 uptake rate by seasonal vegetation (in mol m-2 a-1)
asst CO2 uptake rate by trees (in mol m-2 a-1)
rlg Leaf respiration rate by seasonal vegetation (in mol m-2 a-1)
rrg Root respiration rate by seasonal vegetation (in mol m-2 a-1)
rlt Leaf respiration rate by perennial vegetation (in mol m-2 a-1)
rrt Root respiration rate by perennial vegetation (in mol m-2 a-1)
cpccg Carbon costs related to water distribution and storage for seasonal vegetation (in mol m-2 a-1)
tcg Carbon costs related to maintenance of gras foliage (in mol m-2 a-1)
cpcct Carbon costs related to water distribution and storage for perennial vegetation (in mol m-2 a-1)
tct Carbon costs related to maintenance of tree foliage (in mol m-2 a-1)

rsurf_daily.txt

The file “rsurf_daily.txt” is an output file from VOM, containing a midnight snapshots of the root surface distributions in the soil profile in ascii format.

As the number of soil layers also depends on given soil depth, this file has a variable number of columns. These columns do not have their own variable names. They are all saved within and behind the last variable name (rsurft_sublayer), e.g.:

fyear Year
fmonth Month of the year
fday Day of the month
nday Day of the model
rsurft_sublayer Root surface area density (root surface area per unit soil volume) in each soil layer (in m2 m-3 d-1)

ruptk_hourly.txt

The file “ruptkt_hourly.txt” is an output file from VOM, containing hourly root water uptake rates in each soil layer during the last few years of the model run in ascii format.

As the number of soil layers also depends on input given soil depth, this file has a variably number of rows. These rows don’t have their own variable names. They are all saved within and behind the last variable name (delyusublayer), e.g.:

fyear Year
fmonth Month of the year
fday Day of the month
nday Day of the model
ruptkt_sublayer Root water uptake rate in each soil layer (in m h-1)

su_hourly.txt

The file “su_hourly.txt” is an output file from VOM, containing hourly soil saturation degrees in each soil layer during the last few years of the model run in ascii format.

As the number of soil layers also depends on input given soil depth, this file has a variably number of rows. These rows don’t have their own variable names. They are all saved within and behind the last variable name (su_sublayer), e.g.:

fyear Year
fmonth Month of the year
fday Day of the month
nday Day of the model
su_sublayer Soil saturation degree in each sublayer (1.0 means fully saturated)

delz_hourly.txt

The file “delz_hourly.txt” is an output file from VOM, containing the thickness of each unsaturated soil layers in ascii format.

As the number of soil layers also depends on the position of the water table, this file has a variable number of rows. These rows do not have their own variable names. They are all saved within and behind the last variable name (delz_sublayer), e.g.:

fyear Year
fmonth Month of the year
fday Day of the month
nday Day of the model
delz_sublayer Thickness of each unsaturated soil layer (in m)

Shuffled Complex Evolutionary algorithm

The Shuffled Complex Evolutionary algorithm of Duan et al. (1994) is used to optimize the VOM. The main settings can be found in the VOM_namelist:

i_ncomp MAXIMUM NUMBER OF COMPLEXES (p) -
i_ncompmin MINIMUM NUMBER OF COMPLEXES (pmin) -
i_resolution RESOLUTION OF OPTIMISATION (% OF MAX VARIATION WHEN OPTIMISATION STOPS) -
i_patience NUMBER OF LOOPS WITHOUT INCREASE IN OF BEFORE OPTIMISATION STOPS -
i_nsimp NUMBER OF OPTIMISATIONS PER COMPLEX AND RUN -
i_focus IF <1.0, THE SPREAD OF THE RANDOM SEED AROUND THE INITIAL VALUES IS LIMITED -
i_iter Maximum iterations in case of random runs -
vom_npar number of parameters in shuffle2par used for optimization in SCE -
n_thread number of threads to be used in parallel (one complex per thread) -
sce_restart restart SCE from previous run, TRUE or FALSE -
runtime_limit time in minutes before sce stops at it’s earliest possibility minutes

The SCE-algorithm (mode 1) can be run in parallel by setting the number of threads. When specified, the SCE-algorithm runs over the different complexes in parallel (one complex per thread). The maximum runtime (in minutes) can be set, after which the algorithm tries to stop at the earliest possibility. Afterwards, the SCE-algorithm can be restarted when sce_restart is set to TRUE and the files of the previous round are available.

Outputs

After the SCE-algoritm finishes, it runs the VOM once more with the optimized parameters. It creates the same files as for a single run, as can be found in the section on the outputs for a single run (see outputfiles).

Filename Description
sce_progress.txt Gets progressively filled with messages as the model runs.
sce_out.txt Gets progressively filled with an experimental parameter set and the respective value of the objective function. Contains a line for every parameter set explored, composed of the parameter values followed by the value of the objective function.
sce_lastloop.txt Written at the end of each optimisation loop and contains all information needed to continue with the next loop, i.e. the number of complexes the number of previous loops, the number of runs performed already, the number of runs since the best objective function was achieved, followed by all the parameter sets explored in the last completed loop and their respective objective function values (similar as sce_out.txt, but limited to the last loop only).
sce_lastbest.txt Contains the best parameter set and objective function of the most recent loop.
sce_bestpars.txt Written whenever a parameter set is found that yields the best objective function value.
sce_status.txt Created when optimisation finished successfully, contains one ascii symbol: “1”

Indices and tables

Theory

The original theory and equations used in the model are described in:

S. J. Schymanski. Transpiration as the Leak in the Carbon Factory: A Model of Self-Optimising Vegetation. PhD thesis, University of Western Australia, Perth, Australia, 2007.

Information

Author Contact: Stan Schymanski Luxembourg Institute of Science and Technology www.list.lu

Code availability: https://github.com/schymans/VOM

Date of first version: April 2006