#include <triqs/stat/lin_binning.hpp>

Detailed Description

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

Linear binning accumulator.

Accumulate consecutive data points into either a fixed number of bins with a dynamic bin capacity or a growing number of bins with a fixed bin capacity.

The bins are stored and can be accessed at any time to perform further analysis, e.g. to estimate the error of the mean and the integrated autocorrelation time or to resample via the Jackknife method. The data stored in the bins is the mean of the accumulated samples in each bin.

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

max_n_bins >= 2: The data is accumulated into a fixed number of bins with initial capacity bin_capacity. Once all bins are full, i.e. they have accumulated bin_capacity data points, the bins are compressed by a factor of \( 2 \). This means that the data of two adjacent bins is averaged and stored in the first max_n_bins / 2 bins and that the bin capacity is doubled. Any left over data is put into the bin with index max_n_bins / 2. Before the compression is done, an optional callback function is called (usually to report autocorrelation times).
max_n_bins == -1: The data is accumulated into an unbounded number of bins with capacity bin_capacity. Once a bin is full, a new bin is created and appended.

Any other value of max_n_bins is rejected at construction. bin_capacity must always be \( \geq 1 \).

In addition to the linear bins, the accumulator further keeps track of the overall mean and the sum of the squared deviations from the mean. This is used to provide an estimate for the integrated autocorrelation time.

Note: For an unbinned running mean and standard error, use log_binning(sample, 1). To toggle accumulation on/off at runtime, wrap the accumulator in std::optional<lin_binning>.

Template Parameters

T	triqs::stat::AccCompatible type.

Definition at line 108 of file lin_binning.hpp.

Public Types
using	callback_t = std::function<void(lin_binning const &)>
	Type of the callback function that is called when bins are compressed.
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
	lin_binning ()=default
	Default construct a linear binning accumulator.
	lin_binning (T const &sample, long max_n_bins, long bin_capacity, callback_t callback={})
	Construct a linear binning accumulator with a dummy sample, the maximum number of bins, the bin capacity and a callback function.
long	bin_capacity () const
	Get the current bin capacity.
auto const &	bins () const
	Get all the bins containing data including the currently active bin.
auto const &	callback () const
	Get the callback function.
void	compress (int fac)
	Compress bins and increase bin capacity.
long	count () const
	Get the total number of accumulated samples.
std::vector< T >	full_bins () const
	Get only the full bins, i.e. bins that are filled up to the bin capacity.
bool	is_unbounded () const
	True if the accumulator was constructed with an unbounded number of bins.
long	last_bin_count () const
	Get the number of samples in the currently active bin.
long	max_n_bins () const
	Get the maximum number of bins.
auto const &	mean () const
	Get the overall mean.
auto	mean_error_and_tau () const
	Get the mean, its standard error and an estimate for the integrated autocorrelation time.
auto	mean_error_and_tau (mpi::communicator c) const
	Get the mean, its standard error and an estimate for the integrated autocorrelation time from accumulators on multiple MPI processes.
auto	mpi_all_gather (mpi::communicator c, bool same_capacity=true) const
	Allgather full bins from multiple MPI processes.
auto	mpi_all_reduce (mpi::communicator c) const
	Allreduce the overall mean and sum of squared deviations from the mean over multiple MPI processes.
long	n_bins () const
	Get the number of bins containing data including the currently active bin.
long	n_full_bins () const
	Get the number of full bins, i.e. bins that are filled up to the bin capacity.
template<typename U>
auto &	operator<< (U &&x)
	Accumulate a new sample.
auto const &	var_data () const
	Get the overall 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, lin_binning &acc)
	Read a triqs::stat::lin_binning accumulator from HDF5.
void	h5_write (h5::group g, std::string const &name, lin_binning const &acc)
	Write a triqs::stat::lin_binning accumulator to HDF5.

Constructor & Destructor Documentation

◆ lin_binning() [1/2]

template<AccCompatible T>

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

default

Default construct a linear binning accumulator.

The accumulator is unbounded (max_n_bins is set to \( -1 \)) with a bin capacity of \( 1 \) and no callback function. No memory is allocated for the bins until the first sample is added to the accumulator.

◆ lin_binning() [2/2]

template<AccCompatible T>

triqs::stat::lin_binning< T >::lin_binning	(	T const &	sample,
		long	max_n_bins,
		long	bin_capacity,
		callback_t	callback = {} )

inline

Construct a linear binning accumulator with a dummy sample, the maximum number of bins, the bin capacity and a callback function.

The callback function is called just before the bins are compressed. See also lin_binning::compress.

Parameters

sample	Dummy sample to determine which type is stored and accumulated in the bins.
max_n_bins	Maximum number of bins.
bin_capacity	Initial/Fixed capacity of each bin.
callback	Callback function of type lin_binning::callback_t.

