Detailed Description

Calculates the average and variance of a sampled property.

Average calculates block and global averages of a sampled value and its square, from which it obtains a global average and variance for a sequence. A hierarchical blocking algorithm is used to estimate the error on the average. No error estimate is provided for the variance.

The sample function of also optionally calculates block averages, which can be useful for reducing how frequently values are logged to a file. The parameter nSamplePerBlock is the number of samples per block average. This is initialized to zero. A zero value disables calculation of block averages. An overloaded method of the sample function that takes an std::ostream file as an argument outputs block averages to file as blocks are completed.

The hierarchical blocking algorithm is implemented using a linked list of Util::AverageStage objects. See documentation of that class for further details, and a literature reference.

Definition at line 43 of file Average.h.

#include <Average.h>

Inheritance diagram for Util::Average:

Public Member Functions
	Average (int blockFactor=2)
	Constructor. More...

virtual	~Average ()
	Destructor. More...

void	readParameters (std::istream &in)
	Read parameter nSamplePerBlock from file and initialize. More...

void	setNSamplePerBlock (int nSamplePerBlock)
	Set nSamplePerBlock. More...

virtual void	loadParameters (Serializable::IArchive &ar)
	Load internal state from an archive. More...

virtual void	save (Serializable::OArchive &ar)
	Save internal state to an archive. More...

template<class Archive >
void	serialize (Archive &ar, const unsigned int version)
	Serialize this Average to or from an archive. More...

void	clear ()
	Clear all accumulators, set to empty initial state. More...

void	sample (double value)
	Add a sampled value to the ensemble. More...

void	sample (double value, std::ostream &out)
	Add a sampled value to ensemble, and output block averages. More...

void	output (std::ostream &out) const
	Output final statistical properties to file. More...

double	blockingError () const
	Return estimated error on average from blocking analysis. More...

int	nSamplePerBlock () const
	Get number of samples per block average. More...

int	iBlock () const
	Get number of samples in current block average. More...

bool	isBlockComplete () const
	Is the current block average complete? More...

Public Member Functions inherited from Util::AverageStage
	AverageStage (int blockFactor=2)
	Constructor. More...

virtual	~AverageStage ()
	Destructor. More...

void	setBlockFactor (int blockFactor)
	Reset the value of blockFactor. More...

template<class Archive >
void	serialize (Archive &ar, const unsigned int version)
	Add a sampled value to the ensemble. More...

double	average () const
	Return the average of all sampled values. More...

double	variance () const
	Return the variance of all sampled values. More...

double	stdDeviation () const
	Return the standard deviation of all sampled values. More...

double	error () const
	Return a naive estimate for the std deviation of the average. More...

long	nSample () const
	Return the number of sampled values in this sequence. More...

long	stageInterval () const
	Return the number of sampled values per block at this stage. More...

Public Member Functions inherited from Util::ParamComposite
	ParamComposite ()
	Constructor. More...

	ParamComposite (const ParamComposite &other)
	Copy constructor. More...

	ParamComposite (int capacity)
	Constructor. More...

virtual	~ParamComposite ()
	Virtual destructor. More...

void	resetParam ()
	Resets ParamComposite to its empty state. More...

virtual void	readParam (std::istream &in)
	Read the parameter file block. More...

virtual void	readParamOptional (std::istream &in)
	Read optional parameter file block. More...

virtual void	writeParam (std::ostream &out)
	Write all parameters to an output stream. More...

virtual void	load (Serializable::IArchive &ar)
	Load all parameters from an input archive. More...

virtual void	loadOptional (Serializable::IArchive &ar)
	Load an optional ParamComposite. More...

void	saveOptional (Serializable::OArchive &ar)
	Saves isActive flag, and then calls save() iff isActive is true. More...

void	readParamComposite (std::istream &in, ParamComposite &child, bool next=true)
	Add and read a required child ParamComposite. More...

