Debian Codegraph @

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

raw
1
2 ///////////////////////////////////////////////////////////////////////////////
3 // Copyright 2014 Anton Bikineev
4 // Copyright 2014 Christopher Kormanyos
5 // Copyright 2014 John Maddock
6 // Copyright 2014 Paul Bristow
7 // Distributed under the Boost
8 // Software License, Version 1.0. (See accompanying file
9 // LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
10
11 #ifndef BOOST_HYPERGEOMETRIC_1F1_RECURRENCE_HPP_
12 #define BOOST_HYPERGEOMETRIC_1F1_RECURRENCE_HPP_
13
14 #include <boost/math/special_functions/modf.hpp>
15 #include <boost/math/special_functions/next.hpp>
16
17 #include <boost/math/tools/recurrence.hpp>
18 #include <boost/math/special_functions/detail/hypergeometric_pFq_checked_series.hpp>
19
20 namespace boost { namespace math { namespace detail {
21
22 // forward declaration for initial values
23 template <class T, class Policy>
24 inline T hypergeometric_1F1_imp(const T& a, const T& b, const T& z, const Policy& pol);
25
26 template <class T, class Policy>
27 inline T hypergeometric_1F1_imp(const T& a, const T& b, const T& z, const Policy& pol, long long& log_scaling);
28
29 template <class T>
30 struct hypergeometric_1F1_recurrence_a_coefficients
31 {
32 using result_type = boost::math::tuple<T, T, T>;
33
34 hypergeometric_1F1_recurrence_a_coefficients(const T& a, const T& b, const T& z):
35 a(a), b(b), z(z)
36 {
37 }
38
39 hypergeometric_1F1_recurrence_a_coefficients(const hypergeometric_1F1_recurrence_a_coefficients&) = default;
40
41 hypergeometric_1F1_recurrence_a_coefficients operator=(const hypergeometric_1F1_recurrence_a_coefficients&) = delete;
42
43 result_type operator()(std::intmax_t i) const
44 {
45 const T ai = a + i;
46
47 const T an = b - ai;
48 const T bn = (2 * ai - b + z);
49 const T cn = -ai;
50
51 return boost::math::make_tuple(an, bn, cn);
52 }
53
54 private:
55 const T a;
56 const T b;
57 const T z;
58 };
59
60 template <class T>
61 struct hypergeometric_1F1_recurrence_b_coefficients
62 {
63 using result_type = boost::math::tuple<T, T, T>;
64
65 hypergeometric_1F1_recurrence_b_coefficients(const T& a, const T& b, const T& z):
66 a(a), b(b), z(z)
67 {
68 }
69
70 hypergeometric_1F1_recurrence_b_coefficients(const hypergeometric_1F1_recurrence_b_coefficients&) = default;
71
72 hypergeometric_1F1_recurrence_b_coefficients& operator=(const hypergeometric_1F1_recurrence_b_coefficients&) = delete;
73
74 result_type operator()(std::intmax_t i) const
75 {
76 const T bi = b + i;
77
78 const T an = bi * (bi - 1);
79 const T bn = bi * (1 - bi - z);
80 const T cn = z * (bi - a);
81
82 return boost::math::make_tuple(an, bn, cn);
83 }
84
85 private:
86 const T a;
87 const T b;
88 const T z;
89 };
90 //
91 // for use when we're recursing to a small b:
92 //
93 template <class T>
94 struct hypergeometric_1F1_recurrence_small_b_coefficients
95 {
96 using result_type = boost::math::tuple<T, T, T>;
97
98 hypergeometric_1F1_recurrence_small_b_coefficients(const T& a, const T& b, const T& z, int N) :
99 a(a), b(b), z(z), N(N)
100 {
101 }
102
103 hypergeometric_1F1_recurrence_small_b_coefficients(const hypergeometric_1F1_recurrence_small_b_coefficients&) = default;
104
105 hypergeometric_1F1_recurrence_small_b_coefficients operator=(const hypergeometric_1F1_recurrence_small_b_coefficients&) = delete;
106
107 result_type operator()(std::intmax_t i) const
108 {
109 const T bi = b + (i + N);
110 const T bi_minus_1 = b + (i + N - 1);
111
112 const T an = bi * bi_minus_1;
113 const T bn = bi * (-bi_minus_1 - z);
114 const T cn = z * (bi - a);
115
116 return boost::math::make_tuple(an, bn, cn);
117 }
118
119 private:
120 const T a;
121 const T b;
122 const T z;
123 int N;
124 };
125
126 template <class T>
127 struct hypergeometric_1F1_recurrence_a_and_b_coefficients
128 {
129 using result_type = boost::math::tuple<T, T, T>;
130
131 hypergeometric_1F1_recurrence_a_and_b_coefficients(const T& a, const T& b, const T& z, int offset = 0):
132 a(a), b(b), z(z), offset(offset)
133 {
134 }
135
136 hypergeometric_1F1_recurrence_a_and_b_coefficients(const hypergeometric_1F1_recurrence_a_and_b_coefficients&) = default;
137
138 hypergeometric_1F1_recurrence_a_and_b_coefficients operator=(const hypergeometric_1F1_recurrence_a_and_b_coefficients&) = delete;
139
140 result_type operator()(std::intmax_t i) const
141 {
142 const T ai = a + (offset + i);
143 const T bi = b + (offset + i);
144
145 const T an = bi * (b + (offset + i - 1));
146 const T bn = bi * (z - (b + (offset + i - 1)));
147 const T cn = -ai * z;
148
149 return boost::math::make_tuple(an, bn, cn);
150 }
151
152 private:
153 const T a;
154 const T b;
155 const T z;
156 int offset;
157 };
158 #if 0
159 //
160 // These next few recurrence relations are archived for future reference, some of them are novel, though all
161 // are trivially derived from the existing well known relations:
162 //
163 // Recurrence relation for double-stepping on both a and b:
164 // - b(b-1)(b-2) / (2-b+z) M(a-2,b-2,z) + [b(a-1)z / (2-b+z) + b(1-b+z) + abz(b+1) /(b+1)(z-b)] M(a,b,z) - a(a+1)z^2 / (b+1)(z-b) M(a+2,b+2,z)
165 //
166 template <class T>
167 struct hypergeometric_1F1_recurrence_2a_and_2b_coefficients
168 {
169 typedef boost::math::tuple<T, T, T> result_type;
170
171 hypergeometric_1F1_recurrence_2a_and_2b_coefficients(const T& a, const T& b, const T& z, int offset = 0) :
172 a(a), b(b), z(z), offset(offset)
173 {
174 }
175
176 result_type operator()(std::intmax_t i) const
177 {
178 i *= 2;
179 const T ai = a + (offset + i);
180 const T bi = b + (offset + i);
181
182 const T an = -bi * (b + (offset + i - 1)) * (b + (offset + i - 2)) / (-(b + (offset + i - 2)) + z);
183 const T bn = bi * (a + (offset + i - 1)) * z / (z - (b + (offset + i - 2)))
184 + bi * (z - (b + (offset + i - 1)))
185 + ai * bi * z * (b + (offset + i + 1)) / ((b + (offset + i + 1)) * (z - bi));
186 const T cn = -ai * (a + (offset + i + 1)) * z * z / ((b + (offset + i + 1)) * (z - bi));
187
188 return boost::math::make_tuple(an, bn, cn);
189 }
190
191 private:
192 const T a, b, z;
193 int offset;
194 hypergeometric_1F1_recurrence_2a_and_2b_coefficients operator=(const hypergeometric_1F1_recurrence_2a_and_2b_coefficients&);
195 };
196
197 //
198 // Recurrence relation for double-stepping on a:
199 // -(b-a)(1 + b - a)/(2a-2-b+z)M(a-2,b,z) + [(b-a)(a-1)/(2a-2-b+z) + (2a-b+z) + a(b-a-1)/(2a+2-b+z)]M(a,b,z) -a(a+1)/(2a+2-b+z)M(a+2,b,z)
200 //
201 template <class T>
202 struct hypergeometric_1F1_recurrence_2a_coefficients
203 {
204 typedef boost::math::tuple<T, T, T> result_type;
205
206 hypergeometric_1F1_recurrence_2a_coefficients(const T& a, const T& b, const T& z, int offset = 0) :
207 a(a), b(b), z(z), offset(offset)
208 {
209 }
210
211 result_type operator()(std::intmax_t i) const
212 {
213 i *= 2;
214 const T ai = a + (offset + i);
215 // -(b-a)(1 + b - a)/(2a-2-b+z)
216 const T an = -(b - ai) * (b - (a + (offset + i - 1))) / (2 * (a + (offset + i - 1)) - b + z);
217 const T bn = (b - ai) * (a + (offset + i - 1)) / (2 * (a + (offset + i - 1)) - b + z) + (2 * ai - b + z) + ai * (b - (a + (offset + i + 1))) / (2 * (a + (offset + i + 1)) - b + z);
218 const T cn = -ai * (a + (offset + i + 1)) / (2 * (a + (offset + i + 1)) - b + z);
219
220 return boost::math::make_tuple(an, bn, cn);
221 }
222
223 private:
224 const T a, b, z;
225 int offset;
226 hypergeometric_1F1_recurrence_2a_coefficients operator=(const hypergeometric_1F1_recurrence_2a_coefficients&);
227 };
228
229 //
230 // Recurrence relation for double-stepping on b:
231 // b(b-1)^2(b-2)/((1-b)(2-b-z)) M(a,b-2,z) + [zb(b-1)(b-1-a)/((1-b)(2-b-z)) + b(1-b-z) + z(b-a)(b+1)b/((b+1)(b+z)) ] M(a,b,z) + z^2(b-a)(b+1-a)/((b+1)(b+z)) M(a,b+2,z)
232 //
233 template <class T>
234 struct hypergeometric_1F1_recurrence_2b_coefficients
235 {
236 typedef boost::math::tuple<T, T, T> result_type;
237
238 hypergeometric_1F1_recurrence_2b_coefficients(const T& a, const T& b, const T& z, int offset = 0) :
239 a(a), b(b), z(z), offset(offset)
240 {
241 }
242
243 result_type operator()(std::intmax_t i) const
244 {
245 i *= 2;
246 const T bi = b + (offset + i);
247 const T bi_m1 = b + (offset + i - 1);
248 const T bi_p1 = b + (offset + i + 1);
249 const T bi_m2 = b + (offset + i - 2);
250
251 const T an = bi * (bi_m1) * (bi_m1) * (bi_m2) / (-bi_m1 * (-bi_m2 - z));
252 const T bn = z * bi * bi_m1 * (bi_m1 - a) / (-bi_m1 * (-bi_m2 - z)) + bi * (-bi_m1 - z) + z * (bi - a) * bi_p1 * bi / (bi_p1 * (bi + z));
253 const T cn = z * z * (bi - a) * (bi_p1 - a) / (bi_p1 * (bi + z));
254
255 return boost::math::make_tuple(an, bn, cn);
256 }
257
258 private:
259 const T a, b, z;
260 int offset;
261 hypergeometric_1F1_recurrence_2b_coefficients operator=(const hypergeometric_1F1_recurrence_2b_coefficients&);
262 };
263
264 //
265 // Recurrence relation for a+ b-:
266 // -z(b-a)(a-1-b)/(b(a-1+z)) M(a-1,b+1,z) + [(b-a)(a-1)b/(b(a-1+z)) + (2a-b+z) + a(b-a-1)/(a+z)] M(a,b,z) + a(1-b)/(a+z) M(a+1,b-1,z)
267 //
268 // This is potentially the most useful of these novel recurrences.
269 // - - + - +
270 template <class T>
271 struct hypergeometric_1F1_recurrence_a_plus_b_minus_coefficients
272 {
273 typedef boost::math::tuple<T, T, T> result_type;
274
275 hypergeometric_1F1_recurrence_a_plus_b_minus_coefficients(const T& a, const T& b, const T& z, int offset = 0) :
276 a(a), b(b), z(z), offset(offset)
277 {
278 }
279
280 result_type operator()(std::intmax_t i) const
281 {
282 const T ai = a + (offset + i);
283 const T bi = b - (offset + i);
284
285 const T an = -z * (bi - ai) * (ai - 1 - bi) / (bi * (ai - 1 + z));
286 const T bn = z * ((-1 / (ai + z) - 1 / (ai + z - 1)) * (bi + z - 1) + 3) + bi - 1;
287 const T cn = ai * (1 - bi) / (ai + z);
288
289 return boost::math::make_tuple(an, bn, cn);
290 }
291
292 private:
293 const T a, b, z;
294 int offset;
295 hypergeometric_1F1_recurrence_a_plus_b_minus_coefficients operator=(const hypergeometric_1F1_recurrence_a_plus_b_minus_coefficients&);
296 };
297 #endif
298
299 template <class T, class Policy>
300 inline T hypergeometric_1F1_backward_recurrence_for_negative_a(const T& a, const T& b, const T& z, const Policy& pol, const char* function, long long& log_scaling)
301 {
302 BOOST_MATH_STD_USING // modf, frexp, fabs, pow
303
304 std::intmax_t integer_part = 0;
305 T ak = modf(a, &integer_part);
306 //
307 // We need ak-1 positive to avoid infinite recursion below:
308 //
309 if (0 != ak)
310 {
311 ak += 2;
312 integer_part -= 2;
313 }
314 if (ak - 1 == b)
315 {
316 // When ak - 1 == b are recursion coefficients disappear to zero and
317 // we end up with a NaN result. Reduce the recursion steps by 1 to
318 // avoid this. We rely on |b| small and therefore no infinite recursion.
319 ak -= 1;
320 integer_part += 1;
321 }
322
323 if (-integer_part > static_cast<std::intmax_t>(policies::get_max_series_iterations<Policy>()))
324 return policies::raise_evaluation_error<T>(function, "1F1 arguments sit in a range with a so negative that we have no evaluation method, got a = %1%", std::numeric_limits<T>::quiet_NaN(), pol);
325
326 T first {};
327 T second {};
328 if(ak == 0)
329 {
330 first = 1;
331 ak -= 1;
332 second = 1 - z / b;
333 if (fabs(second) < 0.5)
334 second = (b - z) / b; // cancellation avoidance
335 }
336 else
337 {
338 long long scaling1 {};
339 long long scaling2 {};
340 first = detail::hypergeometric_1F1_imp(ak, b, z, pol, scaling1);
341 ak -= 1;
342 second = detail::hypergeometric_1F1_imp(ak, b, z, pol, scaling2);
343 if (scaling1 != scaling2)
344 {
345 second *= exp(T(scaling2 - scaling1));
346 }
347 log_scaling += scaling1;
348 }
349 ++integer_part;
350
351 detail::hypergeometric_1F1_recurrence_a_coefficients<T> s(ak, b, z);
352
353 return tools::apply_recurrence_relation_backward(s,
354 static_cast<unsigned int>(std::abs(integer_part)),
355 first,
356 second, &log_scaling);
357 }
358
359
360 template <class T, class Policy>
361 T hypergeometric_1F1_backwards_recursion_on_b_for_negative_a(const T& a, const T& b, const T& z, const Policy& pol, const char*, long long& log_scaling)
362 {
363 using std::swap;
364 BOOST_MATH_STD_USING // modf, frexp, fabs, pow
365 //
366 // We compute
367 //
368 // M[a + a_shift, b + b_shift; z]
369 //
370 // and recurse backwards on a and b down to
371 //
372 // M[a, b, z]
373 //
374 // With a + a_shift > 1 and b + b_shift > z
375 //
376 // There are 3 distinct regions to ensure stability during the recursions:
377 //
378 // a > 0 : stable for backwards on a
379 // a < 0, b > 0 : stable for backwards on a and b
380 // a < 0, b < 0 : stable for backwards on b (as long as |b| is small).
381 //
382 // We could simplify things by ignoring the middle region, but it's more efficient
383 // to recurse on a and b together when we can.
384 //
385
386 BOOST_MATH_ASSERT(a < -1); // Not tested nor taken for -1 < a < 0
387
388 int b_shift = itrunc(z - b) + 2;
389
390 int a_shift = itrunc(-a);
391 if (a + a_shift != 0)
392 {
393 a_shift += 2;
394 }
395 //
396 // If the shifts are so large that we would throw an evaluation_error, try the series instead,
397 // even though this will almost certainly throw as well:
398 //
399 if (b_shift > static_cast<std::intmax_t>(boost::math::policies::get_max_series_iterations<Policy>()))
400 return hypergeometric_1F1_checked_series_impl(a, b, z, pol, log_scaling);
401
402 if (a_shift > static_cast<std::intmax_t>(boost::math::policies::get_max_series_iterations<Policy>()))
403 return hypergeometric_1F1_checked_series_impl(a, b, z, pol, log_scaling);
404
405 int a_b_shift = b < 0 ? itrunc(b + b_shift) : b_shift; // The max we can shift on a and b together
406 int leading_a_shift = (std::min)(3, a_shift); // Just enough to make a negative
407 if (a_b_shift > a_shift - 3)
408 {
409 a_b_shift = a_shift < 3 ? 0 : a_shift - 3;
410 }
411 else
412 {
413 // Need to ensure that leading_a_shift is large enough that a will reach it's target
414 // after the first 2 phases (-,0) and (-,-) are over:
415 leading_a_shift = a_shift - a_b_shift;
416 }
417 int trailing_b_shift = b_shift - a_b_shift;
418 if (a_b_shift < 5)
419 {
420 // Might as well do things in two steps rather than 3:
421 if (a_b_shift > 0)
422 {
423 leading_a_shift += a_b_shift;
424 trailing_b_shift += a_b_shift;
425 }
426 a_b_shift = 0;
427 --leading_a_shift;
428 }
429
430 BOOST_MATH_ASSERT(leading_a_shift > 1);
431 BOOST_MATH_ASSERT(a_b_shift + leading_a_shift + (a_b_shift == 0 ? 1 : 0) == a_shift);
432 BOOST_MATH_ASSERT(a_b_shift + trailing_b_shift == b_shift);
433
434 if ((trailing_b_shift == 0) && (fabs(b) < 0.5) && a_b_shift)
435 {
436 // Better to have the final recursion on b alone, otherwise we lose precision when b is very small:
437 int diff = (std::min)(a_b_shift, 3);
438 a_b_shift -= diff;
439 leading_a_shift += diff;
440 trailing_b_shift += diff;
441 }
442
443 T first {};
444 T second {};
445 long long scale1 {};
446 long long scale2 {};
447 first = boost::math::detail::hypergeometric_1F1_imp(T(a + a_shift), T(b + b_shift), z, pol, scale1);
448 //
449 // It would be good to compute "second" from first and the ratio - unfortunately we are right on the cusp
450 // recursion on a switching from stable backwards to stable forwards behaviour and so this is not possible here.
451 //
452 second = boost::math::detail::hypergeometric_1F1_imp(T(a + a_shift - 1), T(b + b_shift), z, pol, scale2);
453 if (scale1 != scale2)
454 second *= exp(T(scale2 - scale1));
455 log_scaling += scale1;
456
457 //
458 // Now we have [a + a_shift, b + b_shift, z] and [a + a_shift - 1, b + b_shift, z]
459 // and want to recurse until [a + a_shift - leading_a_shift, b + b_shift, z] and [a + a_shift - leadng_a_shift - 1, b + b_shift, z]
460 // which is leading_a_shift -1 steps.
461 //
462 second = boost::math::tools::apply_recurrence_relation_backward(
463 hypergeometric_1F1_recurrence_a_coefficients<T>(a + a_shift - 1, b + b_shift, z),
464 leading_a_shift, first, second, &log_scaling, &first);
465
466 if (a_b_shift)
467 {
468 //
469 // Now we need to switch to an a+b shift so that we have:
470 // [a + a_shift - leading_a_shift, b + b_shift, z] and [a + a_shift - leadng_a_shift - 1, b + b_shift - 1, z]
471 // A&S 13.4.3 gives us what we need:
472 //
473 {
474 // local a's and b's:
475 T la = a + a_shift - leading_a_shift - 1;
476 T lb = b + b_shift;
477 second = ((1 + la - lb) * second - la * first) / (1 - lb);
478 }
479 //
480 // Now apply a_b_shift - 1 recursions to get down to
481 // [a + 1, b + trailing_b_shift + 1, z] and [a, b + trailing_b_shift, z]
482 //
483 second = boost::math::tools::apply_recurrence_relation_backward(
484 hypergeometric_1F1_recurrence_a_and_b_coefficients<T>(a, b + b_shift - a_b_shift, z, a_b_shift - 1),
485 a_b_shift - 1, first, second, &log_scaling, &first);
486 //
487 // Now we need to switch to a b shift, a different application of A&S 13.4.3
488 // will get us there, we leave "second" where it is, and move "first" sideways:
489 //
490 {
491 T lb = b + trailing_b_shift + 1;
492 first = (second * (lb - 1) - a * first) / -(1 + a - lb);
493 }
494 }
495 else
496 {
497 //
498 // We have M[a+1, b+b_shift, z] and M[a, b+b_shift, z] and need M[a, b+b_shift-1, z] for
499 // recursion on b: A&S 13.4.3 gives us what we need.
500 //
501 T third = -(second * (1 + a - b - b_shift) - first * a) / (b + b_shift - 1);
502 swap(first, second);
503 swap(second, third);
504 --trailing_b_shift;
505 }
506 //
507 // Finish off by applying trailing_b_shift recursions:
508 //
509 if (trailing_b_shift)
510 {
511 second = boost::math::tools::apply_recurrence_relation_backward(
512 hypergeometric_1F1_recurrence_small_b_coefficients<T>(a, b, z, trailing_b_shift),
513 trailing_b_shift, first, second, &log_scaling);
514 }
515 return second;
516 }
517
518
519
520 } } } // namespaces
521
522 #endif // BOOST_HYPERGEOMETRIC_1F1_RECURRENCE_HPP_