smash::random Namespace Reference

Namespace random provides functions for random Number Generation. More...

Classes
class	BesselSampler
	The intention of this class is to efficiently sample \( (N_1, N_2) \) from the Bessel distribution \( p(N_1,N_2) \sim \mathrm{Poi}(\nu_1) \mathrm{Poi}(\nu_2) \delta(N_1 - N_2 = N)\), where \(\mathrm{Poi}(\nu)\) denotes Poisson distribution with mean \(\nu\). More...
class	discrete_dist
	Discrete distribution with weight given by probability vector. More...
class	uniform_dist
	Provides uniform random numbers on a fixed interval. More...

Typedefs
using	Engine = std::mt19937_64
	The random number engine used is the Mersenne Twister. More...

Functions
template<typename T >
void	set_seed (T &&seed)
	Sets the seed of the random number engine. More...
Engine::result_type	advance ()
	Advance the engine's state and return the generated value. More...
template<typename T >
T	uniform (T min, T max)
template<typename T >
T	uniform_int (T min, T max)
template<typename T = double>
T	canonical ()
template<typename T = double>
T	canonical_nonzero ()
template<typename T >
uniform_dist< T >	make_uniform_distribution (T min, T max)
template<typename T = double>
T	exponential (T lambda)
	Draws an exponentially distributed random number. More...
template<typename T = double>
T	expo (T A, T x1, T x2)
	Draws a random number x from an exponential distribution exp(A*x), where A is assumed to be positive, and x is typically negative. More...
template<typename T >
int	sgn (T val)
	Signum function. More...
template<typename T = double>
T	power (T n, T xMin, T xMax)
	Draws a random number according to a power-law distribution ~ x^n. More...
template<typename T >
int	poisson (const T &lam)
	Returns a Poisson distributed random number. More...
template<typename T >
int	binomial (const int N, const T &p)
	Returns a binomially distributed random number. More...
template<typename T >
double	normal (const T &mean, const T &sigma)
	Returns a random number drawn from a normal distribution. More...
template<typename T = double>
T	cauchy (T pole, T width, T min, T max)
	Draws a random number from a Cauchy distribution (sometimes also called Lorentz or non-relativistic Breit-Wigner distribution) with the given parameters (constant width!) inside the range [min,max]. More...
template<typename T = double>
T	beta (T a, T b)
	Draws a random number from a beta-distribution, where probability density of \(x\) is \(p(x) = frac{\Gamma(a)\Gamma(b)}{Gamma(a+b)} x^{a-1} (1-x)^{b-1}\). More...
template<typename T = double>
T	beta_a0 (T xmin, T b)
	Draws a random number from a beta-distribution with a = 0. More...

Variables
Engine	engine
	The engine that is used commonly by all distributions. More...

Detailed Description

Namespace random provides functions for random Number Generation.

Typedef Documentation

Engine

using smash::random::Engine = typedef std::mt19937_64

The random number engine used is the Mersenne Twister.

Definition at line 27 of file random.h.

Function Documentation

set_seed()

template<typename T >

void smash::random::set_seed

(

T &&

seed

)

Sets the seed of the random number engine.

Definition at line 68 of file random.h.

                        {
  static_assert(std::is_same<Engine::result_type, uint64_t>::value,
                "experiment.cc needs the seed to be 64 bits");
  engine.seed(std::forward<T>(seed));
}

Here is the caller graph for this function:

advance()

Engine::result_type smash::random::advance ( )

inline

Advance the engine's state and return the generated value.

Definition at line 75 of file random.h.

{ return engine(); }

Here is the caller graph for this function:

uniform()

template<typename T >

T smash::random::uniform	(	T	min,
		T	max
	)

Returns

A uniformly distributed random real number \(\chi \in [{\rm min}, {\rm max})\)

Parameters

min	Minimal sampled value.
max	Maximal sampled value.

Definition at line 85 of file random.h.

                        {
  return std::uniform_real_distribution<T>(min, max)(engine);
}

Here is the caller graph for this function:

uniform_int()

template<typename T >

T smash::random::uniform_int	(	T	min,
		T	max
	)

Returns

A uniformly distributed random integer number \(\chi \in [{\rm min}, {\rm max})\)

Parameters

min	Minimal sampled value.
max	Maximal sampled value.

Definition at line 97 of file random.h.

                            {
  return std::uniform_int_distribution<T>(min, max)(engine);
}

