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