R: Evaluates a Derivative Function Represented in a DLL

DLLfunc {deSolve} | R Documentation

## Evaluates a Derivative Function Represented in a DLL

### Description

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"`.

### 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`.

### Value

a list containing:

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

### Author(s)

Karline Soetaert <karline.soetaert@nioz.nl>

### See Also

`ode` for a general interface to most of the ODE solvers

### 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")  )

    ## ==========================================================================
    ## 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"))
    ## 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"))

[Package deSolve version 1.32 Index]