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)
	Sample from a power-law probability density proportional to \|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 30 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 21 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;
 }

Here is the caller graph for this function:

◆ set_seed()

template<typename T >

void smash::random::set_seed ( T && seed )

Sets the seed of the random number engine.

Definition at line 74 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 81 of file random.h.

81 { 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 91 of file random.h.

                         {
   /* Strictly speaking, a distribution could be created with min == max, but
    * then it would be UB to use the call operator(), which we do here. */
   assert(min < max);
   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 106 of file random.h.

                             {
   /* Strictly speaking, a distribution could be created with min == max, but
    * then it would be UB to use the call operator(), which we do here. */
   assert(min < max);
   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 122 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 131 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 144 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 158 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.

Exceptions

std::logic_error if the computed sampling interval is degenerate, reversed, or otherwise invalid.

Definition at line 178 of file random.h.

                         {
   const T a1 = A * x1, a2 = A * x2;
   const T a_min = std::log(std::numeric_limits<T>::min());
   assert(A > T(0.) && x1 > x2 && a1 > a_min);
   const T high = std::exp(a1);
   const T low = a2 > a_min ? std::exp(a2) : T(0.);  // prevent underflow
   if (unlikely(!(low < high))) {                    // catches NANs, too
     std::ostringstream error_message{};
     error_message << "Function " << __func__
                   << ": internal invariant 'low < high' violated (low = " << low
                   << ", high = " << high << ")";
     throw std::logic_error(error_message.str());
   }
   T x{};
   do {
     /* sample repeatedly until x is in the requested range
      * (it can get outside due to numerical errors). */
     x = std::log(uniform(low, high)) / 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 207 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
	)

Sample from a power-law probability density proportional to |x|^n.

The sample is drawn on the interval [xMin, xMax]. The interval must lie entirely on one side of zero; intervals crossing zero are not supported. Negative intervals are handled by sampling the absolute values and restoring the negative sign. For n ≈ -1, the distribution is sampled using the logarithmic limit.

Template Parameters

T	Floating-point type.

Parameters

n	Power-law exponent.
xMin	Lower interval bound.
xMax	Upper interval bound.

Returns: Random value distributed as p(x) ∝ |x|^n on the given interval.

Exceptions

std::invalid_argument	if the interval crosses zero.
std::invalid_argument	if the interval touches zero and n <= -1, where the distribution is not normalizable.

Definition at line 229 of file random.h.

                              {
   const T n1 = n + T(1);
  
   if ((xMin < 0 && xMax > 0) || (xMax < 0 && xMin > 0)) {
     throw std::invalid_argument(
         "power: interval crossing zero is not supported");
   } else if ((xMin == 0 || xMax == 0) && n <= -1) {
     throw std::invalid_argument("power: distribution not normalizable at x=0");
   }
  
   if (xMin > xMax) {
     std::swap(xMin, xMax);
   }
   const T sign = xMax < T(0) ? T(-1) : T(1);
  
   const T lo = std::abs(xMin);
   const T hi = std::abs(xMax);
  
   if (std::abs(n1) < T(1e-3)) {
     return sign * lo * std::pow(hi / lo, canonical());
   }
  
   T a = std::pow(lo, n1);
   T b = std::pow(hi, n1);
  
   if (a > b) {
     std::swap(a, b);
   }
  
   return sign * std::pow(uniform(a, b), T(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 270 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 282 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 294 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 351 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 373 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 395 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

extern

The engine that is used commonly by all distributions.

Definition at line 19 of file random.cc.

Classes

Typedefs

Functions

Variables

Detailed Description

Typedef Documentation

◆ Engine

Function Documentation

◆ generate_63bit_seed()

◆ set_seed()

◆ advance()

◆ uniform()

◆ uniform_int()

◆ canonical()

◆ canonical_nonzero()

◆ make_uniform_distribution()

◆ exponential()

◆ expo()

◆ sgn()

◆ power()

◆ poisson()

◆ binomial()

◆ normal()

◆ cauchy()

◆ beta()

◆ beta_a0()

Variable Documentation

◆ engine