xswms2d {SoPhy}R Documentation

Modelling of water flux and solute transport

Description

Interactive surface that is used to define a soil profile and to give the physical and chemical properties for each horizon. It simulates the water flux and solute transport using swms2d by J. Simunek, T. Vogel, and M.Th. van Genuchten.

Usage

sophy(...)

xswms2d(h, xlim, ylim, step, picture=NULL,
  water=list(
    TPrint=500, red=4, print=7, mesh=TRUE, lim.rf = 1,
    lim.swms2d = 1, 
    TolTh=0.0001, TolH=0.01, lWat=TRUE, dt=1, dtMinMax = c(0.01, 60),
    max.iteration=1000,  max.iter.prec=50000,
    iter.print=100, breakpoint=100,
    top.bound=2, top.value=0, bottom.bound=1, bottom.value=0
  ),
  materials=list(
     thr=.02, ths=0.35, tha=0.02, thm=0.35, Alfa=0.041, n=1.964,
     Ks=0.000722, Kk=0.000695, thk=0.2875,
     first=1, second=1, angle=0, 
     Hslope=0, Hseg=-100, POptm=-25, sharpness=1, 
     Bulk.d=1500, Diffus=0, longiDisper=1, transvDisper=0.5,
     Adsorp=0.0004, SinkL1=-0.01, SinkS1=-0.01, SinkL0=0, SinkS0=0
  ),
  Hinit = function(Hseg, depth) Hseg,
  model=list(model="exp", param=c(0, 0.25, 0, diff(ylim) * 0.1)),
  anisotropy=NULL,
  miller.link=function(rf) exp(sign(rf) * sqrt(abs(rf))),
  millerH = function(lambda) lambda, 
  millerK = function(lambda) lambda^-2, 
  millerT = function(lambda) 1,

  chemical=list(
     lChem=FALSE, Epsi=2, lUpW=1, lArtD=FALSE, PeCr=10, tPulse=500,
     top.bound=2, top.value=1, bottom.bound=1, bottom.value=0,
     root.uptake=0, intern.source=0
  ),
  
  atmosphere=list(
     AtmInf=TRUE, tInit=0, Aqh=-.1687, Bqh=-.02674,
     hCritS=1.e30, GWL0L=ylim[2], rLen=diff(xlim)
  ),
  atm.periods=1, 
  atm.data=c(
     end=100000000, prec=0, cPrec=0, rSoil=0, rRoot=0, 
     hCritA= 1000000, rGWL=0, GWL=0, crt=0, cht=0
  ),

  stone=list(
     value=NA, lambda=0,
     no.upper=FALSE, no.lower=TRUE, no.overlap=FALSE,
     main.distr=rnorm,  main.mean=diff(ylim)/20, main.s=diff(ylim)/400,
     sec.distr=rnorm, sec.mean=diff(ylim)/50, sec.s=diff(ylim)/400,
     phi.distr=rnorm, phi.mean=1, phi.s=0
  ),

  plant.types=1,
  Kf=function(plant, distances, depth, rf, 
              param=list(field.value=1, field.factor=0))
     rep(param$field.value, length(rf)) + param$field.factor * rf,
  beta=function(plant, distances, depth, rf, 
              param=list(beta.value=1, beta.factor=0))
    rep(param$beta.value, length(rf)) + param$beta.factor * rf,
  root=list(
     plants.lambda=0,
     plants.mindist=diff(xlim) / 20,
     mean=sqrt(diff(ylim) * diff(xlim)),
     sd=sqrt(diff(ylim) * diff(xlim)) / 5,
     knot.probab=0.1,
     knot.mindist = 5 * step,
     shoots.3=0.4, shoots.4=0,
     stop.probab=function(knot, dist, m, s) 1 - exp(-m + s * dist),
     stop.m=0, stop.s=0,
     rf.link=function(v, m, s){
               v <- s * v
               m * (exp(sign(v) * sqrt(abs(v))))^(-2)
             },
     rf.m=0, rf.s=0,
     no.own.root=TRUE, age.bonus=1.2, depth.bonus=5.2,
     side.bonus=5.1, diagonal=TRUE, dir.ch=3.71, dir.ch.s=0.5,
     rf.Kf=FALSE, P0=-10, P2H=-200, P2L=-800, P3=-8000, r2H=0.5,
     r2L=0.1, root.condition=3, root.uptake=-150
     ),
  root.zone = NULL,
  col.rf = NULL, col.simu = NULL,
  MaxIt=20, hTab=c(0.001,200), DMul=c(1.1, 0.33),
  col.rect="red", col.bg="yellow", col.sep="gray", col.left="red",
  col.mid="darkgreen", col.right="darkgreen", col.line="red",
  col.txt="black", col.submenue="darkgreen", col.subord="steelblue",
  col.forbid="gray88", col.bg.forbid="lightyellow", col.flash="blue",
  ## drawing configure CFLAGS="-O2 -Wall -pedantic"

  col.hor=c("#000000", "#996600", "#660000",  "#CC9933", "#666600",
            "#CCCC99", "#CCCCCC", "#990000", "#FFCC00", "#FFFFCC"),
  col.draw="green", col.mess="red",
  col.mesh="blue", col.mesh.pt="green",
  col.exception = c("brown", "lightgray"),
  cex.eval = 0.8,
  areas=is.null(h$picture), PrintLevel=RFparameters()$Print,
  new=TRUE, X11.width=9.5, X11.height=X11.width * 0.789,
  frequent.reset = TRUE, update=FALSE, waterflow=FALSE, 
  zlim = NULL, Zlim = NULL,
  print.par=list(ps="sophy", height=3, titl=TRUE, legend = TRUE)   
)

