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

PDF version (NAG web site, 64-bit version, 64-bit version)

Chapter Contents

Chapter Introduction

NAG Toolbox

NAG Toolbox: nag_specfun_1f1_real_scaled (s22bb)

▸▿ Contents

1 Purpose

2 Syntax

3 Description

4 References

▸▿ 5 Parameters

5.1 Compulsory Input Parameters

5.2 Optional Input Parameters

5.3 Output Parameters

6 Error Indicators and Warnings

7 Accuracy

8 Further Comments

9 Example

Purpose

nag_specfun_1f1_real_scaled (s22bb) returns a value for the confluent hypergeometric function

{}_{1}F_{1} (a; b; x)

, with real parameters

a

and

b

and real argument

x

. The solution is returned in the scaled form

{}_{1}F_{1} (a; b; x) = m_{f} \times 2^{m_{s}}

. This function is sometimes also known as Kummer's function

M (a, b, x)

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} (a; b; x)

, with real parameters

a

and

b

and real argument

x

, in the scaled form

{}_{1}F_{1} (a; b; x) = m_{f} \times 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,

{}_{1}F_{1} (a; b; x) = M (a, b, x) = \sum_{s = 0}^{\infty} \frac{{(a)}_{s} x^{s}}{{(b)}_{s} s!} = 1 + \frac{a}{b} x + \frac{a (a + 1)}{b (b + 1) 2!} x^{2} + \dots

where

{(a)}_{s} = 1 (a) (a + 1) (a + 2) \dots (a + s - 1)

is the rising factorial of

a

M (a, b, x)

is a solution to the second order ODE (Kummer's Equation):

x \frac{d^{2} M}{d x^{2}} + (b - x) \frac{d M}{d x} - a M = 0 .

(1)

Given the parameters and argument

(a, b, x)

, this function determines a set of safe values

\{(α_{i}, β_{i}, ζ_{i}) ∣ i \leq 2\}

and selects an appropriate algorithm to accurately evaluate the functions

M_{i} (α_{i}, β_{i}, ζ_{i})

. The result is then used to construct the solution to the original problem

M (a, b, x)

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}| \leq 0.5

and

a_{i} = a - a_{r}

is integral.

b

is similarly deconstructed.

Additionally, an artificial bound,

arbnd

is placed on the magnitudes of

a_{i}

b_{i}

and

x

to minimize the occurrence of overflow in internal calculations.

arbnd = 0.0001 \times I_{\max}

, where

I_{\max} = 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: $ani$ – double scalar

a_{i}

, the nearest integer to

a

, satisfying

a_{i} = a - a_{r}

Constraints:

$ani = ⌊ani⌋$ ;
$|ani| \leq arbnd$ .

2: $adr$ – double scalar

a_{r}

, the signed decimal remainder satisfying

a_{r} = a - a_{i}

and

|a_{r}| \leq 0.5

Constraint:

|adr| \leq 0.5

Note: if

|adr| < 100.0 ε

a_{r} = 0.0

will be used, where

ε

is the machine precision as returned by nag_machine_precision (x02aj).

3: $bni$ – double scalar

b_{i}

, the nearest integer to

b

, satisfying

b_{i} = b - b_{r}

Constraints:

$bni = ⌊bni⌋$ ;
$|bni| \leq arbnd$ ;
if $bdr = 0.0$ , $bni > 0$ .

4: $bdr$ – double scalar

b_{r}

, the signed decimal remainder satisfying

b_{r} = b - b_{i}

and

|b_{r}| \leq 0.5

Constraint:

|bdr| \leq 0.5

Note: if

|bdr - adr| < 100.0 ε

a_{r} = b_{r}

will be used, where

ε

is the machine precision as returned by nag_machine_precision (x02aj).

5: $x$ – double scalar

The argument

x

of the function.

Constraint:

|x| \leq arbnd

Optional Input Parameters

None.

Output Parameters

