Debian Codegraph @

man/DLLfunc.Rd

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