hide long namesshow long names
hide short namesshow short names
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 (s22be)


    1  Purpose
    2  Syntax
    7  Accuracy
    9  Example


nag_specfun_2f1_real (s22be) returns a value for the Gauss hypergeometric function F 1 2 a,b;c;x  for real parameters a,b and c, and real argument x.


[result, ifail] = s22be(a, b, c, x)
[result, ifail] = nag_specfun_2f1_real(a, b, c, x)


nag_specfun_2f1_real (s22be) returns a value for the Gauss hypergeometric function F1 2 a,b;c;x  for real parameters a, b and c, and for real argument x.
The associated function nag_specfun_2f1_real_scaled (s22bf) performs the same operations, but returns F1 2 a,b;c;x  in the scaled form F1 2 a,b;c;x=ffr×2fsc to allow calculations to be performed when F1 2 a,b;c;x  is not representable as a single working precision number. It also accepts the parameters a, b and c as summations of an integer and a decimal fraction, giving higher accuracy when any are close to an integer.
The Gauss hypergeometric function is a solution to the hypergeometric differential equation,
x1-x d2 f dx2 + c-a+b+1x d f dx - a b f = 0 . (1)
For x<1, it may be defined by the Gauss series,
F1 2 a,b;c;x = s=0 as bs cs s! xs = 1+ ab c x + aa+1 bb+1 cc+1 2! x2 + , (2)
where as=1aa+1a+2a+s-1 is the rising factorial of a. F1 2 a,b;c;x  is undefined for c=0 or c a negative integer.
For x<1, the series is absolutely convergent and F1 2 a,b;c;x  is finite.
For x<1, linear transformations of the form,
F1 2 a,b;c;x = C1 a1,b1,c1,x1 F1 2 a1, b1 ;c1;x1 + C2 a2,b2,c2,x2 F1 2 a2, b2 ;c2;x2 (3)
exist, where x1, x20,1. C1 and C2 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, F1 2 a,b;c;x  is defined by analytic continuation, and for x<1, F1 2 a,b;c;x  is real and finite.
For x=1, the following apply:
In the complex plane, the principal branch of F1 2 a,b;c;z  is taken along the real axis from x=1.0 increasing. F1 2 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<x0.5, sets of safe parameters αi,j;βi,j;ζi,j; χj 1j2 ;1i4  are determined, such that the values of F 1 2 aj,bj;cj;xj  required for an appropriate transformation of the type (3) may be calculated either directly or using recurrence relations from the solutions of F 1 2 αi,j,βi,j ;ζi,j;χj . If c is positive, then only transformations with C2=0.0 will be used, implying only F 1 2 a1,b1;c1;x1  will be required, with the transformed argument x1=x. If c is negative, in some cases a transformation with C20.0 will be used, with the argument x2=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 xj=1.0-x is employed, and the above strategy for 0<x0.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<x0.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.
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×Imax, where Imax 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.


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


Compulsory Input Parameters

1:     a – double scalar
The parameter a.
Constraint: aarbnd.
2:     b – double scalar
The parameter b.
Constraint: barbnd.
3:     c – double scalar
The parameter c.
  • carbnd;
  • c0,-1,-2,.
4:     x – double scalar
The argument x.
Constraint: -arbnd<x1.

Optional Input Parameters


Output Parameters

1:     result – double scalar
2:     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:
Underflow occurred during the evaluation of F 1 2 a,b; c;x . The returned value may be inaccurate.
All approximations have completed, and the final residual estimate indicates some precision may have been lost.
All approximations have completed, and the final residual estimate indicates no accuracy can be guaranteed.
On entry, x=_, c=_, a+b=_.
F 1 2 a,b; c;1  is infinite in the case ca+b.
On completion, overflow occurred in the evaluation of F 1 2 a,b; c;x .
Overflow occurred in a subcalculation of F 1 2 a,b; c;x . The result may or may not be infinite.
An internal calculation has resulted in an undefined result.
On entry, a does not satisfy aarbnd=_.
On entry, b does not satisfy barbnd=_.
On entry, c does not satisfy carbnd=_.
On entry.
F 1 2 a,b; c;x  is undefined when c is zero or a negative integer.
On entry, x does not satisfy xarbnd=_.
On entry.
In general, F 1 2 a,b; c;x  is not real valued when x>1.
An unexpected error has been triggered by this routine. Please contact NAG.
Your licence key may have expired or may not have been installed correctly.
Dynamic memory allocation failed.


