#include <triqs/stat/log_binning.hpp>

Detailed Description

template<AccCompatible T>
class triqs::stat::log_binning< T >

Logarithmic binning accumulator.

Estimate the autocorrelation time of the samples by calculating the standard error of the data binned with different bin sizes. For correlated samples, the error should increase as the bin size increases up to the point where the bin size is large enough such that the binned samples become statistically independent.

Logarithmic binning uses bin sizes that are powers of two, i.e. \( 1, 2, 4, 8, 16, \dots \), up to an optional user-defined maximum.

Depending on the given parameter max_n_bins, which is given during construction, logarithmic binning is done in the following way:

max_n_bins == 1: Welford-only mode — only the running mean and standard error of the unbinned samples are tracked. No estimate of the autocorrelation time is available.
max_n_bins >= 2: The maximum number of bins \( N \) is restricted. The bin size of the last bin is \(2^{N - 1} \).
max_n_bins == -1: The maximum number of bins is unbounded. A new bin is created as soon as the total number of accumulated samples is equal to a power of 2. The bin size of the new bin is \( 2^{N - 1} \), where \( N \) is the number of bins after the new one has been added.

Any other value of max_n_bins is rejected at construction. To toggle accumulation on/off at runtime, wrap the accumulator in std::optional<log_binning>.

See log_binning::operator<< for details on how the data is accumulated.

Note: Underestimating the autocorrelation time and a lack of ergodicity are common sources of systematic errors in Monte Carlo simulations. Provided the computational and memory costs are acceptable, it is advisable to always turn on logarithmic binning to check that \( \tau \) was estimated correctly and acts as expected.

Template Parameters

T	triqs::stat::AccCompatible type.

Definition at line 78 of file log_binning.hpp.

Public Types
using	real_t = get_real_t<T>
	Real type of the accumulated data type.
using	value_t = T
	Type of the accumulated data.

Public Member Functions
	log_binning ()=default
	Default construct a logarithmic binning accumulator.
	log_binning (T const &sample, int max_n_bins)
	Construct a logarithmic binning accumulator with a dummy sample and the maximum number of bins.
auto const &	bare_bins () const
	Get the bins that are used for accumulating the bare samples.
auto const &	bare_counts () const
	Get the number of samples currently in the bare bins.
long	count () const
	Get the total number of accumulated samples.
auto	effective_counts () const
	Get the number of effective samples accumulated in each bin.
bool	is_unbounded () const
	True if the accumulator was constructed with an unbounded number of bins.
long	max_n_bins () const
	Get the maximum number of bins.
auto const &	mean_bins () const
	Get the bins that store the mean data.
auto	mean_errors_and_taus (int min_samples=2) const
	Get the overall mean of the data as well as the estimated standard error, integrated autocorrelation time and effective number of samples for each bin.
auto	mean_errors_and_taus (mpi::communicator c, int min_samples=2) const
	Get the overall mean of the data as well as the estimated standard error, integrated autocorrelation time and effective number of samples for each bin on multiple MPI processes.
auto	mpi_all_reduce (mpi::communicator c) const
	Allreduce the accumulated data over multiple MPI processes.
long	n_bins () const
	Get the current number of bins.
template<typename U>
log_binning< T > &	operator<< (U const &x)
	Accumulate a new sample.
auto const &	var_bins () const
	Get the bins that store the sum of the squared deviations from the mean.

Static Public Member Functions
static std::string	hdf5_format ()
	Get the HDF5 format string.

Friends
void	h5_read (h5::group g, std::string const &name, log_binning &acc)
	Read a triqs::stat::log_binning accumulator from HDF5.
void	h5_write (h5::group g, std::string const &name, log_binning const &acc)
	Write a triqs::stat::log_binning accumulator to HDF5.

Constructor & Destructor Documentation

◆ log_binning() [1/2]

template<AccCompatible T>

