Configuration

Program organisation

The main module of VAMPS is the vamps program itself. It uses a series of equations to describe the flow of water through a forested ecosystem. Preparing input for VAMPS takes quite a while and is by no means a trivial task.

Post-processing tools included with VAMPS:

• vsel — the recommended tool for general post-processing. It can produce data that can be fed directly to plotting programmes such as gnuplot.

• util.py in share/ — Python equivalent providing vsel(), vprof(), and f_save().

VAMPS can crash in certain situations:

1. A genuine bug.

2. The situation to be modelled is beyond the capabilities of VAMPS.

3. The timestep estimate done by VAMPS is not right. A lot of precipitation on a very clayey soil is a recipe for disaster.

Troubleshooting options are described in Troubleshooting.

Layers in the soil section

The layers variable in the [soil] section determines the number of layers used in the calculations (nodes, strictly speaking). The number of physical layers (with different \(K_{sat}\), for example) is determined by the number of [layer_n] sections. Any computational layer that is not assigned a specific layer section automatically inherits the settings from the overlying layer.

The [layer_0] section is the only one that is mandatory.

Time series and time-steps

Time series are values of variables over time used as input. All time series must be listed in the [ts] section.

The precipitation time series is special because it also determines the time-steps at which output is calculated. The x-column should be in days or fractions of a day (e.g. 1.5 means halfway through day 1). Time-steps may vary within one run. Example precipitation file:

# This is a comment
# Precipitation from the no-name site
# time in days         amounts in cm/day (intensity!)
0.5     0.6
1.0     0.9
2.0     0.7
2.1     0.9
2.2     0.7
2.3     0.5
3.0     0.8
3.5     0.0

Points to remember:

1. Units are cm/day (intensities). Convert precipitation data if necessary.

2. The time in the x-column is the end of an interval. Output at time 3.0 covers the period from time 2.3 to 3.0 (duration 0.7 days). The first record has no known preceding interval; VAMPS defaults to one day. You can change this with the firststep variable in the [time] section.

3. The x-column in all files except the precipitation file is ignored (it must be present but VAMPS does not check the time values).

Input file format

The VAMPS input file format is similar to Windows .ini files. All names and sections are case-insensitive. String variable values preserve case, so filenames are case-sensitive if the operating system is.

The file is divided into sections, each containing variables with a related purpose. Each variable name is followed by = and then the value. Example:

[vamps]
verbose = TRUE
# This is a comment

[environment]
caseid = Interception test file. Bisley catchment.\
Summer of 1995

The \ character may be used to break long strings over more than one line (it is converted to a space). The # sign at the start of a line denotes a comment. Only the first = sign is significant. Spaces within variable names are preserved verbatim, making the following legal:

[vamps]
output mode = This is ('=') a nonsense example.

VAMPS uses six variable types:

1. floats — floating point numbers

2. arrays — a row of floating point numbers separated by whitespace

3. strings — a series of characters

4. integers — whole signed numbers

5. characters — a single printable character

6. boolean — either 0/1, FALSE/TRUE, or NO/YES

Available sections and variables

[vamps]

verbose

If set to FALSE VAMPS will be silent; if set to TRUE VAMPS will display progress information.

header

If set to FALSE no header is added to the output; if set to TRUE a header is added. Default is FALSE.

logging

FALSE = no logging; TRUE = logging is on.

logfilename

Name of the file to which logging is written.

iniinmem

TRUE = the input file is read into memory (some speed-up); FALSE = the input file is not read into memory.

progstr

String used to display progress information. Use 0, 1 or 2 for built-in strings: 0 = calculation time and estimated time remaining; 1 = percentage finished bar; 2 = ‘calculating’. You can define your own string.

graphcommand

Full path to gnuplot with optional command-line options.

commentchars

Character(s) that denote the start of a comment. Defaults to #%. The first character should not be changed without good reason.

xtrapy

Path to a Python script to load at startup. The path is resolved relative to the .inp file. The script may define at_start(), each_step(), and/or at_end() functions. See Python Scripting for details.

[time]

steps

Integer value specifying the number of steps in the current simulation. This value must be smaller than or equal to the number of entries in the precipitation file.

startpos

Position (line) in the precipitation input file used as start. Counting starts at zero.

starttime

