boost/random/lognormal_distribution.hpp

0001 /* boost random/lognormal_distribution.hpp header file
0002  *
0003  * Copyright Jens Maurer 2000-2001
0004  * Copyright Steven Watanabe 2011
0005  * Distributed under the Boost Software License, Version 1.0. (See
0006  * accompanying file LICENSE_1_0.txt or copy at
0007  * http://www.boost.org/LICENSE_1_0.txt)
0008  *
0009  * See http://www.boost.org for most recent version including documentation.
0010  *
0011  * $Id$
0012  *
0013  * Revision history
0014  *  2001-02-18  moved to individual header files
0015  */
0016
0017 #ifndef BOOST_RANDOM_LOGNORMAL_DISTRIBUTION_HPP
0018 #define BOOST_RANDOM_LOGNORMAL_DISTRIBUTION_HPP
0019
0020 #include <boost/config/no_tr1/cmath.hpp>      // std::exp, std::sqrt
0021 #include <cassert>
0022 #include <iosfwd>
0023 #include <istream>
0024 #include <boost/limits.hpp>
0025 #include <boost/random/detail/config.hpp>
0026 #include <boost/random/detail/operators.hpp>
0027 #include <boost/random/normal_distribution.hpp>
0028
0029 namespace boost {
0030 namespace random {
0031
0032 /**
0033  * Instantiations of class template lognormal_distribution model a
0034  * \random_distribution. Such a distribution produces random numbers
0035  * with \f$\displaystyle p(x) = \frac{1}{x s \sqrt{2\pi}} e^{\frac{-\left(\log(x)-m\right)^2}{2s^2}}\f$
0036  * for x > 0.
0037  *
0038  * @xmlwarning
0039  * This distribution has been updated to match the C++ standard.
0040  * Its behavior has changed from the original
0041  * boost::lognormal_distribution.  A backwards compatible
0042  * version is provided in namespace boost.
0043  * @endxmlwarning
0044  */
0045 template<class RealType = double>
0046 class lognormal_distribution
0047 {
0048 public:
0049     typedef typename normal_distribution<RealType>::input_type input_type;
0050     typedef RealType result_type;
0051
0052     class param_type
0053     {
0054     public:
0055
0056         typedef lognormal_distribution distribution_type;
0057
0058         /** Constructs the parameters of a lognormal_distribution. */
0059         explicit param_type(RealType m_arg = RealType(0.0),
0060                             RealType s_arg = RealType(1.0))
0061           : _m(m_arg), _s(s_arg) {}
0062
0063         /** Returns the "m" parameter of the distribution. */
0064         RealType m() const { return _m; }
0065
0066         /** Returns the "s" parameter of the distribution. */
0067         RealType s() const { return _s; }
0068
0069         /** Writes the parameters to a std::ostream. */
0070         BOOST_RANDOM_DETAIL_OSTREAM_OPERATOR(os, param_type, parm)
0071         {
0072             os << parm._m << " " << parm._s;
0073             return os;
0074         }
0075
0076         /** Reads the parameters from a std::istream. */
0077         BOOST_RANDOM_DETAIL_ISTREAM_OPERATOR(is, param_type, parm)
0078         {
0079             is >> parm._m >> std::ws >> parm._s;
0080             return is;
0081         }
0082
0083         /** Returns true if the two sets of parameters are equal. */
0084         BOOST_RANDOM_DETAIL_EQUALITY_OPERATOR(param_type, lhs, rhs)
0085         { return lhs._m == rhs._m && lhs._s == rhs._s; }
0086
0087         /** Returns true if the two sets of parameters are different. */
0088         BOOST_RANDOM_DETAIL_INEQUALITY_OPERATOR(param_type)
0089
0090     private:
0091         RealType _m;
0092         RealType _s;
0093     };
0094
0095     /**
0096      * Constructs a lognormal_distribution. @c m and @c s are the
0097      * parameters of the distribution.
0098      */
0099     explicit lognormal_distribution(RealType m_arg = RealType(0.0),
0100                                     RealType s_arg = RealType(1.0))
0101       : _normal(m_arg, s_arg) {}
0102
0103     /**
0104      * Constructs a lognormal_distribution from its parameters.
0105      */
0106     explicit lognormal_distribution(const param_type& parm)
0107       : _normal(parm.m(), parm.s()) {}
0108
0109     // compiler-generated copy ctor and assignment operator are fine
0110
0111     /** Returns the m parameter of the distribution. */
0112     RealType m() const { return _normal.mean(); }
0113     /** Returns the s parameter of the distribution. */
0114     RealType s() const { return _normal.sigma(); }
0115
0116     /** Returns the smallest value that the distribution can produce. */
0117     RealType min BOOST_PREVENT_MACRO_SUBSTITUTION () const
0118     { return RealType(0); }
0119     /** Returns the largest value that the distribution can produce. */
0120     RealType max BOOST_PREVENT_MACRO_SUBSTITUTION () const
0121     { return (std::numeric_limits<RealType>::infinity)(); }
0122
0123     /** Returns the parameters of the distribution. */
0124     param_type param() const { return param_type(m(), s()); }
0125     /** Sets the parameters of the distribution. */
0126     void param(const param_type& parm)
0127     {
0128         typedef normal_distribution<RealType> normal_type;
0129         typename normal_type::param_type normal_param(parm.m(), parm.s());
0130         _normal.param(normal_param);
0131     }
0132
0133     /**
0134      * Effects: Subsequent uses of the distribution do not depend
0135      * on values produced by any engine prior to invoking reset.
0136      */
0137     void reset() { _normal.reset(); }
0138
0139     /**
0140      * Returns a random variate distributed according to the
0141      * lognormal distribution.
0142      */
0143     template<class Engine>
0144     result_type operator()(Engine& eng)
0145     {
0146         using std::exp;
0147         return exp(_normal(eng));
0148     }
0149
0150     /**
0151      * Returns a random variate distributed according to the
0152      * lognormal distribution with parameters specified by param.
0153      */
0154     template<class Engine>
0155     result_type operator()(Engine& eng, const param_type& parm)
0156     { return lognormal_distribution(parm)(eng); }
0157
0158     /** Writes the distribution to a @c std::ostream. */
0159     BOOST_RANDOM_DETAIL_OSTREAM_OPERATOR(os, lognormal_distribution, ld)
0160     {
0161         os << ld._normal;
0162         return os;
0163     }
0164
0165     /** Reads the distribution from a @c std::istream. */
0166     BOOST_RANDOM_DETAIL_ISTREAM_OPERATOR(is, lognormal_distribution, ld)
0167     {
0168         is >> ld._normal;
0169         return is;
0170     }
0171
0172     /**
0173      * Returns true if the two distributions will produce identical
0174      * sequences of values given equal generators.
0175      */
0176     BOOST_RANDOM_DETAIL_EQUALITY_OPERATOR(lognormal_distribution, lhs, rhs)
0177     { return lhs._normal == rhs._normal; }
0178
0179     /**
0180      * Returns true if the two distributions may produce different
0181      * sequences of values given equal generators.
0182      */
0183     BOOST_RANDOM_DETAIL_INEQUALITY_OPERATOR(lognormal_distribution)
0184
0185 private:
0186     normal_distribution<result_type> _normal;
0187 };
0188
0189 } // namespace random
0190
0191 /// \cond show_deprecated
0192
0193 /**
0194  * Provided for backwards compatibility.  This class is
0195  * deprecated.  It provides the old behavior of lognormal_distribution with
0196  * \f$\displaystyle p(x) = \frac{1}{x \sigma_N \sqrt{2\pi}} e^{\frac{-\left(\log(x)-\mu_N\right)^2}{2\sigma_N^2}}\f$
0197  * for x > 0, where \f$\displaystyle \mu_N = \log\left(\frac{\mu^2}{\sqrt{\sigma^2 + \mu^2}}\right)\f$ and
0198  * \f$\displaystyle \sigma_N = \sqrt{\log\left(1 + \frac{\sigma^2}{\mu^2}\right)}\f$.
0199  */
0200 template<class RealType = double>
0201 class lognormal_distribution
0202 {
0203 public:
0204     typedef typename normal_distribution<RealType>::input_type input_type;
0205     typedef RealType result_type;
0206
0207     lognormal_distribution(RealType mean_arg = RealType(1.0),
0208                            RealType sigma_arg = RealType(1.0))
0209       : _mean(mean_arg), _sigma(sigma_arg)
0210     {
0211         init();
0212     }
0213     RealType mean() const { return _mean; }
0214     RealType sigma() const { return _sigma; }
0215     void reset() { _normal.reset(); }
0216     template<class Engine>
0217     RealType operator()(Engine& eng)
0218     {
0219         using std::exp;
0220         return exp(_normal(eng) * _nsigma + _nmean);
0221     }
0222     BOOST_RANDOM_DETAIL_OSTREAM_OPERATOR(os, lognormal_distribution, ld)
0223     {
0224         os << ld._normal << " " << ld._mean << " " << ld._sigma;
0225         return os;
0226     }
0227     BOOST_RANDOM_DETAIL_ISTREAM_OPERATOR(is, lognormal_distribution, ld)
0228     {
0229         is >> ld._normal >> std::ws >> ld._mean >> std::ws >> ld._sigma;
0230         ld.init();
0231         return is;
0232     }
0233 private:
0234     /// \cond show_private
0235     void init()
0236     {
0237         using std::log;
0238         using std::sqrt;
0239         _nmean = log(_mean*_mean/sqrt(_sigma*_sigma + _mean*_mean));
0240         _nsigma = sqrt(log(_sigma*_sigma/_mean/_mean+result_type(1)));
0241     }
0242     RealType _mean;
0243     RealType _sigma;
0244     RealType _nmean;
0245     RealType _nsigma;
0246     normal_distribution<RealType> _normal;
0247     /// \endcond
0248 };
0249
0250 /// \endcond
0251
0252 } // namespace boost
0253
0254 #endif // BOOST_RANDOM_LOGNORMAL_DISTRIBUTION_HPP