Compile a Stan program — model-method-compile • cmdstanr
Description: The $compile() method of a CmdStanModel object checks the syntax of the Stan program, translates the program to C++, and creates a compiled executable. To just check the syntax of a Stan program without compiling it use the $check_syntax() method instead. 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 a Stan program

Source: `R/model.R`
`model-method-compile.Rd`

The `$compile()` method of a `CmdStanModel` object checks the syntax of the Stan program, translates the program to C++, and creates a compiled executable. To just check the syntax of a Stan program without compiling it use the `$check_syntax()` method instead.

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,
      user_header = NULL,
      cpp_options = list(),
      stanc_options = list(),
      force_recompile = getOption("cmdstanr_force_recompile", default = FALSE),
      compile_model_methods = FALSE,
      compile_hessian_method = FALSE,
      compile_standalone = 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 without compiling it or for a model that is already compiled the `$check_syntax()` method can be used instead.

include_paths

  (character vector) Paths to directories where Stan should look for files specified in `#include` directives in the Stan program.

user_header

  (string) The path to a C++ file (with a .hpp extension) to compile with the Stan model.

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. For an example of using threading see the Stan case study Reduce Sum: A Minimal Example.

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`. Can also be set via a global `cmdstanr_force_recompile` option.

compile_model_methods

  (logical) Compile additional model methods (`log_prob()`, `grad_log_prob()`, `constrain_variables()`, `unconstrain_variables()`).

compile_hessian_method

  (logical) Should the (experimental) `hessian()` method be be compiled with the model methods?

compile_standalone

  (logical) Should functions in the Stan model be compiled for use in R? If `TRUE` the functions will be available via the `functions` field in the compiled model object. This can also be done after compilation using the `$expose_functions()` method.

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 `$check_syntax()` method to check Stan syntax or enable pedantic model without compiling.

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-diagnose`, `model-method-expose_functions`, `model-method-format`, `model-method-generate-quantities`, `model-method-optimize`, `model-method-sample_mpi`, `model-method-sample`, `model-method-variables`, `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()
    mod$exe_file()
    #> [1] "/Users/jgabry/.cmdstan/cmdstan-2.32.2/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))
    mod$exe_file()
    #> [1] "/Users/jgabry/.cmdstan/cmdstan-2.32.2/examples/bernoulli/bernoulli"

    # 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)
    #> Warning in '/var/folders/s0/zfzm55px2nd2v__zlw5xfj2h0000gn/T/RtmpFBtN6X/model-1621885c67f.stan', line 6, column 2: Parameter
    #>     sigma is given a exponential distribution, which has strictly positive
    #>     support, but sigma was not constrained to be strictly positive.

    # }