random.h File Reference

Pseudo-random number generators. More...

#include <stdint.h>
#include <stdfix-full-iso.h>

Go to the source code of this file.

Marsaglia 32-bit KISS uniform random number generator
Implementation of a Marsaglia 32-bit KISS generator which uses no multiply instructions 209.9 nanosecs (i.e. 42 ticks) per call Only available in simple form. Very good for single stream of PRNs. Cite: Marsaglia, George. (2011) RNGs with periods exceeding 10 (40million). Message-ID!603ebe15-a32f-4fbb-ba44-6c73f7919a33@t35g2000yqj.googlegroups.com? in newsgroups sci.math, comp.lang.c and sci.crypt
typedef uint32_t	mars_kiss64_seed_t[4]
	Seed type for the Marsaglia KISS 64 RNG.
uint32_t	mars_kiss32 (void)
	Marsaglia 32-bit KISS generator using no multiplication instructions.
uint32_t	mars_kiss64_simp (void)
	Implementation of Marsaglia JKISS RNG uses 64-bit value and 2x multiplies.
void	validate_mars_kiss64_seed (mars_kiss64_seed_t seed)
	Validate seed for Marsaglia KISS 64.
uint32_t	mars_kiss64_seed (mars_kiss64_seed_t seed)
	The Marsaglia KISS 64 RNG with custom seed.

WELL 1024a
WELL 1024a long cycle generator (21024 - 1) from L'Ecuyer & Panneton. Better equi-distribution and warm-up performance than Mersenne Twister, and faster. Cite: Panneton, François & L’Ecuyer, Pierre & Matsumoto, Makoto. (2006). Improved long-period generators based on linear recurrences modulo 2. ACM Trans. Math. Softw.. 32. 1-16. DOI: 10.1145/1132973.1132974.
typedef uint32_t	WELL1024a_seed_t[33]
	Seed type for the L'Ecuyer WELL 1024a RNG.
void	init_WELL1024a_simp (void)
	The initialiser function that MUST BE CALLED ONCE before WELLRNG1024a_simp() is used. Global WELL1024a seed is randomised each time it is called.
uint32_t	WELL1024a_simp (void)
	The WELL generator itself.
void	validate_WELL1024a_seed (WELL1024a_seed_t seed)
	MUST USE THIS before passing the seed to WELL1024a_seed() the first time.
uint32_t	WELL1024a_seed (WELL1024a_seed_t seed)
	The WELL 1024a RNG with custom seed.

Non-Uniform RNGs
Being added to all the time, and updated for better speed as fixed-point transcendentals and optimised multiplies become available
typedef uint32_t(*	uniform_rng) (uint32_t *)
	The interface type to the uniform RNGs.
s1615	exponential_dist_variate (uniform_rng uni_rng, uint32_t *seed_arg)
	Von Neuman's exponential distribution generator.
s1615	gaussian_dist_variate (uniform_rng uni_rng, uint32_t *seed_arg)
	Returns standard Gaussian deviate.
uint32_t	poisson_dist_variate (uniform_rng uni_rng, uint32_t *seed_arg, s1615 lambda)
	A poisson distributed random variable, given \( \exp(-\lambda) \).
uint32_t	poisson_dist_variate_exp_minus_lambda (uniform_rng uni_rng, uint32_t *seed_arg, u032 exp_minus_lambda)
	Use this version for Poisson with pre-calculated exp(-λ) for speed gain.

Detailed Description

Pseudo-random number generators.

Author

Michael Hopkins

Date

February 2014

These all return well-distributed unsigned 32-bit ints that have been tested rigorously on the DIEHARD, dieharder and TestU01 test suites. The Marsaglia KISS generators are slightly faster and the 64-bit one uses the theoretically superior multiplicative algorithm. The WELL1024a has a cycle length of (2^1024)-1

Two versions are available. A simple version which has a global hidden seed which does not need to be set, and a custom version which allows seeds to be set by the user to either

1. promote independence or
2. guarantee identical behaviour

across multiple random number streams.

These generators can all be used with the non-uniform RNGs below.

Warning

Production code must use the version with explicit seeds to allow for reproducible random numbers, as this is a critical requirement for testability and verifiability. Seeds should be supplied from your Python control code.

Typedef Documentation

WELL1024a_seed_t

typedef uint32_t WELL1024a_seed_t[33]

Seed type for the L'Ecuyer WELL 1024a RNG.

The 33rd element is the static variable used in simple version.

uniform_rng

typedef uint32_t(* uniform_rng) (uint32_t *)