void	readParamCompositeOptional (std::istream &in, ParamComposite &child, bool next=true)
	Add and attempt to read an optional child ParamComposite. More...

template<typename Type >
ScalarParam< Type > &	read (std::istream &in, const char *label, Type &value)
	Add and read a new required ScalarParam < Type > object. More...

template<typename Type >
ScalarParam< Type > &	readOptional (std::istream &in, const char *label, Type &value)
	Add and read a new optional ScalarParam < Type > object. More...

template<typename Type >
CArrayParam< Type > &	readCArray (std::istream &in, const char label, Type value, int n)
	Add and read a required C array parameter. More...

template<typename Type >
CArrayParam< Type > &	readOptionalCArray (std::istream &in, const char label, Type value, int n)
	Add and read an optional C array parameter. More...

template<typename Type >
DArrayParam< Type > &	readDArray (std::istream &in, const char *label, DArray< Type > &array, int n)
	Add and read a required DArray < Type > parameter. More...

template<typename Type >
DArrayParam< Type > &	readOptionalDArray (std::istream &in, const char *label, DArray< Type > &array, int n)
	Add and read an optional DArray < Type > parameter. More...

template<typename Type , int N>
FArrayParam< Type, N > &	readFArray (std::istream &in, const char *label, FArray< Type, N > &array)
	Add and read a required FArray < Type, N > array parameter. More...

template<typename Type , int N>
FArrayParam< Type, N > &	readOptionalFArray (std::istream &in, const char *label, FArray< Type, N > &array)
	Add and read an optional FArray < Type, N > array parameter. More...

template<typename Type >
CArray2DParam< Type > &	readCArray2D (std::istream &in, const char label, Type value, int m, int n, int np)
	Add and read a required CArray2DParam < Type > 2D C-array. More...

template<typename Type >
CArray2DParam< Type > &	readOptionalCArray2D (std::istream &in, const char label, Type value, int m, int n, int np)
	Add and read an optional CArray2DParam < Type > 2D C-array parameter. More...

template<typename Type >
DMatrixParam< Type > &	readDMatrix (std::istream &in, const char *label, DMatrix< Type > &matrix, int m, int n)
	Add and read a required DMatrix < Type > matrix parameter. More...

template<typename Type >
DMatrixParam< Type > &	readOptionalDMatrix (std::istream &in, const char *label, DMatrix< Type > &matrix, int m, int n)
	Add and read an optional DMatrix < Type > matrix parameter. More...

template<typename Type >
DSymmMatrixParam< Type > &	readDSymmMatrix (std::istream &in, const char *label, DMatrix< Type > &matrix, int n)
	Add and read a required symmetrix DMatrix. More...

template<typename Type >
DSymmMatrixParam< Type > &	readOptionalDSymmMatrix (std::istream &in, const char *label, DMatrix< Type > &matrix, int n)
	Add and read an optional DMatrix matrix parameter. More...

Begin &	readBegin (std::istream &in, const char *label, bool isRequired=true)
	Add and read a class label and opening bracket. More...

End &	readEnd (std::istream &in)
	Add and read the closing bracket. More...

Blank &	readBlank (std::istream &in)
	Add and read a new Blank object, representing a blank line. More...

void	loadParamComposite (Serializable::IArchive &ar, ParamComposite &child, bool next=true)
	Add and load a required child ParamComposite. More...

void	loadParamCompositeOptional (Serializable::IArchive &ar, ParamComposite &child, bool next=true)
	Add and load an optional child ParamComposite if isActive. More...

template<typename Type >
ScalarParam< Type > &	loadParameter (Serializable::IArchive &ar, const char *label, Type &value, bool isRequired)
	Add and load a new ScalarParam < Type > object. More...

template<typename Type >
ScalarParam< Type > &	loadParameter (Serializable::IArchive &ar, const char *label, Type &value)
	Add and load new required ScalarParam < Type > object. More...

