NAG CL Interface
s22bfc (hyperg_gauss_real_scaled)
1
Purpose
s22bfc returns a value for the Gauss hypergeometric function ${}_{2}F_{1}(a,b;c;x)$ for real parameters $a,b$ and $c$, and real argument $x$. The result is returned in the scaled form ${}_{2}F_{1}(a,b;c;x)={f}_{\mathrm{fr}}\times {2}^{{f}_{\mathrm{sc}}}$.
2
Specification
The function may be called by the names: s22bfc, nag_specfun_hyperg_gauss_real_scaled or nag_specfun_2f1_real_scaled.
3
Description
s22bfc returns a value for the Gauss hypergeometric function ${}_{2}F_{1}(a,b;c;x)$ for real parameters $a$, $b$ and $c$, and for real argument $x$.
The Gauss hypergeometric function is a solution to the hypergeometric differential equation,
For
$\leftx\right<1$, it may be defined by the Gauss series,
where
${\left(a\right)}_{s}=1\left(a\right)(a+1)(a+2)\dots (a+s1)$ is the rising factorial of
$a$.
${}_{2}F_{1}(a,b;c;x)$ is undefined for
$c=0$ or
$c$ a negative integer.
For $\leftx\right<1$, the series is absolutely convergent and ${}_{2}F_{1}(a,b;c;x)$ is finite.
For
$x<1$, linear transformations of the form,
exist, where
${x}_{1}$,
${x}_{2}\in (0,1]$.
${C}_{1}$ and
${C}_{2}$ are real valued functions of the parameters and argument, typically involving products of gamma functions. When these are degenerate, finite limiting cases exist. Hence for
$x<0$,
${}_{2}F_{1}(a,b;c;x)$ is defined by analytic continuation, and for
$x<1$,
${}_{2}F_{1}(a,b;c;x)$ is real and finite.
For
$x=1$, the following apply:
 If $c>a+b$, ${}_{2}F_{1}(a,b;c;1)=\frac{\Gamma \left(c\right)\Gamma (cab)}{\Gamma (ca)\Gamma (cb)}$, and hence is finite. Solutions also exist for the degenerate cases where $ca$ or $cb$ are negative integers or zero.
 If $c\le a+b$, ${}_{2}F_{1}(a,b;c;1)$ is infinite, and the sign of ${}_{2}F_{1}(a,b;c;1)$ is determinable as $x$ approaches $1$ from below.
