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