swms2d                 package:SoPhy                 R Documentation

_S_W_M_S_2_D _f_u_n_c_t_i_o_n _c_a_l_l

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

     Modelling of water flow and solute transport by SWMS2D

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

     swms2d(d, max.iteration = 1e+05, iter.print = max.iteration, ShortF = TRUE, 
            message = NULL, breakpoint = 1e+10, intermediate.result = NULL)

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

       d: list; see details

max.iteration: maximum number of incremental time steps

iter.print: number of incremental time steps after which a short
          message of status is given

  ShortF: logical. If 'TRUE' information is provided only at selected
          time points given by 'd$TPrint'

 message: 'NULL' or a function that takes a scalar time argument and
          returns a logical value. The function is called in case
          'max.iteration' is exceeded. The function may allow the user
          to decide on the basis of the current time whether the
          simulation should be continued.

breakpoint: number of incremental time steps after which
          'intermediate.result' is called

intermediate.result: 'NULL' or a function with two parameters: the
          first one gives the time, the second is a (6 x 'NumNP' x
          1)-array where the first dimension gives the (1) current
          pressure h, (2) discharge rate Q, (3) water content theta,
          (4) x-component vx of Darcian flux, (5) z-component vz of
          Darcian flux,  and (6) the solute concentration; 'NumNP'
          gives the number of nodes; 'intermediate.result' can be used
          to create movies of water flow at calculation time.

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

     'd' is a profile definition of a type as the return list of
     'link{xswms2d}', or it is  a list that should contain the
     following elements

   '_K_a_t' type of flow system; 0:horizontal, 1:axisymmetric; 2:vertical.

   '_M_a_x_I_t' maximum number of iteration during any time step.

   '_T_o_l_T_h' maximum desired change of water content within one step.

   '_T_o_l_H' maximum desired change of pressure head within one step.

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

   '_F_r_e_e_D' logical. 'TRUE' if free drainage at the bottom.

   '_N_L_a_y' Number of subregions for water balances.

   '_h_T_a_b' 'c(hTab1, hTabN)', interval of pressure heads within which a
        table of hydraulic properties is generated.

   '_P_a_r' vector of 9 elements or matrix of 9 columns, each row
        representing a different kind of material.

   '_d_t' initial time increment.

   '_d_t_M_i_n_M_a_x' 'c(dtmin, dtmax)', minimum and maximum permitted time
        increment.

   '_D_M_u_l' 'c(dMul, dMul2)', 'dMul >= 1', 'dMul2 <= 1'; if number of
        required iterations is less than 4 or greater than 6 then the
        next time step is multiplied by 'dMul' and 'dMul2',
        respectively.


   '_T_P_r_i_n_t' vector of increasing print-times.

   '_N_P' seepage information: matrix or list. matrix of one or two rows
        and arbitrary columns or each row defines a seepage face, the
        columns give the node numbers (or are 'NA') or a list of
        vectors;

   '_D_r_C_o_r_r' reduction factor for drainage; see the SWMS2D manual.

   '_N_D' vector of up to two elements given the global node number of
        the drain.

   '_E_f_D_i_m' '(length{ND} x 2)-matrix' drain information: first column
        gives the effective diameter; second column gives the dimension
        of the square in the finite element mesh.

   '_K_E_l_D_r' drainage information: matrix or list; matrix of 'length(ND)'
        rows and arbitrary colums; each row defines the surrounding
        finite elements of the drain; values are either the global
        finite element numbers or 'NA' or a list of vectors.

   '_E_p_s_i' temporal weighing coefficient: 0: explicit scheme,
        0.5:Crank-Nicholson, 1:fully implicit.

   '_l_U_p_W' logical. Upstream weighing formalation used if 'TRUE' else
        Galkerin formulation.

   '_l_A_r_t_D' logical. 'TRUE' if artificial dispersion is to be added to
        fulfill the stability criterion 'PeCr'.

   '_P_e_C_r' Stability criterion, see the SWMS2D manual; zero if 'lUpW'.

   '_C_h_P_a_r' vector of 9 element if 'Par' is a vector; other wise
        ('nrow(Par)' x 9)-matrix; chemical material properties: bulk
        density, ionic diffusion coeffcient in free water, longitudinal
        dispersivity, transverse dispersivity, Freundlich isotherm
        coefficient, first-order rate constant for dissolved phase,
        first-order rate constant for solid phase, zero-order rate
        constant for dissolved phase, zero-order rate constant for
        solid phase.

   '_K_o_d_C_B' vector of 'sum(nCodeM[,2]!=0)' elements, defining the
        chemical boundary conditions, see the SWMS2D manual.

   '_c_B_o_u_n_d' vector of six elements: jth element gives the 
        concentration for boundary nodes 'i' with chemical boundary
        condition 'abs(KodCB[i])==j'.

   '_t_P_u_l_s' time duration of the concentration pulse.

   '_n_C_o_d_e_M' matrix of 11 or 12 columns and arbitrary number of rows;
        'nCodeM' gives the nodal information; the 12 columns contain:
        (1) nodal number (might be omitted), (2) code giving the
        boundary condition (see the SWMS2D manual), (3) x-coordinate,
        (4) z-coordinate, (5) initial pressure head, (6) initial
        concentration, (7) prescribed recharge or discharge rate, (8)
        material number, (9) water uptake distribution value, (10)
        pressure head scaling factor, (11) conductivity scaling factor,
        (12) water content scaling factor.


   '_K_X_R' matrix of 8 columns and arbitrary rows; gives the finite
        element information; first 4 colums give the nodes in
        counter-clockwise order (last node is repeated if element is a
        triangle), 5th to 7th column give anisotropy parameters of the
        conductivity tensor (angle, first and second principal
        component), 8th column: subregion number.


   '_W_i_d_t_h' scalar or vector of 'sum(nCodeM[,2]!=0)' elements; width of
        the boundary associated with the boundary nodes (in the order
        given by nCodeM).

   '_r_L_e_n' width of soil surface associated with transpiration

   '_N_o_d_e' vector of observation nodes for which information is
        collected at each time level.

   '_S_i_n_k_F' logical; water extraction from the root zone if 'TRUE'. 

   '_q_G_W_L_F' logical; If 'TRUE' then the discharge-groundwater level
        relationship is used, see the SWMS2D manual.

   '_G_W_L_0_L' reference position of groundwater table (usually the
        z-coordinate of the soil surface).

   '_A_q_h' parameter in the discharge-groundwater level relationship.

   '_B_q_h' second parameter in the discharge-groundwater level
        relationship.

   '_t_I_n_i_t' starting time of the simulation.

   '_h_C_r_i_t_S' maximum allowed pressure head at soil surface.

   '_a_t_m_o_s_p_h_e_r_e' matrix of 10 columns and arbitrary rows; each row
        presents the atmospherical conditions at a certain instance;
        the columns are (1) the instance at which the time period ends
        (2) precipitation, (3) solute concentration of rainfall water,
        (4) potential evaporation rate, (5) potential transpiration
        rate, (6) absolute value of minimum allowed pressure head at
        the soil surface, (7) drainage flux across the bottom boundary
        (for 'abs(nCodeM[,2])==3'), (8) ground water level, (9)
        concentration of drainage flux (for '(abs(nCodeM[,2])==3) &
        (KodCB<0)') (10)  concentration of drainage flux (for
        '(abs(nCodeM[,2])==3) & (KodCB>0)').


   '_r_o_o_t' vector of 6 elements or ('nrow(nCodeM)' x 6)-matrix. 'c(P0,
        P2H, P2L, P3, r2H, r2L)' information about water uptake by
        roots, see the SWMS2D manual.

   '_P_O_p_t_m' pressure heads, below which roots start to extract water at
        maximum possible rate; if 'is.vector(root)' then 'POptm' is a 
        scalar if 'Par' is a vector, and a vector of 'nrow{Par}'
        elements otherwise; if '!is.vector(root)' then 'POptm' has
        'nrow(nCodeM)' elements.

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

     If an error occured a string containing the error message is
     returned. Otherwise the result is a list of the following elements 

 hQThFlC: array(dim=c(6, 'NumNP', n)) where n <= 'MPL' + 2 (simulation
          output); first dimension gives (i) water pressure H, (2)
          discharge rate Q, (3) water content theta, (4) x-component vx
          of Darcian flux, (5) z-component vz of Darcian flux,  and (6)
          concentration; the third dimension gives the time points
          given by TPrint except the first that gives the initial
          conditions. 

