Generator¶

template<typename RandomEngine> class Generator¶

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.

using namespace HighFM::random;
DefaultGenerator rng;              // Creates a new DefaultGenerator with the default seed and stream
int n = rng.uniform<int>(-10, 10); // Generates a random integer from U(-10, 10)
double f = rng();                  // Generates a random double from U(0, 1)
double e = rng.exp(2.0);           // Generates a random double from EXP with 2.0 as the rate parameter
DefaultGenerator rng2(8723, 6781); // Creates a new DefaultGenerator with seed=8723 and stream=6781
Generator<Xoroshiro128> rng3(87771); //Creates a new Generator using the Xoroshiro128 as RandomEngine with seed = 87771

Note

When using multiple Generator instances, it is recommended to use a hash function (such as the hash64() or hash128() methods) to create the seeds (and streams, if applicable) in order to spread them over a wider range of initialization states of the RandomEngine and reducing the chances of similarities between the instances.

Basic Functions

inline Generator(state_type seed = default_seed, state_type stream = default_stream)¶: Creates an instance of a random generator.

inline Generator(const Generator &other)¶

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

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

inline Generator(const RandomEngine &other)¶

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

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

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

Copy the internal parameters from other.

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

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

Copy the internal parameters from other.

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

inline constexpr void seed(state_type seed = default_seed, state_type stream = default_stream)¶

Reseeds the generator.

Parameters:

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

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

Random Generation

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

template<std::floating_point T> inline T random()¶

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

Returns:: A random floating-point number

template<Complex T> inline T random()¶

Generates a random complex number with a real and imaginary part in the range [0, 1], considering an uniform distribution.

Returns:: A random complex number

template<std::integral T> 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 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

Random Distributions

template<Number T> inline T uniform(T low = T(0), T high = T(1))¶

Draws a sample from a uniform distribution. The samples are uniformly distributed over the semi-closed interval [low, high). This routine may have a slight 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<Number T, template<typename, typename> typename S> inline void uniform(Matrix<T, Host, S> &A, T low = T(0), T high = T(1))¶

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

Parameters:

A – [out] Output Matrix
low – [in] Lower limit of the range
high – [in] Upper limit of the range

template<Number T, template<typename, typename> typename S> inline void uniform(Vector<T, Host, S> &vec, T low = T(0), T high = T(1))¶

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

Parameters:

vec – [out] Output Vector
low – [in] Lower limit of the range
high – [in] Upper limit of the range

template<std::floating_point 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<std::floating_point T> inline T normal(T mu = 0.0, T sigma = 1.0)¶

Generates a random number from the normal distribution using the Box-Muller method.

Parameters:

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

Returns:

A random floating-point number

template<std::floating_point T, template<typename, typename> typename S> inline void normal(Matrix<T, Host, S> &A, T mu = 0.0, T sigma = 1.0)¶

Generates a random matrix from the normal distribution using the Box-Muller method.

Parameters:

A – [out] Output Matrix
mu – [in] mean value
sigma – [in] standard deviation

template<std::floating_point T, template<typename, typename> typename S> inline void normal(Vector<T, Host, S> &vec, T mu = 0.0, T sigma = 1.0)¶

Generates a random vector from the normal distribution using the Box-Muller method.

Parameters:

vec – [out] Output Vector
mu – [in] mean value
sigma – [in] standard deviation

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

Generates a random number from the normal distribution using the Box-Muller method.

Parameters:

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

Returns:

A random floating-point number

template<std::floating_point T> inline std::tuple<T, T> normal2(T mu = 0.0, T sigma = 1.0)¶

Generates two random numbers from the normal distribution using the Box-Muller method.

Parameters:

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

Returns:

Two random floating-point numbers

Public Static Attributes

static constexpr short bytes = RandomEngine::bytes¶: The number of bytes generated.

static constexpr uint64_t max_val = RandomEngine::max_val¶: The largest possible value generated.

static constexpr uint64_t min_val = RandomEngine::min_val¶: The smallest possible value generated.