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/>.
 */


#ifndef LSST_AFW_MATH_RANDOM_H
#define LSST_AFW_MATH_RANDOM_H

#include <memory>

#include "gsl/gsl_rng.h"

#include "lsst/pex/exceptions.h"
#include "lsst/pex/policy/Policy.h"


namespace lsst { namespace afw { namespace math {

class Random {
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);
    explicit Random(lsst::pex::policy::Policy::Ptr const policy);
    // Use compiler generated destructor and shallow copy constructor/assignment operator

    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 nu);

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 &);
};

/************************************************************************************************************/
/*
 * 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);


}}} // end of namespace lsst::afw::math

#endif // LSST_AFW_MATH_RANDOM_H