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

#include <gromacs/random/gammadistribution.h>

Description

template<class RealType = real>
class gmx::GammaDistribution< RealType >

Gamma distribution.

The C++ standard library does provide a gamma distribution, but when using libstdc++-4.4.7 with at least gcc-4.6 or icc-14.0 the headers produce errors. Even for newer compilers, libstdc++ and libc++ appear to use different algorithms to generate it, which means their values differ in contrast to the uniform and normal distributions where they are identical. To avoid both compiler bugs and make it easier to use GROMACS unit tests that depend on random numbers, we have our own implementation.

Be warned that the gamma distribution works like the standard normal distribution and keeps drawing values from the random engine in a loop, so you want to make sure you use a random stream with a very large margin to make sure you do not run out of random numbers in an unlucky case (which will lead to an exception with the GROMACS default random engine).

The gamma distribution is defined as

\[ p(x|\alpha,\theta) = \frac{1}{\Gamma(\alpha)\theta^{alpha}} x^{\alpha - 1} e^{-\frac{x}{\theta}}, x\geq 0 , \alpha>0, \theta>0 \]

In this definition, the parameter α is the so-called shape, while θ is so-called scale. This distribution will have the expectation value αθ, and the variance αθθ.

Note
The gamma distribution is sometimes defined in terms of a parameter β that is the inverse of θ (i.e., a rate rather than scale), while in other cases the parameter in the definition above is simply called β. We can't do a lot about these different definitions, so make sure you look at the expectation value and variance unless you are certain you are using e.g. scale or rate for the second parameter - do not trust that it e.g. rate just because it is called β in your equations.
For now, we generate the gamma distribution using the algorithm from Marsaglia G, Tsang WW (2000). ACM Trans. Math. Softw. 26(3), 363-372. DOI:10.1145/358407.358414
Template Parameters
RealTypeFloating-point type, real by default in GROMACS.

Classes

class  param_type
 Gamma distribution parameters. More...
 

Public Types

typedef RealType result_type
 Type of values returned.
 

Public Member Functions

 GammaDistribution (result_type alpha=1.0, result_type theta=1.0)
 Construct new distribution with given floating-point parameters. More...
 
 GammaDistribution (const param_type &param)
 Construct new distribution from parameter class. More...
 
void reset ()
 Flush all internal saved values.
 
template<class Rng >
result_type operator() (Rng &g)
 Return values from gamma distribution with internal parameters. More...
 
template<class Rng >
result_type operator() (Rng &g, const param_type &param)
 Return value from gamma distribution with given parameters. More...
 
result_type alpha () const
 Return the shape parameter of gamma distribution.
 
result_type theta () const
 Return the scale parameter of gamma distribution.
 
param_type param () const
 Return the full parameter class of gamma distribution.
 
result_type min () const
 Smallest value that can be returned from gamma distribution.
 
result_type max () const
 Largest value that can be returned from gamma distribution.
 
bool operator== (const GammaDistribution &x) const
 True if two gamma distributions will produce the same values. More...
 
bool operator!= (const GammaDistribution &x) const
 True if two gamma distributions will produce different values. More...
 

Constructor & Destructor Documentation

template<class RealType = real>
gmx::GammaDistribution< RealType >::GammaDistribution ( result_type  alpha = 1.0,
result_type  theta = 1.0 
)
inlineexplicit

Construct new distribution with given floating-point parameters.

Parameters
alphaShape parameter of gamma distribution
thetaScale parameter of gamma distribution
Exceptions
InvalidInputErrorif either parameter is negative or zero.
template<class RealType = real>
gmx::GammaDistribution< RealType >::GammaDistribution ( const param_type param)
inlineexplicit

Construct new distribution from parameter class.

Parameters
paramParameter class as defined inside gmx::GammaDistribution.

Member Function Documentation

template<class RealType = real>
bool gmx::GammaDistribution< RealType >::operator!= ( const GammaDistribution< RealType > &  x) const
inline

True if two gamma distributions will produce different values.

Parameters
xInstance to compare with.
template<class RealType = real>
template<class Rng >
result_type gmx::GammaDistribution< RealType >::operator() ( Rng &  g)
inline

Return values from gamma distribution with internal parameters.

Template Parameters
RngRandom engine class
Parameters
gRandom engine
template<class RealType = real>
template<class Rng >
result_type gmx::GammaDistribution< RealType >::operator() ( Rng &  g,
const param_type param 
)
inline

Return value from gamma distribution with given parameters.

Template Parameters
RngRandom engine class
Parameters
gRandom engine
paramParameters to use
template<class RealType = real>
bool gmx::GammaDistribution< RealType >::operator== ( const GammaDistribution< RealType > &  x) const
inline

True if two gamma distributions will produce the same values.

Parameters
xInstance to compare with.

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