NAG Library Function Document
nag_specfun_1f1_real (s22bac)
1
Purpose
nag_specfun_1f1_real (s22bac) returns a value for the confluent hypergeometric function with real parameters and , and real argument . This function is sometimes also known as Kummer's function .
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 with real parameters and , and real argument . This function is unbounded or not uniquely defined for equal to zero or a negative integer.
The associated function
nag_specfun_1f1_real_scaled (s22bbc) 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
or
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
where
is the rising factorial of
.
is a solution to the second order ODE (Kummer's Equation):
Given the parameters and argument , this function determines a set of safe values and selects an appropriate algorithm to accurately evaluate the functions . The result is then used to construct the solution to the original problem using, where necessary, recurrence relations and/or continuation.
Additionally, an artificial bound, is placed on the magnitudes of , and to minimize the occurrence of overflow in internal calculations. , where . It should, however, not be assumed that this function will produce an accurate result for all values of , and satisfying this criterion.
Please consult the
NIST Digital Library of Mathematical Functions for a detailed discussion of the confluent hypergeometric function including special cases, transformations, relations and asymptotic approximations.
4
References
Pearson J (2009) Computation of hypergeometric functions MSc Dissertation, Mathematical Institute, University of Oxford
5
Arguments
- 1:
– doubleInput
-
On entry: the parameter of the function.
Constraint:
.
- 2:
– doubleInput
-
On entry: the parameter of the function.
Constraint:
.
- 3:
– doubleInput
-
On entry: the argument of the function.
Constraint:
.
- 4:
– double *Output
-
On exit: the solution
.
Note: if overflow occurs upon completion, as indicated by
NW_OVERFLOW_WARN,
may be assumed to be too large to be representable.
m will be returned as
, where
is the largest representable real number (see
nag_real_largest_number (X02ALC)). The sign of
m should match the sign of
. If overflow occurs during a subcalculation, as indicated by
NE_OVERFLOW, the sign may be incorrect, and the true value of
may or may not be greater than
. In either case it is advisable to subsequently use
nag_specfun_1f1_real_scaled (s22bbc).
- 5:
– NagError *Input/Output
-
The NAG error argument (see
Section 3.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 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.
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 .
The answer may be completely incorrect.
- NE_REAL
-
On entry, .
is undefined when is zero or a negative integer.
- NE_REAL_RANGE_CONS
-
On entry, .
Constraint: .
On entry, .
Constraint: .
On entry, .
Constraint: .
- NE_TOTAL_PRECISION_LOSS
-
All approximations have completed, and the final residual estimate indicates no accuracy can be guaranteed.
Relative residual .
- 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.
Relative residual .
- 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_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.
None.
10
Example
This example prints the results returned by nag_specfun_1f1_real (s22bac) called using parameters and with differing values of argument .
10.1
Program Text
Program Text (s22bace.c)
10.2
Program Data
None.
10.3
Program Results
Program Results (s22bace.r)