No-U-Turn Sampler (NUTS). More...

#include <nuts.hpp>

Inheritance diagram for stan::mcmc::nuts< BaseRNG >:

Public Member Functions
	nuts (stan::model::prob_grad &model, int maxdepth=10, double epsilon=-1, double epsilon_pm=0.0, bool epsilon_adapt=true, double delta=0.6, double gamma=0.05, BaseRNG base_rng=BaseRNG(std::time(0)), const std::vector< double > params_r=0, const std::vector< int > params_i=0)
	Construct a No-U-Turn Sampler (NUTS) for the specified model, using the specified step size and number of leapfrog steps, with the specified random seed for randomization. More...

	~nuts ()
	Destructor. More...

virtual sample	next_impl ()
	Return the next sample. More...

virtual void	write_sampler_param_names (std::ostream &o)
	Write out any sampler-specific parameter names for output. More...

virtual void	write_sampler_params (std::ostream &o)
	Write out any sampler-specific parameters for output. More...

virtual void	get_sampler_param_names (std::vector< std::string > &names)
	Get any sampler-specific parameter namess. More...

virtual void	get_sampler_params (std::vector< double > &values)
	Get any sampler-specific parameters. More...

void	build_tree (const std::vector< double > &x, const std::vector< double > &m, const std::vector< double > &grad, double u, int direction, int depth, double H0, std::vector< double > &xminus, std::vector< double > &mminus, std::vector< double > &gradminus, std::vector< double > &xplus, std::vector< double > &mplus, std::vector< double > &gradplus, std::vector< double > &newx, std::vector< double > &newgrad, double &newlogp, int &nvalid, bool &criterion, double &prob_sum, int &n_considered)
	The core recursion in NUTS. More...

Public Member Functions inherited from stan::mcmc::hmc_base< boost::mt19937 >
	hmc_base (stan::model::prob_grad &model, double epsilon=-1, double epsilon_pm=0.0, bool epsilon_adapt=true, double delta=0.651, double gamma=0.05, boost::mt19937 rand_int=boost::mt19937(std::time(0)), const std::vector< double > params_r=0, const std::vector< int > params_i=0)
	Construct a base HMC sampler. More...

virtual	~hmc_base ()

virtual void	set_params (const std::vector< double > &x, const std::vector< int > &z)
	Sets the model real and integer parameters to the specified values. More...

void	set_params_r (const std::vector< double > &x)
	Sets the model real parameters to the specified values and update gradients and log probability to match. More...

void	set_params_i (const std::vector< int > &z)
	Sets the model integer parameters to the specified values and update gradients and log probability to match. More...

bool	varying_epsilon ()

virtual void	adapt_off ()
	Turn off parameter adaptation. More...

virtual void	get_parameters (std::vector< double > &params)
	Write the step size into position 1 of the specified vector. More...

Public Member Functions inherited from stan::mcmc::adaptive_sampler
	adaptive_sampler (bool adapt, std::ostream error_msgs=0, std::ostream output_msgs=0)
	Constructs an adaptive sampler with specified adaptation status. More...

virtual	~adaptive_sampler ()
	Destructor. More...

void	set_error_stream (std::ostream &error_msgs)
	Set the stream into which errors will be written as the sampler runs. More...

void	unset_error_stream ()
	Unset the stream into which errors are written to 0 so that error messages are ignored. More...

void	set_output_stream (std::ostream &output_msgs)
	Set the stream into which output will be written as the sampler runs. More...

void	unset_output_stream ()
	Unset the stream into which errors are written to 0 so that output messages are ignored. More...

sample	next ()
	Returns the next sample from this sampler. More...

double	mean_stat ()
	Returns the value of the statistic we are trying to coerce. More...

void	set_mean_stat (double v)
	Sets the mean statistic to the specified value. More...

void	update_mean_stat (double avg_eta, double adapt_stat)
	Updates the mean statistic given the specified adaptation statistic and weighting. More...

unsigned int	nfevals ()
	Returns the number of times that the (possibly unnormalized) log probability function has been evaluated by this sampler. More...

void	nfevals_plus_eq (int n)
	Add the specified number of evaluations to the number of function evaluations. More...

int	n_steps ()
	Return the number of iterations for this sampler. More...

int	n_adapt_steps ()
	Return how many iterations parameter adaptation has happened for. More...

virtual void	adapt_on ()
	Turn on parameter adaptation. More...

bool	adapting ()
	Return whether or not parameter adaptation is on. More...

