| 1 |
\name{DLLfunc} |
| 2 |
\alias{DLLfunc} |
| 3 |
\title{Evaluates a Derivative Function Represented in a DLL} |
| 4 |
\description{Calls a function, defined in a compiled language as a DLL} |
| 5 |
\usage{DLLfunc(func, times, y, parms, dllname, |
| 6 |
initfunc = dllname, rpar = NULL, ipar = NULL, nout = 0, |
| 7 |
outnames = NULL, forcings = NULL, initforc = NULL, |
| 8 |
fcontrol = NULL) |
| 9 |
|
| 10 |
} |
| 11 |
\arguments{ |
| 12 |
\item{func }{the name of the function in the dynamically loaded |
| 13 |
shared library, |
| 14 |
} |
| 15 |
\item{times }{first value = the time at which the function needs to be |
| 16 |
evaluated, |
| 17 |
} |
| 18 |
\item{y }{the values of the dependent variables for which the function |
| 19 |
needs to be evaluated, |
| 20 |
} |
| 21 |
\item{parms }{the parameters that are passed to the initialiser function, |
| 22 |
} |
| 23 |
\item{dllname }{a string giving the name of the shared library (without |
| 24 |
extension) that contains the compiled function or subroutine definitions |
| 25 |
referred to in \code{func}, |
| 26 |
} |
| 27 |
\item{initfunc }{if not \code{NULL}, the name of the initialisation function |
| 28 |
(which initialises values of parameters), as provided in \file{dllname}. |
| 29 |
See details. |
| 30 |
} |
| 31 |
\item{rpar }{a vector with double precision values passed to the |
| 32 |
DLL-function \code{func} and \code{jacfunc} present in the DLL, via |
| 33 |
argument rpar, |
| 34 |
} |
| 35 |
\item{ipar }{a vector with integer values passed to the dll-function |
| 36 |
\code{func} and \code{jacfunc} present in the DLL, via function argument |
| 37 |
ipar, |
| 38 |
} |
| 39 |
\item{nout }{the number of output variables. |
| 40 |
} |
| 41 |
\item{outnames }{only used if \file{dllname} is specified and |
| 42 |
\code{nout} > 0: the names of output variables calculated in the |
| 43 |
compiled function \code{func}, present in the shared library. |
| 44 |
} |
| 45 |
\item{forcings }{only used if \file{dllname} is specified: a list with |
| 46 |
the forcing function data sets, each present as a two-columned matrix, |
| 47 |
with (time, value); interpolation outside the interval |
| 48 |
[min(\code{times}), max(\code{times})] is done by taking the value at |
| 49 |
the closest data extreme. |
| 50 |
|
| 51 |
See package vignette \code{"compiledCode"}. |
| 52 |
} |
| 53 |
\item{initforc }{if not \code{NULL}, the name of the forcing function |
| 54 |
initialisation function, as provided in |
| 55 |
\file{dllname}. It MUST be present if \code{forcings} has been given a |
| 56 |
value. |
| 57 |
See package vignette \code{"compiledCode"}. |
| 58 |
} |
| 59 |
\item{fcontrol }{A list of control parameters for the forcing functions. |
| 60 |
See package vignette \code{"compiledCode"}. |
| 61 |
} |
| 62 |
} |
| 63 |
\value{ |
| 64 |
a list containing: |
| 65 |
\item{dy }{the rate of change estimated by the function, |
| 66 |
} |
| 67 |
\item{var }{the ordinary output variables of the function. |
| 68 |
} |
| 69 |
} |
| 70 |
\details{ |
| 71 |
This function is meant to help developing FORTRAN or C models that are |
| 72 |
to be used to solve ordinary differential equations (ODE) in packages |
| 73 |
\code{deSolve} and/or \code{rootSolve}. |
| 74 |
} |
| 75 |
\author{Karline Soetaert <[email protected]>} |
| 76 |
\examples{ |
| 77 |
## ========================================================================== |
| 78 |
## ex. 1 |
| 79 |
## ccl4model |
| 80 |
## ========================================================================== |
| 81 |
## Parameter values and initial conditions |
| 82 |
## see example(ccl4model) for a more comprehensive implementation |
| 83 |
|
| 84 |
Parms <- c(0.182, 4.0, 4.0, 0.08, 0.04, 0.74, 0.05, 0.15, 0.32, |
| 85 |
16.17, 281.48, 13.3, 16.17, 5.487, 153.8, 0.04321671, |
| 86 |
0.4027255, 1000, 0.02, 1.0, 3.8) |
| 87 |
|
| 88 |
yini <- c(AI = 21, AAM = 0, AT = 0, AF = 0, AL = 0, CLT = 0, AM = 0) |
| 89 |
|
| 90 |
## the rate of change |
| 91 |
DLLfunc(y = yini, dllname = "deSolve", func = "derivsccl4", |
| 92 |
initfunc = "initccl4", parms = Parms, times = 1, |
| 93 |
nout = 3, outnames = c("DOSE", "MASS", "CP") ) |
| 94 |
|
| 95 |
## ========================================================================== |
| 96 |
## ex. 2 |
| 97 |
## SCOC model |
| 98 |
## ========================================================================== |
| 99 |
|
| 100 |
## Forcing function "data" |
| 101 |
Flux <- matrix(ncol = 2, byrow = TRUE, data = c(1, 0.654, 2, 0.167)) |
| 102 |
parms <- c(k = 0.01) |
| 103 |
Yini <- 60 |
| 104 |
|
| 105 |
DLLfunc(y=Yini, times=1, func = "scocder", |
| 106 |
parms = parms, dllname = "deSolve", |
| 107 |
initforc = "scocforc", forcings = Flux, |
| 108 |
initfunc = "scocpar", nout = 2, |
| 109 |
outnames = c("Mineralisation","Depo")) |
| 110 |
## correct value = dy = flux - k * y = 0.654 - 0.01 * 60 |
| 111 |
|
| 112 |
DLLfunc(y = Yini, times = 2, func = "scocder", |
| 113 |
parms = parms, dllname = "deSolve", |
| 114 |
initforc = "scocforc", forcings = Flux, |
| 115 |
initfunc = "scocpar", nout = 2, |
| 116 |
outnames = c("Mineralisation", "Depo")) |
| 117 |
} |
| 118 |
\keyword{utilities} |
| 119 |
|
| 120 |
\seealso{ |
| 121 |
\code{\link{ode}} for a general interface to most of the ODE solvers |
| 122 |
} |