distributions/detail/derived_accessors.hpp

0001 //  Copyright John Maddock 2006.
0002 //  Copyright Matt Borland 2024.
0003 //  Use, modification and distribution are subject to the
0004 //  Boost Software License, Version 1.0. (See accompanying file
0005 //  LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
0006
0007 #ifndef BOOST_STATS_DERIVED_HPP
0008 #define BOOST_STATS_DERIVED_HPP
0009
0010 // This file implements various common properties of distributions
0011 // that can be implemented in terms of other properties:
0012 // variance OR standard deviation (see note below),
0013 // hazard, cumulative hazard (chf), coefficient_of_variation.
0014 //
0015 // Note that while both variance and standard_deviation are provided
0016 // here, each distribution MUST SPECIALIZE AT LEAST ONE OF THESE
0017 // otherwise these two versions will just call each other over and over
0018 // until stack space runs out ...
0019
0020 // Of course there may be more efficient means of implementing these
0021 // that are specific to a particular distribution, but these generic
0022 // versions give these properties "for free" with most distributions.
0023 //
0024 // In order to make use of this header, it must be included AT THE END
0025 // of the distribution header, AFTER the distribution and its core
0026 // property accessors have been defined: this is so that compilers
0027 // that implement 2-phase lookup and early-type-checking of templates
0028 // can find the definitions referred to herein.
0029 //
0030
0031 #include <boost/math/tools/config.hpp>
0032 #include <boost/math/tools/assert.hpp>
0033
0034 #ifndef BOOST_MATH_HAS_NVRTC
0035 #include <cmath>
0036 #endif
0037
0038 #ifdef _MSC_VER
0039 # pragma warning(push)
0040 # pragma warning(disable: 4723) // potential divide by 0
0041 // Suppressing spurious warning in coefficient_of_variation
0042 #endif
0043
0044 namespace boost{ namespace math{
0045
0046 template <class Distribution>
0047 BOOST_MATH_GPU_ENABLED typename Distribution::value_type variance(const Distribution& dist);
0048
0049 template <class Distribution>
0050 BOOST_MATH_GPU_ENABLED inline typename Distribution::value_type standard_deviation(const Distribution& dist)
0051 {
0052    BOOST_MATH_STD_USING  // ADL of sqrt.
0053    return sqrt(variance(dist));
0054 }
0055
0056 template <class Distribution>
0057 BOOST_MATH_GPU_ENABLED inline typename Distribution::value_type variance(const Distribution& dist)
0058 {
0059    typename Distribution::value_type result = standard_deviation(dist);
0060    return result * result;
0061 }
0062
0063 template <class Distribution, class RealType>
0064 BOOST_MATH_GPU_ENABLED inline typename Distribution::value_type hazard(const Distribution& dist, const RealType& x)
0065 { // hazard function
0066   // http://www.itl.nist.gov/div898/handbook/eda/section3/eda362.htm#HAZ
0067    typedef typename Distribution::value_type value_type;
0068    typedef typename Distribution::policy_type policy_type;
0069    value_type p = cdf(complement(dist, x));
0070    value_type d = pdf(dist, x);
0071    if(d > p * tools::max_value<value_type>())
0072       return policies::raise_overflow_error<value_type>(
0073       "boost::math::hazard(const Distribution&, %1%)", nullptr, policy_type());
0074    if(d == 0)
0075    {
0076       // This protects against 0/0, but is it the right thing to do?
0077       return 0;
0078    }
0079    return d / p;
0080 }
0081
0082 template <class Distribution, class RealType>
0083 BOOST_MATH_GPU_ENABLED inline typename Distribution::value_type chf(const Distribution& dist, const RealType& x)
0084 { // cumulative hazard function.
0085   // http://www.itl.nist.gov/div898/handbook/eda/section3/eda362.htm#HAZ
0086    BOOST_MATH_STD_USING
0087    return -log(cdf(complement(dist, x)));
0088 }
0089
0090 template <class Distribution>
0091 BOOST_MATH_GPU_ENABLED inline typename Distribution::value_type coefficient_of_variation(const Distribution& dist)
0092 {
0093    typedef typename Distribution::value_type value_type;
0094    typedef typename Distribution::policy_type policy_type;
0095
0096    using std::abs;
0097
0098    value_type m = mean(dist);
0099    value_type d = standard_deviation(dist);
0100    if((abs(m) < 1) && (d > abs(m) * tools::max_value<value_type>()))
0101    { // Checks too that m is not zero,
0102       return policies::raise_overflow_error<value_type>("boost::math::coefficient_of_variation(const Distribution&, %1%)", nullptr, policy_type());
0103    }
0104    return d / m; // so MSVC warning on zerodivide is spurious, and suppressed.
0105 }
0106 //
0107 // Next follow overloads of some of the standard accessors with mixed
0108 // argument types. We just use a typecast to forward on to the "real"
0109 // implementation with all arguments of the same type:
0110 //
0111 template <class Distribution, class RealType>
0112 BOOST_MATH_GPU_ENABLED inline typename Distribution::value_type pdf(const Distribution& dist, const RealType& x)
0113 {
0114    typedef typename Distribution::value_type value_type;
0115    return pdf(dist, static_cast<value_type>(x));
0116 }
0117 template <class Distribution, class RealType>
0118 BOOST_MATH_GPU_ENABLED inline typename Distribution::value_type logpdf(const Distribution& dist, const RealType& x)
0119 {
0120    using std::log;
0121    typedef typename Distribution::value_type value_type;
0122    return log(pdf(dist, static_cast<value_type>(x)));
0123 }
0124 template <class Distribution, class RealType>
0125 BOOST_MATH_GPU_ENABLED inline typename Distribution::value_type cdf(const Distribution& dist, const RealType& x)
0126 {
0127    typedef typename Distribution::value_type value_type;
0128    return cdf(dist, static_cast<value_type>(x));
0129 }
0130 template <class Distribution, class Realtype>
0131 BOOST_MATH_GPU_ENABLED inline typename Distribution::value_type logcdf(const Distribution& dist, const Realtype& x)
0132 {
0133    using std::log;
0134    using value_type = typename Distribution::value_type;
0135    return log(cdf(dist, static_cast<value_type>(x)));
0136 }
0137 template <class Distribution, class RealType>
0138 BOOST_MATH_GPU_ENABLED inline typename Distribution::value_type quantile(const Distribution& dist, const RealType& x)
0139 {
0140    typedef typename Distribution::value_type value_type;
0141    return quantile(dist, static_cast<value_type>(x));
0142 }
0143 /*
0144 template <class Distribution, class RealType>
0145 inline typename Distribution::value_type chf(const Distribution& dist, const RealType& x)
0146 {
0147    typedef typename Distribution::value_type value_type;
0148    return chf(dist, static_cast<value_type>(x));
0149 }
0150 */
0151 template <class Distribution, class RealType>
0152 BOOST_MATH_GPU_ENABLED inline typename Distribution::value_type cdf(const complemented2_type<Distribution, RealType>& c)
0153 {
0154    typedef typename Distribution::value_type value_type;
0155    return cdf(complement(c.dist, static_cast<value_type>(c.param)));
0156 }
0157
0158 template <class Distribution, class RealType>
0159 BOOST_MATH_GPU_ENABLED inline typename Distribution::value_type logcdf(const complemented2_type<Distribution, RealType>& c)
0160 {
0161    using std::log;
0162    typedef typename Distribution::value_type value_type;
0163    return log(cdf(complement(c.dist, static_cast<value_type>(c.param))));
0164 }
0165
0166 template <class Distribution, class RealType>
0167 BOOST_MATH_GPU_ENABLED inline typename Distribution::value_type quantile(const complemented2_type<Distribution, RealType>& c)
0168 {
0169    typedef typename Distribution::value_type value_type;
0170    return quantile(complement(c.dist, static_cast<value_type>(c.param)));
0171 }
0172
0173 template <class Dist>
0174 BOOST_MATH_GPU_ENABLED inline typename Dist::value_type median(const Dist& d)
0175 { // median - default definition for those distributions for which a
0176   // simple closed form is not known,
0177   // and for which a domain_error and/or NaN generating function is NOT defined.
0178   typedef typename Dist::value_type value_type;
0179   return quantile(d, static_cast<value_type>(0.5f));
0180 }
0181
0182 } // namespace math
0183 } // namespace boost
0184
0185
0186 #ifdef _MSC_VER
0187 # pragma warning(pop)
0188 #endif
0189
0190 #endif // BOOST_STATS_DERIVED_HPP