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