Arguments

h a list of the output format, see the Details. If h is given the parameters xlim, ..., col.simu are ignored.
xlim vector of two elements. The horizontal extension of the profile, see also picture. If diff(xlim) is not an integer multiple of step then xlim[2] is decreased suitably.
ylim vector of two elements. The vertical extension of the profile, see also picture. If diff(ylim) is not an integer multiple of step then ylim[2] is decreased suitably.
step numeric. the grid spacing for both directions. The finite element method is essentially based on a quadratic mesh.
picture array or file name for a digitised profile in tif or jpeg format; if picture is an array it must have three dimensions, where the third dimension has 3 or 4 components (RGB or RGBA format).
If picture is given then either xlim or ylim might be missing and is calculated from the other lim parameter and the dimension of the picture.
water {swms2d, water} list of the following components
TPrint {TPrint}
scale; modelling time after which the result is printed.
Note that for directly calls of create.waterflow and subsequent call of swms2d, TPrint might also be a vector, see read.swms2d.table for futher information.

red {size reduction}
positive integer. to increase the simulation spead the size of the finite element grid can coarsened

print {printed variable}
integer 1,...,6. One of the following spatial data sets can be plotted: the water potential H, discharge/recharge rates Q for internal sink/sources, the water contents theta, the x-components of the Darcian flux vector vx, the z-components of the Darcian flux vector vz, or the soulte concentration Conc. These variables are numbered consecutively form 1 to 6.

mesh {show FE mesh}
logical. If TRUE the currently used finite element mesh in a swms2d simulation is shown in the upper left drawing area.

lim.rf {upper quantile for random field plot}
numeric in [0,1]. The value of zlim[2] in image equals the lim.rf quantile of the random field values when the transformed random field is plotted.

lim.swms2d {quantile for swms2s plot}
numeric in [0,1]. See plotWater for details.

TolTh {TolTh}
maximum desired change of water content within one step of the FE method.

TolH {TolH}
maximum desired change of pressure head within one step of the FE method.

lWat {LWat}
logical. If TRUE transient water flow else steady state.

dt {dt - initial time step}
initial time increment of the FE method.

dtMinMax {minimal time step} and {maximal time step}
c(dtmin, dtmax), minimum and maximum permitted time increment of the FE method.

max.iteration {max. iterations}
maximum number of incremental time steps for coarsed finite element meshes. Once max.iteration is reached, the current time and the aimed time is shown. The user is asked whether it should be continued.

max.iter.prec {max. iter. (precise)}
same as max.iteration except that this value is used if the main menue bottom “precise waterflow” is pressed.

iter.print {swms message, loop period}
number of incremental time steps after which a short message of status is given.

breakpoint {swms, image, loop period}
number of incremental time steps after which the current value of the spatial variable is shown in a two dimensional plot. If breakpoint is chosen appropriately the user gets the impression of a movie. Note that pictures are presented after a certain amount of iteration loops, so the length of the simulated time intervals between the pictures differ.

top.bound {top}
surface boundary condition: 1 (impermeable), 2 (Dirichlet), 3 (Neumann), 4 (variable H), 5 (variable Q), or 6 (atmospheric). See the SWMS2D manual for details.

top.value {top value}
the value of the top.bound condition, if appropriate.

bottom.bound {bottom}
boundary condition at the bottom: 1 (free drainage), 2 (deep drainage), 3 (impermeable), 4 (Dirichlet), or 5 (Neumann). See the SWMS2D manual for details.

bottom.value {bottom value}
the value of the bottom.bound condition, if appropriate.
materials {material (phys) / material (chem)}; thr,...,sharpness are found in the menue for the physical properties, Bulk.d,...,SinkS0 in the menue for the chemical ones. List has the following components
thr {theta_r}
residual water contents theta_r

ths {theta_s}
staturated water contents theta_s

tha {theta_a}
fictious parameter theta_a<=theta_r, introduced into the van Genuchten model for more flexibility (to allow for a non-zero air-entry value), see page 10 of the SWMS2d manual for details.

thm {theta_m}
theta_m>=theta_s, introduced into the van Genuchten model for more flexibility (to allow for a non-zero air-entry value)

Alfa {alpha}
factor alpha in the van Genuchten model

n {n}
exponent n in the van Genuchten model

Ks {K_s}
saturated hydraulic conductivity K_s

Kk {K_k}
non-saturated hydraulic conductivity K_k measured for some theta_k

thk {theta_k}
see K_k

first {1st principal comp}
anisotropy parameter for the conductivity tensor

second {2nd principal comp}
anisotropy parameter for the conductivity tensor

angle {angle (degrees)}
anisotropy parameter for the conductivity tensor

Hslope {intial H, slope}
The initial matrix potential is calculated from the miller.linked and then millerH-transformed Gaussian random field by linear transformation. Hslope and and a function of Hseg, see Hinit, give the slope and the segment of that linear transformation.

Hseg {initial H, segment}
see Hslope and Hinit

POptm {POptm (root)}
highest (negative) matrix potential (so close to saturation) for which the water uptake is still optimal; see root$P2H for further information