Definition at line 138 of file lin_binning.hpp.

Member Function Documentation

◆ compress()

template<AccCompatible T>

void triqs::stat::lin_binning< T >::compress ( int fac )

inline

Compress bins and increase bin capacity.

The compression factor determines the number of adjacent bins that are merged together and the factor the bin capacity is multiplied with.

The data of the bins is averaged and stored in the first n_full_bins() / fac bins. If there are any left over bins, the data is put into a new bin, which becomes the currently active bin.

It does nothing, if linear binning is turned off, if there is only one bin or if the compression factor is less than 2.

Parameters

fac	Compression factor.

Definition at line 258 of file lin_binning.hpp.

◆ mean_error_and_tau() [1/2]

template<AccCompatible T>

auto triqs::stat::lin_binning< T >::mean_error_and_tau ( ) const

inlinenodiscard

Get the mean, its standard error and an estimate for the integrated autocorrelation time.

For definitions of the standard error and the integrated autocorrelation time, see log_binning::mean_errors_and_taus.

Returns: std::tuple containing the mean, its standard error and an estimate for the integrated autocorrelation time.

Definition at line 299 of file lin_binning.hpp.

◆ mean_error_and_tau() [2/2]

template<AccCompatible T>

auto triqs::stat::lin_binning< T >::mean_error_and_tau ( mpi::communicator c ) const

inlinenodiscard

Get the mean, its standard error and an estimate for the integrated autocorrelation time from accumulators on multiple MPI processes.

The overall mean and the sum of squared deviations from the mean are reduced and (full) bins are gathered from all MPI processes.

The results will be available on all MPI processes.

For definitions of the standard error and the integrated autocorrelation time, see log_binning::mean_errors_and_taus.

Parameters

c	MPI communicator.

Returns: std::tuple containing the reduced mean, its standard error and an estimate for the integrated autocorrelation time.

Definition at line 320 of file lin_binning.hpp.

◆ mpi_all_gather()

template<AccCompatible T>

auto triqs::stat::lin_binning< T >::mpi_all_gather	(	mpi::communicator	c,
		bool	same_capacity = true ) const

inlinenodiscard

Allgather full bins from multiple MPI processes.

Only full bins are considered. Furthermore, if same_capacity is set to true, the bins are compressed to have the same capacity on all processes and only those bins are then gathered.

Parameters

c	MPI communicator.
same_capacity	Compress bins to have the same capacity on all processes and only gather those bins.

Returns: std::vector containing the full (and compressed) bins from all processes.

Definition at line 361 of file lin_binning.hpp.

◆ mpi_all_reduce()

template<AccCompatible T>

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

inlinenodiscard

Allreduce the overall mean and sum of squared deviations from the mean over multiple MPI processes.

The results will be available on all MPI processes.

Parameters

c	MPI communicator.

Returns: std::tuple containing the reduced mean, sum of squared deviations from the mean and the total number of accumulated samples.

Definition at line 336 of file lin_binning.hpp.

◆ operator<<()

template<AccCompatible T>

template<typename U>

auto & triqs::stat::lin_binning< T >::operator<< ( U && x )

inline

Accumulate a new sample.

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

The data point is accumulated into the currently active bin. In case that the active bin is full and the maximum number of bins is reached, the bins are compressed by merging two adjacent bins into one (see lin_binning::compress). Otherwise, a new bin with the given data point is added.

Let \( m_n(k_n) \) be the stored mean of the data in the currently active bin \( n \) and let \( k_n \) be the number of data points in that bin. The mean in the bin is then updated as

\[ m_n(k_n) = m_n(k_n - 1) + \frac{x_i - m_n(k_n - 1)}{k_n} \; . \]

The overall mean \( m(N) \) is updated similarly, whereas the overall sum of the squared deviations is updated as

\[ q(N) = q(N - 1) + \frac{N - 1}{N} \left| x_i - m(N - 1) \right|^2 \; , \]

where \( N \) is the total number of data points accumulated.

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 214 of file lin_binning.hpp.

◆ h5_read

template<AccCompatible T>

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

friend

Read a triqs::stat::lin_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 415 of file lin_binning.hpp.

◆ h5_write

template<AccCompatible T>

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

friend

Write a triqs::stat::lin_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 396 of file lin_binning.hpp.

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

triqs/stat/lin_binning.hpp

Detailed Description

Public Types

Public Member Functions

Static Public Member Functions

Friends

Constructor & Destructor Documentation

◆ lin_binning() [1/2]

◆ lin_binning() [2/2]

Member Function Documentation

◆ compress()

◆ mean_error_and_tau() [1/2]

◆ mean_error_and_tau() [2/2]

◆ mpi_all_gather()

◆ mpi_all_reduce()

◆ operator<<()

Friends And Related Symbol Documentation

◆ h5_read

◆ h5_write