LSSTApplications  20.0.0
LSSTDataManagementBasePackage
Random.h
Go to the documentation of this file.
1 // -*- lsst-c++ -*-
2 
3 /*
4  * LSST Data Management System
5  * Copyright 2008, 2009, 2010 LSST Corporation.
6  *
7  * This product includes software developed by the
8  * LSST Project (http://www.lsst.org/).
9  *
10  * This program is free software: you can redistribute it and/or modify
11  * it under the terms of the GNU General Public License as published by
12  * the Free Software Foundation, either version 3 of the License, or
13  * (at your option) any later version.
14  *
15  * This program is distributed in the hope that it will be useful,
16  * but WITHOUT ANY WARRANTY; without even the implied warranty of
17  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
18  * GNU General Public License for more details.
19  *
20  * You should have received a copy of the LSST License Statement and
21  * the GNU General Public License along with this program. If not,
22  * see <http://www.lsstcorp.org/LegalNotices/>.
23  */
24 
25 /*
26  * Random number generator class.
27  */
28 
29 #ifndef LSST_AFW_MATH_RANDOM_H
30 #define LSST_AFW_MATH_RANDOM_H
31 
32 #include <memory>
33 
34 #include "gsl/gsl_rng.h"
35 
36 #include "lsst/pex/exceptions.h"
37 
38 namespace lsst {
39 namespace afw {
40 namespace math {
41 
57 class Random final {
58 public:
60  enum Algorithm {
62  MT19937 = 0,
83  MRG,
93  };
94 
95  // -- Constructor --------
110  explicit Random(Algorithm algorithm = MT19937, unsigned long seed = 1);
123  explicit Random(std::string const &algorithm, unsigned long seed = 1);
124 
125  // Use compiler generated destructor and shallow copy constructor/assignment operator
126  Random(Random const &) = default;
127  Random(Random &&) = default;
128  Random &operator=(Random const &) = default;
129  Random &operator=(Random &&) = default;
130  ~Random() = default;
131 
141  Random deepCopy() const;
142 
144 
155  State getState() const;
156  void setState(State const &state);
157  std::size_t getStateSize() const;
159 
160  // -- Accessors --------
164  Algorithm getAlgorithm() const;
177  unsigned long getSeed() const;
178 
179  // -- Modifiers: generating random numbers --------
192  double uniform();
204  double uniformPos();
223  unsigned long uniformInt(unsigned long n);
224 
225  // -- Modifiers: computing random variates for various distributions --------
233  double flat(double const a, double const b);
242  double gaussian();
249  double chisq(double const nu);
256  double poisson(double const mu);
257 
258 private:
260  unsigned long _seed;
261  Algorithm _algorithm;
262 
263  static ::gsl_rng_type const *const _gslRngTypes[NUM_ALGORITHMS];
264  static char const *const _algorithmNames[NUM_ALGORITHMS];
265  static char const *const _algorithmEnvVarName;
266  static char const *const _seedEnvVarName;
267 
271  void initialize();
280  void initialize(std::string const &algorithm);
281 };
282 
283 /*
284  * Create Images containing random numbers
285  */
292 template <typename ImageT>
293 void randomUniformImage(ImageT *image, Random &rand);
294 
301 template <typename ImageT>
302 void randomUniformPosImage(ImageT *image, Random &rand);
303 
311 template <typename ImageT>
312 void randomUniformIntImage(ImageT *image, Random &rand, unsigned long n);
313 
322 template <typename ImageT>
323 void randomFlatImage(ImageT *image, Random &rand, double const a, double const b);
324 
331 template <typename ImageT>
332 void randomGaussianImage(ImageT *image, Random &rand);
333 
341 template <typename ImageT>
342 void randomChisqImage(ImageT *image, Random &rand, double const nu);
343 
351 template <typename ImageT>
352 void randomPoissonImage(ImageT *image, Random &rand, double const mu);
353 } // namespace math
354 } // namespace afw
355 } // namespace lsst
356 
357 #endif // LSST_AFW_MATH_RANDOM_H
lsst::afw::math::Random::flat
double flat(double const a, double const b)
Returns a random variate from the flat (uniform) distribution on [a, b).
Definition: Random.cc:159
lsst::afw::math::Random::RANLUX
@ RANLUX
Original version of the RANLUX algorithm, 24-bit output.
Definition: Random.h:77
lsst::afw::image
Backwards-compatibility support for depersisting the old Calib (FluxMag0/FluxMag0Err) objects.
Definition: imageAlgorithm.dox:1
lsst::afw::math::Random::RANLXD1
@ RANLXD1
Double precision (48-bit) output using the RANLXS algorithm, luxury level 1 (weakest).
Definition: Random.h:73
std::string
STL class.
std::shared_ptr< ::gsl_rng >
lsst::afw::math::Random::operator=
Random & operator=(Random &&)=default
lsst::afw::math::Random::uniformPos
double uniformPos()
Returns a uniformly distributed random double precision floating point number from the generator.
Definition: Random.cc:148
lsst::afw::math::Random::getAlgorithmName
std::string getAlgorithmName() const
Definition: Random.cc:130
std::vector< std::string >
lsst::afw::math::Random::Random
Random(Algorithm algorithm=MT19937, unsigned long seed=1)
Creates a random number generator that uses the given algorithm to produce random numbers,...
Definition: Random.cc:89
lsst::afw::math::Random::TAUS2
@ TAUS2
A maximally equidistributed combined Tausworthe generator by L'Ecuyer with improved seeding relative ...
Definition: Random.h:88
lsst::afw::math::Random::RANLUX389
@ RANLUX389
Original version of the RANLUX algorithm, 24-bit output (all bits are decorrelated).
Definition: Random.h:79
lsst::afw
Definition: imageAlgorithm.dox:1
lsst::afw::math::Random::TAUS
@ TAUS
A maximally equidistributed combined Tausworthe generator by L'Ecuyer.
Definition: Random.h:85
lsst::afw::math::Random::getStateSize
std::size_t getStateSize() const
Definition: Random.cc:124
lsst::afw::math::Random::uniform
double uniform()
Returns a uniformly distributed random double precision floating point number from the generator.
Definition: Random.cc:146
lsst::afw::math::randomFlatImage
void randomFlatImage(ImageT *image, Random &rand, double const a, double const b)
Set image to random numbers uniformly distributed in the range [a, b)
Definition: RandomImage.cc:125
lsst::afw::math::Random::getSeed
unsigned long getSeed() const
Definition: Random.cc:142
lsst::afw::math::Random::uniformInt
unsigned long uniformInt(unsigned long n)
Returns a uniformly distributed random integer from 0 to n-1.
Definition: Random.cc:150
lsst::afw::math::Random::MRG
@ MRG
Fifth-order multiple recursive generator by L'Ecuyer, Blouin, and Coutre.
Definition: Random.h:83
lsst::afw::math::Random::getAlgorithm
Algorithm getAlgorithm() const
Definition: Random.cc:128
lsst::afw::math::Random::getAlgorithmNames
static std::vector< std::string > const & getAlgorithmNames()
Definition: Random.cc:132
lsst::afw::math::Random::RANLXS2
@ RANLXS2
Second-generation version of the RANLUX algorithm of Lüscher, 24-bit output, luxury level 2 (stronges...
Definition: Random.h:71
lsst::afw::math::randomUniformPosImage
void randomUniformPosImage(ImageT *image, Random &rand)
Set image to random numbers uniformly distributed in the range (0, 1)
Definition: RandomImage.cc:115
lsst::afw::math::Random::chisq
double chisq(double const nu)
Returns a random variate from the chi-squared distribution with nu degrees of freedom.
Definition: Random.cc:163
lsst::afw::math::Random::Algorithm
Algorithm
Identifiers for the list of supported algorithms.
Definition: Random.h:60
lsst::afw::math::Random::Random
Random(Random &&)=default
lsst::afw::math::Random::Random
Random(Random const &)=default
lsst::afw::math::randomGaussianImage
void randomGaussianImage(ImageT *image, Random &rand)
Set image to random numbers with a gaussian N(0, 1) distribution.
Definition: RandomImage.cc:130
lsst::afw::math::Random::CMRG
@ CMRG
Combined multiple recursive generator by L'Ecuyer.
Definition: Random.h:81
b
table::Key< int > b
Definition: TransmissionCurve.cc:467
lsst::afw::math::Random::State
std::string State
Accessors for the opaque state of the random number generator.
Definition: Random.h:154
lsst
A base class for image defects.
Definition: imageAlgorithm.dox:1
lsst::afw::math::Random::NUM_ALGORITHMS
@ NUM_ALGORITHMS
Number of supported algorithms.
Definition: Random.h:92
lsst::afw::math::randomChisqImage
void randomChisqImage(ImageT *image, Random &rand, double const nu)
Set image to random numbers with a chi^2_{nu} distribution.
Definition: RandomImage.cc:135
lsst::afw::math::Random::setState
void setState(State const &state)
Definition: Random.cc:113
lsst::afw::math::Random::getState
State getState() const
Definition: Random.cc:109
lsst::afw::math::Random::~Random
~Random()=default
lsst::afw::math::Random::RANLXS1
@ RANLXS1
Second-generation version of the RANLUX algorithm of Lüscher, 24-bit output, luxury level 1 (stronger...
Definition: Random.h:68
lsst::afw::math::Random
A class that can be used to generate sequences of random numbers according to a number of different a...
Definition: Random.h:57
lsst::afw::math::Random::operator=
Random & operator=(Random const &)=default
a
table::Key< int > a
Definition: TransmissionCurve.cc:466
lsst::afw::math::Random::gaussian
double gaussian()
Returns a gaussian random variate with mean 0 and standard deviation 1
Definition: Random.cc:161
lsst::afw::math::Random::RANLXD2
@ RANLXD2
Double precision (48-bit) output using the RANLXS algorithm, luxury level 2 (strongest).
Definition: Random.h:75
lsst::afw::math::Random::GFSR4
@ GFSR4
A fifth-order multiple recursive generator by L'Ecuyer, Blouin, and Coutre.
Definition: Random.h:90
lsst::afw::math::randomUniformIntImage
void randomUniformIntImage(ImageT *image, Random &rand, unsigned long n)
Set image to random integers uniformly distributed in the range 0 ...
Definition: RandomImage.cc:120
lsst::afw::math::Random::RANLXS0
@ RANLXS0
Second-generation version of the RANLUX algorithm of Lüscher, 24-bit output, luxury level 0 (weakest)
Definition: Random.h:65
std::size_t
lsst::afw::math::Random::MT19937
@ MT19937
The MT19937 "Mersenne Twister" generator of Makoto Matsumoto and Takuji Nishimura.
Definition: Random.h:62
lsst::afw::math::randomUniformImage
void randomUniformImage(ImageT *image, Random &rand)
Set image to random numbers uniformly distributed in the range [0, 1)
Definition: RandomImage.cc:110
lsst::afw::math::Random::deepCopy
Random deepCopy() const
Creates a deep copy of this random number generator.
Definition: Random.cc:100
lsst::afw::math::Random::poisson
double poisson(double const mu)
Returns a random variate from the poisson distribution with mean mu.
Definition: Random.cc:165
lsst::afw::math::randomPoissonImage
void randomPoissonImage(ImageT *image, Random &rand, double const mu)
Set image to random numbers with a Poisson distribution with mean mu (n.b.
Definition: RandomImage.cc:140
exceptions.h