R: C snippets

Csnippet {pomp}

R Documentation

C snippets

Description

Accelerating computations through inline snippets of C code

Usage

Csnippet(text)

Arguments

text

character; text written in the C language

Details

pomp provides a facility whereby users can define their model's components using inline C code. C snippets are written to a C file, by default located 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.

Note to Windows and Mac users

By default, your R installation may not support R CMD SHLIB. The package website contains installation instructions that explain how to enable this powerful feature of R.

General rules for writing C snippets

In writing a C snippet 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. These are explained here in the form of general rules. Additional specific rules apply according to the function of the particular C snippet. Illustrative examples are given in the tutorials on the package website.

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 will be generated. Compiler messages will be displayed, but no attempt will be made by pomp to interpret them. Typically, compilation errors are due to either invalid C syntax or undeclared variables.
State variables, parameters, observables, and covariates must be left undeclared within the snippet. State variables and parameters are declared via the statenames or paramnames arguments to pomp, respectively. Compiler errors that complain about undeclared state variables or parameters are usually due to failure to declare these in statenames or paramnames, as appropriate.
A C snippet can declare local variables. Be careful not to use names that match those of state variables, observables, or parameters. One must never declare state variables, observables, covariates, or parameters within a C snippet.
Names of observables must match the names given given in the data. They must be referred to in measurement model C snippets (rmeasure and dmeasure) by those names.
If the ‘pomp’ object contains a table of covariates (see above), then the variables in the covariate table will be available, by their names, in the context within which the C snippet is executed.
Because the dot ‘.’ has syntactic meaning in C, R variables with names containing dots (‘.’) are replaced in the C codes by variable names in which all dots have been replaced by underscores (‘_’).
The headers ‘R.h’ and ‘Rmath.h’, provided with R, will be included in the generated C file, making all of the R C API available for use in the C snippet. This makes a great many useful functions available, including all of R's statistical distribution functions.
The header ‘pomp.h’, provided with pomp, will also be included, making all of the pomp C API available for use in every C snippet.
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.

Linking to precompiled libraries

It is straightforward to link C snippets with precompiled C libraries. To do so, one must make sure the library's header files are included; the globals argument can be used for this purpose. The shlib.args argument can then be used to specify additional arguments to be passed to R CMD SHLIB. FAQ 3.7 gives an example.

C snippets are salted

To prevent collisions in parallel computations, a ‘pomp’ object built using C snippets is “salted” with the current time and a random number. A result is that two ‘pomp’ objects, built on identical codes and data, will not be identical as R objects, though they will be functionally identical in every respect.

Note for Windows users

Some Windows users report problems when using C snippets in parallel computations. These appear to arise when the temporary files created during the C snippet compilation process are not handled properly by the operating system. To circumvent this problem, use the cdir and cfile options to cause the C snippets to be written to a file of your choice, thus avoiding the use of temporary files altogether.