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