Detailed Description

Free functions that compute the mean / sum and a corresponding error estimate from a range of samples.

Given a range of samples \( \{ x_i : i = 1, \ldots, N \} \), this group provides:

triqs::stat::mean and its MPI-aware counterpart triqs::stat::mean_mpi, which return either the simple sum \(\sum_i x_i \) or the arithmetic mean \( \overline{x} \) depending on the triqs::stat::mean_tag template parameter.
triqs::stat::mean_and_err and triqs::stat::mean_and_err_mpi, which return both the mean / sum and an error estimate. The flavour of error is selected through the triqs::stat::error_tag enum: sum of squared deviations from the mean, variance of the data, variance of the mean, standard error of the data, standard error of the mean, or jackknife error.
triqs::stat::tau_estimate_from_errors, which computes an estimate of the integrated autocorrelation time \( \tau = \frac{1}{2} (s_n^2 / s_0^2 - 1) \) from a binned and an unbinned standard error.

The two MPI variants accept a std::optional<mpi::communicator> and fall back to the serial implementation when no communicator is provided; otherwise per-rank partial results are combined with a numerically careful reweighting so that the reduced mean and sum of squared deviations match what a serial run on the concatenated data would have produced.

Enumerations
enum class	triqs::stat::error_tag
	Tag to indicate what to calculate when computing the error of a range of values. More...
enum class	triqs::stat::mean_tag
	Tag to indicate what to calculate when computing the mean of a range of values. More...

Functions
template<error_tag etag, AccCompatible T>
void	triqs::stat::apply_error_tag (T &sum_sq_devs, long nsamples)
	Given the sum of squared deviations from the mean, \( S^2 = \sum_{i=1}^N \left\| x_i - \overline{x} \right\|^2 \), and the number of samples \( N \), apply a transformation to get the result specified by the given error tag.
template<mean_tag mtag, AccCompatible T>
void	triqs::stat::apply_mean_tag (T &m, long nsamples)
	Given the mean \( \overline{x} \) and the number of samples \( N \), apply a transformation to get the result specified by the given mean tag.
template<mean_tag mtag = mean_tag::mean, StatCompatibleRange R>
auto	triqs::stat::mean (R &&rg)
	Calculate the arithmetic mean or the simple sum of some range of values.
template<error_tag etag = error_tag::err_mean, mean_tag mtag = mean_tag::mean, StatCompatibleRange R>
auto	triqs::stat::mean_and_err (R &&rg)
	Calculate the arithmetic mean or the simple sum as well as a corresponding error estimate of some range of values.
template<error_tag etag = error_tag::err_mean, mean_tag mtag = mean_tag::mean, StatCompatibleRange R>
auto	triqs::stat::mean_and_err_mpi (std::optional< mpi::communicator > c, R &&rg)
	Calculate the arithmetic mean or the simple sum as well as a corresponding error estimate of some range of values spread across multiple MPI processes.
template<mean_tag mtag = mean_tag::mean, StatCompatibleRange R>
auto	triqs::stat::mean_mpi (std::optional< mpi::communicator > c, R &&rg)
	Calculate the arithmetic mean or the simple sum of some range of values spread across multiple MPI processes.
template<StatCompatible T>
auto	triqs::stat::tau_estimate_from_errors (T const &s_n, T const &s_0)
	Compute an estimate for the integrated auto-correlation time from standard errors.
auto	triqs::stat::tau_estimate_from_vars (auto const &var, auto const &var0)
	Compute an estimate for the integrated auto-correlation time from variances.

Enumeration Type Documentation

◆ error_tag

enum class triqs::stat::error_tag

strong

#include <triqs/stat/mean_error.hpp>

Tag to indicate what to calculate when computing the error of a range of values.

This tag is mostly used internally. Given a range of values \( \{x_i : i = 1, \ldots, N\} \), the tag determines if we either calculate the

sum of squared deviations from the mean (sum): \( S^2 = \sum_{i=1}^N \left| x_i - \overline{x} \right|^2 \),
variance of the data itself (var_data): \( s_{x}^2 = \frac{1}{N - 1} S^2 \),
variance of the mean (var_mean): \( s_{\overline{x}}^2 = \frac{s_x^2}{N} \),
standard error of the data (err_data): \( s_x = \sqrt{s_x^2} \),
standard error of the mean (err_mean): \( s_{\overline{x}} = \sqrt{s_{\overline{x}}^2} \) or
jackknife error estimate (jk_err): \( s_x = \sqrt{\frac{N - 1}{N} S^2} \).

