Debian Codegraph @

man/rk4.Rd

raw
1 \name{rk4}
2 \alias{rk4}
3 \alias{euler}
4 \alias{euler.1D}
5 \title{Solve System of ODE (Ordinary Differential Equation)s by
6 Euler's Method or Classical Runge-Kutta 4th Order Integration.
7 }
8 \description{Solving initial value problems for systems of first-order
9 ordinary differential equations (ODEs) using Euler's method or the
10 classical Runge-Kutta 4th order integration.
11 }
12 \usage{
13 euler(y, times, func, parms, verbose = FALSE, ynames = TRUE,
14 dllname = NULL, initfunc = dllname, initpar = parms,
15 rpar = NULL, ipar = NULL, nout = 0, outnames = NULL,
16 forcings = NULL, initforc = NULL, fcontrol = NULL, ...)
17
18 rk4(y, times, func, parms, verbose = FALSE, ynames = TRUE,
19 dllname = NULL, initfunc = dllname, initpar = parms,
20 rpar = NULL, ipar = NULL, nout = 0, outnames = NULL,
21 forcings = NULL, initforc = NULL, fcontrol = NULL, ...)
22
23 euler.1D(y, times, func, parms, nspec = NULL, dimens = NULL,
24 names = NULL, verbose = FALSE, ynames = TRUE,
25 dllname = NULL, initfunc = dllname, initpar = parms,
26 rpar = NULL, ipar = NULL, nout = 0, outnames = NULL,
27 forcings = NULL, initforc = NULL, fcontrol = NULL, ...)
28 }
29 \arguments{
30 \item{y }{the initial (state) values for the ODE system. If \code{y}
31 has a name attribute, the names will be used to label the output
32 matrix.
33 }
34 \item{times }{times at which explicit estimates for \code{y} are
35 desired. The first value in \code{times} must be the initial time.
36 }
37 \item{func }{either an \R-function that computes the values of the
38 derivatives in the ODE system (the \emph{model definition}) at time
39 t, or a character string giving the name of a compiled function in a
40 dynamically loaded shared library.
41
42 If \code{func} is an \R-function, it must be defined as:
43 \code{func <- function(t, y, parms,...)}. \code{t} is the current
44 time point in the integration, \code{y} is the current estimate of
45 the variables in the ODE system. If the initial values \code{y} has
46 a \code{names} attribute, the names will be available inside \code{func}.
47 \code{parms} is a vector or list of parameters; ... (optional) are
48 any other arguments passed to the function.
49
50 The return value of \code{func} should be a list, whose first
51 element is a vector containing the derivatives of \code{y} with
52 respect to \code{time}, and whose next elements are global values
53 that are required at each point in \code{times}. The derivatives
54 must be specified in the \bold{same order} as the state variables \code{y}.
55
56 If \code{func} is a string, then \code{dllname} must give the name
57 of the shared library (without extension) which must be loaded
58 before \code{rk4} is called. See package vignette
59 \code{"compiledCode"} for more details.
60 }
61 \item{parms }{vector or list of parameters used in \code{func}.
62 }
63 \item{nspec }{for 1D models only: the number of \bold{species} (components)
64 in the model. If \code{NULL}, then \code{dimens} should be specified.
65 }
66 \item{dimens}{for 1D models only: the number of \bold{boxes} in the
67 model. If \code{NULL}, then \code{nspec} should be specified.
68 }
69 \item{names }{for 1D models only: the names of the components; used
70 for plotting.
71 }
72 \item{verbose }{a logical value that, when \code{TRUE}, triggers more
73 verbose output from the ODE solver.
74 }
75 \item{ynames }{if \code{FALSE}: names of state variables are not passed
76 to function \code{func} ; this may speed up the simulation especially
77 for large models.
78 }
79 \item{dllname }{a string giving the name of the shared library
80 (without extension) that contains all the compiled function or
81 subroutine definitions refered to in \code{func}.
82 See package vignette \code{"compiledCode"}.
83 }
84 \item{initfunc }{if not \code{NULL}, the name of the initialisation function
85 (which initialises values of parameters), as provided in
86 \file{dllname}. See package vignette \code{"compiledCode"},
87 }
88 \item{initpar }{only when \file{dllname} is specified and an
89 initialisation function \code{initfunc} is in the DLL: the
90 parameters passed to the initialiser, to initialise the common
91 blocks (FORTRAN) or global variables (C, C++).
92 }
93 \item{rpar }{only when \file{dllname} is specified: a vector with
94 double precision values passed to the DLL-functions whose names are
95 specified by \code{func} and \code{jacfunc}.
96 }
97 \item{ipar }{only when \file{dllname} is specified: a vector with
98 integer values passed to the dll-functions whose names are specified
99 by \code{func} and \code{jacfunc}.
100 }
101 \item{nout }{only used if \code{dllname} is specified and the model is
102 defined in compiled code: the number of output variables calculated
103 in the compiled function \code{func}, present in the shared
104 library. Note: it is not automatically checked whether this is
105 indeed the number of output variables calculated in the DLL - you have
106 to perform this check in the code. See package vignette
107 \code{"compiledCode"}.
108 }
109 \item{outnames }{only used if \file{dllname} is specified and
110 \code{nout} > 0: the names of output variables calculated in the
111 compiled function \code{func}, present in the shared library.
112 }
113 \item{forcings }{only used if \file{dllname} is specified: a list with
114 the forcing function data sets, each present as a two-columned matrix,
115 with (time, value); interpolation outside the interval
116 [min(\code{times}), max(\code{times})] is done by taking the value at
117 the closest data extreme.
118
119 See \link{forcings} or package vignette \code{"compiledCode"}.
120 }
121 \item{initforc }{if not \code{NULL}, the name of the forcing function
122 initialisation function, as provided in
123 \file{dllname}. It MUST be present if \code{forcings} has been given a
124 value.
125 See \link{forcings} or package vignette \code{"compiledCode"}.
126 }
127 \item{fcontrol }{A list of control parameters for the forcing functions.
128 See \link{forcings} or vignette \code{compiledCode}.
129 }
130 \item{... }{additional arguments passed to \code{func} allowing this
131 to be a generic function.
132 }
133 }
134 \author{Thomas Petzoldt \email{[email protected]}}
135 \details{
136 \code{rk4} and \code{euler} are special versions of the two fixed step
137 solvers with less overhead and less functionality (e.g. no interpolation
138 and no events) compared to the generic Runge-Kutta codes called by
139 \code{\link{ode}} resp. \code{\link{rk}}.
140
141 If you need different internal and external time steps or want to use events,
142 please use:
143 \code{rk(y, times, func, parms, method = "rk4")} or
144 \code{rk(y, times, func, parms, method = "euler")}.
145
146 See help pages of \code{\link{rk}} and \code{\link{rkMethod}}
147 for details.
148
149 Function \code{euler.1D} essentially calls function \code{euler} but
150 contains additional code to support plotting of 1D models, see
151 \code{\link{ode.1D}} and \code{\link{plot.1D}} for details.
152 }
153 \note{
154 For most practical cases, solvers with flexible timestep
155 (e.g. \code{rk(method = "ode45")} and especially solvers of the
156 Livermore family (ODEPACK, e.g. \code{\link{lsoda}}) are superior.
157 }
158
159 \value{
160 A matrix of class \code{deSolve} with up to as many rows as elements
161 in \code{times} and as many columns as elements in \code{y} plus the
162 number of "global" values returned in the next elements of the return
163 from \code{func}, plus and additional column for the time value.
164 There will be a row for each element in \code{times} unless the
165 integration routine returns with an unrecoverable error. If \code{y}
166 has a names attribute, it will be used to label the columns of the
167 output value.
168 }
169
170 \examples{
171 ## =======================================================================
172 ## Example: Analytical and numerical solutions of logistic growth
173 ## =======================================================================
174
175 ## the derivative of the logistic
176 logist <- function(t, x, parms) {
177 with(as.list(parms), {
178 dx <- r * x[1] * (1 - x[1]/K)
179 list(dx)
180 })
181 }
182
183 time <- 0:100
184 N0 <- 0.1; r <- 0.5; K <- 100
185 parms <- c(r = r, K = K)
186 x <- c(N = N0)
187
188 ## analytical solution
189 plot(time, K/(1 + (K/N0-1) * exp(-r*time)), ylim = c(0, 120),
190 type = "l", col = "red", lwd = 2)
191
192 ## reasonable numerical solution with rk4
193 time <- seq(0, 100, 2)
194 out <- as.data.frame(rk4(x, time, logist, parms))
195 points(out$time, out$N, pch = 16, col = "blue", cex = 0.5)
196
197 ## same time step with euler, systematic under-estimation
198 time <- seq(0, 100, 2)
199 out <- as.data.frame(euler(x, time, logist, parms))
200 points(out$time, out$N, pch = 1)
201
202 ## unstable result
203 time <- seq(0, 100, 4)
204 out <- as.data.frame(euler(x, time, logist, parms))
205 points(out$time, out$N, pch = 8, cex = 0.5)
206
207 ## method with automatic time step
208 out <- as.data.frame(lsoda(x, time, logist, parms))
209 points(out$time, out$N, pch = 1, col = "green")
210
211 legend("bottomright",
212 c("analytical","rk4, h=2", "euler, h=2",
213 "euler, h=4", "lsoda"),
214 lty = c(1, NA, NA, NA, NA), lwd = c(2, 1, 1, 1, 1),
215 pch = c(NA, 16, 1, 8, 1),
216 col = c("red", "blue", "black", "black", "green"))
217 }
218 \seealso{
219 \itemize{
220 \item \code{\link{rkMethod}} for a list of available Runge-Kutta
221 parameter sets,
222 \item \code{\link{rk}} for the more general Runge-Code,
223 \item \code{\link{lsoda}}, \code{\link{lsode}},
224 \code{\link{lsodes}}, \code{\link{lsodar}}, \code{\link{vode}},
225 \code{\link{daspk}} for solvers of the Livermore family,
226 \item \code{\link{ode}} for a general interface to most of the ODE solvers,
227 \item \code{\link{ode.band}} for solving models with a banded
228 Jacobian,
229 \item \code{\link{ode.1D}} for integrating 1-D models,
230 \item \code{\link{ode.2D}} for integrating 2-D models,
231 \item \code{\link{ode.3D}} for integrating 3-D models,
232 \item \code{\link{dede}} for integrating models with delay
233 differential equations,
234 }
235 \code{\link{diagnostics}} to print diagnostic messages.
236 }
237 \keyword{math}
238