pyhmc.hmc

pyhmc.hmc(fun, x0, n_samples=1000, args=(), display=False, n_steps=1, n_burn=0, persistence=False, decay=0.9, epsilon=0.2, window=1, return_logp=False, return_diagnostics=False, random_state=None)

Hamiltonian Monte Carlo sampler.

Uses a Hamiltonian / Hybrid Monte Carlo algorithm to sample from the distribution P ~ exp(f). The Markov chain starts at the point x0. The callable fun should return the log probability and gradient of the log probability of the target density.

Parameters:

fun : callable

A callable which takes a vector in the parameter spaces as input and returns the natural logarithm of the posterior probabily for that position, and gradient of the posterior probability with respect to the parameter vector, logp, grad = func(x, *args).

x0 : 1-d array

Starting point for the sampling Markov chain.

Returns:

samples : array, shape=(n_samples, n_params)

Array with data samples in rows.

logp : array, shape=(n_samples)

If return_logp is True, also returns an array of the log probability for all samples.

diagn : dict

If return_diagnostics is True, also returns a dictionary with diagnostic information (position, momentum and acceptance threshold) for each step of the chain in diagn['pos'], diagn['mom'] and diagn['acc'] respectively. All candidate states (including rejected ones) are stored in diagn['pos']. The diagn dictionary contains the following items:

pos : array

the position vectors of the dynamic process

mom : array

the momentum vectors of the dynamic process

acc : array

the acceptance thresholds

rej : float

the rejection rate

stp : float

the step size vectors

Other Parameters:  

n_samples : int

The number of samples retained from the Markov chain.

args : tuple

additional arguments to be passed to fun().

display : bool

If True, enables verbose display output. Default: False

n_steps : int

Defines the trajectory length between Metropolized steps (i.e. the number of leapfrog steps at each iteration before accept/reject).

n_burn : int

The number of samples omitted from the start of the chain as ‘burn in’.

persistence : bool

If True, momentum persistence is used (i.e. the momentum variables decay rather than being replaced). Default: False

decay : float, default=0.9

Defines the decay used when a persistent update of (leap-frog) momentum is used. Bounded to the interval [0, 1.).

epsilon : float, default=0.2.

The step adjustment used in the integrator. In physics-terms, this is the time step.

window : int, default=1

The size of the acceptance window (See [1], Section 5.4)

return_logp : bool, default=False

If True, the energy values for all samples are returned.

return_diagnostics : bool, default=False

If True, diagnostic information is returned (see below).

References

[R1]	Neal, Radford. “MCMC using Hamiltonian dynamics.” Handbook of Markov Chain Monte Carlo 2 (2011).