template<typename Type >
CArrayParam< Type > &	loadCArray (Serializable::IArchive &ar, const char label, Type value, int n, bool isRequired)
	Add a C array parameter and load its elements. More...

template<typename Type >
CArrayParam< Type > &	loadCArray (Serializable::IArchive &ar, const char label, Type value, int n)
	Add and load a required CArrayParam< Type > array parameter. More...

template<typename Type >
DArrayParam< Type > &	loadDArray (Serializable::IArchive &ar, const char *label, DArray< Type > &array, int n, bool isRequired)
	Add an load a DArray < Type > array parameter. More...

template<typename Type >
DArrayParam< Type > &	loadDArray (Serializable::IArchive &ar, const char *label, DArray< Type > &array, int n)
	Add and load a required DArray< Type > array parameter. More...

template<typename Type , int N>
FArrayParam< Type, N > &	loadFArray (Serializable::IArchive &ar, const char *label, FArray< Type, N > &array, bool isRequired)
	Add and load an FArray < Type, N > fixed-size array parameter. More...

template<typename Type , int N>
FArrayParam< Type, N > &	loadFArray (Serializable::IArchive &ar, const char *label, FArray< Type, N > &array)
	Add and load a required FArray < Type > array parameter. More...

template<typename Type >
CArray2DParam< Type > &	loadCArray2D (Serializable::IArchive &ar, const char label, Type value, int m, int n, int np, bool isRequired)
	Add and load a CArray2DParam < Type > C 2D array parameter. More...

template<typename Type >
CArray2DParam< Type > &	loadCArray2D (Serializable::IArchive &ar, const char label, Type value, int m, int n, int np)
	Add and load a required < Type > matrix parameter. More...

template<typename Type >
DMatrixParam< Type > &	loadDMatrix (Serializable::IArchive &ar, const char *label, DMatrix< Type > &matrix, int m, int n, bool isRequired)
	Add and load a DMatrixParam < Type > matrix parameter. More...

template<typename Type >
DMatrixParam< Type > &	loadDMatrix (Serializable::IArchive &ar, const char *label, DMatrix< Type > &matrix, int m, int n)
	Add and load a required DMatrixParam < Type > matrix parameter. More...

template<typename Type >
DSymmMatrixParam< Type > &	loadDSymmMatrix (Serializable::IArchive &ar, const char *label, DMatrix< Type > &matrix, int n, bool isRequired)
	Add and load a symmetric DSymmMatrixParam < Type > matrix parameter. More...

template<typename Type >
DSymmMatrixParam< Type > &	loadDSymmMatrix (Serializable::IArchive &ar, const char *label, DMatrix< Type > &matrix, int n)
	Add and load a required DSymmMatrixParam < Type > matrix parameter. More...

void	addParamComposite (ParamComposite &child, bool next=true)
	Add a child ParamComposite object to the format array. More...

Begin &	addBegin (const char *label)
	Add a Begin object representing a class name and bracket. More...

End &	addEnd ()
	Add a closing bracket. More...

Blank &	addBlank ()
	Create and add a new Blank object, representing a blank line. More...

std::string	className () const
	Get class name string. More...

bool	isRequired () const
	Is this ParamComposite required in the input file? More...

bool	isActive () const
	Is this parameter active? More...

Public Member Functions inherited from Util::ParamComponent
virtual	~ParamComponent ()
	Destructor. More...

void	setIndent (const ParamComponent &parent, bool next=true)
	Set indent level. More...

std::string	indent () const
	Return indent string for this object (string of spaces). More...

template<class Archive >
void	serialize (Archive &ar, const unsigned int version)
	Serialize this ParamComponent as a string. More...

Public Member Functions inherited from Util::Serializable
virtual	~Serializable ()
	Destructor. More...

Public Member Functions inherited from Util::MpiFileIo
	MpiFileIo ()
	Constructor. More...

	MpiFileIo (const MpiFileIo &other)
	Copy constructor. More...

bool	isIoProcessor () const
	Can this processor do file I/O ? More...

