Integer type:  int32  int64  nag_int  show int32  show int32  show int64  show int64  show nag_int  show nag_int

Chapter Contents
Chapter Introduction
NAG Toolbox

# NAG Toolbox: nag_specfun_1f1_real_scaled (s22bb)

## Purpose

nag_specfun_1f1_real_scaled (s22bb) 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)$.

## Syntax

[frm, scm, ifail] = s22bb(ani, adr, bni, bdr, x)
[frm, scm, ifail] = nag_specfun_1f1_real_scaled(ani, adr, bni, bdr, x)

## Description

nag_specfun_1f1_real_scaled (s22bb) 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 = Ma,b,x = ∑ s=0 ∞ as xs bs s! = 1 + a b x + aa+1 bb+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 $\left|{a}_{r}\right|\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{x02bb}}$. 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 or the companion (2010) for a detailed discussion of the confluent hypergeometric function including special cases, transformations, relations and asymptotic approximations.

## 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

## Parameters

### Compulsory Input Parameters

1:     $\mathrm{ani}$ – double scalar
${a}_{i}$, the nearest integer to $a$, satisfying ${a}_{i}=a-{a}_{r}$.
Constraints:
• ${\mathbf{ani}}=⌊{\mathbf{ani}}⌋$;
• $\left|{\mathbf{ani}}\right|\le \mathit{arbnd}$.
2:     $\mathrm{adr}$ – double scalar
${a}_{r}$, the signed decimal remainder satisfying ${a}_{r}=a-{a}_{i}$ and $\left|{a}_{r}\right|\le 0.5$.
Constraint: $\left|{\mathbf{adr}}\right|\le 0.5$.
Note: if $\left|{\mathbf{adr}}\right|<100.0\epsilon$, ${a}_{r}=0.0$ will be used, where $\epsilon$ is the machine precision as returned by nag_machine_precision (x02aj).
3:     $\mathrm{bni}$ – double scalar
${b}_{i}$, the nearest integer to $b$, satisfying ${b}_{i}=b-{b}_{r}$.
Constraints:
• ${\mathbf{bni}}=⌊{\mathbf{bni}}⌋$;
• $\left|{\mathbf{bni}}\right|\le \mathit{arbnd}$;
• if ${\mathbf{bdr}}=0.0$, ${\mathbf{bni}}>0$.
4:     $\mathrm{bdr}$ – double scalar
${b}_{r}$, the signed decimal remainder satisfying ${b}_{r}=b-{b}_{i}$ and $\left|{b}_{r}\right|\le 0.5$.
Constraint: $\left|{\mathbf{bdr}}\right|\le 0.5$.
Note: if $\left|{\mathbf{bdr}}-{\mathbf{adr}}\right|<100.0\epsilon$, ${a}_{r}={b}_{r}$ will be used, where $\epsilon$ is the machine precision as returned by nag_machine_precision (x02aj).
5:     $\mathrm{x}$ – double scalar
The argument $x$ of the function.
Constraint: $\left|{\mathbf{x}}\right|\le \mathit{arbnd}$.

None.

### Output Parameters

1:     $\mathrm{frm}$ – double scalar
${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{ifail}}={\mathbf{2}}$, the value of ${m}_{f}$ returned may still be correct. If overflow occurs in a subcalculation, as indicated by ${\mathbf{ifail}}={\mathbf{5}}$, this should not be assumed.
2:     $\mathrm{scm}$int64int32nag_int scalar
${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{ifail}}={\mathbf{2}}$, then ${m}_{s}\ge {I}_{\mathrm{max}}$, where ${I}_{\mathrm{max}}$ is the largest representable integer (see nag_machine_integer_max (x02bb)). If overflow occurs during a subcalculation, as indicated by ${\mathbf{ifail}}={\mathbf{5}}$, ${m}_{s}$ may or may not be greater than ${I}_{\mathrm{max}}$. In either case, ${\mathbf{scm}}={\mathbf{x02bb}}$ will have been returned.
3:     $\mathrm{ifail}$int64int32nag_int scalar
${\mathbf{ifail}}={\mathbf{0}}$ unless the function detects an error (see Error Indicators and Warnings).

## Error Indicators and Warnings

Errors or warnings detected by the function:

Cases prefixed with W are classified as warnings and do not generate an error of type NAG:error_n. See nag_issue_warnings.