In the complex plane, the principal branch of ${}_{2}F_{1}(a,b;c;z)$ is taken along the real axis from $x=1.0$ increasing. ${}_{2}F_{1}(a,b;c;z)$ is multivalued along this branch, and for real parameters $a,b$ and $c$ is typically not real valued. As such, this function will not compute a solution when $x>1$.
The solution strategy used by this function is primarily dependent upon the value of the argument $x$. Once trivial cases and the case $x=1.0$ are eliminated, this proceeds as follows.
For
$0<x\le 0.5$, sets of safe parameters
$\{{\alpha}_{i,j},{\beta}_{i,j},{\zeta}_{i,j},{\chi}_{j}1\le j\le 2,1\le i\le 4\}$ are determined, such that the values of
${}_{2}F_{1}({a}_{j},{b}_{j};{c}_{j};{x}_{j})$ required for an appropriate transformation of the type
(3) may be calculated either directly or using recurrence relations from the solutions of
${}_{2}F_{1}({\alpha}_{i,j},{\beta}_{i,j};{\zeta}_{i,j};{\chi}_{j})$. If
$c$ is positive, then only transformations with
${C}_{2}=0.0$ will be used, implying only
${}_{2}F_{1}({a}_{1},{b}_{1};{c}_{1};{x}_{1})$ will be required, with the transformed argument
${x}_{1}=x$. If
$c$ is negative, in some cases a transformation with
${C}_{2}\ne 0.0$ will be used, with the argument
${x}_{2}=1.0x$. The function then cycles through these sets until acceptable solutions are generated. If no computation produces an accurate answer, the least inaccurate answer is selected to complete the computation. See
Section 7.
For $0.5<x<1.0$, an identical approach is first used with the argument $x$. Should this fail, a linear transformation resulting in both transformed arguments satisfying ${x}_{j}=1.0x$ is employed, and the above strategy for $0<x\le 0.5$ is utilized on both components. Further transformations in these subcomputations are however, limited to single terms with no argument transformation.
For $x<0$, a linear transformation mapping the argument $x$ to the interval $(0,0.5]$ is first employed. The strategy for $0<x\le 0.5$ is then used on each component, including possible further two term transforms. To avoid some degenerate cases, a transform mapping the argument $x$ to $[0.5,1)$ may also be used.
For improved precision in the final result, this function accepts $a,b$ and $c$ split into an integral and a decimal fractional component. Specifically, $a={a}_{i}+{a}_{r}$, where $\left{a}_{r}\right\le 0.5$ and ${a}_{i}=a{a}_{r}$ is integral. The other parameters $b$ and $c$ are similarly deconstructed.
In addition to the above restrictions on
$c$ and
$x$, an artificial bound,
arbnd, is placed on the magnitudes of
$a,b,c$ and
$x$ to minimize the occurrence of overflow in internal calculations, particularly those involving real to integer conversions.
$\mathit{arbnd}=0.0001\times {I}_{\mathrm{max}}$, where
${I}_{\mathrm{max}}$ is the largest machine integer (see
X02BBC). It should however, not be assumed that this function will produce accurate answers for all values of
$a,b,c$ and
$x$ satisfying this criterion.
This function also tests for nonfinite values of the parameters and argument on entry, and assigns nonfinite values upon completion if appropriate. See
Section 9 and
Chapter X07.
Please consult the
NIST Digital Library of Mathematical Functions for a detailed discussion of the Gauss hypergeometric function including special cases, transformations, relations and asymptotic approximations.
4
References
Pearson J (2009) Computation of hypergeometric functions MSc Dissertation, Mathematical Institute, University of Oxford
5
Arguments

1:
$\mathbf{ani}$ – double
Input

On entry: ${a}_{i}$, the nearest integer to $a$, satisfying ${a}_{i}=a{a}_{r}$.
Constraints:
 ${\mathbf{ani}}=\lfloor {\mathbf{ani}}\rfloor $;
 $\left{\mathbf{ani}}\right\le \mathit{arbnd}$.

2:
$\mathbf{adr}$ – double
Input

On entry: ${a}_{r}$, the signed decimal remainder satisfying ${a}_{r}=a{a}_{i}$ and $\left{a}_{r}\right\le 0.5$.
Constraint:
$\left{\mathbf{adr}}\right\le 0.5$.

3:
$\mathbf{bni}$ – double
Input

On entry: ${b}_{i}$, the nearest integer to $b$, satisfying ${b}_{i}=b{b}_{r}$.
Constraints:
 ${\mathbf{bni}}=\lfloor {\mathbf{bni}}\rfloor $;
 $\left{\mathbf{bni}}\right\le \mathit{arbnd}$.

4:
$\mathbf{bdr}$ – double
Input

On entry: ${b}_{r}$, the signed decimal remainder satisfying ${b}_{r}=b{b}_{i}$ and $\left{b}_{r}\right\le 0.5$.
Constraint:
$\left{\mathbf{bdr}}\right\le 0.5$.

5:
$\mathbf{cni}$ – double
Input

On entry: ${c}_{i}$, the nearest integer to $c$, satisfying ${c}_{i}=c{c}_{r}$.
Constraints:
 ${\mathbf{cni}}=\lfloor {\mathbf{cni}}\rfloor $;
 $\left{\mathbf{cni}}\right\le \mathit{arbnd}$;
 if $\left{\mathbf{cdr}}\right<16.0\epsilon $, ${\mathbf{cni}}\ge 1.0$.

6:
$\mathbf{cdr}$ – double
Input

On entry: ${c}_{r}$, the signed decimal remainder satisfying ${c}_{r}=c{c}_{i}$ and $\left{c}_{r}\right\le 0.5$.
Constraint:
$\left{\mathbf{cdr}}\right\le 0.5$.

