Compile a Stan program

The $compile() method of a CmdStanModel object translates the Stan program to C++ and creates a compiled executable. In most cases the user does not need to explicitly call the $compile() method as compilation will occur when calling cmdstan_model(). However it is possible to set compile=FALSE in the call to cmdstan_model() and subsequently call the $compile() method directly.

After compilation, the paths to the executable and the .hpp file containing the generated C++ code are available via the $exe_file() and $hpp_file() methods. The default is to create the executable in the same directory as the Stan program and to write the generated C++ code in a temporary directory. To save the C++ code to a non-temporary location use $save_hpp_file(dir).

compile(
  quiet = TRUE,
  dir = NULL,
  pedantic = FALSE,
  include_paths = NULL,
  cpp_options = list(),
  stanc_options = list(),
  force_recompile = FALSE,
  threads = FALSE
)

Arguments

quiet	(logical) Should the verbose output from CmdStan during compilation be suppressed? The default is TRUE, but if you encounter an error we recommend trying again with quiet=FALSE to see more of the output.
dir	(string) The path to the directory in which to store the CmdStan executable (or .hpp file if using $save_hpp_file()). The default is the same location as the Stan program.
pedantic	(logical) Should pedantic mode be turned on? The default is FALSE. Pedantic mode attempts to warn you about potential issues in your Stan program beyond syntax errors. For details see the Pedantic mode chapter in the Stan Reference Manual. Note: to do a pedantic check for a model that is already compiled use the $check_syntax() method instead.
include_paths	(character vector) Paths to directories where Stan should look for files specified in #include directives in the Stan program.
cpp_options	(list) Any makefile options to be used when compiling the model (STAN_THREADS, STAN_MPI, STAN_OPENCL, etc.). Anything you would otherwise write in the make/local file.
stanc_options	(list) Any Stan-to-C++ transpiler options to be used when compiling the model. See the Examples section below as well as the stanc chapter of the CmdStan Guide for more details on available options: https://mc-stan.org/docs/cmdstan-guide/stanc.html.
force_recompile	(logical) Should the model be recompiled even if was not modified since last compiled. The default is FALSE.
threads	Deprecated and will be removed in a future release. Please turn on threading via cpp_options = list(stan_threads = TRUE) instead.

Value

The $compile() method is called for its side effect of creating the executable and adding its path to the CmdStanModel object, but it also returns the CmdStanModel object invisibly.

After compilation, the $exe_file(), $hpp_file(), and $save_hpp_file() methods can be used and return file paths.

See also

The CmdStanR website (mc-stan.org/cmdstanr) for online documentation and tutorials.

The Stan and CmdStan documentation:

• Stan documentation: mc-stan.org/users/documentation

• CmdStan User’s Guide: mc-stan.org/docs/cmdstan-guide

Other CmdStanModel methods: model-method-check_syntax, model-method-generate-quantities, model-method-optimize, model-method-sample_mpi, model-method-sample, model-method-variational

Examples

# \dontrun{
file <- file.path(cmdstan_path(), "examples/bernoulli/bernoulli.stan")

# by default compilation happens when cmdstan_model() is called.
# to delay compilation until calling the $compile() method set compile=FALSE
mod <- cmdstan_model(file, compile = FALSE)
mod$compile()
#> Model executable is up to date!
mod$exe_file()
#> [1] "/Users/jgabry/.cmdstanr/cmdstan-2.25.0/examples/bernoulli/bernoulli"

# turn on threading support (for using functions that support within-chain parallelization)
mod$compile(force_recompile = TRUE, cpp_options = list(stan_threads = TRUE))
#> Compiling Stan program...
mod$exe_file()
#> [1] "/Users/jgabry/.cmdstanr/cmdstan-2.25.0/examples/bernoulli/bernoulli_threads"

# turn on pedantic mode (new in Stan v2.24)
file_pedantic <- write_stan_file("
parameters {
  real sigma;  // pedantic mode will warn about missing <lower=0>
}
model {
  sigma ~ exponential(1);
}
")
mod <- cmdstan_model(file_pedantic, pedantic = TRUE)
#> Compiling Stan program...
#> Warning at '/var/folders/h6/14xy_35x4wd2tz542dn0qhtc0000gn/T/RtmpGraDrG/model-2ed2582a7eb0.stan', line 6, column 2 to column 7:
#>   Parameter sigma is given a exponential distribution, which has strictly
#>   positive support, but sigma was not constrained to be strictly positive.

# }