chainBundle< T > Class Template Reference

#include <chainBundle.hpp>

List of all members.

Public Member Functions
	chainBundle (Random &random)
	~chainBundle ()
int	nChains ()
	Return number of chains.
T *	chain (const int i)
	Return pointer to ith chain.
double	stepSize ()
	Return current stepsize.
double	nLeapfrog ()
	Return current number of leapfrog steps.
double	ESS (int i)
	Return the ith effective sample size.
double	minESS ()
	Return the smallest effective sample size.
vector< VectorXd > &	samples ()
	Return accumulated samples.
void	setVerbosity (const unsigned int v)
void	setNumSubsample (const int n)
	Set number of HMC transitions per sample.
void	setNumLeapfrog (const int n)
	Set number of leapfrog steps.
void	setWindowSize (const int n)
	Set reject/accept window size.
void	setStepSize (const double s)
	Set stepsize.
void	setStepSizeJitter (const double j)
	Set valid step size jitter, as a fraction of the stepsize.
void	setStepSizeJerk (const double j)
	Set valid step size jerk, as a fraction of the stepsize.
void	setProbStepSizeJerk (const double p)
	Set valid step size jitter, as a fraction of the stepsize.
void	setTemperAlpha (const double a)
	Set HMC tempering parameter.
void	setAdaptIntTime (double t)
	Set target integration time for stepsize adaptation.
void	setAdaptTargetAccept (double a)
	Set target accept rate for stepsize adaptation.
void	setAdaptMaxLeapfrog (int n)
	Set maximum number of leapfrog steps for stepsize adaptation.
void	storeSamples (const bool store=true)
	Set sample storage flag.
void	setMaxLagDisplay (int n)
	Set maximum displayed lag.
void	setMaxLagCalc (int n)
	Set maximum calculated lag.
void	useExternalMoments (VectorXd &mean, VectorXd &var)
void	addChain (T *object)
	Add a new chain to the bundle.
void	evolve (T *chain, const double epsilon)
void	verboseEvolve (T *chain, const double epsilon)
void	engageAdaptation ()
	Engage dual-averaging stepsize adaptation.
void	disengageAdaptation ()
	Disengage dual-averaging stepsize adaptation.
void	initAdaptation ()
void	updateAdaptation (double metropolisProb)
void	transition ()
	Transition all chains currently in the bundle.
void	transition (int i)
bool	transition (T *chain)
void	saveTrajectory (std::ofstream &outputFile, const int i=0)
void	checkIntError (const int i, const int N, const int f=1)
void	seed (const double min, const double max)
void	seed (const int i, const double min, const double max)
void	burn (const int nBurn=100, const int nCheck=100, const double minR=1.1, const bool verbose=true)
void	clearSamples ()
	Clear all stored samples.
void	computeSummaryStats (const int b, const bool verbose=true, std::ofstream *outputFile=NULL)
Protected Member Functions
virtual bool	fConstraint (T *chain)
	Does the chain satisfy all defined constraints?
virtual const VectorXd &	fNormal (T *chain)
	Return the normal to the constraint surface.
double	fLogSumExp (double a, double b)
Protected Attributes
bool	mStoreSamples
	Sample storage flag.
bool	mAdaptStepSize
	Step-size adaptation flag.
bool	mRefStats
	Reference statistics flag.
bool	mChar
	Burn in completion flag.
bool	mConstraint
	Constraint satisfaction flag.
bool	mUseExternalMoments
	External moments for autocorrelation calculation flag.
unsigned int	mVerbosity
	Verbosity level.
Random	mRandom
	Mersenne twistor pseudo-random number generator.
int	mNumSubsample
	Number of HMC transitions per sample.
int	mNumLeapfrog
	Number of leapfrog steps.
int	mWindowSize
	Size of reject/accept windows.
double	mStepSize
	Nominal leapfrog stepsize.
double	mStepSizeJitter
	Stepsize jitter, as fraction of current stepsize.
double	mStepSizeJerk
	Stepsize jerk, as fraction of current stepsize.
double	mProbStepSizeJerk
	Probability of a stepsize jerk instead of the usual jitter.
int	mNumFixedPoint
	Number of fixed point iterations for implicit leapfrog updates.
double	mTemperAlpha
	Tempering parameter.
double	mAdaptTargetAccept
	Stepsize adaptation target accept probability.
double	mAdaptIntTime
	Stepsize adaptation target integration time.
int	mAdaptMaxLeapfrog
	Stepsize adaptation maximum number of leapfrog steps.
double	mAdaptMu
	Stepsize adaptation mu.
double	mAdaptLogEpsBar
	Stepsize adaptation epsilon average.
double	mAdaptHBar
	Stepsize adaptation H average.
double	mAdaptCounter
	Stepsize adaptation counter.
double	mAdaptGamma
	Stepsize adaptation shrinkage parameter.
double	mAdaptKappa
	Stepsize adaptation decay parameter.
double	mAdaptT0
	Stepsize adaptation initialization parameter.
int	mNumSamples
	Total number of computed samples.
vector< VectorXd >	mSamples
	Stored samples.
vector< double >	mSampleE
	Stored sample potential energies.
int	mMaxLagDisplay
	Maximum lag to display/save.
int	mMaxLagCalc
	Maximum lag used in calculation of autocorrelations.
VectorXd	mESS
	Vector of effective sample sizes, computed in computeSummaryStats()
VectorXd *	mExternalMean
	External mean for calculating the autocorrelations.
VectorXd *	mExternalVar
	External variance for calculating the autocorrelations.