Definition at line 67 of file mean_error.hpp.

◆ mean_tag

enum class triqs::stat::mean_tag

strong

#include <triqs/stat/mean_error.hpp>

Tag to indicate what to calculate when computing the mean of a range of values.

This tag is mostly used internally. Given a range of values \( \{x_i : i = 1, \ldots, N\} \), the tag determines if we either calculate the

a simple sum (sum): \( R_x = \sum_{i=1}^N x_i \) or the
arithmetic mean (mean): \( \overline{x} = \frac{1}{N} \sum_{i=1}^N x_i = \frac{1}{N} R_x \).

Definition at line 53 of file mean_error.hpp.

Function Documentation

◆ apply_error_tag()

template<error_tag etag, AccCompatible T>

void triqs::stat::apply_error_tag	(	T &	sum_sq_devs,
		long	nsamples )

#include <triqs/stat/mean_error.hpp>

Given the sum of squared deviations from the mean, \( S^2 = \sum_{i=1}^N \left| x_i - \overline{x} \right|^2 \), and the number of samples \( N \), apply a transformation to get the result specified by the given error tag.

◆ apply_mean_tag()

template<mean_tag mtag, AccCompatible T>

void triqs::stat::apply_mean_tag	(	T &	m,
		long	nsamples )

#include <triqs/stat/mean_error.hpp>

Given the mean \( \overline{x} \) and the number of samples \( N \), apply a transformation to get the result specified by the given mean tag.

◆ mean()

template<mean_tag mtag = mean_tag::mean, StatCompatibleRange R>

auto triqs::stat::mean ( R && rg )

#include <triqs/stat/mean_error.hpp>

Calculate the arithmetic mean or the simple sum of some range of values.

The return type depends on the value type of the data.

See triqs::stat::mean_tag for more information.

Template Parameters

mtag	triqs::stat::mean_tag.
R	triqs::stat::StatCompatibleRange type.

Parameters

rg	Range object containing the data.

Returns: Arithmetic mean/Sum of the data.

Definition at line 120 of file mean_error.hpp.

◆ mean_and_err()

template<error_tag etag = error_tag::err_mean, mean_tag mtag = mean_tag::mean, StatCompatibleRange R>

auto triqs::stat::mean_and_err ( R && rg )

#include <triqs/stat/mean_error.hpp>

Calculate the arithmetic mean or the simple sum as well as a corresponding error estimate of some range of values.

In addition to the mean/sum (see triqs::stat::mean), we also calculate an error estimate which depends on the given error tag.

The return type depends on the value type of the data.

See triqs::stat::mean_tag and triqs::stat::error_tag for more information.

Template Parameters

etag	triqs::stat::error_tag.
mtag	triqs::stat::mean_tag.
R	triqs::stat::StatCompatibleRange type.

Parameters

rg	Range object containing the data.

Returns: std::pair containing the mean/sum and an error estimate of the data.

Definition at line 196 of file mean_error.hpp.

◆ mean_and_err_mpi()

template<error_tag etag = error_tag::err_mean, mean_tag mtag = mean_tag::mean, StatCompatibleRange R>

auto triqs::stat::mean_and_err_mpi	(	std::optional< mpi::communicator >	c,
		R &&	rg )

#include <triqs/stat/mean_error.hpp>

Calculate the arithmetic mean or the simple sum as well as a corresponding error estimate of some range of values spread across multiple MPI processes.

If the optional MPI communicator is provided, we first use triqs::stat::mean_and_err to calculate the mean and the sum of squared deviations from the mean on each process. Then the mean is reduced following the same procedure as in triqs::stat::mean_mpi. With the reduced mean, we calculate

\[ r_i^2 = S_i^2 + N_i \left| \overline{x}_i - \overline{x} \right|^2 \; , \]

on every process \( i \), and reduce it to get the sum of squared deviations from the mean for the combined data. The result will be available on all MPI processes and its type depends on the value type of the range.

If the optional MPI communicator is not provided, it simply calls triqs::stat::mean_and_err.

See triqs::stat::mean_tag and triqs::stat::error_tag for more information.

Template Parameters

