How to use APSIM SWIM
Table of Contents
Introduction
What is APSIM SWIM?
APSIM SWIM is the result of adapting SWIM Version 2.0 to communicate with APSIM.
SWIM (Soil Water Infiltration and Movement) is a soil water and nutrient balance model written by P. J. Ross of C.S.I.R.O. Division of Land and Water.
APSIM (Agricultural Production Systems Simulator) is a cropping systems modelling environment specially designed to
allow a plug-in-pull-out approach for the integration of various simulation
models. It is a product of the Agricultural Production Systems Research Unit (APSRU).
APSIM SWIM is designed to run within APSIM and calculate all flows of water and nutrients through, in, and out, of soil
for a given simulation. These flows include infiltration, runoff, plant uptakes, movement through soil, etc, and the related nutrient flows.
Back To Top
How does SWIM operate within APSIM?
To simultaneously solve the water flow equations SWIM increments its way through time using time steps small enough to
allow the solution of its equations within given tolerance levels. APSIM uses a fixed time step, usually one day in duration. For these two approaches
to exist together SWIM is forced to perform its equations for a time frame within the current APSIM time step. As
APSIM cycles through all the active modules, allowing each to perform its own time step processes, SWIM will be allowed, during its own process step, to
(including infiltration, runoff, drainage, and crop water uptake) and all solute flows (including solutes in infiltration, uptake of all solutes by all
crops in the system). Transformational flows of solutes, such as with nitrogen, will take place on a daily time step in the module that owns that variable,
such as the soil nitrogen balance.
Back To Top
Initialisation
APSIM SWIM uses the standard APSIM input file capabilities and structure. Please refer to the
APSIM documentation for specifics on the formatting of APSIM input files.
Back To Top
The APSIM SWIM Parameter File
The structure of an APSIM SWIM data set is shown on the following page. There are a series of
predefined sections containing related data. The structure shown here could be reproduced many times within one file
as each data set lies within the one logical grouping of data sections.
Back To Top
Configuration Section
The main section of the APSIM SWIM parameter file(s) is the configuration section. Contained in
this are all configuration switches, for specifying all SWIM sub-models, and descriptions of the soil
profile required for model initialisation.
sample.apswim.init
! ---- initial layer information ----
!-----------
! 1 2 3 4 5 6 7 8 9
!-----------
x = 0.0 50.0 100.0 300.0 500.0 750.0 1000. 1600 2000 (mm)
soil_type = soil1 - - - - - - - soil2
psi = -1500 -1500 -1500 -1500 -1500 -1000 -1000 -1000 -500 (cm)
!-----------
slmin = -3.0 () ! slmin and slmax are the minimum and maximum
slmax = 7.0 () ! log suction values used for specifying
! moisture characteristic and hydraulic
! conductivity curves in the soil descriptions
bypass_flow =on (on/off) ! Bypass Flow - On/Off
!
runoff = 2 () ! Runoff Flag - 0) No ponding (all runoff)
! - 1) All ponded (no runoff)
! 2) Use runoff functions
!
top_boundary_condition = 2 () ! Surface Flag - 0) infinite surface conductance
! -- 1) constant potential
! 2) conductance function
!
bottom_boundary_condition = 0 () ! Bottom Flag - 0) constant gradient
! - 1) water table
! 2) zero flux
! 3) free drainage (seepage)
vapour_conductivity = off (on/off) ! Vapour Conductivity flag (0=off, 1=on)
! ----
run_solutes = br cl no3 ! List of solutes SWIM is required to move.
solute_exclusion = on (on/off) ! switch to specify if solute in soil water is
! taken in excess of the crop solute demand.
extra_solute_supply = on (on/off) ! switch to specify if extra solute, above that
! received in the extracted soil water, is to taken
! up using a simple empirical method)
echo_directives = on (on/off) ! choice to echo the receipt of directives such
! as irrigation or tillage.
The SWIM module contains many components and sub-models that can be specified to behave in different ways.
Examples of this may be the equations for runoff or behaviour at the top and bottom soil boundaries. Switches for these are
contained in the main model configuration section above and the in-line documentation in the example above explains the
meaning of each one.
When configuring APSIM SWIM one is required to specify all solutes to be redistributed within the APSIM
simulation. To do this we specify, in this section, the names of all solutes that are to be moved (referred to above as
“run_solutes”). APSIM SWIM will then find out the states of each of these pools and communicate with their owner modules.
Some modules may potentially own solutes that will play no part within the simulation. The user is informed during
initialisation, via the summary file, of any solutes owned by individual modules that are not included in the list of
"run_solutes". The user can decide if any of these should also be added to the list of solutes to be
parameterised and used by APSIM SWIM. The user can alternatively choose to have no "run_solutes" by
setting the parameter to "none".
The soil profile specification (at the beginning of the section - though order is not important) describes
the nodal structure for the current simulation and the soil type at each of these nodes. Each soil type is referred to by
a unique user-defined name. The user can also specify a gradual change in soil type from one node to another by not
defining nodes between them. A single dash (“-”) is used for this purpose. The above example will linearly interpolate,
according to depth, the soil for each node so that the soil properties will gradually change from soil type one at the
surface to soil type two at the bottom boundary. The actual properties of each soil type are described in a soil
specification section for each soil type. The name for each section is the same as the unique name given in the
soil profile description above.
The parameters extra_solute_supply and solute_exclusion allow the user to specify
the response to situations where total uptake of solute does not match the solute demand of the crop.
Extra solute can be excluded or taken up empirically,
depending on the situation. This functionality is not part of the original SWIMV2 model but has
been included to allow flexibility in responses to crop modules depending upon APSwim for uptake
of solutes. The specification of these parameters is optional and default to “off”.
The last parameter, echo_directives, is used to verify the communications between
APSwim and other modules within APSIM. If this value is set to on, all tillage and application of
surface water messages will be reported to the screen and to the simulation summary file.
Back To Top
Soil Type Description Sections
For SWIM to calculate all water and solute movements it needs to know certain
soil-water and soil-solute relations. This information is given as follows:
! -----soil type information -----
sample.apswim.soil1
sl = -3.000000 0.400000 1.000000 1.386233 1.538325 4.355526 7.000000 ()
wc = 0.255000 0.254882 0.253123 0.243884 0.232800 0.078951 0.028610 (cc/cc)
wcd = -0.000000 -0.000545 -0.008644 -0.051190 -0.089358 -0.030304 -0.010982 ()
hkl = -0.551294 -0.554319 -0.599416 -0.841595 -1.144555 -8.187840 -14.799289 ()
hkld = -0.000000 -0.013938 -0.222431 -1.367128 -2.500100 -2.500100 -2.500100 ()
bulk_density = 1.0 (g/cc)
! -----
solute_name = cl br no3 ()
!-----
exco = 0 0 0 ()
fip = 1 1 1 ()
dis = 0 0 0 ()
!-----
sl is log suction where suction has units of cm. For each value of sl there are corresponding values
of volumetric water content (wc). These values define a series of points on the moisture characteristic curve for
this soil type. SWIM uses these points to interpolate all values on this characteristic curve using piece-wise cubic
approximations. To enable this we must also supply the slope of the moisture characteristic curve at each of these
points as well (wcd). wcd is the derivative of the log suction vs water content curve at this point. A similar
approach is used for the specification of the hydraulic conductivity curve. Here log hydraulic conductivity (hkl)
(conductivity in units of cm/h) is supplied as well as the corresponding slope (hkld). These soil characteristic
curves can be specified using the HYPROPS program.
Solute-Soil interactions are specified for each solute in a separate table. For each solute SWIM requires:-
exco - freundlich exchange isotherm coefficient
fip - freundlich exchange isotherm power term such that adsorbed concentration = exco xsolute_concfip
dis - is the dispersivity of the solute in the soil.
Bulk Density is to be expressed as g soil per cubic centimetre.
Back To Top
Solute Specific Information Section
There are some solute parameters required by SWIM that are not related to soil type but are only specific to a particular solute.
! ---- solute information -----
sample.apswim.solute
! ------
solute_name = cl br no3
! ------
slupf = 0 0 1
slos = 0.001 0.001 0.001
d0 = 0 .072 0
a = 0 1 0
dthc = 0 0 0
dthp = 1 1 1
disp = 1 1 1
ground_water_conc = 0 0 0 (ppm)
! ------
slos is defined as the
osmotic pressure per unit solute concentration. (NOTE: All solute
concentrations are expressed as ppm. ie. µg solute per g water)
d0 is the diffusion coefficient.
Tortuosity is calculated with SWIM as:
a. (theta - dthc)dthp
where theta is volumetric soil water content.
Hydrodynamic dispersion is:
dispersivity. |velocity|disp
where dispersivity is the value of dis given for each soil type.
Ground water concentrations are specified for use during simulation whenever the bottom boundary condition is set to allow water entry via the
bottom of the profile.
Back To Top
APSIM SWIM Calculation Parameters
! ---- swim calculation parameters ---
sample.apswim.calc
dtmin = 0.0 (min) ! min time step
dtmax = 1440. (min) ! max time step
dtmax_sol = 60 (min) ! max time step during solute uptake
max_water_increment=1. (mm) ! max water increment
slcerr = 0.000001 () !
ersoil= 0.000001 () !
ernode= 0.000001 () !
errex = 0.01 () !
dppl = 2 () !
dpnl = 1 () !
swt = 0.0 () ! Space Weighting Factor (gravity flow)
! -------
! 0.5 -> 1.0 (central to fully upstream)
! < -1 (central diffs by factor of -1*SWF)
slswt = 0.0 ()
The only point of note for this section that is not covered in the SWIMV2 documentation is the parameter dtmax_sol.
This parameter was not part of the original SWIMV2 but works in tandem with the crop-solute interaction parameter,
solute_exclusion (included in the “init” section). This maximum timestep specification determines the maximum
timestep allowable when the solute_exclusion flag is set to true and there is a non-zero crop solute demand
for the current APSwim timestep. Specifying a small maximum timestep forces APSwim to work slowly through time whilst
solute demand is not satisfied, thus minimising the magnitude of any over-supply of solute as calculated via the flow
of solute with soil water extraction. Once the supply of solute is met this extra constraint is removed and the
normal maximum timestep (dtmax) is used. These two timestep constraints allow for differing levels of precision
depending upon the processes taking place.
Back To Top
Climatic Inputs Section
At present there are three climatic inputs - soil albedo and the rainfall and potential evapotranspiration
data sources. If the user specifies either source as "file" they will then
need to provide a file name (see example below). If these files are to be found in a directory other than the current directory then a full file name
including path will be required.
The user can also direct apswim to get rainfall and
evaporation information from other modules within APSIM, such as the input
module, by simply typing in the name of the variable to use for that data (e.g.
'rain' or 'pan' from met module).
The user can also direct apswim to calculate evaporation data from daily meteorological data. This is achieved
by using the keyword “calc” for the evaporation data source.
! ---- climatic inputs -----
sample.climate
salb = 0.23 ()
rainfall_source = rain () ! use apsim
variable called 'rain'
evap_source = calc ()
! calculate own potential evaporation rate
or
sample.climate
salb = 0.23 ()
rainfall_source = file () ! get rainfall
from a file
rainfall_file = c:\work\myrain.dat
evap_source = file ()
evap_file = c:\work\myevap.dat
Back To Top
Runoff Functions Section
As explained in the configuration section information earlier the runoff sub-model can be configured as follows:-
runoff = 2 () ! Runoff Flag - 0) No ponding (all runoff)
! --- 1) All ponded (no runoff)
! 2) Use runoff functions
If the user chooses option number two then runoff functions are to be used for the calculation of runoff. In this case,
extra information needs to be supplied to APSIM SWIM and this is to be placed in the runoff section.
! ---- runoff functions ----
sample.apswim.runoff
maximum_surface_storage = 20 ! (mm)
minimum_surface_storage = 10 ! (mm)
initial_surface_storage = 15 ! (mm)
precipitation_constant = 50 ! (mm)
runoff_rate_factor = .2 ! (mm/h)/mm^P
runoff_rate_power = 2 ! =P __/
Runoff occurs when the surface water depth is greater than the surface storage. For a water depth that is dH above the
storage, the runoff rate is equal to
Runoff Rate = Runoff Rate Factor . dHP
To allow for a reduction of surface roughness due to rainfall, the storage decreases exponentially with precipitation
energy from the given initial value towards the given minimum. The equation for the exponential decrease in storage is of the form
S = Smin + (Sinitial -
Smin).exp(-E/Espc)
where E is cumulative rainfall energy and Espc is energy in an amount of rain equal to the given storage
precipitation constant falling at 25mm/h.
The user can specify the initial surface storage available to rainfall as any value between the maximum and minimum
surface storages.
Back To Top
Bottom Boundary Conditions Section
There is only one parameter required for one of the possible settings for bottom boundary conditions. If the user
chooses to set a constant gradient for the bottom boundary then it is input as follows.
! --- bottom boundary conditions ----
sample.bottom_boundary
constant_gradient = 0
or
constant_potential = 0
If the user chooses zero flux then no inputs are required from this section.
If a the bottom boundary is to be a user defined potential (eg water table is said to exist at the
bottom boundary) then constant potential will need to be supplied in this section.
If the user wishes to enforce a constant gradient at the base of the profile then this parameter
needs to be specified.
If the user specifies free drainage at the bottom boundary then a value for a constant potential is
required to describe the flow at the bottom of the profile.
Back To Top
Top Boundary Conditions Section
The
soil may have a thin surface layer that impedes water entry. The water flux through this layer is equal
to the surface conductance multiplied by the matric potential difference across
this layer. A soil layer of thickness
dx and saturated hydraulic conductivity Ks would represent a conductance
of Ks/dx at saturation.
To allow for a reduction of surface conductance due to formation of a crust caused by rainfall, the conductance
decreases exponentially with cumulative precipitation energy from the given initial value towards the given minimum.
! --- top boundary conditions ---
sample.apswim.top_boundary
maximum_conductance = 4.0 (/h) ! initial soil surface conductance
minimum_conductance = .02 (/h) ! minimum soil surface conductance
initial_conductance = 1.0 (/h) ! initial soil surface conductance
precipitation_constant = 2.5 (mm) ! used to define rate of surface sealing
The equation for the exponential decrease in conductance is of the form
G = Gmin + (Ginitial - Gmin).exp(-E/Ecpc)
where E is cumulative rainfall energy and Ecpc is energy in an amount of rain equal to the
given conductance precipitation constant falling at 25mm/h.
Back To Top
Bypass Flow Section
If bypass flow has been enabled, within the initialisation section, the following parameters need to be specified.
! ---- bypass flow -----
sample.apswim.bypass_flow
depth = 4 ! (node number)
conductance = .10 ! (/h)
storage = .10 ! (cm water/cm of +ve Psi)
Depth is, of course, the macropore depth within the soil profile. It is expressed in terms of node number.
Back To Top
Crop Parameters Section
sample.apswim.crop
! ----------
crop_name = wheat barley maize
! ----------
min_xylem_potential = -15000. -15000. -15000. (cm)
root_radius = 0.25 0.25 0.25 (mm)
root_conductance = .4d-7 1.4d-7 1.4d-7 (cm3/h)
! -------------
At present the only crop specifications required from the user are the minimum xylem potential,
root radius and root conductance for particular crops. Other day-to-day values such as soil water demands and
root distribution are provided by APSIM during the simulation run.
Back To Top
Rainfall and Potential Evaporation Data
As chosen by the user(see climate data specification section above), APSwim allows two methods
of supplying specified rainfall and potential evaporation data.
The first method utilises the APSIM inter-module communications. In this simple approach, the
data for rainfall or evaporation is described as one homogeneous event. An amount, a starting time and a
duration or intensity is obtained via a general request of all modules for this information just prior to
processing the timestep calculations. This information is generally described in the APSIM weather file as
follows. The values returned to APSwim have been highlighted. In this example rainfall will always fall at
an intensity of 15 mm/h starting at 3:00 p.m. and 5 mm of potential evaporation is said to lie between 6:00
a.m. and 6:00 p.m. each day. Alteratively the rainfall could be said to alway fall between 3:00 p.m. and 4:00
p.m. by using the alternative suggested below.
user-defined..nput.weather
site = Gatton
latitude = -27.0 (degrees)
rain_time = 15:00 (hh:mm)
rain_int = 15.0 (mm/h) (or rain_durn = 60 (min))
eo = 5 (mm)
eo_durn = 720 (min)
eo_time = 6:00 (hh:mm)
year day radn maxt mint rain
() () (MJ) (oC) (oC) (mm)
1995 1 20.0 25.0 15.0 5
1995 2 20.0 25.0 15.0 0
1995 3 20.0 25.0 15.0 10
1995 4 20.0 25.0 15.0 0
The second method uses a simple data log file. At the present stage of development APSIM
SWIM uses a fixed format input file structure for rainfall and potential evaporation data. Later releases
will contain more flexible and more powerful mechanisms for the input of this data.
The input format for rainfall is as follows:-
1991 121 00:00 5. 6
1991 122 00:00 20. 120
1991 122 2:00 10. 600
1991 129 14:00 25. 600
The columns, from left to right, contain year (4 digit specification), day of year, time (24 hour
notation), amount of rainfall, and the time duration* for this record. For example the first line records an event
at 12:00 am on the 121st day of 1991 in which 5 mm fell in 6 minutes. The last line records an event in which 25
mm fell at 2:00pm on 129th day of 1991 and lasted for 10 hours. Evaporation data follow the exact same format.
* Time duration has highest resolution of 1 min.
Back To Top
Irrigation Data
There are two ways of accessing the one mechanism for application of irrigation. APSIM SWIM
responds to a low level “add_water” message. The format of this is:-
apswim add_water amount=20(mm), time=12:00(hh:mm), duration=60 (min),
intensity = 20 (mm/h), no3=10.0(kg/ha)
(Note: implementation would require text on a single line)
This message tells SWIM that 20 mm of irrgation is to be added at midday today. The irrigation
takes 60 minutes to complete and ten kg/ha of nitrate was in that irrigation water. SWIM will then incorporate
all this information into its cumulative water and solute addition with time curves. Any combination of amount,
duration and intensity information will suffice as long as an overall amount and duration can be calculated from
the information given. The APSIM system’s manager or operations manager modules will allow the user to set up
various irrigation schedules using this message format.
However, the APSIM system also contains an irrigation module that has added features such
as automatic irrigation rules and tabular input format. It is highly recommended that users apply irrigation
using the IRRIGATE module. This module will convert the irrigation information into the necessary format for
APSIM SWIM. See documentation of these modules for further assistance.
Back To Top
The effects of cover upon the water balance
Potential Soil Evaporation
The algorithm for
cover effects on potential soil water evaporation is taken from that derived
for the soilwat2 module.
Where
Ep is total potential evapotransipiration
Canopy_coeff is a coefficient for the effect of canopy cover on potential soil water evaporation
Residue_coeff is a coefficient for the effect of residue cover on potential soil water evaporation
Back To Top
Effective Rainfall Energy
Surface residues are said to protect the soil from rainfall energy by shielding the soil surface
from rainfall impact according to the level of residue cover.
Where
rKE is a measure of the energy in an amount of precipitation
if intensity I compared with that of the same amount of precipitation of intensity Ir.
Eff is an efficiency parameter
Coverresidue
is a 0 to 1 measure of surface residue cover.
Back To Top
Water and Solute flows for bottom boundary conditions in SWIM
The following describes the flow of water and solutes across the bottom boundary for the four
boundary conditions supported by the SWIM model. The relevant flow equations are as follows
Richards' Equation
- See equation 4 in Swimv2.1 manual
or
Advection-dispersion equation
- See equation 50 in Swimv2.1 manual
or
See the SWIMv2.1
User manual for more information and definitions of terms.
We shall now look
how the elements of the flow equations above are calculated for the four
different bottom boundary conditions.
Back To Top
Specified matric potential gradient
Water Flow
The flow equations for water in the profile are solved with the matric potential gradient term, shown in the
Richards equation above, set to the user specified value at the lowest node in the profile. The actual value
of the matric potential (ψ) may vary in time but that same gradient will apply until it is changed by the user.
- If the matric potential gradient is set to zero then drainage will proceed simply due to gravity
(δz/δx which is usually 1). This is often referred to as a unit (hydraulic) gradient. Flow can only
proceed downward, at the rate of the hydraulic conductivity.
- If the matric potential gradient is set to -gravity (ie -1) the net results is one of zero flux.
- If matric gradient is negative (and greater than gravity,ie <-1) then water will pushed up into
the profile. Note that, unless the user changes the gradient, the bottom boundary potential will continue to rise
indefinitely until ultimately upward flow was offset by runoff!
- If matric gradient is positive then water will be drawn down out of the profile. Once again, unless
the user alters the gradient, the potential of the lowest node will move toward extremely dry conditions.
Solute Flow
The solute flux calculations for the deepest soil node differ slightly to that for the rest of
the profile. As knowledge of space effectively ceases past this node, swim makes no assumptions regarding
diffusion or dispersion. As can be seen in the equations above, dispersion calculations would require some
assumptions regarding the spatial gradient of solute concentration. As a result, only convection is calculated
for the bottom boundary. The solute concentration in the water flowing across the bottom boundary in either
direction is dependant on the direction of water flow. Thus:
- If the water flow is downward, solutes will progress down across the deepest node. Once solute has passed the
node it cannot return to the profile. Bulges may move across this node, but as we calculate convection only for
this node the concentration gradient, or shape of the bulge, is not considered at this node.
- If the water flow is upward then it is assumed that the solute concentration in the water entering the profile
is the same as the specified ground water concentration. This will act as a supply of solute into the profile
in the same manner as the user-specified potential boundary condition below.
Back To Top
User-Specified potential
Water Flow
The flow equations for water are solved with the potential (hydraulic head = sum of matric and
gravity components) specified within the solution. This matric potential is specified by the user in the input
file for SWIMv2.1. In APSIM SWIM the potential is set initially and can be manipulated at run-time via the
APSIM manager. The potential gradient above this node will fluctuate through time due to the influence of this
fixed potential and the nodes above. This boundary condition is often used for the simulation of the entry of
water tables into the section of the soil profile being modelled.
- If the potential is zero or positive then there is effectively a water table entering the base of
the profile. The magnitude of the potential would represent the height of water above the lowest node. Increasing
this potential does not instantly 'flood' the soil to this height. It may take some time, depending upon the soil
properties, for the upward flow to achieve this and for the soil to equilibrate. Similarly, it may take some time
for drainage if there is any decrease in the specified potential. Note that drainage will still occur during the
presence of the water table. Any infiltration that may tend to increase the height of the water table will cause a
subsequent drainage such that the specified water table height is maintained.
- The flows of water across the bottom boundary for a negative boundary condition are similar to the
case above. This boundary condition may perhaps be used for situations where a water table is known to drop a little
below the specified profile, provided the conductivity is not too low.
Solute Flow
- In situations where the bottom boundary potential is maintained it is assumed that the solute concentration
of the water at that boundary is also maintainedIf the potential is zero or positive then the solute concentration of the
deepest node is maintained at a constant concentration. In APSIM SWIM this concentration is the concentration of solutes in
ground water. In SWIMv2.1 the concentration is held at the value, csl(n), specified by the user in the input file. This
represents the fact that the ground water has entered the profile. It is assumed that the solute concentration within the
ground water is spatially homogeneous. Any water that enters the profile from the ground water will contain solutes at this
given concentration. The solute concentration within water draining out of the profile will be determined via the normal
solute flux calculations. Note that if the bottom boundary is changed to such a condition there will be a sudden change to
the solute balance as solute is removed or added (over the time step) to the deepest node as the new concentration is
applied.
- If the potential is negative the solute concentration is held constant as described above. In this case
though, the user will have to decide on the possible implications of the behavior of the solute balance at this base
node.
Back To Top
Zero flux
There is no flux of water or solute across the bottom boundary when using this boundary condition. The
flow equations are solved with the flux term at the base of the profile set to zero. The matric potential and potential
gradients will fluctuate due to the influence of higher nodes. Water may pond above this boundary. Solutes will move in
response to the water flows and concentration gradients. No special conditions need to be considered by the user.
Back To Top
Seepage with threshold suction
The seepage boundary condition acts as a combination of the zero flux and constant potential boundary conditions.
This condition is useful for simulating the operation of some field and laboratory apparatus or the effective functioning of
particular boundary interfaces (e.g. drainage into gravel).
Water Flow
If the potential at the deepest node is below a critical value specified by the user then the water balance calculations
are identical to the zero flux bottom boundary condition. No flux will occur out of the profile until the potential at the deepest node
has reached the user-defined value. When the potential does reach the user-defined value the boundary condition changes to follow the
behaviour of the "user-specified potential" condition. The flow equations are solved with the potential of the deepest node
set to the specified value. No upward flux can occur.
- If the specified potential is zero or positive then
drainage will not occur until the water table within the profile reaches the
described height. This condition can be
used to simulate apparatus where water tables can build up to a maximum height.
- If the specified potential is negative then water is
removed from the profile until the deepest node equilibrates with the applied
suction. This can be used to simulate
core experiments where the base of the profile has an applied suction.
Solute Flow
Solute flows across the bottom boundary follow those for water. As implied by the nature of the boundary condition,
there can be no dispersion for flux of solutes out of the profile (the profile is discontinuous at this point). Fluxes out of the
profile, therefore, are calculated using convection only.
- If the specified potential is zero or positive solute will accumulate at the base of the profile as is the
case for the accumulation of the perched water table. When drainage does occur, the solute concentration of the drainage
water will equal that of the water at the deepest node.
- If the specified potential is negative then solute will be extracted with the soil water until the soil
equilibrates. The absence of the dispersion term will lead to the extraction of water from the profile being 100% efficient
at removing the solute in that water. Once again, the concentration of solute in drainage water will equal that of the water
at the deepest node.
Back To Top
Responsive Water Table
The responsive water table condition acts like a water table
with a user-specified level of "responsiveness", where responsiveness refers to
the time required for the water table depth to equilibrate with the piezometric
pressure.
This condition is useful for simulating the situations where local management
might temporarily alter the effective water table depth. For example,
irrigation might temporarily raise a water table or plant water use might lower
a water table from that which would correspond to the ground water pressure.
Water Flow
Water flow (in or out) is calculated based upon the difference
between the piezometric pressure and the actual pressure at the base of the
profile. If the pressure is above the ground water pressure, water will flow out
of the profile. If the pressure is below the ground water pressure, water
will flow into the profile. The rate of water flow is calculated as
follows:
q = (W - (ψ-X)) x gw
where q is flow at the base of the profile, W is the depth to
ground water, ψ is pressure head at the bottom of the profile, X is the depth to
the bottom of the profile and gw is a ground water table
"conductance". gw has units of per hour. Therefore, a
value of 1 would provide an flow of 1 cm per hour for every cm of pressure
difference at the base of the profile. This same calculation is used to
provide flows of water into or out of the profile. The sign of the
pressure difference term will dictate the direction of flow.
Solute Flow
Solute flows across the bottom boundary follow those for water. As implied by the nature of the boundary condition,
there can be no dispersion for flux of solutes out of the profile (the profile is discontinuous at this point). Fluxes out of the
profile, therefore, are calculated using convection only.
- In situations where a water table is maintained it is assumed that the solute concentration
of the water at the bottom of the profile is also maintained at a constant
concentration. In APSIM SWIM this concentration is the concentration of
solutes in ground water. It is assumed that the solute concentration
within the ground water is spatially homogeneous. Any water that enters the
profile from the ground water will contain solutes at this given
concentration.
- The solute concentration within water draining out of the
profile will be determined via the normal solute flux calculations (convection
only).
Back To Top
Runtime alterations to the bottom boundary condition
The user can change the bottom boundary condition and/or value at runtime via the setting of the state of the
bottom boundary condition at any time via the messaging system. The following manager code will change the bottom boundary
to a water table for five days before reverting to a constant gradient at the end of this period.
If day = 1 then
Apswim.bbc_potential = 50
Elseif day = 6 then
Apswim.bbc_gradient = 0
Endif
In this example days 1 to 5 will have a water table 50 cm above the bottom of the soil profile. Day
6 will be the start of a gradual drainage event out of this state. Currently, these are the only two boundary condition
state changes supported for alteration at runtime.
Back To Top
Subsurface Flows
Subsurface Drains
The flux of water and solutes into subsurface tile drains can
be calculated using a formulation of the Hooghoudt equation as utilised in the
DrainMod model.
The basic geometry of the system is as follows:
The flow into the drain (q) is calculated
q = (8.0 Ke de m + 4Ke m2)/L2
where Ke is the effective lateral conductivity of
the soil profile, m is the height of the water table above the drains, d is the
height of the drains above the impermeable soil horizon, L is the drain spacing,
r is the drain radius and de is the effective depth of impermeable
soil horizon which takes into effect the convergence near to the drains. de
is calculated as:
de = L*π/(8 log (L/r) - 1.15) , where d/L >= 0.3
de = d/(1.0+d/L*(8π log (d/r) - α)),
where d/L < 0.3, α = 3.55 - 1.6(d/L) + 2(d/L)2
The user specifies the system via input parameters for the
various aspects of the geometry as follows:
sample.apswim.drain
drain_depth = 1000. (mm)
! depth of the drain below the soil surface
drain_spacing = 30000 (mm) ! distance
between subsurface drains
drain_radius = 50 (mm)
! radius of each tile drain
Klat = 1000. (mm/d)
! lateral conductivity
imperm_depth = 3000.
! depth of the impermeable soil profile below the soil surface
Back To Top
APSIM SWIM Interface
Crop Interface to APSIM SWIM
All uptake of water and/or solutes by crops is handled by SWIM. The uptake of these substances in
built into the SWIM flow equations. Competition between crops for resources such as water and solute is intrinsic
to the solution of the flow equations and APSIM takes full advantage of this. Competition of other resources such
as light must be allowed for in another module. Such modules are currently available within APSIM.
The crop module must also have been created from a
template that allows for uptake calculation external to the module.
To enable SWIM to calculate crop uptakes each crop must be
able to provide
| |
Name |
Units |
Description |
| |
crop_type |
- |
name of crop type eg. wheat (not module name) |
| |
sw_demand |
mm |
potential plant transpiration |
| |
nnnn_demand |
kg/ha |
crop solute demand (where nnnn is the solute name) |
| |
cover_tot |
0-1 fraction |
total crop cover |
| |
rlv |
mm/mm3 |
root length volume (on a layer basis) |
|
With this information SWIM will calculate the uptake of water and all solutes for each crop. These are
available to the crop using the uptake_nnnn_cccc variable as described in the output section. To be able
to provide information such as potential plant transpiration for the current APSIM time step the crops will need to
calculate these values in preparation for the time step (the PREPARE stage). Also, SWIM will have to be included in the
module list ahead of any crop or solute modules to allow SWIM to calculate ALL flows before the owner modules perform
their daily time step.
Back To Top
Solute Interface to APSIM SWIM
The interface between solute owner modules and APSIM SWIM is very simple.
The APSIM SWIM parameter file must contain the names of all solutes the user is wanting SWIM to
move for the current simulation. APSIM SWIM will then ask all modules for the states of these pools, as does
any other module requiring that information, and will receive that information via the standard message passing
system in APSIM. Only the amount of solute in each layer (kg/ha) is required. All movement parameters are included
in the APSIM SWIM parameter file. APSIM SWIM will notify the user if it has been parameterised to move solutes that
do not exist within the simulation, or if solutes exist for which it is not parameterised.
To receive back updated values of solute, after solute flows are accounted for by SWIM, the solute
owner module needs to be able to respond to the standard “SET” message. This should also already be implemented in
the solute owner module. The solute module does not need to provide any solute flow information.
As is shown, almost no effort is required to couple a solute module to APSIM SWIM.
NOTE: For those interested in the flow of simple solute tracers, without solute transformations, there
is a simple solute module within APSIM that will allow the addition of any solute into the APSIM modelling system.
Back To Top
APSIM SWIM module actions
Reset
The reset action can be invoked to reset the module to the
state specified within the module's input data, which includes the soil
moisture characteristics, runoff and boundary condition parameters and the
initial soil water profile. The Reset
action is identical to the initialise action used by the simulation engine at
the start of the simulation except that a description of the reinitialised
state is not printed in the simulation summary file.
APSIM Manager Example:
sample.manager.start_of_day
! reinitialise apsim swim at the beginning of each sowing window
If day = 100 then
apswim reset
endif
Initialise
The initialise action has now been replaced by the reset action (see above).
Summary Report
At initialisation, at series of tables and useful information is printed to the simulation summary file for perusal by
the user. These tables can be printed to the summary file at any point during the simulation as a detailed record of the
system state at a particular time.
APSIM Manager Example:
sample.manager.start_of_day
! Print out a summary of module state to the summary file
If day = 100 then
apswim sum_report
endif
Back To Top