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