Debian Codegraph @

man/vode.Rd

raw
1 \name{vode}
2 \alias{vode}
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:
9
10 \deqn{dy/dt = f(t,y)}
11
12 The \R function \code{vode} provides an interface to the FORTRAN ODE
13 solver of the same name, written by Peter N. Brown, Alan C. Hindmarsh
14 and George D. Byrne.
15
16 The system of ODE's is written as an \R function or be defined in
17 compiled code that has been dynamically loaded.
18
19 In contrast to \code{\link{lsoda}}, the user has to specify whether or
20 not the problem is stiff and choose the appropriate solution method.
21
22 \code{vode} is very similar to \code{\link{lsode}}, but uses a
23 variable-coefficient method rather than the fixed-step-interpolate
24 methods in \code{\link{lsode}}. In addition, in vode it is possible
25 to choose whether or not a copy of the Jacobian is saved for reuse in
26 the corrector iteration algorithm; In \code{lsode}, a copy is not
27 kept.
28 }
29
30 \usage{vode(y, times, func, parms, rtol = 1e-6, atol = 1e-6,
31 jacfunc = NULL, jactype = "fullint", mf = NULL, verbose = FALSE,
32 tcrit = NULL, hmin = 0, hmax = NULL, hini = 0, ynames = TRUE,
33 maxord = NULL, bandup = NULL, banddown = NULL, maxsteps = 5000,
34 dllname = NULL, initfunc = dllname, initpar = parms, rpar = NULL,
35 ipar = NULL, nout = 0, outnames = NULL, forcings=NULL,
36 initforc = NULL, fcontrol=NULL, events=NULL, lags = NULL,...)
37 }
38 \arguments{
39 \item{y }{the initial (state) values for the ODE system. If \code{y}
40 has a name attribute, the names will be used to label the output
41 matrix.
42 }
43 \item{times }{time sequence for which output is wanted; the first
44 value of \code{times} must be the initial time; if only one step is
45 to be taken; set \code{times = NULL}.
46 }
47 \item{func }{either an \R-function that computes the values of the
48 derivatives in the ODE system (the \emph{model definition}) at time
49 \code{t}, or a character string giving the name of a compiled function in a
50 dynamically loaded shared library.
51
52 If \code{func} is an \R-function, it must be defined as:
53 \code{func <- function(t, y, parms,...)}. \code{t} is the current time
54 point in the integration, \code{y} is the current estimate of the
55 variables in the ODE system. If the initial values \code{y} has a
56 \code{names} attribute, the names will be available inside \code{func}.
57 \code{parms} is a vector or list of parameters; ... (optional) are
58 any other arguments passed to the function.
59
60 The return value of \code{func} should be a list, whose first
61 element is a vector containing the derivatives of \code{y} with
62 respect to \code{time}, and whose next elements are global values
63 that are required at each point in \code{times}. The derivatives
64 must be specified in the \bold{same order} as the state variables \code{y}.
65
66 If \code{func} is
67 a string, then \code{dllname} must give the name of the shared
68 library (without extension) which must be loaded before
69 \code{vode()} is called. See package vignette \code{"compiledCode"}
70 for more details.
71 }
72 \item{parms }{vector or list of parameters used in \code{func} or
73 \code{jacfunc}.
74 }
75 \item{rtol }{relative error tolerance, either a scalar or an array as
76 long as \code{y}. See details.
77 }
78 \item{atol }{absolute error tolerance, either a scalar or an array as
79 long as \code{y}. See details.
80 }
81 \item{jacfunc }{if not \code{NULL}, an \R function that computes the
82 Jacobian of the system of differential equations
83 \eqn{\partial\dot{y}_i/\partial y_j}{dydot(i)/dy(j)}, or
84 a string giving the name of a function or subroutine in
85 \file{dllname} that computes the Jacobian (see vignette
86 \code{"compiledCode"} for more about this option).
87
88 In some circumstances, supplying
89 \code{jacfunc} can speed up the computations, if the system is
90 stiff. The \R calling sequence for \code{jacfunc} is identical to
91 that of \code{func}.
92
93 If the Jacobian is a full matrix, \code{jacfunc} should return a
94 matrix \eqn{\partial\dot{y}/\partial y}{dydot/dy}, where the ith row contains the derivative of
95 \eqn{dy_i/dt} with respect to \eqn{y_j}, or a vector containing the
96 matrix elements by columns (the way \R and FORTRAN store matrices).
97
98 If the Jacobian is banded, \code{jacfunc} should return a matrix
99 containing only the nonzero bands of the Jacobian, rotated
100 row-wise. See first example of \link{lsode}.
101 }
102 \item{jactype }{the structure of the Jacobian, one of
103 \code{"fullint"}, \code{"fullusr"}, \code{"bandusr"} or
104 \code{"bandint"} - either full or banded and estimated internally or
105 by user; overruled if \code{mf} is not \code{NULL}.
106 }
107 \item{mf }{the "method flag" passed to function vode - overrules
108 \code{jactype} - provides more options than \code{jactype} - see
109 details.
110 }
111 \item{verbose }{if TRUE: full output to the screen, e.g. will
112 print the \code{diagnostiscs} of the integration - see details.
113 }
114 \item{tcrit }{if not \code{NULL}, then \code{vode} cannot integrate
115 past \code{tcrit}. The FORTRAN routine \code{dvode} overshoots its
116 targets (times points in the vector \code{times}), and interpolates
117 values for the desired time points. If there is a time beyond which
118 integration should not proceed (perhaps because of a singularity),
119 that should be provided in \code{tcrit}.
120 }
121 \item{hmin }{an optional minimum value of the integration stepsize. In
122 special situations this parameter may speed up computations with the
123 cost of precision. Don't use hmin if you don't know why!
124 }
125 \item{hmax }{an optional maximum value of the integration stepsize. If
126 not specified, hmax is set to the largest difference in
127 \code{times}, to avoid that the simulation possibly ignores
128 short-term events. If 0, no maximal size is specified.
129 }
130 \item{hini }{initial step size to be attempted; if 0, the initial step
131 size is determined by the solver.
132 }
133 \item{ynames }{logical; if \code{FALSE}: names of state variables are not
134 passed to function \code{func} ; this may speed up the simulation
135 especially for multi-D models.
136 }
137 \item{maxord }{the maximum order to be allowed. \code{NULL} uses the default,
138 i.e. order 12 if implicit Adams method (meth = 1), order 5 if BDF
139 method (meth = 2). Reduce maxord to save storage space.
140 }
141 \item{bandup }{number of non-zero bands above the diagonal, in case
142 the Jacobian is banded.
143 }
144 \item{banddown }{number of non-zero bands below the diagonal, in case
145 the Jacobian is banded.
146 }
147 \item{maxsteps }{maximal number of steps per output interval taken by the
148 solver.
149 }
150 \item{dllname }{a string giving the name of the shared library
151 (without extension) that contains all the compiled function or
152 subroutine definitions refered to in \code{func} and \code{jacfunc}.
153 See package vignette \code{"compiledCode"}.
154 }
155 \item{initfunc }{if not \code{NULL}, the name of the initialisation function
156 (which initialises values of parameters), as provided in
157 \file{dllname}. See package vignette \code{"compiledCode"}.
158 }
159 \item{initpar }{only when \file{dllname} is specified and an
160 initialisation function \code{initfunc} is in the dll: the
161 parameters passed to the initialiser, to initialise the common
162 blocks (FORTRAN) or global variables (C, C++).
163 }
164 \item{rpar }{only when \file{dllname} is specified: a vector with
165 double precision values passed to the dll-functions whose names are
166 specified by \code{func} and \code{jacfunc}.
167 }
168 \item{ipar }{only when \file{dllname} is specified: a vector with
169 integer values passed to the dll-functions whose names are specified
170 by \code{func} and \code{jacfunc}.
171 }
172 \item{nout }{only used if \code{dllname} is specified and the model is
173 defined in compiled code: the number of output variables calculated
174 in the compiled function \code{func}, present in the shared
175 library. Note: it is not automatically checked whether this is
176 indeed the number of output variables calculated in the dll - you have
177 to perform this check in the code - See package vignette \code{"compiledCode"}.
178 }
179 \item{outnames }{only used if \file{dllname} is specified and
180 \code{nout} > 0: the names of output variables calculated in the
181 compiled function \code{func}, present in the shared library.
182 These names will be used to label the output matrix.
183 }
184 \item{forcings }{only used if \file{dllname} is specified: a list with
185 the forcing function data sets, each present as a two-columned matrix,
186 with (time,value); interpolation outside the interval
187 [min(\code{times}), max(\code{times})] is done by taking the value at
188 the closest data extreme.
189
190 See \link{forcings} or package vignette \code{"compiledCode"}.
191 }
192 \item{initforc }{if not \code{NULL}, the name of the forcing function
193 initialisation function, as provided in
194 \file{dllname}. It MUST be present if \code{forcings} has been given a
195 value.
196 See \link{forcings} or package vignette \code{"compiledCode"}.
197 }
198 \item{fcontrol }{A list of control parameters for the forcing functions.
199 \link{forcings} or package vignette \code{"compiledCode"}
200 }
201 \item{events }{A matrix or data frame that specifies events, i.e. when the value of a
202 state variable is suddenly changed. See \link{events} for more information.
203 }
204 \item{lags }{A list that specifies timelags, i.e. the number of steps
205 that has to be kept. To be used for delay differential equations.
206 See \link{timelags}, \link{dede} for more information.
207 }
208 \item{... }{additional arguments passed to \code{func} and
209 \code{jacfunc} allowing this to be a generic function.
210 }
211 }
212 \value{
213 A matrix of class \code{deSolve} with up to as many rows as elements
214 in \code{times} and as many columns as elements in \code{y} plus the number of "global"
215 values returned in the next elements of the return from \code{func},
216 plus and additional column for the time value. There will be a row
217 for each element in \code{times} unless the FORTRAN routine `vode'
218 returns with an unrecoverable error. If \code{y} has a names
219 attribute, it will be used to label the columns of the output value.
220 }
221 \author{Karline Soetaert <[email protected]>}
222 \examples{
223 ## =======================================================================
224 ## ex. 1
225 ## The famous Lorenz equations: chaos in the earth's atmosphere
226 ## Lorenz 1963. J. Atmos. Sci. 20, 130-141.
227 ## =======================================================================
228
229 chaos <- function(t, state, parameters) {
230 with(as.list(c(state)), {
231
232 dx <- -8/3 * x + y * z
233 dy <- -10 * (y - z)
234 dz <- -x * y + 28 * y - z
235
236 list(c(dx, dy, dz))
237 })
238 }
239
240 state <- c(x = 1, y = 1, z = 1)
241 times <- seq(0, 100, 0.01)
242
243 out <- vode(state, times, chaos, 0)
244
245 plot(out, type = "l") # all versus time
246 plot(out[,"x"], out[,"y"], type = "l", main = "Lorenz butterfly",
247 xlab = "x", ylab = "y")
248
249
250 ## =======================================================================
251 ## ex. 2
252 ## SCOC model, in FORTRAN - to see the FORTRAN code:
253 ## browseURL(paste(system.file(package="deSolve"),
254 ## "/doc/examples/dynload/scoc.f",sep=""))
255 ## example from Soetaert and Herman, 2009, chapter 3. (simplified)
256 ## =======================================================================
257
258 ## Forcing function data
259 Flux <- matrix(ncol = 2, byrow = TRUE, data = c(
260 1, 0.654, 11, 0.167, 21, 0.060, 41, 0.070, 73, 0.277, 83, 0.186,
261 93, 0.140,103, 0.255, 113, 0.231,123, 0.309,133, 1.127,143, 1.923,
262 153,1.091,163, 1.001, 173, 1.691,183, 1.404,194, 1.226,204, 0.767,
263 214,0.893,224, 0.737, 234, 0.772,244, 0.726,254, 0.624,264, 0.439,
264 274,0.168,284, 0.280, 294, 0.202,304, 0.193,315, 0.286,325, 0.599,
265 335,1.889,345, 0.996, 355, 0.681,365, 1.135))
266
267 parms <- c(k = 0.01)
268
269 meanDepo <- mean(approx(Flux[,1], Flux[,2], xout = seq(1, 365, by = 1))$y)
270
271 Yini <- c(y = as.double(meanDepo/parms))
272
273 times <- 1:365
274 out <- vode(Yini, times, func = "scocder",
275 parms = parms, dllname = "deSolve",
276 initforc = "scocforc", forcings = Flux,
277 initfunc = "scocpar", nout = 2,
278 outnames = c("Mineralisation", "Depo"))
279
280 matplot(out[,1], out[,c("Depo", "Mineralisation")],
281 type = "l", col = c("red", "blue"), xlab = "time", ylab = "Depo")
282
283 ## Constant interpolation of forcing function - left side of interval
284 fcontrol <- list(method = "constant")
285
286 out2 <- vode(Yini, times, func = "scocder",
287 parms = parms, dllname = "deSolve",
288 initforc = "scocforc", forcings = Flux, fcontrol = fcontrol,
289 initfunc = "scocpar", nout = 2,
290 outnames = c("Mineralisation", "Depo"))
291 matplot(out2[,1], out2[,c("Depo", "Mineralisation")],
292 type = "l", col = c("red", "blue"), xlab = "time", ylab = "Depo")
293
294 ## Constant interpolation of forcing function - middle of interval
295 fcontrol <- list(method = "constant", f = 0.5)
296
297 out3 <- vode(Yini, times, func = "scocder",
298 parms = parms, dllname = "deSolve",
299 initforc = "scocforc", forcings = Flux, fcontrol = fcontrol,
300 initfunc = "scocpar", nout = 2,
301 outnames = c("Mineralisation", "Depo"))
302
303 matplot(out3[,1], out3[,c("Depo", "Mineralisation")],
304 type = "l", col = c("red", "blue"), xlab = "time", ylab = "Depo")
305
306 plot(out, out2, out3)
307 }
308 \references{
309
310 P. N. Brown, G. D. Byrne, and A. C. Hindmarsh, 1989. VODE: A Variable
311 Coefficient ODE Solver, SIAM J. Sci. Stat. Comput., 10, pp. 1038-1051.
312 \cr Also, LLNL Report UCRL-98412, June 1988.
313 \doi{10.1137/0910062}
314
315 G. D. Byrne and A. C. Hindmarsh, 1975. A Polyalgorithm for the
316 Numerical Solution of Ordinary Differential Equations. ACM
317 Trans. Math. Software, 1, pp. 71-96.
318 \doi{10.1145/355626.355636}
319
320 A. C. Hindmarsh and G. D. Byrne, 1977. EPISODE: An Effective Package
321 for the Integration of Systems of Ordinary Differential
322 Equations. LLNL Report UCID-30112, Rev. 1.
323
324 G. D. Byrne and A. C. Hindmarsh, 1976. EPISODEB: An Experimental
325 Package for the Integration of Systems of Ordinary Differential
326 Equations with Banded Jacobians. LLNL Report UCID-30132, April 1976.
327
328 A. C. Hindmarsh, 1983. ODEPACK, a Systematized Collection of ODE
329 Solvers. in Scientific Computing, R. S. Stepleman et al., eds.,
330 North-Holland, Amsterdam, pp. 55-64.
331
332 K. R. Jackson and R. Sacks-Davis, 1980. An Alternative Implementation
333 of Variable Step-Size Multistep Formulas for Stiff ODEs. ACM
334 Trans. Math. Software, 6, pp. 295-318.
335 \doi{10.1145/355900.355903}
336
337 Netlib: \url{https://netlib.org}
338 }
339 \details{
340
341 Before using the integrator \code{vode}, the user has to decide
342 whether or not the problem is stiff.
343
344 If the problem is nonstiff, use method flag \code{mf} = 10, which
345 selects a nonstiff (Adams) method, no Jacobian used.
346
347 If the problem is stiff, there are four standard choices which can be
348 specified with \code{jactype} or \code{mf}.
349
350 The options for \bold{jactype} are
351 \describe{
352 \item{jac = "fullint":}{a full Jacobian, calculated internally by
353 vode, corresponds to \code{mf} = 22,
354 }
355 \item{jac = "fullusr":}{a full Jacobian, specified by user function
356 \code{jacfunc}, corresponds to \code{mf} = 21,
357 }
358 \item{jac = "bandusr":}{a banded Jacobian, specified by user
359 function \code{jacfunc}; the size of the bands specified by
360 \code{bandup} and \code{banddown}, corresponds to \code{mf} = 24,
361 }
362 \item{jac = "bandint":}{a banded Jacobian, calculated by vode; the
363 size of the bands specified by \code{bandup} and \code{banddown},
364 corresponds to \code{mf} = 25.
365 }
366 }
367
368 More options are available when specifying \bold{mf} directly.
369
370 The legal values of \code{mf} are 10, 11, 12, 13, 14, 15, 20, 21, 22,
371 23, 24, 25, -11, -12, -14, -15, -21, -22, -24, -25.
372
373 \code{mf} is a signed two-digit integer, \code{mf = JSV*(10*METH +
374 MITER)}, where
375 \describe{
376 \item{JSV = SIGN(mf)}{indicates the Jacobian-saving strategy: JSV =
377 1 means a copy of the Jacobian is saved for reuse in the corrector
378 iteration algorithm. JSV = -1 means a copy of the Jacobian is not
379 saved.
380 }
381 \item{METH}{indicates the basic linear multistep method: METH = 1
382 means the implicit Adams method. METH = 2 means the method based
383 on backward differentiation formulas (BDF-s).
384 }
385 \item{MITER}{indicates the corrector iteration method: MITER = 0
386 means functional iteration (no Jacobian matrix is involved).
387
388 MITER = 1 means chord iteration with a user-supplied full (NEQ by
389 NEQ) Jacobian.
390
391 MITER = 2 means chord iteration with an internally generated
392 (difference quotient) full Jacobian (using NEQ extra calls to
393 \code{func} per df/dy value).
394
395 MITER = 3 means chord iteration with an internally generated
396 diagonal Jacobian approximation (using 1 extra call to \code{func}
397 per df/dy evaluation).
398
399 MITER = 4 means chord iteration with a user-supplied banded
400 Jacobian.
401
402 MITER = 5 means chord iteration with an internally generated
403 banded Jacobian (using ML+MU+1 extra calls to \code{func} per
404 df/dy evaluation).
405 }
406 }
407 If MITER = 1 or 4, the user must supply a subroutine \code{jacfunc}.
408
409 The example for integrator \code{\link{lsode}} demonstrates how to
410 specify both a banded and full Jacobian.
411
412 The input parameters \code{rtol}, and \code{atol} determine the
413 \bold{error control} performed by the solver. If the request for
414 precision exceeds the capabilities of the machine, vode will return an
415 error code. See \code{\link{lsoda}} for details.
416
417
418 The diagnostics of the integration can be printed to screen
419 by calling \code{\link{diagnostics}}. If \code{verbose} = \code{TRUE},
420 the diagnostics will written to the screen at the end of the integration.
421
422 See vignette("deSolve") for an explanation of each element in the vectors
423 containing the diagnostic properties and how to directly access them.
424
425 \bold{Models} may be defined in compiled C or FORTRAN code, as well as
426 in an R-function. See package vignette \code{"compiledCode"} for details.
427
428 More information about models defined in compiled code is in the package
429 vignette ("compiledCode"); information about linking forcing functions
430 to compiled code is in \link{forcings}.
431
432 Examples in both C and FORTRAN are in the \file{dynload} subdirectory
433 of the \code{deSolve} package directory.
434
435
436 }
437 \seealso{
438 \itemize{
439 \item \code{\link{rk}}, \item \code{\link{rk4}} and \code{\link{euler}} for
440 Runge-Kutta integrators.
441 \item \code{\link{lsoda}}, \code{\link{lsode}},
442 \code{\link{lsodes}}, \code{\link{lsodar}},
443 \code{\link{daspk}} for other solvers of the Livermore family,
444 \item \code{\link{ode}} for a general interface to most of the ODE solvers,
445 \item \code{\link{ode.band}} for solving models with a banded
446 Jacobian,
447 \item \code{\link{ode.1D}} for integrating 1-D models,
448 \item \code{\link{ode.2D}} for integrating 2-D models,
449 \item \code{\link{ode.3D}} for integrating 3-D models,
450 }
451
452 \code{\link{diagnostics}} to print diagnostic messages.
453 }
454 \note{
455 From version 1.10.4, the default of \code{atol} was changed from 1e-8 to 1e-6,
456 to be consistent with the other solvers.
457 }
458 \keyword{math}
459