S Chapter Contents
S Chapter Introduction
NAG Library Manual

# NAG Library Routine DocumentS22BAF

Note:  before using this routine, please read the Users' Note for your implementation to check the interpretation of bold italicised terms and other implementation-dependent details.

## 1  Purpose

S22BAF returns a value for the confluent hypergeometric function ${}_{1}F_{1}\left(a;b;x\right)$ with real parameters $a$, $b$ and $x$. This function is sometimes also known as Kummer's function $M\left(a,b,x\right)$.

## 2  Specification

 SUBROUTINE S22BAF ( A, B, X, M, IFAIL)
 INTEGER IFAIL REAL (KIND=nag_wp) A, B, X, M

## 3  Description

S22BAF returns a value for the confluent hypergeometric function ${}_{1}F_{1}\left(a;b;x\right)$ with real parameters $a$, $b$ and $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}×{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 integer and a decimal fraction, giving higher accuracy when $a$ or $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
 $F1 1 a;b;x = Ma,b,x = ∑ s=0 ∞ as xs bs s! = 1 + a b x + aa+1 bb+1 2! x2 + ⋯$
where ${\left(a\right)}_{s}=1\left(a\right)\left(a+1\right)\left(a+2\right)\dots \left(a+s-1\right)$ is the rising factorial of $a$. $M\left(a,b,x\right)$ 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 $\left(a,b,x\right)$, this routine determines a set of safe parameters $\left\{\left({\alpha }_{i},{\beta }_{i},{\zeta }_{i}\right)\mid i\le 2\right\}$ and selects an appropriate algorithm to accurately evaluate the functions ${M}_{i}\left({\alpha }_{i},{\beta }_{i},{\zeta }_{i}\right)$. The result is then used to construct the solution to the original problem $M\left(a,b,x\right)$ using, where necessary, recurrence relations and/or continuation.
Additionally, an artificial bound, $\mathit{arbnd}$ is placed on the magnitudes of $a$, $b$ and $x$ to minimize the occurrence of overflow in internal calculations. $\mathit{arbnd}=0.0001×{I}_{\mathrm{max}}$, where ${I}_{\mathrm{max}}={\mathbf{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 or the companion (2010) for a detailed discussion of the confluent hypergeoemtric function including special cases, transformations, relations and asymptotic approximations.
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:     A – REAL (KIND=nag_wp)Input
On entry: the parameter $a$ of the function.
Constraint: $\left|{\mathbf{A}}\right|\le \mathit{arbnd}$.
2:     B – REAL (KIND=nag_wp)Input
On entry: the parameter $b$ of the function.
Constraint: $\left|{\mathbf{B}}\right|\le \mathit{arbnd}$.
3:     X – REAL (KIND=nag_wp)Input
On entry: the argument $x$ of the function.
Constraint: $\left|{\mathbf{X}}\right|\le \mathit{arbnd}$.
4:     M – REAL (KIND=nag_wp)Output
On exit: the solution $M\left(a,b,x\right)$.
Note: if overflow occurs upon completion, as indicated by ${\mathbf{IFAIL}}={\mathbf{2}}$, $\left|M\left(a,b,x\right)\right|$ may be assumed to be too large to be representable. M will be returned as $±{R}_{\mathrm{max}}$, where ${R}_{\mathrm{max}}$ is the largest representable real number (see X02ALF). The sign of M should match the sign of $M\left(a,b,x\right)$. If overflow occurs during a subcalculation, as indicated by ${\mathbf{IFAIL}}={\mathbf{5}}$, the sign may be incorrect, and the true value of $M\left(a,b,x\right)$ may or may not be greater than ${R}_{\mathrm{max}}$. In either case it is advisable to subsequently use S22BBF.
5:     IFAIL – INTEGERInput/Output
On entry: IFAIL must be set to $0$, $-1\text{​ 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\text{​ 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 $-\mathbf{1}\text{​ or ​}\mathbf{1}$ is used it is essential to test the value of IFAIL on exit.
On exit: ${\mathbf{IFAIL}}={\mathbf{0}}$ unless the routine detects an error or a warning has been flagged (see Section 6).

## 6  Error Indicators and Warnings

If on entry ${\mathbf{IFAIL}}={\mathbf{0}}$ or $-{\mathbf{1}}$, explanatory error messages are output on the current error message unit (as defined by X04AAF).
Errors or warnings detected by the routine:
${\mathbf{IFAIL}}=1$
Underflow occurred during the evaluation of $M\left(a,b,x\right)$.
The returned value may be inaccurate.
${\mathbf{IFAIL}}=2$
On completion, overflow occurred in the evaluation of $M\left(a,b,x\right)$.
${\mathbf{IFAIL}}=3$
All approximations have completed, and the final residual estimate indicates some precision may have been lost.
Relative residual $\text{}=⟨\mathit{\text{value}}⟩$.
${\mathbf{IFAIL}}=4$
All approximations have completed, and the final residual estimate indicates no accuracy can be guaranteed.
Relative residual $\text{}=⟨\mathit{\text{value}}⟩$.
${\mathbf{IFAIL}}=5$
Overflow occurred in a subcalculation of $M\left(a,b,x\right)$.
The answer may be completely incorrect.
${\mathbf{IFAIL}}=11$
On entry, ${\mathbf{A}}=⟨\mathit{\text{value}}⟩$.
Constraint: $\left|{\mathbf{A}}\right|\le \mathit{arbnd}=⟨\mathit{\text{value}}⟩$.
${\mathbf{IFAIL}}=31$
On entry, ${\mathbf{B}}=⟨\mathit{\text{value}}⟩$.
Constraint: $\left|{\mathbf{B}}\right|\le \mathit{arbnd}=⟨\mathit{\text{value}}⟩$.
${\mathbf{IFAIL}}=32$
On entry, ${\mathbf{B}}=⟨\mathit{\text{value}}⟩$.
$M\left(a,b,x\right)$ is undefined when $b$ is zero or a negative integer.
${\mathbf{IFAIL}}=51$
On entry, ${\mathbf{X}}=⟨\mathit{\text{value}}⟩$.
Constraint: $\left|{\mathbf{X}}\right|\le \mathit{arbnd}=⟨\mathit{\text{value}}⟩$.

## 7  Accuracy

In general, if ${\mathbf{IFAIL}}={\mathbf{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 $\mathit{res}$ is made internally using equation (1). If the magnitude of $\mathit{res}$ is sufficiently large, a nonzero IFAIL will be returned. Specifically,
 $IFAIL = 0 res≤1000ε 3 1000ε0.1 .$
A further estimate of the residual can be constructed using equation (1), and the differential identity,
 $d Ma,b,x dx = ab M a+1,b+1,x , d2 Ma,b,x dx2 = aa+1 bb+1 M a+2,b+2,x .$
This estimate is however dependent upon the error involved in approximating $M\left(a+1,b+1,x\right)$ and $M\left(a+2,b+2,x\right)$.
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+\text{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.

None.

## 9  Example

This example reads in values for $a$, $b$ and $x$ and prints the result of S22BAF at these values.

### 9.1  Program Text

Program Text (s22bafe.f90)

### 9.2  Program Data

Program Data (s22bafe.d)

### 9.3  Program Results

Program Results (s22bafe.r)