Debian Codegraph @

man/ode.band.Rd

raw
1 \name{ode.band}
2 \alias{ode.band}
3 \title{Solver for Ordinary Differential Equations; Assumes a Banded
4 Jacobian
5 }
6 \description{
7 Solves a system of ordinary differential equations.
8
9 Assumes a banded Jacobian matrix, but does not rearrange the state
10 variables (in contrast to ode.1D). Suitable for 1-D models that
11 include transport only between adjacent layers and that model only one
12 species.
13 }
14
15 \usage{ode.band(y, times, func, parms, nspec = NULL, dimens = NULL,
16 bandup = nspec, banddown = nspec, method = "lsode", names = NULL,
17 ...)
18 }
19 \arguments{
20 \item{y }{the initial (state) values for the ODE system, a vector. If
21 \code{y} has a name attribute, the names will be used to label the
22 output matrix.
23 }
24 \item{times }{time sequence for which output is wanted; the first
25 value of \code{times} must be the initial time.
26 }
27 \item{func }{either an \R-function that computes the values of the
28 derivatives in the ODE system (the model definition) at time
29 \code{t}, or a character string giving the name of a compiled
30 function in a dynamically loaded shared library.
31
32 If \code{func} is an \R-function, it must be defined as:
33 \code{func <- function(t, y, parms, ...)}. \code{t} is the current time
34 point in the integration, \code{y} is the current estimate of the
35 variables in the ODE system. If the initial values \code{y} has a
36 \code{names} attribute, the names will be available inside \code{func}.
37 \code{parms} is a vector or list of parameters; \code{...} (optional) are
38 any other arguments passed to the function.
39
40 The return value of \code{func} should be a list, whose first
41 element is a vector containing the derivatives of \code{y} with
42 respect to \code{time}, and whose next elements are global values
43 that are required at each point in \code{times}.The derivatives
44 must be specified in the \bold{same order} as the state variables \code{y}.
45
46 }
47 \item{parms }{parameters passed to \code{func}.
48 }
49 \item{nspec }{the number of *species* (components) in the model.
50 }
51 \item{dimens}{the number of \bold{boxes} in the model. If \code{NULL}, then
52 \code{nspec} should be specified.
53 }
54 \item{bandup }{the number of nonzero bands above the Jacobian
55 diagonal.
56 }
57 \item{banddown }{the number of nonzero bands below the Jacobian
58 diagonal.
59 }
60 \item{method }{the integrator to use, one of \code{"vode"},
61 \code{"lsode"}, \code{"lsoda"}, \code{"lsodar"}, \code{"radau"}.
62 }
63 \item{names }{the names of the components; used for plotting.
64 }
65 \item{... }{additional arguments passed to the integrator.}
66 }
67 \value{
68 A matrix of class \code{deSolve} with up to as many rows as elements in \code{times} and as
69 many columns as elements in \code{y} plus the number of "global"
70 values returned in the second element of the return from \code{func},
71 plus an additional column (the first) for the time value. There will
72 be one row for each element in \code{times} unless the integrator
73 returns with an unrecoverable error. If \code{y} has a names
74 attribute, it will be used to label the columns of the output value.
75
76 The output will have the attributes \code{istate} and \code{rstate},
77 two vectors with several elements. See the help for the selected
78 integrator for details. the first element of istate returns the
79 conditions under which the last call to the integrator returned. Normal is
80 \code{istate = 2}. If \code{verbose = TRUE}, the settings of
81 \code{istate} and \code{rstate} will be written to the screen.
82 }
83 \author{Karline Soetaert <[email protected]>}
84 \examples{
85
86 ## =======================================================================
87 ## The Aphid model from Soetaert and Herman, 2009.
88 ## A practical guide to ecological modelling.
89 ## Using R as a simulation platform. Springer.
90 ## =======================================================================
91
92 ## 1-D diffusion model
93
94 ## ================
95 ## Model equations
96 ## ================
97 Aphid <- function(t, APHIDS, parameters) {
98 deltax <- c (0.5*delx, rep(delx, numboxes-1), 0.5*delx)
99 Flux <- -D*diff(c(0, APHIDS, 0))/deltax
100 dAPHIDS <- -diff(Flux)/delx + APHIDS*r
101
102 list(dAPHIDS) # the output
103 }
104
105 ## ==================
106 ## Model application
107 ## ==================
108
109 ## the model parameters:
110 D <- 0.3 # m2/day diffusion rate
111 r <- 0.01 # /day net growth rate
112 delx <- 1 # m thickness of boxes
113 numboxes <- 60
114
115 ## distance of boxes on plant, m, 1 m intervals
116 Distance <- seq(from = 0.5, by = delx, length.out = numboxes)
117
118 ## Initial conditions, ind/m2
119 ## aphids present only on two central boxes
120 APHIDS <- rep(0, times = numboxes)
121 APHIDS[30:31] <- 1
122 state <- c(APHIDS = APHIDS) # initialise state variables
123
124 ## RUNNING the model:
125 times <- seq(0, 200, by = 1) # output wanted at these time intervals
126 out <- ode.band(state, times, Aphid, parms = 0,
127 nspec = 1, names = "Aphid")
128
129 ## ================
130 ## Plotting output
131 ## ================
132 image(out, grid = Distance, method = "filled.contour",
133 xlab = "time, days", ylab = "Distance on plant, m",
134 main = "Aphid density on a row of plants")
135
136 matplot.1D(out, grid = Distance, type = "l",
137 subset = time \%in\% seq(0, 200, by = 10))
138
139 # add an observed dataset to 1-D plot (make sure to use correct name):
140 data <- cbind(dist = c(0,10, 20, 30, 40, 50, 60),
141 Aphid = c(0,0.1,0.25,0.5,0.25,0.1,0))
142
143 matplot.1D(out, grid = Distance, type = "l",
144 subset = time \%in\% seq(0, 200, by = 10),
145 obs = data, obspar = list(pch = 18, cex = 2, col="red"))
146 \dontrun{
147 plot.1D(out, grid = Distance, type = "l")
148
149 }
150 }
151 \details{
152 This is the method of choice for single-species 1-D reactive transport
153 models.
154
155 For multi-species 1-D models, this method can only be used if the
156 state variables are arranged per box, per species (e.g. A[1], B[1],
157 A[2], B[2], A[3], B[3], ... for species A, B). By default, the
158 \bold{model} function will have the species arranged as A[1], A[2],
159 A[3], ... B[1], B[2], B[3], ... in this case, use \code{ode.1D}.
160
161 See the selected integrator for the additional options.
162 }
163 \seealso{
164 \itemize{
165 \item \code{\link{ode}} for a general interface to most of the ODE solvers,
166 \item \code{\link{ode.1D}} for integrating 1-D models
167 \item \code{\link{ode.2D}} for integrating 2-D models
168 \item \code{\link{ode.3D}} for integrating 3-D models
169 \item \code{\link{lsode}}, \code{\link{lsoda}}, \code{\link{lsodar}},
170 \code{\link{vode}} for the integration options.
171 }
172 \code{\link{diagnostics}} to print diagnostic messages.
173 }
174 \keyword{math}
175