[Rd] R documentation -- buffer overflow? (PR#3400)
Martin.Schlather at uni-bayreuth.de
Martin.Schlather at uni-bayreuth.de
Fri Jul 4 16:59:21 MEST 2003
This is a multi-part message in MIME format.
--------------090000060304060401040205
Content-Type: text/plain; charset=us-ascii; format=flowed
Content-Transfer-Encoding: 7bit
Hi,
I have attached a larger Rd file that causes an error when
compiled by
R CMD Rdconv -t txt xswms2d.Rd
(for example). If the size is reduced the error vanishes,
see the lines 230 and 527 in the file.
I could not find an error within my text and so my guess
is that there is some buffer overflow within the compiler.
If it is me who has caused the error please let me know --
and many apologies.
Cheers,
Martin
--
Martin Schlather email: Martin.Schlather at uni-bayreuth.de
Abteilung Bodenphysik phone: +49 (0)921 55 2193
Univ. Bayreuth Fax : +49 (0)921 55 2246
D -- 95440 Bayreuth, Germany http://www.geo.uni-bayreuth.de/~martin/
--------------090000060304060401040205
Content-Type: text/plain;
name="xswms2d.Rd"
Content-Transfer-Encoding: 7bit
Content-Disposition: inline;
filename="xswms2d.Rd"
% R CMD Rdconv -t txt xswms2d.Rd
\name{xswms2d}
\alias{xswms2d}
%- Also NEED an '\alias' for EACH other topic documented here.
\title{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{
xswms2d(h, xlim, ylim, step, picture=NULL,
%## material and water flux parameters
water=list(
%## printing
TPrint=500, red=4, print=1, mesh=TRUE,
%## simulation control
TolTh=0.0001, TolH=0.01, lWat=TRUE, dt=1,
max.iteration=1000, max.iter.prec=50000,
iter.print=100, breakpoint=100,
%## boundary conditions
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,
),
model=list(model="gencauchy", param=c(-0.5, 0.25, 0, 5, 1.5, 5)),
anisotropy=NULL,
miller.link=function(rf) exp(sign(rf) * sqrt(abs(rf))),
%## chemical data
chemical=list(
lChem=TRUE, Epsi=1, 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,
),
%## atmospherical data
atmosphere=list(
AtmInf=TRUE, tInit=0, Aqh=-.1687, Bqh=-.02674,
hCritS=1.e30, GWL0L=ylim[2],
),
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,
),
%## stones
stone=list(
%## basics
value=NA, lambda=0,
%## location
no.upper=FALSE, no.lower=TRUE, no.overlap=TRUE,
%## size
main.distr=rnorm, main.mean=14, main.s=0,
sec.distr=rnorm, sec.mean=diff(ylim)/50, sec.s=diff(ylim)/400,
phi.distr=rnorm, phi.mean=1, phi.s=0,
),
%## roots
plant.types=1,
Kf=function(plant, dist, depth)
rep(1, max(length(dist), length(depth))),
beta=function(plant, dist, depth)
rep(1, max(length(dist), length(depth))),
root=list(
plants.lambda=0, plants.mindist=15, mean=100, sd=10,
%## root growth
knot.probab=0.1, knot.mindist=6, shoots.3=0.4, shoots.4=0,
stop.probab=function(knot, dist, m, s) 1 - exp(-m + s * dist),
stop.m=1, stop.s=1,
rf.link=function(v, m, s) exp(m + s * v), rf.m=0, rf.s=0,
%## advanced root growth
no.own.root=TRUE, age.bonus=1.2, depth.bonus=5.2,
side.bonus=5.1, dir.ch=3.71, dir.ch.s=0.5,
%## water uptake / change of conductivity
rf.Kf=FALSE, P0=-10, P2H=-200, P2L=-800, P3=-8000, r2H=0.5,
r2L=0.1, root.condition=3, root.uptake=-150,
),
%## control parameters for swms2d
MaxIt=20, hTab=c(0.001,200), dtMinMax=c(0.01, 60), DMul=c(1.1, 0.33),
%## menue, parameter input
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
col.hor=c("#000000", "#996600", "#660000", "#CC9933", "#666600",
"#CCCC99", "#CCCCCC", "#990000", "#FFCC00", "#FFFFCC"),
col.draw="green", col.mess="red",
%## images
col.rf=paste("#", HEX[1 + rev(l.col) / 16],
HEX[1 + rev(l.col) \%\% 16],HEX[1 + rev(l.col) / 24],
HEX[1 + rev(l.col) \%\% 16],"00", sep=""),
col.simu=paste("#0000", HEX[1 + l.col / 16],
HEX[1 + l.col \%\% 16], sep=""),
%## finite element mesh
col.mesh="blue", col.mesh.pt="green",
upper.lim.z=1, areas=is.null(h$picture),
PrintLevel=1, new=TRUE, X11.width=9.5, X11.height=7.5,
update=FALSE, waterflow=FALSE,
%## postscript output
print.par=list(ps="sophy", height=3, titl=TRUE)
)
}
%- maybe also 'usage' for other objects documented here.
\arguments{
\item{h}{a list of the output format, see the Details.
If \code{h} is given the parameters \code{xlim}, ..., \code{root}
are ignored.
}
\item{xlim}{the horizontal extension of the profile, see also
\code{picture}. If \code{\diff(xlim)} is not an integer multiple of
step \code{xlim[2]} is decreased accordingly.}
\item{ylim}{the vertical extension of the profile, see also
\code{picture}. If \code{\diff(ylim)} is not an integer multiple of
step \code{ylim[2]} is decreased accordingly.}
\item{step}{the grid length for both directions. The finite element
method is essentially based on a quadratic mesh.}
\item{picture}{array or file name for a digitised profile in tif or jpeg
format; if array it must have three dimensions, where third
dimension has 3 or 4 components (RGB or RGBA format).
If \code{picture} is given then either \code{xlim} or
\code{ylim} might be missing and is calculated from the other lim
parameter and the dimension of the picture.
}
%
\item{water}{[swms2d, water] list of the following components
\itemize{
\item{\code{TPrint}}{
[TPrint] modelling time after which the result is printed}
\item{\code{red}}{
[size reduction] positive integer.
to increase the simulation spead the
size of the finite element grid can coarsened}
\item{\code{print}}{
[printed variable] one of the following
spatial data sets are plotted:
the water potential \eqn{H},
discharge/recharge rates \eqn{Q} for internal sink/sources,
the water contents \eqn{theta},
the x-components of the Darcian flux vector vx,
the z-components of the Darcian flux vector vz,
or the soulte concentration}
\item{\code{mesh}}{
[show FE mesh] logical. If \code{TRUE} the currently
used finite element mesh in a swms2d simulation
is shown in the upper left drawing area.}
\item{\code{TolTh}}{
[TolTh] maximum desired change of water content
within one step.}
\item{\code{TolH}}{
[TolH] maximum desired change of pressure head within
one step.}
\item{\code{lWat}}{
[LWat] logical. If \code{TRUE} transient water flow else
steady state.}
\item{\code{dt}}{
[dt -- initial time step] initial time increment.}
\item{\code{max.iteration}}{
[max. iterations] maximum number of
incremental time steps for coarsed finite element meshes.
% coarsening by factor one is also possible
Once \code{max.iteration} is reached, the current time and
the aimed time is shown. The user is asked whether it should be
continued.}
\item{\code{max.iter.prec}}{
[max. iter. (precise)] same at
\code{max.iteration} except that the value is used if the main
menue bottom \code{precise waterflow} is pressed.}
\item{\code{iter.print}}{
[swms message, loop period] number of
incremental time steps after which a short message of status is
given}
\item{\code{breakpoint}}{
[swms, image, loop period] number of incremental
time steps after which the current value of the spatial variable
that is of interest is shown in a two dimensional plot. If
\code{breakpoint} is chosen appropriately the user gets the
impression of seeing 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.}
\item{\code{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.}
\item{\code{top.value}}{
[top value] the value of the condition if
appropriate.}
\item{\code{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.}
\item{\code{bottom.value}}{
[bottom value] the value of the condition if
appropriate.}
}
}
%
\item{materials}{[material (phys) / material (chem)];
\code{thr}...\code{sharpness} are found in the menue for the physical
properties, \code{Bulk.d}...\code{SinkS0} in the menue for chemical ones.
List of the following components
%% no error occurs if the following \itemize is completely deleted
%% (up to line 352); see also below, line 527 for an alternative part.
\itemize{
\item{\code{thr}}{
[\eqn{\theta_r}{theta_r}] residual water contents
\eqn{\theta_r}{theta_r}}
\item{\code{ths}}{
[\eqn{\theta_s}{theta_s}] staturated water contents
\eqn{\theta_s}{theta_s}}
\item{\code{tha}}{
[\eqn{\theta_a}{theta_a}] fictious parameter
\eqn{\theta_a\le\theta_r}{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 SMWS2d manual
for details.}
\item{\code{thm}}{
[\eqn{\theta_m}{theta_m}]
\eqn{\theta_m\ge\theta_s}{theta_m>=theta_s}, introduced
into the van Genuchten model for more flexibility (to allow for
a non-zero air-entry value)}
\item{\code{Alfa}}{
[\eqn{\alpha}{alpha}] factor \eqn{\alpha}{alpha} in
the van Genuchten model}
\item{\code{n}}{
[\eqn{n}] exponent \eqn{n} in the van Genuchten model}
\item{\code{Ks}}{
[\eqn{K_s}] saturated hydraulic conductivity \eqn{K_s}}
\item{\code{Kk}}{
[\eqn{K_k}] non-saturated hydraulic conductivity
\eqn{K_k} measured for some \eqn{\theta_k}{theta_k}}
\item{\code{thk}}{
[\eqn{\theta_k}{theta_k}] see \eqn{K_k}}
%
\item{\code{first}}{
[1st principal comp] anisotropy parameter for the
conductivity tensor}
\item{\code{second}}{
[2nd principal comp] anisotropy parameter for the
conductivity tensor}
\item{\code{angle}}{
[ange (degrees)] anisotropy parameter for the
conductivity tensor}
%
\item{\code{Hslope}}{
[intial H, slope] The initial matrix potential is
calculated from the
\code{miller.link}ed and then \code{millerH}-transformed
Gaussian random field by linear transformation. \code{Hslope}
and \code{Hseg} give the slope and the segment of that linear
transformation.}
\code{millerH}{ is here the identity, see also
\code{\link{create.waterflow}} for \code{millerH}.}
\item{\code{Hseg}}{
[initial H, segment] see \code{Hslope}}
\item{\code{POptm}}{
[POptm (root)] highest (negative) matrix potention
(so close to saturation) for which the water uptake is still
optimal; see \code{root$P2H} for further information}
\item{\code{sharpness}}{
[sharpness]
The values of a simulated subsequent horizon are obtained by a
linear combination of a conditional simulation and an
independent simulation.
\code{sharpness} is the factor for the independent simuation
and
\eqn{\sqrt{1-\code{sharpness}^2}}{(1-\code{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.}
\code{sharpness}{is not used for the initial horizon, thus not
given as a menue point in this case.}
%
\item{\code{Bulk.d}}{
[bulk density] bulk density}
\item{\code{Diffus}}{
[diffusion] ionic diffusion coeffcient in free water}
\item{\code{longiDisper}}{
[longitud. Dispers.] longitudinal dispersivity}
\item{\code{transvDisper}}{
[transvers. Dispers.] transverse dispersivity}
\item{\code{Adsorp}}{
[Freundlich isoth coeff.] Freundlich
isotherm coefficient}
\item{\code{SinkL1}}{
[1st-order const./dissolved] first-order rate
constant \eqn{\mu_w}{mu_w} for dissolved phase, see page 15 of
the SWMS2d manuscript}
\item{\code{SinkS1}}{
[1st-order const./solid] first-order rate constant
\eqn{\mu_s}{mu_s} for solid phase}
\item{\code{SinkL0}}{
[0-order const./dissolved] zero-order rate
constant \eqn{\gamma_w}{gamma_w} for dissolved phase}
\item{SinkS0}{
[0-order const./solid] zero-order rate constant
\eqn{\gamma_s}{gamma_s} for solid phase}
}
}
%
\item{model}{
[structure] the covariance model for the Gaussian random
fields used for the definition of the Miller similar media.
See \code{\link[RandomFields]{CovarianceFct}} for details on the
definiton of the covariance model.
If the mean equals \code{NA} and if it is genuine last horizon,
the area is interpreted as air.
}
\item{anisotropy}{
logical or \code{NULL}. If logical it overrides the
anisotropy condition given by model. If \code{model} was
anisotropic and \code{anisotropic=FALSE}, the first anisotropic
scale parameter is used as scale for the isotropic model.
If \code{model} is isotropic, only the representation is changed,
and the user has the opportunity to change the values to an
truely anisotropic model.
}
\item{miller.link}{
function that transforms of the Gaussian
random field to a
field of non-negative values. The argument and the value are
matrices (of the same size). If \code{NULL} the \code{miller.link}
is the identity.}
%
\item{chemical}{
[swms2d (chem)] list of the following components
\itemize{
\item{\code{lChem}}{
[Solute transport] logical that indicates whether solute transport should
be modelled}
\item{\code{Epsi}}{
[scheme] temporal weighing coefficient:
1 (explicit: weight=0), 2 (Crank-Nicholson: weight=0.5) or
3 (implicit: weight=1)}
\item{\code{lUpW}}{
[formulation] 1 (upstream weighing formulation)
or 2 (Galerkin formulation)}
\item{\code{lArtD}}{
[added artific. disp] logical. If \code{TRUE}
artificial dispersion is added to satisfy the stability
criterion \code{PeCr}}
\item{\code{PeCr}}{
[PeCr] Stability criterion (Peclet number * Courant
number); usually 2, but can be increase to 5 or 10;
see page 44 of the SWMS2D manuscript.}
\item{\code{tPulse}}{
[pulse duration] time duration of the
concentration pulse}
%
\item{\code{top.bound}}{
[top] boundary condition for soil surface:
1 (impermeable), 2 (Dirichlet), 3 (Neumann), 4 (variable
Concentration), 5 (variable Q), 6 (atmospheric)}
\item{\code{top.value}}{
[top value] value of the boundary condition if
appropriate}
\item{\code{bottom.bound}}{
[bottom] boundary condition for the bottom:
1 (free drainage), 2 (deep drainage), 3 (impermeable)}
\item{\code{bottom.value}}{
[bottom value] value of the boundary condition
if appropriate}
\item{\code{root.uptake}}{
[root uptake] -- not used yet}
\item{\code{intern.source}}{
[internal source] -- not used yet}
%
}
}
%
\item{atmosphere}{[atmosphere, control] list of the following components
\itemize{
\item{\code{AtmInf}}{
[use atmospheric data] logical.}
\item{\code{tInit}}{
[start time of simu.] starting time of the
simulation. This information is necessary since the
\code{atm.data} give the end of an atmospheric period only.
So for the first period the starting time is missing.}
\item{\code{Aqh}}{
[\eqn{A_{qh}}] only used if \code{water$bottom.bound}
equal 2 (deep drainage). Then the modulus of discharge rate equals
\code{step}*\eqn{A_{qh}}\eqn{\exp(B_{qh} |h -
\mbox{GWL0L}|)}{exp(B_qh |h - GWL0L|)} where \eqn{h} is local
pressure head.}
\item{\code{Bqh}}{
[\eqn{B_{qh}}] see \code{Aqh}}
\item{\code{hCritS}}{
[max pressure at surface] maximum allowed pressure
head at the soil surface}
\item{\code{GWL0L}}{
[ref. pos of groundwater] Reference position of
groundwater table (usually the z-coordinate of the soil surface);
only used if
\code{water$bottom.bound} equal 2 (deep drainage)}
}
}
\item{atm.periods}{
(maximum) number of atmospherical periods. Only
used if \code{atm.data} is a vector. Otherwise \code{atm.periods}
is set to the number of rows of \code{atm.data}.}
\item{atm.data}{
[atmosphere, data]
vector of 10 components or matrix of 10 columns.
The 10 components are
\itemize{
\item{\code{end}}{
[end point] end point of the atmospherical
period; the value of of \code{end} for the last atmospherical
period must be greater than the value of \code{TPrint}}
\item{\code{prec}}{
[precipitation] precipitation [L/T]}
\item{\code{cPrec}}{
[solute, precipitation] solute concentration
of rainfall water [\eqn{M/L^3}]}
\item{\code{rSoil}}{
[potential evaporation]
potential evaporation rate [L/T]}
\item{\code{rRoot}}{
[potential transpiration] potential
transpiration rate [L/T]}
\item{\code{hCritA}}{
[abs. min. pressure at surface] absolute
value of the minimum allowed pressure head at the soil surface}
\item{\code{rGWL}}{
[drainage flux (drain or var. Q)] drainage
flux or other time-dependent prescribed flux boundary
condition. For nodes with atmospheric flux condition.}
\item{\code{GWL}}{
[ground water level] groundwater level or other
time-dependent prescribed head boundary condition. For nodes
with atmospheric head condition. Pressure is then
\code{GWL}+\code{GWL0L}.}
\item{\code{crt}}{
[conc. flux (drainage)] time-dependent concentration flux}
\item{\code{cht}}{
[conc. 'pressure' (drain/var. H)] time-dependent
concentration of the first-type boundary condition. See the
SWMS2D manual for details.}
}
}
%
\item{stone}{[stones] list of the following components
%% no error occurs if the following \itemize is completely deleted
%% (up to line 596); see also above, line 230
\itemize{
\item{\code{value}}{
[value] numeric or \code{NA}. \code{NA} is used to
model stones, i.e. water cannot penetrate.
If not \code{NA},
the (Gaussian) random field gets, at the place of the 'stone', the value
\code{value}. This might be of interest if small lenses are modelled
by means of 'stones.}
\item{\code{lambda}}{
[intensity] intensity of the stones}
\item{\code{no.upper}}{
[!overlap into upper horizons] if \code{TRUE}
overlap into any the upper horizon is forbidden}
\item{\code{no.lower}}{
[!overlap into lower horizons] if \code{TRUE}
overlap into any upper horizon is forbidden}
\item{\code{no.overlap}}{
[!overlap of stones] if \code{TRUE} the
overlap of stones is forbidden. This is clear from a practical
point of view. However the currently implemented algorithm
(SSI) 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.}
\item{\code{main.distr}}{
distribution for the length of the main axis of
the ellipse}
\item{\code{main.mean}}{
[main axis, mean] the parameter for the mean of
the distribution}
\item{\code{main.s}}{
[main axis, sd] the parameter for the standard
deviation of the distribution}
\item{\code{sec.distr}}{
distribution for the length of the second axis of
the ellipse}
\item{\code{sec.mean}}{
[second axis, mean] the parameter for the mean of
the distribution}
\item{\code{sec.s}}{
[second axis, sd] the parameter for the standard
deviation of the distribution}
\item{\code{phi.distr}}{
distribution for the angle between the horizontal
line and the main axis of the ellipse}
\item{\code{phi.mean}}{
[second axis, mean] the parameter for the mean of
the distribution}
\item{\code{phi.s}}{
[second axis, sd] the parameter for the standard
deviation of the distribution}
}
}
\item{plant.types}{positive integer. Number of different type of
plants that will be generated}
\item{Kf}{function(plant, distance, depth).
According to the parameter the (Gaussian) random field get
a new value if there is a root pixel.
Here, \code{plant} is the type
of plant, \code{distance} the distance from the current position
to the surface along the root, and depth is the depth of the current
position.
Only used if \code{root$rf.Kf} is \code{TRUE} for the specific
plant type. This function is still in an experimental stage.}
\item{beta}{function(plant, distance, depth) gives the raw
potential root
water uptake according to the \code{plant} type, the \code{distance}
to the beginning of the root and the \code{depth}. The raw potential
values are subsequently normed such they sum up to one. This gives the
potential root water uptake.}
\item{root}{[root growth] for \code{plants.lambda} to \code{dir.ch.s}
and [root, water uptake] otherwise. Any plant type is set to the
values of \code{root} at starting time.
List of the following components
\itemize{
\item{\code{plants.lambda}}{
[mean \# of plants] the number of
plants is Poisson distributed with mean \code{plants.lambda}}
\item{\code{plants.mindist}}{
[min. plant. dist.] plants of the
same species are at least \code{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.}
\item{\code{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 \code{mean}, but the algorithm is not
too sophisticated to guarantee this.}
\item{\code{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 \code{sd}}
\item{\code{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 \code{knot.mindist}. Then the
probability for a knot is 0.}
\item{\code{knot.mindist}}{
[min. knot diXstance] see \code{knot.probab}}
\item{\code{shoots.3}}{
[3 shoots probab.] positive number, see
\code{shoots.4}}
\item{\code{shoots.4}}{
[4 shoots probab.] positive number.
\itemize{
\item \code{shoots.4}\eqn{\ge}{>=}1
knots have always 4 shoots.
\item \code{shoots.4}\eqn{<}1
and \code{shoots.4}+\code{shoots.3}\eqn{\ge}{>=}1
knots have with probability \code{shoots.4} 4 shots and 3
shoots otherwise.
\item \code{shoots.4}\eqn{<}1
and \code{shoots.4}+\code{shoots.3}\eqn{\ge}{<}1
knots have 4, 3, 2 shoots with probability \code{shoots.4},
\code{shoots.3} and 1-\code{shoots.4}-\code{shoots.3},
respectively
}
}
\item{\code{stop.probab}}{
\code{function(knot, dist, stop.m, stop.s)}
that returns a values in \eqn{[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. \code{knot} is the number of knots preceding and
including the current pixel,
\code{dist} is the distance to the surface along the root,
\code{stop.m} and \code{stop.s} are arbitrary
additional parameters.}
\item{\code{stop.m}}{
[stop probability, m], see \code{stop.probab}}
\item{\code{stop.s}}{
[stop probability, s], see \code{stop.probab}}
\item{\code{rf.link}}{
\code{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.
\code{rf.link} transforms the value of the simulated
Gaussian random field where \code{rf.m} and \code{rf.s}
are additional parameters.}
\item{\code{rf.m}}{
[random field link, m], see \code{rf.link}}
\item{\code{rf.s}}{
[random field link, s], see \code{rf.link}}
\item{\code{no.own.root}}{
[own root penetration], if \code{TRUE} a
pixel may contain at most one root part.}
\item{\code{age.bonus}}{
[age bonus]
factor by which the priority number of a pixel is
multiplied after each step. The \code{age.bonus}
is usually greater than or equal to 1.}
\item{\code{depth.bonus}}{
[depth bonus] summand added to the
priority if the subsequent pixel is below the current root pixel}
\item{\code{side.bonus}}{
[side bonus] summand added to the
priority if the subsequent pixel has the same depth than
the current root pixel; see \code{depth.bonus} for deeper
points.}
\item{\code{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 \eqn{d} between 0 and 4.
E.g., if the sequence of root pixels ghas (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,
\eqn{d=1+2=3}.
Let \eqn{v=d \code{dir.ch}}{v = d * \code{dir.ch}}.
Then the summand for the priority of a pixel is given by normal random
variable with mean v and \eqn{sd=|v| \code{dir.ch.s}}.}
\item{\code{dir.ch.s}}{
[no dir. change, rel. sd] see \code{dir.ch}}
\item{\code{rf.Kf}}{
[root, water uptake][root changes field value]
logical. If \code{TRUE} the value of the (Gaussian) random
field at a root segment
is changed according to the function \code{Kf}.}
\item{\code{P0}}{
[root, water uptake][P0] (negative) pressure
above which too less
oxygene to allow water uptake by plants}
\item{\code{P2H}}{
[root, water uptake][P2H], \code{P2H}, \code{P2L},
\code{r2H} and \code{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 \code{materials$POptm}.
See the SWMS2D manual for details.}
\item{\code{P2L}}{
[root, water uptake][P2L] see \code{P2H}}
\item{\code{r2H}}{
[root, water uptake][r2H] see \code{P2H}}
\item{\code{r2L}}{
[root, water uptake][r2L] see \code{P2H}}
\item{\code{P3}}{
[root, water uptake][P3] (negative) pressure below which
no water uptake is possible}
\item{\code{root.condition}}{
[root, water uptake][root water uptake]}
\item{\code{root.uptake}}{
[root, water uptake][water uptake value]}
}
}
%
\item{MaxIt}{
maximum number of iteration during any time step.}
\item{hTab}{
\code{c(hTab1, hTabN)}, interval of pressure heads
within which a table of hydraulic properties is generated.}
\item{dtMinMax}{
\code{c(dtmin, dtmax)}, minimum and maximum permitted
time increment.}
\item{DMul}{
\code{c(dMul, dMul2)},
\eqn{\code{dMul}\ge 1}{\code{dMul >= 1}},
\eqn{\code{dMul2}\le 1}{\code{dMul2 <= 1}};
if number of required iterations is less than 4 or greater than 6
then the next time
step is multiplied by \code{dMul} and \code{dMul2}, respectively.}
%
\item{col.rect}{
colour of the button for free input; see
\code{\link[RandomFields]{eval.parameters}}}
\item{col.bg}{
colour of a interactive bar; see
\code{\link[RandomFields]{eval.parameters}}}
\item{col.sep}{
colour of the separating line; see
\code{\link[RandomFields]{eval.parameters}}}
\item{col.left}{
colour of preceding element; see
\code{\link[RandomFields]{eval.parameters}}}
\item{col.mid}{
colour for the message; see
\code{\link[RandomFields]{eval.parameters}}}
\item{col.right}{
colour of subsequent element; see
\code{\link[RandomFields]{eval.parameters}}}
\item{col.line}{
colour of the marking line in interactive bars of
absolute choice; see \code{\link[RandomFields]{eval.parameters}}}
\item{col.txt}{
colour of headers; see
\code{\link[RandomFields]{eval.parameters}}}
\item{col.submenue}{
colour for text of main menue}
\item{col.subord}{
colour for text of title of secondary menue}
\item{col.forbid}{colour for
text of forbidden main menues, e.g. 'polygon' after
having defined already the maximum number of allowed horizons}
\item{col.bg.forbid}{background colour for forbidden menue points}
\item{col.flash}{
colour for hints or the titles of active windows}
\item{col.hor}{
sequence of colours that are used to draw the horizons}
\item{col.draw}{
colour for drawing and for showing selected horizons}
\item{col.mess}{
colour for warning or error messages}
\item{col.rf}{
sequence of colours that are used to show the
random field}
\item{col.simu}{
seqeuence of colours that are used to present any
simulation result by swms2d}
\item{col.mesh}{
colour for the edges of the finite element mesh}
\item{col.mesh.pt}{
colour for the vertices of the finite element mesh}
%
\item{update}{
[updating] logical. If \code{TRUE} the simulations are
updated after any changing of the parameters.}
\item{waterflow}{
[water flow] logical. If \code{TRUE} swms2d is run}
\item{upper.lim.z}{
numeric. The value of \code{zlim[2]} in
\code{image} equals the \code{upper.lim.z} quantile of
the random field values when the transformed random field is plotted.}
\item{areas}{
logical. If \code{TRUE} the horizons are coloured. If
\code{FALSE} only the borders between the horizons are given.}
\item{PrintLevel}{
If \eqn{\le}{<=}0 nothing is printed. The higher the
value the information is given.}
\item{new}{
logical or \code{NULL}. If \code{TRUE} the interactive plot is opened in
a new window. If \code{NULL} then the interactive window is not
opened and the standard definitions are returned.}
\item{X11.width}{
numeric. Height of the window. Only used if
\code{new=TRUE}.}
\item{X11.height}{n
umeric. Height of the window. Only used if
\code{new=TRUE}.}
%
\item{print.par}{
[postscript] list of the following components
\itemize{
\item{\code{ps}}{
[ps base name] character. Base name of the
postscript file.}
\item{\code{height}}{
[picture height] numeric. Height of the
postscript figure in inches.}
\item{\code{title}}{
[plot title] logical. If \code{TRUE} a
title is plotted.}
}
}
%
}
\details{
Menue points of the interactive plot are
\describe{
\item{postscript}{plotting
the water potential \eqn{H},
discharge/recharge rates \eqn{Q} for internal sink/sources,
the water contents \eqn{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 given whether the
'precise water flow' or the result of the approximate 'water flow'
is given (according to the main menu point 'precise waterflow')
and subsequent update of simulation.
Further the random field might be plotted.
For the additional parameters, see the input variable \code{print.par}.
}
\item{polygon}{Clicking with the left mouse key in the upper left
drawing area defines the vertices of the polygon. Up to 512
vertices are allowed. The right mouse key terminates the
drawing.
A polygon must consist of at least three points. The points may
such that the connecting lines cross.
}
\item{horizon}{Clicking with the left mouse key in the upper left
drawing area defines the border of the horizon. Up to 512
vertices are allowed. The right mouse key 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.
}
\item{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 clicking 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
\code{\link[RandomFields]{ShowModels}} for details,
\describe{
\item{bottom left}{a simulation of the Gaussian random field
with the specified parameters.}
\item{top left}{the covariance function or the variogram for
the random field and the the transformed random field according
to \code{miller.link}. If the \code{model} is anisotrope or
\code{anisotrop=TRUE} is given explicitely, the models are shown
for the two main axis.
}
\item{right}{from top to bottom: 'simulate' is 'updating' in the
main menue is \code{FALSE}, the name of the model, the formula,
the specific parameters if there are any, variance, nugget
effect, the scale parameter or the anisotropy paramters, and the
mean.
If 'practical range'=\code{TRUE} then the (isotropic) covariance
model is
rescaled such that at distance 1 the value of the model is
approximately 0.05. Finally, 'variogram' switches between the
presentation of the variogram and the corresponding covariance
function.
}
}
This menue is left by the right mouse bottom and then a menue for
choosing a variogram model is reached. Right mouse bottom again
leaves the whole menue for 'structure'.
The first horizon gets as default the model and the
parameter values passed to \code{xswms2d} by \code{model} and
\code{anisotropy}.
For the following horizons the values of the previously considered
horizon are taken over, when considered first.
}
\item{stones}{definition of the stones}
\item{root growth}{definition of the root growth; if \code{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, and
is used nowhere else. The decription of all the other variables
('mean \# of plants',...,'no dir. change, rel. sd') is given for
the input variable \code{root}.
}
\item{material[phys]}{Definition of the physical material constants,
see variable \code{materials}.}
\item{material[chem]}{Definition of the chemical material constants,
see variable \code{materials}.}
\item{root water uptake}{
Definition of the water uptake by the roots. See the variable
\code{root}.}
\item{atmosphere, data}{
See the variable \code{atm.data} for a description.
If \code{nrow(atm.data)} or \code{atm.periods} is greater than 1
then the user chooses the atmospherical period first.
}
\item{swms2d [water]}{see the variable \code{water} for a description}
\item{swms2d [chem]}{see the variable \code{chemical} for a description}
\item{atmosphere control}{see the variable \code{atmosphere}
for a description}
\item{new simulation}{If parameters are changed, simulations are
redone reusing previous parts 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.
}
\item{precise waterflow}{By 'swms2d water',
submenue 'size reduction' (variable \code{water$red}) the finite
element mesh can be coarsened for faster simulations. If the
coarsening is genuine, i.e. \code{water$red}\eqn{>}1, then this
menue point is active. If pressed, a simulation is performed on
the original finite element mesh.}
\item{water flow}{yes/no. If 'no', only the Gaussian random field,
the stones and the roots are simulated.}
\item{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.}
\item{end}{terminates the interactive surface}
}
General information
\itemize{
\item Currently, the number of horizons is limited to max.horizon=10.
\item The horizons are build up from the bottom, i.e. first, the
boundary for C horizon should be drawn then those for the B
horizons, etc.
\item If the mean of the last genuine(!)
horizon is defined \code{NA} within the menue
'structure', then this part of the profile is interpreted as air and
the previously defined horizons are genuine ones.
Any other horizon but the last one should not have mean
\code{NA}.
\item Polygons are used to define large lenses or to circumvent the
the predefined ordering of horizons.
\item The ordering (as the sequence in which the horizons and
polygons are defined, not their position in the profile)
of the horizons and polygons is used in the conditional simulation
of the Gaussian random fields, where conditioning happens with
respect to preceding horizons.
\item First the Gaussian random field is simulated, starting with
the first horizon. After simulation of the complete profile, the
stones are simulated, then the roots. If 'water flow 'yes'
then the SWMS2D simulation is performed. See
\code{\link{simulate.horizons}}
and the references therein for further details on the stochastic
simulation. See the SWMS2D manuscript for details on SWMS2D.
\item If a parameter was changed, usually only a part of the
simulations is redone, namely that level of simulation that
corresponds to the parameter (random field for a specific horizon,
stones, roots, SWMS2D) and all subsequent levels.
For example, if a stone parameter has been changed, the simulation of
the stones and the roots is done, and SWMS2D is performed.
}
}
\note{In phrases in brackets in the argument section of this documents
give the respective menue points of the interactive plot.}
\value{
A list, where
the first 10 components contain the definition 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.
\item{1:10}{
Each of the first 10 components is a list of the following
elements:
\itemize{
\item{\code{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').}
\item{\code{cut.x},\code{cut.y}}{
\code{cut.x} and \code{cut.y} define the horziontal and
vertical position of a rectangle, respective, which encloses the
whole horizon or polygon. \code{cut.x} and \code{cut.y} should be
as tight as possible, to accelerate the simulation of the random
fields for the horizons.}
\item{\code{stone}}{
list of stone parameters, see the input variable
\code{stone}. The input parameters are the default parameters for
all stone specifications}
\item{\code{materials}}{
list of material constants, see the input variable
\code{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)}
\item{\code{model}}{
list or \code{NULL}. Covariance model in list format, see
\code{\link[RandomFields]{CovarianceFct}}.
The \code{model} is \code{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
\code{model} is set to \code{NULL} for the 'Start' horizon.}
\item{\code{border}}{
matrix of two columns or \code{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.
\code{border} is \code{NULL} if only the 'Start' horizon exists.}
\item{\code{idx}}{
matrix of logical values with \code{diff(cut.x)+1} rows
and \code{diff(cut.y)+1} columns. \code{idx} indicates which
pixels of the \code{cut.x}\eqn{\times}{x}\code{cut.y} area belongs
to the present horizon.}
}
}
\item{grid.x}{\code{seq(xlim[1], xlim[2], step)}}
\item{grid.y}{\code{seq(ylim[1], xlim[2], step)}}
\item{idx.rf}{integer. Matrix of size
\code{length(grid.x)}\eqn{\times}{x}\code{length(grid.y)}
indication the affiliation to a horizon or polygon (number is
decremented by 1, i.e., \eqn{0,...,\code{h$n}-1}), see also
the output variable \code{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 max.horizon=10.
The modulus by max.horizon gives the by 1 decremented
number of the horizon.
}
\item{n}{current number of horizons}
\item{step}{input parameter \code{step}}
\item{beta}{input parameter \code{beta}}
\item{root}{list, where \code{length($root)} equals the
input parameter \code{plant.types}.
Each component of the list is a list with the same components as
the input parameter \code{root}. Additionally, it has the
component \code{plant.type} a user defined name of the species.
}
\item{atmophere}{input parameter \code{atmosphere}}
\item{atm.data}{matrix of 10 columns, corresponds to the input
parameter \code{atm.data} and \code{atm.periods}.}
\item{water}{input parameter \code{water}}
\item{chem}{input parameter \code{chemical}}
\item{Kf}{input parameter \code{Kf}}
\item{RF}{matrix of size
\code{length(grid.x)}\eqn{\times}{x}\code{length(grid.y)} or \code{NULL}.
\code{RF} contains the Gaussian random field resulting from all
definitions for the horizons.
\code{RF} is \code{NULL} if
\code{simulate.horizon} has not been called yet.
}
\item{rf}{matrix of size
\code{length(grid.x)}\eqn{\times}{x}\code{length(grid.y)} or
\code{NULL}.
The value of \code{rf} is the Gaussian random field modified by the
stones and the roots (concerning hydraulic conductivity).
Stones have usually value \code{NA}, whereas air has value
\code{NaN}. Further, if \code{root$rf.Kf} is \code{TRUE}
the values at the respecitve root segments are given by
\code{h$KF}.
\code{rf} is \code{NULL} if
\code{simulate.horizon} has not been called yet or terminated
with an error. Further \code{rf} is set to \code{NULL} if
\code{materials$sharpness} has been changed, or 'structure',
'undo', 'horizon', or 'polygon' has
been called.}
\item{m.link}{link function used in the submenue 'structure',
currently the function is identical to \code{miller.link}}
\item{miller.link}{input parameter \code{miller.link}}
\item{random.seed}{list or \code{NULL}.
Each element contains the random seed for
simulation of the Gaussian random field in the respective horizon.
\code{random.seed} is \code{NULL} if
\code{\link{simulate.horizons}}
has not been called yet.
}
\item{stone.random.seed}{The random seed for the simulation of the stones}
\item{root.random.seed}{The random seed for the simulaton of the roots}
\item{rf.complete}{logical. \code{TRUE} if the stochastic simulation
has been performed completely.}
\item{stones.ok}{\code{TRUE} or \code{NULL}. \code{TRUE} if the
simulation of the stones is up to date.}
\item{plants}{list or \code{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 pixels that contain a part of the
roots.
The 8 columns are
\enumerate{
\item horizontal coordinate of a root segment.
The coordinate is given in pixels.
\item vertical coordinate of a root segment,
For the first pixel it is 1 plus the vertical position of the first
pixel that is not air at the drawn horizontal pixel.
\item index for the parent root pixel
\item index where the subsequent root pixel is found; \code{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 others
follow immediately.
\item number of children in case it is a knot, 1 otherwise
\item the number of preceding knots until and including this position
\item aimed random total length of the roots if it is the first
pixel, and the current distance to the surface along the roots,
otherwise.
\item distance to the preceding knot
}
\code{plants} is \code{NULL} is \code{\link{simulate.horizons}}
has not been called yet, or any parameter in \code{root}
has been changed.
}
\item{plants.idx}{vector or \code{NULL}. \code{plant.idx[i]} gives the
plant type (\eqn{1,\ldots,\code{}}{1,...,\code{plant.types}})
of the \code{i}th simulated plant.
\code{plants.idx} is \code{NULL} if
\code{\link{create.roots}} or \code{\link{simulate.horizons}}
has not been called yet.}
\item{water.x}{the coordinates of \code{grid.x} after thinning by
factor \code{water$red}}
\item{water.y}{the coordinates of \code{grid.y} after thinning by
factor \code{water$red}}
\item{flux}{logical vector of
\code{length(water.x)}\eqn{\times}{x}\code{length(water.y)} elements.
\code{flux} indicates which pixels of the
\code{length(water.x)}\eqn{\times}{x}\code{length(water.y)}
grid are used in the SWMS2D simulation. (Pixel are left out
if they indicate stones (\code{NA}) or air (\code{NaN}).)
}
\item{swms2d}{three dimensional array or \code{NULL}.
The first dimension has 6 components which are
\enumerate{
\item the water potential \eqn{H}
\item discharge/recharge rates \eqn{Q} for internal sink/sources
\item the water contents \eqn{theta}
\item the x-components of the Darcian flux vector vx
\item the z-components of the Darcian flux vector vz
\item the concentration
}
The second component corresponds to the sequence of pixels
used in the SWMS2D simulation and has length \code{sum(flux)}.
\code{swms2s} is \code{NULL} if
water flux has not been simulated yet
because no simulation has been performed or one of the stochatic
simulations (Gaussian random field, stones, roots) failed,
or 'water flow' has been
set to 'no'. Further \code{swms2d} is set to \code{NULL}
if an error occures when trying to plot
the SWMS2D simulation results (by \code{\link{plotWater}}); this
happens if the result has no finite values.
Finally, \code{swms2d} is set to \code{NULL} if one relevant
parameters are changed, such as those in
\code{atmosphere}, \code{atm.data}, \code{materials}, \code{chem}
or \code{water}.
}
Any of the lists that contain input parameters may have as additional
component \code{.last.par}, an internal variable used the menue programme.
}
\section{Warning}{The user should consider the following parameters
of \code{h[[i]]} as being read-only:
\itemize{
\item \code{cut.x}
\item \code{cut.y}
\item \code{border}
\item \code{idx}
}
}
\author{Martin Schlather, \email{Martin.Schlather at uni-bayreuth.de}
\url{http://www.geo.uni-bayreuth.de/~martin}}
\references{
\itemize{
\item
Simunek., J., Vogel, T., and van Genuchten, M.Th. (1994)
\emph{The SWMS2D code for simulating water flow and solute transport
in two-dimensional variably saturated media, Version 1.21.}
Research Report No. 132, 197 p.,
U.S. Salinity Laboratory, USDA, ARS, Riverside, California.
\item Stoyan, D., Kendall, W.S., Mecke, J. (1995)
\emph{Stochastic Geometry and its Applications} Chichester: Wiley, 2nd
edition.
\item Schlather, M., Huwe, B. (2003)
SOPHY -- an interactive programme for water flow modelling.
\emph{In preparation}
}
}
\seealso{\code{\link{calculate.horizons}},
\code{\link{create.roots}},
\code{\link{create.stones}},
\code{\link{create.waterflow}},
\code{\link{draw.horizons}},
\code{\link{modify.horizons}},
\code{\link{plotRF}},
\code{\link{plotWater}},
\code{\link{simulate.horizons}},
\code{\link{SoPhy}},
\code{\link{swms2d}}
}
\examples{
% library(SoilPhysics, lib="~/TMP"); library(RandomFields)
% source("/home/schlather/article/R/SOPHY/SoilPhysics/R/simu.R")
% source("/home/schlather/article/R/SOPHY/SoilPhysics/R/Sophy.R")
xswms2d(xlim=c(1, 100), ylim=c(1, 100), step=1)
}
\keyword{spatial}
--------------090000060304060401040205--
More information about the R-devel
mailing list