smash::random Namespace Reference

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

Classes
class	uniform_dist
	Provides uniform random numbers on a fixed interval. More...
class	discrete_dist
	Discrete distribution with weight given by probability vector. More...
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...

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

Functions
int64_t	generate_63bit_seed ()
	Generates a seed with a truly random 63-bit value, if possible. More...
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

generate_63bit_seed()

int64_t smash::random::generate_63bit_seed

(

)

Generates a seed with a truly random 63-bit value, if possible.

Definition at line 20 of file random.cc.

                                    {
  std::random_device rd;
  static_assert(std::is_same<decltype(rd()), uint32_t>::value,
                "random_device is assumed to generate uint32_t");
  uint64_t unsigned_seed =
      (static_cast<uint64_t>(rd()) << 32) | static_cast<uint64_t>(rd());
  // Discard the highest bit to make sure it fits into a positive int64_t
  const int64_t seed = static_cast<int64_t>(unsigned_seed >> 1);
  return seed;
}

set_seed()

template<typename T >

void smash::random::set_seed

(

T &&

seed

)

Sets the seed of the random number engine.

Definition at line 71 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));
}

advance()

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

inline

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

Definition at line 78 of file random.h.

{ return engine(); }

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 88 of file random.h.

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

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 100 of file random.h.

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

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 113 of file random.h.

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

canonical_nonzero()

template<typename T = double>

T smash::random::canonical_nonzero

(

)

Returns

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

Definition at line 122 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));
}

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 135 of file random.h.

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

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 149 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;
}

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 166 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;
}

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 190 of file random.h.

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

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 203 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);
  }
}

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 226 of file random.h.

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

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 238 of file random.h.

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

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 250 of file random.h.

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

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 307 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);
}

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 329 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);
}

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 351 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);
}

Variable Documentation

engine

random::Engine smash::random::engine

extern

The engine that is used commonly by all distributions.

Definition at line 18 of file random.cc.