| // Copyright 2017 The Abseil Authors. |
| // |
| // Licensed under the Apache License, Version 2.0 (the "License"); |
| // you may not use this file except in compliance with the License. |
| // You may obtain a copy of the License at |
| // |
| // https://www.apache.org/licenses/LICENSE-2.0 |
| // |
| // Unless required by applicable law or agreed to in writing, software |
| // distributed under the License is distributed on an "AS IS" BASIS, |
| // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. |
| // See the License for the specific language governing permissions and |
| // limitations under the License. |
| |
| #ifndef ABSL_RANDOM_BETA_DISTRIBUTION_H_ |
| #define ABSL_RANDOM_BETA_DISTRIBUTION_H_ |
| |
| #include <cassert> |
| #include <cmath> |
| #include <istream> |
| #include <limits> |
| #include <ostream> |
| #include <type_traits> |
| |
| #include "absl/random/internal/distribution_impl.h" |
| #include "absl/random/internal/fast_uniform_bits.h" |
| #include "absl/random/internal/fastmath.h" |
| #include "absl/random/internal/iostream_state_saver.h" |
| |
| namespace absl { |
| |
| // absl::beta_distribution: |
| // Generate a floating-point variate conforming to a Beta distribution: |
| // pdf(x) \propto x^(alpha-1) * (1-x)^(beta-1), |
| // where the params alpha and beta are both strictly positive real values. |
| // |
| // The support is the open interval (0, 1), but the return value might be equal |
| // to 0 or 1, due to numerical errors when alpha and beta are very different. |
| // |
| // Usage note: One usage is that alpha and beta are counts of number of |
| // successes and failures. When the total number of trials are large, consider |
| // approximating a beta distribution with a Gaussian distribution with the same |
| // mean and variance. One could use the skewness, which depends only on the |
| // smaller of alpha and beta when the number of trials are sufficiently large, |
| // to quantify how far a beta distribution is from the normal distribution. |
| template <typename RealType = double> |
| class beta_distribution { |
| public: |
| using result_type = RealType; |
| |
| class param_type { |
| public: |
| using distribution_type = beta_distribution; |
| |
| explicit param_type(result_type alpha, result_type beta) |
| : alpha_(alpha), beta_(beta) { |
| assert(alpha >= 0); |
| assert(beta >= 0); |
| assert(alpha <= (std::numeric_limits<result_type>::max)()); |
| assert(beta <= (std::numeric_limits<result_type>::max)()); |
| if (alpha == 0 || beta == 0) { |
| method_ = DEGENERATE_SMALL; |
| x_ = (alpha >= beta) ? 1 : 0; |
| return; |
| } |
| // a_ = min(beta, alpha), b_ = max(beta, alpha). |
| if (beta < alpha) { |
| inverted_ = true; |
| a_ = beta; |
| b_ = alpha; |
| } else { |
| inverted_ = false; |
| a_ = alpha; |
| b_ = beta; |
| } |
| if (a_ <= 1 && b_ >= ThresholdForLargeA()) { |
| method_ = DEGENERATE_SMALL; |
| x_ = inverted_ ? result_type(1) : result_type(0); |
| return; |
| } |
| // For threshold values, see also: |
| // Evaluation of Beta Generation Algorithms, Ying-Chao Hung, et. al. |
| // February, 2009. |
| if ((b_ < 1.0 && a_ + b_ <= 1.2) || a_ <= ThresholdForSmallA()) { |
| // Choose Joehnk over Cheng when it's faster or when Cheng encounters |
| // numerical issues. |
| method_ = JOEHNK; |
| a_ = result_type(1) / alpha_; |
| b_ = result_type(1) / beta_; |
| if (std::isinf(a_) || std::isinf(b_)) { |
| method_ = DEGENERATE_SMALL; |
| x_ = inverted_ ? result_type(1) : result_type(0); |
| } |
| return; |
| } |
| if (a_ >= ThresholdForLargeA()) { |
| method_ = DEGENERATE_LARGE; |
| // Note: on PPC for long double, evaluating |
| // `std::numeric_limits::max() / ThresholdForLargeA` results in NaN. |
| result_type r = a_ / b_; |
| x_ = (inverted_ ? result_type(1) : r) / (1 + r); |
| return; |
| } |
| x_ = a_ + b_; |
| log_x_ = std::log(x_); |
| if (a_ <= 1) { |
| method_ = CHENG_BA; |
| y_ = result_type(1) / a_; |
| gamma_ = a_ + a_; |
| return; |
| } |
| method_ = CHENG_BB; |
| result_type r = (a_ - 1) / (b_ - 1); |
| y_ = std::sqrt((1 + r) / (b_ * r * 2 - r + 1)); |
| gamma_ = a_ + result_type(1) / y_; |
| } |
| |
| result_type alpha() const { return alpha_; } |
| result_type beta() const { return beta_; } |
| |
| friend bool operator==(const param_type& a, const param_type& b) { |
| return a.alpha_ == b.alpha_ && a.beta_ == b.beta_; |
| } |
| |
| friend bool operator!=(const param_type& a, const param_type& b) { |
| return !(a == b); |
| } |
| |
| private: |
| friend class beta_distribution; |
| |
| #ifdef COMPILER_MSVC |
| // MSVC does not have constexpr implementations for std::log and std::exp |
| // so they are computed at runtime. |
| #define ABSL_RANDOM_INTERNAL_LOG_EXP_CONSTEXPR |
| #else |
| #define ABSL_RANDOM_INTERNAL_LOG_EXP_CONSTEXPR constexpr |
| #endif |
| |
| // The threshold for whether std::exp(1/a) is finite. |
| // Note that this value is quite large, and a smaller a_ is NOT abnormal. |
| static ABSL_RANDOM_INTERNAL_LOG_EXP_CONSTEXPR result_type |
| ThresholdForSmallA() { |
| return result_type(1) / |
| std::log((std::numeric_limits<result_type>::max)()); |
| } |
| |
| // The threshold for whether a * std::log(a) is finite. |
| static ABSL_RANDOM_INTERNAL_LOG_EXP_CONSTEXPR result_type |
| ThresholdForLargeA() { |
| return std::exp( |
| std::log((std::numeric_limits<result_type>::max)()) - |
| std::log(std::log((std::numeric_limits<result_type>::max)())) - |
| ThresholdPadding()); |
| } |
| |
| #undef ABSL_RANDOM_INTERNAL_LOG_EXP_CONSTEXPR |
| |
| // Pad the threshold for large A for long double on PPC. This is done via a |
| // template specialization below. |
| static constexpr result_type ThresholdPadding() { return 0; } |
| |
| enum Method { |
| JOEHNK, // Uses algorithm Joehnk |
| CHENG_BA, // Uses algorithm BA in Cheng |
| CHENG_BB, // Uses algorithm BB in Cheng |
| |
| // Note: See also: |
| // Hung et al. Evaluation of beta generation algorithms. Communications |
| // in Statistics-Simulation and Computation 38.4 (2009): 750-770. |
| // especially: |
| // Zechner, Heinz, and Ernst Stadlober. Generating beta variates via |
| // patchwork rejection. Computing 50.1 (1993): 1-18. |
| |
| DEGENERATE_SMALL, // a_ is abnormally small. |
| DEGENERATE_LARGE, // a_ is abnormally large. |
| }; |
| |
| result_type alpha_; |
| result_type beta_; |
| |
| result_type a_; // the smaller of {alpha, beta}, or 1.0/alpha_ in JOEHNK |
| result_type b_; // the larger of {alpha, beta}, or 1.0/beta_ in JOEHNK |
| result_type x_; // alpha + beta, or the result in degenerate cases |
| result_type log_x_; // log(x_) |
| result_type y_; // "beta" in Cheng |
| result_type gamma_; // "gamma" in Cheng |
| |
| Method method_; |
| |
| // Placing this last for optimal alignment. |
| // Whether alpha_ != a_, i.e. true iff alpha_ > beta_. |
| bool inverted_; |
| |
| static_assert(std::is_floating_point<RealType>::value, |
| "Class-template absl::beta_distribution<> must be " |
| "parameterized using a floating-point type."); |
| }; |
| |
| beta_distribution() : beta_distribution(1) {} |
| |
| explicit beta_distribution(result_type alpha, result_type beta = 1) |
| : param_(alpha, beta) {} |
| |
| explicit beta_distribution(const param_type& p) : param_(p) {} |
| |
| void reset() {} |
| |
| // Generating functions |
| template <typename URBG> |
| result_type operator()(URBG& g) { // NOLINT(runtime/references) |
| return (*this)(g, param_); |
| } |
| |
| template <typename URBG> |
| result_type operator()(URBG& g, // NOLINT(runtime/references) |
| const param_type& p); |
| |
| param_type param() const { return param_; } |
| void param(const param_type& p) { param_ = p; } |
| |
| result_type(min)() const { return 0; } |
| result_type(max)() const { return 1; } |
| |
| result_type alpha() const { return param_.alpha(); } |
| result_type beta() const { return param_.beta(); } |
| |
| friend bool operator==(const beta_distribution& a, |
| const beta_distribution& b) { |
| return a.param_ == b.param_; |
| } |
| friend bool operator!=(const beta_distribution& a, |
| const beta_distribution& b) { |
| return a.param_ != b.param_; |
| } |
| |
| private: |
| template <typename URBG> |
| result_type AlgorithmJoehnk(URBG& g, // NOLINT(runtime/references) |
| const param_type& p); |
| |
| template <typename URBG> |
| result_type AlgorithmCheng(URBG& g, // NOLINT(runtime/references) |
| const param_type& p); |
| |
| template <typename URBG> |
| result_type DegenerateCase(URBG& g, // NOLINT(runtime/references) |
| const param_type& p) { |
| if (p.method_ == param_type::DEGENERATE_SMALL && p.alpha_ == p.beta_) { |
| // Returns 0 or 1 with equal probability. |
| random_internal::FastUniformBits<uint8_t> fast_u8; |
| return static_cast<result_type>((fast_u8(g) & 0x10) != |
| 0); // pick any single bit. |
| } |
| return p.x_; |
| } |
| |
| param_type param_; |
| random_internal::FastUniformBits<uint64_t> fast_u64_; |
| }; |
| |
| #if defined(__powerpc64__) || defined(__PPC64__) || defined(__powerpc__) || \ |
| defined(__ppc__) || defined(__PPC__) |
| // PPC needs a more stringent boundary for long double. |
| template <> |
| constexpr long double |
| beta_distribution<long double>::param_type::ThresholdPadding() { |
| return 10; |
| } |
| #endif |
| |
| template <typename RealType> |
| template <typename URBG> |
| typename beta_distribution<RealType>::result_type |
| beta_distribution<RealType>::AlgorithmJoehnk( |
| URBG& g, // NOLINT(runtime/references) |
| const param_type& p) { |
| // Based on Joehnk, M. D. Erzeugung von betaverteilten und gammaverteilten |
| // Zufallszahlen. Metrika 8.1 (1964): 5-15. |
| // This method is described in Knuth, Vol 2 (Third Edition), pp 134. |
| using RandU64ToReal = typename random_internal::RandU64ToReal<result_type>; |
| using random_internal::PositiveValueT; |
| result_type u, v, x, y, z; |
| for (;;) { |
| u = RandU64ToReal::template Value<PositiveValueT, false>(fast_u64_(g)); |
| v = RandU64ToReal::template Value<PositiveValueT, false>(fast_u64_(g)); |
| |
| // Direct method. std::pow is slow for float, so rely on the optimizer to |
| // remove the std::pow() path for that case. |
| if (!std::is_same<float, result_type>::value) { |
| x = std::pow(u, p.a_); |
| y = std::pow(v, p.b_); |
| z = x + y; |
| if (z > 1) { |
| // Reject if and only if `x + y > 1.0` |
| continue; |
| } |
| if (z > 0) { |
| // When both alpha and beta are small, x and y are both close to 0, so |
| // divide by (x+y) directly may result in nan. |
| return x / z; |
| } |
| } |
| |
| // Log transform. |
| // x = log( pow(u, p.a_) ), y = log( pow(v, p.b_) ) |
| // since u, v <= 1.0, x, y < 0. |
| x = std::log(u) * p.a_; |
| y = std::log(v) * p.b_; |
| if (!std::isfinite(x) || !std::isfinite(y)) { |
| continue; |
| } |
| // z = log( pow(u, a) + pow(v, b) ) |
| z = x > y ? (x + std::log(1 + std::exp(y - x))) |
| : (y + std::log(1 + std::exp(x - y))); |
| // Reject iff log(x+y) > 0. |
| if (z > 0) { |
| continue; |
| } |
| return std::exp(x - z); |
| } |
| } |
| |
| template <typename RealType> |
| template <typename URBG> |
| typename beta_distribution<RealType>::result_type |
| beta_distribution<RealType>::AlgorithmCheng( |
| URBG& g, // NOLINT(runtime/references) |
| const param_type& p) { |
| // Based on Cheng, Russell CH. Generating beta variates with nonintegral |
| // shape parameters. Communications of the ACM 21.4 (1978): 317-322. |
| // (https://dl.acm.org/citation.cfm?id=359482). |
| using RandU64ToReal = typename random_internal::RandU64ToReal<result_type>; |
| using random_internal::PositiveValueT; |
| |
| static constexpr result_type kLogFour = |
| result_type(1.3862943611198906188344642429163531361); // log(4) |
| static constexpr result_type kS = |
| result_type(2.6094379124341003746007593332261876); // 1+log(5) |
| |
| const bool use_algorithm_ba = (p.method_ == param_type::CHENG_BA); |
| result_type u1, u2, v, w, z, r, s, t, bw_inv, lhs; |
| for (;;) { |
| u1 = RandU64ToReal::template Value<PositiveValueT, false>(fast_u64_(g)); |
| u2 = RandU64ToReal::template Value<PositiveValueT, false>(fast_u64_(g)); |
| v = p.y_ * std::log(u1 / (1 - u1)); |
| w = p.a_ * std::exp(v); |
| bw_inv = result_type(1) / (p.b_ + w); |
| r = p.gamma_ * v - kLogFour; |
| s = p.a_ + r - w; |
| z = u1 * u1 * u2; |
| if (!use_algorithm_ba && s + kS >= 5 * z) { |
| break; |
| } |
| t = std::log(z); |
| if (!use_algorithm_ba && s >= t) { |
| break; |
| } |
| lhs = p.x_ * (p.log_x_ + std::log(bw_inv)) + r; |
| if (lhs >= t) { |
| break; |
| } |
| } |
| return p.inverted_ ? (1 - w * bw_inv) : w * bw_inv; |
| } |
| |
| template <typename RealType> |
| template <typename URBG> |
| typename beta_distribution<RealType>::result_type |
| beta_distribution<RealType>::operator()(URBG& g, // NOLINT(runtime/references) |
| const param_type& p) { |
| switch (p.method_) { |
| case param_type::JOEHNK: |
| return AlgorithmJoehnk(g, p); |
| case param_type::CHENG_BA: |
| ABSL_FALLTHROUGH_INTENDED; |
| case param_type::CHENG_BB: |
| return AlgorithmCheng(g, p); |
| default: |
| return DegenerateCase(g, p); |
| } |
| } |
| |
| template <typename CharT, typename Traits, typename RealType> |
| std::basic_ostream<CharT, Traits>& operator<<( |
| std::basic_ostream<CharT, Traits>& os, // NOLINT(runtime/references) |
| const beta_distribution<RealType>& x) { |
| auto saver = random_internal::make_ostream_state_saver(os); |
| os.precision(random_internal::stream_precision_helper<RealType>::kPrecision); |
| os << x.alpha() << os.fill() << x.beta(); |
| return os; |
| } |
| |
| template <typename CharT, typename Traits, typename RealType> |
| std::basic_istream<CharT, Traits>& operator>>( |
| std::basic_istream<CharT, Traits>& is, // NOLINT(runtime/references) |
| beta_distribution<RealType>& x) { // NOLINT(runtime/references) |
| using result_type = typename beta_distribution<RealType>::result_type; |
| using param_type = typename beta_distribution<RealType>::param_type; |
| result_type alpha, beta; |
| |
| auto saver = random_internal::make_istream_state_saver(is); |
| alpha = random_internal::read_floating_point<result_type>(is); |
| if (is.fail()) return is; |
| beta = random_internal::read_floating_point<result_type>(is); |
| if (!is.fail()) { |
| x.param(param_type(alpha, beta)); |
| } |
| return is; |
| } |
| |
| } // namespace absl |
| |
| #endif // ABSL_RANDOM_BETA_DISTRIBUTION_H_ |