Lumprem 2
Lumprem 2
John Doherty
Watermark Numerical Computing
April, 2021
Table of Contents
Table of Contents
1. Introduction ........................................................................................................................................ 1
1.1 General .......................................................................................................................................... 1
1.2 LUMPREM2 Output Files ............................................................................................................... 1
1.2.1 Tabular Output File ................................................................................................................ 1
1.2.2 CSV File ................................................................................................................................... 1
1.2.3 Site Sample File ...................................................................................................................... 2
1.2.4 Run Record File ...................................................................................................................... 2
1.3 Running LUMPREM2 ..................................................................................................................... 3
2. Concepts.............................................................................................................................................. 4
2.1 Soil Moisture Stores ...................................................................................................................... 4
2.2 Operation of the Upper Soil Moisture Store................................................................................. 5
2.3 Operation of the Lower Soil Moisture Store ................................................................................. 5
2.3.1 Drainage ................................................................................................................................. 5
2.3.2 Overflow................................................................................................................................. 5
2.3.3. Extraction .............................................................................................................................. 5
2.3.4 Volume to Elevation ............................................................................................................... 6
3. The LUMPREM2 Input File .................................................................................................................. 7
3.1 Backwards Combability ................................................................................................................. 7
3.2 Units .............................................................................................................................................. 7
3.3 File Specifications .......................................................................................................................... 7
3.3.1 General ................................................................................................................................... 7
3.3.2 Specifics.................................................................................................................................. 7
Introduction 1
1. Introduction
1.1 General
LUMPREM2 extends the functionality of LUMPREM. It is backwards compatible with LUMPREM. Hence
it can be used with existing LUMPREM input files. However its main output file is slightly different
from that of LUMPREM. It also records some new output files that the original version of LUMPREM
does not provide.
For the moment, LUMPREM2 is offered as a separate program. The manual for the original version of
LUMPREM should be read prior to reading the manual for LUMPREM2 that you are reading now.
Features that are new to LUMPREM2 include the following:
• Error checking of LUMPREM2 input files is greatly improved over that of LUMPREM.
• Blank lines and comments are allowed in LUMPREM2 input files.
• LUMPREM2 writes a brief run record file in which the values of its input variables are echoed.
A user can therefore verify that these are as expected.
• Optionally, LUMPREM2 records a CSV output file in addition to its tabular output file. The
contents of this file are almost identical to those of its tabular output file.
• Optionally, one or a number of time series produced by LUMPREM can be recorded in a site
sample file (also known as a bore sample file). This type of file is easily read, and its contents
readily manipulated, by members of the PEST Groundwater Utility suite.
• LUMPREM2 features two soil moisture stores instead of one. The lower store is referred to as
a “below root zone” soil moisture store. This store can delay and dampen recharge that
emerges from the upper soil moisture store. The upper soil moisture store simulates root zone
processes.
LUMPREM2 output files are now discussed in greater detail.
1
Introduction 2
2
Introduction 3
3
Concepts 4
2. Concepts
2.1 Soil Moisture Stores
Figure 2.1 depicts the conceptual model on which the LUMPREM2 numerical model is based.
4
Concepts 5
2.3.1 Drainage
Drainage from the lower soil moisture store is calculated in the same way as drainage from the upper
soil moisture store. The equation is:
𝑚 2
𝐷 = 𝐾𝑠 [𝑣 ′ ]𝑙 [1 − (1 − [𝑣 ′ ]1/𝑚 ) ] (2.1)
where:
D = rate of drainage;
Ks = saturated hydraulic conductivity;
v = relative volume of water in the soil moisture store (i.e. v/vmax);
l = pore-connectivity parameter (normally about 0.5); and
m = a parameter determining the shape of the drainage rate vs. stored water relationship (see
documentation of LUMPREM).
Obviously, the values of the above parameters (including vmax) for the lower store can be different
from those of the upper store. Equation 2.1 is graphed in documentation of LUMPREM.
2.3.2 Overflow
The lower store overflows when its volume exceeds vtot, calculated as:
vtot = vmax + vext (2.2)
The use of this “extra volume” (i.e. vext) allows a user to specify an overflow volume that exceeds the
maximum volume (i.e. vmax) that is used in equation 2.1.
2.3.3. Extraction
Extraction from the lower store is calculated in the same way as evaporative extraction is calculated
for the upper store. However this extraction is “evaporation” in name only. Its status as “pseudo
evaporation” allows the rate of water extraction from this store to be reduced as the volume of water
in the store decreases. The equation that is used to enforce this reduction is exactly the same as that
used in the upper store. The equation is:
′
1−𝑒 −𝛾𝑣
𝐸 = 𝑓𝐸𝑝 ′ (2.3)
1−2𝑒 −𝛾 +𝑒 −𝛾𝑣
where:
E = rate of water loss;
Ep = “potential evapotranspiration rate”;
5
Concepts 6
f = “crop factor”;
v = relative volume of water in the lower soil moisture store (i.e. v/vmax where v is the current
volume of water in the store and vmax is the volume of the lower soil moisture store); and
= a parameter determining the shape of the evaporation rate vs. stored water relationship
(see documentation of LUMPREM).
The “crop factor” for the lower soil moisture store is internally set to 1.0. A time series of “potential
evaporation” is supplied by the user; this is a different time series from that applied to the upper
moisture store. So too is the value of .
Equation 2.3 is graphed in the LUMPREM manual.
As stated above, extraction from the lower store is “evaporation” in name only. When LUMPREM2
calculates potential evaporation available for groundwater, it does not subtract water lost from the
lower soil moisture store from potential evaporation applied to the upper store. It subtracts only
evaporative losses from the upper store in order to calculate potential evaporation available to
groundwater.
Simulation of water loss from the lower store as a kind of pseudo evapotranspiration is included in
LUMPREM2 functionality simply as means of providing a little extra flexibility when LUMPREM2 is
deployed to calculate heads or water depths at groundwater model boundaries. This is now discussed.
As well as elevations, LUMPREM also records depths. These are calculated by subtracting water
elevations from a reference elevation (for example the elevation of a topographic surface); the latter
is supplied by the user. Let the reference (topographic) elevation be denoted by s. Depth to water d is
calculated using the formula:
d=s–h (2.5)
where:
d is the depth to water; and
s is the reference elevation.
LUMPREM2 uses these same formulae to convert volumes of water contained in a soil moisture store
to elevations and depths. When using LUMPREM2, the user chooses which store is used for this
purpose. (For the original LUMPREM it is the upper store, because this is the only store which it
employs.)
6
The LUMPREM2 Input File 7
3.2 Units
As for LUMPREM, LUMPREM2’s time units are days. Length (and volume) units are immaterial;
LUMPREM2’s only requirement is that they be consistent.
3.3.1 General
Like a LUMPREM input file, a LUMPREM2 input file is divided into sections. The name of each section
begins with the character “*”. This is followed by a space, followed by the name of the section.
LUMPREM2 allows any line of its input file to be blank. On any line, any characters which follow a “#”
character are ignored. Comments can therefore be included in a LUMPREM2 input file.
3.3.2 Specifics
LUMPREM2 input variables are recognized by their position in the file. These are set out in Figure 3.1.
Square brackets denote optional variables in this figure. Figure 3.2 shows an example of a LUMPREM2
input file. Table 3.1 describes all variables.
7
The LUMPREM2 Input File 8
* earth properties
maxvol irrigvolfrac [maxvol_br extravol_br gamma_br]
rdelay mdelay
ks m l mflowmax [ks_br m_br l_br]
* volume to elevation
offset factor1 factor2 power [elevmin elevmax] [upper_or_lower]
* topographic surface
surface
* initial conditions
vol [vol_br]
nrbuf nmbuf
(rbuf(i), i=1,nrbuf)
(mbuf(i), i=1,nmbuf)
* solution parameters
nstep mxiter tol
* timing information
numdays noutdays
(outday(i),i=1,noutdays)
* data filenames
vegfile OR cropfac_all gamma_all
rainfile
epotfile
irrigfile OR irrigcode_all gwirrigfrac_all
[epotfile_br] OR [epot_br_all]
* ssf file
ssffile
date_spec starting_date starting_time
numssfseries
lumprem_series_name ssf_series_name scale_ssf offset_ssf minval_ssf maxval_ssf
(the above line should appear numssfseries times)
Figure 3.1. Structure of a LUMPREM2 input file. Variables in square brackets are optional. The “ssf
file” section is optional.
8
The LUMPREM2 Input File 9
* earth properties
# maxvol irrigvolfrac maxvol_br extravol_br gamma_br
1.0 0.5 0.5 0.1 2.0
# rdelay mdelay
4.5 1.5
# ks m l mflowmax ks_br m_br l_br
0.1 0.5 0.5 0.1 1.0e-3 0.5 0.5
* volume to elevation
# offset factor1 factor2 power elevmin elevmax lower_or_upper
0.0 2.0 3.0 0.5 -1.0e30 1.0e30 lower
* topographic surface
# surface
0.0
* initial conditions
# vol vol_br
0.5 0.0
# nrbuf #nmbuf
1 2
# rbuf()
0.0
# mbuf()
0.0 0.1
* solution parameters
# nstep mxiter tol
20 200 1e-05
* timing information
# numdays noutdays
3653 120
31 60 91 121 152 182 213 244 274 305 335 366 397 425 456 486 517 547 578 609 639
670 700 731 762 790 821 851 882 912 943 974 1004 1035 1065 1096 1127 1155 1186 1216
1247 1277 1308 1339 1369 1400 1430 1461 1492 1521 1552 1582 1613 1643 1674 1705
1735 1766 1796 1827 1858 1886 1917 1947 1978 2008 2039 2070 2100 2131 2161 2192
2223 2251 2282 2312 2343 2373 2404 2435 2465 2496 2526 2557 2588 2616 2647 2677
2708 2738 2769 2800 2830 2861 2891 2922 2953 2982 3013 3043 3074 3104 3135 3166
3196 3227 3257 3288 3319 3347
3378 3408 3439 3469 3500 3531 3561 3592 3622 3653
* data filenames
# vegfile
veg.dat
# rainfile
rain.dat
# epotfile
epot.dat
# irrigfile
0 0.0
# epotfile_br
0.0
* ssf file
# ssffile
temp.ssf
# date_format starting_date starting_time
dd/mm/yyyy 1/1/2000 00:00:00
# numssfser
4
# lumpsername ssfsername scale_ssf offset_ssf minval_ssf maxval_ssf
total_rech recharge 1.0 0.0 -1e30 1e30
drain_upper soildraing 1.0 0.0 -1e30 1e30
net_recharge net_recharge 1.0 0.0 -1e30 1e30
depth-to-water depth 1.0 0.0 -1e30 1e30
9
The LUMPREM2 Input File 10
Variables appearing in a LUMPREM2 input file are listed in Table 3.1. Variables are real numbers,
unless stated otherwise. For more details see documentation of LUMPREM.
Table 3.1 Variables which appear in a LUMPREM2 input file. Variables are real numbers unless
stated otherwise.
Variable Role
maxvol The volume of the upper soil moisture store. This must be greater than
zero.
irrigvolfrac The fractional soil moisture volume which irrigation water must
maintain. See documentation of LUMPREM for more details.
maxvol_br The volume of the lower soil moisture store. Set this to zero (or omit this
variable altogether) to disable the lower soil moisture store.
extravol_br The rate of drainage of moisture from the lower soil moisture store is
calculated using v/vmax, where v is the current moisture volume and vmax
is the maximum soil moisture volume (i.e. input variable maxvol_br).
However, the lower soil moisture store does not overflow until it reaches
a level of maxvol_br + extravol_br. Extravol_br must be set to zero or
greater.
rdelay The delay, in days, between water draining from the upper soil moisture
store (calculated using equation 2.1) and being assigned to either
groundwater recharge (if the lower soil moisture store is absent) or as
inflow to the lower soil moisture store. This is a real number; it can
include fractional days.
mdelay The delay, in days, between water leaving the upper soil moisture store
(calculated as overflow of this store up to a maximum rate of mflowmax)
and being assigned to macropore groundwater recharge. This is a real
number; it can include fractional days.
10
The LUMPREM2 Input File 11
elevmin Outcomes of equation 2.4 are clipped at this value if they are below it.
This variable is optional.
elevmax Outcomes of equation 2.4 are clipped at this value if they are above it.
This variable is optional.
vol The initial volume of water in the upper soil moisture store.
vol_br The initial volume of water in the lower soil moisture store. This variable
can be omitted if maxvol_br is not supplied, or is supplied as 0.0.
nrbuf The number of elements of the rbuf array to be supplied on the next line.
This is an integer variable.
nmbuf The number of elements of the mbuf array to be supplied two lines
down. This is an integer variable.
(rbuf(i), i=1,nrbuf) The recharge delay buffer. Supply initial values for the elements of this
array. The content of the first element is assumed to have left the soil
moisture store on the previous day; the content of the second element
is assumed to have drained from the soil moisture store two days
previously, etc. All elements of this array must be recorded on a single
line of the LUMPREM2 input file.
(mbuf(i), i=1,nmbuf) The macropore recharge delay buffer. Supply initial values for the
elements of this array. The content of the first element is assumed to
have left the soil moisture store on the previous day; the content of the
second element is assumed to have left the soil moisture store two days
earlier, etc. All elements of this array must be recorded on a single line.
nstep The number of steps into which each day is subdivided for the purpose
of iterative soil moisture store computation. This is an integer variable.
mxiter The maximum number of iterations per time step. LUMPREM2 accepts
the calculated value of soil moisture store after this many iterations have
elapsed, regardless of whether the solution process has converged to
the desired tolerance. This is an integer variable.
11
The LUMPREM2 Input File 12
noutdays The number of days for which LUMPREM2 output is required (equivalent
to the number of times that LUMPREM2 calls the RECHMOD subroutine
– see documentation of the original version of LUMPREM). This is an
integer variable.
(outday(i), An integer array with noutdays elements listing the simulation days at
i=1,noutdays) which output is required. If desired, elements of this array can wrap onto
ensuing lines.
vegfile The name of the “vegetation file” which LUMPREM2 must read to obtain
crop factor and data. Alternatively, time-invariant values of the crop
factor and gamma (in that order) can be read from this line. See
documentation of LUMPREM for the format of the vegetation file.
rainfile The name of the “rainfall file” which LUMPREM2 must read to obtain
rainfall data. See documentation of LUMPREM for the format of this file.
epotfile The name of the “evaporation file” which LUMPREM2 must read to
obtain potential evaporation data. The contents of this file are applied to
the upper soil moisture store. See documentation of LUMPREM for the
format of this file.
irrigfile The name of the “irrigation file” which LUMPREM2 must read to obtain
irrigation data. Alternatively, time-invariant values for the irrigation code
and groundwater extraction fraction (in that order) can be read from this
line. The irrigation code is an integer (zero or one), while groundwater
extraction fraction is a real number. See documentation of LUMPREM for
the format of the irrigation file.
epotfile_br If maxvol_br is greater than 0.0 (indicating the presence of a lower store),
then either the name of a “potential evaporation” file must be supplied,
or a single value for potential evaporation must be supplied (i.e. the
variable epot_br_all). If epot_br_all (a real number) is supplied, then this
rate of potential evaporation is applied during every simulation day;
often this rate is 0.0. If supplied, file epotfile_br employs the same format
as epotfile for recording of daily rates of potential evaporation. See the
LUMPREM manual for details.
ssffile The name of the site sample file which LUMPREM2 must write. This is
supplied only if a “site sample file” section is present in the LUMPREM2
input file.
12
The LUMPREM2 Input File 13
starting_date The date at which the LUMPREM2 simulation begins. Supply this date
using the protocol provided with date_format.
starting_time The time of day at which the LUMPREM2 simulation begins. This time will
comprise the third entry of all lines of the LUMPREM2-produced site
sample file. The protocol is hh:mm:ss.
numssfser The number of time series to record in the site sample file; hence the
number of lines to follow. This is an integer.
ssfsername This is the “site name” that will be attributed to the time series in the site
sample file which LUMPREM2 records. LUMPREM2 insists that this name
be 15 characters or less in length, and does not contain a space.
Optionally it can be surrounded by quotes.
minval_ssf LUMPREM2 clips time series elements from below at this number before
recording them in its site sample output file.
maxval_ssf LUMPREM2 clips time series elements from above at this number before
recording them in its site sample output file.
13