void	setIoCommunicator (MPI::Intracomm &communicator)
	Set the communicator. More...

void	clearCommunicator ()
	Clear (nullify) the communicator. More...

bool	hasIoCommunicator () const
	Does this object have an associated MPI communicator? More...

MPI::Intracomm &	ioCommunicator () const
	Get the MPI communicator by reference. More...

Additional Inherited Members
Public Types inherited from Util::Serializable
typedef BinaryFileOArchive	OArchive
	Type of output archive used by save method. More...

typedef BinaryFileIArchive	IArchive
	Type of input archive used by load method. More...

Static Public Member Functions inherited from Util::ParamComponent
static void	initStatic ()
	Initialize static echo member to false. More...

static void	setEcho (bool echo=true)
	Enable or disable echoing for all subclasses of ParamComponent. More...

static bool	echo ()
	Get echo parameter. More...

Protected Member Functions inherited from Util::AverageStage
bool	hasChild () const
	Does this object have a child AverageStage for block averages? More...

AverageStage &	child ()
	Return the child AverageStage by reference. More...

Protected Member Functions inherited from Util::ParamComposite
void	setClassName (const char *className)
	Set class name string. More...

void	setIsRequired (bool isRequired)
	Set or unset the isActive flag. More...

void	setIsActive (bool isActive)
	Set or unset the isActive flag. More...

void	setParent (ParamComponent &param, bool next=true)
	Set this to the parent of a child component. More...

void	addComponent (ParamComponent &param, bool isLeaf=true)
	Add a new ParamComponent object to the format array. More...

template<typename Type >
ScalarParam< Type > &	add (std::istream &in, const char *label, Type &value, bool isRequired=true)
	Add a new required ScalarParam < Type > object. More...

template<typename Type >
CArrayParam< Type > &	addCArray (std::istream &in, const char label, Type value, int n, bool isRequired=true)
	Add (but do not read) a required C array parameter. More...

template<typename Type >
DArrayParam< Type > &	addDArray (std::istream &in, const char *label, DArray< Type > &array, int n, bool isRequired=true)
	Add (but do not read) a DArray < Type > parameter. More...

template<typename Type , int N>
FArrayParam< Type, N > &	addFArray (std::istream &in, const char *label, FArray< Type, N > &array, bool isRequired=true)
	Add (but do not read) a FArray < Type, N > array parameter. More...

template<typename Type >
CArray2DParam< Type > &	addCArray2D (std::istream &in, const char label, Type value, int m, int n, int np, bool isRequired=true)
	Add (but do not read) a CArray2DParam < Type > 2D C-array. More...

template<typename Type >
DMatrixParam< Type > &	addDMatrix (std::istream &in, const char *label, DMatrix< Type > &matrix, int m, int n, bool isRequired=true)
	Add and read a required DMatrix < Type > matrix parameter. More...

Protected Member Functions inherited from Util::ParamComponent
	ParamComponent ()
	Constructor. More...

	ParamComponent (const ParamComponent &other)
	Copy constructor. More...

Constructor & Destructor Documentation

Util::Average::Average ( int blockFactor = 2 )

Constructor.

Parameters

blockFactor ratio of block sizes for subsequent stages.

Definition at line 20 of file Average.cpp.

References Util::ParamComposite::setClassName().

Util::Average::~Average ( )

virtual

Destructor.

Definition at line 36 of file Average.cpp.

Member Function Documentation

void Util::Average::readParameters ( std::istream & in )

virtual

Read parameter nSamplePerBlock from file and initialize.

See setNSamplePerBlock() for discussion of value.

Parameters

in	input stream

Reimplemented from Util::ParamComposite.

Definition at line 52 of file Average.cpp.

References UTIL_THROW.

void Util::Average::setNSamplePerBlock ( int nSamplePerBlock )

Set nSamplePerBlock.

If nSamplePerBlock > 0, the sample function will increment block averages, and reset the average every nSamplePerBlock samples.

