simecol (version 0.8-2)

iteration: Discrete Simulation

Description

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

Usage

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

Arguments

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:

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.

Value

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

Details

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.

See Also

sim, observer, parms, lsoda, rk4, euler.

Examples

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