vector< T * >	mChains
	Vector of baseChain pointers.
vector< T * >::iterator	mIt
	Vector iterator.

---

Detailed Description

template<typename T>
class chainBundle< T >

Author:

Michael Betancourt

Container for an ensemble of Markov chains, including functionality for constrainted Hamiltonian Monte Carlo transitions, convergence diagnostics, and sample analysis.

See chainBundle::evolve() for details on the symplectic integrator used for the Hamiltonian evolution.

Examples:

examples/main.cpp.

---

Constructor & Destructor Documentation

template<typename T >

chainBundle< T >::chainBundle

(

Random &

random

)

[explicit]

Constructor

Parameters:

random

Pointer to externally instantiated random number generator

See also:

~chainBundle()

template<typename T >

chainBundle< T >::~chainBundle

(

)

Destructor

See also:

chainBundle()

---

Member Function Documentation

template<typename T >

void chainBundle< T >::burn	(	const int	nBurn = 100,
		const int	nCheck = 100,
		const double	minR = 1.1,
		const bool	verbose = true
	)

Burn in all chains until the Gelman-Rubin convergence critieria has been satisfied

Gelman, A. Inference and monitoring convergence, "Markov Chain Monte Carlo in Practice" (1996) Chapman & Hall/CRC, New York

Parameters:

nBurn	Number of burn in iterations
nCheck	Number of samples for diagnosing burn in
minR	Minimum Gelman-Rubin statistic
verbose	Set verbose output, defaults to true

template<typename T >

void chainBundle< T >::checkIntError	(	const int	i,
		const int	N,
		const int	f = 1
	)

Check the accumulated error in the symplectic integrator implemented in the ith chain by evolving the chain n time steps, displaying the error every f steps.

Parameters:

i	Index of the chain
N	Number of time steps
f	Frequncy of output

template<typename T >

void chainBundle< T >::computeSummaryStats	(	const int	b,
		const bool	verbose = true,
		std::ofstream *	outputFile = NULL
	)

Compute summary statistics for the accumulated samples, averaged into batches of size b. If a pointer to an output file is passed then the file is filled with batch and autocorrelation information ready for parsing with the included gnuplot script, plotTrace.

Note that the Monte Carlo Standard Error assumes independent batches.

/param ref Index of chain whose mean and variance will be used in computing the autocorrelations /param b Number of samples to be averaged into a single batch /param verbose Flag for verbose diagnostic output /param outputFile Pointer to an external ofstream instance for optional text output

template<typename T >

void chainBundle< T >::evolve	(	T *	chain,
		const double	epsilon
	)

Evolve the input Hamiltonian through a time epsilon assuming a splitting of the Hamiltonian of the form

where

and

are the kinetic and potential Poisson operators, respectively, and is any constraint potential operator. Note that this implementation assumes that the constraint potential is infinitely large so that vanishes when the constraints are violated.

Parameters:

chain	Input Hamiltonian chain
epsilon	Time step

template<typename T >

double chainBundle< T >::fLogSumExp	(	double	a,
		double	b
	)		[protected]

Compute the logarithm of the sum of two exponentials, param a Argument of one exponential param b Argument of the second exponential return logarithm of the summed exponentials

template<typename T >

void chainBundle< T >::initAdaptation

(

)

Initialize the dual averaging stepsize adaptation parameters, and the number of leapfrog steps to ensure a proper integrationt time initialization

template<typename T >

void chainBundle< T >::saveTrajectory	(	std::ofstream &	outputFile,
		const int	i = 0
	)

Compute a trajectory for the ith chain, using the current step size and number of steps, saving the results to outputFile

Parameters:

outputFile	File to which the output is written
i	Index of the chain

template<typename T >

void chainBundle< T >::seed	(	const int	i,
		const double	min,
		const double	max
	)

Seed the ith component of the feature space for all chains

Parameters:

i	The selected component of the feature space
min	Minimum bound for the ith component
max	Maximum bound for the ith component

template<typename T >

void chainBundle< T >::seed	(	const double	min,
		const double	max
	)

Seed all chains, using the same bounds for all components

Parameters:

min	Minimum bound for all components
max	Maximum bound for all components

template<typename T>

void chainBundle< T >::setVerbosity

(

const unsigned int

v

)

[inline]

Set verbosity of transition output 0 : No output 1 : NaN warnings 2 : Above plus initial and final states along with acceptance information

template<typename T >

void chainBundle< T >::transition

(

int

i

)

Transition the ith chain in the bundle

Parameters:

i	Index of the chain

template<typename T >

bool chainBundle< T >::transition

(

T *

chain

)

Generate nNumSubsample consecutive transitions from the input chain using constrained Hamiltonian Monte Carlo, storing the final state as a sample if desired. Note that any state with a NaN is immediately rejected as the probability of transitions to and from such states are defined to be zero.

Parameters:

chain

Input Markov chain

Returns:

Was the final proposal accepted?

template<typename T >

void chainBundle< T >::updateAdaptation

(

double

metropolisProb

)

Update the dual averaging stepsize adaptation

Parameters:

metropolisProb

Acceptance probability current proposal

template<typename T >

void chainBundle< T >::verboseEvolve	(	T *	chain,
		const double	epsilon
	)

Evolve the input Hamiltonian through a time epsilon, displaying the variation of the Hamiltonian after each update.

See also:

evolve

Parameters:

chain	Input Hamiltonian chain
epsilon	Time step

---

The documentation for this class was generated from the following file:

• base/chainBundle.hpp