lsst::afw::math::Random Class Reference

A class that can be used to generate sequences of random numbers according to a number of different algorithms. More...

#include <Random.h>

Public Types
enum	Algorithm {   MT19937 = 0 , RANLXS0 , RANLXS1 , RANLXS2 ,   RANLXD1 , RANLXD2 , RANLUX , RANLUX389 ,   CMRG , MRG , TAUS , TAUS2 ,   GFSR4 , NUM_ALGORITHMS }
	Identifiers for the list of supported algorithms. More...
using	State = std::string
	Accessors for the opaque state of the random number generator. More...

Public Member 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. More...
	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. More...
	Random (Random const &)=default
	Random (Random &&)=default
Random &	operator= (Random const &)=default
Random &	operator= (Random &&)=default
	~Random ()=default
Random	deepCopy () const
	Creates a deep copy of this random number generator. More...
State	getState () const
void	setState (State const &state)
std::size_t	getStateSize () const
Algorithm	getAlgorithm () const
std::string	getAlgorithmName () const
unsigned long	getSeed () const
double	uniform ()
	Returns a uniformly distributed random double precision floating point number from the generator. More...
double	uniformPos ()
	Returns a uniformly distributed random double precision floating point number from the generator. More...
unsigned long	uniformInt (unsigned long n)
	Returns a uniformly distributed random integer from 0 to n-1. More...
double	flat (double const a, double const b)
	Returns a random variate from the flat (uniform) distribution on [a, b). More...
double	gaussian ()
	Returns a gaussian random variate with mean 0 and standard deviation 1 More...
double	chisq (double const nu)
	Returns a random variate from the chi-squared distribution with nu degrees of freedom. More...
double	poisson (double const mu)
	Returns a random variate from the poisson distribution with mean mu. More...

Static Public Member Functions
static std::vector< std::string > const &	getAlgorithmNames ()

Detailed Description

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 also

Random number generation in GSL

Random number distributions in GSL

Definition at line 57 of file Random.h.

Member Typedef Documentation

State

using lsst::afw::math::Random::State = std::string

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.

Definition at line 154 of file Random.h.

Member Enumeration Documentation

Algorithm

enum lsst::afw::math::Random::Algorithm

Identifiers for the list of supported algorithms.

Enumerator
MT19937	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.

Definition at line 60 of file Random.h.

                   {
        MT19937 = 0,
        RANLXS0,
        RANLXS1,
        RANLXS2,
        RANLXD1,
        RANLXD2,
        RANLUX,
        RANLUX389,
        CMRG,
        MRG,
        TAUS,
        TAUS2,
        GFSR4,
        NUM_ALGORITHMS
    };

Constructor & Destructor Documentation

Random() [1/4]

lsst::afw::math::Random::Random ( Algorithm  algorithm = MT19937, unsigned long  seed = 1  )

explicit

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.

Definition at line 89 of file Random.cc.

                                                            : _rng(), _seed(seed), _algorithm(algorithm) {
    if (_algorithm < 0 || _algorithm >= NUM_ALGORITHMS) {
        throw LSST_EXCEPT(ex::InvalidParameterError, "Invalid RNG algorithm");
    }
    initialize();
}

Random() [2/4]

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

explicit

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.

Definition at line 96 of file Random.cc.

                                                             : _rng(), _seed(seed) {
    initialize(algorithm);
}

Random() [3/4]

lsst::afw::math::Random::Random ( Random const &  )

default

Random() [4/4]

lsst::afw::math::Random::Random ( Random &&  )

default

~Random()

lsst::afw::math::Random::~Random ( )

default

Member Function Documentation

chisq()

double lsst::afw::math::Random::chisq

(

double const

nu

)

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

Parameters

[in]

nu

the number of degrees of freedom in the chi-squared distribution

Returns

a random variate from the chi-squared distribution

Definition at line 163 of file Random.cc.

{ return ::gsl_ran_chisq(_rng.get(), nu); }

deepCopy()

Random lsst::afw::math::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.

Returns

a deep copy of this random number generator

Exceptions

std::bad_alloc

Thrown if memory allocation for internal generator state fails.

Definition at line 100 of file Random.cc.

                              {
    Random rng = *this;
    rng._rng.reset(::gsl_rng_clone(_rng.get()), ::gsl_rng_free);
    if (!rng._rng) {
        throw std::bad_alloc();
    }
    return rng;
}

flat()

double lsst::afw::math::Random::flat	(	double const	a,
		double const	b
	)

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

Parameters

[in]	a	lower endpoint of uniform distribution range (inclusive)
[in]	b	upper endpoint of uniform distribution range (exclusive)

