boost/random/beta_distribution.hpp

0001 /* boost random/beta_distribution.hpp header file
0002  *
0003  * Copyright Steven Watanabe 2014
0004  * Distributed under the Boost Software License, Version 1.0. (See
0005  * accompanying file LICENSE_1_0.txt or copy at
0006  * http://www.boost.org/LICENSE_1_0.txt)
0007  *
0008  * See http://www.boost.org for most recent version including documentation.
0009  *
0010  * $Id$
0011  */
0012
0013 #ifndef BOOST_RANDOM_BETA_DISTRIBUTION_HPP
0014 #define BOOST_RANDOM_BETA_DISTRIBUTION_HPP
0015
0016 #include <cassert>
0017 #include <istream>
0018 #include <iosfwd>
0019 #include <boost/random/detail/operators.hpp>
0020 #include <boost/random/gamma_distribution.hpp>
0021
0022 namespace boost {
0023 namespace random {
0024
0025 /**
0026  * The beta distribution is a real-valued distribution which produces
0027  * values in the range [0, 1].  It has two parameters, alpha and beta.
0028  *
0029  * It has \f$\displaystyle p(x) = \frac{x^{\alpha-1}(1-x)^{\beta-1}}{B(\alpha, \beta)}\f$.
0030  */
0031 template<class RealType = double>
0032 class beta_distribution {
0033 public:
0034     typedef RealType result_type;
0035     typedef RealType input_type;
0036
0037     class param_type {
0038     public:
0039         typedef beta_distribution distribution_type;
0040
0041         /**
0042          * Constructs a @c param_type from the "alpha" and "beta" parameters
0043          * of the distribution.
0044          *
0045          * Requires: alpha > 0, beta > 0
0046          */
0047         explicit param_type(RealType alpha_arg = RealType(1.0),
0048                             RealType beta_arg = RealType(1.0))
0049           : _alpha(alpha_arg), _beta(beta_arg)
0050         {
0051             assert(alpha_arg > 0);
0052             assert(beta_arg > 0);
0053         }
0054
0055         /** Returns the "alpha" parameter of the distribtuion. */
0056         RealType alpha() const { return _alpha; }
0057         /** Returns the "beta" parameter of the distribution. */
0058         RealType beta() const { return _beta; }
0059
0060         /** Writes a @c param_type to a @c std::ostream. */
0061         BOOST_RANDOM_DETAIL_OSTREAM_OPERATOR(os, param_type, parm)
0062         { os << parm._alpha << ' ' << parm._beta; return os; }
0063
0064         /** Reads a @c param_type from a @c std::istream. */
0065         BOOST_RANDOM_DETAIL_ISTREAM_OPERATOR(is, param_type, parm)
0066         { is >> parm._alpha >> std::ws >> parm._beta; return is; }
0067
0068         /** Returns true if the two sets of parameters are the same. */
0069         BOOST_RANDOM_DETAIL_EQUALITY_OPERATOR(param_type, lhs, rhs)
0070         { return lhs._alpha == rhs._alpha && lhs._beta == rhs._beta; }
0071
0072         /** Returns true if the two sets of parameters are the different. */
0073         BOOST_RANDOM_DETAIL_INEQUALITY_OPERATOR(param_type)
0074
0075     private:
0076         RealType _alpha;
0077         RealType _beta;
0078     };
0079
0080     /**
0081      * Constructs an @c beta_distribution from its "alpha" and "beta" parameters.
0082      *
0083      * Requires: alpha > 0, beta > 0
0084      */
0085     explicit beta_distribution(RealType alpha_arg = RealType(1.0),
0086                                RealType beta_arg = RealType(1.0))
0087       : _alpha(alpha_arg), _beta(beta_arg)
0088     {
0089         assert(alpha_arg > 0);
0090         assert(beta_arg > 0);
0091     }
0092     /** Constructs an @c beta_distribution from its parameters. */
0093     explicit beta_distribution(const param_type& parm)
0094       : _alpha(parm.alpha()), _beta(parm.beta())
0095     {}
0096
0097     /**
0098      * Returns a random variate distributed according to the
0099      * beta distribution.
0100      */
0101     template<class URNG>
0102     RealType operator()(URNG& urng) const
0103     {
0104         RealType a = gamma_distribution<RealType>(_alpha, RealType(1.0))(urng);
0105         RealType b = gamma_distribution<RealType>(_beta, RealType(1.0))(urng);
0106         return a / (a + b);
0107     }
0108
0109     /**
0110      * Returns a random variate distributed accordint to the beta
0111      * distribution with parameters specified by @c param.
0112      */
0113     template<class URNG>
0114     RealType operator()(URNG& urng, const param_type& parm) const
0115     {
0116         return beta_distribution(parm)(urng);
0117     }
0118
0119     /** Returns the "alpha" parameter of the distribution. */
0120     RealType alpha() const { return _alpha; }
0121     /** Returns the "beta" parameter of the distribution. */
0122     RealType beta() const { return _beta; }
0123
0124     /** Returns the smallest value that the distribution can produce. */
0125     RealType min BOOST_PREVENT_MACRO_SUBSTITUTION () const
0126     { return RealType(0.0); }
0127     /** Returns the largest value that the distribution can produce. */
0128     RealType max BOOST_PREVENT_MACRO_SUBSTITUTION () const
0129     { return RealType(1.0); }
0130
0131     /** Returns the parameters of the distribution. */
0132     param_type param() const { return param_type(_alpha, _beta); }
0133     /** Sets the parameters of the distribution. */
0134     void param(const param_type& parm)
0135     {
0136         _alpha = parm.alpha();
0137         _beta = parm.beta();
0138     }
0139
0140     /**
0141      * Effects: Subsequent uses of the distribution do not depend
0142      * on values produced by any engine prior to invoking reset.
0143      */
0144     void reset() { }
0145
0146     /** Writes an @c beta_distribution to a @c std::ostream. */
0147     BOOST_RANDOM_DETAIL_OSTREAM_OPERATOR(os, beta_distribution, wd)
0148     {
0149         os << wd.param();
0150         return os;
0151     }
0152
0153     /** Reads an @c beta_distribution from a @c std::istream. */
0154     BOOST_RANDOM_DETAIL_ISTREAM_OPERATOR(is, beta_distribution, wd)
0155     {
0156         param_type parm;
0157         if(is >> parm) {
0158             wd.param(parm);
0159         }
0160         return is;
0161     }
0162
0163     /**
0164      * Returns true if the two instances of @c beta_distribution will
0165      * return identical sequences of values given equal generators.
0166      */
0167     BOOST_RANDOM_DETAIL_EQUALITY_OPERATOR(beta_distribution, lhs, rhs)
0168     { return lhs._alpha == rhs._alpha && lhs._beta == rhs._beta; }
0169
0170     /**
0171      * Returns true if the two instances of @c beta_distribution will
0172      * return different sequences of values given equal generators.
0173      */
0174     BOOST_RANDOM_DETAIL_INEQUALITY_OPERATOR(beta_distribution)
0175
0176 private:
0177     RealType _alpha;
0178     RealType _beta;
0179 };
0180
0181 } // namespace random
0182 } // namespace boost
0183
0184 #endif // BOOST_RANDOM_BETA_DISTRIBUTION_HPP