NAG FL Interface
s22bbf (hyperg_​confl_​real_​scaled)

Settings help

FL Name Style:


FL Specification Language:


1 Purpose

s22bbf returns a value for the confluent hypergeometric function F 1 1 (a;b;x) , with real parameters a and b and real argument x. The solution is returned in the scaled form F 1 1 (a;b;x) = mf × 2ms . This function is sometimes also known as Kummer's function M(a,b,x).

2 Specification

Fortran Interface
Subroutine s22bbf ( ani, adr, bni, bdr, x, frm, scm, ifail)
Integer, Intent (Inout) :: ifail
Integer, Intent (Out) :: scm
Real (Kind=nag_wp), Intent (In) :: ani, adr, bni, bdr, x
Real (Kind=nag_wp), Intent (Out) :: frm
C Header Interface
#include <nag.h>
void  s22bbf_ (const double *ani, const double *adr, const double *bni, const double *bdr, const double *x, double *frm, Integer *scm, Integer *ifail)
The routine may be called by the names s22bbf or nagf_specfun_hyperg_confl_real_scaled.

3 Description

s22bbf returns a value for the confluent hypergeometric function F1 1 (a;b;x) , with real parameters a and b and real argument x, in the scaled form F1 1 (a;b;x) = mf × 2 ms , where mf is the real scaled component and ms is the integer power of two scaling. This function is unbounded or not uniquely defined for b equal to zero or a negative integer.
The confluent hypergeometric function is defined by the confluent series,
F1 1 (a;b;x) = M(a,b,x) = s=0 (a)s xs (b)s s! = 1 + a b x + a(a+1) b(b+1) 2! x2 +  
where (a)s = 1 (a) (a+1) (a+2) (a+s-1) is the rising factorial of a . M(a,b,x) is a solution to the second order ODE (Kummer's Equation):
x d2M dx2 + (b-x) dM dx - a M = 0 . (1)
Given the parameters and argument (a,b,x) , this routine determines a set of safe values {(αi,βi,ζi)i2} and selects an appropriate algorithm to accurately evaluate the functions Mi (αi,βi,ζi) . The result is then used to construct the solution to the original problem M(a,b,x) using, where necessary, recurrence relations and/or continuation.
For improved precision in the final result, this routine accepts a and b split into an integral and a decimal fractional component. Specifically a=ai+ar, where |ar|0.5 and ai=a-ar is integral. b is similarly deconstructed.
Additionally, an artificial bound, arbnd is placed on the magnitudes of ai, bi and x to minimize the occurrence of overflow in internal calculations. arbnd = 0.0001 × Imax , where Imax=x02bbf. It should, however, not be assumed that this routine will produce an accurate result for all values of ai, bi and x satisfying this criterion.
Please consult the NIST Digital Library of Mathematical Functions for a detailed discussion of the confluent hypergeometric function including special cases, transformations, relations and asymptotic approximations.

4 References

NIST Digital Library of Mathematical Functions
Pearson J (2009) Computation of hypergeometric functions MSc Dissertation, Mathematical Institute, University of Oxford

5 Arguments

1: ani Real (Kind=nag_wp) Input
On entry: ai, the nearest integer to a, satisfying ai = a-ar.
Constraints:
  • ani=ani;
  • |ani|arbnd.
2: adr Real (Kind=nag_wp) Input
On entry: ar, the signed decimal remainder satisfying ar = a-ai and |ar| 0.5.
Constraint: |adr|0.5.
Note: if |adr|<100.0ε, ar=0.0 will be used, where ε is the machine precision as returned by x02ajf.
3: bni Real (Kind=nag_wp) Input
On entry: bi, the nearest integer to b, satisfying bi=b-br.
Constraints:
  • bni=bni;
  • |bni|arbnd;
  • if bdr=0.0, bni>0.
4: bdr Real (Kind=nag_wp) Input
On entry: br, the signed decimal remainder satisfying br = b-bi and |br| 0.5.
Constraint: |bdr|0.5.
Note: if |bdr-adr|<100.0ε, ar=br will be used, where ε is the machine precision as returned by x02ajf.
5: x Real (Kind=nag_wp) Input
On entry: the argument x of the function.
Constraint: |x|arbnd.
6: frm Real (Kind=nag_wp) Output
On exit: mf, the scaled real component of the solution satisfying mf=M(a,b,x)×2-ms.
Note: if overflow occurs upon completion, as indicated by ifail=2, the value of mf returned may still be correct. If overflow occurs in a subcalculation, as indicated by ifail=5, this should not be assumed.
7: scm Integer Output
On exit: ms, the scaling power of two, satisfying ms= log2( M(a,b,x) mf ).
Note: if overflow occurs upon completion, as indicated by ifail=2, then msImax, where Imax is the largest representable integer (see x02bbf). If overflow occurs during a subcalculation, as indicated by ifail=5, ms may or may not be greater than Imax. In either case, scm=x02bbf will have been returned.
8: ifail Integer Input/Output
On entry: ifail must be set to 0, -1 or 1 to set behaviour on detection of an error; these values have no effect when no error is detected.
A value of 0 causes the printing of an error message and program execution will be halted; otherwise program execution continues. A value of -1 means that an error message is printed while a value of 1 means that it is not.
If halting is not appropriate, the value -1 or 1 is recommended. If message printing is undesirable, then the value 1 is recommended. Otherwise, the value 0 is recommended. When the value -1 or 1 is used it is essential to test the value of ifail on exit.
On exit: ifail=0 unless the routine detects an error or a warning has been flagged (see Section 6).

6 Error Indicators and Warnings

If on entry ifail=0 or -1, explanatory error messages are output on the current error message unit (as defined by x04aaf).
Errors or warnings detected by the routine:
ifail=1
Underflow occurred during the evaluation of M(a,b,x).
The returned value may be inaccurate.
ifail=2
On completion, overflow occurred in the evaluation of M(a,b,x).
ifail=3
All approximations have completed, and the final residual estimate indicates some precision may have been lost.
Relative residual =value.
ifail=4
All approximations have completed, and the final residual estimate indicates no accuracy can be guaranteed.
Relative residual =value.
ifail=5
Overflow occurred in a subcalculation of M(a,b,x).
The answer may be completely incorrect.
ifail=11
On entry, ani=value.
Constraint: |ani|arbnd=value.
ifail=13
ani is non-integral.
On entry, ani=value.
Constraint: ani=ani.
ifail=21
On entry, adr=value.
Constraint: |adr|0.5.
ifail=31
On entry, bni=value.
Constraint: |bni|arbnd=value.
ifail=32
On entry, b=bni+bdr=value.
M(a,b,x) is undefined when b is zero or a negative integer.
ifail=33
bni is non-integral.
On entry, bni=value.
Constraint: bni=bni.
ifail=41
On entry, bdr=value.
Constraint: |bdr|0.5.
ifail=51
On entry, x=value.
Constraint: |x|arbnd=value.
ifail=-99
An unexpected error has been triggered by this routine. Please contact NAG.
See Section 7 in the Introduction to the NAG Library FL Interface for further information.
ifail=-399
Your licence key may have expired or may not have been installed correctly.
See Section 8 in the Introduction to the NAG Library FL Interface for further information.
ifail=-999
Dynamic memory allocation failed.
See Section 9 in the Introduction to the NAG Library FL Interface for further information.

7 Accuracy

In general, if ifail=0, the value of M may be assumed accurate, with the possible loss of one or two decimal places. Assuming the result does not under or overflow, an error estimate res is made internally using equation (1). If the magnitude of res is sufficiently large a nonzero ifail will be returned. Specifically,
ifail=0 res1000ε
ifail=3 1000ε<res0.1
ifail=4 res>0.1
A further estimate of the residual can be constructed using equation (1), and the differential identity,
d M(a,b,x) dx = ab M (a+1,b+1,x) , d2 M(a,b,x) dx2 = a(a+1) b(b+1) M (a+2,b+2,x) .  
This estimate is however, dependent upon the error involved in approximating M (a+1,b+1,x) and M (a+2,b+2,x) .

8 Parallelism and Performance

s22bbf is threaded by NAG for parallel execution in multithreaded implementations of the NAG Library.
s22bbf makes calls to BLAS and/or LAPACK routines, which may be threaded within the vendor library used by this implementation. Consult the documentation for the vendor library for further information.
Please consult the X06 Chapter Introduction for information on how to control and interrogate the OpenMP environment used within this routine. Please also consult the Users' Note for your implementation for any additional implementation-specific information.

9 Further Comments

The values of mf and ms are implementation dependent. In most cases, if F 1 1 (a;b;x) = 0 , m f = 0 and m s = 0 will be returned, and if F 1 1 (a;b;x) = 0 is finite, the fractional component will be bound by 0.5 | m f | < 1, with m s chosen accordingly.
The values returned in frm (mf) and scm (ms) may be used to explicitly evaluate M(a,b,x), and may also be used to evaluate products and ratios of multiple values of M as follows,
M(a,b,x) = mf × 2ms M (a1,b1,x1) × M (a2,b2,x2) = (mf1×mf2) × 2 (ms1+ms2) M (a1,b1,x1) M (a2,b2,x2) = mf1 mf2 × 2 (ms1-ms2) ln|M(a,b,x)| = ln|mf| + ms × ln(2) .  

10 Example

This example evaluates the confluent hypergeometric function at two points in scaled form using s22bbf, and subsequently calculates their product and ratio without having to explicitly construct M.

10.1 Program Text

Program Text (s22bbfe.f90)

10.2 Program Data

None.

10.3 Program Results

Program Results (s22bbfe.r)