Noise-related Functionality

C++ Random Deviates

class BaseDeviate

Base class for all the various Deviates.

This holds the essential random number generator that all the other classes use.

All deviates have three constructors that define different ways of setting up the random number generator.

1) Only the arguments particular to the derived class (e.g. mean and sigma for GaussianDeviate). In this case, a new random number generator is created and it is seeded using the computer’s microsecond counter.

2) Using a particular seed as the first argument to the constructor. This will also create a new random number generator, but seed it with the provided value.

3) Passing another BaseDeviate as the first arguemnt to the constructor. This will make the new Deviate share the same underlying random number generator with the other Deviate. So you can make one Deviate (of any type), and seed it with a particular deterministic value. Then if you pass that Deviate to any other one you make, they will all be using the same rng and have a particular deterministic series of values. (It doesn’t have to be the first one — any one you’ve made later can also be used to seed a new one.)

There is not much you can do with something that is only known to be a BaseDeviate rather than one of the derived classes other than construct it and change the seed, and use it as an argument to pass to other Deviate constructors.

Subclassed by galsim::BinomialDeviate, galsim::Chi2Deviate, galsim::GammaDeviate, galsim::GaussianDeviate, galsim::PoissonDeviate, galsim::UniformDeviate, galsim::WeibullDeviate

Public Functions

explicit BaseDeviate(long lseed)

Construct and seed a new BaseDeviate, using the provided value as seed.

If lseed == 0, this means to use a random seed from the system: either /dev/urandom if possible, or the time of day otherwise. Note that in the latter case, the microsecond counter is the seed, so BaseDeviates constructed in rapid succession may not be independent.

Parameters:

lseed – [in] A long-integer seed for the RNG.

BaseDeviate(const BaseDeviate &rhs)

Construct a new BaseDeviate, sharing the random number generator with rhs.

BaseDeviate(const char *str_c)

Construct a new BaseDeviate from a serialization string.

inline virtual ~BaseDeviate()

Destructor.

Only deletes the underlying RNG if this is the last one using it.

std::string serialize()

return a serialization string for this BaseDeviate

BaseDeviate duplicate()

Construct a duplicate of this BaseDeviate object.

Both this and the returned duplicate will produce identical sequences of values.

inline virtual shared_ptr<BaseDeviate> duplicate_ptr()

Construct a pointer to a duplicate of this object.

This is usually the version you want when working in C++. It is a virtual function so it resolves to the right function call a compile time, but the return value is always a shared_ptr<BaseDeviate>.

I couldn’t figure out how to have only one of these two nearly identical bits of functionality work both in Python and C++ to do what we want.

inline std::string repr()

Return a string that can act as the repr in python.

inline std::string str()

Return a string that can act as the str in python.

For this we use the same thing as the repr, but omit the (verbose!) seed parameter.

virtual void seed(long lseed)

Re-seed the PRNG using specified seed.

If lseed == 0, this means to use a random seed from the system: either /dev/urandom if possible, or the time of day otherwise. Note that in the latter case, the microsecond counter is the seed, so BaseDeviates constructed in rapid succession may not be independent.

Note that this will reseed all Deviates currently sharing the RNG with this one.

Parameters:

lseed – [in] A long-integer seed for the RNG.

void reset(long lseed)

Like seed(lseed), but severs the relationship between other Deviates.

Other Deviates that had been using the same RNG will be unaffected, while this Deviate will obtain a fresh RNG seed according to lseed.

void reset(const BaseDeviate &dev)

Make this object share its random number generator with another Deviate.

It discards whatever rng it had been using and starts sharing the one held by dev.

inline virtual void clearCache()

Clear the internal cache of the rng object.

Sometimes this is required to get two sequences synced up if the other one is reseeded. e.g. GaussianDeviate generates two deviates at a time for efficiency, so if you don’t do this, and there is still an internal cached value, you’ll get that rather than a new one generated with the new seed.

