hide long namesshow long names
hide short namesshow short names
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_kelvin_kei_vector (s19ar)

 Contents

    1  Purpose
    2  Syntax
    7  Accuracy
    9  Example

Purpose

nag_specfun_kelvin_kei_vector (s19ar) returns an array of values for the Kelvin function keix.

Syntax

[f, ivalid, ifail] = s19ar(x, 'n', n)
[f, ivalid, ifail] = nag_specfun_kelvin_kei_vector(x, 'n', n)

Description

nag_specfun_kelvin_kei_vector (s19ar) evaluates an approximation to the Kelvin function keixi for an array of arguments xi, for i=1,2,,n.
Note:  for x<0 the function is undefined, so we need only consider x0.
The function is based on several Chebyshev expansions:
For 0x1,
keix=-π4ft+x24-gtlogx+vt  
where ft, gt and vt are expansions in the variable t=2x4-1;
For 1<x3,
keix=exp-98x ut  
where ut is an expansion in the variable t=x-2;
For x>3,
keix=π 2x e-x/2 1+1x ctsinβ+1xdtcosβ  
where β= x2+ π8 , and ct and dt are expansions in the variable t= 6x-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
keix=-π4+1-γ-logx2 x24  
and when x is even closer to zero simply as
keix=-π4.  
For large x, keix is asymptotically given by π 2x e-x/2 and this becomes so small that it cannot be computed without underflow and the function fails.

References

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

Parameters

Compulsory Input Parameters

1:     xn – double array
The argument xi of the function, for i=1,2,,n.
Constraint: xi0.0, for i=1,2,,n.

Optional Input Parameters

1:     n int64int32nag_int scalar
Default: the dimension of the array x.
n, the number of points.
Constraint: n0.

Output Parameters

1:     fn – double array
keixi, the function values.
2:     ivalidn int64int32nag_int array
ivalidi contains the error code for xi, for i=1,2,,n.
ivalidi=0
No error.
ivalidi=1
xi is too large, the result underflows. fi contains zero. The threshold value is the same as for ifail=1 in nag_specfun_kelvin_kei (s19ad), as defined in the Users' Note for your implementation.
ivalidi=2
xi<0.0, the function is undefined. fi contains 0.0.
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
On entry, at least one value of x was invalid.
Check ivalid for more information.
   ifail=2
Constraint: n0.
   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

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 x2 - ker1x+ kei1x δ.  
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 πx2e-x/2, which implies a strong attenuation of error. Eventually, keix, which is asymptotically given by π2x e-x/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.

Further Comments

Underflow may occur for a few values of x close to the zeros of keix, below the limit which causes a failure with ifail=1.

Example

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


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

x = [0; 0.1; 1; 2.5; 5; 10; 15];

[f, ivalid, ifail] = s19ar(x);

fprintf('     x           kei(x)   ivalid\n');
for i=1:numel(x)
  fprintf('%12.3e%12.3e%5d\n', x(i), f(i), ivalid(i));
end


s19ar example results

     x           kei(x)   ivalid
   0.000e+00  -7.854e-01    0
   1.000e-01  -7.769e-01    0
   1.000e+00  -4.950e-01    0
   2.500e+00  -1.107e-01    0
   5.000e+00   1.119e-02    0
   1.000e+01  -3.075e-04    0
   1.500e+01   7.963e-06    0

PDF version (NAG web site, 64-bit version, 64-bit version)
Chapter Contents
Chapter Introduction
NAG Toolbox

© The Numerical Algorithms Group Ltd, Oxford, UK. 2009–2015