Day at which the simulation should start. If not specified the simulation starts at the first step in the precipitation input file. If both starttime and startpos are specified, starttime is used.

firststep

Duration to assume for the first time-step when no prior step is known. Default is 1.0 day.

[run]

outputfile

Filename to save output to. Can be overridden with the -o command-line option.

runid

Not currently used.

[determine]

canopy

Determine canopy water balance (see [canopy]).

evaporation

Determine actual evaporation (see [evaporation]).

pevaporation

Determine potential evaporation (see [pevaporation]).

soilmoisture

Determine soil moisture profile (see [soil]).

fit

Use nonlinear regression to fit to measured data (see [fit]).

[pevaporation]

method

• 0 — potential evaporation via Penman \(E_0\) (needs: refrad, netrad, rhumid, windspeed, temp, inrad)

• 1 — potential evaporation via Penman \(E_0\) using sun-ratio (needs: sunratio, rhumid, windspeed, temp, inrad)

• 2, 3 — not yet implemented

• 4 — potential evaporation using Makkink (needs: rhumid, windspeed, temp, inrad)

[evaporation]

method

• 0 — evaporation equal to potential evaporation

• 1 — multiply potential evaporation by a crop factor (needs cropfac)

• 2 — calculate actual evaporation using the Penman–Monteith formula

cropfac

Floating point crop factor by which potential evaporation is multiplied to yield actual evaporation (only needed for method = 1).

[interception]

method

• 0 — Gash analytical model

• 1 — Rutter numerical model

• 2 — LAI fraction

• 3 — Calder regression

gamma

Maximum interception loss per day \(\gamma\) in the Calder equation [mm].

delta

Fitting parameter \(\delta\) in the Calder equation.

E_avg/R

Average evaporation / average rainfall during a storm (Gash model). If not set, Penman–Monteith with \(R_a = 0\) is used.

p_tr

Fraction of water diverted to the trunk (Gash, Rutter).

p_f

Free throughfall coefficient (Gash, Rutter).

S

Canopy storage in cm (Gash, Rutter).

gashm

0 or 1. If set to 1, an adapted Gash model is used that works for time-steps smaller than 1 day. Default = 0.

laifrac

Canopy interception coefficient (LAI fraction method).

lai

Leaf area index. Needed for the laifrac method. If not present it is searched in the [canopy] section.

[canopy]

layers

Number of canopy layers. At present only one layer is allowed.

Rnet_absorb

Fraction of total radiation absorbed by the canopy (\(0 \le \text{Rnet\_absorb} \le 1\)). The remaining amount is used for soil evaporation.

transpiration

Which transpiration equation to use. * 2 — Penman–Monteith * 3 — read from ptr in the [ts] section

z

Height of the canopy [m].

z_0

Aerodynamic roughness length [m].

d

Zero plane displacement length [m].

rs

Canopy resistance [s/m]. If not specified the user-defined regression function estrs() is used.

drytime

If set, this value [days] determines how long it takes for the canopy to dry.

wetevap

If set, this value [cm/day] determines the wet-canopy evaporation rate instead of Penman–Monteith with \(R_s = 0\).

[roots]

depth

Depth of the root zone [cm]. To vary rooting depth in time use the drootz variable in the [ts] section.

swsink

• 0 — sink term according to Feddes (needs: hlim1, hlim2u, hlim2l, hlim3h, hlim3l, hlim4)

• 1 — sink term according to Hoogland (needs: hlim1, hlim2u, hlim2l, hlim3, hlim4)

swhypr

• 0 — linear relation between the points hlim3 and hlim4

• 1 — hyperbolic relation between the points hlim3 and hlim4

swupfu

• 0 — water uptake function according to Feddes

• 1 — water uptake function according to Hoogland

• 2 — water uptake function according to Prasad (1988)

cofsza

Intercept a in Feddes et al. 1988 (only needed if swupfu = 1).

cofszb

Slope b in Feddes et al. 1988 (only needed if swupfu = 1).

hlim1

Pressure head [cm] below which roots start to extract water from the upper soil layer (starting point).

hlim2u

Pressure head [cm] below which roots start to extract water optimally from the upper soil layer.

hlim2l

As above, but for all lower soil layers.

hlim3h

Pressure head [cm] below which roots cannot extract water optimally for a high potential transpiration rate (0.5 cm/d) — limiting point.

hlim3l

