| 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 } |