Class Random

Class Documentation

class Random

A class that can be used to generate sequences of random numbers according to a number of different algorithms. Support for generating random variates from the uniform, Gaussian, Poisson, and chi-squared distributions is provided.

This class is a thin wrapper for the random number generation facilities of GSL, which supports many additional distributions that can easily be added to this class as the need arises.

See

Random number generation in GSL

See

Random number distributions in GSL

Unnamed Group

typedef std::string State

Accessors for the opaque state of the random number generator.

These may be used to save the state and restore it later, possibly after persisting. The state is algorithm-dependent, and possibly platform/architecture dependent; it should only be used for debugging perposes.

We use string here because it’s a format Python and afw::table understand; the actual value is a binary blob that is not expected to be human-readable.

State getState() const
void setState(State const &state)
std::size_t getStateSize() const

Public Types

enum Algorithm

Identifiers for the list of supported algorithms.

Values:

MT19937 = 0

The MT19937 “Mersenne Twister” generator of Makoto Matsumoto and Takuji Nishimura.

RANLXS0

Second-generation version of the RANLUX algorithm of Lüscher, 24-bit output, luxury level 0 (weakest)

RANLXS1

Second-generation version of the RANLUX algorithm of Lüscher, 24-bit output, luxury level 1 (stronger)

RANLXS2

Second-generation version of the RANLUX algorithm of Lüscher, 24-bit output, luxury level 2 (strongest)

RANLXD1

Double precision (48-bit) output using the RANLXS algorithm, luxury level 1 (weakest).

RANLXD2

Double precision (48-bit) output using the RANLXS algorithm, luxury level 2 (strongest).

RANLUX

Original version of the RANLUX algorithm, 24-bit output.

RANLUX389

Original version of the RANLUX algorithm, 24-bit output (all bits are decorrelated).

CMRG

Combined multiple recursive generator by L’Ecuyer.

MRG

Fifth-order multiple recursive generator by L’Ecuyer, Blouin, and Coutre.

TAUS

A maximally equidistributed combined Tausworthe generator by L’Ecuyer.

TAUS2

A maximally equidistributed combined Tausworthe generator by L’Ecuyer with improved seeding relative to TAUS.

GFSR4

A fifth-order multiple recursive generator by L’Ecuyer, Blouin, and Coutre.

NUM_ALGORITHMS

Number of supported algorithms

Public Functions

Random(Algorithm algorithm = MT19937, unsigned long seed = 1)

Creates a random number generator that uses the given algorithm to produce random numbers, and seeds it with the specified value. The default value for algorithm is MT19937, corresponding to the “Mersenne Twister” algorithm by Makoto Matsumoto and Takuji Nishimura.

Parameters

  • [in] algorithm: the algorithm to use for random number generation

  • [in] seed: the seed value to initialize the generator with

Exceptions

  • lsst::pex::exceptions::InvalidParameterError: Thrown if the requested algorithm is not supported.

  • std::bad_alloc: Thrown if memory allocation for internal generator state fails.

Random(std::string const &algorithm, unsigned long seed = 1)

Creates a random number generator that uses the algorithm with the given name to produce random numbers, and seeds it with the specified value.

Parameters

  • [in] algorithm: the name of the algorithm to use for random number generation

  • [in] seed: the seed value to initialize the generator with

Exceptions

  • lsst::pex::exceptions::InvalidParameterError: Thrown if the requested algorithm is not supported.

  • std::bad_alloc: Thrown if memory allocation for internal generator state fails.

Random(Random const&)
Random(Random&&)
Random &operator=(Random const&)
Random &operator=(Random&&)
~Random()
Random deepCopy() const

Creates a deep copy of this random number generator. Both this random number and its copy will subsequently produce an identical stream of random numbers.

Return

a deep copy of this random number generator

Exceptions

  • std::bad_alloc: Thrown if memory allocation for internal generator state fails.

Algorithm getAlgorithm() const

Return

The algorithm in use by this random number generator.

std::string getAlgorithmName() const

Return

The name of the algorithm in use by this random number generator.

unsigned long getSeed() const

Return

The integer this random number generator was seeded with.

Note

The seed is guaranteed not to be zero.

double uniform()

Returns a uniformly distributed random double precision floating point number from the generator. The random number will be in the range [0, 1); the range includes 0.0 but excludes 1.0. Note that some algorithms will not produce randomness across all mantissa bits - choose an algorithm that produces double precisions results (such as Random::RANLXD1, Random::TAUS, or Random::MT19937) if this is important.

Return

a uniformly distributed random double precision floating point number in the range [0, 1).

See

uniformPositiveDouble()

double uniformPos()

Returns a uniformly distributed random double precision floating point number from the generator. The random number will be in the range (0, 1); the range excludes both 0.0 and 1.0. Note that some algorithms will not produce randomness across all mantissa bits - choose an algorithm that produces double precisions results (such as Random::RANLXD1, Random::TAUS, or Random::MT19937) if this is important.

Return

a uniformly distributed random double precision floating point number in the range (0, 1).

unsigned long uniformInt(unsigned long n)

Returns a uniformly distributed random integer from 0 to n-1.

This function is not intended to generate values across the full range of unsigned integer values [0, 2^32 - 1]. If this is necessary, use a high precision algorithm like Random::RANLXD1, Random::TAUS, or Random::MT19937 with a minimum value of zero and call get() directly.

Return

a uniformly distributed random integer

See

get()

See

getMin()

See

getMax()

Parameters

  • [in] n: specifies the range of allowable return values (0 to n-1)

Exceptions

  • lsst::pex::exceptions::RangeError: Thrown if n is larger than the algorithm specific range of the generator.

double flat(double const a, double const b)

Returns a random variate from the flat (uniform) distribution on [a, b).

Return

a uniform random variate.

Parameters

  • [in] a: lower endpoint of uniform distribution range (inclusive)

  • [in] b: upper endpoint of uniform distribution range (exclusive)

double gaussian()

Returns a gaussian random variate with mean 0 and standard deviation 1

Return

a gaussian random variate

Note

The implementation uses the Ziggurat algorithm.

double chisq(double const nu)

Returns a random variate from the chi-squared distribution with nu degrees of freedom.

Return

a random variate from the chi-squared distribution

Parameters

  • [in] nu: the number of degrees of freedom in the chi-squared distribution

double poisson(double const mu)

Returns a random variate from the poisson distribution with mean mu.

Return

a random variate from the Poission distribution

Parameters

  • mu: desired mean (and variance)

Public Static Functions

static std::vector<std::string> const &getAlgorithmNames()

Return

The list of names of supported random number generation algorithms.