dust_package: Create dust model in package

In mrc-ide/dust: Iterate Multiple Realisations of Stochastic Models

Create dust model in package

Description

Updates a dust model in a package. The user-provided code is assumed to the in inst/dust as a series of C++ files; a file inst/dust/model.cpp will be transformed into a file src/model.cpp.

Usage

dust_package(path, quiet = FALSE)

Arguments

path	Path to the package
quiet	Passed to cpp11::cpp_register, if TRUE suppresses informational notices about updates to the cpp11 files

Details

If your code provides a class model then dust will create C++ functions such as dust_model_alloc - if your code also includes names such as this, compilation will fail due to duplicate symbols.

We add "cpp11 attributes" to the created functions, and will run cpp11::cpp_register() on them once the generated code has been created.

Your package needs a src/Makevars file to enable openmp (if your system supports it). If it is not present then a suitable Makevars will be written, containing

PKG_CXXFLAGS=$(SHLIB_OPENMP_CXXFLAGS)
PKG_LIBS=$(SHLIB_OPENMP_CXXFLAGS)

following "Writing R Extensions" (see section "OpenMP support"). If your package does contain a src/Makevars file we do not attempt to edit it but will error if it looks like it does not contain these lines or similar.

You also need to make sure that your package loads the dynamic library; if you are using roxygen, then you might create a file (say, R/zzz.R) containing

#' @useDynLib packagename, .registration = TRUE
NULL

substituting packagename for your package name as appropriate. This will create an entry in NAMESPACE.

Value

Nothing, this function is called for its side effects

See Also

vignette("dust") which contains more discussion of this process

Examples

# This is explained in more detail in the package vignette
path <- system.file("examples/sir.cpp", package = "dust", mustWork = TRUE)
dest <- tempfile()
dir.create(dest)
dir.create(file.path(dest, "inst/dust"), FALSE, TRUE)
writeLines(c("Package: example",
             "Version: 0.0.1",
             "LinkingTo: cpp11, dust"),
           file.path(dest, "DESCRIPTION"))
writeLines("useDynLib('example', .registration = TRUE)",
           file.path(dest, "NAMESPACE"))
file.copy(path, file.path(dest, "inst/dust"))

# An absolutely minimal skeleton contains a DESCRIPTION, NAMESPACE
# and one or more dust model files to compile:
dir(dest, recursive = TRUE)

# Running dust_package will fill in the rest
dust::dust_package(dest)

# More files here now
dir(dest, recursive = TRUE)

mrc-ide/dust documentation built on Oct. 6, 2023, 8:26 a.m.