Random Module¶

Generator¶

template<typename RandomEngine> class Generator : public RandomEngine ¶

The Generator class transforms the random bits generated by the RandomEngine (e.g., PCG, Xoroshiro or SplitMix) into a samples from a wide range of probability distributions as well as other random-based utilities (such as, shuffle()). The DefaultGenerator uses PCG64 as RandomEngine.

Basic Functions

inline Generator()¶: Default Constructor. Creates an instance of a random generator.

inline Generator(const Generator &other)¶

Copy Constructor. Creates a new generator and then copies the internal parameters from other.

Parameters:: other – [in] a random engine to use as data source

inline Generator(const RandomEngine &other)¶

Copy Constructor. Creates a new generator and then copies the internal parameters from other.

Parameters:: other – [in] a random engine to use as data source

inline Generator &operator=(const Generator &other)¶

Copy Assignment. Copy the internal parameters from other.

Parameters:: other – [in] a random engine to use as data source
Returns:: *this

inline Generator &operator=(const RandomEngine &other)¶

Copy Assignment. Copy the internal parameters from other.

Parameters:: other – [in] a random engine to use as data source
Returns:: *this

virtual ~Generator() = default¶: Default Destructor.

Random Generation

template<typename T, std::enable_if_t<std::is_floating_point_v<T>, bool> = true> inline T random()¶

Generates a random number between 0.0 and 1.0, considering an uniform distribution.

Returns:: a random float

template<typename T, std::enable_if_t<std::is_integral_v<T>, bool> = true> inline T random()¶

Generates a random number between 0 and the maximum value of T, considering an uniform distribution. For example, if T == bool, this generates either a 0 or 1.

Returns:: a random integer

inline auto operator()()¶

Returns:: a random floating-point number between 0.0 and 1.0. The precision of the the number depends on the RandomEngine used.

Permutations and Utilities

template<typename Seq> inline void shuffle(Seq &&seq)¶

Shuffles the contents of a sequence using the Fisher–Yates algorithm. A seq can be any container that defines a [] operator and a size() routine.

Parameters:: seq – [inout] sequence to be shuffled

template<typename Seq, typename ProbVec> inline index_t choose(const Seq &seq, const ProbVec &prob)¶

Draws a random sample from a sequence (with replacement). A seq and prob can be any container that defines a [] operator and a size() routine.

Parameters:

seq – [in] sequence to use as data source
prob – [in] the cumulative probability associated with each entry of seq. If not given, assumes an uniform distribution over all elements of seq

Returns:

a random sample from seq

template<typename ProbVec> inline index_t choose_index(const ProbVec &prob)¶

Draws a random index considering the cumulative probability defined in prob.

Parameters:: prob – [in] cummulative probability associated with each index
Returns:: a random index

Random Distributions

template<typename T> inline T uniform(T low, T high)¶

Draws a sample from a uniform distribution. The samples are uniformly distributed over the semi-closed interval [low, high). This routine may be slightly bias toward some numbers in the range (scaling by floating-point/integer multiplication).

Parameters:

low – [in] Lower limit of the range
high – [in] Upper limit of the range

Returns:

a random number from the interval

template<typename T> inline EWiseNullaryOp<T, internal::rand_uniform_op<T, RandomEngine>, 1> uniform(index_t n, T low, T high)¶

Draws n samples from a uniform distribution. The samples are uniformly distributed over the semi-closed interval [low, high). This routine may be slightly bias toward some numbers in the range (scaling by floating-point/integer multiplication).

Parameters:

n – [in] number of samples
low – [in] Lower limit of the range
high – [in] Upper limit of the range

Returns:

a random vector

template<typename T> inline EWiseNullaryOp<T, internal::rand_uniform_op<T, RandomEngine>, 2> uniform(index_t nrows, index_t ncols, T low, T high)¶

Draws nrows * ncols samples from a uniform distribution. The samples are uniformly distributed over the semi-closed interval [low, high). This routine may be slightly bias toward some numbers in the range (scaling by floating-point/integer multiplication).

Parameters:

nrows – [in] number of rows
ncols – [in] number of columns
low – [in] Lower limit of the range
high – [in] Upper limit of the range

Returns:

a random matrix

