nag_specfun_2f1_real_scaled (s22bfc) (PDF version)
s Chapter Contents
s Chapter Introduction
NAG Library Manual

NAG Library Function Document

nag_specfun_2f1_real_scaled (s22bfc)


    1  Purpose
    7  Accuracy

1  Purpose

nag_specfun_2f1_real_scaled (s22bfc) 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. The result is returned in the scaled form F 1 2 a,b;c;x = ffr × 2 fsc .

2  Specification

#include <nag.h>
#include <nags.h>
void  nag_specfun_2f1_real_scaled (double ani, double adr, double bni, double bdr, double cni, double cdr, double x, double *frf, Integer *scf, NagError *fail)

3  Description

nag_specfun_2f1_real_scaled (s22bfc) 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 Gauss hypergeometric function is a solution to the hypergeometric differential equation,
x1-x d2 f dx2 + c- a+b+1 x d f dx - ab 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 = 1 a a+1 a+2 a+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 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 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.
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=ai+ar, where ar0.5 and ai=a-ar 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×Imax, where Imax is the largest machine integer (see nag_max_integer (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 non-finite values of the parameters and argument on entry, and assigns non-finite values upon completion if appropriate. See Section 9 and Chapter x07.
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.

4  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

5  Arguments

1:     ani doubleInput
On entry: ai, the nearest integer to a, satisfying ai = a-ar.
  • ani=ani;
  • aniarbnd.
2:     adr doubleInput
On entry: ar, the signed decimal remainder satisfying ar = a-ai  and ar 0.5.
Constraint: adr0.5.
3:     bni doubleInput
On entry: bi, the nearest integer to b, satisfying bi = b-br.
  • bni=bni;
  • bniarbnd.
4:     bdr doubleInput
On entry: br, the signed decimal remainder satisfying br = b-bi  and br 0.5.
Constraint: bdr0.5.
5:     cni doubleInput
On entry: ci, the nearest integer to c, satisfying ci=c-cr.
  • cni=cni;
  • cniarbnd;
  • if cdr<16.0ε, cni1.0.
6:     cdr doubleInput
On entry: cr, the signed decimal remainder satisfying cr = c-ci and cr 0.5.
Constraint: cdr0.5.
7:     x doubleInput
On entry: the argument x.
Constraint: -arbnd<x1.
8:     frf double *Output
On exit: ffr, the scaled real component of the solution satisfying ffr = F 1 2 a,b;c;x × 2 -fsc , i.e., F 1 2 a,b;c;x = ffr × 2fsc. See Section 9 for the behaviour of ffr  when a finite or non-finite answer is returned.
9:     scf Integer *Output
On exit: fsc, the scaling power of two, satisfying fsc = log2 F 1 2 a,b;c;x ffr , i.e., F 1 2 a,b;c;x = ffr × 2fsc. See Section 9 for the behaviour of fsc when a non-finite answer is returned.
10:   fail NagError *Input/Output
The NAG error argument (see Section 2.7 in How to Use the NAG Library and its Documentation).

6  Error Indicators and Warnings

Dynamic memory allocation failed.
See Section in How to Use the NAG Library and its Documentation for further information.
On entry, argument value had an illegal value.
An internal calculation has resulted in an undefined result.
On entry, x=value.
In general, F 1 2 a,b;c;x  is not real valued when x>1.
On entry, x=value, c=value, a+b=value.
F 1 2 a,b;c;1  is infinite in the case ca+b.
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.
An unexpected error has been triggered by this function. Please contact NAG.
See Section 2.7.6 in How to Use the NAG Library and its Documentation for further information.
Your licence key may have expired or may not have been installed correctly.
See Section 2.7.5 in How to Use the NAG Library and its Documentation for further information.
Overflow occurred in a subcalculation of F 1 2 a,b;c;x . The answer may be completely incorrect.
On entry, adr does not satisfy adr0.5.
On entry, bdr does not satisfy bdr0.5.
On entry, cdr does not satisfy cdr0.5.
On entry, c=cni+cdr=value.
F 1 2 a,b;c;x  is undefined when c is zero or a negative integer.
ANI is non-integral.
On entry, ani=value.
Constraint: ani=ani.
bni is non-integral.
On entry, bni=value.
Constraint: bni=bni.
cni is non-integral.
On entry, cni=value.
Constraint: cni=cni.
On entry, ani does not satisfy aniarbnd=value.
On entry, bni does not satisfy bniarbnd=value.
On entry, cni does not satisfy cniarbnd=value.
On entry, x does not satisfy xarbnd=value.
All approximations have completed, and the final residual estimate indicates no accuracy can be guaranteed.
Relative residual=value.
On completion, overflow occurred in the evaluation of F 1 2 a,b;c;x .
All approximations have completed, and the final residual estimate indicates some precision may have been lost.
Relative residual=value.
Underflow occurred during the evaluation of F 1 2 a,b;c;x . The returned value may be inaccurate.

7  Accuracy

In general, if fail.code= NE_NOERROR, the value of F 1 2 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 different fail.code will be returned. Specifically,
fail.code= NE_NOERROR or NW_UNDERFLOW_WARN res1000ε
fail.code= NW_SOME_PRECISION_LOSS 1000ε<res0.1
fail.code= NE_TOTAL_PRECISION_LOSS res>0.1
where ε is the machine precision as returned by nag_machine_precision (X02AJC). Note that underflow may also have occurred if fail.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,
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 .

8  Parallelism and Performance

nag_specfun_2f1_real_scaled (s22bfc) is not threaded in any implementation.

9  Further Comments

nag_specfun_2f1_real_scaled (s22bfc) returns non-finite values when appropriate. See Chapter x07 for more information on the definitions of non-finite values.
Should a non-finite value be returned, this will be indicated in the value of fail, as detailed in the following cases.
If fail.code= NE_NOERROR or fail.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 ffr and fsc are implementation dependent. In most cases, if F 1 2 a,b;c;x = 0 , f fr = 0 and f sc = 0 will be returned, and if F 1 2 a,b;c;x  is finite, the fractional component will be bound by 0.5 f fr < 1, with f sc  chosen accordingly.
The values returned in frf (ffr) and scf (fsc) may be used to explicitly evaluate F 1 2 a,b;c;x , and may also be used to evaluate products and ratios of multiple values of F 1 2  as follows,
F 1 2 a,b;c;x = ffr × 2 fsc F 1 2 a1, b1 ;c1;x1 × F 1 2 a2, b2 ;c2;x2 = ffr1 × ffr2 × 2 fsc1 + fsc2 F 1 2 a1, b1 ;c1;x1 F 1 2 a2, b2 ;c2;x2 = ffr1 ffr2 × 2 fsc1 - fsc2 ln F 1 2 a,b;c;x = lnffr + fsc × ln2 .  
If fail.code= NE_INFINITE then F1 2 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.
If fail.code= NW_OVERFLOW_WARN then upon completion, F1 2 a,b;c;x > 2 Imax , where Imax is given by nag_max_integer (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 scf=Imax will have been returned.
If fail.code= NE_OVERFLOW then overflow occurred during a subcalculation of F1 2 a,b;c;x . The same result as for fail.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 fsc, or the scaled component ffr of F1 2 a,b;c;x .
If fail.code= NE_NOERROR, frf and scf were inaccessible to nag_specfun_2f1_real_scaled (s22bfc), and as such it is not possible to determine what their values may be following the call to nag_specfun_2f1_real_scaled (s22bfc).
For all other error exits, scf=0 will be returned and frf will be returned as a signalling NaN (see nag_create_nan (x07bbc)).
If fail.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 fail.code= NE_REAL_2 then c is too close to a negative integer or zero on entry, and F1 2 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 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 fail.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.
fail.code= NE_COMPLEX indicates x>1, and hence the requested solution is on the boundary of the principal branch of F1 2 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 nag_specfun_2f1_real_scaled (s22bfc), and subsequently calculates their product and ratio implicitly.

10.1  Program Text

Program Text (s22bfce.c)

10.2  Program Data


10.3  Program Results

Program Results (s22bfce.r)

nag_specfun_2f1_real_scaled (s22bfc) (PDF version)
s Chapter Contents
s Chapter Introduction
NAG Library Manual

© The Numerical Algorithms Group Ltd, Oxford, UK. 2016