compile: Compile a C++ template to DLL suitable for MakeADFun.

In TMB: Template Model Builder: A General Random Effect Tool Inspired by 'ADMB'

Compile a C++ template to DLL suitable for MakeADFun.

Description

Compile a C++ template into a shared object file. OpenMP flag is set if the template is detected to be parallel.

Usage

compile(
  file,
  flags = "",
  safebounds = TRUE,
  safeunload = TRUE,
  openmp = isParallelTemplate(file[1]),
  libtmb = TRUE,
  libinit = TRUE,
  tracesweep = FALSE,
  framework = getOption("tmb.ad.framework"),
  supernodal = FALSE,
  longint = FALSE,
  eigen.disable.warnings = TRUE,
  max.order = NULL,
  ...
)

Arguments

file	C++ file.
flags	Character with compile flags.
safebounds	Turn on preprocessor flag for bound checking?
safeunload	Turn on preprocessor flag for safe DLL unloading?
openmp	Turn on openmp flag? Auto detected for parallel templates.
libtmb	Use precompiled TMB library if available (to speed up compilation)?
libinit	Turn on preprocessor flag to register native routines?
tracesweep	Turn on preprocessor flag to trace AD sweeps? (Silently disables libtmb)
framework	Which AD framework to use ('TMBad' or 'CppAD')
supernodal	Turn on preprocessor flag to use supernodal sparse Cholesky/Inverse from system wide suitesparse library
longint	Turn on preprocessor flag to use long integers for Eigen's SparseMatrix StorageIndex
eigen.disable.warnings	Turn on preprocessor flag to disable nuisance warnings. Note that this is not allowed for code to be compiled on CRAN.
max.order	Maximum derivative order of compiler generated atomic special functions - see details.
...	Passed as Makeconf variables.

Details

TMB relies on R's built in functionality to create shared libraries independent of the platform. A template is compiled by compile("template.cpp"), which will call R's makefile with appropriate preprocessor flags. Compiler and compiler flags can be stored in a configuration file. In order of precedence either via the file pointed at by R_MAKEVARS_USER or the file ~/.R/Makevars if it exists. Additional configuration variables can be set with the flags and ... arguments, which will override any previous selections.

Using a custom SuiteSparse installation

Sparse matrix calculations play an important role in TMB. By default TMB uses a small subset of SuiteSparse available through the R package Matrix. This is sufficient for most use cases, however for some very large models the following extra features are worth considering:

• Some large models benefit from an extended set of graph reordering algorithms (especially METIS) not part of Matrix. It is common that these orderings can provide quite big speedups.

• Some large models need sparse matrices with number of nonzeros exceeding the current 32 bit limitation of Matrix. Normally such cases will result in the cholmod error 'problem too large'. SuiteSparse includes 64 bit integer routines to address this problem.

Experimental support for linking to a custom SuiteSparse installation is available through two arguments to the compile function. The first argument supernodal=TRUE tells TMB to use the supernodal Cholesky factorization from the system wide SuiteSparse on the C++ side. This will affect the speed of the Laplace approximation when run internally (using arguments intern or integrate to MakeADFun).

The second argument longint=TRUE tells TMB to use 64 bit integers for sparse matrices on the C++ side. This works in combination with supernodal=TRUE from Eigen version 3.4.

On Windows a SuiteSparse installation can be obtained using the Rtools package manager. Start 'Rtools Bash' terminal and run:

  pacman -Sy
  pacman -S mingw-w64-{i686,x86_64}-suitesparse

On Linux one should look for the package libsuitesparse-dev.

Selecting the AD framework

TMB supports two different AD libraries 'CppAD' and 'TMBad' selected via the argument framework which works as a switch to set one of two C++ preprocessor flags: 'CPPAD_FRAMEWORK' or 'TMBAD_FRAMEWORK'. The default value of framework can be set from R by options("tmb.ad.framework") or alternatively from the shell via the environment variable 'TMB_AD_FRAMEWORK'. Packages linking to TMB should set one of the two C++ preprocessor flags in Makevars.

Order of compiler generated atomic functions

The argument max.order controls the maximum derivative order of special functions (e.g. pbeta) generated by the compiler. By default the value is set to 3 which is sufficient to obtain the Laplace approximation (order 2) and its derivatives (order 3). However, sometimes a higher value may be needed. For example framework='TMBad' allows one to calculate the Hessian of the Laplace approximation, but that requires 4th order derivatives of special functions in use. A too small value will cause the runtime error 'increase TMB_MAX_ORDER'. Note that compilation time and binary size increases with max.order.

See Also

precompile

TMB documentation built on Nov. 27, 2023, 5:12 p.m.