template<typename T> inline T exp(T lambda = 1.0)¶

Draws a sample from an exponential distribution, whose probability density function is defined as

\[ f(x; \lambda) = \lambda \exp(-\lambda x) \]

for \(x > 0\), \(0\) otherwise.

Parameters:: lambda – [in] rate parameter
Returns:: a random floating-point number

template<typename T> inline T normal(T mu = 0.0, T sigma = 1.0)¶

Generates a random number from the normal distribution. This routine uses the Ziggurat method [1] and code was adapted from [2].

References: [1] G. Marsaglia and W. W. Tsang, “The Ziggurat Method for Generating Random Variables,” J. Stat. Soft., vol. 5, no. 8, 2000, doi: 10.18637/jss.v005.i08. [2] NumPy repository: https://github.com/numpy/numpy/blob/main/numpy/random/src/distributions/distributions.c

Parameters:

mu – [in] mean value
sigma – [in] standard deviation

Returns:

a random floating-point number

template<typename T> inline EWiseNullaryOp<T, internal::rand_normal_op<T, RandomEngine>, 1> normal(index_t n, T mu, T sigma)¶

Generates n random samples from the normal distribution. This routine uses the Ziggurat method [1] and code was adapted from [2].

Parameters:

n – [in] number of samples
mu – [in] mean value
sigma – [in] standard deviation

Returns:

a random vector

template<typename T> inline EWiseNullaryOp<T, internal::rand_normal_op<T, RandomEngine>, 2> normal(index_t nrows, index_t ncols, T mu, T sigma)¶

Generates nrows * ncols random samples from the normal distribution. This routine uses the Ziggurat method [1] and code was adapted from [2].

Parameters:

nrows – [in] number of rows
ncols – [in] number of columns
mu – [in] mean value
sigma – [in] standard deviation

Returns:

a random matrix

template<typename T> inline T mittag_leffler(const T alpha, const T gamma, const T sin_alpha, const T cos_alpha)¶

Draw a sample from a Mittag-Leffler (ML) probability distribution [1] using Kozubowski and Ratchev transformation formula [2-3]. For \( 0 < \alpha \leq 1\), a Mittag-Leffer random number \(Y_\alpha \) can be generated as follows:

/f[ Y_\alpha = - \ln{U} \, [\gamma \sin(\alpha\pi) \cot(\alpha \pi V) - \cos(\alpha\pi)]^{\frac{1}{\alpha}} \f]

with \( \gamma\) as the scale parameter and \(U, V \in [0, 1]\) as uniform random numbers.

References: [1] R. N. Pillai, ‘On Mittag-Leffler functions and related distributions’, Ann Inst Stat Math, vol. 42, no. 1, pp. 157–161, Mar. 1990, doi: 10.1007/BF00050786.

[2] T. J. Kozubowski and S. T. Rachev, ‘Univariate Geometric Stable Laws’, Journal of Computational Analysis and Applications, vol. 1, no. 2, pp. 177–217, Apr. 1999, doi: 10.1023/A:1022629726024.

[3] T. J. Kozubowski, ‘Computer simulation of geometric stable distributions’, Journal of Computational and Applied Mathematics, vol. 116, no. 2, pp. 221–229, Apr. 2000, doi: 10.1016/S0377-0427(99)00318-0.

Parameters:

alpha – [in] ML parameter ( \(0 < \alpha \leq 1\))
gamma – [in] scale parameter
sin_alpha – [in] precalculated \(\sin(\alpha\pi)\) (optional)
cos_alpha – [in] precalculated \(\cos(\alpha\pi)\) (optional)

Returns:

a random floating-point number

template<typename T> inline T levy_stable(const T alpha, const T scale = 1.0, const T loc = 0.0)¶

