Debian Codegraph @

man/dede.Rd

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