Debian Codegraph @

third-party/boost-math/include/boost/math/distributions/cauchy.hpp

raw
1 // Copyright John Maddock 2006, 2007.
2 // Copyright Paul A. Bristow 2007.
3 // Copyright Matt Borland 2024.
4
5 // Use, modification and distribution are subject to the
6 // Boost Software License, Version 1.0. (See accompanying file
7 // LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
8
9 #ifndef BOOST_STATS_CAUCHY_HPP
10 #define BOOST_STATS_CAUCHY_HPP
11
12 #ifdef _MSC_VER
13 #pragma warning(push)
14 #pragma warning(disable : 4127) // conditional expression is constant
15 #endif
16
17 #include <boost/math/tools/config.hpp>
18 #include <boost/math/tools/tuple.hpp>
19 #include <boost/math/tools/numeric_limits.hpp>
20 #include <boost/math/tools/precision.hpp>
21 #include <boost/math/tools/promotion.hpp>
22 #include <boost/math/constants/constants.hpp>
23 #include <boost/math/distributions/complement.hpp>
24 #include <boost/math/distributions/detail/common_error_handling.hpp>
25 #include <boost/math/policies/policy.hpp>
26 #include <boost/math/policies/error_handling.hpp>
27
28 #ifndef BOOST_MATH_HAS_NVRTC
29 #include <boost/math/distributions/fwd.hpp>
30 #include <utility>
31 #include <cmath>
32 #endif
33
34 namespace boost{ namespace math
35 {
36
37 template <class RealType, class Policy>
38 class cauchy_distribution;
39
40 namespace detail
41 {
42
43 template <class RealType, class Policy>
44 BOOST_MATH_GPU_ENABLED RealType cdf_imp(const cauchy_distribution<RealType, Policy>& dist, const RealType& x, bool complement)
45 {
46 //
47 // This calculates the cdf of the Cauchy distribution and/or its complement.
48 //
49 // This implementation uses the formula
50 //
51 // cdf = atan2(1, -x)/pi
52 //
53 // where x is the standardized (i.e. shifted and scaled) domain variable.
54 //
55 BOOST_MATH_STD_USING // for ADL of std functions
56 constexpr auto function = "boost::math::cdf(cauchy<%1%>&, %1%)";
57 RealType result = 0;
58 RealType location = dist.location();
59 RealType scale = dist.scale();
60 if(false == detail::check_location(function, location, &result, Policy()))
61 {
62 return result;
63 }
64 if(false == detail::check_scale(function, scale, &result, Policy()))
65 {
66 return result;
67 }
68 #ifdef BOOST_MATH_HAS_GPU_SUPPORT
69 if(x > tools::max_value<RealType>())
70 {
71 return static_cast<RealType>((complement) ? 0 : 1);
72 }
73 if(x < -tools::max_value<RealType>())
74 {
75 return static_cast<RealType>((complement) ? 1 : 0);
76 }
77 #else
78 if(boost::math::numeric_limits<RealType>::has_infinity && x == boost::math::numeric_limits<RealType>::infinity())
79 { // cdf +infinity is unity.
80 return static_cast<RealType>((complement) ? 0 : 1);
81 }
82 if(boost::math::numeric_limits<RealType>::has_infinity && x == -boost::math::numeric_limits<RealType>::infinity())
83 { // cdf -infinity is zero.
84 return static_cast<RealType>((complement) ? 1 : 0);
85 }
86 #endif
87 if(false == detail::check_x(function, x, &result, Policy()))
88 { // Catches x == NaN
89 return result;
90 }
91 RealType x_std = static_cast<RealType>((complement) ? 1 : -1)*(x - location) / scale;
92 return atan2(static_cast<RealType>(1), x_std) / constants::pi<RealType>();
93 } // cdf
94
95 template <class RealType, class Policy>
96 BOOST_MATH_GPU_ENABLED RealType quantile_imp(
97 const cauchy_distribution<RealType, Policy>& dist,
98 RealType p,
99 bool complement)
100 {
101 // This routine implements the quantile for the Cauchy distribution,
102 // the value p may be the probability, or its complement if complement=true.
103 //
104 // The procedure calculates the distance from the
105 // mid-point of the distribution. This is either added or subtracted
106 // from the location parameter depending on whether `complement` is true.
107 //
108 constexpr auto function = "boost::math::quantile(cauchy<%1%>&, %1%)";
109 BOOST_MATH_STD_USING // for ADL of std functions
110
111 RealType result = 0;
112 RealType location = dist.location();
113 RealType scale = dist.scale();
114 if(false == detail::check_location(function, location, &result, Policy()))
115 {
116 return result;
117 }
118 if(false == detail::check_scale(function, scale, &result, Policy()))
119 {
120 return result;
121 }
122 if(false == detail::check_probability(function, p, &result, Policy()))
123 {
124 return result;
125 }
126 // Special cases:
127 if(p == 1)
128 {
129 return (complement ? -1 : 1) * policies::raise_overflow_error<RealType>(function, 0, Policy());
130 }
131 if(p == 0)
132 {
133 return (complement ? 1 : -1) * policies::raise_overflow_error<RealType>(function, 0, Policy());
134 }
135
136 if(p > 0.5)
137 {
138 p = p - 1;
139 }
140 if(p == 0.5) // special case:
141 {
142 return location;
143 }
144 result = -scale / tan(constants::pi<RealType>() * p);
145 return complement ? RealType(location - result) : RealType(location + result);
146 } // quantile
147
148 } // namespace detail
149
150 template <class RealType = double, class Policy = policies::policy<> >
151 class cauchy_distribution
152 {
153 public:
154 typedef RealType value_type;
155 typedef Policy policy_type;
156
157 BOOST_MATH_GPU_ENABLED cauchy_distribution(RealType l_location = 0, RealType l_scale = 1)
158 : m_a(l_location), m_hg(l_scale)
159 {
160 constexpr auto function = "boost::math::cauchy_distribution<%1%>::cauchy_distribution";
161 RealType result;
162 detail::check_location(function, l_location, &result, Policy());
163 detail::check_scale(function, l_scale, &result, Policy());
164 } // cauchy_distribution
165
166 BOOST_MATH_GPU_ENABLED RealType location()const
167 {
168 return m_a;
169 }
170 BOOST_MATH_GPU_ENABLED RealType scale()const
171 {
172 return m_hg;
173 }
174
175 private:
176 RealType m_a; // The location, this is the median of the distribution.
177 RealType m_hg; // The scale )or shape), this is the half width at half height.
178 };
179
180 typedef cauchy_distribution<double> cauchy;
181
182 #ifdef __cpp_deduction_guides
183 template <class RealType>
184 cauchy_distribution(RealType)->cauchy_distribution<typename boost::math::tools::promote_args<RealType>::type>;
185 template <class RealType>
186 cauchy_distribution(RealType,RealType)->cauchy_distribution<typename boost::math::tools::promote_args<RealType>::type>;
187 #endif
188
189 template <class RealType, class Policy>
190 BOOST_MATH_GPU_ENABLED inline const boost::math::pair<RealType, RealType> range(const cauchy_distribution<RealType, Policy>&)
191 { // Range of permissible values for random variable x.
192 BOOST_MATH_IF_CONSTEXPR (boost::math::numeric_limits<RealType>::has_infinity)
193 {
194 return boost::math::pair<RealType, RealType>(-boost::math::numeric_limits<RealType>::infinity(), boost::math::numeric_limits<RealType>::infinity()); // - to + infinity.
195 }
196 else
197 { // Can only use max_value.
198 using boost::math::tools::max_value;
199 return boost::math::pair<RealType, RealType>(-max_value<RealType>(), max_value<RealType>()); // - to + max.
200 }
201 }
202
203 template <class RealType, class Policy>
204 BOOST_MATH_GPU_ENABLED inline const boost::math::pair<RealType, RealType> support(const cauchy_distribution<RealType, Policy>& )
205 { // Range of supported values for random variable x.
206 // This is range where cdf rises from 0 to 1, and outside it, the pdf is zero.
207 BOOST_MATH_IF_CONSTEXPR (boost::math::numeric_limits<RealType>::has_infinity)
208 {
209 return boost::math::pair<RealType, RealType>(-boost::math::numeric_limits<RealType>::infinity(), boost::math::numeric_limits<RealType>::infinity()); // - to + infinity.
210 }
211 else
212 { // Can only use max_value.
213 using boost::math::tools::max_value;
214 return boost::math::pair<RealType, RealType>(-tools::max_value<RealType>(), max_value<RealType>()); // - to + max.
215 }
216 }
217
218 template <class RealType, class Policy>
219 BOOST_MATH_GPU_ENABLED inline RealType pdf(const cauchy_distribution<RealType, Policy>& dist, const RealType& x)
220 {
221 BOOST_MATH_STD_USING // for ADL of std functions
222
223 constexpr auto function = "boost::math::pdf(cauchy<%1%>&, %1%)";
224 RealType result = 0;
225 RealType location = dist.location();
226 RealType scale = dist.scale();
227 if(false == detail::check_scale(function, scale, &result, Policy()))
228 {
229 return result;
230 }
231 if(false == detail::check_location(function, location, &result, Policy()))
232 {
233 return result;
234 }
235 if((boost::math::isinf)(x))
236 {
237 return 0; // pdf + and - infinity is zero.
238 }
239 // These produce MSVC 4127 warnings, so the above used instead.
240 //if(boost::math::numeric_limits<RealType>::has_infinity && abs(x) == boost::math::numeric_limits<RealType>::infinity())
241 //{ // pdf + and - infinity is zero.
242 // return 0;
243 //}
244
245 if(false == detail::check_x(function, x, &result, Policy()))
246 { // Catches x = NaN
247 return result;
248 }
249
250 RealType xs = (x - location) / scale;
251 result = 1 / (constants::pi<RealType>() * scale * (1 + xs * xs));
252 return result;
253 } // pdf
254
255 template <class RealType, class Policy>
256 BOOST_MATH_GPU_ENABLED inline RealType cdf(const cauchy_distribution<RealType, Policy>& dist, const RealType& x)
257 {
258 return detail::cdf_imp(dist, x, false);
259 } // cdf
260
261 template <class RealType, class Policy>
262 BOOST_MATH_GPU_ENABLED inline RealType quantile(const cauchy_distribution<RealType, Policy>& dist, const RealType& p)
263 {
264 return detail::quantile_imp(dist, p, false);
265 } // quantile
266
267 template <class RealType, class Policy>
268 BOOST_MATH_GPU_ENABLED inline RealType cdf(const complemented2_type<cauchy_distribution<RealType, Policy>, RealType>& c)
269 {
270 return detail::cdf_imp(c.dist, c.param, true);
271 } // cdf complement
272
273 template <class RealType, class Policy>
274 BOOST_MATH_GPU_ENABLED inline RealType quantile(const complemented2_type<cauchy_distribution<RealType, Policy>, RealType>& c)
275 {
276 return detail::quantile_imp(c.dist, c.param, true);
277 } // quantile complement
278
279 template <class RealType, class Policy>
280 BOOST_MATH_GPU_ENABLED inline RealType mean(const cauchy_distribution<RealType, Policy>&)
281 { // There is no mean:
282 typedef typename Policy::assert_undefined_type assert_type;
283 static_assert(assert_type::value == 0, "The Cauchy Distribution has no mean");
284
285 return policies::raise_domain_error<RealType>(
286 "boost::math::mean(cauchy<%1%>&)",
287 "The Cauchy distribution does not have a mean: "
288 "the only possible return value is %1%.",
289 boost::math::numeric_limits<RealType>::quiet_NaN(), Policy());
290 }
291
292 template <class RealType, class Policy>
293 BOOST_MATH_GPU_ENABLED inline RealType variance(const cauchy_distribution<RealType, Policy>& /*dist*/)
294 {
295 // There is no variance:
296 typedef typename Policy::assert_undefined_type assert_type;
297 static_assert(assert_type::value == 0, "The Cauchy Distribution has no variance");
298
299 return policies::raise_domain_error<RealType>(
300 "boost::math::variance(cauchy<%1%>&)",
301 "The Cauchy distribution does not have a variance: "
302 "the only possible return value is %1%.",
303 boost::math::numeric_limits<RealType>::quiet_NaN(), Policy());
304 }
305
306 template <class RealType, class Policy>
307 BOOST_MATH_GPU_ENABLED inline RealType mode(const cauchy_distribution<RealType, Policy>& dist)
308 {
309 return dist.location();
310 }
311
312 template <class RealType, class Policy>
313 BOOST_MATH_GPU_ENABLED inline RealType median(const cauchy_distribution<RealType, Policy>& dist)
314 {
315 return dist.location();
316 }
317
318 template <class RealType, class Policy>
319 BOOST_MATH_GPU_ENABLED inline RealType skewness(const cauchy_distribution<RealType, Policy>& /*dist*/)
320 {
321 // There is no skewness:
322 typedef typename Policy::assert_undefined_type assert_type;
323 static_assert(assert_type::value == 0, "The Cauchy Distribution has no skewness");
324
325 return policies::raise_domain_error<RealType>(
326 "boost::math::skewness(cauchy<%1%>&)",
327 "The Cauchy distribution does not have a skewness: "
328 "the only possible return value is %1%.",
329 boost::math::numeric_limits<RealType>::quiet_NaN(), Policy()); // infinity?
330 }
331
332 template <class RealType, class Policy>
333 BOOST_MATH_GPU_ENABLED inline RealType kurtosis(const cauchy_distribution<RealType, Policy>& /*dist*/)
334 {
335 // There is no kurtosis:
336 typedef typename Policy::assert_undefined_type assert_type;
337 static_assert(assert_type::value == 0, "The Cauchy Distribution has no kurtosis");
338
339 return policies::raise_domain_error<RealType>(
340 "boost::math::kurtosis(cauchy<%1%>&)",
341 "The Cauchy distribution does not have a kurtosis: "
342 "the only possible return value is %1%.",
343 boost::math::numeric_limits<RealType>::quiet_NaN(), Policy());
344 }
345
346 template <class RealType, class Policy>
347 BOOST_MATH_GPU_ENABLED inline RealType kurtosis_excess(const cauchy_distribution<RealType, Policy>& /*dist*/)
348 {
349 // There is no kurtosis excess:
350 typedef typename Policy::assert_undefined_type assert_type;
351 static_assert(assert_type::value == 0, "The Cauchy Distribution has no kurtosis excess");
352
353 return policies::raise_domain_error<RealType>(
354 "boost::math::kurtosis_excess(cauchy<%1%>&)",
355 "The Cauchy distribution does not have a kurtosis: "
356 "the only possible return value is %1%.",
357 boost::math::numeric_limits<RealType>::quiet_NaN(), Policy());
358 }
359
360 template <class RealType, class Policy>
361 BOOST_MATH_GPU_ENABLED inline RealType entropy(const cauchy_distribution<RealType, Policy> & dist)
362 {
363 using std::log;
364 return log(2*constants::two_pi<RealType>()*dist.scale());
365 }
366
367 } // namespace math
368 } // namespace boost
369
370 #ifdef _MSC_VER
371 #pragma warning(pop)
372 #endif
373
374 // This include must be at the end, *after* the accessors
375 // for this distribution have been defined, in order to
376 // keep compilers that support two-phase lookup happy.
377 #include <boost/math/distributions/detail/derived_accessors.hpp>
378
379 #endif // BOOST_STATS_CAUCHY_HPP