| 1 |
\name{rkMethod} |
| 2 |
\alias{rkMethod} |
| 3 |
|
| 4 |
\title{Collection of Parameter Sets (Butcher Arrays) for |
| 5 |
the Runge-Kutta Family of ODE Solvers |
| 6 |
} |
| 7 |
\description{ |
| 8 |
This function returns a list specifying coefficients and properties of |
| 9 |
ODE solver methods from the Runge-Kutta family. |
| 10 |
} |
| 11 |
\usage{ |
| 12 |
rkMethod(method = NULL, ...) |
| 13 |
} |
| 14 |
\arguments{ |
| 15 |
|
| 16 |
\item{method }{a string constant naming one of the pre-defined methods |
| 17 |
of the Runge-Kutta family of solvers. The most common methods are |
| 18 |
the fixed-step methods \code{"euler"}, \code{"rk2"}, \code{"rk4"} or |
| 19 |
the variable step methods \code{"rk23bs"} (alias \code{"ode23"}), |
| 20 |
\code{"rk45dp7"} (alias \code{"ode45"}) or \code{"rk78f"}. |
| 21 |
} |
| 22 |
|
| 23 |
\item{\dots }{specification of a user-defined solver, see \emph{Value} |
| 24 |
and example below. |
| 25 |
} |
| 26 |
} |
| 27 |
\details{ |
| 28 |
This function supplies \code{method} settings for \code{\link{rk}} or |
| 29 |
\code{\link{ode}}. If called without arguments, the names of all |
| 30 |
currently implemented solvers of the Runge-Kutta family are returned. |
| 31 |
|
| 32 |
The following comparison gives an idea how the algorithms of \pkg{deSolve} |
| 33 |
are related to similar algorithms of other simulation languages: |
| 34 |
|
| 35 |
\tabular{lll}{ |
| 36 |
\bold{rkMethod} \tab | \tab \bold{Description} \cr |
| 37 |
"euler" \tab | \tab Euler's Method\cr |
| 38 |
"rk2" \tab | \tab 2nd order Runge-Kutta, fixed time step (Heun's method)\cr |
| 39 |
"rk4" \tab | \tab classical 4th order Runge-Kutta, fixed time step\cr |
| 40 |
"rk23" \tab | \tab Runge-Kutta, order 2(3); Octave: ode23\cr |
| 41 |
"rk23bs", "ode23" \tab | \tab Bogacki-Shampine, order 2(3); Matlab: ode23\cr |
| 42 |
"rk34f" \tab | \tab Runge-Kutta-Fehlberg, order 3(4)\cr |
| 43 |
"rk45ck" \tab | \tab Runge-Kutta Cash-Karp, order 4(5)\cr |
| 44 |
"rk45f" \tab | \tab Runge-Kutta-Fehlberg, order 4(5); Octave: ode45, pair=1 \cr |
| 45 |
"rk45e" \tab | \tab Runge-Kutta-England, order 4(5)\cr |
| 46 |
"rk45dp6" \tab | \tab Dormand-Prince, order 4(5), local order 6\cr |
| 47 |
"rk45dp7", "ode45" \tab | \tab Dormand-Prince 4(5), local order 7 \cr |
| 48 |
\tab | \tab (also known as dopri5; MATLAB: ode45; Octave: ode45, pair=0)\cr |
| 49 |
"rk78f" \tab | \tab Runge-Kutta-Fehlberg, order 7(8)\cr |
| 50 |
"rk78dp" \tab | \tab Dormand-Prince, order 7(8)\cr |
| 51 |
} |
| 52 |
|
| 53 |
Note that this table is based on the Runge-Kutta coefficients only, |
| 54 |
but the algorithms differ also in their implementation, in their |
| 55 |
stepsize adaption strategy and interpolation methods. |
| 56 |
|
| 57 |
The table reflects the state at time of writing and it is of course possible |
| 58 |
that implementations change. |
| 59 |
|
| 60 |
Methods \code{"rk45dp7"} (alias \code{"ode45"}) and \code{"rk45ck"} contain |
| 61 |
specific and efficient built-in interpolation schemes (dense output). |
| 62 |
|
| 63 |
As an alternative, Neville-Aitken polynomials can be used to interpolate between |
| 64 |
time steps. This is available for all RK methods and may be useful to speed |
| 65 |
up computation if no dense-output formula is available. Note however, that |
| 66 |
this can introduce considerable local error; it is disabled by default |
| 67 |
(see \code{nknots} below). |
| 68 |
} |
| 69 |
|
| 70 |
\note{ |
| 71 |
\itemize{ |
| 72 |
\item Adaptive stepsize Runge-Kuttas are preferred if the solution |
| 73 |
contains parts when the states change fast, and parts when not much |
| 74 |
happens. They will take small steps over bumpy ground and long steps |
| 75 |
over uninteresting terrain. |
| 76 |
|
| 77 |
\item As a suggestion, one may use \code{"rk23"} (alias |
| 78 |
\code{"ode23"}) for simple problems and \code{"rk45dp7"} (alias |
| 79 |
\code{"ode45"}) for rough problems. The default solver is |
| 80 |
\code{"rk45dp7"} (alias "ode45"), because of its relatively high |
| 81 |
order (4), re-use of the last intermediate steps (FSAL = first |
| 82 |
same as last) and built-in polynomial interpolation (dense |
| 83 |
output). |
| 84 |
|
| 85 |
\item Solver \code{"rk23bs"}, that supports also FSAL, may be useful for |
| 86 |
slightly stiff systems if demands on precision are relatively low. |
| 87 |
|
| 88 |
\item Another good choice, assuring medium accuracy, is the Cash-Karp |
| 89 |
Runge-Kutta method, \code{"rk45ck"}. |
| 90 |
|
| 91 |
\item Classical \code{"rk4"} is traditionally used in cases where an |
| 92 |
adequate stepsize is known a-priori or if external forcing data |
| 93 |
are provided for fixed time steps only and frequent interpolation |
| 94 |
of external data needs to be avoided. |
| 95 |
|
| 96 |
\item Method \code{"rk45dp7"} (alias \code{"ode45"}) contains an |
| 97 |
efficient built-in interpolation scheme (dense output) based on |
| 98 |
intermediate function evaluations. |
| 99 |
} |
| 100 |
|
| 101 |
Starting with version 1.8 implicit Runge-Kutta (\code{irk}) methods |
| 102 |
are also supported by the general \code{rk} interface, however their |
| 103 |
implementation is still experimental. Instead of this you may |
| 104 |
consider \code{\link{radau}} for a specific full implementation of an |
| 105 |
implicit Runge-Kutta method. |
| 106 |
} |
| 107 |
|
| 108 |
\value{ |
| 109 |
A list with the following elements: |
| 110 |
|
| 111 |
\item{ID}{name of the method (character)} |
| 112 |
\item{varstep}{boolean value specifying if the method allows for |
| 113 |
variable time step (\code{TRUE}) or not (\code{FALSE}). |
| 114 |
} |
| 115 |
|
| 116 |
\item{FSAL}{(first same as last) optional boolean value specifying if |
| 117 |
the method allows re-use of the last function evaluation |
| 118 |
(\code{TRUE}) or not (\code{FALSE} or \code{NULL}). |
| 119 |
} |
| 120 |
|
| 121 |
\item{A}{coefficient matrix of the method. As \code{link{rk}} supports |
| 122 |
only explicit methods, this matrix must be lower triangular. |
| 123 |
\code{A} must be a vector for fixed step methods where only the |
| 124 |
subdiagonal values are different from zero. |
| 125 |
} |
| 126 |
\item{b1}{coefficients of the lower order Runge-Kutta pair. |
| 127 |
} |
| 128 |
\item{b2}{coefficients of the higher order Runge-Kutta pair |
| 129 |
(optional, for embedded methods that allow variable time step). |
| 130 |
} |
| 131 |
\item{c}{coefficients for calculating the intermediate time steps.} |
| 132 |
|
| 133 |
\item{d}{optional coefficients for built-in polynomial interpolation |
| 134 |
of the outputs from internal steps (dense output), currently only |
| 135 |
available for method \code{rk45dp7} (Dormand-Prince). |
| 136 |
} |
| 137 |
|
| 138 |
\item{densetype}{optional integer value specifying the dense output formula; |
| 139 |
currently only \code{densetype = 1} for \code{rk45dp7} (Dormand-Prince) |
| 140 |
and \code{densetype = 2} for \code{rk45ck} (Cash-Karp) are supported. |
| 141 |
Undefined values (e.g., \code{densetype = NULL}) disable dense output. |
| 142 |
} |
| 143 |
|
| 144 |
\item{stage}{number of function evaluations needed (corresponds to |
| 145 |
number of rows in A). |
| 146 |
} |
| 147 |
\item{Qerr}{global error order of the method, important for automatic |
| 148 |
time-step adjustment. |
| 149 |
} |
| 150 |
|
| 151 |
\item{nknots}{integer value specifying the order of interpolation |
| 152 |
polynomials for methods without dense output. If \code{nknots} < 2 |
| 153 |
(the default) then internal interpolation is switched off and |
| 154 |
integration is performed step by step between external time steps. |
| 155 |
|
| 156 |
If \code{nknots} is between 3 and 8, Neville-Aitken polynomials |
| 157 |
are used, which need at least \code{nknots + 1} internal time steps. |
| 158 |
Interpolation may speed up integration but can lead to local |
| 159 |
errors higher than the tolerance, especially if external and |
| 160 |
internal time steps are very different. |
| 161 |
} |
| 162 |
|
| 163 |
\item{alpha}{optional tuning parameter for stepsize |
| 164 |
adjustment. If \code{alpha} is omitted, it is set to |
| 165 |
\eqn{1/Qerr - 0.75 beta}. The default value is |
| 166 |
\eqn{1/Qerr} (for \code{beta} = 0).} |
| 167 |
|
| 168 |
\item{beta}{optional tuning parameter for stepsize adjustment. Typical |
| 169 |
values are \eqn{0} (default) or \eqn{0.4/Qerr}. |
| 170 |
} |
| 171 |
|
| 172 |
} |
| 173 |
|
| 174 |
\references{ |
| 175 |
|
| 176 |
Bogacki, P. and Shampine L.F. (1989) A 3(2) pair of Runge-Kutta |
| 177 |
formulas, Appl. Math. Lett. \bold{2}, 1--9. |
| 178 |
|
| 179 |
Butcher, J. C. (1987) The numerical analysis of ordinary differential |
| 180 |
equations, Runge-Kutta and general linear methods, Wiley, Chichester |
| 181 |
and New York. |
| 182 |
|
| 183 |
Cash, J. R. and Karp A. H., 1990. A variable order Runge-Kutta method |
| 184 |
for initial value problems with rapidly varying right-hand sides, |
| 185 |
ACM Transactions on Mathematical Software \bold{16}, 201--222. |
| 186 |
\doi{10.1145/79505.79507} |
| 187 |
|
| 188 |
Dormand, J. R. and Prince, P. J. (1980) A family of embedded |
| 189 |
Runge-Kutta formulae, J. Comput. Appl. Math. \bold{6}(1), 19--26. |
| 190 |
|
| 191 |
Engeln-Muellges, G. and Reutter, F. (1996) Numerik Algorithmen: |
| 192 |
Entscheidungshilfe zur Auswahl und Nutzung. VDI Verlag, Duesseldorf. |
| 193 |
|
| 194 |
Fehlberg, E. (1967) Klassische Runge-Kutta-Formeln fuenfter and |
| 195 |
siebenter Ordnung mit Schrittweiten-Kontrolle, Computing |
| 196 |
(Arch. Elektron. Rechnen) \bold{4}, 93--106. |
| 197 |
|
| 198 |
Kutta, W. (1901) Beitrag zur naeherungsweisen Integration totaler |
| 199 |
Differentialgleichungen, Z. Math. Phys. \bold{46}, 435--453. |
| 200 |
|
| 201 |
Octave-Forge - Extra Packages for GNU Octave, Package OdePkg. |
| 202 |
\url{https://octave.sourceforge.io} |
| 203 |
|
| 204 |
Prince, P. J. and Dormand, J. R. (1981) High order embedded |
| 205 |
Runge-Kutta formulae, J. Comput. Appl. Math. \bold{7}(1), 67--75. |
| 206 |
\doi{10.1016/0771-050X(81)90010-3} |
| 207 |
|
| 208 |
Runge, C. (1895) Ueber die numerische Aufloesung von |
| 209 |
Differentialgleichungen, Math. Ann. \bold{46}, 167--178. |
| 210 |
|
| 211 |
MATLAB (R) is a registed property of The Mathworks Inc. |
| 212 |
} |
| 213 |
|
| 214 |
\author{Thomas Petzoldt \email{[email protected]}} |
| 215 |
|
| 216 |
\seealso{\code{\link{rk}}, \code{\link{ode}}} |
| 217 |
\examples{ |
| 218 |
rkMethod() # returns the names of all available methods |
| 219 |
rkMethod("rk45dp7") # parameters of the Dormand-Prince 5(4) method |
| 220 |
rkMethod("ode45") # an alias for the same method |
| 221 |
|
| 222 |
func <- function(t, x, parms) { |
| 223 |
with(as.list(c(parms, x)),{ |
| 224 |
dP <- a * P - b * C * P |
| 225 |
dC <- b * P * C - c * C |
| 226 |
res <- c(dP, dC) |
| 227 |
list(res) |
| 228 |
}) |
| 229 |
} |
| 230 |
times <- seq(0, 200, length = 101) |
| 231 |
parms <- c(a = 0.1, b = 0.1, c = 0.1) |
| 232 |
x <- c(P = 2, C = 1) |
| 233 |
|
| 234 |
## rk using ode45 as the default method |
| 235 |
out <- rk(x, times, func, parms) |
| 236 |
|
| 237 |
## all methods can be called also from 'ode' by using rkMethod |
| 238 |
out <- ode(x, times, func, parms, method = rkMethod("rk4")) |
| 239 |
|
| 240 |
## 'ode' has aliases for the most common RK methods |
| 241 |
out <- ode(x, times, func, parms, method = "ode45") |
| 242 |
|
| 243 |
##=========================================================================== |
| 244 |
## Comparison of local error from different interpolation methods |
| 245 |
##=========================================================================== |
| 246 |
|
| 247 |
## lsoda with lower tolerances (1e-10) used as reference |
| 248 |
o0 <- ode(x, times, func, parms, method = "lsoda", atol = 1e-10, rtol = 1e-10) |
| 249 |
|
| 250 |
## rk45dp7 with hmax = 10 > delta_t = 2 |
| 251 |
o1 <- ode(x, times, func, parms, method = rkMethod("rk45dp7"), hmax = 10) |
| 252 |
|
| 253 |
## disable dense-output interpolation |
| 254 |
## and use only Neville-Aitken polynomials instead |
| 255 |
o2 <- ode(x, times, func, parms, |
| 256 |
method = rkMethod("rk45dp7", densetype = NULL, nknots = 5), hmax = 10) |
| 257 |
|
| 258 |
## stop and go: disable interpolation completely |
| 259 |
## and integrate explicitly between external time steps |
| 260 |
o3 <- ode(x, times, func, parms, |
| 261 |
method = rkMethod("rk45dp7", densetype = NULL, nknots = 0, hmax=10)) |
| 262 |
|
| 263 |
## compare different interpolation methods with lsoda |
| 264 |
mf <- par("mfrow" = c(4, 1)) |
| 265 |
matplot(o1[,1], o1[,-1], type = "l", xlab = "Time", main = "State Variables", |
| 266 |
ylab = "P, C") |
| 267 |
matplot(o0[,1], o0[,-1] - o1[,-1], type = "l", xlab = "Time", ylab = "Diff.", |
| 268 |
main="Difference between lsoda and ode45 with dense output") |
| 269 |
abline(h = 0, col = "grey") |
| 270 |
matplot(o0[,1], o0[,-1] - o2[,-1], type = "l", xlab = "Time", ylab = "Diff.", |
| 271 |
main="Difference between lsoda and ode45 with Neville-Aitken") |
| 272 |
abline(h = 0, col = "grey") |
| 273 |
matplot(o0[,1], o0[,-1] - o3[,-1], type = "l", xlab = "Time", ylab = "Diff.", |
| 274 |
main="Difference between lsoda and ode45 in 'stop and go' mode") |
| 275 |
abline(h = 0, col = "grey") |
| 276 |
par(mf) |
| 277 |
|
| 278 |
##=========================================================================== |
| 279 |
## rkMethod allows to define user-specified Runge-Kutta methods |
| 280 |
##=========================================================================== |
| 281 |
out <- ode(x, times, func, parms, |
| 282 |
method = rkMethod(ID = "midpoint", |
| 283 |
varstep = FALSE, |
| 284 |
A = c(0, 1/2), |
| 285 |
b1 = c(0, 1), |
| 286 |
c = c(0, 1/2), |
| 287 |
stage = 2, |
| 288 |
Qerr = 1 |
| 289 |
) |
| 290 |
) |
| 291 |
plot(out) |
| 292 |
|
| 293 |
## compare method diagnostics |
| 294 |
times <- seq(0, 200, length = 10) |
| 295 |
o1 <- ode(x, times, func, parms, method = rkMethod("rk45ck")) |
| 296 |
o2 <- ode(x, times, func, parms, method = rkMethod("rk78dp")) |
| 297 |
diagnostics(o1) |
| 298 |
diagnostics(o2) |
| 299 |
|
| 300 |
} |
| 301 |
|
| 302 |
\keyword{ math } |
| 303 |
|