1: $result$ – double scalar: The result of the function.
2: $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.

$ifail = 1$: The function has been called with an argument that is larger in magnitude than $F$ ; the default result returned is zero.

W $ifail = 2$: The function has been called with an argument that is too close (as determined using the relative tolerance $F$ ) to an odd multiple of $π / 2$ , at which the function is infinite; the function returns a value with the correct sign but a more or less arbitrary but large magnitude (see Accuracy).

$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

δ

and

ε

are the relative errors in the argument and result respectively, then in principle

ε \geq \frac{2 x}{\sin 2 x} δ .

That is a relative error in the argument,

x

, is amplified by at least a factor

2 x / \sin 2 x

in the result.

Similarly if

E

is the absolute error in the result this is given by

E \geq \frac{x}{\cos^{2} x} δ .

The equalities should hold if

δ

is greater than the machine precision (

δ

is a result of data errors etc.) but if

δ

is simply the round-off error in the machine it is possible that internal calculation rounding will lose an extra figure.

The graphs below show the behaviour of these amplification factors.

Figure 1

Figure 2

In the principal range it is possible to preserve relative accuracy even near the zero of

\tan x

x = 0

but at the other zeros only absolute accuracy is possible. Near the infinities of

\tan x

both the relative and absolute errors become infinite and the function must fail (error

2

N

is odd and

|θ| \leq x F_{2}

the function could not return better than two figures and in all probability would produce a result that was in error in its most significant figure. Therefore the function fails and it returns the value

- sign θ (\frac{1}{|x F_{2}|}) ≃ - sign θ \tan (\frac{π}{2} - |x F_{2}|)

which is the value of the tangent at the nearest argument for which a valid call could be made.

Accuracy is also unavoidably lost if the function is called with a large argument. If

|x| > F_{1}

the function fails (error

1

) and returns zero.

Further Comments

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.

Open in the MATLAB editor: s07aa_example

function s07aa_example


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

x = [-2.0   -0.5     1.0     3.0    1.5708];
n = size(x,2);
result = x;

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

disp('      x         tan(x)');
fprintf('%12.4e%12.4e\n',[x; result]);

s07aa example results

      x         tan(x)
 -2.0000e+00  2.1850e+00
 -5.0000e-01 -5.4630e-01
  1.0000e+00  1.5574e+00
  3.0000e+00 -1.4255e-01
  1.5708e+00 -2.7224e+05

PDF version (NAG web site, 64-bit version, 64-bit version)

Chapter Contents

Chapter Introduction

NAG Toolbox