7:
$\mathbf{x}$ – double
Input

On entry: the argument $x$.
Constraint:
$\mathit{arbnd}<{\mathbf{x}}\le 1$.

8:
$\mathbf{frf}$ – double *
Output

On exit:
${f}_{\mathrm{fr}}$, the scaled real component of the solution satisfying
${f}_{\mathrm{fr}}={}_{2}F_{1}(a,b;c;x)\times {2}^{{f}_{\mathrm{sc}}}$, i.e.,
${}_{2}F_{1}(a,b;c;x)={f}_{\mathrm{fr}}\times {2}^{{f}_{\mathrm{sc}}}$. See
Section 9 for the behaviour of
${f}_{\mathrm{fr}}$ when a finite or nonfinite answer is returned.

9:
$\mathbf{scf}$ – Integer *
Output

On exit:
${f}_{\mathrm{sc}}$, the scaling power of two, satisfying
${f}_{\mathrm{sc}}={\mathrm{log}}_{2}\left(\frac{{}_{2}F_{1}(a,b;c;x)}{{f}_{\mathrm{fr}}}\right)$, i.e.,
${}_{2}F_{1}(a,b;c;x)={f}_{\mathrm{fr}}\times {2}^{{f}_{\mathrm{sc}}}$. See
Section 9 for the behaviour of
${f}_{\mathrm{sc}}$ when a nonfinite answer is returned.

10:
$\mathbf{fail}$ – NagError *
Input/Output

The NAG error argument (see
Section 7 in the Introduction to the NAG Library CL Interface).
6
Error Indicators and Warnings
 NE_ALLOC_FAIL

Dynamic memory allocation failed.
See
Section 3.1.2 in the Introduction to the NAG Library CL Interface for further information.
 NE_BAD_PARAM

On entry, argument $\u27e8\mathit{\text{value}}\u27e9$ had an illegal value.
 NE_CANNOT_CALCULATE

An internal calculation has resulted in an undefined result.
 NE_COMPLEX

On entry, ${\mathbf{x}}=\u27e8\mathit{\text{value}}\u27e9$.
In general, ${}_{2}F_{1}(a,b;c;x)$ is not real valued when $x>1$.
 NE_INFINITE

On entry, ${\mathbf{x}}=\u27e8\mathit{\text{value}}\u27e9$, $c=\u27e8\mathit{\text{value}}\u27e9$, $a+b=\u27e8\mathit{\text{value}}\u27e9$.
${}_{2}F_{1}(a,b;c;1)$ is infinite in the case $c\le a+b$.
 NE_INTERNAL_ERROR

An internal error has occurred in this function. Check the function call and any array sizes. If the call is correct then please contact
NAG for assistance.
See
Section 7.5 in the Introduction to the NAG Library CL Interface for further information.
 NE_NO_LICENCE

Your licence key may have expired or may not have been installed correctly.
See
Section 8 in the Introduction to the NAG Library CL Interface for further information.
 NE_OVERFLOW

Overflow occurred in a subcalculation of ${}_{2}F_{1}(a,b;c;x)$. The answer may be completely incorrect.
 NE_REAL

On entry,
adr does not satisfy
$\left{\mathbf{adr}}\right\le 0.5$.
On entry,
bdr does not satisfy
$\left{\mathbf{bdr}}\right\le 0.5$.
On entry,
cdr does not satisfy
$\left{\mathbf{cdr}}\right\le 0.5$.
 NE_REAL_2

On entry, $c={\mathbf{cni}}+{\mathbf{cdr}}=\u27e8\mathit{\text{value}}\u27e9$.
${}_{2}F_{1}(a,b;c;x)$ is undefined when $c$ is zero or a negative integer.
 NE_REAL_ARG_NON_INTEGRAL