If nSamplePerBlock == 0, block averaging is disabled. This is the default (i.e., the initial value set in the constructor).

Parameters

nSamplePerBlock number of samples per block average output

Definition at line 63 of file Average.cpp.

References nSamplePerBlock(), and UTIL_THROW.

void Util::Average::loadParameters ( Serializable::IArchive & ar )

virtual

Load internal state from an archive.

Parameters

ar	input/loading archive

Reimplemented from Util::ParamComposite.

Definition at line 74 of file Average.cpp.

References Util::AverageStage::serialize(), and UTIL_THROW.

Referenced by DdMd::ExternalEnergyAverage::loadParameters(), McMd::StressTensorAverage< SystemType >::loadParameters(), DdMd::VirialStressTensorAverage::loadParameters(), McMd::MdVirialStressTensorAverage::loadParameters(), and McMd::McVirialStressTensorAverage::loadParameters().

void Util::Average::save ( Serializable::OArchive & ar )

virtual

Save internal state to an archive.

Parameters

ar	output/saving archive

Reimplemented from Util::ParamComposite.

Definition at line 88 of file Average.cpp.

template<class Archive >

void Util::Average::serialize	(	Archive &	ar,
		const unsigned int	version
	)

Serialize this Average to or from an archive.

Parameters

ar	input or output archive
version	file version id

Definition at line 252 of file Average.h.

References Util::AverageStage::serialize().

void Util::Average::clear ( )

virtual

Clear all accumulators, set to empty initial state.

Reimplemented from Util::AverageStage.

Definition at line 42 of file Average.cpp.

References Util::AverageStage::clear().

Referenced by DdMd::ExternalEnergyAverage::clear(), DdMd::PairEnergyAverage::clear(), DdMd::VirialStressTensorAverage::clear(), McMd::MdVirialStressTensorAverage::clear(), McMd::McVirialStressTensorAverage::clear(), McMd::McEnergyAnalyzer::clear(), McMd::StressTensorAverage< SystemType >::clear(), McMd::MdEnergyAnalyzer::clear(), DdMd::EnergyAnalyzer::clear(), DdMd::AverageAnalyzer::clear(), McMd::RadiusGyration::readParameters(), McMd::McNVTChemicalPotential::setup(), McMd::PerturbDerivative::setup(), McMd::MdPotentialEnergyAverage::setup(), McMd::NLinkAverage::setup(), McMd::MdKineticEnergyAverage::setup(), McMd::InterIntraLink::setup(), McMd::AverageAnalyzer< SystemType >::setup(), McMd::PressureAverage< SystemType >::setup(), McMd::McPairEnergyAverage::setup(), McMd::BennettsMethod::setup(), McMd::EndtoEndXYZ::setup(), McMd::EndtoEnd::setup(), and McMd::RadiusGyration::setup().

void Util::Average::sample ( double value )

virtual

Add a sampled value to the ensemble.

Parameters

value sampled value

Reimplemented from Util::AverageStage.

Definition at line 94 of file Average.cpp.

References Util::AverageStage::sample().

void Util::Average::sample	(	double	value,
		std::ostream &	out
	)

Add a sampled value to ensemble, and output block averages.

Parameters

value	sampled value
out	output stream to which to write block averages

Definition at line 112 of file Average.cpp.

References Util::AverageStage::sample().

void Util::Average::output ( std::ostream & out ) const

Output final statistical properties to file.

This function outputs the average value, an estimate of the error on the average, the variance. It also outputs a sequence of naive values for the error on the average obtained from sequences of block averages, with different levels of blocking. The naive estimate obtained from each stage is calculated as if subsequent values were uncorrelated. This gives sqrt(variance/nSample), where variance is the variance of the sequence of block averages processed by that stage, and nSample is the number of such block averages thus far. The final estimate of the error on the average is obtained by trying to identify several stages of block averaging that yield statistically indistinguishable naive estimates.

Parameters