Debian Codegraph @

man/events.Rd

raw
1 \name{events}
2 \alias{events}
3 \alias{roots}
4 \title{
5 Implementing Events and Roots in Differential Equation Models.
6 }
7 \description{
8 An \code{event} occurs when the value of a state variable is suddenly
9 changed, e.g. because a value is added, subtracted, or multiplied. The
10 integration routines cannot deal easily with such state variable
11 changes. Typically these events occur only at specific times. In
12 \code{deSolve}, events can be imposed by means of an input data.frame,
13 that specifies at which time and how a certain state variable is altered,
14 or via an event function.
15
16 Roots occur when a root function becomes zero. By default when a root is
17 found, the simulation either stops (no event), or triggers an event.
18 }
19 \details{
20
21 The \code{events} are specified by means of argument \code{events}
22 passed to the integration routines.
23
24 \code{events} should be a list that contains one of the following:
25
26 \describe{
27 \item{func: }{an R-function or the name of a function in compiled
28 code that specifies the event,
29 }
30 \item{data: }{a data.frame that specifies the state variables, times, values and
31 types of the events. Note that the event times must also
32 be part of the integration output times, else the event will not take
33 place. As from version 1.9.1, this is checked by the solver,
34 and a warning message is produced if event times are missing in times;
35 see also \code{\link{cleanEventTimes}} for utility functions
36 to check and solve such issues.
37 }
38 \item{time: }{when events are specified by an event function: the times at
39 which the events take place. Note that these event times must also
40 be part of the integration output times exactly, else the event
41 would not take place. As from version 1.9.1 this is checked by the solver,
42 and an error message produced if event times are missing in times;
43 see also \code{\link{cleanEventTimes}} for utility functions
44 to check and solve such issues.
45 }
46 \item{root: }{when events are specified by a function and triggered
47 by a root, this logical should be set equal to \code{TRUE}
48 }
49 \item{terminalroot: }{when events are triggered by a root, the default is
50 that the simulation continues after the event is executed. In
51 \code{terminalroot}, we can specify which roots should terminate the
52 simulation.
53 }
54 \item{maxroot: }{when \code{root = TRUE}, the maximal number of
55 times at with a root is found and that are kept; defaults to 100. If
56 the number of roots > \code{maxroot}, then only the first
57 \code{maxroot} will be outputted.
58 }
59 \item{ties: }{if events, as specified by a data.frame are "ordered",
60 set to "ordered", the default is "notordered". This will save
61 some computational time.
62 }
63 }
64
65 In case the events are specified by means of an \R \bold{function}
66 (argument \code{events$func}),
67 it must be defined as: \code{function(t, y, parms, ...)}.
68 \code{t} is the current time point in the integration,
69 \code{y} is the current estimate of the variables in the ODE system.
70 If the initial values \code{y} has a \code{names} attribute, the
71 names will be available inside \code{events$func}. \code{parms} is a
72 vector or list of parameters; \code{...} (optional) are any other
73 arguments passed to the function via the call to the integration method.
74 The event function should return the y-values (some of which modified),
75 as a \emph{vector}.
76
77 If \code{events$func} is a string, this indicates that the events are
78 specified by a \code{function} in compiled code. This function has as
79 arguments, the number of state variables, the time, and the state
80 variable vector. See package vignette "compiledCode" for more details.
81
82 In case events are specified by an \R-function,
83 this requires either: input of the \emph{time} of the events, a vector as
84 defined in \code{events$time}
85 OR the specification of a \emph{root} function. In the
86 latter case, the model must be solved with an integration routine
87 with root-finding capability
88
89 The root function itself should be specified with argument \code{rootfunc}.
90 In this case, the integrator is informed that the simulation it to be
91 continued after a root is found by
92 setting \code{events$root} equal to \code{TRUE}.
93
94
95 If the events are specified by a \bold{data frame}
96 (argument \code{events$data}), this should
97 contain the following columns (and in that order):
98 \describe{
99 \item{var: }{the state variable \emph{name} or \emph{number} that is affected
100 by the event}
101 \item{time: }{the time at which the event is to take place; the solvers will
102 check if the time is embraced by the simulation time}
103 \item{value: }{the value, magnitude of the event}
104 \item{method: }{which event is to take place; should be one of ("replace",
105 "add", "multiply"); also allowed is to specify the number
106 (1 = replace, 2 = add, 3 = multiply)
107 }
108 }
109
110 For instance, the following line
111
112 \code{"v1" 10 2 "add"}
113
114 will cause the value 2 to be added to a state variable, called \code{"v1"} at
115 \code{time = 10}.
116
117
118 From deSolve version 1.9.1 the following routines have \bold{root-finding} capability:
119 \link{lsoda}, \link{lsode}, \link{lsodes}, and \link{radau}.
120 For the first 3 integration methods, the
121 root finding algorithm is based on the algorithm in solver LSODAR, and is
122 implemented in FORTRAN. For radau, the root solving algorithm is written
123 in C-code, and it works slightly different. Thus, some problems involving roots
124 may be more efficiently solved with either lsoda, lsode, or lsodes, while other
125 problems are more efficiently solved with radau.
126
127 If a root function is defined, but not an event function, then by default the
128 solver will stop at a root. If this is not desirable, e.g. because we want
129 to record the position of many roots, then a dummy "event" function can be
130 defined which returns the values of the state variables - unaltered.
131
132 If roots and events are combined, and roots are found, then the output will have attribute
133 \code{troot} which will contain the \code{times} at which a root was found (and
134 the event trigerred).
135 There will be at most \code{events$maxroot} such values. The default is 100.
136
137 See two last examples; also see example of \code{\link{ccl4model}}.
138 }
139 \author{
140 Karline Soetaert
141 }
142 \seealso{
143 \link{forcings}, for how to implement forcing functions.
144
145 \link{lsodar}, for more examples of roots
146 }
147 \examples{
148 ## =============================================================================
149 ## 1. EVENTS in a data.frame
150 ## =============================================================================
151
152 ## derivative function: derivatives set to 0
153 derivs <- function(t, var, parms) {
154 list(dvar = rep(0, 2))
155 }
156
157 yini <- c(v1 = 1, v2 = 2)
158 times <- seq(0, 10, by = 0.1)
159
160 eventdat <- data.frame(var = c("v1", "v2", "v2", "v1"),
161 time = c(1, 1, 5, 9) ,
162 value = c(1, 2, 3, 4),
163 method = c("add", "mult", "rep", "add"))
164 eventdat
165
166 out <- vode(func = derivs, y = yini, times = times, parms = NULL,
167 events = list(data = eventdat))
168 plot(out)
169
170 ##
171 eventdat <- data.frame(var = c(rep("v1", 10), rep("v2", 10)),
172 time = c(1:10, 1:10),
173 value = runif(20),
174 method = rep("add", 20))
175 eventdat
176
177 out <- ode(func = derivs, y = yini, times = times, parms = NULL,
178 events = list(data = eventdat))
179
180 plot(out)
181
182 ## =============================================================================
183 ## 2. EVENTS in a function
184 ## =============================================================================
185
186 ## derivative function: rate of change v1 = 0, v2 reduced at first-order rate
187 derivs <- function(t, var, parms) {
188 list(c(0, -0.5 * var[2]))
189 }
190
191
192 # events: add 1 to v1, multiply v2 with random number
193 eventfun <- function(t, y, parms){
194 with (as.list(y),{
195 v1 <- v1 + 1
196 v2 <- 5 * runif(1)
197 return(c(v1, v2))
198 })
199 }
200
201 yini <- c(v1 = 1, v2 = 2)
202 times <- seq(0, 10, by = 0.1)
203
204 out <- ode(func = derivs, y = yini, times = times, parms = NULL,
205 events = list(func = eventfun, time = c(1:9, 2.2, 2.4)) )
206 plot(out, type = "l")
207
208 ## =============================================================================
209 ## 3. EVENTS triggered by a root function
210 ## =============================================================================
211
212 ## derivative: simple first-order decay
213 derivs <- function(t, y, pars) {
214 return(list(-0.1 * y))
215 }
216
217 ## event triggered if state variable = 0.5
218 rootfun <- function (t, y, pars) {
219 return(y - 0.5)
220 }
221
222 ## sets state variable = 1
223 eventfun <- function(t, y, pars) {
224 return(y = 1)
225 }
226
227 yini <- 2
228 times <- seq(0, 100, 0.1)
229
230 ## uses ode to solve; root = TRUE specifies that the event is
231 ## triggered by a root.
232 out <- ode(times = times, y = yini, func = derivs, parms = NULL,
233 events = list(func = eventfun, root = TRUE),
234 rootfun = rootfun)
235
236 plot(out, type = "l")
237
238 ## time of the root:
239 troot <- attributes(out)$troot
240 points(troot, rep(0.5, length(troot)))
241
242
243 ## =============================================================================
244 ## 4. More ROOT examples: Rotation function
245 ## =============================================================================
246 Rotate <- function(t, x, p )
247 list(c( x[2],
248 -x[1] ))
249
250 ## Root = when second state variable = 0
251 rootfun <- function(t, x, p) x[2]
252
253 ## "event" returns state variables unchanged
254 eventfun <- function(t, x, p) x
255 times <- seq(from = 0, to = 15, by = 0.1)
256
257 ## 1. No event: stops at first root
258 out1 <- ode(func = Rotate, y = c(5, 5), parms = 0,
259 times = times, rootfun = rootfun)
260 tail(out1)
261
262 ## 2. Continues till end of times and records the roots
263 out <- ode(func = Rotate, y = c(5, 5), parms = 0,
264 times = times, rootfun = rootfun,
265 events = list(func = eventfun, root = TRUE) )
266
267 plot(out)
268 troot <- attributes(out)$troot # time of roots
269 points(troot,rep(0, length (troot)))
270
271 ## Multiple roots: either one of the state variables = 0
272 root2 <- function(t, x, p) x
273
274 out2 <- ode(func = Rotate, y = c(5, 5), parms = 0,
275 times = times, rootfun = root2,
276 events = list(func = eventfun, root = TRUE) )
277
278 plot(out2, which = 2)
279 troot <- attributes(out2)$troot
280 indroot <- attributes(out2)$indroot # which root was found
281 points(troot, rep(0, length (troot)), col = indroot, pch = 18, cex = 2)
282
283 ## Multiple roots and stop at first time root 1.
284 out3 <- ode(func = Rotate, y = c(5, 5), parms = 0,
285 times = times, rootfun = root2,
286 events = list(func = eventfun, root = TRUE, terminalroot = 1))
287
288
289 ## =============================================================================
290 ## 5. Stop at 5th root - only works with radau.
291 ## =============================================================================
292 Rotate <- function(t, x, p )
293 list(c( x[2],
294 -x[1],
295 0 ))
296
297 ## Root = when second state variable = 0
298 root3 <- function(t, x, p) c(x[2], x[3] - 5)
299 event3 <- function (t, x, p) c(x[1:2], x[3]+1)
300 times <- seq(0, 15, 0.1)
301 out3 <- ode(func = Rotate, y = c(x1 = 5, x2 = 5, nroot = 0),
302 parms = 0, method = "radau",
303 times = times, rootfun = root3,
304 events = list(func = event3, root = TRUE, terminalroot = 2))
305 plot(out3)
306 attributes(out3)[c("troot", "nroot", "indroot")]
307
308 ## =============================================================================
309 ## 6 Event in R-code, model function in compiled code - based on vode example
310 ## =============================================================================
311
312 times <- 1:365
313 Flux <- cbind(times, sin(pi*times/365)^2) # forcing function
314
315 # run without events
316 out <- ode(y = c(C = 1), times, func = "scocder", parms = c(k=0.01),
317 dllname = "deSolve", initforc = "scocforc", forcings = Flux,
318 initfunc = "scocpar", nout = 2, outnames = c("Mineralisation", "Depo"))
319
320 # Event halves the concentration
321 EventMin <- function(t, y , p) y/2
322
323 out2 <- ode(y = c(C = 1), times, func = "scocder", parms = c(k=0.01),
324 dllname = "deSolve", initforc = "scocforc", forcings = Flux,
325 initfunc = "scocpar", nout = 2, outnames = c("Mineralisation", "Depo"),
326 events = list (func = EventMin, time = c(50.1, 200, 210.5)))
327
328 plot(out, out2)
329
330
331 }
332
333 \keyword{utilities}