virtual void	write_adaptation_params (std::ostream &o)
	Use this method to write the adaptation parameters into the output. More...

Additional Inherited Members
Protected Member Functions inherited from stan::mcmc::hmc_base< boost::mt19937 >
virtual void	find_reasonable_parameters ()
	Search for a roughly reasonable (within a factor of 2) setting of the step size epsilon. More...

void	adaptation_init (double epsilon_scale)

Protected Attributes inherited from stan::mcmc::hmc_base< boost::mt19937 >
stan::model::prob_grad &	_model

double	_epsilon

double	_epsilon_pm

double	_epsilon_last

bool	_epsilon_adapt

const double	_delta

const double	_gamma

DualAverage	_da

boost::mt19937	_rand_int

boost::variate_generator< boost::mt19937 &, boost::normal_distribution<> >	_rand_unit_norm

boost::uniform_01< boost::mt19937 & >	_rand_uniform_01

std::vector< double >	_x

std::vector< int >	_z

std::vector< double >	_g

double	_logp

Protected Attributes inherited from stan::mcmc::adaptive_sampler
bool	_adapt

unsigned int	_n_steps

int	_n_adapt_steps

unsigned int	_nfevals

double	_mean_stat

std::ostream *	_error_msgs

std::ostream *	_output_msgs

Detailed Description

template<class BaseRNG = boost::mt19937>
class stan::mcmc::nuts< BaseRNG >

No-U-Turn Sampler (NUTS).

The NUTS sampler requires a probability model with the ability to compute gradients, characterized as an instance of prob_grad.

Definition at line 32 of file nuts.hpp.

Constructor & Destructor Documentation

◆ nuts()

template<class BaseRNG = boost::mt19937>

stan::mcmc::nuts< BaseRNG >::nuts	(	stan::model::prob_grad &	model,
		int	maxdepth = `10`,
		double	epsilon = `-1`,
		double	epsilon_pm = `0.0`,
		bool	epsilon_adapt = `true`,
		double	delta = `0.6`,
		double	gamma = `0.05`,
		BaseRNG	base_rng = `BaseRNG(std::time(0))`,
		const std::vector< double > *	params_r = `0`,
		const std::vector< int > *	params_i = `0`
	)

inline

Construct a No-U-Turn Sampler (NUTS) for the specified model, using the specified step size and number of leapfrog steps, with the specified random seed for randomization.

If the same seed is used twice, the series of samples should be the same. This property is most helpful for testing. If no random seed is specified, the std::time(0) function is called from the ctime library.

Parameters

model	Probability model with gradients.
maxdepth	Maximum depth for searching for a U-Turn. Default is 10.
epsilon	Optional (initial) Hamiltonian dynamics simulation step size. If not specified or set < 0, find_reasonable_parameters() will be called to initialize epsilon.
epsilon_pm	Plus/minus range for uniformly sampling epsilon around its value.
epsilon_adapt	True if epsilon is adapted during warmup.
delta	Optional target value between 0 and 1 used to tune epsilon. Lower delta => higher epsilon => more efficiency, unless epsilon gets too big in which case efficiency suffers. If not specified, defaults to the usually reasonable value of 0.6.
gamma	Gamma tuning parameter for dual averaging adaptation.
base_rng	Optional Seed for random number generator; if not specified, generate new seed based on system time.

Definition at line 89 of file nuts.hpp.

◆ ~nuts()

template<class BaseRNG = boost::mt19937>

stan::mcmc::nuts< BaseRNG >::~nuts ( )

inline

Destructor.

The implementation for this class is a no-op.

Definition at line 121 of file nuts.hpp.

Member Function Documentation

◆ build_tree()

template<class BaseRNG = boost::mt19937>

void stan::mcmc::nuts< BaseRNG >::build_tree	(	const std::vector< double > &	x,
		const std::vector< double > &	m,
		const std::vector< double > &	grad,
		double	u,
		int	direction,
		int	depth,
		double	H0,
		std::vector< double > &	xminus,
		std::vector< double > &	mminus,
		std::vector< double > &	gradminus,
		std::vector< double > &	xplus,
		std::vector< double > &	mplus,
		std::vector< double > &	gradplus,
		std::vector< double > &	newx,
		std::vector< double > &	newgrad,
		double &	newlogp,
		int &	nvalid,
		bool &	criterion,
		double &	prob_sum,
		int &	n_considered
	)

inline

The core recursion in NUTS.