sharpness {sharpness}
The values for a random field (of the hydrolic conductivity) of a simulated horizon are obtained by a linear combination of a conditional simulation (towards random fields of the preceding horizons) and an independent simulation. sharpness is the factor for the independent simuation and (1-sharpness^2)^{1/2} the factor for the conditional simulation. The mean of the random field to be simulated has been substracted beforehand from the boundary conditions.
sharpness is not used for the initial horizon, thus not given as a menue point in this case.

Bulk.d {bulk density}
bulk density

Diffus {diffusion}
ionic diffusion coeffcient in free water

longiDisper {longitud. Dispers.}
longitudinal dispersivity

transvDisper {transvers. Dispers.}
transverse dispersivity

Adsorp {Freundlich isoth coeff.}
Freundlich isotherm coefficient

SinkL1 {1st-order const./dissolved}
first-order rate constant mu_w for dissolved phase, see page 15 of the SWMS2d manuscript

SinkS1 {1st-order const./solid}
first-order rate constant mu_s for solid phase

SinkL0 {0-order const./dissolved}
zero-order rate constant gamma_w for dissolved phase

SinkS0 {0-order const./solid}
zero-order rate constant gamma_s for solid phase
Hinit function of two variables; the first varible is a vector of Hseg, the second the depths d. the initial h values are calculated as

Hinit(Hseg, d) + Hslope * millerH(Z)

where Z is the simulated random field. The initial h value may afterwards be modified for certain segments due to the given boundary conditions and to a given given Dirichlet condition for the roots.

model {structure} the covariance model for the Gaussian random fields used for the definition of the Miller similar media. See CovarianceFct for details on the definiton of the covariance model.
If the mean equals NA and if it is the last horizon, the area is interpreted as air.
anisotropy logical or NULL. If logical it overrides the anisotropy condition given by model. If model was anisotropic and anisotropic=FALSE, the first anisotropic scale parameter is used as scale for the isotropic model. If model is isotropic, only the representation is changed, and the user has the opportunity to change the values to an truely anisotropic model.
miller.link function that transforms the Gaussian random field to a field of non-negative values. The argument and the value are matrices (of the same size). If NULL the miller.link is the identity.
millerH function that transforms the miller.linked field into a field of water potential H. This field is used for areas of constant potential, and for the potential at starting time. For the latter the millerH transformed field is further transformed linearly by a function of $matrials$Hslope, see Hinit, and $matrials$Hseg. The argument and the value are matrices (of the same size).
millerK function that transforms the miller.linked field into a field of scaling factors that are associated with the saturated hydraulic conductivity. The argument and the value are matrices (of the same size).
millerT function that transforms the miller.linked field into a field of scaling factors that are associated with the water content. The argument and the value are matrices (of the same size).
chemical {swms2d (chem)} list of the following components
lChem {Solute transport}
logical that indicates whether solute transport should be modelled

Epsi {scheme}
integer 1,2,3. Temporal weighing coefficient: 1 (explicit: weight=0), 2 (Crank-Nicholson: weight=0.5) or 3 (implicit: weight=1)

lUpW {formulation}
1 (upstream weighing formulation) or 2 (Galerkin formulation)

lArtD {added artific. disp}
logical. If TRUE artificial dispersion is added to satisfy the stability criterion PeCr

PeCr {PeCr}
Stability criterion (Peclet number * Courant number); usually 2, but can be increased to 5 or 10; see page 44 of the SWMS2D manuscript.

tPulse {pulse duration}
time duration of the concentration pulse

top.bound {top}
boundary condition for soil surface: 1 (impermeable), 2 (Dirichlet), 3 (Neumann), 4 (variable Concentration), 5 (variable Q), 6 (atmospheric)

top.value {top value}
value of the boundary condition if appropriate

bottom.bound {bottom}
boundary condition for the bottom: 1 (free drainage), 2 (deep drainage), 3 (impermeable)

bottom.value {bottom value}
value of the boundary condition if appropriate

root.uptake {root uptake}
- not implemented yet

intern.source {internal source}
- not implemented yet
atmosphere {atmosphere, control} list of the following components
AtmInf {use atmospheric data}
logical. Determines whether or not atmospherical data should be used.

tInit {start time of simu}
starting time of the simulation. This information is necessary since the atm.data (see below) give the end of an atmospheric period only. So for the first period the starting time is missing.

Aqh {A_{qh}}
only used if water$bottom.bound equals 2 (deep drainage). Then the modulus of the discharge rate equals step*A_{qh}exp(B_qh |h - GWL0L|) where h is the local pressure head.

Bqh {B_{qh}}
see Aqh

hCritS {max pressure at surface}
maximum allowed pressure head at the soil surface

GWL0L {ref. pos of groundwater}
Reference position of the groundwater table (usually the z-coordinate of the soil surface); only used if water$bottom.bound equals 2 (deep drainage)

rLen {width of soil (transpiration)}
width of soil surface associated with transpiration. Only used in case of atmospheric root uptake.
atm.periods (maximum) number of atmospherical periods. Only used if atm.data is a vector. Otherwise atm.periods is set to the number of the rows of atm.data.
atm.data {atmosphere, data} vector of 10 components or matrix of 10 columns. The 10 components are
end {end point}
end point of the atmospherical period; the value of end for the last atmospherical period must be greater than the value of TPrint

prec {precipitation}
precipitation

cPrec {solute, precipitation}
solute concentration of rainfall water

rSoil {potential evaporation}
potential evaporation rate

rRoot {potential transpiration}
potential transpiration rate

