NAG CL Interfaces22bbc (hyperg_​confl_​real_​scaled)

Settings help

CL Name Style:

1Purpose

s22bbc returns a value for the confluent hypergeometric function ${}_{1}F_{1}\left(a;b;x\right)$, with real parameters $a$ and $b$ and real argument $x$. The solution is returned in the scaled form ${}_{1}F_{1}\left(a;b;x\right)={m}_{f}×{2}^{{m}_{s}}$. This function is sometimes also known as Kummer's function $M\left(a,b,x\right)$.

2Specification

 #include
 void s22bbc (double ani, double adr, double bni, double bdr, double x, double *frm, Integer *scm, NagError *fail)
The function may be called by the names: s22bbc, nag_specfun_hyperg_confl_real_scaled or nag_specfun_1f1_real_scaled.

3Description

s22bbc returns a value for the confluent hypergeometric function ${}_{1}F_{1}\left(a;b;x\right)$, with real parameters $a$ and $b$ and real argument $x$, in the scaled form ${}_{1}F_{1}\left(a;b;x\right)={m}_{f}×{2}^{{m}_{s}}$, where ${m}_{f}$ is the real scaled component and ${m}_{s}$ is the integer power of two scaling. This function is unbounded or not uniquely defined for $b$ equal to zero or a negative integer.
The confluent hypergeometric function is defined by the confluent series,
 $F1 1 (a;b;x) = M(a,b,x) = ∑ s=0 ∞ (a)s xs (b)s s! = 1 + a b x + a(a+1) b(b+1) 2! x2 + ⋯$
where ${\left(a\right)}_{s}=1\left(a\right)\left(a+1\right)\left(a+2\right)\dots \left(a+s-1\right)$ is the rising factorial of $a$. $M\left(a,b,x\right)$ 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 $\left(a,b,x\right)$, this function determines a set of safe values $\left\{\left({\alpha }_{i},{\beta }_{i},{\zeta }_{i}\right)\mid i\le 2\right\}$ and selects an appropriate algorithm to accurately evaluate the functions ${M}_{i}\left({\alpha }_{i},{\beta }_{i},{\zeta }_{i}\right)$. The result is then used to construct the solution to the original problem $M\left(a,b,x\right)$ using, where necessary, recurrence relations and/or continuation.
For improved precision in the final result, this function accepts $a$ and $b$ split into an integral and a decimal fractional component. Specifically $a={a}_{i}+{a}_{r}$, where $|{a}_{r}|\le 0.5$ and ${a}_{i}=a-{a}_{r}$ is integral. $b$ is similarly deconstructed.
Additionally, an artificial bound, $\mathit{arbnd}$ is placed on the magnitudes of ${a}_{i}$, ${b}_{i}$ and $x$ to minimize the occurrence of overflow in internal calculations. $\mathit{arbnd}=0.0001×{I}_{\mathrm{max}}$, where ${I}_{\mathrm{max}}={\mathbf{X02BBC}}$. It should, however, not be assumed that this function will produce an accurate result for all values of ${a}_{i}$, ${b}_{i}$ and $x$ 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.
NIST Digital Library of Mathematical Functions
Pearson J (2009) Computation of hypergeometric functions MSc Dissertation, Mathematical Institute, University of Oxford

5Arguments