Here is the caller graph for this function:

canonical()

template<typename T = double>

T smash::random::canonical

(

)

Returns

a uniformly distributed random number \(\chi \in [0,1)\).

Note that the popular implementations in GCC and clang may return 1:

https://gcc.gnu.org/bugzilla/show_bug.cgi?id=64351 https://llvm.org/bugs/show_bug.cgi?id=18767

Definition at line 110 of file random.h.

              {
  return std::generate_canonical<T, std::numeric_limits<double>::digits>(
      engine);
}

Here is the caller graph for this function:

canonical_nonzero()

template<typename T = double>

T smash::random::canonical_nonzero

(

)

Returns

A uniformly distributed random number \(\chi \in (0,1]\).

Definition at line 119 of file random.h.

                      {
  // use 'nextafter' to generate a value that is guaranteed to be larger than 0
  return std::nextafter(
      std::generate_canonical<T, std::numeric_limits<double>::digits>(engine),
      T(1));
}

Here is the caller graph for this function:

make_uniform_distribution()

template<typename T >

uniform_dist<T> smash::random::make_uniform_distribution	(	T	min,
		T	max
	)

Returns

A uniform_dist object.

Parameters

min	Lower bound of interval.
max	Upper bound of interval.

Definition at line 132 of file random.h.

                                                        {
  return uniform_dist<T>(min, max);
}

Here is the caller graph for this function:

exponential()

template<typename T = double>

T smash::random::exponential

(

T

lambda

)

Draws an exponentially distributed random number.

Probability for a given return value \(\chi\) is \(p(\chi) = \Theta(\chi) \cdot \exp(-t)\).

Parameters

lambda

Rate parameter.

Returns

Sampled random number.

Definition at line 146 of file random.h.

                        {
  // We are not using std::exponential_distribution because of a bug in the
  // implementations by clang and gcc.
  return -std::log(canonical_nonzero()) / lambda;
}

Here is the call graph for this function:

expo()

template<typename T = double>

T smash::random::expo	(	T	A,
		T	x1,
		T	x2
	)

Draws a random number x from an exponential distribution exp(A*x), where A is assumed to be positive, and x is typically negative.

The result x is restricted to lie between x1 and x2 (with x2 < x <= x1).

Parameters

A	Positive shape parameter.
x1	Maximal sampled value.
x2	Minimal sampled value.

Returns

Sampled random number.

Definition at line 163 of file random.h.

                        {
  const T a1 = A * x1, a2 = A * x2;
  const T a_min = std::log(std::numeric_limits<T>::min());
#ifndef NDEBUG
  assert(A > T(0.) && x1 >= x2 && a1 > a_min);
#endif
  const T r1 = std::exp(a1);
  const T r2 = a2 > a_min ? std::exp(a2) : T(0.);  // prevent underflow
  T x;
  do {
    /* sample repeatedly until x is in the requested range
     * (it can get outside due to numerical errors, see issue #2959) */
    x = std::log(uniform(r1, r2)) / A;
  } while (!(x <= x1 && x > x2));
  return x;
}

Here is the call graph for this function:

Here is the caller graph for this function:

sgn()

template<typename T >

int smash::random::sgn

(

T

val

)

Signum function.

Parameters

val	The input value.

Returns

The sign of the input value.

Definition at line 187 of file random.h.

               {
  return (T(0) < val) - (val < T(0));
}

Here is the caller graph for this function:

power()

template<typename T = double>

T smash::random::power	(	T	n,
		T	xMin,
		T	xMax
	)

Draws a random number according to a power-law distribution ~ x^n.

Parameters

n	Exponent in power law (arbitrary real number).
xMin	Minimum value.
xMax	Maximum value.

Returns

random number between xMin and xMax.

Definition at line 200 of file random.h.

                             {
  const T n1 = n + 1;
  if (std::abs(n1) < 1E-3) {
    return xMin * std::pow(xMax / xMin, canonical());
  } else if (xMin > 0. && xMax > 0.) {
    return std::pow(uniform(std::pow(xMin, n1), std::pow(xMax, n1)), 1. / n1);
  } else {
    return sgn(xMin) * std::pow(uniform(std::pow(std::abs(xMin), n1),
                                        std::pow(std::abs(xMax), n1)),
                                1. / n1);
  }
}

Here is the call graph for this function:

Here is the caller graph for this function:

poisson()

template<typename T >

int smash::random::poisson