As far as I know, GaussianDeviate is the only one to require this, but just in case something changes about how boost implements any of these deviates, I overload the virtual function for all of them and call the distribution’s reset() method.

void discard(int n)

Discard some number of values from the random number generator.

long raw()

Get a random value in its raw form as a long integer.

inline double operator()()

Draw a new random number from the distribution.

This is invalid for a BaseDeviate object that is not a derived class. However, we don’t make it pure virtual, since we want to be able to make BaseDeviate objects as a direct way to define a common seed for other Deviates.

inline virtual double generate1()

void generate(long long N, double *data)

Draw N new random numbers from the distribution and save the values in an array.

Parameters:

• N – The number of values to draw

• data – The array into which to write the values

void addGenerate(long long N, double *data)

Draw N new random numbers from the distribution and add them to the values in an array.

Parameters:

• N – The number of values to draw

• data – The array into which to add the values

class UniformDeviate : public galsim::BaseDeviate

Pseudo-random number generator with uniform distribution in interval [0.,1.).

Public Functions

UniformDeviate(long lseed)

Construct and seed a new UniformDeviate, using the provided value as seed.

If lseed == 0, this means to use a random seed from the system: either /dev/urandom if possible, or the time of day otherwise. Note that in the latter case, the microsecond counter is the seed, so BaseDeviates constructed in rapid succession may not be independent.

Parameters:

lseed – [in] A long-integer seed for the RNG.

UniformDeviate(const BaseDeviate &rhs)

Construct a new UniformDeviate, sharing the random number generator with rhs.

UniformDeviate(const UniformDeviate &rhs)

Construct a copy that shares the RNG with rhs.

UniformDeviate(const char *str_c)

Construct a new UniformDeviate from a serialization string.

inline UniformDeviate duplicate()

Construct a duplicate of this UniformDeviate object.

Both this and the returned duplicate will produce identical sequences of values.

inline virtual shared_ptr<BaseDeviate> duplicate_ptr()

Construct a pointer to a duplicate of this object.

virtual double generate1()

Draw a new random number from the distribution.

Returns:

A uniform deviate in the interval [0.,1.)

virtual void clearCache()

Clear the internal cache.

class GaussianDeviate : public galsim::BaseDeviate

Pseudo-random number generator with Gaussian distribution.

Public Functions

GaussianDeviate(long lseed, double mean, double sigma)

Construct a new Gaussian-distributed RNG, using the provided value as seed.

If lseed == 0, this means to use a random seed from the system: either /dev/urandom if possible, or the time of day otherwise. Note that in the latter case, the microsecond counter is the seed, so BaseDeviates constructed in rapid succession may not be independent.

Parameters:

• lseed – [in] Seed to use.

• mean – [in] Mean of the output distribution

• sigma – [in] Standard deviation of the distribution

GaussianDeviate(const BaseDeviate &rhs, double mean, double sigma)

Construct a new Gaussian-distributed RNG, sharing the random number generator with rhs.

Parameters:

• rhs – [in] Other deviate with which to share the RNG

• mean – [in] Mean of the output distribution

• sigma – [in] Standard deviation of the distribution

GaussianDeviate(const GaussianDeviate &rhs)

Construct a copy that shares the RNG with rhs.

Note: the default constructed op= function will do the same thing.

GaussianDeviate(const char *str_c, double mean, double sigma)

Construct a new GaussianDeviate from a serialization string.

inline GaussianDeviate duplicate()

Construct a duplicate of this GaussianDeviate object.

Both this and the returned duplicate will produce identical sequences of values.

inline virtual shared_ptr<BaseDeviate> duplicate_ptr()

Construct a pointer to a duplicate of this object.

virtual double generate1()

Draw a new random number from the distribution.

Returns:

A Gaussian deviate with current mean and sigma

double getMean()

Get current distribution mean.

Returns:

Mean of distribution

double getSigma()

Get current distribution standard deviation.

Returns:

Standard deviation of distribution

void setMean(double mean)

Set current distribution mean.

Parameters:

mean – [in] New mean for distribution

