Integer, Intent (In)	::	n
Integer, Intent (Inout)	::	ifail
Integer, Intent (Out)	::	ivalid(n)
Real (Kind=nag_wp), Intent (In)	::	x(n)
Real (Kind=nag_wp), Intent (Out)	::	f(n)

C Header Interface

#include <nag.h>

void	s19aqf_ (const Integer n, const double x[], double f[], Integer ivalid[], Integer ifail)

The routine may be called by the names s19aqf or nagf_specfun_kelvin_ker_vector.

3 Description

s19aqf evaluates an approximation to the Kelvin function

\ker x_{i}

for an array of arguments

x_{i}

, for

i = 1, 2, \dots, n

Note: for

x < 0

the function is undefined and at

x = 0

it is infinite so we need only consider

x > 0

The routine is based on several Chebyshev expansions:

For

0 < x \leq 1

\ker x = - f (t) \log (x) + \frac{π}{16} x^{2} g (t) + y (t)

where

f (t)

g (t)

and

y (t)

are expansions in the variable

t = 2 x^{4} - 1

For

1 < x \leq 3

\ker x = \exp (- \frac{11}{16} x) q (t)

where

q (t)

is an expansion in the variable

t = x - 2

For

x > 3

\ker x = \sqrt{\frac{π}{2 x}} e^{- x / \sqrt{2}} [(1 + \frac{1}{x} c (t)) \cos β - \frac{1}{x} d (t) \sin β]

where

β = \frac{x}{\sqrt{2}} + \frac{π}{8}

, and

c (t)

and

d (t)

are expansions in the variable

t = \frac{6}{x} - 1

When

x

is sufficiently close to zero, the result is computed as

\ker x = - γ - \log (\frac{x}{2}) + (π - \frac{3}{8} x^{2}) \frac{x^{2}}{16}

and when

x

is even closer to zero, simply as

\ker x = - γ - \log (\frac{x}{2})

For large

x

\ker x

is asymptotically given by

\sqrt{\frac{π}{2 x}} e^{- x / \sqrt{2}}

and this becomes so small that it cannot be computed without underflow and the routine fails.

4 References

NIST Digital Library of Mathematical Functions

5 Arguments

1: $n$ – Integer Input

On entry:

n

, the number of points.

Constraint:

n \geq 0

2: $x (n)$ – Real (Kind=nag_wp) array Input

On entry: the argument

x_{i}

of the function, for

i = 1, 2, \dots, n

Constraint:

x (i) > 0.0

, for

i = 1, 2, \dots, n

3: $f (n)$ – Real (Kind=nag_wp) array Output

On exit:

\ker x_{i}

, the function values.

4: $ivalid (n)$ – Integer array Output

On exit:

ivalid (i)

contains the error code for

x_{i}

, for

i = 1, 2, \dots, n

$ivalid (i) = 0$: No error.
$ivalid (i) = 1$: $x_{i}$ is too large, the result underflows. $f (i)$ contains zero. The threshold value is the same as for $ifail = 1$ in s19acf , as defined in the Users' Note for your implementation.
$ivalid (i) = 2$: $x_{i} \leq 0.0$ , the function is undefined. $f (i)$ contains $0.0$ .

5: $ifail$ – Integer Input/Output

On entry: ifail must be set to

0

−1

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

1

is recommended. If message printing is undesirable, then the value

1

is recommended. Otherwise, the value

0

is recommended. When the value $- 1$ or $1$ is used it is essential to test the value of ifail on exit.

On exit:

ifail = 0

unless the routine detects an error or a warning has been flagged (see Section 6).

6 Error Indicators and Warnings

If on entry

ifail = 0

−1

, explanatory error messages are output on the current error message unit (as defined by x04aaf).

Errors or warnings detected by the routine:

$ifail = 1$: On entry, at least one value of x was invalid.
Check ivalid for more information.

$ifail = 2$: On entry, $n = ⟨ value ⟩$ .
Constraint: $n \geq 0$ .

$ifail = - 99$: An unexpected error has been triggered by this routine. Please contact NAG.
See Section 7 in the Introduction to the NAG Library FL Interface for further information.

$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.

$ifail = - 999$: Dynamic memory allocation failed.
See Section 9 in the Introduction to the NAG Library FL Interface for further information.

7 Accuracy

Let

E

be the absolute error in the result,

ε

be the relative error in the result and

δ

be the relative error in the argument. If

δ

is somewhat larger than the machine precision, then we have:

E ≃ | \frac{x}{\sqrt{2}} (\ker_{1} x + {kei}_{1} x) | δ,

ε ≃ | \frac{x}{\sqrt{2}} \frac{\ker_{1} x + {kei}_{1} x}{\ker x} | δ .

For very small

x

, the relative error amplification factor is approximately given by

\frac{1}{| \log (x) |}

, which implies a strong attenuation of relative error. However,

ε

in general cannot be less than the machine precision.

For small

x

, errors are damped by the function and hence are limited by the machine precision.

For medium and large

x

, the error behaviour, like the function itself, is oscillatory, and hence only the absolute accuracy for the function can be maintained. For this range of

x

, the amplitude of the absolute error decays like

\sqrt{\frac{π x}{2}} e^{- x / \sqrt{2}}

which implies a strong attenuation of error. Eventually,

\ker x

, which asymptotically behaves like

\sqrt{\frac{π}{2 x}} e^{- x / \sqrt{2}}

, becomes so small that it cannot be calculated without causing underflow, and the routine returns zero. Note that for large

x

the errors are dominated by those of the standard function exp.

8 Parallelism and Performance

Background information to multithreading can be found in the Multithreading documentation.

s19aqf is not threaded in any implementation.

9 Further Comments

Underflow may occur for a few values of

x

close to the zeros of

\ker x

, below the limit which causes a failure with

ifail = 1

10 Example

This example reads values of x from a file, evaluates the function at each value of

x_{i}

and prints the results.

s19aq: FL CL CPP AD PY MB

NAG FL Interfaces19aqf (kelvin_​ker_​vector)

▸▿ Contents

1 Purpose

2 Specification

3 Description

4 References

5 Arguments

6 Error Indicators and Warnings

7 Accuracy

8 Parallelism and Performance

9 Further Comments

10 Example

10.1 Program Text

10.2 Program Data

10.3 Program Results

NAG FL Interface
s19aqf (kelvin_ker_vector)