triqs::stat::log_binning< T >::log_binning ( )

default

Default construct a logarithmic binning accumulator.

The accumulator is unbounded (max_n_bins is set to \( -1 \)). No memory is allocated for the bins until the first sample is added to the accumulator.

◆ log_binning() [2/2]

template<AccCompatible T>

triqs::stat::log_binning< T >::log_binning	(	T const &	sample,
		int	max_n_bins )

inline

Construct a logarithmic binning accumulator with a dummy sample and the maximum number of bins.

Parameters

sample	Dummy sample to determine which type is stored and accumulated in the bins.
max_n_bins	Maximum number of bins.

Definition at line 100 of file log_binning.hpp.

Member Function Documentation

◆ mean_errors_and_taus() [1/2]

template<AccCompatible T>

auto triqs::stat::log_binning< T >::mean_errors_and_taus ( int min_samples = 2 ) const

inlinenodiscard

Get the overall mean of the data as well as the estimated standard error, integrated autocorrelation time and effective number of samples for each bin.

The standard error, \( s_n \), is defined as the square root of the variance

\[ s_n^2 = \frac{1}{k_n (k_n - 1)} \sum_{i=1}^{k_n} (y_i - m_n)^2 = \frac{q_n}{k_n (k_n - 1)} \; , \]

where \( m_n \) and \( q_n \) is the mean and the sum of the squared deviations from the mean currently stored in the accumulator for each bin \( n \), respectively. \( k_n \) is the number of effective samples in a bin and \( y_i \) is an effective sample.

The integrated autocorrelation time, \( \tau_n \), can then be estimated as

\[ \tau_n = \frac{1}{2} \left( \frac{s_n^2}{s_0^2} - 1 \right) \; . \]

\( \tau_n \) and \( s_n \) are expected to increase with \( n \) and saturate for large enough bin sizes. At this point, the effective samples in the bins become statistically independent.

Only bins with at least min_samples effective samples are considered for error and autocorrelation time estimation.

Parameters

min_samples Minimum number of effective samples required ( \( \geq 2 \)).

Returns: std::tuple containing the overall mean as well as the standard errors, integrated autocorrelation times and effective number of samples for each bin.

Definition at line 274 of file log_binning.hpp.

◆ mean_errors_and_taus() [2/2]

template<AccCompatible T>

auto triqs::stat::log_binning< T >::mean_errors_and_taus	(	mpi::communicator	c,
		int	min_samples = 2 ) const

inlinenodiscard

Get the overall mean of the data as well as the estimated standard error, integrated autocorrelation time and effective number of samples for each bin on multiple MPI processes.

The data in each bin is first reduced across all MPI processes using log_binning::mpi_all_reduce, before the overall mean, standard error and integrated autocorrelation time are calculated for the reduced bins.

Only bins with at least min_samples effective samples after the reduction are considered for error and autocorrelation time estimation.

The results will be available on all MPI processes.

Parameters

c	MPI communicator.
min_samples	Minimum number of effective samples required ( \( \geq 2 \)).

Returns: std::tuple containing the overall mean as well as the standard errors, integrated autocorrelation times and effective number of samples for each reduced bin.

Definition at line 297 of file log_binning.hpp.

◆ mpi_all_reduce()

template<AccCompatible T>

auto triqs::stat::log_binning< T >::mpi_all_reduce ( mpi::communicator c ) const

inlinenodiscard

Allreduce the accumulated data over multiple MPI processes.

First the bins are resized to the maximum number of bins across all processes. Then the number of effective samples, the mean and sum of squared deviations from the mean are reduced for each bin separately.

Note: Any data in the bare bins is ignored.

Parameters

c	MPI communicator.

Returns: std::tuple containing the reduced mean bins, variance bins and number of effective samples for each bin.

Definition at line 314 of file log_binning.hpp.

◆ operator<<()

template<AccCompatible T>

template<typename U>

