Debian Codegraph @

third-party/boost-math/include/boost/math/special_functions/detail/bessel_ik.hpp

raw
1 // Copyright (c) 2006 Xiaogang Zhang
2 // Copyright (c) 2024 Matt Borland
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 #ifndef BOOST_MATH_BESSEL_IK_HPP
8 #define BOOST_MATH_BESSEL_IK_HPP
9
10 #ifdef _MSC_VER
11 #pragma once
12 #endif
13
14 #include <boost/math/tools/config.hpp>
15 #include <boost/math/tools/cstdint.hpp>
16 #include <boost/math/tools/numeric_limits.hpp>
17 #include <boost/math/tools/type_traits.hpp>
18 #include <boost/math/tools/series.hpp>
19 #include <boost/math/special_functions/sign.hpp>
20 #include <boost/math/special_functions/round.hpp>
21 #include <boost/math/special_functions/gamma.hpp>
22 #include <boost/math/special_functions/sin_pi.hpp>
23 #include <boost/math/constants/constants.hpp>
24 #include <boost/math/policies/error_handling.hpp>
25
26 // Modified Bessel functions of the first and second kind of fractional order
27
28 namespace boost { namespace math {
29
30 namespace detail {
31
32 template <class T, class Policy>
33 struct cyl_bessel_i_small_z
34 {
35 typedef T result_type;
36
37 BOOST_MATH_GPU_ENABLED cyl_bessel_i_small_z(T v_, T z_) : k(0), v(v_), mult(z_*z_/4)
38 {
39 BOOST_MATH_STD_USING
40 term = 1;
41 }
42
43 BOOST_MATH_GPU_ENABLED T operator()()
44 {
45 T result = term;
46 ++k;
47 term *= mult / k;
48 term /= k + v;
49 return result;
50 }
51 private:
52 unsigned k;
53 T v;
54 T term;
55 T mult;
56 };
57
58 template <class T, class Policy>
59 BOOST_MATH_GPU_ENABLED inline T bessel_i_small_z_series(T v, T x, const Policy& pol)
60 {
61 BOOST_MATH_STD_USING
62 T prefix;
63 if(v < max_factorial<T>::value)
64 {
65 prefix = pow(x / 2, v) / boost::math::tgamma(v + 1, pol);
66 }
67 else
68 {
69 prefix = v * log(x / 2) - boost::math::lgamma(v + 1, pol);
70 prefix = exp(prefix);
71 }
72 if(prefix == 0)
73 return prefix;
74
75 cyl_bessel_i_small_z<T, Policy> s(v, x);
76 boost::math::uintmax_t max_iter = policies::get_max_series_iterations<Policy>();
77
78 T result = boost::math::tools::sum_series(s, boost::math::policies::get_epsilon<T, Policy>(), max_iter);
79
80 policies::check_series_iterations<T>("boost::math::bessel_j_small_z_series<%1%>(%1%,%1%)", max_iter, pol);
81 return prefix * result;
82 }
83
84 // Calculate K(v, x) and K(v+1, x) by method analogous to
85 // Temme, Journal of Computational Physics, vol 21, 343 (1976)
86 template <typename T, typename Policy>
87 BOOST_MATH_GPU_ENABLED int temme_ik(T v, T x, T* result_K, T* K1, const Policy& pol)
88 {
89 T f, h, p, q, coef, sum, sum1, tolerance;
90 T a, b, c, d, sigma, gamma1, gamma2;
91 unsigned long k;
92
93 BOOST_MATH_STD_USING
94 using namespace boost::math::tools;
95 using namespace boost::math::constants;
96
97
98 // |x| <= 2, Temme series converge rapidly
99 // |x| > 2, the larger the |x|, the slower the convergence
100 BOOST_MATH_ASSERT(abs(x) <= 2);
101 BOOST_MATH_ASSERT(abs(v) <= 0.5f);
102
103 T gp = boost::math::tgamma1pm1(v, pol);
104 T gm = boost::math::tgamma1pm1(-v, pol);
105
106 a = log(x / 2);
107 b = exp(v * a);
108 sigma = -a * v;
109 c = abs(v) < tools::epsilon<T>() ?
110 T(1) : T(boost::math::sin_pi(v, pol) / (v * pi<T>()));
111 d = abs(sigma) < tools::epsilon<T>() ?
112 T(1) : T(sinh(sigma) / sigma);
113 gamma1 = abs(v) < tools::epsilon<T>() ?
114 T(-euler<T>()) : T((0.5f / v) * (gp - gm) * c);
115 gamma2 = (2 + gp + gm) * c / 2;
116
117 // initial values
118 p = (gp + 1) / (2 * b);
119 q = (1 + gm) * b / 2;
120 f = (cosh(sigma) * gamma1 + d * (-a) * gamma2) / c;
121 h = p;
122 coef = 1;
123 sum = coef * f;
124 sum1 = coef * h;
125
126 BOOST_MATH_INSTRUMENT_VARIABLE(p);
127 BOOST_MATH_INSTRUMENT_VARIABLE(q);
128 BOOST_MATH_INSTRUMENT_VARIABLE(f);
129 BOOST_MATH_INSTRUMENT_VARIABLE(sigma);
130 BOOST_MATH_INSTRUMENT_CODE(sinh(sigma));
131 BOOST_MATH_INSTRUMENT_VARIABLE(gamma1);
132 BOOST_MATH_INSTRUMENT_VARIABLE(gamma2);
133 BOOST_MATH_INSTRUMENT_VARIABLE(c);
134 BOOST_MATH_INSTRUMENT_VARIABLE(d);
135 BOOST_MATH_INSTRUMENT_VARIABLE(a);
136
137 // series summation
138 tolerance = tools::epsilon<T>();
139 for (k = 1; k < policies::get_max_series_iterations<Policy>(); k++)
140 {
141 f = (k * f + p + q) / (k*k - v*v);
142 p /= k - v;
143 q /= k + v;
144 h = p - k * f;
145 coef *= x * x / (4 * k);
146 sum += coef * f;
147 sum1 += coef * h;
148 if (abs(coef * f) < abs(sum) * tolerance)
149 {
150 break;
151 }
152 }
153 policies::check_series_iterations<T>("boost::math::bessel_ik<%1%>(%1%,%1%) in temme_ik", k, pol);
154
155 *result_K = sum;
156 *K1 = 2 * sum1 / x;
157
158 return 0;
159 }
160
161 // Evaluate continued fraction fv = I_(v+1) / I_v, derived from
162 // Abramowitz and Stegun, Handbook of Mathematical Functions, 1972, 9.1.73
163 template <typename T, typename Policy>
164 BOOST_MATH_GPU_ENABLED int CF1_ik(T v, T x, T* fv, const Policy& pol)
165 {
166 T C, D, f, a, b, delta, tiny, tolerance;
167 unsigned long k;
168
169 BOOST_MATH_STD_USING
170
171 // |x| <= |v|, CF1_ik converges rapidly
172 // |x| > |v|, CF1_ik needs O(|x|) iterations to converge
173
174 // modified Lentz's method, see
175 // Lentz, Applied Optics, vol 15, 668 (1976)
176 tolerance = 2 * tools::epsilon<T>();
177 BOOST_MATH_INSTRUMENT_VARIABLE(tolerance);
178 tiny = sqrt(tools::min_value<T>());
179 BOOST_MATH_INSTRUMENT_VARIABLE(tiny);
180 C = f = tiny; // b0 = 0, replace with tiny
181 D = 0;
182 for (k = 1; k < policies::get_max_series_iterations<Policy>(); k++)
183 {
184 a = 1;
185 b = 2 * (v + k) / x;
186 C = b + a / C;
187 D = b + a * D;
188 if (C == 0) { C = tiny; }
189 if (D == 0) { D = tiny; }
190 D = 1 / D;
191 delta = C * D;
192 f *= delta;
193 BOOST_MATH_INSTRUMENT_VARIABLE(delta-1);
194 if (abs(delta - 1) <= tolerance)
195 {
196 break;
197 }
198 }
199 BOOST_MATH_INSTRUMENT_VARIABLE(k);
200 policies::check_series_iterations<T>("boost::math::bessel_ik<%1%>(%1%,%1%) in CF1_ik", k, pol);
201
202 *fv = f;
203
204 return 0;
205 }
206
207 // Calculate K(v, x) and K(v+1, x) by evaluating continued fraction
208 // z1 / z0 = U(v+1.5, 2v+1, 2x) / U(v+0.5, 2v+1, 2x), see
209 // Thompson and Barnett, Computer Physics Communications, vol 47, 245 (1987)
210 template <typename T, typename Policy>
211 BOOST_MATH_GPU_ENABLED int CF2_ik(T v, T x, T* Kv, T* Kv1, const Policy& pol)
212 {
213 BOOST_MATH_STD_USING
214 using namespace boost::math::constants;
215
216 T S, C, Q, D, f, a, b, q, delta, tolerance, current, prev;
217 unsigned long k;
218
219 // |x| >= |v|, CF2_ik converges rapidly
220 // |x| -> 0, CF2_ik fails to converge
221
222 BOOST_MATH_ASSERT(abs(x) > 1);
223
224 // Steed's algorithm, see Thompson and Barnett,
225 // Journal of Computational Physics, vol 64, 490 (1986)
226 tolerance = tools::epsilon<T>();
227 a = v * v - 0.25f;
228 b = 2 * (x + 1); // b1
229 D = 1 / b; // D1 = 1 / b1
230 f = delta = D; // f1 = delta1 = D1, coincidence
231 prev = 0; // q0
232 current = 1; // q1
233 Q = C = -a; // Q1 = C1 because q1 = 1
234 S = 1 + Q * delta; // S1
235 BOOST_MATH_INSTRUMENT_VARIABLE(tolerance);
236 BOOST_MATH_INSTRUMENT_VARIABLE(a);
237 BOOST_MATH_INSTRUMENT_VARIABLE(b);
238 BOOST_MATH_INSTRUMENT_VARIABLE(D);
239 BOOST_MATH_INSTRUMENT_VARIABLE(f);
240
241 for (k = 2; k < policies::get_max_series_iterations<Policy>(); k++) // starting from 2
242 {
243 // continued fraction f = z1 / z0
244 a -= 2 * (k - 1);
245 b += 2;
246 D = 1 / (b + a * D);
247 delta *= b * D - 1;
248 f += delta;
249
250 // series summation S = 1 + \sum_{n=1}^{\infty} C_n * z_n / z_0
251 q = (prev - (b - 2) * current) / a;
252 prev = current;
253 current = q; // forward recurrence for q
254 C *= -a / k;
255 Q += C * q;
256 S += Q * delta;
257 //
258 // Under some circumstances q can grow very small and C very
259 // large, leading to under/overflow. This is particularly an
260 // issue for types which have many digits precision but a narrow
261 // exponent range. A typical example being a "double double" type.
262 // To avoid this situation we can normalise q (and related prev/current)
263 // and C. All other variables remain unchanged in value. A typical
264 // test case occurs when x is close to 2, for example cyl_bessel_k(9.125, 2.125).
265 //
266 if(q < tools::epsilon<T>())
267 {
268 C *= q;
269 prev /= q;
270 current /= q;
271 q = 1;
272 }
273
274 // S converges slower than f
275 BOOST_MATH_INSTRUMENT_VARIABLE(Q * delta);
276 BOOST_MATH_INSTRUMENT_VARIABLE(abs(S) * tolerance);
277 BOOST_MATH_INSTRUMENT_VARIABLE(S);
278 if (abs(Q * delta) < abs(S) * tolerance)
279 {
280 break;
281 }
282 }
283 policies::check_series_iterations<T>("boost::math::bessel_ik<%1%>(%1%,%1%) in CF2_ik", k, pol);
284
285 if(-x < tools::log_min_value<T>())
286 *Kv = exp(0.5f * log(pi<T>() / (2 * x)) - x - log(S));
287 else
288 *Kv = sqrt(pi<T>() / (2 * x)) * exp(-x) / S;
289 *Kv1 = *Kv * (0.5f + v + x + (v * v - 0.25f) * f) / x;
290 BOOST_MATH_INSTRUMENT_VARIABLE(*Kv);
291 BOOST_MATH_INSTRUMENT_VARIABLE(*Kv1);
292
293 return 0;
294 }
295
296 enum{
297 need_i = 1,
298 need_k = 2
299 };
300
301 // Compute I(v, x) and K(v, x) simultaneously by Temme's method, see
302 // Temme, Journal of Computational Physics, vol 19, 324 (1975)
303 template <typename T, typename Policy>
304 BOOST_MATH_GPU_ENABLED int bessel_ik(T v, T x, T* result_I, T* result_K, int kind, const Policy& pol)
305 {
306 // Kv1 = K_(v+1), fv = I_(v+1) / I_v
307 // Ku1 = K_(u+1), fu = I_(u+1) / I_u
308 T u, Iv, Kv, Kv1, Ku, Ku1, fv;
309 T W, current, prev, next;
310 bool reflect = false;
311 unsigned n, k;
312 int org_kind = kind;
313 BOOST_MATH_INSTRUMENT_VARIABLE(v);
314 BOOST_MATH_INSTRUMENT_VARIABLE(x);
315 BOOST_MATH_INSTRUMENT_VARIABLE(kind);
316
317 BOOST_MATH_STD_USING
318 using namespace boost::math::tools;
319 using namespace boost::math::constants;
320
321 constexpr auto function = "boost::math::bessel_ik<%1%>(%1%,%1%)";
322
323 if (v < 0)
324 {
325 reflect = true;
326 v = -v; // v is non-negative from here
327 kind |= need_k;
328 }
329
330 T scale = 1;
331 T scale_sign = 1;
332
333 n = iround(v, pol);
334 u = v - n; // -1/2 <= u < 1/2
335 BOOST_MATH_INSTRUMENT_VARIABLE(n);
336 BOOST_MATH_INSTRUMENT_VARIABLE(u);
337
338 if (((kind & need_i) == 0) && (fabs(4 * v * v - 25) / (8 * x) < tools::forth_root_epsilon<T>()))
339 {
340 // A&S 9.7.2
341 Iv = boost::math::numeric_limits<T>::quiet_NaN(); // any value will do
342 T mu = 4 * v * v;
343 T eight_z = 8 * x;
344 Kv = 1 + (mu - 1) / eight_z + (mu - 1) * (mu - 9) / (2 * eight_z * eight_z) + (mu - 1) * (mu - 9) * (mu - 25) / (6 * eight_z * eight_z * eight_z);
345 Kv *= exp(-x) * constants::root_pi<T>() / sqrt(2 * x);
346 }
347 else
348 {
349 BOOST_MATH_ASSERT(x > 0); // Error handling for x <= 0 handled in cyl_bessel_i and cyl_bessel_k
350
351 // x is positive until reflection
352 W = 1 / x; // Wronskian
353 if (x <= 2) // x in (0, 2]
354 {
355 temme_ik(u, x, &Ku, &Ku1, pol); // Temme series
356 }
357 else // x in (2, \infty)
358 {
359 CF2_ik(u, x, &Ku, &Ku1, pol); // continued fraction CF2_ik
360 }
361 BOOST_MATH_INSTRUMENT_VARIABLE(Ku);
362 BOOST_MATH_INSTRUMENT_VARIABLE(Ku1);
363 prev = Ku;
364 current = Ku1;
365 for (k = 1; k <= n; k++) // forward recurrence for K
366 {
367 T fact = 2 * (u + k) / x;
368 // Check for overflow: if (max - |prev|) / fact > max, then overflow
369 // (max - |prev|) / fact > max
370 // max * (1 - fact) > |prev|
371 // if fact < 1: safe to compute overflow check
372 // if fact >= 1: won't overflow
373 const bool will_overflow = (fact < 1)
374 ? tools::max_value<T>() * (1 - fact) > fabs(prev)
375 : false;
376 if (!will_overflow && ((tools::max_value<T>() - fabs(prev)) / fact < fabs(current)))
377 {
378 prev /= current;
379 scale /= current;
380 scale_sign *= ((boost::math::signbit)(current) ? -1 : 1);
381 current = 1;
382 }
383 next = fact * current + prev;
384 prev = current;
385 current = next;
386 }
387 Kv = prev;
388 Kv1 = current;
389 BOOST_MATH_INSTRUMENT_VARIABLE(Kv);
390 BOOST_MATH_INSTRUMENT_VARIABLE(Kv1);
391 if (kind & need_i)
392 {
393 T lim = (4 * v * v + 10) / (8 * x);
394 lim *= lim;
395 lim *= lim;
396 lim /= 24;
397 if ((lim < tools::epsilon<T>() * 10) && (x > 100))
398 {
399 // x is huge compared to v, CF1 may be very slow
400 // to converge so use asymptotic expansion for large
401 // x case instead. Note that the asymptotic expansion
402 // isn't very accurate - so it's deliberately very hard
403 // to get here - probably we're going to overflow:
404 Iv = asymptotic_bessel_i_large_x(v, x, pol);
405 }
406 else if ((v > 0) && (x / v < 0.25))
407 {
408 Iv = bessel_i_small_z_series(v, x, pol);
409 }
410 else
411 {
412 CF1_ik(v, x, &fv, pol); // continued fraction CF1_ik
413 Iv = scale * W / (Kv * fv + Kv1); // Wronskian relation
414 }
415 }
416 else
417 Iv = boost::math::numeric_limits<T>::quiet_NaN(); // any value will do
418 }
419 if (reflect && (kind & need_i))
420 {
421 BOOST_MATH_ASSERT(fabs(v - n - u) < tools::forth_root_epsilon<T>());
422 T z = (u + n % 2);
423 T fact = (2 / pi<T>()) * (boost::math::sin_pi(z, pol) * Kv);
424 if(fact == 0)
425 *result_I = Iv;
426 else if(tools::max_value<T>() * scale < fact)
427 *result_I = (org_kind & need_i) ? T(sign(fact) * scale_sign * policies::raise_overflow_error<T>(function, nullptr, pol)) : T(0);
428 else
429 *result_I = Iv + fact / scale; // reflection formula
430 }
431 else
432 {
433 *result_I = Iv;
434 }
435 if(tools::max_value<T>() * scale < Kv)
436 *result_K = (org_kind & need_k) ? T(sign(Kv) * scale_sign * policies::raise_overflow_error<T>(function, nullptr, pol)) : T(0);
437 else
438 *result_K = Kv / scale;
439 BOOST_MATH_INSTRUMENT_VARIABLE(*result_I);
440 BOOST_MATH_INSTRUMENT_VARIABLE(*result_K);
441 return 0;
442 }
443
444 }}} // namespaces
445
446 #endif // BOOST_MATH_BESSEL_IK_HPP
447