Debian Codegraph @

man/rkMethod.Rd

raw
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