Integer type: int32 int64 nag_int show int32 show int32 show int64 show int64 show nag_int show nag_int

PDF version (NAG web site, 64-bit version, 64-bit version)

Chapter Contents

Chapter Introduction

NAG Toolbox

NAG Toolbox: nag_specfun_2f1_real_scaled (s22bf)

▸▿ Contents

1 Purpose

2 Syntax

3 Description

4 References

▸▿ 5 Parameters

5.1 Compulsory Input Parameters

5.2 Optional Input Parameters

5.3 Output Parameters

6 Error Indicators and Warnings

7 Accuracy

8 Further Comments

9 Example

Purpose

nag_specfun_2f1_real_scaled (s22bf) 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_{fr} \times 2^{f_{sc}}

Syntax

[frf, scf, ifail] = s22bf(ani, adr, bni, bdr, cni, cdr, x)

[frf, scf, ifail] = nag_specfun_2f1_real_scaled(ani, adr, bni, bdr, cni, cdr, x)

Description

nag_specfun_2f1_real_scaled (s22bf) 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,

x (1 - x) \frac{d^{2} f}{d x^{2}} + (c - (a + b + 1) x) \frac{d f}{d x} - a b f = 0 .

(1)

For

|x| < 1

, it may be defined by the Gauss series,

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

(2)

where

{(a)}_{s} = 1 (a) (a + 1) (a + 2) \dots (a + s - 1)

is the rising factorial of

a

{}_{2}F_{1} (a, b; c; x)

is undefined for

c = 0

c

a negative integer.

For

|x| < 1

, the series is absolutely convergent and

{}_{2}F_{1} (a, b; c; x)

is finite.

For

x < 1

, linear transformations of the form,

{}_{2}F_{1} (a, b; c; x) = C_{1} (a_{1}, b_{1}, c_{1}, x_{1}) {}_{2}F_{1} (a_{1}, b_{1}; c_{1}; x_{1}) + C_{2} (a_{2}, b_{2}, c_{2}, x_{2}) {}_{2}F_{1} (a_{2}, b_{2}; c_{2}; x_{2})

(3)

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{Γ (c) Γ (c - a - b)}{Γ (c - a) Γ (c - b)}$ , and hence is finite. Solutions also exist for the degenerate cases where $c - a$ or $c - b$ are negative integers or zero.
If $c \leq 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 \leq 0.5

, sets of safe parameters

