An abstract base class for adaptive samplers. More...

#include <adaptive_sampler.hpp>

Inheritance diagram for stan::mcmc::adaptive_sampler:

Public Member Functions
	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...

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

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

virtual sample	next_impl ()=0
	Returns the next sample from this sampler. More...

virtual void	find_reasonable_parameters ()
	Find a reasonable initial setting for the adaptable parameters. More...

virtual void	get_parameters (std::vector< double > &params)
	Sets the specified parameter vector to the sequence of tunable parameters for 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...

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

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

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

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

virtual void	write_sampler_param_names (std::ostream &o)
	Write out any sampler-specific parameter names 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...

Protected Attributes
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

An abstract base class for adaptive samplers.

The adaptive_sampler abstract base class maintains the adaptation status, number of steps, as well as recording function evals and the mean statistic being optimized.

Definition at line 19 of file adaptive_sampler.hpp.

Constructor & Destructor Documentation

◆ adaptive_sampler()

stan::mcmc::adaptive_sampler::adaptive_sampler	(	bool	adapt,
		std::ostream *	error_msgs = `0`,
		std::ostream *	output_msgs = `0`
	)

inline

Constructs an adaptive sampler with specified adaptation status.

Parameters

adapt	Initial adaptation status.
error_msgs	Pointer to output stream for error messages.

Definition at line 40 of file adaptive_sampler.hpp.

◆ ~adaptive_sampler()

virtual stan::mcmc::adaptive_sampler::~adaptive_sampler ( )

inlinevirtual

Destructor.

Definition at line 55 of file adaptive_sampler.hpp.

Member Function Documentation

◆ adapt_off()

virtual void stan::mcmc::adaptive_sampler::adapt_off ( )

inlinevirtual

Turn off parameter adaption.

Reimplemented in stan::mcmc::hmc_base< BaseRNG >, stan::mcmc::hmc_base< boost::mt19937 >, and stan::mcmc::adaptive_cdhmc.

Definition at line 243 of file adaptive_sampler.hpp.

◆ adapt_on()

virtual void stan::mcmc::adaptive_sampler::adapt_on ( )

inlinevirtual

Turn on parameter adaptation.

Definition at line 236 of file adaptive_sampler.hpp.

◆ adapting()

bool stan::mcmc::adaptive_sampler::adapting ( )

inline

Return whether or not parameter adaptation is on.

Returns: Whether or not parameter adaptation is on.

Definition at line 252 of file adaptive_sampler.hpp.

◆ find_reasonable_parameters()

virtual void stan::mcmc::adaptive_sampler::find_reasonable_parameters ( )

inlinevirtual

Find a reasonable initial setting for the adaptable parameters.

May not be applicable/implemented for all samplers.

The default implementation is a no-op.

Reimplemented in stan::mcmc::hmc_base< BaseRNG >, stan::mcmc::hmc_base< boost::mt19937 >, and stan::mcmc::adaptive_cdhmc.

Definition at line 140 of file adaptive_sampler.hpp.

◆ get_parameters()

virtual void stan::mcmc::adaptive_sampler::get_parameters ( std::vector< double > & params )

inlinevirtual

Sets the specified parameter vector to the sequence of tunable parameters for this sampler.

The default implementation sets the specified vector to empty.

Parameters

[out] params Where to store the returned parameters.

Reimplemented in stan::mcmc::hmc_base< BaseRNG >, stan::mcmc::hmc_base< boost::mt19937 >, and stan::mcmc::adaptive_cdhmc.

Definition at line 151 of file adaptive_sampler.hpp.

◆ get_sampler_param_names()

virtual void stan::mcmc::adaptive_sampler::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 in stan::mcmc::nuts_diag< BaseRNG >, stan::mcmc::nuts< BaseRNG >, and stan::mcmc::adaptive_hmc< BaseRNG >.

Definition at line 310 of file adaptive_sampler.hpp.

◆ get_sampler_params()

virtual void stan::mcmc::adaptive_sampler::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 in stan::mcmc::nuts_diag< BaseRNG >, stan::mcmc::nuts< BaseRNG >, and stan::mcmc::adaptive_hmc< BaseRNG >.

