absl/random/beta_distribution.h

0001 // Copyright 2017 The Abseil Authors.
0002 //
0003 // Licensed under the Apache License, Version 2.0 (the "License");
0004 // you may not use this file except in compliance with the License.
0005 // You may obtain a copy of the License at
0006 //
0007 //      https://www.apache.org/licenses/LICENSE-2.0
0008 //
0009 // Unless required by applicable law or agreed to in writing, software
0010 // distributed under the License is distributed on an "AS IS" BASIS,
0011 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
0012 // See the License for the specific language governing permissions and
0013 // limitations under the License.
0014
0015 #ifndef ABSL_RANDOM_BETA_DISTRIBUTION_H_
0016 #define ABSL_RANDOM_BETA_DISTRIBUTION_H_
0017
0018 #include <cassert>
0019 #include <cmath>
0020 #include <istream>
0021 #include <limits>
0022 #include <ostream>
0023 #include <type_traits>
0024
0025 #include "absl/meta/type_traits.h"
0026 #include "absl/random/internal/fast_uniform_bits.h"
0027 #include "absl/random/internal/fastmath.h"
0028 #include "absl/random/internal/generate_real.h"
0029 #include "absl/random/internal/iostream_state_saver.h"
0030
0031 namespace absl {
0032 ABSL_NAMESPACE_BEGIN
0033
0034 // absl::beta_distribution:
0035 // Generate a floating-point variate conforming to a Beta distribution:
0036 //   pdf(x) \propto x^(alpha-1) * (1-x)^(beta-1),
0037 // where the params alpha and beta are both strictly positive real values.
0038 //
0039 // The support is the open interval (0, 1), but the return value might be equal
0040 // to 0 or 1, due to numerical errors when alpha and beta are very different.
0041 //
0042 // Usage note: One usage is that alpha and beta are counts of number of
0043 // successes and failures. When the total number of trials are large, consider
0044 // approximating a beta distribution with a Gaussian distribution with the same
0045 // mean and variance. One could use the skewness, which depends only on the
0046 // smaller of alpha and beta when the number of trials are sufficiently large,
0047 // to quantify how far a beta distribution is from the normal distribution.
0048 template <typename RealType = double>
0049 class beta_distribution {
0050  public:
0051   using result_type = RealType;
0052
0053   class param_type {
0054    public:
0055     using distribution_type = beta_distribution;
0056
0057     explicit param_type(result_type alpha, result_type beta)
0058         : alpha_(alpha), beta_(beta) {
0059       assert(alpha >= 0);
0060       assert(beta >= 0);
0061       assert(alpha <= (std::numeric_limits<result_type>::max)());
0062       assert(beta <= (std::numeric_limits<result_type>::max)());
0063       if (alpha == 0 || beta == 0) {
0064         method_ = DEGENERATE_SMALL;
0065         x_ = (alpha >= beta) ? 1 : 0;
0066         return;
0067       }
0068       // a_ = min(beta, alpha), b_ = max(beta, alpha).
0069       if (beta < alpha) {
0070         inverted_ = true;
0071         a_ = beta;
0072         b_ = alpha;
0073       } else {
0074         inverted_ = false;
0075         a_ = alpha;
0076         b_ = beta;
0077       }
0078       if (a_ <= 1 && b_ >= ThresholdForLargeA()) {
0079         method_ = DEGENERATE_SMALL;
0080         x_ = inverted_ ? result_type(1) : result_type(0);
0081         return;
0082       }
0083       // For threshold values, see also:
0084       // Evaluation of Beta Generation Algorithms, Ying-Chao Hung, et. al.
0085       // February, 2009.
0086       if ((b_ < 1.0 && a_ + b_ <= 1.2) || a_ <= ThresholdForSmallA()) {
0087         // Choose Joehnk over Cheng when it's faster or when Cheng encounters
0088         // numerical issues.
0089         method_ = JOEHNK;
0090         a_ = result_type(1) / alpha_;
0091         b_ = result_type(1) / beta_;
0092         if (std::isinf(a_) || std::isinf(b_)) {
0093           method_ = DEGENERATE_SMALL;
0094           x_ = inverted_ ? result_type(1) : result_type(0);
0095         }
0096         return;
0097       }
0098       if (a_ >= ThresholdForLargeA()) {
0099         method_ = DEGENERATE_LARGE;
0100         // Note: on PPC for long double, evaluating
0101         // `std::numeric_limits::max() / ThresholdForLargeA` results in NaN.
0102         result_type r = a_ / b_;
0103         x_ = (inverted_ ? result_type(1) : r) / (1 + r);
0104         return;
0105       }
0106       x_ = a_ + b_;
0107       log_x_ = std::log(x_);
0108       if (a_ <= 1) {
0109         method_ = CHENG_BA;
0110         y_ = result_type(1) / a_;
0111         gamma_ = a_ + a_;
0112         return;
0113       }
0114       method_ = CHENG_BB;
0115       result_type r = (a_ - 1) / (b_ - 1);
0116       y_ = std::sqrt((1 + r) / (b_ * r * 2 - r + 1));
0117       gamma_ = a_ + result_type(1) / y_;
0118     }
0119
0120     result_type alpha() const { return alpha_; }
0121     result_type beta() const { return beta_; }
0122
0123     friend bool operator==(const param_type& a, const param_type& b) {
0124       return a.alpha_ == b.alpha_ && a.beta_ == b.beta_;
0125     }
0126
0127     friend bool operator!=(const param_type& a, const param_type& b) {
0128       return !(a == b);
0129     }
0130
0131    private:
0132     friend class beta_distribution;
0133
0134 #ifdef _MSC_VER
0135     // MSVC does not have constexpr implementations for std::log and std::exp
0136     // so they are computed at runtime.
0137 #define ABSL_RANDOM_INTERNAL_LOG_EXP_CONSTEXPR
0138 #else
0139 #define ABSL_RANDOM_INTERNAL_LOG_EXP_CONSTEXPR constexpr
0140 #endif
0141
0142     // The threshold for whether std::exp(1/a) is finite.
0143     // Note that this value is quite large, and a smaller a_ is NOT abnormal.
0144     static ABSL_RANDOM_INTERNAL_LOG_EXP_CONSTEXPR result_type
0145     ThresholdForSmallA() {
0146       return result_type(1) /
0147              std::log((std::numeric_limits<result_type>::max)());
0148     }
0149
0150     // The threshold for whether a * std::log(a) is finite.
0151     static ABSL_RANDOM_INTERNAL_LOG_EXP_CONSTEXPR result_type
0152     ThresholdForLargeA() {
0153       return std::exp(
0154           std::log((std::numeric_limits<result_type>::max)()) -
0155           std::log(std::log((std::numeric_limits<result_type>::max)())) -
0156           ThresholdPadding());
0157     }
0158
0159 #undef ABSL_RANDOM_INTERNAL_LOG_EXP_CONSTEXPR
0160
0161     // Pad the threshold for large A for long double on PPC. This is done via a
0162     // template specialization below.
0163     static constexpr result_type ThresholdPadding() { return 0; }
0164
0165     enum Method {
0166       JOEHNK,    // Uses algorithm Joehnk
0167       CHENG_BA,  // Uses algorithm BA in Cheng
0168       CHENG_BB,  // Uses algorithm BB in Cheng
0169
0170       // Note: See also:
0171       //   Hung et al. Evaluation of beta generation algorithms. Communications
0172       //   in Statistics-Simulation and Computation 38.4 (2009): 750-770.
0173       // especially:
0174       //   Zechner, Heinz, and Ernst Stadlober. Generating beta variates via
0175       //   patchwork rejection. Computing 50.1 (1993): 1-18.
0176
0177       DEGENERATE_SMALL,  // a_ is abnormally small.
0178       DEGENERATE_LARGE,  // a_ is abnormally large.
0179     };
0180
0181     result_type alpha_;
0182     result_type beta_;
0183
0184     result_type a_{};  // the smaller of {alpha, beta}, or 1.0/alpha_ in JOEHNK
0185     result_type b_{};  // the larger of {alpha, beta}, or 1.0/beta_ in JOEHNK
0186     result_type x_{};  // alpha + beta, or the result in degenerate cases
0187     result_type log_x_{};  // log(x_)
0188     result_type y_{};      // "beta" in Cheng
0189     result_type gamma_{};  // "gamma" in Cheng
0190
0191     Method method_{};
0192
0193     // Placing this last for optimal alignment.
0194     // Whether alpha_ != a_, i.e. true iff alpha_ > beta_.
0195     bool inverted_{};
0196
0197     static_assert(std::is_floating_point<RealType>::value,
0198                   "Class-template absl::beta_distribution<> must be "
0199                   "parameterized using a floating-point type.");
0200   };
0201
0202   beta_distribution() : beta_distribution(1) {}
0203
0204   explicit beta_distribution(result_type alpha, result_type beta = 1)
0205       : param_(alpha, beta) {}
0206
0207   explicit beta_distribution(const param_type& p) : param_(p) {}
0208
0209   void reset() {}
0210
0211   // Generating functions
0212   template <typename URBG>
0213   result_type operator()(URBG& g) {  // NOLINT(runtime/references)
0214     return (*this)(g, param_);
0215   }
0216
0217   template <typename URBG>
0218   result_type operator()(URBG& g,  // NOLINT(runtime/references)
0219                          const param_type& p);
0220
0221   param_type param() const { return param_; }
0222   void param(const param_type& p) { param_ = p; }
0223
0224   result_type(min)() const { return 0; }
0225   result_type(max)() const { return 1; }
0226
0227   result_type alpha() const { return param_.alpha(); }
0228   result_type beta() const { return param_.beta(); }
0229
0230   friend bool operator==(const beta_distribution& a,
0231                          const beta_distribution& b) {
0232     return a.param_ == b.param_;
0233   }
0234   friend bool operator!=(const beta_distribution& a,
0235                          const beta_distribution& b) {
0236     return a.param_ != b.param_;
0237   }
0238
0239  private:
0240   template <typename URBG>
0241   result_type AlgorithmJoehnk(URBG& g,  // NOLINT(runtime/references)
0242                               const param_type& p);
0243
0244   template <typename URBG>
0245   result_type AlgorithmCheng(URBG& g,  // NOLINT(runtime/references)
0246                              const param_type& p);
0247
0248   template <typename URBG>
0249   result_type DegenerateCase(URBG& g,  // NOLINT(runtime/references)
0250                              const param_type& p) {
0251     if (p.method_ == param_type::DEGENERATE_SMALL && p.alpha_ == p.beta_) {
0252       // Returns 0 or 1 with equal probability.
0253       random_internal::FastUniformBits<uint8_t> fast_u8;
0254       return static_cast<result_type>((fast_u8(g) & 0x10) !=
0255                                       0);  // pick any single bit.
0256     }
0257     return p.x_;
0258   }
0259
0260   param_type param_;
0261   random_internal::FastUniformBits<uint64_t> fast_u64_;
0262 };
0263
0264 #if defined(__powerpc64__) || defined(__PPC64__) || defined(__powerpc__) || \
0265     defined(__ppc__) || defined(__PPC__)
0266 // PPC needs a more stringent boundary for long double.
0267 template <>
0268 constexpr long double
0269 beta_distribution<long double>::param_type::ThresholdPadding() {
0270   return 10;
0271 }
0272 #endif
0273
0274 template <typename RealType>
0275 template <typename URBG>
0276 typename beta_distribution<RealType>::result_type
0277 beta_distribution<RealType>::AlgorithmJoehnk(
0278     URBG& g,  // NOLINT(runtime/references)
0279     const param_type& p) {
0280   using random_internal::GeneratePositiveTag;
0281   using random_internal::GenerateRealFromBits;
0282   using real_type =
0283       absl::conditional_t<std::is_same<RealType, float>::value, float, double>;
0284
0285   // Based on Joehnk, M. D. Erzeugung von betaverteilten und gammaverteilten
0286   // Zufallszahlen. Metrika 8.1 (1964): 5-15.
0287   // This method is described in Knuth, Vol 2 (Third Edition), pp 134.
0288
0289   result_type u, v, x, y, z;
0290   for (;;) {
0291     u = GenerateRealFromBits<real_type, GeneratePositiveTag, false>(
0292         fast_u64_(g));
0293     v = GenerateRealFromBits<real_type, GeneratePositiveTag, false>(
0294         fast_u64_(g));
0295
0296     // Direct method. std::pow is slow for float, so rely on the optimizer to
0297     // remove the std::pow() path for that case.
0298     if (!std::is_same<float, result_type>::value) {
0299       x = std::pow(u, p.a_);
0300       y = std::pow(v, p.b_);
0301       z = x + y;
0302       if (z > 1) {
0303         // Reject if and only if `x + y > 1.0`
0304         continue;
0305       }
0306       if (z > 0) {
0307         // When both alpha and beta are small, x and y are both close to 0, so
0308         // divide by (x+y) directly may result in nan.
0309         return x / z;
0310       }
0311     }
0312
0313     // Log transform.
0314     // x = log( pow(u, p.a_) ), y = log( pow(v, p.b_) )
0315     // since u, v <= 1.0,  x, y < 0.
0316     x = std::log(u) * p.a_;
0317     y = std::log(v) * p.b_;
0318     if (!std::isfinite(x) || !std::isfinite(y)) {
0319       continue;
0320     }
0321     // z = log( pow(u, a) + pow(v, b) )
0322     z = x > y ? (x + std::log(1 + std::exp(y - x)))
0323               : (y + std::log(1 + std::exp(x - y)));
0324     // Reject iff log(x+y) > 0.
0325     if (z > 0) {
0326       continue;
0327     }
0328     return std::exp(x - z);
0329   }
0330 }
0331
0332 template <typename RealType>
0333 template <typename URBG>
0334 typename beta_distribution<RealType>::result_type
0335 beta_distribution<RealType>::AlgorithmCheng(
0336     URBG& g,  // NOLINT(runtime/references)
0337     const param_type& p) {
0338   using random_internal::GeneratePositiveTag;
0339   using random_internal::GenerateRealFromBits;
0340   using real_type =
0341       absl::conditional_t<std::is_same<RealType, float>::value, float, double>;
0342
0343   // Based on Cheng, Russell CH. Generating beta variates with nonintegral
0344   // shape parameters. Communications of the ACM 21.4 (1978): 317-322.
0345   // (https://dl.acm.org/citation.cfm?id=359482).
0346   static constexpr result_type kLogFour =
0347       result_type(1.3862943611198906188344642429163531361);  // log(4)
0348   static constexpr result_type kS =
0349       result_type(2.6094379124341003746007593332261876);  // 1+log(5)
0350
0351   const bool use_algorithm_ba = (p.method_ == param_type::CHENG_BA);
0352   result_type u1, u2, v, w, z, r, s, t, bw_inv, lhs;
0353   for (;;) {
0354     u1 = GenerateRealFromBits<real_type, GeneratePositiveTag, false>(
0355         fast_u64_(g));
0356     u2 = GenerateRealFromBits<real_type, GeneratePositiveTag, false>(
0357         fast_u64_(g));
0358     v = p.y_ * std::log(u1 / (1 - u1));
0359     w = p.a_ * std::exp(v);
0360     bw_inv = result_type(1) / (p.b_ + w);
0361     r = p.gamma_ * v - kLogFour;
0362     s = p.a_ + r - w;
0363     z = u1 * u1 * u2;
0364     if (!use_algorithm_ba && s + kS >= 5 * z) {
0365       break;
0366     }
0367     t = std::log(z);
0368     if (!use_algorithm_ba && s >= t) {
0369       break;
0370     }
0371     lhs = p.x_ * (p.log_x_ + std::log(bw_inv)) + r;
0372     if (lhs >= t) {
0373       break;
0374     }
0375   }
0376   return p.inverted_ ? (1 - w * bw_inv) : w * bw_inv;
0377 }
0378
0379 template <typename RealType>
0380 template <typename URBG>
0381 typename beta_distribution<RealType>::result_type
0382 beta_distribution<RealType>::operator()(URBG& g,  // NOLINT(runtime/references)
0383                                         const param_type& p) {
0384   switch (p.method_) {
0385     case param_type::JOEHNK:
0386       return AlgorithmJoehnk(g, p);
0387     case param_type::CHENG_BA:
0388       ABSL_FALLTHROUGH_INTENDED;
0389     case param_type::CHENG_BB:
0390       return AlgorithmCheng(g, p);
0391     default:
0392       return DegenerateCase(g, p);
0393   }
0394 }
0395
0396 template <typename CharT, typename Traits, typename RealType>
0397 std::basic_ostream<CharT, Traits>& operator<<(
0398     std::basic_ostream<CharT, Traits>& os,  // NOLINT(runtime/references)
0399     const beta_distribution<RealType>& x) {
0400   auto saver = random_internal::make_ostream_state_saver(os);
0401   os.precision(random_internal::stream_precision_helper<RealType>::kPrecision);
0402   os << x.alpha() << os.fill() << x.beta();
0403   return os;
0404 }
0405
0406 template <typename CharT, typename Traits, typename RealType>
0407 std::basic_istream<CharT, Traits>& operator>>(
0408     std::basic_istream<CharT, Traits>& is,  // NOLINT(runtime/references)
0409     beta_distribution<RealType>& x) {       // NOLINT(runtime/references)
0410   using result_type = typename beta_distribution<RealType>::result_type;
0411   using param_type = typename beta_distribution<RealType>::param_type;
0412   result_type alpha, beta;
0413
0414   auto saver = random_internal::make_istream_state_saver(is);
0415   alpha = random_internal::read_floating_point<result_type>(is);
0416   if (is.fail()) return is;
0417   beta = random_internal::read_floating_point<result_type>(is);
0418   if (!is.fail()) {
0419     x.param(param_type(alpha, beta));
0420   }
0421   return is;
0422 }
0423
0424 ABSL_NAMESPACE_END
0425 }  // namespace absl
0426
0427 #endif  // ABSL_RANDOM_BETA_DISTRIBUTION_H_