xswms2d                package:SoPhy                R Documentation

_M_o_d_e_l_l_i_n_g _o_f _w_a_t_e_r _f_l_u_x _a_n_d _s_o_l_u_t_e _t_r_a_n_s_p_o_r_t

_D_e_s_c_r_i_p_t_i_o_n:

     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.

_U_s_a_g_e:

     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)   
     )

_A_r_g_u_m_e_n_t_s:

       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

          '_T_P_r_i_n_t' {_T_P_r_i_n_t} 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.


          '_r_e_d' {_s_i_z_e _r_e_d_u_c_t_i_o_n} positive integer. to increase the
               simulation spead the size of the finite element grid can
               coarsened

          '_p_r_i_n_t' {_p_r_i_n_t_e_d _v_a_r_i_a_b_l_e} 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.


          '_m_e_s_h' {_s_h_o_w _F_E _m_e_s_h} logical.  If 'TRUE' the currently used
               finite element mesh in a swms2d simulation is shown in
               the upper left drawing area.

          '_l_i_m._r_f' {_u_p_p_e_r _q_u_a_n_t_i_l_e _f_o_r _r_a_n_d_o_m _f_i_e_l_d _p_l_o_t} 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.

          '_l_i_m._s_w_m_s_2_d' {_q_u_a_n_t_i_l_e _f_o_r _s_w_m_s_2_s _p_l_o_t} numeric in [0,1]. See
               'plotWater' for details.

          '_T_o_l_T_h' {_T_o_l_T_h} maximum desired change of water content
               within one step of the FE method.

          '_T_o_l_H' {_T_o_l_H} maximum desired change of pressure head within
               one step of the FE method.

          '_l_W_a_t' {_L_W_a_t} logical. If 'TRUE' transient water flow else
               steady state.

          '_d_t' {_d_t - _i_n_i_t_i_a_l _t_i_m_e _s_t_e_p} initial time increment of the
               FE method.

          '_d_t_M_i_n_M_a_x' {_m_i_n_i_m_a_l _t_i_m_e _s_t_e_p} _a_n_d {_m_a_x_i_m_a_l _t_i_m_e _s_t_e_p} 'c(dtm
               in, dtmax)', minimum and maximum permitted time
               increment of the FE method.

          '_m_a_x._i_t_e_r_a_t_i_o_n' {_m_a_x. _i_t_e_r_a_t_i_o_n_s} 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.

          '_m_a_x._i_t_e_r._p_r_e_c' {_m_a_x. _i_t_e_r. (_p_r_e_c_i_s_e)} same as
               'max.iteration' except that this value is used if the
               main menue bottom "precise waterflow" is pressed.

          '_i_t_e_r._p_r_i_n_t' {_s_w_m_s _m_e_s_s_a_g_e, _l_o_o_p _p_e_r_i_o_d} number of
               incremental time steps after which a short message of
               status is given.

          '_b_r_e_a_k_p_o_i_n_t' {_s_w_m_s, _i_m_a_g_e, _l_o_o_p _p_e_r_i_o_d} 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.

          '_t_o_p._b_o_u_n_d' {_t_o_p} surface boundary condition: 1
               (impermeable), 2 (Dirichlet), 3 (Neumann), 4 (variable
               H), 5 (variable Q), or 6 (atmospheric).  See the SWMS2D
               manual for details.

          '_t_o_p._v_a_l_u_e' {_t_o_p _v_a_l_u_e} the value of the 'top.bound'
               condition, if appropriate.

          '_b_o_t_t_o_m._b_o_u_n_d' {_b_o_t_t_o_m} boundary condition at the bottom: 1
               (free drainage), 2 (deep drainage), 3 (impermeable), 4
               (Dirichlet), or 5 (Neumann).  See the SWMS2D manual for
               details.

          '_b_o_t_t_o_m._v_a_l_u_e' {_b_o_t_t_o_m _v_a_l_u_e} 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

          '_t_h_r' {_t_h_e_t_a__r} residual water contents theta_r

          '_t_h_s' {_t_h_e_t_a__s} staturated water contents theta_s

          '_t_h_a' {_t_h_e_t_a__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.

          '_t_h_m' {_t_h_e_t_a__m} theta_m>=theta_s, introduced  into the van
               Genuchten model for more flexibility (to allow for a
               non-zero air-entry value)

          '_A_l_f_a' {_a_l_p_h_a} factor alpha in the van Genuchten model

          '_n' {_n} exponent n in the van Genuchten model

          '_K_s' {_K__s} saturated hydraulic conductivity K_s

          '_K_k' {_K__k} non-saturated hydraulic conductivity K_k measured
               for some theta_k

          '_t_h_k' {_t_h_e_t_a__k} see K_k

          '_f_i_r_s_t' {_1_s_t _p_r_i_n_c_i_p_a_l _c_o_m_p} anisotropy parameter for the
               conductivity tensor

          '_s_e_c_o_n_d' {_2_n_d _p_r_i_n_c_i_p_a_l _c_o_m_p} anisotropy parameter for the
               conductivity tensor

          '_a_n_g_l_e' {_a_n_g_l_e (_d_e_g_r_e_e_s)} anisotropy parameter for the
               conductivity tensor

          '_H_s_l_o_p_e' {_i_n_t_i_a_l _H, _s_l_o_p_e} The initial matrix potential is
               calculated from the 'miller.link'ed 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.

          '_H_s_e_g' {_i_n_i_t_i_a_l _H, _s_e_g_m_e_n_t} see 'Hslope' and 'Hinit'

          '_P_O_p_t_m' {_P_O_p_t_m (_r_o_o_t)} highest (negative) matrix potential
               (so close to saturation) for which the water uptake is
               still optimal; see 'root$P2H' for further information

          '_s_h_a_r_p_n_e_s_s' {_s_h_a_r_p_n_e_s_s} 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.

          '_B_u_l_k._d' {_b_u_l_k _d_e_n_s_i_t_y} bulk density

          '_D_i_f_f_u_s' {_d_i_f_f_u_s_i_o_n} ionic diffusion coeffcient in free water

          '_l_o_n_g_i_D_i_s_p_e_r' {_l_o_n_g_i_t_u_d. _D_i_s_p_e_r_s.} longitudinal dispersivity

          '_t_r_a_n_s_v_D_i_s_p_e_r' {_t_r_a_n_s_v_e_r_s. _D_i_s_p_e_r_s.} transverse dispersivity

          '_A_d_s_o_r_p' {_F_r_e_u_n_d_l_i_c_h _i_s_o_t_h _c_o_e_f_f.} Freundlich isotherm
               coefficient

          '_S_i_n_k_L_1' {_1_s_t-_o_r_d_e_r _c_o_n_s_t./_d_i_s_s_o_l_v_e_d} first-order rate
               constant mu_w for dissolved phase, see page 15 of the
               SWMS2d manuscript

          '_S_i_n_k_S_1' {_1_s_t-_o_r_d_e_r _c_o_n_s_t./_s_o_l_i_d} first-order rate constant
               mu_s for solid phase

          '_S_i_n_k_L_0' {_0-_o_r_d_e_r _c_o_n_s_t./_d_i_s_s_o_l_v_e_d} zero-order rate constant
               gamma_w for dissolved phase

          '_S_i_n_k_S_0' {_0-_o_r_d_e_r _c_o_n_s_t./_s_o_l_i_d} 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.link'ed 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.link'ed 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.link'ed 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

          '_l_C_h_e_m' {_S_o_l_u_t_e _t_r_a_n_s_p_o_r_t} logical that indicates whether
               solute transport should be modelled

          '_E_p_s_i' {_s_c_h_e_m_e} integer 1,2,3.  Temporal weighing
               coefficient: 1 (explicit: weight=0), 2 (Crank-Nicholson:
               weight=0.5) or 3 (implicit: weight=1)

          '_l_U_p_W' {_f_o_r_m_u_l_a_t_i_o_n} 1 (upstream weighing formulation) or 2
               (Galerkin formulation)

          '_l_A_r_t_D' {_a_d_d_e_d _a_r_t_i_f_i_c. _d_i_s_p} logical.  If 'TRUE' artificial
               dispersion is added to satisfy the stability criterion
               'PeCr'

          '_P_e_C_r' {_P_e_C_r} Stability criterion (Peclet number * Courant
               number); usually 2, but can be increased to 5 or 10; see
               page 44 of the SWMS2D manuscript.

          '_t_P_u_l_s_e' {_p_u_l_s_e _d_u_r_a_t_i_o_n} time duration of the concentration
               pulse

          '_t_o_p._b_o_u_n_d' {_t_o_p} boundary condition for soil surface: 1
               (impermeable), 2 (Dirichlet), 3 (Neumann), 4 (variable
               Concentration), 5 (variable Q), 6 (atmospheric)

          '_t_o_p._v_a_l_u_e' {_t_o_p _v_a_l_u_e} value of the boundary condition if
               appropriate

          '_b_o_t_t_o_m._b_o_u_n_d' {_b_o_t_t_o_m} boundary condition for the bottom: 1
               (free drainage), 2 (deep drainage), 3 (impermeable)

          '_b_o_t_t_o_m._v_a_l_u_e' {_b_o_t_t_o_m _v_a_l_u_e} value of the boundary condition
               if appropriate

          '_r_o_o_t._u_p_t_a_k_e' {_r_o_o_t _u_p_t_a_k_e} - not implemented yet

          '_i_n_t_e_r_n._s_o_u_r_c_e' {_i_n_t_e_r_n_a_l _s_o_u_r_c_e} - not implemented yet

atmosphere: {atmosphere, control} list of the following components 

          '_A_t_m_I_n_f' {_u_s_e _a_t_m_o_s_p_h_e_r_i_c _d_a_t_a} logical.  Determines whether
               or not atmospherical data should be used.

          '_t_I_n_i_t' {_s_t_a_r_t _t_i_m_e _o_f _s_i_m_u} 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.

          '_A_q_h' {_A_{_q_h}} 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. 

          '_B_q_h' {_B_{_q_h}} see 'Aqh'

          '_h_C_r_i_t_S' {_m_a_x _p_r_e_s_s_u_r_e _a_t _s_u_r_f_a_c_e} maximum allowed pressure
               head at the soil surface

          '_G_W_L_0_L' {_r_e_f. _p_o_s _o_f _g_r_o_u_n_d_w_a_t_e_r} Reference position of the
               groundwater table (usually the z-coordinate of the soil
               surface); only used if 'water$bottom.bound' equals 2
               (deep drainage)

          '_r_L_e_n' {_w_i_d_t_h _o_f _s_o_i_l (_t_r_a_n_s_p_i_r_a_t_i_o_n)} 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

          '_e_n_d' {_e_n_d _p_o_i_n_t} end point of the atmospherical period; the
               value of 'end' for the last atmospherical period must be
               greater than the value of 'TPrint'

          '_p_r_e_c' {_p_r_e_c_i_p_i_t_a_t_i_o_n} precipitation 


          '_c_P_r_e_c' {_s_o_l_u_t_e, _p_r_e_c_i_p_i_t_a_t_i_o_n} solute concentration of
               rainfall water 


          '_r_S_o_i_l' {_p_o_t_e_n_t_i_a_l _e_v_a_p_o_r_a_t_i_o_n} potential evaporation rate 


          '_r_R_o_o_t' {_p_o_t_e_n_t_i_a_l _t_r_a_n_s_p_i_r_a_t_i_o_n} potential transpiration
               rate 


          '_h_C_r_i_t_A' {_a_b_s. _m_i_n. _p_r_e_s_s_u_r_e _a_t _s_u_r_f_a_c_e} absolute value of
               the minimum allowed pressure head at the soil surface

          '_r_G_W_L' {_d_r_a_i_n_a_g_e _f_l_u_x (_d_r_a_i_n _o_r _v_a_r. _Q)} drainage flux or
               other time-dependent prescribed flux boundary condition.
               For nodes with atmospheric flux condition.

          '_G_W_L' {_g_r_o_u_n_d _w_a_t_e_r _l_e_v_e_l} groundwater level or other
               time-dependent prescribed head boundary condition. For
               nodes with atmospheric head condition.  Pressure is then
               'GWL'+'GWL0L'.

          '_c_r_t' {_c_o_n_c. _f_l_u_x (_d_r_a_i_n_a_g_e)} time-dependent concentration
               flux

          '_c_h_t' {_c_o_n_c. '_p_r_e_s_s_u_r_e' (_d_r_a_i_n/_v_a_r. _H)} time-dependent
               concentration of the first-type boundary condition.  See
               the SWMS2D manual for details.

   stone: {stones} list of the following components

          '_v_a_l_u_e' {_v_a_l_u_e} 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'.

          '_l_a_m_b_d_a' {_i_n_t_e_n_s_i_t_y} intensity of the stones

          '_n_o._u_p_p_e_r' {!_o_v_e_r_l_a_p _i_n_t_o _u_p_p_e_r _h_o_r_i_z_o_n_s} if 'TRUE' overlap
               into any upper horizon is forbidden

          '_n_o._l_o_w_e_r' {!_o_v_e_r_l_a_p _i_n_t_o _l_o_w_e_r _h_o_r_i_z_o_n_s} if 'TRUE' overlap
               into any lower horizon is forbidden

          '_n_o._o_v_e_r_l_a_p' {!_o_v_e_r_l_a_p _o_f _s_t_o_n_e_s} 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.

          '_m_a_i_n._d_i_s_t_r' distribution for the length of the main axis of
               the ellipse

          '_m_a_i_n._m_e_a_n' {_m_a_i_n _a_x_i_s, _m_e_a_n} the parameter for the mean of
               the distribution

          '_m_a_i_n._s' {_m_a_i_n _a_x_i_s, _s_d} the parameter for the standard
               deviation of the distribution

          '_s_e_c._d_i_s_t_r' distribution for the length of the second axis of
               the ellipse

          '_s_e_c._m_e_a_n' {_s_e_c_o_n_d _a_x_i_s, _m_e_a_n} the parameter for the mean of
               the distribution

          '_s_e_c._s' {_s_e_c_o_n_d _a_x_i_s, _s_d} the parameter for the standard
               deviation of the distribution

          '_p_h_i._d_i_s_t_r' distribution for the angle between the horizontal
               line and the main axis of the ellipse

          '_p_h_i._m_e_a_n' {_s_e_c_o_n_d _a_x_i_s, _m_e_a_n} the parameter for the mean of
               the distribution

          '_p_h_i._s' {_s_e_c_o_n_d _a_x_i_s, _s_d} 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

          '_p_l_a_n_t_s._l_a_m_b_d_a' {_m_e_a_n # _o_f _p_l_a_n_t_s} the number of plants is
               Poisson distributed with mean 'plants.lambda'

          '_p_l_a_n_t_s._m_i_n_d_i_s_t' {_m_i_n. _p_l_a_n_t. _d_i_s_t.} 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.

          '_m_e_a_n' {_a_i_m_e_d _m_e_a_n _t_o_t_a_l _l_e_n_g_t_h} 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.

          '_s_d' {_a_i_m_e_d _s_d _o_f _t_o_t_a_l _l_e_n_g_t_h} 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'

          '_k_n_o_t._p_r_o_b_a_b' {_k_n_o_t _p_r_o_b_a_b_i_l_i_t_y} 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.

          '_k_n_o_t._m_i_n_d_i_s_t' {_m_i_n. _k_n_o_t _d_i_s_t_a_n_c_e} see 'knot.probab'

          '_s_h_o_o_t_s._3' {_3 _s_h_o_o_t_s _p_r_o_b_a_b.} positive number, see 'shoots.4'

          '_s_h_o_o_t_s._4' {_4 _s_h_o_o_t_s _p_r_o_b_a_b.} positive number.

               '_s_h_o_o_t_s._4'>=_1 knots have always 4 shoots.

               '_s_h_o_o_t_s._4'<_1 _a_n_d '_s_h_o_o_t_s._4'+'_s_h_o_o_t_s._3'>=_1 knots have
                    with probability 'shoots.4' 4 shots and 3 shoots
                    otherwise.

               '_s_h_o_o_t_s._4'<_1 _a_n_d '_s_h_o_o_t_s._4'+'_s_h_o_o_t_s._3'<_1 knots have 4,
                    3, 2 shoots with probability 'shoots.4', 'shoots.3'
                    and 1-'shoots.4'-'shoots.3', respectively


          '_s_t_o_p._p_r_o_b_a_b' '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.

          '_s_t_o_p._m' {_s_t_o_p _p_r_o_b_a_b_i_l_i_t_y, _m} see 'stop.probab'

          '_s_t_o_p._s' {_s_t_o_p _p_r_o_b_a_b_i_l_i_t_y, _s} see 'stop.probab'

          '_r_f._l_i_n_k' '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.

          '_r_f._m' {_r_a_n_d_o_m _f_i_e_l_d _l_i_n_k, _m} see 'rf.link'

          '_r_f._s' {_r_a_n_d_o_m _f_i_e_l_d _l_i_n_k, _s} see 'rf.link'

          '_n_o._o_w_n._r_o_o_t' {_o_w_n _r_o_o_t _p_e_n_e_t_r_a_t_i_o_n} if 'TRUE' a pixel may
               contain at most one root part of the same plant.

          '_a_g_e._b_o_n_u_s' {_a_g_e _b_o_n_u_s} 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.

          '_d_e_p_t_h._b_o_n_u_s' {_d_e_p_t_h _b_o_n_u_s} summand added to the priority
               number if the subsequent pixel is below the current root
               pixel

          '_s_i_d_e._b_o_n_u_s' {_s_i_d_e _b_o_n_u_s} summand added to the priority if
               the subsequent pixel has the same depth than the current
               root pixel;  see 'depth.bonus' for deeper points.

          '_d_i_a_g_o_n_a_l' {_d_i_a_g_o_n_a_l _d_i_r_e_c_t_i_o_n_s} if 'TRUE' then roots may
               also grow into diagonal directions.


          '_d_i_r._c_h' {_n_o _d_i_r_e_c_t_i_o_n _c_h_a_n_g_e} 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'.

          '_d_i_r._c_h._s' {_n_o _d_i_r. _c_h_a_n_g_e, _r_e_l. _s_d} see 'dir.ch'

          '_r_f._K_f' {_r_o_o_t, _w_a_t_e_r _u_p_t_a_k_e}{_r_o_o_t _c_h_a_n_g_e_s _f_i_e_l_d _v_a_l_u_e} logica
               l.  If 'TRUE' the value of the (Gaussian) random field
               at a root segment is changed according to the function
               'Kf'.

          '_f_i_e_l_d._v_a_l_u_e' {_r_o_o_t, _w_a_t_e_r _u_p_t_a_k_e}{_f_i_e_l_d._v_a_l_u_e} 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'.

          '_f_i_e_l_d._f_a_c_t_o_r' {_r_o_o_t, _w_a_t_e_r _u_p_t_a_k_e}{_f_i_e_l_d._f_a_c_t_o_r} see
               'field.value'

          '_b_e_t_a._v_a_l_u_e' {_r_o_o_t, _w_a_t_e_r _u_p_t_a_k_e}{_b_e_t_a._v_a_l_u_e} 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'. 

          '_b_e_t_a._f_a_c_t_o_r' {_r_o_o_t, _w_a_t_e_r _u_p_t_a_k_e}{_b_e_t_a._f_a_c_t_o_r} see
               'beta.value'

          '_P_0' {_r_o_o_t, _w_a_t_e_r _u_p_t_a_k_e}{_P_0} (negative) pressure above which
               too less  oxygene to allow water uptake by plants

          '_P_2_H' {_r_o_o_t, _w_a_t_e_r _u_p_t_a_k_e}{_P_2_H} '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.

          '_P_2_L' {_r_o_o_t, _w_a_t_e_r _u_p_t_a_k_e}{_P_2_L} see 'P2H'

          '_P_3' {_r_o_o_t, _w_a_t_e_r _u_p_t_a_k_e}{_P_3} (negative) pressure below which
               no water uptake is possible

          '_r_2_H' {_r_o_o_t, _w_a_t_e_r _u_p_t_a_k_e}{_r_2_H} see 'P2H'

          '_r_2_L' {_r_o_o_t, _w_a_t_e_r _u_p_t_a_k_e}{_r_2_L} see 'P2H'

          '_r_o_o_t._c_o_n_d_i_t_i_o_n' {_r_o_o_t, _w_a_t_e_r _u_p_t_a_k_e}{_r_o_o_t _w_a_t_e_r _u_p_t_a_k_e} boun
               dary condition for the root.  Orginially, only
               'atmospheric' was allowed.


          '_r_o_o_t._u_p_t_a_k_e' {_r_o_o_t, _w_a_t_e_r _u_p_t_a_k_e}{_w_a_t_e_r _u_p_t_a_k_e _v_a_l_u_e} 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 'image's. 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

          '_p_s' {_p_s _b_a_s_e _n_a_m_e} character. Base name of the postscript
               file.

          '_h_e_i_g_h_t' {_p_i_c_t_u_r_e _h_e_i_g_h_t} numeric. Height of the postscript
               figure in inches.

          '_t_i_t_l_e' {_p_l_o_t _t_i_t_l_e}  logical. If 'TRUE' a title is plotted.

          '_l_e_g_e_n_d' {_l_e_g_e_n_d}  logical. If 'TRUE' a legend is added to
               the plot.

     ...: 'sophy' is alias for 'xswms2d' and takes the same arguments
          as 'xswms2d'.

_D_e_t_a_i_l_s:

     *The interactive plot* is organised as follows:

     _l_e_f_t _t_o_p 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.

     _l_e_f_t _b_o_t_t_o_m 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.)

     _c_e_n_t_r_e _t_o_p Main menue; this area is also used for defining the
          parameters of the Gaussian random fields

     _c_e_n_t_r_e _b_o_t_t_o_m 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.

     _r_i_g_h_t area used by submenues

     _r_i_g_h_t _b_o_t_t_o_m 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

     _p_o_s_t_s_c_r_i_p_t 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'.

     _p_o_l_y_g_o_n 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.

     _h_o_r_i_z_o_n 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.

     _s_t_r_u_c_t_u_r_e 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,

          _b_o_t_t_o_m _l_e_f_t a simulation of the Gaussian random field with
               the specified parameters.

          _t_o_p _l_e_f_t 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.

          _r_i_g_h_t 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.

     _s_t_o_n_e_s definition of the stones

     _r_o_o_t _g_r_o_w_t_h 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'.

     _m_a_t_e_r_i_a_l[_p_h_y_s] Definition of the physical material constants, see
          variable 'materials'.

     _m_a_t_e_r_i_a_l[_c_h_e_m] Definition of the chemical material constants, see
          variable 'materials'.

     _r_o_o_t _w_a_t_e_r _u_p_t_a_k_e Definition of the water uptake by the roots. 
          See the variable 'root'.

     _a_t_m_o_s_p_h_e_r_e, _d_a_t_a 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.

     _s_w_m_s_2_d [_w_a_t_e_r] see the variable 'water' for a description

     _s_w_m_s_2_d [_c_h_e_m] see the variable 'chemical' for a description

     _a_t_m_o_s_p_h_e_r_e _c_o_n_t_r_o_l see the variable 'atmosphere' for a description

     _n_e_w _s_i_m_u_l_a_t_i_o_n 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.

     _p_r_e_c_i_s_e _w_a_t_e_r_f_l_o_w 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.

     _w_a_t_e_r _f_l_o_w yes/no.  If 'no', only the Gaussian random field, the
          stones and the roots are simulated.

     _u_p_d_a_t_i_n_g 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.

     _e_n_d terminates the interactive surface

     *General information*

        *  Currently, the number of horizons is limited to
           'h$max.horizon'=10.

        *  The horizons are build up from the bottom, i.e. first, the
           boundary for the C horizon should be drawn then those for
           the B horizons, etc.

        *  If the mean of the last genuine(!) horizon (polygons
           excluded) is defined '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 'NA'.

        *  Polygons are used to define large lenses or to circumvent
           the predefined ordering of horizons.

        *  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.

        *  First the Gaussian random fields are 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
           'simulateHorizons' and the references therein for further
           details on the stochastic simulation.  See the SWMS2D
           manuscript for details on SWMS2D.

        *  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. 

_V_a_l_u_e:

     '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: 

          '_t_y_p_e' character. Either 'Start', 'H', or 'P'. Exactly the 
               first element has the value 'Start', all the others may
               be  horizons ('H') or polygons ('P').

          '_c_u_t._x', '_c_u_t._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.

          '_s_t_o_n_e' list of stone parameters, see the input variable
               'stone'.  The input parameters are the default
               parameters for all stone specifications

          '_m_a_t_e_r_i_a_l_s' 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)

          '_m_o_d_e_l' 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. 

          '_b_o_r_d_e_r' 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.

          '_i_d_x' 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)'x'length(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 'i'th 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)'x'length(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'.

_W_a_r_n_i_n_g:

     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.

_N_o_t_e:

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

_A_u_t_h_o_r(_s):

     Martin Schlather, schlath@hsu-hh.de <URL:
     http://www.unibw-hamburg.de/WWEB/math/schlath/schlather.html>

_R_e_f_e_r_e_n_c_e_s:

        *  Simunek., J., Vogel, T., and van Genuchten, M.Th. (1994)
           _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.

        *  Stoyan, D., Kendall, W.S., Mecke, J. (1995) _Stochastic
           Geometry and its Applications_ Chichester: Wiley, 2nd
           edition.

        *  Schlather, M., Huwe, B. (2005) SOPHY - an interactive
           programme for water flow modelling. _In preparation_

_S_e_e _A_l_s_o:

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

_E_x_a_m_p_l_e_s:

     ## 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)

         

