nag_specfun_1f1_real (s22bac) (PDF version)
s Chapter Contents
s Chapter Introduction
NAG Library Manual

NAG Library Function Document

nag_specfun_1f1_real (s22bac)

 Contents

    1  Purpose
    7  Accuracy

1  Purpose

nag_specfun_1f1_real (s22bac) returns a value for the confluent hypergeometric function F 1 1 a;b;x  with real parameters a and b, and real argument x. This function is sometimes also known as Kummer's function Ma,b,x.

2  Specification

#include <nag.h>
#include <nags.h>
void  nag_specfun_1f1_real (double a, double b, double x, double *m, NagError *fail)

3  Description

nag_specfun_1f1_real (s22bac) returns a value for the confluent hypergeometric function F1 1 a;b;x  with real parameters a and b, and real argument x. This function is unbounded or not uniquely defined for b equal to zero or a negative integer.
The associated function nag_specfun_1f1_real_scaled (s22bbc) performs the same operations, but returns M in the scaled form M=mf×2ms to allow calculations to be performed when M is not representable as a single working precision number. It also accepts the parameters a and b as summations of an integer and a decimal fraction, giving higher accuracy when a or b are close to an integer. In such cases, nag_specfun_1f1_real_scaled (s22bbc) should be used when high accuracy is required.
The confluent hypergeometric function is defined by the confluent series
F1 1 a;b;x = Ma,b,x = s=0 as xs bs s! = 1 + a b x + aa+1 bb+1 2! x2 +  
where as = 1 a a+1 a+2 a+s-1  is the rising factorial of a. Ma,b,x  is a solution to the second order ODE (Kummer's Equation):
x d2M dx2 + b-x dM dx - a M = 0 . (1)
Given the parameters and argument a,b,x , this function determines a set of safe values αi,βi,ζi i2  and selects an appropriate algorithm to accurately evaluate the functions Mi αi,βi,ζi . The result is then used to construct the solution to the original problem Ma,b,x  using, where necessary, recurrence relations and/or continuation.
Additionally, an artificial bound, arbnd is placed on the magnitudes of a, b and x to minimize the occurrence of overflow in internal calculations. arbnd = 0.0001 × Imax , where Imax=X02BBC. It should, however, not be assumed that this function will produce an accurate result for all values of a, b and x satisfying this criterion.
Please consult the NIST Digital Library of Mathematical Functions or the companion (2010) for a detailed discussion of the confluent hypergeoemtric 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 a of the function.
Constraint: aarbnd.
2:     b doubleInput
On entry: the parameter b of the function.
Constraint: barbnd.
3:     x doubleInput
On entry: the argument x of the function.
Constraint: xarbnd.
4:     m double *Output
On exit: the solution Ma,b,x.
Note: if overflow occurs upon completion, as indicated by fail.code= NW_OVERFLOW_WARN, Ma,b,x may be assumed to be too large to be representable. m will be returned as ±Rmax, where Rmax is the largest representable real number (see nag_real_largest_number (X02ALC)). The sign of m should match the sign of Ma,b,x. If overflow occurs during a subcalculation, as indicated by fail.code= NE_OVERFLOW, the sign may be incorrect, and the true value of Ma,b,x may or may not be greater than Rmax. In either case it is advisable to subsequently use nag_specfun_1f1_real_scaled (s22bbc).
5:     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

NE_ALLOC_FAIL
Dynamic memory allocation failed.
See Section 2.3.1.2 in How to Use the NAG Library and its Documentation for further information.
NE_BAD_PARAM
On entry, argument value had an illegal value.
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.
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.
NE_NO_LICENCE
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.
NE_OVERFLOW
Overflow occurred in a subcalculation of Ma,b,x.
The answer may be completely incorrect.
NE_REAL
On entry, b=value.
Ma,b,x is undefined when b is zero or a negative integer.
NE_REAL_RANGE_CONS
On entry, a=value.
Constraint: aarbnd=value.
On entry, b=value.
Constraint: barbnd=value.
On entry, x=value.
Constraint: xarbnd=value.
NE_TOTAL_PRECISION_LOSS
All approximations have completed, and the final residual estimate indicates no accuracy can be guaranteed.
Relative residual =value.
NW_OVERFLOW_WARN
On completion, overflow occurred in the evaluation of Ma,b,x.
NW_SOME_PRECISION_LOSS
All approximations have completed, and the final residual estimate indicates some precision may have been lost.
Relative residual =value.
NW_UNDERFLOW_WARN
Underflow occurred during the evaluation of Ma,b,x.
The returned value may be inaccurate.

7  Accuracy

In general, if fail.code= NE_NOERROR, the value of M 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 different fail.code will be returned. Specifically,
fail.code= NE_NOERROR 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).
A further estimate of the residual can be constructed using equation (1), and the differential identity,
d Ma,b,x dx = ab M a+1,b+1,x , d2 Ma,b,x dx2 = aa+1 bb+1 M a+2,b+2,x .  
This estimate is however dependent upon the error involved in approximating M a+1,b+1,x  and M a+2,b+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 b=bi+br=100+1.0e−6, then on a machine with 16 decimal digits of precision, the internal calculation of br 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_1f1_real_scaled (s22bbc), which requires you to supply the correct decimal fraction.

8  Parallelism and Performance

nag_specfun_1f1_real (s22bac) is threaded by NAG for parallel execution in multithreaded implementations of the NAG Library.
nag_specfun_1f1_real (s22bac) makes calls to BLAS and/or LAPACK routines, which may be threaded within the vendor library used by this implementation. Consult the documentation for the vendor library for further information.
Please consult the x06 Chapter Introduction for information on how to control and interrogate the OpenMP environment used within this function. Please also consult the Users' Note for your implementation for any additional implementation-specific information.

9  Further Comments

None.

10  Example

This example prints the results returned by nag_specfun_1f1_real (s22bac) called using parameters a=13.6 and b=14.2 with 11 differing values of argument x.

10.1  Program Text

Program Text (s22bace.c)

10.2  Program Data

None.

10.3  Program Results

Program Results (s22bace.r)


nag_specfun_1f1_real (s22bac) (PDF version)
s Chapter Contents
s Chapter Introduction
NAG Library Manual

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