LSSTApplications  10.0-2-g4f67435,11.0.rc2+1,11.0.rc2+12,11.0.rc2+3,11.0.rc2+4,11.0.rc2+5,11.0.rc2+6,11.0.rc2+7,11.0.rc2+8
LSSTDataManagementBasePackage
Public Types | Public Member Functions | Static Public Member Functions | Private Member Functions | Private Attributes | Static Private Attributes | List of all members
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

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.

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]algorithmthe algorithm to use for random number generation
[in]seedthe seed value to initialize the generator with
Exceptions
lsst::pex::exceptions::InvalidParameterErrorThrown if the requested algorithm is not supported or a seed value of zero (corresponding to an algorithm specific seed) is chosen.
lsst::pex::exceptions::MemoryErrorThrown if memory allocation for internal generator state fails.

Definition at line 151 of file Random.cc.

152  : _rng(), _seed(seed), _algorithm(algorithm)
153 {
154  if (_algorithm < 0 || _algorithm >= NUM_ALGORITHMS) {
155  throw LSST_EXCEPT(ex::InvalidParameterError, "Invalid RNG algorithm");
156  }
157  initialize();
158 }
unsigned long _seed
Definition: Random.h:141
#define LSST_EXCEPT(type,...)
Definition: Exception.h:46
boost::shared_ptr< ::gsl_rng > _rng
Definition: Random.h:140
Algorithm _algorithm
Definition: Random.h:142
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]algorithmthe name of the algorithm to use for random number generation
[in]seedthe seed value to initialize the generator with
Exceptions
lsst::pex::exceptions::InvalidParameterErrorThrown if the requested algorithm is not supported or a seed value of zero (corresponding to an algorithm specific seed) is chosen.
lsst::pex::exceptions::MemoryErrorThrown if memory allocation for internal generator state fails.

Definition at line 175 of file Random.cc.

176  : _rng(), _seed(seed)
177 {
178  initialize(algorithm);
179 }
unsigned long _seed
Definition: Random.h:141
boost::shared_ptr< ::gsl_rng > _rng
Definition: Random.h:140
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]policypolicy which contains the algorithm and seed to to use for random number generation
Returns
a newly created random number generator
Exceptions
lsst::pex::exceptions::InvalidParameterErrorThrown if the requested algorithm is not supported.
lsst::pex::exceptions::MemoryErrorThrown if memory allocation for internal generator state fails.
lsst::pex::exceptions::RuntimeErrorThrown if the "rngSeed" policy value cannot be converted to an unsigned long int.

Definition at line 200 of file Random.cc.

201  : _rng(), _seed()
202 {
203  std::string const seed(policy->getString("rngSeed"));
204  try {
205  _seed = boost::lexical_cast<unsigned long>(seed);
206  } catch(boost::bad_lexical_cast &) {
207  throw LSST_EXCEPT(ex::RuntimeError,
208  (boost::format("Invalid \"rngSeed\" policy value: \"%1%\"") % seed).str());
209  }
210  initialize(policy->getString("rngAlgorithm"));
211 }
unsigned long _seed
Definition: Random.h:141
#define LSST_EXCEPT(type,...)
Definition: Exception.h:46
boost::shared_ptr< ::gsl_rng > _rng
Definition: Random.h:140

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]nuthe 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.

380  {
381  return ::gsl_ran_chisq(_rng.get(), nu);
382 }
boost::shared_ptr< ::gsl_rng > _rng
Definition: Random.h:140
math::Random lsst.afw.math::Random::deepCopy ( void  ) 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::MemoryErrorThrown if memory allocation for internal generator state fails.

Definition at line 223 of file Random.cc.

223  {
224  Random rng = *this;
225  rng._rng.reset(::gsl_rng_clone(_rng.get()), ::gsl_rng_free);
226  if (!rng._rng) {
227  throw LSST_EXCEPT(ex::MemoryError, "gsl_rng_clone() failed");
228  }
229  return rng;
230 }
Random(Algorithm algorithm=MT19937, unsigned long seed=1)
Definition: Random.cc:151
#define LSST_EXCEPT(type,...)
Definition: Exception.h:46
boost::shared_ptr< ::gsl_rng > _rng
Definition: Random.h:140
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]alower endpoint of uniform distribution range (inclusive)
[in]bupper endpoint of uniform distribution range (exclusive)
Returns
a uniform random variate.

Definition at line 358 of file Random.cc.

358  {
359  return ::gsl_ran_flat(_rng.get(), a, b);
360 }
afw::table::Key< double > b
boost::shared_ptr< ::gsl_rng > _rng
Definition: Random.h:140
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.

370  {
371  return ::gsl_ran_gaussian_ziggurat(_rng.get(), 1.0);
372 }
boost::shared_ptr< ::gsl_rng > _rng
Definition: Random.h:140
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.

256  {
257  return _algorithm;
258 }
Algorithm _algorithm
Definition: Random.h:142
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.