Draw a sample from a Levy \(\alpha\)-stable probability distribution based on Chambers, Mallows and Stuck method [1]. This code was adapted from the arlpy package for Python (https://github.com/org-arl/arlpy/tree/master).

References: [1] J. M. Chambers, C. L. Mallows, and B. W. Stuck, “A Method for Simulating Stable Random Variables,” Journal of the American Statistical Association, vol. 71, no. 354, pp. 340–344, Jun. 1976, doi: 10.1080/01621459.1976.10480344.

Parameters:

alpha – Levy parameter ( \(0 < \alpha \leq 2\))
scale – scale parameter
loc – location parameter

Returns:

a random floating-point number

PCG64¶

class PCG64¶

A C++ implementation of the PCG64 random number generator from the Permuted Congruential Generator (PCG) family. A improved version of the NumPy’s default generator (PCG64DXSM, see https://numpy.org/doc/stable/reference/random/upgrading-pcg64.html for more details).

Original design by Melissa E. O’Neill. For more information about the PCG family of random number generators, please visit https://www.pcg-random.org/.

Note

For the best performance, it is recommended to use a platform and compiler that supports 128-bit integer arithmetic. Otherwise, MOCCA must emulate all the operations, which may result in a significant performance loss.

Public Functions

inline PCG64(uint128_t seed = PCG64_DEFAULT_SEED, uint128_t stream = PCG64_DEFAULT_STREAM)¶

Constructor. Creates a new instance of the PCG64 generator.

Parameters:

seed – [in] generator seed (optional)
stream – [in] generator stream (optional)

inline PCG64(const PCG64 &other)¶

Copy Constructor. Creates a new instance of the PCG64 generator from other instance.

Parameters:: other – [in] PCG64 generator to use as data source

PCG64 &operator=(const PCG64 &other) = default¶

Copy assignment. Copy the internal state from other.

Parameters:: other – [in] PCG64 generator to use as data source
Returns:: *this

virtual ~PCG64() = default¶: Default destructor.

inline constexpr void seed(uint128_t seed, uint128_t stream = PCG64_DEFAULT_STREAM)¶

Reseeds the generator.

Parameters:

seed – [in] generator seed
stream – [in] generator stream (optional)

inline constexpr void set_stream(uint128_t stream)¶: Sets the generator stream to a given value.

Note

A single call to the seed() method with only one argument will reset the stream to the default value.

inline constexpr uint64_t next()¶: Advances the generator state and generates a new pseudorandom 64-bits integer.

Note

This code was adapted from the NumPy GitHub repository (v1.21.6). See https://github.com/numpy/numpy for the original code.

inline constexpr uint64_t operator()()¶: Advances the generator state and generates a new pseudorandom 64-bits integer.

Public Static Functions

static inline constexpr uint64_t max()¶

Returns:: the largest possible value generated (UINT64_MAX)

static inline constexpr uint64_t min()¶

Returns:: the smallest possible value generated (0)

static inline constexpr short bytes()¶

Returns:: the number of bytes generated

PCG32¶

class PCG32¶

A C++ implementation of the PCG32 random number generator from the Permuted Congruential Generator (PCG) family. This version uses the XSH RR variant. Designed by Melissa E. O’Neill.

For more information about the PCG family of random number generators, please visit https://www.pcg-random.org/.

Public Functions

inline PCG32(uint64_t seed = PCG32_DEFAULT_SEED, uint64_t stream = PCG32_DEFAULT_STREAM)¶

Constructor. Creates a new instance of the PCG32 generator.

Parameters:

seed – [in] generator seed (optional)
stream – [in] generator stream (optional)

inline PCG32(const PCG32 &other)¶

Copy Constructor. Creates a new instance of the PCG32 generator from other instance.

Parameters:: other – [in] PCG32 generator to use as data source

PCG32 &operator=(const PCG32 &other) = default¶

Copy assignment. Copy the internal state from other.

Parameters:: other – [in] PCG32 generator to use as data source
Returns:: *this

virtual ~PCG32() = default¶: Default destructor.

inline constexpr void seed(uint64_t seed, uint64_t stream = PCG32_DEFAULT_STREAM)¶

Reseeds the generator.

Parameters:

seed – [in] generator seed
stream – [in] generator stream (optional)

inline constexpr void set_stream(uint64_t stream)¶: Sets the generator stream to a given value.

Note

A single call to the seed() method with only one argument will reset the stream to the default value.

inline constexpr uint32_t next()¶: Advances the generator state and generates a new pseudorandom 32-bits integer.

inline constexpr uint32_t operator()()¶: Advances the generator state and generates a new pseudorandom 32-bits integer.

Public Static Functions

static inline constexpr uint32_t max()¶

Returns:: the largest possible value generated (UINT32_MAX)

static inline constexpr uint32_t min()¶

Returns:: the smallest possible value generated (0)

static inline constexpr short bytes()¶

Returns:: the number of bytes generated

SplitMix64¶

class SplitMix64¶

A C++ implementation of the SplitMix random number generator

Original design by Guy L. Steele, Jr., Doug Lea and Christine H. Flood Described in Fast splittable pseudorandom number generators (http://dx.doi.org/10.1145/2714064.2660195) and implemented in Java 8 as SplittableRandom.

Based on the code from the original paper and Melissa E. O’Neill C++ implementation (https://www.pcg-random.org/posts/some-prng-implementations.html), besides other public available sources.

Subclassed by mocca::random::SplitMix32

Public Functions

inline SplitMix64(uint64_t seed = SPLITMIX_DEFAULT_SEED, uint64_t gamma = SPLITMIX_DEFAULT_GAMMA)¶

Constructor. Creates a new instance of the SplitMix64 generator.

Parameters:

seed – [in] generator seed
gamma – [in] generator increment

inline SplitMix64(const SplitMix64 &other)¶

Copy Constructor. Creates a new instance of the SplitMix64 generator from other generator.

Parameters:: other – [in] SplitMix64 generator to use as data source

SplitMix64 &operator=(const SplitMix64 &other) = default¶

Copy assignment. Copy the internal state and gamma from other.

Parameters:: other – [in] SplitMix64 generator to use as data source
Returns:: *this

virtual ~SplitMix64() = default¶: Default destructor.

inline constexpr void seed(uint64_t seed, uint64_t gamma = SPLITMIX_DEFAULT_GAMMA)¶

Reseeds the generator.

Parameters:

seed – [in] generator seed
gamma – [in] generator increment

inline constexpr uint64_t next()¶: Advances the generator state and generates a new pseudorandom 64-bits integer.

inline constexpr uint64_t operator()()¶: Advances the generator state and generates a new pseudorandom 64-bits integer.

inline SplitMix64 split()¶: “Splits” the generator, creating a new instance of SplitMix64 in the process.

Public Static Functions

static inline constexpr uint64_t max()¶

Returns:: the largest possible value generated (UINT64_MAX)

static inline constexpr uint64_t min()¶

Returns:: the smallest possible value generated (0)

static inline constexpr short bytes()¶

Returns:: the number of bytes generated

SplitMix32¶

class SplitMix32 : public mocca::random::SplitMix64 ¶

The 32-bits version of the SplitMix random number generator. Internally, this generator is identical to the SplitMix64 generator, except for the “mixing” function, which discards the low order bits to create a pseudorandom 32-bits number, besides other optimisations.

Xoroshiro256¶

class Xoroshiro256¶

A C++ implementation of the Xoroshiro256++ random number generator.

Original design by David Blackman and Sebastiano Vigna as described in their paper: Scrambled Linear Pseudorandom Number Generators (https://arxiv.org/pdf/1805.01407.pdf).

Based on the C code at Vigna’s website (https://prng.di.unimi.it/).

Public Functions

inline Xoroshiro256(uint64_t seed = SPLITMIX_DEFAULT_SEED, uint64_t gamma = SPLITMIX_DEFAULT_GAMMA)¶

Constructor. Creates a new instance of the Xoroshiro256 generator. This routine uses a SplitMix64 generator to populate the 256-bits internal state.

Parameters:

seed – [in] seed for the SplitMix64 generator(optional)
gamma – [in] gamma for the SplitMix64 generator(optional)

inline Xoroshiro256(uint64_t seeds[4])¶

Constructor. Creates a new instance of the Xoroshiro256 generator and initialize its 256-bit internal state using seeds.

Parameters:: seeds – [in] initial state

inline Xoroshiro256(const Xoroshiro256 &other)¶

Copy Constructor. Creates a new instance of the Xoroshiro256 generator from other instance.

Parameters:: other – [in] Xoroshiro256 generator to use as data source

inline Xoroshiro256 &operator=(const Xoroshiro256 &other)¶

Copy assignment. Copy the internal state from other.

Parameters:: other – [in] Xoroshiro256 generator to use as data source
Returns:: *this

virtual ~Xoroshiro256() = default¶: Default destructor.

inline void seed(uint64_t seed, uint64_t gamma = SPLITMIX_DEFAULT_GAMMA)¶

Populate the internal state using the SplitMix64 generator.

Parameters:

seed – [in] seed for the SplitMix64 generator
gamma – [in] gamma for the SplitMix64 generator(optional)

inline void seed(uint64_t state[4])¶

Set the internal state to state.

Parameters:: state – [in] 256-bit number to use as data source

inline constexpr uint64_t next()¶: Advances the generator state and generates a new pseudorandom 64-bits integer.

inline constexpr uint64_t operator()()¶: Advances the generator state and generates a new pseudorandom 64-bits integer.

Public Static Functions

static inline constexpr uint64_t max()¶

Returns:: the largest possible value generated (UINT64_MAX)

static inline constexpr uint64_t min()¶

Returns:: the smallest possible value generated (1)

static inline constexpr short bytes()¶

Returns:: the number of bytes generated

Xoroshiro128¶

class Xoroshiro128¶

A C++ implementation of the Xoroshiro128++ random number generator.

Original design by David Blackman and Sebastiano Vigna, described in ther paper: Scrambled Linear Pseudorandom Number Generators (https://arxiv.org/pdf/1805.01407.pdf).

Based on the C code at Vigna’s website (https://prng.di.unimi.it/).

Public Functions

inline Xoroshiro128(uint64_t seed = SPLITMIX_DEFAULT_SEED, uint64_t gamma = SPLITMIX_DEFAULT_GAMMA)¶

Constructor. Creates a new instance of the Xoroshiro128 generator. This routine uses a SplitMix32 generator to populate the 128-bit internal state.

Parameters:

seed – [in] seed for the SplitMix32 generator (optional)
gamma – [in] gamma for the SplitMix64 generator(optional)

inline Xoroshiro128(uint32_t seeds[4])¶

Constructor. Creates a new instance of the Xoroshiro256 generator and initialize its 128-bit internal state using seeds.

Parameters:: seeds – [in] initial state

inline Xoroshiro128(const Xoroshiro128 &other)¶

Copy Constructor. Creates a new instance of the Xoroshiro128 generator from other instance.

Parameters:: other – [in] Xoroshiro128 generator to use as data source

inline Xoroshiro128 &operator=(const Xoroshiro128 &other)¶

Copy assignment. Copy the internal state from other.

Parameters:: other – [in] Xoroshiro128 generator to use as data source
Returns:: *this

virtual ~Xoroshiro128() = default¶: Default destructor.

inline void seed(const uint64_t seed, uint64_t gamma = SPLITMIX_DEFAULT_GAMMA)¶

Populate the internal state using a SplitMix32 generator.

Parameters:

seed – [in] seed for the SplitMix32 generator
gamma – [in] gamma for the SplitMix64 generator(optional)

inline void seed(const uint32_t state[4])¶

Set the internal state to state.

Parameters:: state – [in] 128-bit number to use as data source

inline constexpr uint32_t next()¶: Advances the generator state and generates a new pseudorandom 32-bits integer.

inline constexpr uint32_t operator()()¶: Advances the generator state and generates a new pseudorandom 32-bits integer.

Public Static Functions

static inline constexpr uint32_t max()¶

Returns:: the largest possible value generated (UINT32_MAX)

static inline constexpr uint32_t min()¶

Returns:: the smallest possible value generated (1)

static inline constexpr short bytes()¶

Returns:: the number of bytes generated

Hash¶

static inline uint128_t hash128(uint64_t key)¶

A C++ implementation of the MurmurHash3 (x64-128 variant), a fast non-cryptographic hash function suitable created by Austin Appleby (https://github.com/aappleby/smhasher).

Parameters:: key – [in] 64-bit value
Returns:: a 128-bit hash value

static inline uint64_t hash64(uint64_t key)¶

A C++ implementation of the MurmurHash3 (x64-128 variant), a fast non-cryptographic hash function suitable created by Austin Appleby (https://github.com/aappleby/smhasher).

Parameters:: key – [in] 64-bit value
Returns:: the upper half of the 128-bit hash value