Debian Codegraph @

man/lsode.Rd

raw
1 \name{lsode}
2 \alias{lsode}
3
4 \title{Solver for Ordinary Differential Equations (ODE)}
5
6 \description{
7 Solves the initial value problem for stiff or nonstiff systems of
8 ordinary differential equations (ODE) in the form: \deqn{dy/dt =
9 f(t,y)}.
10
11 The \R function \code{lsode} provides an interface to the FORTRAN ODE
12 solver of the same name, written by Alan C. Hindmarsh and Andrew
13 H. Sherman.
14
15 It combines parts of the code \code{lsodar} and can thus find the root
16 of at least one of a set of constraint functions g(i) of the independent
17 and dependent variables. This can be used to stop the simulation or to
18 trigger \link{events}, i.e. a sudden change in one of the state variables.
19
20 The system of ODE's is written as an \R function or be defined in
21 compiled code that has been dynamically loaded.
22
23 In contrast to \code{\link{lsoda}}, the user has to specify whether or
24 not the problem is stiff and choose the appropriate solution method.
25
26 \code{lsode} is very similar to \code{\link{vode}}, but uses a
27 fixed-step-interpolate method rather than the variable-coefficient
28 method in \code{\link{vode}}. In addition, in \code{vode} it is
29 possible to choose whether or not a copy of the Jacobian is saved for
30 reuse in the corrector iteration algorithm; In \code{lsode}, a copy is
31 not kept.
32 }
33 \usage{
34 lsode(y, times, func, parms, rtol = 1e-6, atol = 1e-6,
35 jacfunc = NULL, jactype = "fullint", mf = NULL, rootfunc = NULL,
36 verbose = FALSE, nroot = 0, tcrit = NULL, hmin = 0, hmax = NULL,
37 hini = 0, ynames = TRUE, maxord = NULL, bandup = NULL, banddown = NULL,
38 maxsteps = 5000, dllname = NULL, initfunc = dllname,
39 initpar = parms, rpar = NULL, ipar = NULL, nout = 0,
40 outnames = NULL, forcings=NULL, initforc = NULL,
41 fcontrol=NULL, events=NULL, lags = NULL,...)
42 }
43
44 \arguments{
45 \item{y }{the initial (state) values for the ODE system. If \code{y}
46 has a name attribute, the names will be used to label the output
47 matrix.
48 }
49 \item{times }{time sequence for which output is wanted; the first
50 value of \code{times} must be the initial time; if only one step is
51 to be taken; set \code{times} = \code{NULL}.
52 }
53 \item{func }{either an \R-function that computes the values of the
54 derivatives in the ODE system (the \emph{model definition}) at time
55 t, or a character string giving the name of a compiled function in a
56 dynamically loaded shared library.
57
58 If \code{func} is an \R-function, it must be defined as:
59 \code{func <- function(t, y, parms,...)}. \code{t} is the current time
60 point in the integration, \code{y} is the current estimate of the
61 variables in the ODE system. If the initial values \code{y} has a
62 \code{names} attribute, the names will be available inside \code{func}.
63 \code{parms} is a vector or list of parameters; ... (optional) are
64 any other arguments passed to the function.
65
66 The return value of \code{func} should be a list, whose first
67 element is a vector containing the derivatives of \code{y} with
68 respect to \code{time}, and whose next elements are global values
69 that are required at each point in \code{times}. The derivatives
70 must be specified in the \bold{same order} as the state variables \code{y}.
71
72 If \code{func} is
73 a string, then \code{dllname} must give the name of the shared
74 library (without extension) which must be loaded before
75 \code{lsode()} is called. See package vignette \code{"compiledCode"}
76 for more details.
77 }
78 \item{parms }{vector or list of parameters used in \code{func} or
79 \code{jacfunc}.
80 }
81 \item{rtol }{relative error tolerance, either a
82 scalar or an array as long as \code{y}. See details.
83 }
84 \item{atol }{absolute error tolerance, either a scalar or an array as
85 long as \code{y}. See details.
86 }
87 \item{jacfunc }{if not \code{NULL}, an \R function that computes the
88 Jacobian of the system of differential equations
89 \eqn{\partial\dot{y}_i/\partial y_j}{dydot(i)/dy(j)}, or
90 a string giving the name of a function or subroutine in
91 \file{dllname} that computes the Jacobian (see vignette
92 \code{"compiledCode"} for more about this option).
93
94 In some circumstances, supplying
95 \code{jacfunc} can speed up the computations, if the system is
96 stiff. The \R calling sequence for \code{jacfunc} is identical to
97 that of \code{func}.
98
99 If the Jacobian is a full matrix,
100 \code{jacfunc} should return a matrix \eqn{\partial\dot{y}/\partial y}{dydot/dy}, where the ith row
101 contains the derivative of \eqn{dy_i/dt} with respect to \eqn{y_j},
102 or a vector containing the matrix elements by columns (the way \R
103 and FORTRAN store matrices). \cr If the Jacobian is banded,
104 \code{jacfunc} should return a matrix containing only the nonzero
105 bands of the Jacobian, rotated row-wise. See first example of \link{lsode}.
106 }
107 \item{jactype }{the structure of the Jacobian, one of
108 \code{"fullint"}, \code{"fullusr"}, \code{"bandusr"} or
109 \code{"bandint"} - either full or banded and estimated internally or
110 by user; overruled if \code{mf}is not \code{NULL}.
111 }
112 \item{mf }{the "method flag" passed to function lsode - overrules
113 \code{jactype} - provides more options than \code{jactype} - see
114 details.
115 }
116 \item{rootfunc }{if not \code{NULL}, an \R function that computes the
117 function whose root has to be estimated or a string giving the name
118 of a function or subroutine in \file{dllname} that computes the root
119 function. The \R calling sequence for \code{rootfunc} is identical
120 to that of \code{func}. \code{rootfunc} should return a vector with
121 the function values whose root is sought.
122 }
123 \item{verbose }{if TRUE: full output to the screen, e.g. will
124 print the \code{diagnostiscs} of the integration - see details.
125 }
126 \item{nroot }{only used if \file{dllname} is specified: the number of
127 constraint functions whose roots are desired during the integration;
128 if \code{rootfunc} is an R-function, the solver estimates the number
129 of roots.
130 }
131 \item{tcrit }{if not \code{NULL}, then \code{lsode} cannot integrate
132 past \code{tcrit}. The FORTRAN routine \code{lsode} overshoots its
133 targets (times points in the vector \code{times}), and interpolates
134 values for the desired time points. If there is a time beyond which
135 integration should not proceed (perhaps because of a singularity),
136 that should be provided in \code{tcrit}.
137 }
138 \item{hmin }{an optional minimum value of the integration stepsize. In
139 special situations this parameter may speed up computations with the
140 cost of precision. Don't use \code{hmin} if you don't know why!
141 }
142 \item{hmax }{an optional maximum value of the integration stepsize. If
143 not specified, \code{hmax} is set to the largest difference in
144 \code{times}, to avoid that the simulation possibly ignores
145 short-term events. If 0, no maximal size is specified.
146 }
147 \item{hini }{initial step size to be attempted; if 0, the initial step
148 size is determined by the solver.
149 }
150 \item{ynames }{logical, if \code{FALSE} names of state variables are not
151 passed to function \code{func}; this may speed up the simulation especially
152 for multi-D models.
153 }
154 \item{maxord }{the maximum order to be allowed. \code{NULL} uses the default,
155 i.e. order 12 if implicit Adams method (meth = 1), order 5 if BDF
156 method (meth = 2). Reduce maxord to save storage space.
157 }
158 \item{bandup }{number of non-zero bands above the diagonal, in case
159 the Jacobian is banded.
160 }
161 \item{banddown }{number of non-zero bands below the diagonal, in case
162 the Jacobian is banded.
163 }
164 \item{maxsteps }{maximal number of steps per output interval taken by the
165 solver.
166 }
167 \item{dllname }{a string giving the name of the shared library
168 (without extension) that contains all the compiled function or
169 subroutine definitions refered to in \code{func} and
170 \code{jacfunc}. See package vignette \code{"compiledCode"}.
171 }
172 \item{initfunc }{if not \code{NULL}, the name of the initialisation function
173 (which initialises values of parameters), as provided in
174 \file{dllname}. See package vignette \code{"compiledCode"}.
175 }
176 \item{initpar }{only when \file{dllname} is specified and an
177 initialisation function \code{initfunc} is in the dll: the
178 parameters passed to the initialiser, to initialise the common
179 blocks (FORTRAN) or global variables (C, C++).
180 }
181 \item{rpar }{only when \file{dllname} is specified: a vector with
182 double precision values passed to the dll-functions whose names are
183 specified by \code{func} and \code{jacfunc}.
184 }
185 \item{ipar }{only when \file{dllname} is specified: a vector with
186 integer values passed to the dll-functions whose names are specified
187 by \code{func} and \code{jacfunc}.
188 }
189 \item{nout }{only used if \code{dllname} is specified and the model is
190 defined in compiled code: the number of output variables calculated
191 in the compiled function \code{func}, present in the shared
192 library. Note: it is not automatically checked whether this is
193 indeed the number of output variables calculated in the dll - you have
194 to perform this check in the code - See package vignette
195 \code{"compiledCode"}.
196 }
197 \item{outnames }{only used if \file{dllname} is specified and
198 \code{nout} > 0: the names of output variables calculated in the
199 compiled function \code{func}, present in the shared library.
200 These names will be used to label the output matrix.
201 }
202 \item{forcings }{only used if \file{dllname} is specified: a list with
203 the forcing function data sets, each present as a two-columned matrix,
204 with (time,value); interpolation outside the interval
205 [min(\code{times}), max(\code{times})] is done by taking the value at
206 the closest data extreme.
207
208 See \link{forcings} or package vignette \code{"compiledCode"}.
209 }
210 \item{initforc }{if not \code{NULL}, the name of the forcing function
211 initialisation function, as provided in
212 \file{dllname}. It MUST be present if \code{forcings} has been given a
213 value.
214 See \link{forcings} or package vignette \code{"compiledCode"}.
215 }
216 \item{fcontrol }{A list of control parameters for the forcing functions.
217 See \link{forcings} or vignette \code{compiledCode}.
218 }
219 \item{events }{A matrix or data frame that specifies events, i.e. when the value of a
220 state variable is suddenly changed. See \link{events} for more information.
221 }
222 \item{lags }{A list that specifies timelags, i.e. the number of steps
223 that has to be kept. To be used for delay differential equations.
224 See \link{timelags}, \link{dede} for more information.
225 }
226 \item{... }{additional arguments passed to \code{func} and
227 \code{jacfunc} allowing this to be a generic function.
228 }
229 }
230 \value{
231 A matrix of class \code{deSolve} with up to as many rows as elements
232 in \code{times} and as many columns as elements in \code{y} plus the number of "global"
233 values returned in the next elements of the return from \code{func},
234 plus and additional column for the time value. There will be a row
235 for each element in \code{times} unless the FORTRAN routine `lsode'
236 returns with an unrecoverable error. If \code{y} has a names
237 attribute, it will be used to label the columns of the output value.
238
239 }
240 \author{Karline Soetaert <[email protected]>}
241 \examples{
242 ## =======================================================================
243 ## Example 1:
244 ## Various ways to solve the same model.
245 ## =======================================================================
246
247 ## the model, 5 state variables
248 f1 <- function (t, y, parms) {
249 ydot <- vector(len = 5)
250
251 ydot[1] <- 0.1*y[1] -0.2*y[2]
252 ydot[2] <- -0.3*y[1] +0.1*y[2] -0.2*y[3]
253 ydot[3] <- -0.3*y[2] +0.1*y[3] -0.2*y[4]
254 ydot[4] <- -0.3*y[3] +0.1*y[4] -0.2*y[5]
255 ydot[5] <- -0.3*y[4] +0.1*y[5]
256
257 return(list(ydot))
258 }
259
260 ## the Jacobian, written as a full matrix
261 fulljac <- function (t, y, parms) {
262 jac <- matrix(nrow = 5, ncol = 5, byrow = TRUE,
263 data = c(0.1, -0.2, 0 , 0 , 0 ,
264 -0.3, 0.1, -0.2, 0 , 0 ,
265 0 , -0.3, 0.1, -0.2, 0 ,
266 0 , 0 , -0.3, 0.1, -0.2,
267 0 , 0 , 0 , -0.3, 0.1))
268 return(jac)
269 }
270
271 ## the Jacobian, written in banded form
272 bandjac <- function (t, y, parms) {
273 jac <- matrix(nrow = 3, ncol = 5, byrow = TRUE,
274 data = c( 0 , -0.2, -0.2, -0.2, -0.2,
275 0.1, 0.1, 0.1, 0.1, 0.1,
276 -0.3, -0.3, -0.3, -0.3, 0))
277 return(jac)
278 }
279
280 ## initial conditions and output times
281 yini <- 1:5
282 times <- 1:20
283
284 ## default: stiff method, internally generated, full Jacobian
285 out <- lsode(yini, times, f1, parms = 0, jactype = "fullint")
286
287 ## stiff method, user-generated full Jacobian
288 out2 <- lsode(yini, times, f1, parms = 0, jactype = "fullusr",
289 jacfunc = fulljac)
290
291 ## stiff method, internally-generated banded Jacobian
292 ## one nonzero band above (up) and below(down) the diagonal
293 out3 <- lsode(yini, times, f1, parms = 0, jactype = "bandint",
294 bandup = 1, banddown = 1)
295
296 ## stiff method, user-generated banded Jacobian
297 out4 <- lsode(yini, times, f1, parms = 0, jactype = "bandusr",
298 jacfunc = bandjac, bandup = 1, banddown = 1)
299
300 ## non-stiff method
301 out5 <- lsode(yini, times, f1, parms = 0, mf = 10)
302
303 ## =======================================================================
304 ## Example 2:
305 ## diffusion on a 2-D grid
306 ## partially specified Jacobian
307 ## =======================================================================
308
309 diffusion2D <- function(t, Y, par) {
310 y <- matrix(nrow = n, ncol = n, data = Y)
311 dY <- r*y # production
312
313 ## diffusion in X-direction; boundaries = 0-concentration
314 Flux <- -Dx * rbind(y[1,],(y[2:n,]-y[1:(n-1),]),-y[n,])/dx
315 dY <- dY - (Flux[2:(n+1),]-Flux[1:n,])/dx
316
317 ## diffusion in Y-direction
318 Flux <- -Dy * cbind(y[,1],(y[,2:n]-y[,1:(n-1)]),-y[,n])/dy
319 dY <- dY - (Flux[,2:(n+1)]-Flux[,1:n])/dy
320
321 return(list(as.vector(dY)))
322 }
323
324 ## parameters
325 dy <- dx <- 1 # grid size
326 Dy <- Dx <- 1 # diffusion coeff, X- and Y-direction
327 r <- 0.025 # production rate
328 times <- c(0, 1)
329
330 n <- 50
331 y <- matrix(nrow = n, ncol = n, 0)
332
333 pa <- par(ask = FALSE)
334
335 ## initial condition
336 for (i in 1:n) {
337 for (j in 1:n) {
338 dst <- (i - n/2)^2 + (j - n/2)^2
339 y[i, j] <- max(0, 1 - 1/(n*n) * (dst - n)^2)
340 }
341 }
342 filled.contour(y, color.palette = terrain.colors)
343
344 ## =======================================================================
345 ## jacfunc need not be estimated exactly
346 ## a crude approximation, with a smaller bandwidth will do.
347 ## Here the half-bandwidth 1 is used, whereas the true
348 ## half-bandwidths are equal to n.
349 ## This corresponds to ignoring the y-direction coupling in the ODEs.
350 ## =======================================================================
351
352 print(system.time(
353 for (i in 1:20) {
354 out <- lsode(func = diffusion2D, y = as.vector(y), times = times,
355 parms = NULL, jactype = "bandint", bandup = 1, banddown = 1)
356
357 filled.contour(matrix(nrow = n, ncol = n, out[2,-1]), zlim = c(0,1),
358 color.palette = terrain.colors, main = i)
359
360 y <- out[2, -1]
361 }
362 ))
363 par(ask = pa)
364 }
365 \references{
366 Alan C. Hindmarsh, "ODEPACK, A Systematized Collection of ODE
367 Solvers," in Scientific Computing, R. S. Stepleman, et al., Eds.
368 (North-Holland, Amsterdam, 1983), pp. 55-64.
369 }
370 \details{
371 The work is done by the FORTRAN subroutine \code{lsode}, whose
372 documentation should be consulted for details (it is included as
373 comments in the source file \file{src/opkdmain.f}). The implementation
374 is based on the November, 2003 version of lsode, from Netlib.
375
376 Before using the integrator \code{lsode}, the user has to decide
377 whether or not the problem is stiff.
378
379 If the problem is nonstiff, use method flag \code{mf} = 10, which
380 selects a nonstiff (Adams) method, no Jacobian used.\cr If the problem
381 is stiff, there are four standard choices which can be specified with
382 \code{jactype} or \code{mf}.
383
384 The options for \bold{jactype} are
385
386 \describe{
387 \item{jactype = "fullint"}{a full Jacobian, calculated internally by
388 lsode, corresponds to \code{mf} = 22,
389 }
390 \item{jactype = "fullusr"}{a full Jacobian, specified by user
391 function \code{jacfunc}, corresponds to \code{mf} = 21,
392 }
393 \item{jactype = "bandusr"}{a banded Jacobian, specified by user
394 function \code{jacfunc}; the size of the bands specified by
395 \code{bandup} and \code{banddown}, corresponds to \code{mf} = 24,
396 }
397 \item{jactype = "bandint"}{a banded Jacobian, calculated by lsode;
398 the size of the bands specified by \code{bandup} and
399 \code{banddown}, corresponds to \code{mf} = 25.
400 }
401 }
402
403 More options are available when specifying \bold{mf} directly. \cr The
404 legal values of \code{mf} are 10, 11, 12, 13, 14, 15, 20, 21, 22, 23,
405 24, 25.\cr \code{mf} is a positive two-digit integer, \code{mf} =
406 (10*METH + MITER), where
407
408 \describe{
409
410 \item{METH}{indicates the basic linear multistep method: METH = 1
411 means the implicit Adams method. METH = 2 means the method based
412 on backward differentiation formulas (BDF-s).
413 }
414
415 \item{MITER}{indicates the corrector iteration method: MITER = 0
416 means functional iteration (no Jacobian matrix is involved).
417 MITER = 1 means chord iteration with a user-supplied full (NEQ by
418 NEQ) Jacobian. MITER = 2 means chord iteration with an internally
419 generated (difference quotient) full Jacobian (using NEQ extra
420 calls to \code{func} per df/dy value). MITER = 3 means chord
421 iteration with an internally generated diagonal Jacobian
422 approximation (using 1 extra call to \code{func} per df/dy
423 evaluation). MITER = 4 means chord iteration with a user-supplied
424 banded Jacobian. MITER = 5 means chord iteration with an
425 internally generated banded Jacobian (using ML+MU+1 extra calls to
426 \code{func} per df/dy evaluation).}
427 }
428
429 If MITER = 1 or 4, the user must supply a subroutine \code{jacfunc}.
430
431 Inspection of the example below shows how to specify both a banded and
432 full Jacobian.
433
434 The input parameters \code{rtol}, and \code{atol} determine the
435 \bold{error control} performed by the solver. See \code{\link{lsoda}}
436 for details.
437
438 The diagnostics of the integration can be printed to screen
439 by calling \code{\link{diagnostics}}. If \code{verbose} = \code{TRUE},
440 the diagnostics will written to the screen at the end of the integration.
441
442 See vignette("deSolve") for an explanation of each element in the vectors
443 containing the diagnostic properties and how to directly access them.
444
445 \bold{Models} may be defined in compiled C or FORTRAN code, as well as
446 in an R-function. See package vignette \code{"compiledCode"} for details.
447
448 More information about models defined in compiled code is in the package
449 vignette ("compiledCode"); information about linking forcing functions
450 to compiled code is in \link{forcings}.
451
452 Examples in both C and FORTRAN are in the \file{dynload} subdirectory
453 of the \code{deSolve} package directory.
454
455 \code{lsode} can find the root of at least one of a set of constraint functions
456 \code{rootfunc} of the independent and dependent variables. It then returns the
457 solution at the root if that occurs sooner than the specified stop
458 condition, and otherwise returns the solution according the specified
459 stop condition.
460
461 Caution: Because of numerical errors in the function
462 \code{rootfun} due to roundoff and integration error, \code{lsode} may
463 return false roots, or return the same root at two or more
464 nearly equal values of \code{time}.
465
466
467 }
468 \seealso{
469 \itemize{
470 \item \code{\link{rk}}, \item \code{\link{rk4}} and \code{\link{euler}} for
471 Runge-Kutta integrators.
472 \item \code{\link{lsoda}},
473 \code{\link{lsodes}}, \code{\link{lsodar}}, \code{\link{vode}},
474 \code{\link{daspk}} for other solvers of the Livermore family,
475 \item \code{\link{ode}} for a general interface to most of the ODE solvers,
476 \item \code{\link{ode.band}} for solving models with a banded
477 Jacobian,
478 \item \code{\link{ode.1D}} for integrating 1-D models,
479 \item \code{\link{ode.2D}} for integrating 2-D models,
480 \item \code{\link{ode.3D}} for integrating 3-D models,
481 }
482
483 \code{\link{diagnostics}} to print diagnostic messages.
484 }
485 \keyword{math}
486