void setSigma(double sigma)

Set current distribution standard deviation.

Parameters:

sigma – [in] New standard deviation for distribution. Behavior for non-positive value is undefined.

virtual void clearCache()

Clear the internal cache.

This one is definitely required, since _normal generates two deviates at a time and stores one for later. So this clears that out when necessary.

void generateFromVariance(long long N, double *data)

Replace data with Gaussian draws using the existing data as the variances.

Parameters:

• N – The number of values to draw

• data – The array with the given variances to replace with Gaussian draws.

class BinomialDeviate : public galsim::BaseDeviate

A Binomial deviate for N trials each of probability p.

Public Functions

BinomialDeviate(long lseed, int N, double p)

Construct a new binomial-distributed RNG, using the provided value as seed.

If lseed == 0, this means to use a random seed from the system: either /dev/urandom if possible, or the time of day otherwise. Note that in the latter case, the microsecond counter is the seed, so BaseDeviates constructed in rapid succession may not be independent.

Parameters:

• lseed – [in] Seed to use

• N – [in] Number of “coin flips” per trial

• p – [in] Probability of success per coin flip.

BinomialDeviate(const BaseDeviate &rhs, int N, double p)

Construct a new binomial-distributed RNG, sharing the random number generator with rhs.

Parameters:

• rhs – [in] Other deviate with which to share the RNG

• N – [in] Number of “coin flips” per trial

• p – [in] Probability of success per coin flip.

BinomialDeviate(const BinomialDeviate &rhs)

Construct a copy that shares the RNG with rhs.

Note: the default constructed op= function will do the same thing.

BinomialDeviate(const char *str_c, int N, double p)

Construct a new BinomialDeviate from a serialization string.

inline BinomialDeviate duplicate()

Construct a duplicate of this BinomialDeviate object.

Both this and the returned duplicate will produce identical sequences of values.

inline virtual shared_ptr<BaseDeviate> duplicate_ptr()

Construct a pointer to a duplicate of this object.

virtual double generate1()

Draw a new random number from the distribution.

Returns:

A binomial deviate with current N and p

int getN()

Report current value of N.

Returns:

Current value of N

double getP()

Report current value of p.

Returns:

Current value of p

void setN(int N)

Reset value of N.

Parameters:

N – [in] New value of N

void setP(double p)

Reset value of p.

Parameters:

p – [in] New value of p

virtual void clearCache()

Clear the internal cache.

class PoissonDeviate : public galsim::BaseDeviate

A Poisson deviate with specified mean.

Public Functions

PoissonDeviate(long lseed, double mean)

Construct a new Poisson-distributed RNG, using the provided value as seed.

If lseed == 0, this means to use a random seed from the system: either /dev/urandom if possible, or the time of day otherwise. Note that in the latter case, the microsecond counter is the seed, so BaseDeviates constructed in rapid succession may not be independent.

Parameters:

• lseed – [in] Seed to use

• mean – [in] Mean of the output distribution

PoissonDeviate(const BaseDeviate &rhs, double mean)

Construct a new Poisson-distributed RNG, sharing the random number generator with rhs.

Parameters:

• rhs – [in] Other deviate with which to share the RNG

• mean – [in] Mean of the output distribution

PoissonDeviate(const PoissonDeviate &rhs)

Construct a copy that shares the RNG with rhs.

Note: the default constructed op= function will do the same thing.

PoissonDeviate(const char *str_c, double mean)

Construct a new PoissonDeviate from a serialization string.

virtual double generate1()

Draw a new random number from the distribution.

Returns:

A Poisson deviate with current mean

inline PoissonDeviate duplicate()

Construct a duplicate of this PoissonDeviate object.

Both this and the returned duplicate will produce identical sequences of values.

inline virtual shared_ptr<BaseDeviate> duplicate_ptr()

Construct a pointer to a duplicate of this object.

double getMean()

Report current distribution mean.

Returns:

Current mean value

void setMean(double mean)

Reset distribution mean.

Parameters:

