Evaluates a Derivative Function Represented in a DLL

Calls a function, defined in a compiled language as a DLL

Usage

DLLfunc(func, times, y, parms, dllname,
  initfunc = dllname, rpar = NULL, ipar = NULL, nout = 0,
  outnames = NULL, forcings = NULL, initforc = NULL,
  fcontrol = NULL)

Arguments

func

the name of the function in the dynamically loaded shared library,

times

first value = the time at which the function needs to be evaluated,

y

the values of the dependent variables for which the function needs to be evaluated,

parms

the parameters that are passed to the initialiser function,

dllname

a string giving the name of the shared library (without extension) that contains the compiled function or subroutine definitions referred to in func,

initfunc

if not NULL, the name of the initialisation function (which initialises values of parameters), as provided in dllname. See details.

rpar

a vector with double precision values passed to the DLL-function func and jacfunc present in the DLL, via argument rpar,

ipar

a vector with integer values passed to the dll-function func and jacfunc present in the DLL, via function argument ipar,

nout

the number of output variables.

outnames

only used if dllname is specified and nout > 0: the names of output variables calculated in the compiled function func, present in the shared library.

forcings

only used if dllname is specified: a list with the forcing function data sets, each present as a two-columned matrix, with (time, value); interpolation outside the interval [min(times), max(times)] is done by taking the value at the closest data extreme.

See package vignette "compiledCode".

initforc

if not NULL, the name of the forcing function initialisation function, as provided in dllname. It MUST be present if forcings has been given a value. See package vignette "compiledCode".

fcontrol

A list of control parameters for the forcing functions. See package vignette "compiledCode".

Value

a list containing:

dy: the rate of change estimated by the function,
var: the ordinary output variables of the function.

Details

This function is meant to help developing FORTRAN or C models that are to be used to solve ordinary differential equations (ODE) in packages deSolve and/or rootSolve.

Author

Karline Soetaert <karline.soetaert@nioz.nl>

Examples

## ==========================================================================
## ex. 1
## ccl4model
## ==========================================================================
## Parameter values and initial conditions
## see example(ccl4model) for a more comprehensive implementation

Parms <- c(0.182, 4.0, 4.0, 0.08, 0.04, 0.74, 0.05, 0.15, 0.32,
        16.17, 281.48, 13.3, 16.17, 5.487, 153.8, 0.04321671,
        0.4027255, 1000, 0.02, 1.0, 3.8)

yini <- c(AI = 21, AAM = 0, AT = 0, AF = 0, AL = 0, CLT = 0,  AM = 0)

## the rate of change
DLLfunc(y = yini, dllname = "deSolve", func = "derivsccl4",
        initfunc = "initccl4", parms = Parms, times = 1,
        nout = 3, outnames = c("DOSE", "MASS", "CP")  )
#> $dy
#>          AI         AAM          AT          AF          AL         CLT 
#> -20.0582048   6.2842256   9.4263383   0.9819102   2.9457307   0.0000000 
#>          AM 
#>   0.0000000 
#> 
#> $var
#>       DOSE       MASS         CP 
#>   1.758626   0.000000 922.727067 
#> 

## ==========================================================================
## ex. 2
## SCOC model
## ==========================================================================

## Forcing function "data"
Flux  <- matrix(ncol = 2, byrow = TRUE, data = c(1, 0.654, 2, 0.167))
parms <- c(k = 0.01)
Yini  <- 60

DLLfunc(y=Yini, times=1, func = "scocder",
    parms = parms, dllname = "deSolve",
    initforc = "scocforc",  forcings = Flux,
    initfunc = "scocpar", nout = 2,
    outnames = c("Mineralisation","Depo"))
#> $dy
#> [1] 0.054
#> 
#> $var
#> Mineralisation           Depo 
#>          0.600          0.654 
#> 
## correct value = dy = flux - k * y = 0.654 - 0.01 * 60

DLLfunc(y = Yini, times = 2, func = "scocder",
    parms = parms, dllname = "deSolve",
    initforc = "scocforc",  forcings = Flux,
    initfunc = "scocpar", nout = 2,
    outnames = c("Mineralisation", "Depo"))
#> $dy
#> [1] -0.433
#> 
#> $var
#> Mineralisation           Depo 
#>          0.600          0.167 
#>