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” |
Background¶
Equations¶
equations.pdf Pdf-file with equations for vegetation transport model.
Watbal3.pdf Pdf-file with equations regaring the water balance.
Literature¶
Source code¶
To be added
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