Debian Codegraph @

third-party/boost-math/include/boost/math/special_functions/ellint_3.hpp

raw
1 // Copyright (c) 2006 Xiaogang Zhang
2 // Copyright (c) 2006 John Maddock
3 // Use, modification and distribution are subject to the
4 // Boost Software License, Version 1.0. (See accompanying file
5 // LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
6 //
7 // History:
8 // XZ wrote the original of this file as part of the Google
9 // Summer of Code 2006. JM modified it to fit into the
10 // Boost.Math conceptual framework better, and to correctly
11 // handle the various corner cases.
12 //
13
14 #ifndef BOOST_MATH_ELLINT_3_HPP
15 #define BOOST_MATH_ELLINT_3_HPP
16
17 #ifdef _MSC_VER
18 #pragma once
19 #endif
20
21 #include <boost/math/tools/config.hpp>
22 #include <boost/math/tools/type_traits.hpp>
23 #include <boost/math/special_functions/math_fwd.hpp>
24 #include <boost/math/special_functions/ellint_rf.hpp>
25 #include <boost/math/special_functions/ellint_rj.hpp>
26 #include <boost/math/special_functions/ellint_1.hpp>
27 #include <boost/math/special_functions/ellint_2.hpp>
28 #include <boost/math/special_functions/log1p.hpp>
29 #include <boost/math/special_functions/atanh.hpp>
30 #include <boost/math/constants/constants.hpp>
31 #include <boost/math/policies/error_handling.hpp>
32 #include <boost/math/tools/workaround.hpp>
33 #include <boost/math/special_functions/round.hpp>
34
35 // Elliptic integrals (complete and incomplete) of the third kind
36 // Carlson, Numerische Mathematik, vol 33, 1 (1979)
37
38 namespace boost { namespace math {
39
40 namespace detail{
41
42 template <typename T, typename Policy>
43 BOOST_MATH_CUDA_ENABLED T ellint_pi_imp(T v, T k, T vc, const Policy& pol);
44
45 // Elliptic integral (Legendre form) of the third kind
46 template <typename T, typename Policy>
47 BOOST_MATH_CUDA_ENABLED T ellint_pi_imp(T v, T phi, T k, T vc, const Policy& pol)
48 {
49 // Note vc = 1-v presumably without cancellation error.
50 BOOST_MATH_STD_USING
51
52 constexpr auto function = "boost::math::ellint_3<%1%>(%1%,%1%,%1%)";
53
54
55 T sphi = sin(fabs(phi));
56 T result = 0;
57
58 if (k * k * sphi * sphi > 1)
59 {
60 return policies::raise_domain_error<T>(function, "Got k = %1%, function requires |k| <= 1", k, pol);
61 }
62 // Special cases first:
63 if(v == 0)
64 {
65 // A&S 17.7.18 & 19
66 return (k == 0) ? phi : ellint_f_imp(phi, k, pol);
67 }
68 if((v > 0) && (1 / v < (sphi * sphi)))
69 {
70 // Complex result is a domain error:
71 return policies::raise_domain_error<T>(function, "Got v = %1%, but result is complex for v > 1 / sin^2(phi)", v, pol);
72 }
73
74 if(v == 1)
75 {
76 if (k == 0)
77 return tan(phi);
78
79 // http://functions.wolfram.com/08.06.03.0008.01
80 T m = k * k;
81 result = sqrt(1 - m * sphi * sphi) * tan(phi) - ellint_e_imp(phi, k, pol);
82 result /= 1 - m;
83 result += ellint_f_imp(phi, k, pol);
84 return result;
85 }
86 if(phi == constants::half_pi<T>())
87 {
88 // Have to filter this case out before the next
89 // special case, otherwise we might get an infinity from
90 // tan(phi).
91 // Also note that since we can't represent PI/2 exactly
92 // in a T, this is a bit of a guess as to the users true
93 // intent...
94 //
95 return ellint_pi_imp(v, k, vc, pol);
96 }
97 if((phi > constants::half_pi<T>()) || (phi < 0))
98 {
99 // Carlson's algorithm works only for |phi| <= pi/2,
100 // use the integrand's periodicity to normalize phi
101 //
102 // Xiaogang's original code used a cast to long long here
103 // but that fails if T has more digits than a long long,
104 // so rewritten to use fmod instead:
105 //
106 // See http://functions.wolfram.com/08.06.16.0002.01
107 //
108 if(fabs(phi) > 1 / tools::epsilon<T>())
109 {
110 // Invalid for v > 1, this case is caught above since v > 1 implies 1/v < sin^2(phi)
111 BOOST_MATH_ASSERT(v <= 1);
112 //
113 // Phi is so large that phi%pi is necessarily zero (or garbage),
114 // just return the second part of the duplication formula:
115 //
116 result = 2 * fabs(phi) * ellint_pi_imp(v, k, vc, pol) / constants::pi<T>();
117 }
118 else
119 {
120 T rphi = boost::math::tools::fmod_workaround(T(fabs(phi)), T(constants::half_pi<T>()));
121 T m = boost::math::round((fabs(phi) - rphi) / constants::half_pi<T>());
122 int sign = 1;
123 if((m != 0) && (k >= 1))
124 {
125 return policies::raise_domain_error<T>(function, "Got k=1 and phi=%1% but the result is complex in that domain", phi, pol);
126 }
127 if(boost::math::tools::fmod_workaround(m, T(2)) > T(0.5))
128 {
129 m += 1;
130 sign = -1;
131 rphi = constants::half_pi<T>() - rphi;
132 }
133 result = sign * ellint_pi_imp(v, rphi, k, vc, pol);
134 if((m > 0) && (vc > 0))
135 result += m * ellint_pi_imp(v, k, vc, pol);
136 }
137 return phi < 0 ? T(-result) : result;
138 }
139 if(k == 0)
140 {
141 // A&S 17.7.20:
142 if(v < 1)
143 {
144 T vcr = sqrt(vc);
145 return atan(vcr * tan(phi)) / vcr;
146 }
147 else
148 {
149 // v > 1:
150 T vcr = sqrt(-vc);
151 T arg = vcr * tan(phi);
152 return (boost::math::log1p(arg, pol) - boost::math::log1p(-arg, pol)) / (2 * vcr);
153 }
154 }
155 if((v < 0) && fabs(k) <= 1)
156 {
157 //
158 // If we don't shift to 0 <= v <= 1 we get
159 // cancellation errors later on. Use
160 // A&S 17.7.15/16 to shift to v > 0.
161 //
162 // Mathematica simplifies the expressions
163 // given in A&S as follows (with thanks to
164 // Rocco Romeo for figuring these out!):
165 //
166 // V = (k2 - n)/(1 - n)
167 // Assuming[(k2 >= 0 && k2 <= 1) && n < 0, FullSimplify[Sqrt[(1 - V)*(1 - k2 / V)] / Sqrt[((1 - n)*(1 - k2 / n))]]]
168 // Result: ((-1 + k2) n) / ((-1 + n) (-k2 + n))
169 //
170 // Assuming[(k2 >= 0 && k2 <= 1) && n < 0, FullSimplify[k2 / (Sqrt[-n*(k2 - n) / (1 - n)] * Sqrt[(1 - n)*(1 - k2 / n)])]]
171 // Result : k2 / (k2 - n)
172 //
173 // Assuming[(k2 >= 0 && k2 <= 1) && n < 0, FullSimplify[Sqrt[1 / ((1 - n)*(1 - k2 / n))]]]
174 // Result : Sqrt[n / ((k2 - n) (-1 + n))]
175 //
176 T k2 = k * k;
177 T N = (k2 - v) / (1 - v);
178 T Nm1 = (1 - k2) / (1 - v);
179 T p2 = -v * N;
180 T t;
181 if (p2 <= tools::min_value<T>())
182 {
183 p2 = sqrt(-v) * sqrt(N);
184 }
185 else
186 p2 = sqrt(p2);
187 T delta = sqrt(1 - k2 * sphi * sphi);
188 if(N > k2)
189 {
190 result = ellint_pi_imp(N, phi, k, Nm1, pol);
191 result *= v / (v - 1);
192 result *= (k2 - 1) / (v - k2);
193 }
194
195 if(k != 0)
196 {
197 t = ellint_f_imp(phi, k, pol);
198 t *= k2 / (k2 - v);
199 result += t;
200 }
201 t = v / ((k2 - v) * (v - 1));
202 if(t > tools::min_value<T>())
203 {
204 result += atan((p2 / 2) * sin(2 * phi) / delta) * sqrt(t);
205 }
206 else
207 {
208 result += atan((p2 / 2) * sin(2 * phi) / delta) * sqrt(fabs(1 / (k2 - v))) * sqrt(fabs(v / (v - 1)));
209 }
210 return result;
211 }
212 if(k == 1)
213 {
214 // See http://functions.wolfram.com/08.06.03.0013.01
215 result = sqrt(v) * atanh(sqrt(v) * sin(phi), pol) - log(1 / cos(phi) + tan(phi));
216 result /= v - 1;
217 return result;
218 }
219 #if 0 // disabled but retained for future reference: see below.
220 if(v > 1)
221 {
222 //
223 // If v > 1 we can use the identity in A&S 17.7.7/8
224 // to shift to 0 <= v <= 1. In contrast to previous
225 // revisions of this header, this identity does now work
226 // but appears not to produce better error rates in
227 // practice. Archived here for future reference...
228 //
229 T k2 = k * k;
230 T N = k2 / v;
231 T Nm1 = (v - k2) / v;
232 T p1 = sqrt((-vc) * (1 - k2 / v));
233 T delta = sqrt(1 - k2 * sphi * sphi);
234 //
235 // These next two terms have a large amount of cancellation
236 // so it's not clear if this relation is useable even if
237 // the issues with phi > pi/2 can be fixed:
238 //
239 result = -ellint_pi_imp(N, phi, k, Nm1, pol);
240 result += ellint_f_imp(phi, k, pol);
241 //
242 // This log term gives the complex result when
243 // n > 1/sin^2(phi)
244 // However that case is dealt with as an error above,
245 // so we should always get a real result here:
246 //
247 result += log((delta + p1 * tan(phi)) / (delta - p1 * tan(phi))) / (2 * p1);
248 return result;
249 }
250 #endif
251 //
252 // Carlson's algorithm works only for |phi| <= pi/2,
253 // by the time we get here phi should already have been
254 // normalised above.
255 //
256 BOOST_MATH_ASSERT(fabs(phi) < constants::half_pi<T>());
257 BOOST_MATH_ASSERT(phi >= 0);
258 T x, y, z, p, t;
259 T cosp = cos(phi);
260 x = cosp * cosp;
261 t = sphi * sphi;
262 y = 1 - k * k * t;
263 z = 1;
264 if(v * t < T(0.5))
265 p = 1 - v * t;
266 else
267 p = x + vc * t;
268 result = sphi * (ellint_rf_imp(x, y, z, pol) + v * t * ellint_rj_imp(x, y, z, p, pol) / 3);
269
270 return result;
271 }
272
273 // Complete elliptic integral (Legendre form) of the third kind
274 template <typename T, typename Policy>
275 BOOST_MATH_CUDA_ENABLED T ellint_pi_imp(T v, T k, T vc, const Policy& pol)
276 {
277 // Note arg vc = 1-v, possibly without cancellation errors
278 BOOST_MATH_STD_USING
279 using namespace boost::math::tools;
280
281 constexpr auto function = "boost::math::ellint_pi<%1%>(%1%,%1%)";
282
283 if (abs(k) >= 1)
284 {
285 return policies::raise_domain_error<T>(function, "Got k = %1%, function requires |k| <= 1", k, pol);
286 }
287 if(vc <= 0)
288 {
289 // Result is complex:
290 return policies::raise_domain_error<T>(function, "Got v = %1%, function requires v < 1", v, pol);
291 }
292
293 if(v == 0)
294 {
295 return (k == 0) ? boost::math::constants::pi<T>() / 2 : boost::math::ellint_1(k, pol);
296 }
297
298 if(v < 0)
299 {
300 // Apply A&S 17.7.17:
301 T k2 = k * k;
302 T N = (k2 - v) / (1 - v);
303 T Nm1 = (1 - k2) / (1 - v);
304 T result = 0;
305 result = boost::math::detail::ellint_pi_imp(N, k, Nm1, pol);
306 // This next part is split in two to avoid spurious over/underflow:
307 result *= -v / (1 - v);
308 result *= (1 - k2) / (k2 - v);
309 result += boost::math::ellint_1(k, pol) * k2 / (k2 - v);
310 return result;
311 }
312
313 T x = 0;
314 T y = 1 - k * k;
315 T z = 1;
316 T p = vc;
317 T value = ellint_rf_imp(x, y, z, pol) + v * ellint_rj_imp(x, y, z, p, pol) / 3;
318
319 return value;
320 }
321
322 template <class T1, class T2, class T3>
323 BOOST_MATH_CUDA_ENABLED inline typename tools::promote_args<T1, T2, T3>::type ellint_3(T1 k, T2 v, T3 phi, const boost::math::false_type&)
324 {
325 return boost::math::ellint_3(k, v, phi, policies::policy<>());
326 }
327
328 template <class T1, class T2, class Policy>
329 BOOST_MATH_CUDA_ENABLED inline typename tools::promote_args<T1, T2>::type ellint_3(T1 k, T2 v, const Policy& pol, const boost::math::true_type&)
330 {
331 typedef typename tools::promote_args<T1, T2>::type result_type;
332 typedef typename policies::evaluation<result_type, Policy>::type value_type;
333 return policies::checked_narrowing_cast<result_type, Policy>(
334 detail::ellint_pi_imp(
335 static_cast<value_type>(v),
336 static_cast<value_type>(k),
337 static_cast<value_type>(1-v),
338 pol), "boost::math::ellint_3<%1%>(%1%,%1%)");
339 }
340
341 } // namespace detail
342
343 template <class T1, class T2, class T3, class Policy>
344 BOOST_MATH_CUDA_ENABLED inline typename tools::promote_args<T1, T2, T3>::type ellint_3(T1 k, T2 v, T3 phi, const Policy&)
345 {
346 typedef typename tools::promote_args<T1, T2, T3>::type result_type;
347 typedef typename policies::evaluation<result_type, Policy>::type value_type;
348 typedef typename policies::normalise<Policy, policies::promote_float<false>, policies::promote_double<false> >::type forwarding_policy;
349 return policies::checked_narrowing_cast<result_type, Policy>(
350 detail::ellint_pi_imp(
351 static_cast<value_type>(v),
352 static_cast<value_type>(phi),
353 static_cast<value_type>(k),
354 static_cast<value_type>(1-v),
355 forwarding_policy()), "boost::math::ellint_3<%1%>(%1%,%1%,%1%)");
356 }
357
358 template <class T1, class T2, class T3>
359 BOOST_MATH_CUDA_ENABLED typename detail::ellint_3_result<T1, T2, T3>::type ellint_3(T1 k, T2 v, T3 phi)
360 {
361 typedef typename policies::is_policy<T3>::type tag_type;
362 return detail::ellint_3(k, v, phi, tag_type());
363 }
364
365 template <class T1, class T2>
366 BOOST_MATH_CUDA_ENABLED inline typename tools::promote_args<T1, T2>::type ellint_3(T1 k, T2 v)
367 {
368 return ellint_3(k, v, policies::policy<>());
369 }
370
371 }} // namespaces
372
373 #endif // BOOST_MATH_ELLINT_3_HPP
374