mean – [in] New mean value

virtual void clearCache()

Clear the internal cache.

void generateFromExpectation(long long N, double *data)

Replace data with Poisson draws using the existing data as the expectation value.

Parameters:

• N – The number of values to draw

• data – The array with the given data to replace with Poisson draws.

class WeibullDeviate : public galsim::BaseDeviate

A Weibull-distributed deviate with shape parameter a and scale parameter b.

The Weibull distribution is related to a number of other probability distributions; in particular, it interpolates between the exponential distribution (a=1) and the Rayleigh distribution (a=2). See http://en.wikipedia.org/wiki/Weibull_distribution (a=k and b=lambda in the notation adopted in the Wikipedia article). The Weibull distribution is a real valued distribution producing deviates >= 0.

Public Functions

WeibullDeviate(long lseed, double a, double b)

Construct a new Weibull-distributed RNG, using the provided value as seed.

If lseed == 0, this means to use a random seed from the system: either /dev/urandom if possible, or the time of day otherwise. Note that in the latter case, the microsecond counter is the seed, so BaseDeviates constructed in rapid succession may not be independent.

Parameters:

• lseed – [in] Seed to use

• a – [in] Shape parameter of the output distribution, must be > 0.

• b – [in] Scale parameter of the distribution, must be > 0.

WeibullDeviate(const BaseDeviate &rhs, double a, double b)

Construct a new Weibull-distributed RNG, sharing the random number generator with rhs.

Parameters:

• rhs – [in] Other deviate with which to share the RNG

• a – [in] Shape parameter of the output distribution, must be > 0.

• b – [in] Scale parameter of the distribution, must be > 0.

WeibullDeviate(const WeibullDeviate &rhs)

Construct a copy that shares the RNG with rhs.

Note: the default constructed op= function will do the same thing.

WeibullDeviate(const char *str_c, double a, double b)

Construct a new WeibullDeviate from a serialization string.

inline WeibullDeviate duplicate()

Construct a duplicate of this WeibullDeviate object.

Both this and the returned duplicate will produce identical sequences of values.

inline virtual shared_ptr<BaseDeviate> duplicate_ptr()

Construct a pointer to a duplicate of this object.

virtual double generate1()

Draw a new random number from the distribution.

Returns:

A Weibull deviate with current shape k and scale lam.

double getA()

Get current distribution shape parameter a.

Returns:

Shape parameter a of distribution.

double getB()

Get current distribution scale parameter b.

Returns:

Scale parameter b of distribution.

void setA(double a)

Set current distribution shape parameter a.

Parameters:

a – [in] New shape parameter for distribution. Behaviour for non-positive value is undefined.

void setB(double b)

Set current distribution scale parameter b.

Parameters:

b – [in] New scale parameter for distribution. Behavior for non-positive value is undefined.

virtual void clearCache()

Clear the internal cache.

class GammaDeviate : public galsim::BaseDeviate

A Gamma-distributed deviate with shape parameter k and scale parameter theta.

See http://en.wikipedia.org/wiki/Gamma_distribution. (Note: we use the k, theta notation. If you prefer alpha, beta, use k=alpha, theta=1/beta.) The Gamma distribution is a real valued distribution producing deviates >= 0.

Public Functions

GammaDeviate(long lseed, double k, double theta)

Construct a new Gamma-distributed RNG, using the provided value as seed.

If lseed == 0, this means to use a random seed from the system: either /dev/urandom if possible, or the time of day otherwise. Note that in the latter case, the microsecond counter is the seed, so BaseDeviates constructed in rapid succession may not be independent.

Parameters:

• lseed – [in] Seed to use.

• k – [in] Shape parameter of the output distribution, must be > 0.

• theta – [in] Scale parameter of the distribution, must be > 0.

GammaDeviate(const BaseDeviate &rhs, double k, double theta)

Construct a new Gamma-distributed RNG, sharing the random number generator with rhs.

Parameters:

• rhs – [in] Other deviate with which to share the RNG