Parameters

[in]	x	The position value to start from.
[in]	m	The momentum value to start from.
[in]	grad	The gradient at the initial position.
[in]	u	The slice variable.
[in]	direction	Simulate backwards if -1, forwards if 1.
[in]	depth	The depth of the tree to build—we'll run 2^depth leapfrog steps.
[in]	H0	The joint probability of the position-momentum we started from initially—used to compute statistic to adapt epsilon.
[out]	xminus	Returns the position of the backwardmost leaf of this subtree.
[out]	mminus	Returns the momentum of the backwardmost leaf of this subtree.
[out]	gradminus	Returns the gradient at xminus.
[out]	xplus	Returns the position of the forwardmost leaf of this subtree.
[out]	mplus	Returns the momentum of the forwardmost leaf of this subtree.
[out]	gradplus	Returns the gradient at xplus.
[out]	newx	Returns the new position sample selected from this subtree.
[out]	newgrad	Returns the gradient at the new sample selected from this subtree.
[out]	newlogp	Returns the log-probability of the new sample selected from this subtree.
[out]	nvalid	Returns the number of usable points in the subtree.
[out]	criterion	Returns true if the subtree is usable, false if not.
[out]	prob_sum	Returns the sum of the HMC acceptance probabilities at each point in the subtree.
[out]	n_considered	Returns the number of states in the subtree.

Definition at line 275 of file nuts.hpp.

◆ get_sampler_param_names()

template<class BaseRNG = boost::mt19937>

virtual void stan::mcmc::nuts< BaseRNG >::get_sampler_param_names ( std::vector< std::string > & names )

inlinevirtual

Get any sampler-specific parameter namess.

Parameters

[out] names Output vector to which param names are written.

Reimplemented from stan::mcmc::adaptive_sampler.

Definition at line 228 of file nuts.hpp.

◆ get_sampler_params()

template<class BaseRNG = boost::mt19937>

virtual void stan::mcmc::nuts< BaseRNG >::get_sampler_params ( std::vector< double > & values )

inlinevirtual

Get any sampler-specific parameters.

Parameters

[out] values Output vector to which params are written. All values are casted to type double. This function should match get_sampler_param_names.

Reimplemented from stan::mcmc::adaptive_sampler.

Definition at line 234 of file nuts.hpp.

◆ next_impl()

template<class BaseRNG = boost::mt19937>

virtual sample stan::mcmc::nuts< BaseRNG >::next_impl ( )

inlinevirtual

Return the next sample.

Returns: The next sample.

Implements stan::mcmc::adaptive_sampler.

Definition at line 128 of file nuts.hpp.

◆ write_sampler_param_names()

template<class BaseRNG = boost::mt19937>

virtual void stan::mcmc::nuts< BaseRNG >::write_sampler_param_names ( std::ostream & o )

inlinevirtual

Write out any sampler-specific parameter names for output.

This method must match write_sampler_params() in terms of number of parameters written.

Params should be writte starting with a comma, then the first parameter, then a comma, then the second parameter, ending on the final parameter.

The base class implementation is a no-op.

Parameters

[out] o Output stream to which param names are written.

Reimplemented from stan::mcmc::adaptive_sampler.

Definition at line 216 of file nuts.hpp.

◆ write_sampler_params()

template<class BaseRNG = boost::mt19937>

virtual void stan::mcmc::nuts< BaseRNG >::write_sampler_params ( std::ostream & o )

inlinevirtual

Write out any sampler-specific parameters for output.

This method must match write_sampler_param_names() in terms of number of parameters written.

Params should be writte starting with a comma, then the first parameter, then a comma, then the second parameter, ending on the final parameter.

The base class implementation is a no-op.

Parameters

[out] o Output stream to which params are written.

Reimplemented from stan::mcmc::adaptive_sampler.

Definition at line 222 of file nuts.hpp.

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

src/stan/mcmc/nuts.hpp

Public Member Functions

Additional Inherited Members

Detailed Description

template<class BaseRNG = boost::mt19937> class stan::mcmc::nuts< BaseRNG >

Constructor & Destructor Documentation

◆ nuts()

◆ ~nuts()

Member Function Documentation

◆ build_tree()

◆ get_sampler_param_names()

◆ get_sampler_params()

◆ next_impl()

◆ write_sampler_param_names()

◆ write_sampler_params()

template<class BaseRNG = boost::mt19937>
class stan::mcmc::nuts< BaseRNG >