| 1 |
\name{dede} |
| 2 |
\alias{dede} |
| 3 |
\title{ |
| 4 |
General Solver for Delay Differential Equations. |
| 5 |
} |
| 6 |
\description{ |
| 7 |
Function \code{dede} is a general solver for delay differential equations, i.e. |
| 8 |
equations where the derivative depends on past values of the state variables |
| 9 |
or their derivatives. |
| 10 |
} |
| 11 |
\usage{ |
| 12 |
dede(y, times, func=NULL, parms, |
| 13 |
method = c( "lsoda", "lsode", "lsodes", "lsodar", "vode", |
| 14 |
"daspk", "bdf", "adams", "impAdams", "radau"), control = NULL, ...) |
| 15 |
} |
| 16 |
\arguments{ |
| 17 |
\item{y }{the initial (state) values for the DE system, a vector. If |
| 18 |
\code{y} has a name attribute, the names will be used to label the |
| 19 |
output matrix. |
| 20 |
} |
| 21 |
\item{times }{time sequence for which output is wanted; the first |
| 22 |
value of \code{times} must be the initial time. |
| 23 |
} |
| 24 |
\item{func }{an \R-function that computes the values of the |
| 25 |
derivatives in the ODE system (the model definition) at time \eqn{t}. |
| 26 |
|
| 27 |
\code{func} must be defined as: |
| 28 |
\code{func <- function(t, y, parms, ...)}. \code{t} is the current time |
| 29 |
point in the integration, \code{y} is the current estimate of the |
| 30 |
variables in the DE system. If the initial values \code{y} has a |
| 31 |
\code{names} attribute, the names will be available inside \code{func}. |
| 32 |
\code{parms} is a vector or list of parameters; \code{...} (optional) are |
| 33 |
any other arguments passed to the function. |
| 34 |
|
| 35 |
The return value of \code{func} should be a list, whose first |
| 36 |
element is a vector containing the derivatives of \code{y} with |
| 37 |
respect to \code{time}, and whose next elements are global values |
| 38 |
that are required at each point in \code{times}.The derivatives |
| 39 |
must be specified in the \bold{same order} as the state variables \code{y}. |
| 40 |
|
| 41 |
If method "daspk" is used, then \code{func} can be \code{NULL}, in which |
| 42 |
case \code{res} should be used. |
| 43 |
} |
| 44 |
\item{parms }{parameters passed to \code{func}. |
| 45 |
} |
| 46 |
\item{method }{the integrator to use, either a string (\code{"lsoda"}, |
| 47 |
\code{"lsode"}, \code{"lsodes"}, \code{"lsodar"}, \code{"vode"}, |
| 48 |
\code{"daspk"}, \code{"bdf"}, \code{"adams"}, \code{"impAdams"}, \code{"radau"}) |
| 49 |
or a function that performs the integration. |
| 50 |
The default integrator used is \link{lsoda}. |
| 51 |
} |
| 52 |
\item{control }{a list that can supply (1) the size of the history array, as |
| 53 |
\code{control$mxhist}; the default is 1e4 and (2) how to interpolate, as |
| 54 |
\code{control$interpol}, where \code{1} is hermitian interpolation, |
| 55 |
\code{2} is variable order interpolation, using the Nordsieck history array. |
| 56 |
Only for the two Adams methods is the second option recommended. |
| 57 |
} |
| 58 |
\item{... }{additional arguments passed to the integrator. |
| 59 |
} |
| 60 |
} |
| 61 |
|
| 62 |
\value{ |
| 63 |
A matrix of class \code{deSolve} with up to as many rows as elements in |
| 64 |
\code{times} and as many |
| 65 |
columns as elements in \code{y} plus the number of "global" values |
| 66 |
returned in the second element of the return from \code{func}, plus an |
| 67 |
additional column (the first) for the time value. There will be one |
| 68 |
row for each element in \code{times} unless the integrator returns |
| 69 |
with an unrecoverable error. If \code{y} has a names attribute, it |
| 70 |
will be used to label the columns of the output value. |
| 71 |
|
| 72 |
} |
| 73 |
\author{Karline Soetaert <[email protected]>} |
| 74 |
|
| 75 |
\details{ |
| 76 |
Functions \link{lagvalue} and \link{lagderiv} are to be used with \code{dede} |
| 77 |
as they provide access to past (lagged) |
| 78 |
values of state variables and derivatives. The number of past values that |
| 79 |
are to be stored in a history matrix, can be specified in \code{control$mxhist}. |
| 80 |
The default value (if unspecified) is 1e4. |
| 81 |
|
| 82 |
Cubic Hermite interpolation is used by default to obtain an accurate |
| 83 |
interpolant at the requested lagged time. For methods \code{adams, impAdams}, |
| 84 |
a more accurate interpolation method can be triggered by setting |
| 85 |
\code{control$interpol = 2}. |
| 86 |
|
| 87 |
\code{dede} does not deal explicitly with propagated derivative discontinuities, |
| 88 |
but relies on the integrator to control the stepsize in the region of a |
| 89 |
discontinuity. |
| 90 |
|
| 91 |
\code{dede} does not include methods to deal with delays that are smaller than the |
| 92 |
stepsize, although in some cases it may be possible to solve such models. |
| 93 |
|
| 94 |
For these reasons, it can only solve rather simple delay differential equations. |
| 95 |
|
| 96 |
When used together with integrator \code{lsodar}, or \code{lsode}, \code{dde} |
| 97 |
can simultaneously locate a root, and trigger an event. See last example. |
| 98 |
|
| 99 |
} |
| 100 |
\seealso{ |
| 101 |
\link{lagvalue}, \link{lagderiv},for how to specify lagged variables and |
| 102 |
derivatives. |
| 103 |
} |
| 104 |
\examples{ |
| 105 |
## ============================================================================= |
| 106 |
## A simple delay differential equation |
| 107 |
## dy(t) = -y(t-1) ; y(t<0)=1 |
| 108 |
## ============================================================================= |
| 109 |
|
| 110 |
##----------------------------- |
| 111 |
## the derivative function |
| 112 |
##----------------------------- |
| 113 |
derivs <- function(t, y, parms) { |
| 114 |
if (t < 1) |
| 115 |
dy <- -1 |
| 116 |
else |
| 117 |
dy <- - lagvalue(t - 1) |
| 118 |
list(c(dy)) |
| 119 |
} |
| 120 |
|
| 121 |
##----------------------------- |
| 122 |
## initial values and times |
| 123 |
##----------------------------- |
| 124 |
yinit <- 1 |
| 125 |
times <- seq(0, 30, 0.1) |
| 126 |
|
| 127 |
##----------------------------- |
| 128 |
## solve the model |
| 129 |
##----------------------------- |
| 130 |
yout <- dede(y = yinit, times = times, func = derivs, parms = NULL) |
| 131 |
|
| 132 |
##----------------------------- |
| 133 |
## display, plot results |
| 134 |
##----------------------------- |
| 135 |
plot(yout, type = "l", lwd = 2, main = "dy/dt = -y(t-1)") |
| 136 |
|
| 137 |
## ============================================================================= |
| 138 |
## The infectuous disease model of Hairer; two lags. |
| 139 |
## example 4 from Shampine and Thompson, 2000 |
| 140 |
## solving delay differential equations with dde23 |
| 141 |
## ============================================================================= |
| 142 |
|
| 143 |
##----------------------------- |
| 144 |
## the derivative function |
| 145 |
##----------------------------- |
| 146 |
derivs <- function(t,y,parms) { |
| 147 |
if (t < 1) |
| 148 |
lag1 <- 0.1 |
| 149 |
else |
| 150 |
lag1 <- lagvalue(t - 1,2) |
| 151 |
if (t < 10) |
| 152 |
lag10 <- 0.1 |
| 153 |
else |
| 154 |
lag10 <- lagvalue(t - 10,2) |
| 155 |
|
| 156 |
dy1 <- -y[1] * lag1 + lag10 |
| 157 |
dy2 <- y[1] * lag1 - y[2] |
| 158 |
dy3 <- y[2] - lag10 |
| 159 |
list(c(dy1, dy2, dy3)) |
| 160 |
} |
| 161 |
|
| 162 |
##----------------------------- |
| 163 |
## initial values and times |
| 164 |
##----------------------------- |
| 165 |
yinit <- c(5, 0.1, 1) |
| 166 |
times <- seq(0, 40, by = 0.1) |
| 167 |
|
| 168 |
##----------------------------- |
| 169 |
## solve the model |
| 170 |
##----------------------------- |
| 171 |
system.time( |
| 172 |
yout <- dede(y = yinit, times = times, func = derivs, parms = NULL) |
| 173 |
) |
| 174 |
|
| 175 |
##----------------------------- |
| 176 |
## display, plot results |
| 177 |
##----------------------------- |
| 178 |
matplot(yout[,1], yout[,-1], type = "l", lwd = 2, lty = 1, |
| 179 |
main = "Infectuous disease - Hairer") |
| 180 |
|
| 181 |
## ============================================================================= |
| 182 |
## time lags + EVENTS triggered by a root function |
| 183 |
## The two-wheeled suitcase model |
| 184 |
## example 8 from Shampine and Thompson, 2000 |
| 185 |
## solving delay differential equations with dde23 |
| 186 |
## ============================================================================= |
| 187 |
|
| 188 |
##----------------------------- |
| 189 |
## the derivative function |
| 190 |
##----------------------------- |
| 191 |
derivs <- function(t, y, parms) { |
| 192 |
if (t < tau) |
| 193 |
lag <- 0 |
| 194 |
else |
| 195 |
lag <- lagvalue(t - tau) |
| 196 |
|
| 197 |
dy1 <- y[2] |
| 198 |
dy2 <- -sign(y[1]) * gam * cos(y[1]) + |
| 199 |
sin(y[1]) - bet * lag[1] + A * sin(omega * t + mu) |
| 200 |
list(c(dy1, dy2)) |
| 201 |
} |
| 202 |
|
| 203 |
## root and event function |
| 204 |
root <- function(t,y,parms) ifelse(t>0, return(y), return(1)) |
| 205 |
event <- function(t,y,parms) return(c(y[1], y[2]*0.931)) |
| 206 |
|
| 207 |
gam = 0.248; bet = 1; tau = 0.1; A = 0.75 |
| 208 |
omega = 1.37; mu = asin(gam/A) |
| 209 |
|
| 210 |
##----------------------------- |
| 211 |
## initial values and times |
| 212 |
##----------------------------- |
| 213 |
yinit <- c(y = 0, dy = 0) |
| 214 |
times <- seq(0, 12, len = 1000) |
| 215 |
|
| 216 |
##----------------------------- |
| 217 |
## solve the model |
| 218 |
##----------------------------- |
| 219 |
## Note: use a solver that supports both root finding and events, |
| 220 |
## e.g. lsodar, lsode, lsoda, adams, bdf |
| 221 |
yout <- dede(y = yinit, times = times, func = derivs, parms = NULL, |
| 222 |
method = "lsodar", rootfun = root, events = list(func = event, root = TRUE)) |
| 223 |
|
| 224 |
##----------------------------- |
| 225 |
## display, plot results |
| 226 |
##----------------------------- |
| 227 |
|
| 228 |
plot(yout, which = 1, type = "l", lwd = 2, main = "suitcase model", mfrow = c(1,2)) |
| 229 |
plot(yout[,2], yout[,3], xlab = "y", ylab = "dy", type = "l", lwd = 2) |
| 230 |
|
| 231 |
} |
| 232 |
|
| 233 |
\keyword{utilities} |