NAG Library Function Document
nag_specfun_2f1_real (s22bec)
1 Purpose
nag_specfun_2f1_real (s22bec) returns a value for the Gauss hypergeometric function for real parameters and , and real argument .
2 Specification
#include <nag.h> |
#include <nags.h> |
double |
nag_specfun_2f1_real (double a,
double b,
double c,
double x,
NagError *fail) |
|
3 Description
nag_specfun_2f1_real (s22bec) returns a value for the Gauss hypergeometric function for real parameters , and , and for real argument .
The associated function
nag_specfun_2f1_real_scaled (s22bfc) performs the same operations, but returns
in the scaled form
to allow calculations to be performed when
is not representable as a single working precision number. It also accepts the parameters
,
and
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,
For
, it may be defined by the Gauss series,
where
is the rising factorial of
.
is undefined for
or
a negative integer.
For , the series is absolutely convergent and is finite.
For
, linear transformations of the form,
exist, where
,
.
and
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
,
is defined by analytic continuation, and for
,
is real and finite.
For
, the following apply:
- If , , and hence is finite. Solutions also exist for the degenerate cases where or are negative integers or zero.
- If , is infinite, and the sign of is determinable as approaches from below.
In the complex plane, the principal branch of is taken along the real axis from increasing. is multivalued along this branch, and for real parameters and is typically not real valued. As such, this function will not compute a solution when .
The solution strategy used by this function is primarily dependent upon the value of the argument . Once trivial cases and the case are eliminated, this proceeds as follows.
For
, sets of safe parameters
are determined, such that the values of
required for an appropriate transformation of the type
(3) may be calculated either directly or using recurrence relations from the solutions of
. If
is positive, then only transformations with
will be used, implying only
will be required, with the transformed argument
. If
is negative, in some cases a transformation with
will be used, with the argument
. 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 , an identical approach is first used with the argument . Should this fail, a linear transformation resulting in both transformed arguments satisfying is employed, and the above strategy for is utilized on both components. Further transformations in these sub-computations are however limited to single terms with no argument transformation.
For , a linear transformation mapping the argument to the interval is first employed. The strategy for is then used on each component, including possible further two term transforms. To avoid some degenerate cases, a transform mapping the argument to may also be used.
In addition to the above restrictions on
and
, an artificial bound,
arbnd, is placed on the magnitudes of
and
to minimize the occurrence of overflow in internal calculations, particularly those involving real to integer conversions.
, where
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
and
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:
a – doubleInput
-
On entry: the parameter .
Constraint:
.
- 2:
b – doubleInput
-
On entry: the parameter .
Constraint:
.
- 3:
c – doubleInput
-
On entry: the parameter .
- 4:
x – doubleInput
-
On entry: the argument .
Constraint:
.
- 5:
fail – NagError *Input/Output
-
The NAG error argument (see
Section 3.6 in the Essential Introduction).
6 Error Indicators and Warnings
- NE_ALLOC_FAIL
-
Dynamic memory allocation failed.
- NE_CANNOT_CALCULATE
-
An internal calculation has resulted in an undefined result.
- NE_COMPLEX
-
On entry, .
In general, is not real valued when .
- NE_INFINITE
-
On entry, , , .
is infinite in the case .
- 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.
- NE_OVERFLOW
-
Overflow occurred in a subcalculation of . The result may or may not be infinite.
- NE_REAL
-
On entry, .
is undefined when is zero or a negative integer.
- NE_REAL_RANGE_CONS
-
On entry,
a does not satisfy
.
On entry,
b does not satisfy
.
On entry,
c does not satisfy
.
On entry,
x does not satisfy
.
- NE_TOTAL_PRECISION_LOSS
-
All approximations have completed, and the final residual estimate indicates no accuracy can be guaranteed.
.
- NW_OVERFLOW_WARN
-
On completion, overflow occurred in the evaluation of .
- NW_SOME_PRECISION_LOSS
-
All approximations have completed, and the final residual estimate indicates some precision may have been lost.
.
- NW_UNDERFLOW_WARN
-
Underflow occurred during the evaluation of . The returned value may be inaccurate.
7 Accuracy
In general, if
NE_NOERROR, the value of
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
is made internally using equation
(1). If the magnitude of
is sufficiently large, a
different
fail.code
will be returned. Specifically,
where
is the
machine precision as returned by
nag_machine_precision (X02AJC).
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 and .
Furthermore, the accuracy of the solution, and the error estimate, can be dependent upon the accuracy of the decimal fraction of the input parameters
and
. For example, if
, then on a machine with
decimal digits of precision, the internal calculation of
will only be accurate to
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 (s22bfc), which requires you to supply the correct decimal fraction.
8 Parallelism and Performance
Not applicable.
nag_specfun_2f1_real (s22bec) 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
NE_NOERROR, or
NE_TOTAL_PRECISION_LOSS,
NW_SOME_PRECISION_LOSS or
NW_UNDERFLOW_WARN, a finite value will have been returned with an approximate accuracy as detailed in
Section 7.
If
NE_INFINITE then
is infinite, and a signed infinity will have been returned. The sign of the infinity should be correct when taking the limit as
approaches
from below.
If
NW_OVERFLOW_WARN then upon completion,
, where
is the largest machine number given by
nag_real_largest_number (X02ALC), and hence is too large to be representable. The result will be returned as a signed infinity. The sign should be correct.
If
NE_OVERFLOW then overflow occurred during a subcalculation of
. A signed infinity will have been returned, however there is no guarantee that this is representative of either the magnitude or the sign of
.
For all other error exits, nag_specfun_2f1_real (s22bec) will return a signalling NaN (see
nag_create_nan (x07bbc)).
If
NE_CANNOT_CALCULATE 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
NE_REAL then
is too close to a negative integer or zero on entry, and
is considered undefined. Note, this will also be the case when
is a negative integer, and a (possibly trivial) linear transformation of the form
(3) would result in either:
(i) |
all not being negative integers, |
(ii) |
for any which remain as negative integers, one of the corresponding parameters or is a negative integer of magnitude less than . |
In the first case, the transformation coefficients
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
NE_REAL_RANGE_CONS then no computation will have been performed. The actual solution may however be finite.
NE_COMPLEX indicates
. Hence the requested solution is on the boundary of the principal branch of
, and hence is multivalued, typically with a non-zero imaginary component. It is however strictly finite.
10 Example
This example evaluates at a fixed set of parameters and , and for several values for the argument .
10.1 Program Text
Program Text (s22bece.c)
10.2 Program Data
None.
10.3 Program Results
Program Results (s22bece.r)