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

#include <Random.h>

Public Types
enum	Algorithm {   MT19937 = 0, RANLXS0, RANLXS1, RANLXS2,   RANLXD1, RANLXD2, RANLUX, RANLUX389,   CMRG, MRG, TAUS, TAUS2,   GFSR4, NUM_ALGORITHMS }

Public Member Functions
	Random (Algorithm algorithm=MT19937, unsigned long seed=1)
	Random (std::string const &algorithm, unsigned long seed=1)
	Random (lsst::pex::policy::Policy::Ptr const policy)
Random	deepCopy () const
Algorithm	getAlgorithm () const
std::string	getAlgorithmName () const
unsigned long	getSeed () const
double	uniform ()
double	uniformPos ()
unsigned long	uniformInt (unsigned long n)
double	flat (double const a, double const b)
double	gaussian ()
double	chisq (double const nu)
double	poisson (double const nu)

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

Private Member Functions
void	initialize ()
void	initialize (std::string const &)

Private Attributes
boost::shared_ptr< ::gsl_rng >	_rng
unsigned long	_seed
Algorithm	_algorithm

Static Private Attributes
::gsl_rng_type const *const	_gslRngTypes [NUM_ALGORITHMS]
static char const *const	_algorithmNames [NUM_ALGORITHMS]
static char const *const	_algorithmEnvVarName = "LSST_RNG_ALGORITHM"
static char const *const	_seedEnvVarName = "LSST_RNG_SEED"
typedef std::string	State
State	getState () const
void	setState (State const &state)
std::size_t	getStateSize () const

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.

To enable reproducibility, factory functions which determine the algorithm type and seed value to used based on the the LSST_RNG_ALGORITHM and LSST_RNG_SEED environment variables (or the "rngAlgorithm" and "rngSeed" keys in a policy) are provided.

See Also

Random number generation in GSL

Random number distributions in GSL

Definition at line 62 of file Random.h.

Member Typedef Documentation

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

Definition at line 116 of file Random.h.

Member Enumeration Documentation

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 66 of file Random.h.

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

Constructor & Destructor Documentation

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. Passing a seed-value of zero will cause the generator to be seeded with an algorithm specific default 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 or a seed value of zero (corresponding to an algorithm specific seed) is chosen.
lsst::pex::exceptions::MemoryError	Thrown if memory allocation for internal generator state fails.

Definition at line 151 of file Random.cc.

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

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. Passing a seed-value of zero will cause the generator to be seeded with an algorithm specific default 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 or a seed value of zero (corresponding to an algorithm specific seed) is chosen.
lsst::pex::exceptions::MemoryError	Thrown if memory allocation for internal generator state fails.

Definition at line 175 of file Random.cc.

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

lsst::afw::math::Random::Random ( lsst::pex::policy::Policy::Ptr const  policy )

explicit

Creates a random number generator using the algorithm and seed specified in the given policy. The algorithm name and seed are expected to be specified in string-valued keys named "rngAlgorithm" and "rngSeed" respectively. The "rngSeed" value is expected to be convertible to an unsigned long integer and must not be positive.

Parameters

[in]

policy

policy which contains the algorithm and seed to to use for random number generation

Returns

a newly created random number generator

Exceptions

lsst::pex::exceptions::InvalidParameterError	Thrown if the requested algorithm is not supported.
lsst::pex::exceptions::MemoryError	Thrown if memory allocation for internal generator state fails.
lsst::pex::exceptions::RuntimeError	Thrown if the "rngSeed" policy value cannot be converted to an unsigned long int.

Definition at line 200 of file Random.cc.

    : _rng(), _seed()
{
    std::string const seed(policy->getString("rngSeed"));
    try {
        _seed = boost::lexical_cast<unsigned long>(seed);
    } catch(boost::bad_lexical_cast &) {
        throw LSST_EXCEPT(ex::RuntimeError,
        (boost::format("Invalid \"rngSeed\" policy value: \"%1%\"") % seed).str());
    }
    initialize(policy->getString("rngAlgorithm"));
}

Member Function Documentation

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 380 of file Random.cc.

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

math::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

lsst::pex::exceptions::MemoryError

Thrown if memory allocation for internal generator state fails.

