NAG Library Function Document

nag_kelvin_kei_vector (s19arc)

+− 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

1 Purpose

nag_kelvin_kei_vector (s19arc) returns an array of values for the Kelvin function

kei x

2 Specification

#include <nag.h>

#include <nags.h>

void	nag_kelvin_kei_vector (Integer n, const double x[], double f[], Integer ivalid[], NagError *fail)

3 Description

nag_kelvin_kei_vector (s19arc) evaluates an approximation to the Kelvin function

kei x_{i}

for an array of arguments

x_{i}

, for

i = 1, 2, \dots, n

Note: for

x < 0

the function is undefined, so we need only consider

x \geq 0

The function is based on several Chebyshev expansions:

For

0 \leq x \leq 1

kei x = - \frac{π}{4} f (t) + \frac{x^{2}}{4} [- g (t) \log (x) + v (t)]

where

f (t)

g (t)

and

v (t)

are expansions in the variable

t = 2 x^{4} - 1

;

For

1 < x \leq 3

kei x = \exp (- \frac{9}{8} x) u (t)

where

u (t)

is an expansion in the variable

t = x - 2

;

For

x > 3

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

where

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

, and

c (t)

and

d (t)

are expansions in the variable

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

For

x < 0

, the function is undefined, and hence the function fails and returns zero.

When

x

is sufficiently close to zero, the result is computed as

kei x = - \frac{π}{4} + (1 - γ - \log (\frac{x}{2})) \frac{x^{2}}{4}

and when

x

is even closer to zero simply as

kei x = - \frac{π}{4} .

For large

x

kei 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 function fails.

4 References

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

5 Arguments

1: n – IntegerInput

On entry:

n

, the number of points.

Constraint:

n \geq 0

2: x[n] – const doubleInput

On entry: the argument

x_{i}

of the function, for

i = 1, 2, \dots, n

Constraint:

x [i - 1] \geq 0.0

, for

i = 1, 2, \dots, n

3: f[n] – doubleOutput

On exit:

kei x_{i}

, the function values.

4: ivalid[n] – IntegerOutput

On exit:

ivalid [i - 1]

contains the error code for

x_{i}

, for

i = 1, 2, \dots, n

$ivalid [i - 1] = 0$: No error.
$ivalid [i - 1] = 1$: $x_{i}$ is too large, the result underflows. $f [i - 1]$ contains zero. The threshold value is the same as for $fail . code =$ NE_REAL_ARG_GT in nag_kelvin_kei (s19adc), as defined in the Users' Note for your implementation.
$ivalid [i - 1] = 2$: $x_{i} < 0.0$ , the function is undefined. $f [i - 1]$ contains $0.0$ .

5: fail – NagError *Input/Output

The NAG error argument (see Section 3.6 in the Essential Introduction).

6 Error Indicators and Warnings

NE_BAD_PARAM: On entry, argument $⟨value⟩$ had an illegal value.
NE_INT: On entry, $n = ⟨value⟩$ .
Constraint: $n \geq 0$ .
NE_INTERNAL_ERROR: An internal error has occurred in this function. Check the function call and any array sizes. If the call is correct then please contact NAG for assistance.
NW_IVALID: On entry, at least one value of x was invalid.
Check ivalid for more information.

7 Accuracy

Let

E

be the absolute error in the result, and

δ

be the relative error in the argument. If

δ

is somewhat larger than the machine representation error, then we have:

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

For small

x

, errors are attenuated 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 absolute accuracy of 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,

kei x

, which is asymptotically given by

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

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

x

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

8 Parallelism and Performance

Not applicable.

9 Further Comments

Underflow may occur for a few values of

x

close to the zeros of

kei x

, below the limit which causes a failure with

fail . code =

NW_IVALID.

10 Example

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

x_{i}

and prints the results.

NAG Library Function Documentnag_kelvin_kei_vector (s19arc)

+− 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 Library Function Document

nag_kelvin_kei_vector (s19arc)