Debian Codegraph @

man/ode.3D.Rd

raw
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