Debian Codegraph @

man/lsodar.Rd

raw
1 \name{lsodar}
2 \alias{lsodar}
3 \title{Solver for Ordinary Differential Equations (ODE),
4 Switching Automatically Between Stiff and Non-stiff Methods and With
5 Root Finding
6 }
7 \description{Solving initial value problems for stiff or non-stiff
8 systems of first-order ordinary differential equations (ODEs) and
9 including root-finding.
10
11 The \R function \code{lsodar} provides an interface to the FORTRAN ODE
12 solver of the same name, written by Alan C. Hindmarsh and Linda
13 R. Petzold.
14
15 The system of ODE's is written as an \R function or be defined in
16 compiled code that has been dynamically loaded. - see description of
17 \code{\link{lsoda}} for details.
18
19 \code{lsodar} differs from \code{lsode} in two respects.
20 \itemize{
21 \item It switches automatically between stiff and nonstiff methods
22 (similar as lsoda).
23 \item It finds the root of at least one of a set of constraint
24 functions g(i) of the independent and dependent variables.
25 }
26
27 Two uses of \code{lsodar} are:
28 \itemize{
29 \item To stop the simulation when a certain condition is met
30 \item To trigger \link{events}, i.e. sudden changes in one of the
31 state variables when a certain condition is met.
32 }
33 when a particular condition is met.
34 }
35 \usage{lsodar(y, times, func, parms, rtol = 1e-6, atol = 1e-6,
36 jacfunc = NULL, jactype = "fullint", rootfunc = NULL,
37 verbose = FALSE, nroot = 0, tcrit = NULL, hmin = 0,
38 hmax = NULL, hini = 0, ynames = TRUE, maxordn = 12,
39 maxords = 5, bandup = NULL, banddown = NULL, maxsteps = 5000,
40 dllname = NULL, initfunc = dllname, initpar = parms,
41 rpar = NULL, ipar = NULL, nout = 0, outnames = NULL, forcings=NULL,
42 initforc = NULL, fcontrol=NULL, events=NULL, lags = NULL, ...)
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 }{times at which explicit estimates for \code{y} are
50 desired. The first value in \code{times} must be the initial time.
51 }
52 \item{func }{either an \R-function that computes the values of the
53 derivatives in the ODE system (the \emph{model definition}) at time
54 t, or a character string giving the name of a compiled function in a
55 dynamically loaded shared library.
56
57 If \code{func} is an \R-function, it must be defined as:
58 \code{func <- function(t, y, parms,...)}. \code{t} is the current time
59 point in the integration, \code{y} is the current estimate of the
60 variables in the ODE system. If the initial values \code{y} has a
61 \code{names} attribute, the names will be available inside \code{func}.
62 \code{parms} is a vector or list of parameters; ... (optional) are
63 any other arguments passed to the function.
64
65 The return value of \code{func} should be a list, whose first
66 element is a vector containing the derivatives of \code{y} with
67 respect to \code{time}, and whose next elements are global values
68 that are required at each point in \code{times}. The derivatives
69 must be specified in the \bold{same order} as the state variables \code{y}.
70
71 If \code{func} is a string, then \code{dllname} must give the name
72 of the shared library (without extension) which must be loaded
73 before \code{lsodar()} is called. See package vignette
74 \code{"compiledCode"} for more
75 details.
76 }
77 \item{parms }{vector or list of parameters used in \code{func} or
78 \code{jacfunc}.
79 }
80 \item{rtol }{relative error tolerance, either a scalar or an array as
81 long as \code{y}. See details.
82 }
83 \item{atol }{absolute error tolerance, either a scalar or an array as
84 long as \code{y}. See details.
85 }
86 \item{jacfunc }{if not \code{NULL}, an \R function, that computes the
87 Jacobian of the system of differential equations
88 \eqn{\partial\dot{y}_i/\partial y_j}{dydot(i)/dy(j)}, or
89 a string giving the name of a function or subroutine in
90 \file{dllname} that computes the Jacobian (see vignette
91 \code{"compiledCode"} for more about this option).
92
93 In some circumstances, supplying
94 \code{jacfunc} can speed up the computations, if the system is
95 stiff. The \R calling sequence for \code{jacfunc} is identical to
96 that of \code{func}.
97
98 If the Jacobian is a full matrix, \code{jacfunc} should return a
99 matrix \eqn{\partial\dot{y}/\partial y}{dydot/dy}, where the ith row
100 contains the derivative of
101 \eqn{dy_i/dt} with respect to \eqn{y_j}, or a vector containing the
102 matrix elements by columns (the way \R and FORTRAN store matrices).
103
104 If the Jacobian is banded, \code{jacfunc} should return a matrix
105 containing only the nonzero bands of the Jacobian, rotated
106 row-wise. See first example of \link{lsode}.
107 }
108 \item{jactype }{the structure of the Jacobian, one of
109 \code{"fullint"}, \code{"fullusr"}, \code{"bandusr"} or
110 \code{"bandint"} - either full or banded and estimated internally or
111 by user.
112 }
113 \item{rootfunc }{if not \code{NULL}, an \R function that computes the
114 function whose root has to be estimated or a string giving the name
115 of a function or subroutine in \file{dllname} that computes the root
116 function. The \R calling sequence for \code{rootfunc} is identical
117 to that of \code{func}. \code{rootfunc} should return a vector with
118 the function values whose root is sought.
119 }
120 \item{verbose }{a logical value that, when \code{TRUE}, will
121 print the \code{diagnostiscs} of the integration - see details.
122 }
123 \item{nroot }{only used if \file{dllname} is specified: the number of
124 constraint functions whose roots are desired during the integration;
125 if \code{rootfunc} is an R-function, the solver estimates the number
126 of roots.
127 }
128 \item{tcrit }{if not \code{NULL}, then \code{lsodar} cannot integrate
129 past \code{tcrit}. The FORTRAN routine \code{lsodar} overshoots its
130 targets (times points in the vector \code{times}), and interpolates
131 values for the desired time points. If there is a time beyond which
132 integration should not proceed (perhaps because of a singularity),
133 that should be provided in \code{tcrit}.
134 }
135 \item{hmin }{an optional minimum value of the integration stepsize. In
136 special situations this parameter may speed up computations with the
137 cost of precision. Don't use \code{hmin} if you don't know why!
138 }
139 \item{hmax }{an optional maximum value of the integration stepsize. If
140 not specified, \code{hmax} is set to the largest difference in
141 \code{times}, to avoid that the simulation possibly ignores
142 short-term events. If 0, no maximal size is specified.
143 }
144 \item{hini }{initial step size to be attempted; if 0, the initial step
145 size is determined by the solver.
146 }
147 \item{ynames }{logical, if \code{FALSE}: names of state variables are not
148 passed to function \code{func}; this may speed up the simulation
149 especially for large models.
150 }
151 \item{maxordn }{the maximum order to be allowed in case the method is
152 non-stiff. Should be <= 12. Reduce \code{maxord} to save storage space.
153 }
154 \item{maxords }{the maximum order to be allowed in case the method is
155 stiff. Should be <= 5. Reduce maxord to save storage space.
156 }
157 \item{bandup }{number of non-zero bands above the diagonal, in case
158 the Jacobian is banded.
159 }
160 \item{banddown }{number of non-zero bands below the diagonal, in case
161 the Jacobian is banded.
162 }
163 \item{maxsteps }{maximal number of steps per output interval taken by the
164 solver.
165 }
166 \item{dllname }{a string giving the name of the shared library
167 (without extension) that contains all the compiled function or
168 subroutine definitions refered to in \code{func} and
169 \code{jacfunc}. See package vignette \code{"compiledCode"}.
170 }
171 \item{initfunc }{if not \code{NULL}, the name of the initialisation function
172 (which initialises values of parameters), as provided in
173 \file{dllname}. See package vignette \code{"compiledCode"}.
174 }
175 \item{initpar }{only when \file{dllname} is specified and an
176 initialisation function \code{initfunc} is in the dll: the
177 parameters passed to the initialiser, to initialise the common
178 blocks (FORTRAN) or global variables (C, C++).
179 }
180 \item{rpar }{only when \file{dllname} is specified: a vector with
181 double precision values passed to the dll-functions whose names are
182 specified by \code{func} and \code{jacfunc}.
183 }
184 \item{ipar }{only when \file{dllname} is specified: a vector with
185 integer values passed to the dll-functions whose names are specified
186 by \code{func} and \code{jacfunc}.
187 }
188 \item{nout }{only used if \code{dllname} is specified and the model is
189 defined in compiled code: the number of output variables calculated
190 in the compiled function \code{func}, present in the shared
191 library. Note: it is not automatically checked whether this is
192 indeed the number of output variables calculated in the dll - you have
193 to perform this check in the code - See package vignette
194 \code{"compiledCode"}.
195 }
196 \item{outnames }{only used if \file{dllname} is specified and
197 \code{nout} > 0: the names of output variables calculated in the
198 compiled function \code{func}, present in the shared library.
199 These names will be used to label the output matrix.
200 }
201 \item{forcings }{only used if \file{dllname} is specified: a list with
202 the forcing function data sets, each present as a two-columned matrix,
203 with (time,value); interpolation outside the interval
204 [min(\code{times}), max(\code{times})] is done by taking the value at
205 the closest data extreme.
206
207 See \link{forcings} or package vignette \code{"compiledCode"}.
208 }
209 \item{initforc }{if not \code{NULL}, the name of the forcing function
210 initialisation function, as provided in
211 \file{dllname}. It MUST be present if \code{forcings} has been given a
212 value.
213 See \link{forcings} or package vignette \code{"compiledCode"}.
214 }
215 \item{fcontrol }{A list of control parameters for the forcing functions.
216 See \link{forcings} or vignette \code{compiledCode}.
217 }
218 \item{events }{A matrix or data frame that specifies events, i.e. when the value of a
219 state variable is suddenly changed. See \link{events} for more information.
220 }
221 \item{lags }{A list that specifies timelags, i.e. the number of steps
222 that has to be kept. To be used for delay differential equations.
223 See \link{timelags}, \link{dede} for more information.
224 }
225 \item{... }{additional arguments passed to \code{func} and
226 \code{jacfunc} allowing this to be a generic function.
227 }
228 }
229 \value{
230 A matrix of class \code{deSolve} with up to as many rows as elements
231 in \code{times} and as many columns as elements in \code{y} plus the number of "global"
232 values returned in the next elements of the return from \code{func},
233 plus and additional column for the time value. There will be a row
234 for each element in \code{times} unless the FORTRAN routine `lsodar'
235 returns with an unrecoverable error. If \code{y} has a names
236 attribute, it will be used to label the columns of the output value.
237
238 If a root has been found, the output will have the attribute
239 \code{iroot}, an integer indicating which root has been found.
240
241 }
242 \author{Karline Soetaert <[email protected]>}
243 \examples{
244 ## =======================================================================
245 ## Example 1:
246 ## from lsodar source code
247 ## =======================================================================
248
249 Fun <- function (t, y, parms) {
250 ydot <- vector(len = 3)
251 ydot[1] <- -.04*y[1] + 1.e4*y[2]*y[3]
252 ydot[3] <- 3.e7*y[2]*y[2]
253 ydot[2] <- -ydot[1] - ydot[3]
254 return(list(ydot, ytot = sum(y)))
255 }
256
257 rootFun <- function (t, y, parms) {
258 yroot <- vector(len = 2)
259 yroot[1] <- y[1] - 1.e-4
260 yroot[2] <- y[3] - 1.e-2
261 return(yroot)
262 }
263
264 y <- c(1, 0, 0)
265 times <- c(0, 0.4*10^(0:8))
266
267 out <- lsodar(y = y, times = times, fun = Fun, rootfun = rootFun,
268 rtol = 1e-4, atol = c(1e-6, 1e-10, 1e-6), parms = NULL)
269 print(paste("root is found for eqn", which(attributes(out)$iroot == 1)))
270 print(out[nrow(out),])
271
272 diagnostics(out)
273
274 ## =======================================================================
275 ## Example 2:
276 ## using lsodar to estimate steady-state conditions
277 ## =======================================================================
278
279 ## Bacteria (Bac) are growing on a substrate (Sub)
280 model <- function(t, state, pars) {
281 with (as.list(c(state, pars)), {
282 ## substrate uptake death respiration
283 dBact <- gmax*eff*Sub/(Sub+ks)*Bact - dB*Bact - rB*Bact
284 dSub <- -gmax *Sub/(Sub+ks)*Bact + dB*Bact + input
285
286 return(list(c(dBact,dSub)))
287 })
288 }
289
290 ## root is the condition where sum of |rates of change|
291 ## is very small
292
293 rootfun <- function (t, state, pars) {
294 dstate <- unlist(model(t, state, pars)) # rate of change vector
295 return(sum(abs(dstate)) - 1e-10)
296 }
297
298 pars <- list(Bini = 0.1, Sini = 100, gmax = 0.5, eff = 0.5,
299 ks = 0.5, rB = 0.01, dB = 0.01, input = 0.1)
300
301 tout <- c(0, 1e10)
302 state <- c(Bact = pars$Bini, Sub = pars$Sini)
303 out <- lsodar(state, tout, model, pars, rootfun = rootfun)
304 print(out)
305
306
307 ## =======================================================================
308 ## Example 3:
309 ## using lsodar to trigger an event
310 ## =======================================================================
311
312 ## a state variable is decaying at a first-order rate.
313 ## when it reaches the value 0.1, a random amount is added.
314
315 derivfun <- function (t,y,parms)
316 list (-0.05 * y)
317
318 rootfun <- function (t,y,parms)
319 return(y - 0.1)
320
321 eventfun <- function(t,y,parms)
322 return(y + runif(1))
323
324 yini <- 0.8
325 times <- 0:200
326
327 out <- lsodar(func=derivfun, y = yini, times=times,
328 rootfunc = rootfun, events = list(func=eventfun, root = TRUE))
329
330 plot(out, type = "l", lwd = 2, main = "lsodar with event")
331
332 }
333 \references{
334
335 Alan C. Hindmarsh, ODEPACK, A Systematized Collection of ODE Solvers,
336 in Scientific Computing, R. S. Stepleman et al. (Eds.), North-Holland,
337 Amsterdam, 1983, pp. 55-64.
338
339 Linda R. Petzold, Automatic Selection of Methods for Solving Stiff and
340 Nonstiff Systems of Ordinary Differential Equations, Siam
341 J. Sci. Stat. Comput. 4 (1983), pp. 136-148.
342 \doi{10.1137/0904010}
343
344 Kathie L. Hiebert and Lawrence F. Shampine, Implicitly Defined Output
345 Points for Solutions of ODEs, Sandia Report SAND80-0180, February 1980.
346
347 Netlib: \url{https://netlib.org}
348
349 }
350 \details{
351 The work is done by the FORTRAN subroutine \code{lsodar}, whose
352 documentation should be consulted for details (it is included as
353 comments in the source file \file{src/opkdmain.f}). The
354 implementation is based on the November, 2003 version of lsodar, from
355 Netlib.
356
357 \code{lsodar} switches automatically between stiff and nonstiff
358 methods (similar as \code{lsoda}). This means that the user does not
359 have to determine whether the problem is stiff or not, and the solver
360 will automatically choose the appropriate method. It always starts
361 with the nonstiff method.
362
363 \code{lsodar} can find the root of at least one of a set of constraint functions
364 \code{rootfunc} of the independent and dependent variables. It then returns the
365 solution at the root if that occurs sooner than the specified stop
366 condition, and otherwise returns the solution according the specified
367 stop condition.
368
369 Caution: Because of numerical errors in the function
370 \code{rootfun} due to roundoff and integration error, \code{lsodar} may
371 return false roots, or return the same root at two or more
372 nearly equal values of \code{time}.
373
374 The form of the \bold{Jacobian} can be specified by \code{jactype}
375 which can take the following values:
376 \describe{
377 \item{jactype = "fullint":}{a full Jacobian, calculated internally
378 by lsodar, the default,
379 }
380 \item{jactype = "fullusr":}{a full Jacobian, specified by user
381 function \code{jacfunc},
382 }
383 \item{jactype = "bandusr":}{a banded Jacobian, specified by user
384 function \code{jacfunc}; the size of the bands specified by
385 \code{bandup} and \code{banddown},
386 }
387 \item{jactype = "bandint":}{banded Jacobian, calculated by lsodar;
388 the size of the bands specified by \code{bandup} and
389 \code{banddown}.
390 }
391 }
392 If \code{jactype} = "fullusr" or "bandusr" then the user must supply a
393 subroutine \code{jacfunc}.
394
395 The input parameters \code{rtol}, and \code{atol} determine the
396 \bold{error control} performed by the solver. See \code{\link{lsoda}}
397 for details.
398
399 The output will have the attribute \bold{iroot}, if a root was found
400 \bold{iroot} is a vector, its length equal to the number of constraint
401 functions it will have a value of 1 for the constraint function whose
402 root that has been found and 0 otherwise.
403
404 The diagnostics of the integration can be printed to screen
405 by calling \code{\link{diagnostics}}. If \code{verbose} = \code{TRUE},
406 the diagnostics will written to the screen at the end of the integration.
407
408 See vignette("deSolve") for an explanation of each element in the vectors
409 containing the diagnostic properties and how to directly access them.
410
411 \bold{Models} may be defined in compiled C or FORTRAN code, as well as
412 in an R-function. See package vignette \code{"compiledCode"} for details.
413
414 More information about models defined in compiled code is in the package
415 vignette ("compiledCode"); information about linking forcing functions
416 to compiled code is in \link{forcings}.
417
418 Examples in both C and FORTRAN are in the \file{dynload} subdirectory
419 of the \code{deSolve} package directory.
420 }
421 \seealso{
422 \itemize{
423 \item \code{\link{roots}} for more examples on roots and events
424 \item \code{\link{rk}}, \code{\link{rkMethod}}, \code{\link{rk4}} and \code{\link{euler}} for
425 Runge-Kutta integrators.
426 \item \code{\link{lsoda}}, \code{\link{lsode}},
427 \code{\link{lsodes}}, \code{\link{vode}},
428 \code{\link{daspk}} for other solvers of the Livermore family,
429 \item \code{\link{ode}} for a general interface to most of the ODE solvers,
430 \item \code{\link{ode.band}} for solving models with a banded
431 Jacobian,
432 \item \code{\link{ode.1D}} for integrating 1-D models,
433 \item \code{\link{ode.2D}} for integrating 2-D models,
434 \item \code{\link{ode.3D}} for integrating 3-D models,
435 }
436
437 \code{\link{diagnostics}} to print diagnostic messages.
438 }
439 \keyword{math}
440