ceph/src/boost/boost/math/distributions/normal.hpp

   1 //  Copyright John Maddock 2006, 2007.
   2 //  Copyright Paul A. Bristow 2006, 2007.
   3
   4 //  Use, modification and distribution are subject to the
   5 //  Boost Software License, Version 1.0. (See accompanying file
   6 //  LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
   7
   8 #ifndef BOOST_STATS_NORMAL_HPP
   9 #define BOOST_STATS_NORMAL_HPP
  10
  11 // http://en.wikipedia.org/wiki/Normal_distribution
  12 // http://www.itl.nist.gov/div898/handbook/eda/section3/eda3661.htm
  13 // Also:
  14 // Weisstein, Eric W. "Normal Distribution."
  15 // From MathWorld--A Wolfram Web Resource.
  16 // http://mathworld.wolfram.com/NormalDistribution.html
  17
  18 #include <boost/math/distributions/fwd.hpp>
  19 #include <boost/math/special_functions/erf.hpp> // for erf/erfc.
  20 #include <boost/math/distributions/complement.hpp>
  21 #include <boost/math/distributions/detail/common_error_handling.hpp>
  22
  23 #include <utility>
  24
  25 namespace boost{ namespace math{
  26
  27 template <class RealType = double, class Policy = policies::policy<> >
  28 class normal_distribution
  29 {
  30 public:
  31    typedef RealType value_type;
  32    typedef Policy policy_type;
  33
  34    normal_distribution(RealType l_mean = 0, RealType sd = 1)
  35       : m_mean(l_mean), m_sd(sd)
  36    { // Default is a 'standard' normal distribution N01.
  37      static const char* function = "boost::math::normal_distribution<%1%>::normal_distribution";
  38
  39      RealType result;
  40      detail::check_scale(function, sd, &result, Policy());
  41      detail::check_location(function, l_mean, &result, Policy());
  42    }
  43
  44    RealType mean()const
  45    { // alias for location.
  46       return m_mean;
  47    }
  48
  49    RealType standard_deviation()const
  50    { // alias for scale.
  51       return m_sd;
  52    }
  53
  54    // Synonyms, provided to allow generic use of find_location and find_scale.
  55    RealType location()const
  56    { // location.
  57       return m_mean;
  58    }
  59    RealType scale()const
  60    { // scale.
  61       return m_sd;
  62    }
  63
  64 private:
  65    //
  66    // Data members:
  67    //
  68    RealType m_mean;  // distribution mean or location.
  69    RealType m_sd;    // distribution standard deviation or scale.
  70 }; // class normal_distribution
  71
  72 typedef normal_distribution<double> normal;
  73
  74 //
  75 // Deduction guides, note we don't check the
  76 // value of __cpp_deduction_guides, just assume
  77 // they work as advertised, even if this is pre-final C++17.
  78 //
  79 #ifdef __cpp_deduction_guides
  80
  81 template <class RealType>
  82 normal_distribution(RealType, RealType)->normal_distribution<typename boost::math::tools::promote_args<RealType>::type>;
  83 template <class RealType>
  84 normal_distribution(RealType)->normal_distribution<typename boost::math::tools::promote_args<RealType>::type>;
  85
  86 #endif
  87
  88 #ifdef _MSC_VER
  89 #pragma warning(push)
  90 #pragma warning(disable:4127)
  91 #endif
  92
  93 template <class RealType, class Policy>
  94 inline const std::pair<RealType, RealType> range(const normal_distribution<RealType, Policy>& /*dist*/)
  95 { // Range of permissible values for random variable x.
  96   if (std::numeric_limits<RealType>::has_infinity)
  97   {
  98      return std::pair<RealType, RealType>(-std::numeric_limits<RealType>::infinity(), std::numeric_limits<RealType>::infinity()); // - to + infinity.
  99   }
 100   else
 101   { // Can only use max_value.
 102     using boost::math::tools::max_value;
 103     return std::pair<RealType, RealType>(-max_value<RealType>(), max_value<RealType>()); // - to + max value.
 104   }
 105 }
 106
 107 template <class RealType, class Policy>
 108 inline const std::pair<RealType, RealType> support(const normal_distribution<RealType, Policy>& /*dist*/)
 109 { // This is range values for random variable x where cdf rises from 0 to 1, and outside it, the pdf is zero.
 110   if (std::numeric_limits<RealType>::has_infinity)
 111   {
 112      return std::pair<RealType, RealType>(-std::numeric_limits<RealType>::infinity(), std::numeric_limits<RealType>::infinity()); // - to + infinity.
 113   }
 114   else
 115   { // Can only use max_value.
 116    using boost::math::tools::max_value;
 117    return std::pair<RealType, RealType>(-max_value<RealType>(),  max_value<RealType>()); // - to + max value.
 118   }
 119 }
 120
 121 #ifdef _MSC_VER
 122 #pragma warning(pop)
 123 #endif
 124
 125 template <class RealType, class Policy>
 126 inline RealType pdf(const normal_distribution<RealType, Policy>& dist, const RealType& x)
 127 {
 128    BOOST_MATH_STD_USING  // for ADL of std functions
 129
 130    RealType sd = dist.standard_deviation();
 131    RealType mean = dist.mean();
 132
 133    static const char* function = "boost::math::pdf(const normal_distribution<%1%>&, %1%)";
 134
 135    RealType result = 0;
 136    if(false == detail::check_scale(function, sd, &result, Policy()))
 137    {
 138       return result;
 139    }
 140    if(false == detail::check_location(function, mean, &result, Policy()))
 141    {
 142       return result;
 143    }
 144    if((boost::math::isinf)(x))
 145    {
 146      return 0; // pdf + and - infinity is zero.
 147    }
 148    // Below produces MSVC 4127 warnings, so the above used instead.
 149    //if(std::numeric_limits<RealType>::has_infinity && abs(x) == std::numeric_limits<RealType>::infinity())
 150    //{ // pdf + and - infinity is zero.
 151    //  return 0;
 152    //}
 153    if(false == detail::check_x(function, x, &result, Policy()))
 154    {
 155       return result;
 156    }
 157
 158    RealType exponent = x - mean;
 159    exponent *= -exponent;
 160    exponent /= 2 * sd * sd;
 161
 162    result = exp(exponent);
 163    result /= sd * sqrt(2 * constants::pi<RealType>());
 164
 165    return result;
 166 } // pdf
 167
 168 template <class RealType, class Policy>
 169 inline RealType cdf(const normal_distribution<RealType, Policy>& dist, const RealType& x)
 170 {
 171    BOOST_MATH_STD_USING  // for ADL of std functions
 172
 173    RealType sd = dist.standard_deviation();
 174    RealType mean = dist.mean();
 175    static const char* function = "boost::math::cdf(const normal_distribution<%1%>&, %1%)";
 176    RealType result = 0;
 177    if(false == detail::check_scale(function, sd, &result, Policy()))
 178    {
 179       return result;
 180    }
 181    if(false == detail::check_location(function, mean, &result, Policy()))
 182    {
 183       return result;
 184    }
 185    if((boost::math::isinf)(x))
 186    {
 187      if(x < 0) return 0; // -infinity
 188      return 1; // + infinity
 189    }
 190    // These produce MSVC 4127 warnings, so the above used instead.
 191    //if(std::numeric_limits<RealType>::has_infinity && x == std::numeric_limits<RealType>::infinity())
 192    //{ // cdf +infinity is unity.
 193    //  return 1;
 194    //}
 195    //if(std::numeric_limits<RealType>::has_infinity && x == -std::numeric_limits<RealType>::infinity())
 196    //{ // cdf -infinity is zero.
 197    //  return 0;
 198    //}
 199    if(false == detail::check_x(function, x, &result, Policy()))
 200    {
 201      return result;
 202    }
 203    RealType diff = (x - mean) / (sd * constants::root_two<RealType>());
 204    result = boost::math::erfc(-diff, Policy()) / 2;
 205    return result;
 206 } // cdf
 207
 208 template <class RealType, class Policy>
 209 inline RealType quantile(const normal_distribution<RealType, Policy>& dist, const RealType& p)
 210 {
 211    BOOST_MATH_STD_USING  // for ADL of std functions
 212
 213    RealType sd = dist.standard_deviation();
 214    RealType mean = dist.mean();
 215    static const char* function = "boost::math::quantile(const normal_distribution<%1%>&, %1%)";
 216
 217    RealType result = 0;
 218    if(false == detail::check_scale(function, sd, &result, Policy()))
 219       return result;
 220    if(false == detail::check_location(function, mean, &result, Policy()))
 221       return result;
 222    if(false == detail::check_probability(function, p, &result, Policy()))
 223       return result;
 224
 225    result= boost::math::erfc_inv(2 * p, Policy());
 226    result = -result;
 227    result *= sd * constants::root_two<RealType>();
 228    result += mean;
 229    return result;
 230 } // quantile
 231
 232 template <class RealType, class Policy>
 233 inline RealType cdf(const complemented2_type<normal_distribution<RealType, Policy>, RealType>& c)
 234 {
 235    BOOST_MATH_STD_USING  // for ADL of std functions
 236
 237    RealType sd = c.dist.standard_deviation();
 238    RealType mean = c.dist.mean();
 239    RealType x = c.param;
 240    static const char* function = "boost::math::cdf(const complement(normal_distribution<%1%>&), %1%)";
 241
 242    RealType result = 0;
 243    if(false == detail::check_scale(function, sd, &result, Policy()))
 244       return result;
 245    if(false == detail::check_location(function, mean, &result, Policy()))
 246       return result;
 247    if((boost::math::isinf)(x))
 248    {
 249      if(x < 0) return 1; // cdf complement -infinity is unity.
 250      return 0; // cdf complement +infinity is zero
 251    }
 252    // These produce MSVC 4127 warnings, so the above used instead.
 253    //if(std::numeric_limits<RealType>::has_infinity && x == std::numeric_limits<RealType>::infinity())
 254    //{ // cdf complement +infinity is zero.
 255    //  return 0;
 256    //}
 257    //if(std::numeric_limits<RealType>::has_infinity && x == -std::numeric_limits<RealType>::infinity())
 258    //{ // cdf complement -infinity is unity.
 259    //  return 1;
 260    //}
 261    if(false == detail::check_x(function, x, &result, Policy()))
 262       return result;
 263
 264    RealType diff = (x - mean) / (sd * constants::root_two<RealType>());
 265    result = boost::math::erfc(diff, Policy()) / 2;
 266    return result;
 267 } // cdf complement
 268
 269 template <class RealType, class Policy>
 270 inline RealType quantile(const complemented2_type<normal_distribution<RealType, Policy>, RealType>& c)
 271 {
 272    BOOST_MATH_STD_USING  // for ADL of std functions
 273
 274    RealType sd = c.dist.standard_deviation();
 275    RealType mean = c.dist.mean();
 276    static const char* function = "boost::math::quantile(const complement(normal_distribution<%1%>&), %1%)";
 277    RealType result = 0;
 278    if(false == detail::check_scale(function, sd, &result, Policy()))
 279       return result;
 280    if(false == detail::check_location(function, mean, &result, Policy()))
 281       return result;
 282    RealType q = c.param;
 283    if(false == detail::check_probability(function, q, &result, Policy()))
 284       return result;
 285    result = boost::math::erfc_inv(2 * q, Policy());
 286    result *= sd * constants::root_two<RealType>();
 287    result += mean;
 288    return result;
 289 } // quantile
 290
 291 template <class RealType, class Policy>
 292 inline RealType mean(const normal_distribution<RealType, Policy>& dist)
 293 {
 294    return dist.mean();
 295 }
 296
 297 template <class RealType, class Policy>
 298 inline RealType standard_deviation(const normal_distribution<RealType, Policy>& dist)
 299 {
 300    return dist.standard_deviation();
 301 }
 302
 303 template <class RealType, class Policy>
 304 inline RealType mode(const normal_distribution<RealType, Policy>& dist)
 305 {
 306    return dist.mean();
 307 }
 308
 309 template <class RealType, class Policy>
 310 inline RealType median(const normal_distribution<RealType, Policy>& dist)
 311 {
 312    return dist.mean();
 313 }
 314
 315 template <class RealType, class Policy>
 316 inline RealType skewness(const normal_distribution<RealType, Policy>& /*dist*/)
 317 {
 318    return 0;
 319 }
 320
 321 template <class RealType, class Policy>
 322 inline RealType kurtosis(const normal_distribution<RealType, Policy>& /*dist*/)
 323 {
 324    return 3;
 325 }
 326
 327 template <class RealType, class Policy>
 328 inline RealType kurtosis_excess(const normal_distribution<RealType, Policy>& /*dist*/)
 329 {
 330    return 0;
 331 }
 332
 333 template <class RealType, class Policy>
 334 inline RealType entropy(const normal_distribution<RealType, Policy> & dist)
 335 {
 336    using std::log;
 337    RealType arg = constants::two_pi<RealType>()*constants::e<RealType>()*dist.standard_deviation()*dist.standard_deviation();
 338    return log(arg)/2;
 339 }
 340
 341 } // namespace math
 342 } // namespace boost
 343
 344 // This include must be at the end, *after* the accessors
 345 // for this distribution have been defined, in order to
 346 // keep compilers that support two-phase lookup happy.
 347 #include <boost/math/distributions/detail/derived_accessors.hpp>
 348
 349 #endif // BOOST_STATS_NORMAL_HPP
 350
 351