Skip to contents

Run HMC/NUTS on all eligible nodes (with slice fallback), optionally in parallel

Source: R/runners.R
run_hmc_all_nodes_parallel.Rd

Configures gradient-based MCMC using nimbleHMC (HMC/NUTS) for all nodes that can be handled by HMC. Any remaining unsampled nodes are automatically assigned a slice sampler as a robust fallback. If nchains > 1 and build_fn supports a chain_id argument, chains are run in true parallel (PSOCK). Otherwise, execution falls back to a safe sequential mode.

Usage

run_hmc_all_nodes_parallel(
  build_fn,
  niter,
  nburnin = floor(0.25 * niter),
  thin = 1L,
  monitors = NULL,
  nchains = 1L,
  opts = samOptiPro_options()
)

Arguments

build_fn

Builder function that creates a fresh NIMBLE model and returns a list with at least model, cmodel and conf. For parallel execution, the builder should accept chain_id and build/compile chain-specific objects.

niter

Total number of MCMC iterations.

nburnin

Number of burn-in iterations discarded.

thin

Thinning interval (keep 1 draw every thin iterations).

monitors

Optional character vector of monitor roots. If NULL, monitors may be inferred by .fresh_build() or taken from the builder output.

nchains

Integer; number of chains. If nchains > 1 and the builder supports chain_id, chains are run in parallel (PSOCK).

opts

List of options as returned by samOptiPro_options() (e.g. seed, export strategy handled by .fresh_build()).

Value

A list with components:

samples

Posterior draws (typically a coda::mcmc.list in parallel mode).

samples2

Optional secondary draws (as produced by .run_and_collect()).

runtime_s

Runtime (seconds) of the sampling phase; slowest chain in parallel mode.

conf

MCMC configuration (nimbleMCMCconf) in sequential mode; NULL in parallel.

hmc_applied

Logical; TRUE if HMC/NUTS configuration succeeded (all chains in parallel).

conf_by_chain

List of per-chain MCMC configurations (parallel mode); also attached as an attribute.

Details

Runtime is measured for the sampling phase only (around runMCMC()), not for model/MCMC compilation. In parallel mode, runtime_s is the maximum runtime across chains (slowest chain). Because each chain has its own MCMC configuration (after HMC + slice fallback), conf is returned in sequential mode only.

Examples

if (FALSE) { # \dontrun{
res <- run_hmc_all_nodes(
  build_fn  = build_M,
  niter     = 2000,
  nburnin   = 500,
  thin      = 2,
  monitors  = c("N", "logit_theta"),
  nchains   = 4
)
} # }