#include <triqs/stat/histograms.hpp>

Detailed Description

Class representing a histogram on a given interval.

The histogram is defined on the interval \( [a, b] \) with the following values for the center of its bins:

\[ g_n = a + n h = a + n \frac{b - a}{N - 1} \; . \]

Here, \( N \) is the number of bins in the histogram, \( h \) is the bin size and \( n = 0, 1, \ldots, N - 1 \) is the index of the bin.

That means that each bin is of the same size \( h \), except for the first and last bins, which have a size of \( h / 2 \).

Values are added to the histogram using the streaming operator <<. For example, hist << 1.5 adds the value 1.5 to the histogram hist.

When a value is added to the histogram, it first determines into which bin the value falls and then increases the count of that bin. If the value is outside of the interval, it is discarded. Additionally, the histogram keeps track of the total number of data points as well as the number of lost points that fall outside of the interval.

Definition at line 69 of file histograms.hpp.

Public Member Functions
	histogram ()=default
	Default constructor leaves the histogram in a valid but unusable state.
	histogram (double a, double b, std::size_t nbins)
	Construct a histogram on the interval \( [a, b] \) with the given number \( N \) of bins.
	histogram (int a, int b)
	Construct a histogram on the interval \( [a, b] \) with a bin size of 1, except for the first and last bins, which have a size of 0.5.
void	clear ()
	Reset the histogram to its initial state, i.e. with no data points added to it.
auto const &	data () const
	Get the data stored in the histogram.
void	deserialize (auto &ar)
	Deserialize the histogram from an archive.
auto	limits () const
	Get the domain on which the histogram is defined.
auto	mesh_point (int n) const
	Get the position of the center of the n-th bin.
auto	n_data_pts () const
	Get the number of data points that have been added to the histogram.
auto	n_lost_pts () const
	Get the number of data points that fell outside of the interval and were discarded.
histogram &	operator<< (double x)
	Add a data point to the histogram.
bool	operator== (histogram const &h) const =default
	Default equal-to operator compares the domains, data vectors, number of accumulated and discarded data points and bin sizes.
void	serialize (auto &ar) const
	Serialize the histogram to an archive.
auto	size () const
	Get number of bins in the histogram.

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

Friends
histogram	cdf (histogram const &h)
	Normalize and integrate a histogram.
void	h5_read (h5::group g, std::string const &name, histogram &h)
	Read a triqs::stat::histogram from HDF5.
void	h5_write (h5::group g, std::string const &name, histogram const &h)
	Write a triqs::stat::histogram to HDF5.
void	mpi_broadcast (histogram &h, mpi::communicator c={}, int root=0)
	Implementation of an MPI broadcast for triqs::stat::histogram.
histogram	mpi_reduce (histogram const &h, mpi::communicator c={}, int root=0, bool all=false, MPI_Op op=MPI_SUM)
	Implementation of an MPI reduce for triqs::stat::histogram.
histogram	operator+ (histogram h1, histogram const &h2)
	Add two histograms together.
std::ostream &	operator<< (std::ostream &os, histogram const &h)
	Write a histogram to a std::ostream.
histogram	pdf (histogram const &h)
	Normalize a histogram.

Constructor & Destructor Documentation

◆ histogram() [1/2]

triqs::stat::histogram::histogram	(	int	a,
		int	b )

Construct a histogram on the interval \( [a, b] \) with a bin size of 1, except for the first and last bins, which have a size of 0.5.

The histogram will have a total of \( N = b - a + 1 \) bins.

If \( a \geq b \), an exception is thrown.

Parameters

a	Lower bound of the interval.
b	Upper bound of the interval.

Definition at line 44 of file histograms.cpp.

◆ histogram() [2/2]

triqs::stat::histogram::histogram	(	double	a,
		double	b,
		std::size_t	nbins )

Construct a histogram on the interval \( [a, b] \) with the given number \( N \) of bins.

The bin size is set to \( h = (b - a) / (N - 1) \). The first and last bins have a size of \( h / 2 \).

If \( a \geq b \) or if the number of bins is smaller than 2, an exception is thrown.

Parameters

a	Lower bound of the interval.
b	Upper bound of the interval.
nbins	Number of bins.

Definition at line 46 of file histograms.cpp.

Member Function Documentation

◆ data()

auto const & triqs::stat::histogram::data ( ) const

inline

Get the data stored in the histogram.

Returns: nda::vector<double> containing the number of data points in each bin.

Definition at line 145 of file histograms.hpp.

◆ deserialize()

void triqs::stat::histogram::deserialize ( auto & ar )

inline

Deserialize the histogram from an archive.

Parameters

ar	Archive from which the histogram is deserialized.

Definition at line 256 of file histograms.hpp.

◆ limits()

auto triqs::stat::histogram::limits ( ) const

inline

Get the domain on which the histogram is defined.

Returns: std::pair containing the lower and upper bounds \( [a, b] \) of the histogram.

Definition at line 139 of file histograms.hpp.

◆ mesh_point()

auto triqs::stat::histogram::mesh_point ( int n ) const

inline

Get the position of the center of the n-th bin.

Parameters

n	Index of the bin.

Returns: Position of the n-th bin center, i.e. \( a + n h \).

Definition at line 127 of file histograms.hpp.

◆ n_data_pts()