1: $frm$ – double scalar: $m_{f}$ , the scaled real component of the solution satisfying $m_{f} = M (a, b, x) \times 2^{- m_{s}}$ .
Note: if overflow occurs upon completion, as indicated by $ifail = 2$ , the value of $m_{f}$ returned may still be correct. If overflow occurs in a subcalculation, as indicated by $ifail = 5$ , this should not be assumed.
2: $scm$ – int64int32nag_int scalar: $m_{s}$ , the scaling power of two, satisfying $m_{s} = \log_{2} (\frac{M (a, b, x)}{m_{f}})$ .
Note: if overflow occurs upon completion, as indicated by $ifail = 2$ , then $m_{s} \geq I_{\max}$ , where $I_{\max}$ is the largest representable integer (see nag_machine_integer_max (x02bb)). If overflow occurs during a subcalculation, as indicated by $ifail = 5$ , $m_{s}$ may or may not be greater than $I_{\max}$ . In either case, $scm = x02bb$ will have been returned.
3: $ifail$ – int64int32nag_int scalar: $ifail = 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 $ifail = 1$: Underflow occurred during the evaluation of $M (a, b, x)$ .
The returned value may be inaccurate.

W $ifail = 2$: On completion, overflow occurred in the evaluation of $M (a, b, x)$ .

W $ifail = 3$: All approximations have completed, and the final residual estimate indicates some precision may have been lost.

$ifail = 4$: All approximations have completed, and the final residual estimate indicates no accuracy can be guaranteed.

$ifail = 5$: Overflow occurred in a subcalculation of $M (a, b, x)$ .
The answer may be completely incorrect.

$ifail = 11$: Constraint: $|ani| \leq arbnd =_$ .

$ifail = 13$: Constraint: $ani = ⌊ani⌋$ .

$ifail = 21$: Constraint: $|adr| \leq 0.5$ .

$ifail = 31$: Constraint: $|bni| \leq arbnd =_$ .

$ifail = 32$: On entry $b = bni + bdr =_$ .
$M (a, b, x)$ is undefined when $b$ is zero or a negative integer.

$ifail = 33$: Constraint: $bni = ⌊bni⌋$ .

$ifail = 41$: Constraint: $|bdr| \leq 0.5$ .

$ifail = 51$: Constraint: $|x| \leq arbnd =_$ .

$ifail = - 99$: An unexpected error has been triggered by this routine. Please contact NAG.

$ifail = - 399$: Your licence key may have expired or may not have been installed correctly.

$ifail = - 999$: Dynamic memory allocation failed.

Accuracy

In general, if

ifail = 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

res

is made internally using equation (1). If the magnitude of

res

is sufficiently large a nonzero ifail will be returned. Specifically,

$ifail = 0$	$res \leq 1000 ε$
$ifail = 3$	$1000 ε < res \leq 0.1$
$ifail = 4$	$res > 0.1$

A further estimate of the residual can be constructed using equation (1), and the differential identity,

\begin{matrix} \frac{d M (a, b, x)}{d x} & = & \frac{a}{b} M (a + 1, b + 1, x), \\ \frac{d^{2} M (a, b, x)}{d x^{2}} & = & \frac{a (a + 1)}{b (b + 1)} M (a + 2, b + 2, x) . \end{matrix}

This estimate is however dependent upon the error involved in approximating

M (a + 1, b + 1, x)

and

M (a + 2, b + 2, x)

Further Comments

The values of

m_{f}

and

m_{s}

are implementation dependent. In most cases, if

{}_{1}F_{1} (a; b; x) = 0

m_{f} = 0

and

m_{s} = 0

will be returned, and if

{}_{1}F_{1} (a; b; x) = 0

is finite, the fractional component will be bound by

0.5 \leq |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 (a, b, x)

, and may also be used to evaluate products and ratios of multiple values of

M

as follows,

\begin{matrix} M (a, b, x) & = & m_{f} \times 2^{m_{s}} \\ M (a_{1}, b_{1}, x_{1}) \times M (a_{2}, b_{2}, x_{2}) & = & (m_{f 1} \times m_{f 2}) \times 2^{(m_{s 1} + m_{s 2})} \\ \frac{M (a_{1}, b_{1}, x_{1})}{M (a_{2}, b_{2}, x_{2})} & = & \frac{m_{f 1}}{m_{f 2}} \times 2^{(m_{s 1} - m_{s 2})} \\ \ln |M (a, b, x)| & = & \ln |m_{f}| + m_{s} \times \ln (2) \end{matrix} .

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

Open in the MATLAB editor: s22bb_example

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

PDF version (NAG web site, 64-bit version, 64-bit version)

Chapter Contents

Chapter Introduction

NAG Toolbox