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” |
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¶
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