\{α_{i, j}, β_{i, j}, ζ_{i, j}, χ_{j} |1 \leq j \leq 2|, 1 \leq i \leq 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} (α_{i, j}, β_{i, j}; ζ_{i, j}; χ_{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} \neq 0.0

will be used, with the argument

x_{2} = 1.0 - x

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

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.0 - x

is employed, and the above strategy for

0 < x \leq 0.5

is utilized on both components. Further transformations in these sub-computations 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 \leq 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

[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

|a_{r}| \leq 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.

arbnd = 0.0001 \times I_{\max}

, where

I_{\max}

is the largest machine integer (see nag_machine_integer_max (x02bb)). 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 non-finite values of the parameters and argument on entry, and assigns non-finite values upon completion if appropriate. See Further Comments

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

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

Parameters

Compulsory Input Parameters

1: $ani$ – double scalar

a_{i}

, the nearest integer to

a

, satisfying

a_{i} = a - a_{r}

Constraints:

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

2: $adr$ – double scalar

a_{r}

, the signed decimal remainder satisfying

a_{r} = a - a_{i}

and

|a_{r}| \leq 0.5

Constraint:

|adr| \leq 0.5

3: $bni$ – double scalar

b_{i}

, the nearest integer to

b

, satisfying

b_{i} = b - b_{r}

Constraints:

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

4: $bdr$ – double scalar

b_{r}

, the signed decimal remainder satisfying

b_{r} = b - b_{i}

and

|b_{r}| \leq 0.5

Constraint:

|bdr| \leq 0.5

5: $cni$ – double scalar

c_{i}

, the nearest integer to

c

, satisfying

c_{i} = c - c_{r}

Constraints:

$cni = ⌊cni⌋$ ;
$|cni| \leq arbnd$ ;
if $|cdr| < 16.0 ε$ , $cni \geq 1.0$ .

6: $cdr$ – double scalar

c_{r}

, the signed decimal remainder satisfying

c_{r} = c - c_{i}

and

|c_{r}| \leq 0.5

Constraint:

|cdr| \leq 0.5

7: $x$ – double scalar

The argument

x

Constraint:

- arbnd < x \leq 1

Optional Input Parameters

None.

Output Parameters

1: $frf$ – double scalar: $f_{fr}$ , the scaled real component of the solution satisfying $f_{fr} = {}_{2}F_{1} (a, b; c; x) \times 2^{- f_{sc}}$ , i.e., ${}_{2}F_{1} (a, b; c; x) = f_{fr} \times 2^{f_{sc}}$ . See Further Comments for the behaviour of $f_{fr}$ when a finite or non-finite answer is returned.
2: $scf$ – int64int32nag_int scalar: $f_{sc}$ , the scaling power of two, satisfying $f_{sc} = \log_{2} (\frac{{}_{2}F_{1} (a, b; c; x)}{f_{fr}})$ , i.e., ${}_{2}F_{1} (a, b; c; x) = f_{fr} \times 2^{f_{sc}}$ . See Further Comments for the behaviour of $f_{sc}$ when a non-finite answer is returned.
3: $ifail$ – int64int32nag_int scalar: $ifail = 0$ unless the function detects an error (see Error Indicators and Warnings).

Error Indicators and Warnings

Errors or warnings detected by the function:

$ifail = 1$: Underflow occurred during the evaluation of ${}_{2}F_{1} (a, b; c; x)$ . The returned value may be inaccurate.

$ifail = 2$: All approximations have completed, and the final residual estimate indicates some precision may have been lost.

$ifail = 3$: All approximations have completed, and the final residual estimate indicates no accuracy can be guaranteed.

$ifail = 4$: On entry, $x =_$ , $c =_$ , $a + b =_$ .
${}_{2}F_{1} (a, b; c; 1)$ is infinite in the case $c \leq a + b$ .

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

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

$ifail = 9$: An internal calculation has resulted in an undefined result.

$ifail = 11$: On entry, ani does not satisfy $|ani| \leq arbnd =_$ .

$ifail = 13$: Constraint: $ani = ⌊ani⌋$ .

$ifail = 21$: On entry, adr does not satisfy $|adr| \leq 0.5$ .

$ifail = 31$: On entry, bni does not satisfy $|bni| \leq arbnd =_$ .

$ifail = 33$: Constraint: $bni = ⌊bni⌋$ .

$ifail = 41$: On entry, bdr does not satisfy $|bdr| \leq 0.5$ .

$ifail = 51$: On entry, cni does not satisfy $|cni| \leq arbnd =_$ .

$ifail = 52$: ${}_{2}F_{1} (a, b; c; x)$ is undefined when $c$ is zero or a negative integer.

$ifail = 53$: Constraint: $cni = ⌊cni⌋$ .

$ifail = 61$: On entry, cdr does not satisfy $|cdr| \leq 0.5$ .

$ifail = 71$: On entry, x does not satisfy $|x| \leq arbnd =_$ .

$ifail = 72$: ${}_{2}F_{1} (a, b; c; x)$ is not real valued when $x > 1$ .

$ifail = - 99$: An unexpected error has been triggered by this routine. Please contact NAG.

$ifail = - 399$: Your licence key may have expired or may not have been installed correctly.

$ifail = - 999$: Dynamic memory allocation failed.

Accuracy

In general, if

ifail = 0

, 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

res

is made internally using equation (1). If the magnitude of this residual

res

is sufficiently large, a nonzero ifail will be returned. Specifically,

$ifail = 0$ or $1$	$res \leq 1000 ε$
$ifail = 2$	$1000 ε < res \leq 0.1$
$ifail = 3$	$res > 0.1$

where

ε

is the machine precision as returned by nag_machine_precision (x02aj). Note that underflow may also have occurred if

ifail = 2

3

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

\begin{matrix} \frac{d ({}_{2}F_{1} (a, b; c; x))}{d x} = \frac{a b}{c} {}_{2}F_{1} (a + 1, b + 1; c + 1; x) \\ \frac{d^{2} ({}_{2}F_{1} (a, b; c; x))}{d x^{2}} = \frac{a (a + 1) b (b + 1)}{c (c + 1)} {}_{2}F_{1} (a + 2, b + 2; c + 2; x) \end{matrix}

(4)

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)

Further Comments

nag_specfun_2f1_real_scaled (s22bf) returns non-finite values when appropriate.

Should a non-finite value be returned, this will be indicated in the value of ifail, as detailed in the following cases.

ifail = 0

ifail = 1

2

3

, a finite value will have been returned with approximate accuracy as detailed in Accuracy.

The values of

f_{f r}

and

f_{s c}

are implementation dependent. In most cases, if

{}_{2}F_{1} (a, b; c; x) = 0

f_{f r} = 0

and

f_{s c} = 0

will be returned, and if

{}_{2}F_{1} (a, b; c; x)

is finite, the fractional component will be bound by

0.5 \leq |f_{f r}| < 1

, with

f_{s c}

chosen accordingly.

The values returned in frf (

f_{fr}

) and scf (

f_{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,

\begin{matrix} {}_{2}F_{1} (a, b; c; x) = f_{fr} \times 2^{f_{sc}} \\ {}_{2}F_{1} (a_{1}, b_{1}; c_{1}; x_{1}) \times {}_{2}F_{1} (a_{2}, b_{2}; c_{2}; x_{2}) = (f_{fr 1} \times f_{fr 2}) \times 2^{(f_{sc 1} + f_{sc 2})} \\ \frac{{}_{2}F_{1} (a_{1}, b_{1}; c_{1}; x_{1})}{{}_{2}F_{1} (a_{2}, b_{2}; c_{2}; x_{2})} = \frac{f_{fr 1}}{f_{fr 2}} \times 2^{(f_{sc 1} - f_{sc 2})} \\ \ln |{}_{2}F_{1} (a, b; c; x)| = \ln |f_{fr}| + f_{sc} \times \ln (2) . \end{matrix}

ifail = 4

then

{}_{2}F_{1} (a, b; c; x)

is infinite. A signed infinity will have been returned for frf, and

scf = 0

. The sign of frf should be correct when taking the limit as

x

approaches

1

from below.

ifail = 5

then upon completion,

|{}_{2}F_{1} (a, b; c; x)| > 2^{I_{\max}}

, where

I_{\max}

is given by nag_machine_integer_max (x02bb), 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

scf = I_{\max}

will have been returned.

ifail = 6

then overflow occurred during a subcalculation of

{}_{2}F_{1} (a, b; c; x)

. The same result as for

ifail = 5

will have been returned, however there is no guarantee that this is representative of either the magnitude of the scaling power

f_{sc}

, or the scaled component

f_{fr}

{}_{2}F_{1} (a, b; c; x)

For all other error exits,

scf = 0

will be returned and frf will be returned as a signalling NaN.

ifail = 9

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.

ifail = 52

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.

ifail = 11

31

51

71

then no computation will have been performed due to the risk of integer overflow. The actual solution may however be finite.

ifail = 72

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 non-zero imaginary component. It is however strictly finite.

Example

This example evaluates the Gauss hypergeometric function at two points in scaled form using nag_specfun_2f1_real_scaled (s22bf), and subsequently calculates their product and ratio implicitly.

Open in the MATLAB editor: s22bf_example

function s22bf_example


fprintf('s22bf example results\n\n');

% Evaluate 2F1(a,b;c;x) at two points a small delta either
% side of (a,b,c) = (-10,2,-5).

delta = 10^-4;
ani = -10;  adr =  delta;
bni =   2;  bdr = -delta;
cni =  -5;  cdr =  delta;

x = 0.45;

fprintf('%10s%10s%10s%10s%14s%7s%14s\n',...
        'a','b','c','x','frf','scf','2F1(a,b;c;x)');

for j = 1:2
  [frf(j), scf(j), ifail] = s22bf( ...
                               ani,  adr, bni,  bdr, cni,  cdr, x);
  scale = frf(j)*2^double(scf(j));
  fprintf('%10.4f%10.4f%10.4f%10.4f%14.5e%7d%14.5e\n',...
          ani+adr, bni+bdr, cni+cdr, x, frf(j), scf(j), scale);
  adr = -adr;
  bdr = -bdr;
  cdr = -cdr;
end

% Product of solutions
frfp = prod(frf);
scfp = sum(scf);
scale = frfp*2^double(scfp);
fprintf('\n%-40s%14.5e%7d%14.5e\n','Solution Product', frfp, scfp, scale);

% Ratio of solutions
frfr = frf(1)/frf(2);
scfr = scf(1) - scf(2);
scale = frfr*(2^double(scfr));
fprintf('%-40s%14.5e%7d%14.5e\n','Solution Ratio', frfr, scfr, scale);

s22bf example results

         a         b         c         x           frf    scf  2F1(a,b;c;x)
   -9.9999    1.9999   -4.9999    0.4500  -5.44477e-01     16  -3.56828e+04
  -10.0001    2.0001   -5.0001    0.4500   5.44547e-01     16   3.56875e+04

Solution Product                          -2.96494e-01     32  -1.27343e+09
Solution Ratio                            -9.99871e-01      0  -9.99871e-01

PDF version (NAG web site, 64-bit version, 64-bit version)

Chapter Contents

Chapter Introduction

NAG Toolbox