| 1 |
\name{ode.3D} |
| 2 |
\alias{ode.3D} |
| 3 |
|
| 4 |
\title{Solver for 3-Dimensional Ordinary Differential Equations} |
| 5 |
|
| 6 |
\description{ |
| 7 |
Solves a system of ordinary differential equations resulting from |
| 8 |
3-Dimensional partial differential equations |
| 9 |
that have been converted to ODEs by numerical differencing. |
| 10 |
} |
| 11 |
|
| 12 |
\usage{ode.3D(y, times, func, parms, nspec = NULL, dimens, |
| 13 |
method = c("lsodes", "euler", "rk4", "ode23", "ode45", "adams", "iteration"), |
| 14 |
names = NULL, cyclicBnd = NULL, ...)} |
| 15 |
\arguments{ |
| 16 |
\item{y }{the initial (state) values for the ODE system, a vector. If |
| 17 |
\code{y} has a name attribute, the names will be used to label the |
| 18 |
output matrix. |
| 19 |
} |
| 20 |
\item{times }{time sequence for which output is wanted; the first |
| 21 |
value of \code{times} must be the initial time. |
| 22 |
} |
| 23 |
\item{func }{either an \R-function that computes the values of the |
| 24 |
derivatives in the ODE system (the model definition) at time |
| 25 |
\code{t}, or a character string giving the name of a compiled |
| 26 |
function in a dynamically loaded shared library. |
| 27 |
|
| 28 |
If \code{func} is an \R-function, it must be defined as: |
| 29 |
\code{func <- function(t, y, parms, ...)}. \code{t} is the current time |
| 30 |
point in the integration, \code{y} is the current estimate of the |
| 31 |
variables in the ODE system. If the initial values \code{y} has a |
| 32 |
\code{names} attribute, the names will be available inside \code{func}. |
| 33 |
\code{parms} is a vector or list of parameters; \code{...} (optional) are |
| 34 |
any other arguments passed to the function. |
| 35 |
|
| 36 |
The return value of \code{func} should be a list, whose first |
| 37 |
element is a vector containing the derivatives of \code{y} with |
| 38 |
respect to \code{time}, and whose next elements are global values |
| 39 |
that are required at each point in \code{times}. The derivatives |
| 40 |
must be specified in the \bold{same order} as the state variables \code{y}. |
| 41 |
|
| 42 |
} |
| 43 |
\item{parms }{parameters passed to \code{func}.} |
| 44 |
\item{nspec }{the number of \bold{species} (components) in the model.} |
| 45 |
\item{dimens}{3-valued vector with the number of \bold{boxes} in three |
| 46 |
dimensions in the model. |
| 47 |
} |
| 48 |
\item{names }{the names of the components; used for plotting. |
| 49 |
} |
| 50 |
\item{cyclicBnd }{if not \code{NULL} then a number or a 3-valued vector |
| 51 |
with the dimensions where a cyclic boundary is used - \code{1}: x-dimension, |
| 52 |
\code{2}: y-dimension; \code{3}: z-dimension. |
| 53 |
} |
| 54 |
\item{method }{the integrator. Use \code{"lsodes"} if the model is very stiff; |
| 55 |
"impAdams" may be best suited for mildly stiff problems; |
| 56 |
\code{"euler", "rk4", "ode23", "ode45", "adams"} are most |
| 57 |
efficient for non-stiff problems. Also allowed is to pass an integrator |
| 58 |
\code{function}. Use one of the other Runge-Kutta methods via |
| 59 |
\code{rkMethod}. For instance, \code{method = rkMethod("ode45ck")} will |
| 60 |
trigger the Cash-Karp method of order 4(5). |
| 61 |
|
| 62 |
Method \code{"iteration"} is special in that here the function \code{func} should |
| 63 |
return the new value of the state variables rather than the rate of change. |
| 64 |
This can be used for individual based models, for difference equations, |
| 65 |
or in those cases where the integration is performed within \code{func}) |
| 66 |
|
| 67 |
} |
| 68 |
\item{... }{additional arguments passed to \code{lsodes}.} |
| 69 |
} |
| 70 |
\value{ |
| 71 |
|
| 72 |
A matrix of class \code{deSolve} with up to as many rows as elements in times and as many |
| 73 |
columns as elements in \code{y} plus the number of "global" values |
| 74 |
returned in the second element of the return from \code{func}, plus an |
| 75 |
additional column (the first) for the time value. There will be one |
| 76 |
row for each element in \code{times} unless the integrator returns |
| 77 |
with an unrecoverable error. If \code{y} has a names attribute, it |
| 78 |
will be used to label the columns of the output value. |
| 79 |
|
| 80 |
The output will have the attributes \code{istate}, and \code{rstate}, |
| 81 |
two vectors with several useful elements. The first element of istate |
| 82 |
returns the conditions under which the last call to the integrator |
| 83 |
returned. Normal is \code{istate = 2}. If \code{verbose = TRUE}, the |
| 84 |
settings of istate and rstate will be written to the screen. See the |
| 85 |
help for the selected integrator for details. |
| 86 |
|
| 87 |
} |
| 88 |
\note{ |
| 89 |
It is advisable though not mandatory to specify \bold{both} |
| 90 |
\code{nspec} and \code{dimens}. In this case, the solver can check |
| 91 |
whether the input makes sense (as \code{nspec*dimens[1]*dimens[2]*dimens[3] |
| 92 |
== length(y)}). |
| 93 |
|
| 94 |
Do \bold{not} use this method for problems that are not 3D! |
| 95 |
} |
| 96 |
\author{Karline Soetaert <[email protected]>} |
| 97 |
\examples{ |
| 98 |
## ======================================================================= |
| 99 |
## Diffusion in 3-D; imposed boundary conditions |
| 100 |
## ======================================================================= |
| 101 |
diffusion3D <- function(t, Y, par) { |
| 102 |
|
| 103 |
## function to bind two matrices to an array |
| 104 |
mbind <- function (Mat1, Array, Mat2, along = 1) { |
| 105 |
dimens <- dim(Array) + c(0, 0, 2) |
| 106 |
if (along == 3) |
| 107 |
array(dim = dimens, data = c(Mat1, Array, Mat2)) |
| 108 |
else if (along == 1) |
| 109 |
aperm(array(dim = dimens, |
| 110 |
data=c(Mat1, aperm(Array, c(3, 2, 1)), Mat2)), c(3, 2, 1)) |
| 111 |
else if (along == 2) |
| 112 |
aperm(array(dim = dimens, |
| 113 |
data = c(Mat1, aperm(Array, c(1, 3, 2)), Mat2)), c(1, 3, 2)) |
| 114 |
} |
| 115 |
|
| 116 |
yy <- array(dim=c(n, n, n), data = Y) # vector to 3-D array |
| 117 |
dY <- -r*yy # consumption |
| 118 |
BND <- matrix(nrow = n, ncol = n, data = 1) # boundary concentration |
| 119 |
|
| 120 |
## diffusion in x-direction |
| 121 |
## new array including boundary concentrations in X-direction |
| 122 |
BNDx <- mbind(BND, yy, BND, along = 1) |
| 123 |
## diffusive Flux |
| 124 |
Flux <- -Dx * (BNDx[2:(n+2),,] - BNDx[1:(n+1),,])/dx |
| 125 |
## rate of change = - flux gradient |
| 126 |
dY[] <- dY[] - (Flux[2:(n+1),,] - Flux[1:n,,])/dx |
| 127 |
|
| 128 |
## diffusion in y-direction |
| 129 |
BNDy <- mbind(BND, yy, BND, along = 2) |
| 130 |
Flux <- -Dy * (BNDy[,2:(n+2),] - BNDy[,1:(n+1),])/dy |
| 131 |
dY[] <- dY[] - (Flux[,2:(n+1),] - Flux[,1:n,])/dy |
| 132 |
|
| 133 |
## diffusion in z-direction |
| 134 |
BNDz <- mbind(BND, yy, BND, along = 3) |
| 135 |
Flux <- -Dz * (BNDz[,,2:(n+2)] - BNDz[,,1:(n+1)])/dz |
| 136 |
dY[] <- dY[] - (Flux[,,2:(n+1)] - Flux[,,1:n])/dz |
| 137 |
|
| 138 |
return(list(as.vector(dY))) |
| 139 |
} |
| 140 |
|
| 141 |
## parameters |
| 142 |
dy <- dx <- dz <-1 # grid size |
| 143 |
Dy <- Dx <- Dz <-1 # diffusion coeff, X- and Y-direction |
| 144 |
r <- 0.025 # consumption rate |
| 145 |
|
| 146 |
n <- 10 |
| 147 |
y <- array(dim=c(n,n,n),data=10.) |
| 148 |
|
| 149 |
## use lsodes, the default (for n>20, Runge-Kutta more efficient) |
| 150 |
print(system.time( |
| 151 |
RES <- ode.3D(y, func = diffusion3D, parms = NULL, dimens = c(n, n, n), |
| 152 |
times = 1:20, lrw = 120000, atol = 1e-10, |
| 153 |
rtol = 1e-10, verbose = TRUE) |
| 154 |
)) |
| 155 |
|
| 156 |
y <- array(dim = c(n, n, n), data = RES[nrow(RES), -1]) |
| 157 |
filled.contour(y[, , n/2], color.palette = terrain.colors) |
| 158 |
|
| 159 |
summary(RES) |
| 160 |
|
| 161 |
\dontrun{ |
| 162 |
for (i in 2:nrow(RES)) { |
| 163 |
y <- array(dim=c(n,n,n),data=RES[i,-1]) |
| 164 |
filled.contour(y[,,n/2],main=i,color.palette=terrain.colors) |
| 165 |
} |
| 166 |
} |
| 167 |
} |
| 168 |
\details{ |
| 169 |
This is the method of choice for 3-dimensional models, that are only |
| 170 |
subjected to transport between adjacent layers. |
| 171 |
|
| 172 |
Based on the dimension of the problem, the method first calculates the |
| 173 |
sparsity pattern of the Jacobian, under the assumption that transport |
| 174 |
is only occurring between adjacent layers. Then \code{lsodes} is |
| 175 |
called to solve the problem. |
| 176 |
|
| 177 |
As \code{lsodes} is used to integrate, it will probably be necessary |
| 178 |
to specify the length of the real work array, \code{lrw}. |
| 179 |
|
| 180 |
Although a reasonable guess of \code{lrw} is made, it is likely that |
| 181 |
this will be too low. |
| 182 |
|
| 183 |
In this case, \code{ode.2D} will return with an |
| 184 |
error message telling the size of the work array actually needed. In |
| 185 |
the second try then, set \code{lrw} equal to this number. |
| 186 |
|
| 187 |
For instance, if you get the error: |
| 188 |
\preformatted{ |
| 189 |
DLSODES- RWORK length is insufficient to proceed. |
| 190 |
Length needed is .ge. LENRW (=I1), exceeds LRW (=I2) |
| 191 |
In above message, I1 = 27627 I2 = 25932 |
| 192 |
} |
| 193 |
set \code{lrw} equal to 27627 or a higher value. |
| 194 |
|
| 195 |
See \link{lsodes} for the additional options. |
| 196 |
} |
| 197 |
\seealso{ |
| 198 |
\itemize{ |
| 199 |
\item \code{\link{ode}} for a general interface to most of the ODE solvers, |
| 200 |
\item \code{\link{ode.band}} for integrating models with a banded Jacobian |
| 201 |
\item \code{\link{ode.1D}} for integrating 1-D models |
| 202 |
\item \code{\link{ode.2D}} for integrating 2-D models |
| 203 |
\item \code{\link{lsodes}} for the integration options. |
| 204 |
} |
| 205 |
\code{\link{diagnostics}} to print diagnostic messages. |
| 206 |
} |
| 207 |
\keyword{math} |
| 208 |
|