In general, if ifail=0, the value of F1 2 a,b;c;x  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 or 1 res1000ε
ifail=2 1000ε<res0.1
ifail=3 res>0.1
where ε is the machine precision as returned by nag_machine_precision (x02aj).
A further estimate of the residual can be constructed using equation (1), and the differential identity,
d F 1 2 a,b; c;x dx = ab c F 1 2 a+1,b+1; c+1;x d2 F 1 2 a,b; c;x dx2 = aa+1 bb+1 cc+1 F 1 2 a+2,b+2; c+2;x (4)
This estimate is however dependent upon the error involved in approximating F 1 2 a+1,b+1; c+1;x  and F 1 2 a+2,b+2; c+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 c=ci+cr=100+1.0e−6, then on a machine with 16 decimal digits of precision, the internal calculation of cr 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 nag_specfun_2f1_real_scaled (s22bf), which requires you to supply the correct decimal fraction.

Further Comments

nag_specfun_2f1_real (s22be) 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.
If ifail=0, or ifail=1, 2 or 3, a finite value will have been returned with an approximate accuracy as detailed in Accuracy.
If ifail=4 then F1 2 a,b;c;x  is infinite, and a signed infinity will have been returned. The sign of the infinity should be correct when taking the limit as x approaches 1 from below.
If ifail=5 then upon completion, F1 2 a,b;c;x > Rmax , where Rmax is the largest machine number given by nag_machine_real_largest (x02al), and hence is too large to be representable. The result will be returned as a signed infinity. The sign should be correct.
If ifail=6 then overflow occurred during a subcalculation of F1 2 a,b;c;x . A signed infinity will have been returned, however there is no guarantee that this is representative of either the magnitude or the sign of F1 2 a,b;c;x .
For all other error exits, nag_specfun_2f1_real (s22be) will return a signalling NaN
If ifail=9 then 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 ifail=32 then c is too close to a negative integer or zero on entry, and F1 2 a,b;c;x  is considered 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 cj not being negative integers,
(ii) for any cj which remain as negative integers, one of the corresponding parameters aj or bj is a negative integer of magnitude less than cj.
In the first case, the transformation coefficients Cj aj,bj,cj,xj  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 ifail=11, 21, 31 or 41 then no computation will have been performed. The actual solution may however be finite.
ifail=42 indicates x>1. Hence the requested solution is on the boundary of the principal branch of F1 2 a,b;c;x , and hence is multivalued, typically with a non-zero imaginary component. It is however strictly finite.


This example evaluates F 1 2 a,b;c;x  at a fixed set of parameters a,b and c, and for several values for the argument x.
function s22be_example

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

% Evaluate 2F1(a,b;c;x) for fixed a,b,c

a =  1.2;
b = -2.6;
c =  3.5;
x = [-4:0.25:1];
f = x;

for i = 1:21
  [f(i), ifail] = s22be(a, b, c, x(i));

fprintf(' a = %4.1f, b = %4.1f, c = %4.1f\n\n',a,b,c);
disp('    x     2F1(a,b;c;x)');

fig1 = figure;
ttext = sprintf('Gausian Hypergeometric for a=%4.1f, b=%4.1f, c=%4.1f',a,b,c);

s22be example results

 a =  1.2, b = -2.6, c =  3.5

    x     2F1(a,b;c;x)
  -4.00     12.3289
  -3.75     11.0602
  -3.50      9.8783
  -3.25      8.7806
  -3.00      7.7649
  -2.75      6.8286
  -2.50      5.9692
  -2.25      5.1841
  -2.00      4.4707
  -1.75      3.8263
  -1.50      3.2480
  -1.25      2.7330
  -1.00      2.2784
  -0.75      1.8811
  -0.50      1.5378
  -0.25      1.2453
   0.00      1.0000
   0.25      0.7983
   0.50      0.6362
   0.75      0.5094
   1.00      0.3659

PDF version (NAG web site, 64-bit version, 64-bit version)
Chapter Contents
Chapter Introduction
NAG Toolbox

© The Numerical Algorithms Group Ltd, Oxford, UK. 2009–2015