Description Usage Arguments Details Value Author(s)
compile a collection of models and nimbleFunctions: generate C++, compile the C++, load the result, and return an interface object
1 2 | compileNimble(..., project, dirName = NULL, projectName = "",
control = list(), resetFunctions = FALSE)
|
... |
An arbitrary set of NIMBLE models and nimbleFunctions, or lists of them. If given as named parameters, those names may be used in the return list. |
project |
Optional NIMBLE model or nimbleFunction already associated with a project, which the current units for compilation should join. If not provided, a new project will be created and the current compilation units will be associated with it. |
dirName |
Optional directory name in which to
generate the C++ code. If not provided, a temporary
directory will be generated using R's |
projectName |
Optional character name for labeling the project if it is new |
control |
A list mostly for internal use. See details. |
resetFunctions |
Logical value stating whether nimbleFunctions associated with an existing project should all be reset for compilation purposes. See details. |
This is the main function for calling the NIMBLE compiler.
A set of compiler calls and output will be seen. Compiling
in NIMBLE does 4 things: 1. It generates C++ code files for
all the model and nimbleFunction components. 2. It calls
the system's C++ compiler. 3. It loads the compiled
object(s) into R using dyn.load
. And 4. it generates
R objects for using the compiled model and nimbleFunctions.
When the units for compilation provided in ...
include multiple models and/or nimbleFunctions, models are
compiled first, in the order in which they are provided.
Groups of nimbleFunctions that were specialized from the
same nimbleFunction generator (the result of a call to
nimbleFunction
, which then takes setup arguments and
returns a specialized nimbleFunction) are then compiled as
a group, in the order of first appearance.
The behavior of adding new compilation units to an existing
project is limited. For example, one can compile a model
in one call to compileNimble
and then compile a
nimbleFunction that uses the model (i.e. was given the
model as a setup argument) in a second call to
compileNimble
, with the model provided as the
project
argument. Either the uncompiled or compiled
model can be provided. However, compiling a second
nimbleFunction and adding it to the same project will only
work in limited circumstances. Basically, the limitations
occur because it attempts to re-use already compiled
pieces, but if these do not have all the necessary
information for the new compilation, it gives up. An
attempt has been made to give up in a controlled manner and
provide somewhat informative messages.
When compilation is not allowed or doesn't work, try using
resetFunctions = TRUE
, which will force
recompilation of all nimbleFunctions in the new call.
Previously compiled nimbleFunctions will be unaffected, and
their R interface objects should continue to work. The
only cost is additional compilation time for the current
compilation call. If that doesn't work, try re-creating
the model and/or the nimbleFunctions from their generators.
An alternative possible fix is to compile multiple units in
one call, rather than sequentially in multiple calls.
#' The control list can contain the following named
elements, each with TRUE
or FALSE
: debug,
which sets a debug mode for the compiler for development
purposes; debugCpp, which inserts an output message before
every line of C++ code for debugging purposes; compileR,
which determines whether the R-only steps of compilation
should be executed; writeCpp, which determines whether the
C++ files should be generated; compileCpp, which determines
whether the C++ should be compiled; loadSO, which
determines whether the DLL or shared object should be
loaded and interfaced; and returnAsList, which determines
whether calls to the compiled nimbleFunction should return
only the returned value of the call (returnAsList =
FALSE
) or whether a list including the input arguments,
possibly modified, should be returned in a list with the
returned value of the call at the end (returnAsList =
TRUE
). The control list is mostly for developer use,
although returnAsArgs
may be useful to a user. An
example of developer use is that one can have the compiler
write the C++ files but not compile them, then modify them
by hand, then have the C++ compiler do the subsequent steps
without over-writing the files.
See NIMBLE User Manual for examples
If there is only one compilation unit (one model or
nimbleFunction), an R interface object is returned. This
object can be used like the uncompiled model or
nimbleFunction, but execution will call the corresponding
compiled objects or functions. If there are multiple
compilation units, they will be returned as a list of
interface objects, in the order provided. If names were
included in the arguments, or in a list if any elements of
...
are lists, those names will be used for the
corresponding element of the returned list. Otherwise an
attempt will be made to generate names from the argument
code. For example compileNimble(A = fun1, B = fun2,
project = myModel)
will return a list with named elements
A and B, while compileNimble(fun1, fun2, project =
myModel)
will return a list with named elements fun1 and
fun2.
Perry de Valpine
Add the following code to your website.
For more information on customizing the embed code, read Embedding Snippets.