1: $\mathbf{ani}$double Input
On entry: ${a}_{i}$, the nearest integer to $a$, satisfying ${a}_{i}=a-{a}_{r}$.
Constraints:
• ${\mathbf{ani}}=⌊{\mathbf{ani}}⌋$;
• $|{\mathbf{ani}}|\le \mathit{arbnd}$.
2: $\mathbf{adr}$double Input
On entry: ${a}_{r}$, the signed decimal remainder satisfying ${a}_{r}=a-{a}_{i}$ and $|{a}_{r}|\le 0.5$.
Constraint: $|{\mathbf{adr}}|\le 0.5$.
Note: if $|{\mathbf{adr}}|<100.0\epsilon$, ${a}_{r}=0.0$ will be used, where $\epsilon$ is the machine precision as returned by X02AJC.
3: $\mathbf{bni}$double Input
On entry: ${b}_{i}$, the nearest integer to $b$, satisfying ${b}_{i}=b-{b}_{r}$.
Constraints:
• ${\mathbf{bni}}=⌊{\mathbf{bni}}⌋$;
• $|{\mathbf{bni}}|\le \mathit{arbnd}$;
• if ${\mathbf{bdr}}=0.0$, ${\mathbf{bni}}>0$.
4: $\mathbf{bdr}$double Input
On entry: ${b}_{r}$, the signed decimal remainder satisfying ${b}_{r}=b-{b}_{i}$ and $|{b}_{r}|\le 0.5$.
Constraint: $|{\mathbf{bdr}}|\le 0.5$.
Note: if $|{\mathbf{bdr}}-{\mathbf{adr}}|<100.0\epsilon$, ${a}_{r}={b}_{r}$ will be used, where $\epsilon$ is the machine precision as returned by X02AJC.
5: $\mathbf{x}$double Input
On entry: the argument $x$ of the function.
Constraint: $|{\mathbf{x}}|\le \mathit{arbnd}$.
6: $\mathbf{frm}$double * Output
On exit: ${m}_{f}$, the scaled real component of the solution satisfying ${m}_{f}=M\left(a,b,x\right)×{2}^{-{m}_{s}}$.
Note: if overflow occurs upon completion, as indicated by ${\mathbf{fail}}\mathbf{.}\mathbf{code}=$ NW_OVERFLOW_WARN, the value of ${m}_{f}$ returned may still be correct. If overflow occurs in a subcalculation, as indicated by ${\mathbf{fail}}\mathbf{.}\mathbf{code}=$ NE_OVERFLOW, this should not be assumed.
7: $\mathbf{scm}$Integer * Output
On exit: ${m}_{s}$, the scaling power of two, satisfying ${m}_{s}={\mathrm{log}}_{2}\left(\frac{M\left(a,b,x\right)}{{m}_{f}}\right)$.
Note: if overflow occurs upon completion, as indicated by ${\mathbf{fail}}\mathbf{.}\mathbf{code}=$ NW_OVERFLOW_WARN, then ${m}_{s}\ge {I}_{\mathrm{max}}$, where ${I}_{\mathrm{max}}$ is the largest representable integer (see X02BBC). If overflow occurs during a subcalculation, as indicated by ${\mathbf{fail}}\mathbf{.}\mathbf{code}=$ NE_OVERFLOW, ${m}_{s}$ may or may not be greater than ${I}_{\mathrm{max}}$. In either case, ${\mathbf{scm}}={\mathbf{nag_max_integer}}$ will have been returned.
8: $\mathbf{fail}$NagError * Input/Output
The NAG error argument (see Section 7 in the Introduction to the NAG Library CL Interface).

6Error Indicators and Warnings