Definition at line 223 of file Random.cc.

                                      {
    Random rng = *this;
    rng._rng.reset(::gsl_rng_clone(_rng.get()), ::gsl_rng_free);
    if (!rng._rng) {
        throw LSST_EXCEPT(ex::MemoryError, "gsl_rng_clone() failed");
    }
    return rng;
}

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 358 of file Random.cc.

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

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 370 of file Random.cc.

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

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

(

)

const

Returns

The algorithm in use by this random number generator.

Definition at line 256 of file Random.cc.

                                                   {
    return _algorithm;
}

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

(

)

const

Returns

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

Definition at line 263 of file Random.cc.

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

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 270 of file Random.cc.

                                                           {
    static std::vector<std::string> names;
    if (names.size() == 0) {
        for (int i = 0; i < NUM_ALGORITHMS; ++i) {
            names.push_back(_algorithmNames[i]);
        }
    }
    return names;
}

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

(

)

const

Returns

The integer this random number generator was seeded with.

Note

A seed value of 0 indicates that the random number generator was seeded with an algorithm specific default value.

Definition at line 285 of file Random.cc.

                                        {
    return _seed;
}

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

(

)

const

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 232 of file Random.cc.

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

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

(

)

const

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 247 of file Random.cc.

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

void lsst::afw::math::Random::initialize ( )

private

Definition at line 96 of file Random.cc.

                            {
    if (_seed == 0) {
        throw LSST_EXCEPT(ex::InvalidParameterError,
                          (boost::format("Invalid RNG seed: %lu") % _seed).str());
    }
    ::gsl_rng * rng = ::gsl_rng_alloc(_gslRngTypes[_algorithm]);
    if (rng == 0) {
        throw LSST_EXCEPT(ex::MemoryError, "gsl_rng_alloc() failed");
    }
    ::gsl_rng_set(rng, _seed);
    _rng.reset(rng, ::gsl_rng_free);
}

void lsst::afw::math::Random::initialize ( std::string const &  algorithm )

private

Definition at line 119 of file Random.cc.

                                                       {
   // linear search (the number of algorithms is small)
   for (int i = 0; i < NUM_ALGORITHMS; ++i) {
        if (_algorithmNames[i] == algorithm) {
            _algorithm = static_cast<Algorithm>(i);
            initialize();
            return;
        }
    }
    throw LSST_EXCEPT(ex::InvalidParameterError, "RNG algorithm " +
                      algorithm + " is not supported");
}

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

(

double const

nu

)

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

Returns

a random variate from the Poission distribution

Parameters

nu	desired mean (and variance)

Definition at line 390 of file Random.cc.

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

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

(

State const &

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.

Definition at line 236 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())));
}

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 304 of file Random.cc.

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

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 341 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);
}

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 319 of file Random.cc.

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

Member Data Documentation

Algorithm lsst::afw::math::Random::_algorithm

private

Definition at line 142 of file Random.h.

char const *const lsst::afw::math::Random::_algorithmEnvVarName = "LSST_RNG_ALGORITHM"

staticprivate

Definition at line 146 of file Random.h.

char const *const lsst::afw::math::Random::_algorithmNames

staticprivate

Initial value:

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

Definition at line 145 of file Random.h.

gsl_rng_type const *const lsst::afw::math::Random::_gslRngTypes

staticprivate

Initial value:

= {
    ::gsl_rng_mt19937,
    ::gsl_rng_ranlxs0,
    ::gsl_rng_ranlxs1,
    ::gsl_rng_ranlxs2,
    ::gsl_rng_ranlxd1,
    ::gsl_rng_ranlxd2,
    ::gsl_rng_ranlux,
    ::gsl_rng_ranlux389,
    ::gsl_rng_cmrg,
    ::gsl_rng_mrg,
    ::gsl_rng_taus,
    ::gsl_rng_taus2,
    ::gsl_rng_gfsr4
}

Definition at line 144 of file Random.h.

boost::shared_ptr< ::gsl_rng> lsst::afw::math::Random::_rng

private

Definition at line 140 of file Random.h.

unsigned long lsst::afw::math::Random::_seed

private

Definition at line 141 of file Random.h.

char const *const lsst::afw::math::Random::_seedEnvVarName = "LSST_RNG_SEED"

staticprivate

Definition at line 147 of file Random.h.

---

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

• /home/lsstsw/stack/Linux64/afw/11.0-2-g04d2804/include/lsst/afw/math/Random.h
• /home/lsstsw/stack/Linux64/afw/11.0-2-g04d2804/src/math/Random.cc