s22ba: FL CL CPP AD

NAG FL Interface
s22baf (hyperg_confl_real)

Keyword Search:

NAG Library Manual, Mark 28.3

Interfaces: FL CL CPP AD

NAG FL Interface Introduction

S (Specfun) Chapter Contents

S (Specfun) Chapter Introduction

s22ba: FL CL CPP AD

▸▿ Contents

1 Purpose

2 Specification

3 Description

4 References

5 Arguments

6 Error Indicators and Warnings

7 Accuracy

8 Parallelism and Performance

9 Further Comments

▸▿ 10 Example

10.1 Program Text

10.2 Program Data

10.3 Program Results

1 Purpose

s22baf returns a value for the confluent hypergeometric function

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

with real parameters

a

and

b

, and real argument

x

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

M (a, b, x)

2 Specification

Fortran Interface

Subroutine s22baf (

a, b, x, m, ifail)

Integer, Intent (Inout)	::	ifail
Real (Kind=nag_wp), Intent (In)	::	a, b, x
Real (Kind=nag_wp), Intent (Out)	::	m

C Header Interface

#include <nag.h>

void	s22baf_ (const double a, const double b, const double x, double m, Integer *ifail)

The routine may be called by the names s22baf or nagf_specfun_hyperg_confl_real.

3 Description

s22baf returns a value for the confluent hypergeometric function

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

with real parameters

a

and

b

, and real argument

x

. This function is unbounded or not uniquely defined for

b

equal to zero or a negative integer.

The associated routine s22bbf performs the same operations, but returns

M

in the scaled form

M = m_{f} \times 2^{m_{s}}

to allow calculations to be performed when

M

is not representable as a single working precision number. It also accepts the parameters

a

and

b

as summations of an integer and a decimal fraction, giving higher accuracy when

a

b

are close to an integer. In such cases, s22bbf should be used when high accuracy is required.

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 and argument

(a, b, x)

, this routine determines a set of safe values

{(α_{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.

Additionally, an artificial bound,

arbnd

is placed on the magnitudes of

a

b

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

b

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: $a$ – Real (Kind=nag_wp) Input: On entry: the parameter $a$ of the function.

Constraint: $| a | \leq arbnd$ .
2: $b$ – Real (Kind=nag_wp) Input: On entry: the parameter $b$ of the function.

Constraint: $| b | \leq arbnd$ .
3: $x$ – Real (Kind=nag_wp) Input: On entry: the argument $x$ of the function.

Constraint: $| x | \leq arbnd$ .
4: $m$ – Real (Kind=nag_wp) Output: On exit: the solution $M (a, b, x)$ .
Note: if overflow occurs upon completion, as indicated by $ifail = 2$ , $| M (a, b, x) |$ may be assumed to be too large to be representable. m will be returned as $\pm R_{\max}$ , where $R_{\max}$ is the largest representable real number (see x02alf). The sign of m should match the sign of $M (a, b, x)$ . If overflow occurs during a subcalculation, as indicated by $ifail = 5$ , the sign may be incorrect, and the true value of $M (a, b, x)$ may or may not be greater than $R_{\max}$ . In either case it is advisable to subsequently use s22bbf.
5: $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

−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, $a = ⟨ value ⟩$ .
Constraint: $| a | \leq arbnd = ⟨ value ⟩$ .

$ifail = 31$: On entry, $b = ⟨ value ⟩$ .
Constraint: $| b | \leq arbnd = ⟨ value ⟩$ .

$ifail = 32$: On entry, $b = ⟨ value ⟩$ .
$M (a, b, x)$ is undefined when $b$ is zero or a negative integer.

$ifail = 51$: On entry, $x = ⟨ value ⟩$ .
Constraint: $| x | \leq 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$	$res \leq 1000 ε$
$ifail = 3$	$1000 ε < res \leq 0.1$
$ifail = 4$	$res > 0.1$

where

ε

is the machine precision as returned by x02ajf.

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)

Furthermore, the accuracy of the solution, and the error estimate, can be dependent upon the accuracy of the decimal fraction of the input parameters

a

and

b

. For example, if

b = b_{i} + b_{r} = 100 + 1.0E−6

, then on a machine with

16

decimal digits of precision, the internal calculation of

b_{r}

will only be accurate to

8

decimal places. This can subsequently pollute the final solution by several decimal places without affecting the residual estimate as greatly. Should you require higher accuracy in such regions, then you should use s22bbf, which requires you to supply the correct decimal fraction.

8 Parallelism and Performance

s22baf is threaded by NAG for parallel execution in multithreaded implementations of the NAG Library.

s22baf 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.