csnippet: C code snippets for accelerating computations

In pomp: Statistical Inference for Partially Observed Markov Processes

Description

For including snippets of C code in pomp objects.

Usage

  Csnippet(text)

Arguments

text	character; a snippet of C code.

Value

An object of class Csnippet.

Using C snippets to accelerate computations

From version 0.50, pomp provides a facility whereby users can define their model's components using inline C code. Furnishing one or more Csnippets as arguments to the pomp constructor causes them to be written to a C file stored in the R session's temporary directory, which is then compiled (via R CMD SHLIB) into a dynamically loadable shared object file. This is then loaded as needed.

One can choose to store these files in a different directory by setting the global option pomp.cache, e.g.:

options(pomp.cache=getwd())

.

Note to Windows and Mac users: By default, your R installation may not support R CMD SHLIB. Have a look at the tutorials on the package website for instructions on enabling this powerful feature of R.

In writing a Csnippet one must bear in mind both the goal of the snippet, i.e., what computation it is intended to perform, and the context in which it will be executed. Details of both of these are given below in the form of rules governing the use of Csnippets. Illustrative examples are given in the tutorials on the package website.

General rules for writing C snippets

1. C snippets must be valid C. They will embedded verbatim in a template file which will then be compiled by a call to R CMD SHLIB. If the resulting file does not compile, an error message wil be generated. No attempt is made by pomp to interpret this message. Typically, compilation errors are due to either invalid C syntax or undeclared variables.

2. State variables, parameters, observables, and covariates must be left undeclared in the snippet. State variables and parameters must be declared in either the statenames or paramnames argument to pomp, as appropriate. Compiler errors that complain about undeclared state variables or parameters are usually due to failure to include these parameters in the appropriate vector of names.

3. A C snippet can declare local variables. Be careful not to use names that match those of state variables, observables, or parameters. The latter must never be declared within a snippet.

4. Names of observables are determined by their names in the data. They must be referred to in measurement model snippets (rmeasure or dmeasure) by those names.

5. If the pomp object contains a table of covariates (see pomp), then the variables in the covariate table will be available, by their names, in the context within which the snippet is executed.

6. R variables with names containing dots (‘.’) are replaced in the C codes by variable names in which all dots have been replaced by underscores (‘_’).

7. The header ‘R.h’, provided with R, will be included in the generated C file, making all of the R C API available for use in the snippet.

8. The header ‘pomp.h’, provided with pomp, will also be included, making all of the pomp C API available for use in every snippet. Do

   file.show(system.file("include/pomp.h",package="pomp"))

   to view this header file.

9. Snippets of C code passed to the globals argument of pomp will be included at the head of the generated C file. This can be used to declare global variables, define useful functions, and include arbitrary header files.

Rules for writing rmeasure snippets

1. The goal of such a snippet is to fill the observables with random values drawn from the measurement model distribution. Accordingly, each observable should be assigned a new value.

2. In addition to the states, parameters, covariates (if any), and observables, the variable t, containing the time of the observation, will be defined in the context in which the snippet is executed.

Rules for writing dmeasure snippets

1. The goal of such a snippet is to fill the lik variable with the likelihood of the data given the state. Alternatively, if give_log=1, lik should be filled with the log likelihood.

2. In addition to the states, parameters, covariates (if any), and observables, the variable t, containing the time of the observation, will be defined in the context in which the snippet is executed.

Rules for writing euler.sim and discrete.time.sim snippets

1. The goal of such a snippet is to replace the state variables with their new random values at the end of the time interval. Accordingly, each state variable should be over-written with its new value.

2. In addition to the states, parameters, covariates (if any), and observables, the variables t and dt, containing respectively the time at the beginning of the Euler step and the Euler step's duration, will be defined in the context in which the snippet is executed.

Rules for writing skeleton snippets

1. For each state variable, there is a corresponding component of the deterministic skeleton. The goal of such a snippet is to compute all the components.

2. When the skeleton is a map, the component corresponding to state variable x is named Dx and is the new value of x after one iteration of the map.

3. When the skeleton is a vectorfield, the component corresponding to state variable x is named Dx and is the value of $dx/dt$.

4. As with the other C snippets, all states, parameters and covariates, as well as the current time, t, will be defined in the context within which the snippet is executed.

Rules for writing rprior snippets

1. The goal of such a snippet is the replacement of parameters with values drawn from the prior distribution.

2. Within the context in which the snippet will be evaluated, only the parameters will be defined.

3. Hyperparameters can be included in the ordinary parameter list. Obviously, hyperparameters should not be replaced with random draws.

Rules for writing dprior snippets

1. The goal of such a snippet is computation of the prior probability density, or the log of same, at a given point in parameter space. This scalar value should be returned in the variable lik. When give_log=1, the user should return the log of the prior probability density.

2. Within the context in which the snippet will be evaluated, only the parameters and give_log will be defined.

3. Hyperparameters can be included in the ordinary parameter list. Obviously, hyperparameters should not be replaced with random draws.

Rules for writing parameter transformation snippets

1. The parameter transformation mapping a parameter vector from the scale used by the model codes to another scale is specified using the toEstimationScale argument whilst the transformation mapping a parameter vector from the alternative scale to that on which the model is defined is specified with the fromEstimationScale argument.

2. The goal of these snippets is the computation of the values of the transformed parameters. The value of transformed parameter x should be assigned to variable Tx.

3. Time-, state-, and covariate-dependent transformations are not allowed. Therefore, neither the time, nor any state variables, nor any of the covariates will be available in the context within which a parameter transformation snippet is executed.

Rules for writing initializer snippets

1. The goal of a this snippet is the construction of a state vector, i.e., the setting of the dynamical states at time \code{t0}.

2. In addition to the parameters and covariates (if any), the variable t, containing the time of the observation, will be defined in the context in which the snippet is executed.

3. NB: The statenames argument plays a particularly important role when the initializer is specified using a Csnippet. In particular, every state variable must be named in statenames. Failure to follow this rule will result in undefined behavior.

Viewing the generated C code

It can be useful to view the C code generated by calling pomp with one or more Csnippet arguments. To do so, set options(verbose=TRUE) before calling pomp. A message giving the name of the generated C file (in the session temporary directory) will be printed.

Author(s)

Aaron A. King kingaa at umich dot edu

See Also

pomp, plugins, and the tutorials on the package website.

pomp documentation built on May 2, 2019, 4:09 p.m.