NAG Library Routine Document

S22BBF

+− Contents

1 Purpose

2 Specification

3 Description

4 References

5 Parameters

6 Error Indicators and Warnings

7 Accuracy

8 Further Comments

+− 9 Example

9.1 Program Text

9.2 Program Data

9.3 Program Results

1 Purpose

S22BBF returns a value for the confluent hypergeometric function

{}_{1}F_{1} (a; b; x)

with real parameters

a

b

and

x

in the scaled form

{}_{1}F_{1} (a; b; x) = m_{f} \times 2^{m_{s}}

. This function is sometimes also known as Kummer's function

M (a, b, x)

2 Specification

SUBROUTINE S22BBF (

ANI, ADR, BNI, BDR, X, FRM, SCM, IFAIL)

INTEGER	SCM, IFAIL
REAL (KIND=nag_wp)	ANI, ADR, BNI, BDR, X, FRM

3 Description

S22BBF returns a value for the confluent hypergeometric function

{}_{1}F_{1} (a; b; x)

with real parameters

a

b

and

x

in the scaled form

{}_{1}F_{1} (a; b; x) = m_{f} \times 2^{m_{s}}

, where

m_{f}

is the real scaled component and

m_{s}

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

{}_{1}F_{1} (a; b; x) = M (a, b, x) = \sum_{s = 0}^{\infty} \frac{{(a)}_{s} x^{s}}{{(b)}_{s} s!} = 1 + \frac{a}{b} x + \frac{a (a + 1)}{b (b + 1) 2!} x^{2} + \dots

where

