Random.h

Go to the documentation of this file.

// -*- lsst-c++ -*-

/*
 * LSST Data Management System
 * Copyright 2008, 2009, 2010 LSST Corporation.
 *
 * This product includes software developed by the
 * LSST Project (http://www.lsst.org/).
 *
 * This program is free software: you can redistribute it and/or modify
 * it under the terms of the GNU General Public License as published by
 * the Free Software Foundation, either version 3 of the License, or
 * (at your option) any later version.
 *
 * This program is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 * GNU General Public License for more details.
 *
 * You should have received a copy of the LSST License Statement and
 * the GNU General Public License along with this program.  If not,
 * see <http://www.lsstcorp.org/LegalNotices/>.
 */

/*
 * Random number generator class.
 */

#ifndef LSST_AFW_MATH_RANDOM_H
#define LSST_AFW_MATH_RANDOM_H

#include <memory>

#include "gsl/gsl_rng.h"

#include "lsst/pex/exceptions.h"

namespace lsst {
namespace afw {
namespace math {

class Random final {
public:
    enum Algorithm {
        MT19937 = 0,
        RANLXS0,
        RANLXS1,
        RANLXS2,
        RANLXD1,
        RANLXD2,
        RANLUX,
        RANLUX389,
        CMRG,
        MRG,
        TAUS,
        TAUS2,
        GFSR4,
        NUM_ALGORITHMS
    };

    // -- Constructor --------
    explicit Random(Algorithm algorithm = MT19937, unsigned long seed = 1);
    explicit Random(std::string const &algorithm, unsigned long seed = 1);

    // Use compiler generated destructor and shallow copy constructor/assignment operator
    Random(Random const &) = default;
    Random(Random &&) = default;
    Random &operator=(Random const &) = default;
    Random &operator=(Random &&) = default;
    ~Random() = default;

    Random deepCopy() const;


    typedef std::string State;
    State getState() const;
    void setState(State const &state);
    std::size_t getStateSize() const;

    // -- Accessors --------
    Algorithm getAlgorithm() const;
    std::string getAlgorithmName() const;
    static std::vector<std::string> const &getAlgorithmNames();
    unsigned long getSeed() const;

    // -- Modifiers: generating random numbers --------
    double uniform();
    double uniformPos();
    unsigned long uniformInt(unsigned long n);

    // -- Modifiers: computing random variates for various distributions --------
    double flat(double const a, double const b);
    double gaussian();
    double chisq(double const nu);
    double poisson(double const mu);

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

    static ::gsl_rng_type const *const _gslRngTypes[NUM_ALGORITHMS];
    static char const *const _algorithmNames[NUM_ALGORITHMS];
    static char const *const _algorithmEnvVarName;
    static char const *const _seedEnvVarName;

    void initialize();
    void initialize(std::string const &algorithm);
};

/*
 * Create Images containing random numbers
 */
template <typename ImageT>
void randomUniformImage(ImageT *image, Random &rand);

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

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

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

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

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

template <typename ImageT>
void randomPoissonImage(ImageT *image, Random &rand, double const mu);
}  // namespace math
}  // namespace afw
}  // namespace lsst

#endif  // LSST_AFW_MATH_RANDOM_H