Debian Codegraph @

man/rk.Rd

raw
1 \name{rk}
2 \alias{rk}
3
4 \title{Explicit One-Step Solvers for Ordinary Differential Equations
5 (ODE)}
6
7 \description{Solving initial value problems for non-stiff systems of
8 first-order ordinary differential equations (ODEs).
9
10 The \R function \code{rk} is a top-level function that provides
11 interfaces to a collection of common explicit one-step solvers of the
12 Runge-Kutta family with fixed or variable time steps.
13
14 The system of ODE's is written as an \R function (which may, of
15 course, use \code{\link{.C}}, \code{\link{.Fortran}},
16 \code{\link{.Call}}, etc., to call foreign code) or be defined in
17 compiled code that has been dynamically loaded. A vector of
18 parameters is passed to the ODEs, so the solver may be used as part of
19 a modeling package for ODEs, or for parameter estimation using any
20 appropriate modeling tool for non-linear models in \R such as
21 \code{\link{optim}}, \code{\link{nls}}, \code{\link{nlm}} or
22 \code{\link[nlme]{nlme}}
23 }
24 \usage{
25 rk(y, times, func, parms, rtol = 1e-6, atol = 1e-6,
26 verbose = FALSE, tcrit = NULL, hmin = 0, hmax = NULL,
27 hini = hmax, ynames = TRUE, method = rkMethod("rk45dp7", ... ),
28 maxsteps = 5000, dllname = NULL, initfunc = dllname,
29 initpar = parms, rpar = NULL, ipar = NULL,
30 nout = 0, outnames = NULL, forcings = NULL,
31 initforc = NULL, fcontrol = NULL, events = NULL, ...)
32 }
33 \arguments{
34 \item{y }{the initial (state) values for the ODE system. If \code{y}
35 has a name attribute, the names will be used to label the output
36 matrix.
37 }
38 \item{times }{times at which explicit estimates for \code{y} are
39 desired. The first value in \code{times} must be the initial time.
40 }
41 \item{func }{either an \R-function that computes the values of the
42 derivatives in the ODE system (the \emph{model definition}) at time
43 t, or a character string giving the name of a compiled function in a
44 dynamically loaded shared library.
45
46 If \code{func} is an \R-function, it must be defined as:
47 \code{func <- function(t, y, parms,...)}. \code{t} is the current
48 time point in the integration, \code{y} is the current estimate of
49 the variables in the ODE system. If the initial values \code{y} has
50 a \code{names} attribute, the names will be available inside \code{func}.
51 \code{parms} is a vector or list of parameters; ... (optional) are
52 any other arguments passed to the function.
53
54 The return value of \code{func} should be a list, whose first
55 element is a vector containing the derivatives of \code{y} with
56 respect to \code{time}, and whose next elements are global values
57 that are required at each point in \code{times}. The derivatives
58 must be specified in the \bold{same order} as the state variables \code{y}.
59
60 If \code{func} is
61 a string, then \code{dllname} must give the name of the shared
62 library (without extension) which must be loaded before
63 \code{rk} is called. See package vignette \code{"compiledCode"}
64 for more details.
65
66 }
67 \item{parms }{vector or list of parameters used in \code{func}.
68 }
69 \item{rtol }{relative error tolerance, either a scalar or an array as
70 long as \code{y}. Only applicable to methods with variable time
71 step, see details.
72 }
73 \item{atol }{absolute error tolerance, either a scalar or an array as
74 long as \code{y}. Only applicable to methods with variable time
75 step, see details.
76 }
77 \item{tcrit }{if not \code{NULL}, then \code{rk} cannot integrate past
78 \code{tcrit}. This parameter is for compatibility with other solvers.
79 }
80 \item{verbose }{a logical value that, when TRUE, triggers more
81 verbose output from the ODE solver.
82 }
83 \item{hmin }{an optional minimum value of the integration stepsize. In
84 special situations this parameter may speed up computations with the
85 cost of precision. Don't use \code{hmin} if you don't know why!
86 }
87 \item{hmax }{an optional maximum value of the integration stepsize. If
88 not specified, \code{hmax} is set to the maximum of \code{hini} and
89 the largest difference in \code{times}, to avoid that the simulation
90 possibly ignores short-term events. If 0, no maximal size is
91 specified. Note that \code{hmin} and \code{hmax} are ignored by
92 fixed step methods like \code{"rk4"} or \code{"euler"}.
93 }
94 \item{hini }{initial step size to be attempted; if 0, the initial step
95 size is determined automatically by solvers with flexible time step.
96 For fixed step methods, setting \code{hini = 0} forces
97 internal time steps identically to external time steps provided by
98 \code{times}. Similarly, internal time steps of non-interpolating
99 solvers cannot be bigger than external time steps specified in \code{times}.
100 }
101 \item{ynames }{if \code{FALSE}: names of state variables are not passed
102 to function \code{func} ; this may speed up the simulation especially
103 for large models.
104 }
105
106 \item{method }{the integrator to use. This can either be a string
107 constant naming one of the pre-defined methods or a call to function
108 \code{\link{rkMethod}} specifying a user-defined method. The most
109 common methods are the fixed-step methods \code{"euler"}, second and
110 fourth-order Runge Kutta (\code{"rk2"}, \code{"rk4"}), or the
111 variable step methods Bogacki-Shampine \code{"rk23bs"},
112 Runge-Kutta-Fehlberg \code{"rk34f"}, the fifth-order Cash-Karp
113 method \code{"rk45ck"} or the fifth-order Dormand-Prince method with
114 seven stages \code{"rk45dp7"}.
115 As a suggestion, one may use \code{"rk23bs"} (alias \code{"ode23"}) for
116 simple problems and \code{"rk45dp7"} (alias \code{"ode45"}) for
117 rough problems.
118 }
119 \item{maxsteps }{average maximal number of steps per output interval
120 taken by the solver. This argument is defined such as to ensure
121 compatibility with the Livermore-solvers. \code{rk} only accepts the maximal
122 number of steps for the entire integration. It is calculated
123 as \code{max(length(times) * maxsteps, max(diff(times)/hini + 1)}.
124 }
125 \item{dllname }{a string giving the name of the shared library
126 (without extension) that contains all the compiled function or
127 subroutine definitions refered to in \code{func} and
128 \code{jacfunc}. See package vignette \code{"compiledCode"}.
129 }
130 \item{initfunc }{if not \code{NULL}, the name of the initialisation function
131 (which initialises values of parameters), as provided in
132 \file{dllname}. See package vignette \code{"compiledCode"}.
133 }
134 \item{initpar }{only when \file{dllname} is specified and an
135 initialisation function \code{initfunc} is in the dll: the
136 parameters passed to the initialiser, to initialise the common
137 blocks (FORTRAN) or global variables (C, C++).
138 }
139 \item{rpar }{only when \file{dllname} is specified: a vector with
140 double precision values passed to the dll-functions whose names are
141 specified by \code{func} and \code{jacfunc}.
142 }
143 \item{ipar }{only when \file{dllname} is specified: a vector with
144 integer values passed to the dll-functions whose names are specified
145 by \code{func} and \code{jacfunc}.
146 }
147 \item{nout }{only used if \code{dllname} is specified and the model is
148 defined in compiled code: the number of output variables calculated
149 in the compiled function \code{func}, present in the shared
150 library. Note: it is not automatically checked whether this is
151 indeed the number of output variables calculated in the dll - you have
152 to perform this check in the code. See package vignette
153 \code{"compiledCode"}.
154 }
155 \item{outnames }{only used if \file{dllname} is specified and
156 \code{nout} > 0: the names of output variables calculated in the
157 compiled function \code{func}, present in the shared library.
158 }
159 \item{forcings }{only used if \file{dllname} is specified: a list with
160 the forcing function data sets, each present as a two-columned matrix,
161 with (time,value); interpolation outside the interval
162 [min(\code{times}), max(\code{times})] is done by taking the value at
163 the closest data extreme.
164
165 See \link{forcings} or package vignette \code{"compiledCode"}.
166 }
167 \item{initforc }{if not \code{NULL}, the name of the forcing function
168 initialisation function, as provided in
169 \file{dllname}. It MUST be present if \code{forcings} has been given a
170 value.
171 See \link{forcings} or package vignette \code{"compiledCode"}.
172 }
173 \item{fcontrol }{A list of control parameters for the forcing functions.
174 See \link{forcings} or vignette \code{compiledCode}.
175 }
176 \item{events }{A matrix or data frame that specifies events, i.e. when the value of a
177 state variable is suddenly changed. See \link{events} for more information.
178 Not also that if events are specified, then polynomial interpolation
179 is switched off and integration takes place from one external time step
180 to the next, with an internal step size less than or equal the difference
181 of two adjacent points of \code{times}.
182 }
183 \item{... }{additional arguments passed to \code{func} allowing this
184 to be a generic function.
185 }
186 }
187
188 \details{
189 Function \code{rk} is a generalized implementation that can be used to
190 evaluate different solvers of the Runge-Kutta family of explicit ODE
191 solvers. A pre-defined set of common method parameters is in function
192 \code{\link{rkMethod}} which also allows to supply user-defined
193 Butcher tables.
194
195 The input parameters \code{rtol}, and \code{atol} determine the error
196 control performed by the solver. The solver will control the vector
197 of estimated local errors in \bold{y}, according to an inequality of
198 the form max-norm of ( \bold{e}/\bold{ewt} ) \eqn{\leq}{ <= } 1, where
199 \bold{ewt} is a vector of positive error weights. The values of
200 \code{rtol} and \code{atol} should all be non-negative. The form of
201 \bold{ewt} is:
202
203 \deqn{\mathbf{rtol} \times \mathrm{abs}(\mathbf{y}) +
204 \mathbf{atol}}{\bold{rtol} * abs(\bold{y}) + \bold{atol}}
205
206 where multiplication of two vectors is element-by-element.
207
208 \bold{Models} can be defined in \R as a user-supplied
209 \bold{R-function}, that must be called as: \code{yprime = func(t, y,
210 parms)}. \code{t} is the current time point in the integration,
211 \code{y} is the current estimate of the variables in the ODE system.
212
213 The return value of \code{func} should be a list, whose first element
214 is a vector containing the derivatives of \code{y} with respect to
215 time, and whose second element contains output variables that are
216 required at each point in time. Examples are given below.
217 }
218 \value{
219 A matrix of class \code{deSolve} with up to as many rows as elements
220 in \code{times} and as many columns as elements in \code{y} plus the
221 number of "global" values returned in the next elements of the return
222 from \code{func}, plus and additional column for the time value.
223 There will be a row for each element in \code{times} unless the
224 integration routine returns with an unrecoverable error. If \code{y}
225 has a names attribute, it will be used to label the columns of the
226 output value.
227 }
228 \note{
229 Arguments \code{rpar} and \code{ipar} are provided for compatibility
230 with \code{lsoda}.
231
232 Starting with version 1.8 implicit Runge-Kutta methods are also
233 supported by this general \code{rk} interface, however their
234 implementation is still experimental. Instead of this you may
235 consider \code{\link{radau}} for a specific full implementation of an
236 implicit Runge-Kutta method.
237 }
238 \references{
239 Butcher, J. C. (1987) The numerical analysis of ordinary differential
240 equations, Runge-Kutta and general linear methods, Wiley, Chichester
241 and New York.
242
243 Engeln-Muellges, G. and Reutter, F. (1996) Numerik Algorithmen:
244 Entscheidungshilfe zur Auswahl und Nutzung. VDI Verlag, Duesseldorf.
245
246 Hindmarsh, Alan C. (1983) ODEPACK, A Systematized Collection of ODE
247 Solvers; in p.55--64 of Stepleman, R.W. et al.[ed.] (1983)
248 \emph{Scientific Computing}, North-Holland, Amsterdam.
249
250 Press, W. H., Teukolsky, S. A., Vetterling, W. T. and Flannery,
251 B. P. (2007) Numerical Recipes in C. Cambridge University Press.
252 }
253
254 \author{Thomas Petzoldt \email{[email protected]}}
255
256 \seealso{
257 For most practical cases, solvers of the Livermore family (i.e. the
258 ODEPACK solvers, see below) are superior. Some of them are also
259 suitable for stiff ODEs, differential algebraic equations (DAEs), or
260 partial differential equations (PDEs).
261
262 \itemize{
263 \item \code{\link{rkMethod}} for a list of available Runge-Kutta
264 parameter sets,
265 \item \code{\link{rk4}} and \code{\link{euler}} for special
266 versions without interpolation (and less overhead),
267 \item \code{\link{lsoda}}, \code{\link{lsode}},
268 \code{\link{lsodes}}, \code{\link{lsodar}}, \code{\link{vode}},
269 \code{\link{daspk}} for solvers of the Livermore family,
270 \item \code{\link{ode}} for a general interface to most of the ODE solvers,
271 \item \code{\link{ode.band}} for solving models with a banded
272 Jacobian,
273 \item \code{\link{ode.1D}} for integrating 1-D models,
274 \item \code{\link{ode.2D}} for integrating 2-D models,
275 \item \code{\link{ode.3D}} for integrating 3-D models,
276 \item \code{\link{diagnostics}} to print diagnostic messages.
277 }
278 }
279
280
281 \examples{
282 ## =======================================================================
283 ## Example: Resource-producer-consumer Lotka-Volterra model
284 ## =======================================================================
285
286 ## Notes:
287 ## - Parameters are a list, names accessible via "with" function
288 ## - Function sigimp passed as an argument (input) to model
289 ## (see also ode and lsoda examples)
290
291 SPCmod <- function(t, x, parms, input) {
292 with(as.list(c(parms, x)), {
293 import <- input(t)
294 dS <- import - b*S*P + g*C # substrate
295 dP <- c*S*P - d*C*P # producer
296 dC <- e*P*C - f*C # consumer
297 res <- c(dS, dP, dC)
298 list(res)
299 })
300 }
301
302 ## The parameters
303 parms <- c(b = 0.001, c = 0.1, d = 0.1, e = 0.1, f = 0.1, g = 0.0)
304
305 ## vector of timesteps
306 times <- seq(0, 200, length = 101)
307
308 ## external signal with rectangle impulse
309 signal <- data.frame(times = times,
310 import = rep(0, length(times)))
311
312 signal$import[signal$times >= 10 & signal$times <= 11] <- 0.2
313
314 sigimp <- approxfun(signal$times, signal$import, rule = 2)
315
316 ## Start values for steady state
317 xstart <- c(S = 1, P = 1, C = 1)
318
319 ## Euler method
320 out1 <- rk(xstart, times, SPCmod, parms, hini = 0.1,
321 input = sigimp, method = "euler")
322
323 ## classical Runge-Kutta 4th order
324 out2 <- rk(xstart, times, SPCmod, parms, hini = 1,
325 input = sigimp, method = "rk4")
326
327 ## Dormand-Prince method of order 5(4)
328 out3 <- rk(xstart, times, SPCmod, parms, hmax = 1,
329 input = sigimp, method = "rk45dp7")
330
331 mf <- par("mfrow")
332 ## deSolve plot method for comparing scenarios
333 plot(out1, out2, out3, which = c("S", "P", "C"),
334 main = c ("Substrate", "Producer", "Consumer"),
335 col =c("black", "red", "green"),
336 lty = c("solid", "dotted", "dotted"), lwd = c(1, 2, 1))
337
338 ## user-specified plot function
339 plot (out1[,"P"], out1[,"C"], type = "l", xlab = "Producer", ylab = "Consumer")
340 lines(out2[,"P"], out2[,"C"], col = "red", lty = "dotted", lwd = 2)
341 lines(out3[,"P"], out3[,"C"], col = "green", lty = "dotted")
342
343 legend("center", legend = c("euler", "rk4", "rk45dp7"),
344 lty = c(1, 3, 3), lwd = c(1, 2, 1),
345 col = c("black", "red", "green"))
346 par(mfrow = mf)
347 }
348
349 \keyword{ math }