buildHMC: Build HMC

In nimbleHMC: Hamiltonian Monte Carlo and Other Gradient-Based MCMC Sampling Algorithms for 'nimble'

Build HMC

Description

Build an MCMC algorithm which applies HMC sampling to continuous-valued dimensions

Usage

buildHMC(
  model,
  nodes = character(),
  type = "NUTS",
  control = list(),
  print = TRUE,
  ...
)

Arguments

model	A nimble model, as returned by 'nimbleModel'. Alternatively, an MCMC configuration object, as returned by either 'configureHMC' or 'configureHMC'. See details.
nodes	A character vector of stochastic node names to be sampled. If an empty character vector is provided (the default), then all stochastic non-data nodes will be sampled. An HMC sampler will be applied to all continuous-valued non-data nodes, and nimble's default sampler will be assigned for all discrete-valued nodes.
type	A character string specifying the type of HMC sampling to apply, either "NUTS" or "NUTS_classic". See 'help(NUTS)' or 'help(NUTS_classic)' for details of each sampler. The default sampler type is "NUTS".
control	Optional named list of control parameters to be passed as the 'control' argument to the HMC sampler. See 'help(NUTS)' or 'help(NUTS_classic)' for details of the control list elements accepted by each sampler.
print	Logical argument specifying whether to print the montiors and samplers. Default is TRUE.
...	Other arguments that will be passed to 'configureHMC'.

Details

This is the most direct way to create an MCMC algorithm using HMC sampling in nimble. This will create a compilable, executable MCMC algorithm, with HMC sampling assigned to all continuous-valued model dimensions, and nimble's default sampler assigned to all discrete-valued dimensions. The ‘nodes' argument can be used to control which model nodes are assigned samplers. Use this if you don’t otherwise need to modify the MCMC configuration.

Either the 'NUTS_classic' or the 'NUTS' sampling can be applied, which is controled by the 'type' argument. Both implement variants of No-U-Turn HMC sampling, however the 'NUTS' sampler uses more modern adapatation techniques. See 'help(NUTS)' or 'help(NUTS_classic)' for details.

Note that when an MCMC configuration object is provided as the 'model' argument, then an executable MCMC algorithm is generated using the MCMC configuration that was provided - regardless of whether or not it specifies any HMC samplers.

Value

An object of class 'MCMC'.

Author(s)

Daniel Turek

See Also

addHMC configureHMC configureMCMC addSampler sampler_NUTS sampler_NUTS_classic

Examples

code <- nimbleCode({
    b0 ~ dnorm(0, 0.001)
    b1 ~ dnorm(0, 0.001)
    sigma ~ dunif(0, 10000)
    for(i in 1:N) {
        mu[i] <- b0 + b1 * x[i]
        y[i] ~ dnorm(mu[i], sd = sigma)
    }
})

N <- 10
constants <- list(N = N, x = 1:N)
data <- list(y = 1:N)
inits <- list(b0 = 1, b1 = 0.1, sigma = 1)
Rmodel <- nimbleModel(code, constants, data, inits, buildDerivs = TRUE)

Rmcmc <- buildHMC(Rmodel)

# Cmodel <- compileNimble(Rmodel)
# Cmcmc <- compileNimble(Rmcmc, project = Rmodel)
# samples <- runMCMC(Cmcmc)

nimbleHMC documentation built on Dec. 16, 2025, 9:09 a.m.