auto triqs::stat::histogram::n_data_pts ( ) const

inline

Get the number of data points that have been added to the histogram.

Returns: Number of accumulated data points.

Definition at line 151 of file histograms.hpp.

◆ n_lost_pts()

auto triqs::stat::histogram::n_lost_pts ( ) const

inline

Get the number of data points that fell outside of the interval and were discarded.

Returns: Number of discarded data points.

Definition at line 157 of file histograms.hpp.

◆ operator<<()

histogram & triqs::stat::histogram::operator<< ( double x )

Add a data point to the histogram.

The data point \( x \) falls into the bin \( n = \lfloor \frac{x - a}{h} + 0.5 \rfloor \).

If \( x \notin [a, b] \), the data point is not added to the histogram but instead the number of lost points is increased.

Parameters

x	Data point to be added to the histogram.

Returns: Reference to this object.

Definition at line 50 of file histograms.cpp.

◆ serialize()

void triqs::stat::histogram::serialize ( auto & ar ) const

inline

Serialize the histogram to an archive.

Parameters

ar	Archive to which the histogram is serialized.

Definition at line 250 of file histograms.hpp.

◆ size()

auto triqs::stat::histogram::size ( ) const

inline

Get number of bins in the histogram.

Returns: Size of the data vector.

Definition at line 133 of file histograms.hpp.

◆ cdf

histogram cdf ( histogram const & h )

friend

Normalize and integrate a histogram.

It simply performs partial summation of the bin counts and then divides by the number of in-range data points (lost points are excluded).

This does not return the CDF of the underlying continuous distribution but rather the CDF of the discrete probabilities that a data point falls into a certain bin.

Parameters

h	Histogram to be normalized and integrated.

Returns: Normalized and integrated histogram.

Definition at line 287 of file histograms.hpp.

◆ h5_read

void h5_read	(	h5::group	g,
		std::string const &	name,
		histogram &	h )

friend

Read a triqs::stat::histogram from HDF5.

Parameters

g	h5::group containing the dataset.
name	Name of the dataset from which the histogram will be read.
h	Histogram to be read into.

Definition at line 80 of file histograms.cpp.

◆ h5_write

void h5_write	(	h5::group	g,
		std::string const &	name,
		histogram const &	h )

friend

Write a triqs::stat::histogram to HDF5.

Parameters

g	h5::group in which the dataset is created.
name	Name of the dataset to which the histogram will be written.
h	Histogram to be written.

Definition at line 70 of file histograms.cpp.

◆ mpi_broadcast

void mpi_broadcast	(	histogram &	h,
		mpi::communicator	c = {},
		int	root = 0 )

friend

Implementation of an MPI broadcast for triqs::stat::histogram.

Parameters

h	Histogram to be broadcasted.
c	MPI communicator object.
root	Rank of the root process.

Definition at line 186 of file histograms.hpp.

◆ mpi_reduce

histogram mpi_reduce	(	histogram const &	h,
		mpi::communicator	c = {},
		int	root = 0,
		bool	all = false,
		MPI_Op	op = MPI_SUM )

friend

Implementation of an MPI reduce for triqs::stat::histogram.

The reduction does the same as the operator+(histogram, histogram const &).

Parameters

h	Histogram to be reduced.
c	MPI communicator object.
root	Rank of the root process.
all	Should all processes receive the result of the reduction.
op	MPI reduction operation (only MPI_SUM is allowed).

Returns: Reduced histogram.

Definition at line 207 of file histograms.hpp.

◆ operator+

histogram operator+	(	histogram	h1,
		histogram const &	h2 )

friend

Add two histograms together.

It simply adds the data vector, the number of accumulated data points and the number of discarded data points together.

It throws an exception if the domains or the number of bins of the two histograms are not equal.

Parameters

h1	Left-hand side histogram operand.
h2	Right-hand side histogram operand.

Returns: Sum of the two histograms.

Definition at line 61 of file histograms.cpp.

◆ operator<<

std::ostream & operator<<	(	std::ostream &	os,
		histogram const &	h )

friend

Write a histogram to a std::ostream.

Parameters

os	std::ostream to which the histogram will be written.
h	Histogram to be written.

Returns: Reference to the same std::ostream.

Definition at line 91 of file histograms.cpp.

◆ pdf

histogram pdf ( histogram const & h )

friend

Normalize a histogram.

It simply divides each bin count by the number of in-range data points (lost points are excluded).

Note: This does not return the PDF of the underlying continuous distribution but rather the discrete probabilities that a data point falls into a certain bin.

Parameters

h	Histogram to be normalized.

Returns: Normalized histogram.

Definition at line 269 of file histograms.hpp.

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

triqs/stat/histograms.hpp
triqs/stat/histograms.cpp

Detailed Description

Public Member Functions

Static Public Member Functions

Friends

Constructor & Destructor Documentation

◆ histogram() [1/2]

◆ histogram() [2/2]

Member Function Documentation

◆ data()

◆ deserialize()

◆ limits()

◆ mesh_point()

◆ n_data_pts()

◆ n_lost_pts()

◆ operator<<()

◆ serialize()

◆ size()

Friends And Related Symbol Documentation

◆ cdf

◆ h5_read

◆ h5_write

◆ mpi_broadcast

◆ mpi_reduce

◆ operator+

◆ operator<<

◆ pdf