hCritA {abs. min. pressure at surface}
absolute value of the minimum allowed pressure head at the soil surface

rGWL {drainage flux (drain or var. Q)}
drainage flux or other time-dependent prescribed flux boundary condition. For nodes with atmospheric flux condition.

GWL {ground water level}
groundwater level or other time-dependent prescribed head boundary condition. For nodes with atmospheric head condition. Pressure is then GWL+GWL0L.

crt {conc. flux (drainage)}
time-dependent concentration flux

cht {conc. ‘pressure’ (drain/var. H)}
time-dependent concentration of the first-type boundary condition. See the SWMS2D manual for details.
stone {stones} list of the following components
value {value}
numeric or NA. NA is used to model stones, i.e. water cannot penetrate. If not NA, the (Gaussian) random field gets, at the place of the ‘stone’, the value value. This might be of interest if small lenses are modelled by means of ‘stones’.

lambda {intensity}
intensity of the stones

no.upper {!overlap into upper horizons}
if TRUE overlap into any upper horizon is forbidden

no.lower {!overlap into lower horizons}
if TRUE overlap into any lower horizon is forbidden

no.overlap {!overlap of stones}
if TRUE the overlap of stones is forbidden. This point is clear from a practical point of view. However the currently implemented algorithm (SSI/RSA) for non-overlapping stones is slow and it is furthermore not guarantied that it will not fail (due to ‘bad’ random numbers). If overlapping is allowed a fast and simple algorithm is used (Boolean model). See for both, SSI and Boolean model, the references in Stoyan et al., for example.

main.distr
distribution for the length of the main axis of the ellipse

main.mean {main axis, mean}
the parameter for the mean of the distribution

main.s {main axis, sd}
the parameter for the standard deviation of the distribution

sec.distr
distribution for the length of the second axis of the ellipse

sec.mean {second axis, mean}
the parameter for the mean of the distribution

sec.s {second axis, sd}
the parameter for the standard deviation of the distribution

phi.distr
distribution for the angle between the horizontal line and the main axis of the ellipse

phi.mean {second axis, mean}
the parameter for the mean of the distribution

phi.s {second axis, sd}
the parameter for the standard deviation of the distribution
plant.types positive integer. Number of different types of root systemes that will be generated
Kf function(plant, distances, depths, rf, param=list(field.value=1, field.factor=0)). According to the parameters the (Gaussian) random field get a new value if there is a root pixel. Here, plant is the type of plant (scalar integer value 1..plant.types), distances a vector of distances from the considered locations to the surface along the root, depth is a vector of depths of the considered locations, and rf is the value of the Gaussian random field (including the stones). param is a list of named elements (possibly empty) whose values can be modified interactively; all parameters are real valued and the usual magnitude of the range is 1; the names may not match any name in the list for root, since the parameters are included in the root list, which is passed to Kf as a whole.

