Skip to contents

Configure and run HMC/NUTS safely (global / subset / auto)

Source: R/diagnostics.R
configure_hmc_safely_bis.Rd

Minimal, strict wrapper around NIMBLE + nimbleHMC that:

  1. builds the model,

  2. configures NUTS either globally (model signature), on a subset of nodes (conf + model + nodes signature), or in auto mode,

  3. compiles the MCMC,

  4. runs MCMC.

Usage

configure_hmc_safely_bis(
  build_fn,
  niter,
  nburnin,
  thin,
  nchains,
  monitors = NULL,
  nuts_mode = c("all", "subset", "auto", "none"),
  nuts_nodes = NULL,
  enable_WAIC = FALSE,
  buildDerivs = TRUE,
  compiler_cores = max(1L, parallel::detectCores(TRUE)%/%2L),
  show_compiler_output = TRUE,
  project_name = NULL,
  out_dir = NULL,
  inits = NULL,
  save_samples = TRUE
)

Arguments

build_fn

Function; model builder (e.g. build_M) used to create the NIMBLE model before configuring HMC/NUTS. If .fresh_build() exists, it will be called as .fresh_build(build_fn, monitors, thin). Otherwise, build_fn() must return a list with at least model and conf (NIMBLE objects).

niter

Integer. Total number of iterations.

nburnin

Integer (>= 0). Number of burn-in iterations (0 allowed).

thin

Integer (>= 1). Thinning interval.

nchains

Integer (>= 1). Number of chains.

monitors

Character vector or NULL. Passed through to building and/or global HMC configuration.

nuts_mode

Character. One of c("all","subset","auto","none"):

"all"

Global NUTS via nimbleHMC::configureHMC(model, monitors = ..., enableWAIC = ..., buildDerivs = ...).

"subset"

NUTS only on nuts_nodes via nimbleHMC::configureHMC(conf, model, nodes = ..., ...).

"auto"

Let nimbleHMC::configureHMC(conf, model, ...) choose targets automatically.

"none"

Do not modify the existing configuration.

nuts_nodes

Character vector of node names (can include indexed forms such as "beta[]") when nuts_mode = "subset".

enable_WAIC

Logical. Only relevant for "all" (model-signature path).

buildDerivs

Logical. Passed to nimbleHMC::configureHMC().

compiler_cores

Integer. Passed to nimbleOptions(numCompilerCores = ...).

show_compiler_output

Logical. Passed to nimbleOptions(showCompilerOutput = ...).

project_name

Character or NULL. If non-NULL, sets options(nimbleProjectName = ...) to sanitize the C++ cache.

out_dir

Character or NULL. If non-NULL, saves a sessionInfo() log and, optionally, samples as .rds.

inits

NULL or a list of per-chain initial values to pass to nimble::runMCMC() (length must match nchains if provided).

save_samples

Logical. If TRUE (default) and out_dir is non-NULL, save samples as .rds. If FALSE, skip saving samples.

Value

A list with elements:

  • conf: final MCMC configuration (with HMC/NUTS if configured),

  • cmcmc: compiled MCMC object,

  • samples: coda::mcmc.list of posterior samples,

  • runtime_s: wall time in seconds,

  • build: the build object returned by build_fn or .fresh_build().

Details

No per-node fallback such as addSampler("NUTS") is attempted: on error, the function stops.