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)

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)

Scripts for running the model

In the folder VOM-scripts, two shell-scripts can be found for running the VOM:

vom_parallel.job


run_vom.sh

The model is compiled and executed by the script run_vom.sh. It can be used in the following way:

bash src_sh/run_vom.sh src/VOM/VOM_Fortran/ <inputdir> <dailyweather.prn> <soilprofile.par> <vom_namelist> <outputdir>

vom_parallel.job is a job script for the LIST HPC using SLURM. Note that the script needs to be modified for own applications of the VOM on an HPC and serves here as an example. In this example, submitting a job with SLURM functions as follows:

sbatch -o <output_logfile> -e <error_logfile> -n <number of cpu's> -J <jobname> vom_parallel.job <VOM-src> <input-directory> <dailyweather.prn> <soilprofile.par> <vom_namelist> <output-directory>

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.

Other options

Initially, the VOM schematized the vegetation as two big leaves, for the perennial and seasonal vegetation. In the newest VOM version, leaf area dynamics can be included in a dynamic way as well, by setting the parameter i_lai_function in the VOM_namelist:

1 No LAI dynamics are included.

2 LAI is dynamically modelled, but there is no distinction between shaded and sunlit leaves, as well as different radiation components.

3 LAI is dynamically modelled. Shaded and sunlit fractions are determined and a distinction between direct and diffuse radiation is made, but leaves are still treated as a big leave with a single photosynthetic capacity.

4 LAI is dynamically modelled. Shaded and sunlit fractions are determined and a distinction between direct and diffuse radiation is made. The model considers shaded and sunlit leaves with different photosynthetic capacities. Eletron transport capacities are separately optimized for shaded and sunlit leaves.

VOM_namelist

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

i_alpha initial slope of j(par) curve -
i_cpccf water transport cost factor (cpcc=pc * rootdepth * cpccf) mol/m^3/s
i_tcfg turnover cost factor for foliage grasses (tc=tcf*LAI) mol/m^2/s
i_tcft turnover cost factor for foliage trees (tc=tcf*LAI) mol/m^2/s
i_maxyear number of years to process -
i_testyear number of years after which to perform initial test of netass -
i_ha parameters to calculate jmax(temp) J/mol
i_hd parameters to calculate jmax(temp) J/mol
i_toptf parameter to calculate adaptation of topt (range 0-1, 0.0 means no adaption, 1.0 means topt=tair) -
i_toptstart start parameter for topt to calculate jmax K
i_rlratio leaf respiration parameter (rl=rlratio*assmax) -
i_mdtf total dry mass of living tissues of trees per unit pc g/m^2
i_mqxtf total water storage capacity in living tissues of trees per unit md
i_rrootm root water uptake resistivity s
i_rsurfmin minimum root area to be maintained m^2/m^3
i_rsurf initial root surface area m^2/m^3
i_rootrad fine root radius m
i_prootmg constant root balance pressure in grasses m
i_growthmax parameter determining maximum daily growth increment of root surface area m^2/m^3/d
i_incrcovg parameter determining maximum increment percentage of grass cover -
i_incrjmax parameter determining maximum increment percentage of jmax25 -
i_jmax_ini parameter determining the start value of jmax25 mol/m^2/s
i_incrlait parameter determining maximum increment percentage of LAI grasses -
i_incrlaig parameter determining maximum increment percentage of LAI trees -
i_firstyear firstyear for the generation of hourly output in computation mode -
i_lastyear lastyear for the generation of hourly output in computation mode -
i_write_h flag to greate a file with hourly values from daily values -
i_read_pc flag to read vegetation coverage values from file -
i_write_nc flag to write to netcdf instead of plain text -
i_trans_vegcov fraction of radiative energy reaching soil under full cover (0-1) -
i_lai_function switch for 1) no LAI dynamics, 2) dynamic LAI, 3) dynamic LAI with shaded/sunlit fractions, 4) dynamic LAI with shaded/sunlit fractions and different Jmax for shaded/sunlit fractions - -
i_no_veg switch for running VOM without vegetation (0-with, 1-without) -
i_chi_g ratio projected areas of grass canopy elements on horizontal and vertical surfaces (-) -
i_chi_t ratio projected areas of tree canopy elements on horizontal and vertical surfaces (-) -
i_inputpath path to folder with inputfiles -
i_outputpath path to folder with outputfiles -
o_lambdagf factor for calculating lambdag_d mol/mol/m
o_wsgexp exponent for calculating lambdag -
o_lambdatf factor for calculating lambdat_d mol/mol/m
o_wstexp exponent for calculating lambdat_d -
o_cait projected cover perennial vegetation (0-1) -
o_rtdepth tree rooting depth m
o_mdstore wood water storage parameter of trees (can be in shufflepar) g/m^2
o_rgdepth root depth grasses (can be in shufflepar) m
i_lat geogr. latitude in degrees degrees
i_lon geogr. longitude in degrees degrees
i_cz average soil elevation m
i_cgs Capital Gamma S (length scale for seepage outflow REG) m
i_zr average channel bed elevation m
i_go slope close to channel rad
i_ksat Saturated hydraulic conductivity m/s
i_thetar residual soil moisture -
i_thetas saturated soil moisture -
i_nvg van Genuchten soil parameter n -
i_avg van Genuchten soil parameter alpha 1/m
i_delz thickness of soil sublayers m
vom_command COMMAND LINE TO RUN ASSIMILATION MODEL -
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 -
sce_restart restart SCE from previous run -
runtime_limit time in minutes before sce stops minutes
parname0 list of parameter names -
parval0 list of default parameter values -
parmin0 list of minimum parameter values -
parmax0 list of maximum parameter values -
paropt0 list of parameters to optimize (0-1) -

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)
jmax25ts Electron transport capacity at 25oC by trees, shaded part (in mol m-2 s-1)
jmax25gs Electron transport capacity at 25oC by grasses, shaded part (in mol m-2 s-1)
pc Area fraction covered by grasses and trees combined
rlt Daily leaf respiration rate by trees (in mol m-2 d-1)
rlh Daily leaf respiration rate by grasses (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 Daily 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)
tcg Grass foliage turnover costs (mol/m2/s)
tct Tree foliage turnover costs (mol/m2/s)
cpccg_d Grass water transport costs (mol/m2/s)
cpcct_d Tree water transport costs (mol/m2/s)
fsun_t Fraction of sun trees (-)
fshade_t Fraction of shade trees (-)
fsun_g Fraction of sun grasses (-)
fshade_g Fraction of shade grasses (-)
lai_t Leaf area index trees (-)
lai_g Leaf area index grasses (-)
lai_tot Total leaf area index (-)
cai_g Crown area index grasses (-)
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 Hourly transpiration rate by trees (in m h-1)
etmg Hourly 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 (mm/year)
etmt Yearly transpiration rate by trees (in mm/year)
etmg Yearly transpiration rate by grasses (in mm/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