@lakutata/math 0.0.0-stage → 3.1.3

package/vendor/boost/math/include/boost/math/distributions/geometric.hpp

@@ -0,0 +1,571 @@
+// boost\math\distributions\geometric.hpp
+
+// Copyright John Maddock 2010.
+// Copyright Paul A. Bristow 2010.
+
+// Use, modification and distribution are subject to the
+// Boost Software License, Version 1.0.
+// (See accompanying file LICENSE_1_0.txt
+// or copy at http://www.boost.org/LICENSE_1_0.txt)
+
+// geometric distribution is a discrete probability distribution.
+// It expresses the probability distribution of the number (k) of
+// events, occurrences, failures or arrivals before the first success.
+// supported on the set {0, 1, 2, 3...}
+
+// Note that the set includes zero (unlike some definitions that start at one).
+
+// The random variate k is the number of events, occurrences or arrivals.
+// k argument may be integral, signed, or unsigned, or floating point.
+// If necessary, it has already been promoted from an integral type.
+
+// Note that the geometric distribution
+// (like others including the binomial, geometric & Bernoulli)
+// is strictly defined as a discrete function:
+// only integral values of k are envisaged.
+// However because the method of calculation uses a continuous gamma function,
+// it is convenient to treat it as if a continuous function,
+// and permit non-integral values of k.
+// To enforce the strict mathematical model, users should use floor or ceil functions
+// on k outside this function to ensure that k is integral.
+
+// See http://en.wikipedia.org/wiki/geometric_distribution
+// http://documents.wolfram.com/v5/Add-onsLinks/StandardPackages/Statistics/DiscreteDistributions.html
+// http://mathworld.wolfram.com/GeometricDistribution.html
+
+#ifndef BOOST_MATH_SPECIAL_GEOMETRIC_HPP
+#define BOOST_MATH_SPECIAL_GEOMETRIC_HPP
+
+#include <boost/math/tools/config.hpp>
+#include <boost/math/tools/tuple.hpp>
+#include <boost/math/tools/numeric_limits.hpp>
+#include <boost/math/distributions/fwd.hpp>
+#include <boost/math/special_functions/beta.hpp> // for ibeta(a, b, x) == Ix(a, b).
+#include <boost/math/distributions/complement.hpp> // complement.
+#include <boost/math/distributions/detail/common_error_handling.hpp> // error checks domain_error & logic_error.
+#include <boost/math/special_functions/fpclassify.hpp> // isnan.
+#include <boost/math/tools/roots.hpp> // for root finding.
+#include <boost/math/distributions/detail/inv_discrete_quantile.hpp>
+#include <boost/math/special_functions/log1p.hpp>
+
+#if defined (BOOST_MSVC)
+#  pragma warning(push)
+// This believed not now necessary, so commented out.
+//#  pragma warning(disable: 4702) // unreachable code.
+// in domain_error_imp in error_handling.
+#endif
+
+namespace boost
+{
+  namespace math
+  {
+    namespace geometric_detail
+    {
+      // Common error checking routines for geometric distribution function:
+      template <class RealType, class Policy>
+      BOOST_MATH_GPU_ENABLED inline bool check_success_fraction(const char* function, const RealType& p, RealType* result, const Policy& pol)
+      {
+        if( !(boost::math::isfinite)(p) || (p < 0) || (p > 1) )
+        {
+          *result = policies::raise_domain_error<RealType>(
+            function,
+            "Success fraction argument is %1%, but must be >= 0 and <= 1 !", p, pol);
+          return false;
+        }
+        return true;
+      }
+
+      template <class RealType, class Policy>
+      BOOST_MATH_GPU_ENABLED inline bool check_dist(const char* function, const RealType& p, RealType* result, const Policy& pol)
+      {
+        return check_success_fraction(function, p, result, pol);
+      }
+
+      template <class RealType, class Policy>
+      BOOST_MATH_GPU_ENABLED inline bool check_dist_and_k(const char* function,  const RealType& p, RealType k, RealType* result, const Policy& pol)
+      {
+        if(check_dist(function, p, result, pol) == false)
+        {
+          return false;
+        }
+        if( !(boost::math::isfinite)(k) || (k < 0) )
+        { // Check k failures.
+          *result = policies::raise_domain_error<RealType>(
+            function,
+            "Number of failures argument is %1%, but must be >= 0 !", k, pol);
+          return false;
+        }
+        return true;
+      } // Check_dist_and_k
+
+      template <class RealType, class Policy>
+      BOOST_MATH_GPU_ENABLED inline bool check_dist_and_prob(const char* function, RealType p, RealType prob, RealType* result, const Policy& pol)
+      {
+        if((check_dist(function, p, result, pol) && detail::check_probability(function, prob, result, pol)) == false)
+        {
+          return false;
+        }
+        return true;
+      } // check_dist_and_prob
+    } //  namespace geometric_detail
+
+    template <class RealType = double, class Policy = policies::policy<> >
+    class geometric_distribution
+    {
+    public:
+      typedef RealType value_type;
+      typedef Policy policy_type;
+
+      BOOST_MATH_GPU_ENABLED geometric_distribution(RealType p) : m_p(p)
+      { // Constructor stores success_fraction p.
+        RealType result;
+        geometric_detail::check_dist(
+          "geometric_distribution<%1%>::geometric_distribution",
+          m_p, // Check success_fraction 0 <= p <= 1.
+          &result, Policy());
+      } // geometric_distribution constructor.
+
+      // Private data getter class member functions.
+      BOOST_MATH_GPU_ENABLED RealType success_fraction() const
+      { // Probability of success as fraction in range 0 to 1.
+        return m_p;
+      }
+      BOOST_MATH_GPU_ENABLED RealType successes() const
+      { // Total number of successes r = 1 (for compatibility with negative binomial?).
+        return 1;
+      }
+
+      // Parameter estimation.
+      // (These are copies of negative_binomial distribution with successes = 1).
+      BOOST_MATH_GPU_ENABLED static RealType find_lower_bound_on_p(
+        RealType trials,
+        RealType alpha) // alpha 0.05 equivalent to 95% for one-sided test.
+      {
+        constexpr auto function = "boost::math::geometric<%1%>::find_lower_bound_on_p";
+        RealType result = 0;  // of error checks.
+        RealType successes = 1;
+        RealType failures = trials - successes;
+        if(false == detail::check_probability(function, alpha, &result, Policy())
+          && geometric_detail::check_dist_and_k(
+          function, RealType(0), failures, &result, Policy()))
+        {
+          return result;
+        }
+        // Use complement ibeta_inv function for lower bound.
+        // This is adapted from the corresponding binomial formula
+        // here: http://www.itl.nist.gov/div898/handbook/prc/section2/prc241.htm
+        // This is a Clopper-Pearson interval, and may be overly conservative,
+        // see also "A Simple Improved Inferential Method for Some
+        // Discrete Distributions" Yong CAI and K. KRISHNAMOORTHY
+        // http://www.ucs.louisiana.edu/~kxk4695/Discrete_new.pdf
+        //
+        return ibeta_inv(successes, failures + 1, alpha, static_cast<RealType*>(nullptr), Policy());
+      } // find_lower_bound_on_p
+
+      BOOST_MATH_GPU_ENABLED static RealType find_upper_bound_on_p(
+        RealType trials,
+        RealType alpha) // alpha 0.05 equivalent to 95% for one-sided test.
+      {
+        constexpr auto function = "boost::math::geometric<%1%>::find_upper_bound_on_p";
+        RealType result = 0;  // of error checks.
+        RealType successes = 1;
+        RealType failures = trials - successes;
+        if(false == geometric_detail::check_dist_and_k(
+          function, RealType(0), failures, &result, Policy())
+          && detail::check_probability(function, alpha, &result, Policy()))
+        {
+          return result;
+        }
+        if(failures == 0)
+        {
+           return 1;
+        }// Use complement ibetac_inv function for upper bound.
+        // Note adjusted failures value: *not* failures+1 as usual.
+        // This is adapted from the corresponding binomial formula
+        // here: http://www.itl.nist.gov/div898/handbook/prc/section2/prc241.htm
+        // This is a Clopper-Pearson interval, and may be overly conservative,
+        // see also "A Simple Improved Inferential Method for Some
+        // Discrete Distributions" Yong CAI and K. Krishnamoorthy
+        // http://www.ucs.louisiana.edu/~kxk4695/Discrete_new.pdf
+        //
+        return ibetac_inv(successes, failures, alpha, static_cast<RealType*>(nullptr), Policy());
+      } // find_upper_bound_on_p
+
+      // Estimate number of trials :
+      // "How many trials do I need to be P% sure of seeing k or fewer failures?"
+
+      BOOST_MATH_GPU_ENABLED static RealType find_minimum_number_of_trials(
+        RealType k,     // number of failures (k >= 0).
+        RealType p,     // success fraction 0 <= p <= 1.
+        RealType alpha) // risk level threshold 0 <= alpha <= 1.
+      {
+        constexpr auto function = "boost::math::geometric<%1%>::find_minimum_number_of_trials";
+        // Error checks:
+        RealType result = 0;
+        if(false == geometric_detail::check_dist_and_k(
+          function, p, k, &result, Policy())
+          && detail::check_probability(function, alpha, &result, Policy()))
+        {
+          return result;
+        }
+        result = ibeta_inva(k + 1, p, alpha, Policy());  // returns n - k
+        return result + k;
+      } // RealType find_number_of_failures
+
+      BOOST_MATH_GPU_ENABLED static RealType find_maximum_number_of_trials(
+        RealType k,     // number of failures (k >= 0).
+        RealType p,     // success fraction 0 <= p <= 1.
+        RealType alpha) // risk level threshold 0 <= alpha <= 1.
+      {
+        constexpr auto function = "boost::math::geometric<%1%>::find_maximum_number_of_trials";
+        // Error checks:
+        RealType result = 0;
+        if(false == geometric_detail::check_dist_and_k(
+          function, p, k, &result, Policy())
+          &&  detail::check_probability(function, alpha, &result, Policy()))
+        {
+          return result;
+        }
+        result = ibetac_inva(k + 1, p, alpha, Policy());  // returns n - k
+        return result + k;
+      } // RealType find_number_of_trials complemented
+
+    private:
+      //RealType m_r; // successes fixed at unity.
+      RealType m_p; // success_fraction
+    }; // template <class RealType, class Policy> class geometric_distribution
+
+    typedef geometric_distribution<double> geometric; // Reserved name of type double.
+
+    #ifdef __cpp_deduction_guides
+    template <class RealType>
+    geometric_distribution(RealType)->geometric_distribution<typename boost::math::tools::promote_args<RealType>::type>;
+    #endif
+
+    template <class RealType, class Policy>
+    BOOST_MATH_GPU_ENABLED inline const boost::math::pair<RealType, RealType> range(const geometric_distribution<RealType, Policy>& /* dist */)
+    { // Range of permissible values for random variable k.
+       using boost::math::tools::max_value;
+       return boost::math::pair<RealType, RealType>(static_cast<RealType>(0), max_value<RealType>()); // max_integer?
+    }
+
+    template <class RealType, class Policy>
+    BOOST_MATH_GPU_ENABLED inline const boost::math::pair<RealType, RealType> support(const geometric_distribution<RealType, Policy>& /* dist */)
+    { // Range of supported values for random variable k.
+       // This is range where cdf rises from 0 to 1, and outside it, the pdf is zero.
+       using boost::math::tools::max_value;
+       return boost::math::pair<RealType, RealType>(static_cast<RealType>(0),  max_value<RealType>()); // max_integer?
+    }
+
+    template <class RealType, class Policy>
+    BOOST_MATH_GPU_ENABLED inline RealType mean(const geometric_distribution<RealType, Policy>& dist)
+    { // Mean of geometric distribution = (1-p)/p.
+      return (1 - dist.success_fraction() ) / dist.success_fraction();
+    } // mean
+
+    // median implemented via quantile(half) in derived accessors.
+
+    template <class RealType, class Policy>
+    BOOST_MATH_GPU_ENABLED inline RealType mode(const geometric_distribution<RealType, Policy>&)
+    { // Mode of geometric distribution = zero.
+      BOOST_MATH_STD_USING // ADL of std functions.
+      return 0;
+    } // mode
+
+    template <class RealType, class Policy>
+    BOOST_MATH_GPU_ENABLED inline RealType variance(const geometric_distribution<RealType, Policy>& dist)
+    { // Variance of Binomial distribution = (1-p) / p^2.
+      return  (1 - dist.success_fraction())
+        / (dist.success_fraction() * dist.success_fraction());
+    } // variance
+
+    template <class RealType, class Policy>
+    BOOST_MATH_GPU_ENABLED inline RealType skewness(const geometric_distribution<RealType, Policy>& dist)
+    { // skewness of geometric distribution = 2-p / (sqrt(r(1-p))
+      BOOST_MATH_STD_USING // ADL of std functions.
+      RealType p = dist.success_fraction();
+      return (2 - p) / sqrt(1 - p);
+    } // skewness
+
+    template <class RealType, class Policy>
+    BOOST_MATH_GPU_ENABLED inline RealType kurtosis(const geometric_distribution<RealType, Policy>& dist)
+    { // kurtosis of geometric distribution
+      // http://en.wikipedia.org/wiki/geometric is kurtosis_excess so add 3
+      RealType p = dist.success_fraction();
+      return 3 + (p*p - 6*p + 6) / (1 - p);
+    } // kurtosis
+
+     template <class RealType, class Policy>
+    BOOST_MATH_GPU_ENABLED inline RealType kurtosis_excess(const geometric_distribution<RealType, Policy>& dist)
+    { // kurtosis excess of geometric distribution
+      // http://mathworld.wolfram.com/Kurtosis.html table of kurtosis_excess
+      RealType p = dist.success_fraction();
+      return (p*p - 6*p + 6) / (1 - p);
+    } // kurtosis_excess
+
+    // RealType standard_deviation(const geometric_distribution<RealType, Policy>& dist)
+    // standard_deviation provided by derived accessors.
+    // RealType hazard(const geometric_distribution<RealType, Policy>& dist)
+    // hazard of geometric distribution provided by derived accessors.
+    // RealType chf(const geometric_distribution<RealType, Policy>& dist)
+    // chf of geometric distribution provided by derived accessors.
+
+    template <class RealType, class Policy>
+    BOOST_MATH_GPU_ENABLED inline RealType pdf(const geometric_distribution<RealType, Policy>& dist, const RealType& k)
+    { // Probability Density/Mass Function.
+      BOOST_FPU_EXCEPTION_GUARD
+      BOOST_MATH_STD_USING  // For ADL of math functions.
+      constexpr auto function = "boost::math::pdf(const geometric_distribution<%1%>&, %1%)";
+
+      RealType p = dist.success_fraction();
+      RealType result = 0;
+      if(false == geometric_detail::check_dist_and_k(
+        function,
+        p,
+        k,
+        &result, Policy()))
+      {
+        return result;
+      }
+      if (k == 0)
+      {
+        return p; // success_fraction
+      }
+      RealType q = 1 - p;  // Inaccurate for small p?
+      // So try to avoid inaccuracy for large or small p.
+      // but has little effect > last significant bit.
+      //cout << "p *  pow(q, k) " << result << endl; // seems best whatever p
+      //cout << "exp(p * k * log1p(-p)) " << p * exp(k * log1p(-p)) << endl;
+      //if (p < 0.5)
+      //{
+      //  result = p *  pow(q, k);
+      //}
+      //else
+      //{
+      //  result = p * exp(k * log1p(-p));
+      //}
+      result = p * pow(q, k);
+      return result;
+    } // geometric_pdf
+
+    template <class RealType, class Policy>
+    BOOST_MATH_GPU_ENABLED inline RealType cdf(const geometric_distribution<RealType, Policy>& dist, const RealType& k)
+    { // Cumulative Distribution Function of geometric.
+      constexpr auto function = "boost::math::cdf(const geometric_distribution<%1%>&, %1%)";
+
+      // k argument may be integral, signed, or unsigned, or floating point.
+      // If necessary, it has already been promoted from an integral type.
+      RealType p = dist.success_fraction();
+      // Error check:
+      RealType result = 0;
+      if(false == geometric_detail::check_dist_and_k(
+        function,
+        p,
+        k,
+        &result, Policy()))
+      {
+        return result;
+      }
+      if(k == 0)
+      {
+        return p; // success_fraction
+      }
+      //RealType q = 1 - p;  // Bad for small p
+      //RealType probability = 1 - std::pow(q, k+1);
+
+      RealType z = boost::math::log1p(-p, Policy()) * (k + 1);
+      RealType probability = -boost::math::expm1(z, Policy());
+
+      return probability;
+    } // cdf Cumulative Distribution Function geometric.
+
+    template <class RealType, class Policy>
+    BOOST_MATH_GPU_ENABLED inline RealType logcdf(const geometric_distribution<RealType, Policy>& dist, const RealType& k)
+    { // Cumulative Distribution Function of geometric.
+      BOOST_MATH_STD_USING
+      constexpr auto function = "boost::math::logcdf(const geometric_distribution<%1%>&, %1%)";
+
+      // k argument may be integral, signed, or unsigned, or floating point.
+      // If necessary, it has already been promoted from an integral type.
+      RealType p = dist.success_fraction();
+      // Error check:
+      RealType result = 0;
+      if(false == geometric_detail::check_dist_and_k(
+        function,
+        p,
+        k,
+        &result, Policy()))
+      {
+        return -boost::math::numeric_limits<RealType>::infinity();
+      }
+      if(k == 0)
+      {
+        return log(p); // success_fraction
+      }
+      //RealType q = 1 - p;  // Bad for small p
+      //RealType probability = 1 - std::pow(q, k+1);
+
+      RealType z = boost::math::log1p(-p, Policy()) * (k + 1);
+      return log1p(-exp(z), Policy());
+    } // logcdf Cumulative Distribution Function geometric.
+
+    template <class RealType, class Policy>
+    BOOST_MATH_GPU_ENABLED inline RealType cdf(const complemented2_type<geometric_distribution<RealType, Policy>, RealType>& c)
+    { // Complemented Cumulative Distribution Function geometric.
+      BOOST_MATH_STD_USING
+      constexpr auto function = "boost::math::cdf(const geometric_distribution<%1%>&, %1%)";
+      // k argument may be integral, signed, or unsigned, or floating point.
+      // If necessary, it has already been promoted from an integral type.
+      RealType const& k = c.param;
+      geometric_distribution<RealType, Policy> const& dist = c.dist;
+      RealType p = dist.success_fraction();
+      // Error check:
+      RealType result = 0;
+      if(false == geometric_detail::check_dist_and_k(
+        function,
+        p,
+        k,
+        &result, Policy()))
+      {
+        return result;
+      }
+      RealType z = boost::math::log1p(-p, Policy()) * (k+1);
+      RealType probability = exp(z);
+      return probability;
+    } // cdf Complemented Cumulative Distribution Function geometric.
+
+    template <class RealType, class Policy>
+    BOOST_MATH_GPU_ENABLED inline RealType logcdf(const complemented2_type<geometric_distribution<RealType, Policy>, RealType>& c)
+    { // Complemented Cumulative Distribution Function geometric.
+      BOOST_MATH_STD_USING
+      constexpr auto function = "boost::math::logcdf(const geometric_distribution<%1%>&, %1%)";
+      // k argument may be integral, signed, or unsigned, or floating point.
+      // If necessary, it has already been promoted from an integral type.
+      RealType const& k = c.param;
+      geometric_distribution<RealType, Policy> const& dist = c.dist;
+      RealType p = dist.success_fraction();
+      // Error check:
+      RealType result = 0;
+      if(false == geometric_detail::check_dist_and_k(
+        function,
+        p,
+        k,
+        &result, Policy()))
+      {
+        return -boost::math::numeric_limits<RealType>::infinity();
+      }
+
+      return boost::math::log1p(-p, Policy()) * (k+1);
+    } // logcdf Complemented Cumulative Distribution Function geometric.
+
+    template <class RealType, class Policy>
+    BOOST_MATH_GPU_ENABLED inline RealType quantile(const geometric_distribution<RealType, Policy>& dist, const RealType& x)
+    { // Quantile, percentile/100 or Percent Point geometric function.
+      // Return the number of expected failures k for a given probability p.
+
+      // Inverse cumulative Distribution Function or Quantile (percentile / 100) of geometric Probability.
+      // k argument may be integral, signed, or unsigned, or floating point.
+
+      constexpr auto function = "boost::math::quantile(const geometric_distribution<%1%>&, %1%)";
+      BOOST_MATH_STD_USING // ADL of std functions.
+
+      RealType success_fraction = dist.success_fraction();
+      // Check dist and x.
+      RealType result = 0;
+      if(false == geometric_detail::check_dist_and_prob
+        (function, success_fraction, x, &result, Policy()))
+      {
+        return result;
+      }
+
+      // Special cases.
+      if (x == 1)
+      {  // Would need +infinity failures for total confidence.
+        result = policies::raise_overflow_error<RealType>(
+            function,
+            "Probability argument is 1, which implies infinite failures !", Policy());
+        return result;
+       // usually means return +std::numeric_limits<RealType>::infinity();
+       // unless #define BOOST_MATH_THROW_ON_OVERFLOW_ERROR
+      }
+      if (x == 0)
+      { // No failures are expected if P = 0.
+        return 0; // Total trials will be just dist.successes.
+      }
+      // if (P <= pow(dist.success_fraction(), 1))
+      if (x <= success_fraction)
+      { // p <= pdf(dist, 0) == cdf(dist, 0)
+        return 0;
+      }
+      if (x == 1)
+      {
+        return 0;
+      }
+
+      // log(1-x) /log(1-success_fraction) -1; but use log1p in case success_fraction is small
+      result = boost::math::log1p(-x, Policy()) / boost::math::log1p(-success_fraction, Policy()) - 1;
+      // Subtract a few epsilons here too?
+      // to make sure it doesn't slip over, so ceil would be one too many.
+      return result;
+    } // RealType quantile(const geometric_distribution dist, p)
+
+    template <class RealType, class Policy>
+    BOOST_MATH_GPU_ENABLED inline RealType quantile(const complemented2_type<geometric_distribution<RealType, Policy>, RealType>& c)
+    {  // Quantile or Percent Point Binomial function.
+       // Return the number of expected failures k for a given
+       // complement of the probability Q = 1 - P.
+       constexpr auto function = "boost::math::quantile(const geometric_distribution<%1%>&, %1%)";
+       BOOST_MATH_STD_USING
+       // Error checks:
+       RealType x = c.param;
+       const geometric_distribution<RealType, Policy>& dist = c.dist;
+       RealType success_fraction = dist.success_fraction();
+       RealType result = 0;
+       if(false == geometric_detail::check_dist_and_prob(
+          function,
+          success_fraction,
+          x,
+          &result, Policy()))
+       {
+          return result;
+       }
+
+       // Special cases:
+       if(x == 1)
+       {  // There may actually be no answer to this question,
+          // since the probability of zero failures may be non-zero,
+          return 0; // but zero is the best we can do:
+       }
+       if (-x <= boost::math::powm1(dist.success_fraction(), dist.successes(), Policy()))
+       {  // q <= cdf(complement(dist, 0)) == pdf(dist, 0)
+          return 0; //
+       }
+       if(x == 0)
+       {  // Probability 1 - Q  == 1 so infinite failures to achieve certainty.
+          // Would need +infinity failures for total confidence.
+          result = policies::raise_overflow_error<RealType>(
+             function,
+             "Probability argument complement is 0, which implies infinite failures !", Policy());
+          return result;
+          // usually means return +std::numeric_limits<RealType>::infinity();
+          // unless #define BOOST_MATH_THROW_ON_OVERFLOW_ERROR
+       }
+       // log(x) /log(1-success_fraction) -1; but use log1p in case success_fraction is small
+       result = log(x) / boost::math::log1p(-success_fraction, Policy()) - 1;
+      return result;
+
+    } // quantile complement
+
+ } // namespace math
+} // namespace boost
+
+// This include must be at the end, *after* the accessors
+// for this distribution have been defined, in order to
+// keep compilers that support two-phase lookup happy.
+#include <boost/math/distributions/detail/derived_accessors.hpp>
+
+#if defined (BOOST_MSVC)
+# pragma warning(pop)
+#endif
+
+#endif // BOOST_MATH_SPECIAL_GEOMETRIC_HPP