log_binning< T > & triqs::stat::log_binning< T >::operator<< ( U const & x )

inline

Accumulate a new sample.

Let \( x_i \) be the i^th sample that is currently being added to the accumulator.

For each bin \( n = 0, 1, \dots, N - 1 \), let us define the following quantities:

the bin size \( b_n = 2^n \),
the current number of effective samples \( k_n(i) = \lfloor i / b_n \rfloor \),
the current number of bare samples \( l_n(i) = i - k_n(i) b_n \),
the current sum of bare samples \( p_n(i) = \sum_{j=1}^{l_n(i)} x_{j + k_n(i) b_n} \),
the \( k_n(i) \) effective samples \( y_n[k_n(i)] = \frac{1}{b_n} \sum_{j=1}^{b_n} x_{j + k_n(i) b_n} \),
the current mean of the effective samples \( m_n[k_n(i)] = \frac{1}{k_n(i)} \sum_{j=1}^{k_n(i)} y_j \) and
the current sum of the squared deviations from the mean \( q_n[k_n(i)] = \sum_{j=1}^{k_n(i)} \left\{ y_n(j) - m_n[k_n(i)] \right\}^2 \).

The new data point is first added to the bare samples of each bin:

\[ p_n(i) = \begin{cases} p_n(i-1) + x_i & \text{if } 1 < l_n(i) \leq b_n \\ x_i & \text{if } l_n(i) = 1 \end{cases} \; . \]

If the number of bare samples is equal to the bin size, i.e. \( l_n(i) = b_n \), we take the mean of the accumulated bare samples to get the effective sample \( y_n[k_n(i)] = p_n(i) / b_n \). The effective sample is then added to the mean

\[ m_n[k_n(i)] = m_n[k_n(i) - 1] + \frac{ y_n[k_n(i)] - m_n[k_n(i) - 1]}{k} \]

and to the sum of squared deviations from the mean

\[ q_n[k_n(i)] = q_n[k_n(i) - 1] + \frac{k - 1}{k} \left\{ y_n[k_n(i)] - m_n[k_n(i) - 1] \right\}^2 \; . \]

In case, \( i = 2^{N - 1} \) and the maximum number of bins is not reached yet, a new bin with bin size \( 2^{N} \) will be added.

For more information, see e.g. Wikipedia or Chan, Golub, LeVeque. Am. Stat. 37, 242 (1983).

Template Parameters

U	Type of the data point to be added to the accumulator.

Parameters

x	Data point to be added to the accumulator.

Returns: Reference to this object.

Definition at line 148 of file log_binning.hpp.

◆ h5_read

template<AccCompatible T>

void h5_read	(	h5::group	g,
		std::string const &	name,
		log_binning< T > &	acc )

friend

Read a triqs::stat::log_binning accumulator from HDF5.

Parameters

g	h5::group containing the subgroup.
name	Name of the subgroup from which the accumulator will be read.
acc	Accumulator to be read into.

Definition at line 368 of file log_binning.hpp.

◆ h5_write

template<AccCompatible T>

void h5_write	(	h5::group	g,
		std::string const &	name,
		log_binning< T > const &	acc )

friend

Write a triqs::stat::log_binning accumulator to HDF5.

Parameters

g	h5::group in which the subgroup is created.
name	Name of the subgroup to which the accumulator will be written.
acc	Accumulator to be written.

Definition at line 350 of file log_binning.hpp.

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

triqs/stat/log_binning.hpp

Detailed Description

Public Types

Public Member Functions

Static Public Member Functions

Friends

Constructor & Destructor Documentation

◆ log_binning() [1/2]

◆ log_binning() [2/2]

Member Function Documentation

◆ mean_errors_and_taus() [1/2]

◆ mean_errors_and_taus() [2/2]

◆ mpi_all_reduce()

◆ operator<<()

Friends And Related Symbol Documentation

◆ h5_read

◆ h5_write