As above, but for low potential transpiration rate (0.1 cm/d).

hlim3

Pressure head [cm] below which roots cannot extract water any more (limiting point; Hoogland method).

hlim4

Pressure head [cm] below which no water uptake by roots is possible (wilting point).

[ts]

Lists the forcing time series. Each variable name maps to a file path. The precipitation variable (pre) is mandatory.

File format: two whitespace-separated columns (time, value). VAMPS assumes column 0 = time and column 1 = value. You can override this by appending ,xcol,ycol to the filename (a comma is therefore not allowed in filenames).

Standard variables:

pre

Precipitation [cm/day]. Also determines the simulation time-steps.

rlh

Relative humidity [%].

tem

Dry-bulb temperature [°C].

win

Wind speed [m/s].

nra

Net radiation [W/m²].

ira

Incoming (global) radiation [W/m²].

ptr

Potential transpiration [cm/day] (if pre-computed).

spe

Potential soil evaporation [cm/day] (if pre-computed).

inr

Interception [cm/day] (if pre-computed).

hea

Head at the bottom node [cm] (bottom condition 4).

rdp

Rooting depth [cm]. You must specify at least three points; other points are interpolated using a spline.

gwt

Groundwater table [cm] (bottom condition 0).

lai

Leaf area index.

sca

Canopy storage [cm].

[soil]

outskip

Skip this many timesteps in soil output. Used to reduce output file size.

initprof

• 0 — water content profile (needs theta_initial array)

• 1 — pressure head profile (needs h_initial array)

• 2 — calculate pressure head profile (needs gw_initial)

gw_initial

Initial groundwater level [cm below field level]. Needed if initprof = 2.

swredu

Reduction of soil evaporation: * 0 — no reduction * 1 — Black (1969) model * 2 — Boesten (1986) model * 3 — adapted Boesten (1986) model (takes into account actual surface moisture)

cofred

Factor alfa in Black or beta in Boesten. Not needed for swredu = 0.

bottom

Bottom boundary condition (see The Soil for descriptions): 0 = groundwater table, 1 = fixed flux, 2 = seepage/infiltration, 3 = flux as function of head, 4 = fixed head, 5 = zero flux, 6 = free drainage.

smooth

Size of the running average used for smoothing the ksat, theta_saturation, and residual_water profiles. Set to zero for no smoothing (default).

layers

Number of computational soil layers. The number of physical layers is determined by the number of [layer_n] sections.

pondmx

Maximum amount of ponding [cm] at the top of the profile. Defaults to 0.0.

gwlevel

Water level at the bottom of the profile [cm]. Needed if bottom = 4.

dtmax

Maximum timestep [days] in the soil module. Lower this if you experience large mass-balance errors.

dtmin

Minimum timestep [days] in the soil module. Setting dtmin and dtmax to equal values forces VAMPS to use a fixed timestep.

speed

Integer from 1 (slow/accurate) to 6 (fastest/least accurate) controlling the trade-off between calculation accuracy and speed. Combines the settings of dtmin, thetol, solvemet, mktable, maxitr, and swnums. Individually specified variables override the speed preset. Default is 3.

maxitr

Maximum number of iterations in the soil module. Iterations are only performed if swnums != 1.

thetol

Theta tolerance. VAMPS checks if the solution is good enough and iterates if needed. Usually between 1.0E-2 and 1.0E-5. The default value usually works fine.

solvemet

How VAMPS solves the equation matrix: * 0 — default tridiagonal (Thomas algorithm) * 1 — always use band-diagonal * 2 — very general solution (regains full machine precision; slow)

swnums

If set to 1 the soil module will not check for convergence; it assumes the initial maximum dt is a good guess. Much faster but can give poor results.

mktable

If set to TRUE VAMPS creates lookup tables for the \(\theta\)–\(K\) relation and uses them during iteration. Default is FALSE. Can speed up calculations by up to 50 % at a slight loss of precision. The default table size is 300 points; change with tablesize.

tablesize

Size of the lookup tables. Default 300. Increasing improves accuracy at some memory and performance cost. Table sizes up to 1200 still provide speed improvements over not using tables.

dumptables

If TRUE the lookup tables are dumped to the initial section of the output file (useful for plotting pF curves).

estdmc

If TRUE and mktable is also TRUE, the dmc table is built using ts_slopes and the pF curve instead of the h2dmc function.

