Debian Codegraph @

man/zvode.Rd

raw
1 \name{zvode}
2 \alias{zvode}
3
4 \title{Solver for Ordinary Differential Equations (ODE) for COMPLEX variables}
5
6 \description{
7 Solves the initial value problem for stiff or nonstiff systems of
8 ordinary differential equations (ODE) in the form:
9
10 \deqn{dy/dt = f(t,y)}
11
12 where \eqn{dy} and \eqn{y} are complex variables.
13
14 The \R function \code{zvode} provides an interface to the FORTRAN ODE
15 solver of the same name, written by Peter N. Brown, Alan C. Hindmarsh
16 and George D. Byrne.
17
18 }
19
20 \usage{zvode(y, times, func, parms, rtol = 1e-6, atol = 1e-6,
21 jacfunc = NULL, jactype = "fullint", mf = NULL, verbose = FALSE,
22 tcrit = NULL, hmin = 0, hmax = NULL, hini = 0, ynames = TRUE,
23 maxord = NULL, bandup = NULL, banddown = NULL, maxsteps = 5000,
24 dllname = NULL, initfunc = dllname, initpar = parms, rpar = NULL,
25 ipar = NULL, nout = 0, outnames = NULL, forcings = NULL,
26 initforc = NULL, fcontrol = NULL, ...)
27 }
28 \arguments{
29 \item{y }{the initial (state) values for the ODE system. If \code{y}
30 has a name attribute, the names will be used to label the output
31 matrix. \emph{y has to be complex}
32 }
33 \item{times }{time sequence for which output is wanted; the first
34 value of \code{times} must be the initial time; if only one step is
35 to be taken; set \code{times = NULL}.
36 }
37 \item{func }{either an \R-function that computes the values of the
38 derivatives in the ODE system (the \emph{model definition}) at time
39 \code{t}, or a character string giving the name of a compiled function in a
40 dynamically loaded shared library.
41
42 If \code{func} is an \R-function, it must be defined as:
43 \code{func <- function(t, y, parms, ...)}. \code{t} is the current time
44 point in the integration, \code{y} is the current estimate of the
45 variables in the ODE system. If the initial values \code{y} has a
46 \code{names} attribute, the names will be available inside \code{func}.
47 \code{parms} is a vector or list of parameters; ... (optional) are
48 any other arguments passed to the function.
49
50 The return value of \code{func} should be a list, whose first
51 element is a vector containing the derivatives of \code{y} with
52 respect to \code{time}, and whose next elements are global values
53 that are required at each point in \code{times}. The derivatives
54 must be specified in the \bold{same order} as the state variables \code{y}.
55 They should be \emph{complex numbers}.
56
57 If \code{func} is
58 a string, then \code{dllname} must give the name of the shared
59 library (without extension) which must be loaded before
60 \code{zvode()} is called. See package vignette \code{"compiledCode"}
61 for more details.
62 }
63 \item{parms }{vector or list of parameters used in \code{func} or
64 \code{jacfunc}.
65 }
66 \item{rtol }{relative error tolerance, either a scalar or an array as
67 long as \code{y}. See details.
68 }
69 \item{atol }{absolute error tolerance, either a scalar or an array as
70 long as \code{y}. See details.
71 }
72 \item{jacfunc }{if not \code{NULL}, an \R function that computes the
73 Jacobian of the system of differential equations
74 \eqn{\partial\dot{y}_i/\partial y_j}{dydot(i)/dy(j)}, or
75 a string giving the name of a function or subroutine in
76 \file{dllname} that computes the Jacobian (see vignette
77 \code{"compiledCode"} for more about this option).
78
79 In some circumstances, supplying
80 \code{jacfunc} can speed up the computations, if the system is
81 stiff. The \R calling sequence for \code{jacfunc} is identical to
82 that of \code{func}.
83
84 If the Jacobian is a full matrix, \code{jacfunc} should return a
85 matrix \eqn{\dot{dy}/dy}{dydot/dy}, where the ith row contains the derivative of
86 \eqn{dy_i/dt} with respect to \eqn{y_j}, or a vector containing the
87 matrix elements by columns (the way \R and FORTRAN store matrices).
88 Its elements should be \emph{complex numbers}.
89
90 If the Jacobian is banded, \code{jacfunc} should return a matrix
91 containing only the nonzero bands of the Jacobian, rotated
92 row-wise. See first example of \code{lsode}.
93 }
94 \item{jactype }{the structure of the Jacobian, one of
95 \code{"fullint"}, \code{"fullusr"}, \code{"bandusr"} or
96 \code{"bandint"} - either full or banded and estimated internally or
97 by user; overruled if \code{mf} is not \code{NULL}.
98 }
99 \item{mf }{the "method flag" passed to function \code{zvode} - overrules
100 \code{jactype} - provides more options than \code{jactype} - see
101 details.
102 }
103 \item{verbose }{if TRUE: full output to the screen, e.g. will
104 print the \code{diagnostiscs} of the integration - see details.
105 }
106 \item{tcrit }{if not \code{NULL}, then \code{zvode} cannot integrate
107 past \code{tcrit}. The FORTRAN routine \code{dvode} overshoots its
108 targets (times points in the vector \code{times}), and interpolates
109 values for the desired time points. If there is a time beyond which
110 integration should not proceed (perhaps because of a singularity),
111 that should be provided in \code{tcrit}.
112 }
113 \item{hmin }{an optional minimum value of the integration stepsize. In
114 special situations this parameter may speed up computations with the
115 cost of precision. Don't use hmin if you don't know why!
116 }
117 \item{hmax }{an optional maximum value of the integration stepsize. If
118 not specified, hmax is set to the largest difference in
119 \code{times}, to avoid that the simulation possibly ignores
120 short-term events. If 0, no maximal size is specified.
121 }
122 \item{hini }{initial step size to be attempted; if 0, the initial step
123 size is determined by the solver.
124 }
125 \item{ynames }{logical; if \code{FALSE}: names of state variables are not
126 passed to function \code{func} ; this may speed up the simulation
127 especially for multi-D models.
128 }
129 \item{maxord }{the maximum order to be allowed. \code{NULL} uses the default,
130 i.e. order 12 if implicit Adams method (\code{meth = 1}), order 5 if BDF
131 method (\code{meth = 2}). Reduce maxord to save storage space.
132 }
133 \item{bandup }{number of non-zero bands above the diagonal, in case
134 the Jacobian is banded.
135 }
136 \item{banddown }{number of non-zero bands below the diagonal, in case
137 the Jacobian is banded.
138 }
139 \item{maxsteps }{maximal number of steps per output interval taken by the
140 solver.
141 }
142 \item{dllname }{a string giving the name of the shared library
143 (without extension) that contains all the compiled function or
144 subroutine definitions refered to in \code{func} and \code{jacfunc}.
145 See package vignette \code{"compiledCode"}.
146 }
147 \item{initfunc }{if not \code{NULL}, the name of the initialisation function
148 (which initialises values of parameters), as provided in
149 \file{dllname}. See package vignette \code{"compiledCode"}.
150 }
151 \item{initpar }{only when \file{dllname} is specified and an
152 initialisation function \code{initfunc} is in the dll: the
153 parameters passed to the initialiser, to initialise the common
154 blocks (FORTRAN) or global variables (C, C++).
155 }
156 \item{rpar }{only when \file{dllname} is specified: a vector with
157 double precision values passed to the DLL-functions whose names are
158 specified by \code{func} and \code{jacfunc}.
159 }
160 \item{ipar }{only when \file{dllname} is specified: a vector with
161 integer values passed to the dll-functions whose names are specified
162 by \code{func} and \code{jacfunc}.
163 }
164 \item{nout }{only used if \code{dllname} is specified and the model is
165 defined in compiled code: the number of output variables calculated
166 in the compiled function \code{func}, present in the shared
167 library. Note: it is not automatically checked whether this is
168 indeed the number of output variables calculated in the DLL - you have
169 to perform this check in the code - See package vignette \code{"compiledCode"}.
170 }
171 \item{outnames }{only used if \file{dllname} is specified and
172 \code{nout} > 0: the names of output variables calculated in the
173 compiled function \code{func}, present in the shared library.
174 These names will be used to label the output matrix.
175 }
176 \item{forcings }{only used if \file{dllname} is specified: a list with
177 the forcing function data sets, each present as a two-columned matrix,
178 with (time,value); interpolation outside the interval
179 [min(\code{times}), max(\code{times})] is done by taking the value at
180 the closest data extreme.
181
182 See \link{forcings} or package vignette \code{"compiledCode"}.
183 }
184 \item{initforc }{if not \code{NULL}, the name of the forcing function
185 initialisation function, as provided in
186 \file{dllname}. It MUST be present if \code{forcings} has been given a
187 value.
188 See \link{forcings} or package vignette \code{"compiledCode"}.
189 }
190 \item{fcontrol }{A list of control parameters for the forcing functions.
191 \link{forcings} or package vignette \code{"compiledCode"}
192 }
193 \item{... }{additional arguments passed to \code{func} and
194 \code{jacfunc} allowing this to be a generic function.
195 }
196 }
197 \value{
198 A matrix of class \code{deSolve} with up to as many rows as elements
199 in \code{times} and as many columns as elements in \code{y} plus the
200 number of "global" values returned in the next elements of the return
201 from \code{func},
202 plus and additional column for the time value. There will be a row
203 for each element in \code{times} unless the FORTRAN routine `zvode'
204 returns with an unrecoverable error. If \code{y} has a names
205 attribute, it will be used to label the columns of the output value.
206 }
207 \author{Karline Soetaert <[email protected]>}
208 \examples{
209
210 ## =======================================================================
211 ## Example 1 - very simple example
212 ## df/dt = 1i*f, where 1i is the imaginary unit
213 ## The initial value is f(0) = 1 = 1+0i
214 ## =======================================================================
215
216 ZODE <- function(Time, f, Pars) {
217 df <- 1i*f
218 return(list(df))
219 }
220
221 pars <- NULL
222 yini <- c(f = 1+0i)
223 times <- seq(0, 2*pi, length = 100)
224 out <- zvode(func = ZODE, y = yini, parms = pars, times = times,
225 atol = 1e-10, rtol = 1e-10)
226
227 # The analytical solution to this ODE is the exp-function:
228 # f(t) = exp(1i*t)
229 # = cos(t)+1i*sin(t) (due to Euler's equation)
230
231 analytical.solution <- exp(1i * times)
232
233 ## compare numerical and analytical solution
234 tail(cbind(out[,2], analytical.solution))
235
236
237 ## =======================================================================
238 ## Example 2 - example in "zvode.f",
239 ## df/dt = 1i*f (same as above ODE)
240 ## dg/dt = -1i*g*g*f (an additional ODE depending on f)
241 ##
242 ## Initial values are
243 ## g(0) = 1/2.1 and
244 ## z(0) = 1
245 ## =======================================================================
246
247 ZODE2<-function(Time,State,Pars) {
248 with(as.list(State), {
249 df <- 1i * f
250 dg <- -1i * g*g * f
251 return(list(c(df, dg)))
252 })
253 }
254
255 yini <- c(f = 1 + 0i, g = 1/2.1 + 0i)
256 times <- seq(0, 2*pi, length = 100)
257 out <- zvode(func = ZODE2, y = yini, parms = NULL, times = times,
258 atol = 1e-10, rtol = 1e-10)
259
260
261 ## The analytical solution is
262 ## f(t) = exp(1i*t) (same as above)
263 ## g(t) = 1/(f(t) + 1.1)
264
265 analytical <- cbind(f = exp(1i * times), g = 1/(exp(1i * times) + 1.1))
266
267 ## compare numerical solution and the two analytical ones:
268 tail(cbind(out[,2], analytical[,1]))
269
270 }
271 \references{
272
273 P. N. Brown, G. D. Byrne, and A. C. Hindmarsh, 1989. VODE: A Variable
274 Coefficient ODE Solver, SIAM J. Sci. Stat. Comput., 10, pp. 1038-1051.
275 \cr Also, LLNL Report UCRL-98412, June 1988.
276 \doi{10.1137/0910062}
277
278 G. D. Byrne and A. C. Hindmarsh, 1975. A Polyalgorithm for the
279 Numerical Solution of Ordinary Differential Equations. ACM
280 Trans. Math. Software, 1, pp. 71-96.
281 \doi{10.1145/355626.355636}
282
283 A. C. Hindmarsh and G. D. Byrne, 1977. EPISODE: An Effective Package
284 for the Integration of Systems of Ordinary Differential
285 Equations. LLNL Report UCID-30112, Rev. 1.
286
287 G. D. Byrne and A. C. Hindmarsh, 1976. EPISODEB: An Experimental
288 Package for the Integration of Systems of Ordinary Differential
289 Equations with Banded Jacobians. LLNL Report UCID-30132, April 1976.
290
291 A. C. Hindmarsh, 1983. ODEPACK, a Systematized Collection of ODE
292 Solvers. in Scientific Computing, R. S. Stepleman et al., eds.,
293 North-Holland, Amsterdam, pp. 55-64.
294
295 K. R. Jackson and R. Sacks-Davis, 1980. An Alternative Implementation
296 of Variable Step-Size Multistep Formulas for Stiff ODEs. ACM
297 Trans. Math. Software, 6, pp. 295-318.
298 \doi{10.1145/355900.355903}
299
300 Netlib: \url{https://netlib.org}
301 }
302 \details{
303 see \code{\link{vode}}, the double precision version, for details.
304 }
305 \note{
306 From version 1.10.4, the default of atol was changed from 1e-8 to 1e-6,
307 to be consistent with the other solvers.
308
309 The following text is adapted from the zvode.f source code:
310
311 When using \code{zvode} for a stiff system, it should only be used for
312 the case in which the function f is analytic, that is, when each f(i)
313 is an analytic function of each y(j). Analyticity means that the
314 partial derivative df(i)/dy(j) is a unique complex number, and this
315 fact is critical in the way \code{zvode} solves the dense or banded linear
316 systems that arise in the stiff case. For a complex stiff ODE system
317 in which f is not analytic, \code{zvode} is likely to have convergence
318 failures, and for this problem one should instead use \code{ode} on the
319 equivalent real system (in the real and imaginary parts of y).
320 }
321
322 \seealso{
323 \code{\link{vode}} for the double precision version
324 }
325
326 \keyword{math}
327