• k – [in] Shape parameter of the output distribution, must be > 0.

• theta – [in] Scale parameter of the distribution, must be > 0.

GammaDeviate(const GammaDeviate &rhs)

Construct a copy that shares the RNG with rhs.

Note: the default constructed op= function will do the same thing.

GammaDeviate(const char *str_c, double k, double theta)

Construct a new GammaDeviate from a serialization string.

inline GammaDeviate duplicate()

Construct a duplicate of this GammaDeviate object.

Both this and the returned duplicate will produce identical sequences of values.

inline virtual shared_ptr<BaseDeviate> duplicate_ptr()

Construct a pointer to a duplicate of this object.

virtual double generate1()

Draw a new random number from the distribution.

Returns:

A Gamma deviate with current shape k and scale theta.

double getK()

Get current distribution shape parameter k.

Returns:

Shape parameter k of distribution.

double getTheta()

Get current distribution scale parameter theta.

Returns:

Scale parameter theta of distribution.

void setK(double k)

Set current distribution shape parameter k.

Parameters:

k – [in] New shape parameter for distribution. Behaviour for non-positive value is undefined.

void setTheta(double theta)

Set current distribution scale parameter theta.

Parameters:

theta – [in] New scale parameter for distribution. Behavior for non-positive value is undefined.

virtual void clearCache()

Clear the internal cache.

class Chi2Deviate : public galsim::BaseDeviate

A Chi^2-distributed deviate with degrees-of-freedom parameter n.

See http://en.wikipedia.org/wiki/Chi-squared_distribution (although note that in the Boost random routine this class calls the notation is k=n for the number of degrees of freedom). The Chi^2 distribution is a real valued distribution producing deviates >= 0.

Public Functions

Chi2Deviate(long lseed, double n)

Construct a new Chi^2-distributed RNG, using the provided value as seed.

If lseed == 0, this means to use a random seed from the system: either /dev/urandom if possible, or the time of day otherwise. Note that in the latter case, the microsecond counter is the seed, so BaseDeviates constructed in rapid succession may not be independent.

Parameters:

• lseed – [in] Seed to use

• n – [in] Number of degrees of freedom for the output distribution, must be > 0.

Chi2Deviate(const BaseDeviate &rhs, double n)

Construct a new Chi^2-distributed RNG, sharing the random number generator with rhs.

Parameters:

• rhs – [in] Other deviate with which to share the RNG

• n – [in] Number of degrees of freedom for the output distribution, must be > 0.

Chi2Deviate(const Chi2Deviate &rhs)

Construct a copy that shares the RNG with rhs.

Note: the default constructed op= function will do the same thing.

Chi2Deviate(const char *str_c, double n)

Construct a new Chi2Deviate from a serialization string.

inline Chi2Deviate duplicate()

Construct a duplicate of this Chi2Deviate object.

Both this and the returned duplicate will produce identical sequences of values.

inline virtual shared_ptr<BaseDeviate> duplicate_ptr()

Construct a pointer to a duplicate of this object.

virtual double generate1()

Draw a new random number from the distribution.

Returns:

A Chi^2 deviate with current degrees-of-freedom parameter n.

double getN()

Get current distribution degrees-of-freedom parameter n.

Returns:

Degrees-of-freedom parameter n of distribution.

void setN(double n)

Set current distribution degrees-of-freedom parameter n.

Parameters:

n – [in] New degrees-of-freedom parameter n for distribution. Behaviour for non-positive value is undefined.

virtual void clearCache()

Clear the internal cache.

C++ Correlated Noise

void galsim::calculateCovarianceMatrix(ImageView<double> &cov, const SBProfile &sbp, const Bounds<int> &bounds, double dx)

Return, as a square Image, a noise covariance matrix between every element in an Image with supplied bounds and pixel scale dx for a correlation function represented as an SBProfile.

The matrix is symmetric, and therefore only the upper triangular elements are actually written into. The rest are initialized and remain as zero.

For an example of this function in use, see galsim/correlatednoise.py.