| 1 |
\name{ode} |
| 2 |
\alias{ode} |
| 3 |
\alias{print.deSolve} |
| 4 |
\alias{summary.deSolve} |
| 5 |
\title{General Solver for Ordinary Differential Equations} |
| 6 |
|
| 7 |
\description{Solves a system of ordinary differential equations; a wrapper |
| 8 |
around the implemented ODE solvers} |
| 9 |
|
| 10 |
\usage{ode(y, times, func, parms, |
| 11 |
method = c("lsoda", "lsode", "lsodes", "lsodar", "vode", "daspk", |
| 12 |
"euler", "rk4", "ode23", "ode45", "radau", |
| 13 |
"bdf", "bdf_d", "adams", "impAdams", "impAdams_d", "iteration"), ...) |
| 14 |
|
| 15 |
\method{print}{deSolve}(x, \dots) |
| 16 |
\method{summary}{deSolve}(object, select = NULL, which = select, |
| 17 |
subset = NULL, \dots) |
| 18 |
} |
| 19 |
\arguments{ |
| 20 |
\item{y }{the initial (state) values for the ODE system, a vector. If |
| 21 |
\code{y} has a name attribute, the names will be used to label the |
| 22 |
output matrix. |
| 23 |
} |
| 24 |
\item{times }{time sequence for which output is wanted; the first |
| 25 |
value of \code{times} must be the initial time. |
| 26 |
} |
| 27 |
\item{func }{either an \R-function that computes the values of the |
| 28 |
derivatives in the ODE system (the model definition) at time t, or a |
| 29 |
character string giving the name of a compiled function in a |
| 30 |
dynamically loaded shared library. |
| 31 |
|
| 32 |
If \code{func} is an \R-function, it must be defined as: |
| 33 |
\code{func <- function(t, y, parms,...)}. \code{t} is the current time |
| 34 |
point in the integration, \code{y} is the current estimate of the |
| 35 |
variables in the ODE system. If the initial values \code{y} has a |
| 36 |
\code{names} attribute, the names will be available inside \code{func}. |
| 37 |
\code{parms} is a vector or list of parameters; ... (optional) are |
| 38 |
any other arguments passed to the function. |
| 39 |
|
| 40 |
The return value of \code{func} should be a list, whose first |
| 41 |
element is a vector containing the derivatives of \code{y} with |
| 42 |
respect to \code{time}, and whose next elements are global values |
| 43 |
that are required at each point in \code{times}. The derivatives |
| 44 |
must be specified in the \bold{same order} as the state variables \code{y}. |
| 45 |
|
| 46 |
If \code{func} is a string, then \code{dllname} must give the name |
| 47 |
of the shared library (without extension) which must be loaded |
| 48 |
before \code{ode} is called. See package vignette |
| 49 |
\code{"compiledCode"} for more details. |
| 50 |
} |
| 51 |
\item{parms }{parameters passed to \code{func}.} |
| 52 |
\item{method }{the integrator to use, either a \bold{function} that performs |
| 53 |
integration, or a \bold{list} of class \code{\link{rkMethod}}, or a \bold{string} |
| 54 |
(\code{"lsoda"}, |
| 55 |
\code{"lsode"}, \code{"lsodes"},\code{"lsodar"},\code{"vode"}, |
| 56 |
\code{"daspk"}, \code{"euler"}, \code{"rk4"}, \code{"ode23"}, |
| 57 |
\code{"ode45"}, \code{"radau"}, \code{"bdf"}, \code{"bdf_d"}, \code{"adams"}, |
| 58 |
\code{"impAdams"} or \code{"impAdams_d"} ,"iteration"). |
| 59 |
Options "bdf", "bdf_d", "adams", "impAdams" or "impAdams_d" are the backward |
| 60 |
differentiation formula, the BDF with diagonal representation of the Jacobian, |
| 61 |
the (explicit) Adams and the implicit Adams method, and the implicit Adams |
| 62 |
method with diagonal representation of the Jacobian respectively (see details). |
| 63 |
The default integrator used is \link{lsoda}. |
| 64 |
|
| 65 |
Method \code{"iteration"} is special in that here the function \code{func} should |
| 66 |
return the new value of the state variables rather than the rate of change. |
| 67 |
This can be used for individual based models, for difference equations, |
| 68 |
or in those cases where the integration is performed within \code{func}). |
| 69 |
See last example. |
| 70 |
} |
| 71 |
\item{x }{an object of class \code{deSolve}, as returned by the |
| 72 |
integrators, and to be printed or to be subsetted. |
| 73 |
} |
| 74 |
\item{object }{an object of class \code{deSolve}, as returned by the |
| 75 |
integrators, and whose summary is to be calculated. In contrast to R's default, |
| 76 |
this returns a data.frame. It returns one summary column for a multi-dimensional variable. |
| 77 |
} |
| 78 |
\item{which }{the name(s) or the index to the variables whose summary should be |
| 79 |
estimated. Default = all variables. } |
| 80 |
|
| 81 |
\item{select }{which variable/columns to be selected. |
| 82 |
} |
| 83 |
\item{subset }{logical expression indicating elements or rows to keep when |
| 84 |
calculating a \code{summary}: missing values are taken as \code{FALSE} |
| 85 |
} |
| 86 |
\item{... }{additional arguments passed to the integrator or to the |
| 87 |
methods.} |
| 88 |
} |
| 89 |
|
| 90 |
\value{ |
| 91 |
A matrix of class \code{deSolve} with up to as many rows as elements in |
| 92 |
\code{times} and as many |
| 93 |
columns as elements in \code{y} plus the number of "global" values |
| 94 |
returned in the second element of the return from \code{func}, plus an |
| 95 |
additional column (the first) for the time value. There will be one |
| 96 |
row for each element in \code{times} unless the integrator returns |
| 97 |
with an unrecoverable error. If \code{y} has a names attribute, it |
| 98 |
will be used to label the columns of the output value. |
| 99 |
|
| 100 |
} |
| 101 |
\author{Karline Soetaert <[email protected]>} |
| 102 |
|
| 103 |
\details{ |
| 104 |
This is simply a wrapper around the various ode solvers. |
| 105 |
|
| 106 |
See package vignette for information about specifying the model in |
| 107 |
compiled code. |
| 108 |
|
| 109 |
See the selected integrator for the additional options. |
| 110 |
|
| 111 |
The default integrator used is \code{\link{lsoda}}. |
| 112 |
|
| 113 |
The option \code{method = "bdf"} provdes a handle to the backward |
| 114 |
differentiation formula (it is equal to using \code{method = "lsode"}). |
| 115 |
It is best suited to solve stiff (systems of) equations. |
| 116 |
|
| 117 |
The option \code{method = "bdf_d"} selects the backward |
| 118 |
differentiation formula that uses Jacobi-Newton iteration (neglecting the |
| 119 |
off-diagonal elements of the Jacobian (it is equal to using |
| 120 |
\code{method = "lsode", mf = 23}). |
| 121 |
It is best suited to solve stiff (systems of) equations. |
| 122 |
|
| 123 |
\code{method = "adams"} triggers the Adams method that uses functional |
| 124 |
iteration (no Jacobian used); |
| 125 |
(equal to \code{method = "lsode", mf = 10}. It is often the best |
| 126 |
choice for solving non-stiff (systems of) equations. Note: when functional |
| 127 |
iteration is used, the method is often said to be explicit, although it is |
| 128 |
in fact implicit. |
| 129 |
|
| 130 |
\code{method = "impAdams"} selects the implicit Adams method that uses Newton- |
| 131 |
Raphson iteration (equal to \code{method = "lsode", mf = 12}. |
| 132 |
|
| 133 |
\code{method = "impAdams_d"} selects the implicit Adams method that uses Jacobi- |
| 134 |
Newton iteration, i.e. neglecting all off-diagonal elements (equal to |
| 135 |
\code{method = "lsode", mf = 13}. |
| 136 |
|
| 137 |
For very stiff systems, \code{method = "daspk"} may outperform |
| 138 |
\code{method = "bdf"}. |
| 139 |
|
| 140 |
} |
| 141 |
|
| 142 |
\seealso{ |
| 143 |
\itemize{ |
| 144 |
\item \code{\link{plot.deSolve}} for plotting the outputs, |
| 145 |
\item \code{\link{dede}} general solver for delay differential equations |
| 146 |
\item \code{\link{ode.band}} for solving models with a banded |
| 147 |
Jacobian, |
| 148 |
\item \code{\link{ode.1D}} for integrating 1-D models, |
| 149 |
\item \code{\link{ode.2D}} for integrating 2-D models, |
| 150 |
\item \code{\link{ode.3D}} for integrating 3-D models, |
| 151 |
\item \code{\link{aquaphy}}, \code{\link{ccl4model}}, where |
| 152 |
\code{ode} is used, |
| 153 |
\item \code{\link{lsoda}}, \code{\link{lsode}}, |
| 154 |
\code{\link{lsodes}}, \code{\link{lsodar}}, \code{\link{vode}}, |
| 155 |
\code{\link{daspk}}, \code{\link{radau}}, |
| 156 |
\item \code{\link{rk}}, \code{\link{rkMethod}} for additional |
| 157 |
Runge-Kutta methods, |
| 158 |
\item \code{\link{forcings}} and \code{\link{events}}, |
| 159 |
\item \code{\link{diagnostics}} to print diagnostic messages. |
| 160 |
} |
| 161 |
|
| 162 |
} |
| 163 |
\keyword{math} |
| 164 |
\examples{ |
| 165 |
|
| 166 |
## ======================================================================= |
| 167 |
## Example1: Predator-Prey Lotka-Volterra model (with logistic prey) |
| 168 |
## ======================================================================= |
| 169 |
|
| 170 |
LVmod <- function(Time, State, Pars) { |
| 171 |
with(as.list(c(State, Pars)), { |
| 172 |
Ingestion <- rIng * Prey * Predator |
| 173 |
GrowthPrey <- rGrow * Prey * (1 - Prey/K) |
| 174 |
MortPredator <- rMort * Predator |
| 175 |
|
| 176 |
dPrey <- GrowthPrey - Ingestion |
| 177 |
dPredator <- Ingestion * assEff - MortPredator |
| 178 |
|
| 179 |
return(list(c(dPrey, dPredator))) |
| 180 |
}) |
| 181 |
} |
| 182 |
|
| 183 |
pars <- c(rIng = 0.2, # /day, rate of ingestion |
| 184 |
rGrow = 1.0, # /day, growth rate of prey |
| 185 |
rMort = 0.2 , # /day, mortality rate of predator |
| 186 |
assEff = 0.5, # -, assimilation efficiency |
| 187 |
K = 10) # mmol/m3, carrying capacity |
| 188 |
|
| 189 |
yini <- c(Prey = 1, Predator = 2) |
| 190 |
times <- seq(0, 200, by = 1) |
| 191 |
out <- ode(yini, times, LVmod, pars) |
| 192 |
summary(out) |
| 193 |
|
| 194 |
## Default plot method |
| 195 |
plot(out) |
| 196 |
|
| 197 |
## User specified plotting |
| 198 |
matplot(out[ , 1], out[ , 2:3], type = "l", xlab = "time", ylab = "Conc", |
| 199 |
main = "Lotka-Volterra", lwd = 2) |
| 200 |
legend("topright", c("prey", "predator"), col = 1:2, lty = 1:2) |
| 201 |
|
| 202 |
## ======================================================================= |
| 203 |
## Example2: Substrate-Producer-Consumer Lotka-Volterra model |
| 204 |
## ======================================================================= |
| 205 |
|
| 206 |
## Note: |
| 207 |
## Function sigimp passed as an argument (input) to model |
| 208 |
## (see also lsoda and rk examples) |
| 209 |
|
| 210 |
SPCmod <- function(t, x, parms, input) { |
| 211 |
with(as.list(c(parms, x)), { |
| 212 |
import <- input(t) |
| 213 |
dS <- import - b*S*P + g*C # substrate |
| 214 |
dP <- c*S*P - d*C*P # producer |
| 215 |
dC <- e*P*C - f*C # consumer |
| 216 |
res <- c(dS, dP, dC) |
| 217 |
list(res) |
| 218 |
}) |
| 219 |
} |
| 220 |
|
| 221 |
## The parameters |
| 222 |
parms <- c(b = 0.001, c = 0.1, d = 0.1, e = 0.1, f = 0.1, g = 0.0) |
| 223 |
|
| 224 |
## vector of timesteps |
| 225 |
times <- seq(0, 200, length = 101) |
| 226 |
|
| 227 |
## external signal with rectangle impulse |
| 228 |
signal <- data.frame(times = times, |
| 229 |
import = rep(0, length(times))) |
| 230 |
|
| 231 |
signal$import[signal$times >= 10 & signal$times <= 11] <- 0.2 |
| 232 |
|
| 233 |
sigimp <- approxfun(signal$times, signal$import, rule = 2) |
| 234 |
|
| 235 |
## Start values for steady state |
| 236 |
xstart <- c(S = 1, P = 1, C = 1) |
| 237 |
|
| 238 |
## Solve model |
| 239 |
out <- ode(y = xstart, times = times, |
| 240 |
func = SPCmod, parms = parms, input = sigimp) |
| 241 |
|
| 242 |
## Default plot method |
| 243 |
plot(out) |
| 244 |
|
| 245 |
## User specified plotting |
| 246 |
mf <- par(mfrow = c(1, 2)) |
| 247 |
matplot(out[,1], out[,2:4], type = "l", xlab = "time", ylab = "state") |
| 248 |
legend("topright", col = 1:3, lty = 1:3, legend = c("S", "P", "C")) |
| 249 |
plot(out[,"P"], out[,"C"], type = "l", lwd = 2, xlab = "producer", |
| 250 |
ylab = "consumer") |
| 251 |
par(mfrow = mf) |
| 252 |
|
| 253 |
## ======================================================================= |
| 254 |
## Example3: Discrete time model - using method = "iteration" |
| 255 |
## The host-parasitoid model from Soetaert and Herman, 2009, |
| 256 |
## Springer - p. 284. |
| 257 |
## ======================================================================= |
| 258 |
|
| 259 |
Parasite <- function(t, y, ks) { |
| 260 |
P <- y[1] |
| 261 |
H <- y[2] |
| 262 |
f <- A * P / (ks + H) |
| 263 |
Pnew <- H * (1 - exp(-f)) |
| 264 |
Hnew <- H * exp(rH * (1 - H) - f) |
| 265 |
|
| 266 |
list (c(Pnew, Hnew)) |
| 267 |
} |
| 268 |
rH <- 2.82 # rate of increase |
| 269 |
A <- 100 # attack rate |
| 270 |
ks <- 15 # half-saturation density |
| 271 |
|
| 272 |
out <- ode(func = Parasite, y = c(P = 0.5, H = 0.5), times = 0:50, parms = ks, |
| 273 |
method = "iteration") |
| 274 |
|
| 275 |
out2<- ode(func = Parasite, y = c(P = 0.5, H = 0.5), times = 0:50, parms = 25, |
| 276 |
method = "iteration") |
| 277 |
|
| 278 |
out3<- ode(func = Parasite, y = c(P = 0.5, H = 0.5), times = 0:50, parms = 35, |
| 279 |
method = "iteration") |
| 280 |
|
| 281 |
## Plot all 3 scenarios in one figure |
| 282 |
plot(out, out2, out3, lty = 1, lwd = 2) |
| 283 |
|
| 284 |
## Same like "out", but *output* every two steps |
| 285 |
## hini = 1 ensures that the same *internal* timestep of 1 is used |
| 286 |
outb <- ode(func = Parasite, y = c(P = 0.5, H = 0.5), |
| 287 |
times = seq(0, 50, 2), hini = 1, parms = ks, |
| 288 |
method = "iteration") |
| 289 |
plot(out, outb, type = c("l", "p")) |
| 290 |
|
| 291 |
\dontrun{ |
| 292 |
## ======================================================================= |
| 293 |
## Example4: Playing with the Jacobian options - see e.g. lsoda help page |
| 294 |
## |
| 295 |
## IMPORTANT: The following example is temporarily broken because of |
| 296 |
## incompatibility with R 3.0 on some systems. |
| 297 |
## A fix is on the way. |
| 298 |
## ======================================================================= |
| 299 |
|
| 300 |
## a stiff equation, exponential decay, run 500 times |
| 301 |
stiff <- function(t, y, p) { # y and r are a 500-valued vector |
| 302 |
list(- r * y) |
| 303 |
} |
| 304 |
|
| 305 |
N <- 500 |
| 306 |
r <- runif(N, 15, 20) |
| 307 |
yini <- runif(N, 1, 40) |
| 308 |
|
| 309 |
times <- 0:10 |
| 310 |
|
| 311 |
## Using the default |
| 312 |
print(system.time( |
| 313 |
out <- ode(y = yini, parms = NULL, times = times, func = stiff) |
| 314 |
)) |
| 315 |
# diagnostics(out) shows that the method used = bdf (2), so it it stiff |
| 316 |
|
| 317 |
## Specify that the Jacobian is banded, with nonzero values on the |
| 318 |
## diagonal, i.e. the bandwidth up and down = 0 |
| 319 |
|
| 320 |
print(system.time( |
| 321 |
out2 <- ode(y = yini, parms = NULL, times = times, func = stiff, |
| 322 |
jactype = "bandint", bandup = 0, banddown = 0) |
| 323 |
)) |
| 324 |
|
| 325 |
## Now we also specify the Jacobian function |
| 326 |
|
| 327 |
jacob <- function(t, y, p) -r |
| 328 |
|
| 329 |
print(system.time( |
| 330 |
out3 <- ode(y = yini, parms = NULL, times = times, func = stiff, |
| 331 |
jacfunc = jacob, jactype = "bandusr", |
| 332 |
bandup = 0, banddown = 0) |
| 333 |
)) |
| 334 |
## The larger the value of N, the larger the time gain... |
| 335 |
} |
| 336 |
} |
| 337 |
|