The interface type to the uniform RNGs.

Interface to a generic uniform random number generator is defined as follows

• for a simple type call as ( rng_type, NULL, .. )
• for a seeded type call as ( rng_type, seed_vector, .. )

This will generate some argument type warnings when used with simple URNGs but avoids a lot of code duplication and allows use of any Uniform RNG with any Non-Uniform variates which is valuable flexibility.

Function Documentation

mars_kiss32()

uint32_t mars_kiss32

(

void

)

Marsaglia 32-bit KISS generator using no multiplication instructions.

Only available in simple form. Very good for single stream of PRNs.

Returns

A pseudo-random unsigned 32-bit integer.

mars_kiss64_simp()

uint32_t mars_kiss64_simp

(

void

)

Implementation of Marsaglia JKISS RNG uses 64-bit value and 2x multiplies.

The best general purpose trade-off between speed, equidistribution and cycle length.

Returns

A normally distributed 32-bit unsigned integer.

validate_mars_kiss64_seed()

void validate_mars_kiss64_seed

(

mars_kiss64_seed_t

seed

)

Validate seed for Marsaglia KISS 64.

Note

MUST USE THIS before passing the seed to mars_kiss64_seed() the first time.

Parameters

[in]

seed

The seed to validate

mars_kiss64_seed()

uint32_t mars_kiss64_seed

(

mars_kiss64_seed_t

seed

)

The Marsaglia KISS 64 RNG with custom seed.

Parameters

[in]

seed

The RNG state, including seed value.

Returns

A uniformly randomly distributed 32-bit value.

WELL1024a_simp()

uint32_t WELL1024a_simp

(

void

)

The WELL generator itself.

Returns

A uniformly randomly distributed 32-bit value.

validate_WELL1024a_seed()

void validate_WELL1024a_seed

(

WELL1024a_seed_t

seed

)

MUST USE THIS before passing the seed to WELL1024a_seed() the first time.

Parameters

[in]

seed

The seed to validate

WELL1024a_seed()

uint32_t WELL1024a_seed

(

WELL1024a_seed_t

seed

)

The WELL 1024a RNG with custom seed.

Parameters

[in]

seed

The RNG state, including seed value.

Returns

A uniformly randomly distributed 32-bit value.

exponential_dist_variate()

s1615 exponential_dist_variate	(	uniform_rng	uni_rng,
		uint32_t *	seed_arg
	)

Von Neuman's exponential distribution generator.

from Ripley p.230 and adapted for our types

Mean number of U(0,1) per call = 5.2

Parameters

[in]	uni_rng	The uniform random number generator
[in]	seed_arg	The seed argument to the uniform RNG.

Returns

Exponentially distributed random number.

gaussian_dist_variate()

s1615 gaussian_dist_variate	(	uniform_rng	uni_rng,
		uint32_t *	seed_arg
	)

Returns standard Gaussian deviate.

translation of NR in C version of Box-Muller

Parameters

[in]	uni_rng	The uniform random number generator
[in]	seed_arg	The seed argument to the uniform RNG.

Returns

Gaussian-distributed random number.

poisson_dist_variate()

uint32_t poisson_dist_variate	(	uniform_rng	uni_rng,
		uint32_t *	seed_arg,
		s1615	lambda
	)

A poisson distributed random variable, given \( \exp(-\lambda) \).

This is Knuth's method, and is \( O(n) \), so don't use for large \( \lambda \)

Parameters

[in]	uni_rng	The uniform random number generator
[in]	seed_arg	The seed argument to the uniform RNG.
[in]	lambda	The shape parameter of the distribution, \( \lambda \)

Returns

Poisson-distributed random number.

Remarks

DRL thinks the cast (from s16.15 to u0.32) might be wasteful.

poisson_dist_variate_exp_minus_lambda()

uint32_t poisson_dist_variate_exp_minus_lambda	(	uniform_rng	uni_rng,
		uint32_t *	seed_arg,
		u032	exp_minus_lambda
	)

Use this version for Poisson with pre-calculated exp(-λ) for speed gain.

Parameters

[in]	uni_rng	The uniform random number generator
[in]	seed_arg	The seed argument to the uniform RNG.
[in]	exp_minus_lambda	The shape parameter of the distribution, \( \exp(-\lambda) \).

Returns

Poisson-distributed random number.

Remarks

DRL thinks this can be simplified to the following code:

while (p > exp_minus_lambda) {
    p *= ulrbits(uni_rng(seed_arg));
    k++;
}

return k;