# NAG FL Interfaces19abf (kelvin_​bei)

## ▸▿ Contents

Settings help

FL Name Style:

FL Specification Language:

## 1Purpose

s19abf returns a value for the Kelvin function $\mathrm{bei}x$ via the function name.

## 2Specification

Fortran Interface
 Function s19abf ( x,
 Real (Kind=nag_wp) :: s19abf Integer, Intent (Inout) :: ifail Real (Kind=nag_wp), Intent (In) :: x
#include <nag.h>
 double s19abf_ (const double *x, Integer *ifail)
The routine may be called by the names s19abf or nagf_specfun_kelvin_bei.

## 3Description

s19abf 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 routine 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+1xa(t))sin⁡α-1xb(t)cos⁡α]$
 $+ex/22π x [(1+1xc(t))cos⁡β-1xd(t)sin⁡β]$
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 routine must fail.

## 4References

NIST Digital Library of Mathematical Functions

## 5Arguments

1: $\mathbf{x}$Real (Kind=nag_wp) Input
On entry: the argument $x$ of the function.
2: $\mathbf{ifail}$Integer Input/Output
On entry: ifail must be set to $0$, $-1$ or $1$ to set behaviour on detection of an error; these values have no effect when no error is detected.
A value of $0$ causes the printing of an error message and program execution will be halted; otherwise program execution continues. A value of $-1$ means that an error message is printed while a value of $1$ means that it is not.
If halting is not appropriate, the value $-1$ or $1$ is recommended. If message printing is undesirable, then the value $1$ is recommended. Otherwise, the value $0$ is recommended. When the value $-\mathbf{1}$ or $\mathbf{1}$ is used it is essential to test the value of ifail on exit.
On exit: ${\mathbf{ifail}}={\mathbf{0}}$ unless the routine detects an error or a warning has been flagged (see Section 6).

## 6Error Indicators and Warnings

If on entry ${\mathbf{ifail}}=0$ or $-1$, explanatory error messages are output on the current error message unit (as defined by x04aaf).
Errors or warnings detected by the routine:
${\mathbf{ifail}}=1$
On entry, ${\mathbf{x}}=⟨\mathit{\text{value}}⟩$.
Constraint: $|{\mathbf{x}}|\le ⟨\mathit{\text{value}}⟩$.
$|{\mathbf{x}}|$ is too large for an accurate result to be returned and the function returns zero.
${\mathbf{ifail}}=-99$
See Section 7 in the Introduction to the NAG Library FL Interface for further information.
${\mathbf{ifail}}=-399$
Your licence key may have expired or may not have been installed correctly.
See Section 8 in the Introduction to the NAG Library FL Interface for further information.
${\mathbf{ifail}}=-999$
Dynamic memory allocation failed.
See Section 9 in the Introduction to the NAG Library FL Interface for further information.

## 7Accuracy

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.

## 8Parallelism and Performance

s19abf is not threaded in any implementation.

None.

## 10Example

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

### 10.1Program Text

Program Text (s19abfe.f90)

### 10.2Program Data

Program Data (s19abfe.d)

### 10.3Program Results

Program Results (s19abfe.r)