1/* boost random/beta_distribution.hpp header file
2 *
3 * Copyright Steven Watanabe 2014
4 * Distributed under the Boost Software License, Version 1.0. (See
5 * accompanying file LICENSE_1_0.txt or copy at
6 * http://www.boost.org/LICENSE_1_0.txt)
7 *
8 * See http://www.boost.org for most recent version including documentation.
9 *
10 * $Id$
11 */
12
13#ifndef BOOST_RANDOM_BETA_DISTRIBUTION_HPP
14#define BOOST_RANDOM_BETA_DISTRIBUTION_HPP
15
16#include <cassert>
17#include <istream>
18#include <iosfwd>
19#include <boost/random/detail/operators.hpp>
20#include <boost/random/gamma_distribution.hpp>
21
22namespace boost {
23namespace random {
24
25/**
26 * The beta distribution is a real-valued distribution which produces
27 * values in the range [0, 1]. It has two parameters, alpha and beta.
28 *
29 * It has \f$\displaystyle p(x) = \frac{x^{\alpha-1}(1-x)^{\beta-1}}{B(\alpha, \beta)}\f$.
30 */
31template<class RealType = double>
32class beta_distribution {
33public:
34 typedef RealType result_type;
35 typedef RealType input_type;
36
37 class param_type {
38 public:
39 typedef beta_distribution distribution_type;
40
41 /**
42 * Constructs a @c param_type from the "alpha" and "beta" parameters
43 * of the distribution.
44 *
45 * Requires: alpha > 0, beta > 0
46 */
47 explicit param_type(RealType alpha_arg = RealType(1.0),
48 RealType beta_arg = RealType(1.0))
49 : _alpha(alpha_arg), _beta(beta_arg)
50 {
51 assert(alpha_arg > 0);
52 assert(beta_arg > 0);
53 }
54
55 /** Returns the "alpha" parameter of the distribtuion. */
56 RealType alpha() const { return _alpha; }
57 /** Returns the "beta" parameter of the distribution. */
58 RealType beta() const { return _beta; }
59
60 /** Writes a @c param_type to a @c std::ostream. */
61 BOOST_RANDOM_DETAIL_OSTREAM_OPERATOR(os, param_type, parm)
62 { os << parm._alpha << ' ' << parm._beta; return os; }
63
64 /** Reads a @c param_type from a @c std::istream. */
65 BOOST_RANDOM_DETAIL_ISTREAM_OPERATOR(is, param_type, parm)
66 { is >> parm._alpha >> std::ws >> parm._beta; return is; }
67
68 /** Returns true if the two sets of parameters are the same. */
69 BOOST_RANDOM_DETAIL_EQUALITY_OPERATOR(param_type, lhs, rhs)
70 { return lhs._alpha == rhs._alpha && lhs._beta == rhs._beta; }
71
72 /** Returns true if the two sets of parameters are the different. */
73 BOOST_RANDOM_DETAIL_INEQUALITY_OPERATOR(param_type)
74
75 private:
76 RealType _alpha;
77 RealType _beta;
78 };
79
80 /**
81 * Constructs an @c beta_distribution from its "alpha" and "beta" parameters.
82 *
83 * Requires: alpha > 0, beta > 0
84 */
85 explicit beta_distribution(RealType alpha_arg = RealType(1.0),
86 RealType beta_arg = RealType(1.0))
87 : _alpha(alpha_arg), _beta(beta_arg)
88 {
89 assert(alpha_arg > 0);
90 assert(beta_arg > 0);
91 }
92 /** Constructs an @c beta_distribution from its parameters. */
93 explicit beta_distribution(const param_type& parm)
94 : _alpha(parm.alpha()), _beta(parm.beta())
95 {}
96
97 /**
98 * Returns a random variate distributed according to the
99 * beta distribution.
100 */
101 template<class URNG>
102 RealType operator()(URNG& urng) const
103 {
104 RealType a = gamma_distribution<RealType>(_alpha, RealType(1.0))(urng);
105 RealType b = gamma_distribution<RealType>(_beta, RealType(1.0))(urng);
106 return a / (a + b);
107 }
108
109 /**
110 * Returns a random variate distributed accordint to the beta
111 * distribution with parameters specified by @c param.
112 */
113 template<class URNG>
114 RealType operator()(URNG& urng, const param_type& parm) const
115 {
116 return beta_distribution(parm)(urng);
117 }
118
119 /** Returns the "alpha" parameter of the distribution. */
120 RealType alpha() const { return _alpha; }
121 /** Returns the "beta" parameter of the distribution. */
122 RealType beta() const { return _beta; }
123
124 /** Returns the smallest value that the distribution can produce. */
125 RealType min BOOST_PREVENT_MACRO_SUBSTITUTION () const
126 { return RealType(0.0); }
127 /** Returns the largest value that the distribution can produce. */
128 RealType max BOOST_PREVENT_MACRO_SUBSTITUTION () const
129 { return RealType(1.0); }
130
131 /** Returns the parameters of the distribution. */
132 param_type param() const { return param_type(_alpha, _beta); }
133 /** Sets the parameters of the distribution. */
134 void param(const param_type& parm)
135 {
136 _alpha = parm.alpha();
137 _beta = parm.beta();
138 }
139
140 /**
141 * Effects: Subsequent uses of the distribution do not depend
142 * on values produced by any engine prior to invoking reset.
143 */
144 void reset() { }
145
146 /** Writes an @c beta_distribution to a @c std::ostream. */
147 BOOST_RANDOM_DETAIL_OSTREAM_OPERATOR(os, beta_distribution, wd)
148 {
149 os << wd.param();
150 return os;
151 }
152
153 /** Reads an @c beta_distribution from a @c std::istream. */
154 BOOST_RANDOM_DETAIL_ISTREAM_OPERATOR(is, beta_distribution, wd)
155 {
156 param_type parm;
157 if(is >> parm) {
158 wd.param(parm);
159 }
160 return is;
161 }
162
163 /**
164 * Returns true if the two instances of @c beta_distribution will
165 * return identical sequences of values given equal generators.
166 */
167 BOOST_RANDOM_DETAIL_EQUALITY_OPERATOR(beta_distribution, lhs, rhs)
168 { return lhs._alpha == rhs._alpha && lhs._beta == rhs._beta; }
169
170 /**
171 * Returns true if the two instances of @c beta_distribution will
172 * return different sequences of values given equal generators.
173 */
174 BOOST_RANDOM_DETAIL_INEQUALITY_OPERATOR(beta_distribution)
175
176private:
177 RealType _alpha;
178 RealType _beta;
179};
180
181} // namespace random
182} // namespace boost
183
184#endif // BOOST_RANDOM_BETA_DISTRIBUTION_HPP
185