ani is nonintegral.
On entry,
${\mathbf{ani}}=\u27e8\mathit{\text{value}}\u27e9$.
Constraint:
${\mathbf{ani}}=\lfloor {\mathbf{ani}}\rfloor $.
bni is nonintegral.
On entry,
${\mathbf{bni}}=\u27e8\mathit{\text{value}}\u27e9$.
Constraint:
${\mathbf{bni}}=\lfloor {\mathbf{bni}}\rfloor $.
cni is nonintegral.
On entry,
${\mathbf{cni}}=\u27e8\mathit{\text{value}}\u27e9$.
Constraint:
${\mathbf{cni}}=\lfloor {\mathbf{cni}}\rfloor $.
 NE_REAL_RANGE_CONS

On entry,
ani does not satisfy
$\left{\mathbf{ani}}\right\le \mathit{arbnd}=\u27e8\mathit{\text{value}}\u27e9$.
On entry,
bni does not satisfy
$\left{\mathbf{bni}}\right\le \mathit{arbnd}=\u27e8\mathit{\text{value}}\u27e9$.
On entry,
cni does not satisfy
$\left{\mathbf{cni}}\right\le \mathit{arbnd}=\u27e8\mathit{\text{value}}\u27e9$.
On entry,
x does not satisfy
$\left{\mathbf{x}}\right\le \mathit{arbnd}=\u27e8\mathit{\text{value}}\u27e9$.
 NE_TOTAL_PRECISION_LOSS

All approximations have completed, and the final residual estimate indicates no accuracy can be guaranteed.
$\text{Relative residual}=\u27e8\mathit{\text{value}}\u27e9$.
 NW_OVERFLOW_WARN

On completion, overflow occurred in the evaluation of ${}_{2}F_{1}(a,b;c;x)$.
 NW_SOME_PRECISION_LOSS

All approximations have completed, and the final residual estimate indicates some precision may have been lost.
$\text{Relative residual}=\u27e8\mathit{\text{value}}\u27e9$.
 NW_UNDERFLOW_WARN