NE_ALLOC_FAIL
Dynamic memory allocation failed.
See Section 3.1.2 in the Introduction to the NAG Library CL Interface for further information.
On entry, argument $⟨\mathit{\text{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.
See Section 7.5 in the Introduction to the NAG Library CL Interface for further information.
NE_NO_LICENCE
Your licence key may have expired or may not have been installed correctly.
See Section 8 in the Introduction to the NAG Library CL Interface for further information.
NE_OVERFLOW
Overflow occurred in a subcalculation of $M\left(a,b,x\right)$.
The answer may be completely incorrect.
NE_REAL
On entry, ${\mathbf{adr}}=⟨\mathit{\text{value}}⟩$.
Constraint: $|{\mathbf{adr}}|\le 0.5$.
On entry, ${\mathbf{bdr}}=⟨\mathit{\text{value}}⟩$.
Constraint: $|{\mathbf{bdr}}|\le 0.5$.
NE_REAL_2
On entry, $b={\mathbf{bni}}+{\mathbf{bdr}}=⟨\mathit{\text{value}}⟩$.
$M\left(a,b,x\right)$ is undefined when $b$ is zero or a negative integer.
NE_REAL_ARG_NON_INTEGRAL
ani is non-integral.
On entry, ${\mathbf{ani}}=⟨\mathit{\text{value}}⟩$.
Constraint: ${\mathbf{ani}}=⌊{\mathbf{ani}}⌋$.
bni is non-integral.
On entry, ${\mathbf{bni}}=⟨\mathit{\text{value}}⟩$.
Constraint: ${\mathbf{bni}}=⌊{\mathbf{bni}}⌋$.
NE_REAL_RANGE_CONS
On entry, ${\mathbf{ani}}=⟨\mathit{\text{value}}⟩$.
Constraint: $|{\mathbf{ani}}|\le \mathit{arbnd}=⟨\mathit{\text{value}}⟩$.
On entry, ${\mathbf{bni}}=⟨\mathit{\text{value}}⟩$.
Constraint: $|{\mathbf{bni}}|\le \mathit{arbnd}=⟨\mathit{\text{value}}⟩$.
On entry, ${\mathbf{x}}=⟨\mathit{\text{value}}⟩$.
Constraint: $|{\mathbf{x}}|\le \mathit{arbnd}=⟨\mathit{\text{value}}⟩$.
NE_TOTAL_PRECISION_LOSS
All approximations have completed, and the final residual estimate indicates no accuracy can be guaranteed.
Relative residual $\text{}=⟨\mathit{\text{value}}⟩$.
NW_OVERFLOW_WARN
On completion, overflow occurred in the evaluation of $M\left(a,b,x\right)$.
NW_SOME_PRECISION_LOSS
All approximations have completed, and the final residual estimate indicates some precision may have been lost.
Relative residual $\text{}=⟨\mathit{\text{value}}⟩$.
NW_UNDERFLOW_WARN
Underflow occurred during the evaluation of $M\left(a,b,x\right)$.
The returned value may be inaccurate.

7Accuracy

In general, if ${\mathbf{fail}}\mathbf{.}\mathbf{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 $\mathit{res}$ is made internally using equation (1). If the magnitude of $\mathit{res}$ is sufficiently large a different fail.code will be returned. Specifically,
 ${\mathbf{fail}}\mathbf{.}\mathbf{code}=$ NE_NOERROR $\mathit{res}\le 1000\epsilon$ ${\mathbf{fail}}\mathbf{.}\mathbf{code}=$ NW_SOME_PRECISION_LOSS $1000\epsilon <\mathit{res}\le 0.1$ ${\mathbf{fail}}\mathbf{.}\mathbf{code}=$ NE_TOTAL_PRECISION_LOSS $\mathit{res}>0.1$
A further estimate of the residual can be constructed using equation (1), and the differential identity,
 $d M(a,b,x) dx = ab M (a+1,b+1,x) , d2 M(a,b,x) dx2 = a(a+1) b(b+1) M (a+2,b+2,x) .$
This estimate is however, dependent upon the error involved in approximating $M\left(a+1,b+1,x\right)$ and $M\left(a+2,b+2,x\right)$.

8Parallelism and Performance

s22bbc is threaded by NAG for parallel execution in multithreaded implementations of the NAG Library.
s22bbc 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.

The values of ${m}_{f}$ and ${m}_{s}$ are implementation dependent. In most cases, if ${}_{1}F_{1}\left(a;b;x\right)=0$, ${m}_{f}=0$ and ${m}_{s}=0$ will be returned, and if ${}_{1}F_{1}\left(a;b;x\right)=0$ is finite, the fractional component will be bound by $0.5\le |{m}_{f}|<1$, with ${m}_{s}$ chosen accordingly.
The values returned in frm (${m}_{f}$) and scm (${m}_{s}$) may be used to explicitly evaluate $M\left(a,b,x\right)$, and may also be used to evaluate products and ratios of multiple values of $M$ as follows,
 $M(a,b,x) = mf × 2ms M (a1,b1,x1) × M (a2,b2,x2) = (mf1×mf2) × 2 (ms1+ms2) M (a1,b1,x1) M (a2,b2,x2) = mf1 mf2 × 2 (ms1-ms2) ln|M(a,b,x)| = ln|mf| + ms × ln(2) .$

10Example

This example evaluates the confluent hypergeometric function at two points in scaled form using s22bbc, and subsequently calculates their product and ratio without having to explicitly construct $M$.

10.1Program Text

Program Text (s22bbce.c)

None.

10.3Program Results

Program Results (s22bbce.r)