263  {
264  return std::string(_algorithmNames[_algorithm]);
265 }
static char const *const _algorithmNames[NUM_ALGORITHMS]
Definition: Random.h:145
Algorithm _algorithm
Definition: Random.h:142
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.

270  {
271  static std::vector<std::string> names;
272  if (names.size() == 0) {
273  for (int i = 0; i < NUM_ALGORITHMS; ++i) {
274  names.push_back(_algorithmNames[i]);
275  }
276  }
277  return names;
278 }
static char const *const _algorithmNames[NUM_ALGORITHMS]
Definition: Random.h:145
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.

285  {
286  return _seed;
287 }
unsigned long _seed
Definition: Random.h:141
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.

232  {
233  return State(static_cast<char*>(::gsl_rng_state(_rng.get())), getStateSize());
234 }
std::size_t getStateSize() const
Definition: Random.cc:247
std::string State
Definition: Random.h:116
boost::shared_ptr< ::gsl_rng > _rng
Definition: Random.h:140
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.

247  {
248  return ::gsl_rng_size(_rng.get());
249 }
boost::shared_ptr< ::gsl_rng > _rng
Definition: Random.h:140
void lsst.afw.math::Random::initialize ( )
private

Definition at line 96 of file Random.cc.

96  {
97  if (_seed == 0) {
98  throw LSST_EXCEPT(ex::InvalidParameterError,
99  (boost::format("Invalid RNG seed: %lu") % _seed).str());
100  }
101  ::gsl_rng * rng = ::gsl_rng_alloc(_gslRngTypes[_algorithm]);
102  if (rng == 0) {
103  throw LSST_EXCEPT(ex::MemoryError, "gsl_rng_alloc() failed");
104  }
105  ::gsl_rng_set(rng, _seed);
106  _rng.reset(rng, ::gsl_rng_free);
107 }
unsigned long _seed
Definition: Random.h:141
::gsl_rng_type const *const _gslRngTypes[NUM_ALGORITHMS]
Definition: Random.h:144
#define LSST_EXCEPT(type,...)
Definition: Exception.h:46
boost::shared_ptr< ::gsl_rng > _rng
Definition: Random.h:140
Algorithm _algorithm
Definition: Random.h:142
void lsst.afw.math::Random::initialize ( std::string const &  algorithm)
private

Definition at line 119 of file Random.cc.

119  {
120  // linear search (the number of algorithms is small)
121  for (int i = 0; i < NUM_ALGORITHMS; ++i) {
122  if (_algorithmNames[i] == algorithm) {
123  _algorithm = static_cast<Algorithm>(i);
124  initialize();
125  return;
126  }
127  }
128  throw LSST_EXCEPT(ex::InvalidParameterError, "RNG algorithm " +
129  algorithm + " is not supported");
130 }
#define LSST_EXCEPT(type,...)
Definition: Exception.h:46
static char const *const _algorithmNames[NUM_ALGORITHMS]
Definition: Random.h:145
Algorithm _algorithm
Definition: Random.h:142
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
nudesired mean (and variance)

Definition at line 390 of file Random.cc.

391  {
392  return ::gsl_ran_poisson(_rng.get(), mu);
393 }
boost::shared_ptr< ::gsl_rng > _rng
Definition: Random.h:140
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.

236  {
237  if (state.size() != getStateSize()) {
238  throw LSST_EXCEPT(
239  pex::exceptions::LengthError,
240  (boost::format("Size of given state vector (%d) does not match expected size (%d)")
241  % state.size() % getStateSize()).str()
242  );
243  }
244  std::copy(state.begin(), state.end(), static_cast<char*>(::gsl_rng_state(_rng.get())));
245 }
SelectEigenView< T >::Type copy(Eigen::EigenBase< T > const &other)
Copy an arbitrary Eigen expression into a new EigenView.
Definition: eigen.h:390
std::size_t getStateSize() const
Definition: Random.cc:247
#define LSST_EXCEPT(type,...)
Definition: Exception.h:46
boost::shared_ptr< ::gsl_rng > _rng
Definition: Random.h:140
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.

304  {
305  return ::gsl_rng_uniform(_rng.get());
306 }
boost::shared_ptr< ::gsl_rng > _rng
Definition: Random.h:140
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]nspecifies the range of allowable return values (0 to n-1)
Returns
a uniformly distributed random integer
Exceptions
lsst::pex::exceptions::RangeErrorThrown 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.

341  {
342  if (n > ::gsl_rng_max(_rng.get()) - ::gsl_rng_min(_rng.get())) {
343  throw LSST_EXCEPT(ex::RangeError,
344  "Desired random number range exceeds generator range");
345  }
346  return ::gsl_rng_uniform_int(_rng.get(), n);
347 }
#define LSST_EXCEPT(type,...)
Definition: Exception.h:46
boost::shared_ptr< ::gsl_rng > _rng
Definition: Random.h:140
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.

319  {
320  return ::gsl_rng_uniform_pos(_rng.get());
321 }
boost::shared_ptr< ::gsl_rng > _rng
Definition: Random.h:140

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: