File Random.h

namespace lsst

Class for a simple mapping implementing a generic AstrometryTransform.

Remove all non-astronomical counts from the Chunk Exposure’s pixels.

Forward declarations for lsst::utils::Cache

For details on the Cache class, see the Cache.h file.

It uses a template rather than a pointer so that the derived classes can use the specifics of the transform. The class simplePolyMapping overloads a few routines.

A base class for image defects

Numeric constants used by the Integrate.h integrator routines.

Compute Image Statistics

Note

Gauss-Kronrod-Patterson quadrature coefficients for use in quadpack routine qng. These coefficients were calculated with 101 decimal digit arithmetic by L. W. Fullerton, Bell Labs, Nov 1981.

Note

The Statistics class itself can only handle lsst::afw::image::MaskedImage() types. The philosophy has been to handle other types by making them look like lsst::afw::image::MaskedImage() and reusing that code. Users should have no need to instantiate a Statistics object directly, but should use the overloaded makeStatistics() factory functions.

namespace afw
namespace math

Functions

template<typename ImageT>
void randomUniformImage(ImageT *image, Random &rand)

Set image to random numbers uniformly distributed in the range [0, 1)

Parameters

  • [out] image: The image to set

  • [inout] rand: definition of random number algorithm, seed, etc.

template<typename ImageT>
void randomUniformPosImage(ImageT *image, Random &rand)

Set image to random numbers uniformly distributed in the range (0, 1)

Parameters

  • [out] image: The image to set

  • [inout] rand: definition of random number algorithm, seed, etc.

template<typename ImageT>
void randomUniformIntImage(ImageT *image, Random &rand, unsigned long n)

Set image to random integers uniformly distributed in the range 0 … n - 1

Parameters

  • [out] image: The image to set

  • [inout] rand: definition of random number algorithm, seed, etc.

  • [in] n: (exclusive) upper limit for random variates

template<typename ImageT>
void randomFlatImage(ImageT *image, Random &rand, double const a, double const b)

Set image to random numbers uniformly distributed in the range [a, b)

Parameters

  • [out] image: The image to set

  • [inout] rand: definition of random number algorithm, seed, etc.

  • [in] a: (inclusive) lower limit for random variates

  • [in] b: (exclusive) upper limit for random variates

template<typename ImageT>
void randomGaussianImage(ImageT *image, Random &rand)

Set image to random numbers with a gaussian N(0, 1) distribution

Parameters

  • [out] image: The image to set

  • [inout] rand: definition of random number algorithm, seed, etc.

template<typename ImageT>
void randomChisqImage(ImageT *image, Random &rand, double const nu)

Set image to random numbers with a chi^2_{nu} distribution

Parameters

  • [out] image: The image to set

  • [inout] rand: definition of random number algorithm, seed, etc.

  • [in] nu: number of degrees of freedom

template<typename ImageT>
void randomPoissonImage(ImageT *image, Random &rand, double const mu)

Set image to random numbers with a Poisson distribution with mean mu (n.b. not per-pixel)

Parameters

  • [out] image: The image to set

  • [inout] rand: definition of random number algorithm, seed, etc.

  • [in] mu: mean of distribution

class Random
#include <Random.h>

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.

Private Functions

void initialize()

Initializes the underlying GSL random number generator.

void initialize(std::string const &algorithm)

Initializes the underlying GSL random number generator.

Parameters

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

Exceptions

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

Private Members

std::shared_ptr<gsl_rng> _rng
unsigned long _seed
Algorithm _algorithm

Private Static Attributes

gsl_rng_type const *const _gslRngTypes[NUM_ALGORITHMS]
char const *const _algorithmNames[NUM_ALGORITHMS]
char const *const _algorithmEnvVarName
char const *const _seedEnvVarName