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_kelvin_bei (s19ab)

## Purpose

nag_specfun_kelvin_bei (s19ab) returns a value for the Kelvin function $\mathrm{bei}x$ via the function name.

## Syntax

[result, ifail] = s19ab(x)
[result, ifail] = nag_specfun_kelvin_bei(x)

## Description

nag_specfun_kelvin_bei (s19ab) evaluates an approximation to the Kelvin function $\mathrm{bei}x$.
Note:  $\mathrm{bei}\left(-x\right)=\mathrm{bei}x$, so the approximation need only consider $x\ge 0.0$.
The function is based on several Chebyshev expansions:
For $0\le x\le 5$,
 $bei⁡x = x24 ∑ r=0 ′ ar Tr t , with ​ t=2 x5 4 - 1 ;$
For $x>5$,
 $bei⁡x=ex/22πx 1+1xat sin⁡α-1xbtcos⁡α$
 $+ex/22π x 1+1xct cos⁡β-1xdtsin⁡β$
where $\alpha =\frac{x}{\sqrt{2}}-\frac{\pi }{8}$, $\beta =\frac{x}{\sqrt{2}}+\frac{\pi }{8}$,
and $a\left(t\right)$, $b\left(t\right)$, $c\left(t\right)$, and $d\left(t\right)$ are expansions in the variable $t=\frac{10}{x}-1$.
When $x$ is sufficiently close to zero, the result is computed as $\mathrm{bei}x=\frac{{x}^{2}}{4}$. If this result would underflow, the result returned is $\mathrm{bei}x=0.0$.
For large $x$, there is a danger of the result being totally inaccurate, as the error amplification factor grows in an essentially exponential manner; therefore the function must fail.

## References

Abramowitz M and Stegun I A (1972) Handbook of Mathematical Functions (3rd Edition) Dover Publications

## Parameters

### Compulsory Input Parameters

1:     $\mathrm{x}$ – double scalar
The argument $x$ of the function.

None.

### Output Parameters

1:     $\mathrm{result}$ – double scalar
The result of the function.
2:     $\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:
${\mathbf{ifail}}=1$
On entry, $\mathrm{abs}\left({\mathbf{x}}\right)$ is too large for an accurate result to be returned. On soft failure, the function returns zero.
${\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

Since the function is oscillatory, the absolute error rather than the relative error is important. Let $E$ be the absolute error in the function, and $\delta$ be the relative error in the argument. If $\delta$ is somewhat larger than the machine precision, then we have:
 $E≃ x2 - ber1⁡x+ bei1⁡x δ$
(provided $E$ is within machine bounds).
For small $x$ the error amplification is insignificant and thus the absolute error is effectively bounded by the machine precision.
For medium and large $x$, the error behaviour is oscillatory and its amplitude grows like $\sqrt{\frac{x}{2\pi }}{e}^{x/\sqrt{2}}$. Therefore it is impossible to calculate the functions with any accuracy when $\sqrt{x}{e}^{x/\sqrt{2}}>\frac{\sqrt{2\pi }}{\delta }$. Note that this value of $x$ is much smaller than the minimum value of $x$ for which the function overflows.

None.

## Example

This example reads values of the argument $x$ from a file, evaluates the function at each value of $x$ and prints the results.
function s19ab_example

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

x = [0.1   1    2.5   5   10   15   -1];
n = size(x,2);
result = x;

for j=1:n
[result(j), ifail] = s19ab(x(j));
end

disp('      x          bei(x)');
fprintf('%12.3e%12.3e\n',[x; result]);

s19ab example results

x          bei(x)
1.000e-01   2.500e-03
1.000e+00   2.496e-01
2.500e+00   1.457e+00
5.000e+00   1.160e-01
1.000e+01   5.637e+01
1.500e+01  -2.953e+03
-1.000e+00   2.496e-01