Add optional method for exposing stan functions to R

[andrjohns]

Submission Checklist

• Run unit tests
• Declare copyright holder and agree to license (see below)

Summary

This PR adds the functionality to compile and expose user-defined functions to R. After fitting a model, the user simply needs to call the expose_functions() method from the fit object, and the functions will be compiled and made available. By default, these functions are not exposed to the global environment, and instead available under the functions member of the fit object:

library(cmdstanr)
#> This is cmdstanr version 0.5.3
#> - CmdStanR documentation and vignettes: mc-stan.org/cmdstanr
#> - CmdStan path: /Users/andrew/.cmdstan/cmdstan-2.30.1
#> - CmdStan version: 2.30.1
model <- "functions { real rtnx(real x) { return x; } } data { real y_mean; } parameters { real y; } model { y ~normal(y_mean, 1); }"
mod <- cmdstan_model(write_stan_file(model))
fit <- mod$sample(data = list(y_mean = 0), refresh = 0)
#> Running MCMC with 4 sequential chains...
#> 
#> Chain 1 finished in 0.0 seconds.
#> Chain 2 finished in 0.0 seconds.
#> Chain 3 finished in 0.0 seconds.
#> Chain 4 finished in 0.0 seconds.
#> 
#> All 4 chains finished successfully.
#> Mean chain execution time: 0.0 seconds.
#> Total execution time: 0.5 seconds.

# Compile and expose functions
fit$expose_functions()
#> Compiling standalone functions...
fit$functions$rtnx(5)
#> [1] 5

^{Created on 2022-10-10 with reprex v2.0.2}

Alternatively, if they use the global = TRUE argument then the functions will be made available in the global environment instead:

library(cmdstanr)
#> This is cmdstanr version 0.5.3
#> - CmdStanR documentation and vignettes: mc-stan.org/cmdstanr
#> - CmdStan path: /Users/andrew/.cmdstan/cmdstan-2.30.1
#> - CmdStan version: 2.30.1
model <- "functions { real rtnx(real x) { return x; } } data { real y_mean; } parameters { real y; } model { y ~normal(y_mean, 1); }"
mod <- cmdstan_model(write_stan_file(model))
fit <- mod$sample(data = list(y_mean = 0), refresh = 0)
#> Running MCMC with 4 sequential chains...
#> 
#> Chain 1 finished in 0.0 seconds.
#> Chain 2 finished in 0.0 seconds.
#> Chain 3 finished in 0.0 seconds.
#> Chain 4 finished in 0.0 seconds.
#> 
#> All 4 chains finished successfully.
#> Mean chain execution time: 0.0 seconds.
#> Total execution time: 0.5 seconds.

# Compile and expose functions
fit$expose_functions(global = TRUE)
#> Compiling standalone functions...
rtnx(5)
#> [1] 5

^{Created on 2022-10-10 with reprex v2.0.2}

Additionally, the user can also request that the methods are compiled with the call to cmdstan_model:

library(cmdstanr)
#> This is cmdstanr version 0.5.3
#> - CmdStanR documentation and vignettes: mc-stan.org/cmdstanr
#> - CmdStan path: /Users/andrew/.cmdstan/cmdstan-2.30.1
#> - CmdStan version: 2.30.1
model <- "functions { real rtnx(real x) { return x; } } data { real y_mean; } parameters { real y; } model { y ~normal(y_mean, 1); }"
mod <- cmdstan_model(write_stan_file(model), compile_standalone = TRUE)
fit <- mod$sample(data = list(y_mean = 0), refresh = 0)
#> Running MCMC with 4 sequential chains...
#> 
#> Chain 1 finished in 0.0 seconds.
#> Chain 2 finished in 0.0 seconds.
#> Chain 3 finished in 0.0 seconds.
#> Chain 4 finished in 0.0 seconds.
#> 
#> All 4 chains finished successfully.
#> Mean chain execution time: 0.0 seconds.
#> Total execution time: 0.6 seconds.

# Functions already compiled and available
fit$functions$rtnx(5)
#> [1] 5

^{Created on 2022-10-10 with reprex v2.0.2}

Copyright and Licensing

Please list the copyright holder for the work you are submitting
(this will be you or your assignee, such as a university or company):
Andrew Johnson

By submitting this pull request, the copyright holder is agreeing to
license the submitted work under the following licenses:

• Code: BSD 3-clause (https://opensource.org/licenses/BSD-3-Clause)
• Documentation: CC-BY 4.0 (https://creativecommons.org/licenses/by/4.0/)

[rok-cesnovar]

Fantastic as always @andrjohns! Will take a look soon.

[rok-cesnovar]

🚀

Looks great, no comments necessary :)

[jgabry]

This is awesome!