verbose

Verbose level in the soil module (0 = silent, 1 = show estimated run time).

smddepth

If set, the SMD (soil moisture deficit) is calculated to this depth. Otherwise the rooting depth is used.

fieldcap

Head [cm] at which the soil is at field capacity. Needed for SMD calculation. Default = −100.0.

mbck

If set to 1, VAMPS uses a simple mass balance check for convergence instead of thetol. Usually faster for the same accuracy.

mbalerr

Required mass balance accuracy per timestep when mbck = 1. A value between 1.0E-2 and 1.0E-5 is usually best. Default = 0.5E-3.

[drainage]

This section is experimental.

method

• 0 — no lateral drainage (default)

• 1 — TOPOG type drainage (only at saturation)

• 2 — allow unsaturated lateral flow as well

If method > 0 then slope must also be set.

slope

Slope used in the calculation of lateral drainage.

exclude

Array of layer indices in which lateral drainage is not allowed. Example: exclude = 12 1 23 45. Combined with a no-flow bottom boundary this can simulate a lysimeter.

[soilsectionname]

This section can have any name and contains the soil-type-specific parameters. The soilsection variable in each [layer_n] section references this section by name.

method

Method for the \(K\) vs \(\theta\) relation:

Value	Description
0	Clapp/Hornberger
1	Van Genuchten (default)
2	Not yet implemented
3	Van Genuchten parameters determined from \(\theta\) vs pF pairs
4	Read TOPOG_soil lookup tables
5	User-defined Python functions (requires Python support; see Python Scripting)
6	Brooks and Corey (1964)

For method 3: given values of alpha and n are used as initial guesses. Required variables: theta (array) and pf (array). The exponent l is fixed at 0.5.

For method 4: VAMPS reads and uses soil tables generated by the TOPOG_soil programme.

For method 5: define getspars, h2t, t2k, t2h, h2dmc, h2k, h2u, and h2dkdp Python functions. See Python Scripting and share/soilf.py / share/soilf_bc.py for reference implementations. It is strongly recommended to also set mktable = 1 in [soil] for acceptable performance.

For method 6: required parameters are lambda, hb, thetas, theta_residual, ksat.

description

Optional description of the soil layer.

ksat

Saturated hydraulic conductivity of the layer.

kh/kv

Ratio of \(K_{sat}\) horizontal to \(K_{sat}\) vertical. Only used with lateral drainage. Default = 1.

thetas

Water content at saturation (porosity).

psisat

Head at saturation (air entry value) — needed for Clapp/Hornberger (method = 0).

b

Factor b in Clapp/Hornberger (method = 0).

theta_residual

Residual soil moisture content.

alpha

\(\alpha\) parameter in Van Genuchten [1/cm].

l

\(l\) parameter in Van Genuchten (use 0.5 if not measured).

n

\(n\) parameter in Van Genuchten.

lambda

Pore-size distribution index \(\lambda\) for Brooks and Corey (method = 6). Starting approximation from Van Genuchten: \(\lambda \approx n - 1\).

hb

Air-entry (bubbling) pressure head \(h_b\) for Brooks and Corey (method = 6), in cm. Must be negative (e.g. hb = -16.4). Starting approximation from Van Genuchten: \(h_b \approx -1/\alpha\).

tablefile

File from which the soil table is read. Use with method = 4.

tablefiletype

Format of the table file:

• 1 — TOPOG format (VAMPS uses columns 1, 3, 4, and 5)

• 2 — whitespace-separated columns (psi theta k); differential moisture capacity is estimated

• 3 — whitespace-separated columns (psi theta k diff_moist)

All table files should be made with descending theta values.

[layer_n]

Only [layer_0] is mandatory. Additional sections are needed only if you have more than one physical soil layer.

thickness

Thickness of the layer [cm].

soilsection

Name of the section that contains the soil-type parameters for this layer.

[fit]

Used with the --fit option or when fit = 1 in [determine].

fitto

Name of a time series (must be in the [ts] section) with actual measurements to fit against.

n (where n = 0 … MAXPAR)

Add a parameter to the fitting list. Available parameters: 1 = n (VG), 2 = alpha, 3 = ksat, 4 = b, 5 = psisat, 6 = l, 7 = residual_water, 8 = thetas.

layer

Physical layer to use in fitting.