(

const T &

lam

)

Returns a Poisson distributed random number.

Probability for a given return value \(\chi\) is \(p(\chi) = \chi^i/i! \cdot \exp(-\chi)\)

Parameters

lam	Mean value of the distribution.

Returns

Sampled random number.

Definition at line 223 of file random.h.

                          {
  return std::poisson_distribution<int>(lam)(engine);
}

Here is the caller graph for this function:

binomial()

template<typename T >

int smash::random::binomial	(	const int	N,
		const T &	p
	)

Returns a binomially distributed random number.

Parameters

N	Number of trials.
p	Probability of a trial generating true.

Returns

Sampled random number.

Definition at line 235 of file random.h.

                                      {
  return std::binomial_distribution<int>(N, p)(engine);
}

Here is the caller graph for this function:

normal()

template<typename T >

double smash::random::normal	(	const T &	mean,
		const T &	sigma
	)

Returns a random number drawn from a normal distribution.

Parameters

mean	Mean value of the distribution.
sigma	Standard deviation of the distribution.

Returns

Sampled random number.

Definition at line 247 of file random.h.

                                             {
  return std::normal_distribution<double>(mean, sigma)(engine);
}

Here is the caller graph for this function:

cauchy()

template<typename T = double>

T smash::random::cauchy	(	T	pole,
		T	width,
		T	min,
		T	max
	)

Draws a random number from a Cauchy distribution (sometimes also called Lorentz or non-relativistic Breit-Wigner distribution) with the given parameters (constant width!) inside the range [min,max].

This function is similar to std::cauchy_distribution, but can return values inside a limited interval.

Parameters

pole	Pole parameter of the Cauchy function, i.e. location of the peak.
width	Width parameter of the Cauchy function, determining the sharpness of the peak.
min	Minimum value to be returned.
max	Maximum value to be returned.

Returns

Sampled random number.

Definition at line 304 of file random.h.

                                        {
  /* Use double-precision variables, in order to work around a glibc bug in
   * tanf:
   * https://sourceware.org/bugzilla/show_bug.cgi?id=18221 */
  const double u_min = std::atan((min - pole) / width);
  const double u_max = std::atan((max - pole) / width);
  const double u = uniform(u_min, u_max);
  return pole + width * std::tan(u);
}

Here is the call graph for this function:

Here is the caller graph for this function:

beta()

template<typename T = double>

T smash::random::beta	(	T	a,
		T	b
	)

Draws a random number from a beta-distribution, where probability density of \(x\) is \(p(x) = frac{\Gamma(a)\Gamma(b)}{Gamma(a+b)} x^{a-1} (1-x)^{b-1}\).

This distribution is necessary for string formation. The implementation uses a property connecting beta distribution to gamma-distribution. Interchanging a and b will not change results.

Parameters

a	Shape parameter.
b	Scale parameter.

Returns

Sampled random number.

Definition at line 326 of file random.h.

                 {
  // Otherwise the integral over probability density diverges
  assert(a > T(0.0) && b > T(0.0));
  const T x1 = std::gamma_distribution<T>(a)(engine);
  const T x2 = std::gamma_distribution<T>(b)(engine);
  return x1 / (x1 + x2);
}

Here is the caller graph for this function:

beta_a0()

template<typename T = double>

T smash::random::beta_a0	(	T	xmin,
		T	b
	)

Draws a random number from a beta-distribution with a = 0.

In this case the probability density is \(p(x) = 1/x (1-x)^b\). The integral from 0 to 1 over this distribution diverges, so the sampling is performed in the interval (xmin, 1). This distribution is necessary for string formation. The implementation uses the following property: \(p(x)dx = dx/x (1-x)^b = (1-x)^b d ln(x) = (1 - e^{-y})^b dy\), where \( y = - ln(x) \).

Parameters

xmin	Minimal sampled value.
b	Second shape parameter.

Returns

Sampled random number.

Definition at line 348 of file random.h.

                       {
  assert(xmin > T(0.0) && xmin < T(1.0));
  T y;
  do {
    y = uniform(0.0, -std::log(xmin));
  } while (std::pow((1.0 - std::exp(-y)), b) < canonical());
  return std::exp(-y);
}

Here is the call graph for this function:

Here is the caller graph for this function:

Variable Documentation

engine

random::Engine smash::random::engine

The engine that is used commonly by all distributions.

Definition at line 15 of file random.cc.