etag	triqs::stat::error_tag.
mtag	triqs::stat::mean_tag.
R	triqs::stat::StatCompatibleRange type.

Parameters

c	std::optional MPI communicator.
rg	Range object containing the data.

Returns: std::pair containing the mean/sum and an error estimate of the data from all MPI processes.

Definition at line 236 of file mean_error.hpp.

◆ mean_mpi()

template<mean_tag mtag = mean_tag::mean, StatCompatibleRange R>

auto triqs::stat::mean_mpi	(	std::optional< mpi::communicator >	c,
		R &&	rg )

#include <triqs/stat/mean_error.hpp>

Calculate the arithmetic mean or the simple sum of some range of values spread across multiple MPI processes.

If the optional MPI communicator is provided, we first use triqs::stat::mean to get the mean/sum of the data on each process and then reduce it with mpi::all_reduce:

mtag == mean_tag::sum: Reduce the sum of the data over all MPI processes.
mtag == mean_tag::mean: Let \( \overline{x}_i \) be the mean of the data on process \( i \). Then the mean of the combined data can be written as
\[ \overline{x} = \frac{1}{N} \sum_{i=1}^P N_i \overline{x}_i \; , \]
where \( N_i \) is the number of samples on process \( i \), \( N \) is the total number of samples and \(P \) is the number of MPI processes.

The result will be available on all MPI processes and its type depends on the value type of the range.

If the optional MPI communicator is not provided, it simply calls triqs::stat::mean.

See triqs::stat::mean_tag for more information.

Template Parameters

mtag	triqs::stat::mean_tag.
R	triqs::stat::StatCompatibleRange type.

Parameters

c	std::optional MPI communicator.
rg	Range object containing the data.

Returns: Arithmetic mean/Sum of the combined data from all MPI processes.

Definition at line 161 of file mean_error.hpp.

◆ tau_estimate_from_errors()

template<StatCompatible T>

auto triqs::stat::tau_estimate_from_errors	(	T const &	s_n,
		T const &	s_0 )

#include <triqs/stat/mean_error.hpp>

Compute an estimate for the integrated auto-correlation time from standard errors.

The integrated autocorrelation time is estimated as

\[ \tau = \frac{1}{2} \left( \frac{s^2_n}{s^2_0} - 1 \right) \; , \]

where \( s_n \) is the standard error of the mean with binning and \( s_0 \) the standard error of the mean without binning. This is a thin wrapper around triqs::stat::tau_estimate_from_vars applied to the squared errors.

Template Parameters

T	triqs::stat::StatCompatible type.

Parameters

s_n	Standard error of the mean with binning.
s_0	Standard error of the mean without binning.

Returns: Estimate of the integrated auto-correlation time.

Definition at line 296 of file mean_error.hpp.

◆ tau_estimate_from_vars()

auto triqs::stat::tau_estimate_from_vars	(	auto const &	var,
		auto const &	var0 )

nodiscard

#include <triqs/stat/mean_error.hpp>

Compute an estimate for the integrated auto-correlation time from variances.

The integrated autocorrelation time is estimated (elementwise) as

\[ \tau = \frac{1}{2} \left( \frac{\mathrm{var}}{\mathrm{var}_0} - 1 \right) \; , \]

where var is the variance of the mean with binning and var0 the variance of the mean without binning. Elements for which var0 is zero (e.g. a constant signal) yield NaN instead of triggering a division by zero.

Parameters

var	Binned estimate of the variance of the mean.
var0	Unbinned estimate of the variance of the mean.

Returns: Estimate of the integrated auto-correlation time.

Definition at line 277 of file mean_error.hpp.

T	triqs::stat::AccCompatible type.
etag	triqs::stat::error_tag to indicate the transformation to apply.

sum_sq_devs	Sum of squared deviations from the mean \( S^2 \).
nsamples	Number of samples \( N \).

T	triqs::stat::AccCompatible type.
mtag	triqs::stat::mean_tag to indicate the transformation to apply.

Detailed Description

Enumerations

Functions

Enumeration Type Documentation

◆ error_tag

◆ mean_tag

Function Documentation

◆ apply_error_tag()

◆ apply_mean_tag()

◆ mean()

◆ mean_and_err()

◆ mean_and_err_mpi()

◆ mean_mpi()

◆ tau_estimate_from_errors()

◆ tau_estimate_from_vars()