TlSolObs: matrix with 46 + 3 * 'NObs' columns (simulation output); the
          columns are (1) time point, (2) rAtm, (3) rRoot, (4-10)
          vK[Atm, Root, 3, 1, Seep, 5, 6], (11-17) hK[Atm, Root, 3, 1,
          Seep, 5, 6], (18) CumQAP, (19) CumQRP, (20-26) CumQ[Atm,
          Root, 3, 1, Seep, 5, 6], (27) dt, (28) Iter, (29) ItCum, (30)
          Peclet, (31) Courant, (32) CumCh0, (33) CumCh1, (34) ChumR,
          (35-40) ChemS[1:6], (41-46) SMean[1:6], hNew[1:'Nobs'] if
          'Nobs' > 0, ThNew[1:'Nobs'] if 'Nobs' > 0, ConcNew[1:'Nobs']
          if 'Nobs' > 0; see the SWMS2D manual for details. 

  atmOut: ('MaxAl' x 9)-matrix (simulation output); (1) AtmTime, (2)
          CumQAP, (3) CumQRP, (4) CumQA, (5) CumQR, (6) CumQ3, (7)
          hAtm, (8) hRoot, (9) hKode3; see the SWMS2D manual for
          details. 

 balance: matrix of 'balance.ncol' columns and at most 'boundary.n'
          rows (simulation output); first 5 columns are (1) time, (2)
          WatBalT, (3) WatBalT, (4) CncBalT, (5) CncBalR; for each of
          the subjects (i) Area, (ii) Volume, (iii) InFlow, (iv) hMean,
          and (v) ConcVol and (vi) cMean if solute transport, 'NLay +1'
          subsequent columns are given for the total value and the
          value of each subregion; see the SWMS2D manual for details. 

