iteration              package:simecol              R Documentation

_D_i_s_c_r_e_t_e _S_i_m_u_l_a_t_i_o_n

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

     Solver function to simulate discrete ecological (or other) dynamic
     models. It is normally called indirectly from 'sim'.

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

       iteration(y, times=FALSE, func=FALSE, parms=FALSE, animate = FALSE, ...)

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

      y : the initial values for the system.  If 'y' has a name
          attribute, the names will be used to label the output matrix.

  times : times at which explicit estimates for 'y' are desired.  The
          first value in 'times' must be the initial time.

   func : a user-supplied function that computes the values of the
          _next time step_ (not the derivatives !!!)  in the system
          (the _model defininition_) at time t. The user-supplied
          function  'func' must be called as: 'yprime = func(t, y,
          parms)'.  't' is the current time point in the integration,
          'y' is the current estimate of the variables in the ode
          system, and 'parms' is a vector of parameters (which may have
          a names attribute, desirable in a large system).

          The return value of func should be a list, whose first
          element is a vector containing the derivatives of 'y' with
          respect to 'time', and whose second element is a vector
          (possibly with a 'names' attribute) of global values that are
          required at each point in 'times'.

  parms : vector or list holding the parameters used in 'func'  that
          should be modifiable without rewriting the function.

 animate: Animation during the simulation (if available for the
          specified class.

     ...: optional arguments passed to the 'plot' function if
          'animate=TRUE'.

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

     The solver method 'iteration' is used to simulate discrete event
     models.  Normally, this function is run indirectly from 'sim'.

     In contrast to differential equation solvers, the 'main' function
     of the model must not return the first derivative but instead and
     explicitly the new state at the specified times.

     The actual value of time is available in the 'main' function as
     'time' and the current increment as 'parms["DELTAT"]' or
     'parms$DELTAT'. It is element of a vector if 'parms' is a vector
     and it is a list if 'parms' is a list.

     If iteration is used for difference equations (see example
     'dlogist' below), it is mandatory to multiply the incremental part
     with 'DELTAT' to ensure that variable time steps are correctly
     respected and that the first row of the simulation outputs
     contains the states at t_0.

     The default 'iteration' method of class 'simObj' supports the
     'observer' mechanism. This means that a function stored in slot
     'observer' is called during each iteration step with the return
     value of 'main' as its first argument. You can use this to control
     the amount of data stored during each iteration step (e.g. whole
     population or only mean values for individual based models), to do
     run-time animation or to write log files.

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

     A list of the model outputs (states ...) for each timestep.

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

     'sim', 'parms', 'lsoda', 'rk4', 'euler'.

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

     data(conway)
     ## plot after simulation:
     plot(sim(conway), delay=100)

     ## plot during simulation
     sim(conway, animate=TRUE, delay=100)

     ## discrete version of logistic growth equation
     ## Note: function main returns the *new value*, not the derivative

     dlogist <- new("odeModel",
       main = function (time, init, parms, ...) {
         x <- init
         with(as.list(parms), {
           x <- x + r * x * (1 - x / K) * DELTAT
           #   ^^^ add to old value       ^^^^^^ special parameter with time step
           list(c(x))
         })
       },
       parms  = c(r=0.1, K=10),
       times  = seq(0, 100, 1),
       init   = c(population=0.1),
       solver = "iteration" #!!!
     )

     plot(sim(dlogist))

     ## alternative with function that returns the derivative
     ## discrete steps are realized with the euler method

     dlogist <- new("odeModel",
       main = function (time, init, parms, ...) {
         x <- init
         with(as.list(parms), {
           x <- r * x * (1 - x / K)
           list(c(x))
         })
       },
       parms  = c(r=0.1, K=10),
       times  = seq(0, 100, 1),
       init   = c(population=0.1),
       solver = "euler"
     )

     plot(sim(dlogist))