Returns

a uniform random variate.

Definition at line 159 of file Random.cc.

{ return ::gsl_ran_flat(_rng.get(), a, b); }

gaussian()

double lsst::afw::math::Random::gaussian

(

)

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

Returns

a gaussian random variate

Note

The implementation uses the Ziggurat algorithm.

Definition at line 161 of file Random.cc.

{ return ::gsl_ran_gaussian_ziggurat(_rng.get(), 1.0); }

getAlgorithm()

Random::Algorithm lsst::afw::math::Random::getAlgorithm

(

)

const

Returns

The algorithm in use by this random number generator.

Definition at line 128 of file Random.cc.

{ return _algorithm; }

getAlgorithmName()

std::string lsst::afw::math::Random::getAlgorithmName

(

)

const

Returns

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

Definition at line 130 of file Random.cc.

{ return std::string(_algorithmNames[_algorithm]); }

getAlgorithmNames()

std::vector< std::string > const & lsst::afw::math::Random::getAlgorithmNames ( )

static

Returns

The list of names of supported random number generation algorithms.

Definition at line 132 of file Random.cc.

                                                      {
    static std::vector<std::string> names;
    if (names.size() == 0) {
        for (auto _algorithmName : _algorithmNames) {
            names.emplace_back(_algorithmName);
        }
    }
    return names;
}

getSeed()

unsigned long lsst::afw::math::Random::getSeed

(

)

const

Returns

The integer this random number generator was seeded with.

Note

The seed is guaranteed not to be zero.

Definition at line 142 of file Random.cc.

{ return _seed; }

getState()

Random::State lsst::afw::math::Random::getState

(

)

const

Definition at line 109 of file Random.cc.

                                   {
    return State(static_cast<char *>(::gsl_rng_state(_rng.get())), getStateSize());
}

getStateSize()

std::size_t lsst::afw::math::Random::getStateSize

(

)

const

Definition at line 124 of file Random.cc.

{ return ::gsl_rng_size(_rng.get()); }

operator=() [1/2]

Random& lsst::afw::math::Random::operator= ( Random &&  )

default

operator=() [2/2]

Random& lsst::afw::math::Random::operator= ( Random const &  )

default

poisson()

double lsst::afw::math::Random::poisson

(

double const

mu

)

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

Parameters

mu	desired mean (and variance)

Returns

a random variate from the Poission distribution

Definition at line 165 of file Random.cc.

{ return ::gsl_ran_poisson(_rng.get(), mu); }

setState()

void lsst::afw::math::Random::setState

(

State const &

state

)

Definition at line 113 of file Random.cc.

                                        {
    if (state.size() != getStateSize()) {
        throw LSST_EXCEPT(
                pex::exceptions::LengthError,
                (boost::format("Size of given state vector (%d) does not match expected size (%d)") %
                 state.size() % getStateSize())
                        .str());
    }
    std::copy(state.begin(), state.end(), static_cast<char *>(::gsl_rng_state(_rng.get())));
}

uniform()

double lsst::afw::math::Random::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.

Returns

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

See also

uniformPositiveDouble()

Definition at line 146 of file Random.cc.

{ return ::gsl_rng_uniform(_rng.get()); }

uniformInt()

unsigned long lsst::afw::math::Random::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.

Parameters

[in]

n

specifies the range of allowable return values (0 to n-1)

Returns

a uniformly distributed random integer

Exceptions

lsst::pex::exceptions::RangeError

Thrown if n is larger than the algorithm specific range of the generator.

See also

get()

getMin()

getMax()

Definition at line 150 of file Random.cc.

                                                {
    if (n > ::gsl_rng_max(_rng.get()) - ::gsl_rng_min(_rng.get())) {
        throw LSST_EXCEPT(ex::RangeError, "Desired random number range exceeds generator range");
    }
    return ::gsl_rng_uniform_int(_rng.get(), n);
}

uniformPos()

double lsst::afw::math::Random::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.

Returns

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

Definition at line 148 of file Random.cc.

{ return ::gsl_rng_uniform_pos(_rng.get()); }

---

The documentation for this class was generated from the following files:

• /j/snowflake/release/lsstsw/stack/lsst-scipipe-0.7.0/Linux64/afw/22.0.1-42-gca6935d93+ba5e5ca3eb/include/lsst/afw/math/Random.h
• /j/snowflake/release/lsstsw/stack/lsst-scipipe-0.7.0/Linux64/afw/22.0.1-42-gca6935d93+ba5e5ca3eb/src/math/Random.cc