Underflow occurred during the evaluation of ${}_{2}F_{1}(a,b;c;x)$. The returned value may be inaccurate.
7
Accuracy
In general, if
${\mathbf{fail}}\mathbf{.}\mathbf{code}=$ NE_NOERROR, the value of
${}_{2}F_{1}(a,b;c;x)$ may be assumed accurate, with the possible loss of one or two decimal places. Assuming the result does not overflow, an error estimate
$\mathit{res}$ is made internally using equation
(1). If the magnitude of this residual
$\mathit{res}$ is sufficiently large, a
different
fail.code
will be returned. Specifically,
where
$\epsilon $ is the
machine precision as returned by
X02AJC. Note that underflow may also have occurred if
${\mathbf{fail}}\mathbf{.}\mathbf{code}=$ NE_TOTAL_PRECISION_LOSS or
NW_SOME_PRECISION_LOSS.
A further estimate of the residual can be constructed using equation
(1), and the differential identity,
This estimate is however, dependent upon the error involved in approximating ${}_{2}F_{1}(a+1,b+1;c+1;x)$ and ${}_{2}F_{1}(a+2,b+2;c+2;x)$.
8
Parallelism and Performance
Background information to multithreading can be found in the
Multithreading documentation.
s22bfc is not threaded in any implementation.
s22bfc returns nonfinite values when appropriate. See
Chapter X07 for more information on the definitions of nonfinite values.
Should a nonfinite value be returned, this will be indicated in the value of
fail, as detailed in the following cases.
If
${\mathbf{fail}}\mathbf{.}\mathbf{code}=$ NE_NOERROR or
${\mathbf{fail}}\mathbf{.}\mathbf{code}=$ NE_TOTAL_PRECISION_LOSS,
NW_SOME_PRECISION_LOSS or
NW_UNDERFLOW_WARN, a finite value will have been returned with approximate accuracy as detailed in
Section 7.
The values of ${f}_{fr}$ and ${f}_{sc}$ are implementation dependent. In most cases, if ${}_{2}F_{1}(a,b;c;x)=0$, ${f}_{fr}=0$ and ${f}_{sc}=0$ will be returned, and if ${}_{2}F_{1}(a,b;c;x)$ is finite, the fractional component will be bound by $0.5\le \left{f}_{fr}\right<1$, with ${f}_{sc}$ chosen accordingly.
The values returned in
frf (
${f}_{\mathrm{fr}}$) and
scf (
${f}_{\mathrm{sc}}$) may be used to explicitly evaluate
${}_{2}F_{1}(a,b;c;x)$, and may also be used to evaluate products and ratios of multiple values of
${}_{2}F_{1}$ as follows,
If
${\mathbf{fail}}\mathbf{.}\mathbf{code}=$ NE_INFINITE then
${}_{2}F_{1}(a,b;c;x)$ is infinite. A signed infinity will have been returned for
frf, and
${\mathbf{scf}}=0$. The sign of
frf should be correct when taking the limit as
$x$ approaches
$1$ from below.
If
${\mathbf{fail}}\mathbf{.}\mathbf{code}=$ NW_OVERFLOW_WARN then upon completion,
$\left{}_{2}F_{1}(a,b;c;x)\right>{2}^{{I}_{\mathrm{max}}}$, where
${I}_{\mathrm{max}}$ is given by
X02BBC, and hence is too large to be representable even in the scaled form. The scaled real component returned in
frf may still be correct, whilst
${\mathbf{scf}}={I}_{\mathrm{max}}$ will have been returned.
If
${\mathbf{fail}}\mathbf{.}\mathbf{code}=$ NE_OVERFLOW then overflow occurred during a subcalculation of
${}_{2}F_{1}(a,b;c;x)$. The same result as for
${\mathbf{fail}}\mathbf{.}\mathbf{code}=$ NW_OVERFLOW_WARN will have been returned, however, there is no guarantee that this is representative of either the magnitude of the scaling power
${f}_{\mathrm{sc}}$, or the scaled component
${f}_{\mathrm{fr}}$ of
${}_{2}F_{1}(a,b;c;x)$.
If
${\mathbf{fail}}\mathbf{.}\mathbf{code}=$ NE_NOERROR,
frf and
scf were inaccessible to
s22bfc, and as such it is not possible to determine what their values may be following the call to
s22bfc.
For all other error exits,
${\mathbf{scf}}=0$ will be returned and
frf will be returned as a signalling NaN (see
x07bbc).
If
${\mathbf{fail}}\mathbf{.}\mathbf{code}=$ NE_CANNOT_CALCULATE an internal computation produced an undefined result. This may occur when two terms overflow with opposite signs, and the result is dependent upon their summation for example.
If
${\mathbf{fail}}\mathbf{.}\mathbf{code}=$ NE_REAL_2 then
$c$ is too close to a negative integer or zero on entry, and
${}_{2}F_{1}(a,b;c;x)$ is undefined. Note, this will also be the case when
$c$ is a negative integer, and a (possibly trivial) linear transformation of the form
(3) would result in either:

(i)all ${c}_{j}$ not being negative integers,

(ii)for any ${c}_{j}$ which remain as negative integers, one of the corresponding parameters ${a}_{j}$ or ${b}_{j}$ is a negative integer of magnitude less than ${c}_{j}$.
In the first case, the transformation coefficients
${C}_{j}({a}_{j},{b}_{j},{c}_{j},{x}_{j})$ are typically either infinite or undefined, preventing a solution being constructed. In the second case, the series
(2) will terminate before the degenerate term, resulting in a polynomial of fixed degree, and hence potentially a finite solution.
If
${\mathbf{fail}}\mathbf{.}\mathbf{code}=$ NE_REAL_RANGE_CONS then no computation will have been performed due to the risk of integer overflow. The actual solution may however, be finite.
${\mathbf{fail}}\mathbf{.}\mathbf{code}=$ NE_COMPLEX indicates
$x>1$, and hence the requested solution is on the boundary of the principal branch of
${}_{2}F_{1}(a,b;c;x)$. Hence it is multivalued, typically with a nonzero imaginary component. It is however, strictly finite.
10
Example
This example evaluates the Gauss hypergeometric function at two points in scaled form using s22bfc, and subsequently calculates their product and ratio implicitly.
10.1
Program Text
10.2
Program Data
None.
10.3
Program Results