Definition at line 321 of file adaptive_sampler.hpp.

◆ mean_stat()

double stan::mcmc::adaptive_sampler::mean_stat ( )

inline

Returns the value of the statistic we are trying to coerce.

For example, if we are trying to set the average acceptance probability of HMC to 0.651 then this method will return the realized acceptance probability averaged across all samples so far.

Returns: Mean observed target statistic for adaptation.

Definition at line 164 of file adaptive_sampler.hpp.

◆ n_adapt_steps()

int stan::mcmc::adaptive_sampler::n_adapt_steps ( )

inline

Return how many iterations parameter adaptation has happened for.

Returns: How many iterations parameter adaptation has happened for.

Definition at line 229 of file adaptive_sampler.hpp.

◆ n_steps()

int stan::mcmc::adaptive_sampler::n_steps ( )

inline

Return the number of iterations for this sampler.

Returns: Number of iterations.

Definition at line 220 of file adaptive_sampler.hpp.

◆ next()

sample stan::mcmc::adaptive_sampler::next ( )

inline

Returns the next sample from this sampler.

This method increments the count of steps with and without adaptation and calls the virtual next_impl() to produce a result.

Returns: Next sample.

Definition at line 117 of file adaptive_sampler.hpp.

◆ next_impl()

virtual sample stan::mcmc::adaptive_sampler::next_impl ( )

pure virtual

Returns the next sample from this sampler.

This pure virtual method must be implemented by concrete subclasses to produce the next sample.

Returns: Next sample.

Implemented in stan::mcmc::nuts_diag< BaseRNG >, stan::mcmc::nuts< BaseRNG >, stan::mcmc::hmc, stan::mcmc::adaptive_hmc< BaseRNG >, and stan::mcmc::adaptive_cdhmc.

◆ nfevals()

unsigned int stan::mcmc::adaptive_sampler::nfevals ( )

inline

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

This is a useful alternative to wall time in evaluating the relative performance of different algorithms. However, it is up to the sampler implementation to be sure to actually keep track of this.

Returns: Number of log probability function evaluations.

Definition at line 201 of file adaptive_sampler.hpp.

◆ nfevals_plus_eq()

void stan::mcmc::adaptive_sampler::nfevals_plus_eq ( int n )

inline

Add the specified number of evaluations to the number of function evaluations.

Parameters

n	Number of evaluations to add.

Definition at line 211 of file adaptive_sampler.hpp.

◆ set_error_stream()

void stan::mcmc::adaptive_sampler::set_error_stream ( std::ostream & error_msgs )

inline

Set the stream into which errors will be written as the sampler runs.

Parameters

error_msgs Stream to which error messages are written.

Definition at line 64 of file adaptive_sampler.hpp.

◆ set_mean_stat()

void stan::mcmc::adaptive_sampler::set_mean_stat ( double v )

inline

Sets the mean statistic to the specified value.

Parameters

v	New value of mean statistic.

Definition at line 173 of file adaptive_sampler.hpp.

◆ set_output_stream()

void stan::mcmc::adaptive_sampler::set_output_stream ( std::ostream & output_msgs )

inline

Set the stream into which output will be written as the sampler runs.

Parameters

error_msgs Stream to which output messages are written.

Definition at line 83 of file adaptive_sampler.hpp.

◆ set_params()

virtual void stan::mcmc::adaptive_sampler::set_params	(	const std::vector< double > &	x,
		const std::vector< int > &	z
	)

pure virtual

Set the model real and integer parameters to the specified values.

This method will typically be used to set the parameters by the client of this class after initialization.

Parameters

x	Real parameters.
z	Integer parameters.

Implemented in stan::mcmc::hmc_base< BaseRNG >, stan::mcmc::hmc_base< boost::mt19937 >, stan::mcmc::hmc, and stan::mcmc::adaptive_cdhmc.

◆ unset_error_stream()

void stan::mcmc::adaptive_sampler::unset_error_stream ( )

inline

Unset the stream into which errors are written to 0 so that error messages are ignored.

Definition at line 72 of file adaptive_sampler.hpp.

◆ unset_output_stream()

