Xoshiro256 Class Reference

A fast, high quality random number generator. More...

#include <random.h>

Public Member Functions
	Xoshiro256 (uint64_t=512)
	Creates a random number generator.
	~Xoshiro256 ()
	Empty.
void	Seed (uint64_t)
	Compute the state of the generator given a seed.
uint64_t	Next ()
	Generate a random 64-bit word.
unsigned int	Integer ()
	Compute a random 32-bit unsigned integer.
int	Integer (int)
	Compute a uniform random integer from 0 to n-1.
int	Integer (int, int)
	Compute a uniform random integer in an interval.
double	Uniform ()
	Compute uniform distribution in [0, 1.0[.
double	Uniform (const double &)
	Compute uniform distribution in [0, a[.
double	Uniform (const double &, const double &)
	Compute uniform distribution in [a, b[.
double	Exponential (const double &)
	Exponential random sequence.
int	geometric (double)
	Geometric random sequence.
unsigned int	Poisson (const double &)
	Poisson random sequence.
int	Pick (const double *, int)
	Randomly pick one item given an array of probabilities.
double	NormalBoxMuller (const double &, const double &)
	Normal distribution.

Static Public Attributes
static Xoshiro256	X512
	Default generator, seeded with 512.

Protected Attributes
uint64_t	s [4]
	State of the generator, which should not be null.

Detailed Description

A fast, high quality random number generator.

This class implements the xoshiro256+ generator of Blackman and Vigna. It has a period of 2^256-1, a state of 256 bits (four 64-bit words), and generates a 64-bit word in a few instructions. Its member functions follow those of Random, so that both classes can be used in the same way.

The lowest bits of the generator are weak: the lowest bit is an LFSR sequence, which fails linearity tests. All the functions of the class therefore use the 53 or 32 highest bits of the 64-bit words; only Xoshiro256::Next() gives access to the raw word, and its lowest bits should not be used on their own.

The generator is not suitable for cryptography.

A default generator seeded with 512 is available as Xoshiro256::X512, in the same way as Random::R239.

Reference: D. Blackman, S. Vigna, Scrambled linear pseudorandom number generators, ACM Transactions on Mathematical Software, 47(4), 2021.

Constructor & Destructor Documentation

Xoshiro256()

Xoshiro256::Xoshiro256 ( uint64_t seed = 512 )

explicit

Creates a random number generator.

The default seed is 512, so that two generators created without argument generate the same sequence.

Parameters

seed	Seed argument used for initialization.

See also

Xoshiro256::Seed

Member Function Documentation

Exponential()

double Xoshiro256::Exponential

(

const double &

mu

)

Exponential random sequence.

Given a random variate U drawn with a uniform distribution, T=-ln(1-U)/lambda has an exponential distribution. Since U is uniform, 1-U and U are equivalent, thus T=-ln(U)/lambda.

Parameters

mu	Mu parameter, inverse of lambda, which is the mean of the distribution.

See also

Random::Exponential

geometric()

int Xoshiro256::geometric

(

double

p

)

Geometric random sequence.

Number of trials needed to get a first success, when the probability of success of each trial is p.

Parameters

p	Probability of success, in ]0,1[.

Returns

An integer greater or equal to 1.

See also

Random::geometric

Integer() [1/3]

unsigned int Xoshiro256::Integer

(

)

Compute a random 32-bit unsigned integer.

The 32 highest bits of the generator are used.

Returns

An integer in [0,2^32[.

Integer() [2/3]

int Xoshiro256::Integer

(

int

n

)

Compute a uniform random integer from 0 to n-1.

The 32 highest bits of the generator are used, and the distribution is exactly uniform: the draws which would introduce a bias are rejected (Lemire's method).

Parameters

n	Number of values, which should be strictly positive. The function returns 0 otherwise.

Returns

An integer in [0,n[.

Integer() [3/3]

int Xoshiro256::Integer	(	int	a,
		int	b )

Compute a uniform random integer in an interval.

Parameters

a,b	Integer interval, the result is in [a,b[ and b should be greater than a.

Returns

An integer in [a,b[.

See also

Xoshiro256::Integer(int)

Next()

uint64_t Xoshiro256::Next ( )

inline

Generate a random 64-bit word.

This is the xoshiro256+ generator. The highest bits of the word are of good quality, the lowest bits are not: the lowest bit is an LFSR sequence.

Returns

A random integer in [0,2^64[.

NormalBoxMuller()

double Xoshiro256::NormalBoxMuller	(	const double &	variance,
		const double &	mean )

Normal distribution.

Two uniform variates in [-1,1] are drawn until they fall in the unit disc, and transformed to a normal variate (polar form of the Box-Muller transform). The second variate of the pair is not used.

The arguments are in the same order as for Random::NormalBoxMuller.

Parameters

variance	Variance.
mean	Mean.

See also

Random::NormalBoxMuller

Pick()

int Xoshiro256::Pick	(	const double *	a,
		int	n )

Randomly pick one item given an array of probabilities.

The probabilities do not need to sum to one: item i is picked with a probability a[i] divided by the sum of the array.

Parameters

a	Array of positive weights.
n	Size of the array.

Returns

The index of the picked item, in [0,n[.

Poisson()

unsigned int Xoshiro256::Poisson

(

const double &

mu

)

Poisson random sequence.

The algorithm multiplies uniform variates until their product falls below exp(-mu), so that its cost is proportional to mu: it should not be used for large values of mu.

Parameters

mu	Mean value.

Returns

A random integer.

Seed()

void Xoshiro256::Seed

(

uint64_t

seed

)

Compute the state of the generator given a seed.

The 256 bits of the state are generated from the 64-bit seed with the splitmix64 generator, which is the initialization recommended for xoshiro generators. Two different seeds give unrelated sequences, and the state is never null.

Parameters

seed

The seed.

Uniform() [1/3]

double Xoshiro256::Uniform ( )

inline

Compute uniform distribution in [0, 1.0[.

The 53 highest bits of the 64-bit word are used, which are all the bits of the mantissa of a double. Every value of the result is a multiple of 2^-53.

Uniform() [2/3]

double Xoshiro256::Uniform

(

const double &

a

)

Compute uniform distribution in [0, a[.

Parameters

a	Amplitude.

Uniform() [3/3]

double Xoshiro256::Uniform	(	const double &	a,
		const double &	b )

Compute uniform distribution in [a, b[.

Parameters

a,b	Amplitude interval.

Member Data Documentation

X512

Xoshiro256 Xoshiro256::X512

static

Default generator, seeded with 512.

This static member is a convenient way to generate random numbers on the fly wherever needed, in the same way as Random::R239.

See also

Random::R239