{(a)}_{s} = 1 (a) (a + 1) (a + 2) \dots (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 \frac{d^{2} M}{d x^{2}} + (b - x) \frac{d M}{d x} - a M = 0 .

(1)

Given the parameters

(a, b, x)

, this routine determines a set of safe parameters

\{(α_{i}, β_{i}, ζ_{i}) ∣ i \leq 2\}

and selects an appropriate algorithm to accurately evaluate the functions

M_{i} (α_{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 = a_{i} + a_{r}

, where

|a_{r}| \leq 0.5

and

a_{i} = a - a_{r}

is integral.

b

is similarly deconstructed.

Additionally, an artificial bound,

arbnd

is placed on the magnitudes of

a_{i}

b_{i}

and

x

to minimize the occurrence of overflow in internal calculations.

arbnd = 0.0001 \times I_{\max}

, where

I_{\max} = X02BBF

. It should, however, not be assumed that this routine will produce an accurate result for all values of

a_{i}

b_{i}

and

x

satisfying this criterion.

Please consult the NIST Digital Library of Mathematical Functions or the companion (2010) for a detailed discussion of the confluent hypergeometric function including special cases, transformations, relations and asymptotic approximations.

4 References

NIST Handbook of Mathematical Functions (2010) (eds F W J Olver, D W Lozier, R F Boisvert, C W Clark) Cambridge University Press

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

5 Parameters

1: ANI – REAL (KIND=nag_wp)Input

On entry:

a_{i}

, the nearest integer to

a

, satisfying

a_{i} = a - a_{r}

Constraints:

$ANI = ⌊ANI⌋$ ;
$|ANI| \leq arbnd$ .

2: ADR – REAL (KIND=nag_wp)Input

On entry:

a_{r}

, the signed decimal remainder satisfying

a_{r} = a - a_{i}

and

|a_{r}| \leq 0.5

Constraint:

|ADR| \leq 0.5

Note: if

|ADR| < 100.0 ε

a_{r} = 0.0

will be used, where

ε

is the machine precision as returned by X02AJF.

3: BNI – REAL (KIND=nag_wp)Input

On entry:

b_{i}

, the nearest integer to

b

, satisfying

b_{i} = b - b_{r}

Constraints:

$BNI = ⌊BNI⌋$ ;
$|BNI| \leq arbnd$ ;
if $BDR = 0.0$ , $BNI > 0$ .

4: BDR – REAL (KIND=nag_wp)Input

On entry:

b_{r}

, the signed decimal remainder satisfying

b_{r} = b - b_{i}

and

|b_{r}| \leq 0.5

Constraint:

|BDR| \leq 0.5

Note: if

|BDR - ADR| < 100.0 ε

a_{r} = b_{r}

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| \leq arbnd

6: FRM – REAL (KIND=nag_wp)Output

On exit:

m_{f}

, the scaled real component of the solution satisfying

m_{f} = M (a, b, x) \times 2^{- m_{s}}

Note: if overflow occurs upon completion, as indicated by

IFAIL = 2

, the value of

m_{f}

returned may still be correct. If overflow occurs in a subcalculation, as indicated by

IFAIL = 5

, this should not be assumed.

7: SCM – INTEGEROutput

On exit:

m_{s}

, the scaling power of two, satisfying

m_{s} = \log_{2} (\frac{M (a, b, x)}{m_{f}})

Note: if overflow occurs upon completion, as indicated by

IFAIL = 2

, then

m_{s} \geq I_{\max}

, where

I_{\max}

is the largest representable integer (see X02BBF). If overflow occurs during a subcalculation, as indicated by

IFAIL = 5

m_{s}

may or may not be greater than

I_{\max}

. In either case,

SCM = X02BBF

will have been returned.

8: IFAIL – INTEGERInput/Output

On entry: IFAIL must be set to

0

- 1 ​ or ​ 1

. If you are unfamiliar with this parameter you should refer to Section 3.3 in the Essential Introduction for details.

For environments where it might be inappropriate to halt program execution when an error is detected, the value

- 1 ​ or ​ 1

is recommended. If the output of error messages is undesirable, then the value

1

is recommended. Otherwise, if you are not familiar with this parameter, the recommended value is

0

. 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

- 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| \leq arbnd = ⟨value⟩$ .

$IFAIL = 13$: ANI is non-integral.
On entry, $ANI = ⟨value⟩$ .
Constraint: $ANI = ⌊ANI⌋$ .

$IFAIL = 21$: On entry, $ADR = ⟨value⟩$ .
Constraint: $|ADR| \leq 0.5$ .

$IFAIL = 31$: On entry, $BNI = ⟨value⟩$ .
Constraint: $|BNI| \leq 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| \leq 0.5$ .

$IFAIL = 51$: On entry, $X = ⟨value⟩$ .
Constraint: $|X| \leq arbnd = ⟨value⟩$ .

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$	$res \leq 1000 ε$
$IFAIL = 3$	$1000 ε < res \leq 0.1$
$IFAIL = 4$	$res > 0.1$

A further estimate of the residual can be constructed using equation (1), and the differential identity,

\begin{matrix} \frac{d M (a, b, x)}{d x} & = & \frac{a}{b} M (a + 1, b + 1, x), \\ \frac{d^{2} M (a, b, x)}{d x^{2}} & = & \frac{a (a + 1)}{b (b + 1)} M (a + 2, b + 2, x) . \end{matrix}

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 Further Comments

The values returned in FRM (

m_{f}

) and SCM (

m_{s}

) 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,

\begin{matrix} M (a, b, x) & = & m_{f} \times 2^{m_{s}} \\ M (a_{1}, b_{1}, x_{1}) \times M (a_{2}, b_{2}, x_{2}) & = & (m_{f 1} \times m_{f 2}) \times 2^{(m_{s 1} + m_{s 2})} \\ \frac{M (a_{1}, b_{1}, x_{1})}{M (a_{2}, b_{2}, x_{2})} & = & \frac{m_{f 1}}{m_{f 2}} \times 2^{(m_{s 1} - m_{s 2})} \\ \ln |M (a, b, x)| & = & \ln |m_{f}| + m_{s} \times \ln (2) \end{matrix} .

9 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