class HMCInfo(samples, acceptance_rate, updated_step_size, init_momentum, orig_hamiltonian, hamiltonian, orig_log_prob, log_prob)

Bases: object

Contains information about a sampling iteration by HMC. Users can get fine control of the sampling process by monitoring these statistics.


Attributes provided in this structure must be fetched together with the corresponding sampling operation and should not be fetched anywhere else. Otherwise you would get undefined behaviors.

  • samples – A dictionary of (string, Tensor) pairs. Samples generated by this HMC iteration.
  • acceptance_rate – A Tensor. The acceptance rate in this iteration.
  • updated_step_size – A Tensor. The updated step size (by adaptation) after this iteration.
  • init_momentum – A dictionary of (string, Tensor) pairs. The initial momentum for each latent variable in this sampling iteration.
  • orig_hamiltonian – A Tensor. The original hamiltonian at the beginning of the iteration.
  • hamiltonian – A Tensor. The current hamiltonian at the end of the iteration.
  • orig_log_prob – A Tensor. The log joint probability at the beginning position of the iteration.
  • log_prob – A Tensor. The current log joint probability at the end position of the iteration.
class HMC(step_size=1.0, n_leapfrogs=10, adapt_step_size=None, target_acceptance_rate=0.8, gamma=0.05, t0=100, kappa=0.75, adapt_mass=None, mass_collect_iters=10, mass_decay=0.99)

Hamiltonian Monte Carlo (Neal, 2011) with adaptation for stepsize (Hoffman & Gelman, 2014) and mass. The usage is similar with a Tensorflow optimizer.

The HMC class supports running multiple MCMC chains in parallel. To use the sampler, the user first creates a (list of) tensorflow Variable storing the initial sample, whose shape is chain axes + data axes. There can be arbitrary number of chain axes followed by arbitrary number of data axes. Then the user provides a log_joint function which returns a tensor of shape chain axes, which is the log joint density for each chain. Finally, the user runs the operation returned by sample(), which updates the sample stored in the Variable.


Currently we do not support invoking the sample() method multiple times per HMC class. Please declare one HMC class per each invoke of the sample() method.


When the adaptations are on, the sampler is not reversible. To guarantee current equilibrium, the user should only turn on the adaptations during the burn-in iterations, and turn them off when collecting samples. To achieve this, the best practice is to set adapt_step_size and adapt_mass to be placeholders and feed different values (True/False) when needed.

  • step_size – A 0-D float32 Tensor. Initial step size.
  • n_leapfrogs – A 0-D int32 Tensor. Number of leapfrog steps.
  • adapt_step_size – A bool Tensor, if set, indicating whether to adapt the step size.
  • target_acceptance_rate – A 0-D float32 Tensor. The desired acceptance rate for adapting the step size.
  • gamma – A 0-D float32 Tensor. Parameter for adapting the step size, see (Hoffman & Gelman, 2014).
  • t0 – A 0-D float32 Tensor. Parameter for adapting the step size, see (Hoffman & Gelman, 2014).
  • kappa – A 0-D float32 Tensor. Parameter for adapting the step size, see (Hoffman & Gelman, 2014).
  • adapt_mass – A bool Tensor, if set, indicating whether to adapt the mass, adapt_step_size must be set.
  • mass_collect_iters – A 0-D int32 Tensor. The beginning iteration to change the mass.
  • mass_decay – A 0-D float32 Tensor. The decay of computing exponential moving variance.
sample(meta_bn, observed, latent)

Return the sampling Operation that runs a HMC iteration and the statistics collected during it, given the log joint function (or a MetaBayesianNet instance), observed values and latent variables.

  • meta_bn – A function or a MetaBayesianNet instance. If it is a function, it accepts a dictionary argument of (string, Tensor) pairs, which are mappings from all StochasticTensor names in the model to their observed values. The function should return a Tensor, representing the log joint likelihood of the model. More conveniently, the user can also provide a MetaBayesianNet instance instead of directly providing a log_joint function. Then a log_joint function will be created so that log_joint(obs) = meta_bn.observe(**obs).log_joint().
  • observed – A dictionary of (string, Tensor) pairs. Mapping from names of observed StochasticTensor s to their values.
  • latent – A dictionary of (string, Variable) pairs. Mapping from names of latent StochasticTensor s to corresponding tensorflow Variables for storing their initial values and samples.

A Tensorflow Operation that runs a HMC iteration.


A HMCInfo instance that collects sampling statistics during an iteration.