The function is only used if root$rf.Kf is TRUE for the specific plant type. This function is still in an experimental stage.
beta function(plant, distances, depths, rf, param= list(beta.value=1, beta.factor=0)). beta gives the raw potential root water uptake according to a single plant type, the distances to the beginning of the root, the depths, and rf (see also Kf). The raw potential values are subsequently normed such that they sum up to one. This gives the potential root water uptake. param is a list of named elements (possibly empty) whose values can be can be modified interactively; all parameters are real valued and the usual magnitude of the range is 1; the names may not match any name in the list for root or any parameter name within the parameter list in Kf, since the parameters are included into the root list, which is passed to beta as a whole.
root {root growth} for plants.lambda to dir.ch.s and
{root, water uptake} otherwise.
Any plant type is set to the values of root at starting time. root is a list of the following components
plants.lambda {mean # of plants}
the number of plants is Poisson distributed with mean plants.lambda

plants.mindist {min. plant. dist.}
plants of the same species are at least plants.mindist away. Actually, the algorithm tries to find random positions so that this condition is satisfied, but will give up if not successful after a few attemps. Then the value of plants.mindist is ignored.

mean {aimed mean total length}
mean total length of all the roots of a single plant. For a long time run, the average will be about the mean, but the algorithm is not too sophisticated to guarantee this.

sd {aimed sd of total length}
standard deviation for the total length of all the roots of a single plant. There is a check by the algorithm to be close to sd

knot.probab {knot probability}
probability of any root pixel to be a knot, except if the distance from the position to the previous knot is less than knot.mindist. Then the probability for a knot is 0.

knot.mindist {min. knot distance}
see knot.probab

shoots.3 {3 shoots probab.}
positive number, see shoots.4

shoots.4 {4 shoots probab.}
positive number.
shoots.4>=1
knots have always 4 shoots.

shoots.4<1 and shoots.4+shoots.3>=1
knots have with probability shoots.4 4 shots and 3 shoots otherwise.

shoots.4<1 and shoots.4+shoots.3<1
knots have 4, 3, 2 shoots with probability shoots.4, shoots.3 and 1-shoots.4-shoots.3, respectively

stop.probab
function(knot, dist, stop.m, stop.s) that returns a values in [0,1], which is the probability that a given root pixel does not continue to grow. The function should be able to take matrices for the first 2 components. knot is the number of knots preceding and including the current pixel, dist is the distance to the surface along the root, stop.m and stop.s are arbitrary additional parameters.

stop.m {stop probability, m}
see stop.probab

stop.s {stop probability, s}
see stop.probab

rf.link
function(v, rf.m, rf.s). Summand in calculating the priority for all the neighbouring pixels of all active root pixels (end points of the roots). The pixels with the highest priority will be the next new root parts. rf.link transforms the value of the simulated Gaussian random field where rf.m and rf.s are additional parameters.
rf.m {random field link, m}
see rf.link

rf.s {random field link, s}
see rf.link

no.own.root {own root penetration}
if TRUE a pixel may contain at most one root part of the same plant.

age.bonus {age bonus}
factor by which the priority number of a pixel is multiplied after each step. The age.bonus is usually greater than or equal to 1.

depth.bonus {depth bonus}
summand added to the priority number if the subsequent pixel is below the current root pixel

side.bonus {side bonus}
summand added to the priority if the subsequent pixel has the same depth than the current root pixel; see depth.bonus for deeper points.

diagonal {diagonal directions}
if TRUE then roots may also grow into diagonal directions.

dir.ch {no direction change}
The number of pixels in x direction and the number of pixels in y direction by which the new direction of the root growth deviates from the previous is added and gives a value d between 0 and 4.
E.g., if the sequence of root pixels is (1,3), (2,4) then the previous direction is (1,1). If the pixel (2,3) is considered the new direction is (0, -1), so the modulus of deviation is 1 and 2 in x and y direction, respectively. So, d=1+2=3.
Let v = d * dir.ch. Then the summand for the priority of a pixel is given by normal random variable with mean v and sd=|v| dir.ch.s.

dir.ch.s {no dir. change, rel. sd}
see dir.ch

rf.Kf {root, water uptake}{root changes field value}
logical. If TRUE the value of the (Gaussian) random field at a root segment is changed according to the function Kf.

field.value {root, water uptake}{field.value}
The list entries field.value and field.factor are present only if the function Kf has the default definition. In general, the named list elements of the parameter param of Kf are given. See also Kf.

field.factor {root, water uptake}{field.factor}
see field.value

beta.value {root, water uptake}{beta.value}
The list entries beta.value and beta.factor are present only if the function beta has the default definition. In general, the named list elements of the parameter param of beta are given. See also beta.

beta.factor {root, water uptake}{beta.factor}
see beta.value

P0 {root, water uptake}{P0}
(negative) pressure above which too less oxygene to allow water uptake by plants

P2H {root, water uptake}{P2H}
P2H, P2L, r2H and r2L determine, in dependence of the potential transpiration, the lower bound for optimal water uptake (piecewise linear curves); the upper bound of optimal water uptake is given by materials$POptm. See the SWMS2D manual for details.

P2L {root, water uptake}{P2L}
see P2H

P3 {root, water uptake}{P3}
(negative) pressure below which no water uptake is possible

r2H {root, water uptake}{r2H}
see P2H

r2L {root, water uptake}{r2L}
see P2H

root.condition {root, water uptake}{root water uptake}
boundary condition for the root. Orginially, only ‘atmospheric’ was allowed.

root.uptake {root, water uptake}{water uptake value}
value at the root in case of ‘dirichlet’ or ‘neumann’ boundary condition
root.zone NULL or function of one variable. If not NULL then rootzone defines for any given x coordinate the interval for the height of the rootzone. A plant of species 1 is defined so that all segments within the so defined root zone contains a root of this plant.
col.rf sequence of colours that are used to show the random field; if NULL then some internally defined color sequence is used
col.simu sequence of colours that are used to present any simulation result by swms2d; if NULL then some internally defined color sequence is used
MaxIt maximum number of iteration during any time step.
hTab c(hTab1, hTabN), interval of pressure heads within which a table of hydraulic properties is generated.
DMul c(dMul, dMul2), dMul >= 1, dMul2 <= 1; if the number of required iterations is less than 4 or greater than 6 then the next time step is multiplied by dMul and dMul2, respectively.
col.rect colour of the button for free input; see eval.parameters
col.bg colour of a interactive bar; see eval.parameters
col.sep colour of the separating line; see eval.parameters
col.left colour of preceding element; see eval.parameters
col.mid colour for the message; see eval.parameters
col.right colour of subsequent element; see eval.parameters
col.line colour of the marking line in interactive bars of absolute choice; see eval.parameters
col.txt colour of headers; see eval.parameters
col.submenue colour for the text in the main menue
col.subord colour for the text in the title of a secondary menue
col.forbid colour for text that indicate forbidden main menues, e.g. ‘polygon’ after having defined already the maximum number of allowed horizons
col.bg.forbid background colour for forbidden menue points
col.flash colour for hints or the titles of active windows
col.hor vector of 10 components. Colours that are used to draw the horizons
col.draw colour for drawing or showing selected horizons
col.mess colour for warning or error messages
col.mesh colour for the edges of the finite element mesh
col.mesh.pt colour for the vertices of the finite element mesh
col.exception vector of 2 components; colour plotted values that are below or above the given range of zlim, see lim.swms2s and zlim.
cex.eval value for the parameters cex and cex.i of eval.parameters and for the parameter cex.names in ShowModels.
areas logical. If TRUE the horizons are coloured. If FALSE only the border lines between the horizons are given.
PrintLevel If <=0 nothing is printed. The higher the value the more information is given.
new logical or NULL. If TRUE the interactive plot is opened in a new window. If NULL then the interactive window is not opened and the standard definitions are returned.
X11.width numeric. Width of the window. Only used if new=TRUE.
X11.height numeric. Height of the window. Only used if new=TRUE.
frequent.reset logical. Background: the current implementation of xswms2d uses split.screen to build the interactive plot; split.screen memorises all changings in the plot and replays them all if the X11 window has to be rebuilt. If frequent.reset=TRUE then the memory effect is reduced at the cost of some flickering of the X11 window in the main menu.
update {updating} logical. If TRUE the simulations are updated after any changing of the parameters.
Independently of the value of update an update of the simulation is performed if the user clicks on any of the given titles or subtitles of the submenu.
waterflow {water flow} logical. If TRUE swms2d is run
zlim vector of 2 components or NULL which gives the limits for the plotted values in the images. If NULL then zlim is calculated internally, cf. plotWater.
Zlim vector of 2 components or NULL which gives the limits for the plotted values in ShowModels.
print.par {postscript} list of the following components
ps {ps base name}
character. Base name of the postscript file.

height {picture height}
numeric. Height of the postscript figure in inches.

title {plot title}
logical. If TRUE a title is plotted.

legend {legend}
logical. If TRUE a legend is added to the plot.
... sophy is alias for xswms2d and takes the same arguments as xswms2d.

Details

The interactive plot is organised as follows:

left top
drawing area: here, a soil profile is shown (if available, see parameter picture) and the user draws the boundaries of the horizons by a sequence of left mouse button clicks.
left bottom
Random field of hydraulic conductivity. That is, the Gaussian random field including stones and roots, to which miller.link and then millerK has been applied. (In the standard setting, the modulus of the Gaussian random field is anti-proportional to the root of the hydraulic conductivity K and proportional to the initial water potential H.)
centre top
Main menue; this area is also used for defining the parameters of the Gaussian random fields
centre bottom
plotting area for the water pressure H, the charge rate Q, water contents theta, the flux vector components or the solute concentration as calculated by swms2d for coarsened grids.
right
area used by submenues
right bottom
plotting area for the water pressure etc for the orginal, fine grid, see main menue point ‘precise waterflow’ below

The menue points of the interactive plot are

postscript
plotting the water potential H, discharge/recharge rates Q for internal sink/sources, the water contents theta, the x-components of the Darcian flux vector vx, the z-components of the Darcian flux vector vz, or the concentration; in grey it is noted whether the ‘precise water flow’ or the result of the approximate ‘water flow’ is given (according to the main menu point ‘precise waterflow’). Further the random field might be plotted. For the additional parameters, see the input variable print.par.
polygon
A sequence of left mouse button clicks in the upper left drawing area defines the vertices of the polygon. Up to 512 vertices are allowed. The right mouse button terminates the drawing. A polygon must consist of at least three points. The points may be placed such that the connecting lines cross.
horizon
A sequence of left mouse button clicks in the upper left drawing area defines the border of the horizon. Up to 512 vertices are allowed. The right mouse button terminates the drawing. A sequence of chosen points is only accepted to define a horizon if the first point has a smaller x-coordinate than all the other points and the last point has a greater x-coordinate than all the other points; except for this restriction and the fact that at least 2 points must be given, any sequence of points is allowed, points may even leave the plotting area. If the first or the last point is within the area then the horizon boundary is linearly extrapolated by a line through the first and second or the two last points, respectively. The new horizon gets as default parameters for the stones the input stone parameters, and for the material the material parameters of the preceding horizon.
structure
Definition of the random fields that underly the Miller similar medium. If more than one horizons or at least one polygon is defined the user selects first the part the user likes to define by a click into the appropriate part of the drawing area. Afterwards a new menue is opened in the upper right part of the window. Within this new menue we have, see ShowModels for details,

bottom left
a simulation of the Gaussian random field with the specified parameters.
top left
the covariance function or the variogram for the random field and the the transformed random field according to miller.link. If the model is anisotrope or anisotrop=TRUE is given explicitely, the models are shown for the two main axis.
right
Interactive menue. From top to bottom:
  • ‘simulate’ is given if ‘updating’ of the main menue is FALSE
  • name of the model
  • the formula. Note the formula is not given for all the coded variogram models.
  • the specific parameters if there are any
  • variance
  • nugget effect
  • the scale parameter or the anisotropy paramters
  • mean.
  • If ‘practical range’=TRUE then the (isotropic) covariance model is rescaled such that at distance 1 the value of the model is approximately 0.05.
  • ‘variogram’ switches between the presentation of the variogram and the corresponding covariance function.
  • ‘variogram angle’ gives the angle for the direction of the main variogram. If ‘variogram angle’=NA the angle equals the angle of the anisotropy specification.
  • If ‘show transformed field’=TRUE then the same transformation as for the hydraulic conductivity parameter alpha_k is applied, i.e., millerK(miller.link( ))

This menue is left by the right mouse button. A menue for choosing another variogram model is reached. Again, the right mouse button leaves the menue.

The first horizon gets as default the model and the parameter values passed to xswms2d by model and anisotropy. For the following horizons the values of the previously considered horizon are taken over, when considered first.

stones
definition of the stones
root growth
definition of the root growth; if plant.types is greater than 1, the user first chooses among the different types, then enters the submenue. ‘plant type’ is used to name a species only, and is used nowhere else. The decription of all the other variables (‘mean # of plants’,...,‘no dir. change, rel. sd’) is given above; see the input variable root.
material[phys]
Definition of the physical material constants, see variable materials.
material[chem]
Definition of the chemical material constants, see variable materials.
root water uptake
Definition of the water uptake by the roots. See the variable root.
atmosphere, data
See the variable atm.data for a description. If nrow(atm.data) or atm.periods is greater than 1 then the user chooses the atmospherical period first.
swms2d [water]
see the variable water for a description
swms2d [chem]
see the variable chemical for a description
atmosphere control
see the variable atmosphere for a description
new simulation
If parameters are changed, simulations are redone reusing previous simulations as much as possible. That is, if a parameter of SWMS2D is changed the simulation of the Gaussian random field is reused. Further the redone simulations are based on the old random seeds.

Here, a simulation is redone from scratch, based on a new random seed.

precise waterflow
By ‘swms2d water’, submenue ‘size reduction’ (variable water$red) the finite element mesh can be coarsened for faster simulations. If the coarsening is genuine, i.e. water$red>1, then this menue point is active. If pressed, a simulation is performed on the original finite element mesh.
water flow
yes/no. If ‘no’, only the Gaussian random field, the stones and the roots are simulated.
updating
yes/no. If yes the simulation is redone after any changing of any parameter, except for ‘structure’ definition, where the new simulation is performed when the submenue ‘structure’ is left.
end
terminates the interactive surface

General information

Value

sophy is a synonym for xswms2d A list is returned, where the first 10 components contain the definitions of the horizons; these 10 components are called by their position in the list. Any other list component does not have a predefined location and may be called only by name.
Note that if sophy or xswms2d is called with parameter new=NULL the interactive window is not opened, but the initial list (of h) is returned immediately.

1:10 Each of the first 10 components is a list of the following elements:
type
character. Either ‘Start’, ‘H’, or ‘P’. Exactly the first element has the value ‘Start’, all the others may be horizons (‘H’) or polygons (‘P’).

cut.x, cut.y
cut.x and cut.y define the horziontal and vertical position of a rectangle, respective, which encloses the whole horizon or polygon. cut.x and cut.y should be as tight as possible, to accelerate the simulation of the random fields for the horizons.

stone
list of stone parameters, see the input variable stone. The input parameters are the default parameters for all stone specifications

materials
list of material constants, see the input variable materials. The default parameters for the first horizon are the input parameters; the default parameters for any other horizon (or polygon) are the parameters of the preceding horizon (or polygon)

model
list or NULL. Covariance model in list format, see CovarianceFct. The model is NULL if ‘structure’ of the main menue has not been called yet for the respective horizon. The ‘Start’ horizon gets the value of the input parameter at starting time. If ‘undo’ is called when only the ‘Start’ horizon exists then model is set to NULL even for the ‘Start’ horizon.

border
matrix of two columns or NULL. boundary points between two horizons (or polygons); used for the conditional simulation of the Gaussian random fields. Further, if for the selection of a horizon the user clicks on such a boundary points, the user is warned. border is NULL if only the ‘Start’ horizon exists.

idx
matrix of logical values with diff(cut.x)+1 rows and diff(cut.y)+1 columns. idx indicates which pixels of the cut.x x cut.y area belongs to the present horizon.
grid.x seq(xlim[1], xlim[2], step)
grid.y seq(ylim[1], xlim[2], step)
idx.rf integer. Matrix of size length(grid.x) x length(grid.y) indicates the affiliation to a horizon or polygon (number is decremented by 1, i.e., 0,...,h$n-1), see also the output variable border within the specific horizons.
It allows also for the indication of the presence of a stone; then, if a stone is present, the horizon number is incremented by h$max.horizon. The modulus by h$max.horizon gives the by 1 decremented number of the horizon.
n current number of horizons
step input parameter step
max.horizons maximum number of horizons; currently 10. The value of this variable may never be changed!
beta input parameter beta
root list, where length(root) equals the input parameter plant.types. Each component of the list is a list with the same components as the input parameter root. Additionally, it has the components
  • plant.type, a user defined name of the species.
  • the parameters within the param list of the function Kf
  • the parameters within the param list of the function beta
  • atmophere input parameter atmosphere
    atm.data matrix of 10 columns, corresponding to the input parameter atm.data and atm.periods.
    water input parameter water
    chem input parameter chemical
    Kf input parameter Kf
    RF matrix of size length(grid.x) x length(grid.y) or NULL. RF contains the Gaussian random field resulting from all definitions for the horizons. RF is NULL if simulate.horizon has not been called yet.
    Stones.RF matrix of size length(grid.x) x length(grid.y) or NULL. The value of Stones.RF is the Gaussian random field modified by the stones (concerning hydraulic conductivity). Stones have usually value NA, whereas air has value NaN.
    Stones.RF is NULL if simulate.horizon has not been called yet or terminated with an error. Further Stones.RF is set to NULL if materials$sharpness has been changed, or ‘structure’, ‘undo’, ‘horizon’, or ‘polygon’ has been called.
    Root.RF matrix of size length(grid.x)xlength(grid.y) or NULL. The value of Root.RF is the value of Stones.RF modified by the roots (concerning hydraulic conductivity). That is, if root$rf.Kf is TRUE the values at the respecitve root segments are given by h$KF.
    Root.RF is NULL if simulate.horizon has not been called yet or terminated with an error. Further Root.RF is set to NULL if materials$sharpness has been changed, or ‘structure’, ‘undo’, ‘horizon’, or ‘polygon’ has been called.
    m.link link function used in the submenue ‘structure’, currently the function is identical to miller.link
    miller.link input parameter miller.link
    col.rf input parameter col.rf if not NULL and the internally defined sequence of colors otherwise
    col.simu input parameter col.simu if not NULL and the internally defined sequence of colors otherwise
    random.seed list or NULL. Each element contains the random seed for the simulation of the Gaussian random field in the respective horizon. random.seed is NULL if simulateHorizons has not been called yet.
    stone.random.seed The random seed for the simulation of the stones
    root.random.seed The random seed for the simulaton of the roots
    rf.complete logical. TRUE if the stochastic simulation has been performed completely.
    plants list or NULL. Each component contains the information on the roots of a single plant. Each component is a matrix of 8 columns and rows according to the number of root segments. The 8 columns are
    1. horizontal coordinate of a root segment. The coordinate is given in pixel units.
    2. vertical coordinate of a root segment. For the first segment it equals 1 plus the vertical position of the first pixel that is not air at the chosen horizontal position.
    3. row index for the parent root pixel
    4. row index where the subsequent root pixel is found; NA if it is a terminating root segment. If the pixel is a knot with k children then the value gives the position of the first child. The other children are given in consecutive rows.
    5. number of children in case it is a knot, 1 otherwise
    6. the number of preceding knots until and including this position
    7. aimed random total length of the roots if it is the first pixel, and the current distance to the surface along the roots, otherwise.
    8. distance to the preceding knot
    plants is NULL if simulateHorizons has not been called yet, or any parameter in root has been changed.
    plants.idx vector or NULL. plant.idx[i] gives the plant type (1,...,plant.types) of the ith simulated plant. plants.idx is NULL if create.roots or simulateHorizons has not been called yet.
    water.x the coordinates of grid.x after thinning by factor water$red
    water.y the coordinates of grid.y after thinning by factor water$red
    flux logical vector of length(water.x) x length(water.y) elements. flux indicates which pixels of the length(water.x)xlength(water.y) grid are used in the SWMS2D simulation. (Pixel are left out if they indicate stones (NA) or air (NaN).)
    swms2d three dimensional array or NULL. The first dimension has 6 components which are
    1. the water potential H
    2. discharge/recharge rates Q for internal sink/sources
    3. the water contents theta
    4. the x-components of the Darcian flux vector vx
    5. the z-components of the Darcian flux vector vz
    6. the concentration
    The second component corresponds to the sequence of pixels used in the SWMS2D simulation and has length sum(flux).
    swms2s is NULL if the water flux has not been simulated yet because no simulation has been performed or one of the stochastic simulations (Gaussian random field, stones, roots) failed, or ‘water flow’ has been set to ‘no’. Further swms2d is set to NULL if an error occurs when trying to plot the SWMS2D simulation results (by plotWater); this happens if the result has no finite values. Finally, swms2d is set to NULL if a relevant parameters was changed, such as those in atmosphere, atm.data, materials, chem or water.


    Any of the lists that contain input parameters may have the additional component .history, an internal variable used by the interactive menue algorithm that gives the last entries by the user; see evalpar.

    Warning

    The user should consider the following parameters of h[[i]] as being read-only:

  • cut.x
  • cut.y
  • border
  • idx
  • Further, h$max.horizon may never be changed.

    Note

    The phrases in brackets in the argument section of this documents give the respective menue points of the interactive plot.

    Author(s)

    Martin Schlather, martin.schlather@math.uni-goettingen.de http://www.stochastik.math.uni-goettingen.de/institute

    References

    See Also

    calculate.horizons, create.roots, create.stones, create.waterflow, draw.horizons, modify.horizons, plotRF, plotWater, simulateHorizons, SoPhy, swms2d

    Examples

    
    ## Not run: 
    ### without underlying profile
    h0 <- xswms2d(xlim=c(1, 100), ylim=c(1, 100), step=1)
    # or, equivalently:
    # h1 <- sophy(xlim=c(1, 100), ylim=c(1, 100), step=1)
    
    ### underlying profile
    ### the profile was taken by M. Flury, J. Leuenberger,
    ### B. Studer, W.A. Jury and H. Fl\"uhler, see also URL
    ### \url{http://www.ito.umnw.ethz.ch/SoilPhys/Fliessmuster/projekt_flury.html}
    pic <- paste(system.file(package='SoPhy'), 'tracer', 'K06', sep="/")
    h <- xswms2d(xlim=c(0,160), step=1, aniso=TRUE,
                 update=FALSE, waterflow=FALSE, pict=pic)
    
    ### repeated call
    h <- xswms2d(h=h, update=TRUE, waterflow=TRUE)
    
    ### an example for non-atmospheric root uptake
    h <- sophy(xl=c(1,10), yl=c(1,10), step=0.1, new=NULL) ## get standard
    h$root[[1]]$root.condition <- 1   ## dirichlet condition for roots
    h$root[[1]]$root.uptake <- -200   ## value for dirichlet condition
    h$root[[1]]$plants.lambda <- 0.07 ## intensity of plants
    h$water$TPrint <- 2     ## end point of simulation (film lasts about 2 min)
    h$water$red <- 1        ## precise simulation
    h$water$breakpoint <- 3 ## high image frequency (close to a film)
    h$water$top.bound <- 2  ## dirichlet
    h$water$top.value <- -8 ## value on the boundary
    h <- xswms2d(h=h, update=TRUE, waterflow=TRUE)
    ## End(Not run)
    
        
    
    

    [Package SoPhy version 1.0.34 Index]