Debian Codegraph @

man/ode.Rd

raw
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