random.h File Reference

#include "kernel/interval.h"
#include "utility/assert.h"
#include "utility/misc.h"
#include "utility/xoshiro256ss.h"
#include <random>
#include <type_traits>

Go to the source code of this file.

Namespaces
namespace	ultra

Typedefs
using	ultra::random::engine_t = vigna::xoshiro256ss

Enumerations
enum class	distribution { uniform , normal }

Functions
engine_t &	ultra::random::engine ()
std::size_t	ultra::random::ring (std::size_t base, std::size_t radius, std::size_t n)
void	ultra::random::randomize ()
template<std::floating_point T>
T	ultra::random::between (T min, T sup)
template<std::integral T>
T	ultra::random::between (T min, T sup)
template<class T> requires std::is_enum_v<T>
T	ultra::random::between (T min, T sup)
template<class T> requires std::is_arithmetic_v<T> || std::is_enum_v<T>
T	ultra::random::sup (T sup)
template<std::ranges::sized_range C>
std::ranges::range_reference_t< const C >	ultra::random::element (const C &c)
template<ArithmeticScalar A>
A	ultra::random::element (const interval< A > &i)
template<std::ranges::sized_range C>
C::value_type &	ultra::random::element (C &c)
bool	ultra::random::boolean (double p)
bool	ultra::random::boolean ()
template<class T> requires std::is_arithmetic_v<T>
T	ultra::random::ephemeral (distribution d, T p1, T p2)

Detailed Description

Remarks

This file is part of ULTRA.

Copyright

Copyright (C) 2024 EOS di Manlio Morini.

License

This Source Code Form is subject to the terms of the Mozilla Public License, v. 2.0. If a copy of the MPL was not distributed with this file, You can obtain one at http://mozilla.org/MPL/2.0/

Typedef Documentation

engine_t

using ultra::random::engine_t = vigna::xoshiro256ss

xoshiro256** (XOR/shift/rotate) is an all-purpose, rock-solid generator (not a cryptographically secure generator). It has excellent (sub-ns) speed, a state space (256 bits) that is large enough for any parallel application, and it passes all tests we are aware of.

Function Documentation

between() [1/2]

template<std::integral T>

T ultra::random::between ( T min, T sup )

nodiscard

Picks up a random integer value uniformly distributed in the set of integers {min, min+1, ..., sup-1}.

Parameters

[in]	min	minimum random number
[in]	sup	upper bound

Returns

a random number in the [min;sup[ range

Note

Contrary to boost usage this function does not take a closed range. Instead it takes a half-open range (C++ usage and same behaviour of the real number distribution).

between() [2/2]

template<std::floating_point T>

T ultra::random::between ( T min, T sup )

nodiscard

A specialization for floating point values of the random::between(T, T) template function.

Parameters

[in]	min	minimum random number
[in]	sup	upper bound

Returns

a random double in the [min;sup[ range

See also

For further details:

• https://www.open-std.org/JTC1/SC22/WG21/docs/papers/2013/n3551.pdf
• https://stackoverflow.com/q/24566574/3235496
• https://stackoverflow.com/q/25222167/3235496

Examples

scheduling.cc, and symbolic_regression03.cc.

boolean() [1/2]

bool ultra::random::boolean ( )

inlinenodiscard

Returns

true or false with equal probability

Note

This overload is the fast path for unbiased coin flips. It caches one PRNG result per thread and consumes it one bit at a time, avoiding the overhead of constructing a Bernoulli distribution for every call.

boolean() [2/2]

bool ultra::random::boolean ( double p )

inlinenodiscard

Parameters

[in]

p

a probability ([0;1] range)

Returns

true with probability p

Note

bool values are produced according to the Bernoulli distribution.

element() [1/3]

template<std::ranges::sized_range C>

C::value_type & ultra::random::element ( C & c )

nodiscard

Parameters

[in]

c

a STL container

Returns

a random element of container c

element() [2/3]

template<std::ranges::sized_range C>

std::ranges::range_reference_t< const C > ultra::random::element ( const C & c )

nodiscard

Parameters

[in]

c

a STL container

Returns

a random element of container c

element() [3/3]

template<ArithmeticScalar A>

A ultra::random::element ( const interval< A > & i )

nodiscard

Parameters

[in]

i

a right-open interval

Returns

a random element of i

engine()

engine_t & ultra::random::engine ( )

nodiscard

Every thread has its own generator initialised with a different seed.

ephemeral()

template<class T>
requires std::is_arithmetic_v<T>

T ultra::random::ephemeral ( distribution d, T p1, T p2 )

nodiscard

Used for ephemeral random constant generation.

Parameters

[in]	d	type of distribution
[in]	p1	minimum for uniform distribution; mean - stddev/2 for normal distribution
[in]	p2	maximum for uniform distribution, mean + stddev/2 for normal distribution

Returns

a random number distributed according to distribution d

Note

For normal distribution:

• p2 - p1 equals the standard deviation;
• std::midpoint(p1, p2) equals the mean.

randomize()

void ultra::random::randomize

(

)

Switches the random subsystem to an unpredictable state.

This function "re-bases" the process-wide seed counter so that random engines created after this call are typically seeded unpredictably.

Implementation notes / assumptions:

• engine_t::result_type is assumed to be an unsigned integer type at least 32 bits wide. This guarantees that cur + 1 is well-defined (wrap-around semantics) and provides a large seed space;
• the entropy used to re-base the counter is drawn from a small bounded interval, because randomize() is expected to be called only a few times and we do not need a huge entropy pool here;
• seed generation is thread-safe and lock-free: a CAS loop updates the atomic counter using relaxed memory ordering (no inter-thread ordering constraints are required).

Each thread owns its own thread-local random engine; therefore, only engines created after this call are affected. Existing engines are left unchanged.

This design allows deterministic and non-deterministic random behaviour to coexist within the same program, depending on when engines are initialised.

ring()

std::size_t ultra::random::ring ( std::size_t base, std::size_t radius, std::size_t n )

nodiscard

Returns a random number in a modular arithmetic system.

Parameters

[in]	base	a base number
[in]	radius	maximum distance from the base number
[in]	n	modulus

Returns

a random number in the [base - radius, base + radius] mod n interval

sup()

template<class T>
requires std::is_arithmetic_v<T> || std::is_enum_v<T>

T ultra::random::sup ( T sup )

nodiscard

Parameters

[in]

sup

upper bound

Returns

a random number in the [0;sup[ range

Note

This is a shortcut for: between<T>(0, sup)