math/distributions/cauchy.hpp

0001 // Copyright John Maddock 2006, 2007.
0002 // Copyright Paul A. Bristow 2007.
0003 // Copyright Matt Borland 2024.
0004
0005 //  Use, modification and distribution are subject to the
0006 //  Boost Software License, Version 1.0. (See accompanying file
0007 //  LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
0008
0009 #ifndef BOOST_STATS_CAUCHY_HPP
0010 #define BOOST_STATS_CAUCHY_HPP
0011
0012 #ifdef _MSC_VER
0013 #pragma warning(push)
0014 #pragma warning(disable : 4127) // conditional expression is constant
0015 #endif
0016
0017 #include <boost/math/tools/config.hpp>
0018 #include <boost/math/tools/tuple.hpp>
0019 #include <boost/math/tools/numeric_limits.hpp>
0020 #include <boost/math/tools/precision.hpp>
0021 #include <boost/math/tools/promotion.hpp>
0022 #include <boost/math/constants/constants.hpp>
0023 #include <boost/math/distributions/complement.hpp>
0024 #include <boost/math/distributions/detail/common_error_handling.hpp>
0025 #include <boost/math/policies/policy.hpp>
0026 #include <boost/math/policies/error_handling.hpp>
0027
0028 #ifndef BOOST_MATH_HAS_NVRTC
0029 #include <boost/math/distributions/fwd.hpp>
0030 #include <utility>
0031 #include <cmath>
0032 #endif
0033
0034 namespace boost{ namespace math
0035 {
0036
0037 template <class RealType, class Policy>
0038 class cauchy_distribution;
0039
0040 namespace detail
0041 {
0042
0043 template <class RealType, class Policy>
0044 BOOST_MATH_GPU_ENABLED RealType cdf_imp(const cauchy_distribution<RealType, Policy>& dist, const RealType& x, bool complement)
0045 {
0046    //
0047    // This calculates the cdf of the Cauchy distribution and/or its complement.
0048    //
0049    // This implementation uses the formula
0050    //
0051    //     cdf = atan2(1, -x)/pi
0052    //
0053    // where x is the standardized (i.e. shifted and scaled) domain variable.
0054    //
0055    BOOST_MATH_STD_USING // for ADL of std functions
0056    constexpr auto function = "boost::math::cdf(cauchy<%1%>&, %1%)";
0057    RealType result = 0;
0058    RealType location = dist.location();
0059    RealType scale = dist.scale();
0060    if(false == detail::check_location(function, location, &result, Policy()))
0061    {
0062      return result;
0063    }
0064    if(false == detail::check_scale(function, scale, &result, Policy()))
0065    {
0066       return result;
0067    }
0068    #ifdef BOOST_MATH_HAS_GPU_SUPPORT
0069    if(x > tools::max_value<RealType>())
0070    {
0071       return static_cast<RealType>((complement) ? 0 : 1);
0072    }
0073    if(x < -tools::max_value<RealType>())
0074    {
0075       return static_cast<RealType>((complement) ? 1 : 0);
0076    }
0077    #else
0078    if(boost::math::numeric_limits<RealType>::has_infinity && x == boost::math::numeric_limits<RealType>::infinity())
0079    { // cdf +infinity is unity.
0080      return static_cast<RealType>((complement) ? 0 : 1);
0081    }
0082    if(boost::math::numeric_limits<RealType>::has_infinity && x == -boost::math::numeric_limits<RealType>::infinity())
0083    { // cdf -infinity is zero.
0084      return static_cast<RealType>((complement) ? 1 : 0);
0085    }
0086    #endif
0087    if(false == detail::check_x(function, x, &result, Policy()))
0088    { // Catches x == NaN
0089       return result;
0090    }
0091    RealType x_std = static_cast<RealType>((complement) ? 1 : -1)*(x - location) / scale;
0092    return atan2(static_cast<RealType>(1), x_std) / constants::pi<RealType>();
0093 } // cdf
0094
0095 template <class RealType, class Policy>
0096 BOOST_MATH_GPU_ENABLED RealType quantile_imp(
0097       const cauchy_distribution<RealType, Policy>& dist,
0098       RealType p,
0099       bool complement)
0100 {
0101    // This routine implements the quantile for the Cauchy distribution,
0102    // the value p may be the probability, or its complement if complement=true.
0103    //
0104    // The procedure calculates the distance from the
0105    // mid-point of the distribution.  This is either added or subtracted
0106    // from the location parameter depending on whether `complement` is true.
0107    //
0108    constexpr auto function = "boost::math::quantile(cauchy<%1%>&, %1%)";
0109    BOOST_MATH_STD_USING // for ADL of std functions
0110
0111    RealType result = 0;
0112    RealType location = dist.location();
0113    RealType scale = dist.scale();
0114    if(false == detail::check_location(function, location, &result, Policy()))
0115    {
0116      return result;
0117    }
0118    if(false == detail::check_scale(function, scale, &result, Policy()))
0119    {
0120       return result;
0121    }
0122    if(false == detail::check_probability(function, p, &result, Policy()))
0123    {
0124       return result;
0125    }
0126    // Special cases:
0127    if(p == 1)
0128    {
0129       return (complement ? -1 : 1) * policies::raise_overflow_error<RealType>(function, 0, Policy());
0130    }
0131    if(p == 0)
0132    {
0133       return (complement ? 1 : -1) * policies::raise_overflow_error<RealType>(function, 0, Policy());
0134    }
0135
0136    if(p > 0.5)
0137    {
0138       p = p - 1;
0139    }
0140    if(p == 0.5)   // special case:
0141    {
0142       return location;
0143    }
0144    result = -scale / tan(constants::pi<RealType>() * p);
0145    return complement ? RealType(location - result) : RealType(location + result);
0146 } // quantile
0147
0148 } // namespace detail
0149
0150 template <class RealType = double, class Policy = policies::policy<> >
0151 class cauchy_distribution
0152 {
0153 public:
0154    typedef RealType value_type;
0155    typedef Policy policy_type;
0156
0157    BOOST_MATH_GPU_ENABLED cauchy_distribution(RealType l_location = 0, RealType l_scale = 1)
0158       : m_a(l_location), m_hg(l_scale)
0159    {
0160     constexpr auto function = "boost::math::cauchy_distribution<%1%>::cauchy_distribution";
0161      RealType result;
0162      detail::check_location(function, l_location, &result, Policy());
0163      detail::check_scale(function, l_scale, &result, Policy());
0164    } // cauchy_distribution
0165
0166    BOOST_MATH_GPU_ENABLED RealType location()const
0167    {
0168       return m_a;
0169    }
0170    BOOST_MATH_GPU_ENABLED RealType scale()const
0171    {
0172       return m_hg;
0173    }
0174
0175 private:
0176    RealType m_a;    // The location, this is the median of the distribution.
0177    RealType m_hg;   // The scale )or shape), this is the half width at half height.
0178 };
0179
0180 typedef cauchy_distribution<double> cauchy;
0181
0182 #ifdef __cpp_deduction_guides
0183 template <class RealType>
0184 cauchy_distribution(RealType)->cauchy_distribution<typename boost::math::tools::promote_args<RealType>::type>;
0185 template <class RealType>
0186 cauchy_distribution(RealType,RealType)->cauchy_distribution<typename boost::math::tools::promote_args<RealType>::type>;
0187 #endif
0188
0189 template <class RealType, class Policy>
0190 BOOST_MATH_GPU_ENABLED inline const boost::math::pair<RealType, RealType> range(const cauchy_distribution<RealType, Policy>&)
0191 { // Range of permissible values for random variable x.
0192   BOOST_MATH_IF_CONSTEXPR (boost::math::numeric_limits<RealType>::has_infinity)
0193   {
0194      return boost::math::pair<RealType, RealType>(-boost::math::numeric_limits<RealType>::infinity(), boost::math::numeric_limits<RealType>::infinity()); // - to + infinity.
0195   }
0196   else
0197   { // Can only use max_value.
0198    using boost::math::tools::max_value;
0199    return boost::math::pair<RealType, RealType>(-max_value<RealType>(), max_value<RealType>()); // - to + max.
0200   }
0201 }
0202
0203 template <class RealType, class Policy>
0204 BOOST_MATH_GPU_ENABLED inline const boost::math::pair<RealType, RealType> support(const cauchy_distribution<RealType, Policy>& )
0205 { // Range of supported values for random variable x.
0206    // This is range where cdf rises from 0 to 1, and outside it, the pdf is zero.
0207   BOOST_MATH_IF_CONSTEXPR (boost::math::numeric_limits<RealType>::has_infinity)
0208   {
0209      return boost::math::pair<RealType, RealType>(-boost::math::numeric_limits<RealType>::infinity(), boost::math::numeric_limits<RealType>::infinity()); // - to + infinity.
0210   }
0211   else
0212   { // Can only use max_value.
0213      using boost::math::tools::max_value;
0214      return boost::math::pair<RealType, RealType>(-tools::max_value<RealType>(), max_value<RealType>()); // - to + max.
0215   }
0216 }
0217
0218 template <class RealType, class Policy>
0219 BOOST_MATH_GPU_ENABLED inline RealType pdf(const cauchy_distribution<RealType, Policy>& dist, const RealType& x)
0220 {
0221    BOOST_MATH_STD_USING  // for ADL of std functions
0222
0223    constexpr auto function = "boost::math::pdf(cauchy<%1%>&, %1%)";
0224    RealType result = 0;
0225    RealType location = dist.location();
0226    RealType scale = dist.scale();
0227    if(false == detail::check_scale(function, scale, &result, Policy()))
0228    {
0229       return result;
0230    }
0231    if(false == detail::check_location(function, location, &result, Policy()))
0232    {
0233       return result;
0234    }
0235    if((boost::math::isinf)(x))
0236    {
0237      return 0; // pdf + and - infinity is zero.
0238    }
0239    // These produce MSVC 4127 warnings, so the above used instead.
0240    //if(boost::math::numeric_limits<RealType>::has_infinity && abs(x) == boost::math::numeric_limits<RealType>::infinity())
0241    //{ // pdf + and - infinity is zero.
0242    //  return 0;
0243    //}
0244
0245    if(false == detail::check_x(function, x, &result, Policy()))
0246    { // Catches x = NaN
0247       return result;
0248    }
0249
0250    RealType xs = (x - location) / scale;
0251    result = 1 / (constants::pi<RealType>() * scale * (1 + xs * xs));
0252    return result;
0253 } // pdf
0254
0255 template <class RealType, class Policy>
0256 BOOST_MATH_GPU_ENABLED inline RealType cdf(const cauchy_distribution<RealType, Policy>& dist, const RealType& x)
0257 {
0258    return detail::cdf_imp(dist, x, false);
0259 } // cdf
0260
0261 template <class RealType, class Policy>
0262 BOOST_MATH_GPU_ENABLED inline RealType quantile(const cauchy_distribution<RealType, Policy>& dist, const RealType& p)
0263 {
0264    return detail::quantile_imp(dist, p, false);
0265 } // quantile
0266
0267 template <class RealType, class Policy>
0268 BOOST_MATH_GPU_ENABLED inline RealType cdf(const complemented2_type<cauchy_distribution<RealType, Policy>, RealType>& c)
0269 {
0270    return detail::cdf_imp(c.dist, c.param, true);
0271 } //  cdf complement
0272
0273 template <class RealType, class Policy>
0274 BOOST_MATH_GPU_ENABLED inline RealType quantile(const complemented2_type<cauchy_distribution<RealType, Policy>, RealType>& c)
0275 {
0276    return detail::quantile_imp(c.dist, c.param, true);
0277 } // quantile complement
0278
0279 template <class RealType, class Policy>
0280 BOOST_MATH_GPU_ENABLED inline RealType mean(const cauchy_distribution<RealType, Policy>&)
0281 {  // There is no mean:
0282    typedef typename Policy::assert_undefined_type assert_type;
0283    static_assert(assert_type::value == 0, "The Cauchy Distribution has no mean");
0284
0285    return policies::raise_domain_error<RealType>(
0286       "boost::math::mean(cauchy<%1%>&)",
0287       "The Cauchy distribution does not have a mean: "
0288       "the only possible return value is %1%.",
0289       boost::math::numeric_limits<RealType>::quiet_NaN(), Policy());
0290 }
0291
0292 template <class RealType, class Policy>
0293 BOOST_MATH_GPU_ENABLED inline RealType variance(const cauchy_distribution<RealType, Policy>& /*dist*/)
0294 {
0295    // There is no variance:
0296    typedef typename Policy::assert_undefined_type assert_type;
0297    static_assert(assert_type::value == 0, "The Cauchy Distribution has no variance");
0298
0299    return policies::raise_domain_error<RealType>(
0300       "boost::math::variance(cauchy<%1%>&)",
0301       "The Cauchy distribution does not have a variance: "
0302       "the only possible return value is %1%.",
0303       boost::math::numeric_limits<RealType>::quiet_NaN(), Policy());
0304 }
0305
0306 template <class RealType, class Policy>
0307 BOOST_MATH_GPU_ENABLED inline RealType mode(const cauchy_distribution<RealType, Policy>& dist)
0308 {
0309    return dist.location();
0310 }
0311
0312 template <class RealType, class Policy>
0313 BOOST_MATH_GPU_ENABLED inline RealType median(const cauchy_distribution<RealType, Policy>& dist)
0314 {
0315    return dist.location();
0316 }
0317
0318 template <class RealType, class Policy>
0319 BOOST_MATH_GPU_ENABLED inline RealType skewness(const cauchy_distribution<RealType, Policy>& /*dist*/)
0320 {
0321    // There is no skewness:
0322    typedef typename Policy::assert_undefined_type assert_type;
0323    static_assert(assert_type::value == 0, "The Cauchy Distribution has no skewness");
0324
0325    return policies::raise_domain_error<RealType>(
0326       "boost::math::skewness(cauchy<%1%>&)",
0327       "The Cauchy distribution does not have a skewness: "
0328       "the only possible return value is %1%.",
0329       boost::math::numeric_limits<RealType>::quiet_NaN(), Policy()); // infinity?
0330 }
0331
0332 template <class RealType, class Policy>
0333 BOOST_MATH_GPU_ENABLED inline RealType kurtosis(const cauchy_distribution<RealType, Policy>& /*dist*/)
0334 {
0335    // There is no kurtosis:
0336    typedef typename Policy::assert_undefined_type assert_type;
0337    static_assert(assert_type::value == 0, "The Cauchy Distribution has no kurtosis");
0338
0339    return policies::raise_domain_error<RealType>(
0340       "boost::math::kurtosis(cauchy<%1%>&)",
0341       "The Cauchy distribution does not have a kurtosis: "
0342       "the only possible return value is %1%.",
0343       boost::math::numeric_limits<RealType>::quiet_NaN(), Policy());
0344 }
0345
0346 template <class RealType, class Policy>
0347 BOOST_MATH_GPU_ENABLED inline RealType kurtosis_excess(const cauchy_distribution<RealType, Policy>& /*dist*/)
0348 {
0349    // There is no kurtosis excess:
0350    typedef typename Policy::assert_undefined_type assert_type;
0351    static_assert(assert_type::value == 0, "The Cauchy Distribution has no kurtosis excess");
0352
0353    return policies::raise_domain_error<RealType>(
0354       "boost::math::kurtosis_excess(cauchy<%1%>&)",
0355       "The Cauchy distribution does not have a kurtosis: "
0356       "the only possible return value is %1%.",
0357       boost::math::numeric_limits<RealType>::quiet_NaN(), Policy());
0358 }
0359
0360 template <class RealType, class Policy>
0361 BOOST_MATH_GPU_ENABLED inline RealType entropy(const cauchy_distribution<RealType, Policy> & dist)
0362 {
0363    using std::log;
0364    return log(2*constants::two_pi<RealType>()*dist.scale());
0365 }
0366
0367 } // namespace math
0368 } // namespace boost
0369
0370 #ifdef _MSC_VER
0371 #pragma warning(pop)
0372 #endif
0373
0374 // This include must be at the end, *after* the accessors
0375 // for this distribution have been defined, in order to
0376 // keep compilers that support two-phase lookup happy.
0377 #include <boost/math/distributions/detail/derived_accessors.hpp>
0378
0379 #endif // BOOST_STATS_CAUCHY_HPP