boundary: array(dim=c('NumBP', 11, n)) where n <= boundary.n
          (simulation output); the second dimension gives (1) i, (2) n,
          (3) x, (4) z, (5) Code, (6) Q, (7) v, (8) h, (9) th, (10)
          Conc, (11) time; see the SWMS2D manual for details. 

    flux: 'd$flux';  different from 'NULL' if the function is called
          with the output of 'create.waterflow' or with a profile
          definition, see the return value of 'xswms2d'.

 water.x: 'd$water.x';  different from 'NULL' if the function is called
          with the output of 'create.waterflow' or with a profile
          definition, see the return value of 'xswms2d'.

 water.y: 'd$water.y';  different from 'NULL' if the function is called
          with the output of 'create.waterflow' or with a profile
          definition, see the return value of 'xswms2d'.

_A_c_k_n_o_w_l_e_d_g_e_m_e_n_t:

     The author is grateful to Rien van Genuchten, Carl A. Mendoza,
     Rene Therrien, and Edward Sudicky for kindly changing the
     copyright of the modified SWMS2D code, as used in this package, to
     the GNU copyleft licence.

     Note that, however, HYDRUS2D, an advanced development of SWMS2D,
     and its code is proprietary.

     The work has been financially supported by the German Federal
     Ministry of Research and Technology (BMFT) grant PT BEO
     51-0339476C during 2000-2002.

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

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

     The Fortran code was published as 'swms_2d' by Jirka Simunek, T.
     Vogel and Martinus Th. van Genuchten,  <URL:
     http://www.ussl.ars.usda.gov/MODELS/MODELS.HTM>; the file
     ORTHOFEM.f was written by Edward A. Sudicky   and Carl A. Mendoza,
     based on code by Frank W. Letniowshi and contributions by Rene
     Therrien, and modified by Jirka Simunek.

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

        *  Schlather, M. and Huwe, B. (2004) The use of the language
           interface of R: two examples for modelling water flux and
           solute transport. _Computers & Geosciences_ *30*, 197-201.

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

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

     'xswms2d', 'read.swms2d.table', 'SoPhy'

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

     ##################################################################
     ##  SWMS2D, Example 1, stochastically modified material properties
     ##################################################################
     # E = exp(mu + 1/2 * sd^2)
     # Var = exp(2*mu + sd^2)*(exp(sd^2) - 1)

     path <- paste(system.file(package='SoPhy'), 'swms2d', sep="/")
     x <- read.swms2d.table(path)
     x$TPrint <- 20 * 60
     sd <- 0.3 ## then sd of log.gauss is 0.306878
     mu <- log(x$nCodeM[, 10]) - 0.5 * sd^2
     n <- if (interactive()) 100 else 10 # better 10000
     front <- integer(n)

     for (j in 1:n) {
       cat(j,"\n")
       x$nCodeM[, 10] <- rlnorm(length(x$nCodeM$z), m = mu, sd = sd)
       x$nCodeM[, 11] <- x$nCodeM[, 10]^(-2)
       z <- swms2d(x)$hQ[3, , ]
       front[j] <- (min(which(z[-1:-2, 2] / z[-1:-2, 1] < 1.005)) %/% 2) + 1
     }

     idx <- 24 
     cat('The probability that the front advances at most', 
         max(x$nCodeM$z) - x$nCodeM$z[2 * idx],'cm is about',
         format(mean(front <= idx), dig=2),'\n')

     par(cex=1, mar=c(4.2,4.2,1.2,0.4))
     distance <- max(x$nCodeM$z) - x$nCodeM$z[2 * front]
     h <- sort(unique(distance))
     dh <- min(diff(h) / 2)
     hist(distance, freq=FALSE,
          breaks=seq(h[1]-dh, h[length(h)]+dh, 2 * dh),
          main="Histogramm for the depth of the water front",
          xlab="depth", cex.axis=1.5, cex.main=1.2, cex.lab=1.5)