void stan::mcmc::adaptive_sampler::unset_output_stream ( )

inline

Unset the stream into which errors are written to 0 so that output messages are ignored.

Definition at line 91 of file adaptive_sampler.hpp.

◆ update_mean_stat()

void stan::mcmc::adaptive_sampler::update_mean_stat	(	double	avg_eta,
		double	adapt_stat
	)

inline

Updates the mean statistic given the specified adaptation statistic and weighting.

The behavior is equivalent to doing

mean_stat += avg_eta * adapt_stat + (1 - avg_eta) * mean_stat.

Parameters

avg_eta	Weight of adaptation statistic.
adapt_stat	Adaptation statistic.

Definition at line 186 of file adaptive_sampler.hpp.

◆ write_adaptation_params()

virtual void stan::mcmc::adaptive_sampler::write_adaptation_params ( std::ostream & o )

inlinevirtual

Use this method to write the adaptation parameters into the output.

These should be written as one or more comment lines, each starting with a pound (#) character.

Parameters

o	Output stream to which adaptation information is written.

Reimplemented in stan::mcmc::nuts_diag< BaseRNG >.

Definition at line 283 of file adaptive_sampler.hpp.

◆ write_sampler_param_names()

virtual void stan::mcmc::adaptive_sampler::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 in stan::mcmc::nuts_diag< BaseRNG >, stan::mcmc::nuts< BaseRNG >, and stan::mcmc::adaptive_hmc< BaseRNG >.

Definition at line 301 of file adaptive_sampler.hpp.

◆ write_sampler_params()

virtual void stan::mcmc::adaptive_sampler::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 in stan::mcmc::nuts_diag< BaseRNG >, stan::mcmc::nuts< BaseRNG >, and stan::mcmc::adaptive_hmc< BaseRNG >.

Definition at line 271 of file adaptive_sampler.hpp.

Member Data Documentation

◆ _adapt

bool stan::mcmc::adaptive_sampler::_adapt

protected

Definition at line 22 of file adaptive_sampler.hpp.

◆ _error_msgs

std::ostream* stan::mcmc::adaptive_sampler::_error_msgs

protected

Definition at line 27 of file adaptive_sampler.hpp.

◆ _mean_stat

double stan::mcmc::adaptive_sampler::_mean_stat

protected

Definition at line 26 of file adaptive_sampler.hpp.

◆ _n_adapt_steps

int stan::mcmc::adaptive_sampler::_n_adapt_steps

protected

Definition at line 24 of file adaptive_sampler.hpp.

◆ _n_steps

unsigned int stan::mcmc::adaptive_sampler::_n_steps

protected

Definition at line 23 of file adaptive_sampler.hpp.

◆ _nfevals

unsigned int stan::mcmc::adaptive_sampler::_nfevals

protected

Definition at line 25 of file adaptive_sampler.hpp.

◆ _output_msgs

std::ostream* stan::mcmc::adaptive_sampler::_output_msgs

protected

Definition at line 28 of file adaptive_sampler.hpp.

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

src/stan/mcmc/adaptive_sampler.hpp

Public Member Functions

Protected Attributes

Detailed Description

Constructor & Destructor Documentation

◆ adaptive_sampler()

◆ ~adaptive_sampler()

Member Function Documentation

◆ adapt_off()

◆ adapt_on()

◆ adapting()

◆ find_reasonable_parameters()

◆ get_parameters()

◆ get_sampler_param_names()

◆ get_sampler_params()

◆ mean_stat()

◆ n_adapt_steps()

◆ n_steps()

◆ next()

◆ next_impl()

◆ nfevals()

◆ nfevals_plus_eq()

◆ set_error_stream()

◆ set_mean_stat()

◆ set_output_stream()

◆ set_params()

◆ unset_error_stream()

◆ unset_output_stream()

◆ update_mean_stat()

◆ write_adaptation_params()

◆ write_sampler_param_names()

◆ write_sampler_params()

Member Data Documentation

◆ _adapt

◆ _error_msgs

◆ _mean_stat

◆ _n_adapt_steps

◆ _n_steps

◆ _nfevals

◆ _output_msgs