Gromacs  2024.4
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
List of all members | Classes | Public Types | Public Member Functions | Static Public Member Functions
gmx::TabulatedNormalDistribution< RealType, tableBits > Class Template Reference

#include <gromacs/random/tabulatednormaldistribution.h>

Description

template<class RealType = real, unsigned int tableBits = detail::c_TabulatedNormalDistributionDefaultBits>
class gmx::TabulatedNormalDistribution< RealType, tableBits >

Tabulated normal random distribution.

Random distribution compatible with C++11 distributions - it can be used with any C++11 random engine.

Template Parameters
RealTypeType of the return value. Float or double. Note that GROMACS uses "real" type by default in contrast to the C++11 standard library, to avoid double/float conversions.
tableBitsSize of the table, specified in bits. The storage space required is sizeof(RealType)*2^tableBits. To keep things sane this is limited to 24 bits.

Some stochastic integrators depend on drawing a lot of normal distribution random numbers quickly, but in many cases the only important property is the distribution - given the noise in forces we do not need very high resolution. This distribution uses an internal table to return samples from a normal distribution with limited resolution. By default the table uses c_TabulatedNormalDistributionDefaultBits bits, but this is specified with a template parameter.

Since this distribution only uses tableBits bits per value generated, the values draw from the random engine are used for several results. To make sure you get a reproducible result when using counter-based random engines (such as ThreeFry2x64), remember to call the reset() method to cancel the internal memory of the distribution.

Note
For modern NUMA systems, you likely want to use separate distributions for each thread, and make sure they are initialized on the CPU where they will run, so the table is placed in that NUMA memory pool.
The finite table resolution means this distribution will NOT return arbitrarily small/large values, but with e.g. 14 bits the results are limited to roughly +/- 4 standard deviations.

Classes

class  param_type
 Normal distribution parameter class (mean and stddev) More...
 

Public Types

typedef RealType result_type
 Type of normal distribution results.
 

Public Member Functions

 TabulatedNormalDistribution (result_type mean=0.0, result_type stddev=1.0)
 Construct new normal distribution with specified mean & stdddev. More...
 
 TabulatedNormalDistribution (const param_type &param)
 Construct new normal distribution from parameter type. More...
 
result_type min () const
 Smallest value that can be generated in normal distributon. More...
 
result_type max () const
 Largest value that can be generated in normal distribution. More...
 
result_type mean () const
 Mean of the present normal distribution.
 
result_type stddev () const
 Standard deviation of the present normal distribution.
 
param_type param () const
 The parameter class (mean & stddev) of the normal distribution.
 
void reset ()
 Clear all internal saved random bits from the random engine.
 
template<class Rng >
result_type operator() (Rng &g)
 Return normal distribution value specified by internal parameters. More...
 
template<class Rng >
result_type operator() (Rng &g, const param_type &param)
 Return normal distribution value specified by given parameters. More...
 
bool operator== (const TabulatedNormalDistribution< RealType, tableBits > &x) const
 Check if two tabulated normal distributions have identical states. More...
 
bool operator!= (const TabulatedNormalDistribution< RealType, tableBits > &x) const
 Check if two tabulated normal distributions have different states. More...
 

Static Public Member Functions

static std::array< RealType, 1
<< tableBits > 
makeTable ()
 Fill the table with values for the normal distribution. More...
 

Constructor & Destructor Documentation

template<class RealType = real, unsigned int tableBits = detail::c_TabulatedNormalDistributionDefaultBits>
gmx::TabulatedNormalDistribution< RealType, tableBits >::TabulatedNormalDistribution ( result_type  mean = 0.0,
result_type  stddev = 1.0 
)
inlineexplicit

Construct new normal distribution with specified mean & stdddev.

Parameters
meanMean value of tabulated normal distribution
stddevStandard deviation of tabulated normal distribution
template<class RealType = real, unsigned int tableBits = detail::c_TabulatedNormalDistributionDefaultBits>
gmx::TabulatedNormalDistribution< RealType, tableBits >::TabulatedNormalDistribution ( const param_type param)
inlineexplicit

Construct new normal distribution from parameter type.

Parameters
paramParameter class containing mean and standard deviation.

Member Function Documentation

template<class RealType = real, unsigned int tableBits = detail::c_TabulatedNormalDistributionDefaultBits>
static std::array<RealType, 1 << tableBits> gmx::TabulatedNormalDistribution< RealType, tableBits >::makeTable ( )
inlinestatic

Fill the table with values for the normal distribution.

This routine returns a new a std::array with the table data.

This routine is used to help construct objects of this class, and is exposed only to permit testing. Normal code should not need to call this function.

template<class RealType = real, unsigned int tableBits = detail::c_TabulatedNormalDistributionDefaultBits>
result_type gmx::TabulatedNormalDistribution< RealType, tableBits >::max ( ) const
inline

Largest value that can be generated in normal distribution.

Note
The largest value is not infinity with a table, but it depends on the table resolution. With 14 bits, this is roughly four standard deviations above the mean.
template<class RealType = real, unsigned int tableBits = detail::c_TabulatedNormalDistributionDefaultBits>
result_type gmx::TabulatedNormalDistribution< RealType, tableBits >::min ( ) const
inline

Smallest value that can be generated in normal distributon.

Note
The smallest value is not -infinity with a table, but it depends on the table resolution. With 14 bits, this is roughly four standard deviations below the mean.
template<class RealType = real, unsigned int tableBits = detail::c_TabulatedNormalDistributionDefaultBits>
bool gmx::TabulatedNormalDistribution< RealType, tableBits >::operator!= ( const TabulatedNormalDistribution< RealType, tableBits > &  x) const
inline

Check if two tabulated normal distributions have different states.

Parameters
xInstance to compare with.
template<class RealType = real, unsigned int tableBits = detail::c_TabulatedNormalDistributionDefaultBits>
template<class Rng >
result_type gmx::TabulatedNormalDistribution< RealType, tableBits >::operator() ( Rng &  g)
inline

Return normal distribution value specified by internal parameters.

Template Parameters
RngRandom engine type used to provide uniform random bits.
Parameters
gRandom engine of class Rng. For normal GROMACS usage you likely want to use ThreeFry2x64.
template<class RealType = real, unsigned int tableBits = detail::c_TabulatedNormalDistributionDefaultBits>
template<class Rng >
result_type gmx::TabulatedNormalDistribution< RealType, tableBits >::operator() ( Rng &  g,
const param_type param 
)
inline

Return normal distribution value specified by given parameters.

Template Parameters
RngRandom engine type used to provide uniform random bits.
Parameters
gRandom engine of class Rng. For normal GROMACS usage you likely want to use ThreeFry2x64.
paramParameters used to specify normal distribution.
template<class RealType = real, unsigned int tableBits = detail::c_TabulatedNormalDistributionDefaultBits>
bool gmx::TabulatedNormalDistribution< RealType, tableBits >::operator== ( const TabulatedNormalDistribution< RealType, tableBits > &  x) const
inline

Check if two tabulated normal distributions have identical states.

Parameters
xInstance to compare with.

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