W  ${\mathbf{ifail}}=1$
Underflow occurred during the evaluation of $M\left(a,b,x\right)$.
The returned value may be inaccurate.
W  ${\mathbf{ifail}}=2$
On completion, overflow occurred in the evaluation of $M\left(a,b,x\right)$.
W  ${\mathbf{ifail}}=3$
All approximations have completed, and the final residual estimate indicates some precision may have been lost.
${\mathbf{ifail}}=4$
All approximations have completed, and the final residual estimate indicates no accuracy can be guaranteed.
${\mathbf{ifail}}=5$
Overflow occurred in a subcalculation of $M\left(a,b,x\right)$.
The answer may be completely incorrect.
${\mathbf{ifail}}=11$
Constraint: $\left|{\mathbf{ani}}\right|\le \mathit{arbnd}=_$.
${\mathbf{ifail}}=13$
Constraint: ${\mathbf{ani}}=⌊{\mathbf{ani}}⌋$.
${\mathbf{ifail}}=21$
Constraint: $\left|{\mathbf{adr}}\right|\le 0.5$.
${\mathbf{ifail}}=31$
Constraint: $\left|{\mathbf{bni}}\right|\le \mathit{arbnd}=_$.
${\mathbf{ifail}}=32$
On entry$b={\mathbf{bni}}+{\mathbf{bdr}}=_$.
$M\left(a,b,x\right)$ is undefined when $b$ is zero or a negative integer.
${\mathbf{ifail}}=33$
Constraint: ${\mathbf{bni}}=⌊{\mathbf{bni}}⌋$.
${\mathbf{ifail}}=41$
Constraint: $\left|{\mathbf{bdr}}\right|\le 0.5$.
${\mathbf{ifail}}=51$
Constraint: $\left|{\mathbf{x}}\right|\le \mathit{arbnd}=_$.
${\mathbf{ifail}}=-99$
${\mathbf{ifail}}=-399$
Your licence key may have expired or may not have been installed correctly.
${\mathbf{ifail}}=-999$
Dynamic memory allocation failed.

## Accuracy

In general, if ${\mathbf{ifail}}={\mathbf{0}}$, 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 nonzero ifail will be returned. Specifically,
 ${\mathbf{ifail}}={\mathbf{0}}$ $\mathit{res}\le 1000\epsilon$ ${\mathbf{ifail}}={\mathbf{3}}$ $1000\epsilon <\mathit{res}\le 0.1$ ${\mathbf{ifail}}={\mathbf{4}}$ $\mathit{res}>0.1$
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\left(a+1,b+1,x\right)$ and $M\left(a+2,b+2,x\right)$.

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 \left|{m}_{f}\right|<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,
 $Ma,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 = lnmf + ms × ln2 .$

## Example

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

fprintf('s22bb example results\n\n');

% n values of a and b
n     = 2;

% delta is perturbation on integer values for a and b
delta = 1e-4;
amod  = [-10    -10]; arem  = [ delta -delta];
bmod  = [ 30     30]; brem  = [-delta  delta];
x     = 25;

fprintf('        a         b         x         frm   scm    M(a,b,x)\n');
for j = 1:n
[frmv(j), scmv(j), ifail] = s22bb( ...
amod(j), arem(j), bmod(j), brem(j), x);
a = amod(j) + arem(j);
b = bmod(j) + brem(j);
fprintf('%9.3f %9.3f %9.3f %11.3e %5d ', a, b, x, frmv(j), scmv(j));
print_scale(frmv(j), scmv(j));
end

% Calculate the product M1*M2
frm = prod(frmv);
scm = sum(scmv);

fprintf('\nSolution product %24.3e %5d ', frm, scm);
print_scale(frm, scm);

% Calculate the ratio M1/M2
if frmv(2) ~= 0
frm = frmv(1)/frmv(2);
scm = scmv(1) - scmv(2);
fprintf('\nSolution ratio   %24.3e %5d ', frm, scm);
print_scale(frm, scm);
end

function print_scale(frm, scm)
if scm < x02bl
scale = frm*2^double(scm);
fprintf('%11.3e\n', scale);
else
fprintf(' Not representable\n');
end
```
```s22bb example results

a         b         x         frm   scm    M(a,b,x)
-10.000    30.000    25.000  -7.733e-01   -15  -2.360e-05
-10.000    30.000    25.000  -7.732e-01   -15  -2.360e-05

Solution product                5.979e-01   -30   5.568e-10

Solution ratio                  1.000e+00     0   1.000e+00
```