Integer type:  int32  int64  nag_int  show int32  show int32  show int64  show int64  show nag_int  show nag_int

Chapter Contents
Chapter Introduction
NAG Toolbox

# NAG Toolbox: nag_specfun_arctanh (s11aa)

## Purpose

nag_specfun_arctanh (s11aa) returns the value of the inverse hyperbolic tangent, $\mathrm{arctanh}x$, via the function name.

## Syntax

[result, ifail] = s11aa(x)
[result, ifail] = nag_specfun_arctanh(x)

## Description

nag_specfun_arctanh (s11aa) calculates an approximate value for the inverse hyperbolic tangent of its argument, $\mathrm{arctanh}x$.
For ${x}^{2}\le \frac{1}{2}$ it is based on the Chebyshev expansion
 $arctanh⁡x=x×yt=x∑′r=0arTrt$
where $-\frac{1}{\sqrt{2}}\le x\le \frac{1}{\sqrt{2}}$, $\text{ }-1\le t\le 1$, $\text{ and }t=4{x}^{2}-1$.
For $\frac{1}{2}<{x}^{2}<1$, it uses
 $arctanh⁡x=12ln1+x 1-x .$
For $\left|x\right|\ge 1$, the function fails as $\mathrm{arctanh}x$ is undefined.

## References

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

## Parameters

### Compulsory Input Parameters

1:     $\mathrm{x}$ – double scalar
The argument $x$ of the function.
Constraint: $\left|{\mathbf{x}}\right|<1.0$.

None.

### Output Parameters

1:     $\mathrm{result}$ – double scalar
The result of the function.
2:     $\mathrm{ifail}$int64int32nag_int scalar
${\mathbf{ifail}}={\mathbf{0}}$ unless the function detects an error (see Error Indicators and Warnings).

## Error Indicators and Warnings

Errors or warnings detected by the function:
${\mathbf{ifail}}=1$
The function has been called with an argument greater than or equal to $1.0$ in magnitude, for which $\mathrm{arctanh}$ is not defined. On soft failure, the result is returned as zero.
${\mathbf{ifail}}=-99$
${\mathbf{ifail}}=-399$
Your licence key may have expired or may not have been installed correctly.
${\mathbf{ifail}}=-999$
Dynamic memory allocation failed.

## Accuracy

If $\delta$ and $\epsilon$ are the relative errors in the argument and result, respectively, then in principle
 $ε≃ x 1-x2 arctanh⁡x ×δ .$
That is, the relative error in the argument, $x$, is amplified by at least a factor $\frac{x}{\left(1-{x}^{2}\right)\mathrm{arctanh}x}$ in the result. The equality should hold if $\delta$ is greater than the machine precision ($\delta$ due to data errors etc.) but if $\delta$ is simply due to round-off in the machine representation then it is possible that an extra figure may be lost in internal calculation round-off.
The behaviour of the amplification factor is shown in the following graph: Figure 1
The factor is not significantly greater than one except for arguments close to $\left|x\right|=1$. However in the region where $\left|x\right|$ is close to one, $1-\left|x\right|\sim \delta$, the above analysis is inapplicable since $x$ is bounded by definition, $\left|x\right|<1$. In this region where arctanh is tending to infinity we have
 $ε∼1/ln⁡δ$
which implies an obvious, unavoidable serious loss of accuracy near $\left|x\right|\sim 1$, e.g., if $x$ and $1$ agree to $6$ significant figures, the result for $\mathrm{arctanh}x$ would be correct to at most about one figure.

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.
```function s11aa_example

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

x = [-0.5     0    0.5     -0.9999];
n = size(x,2);
result = x;

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

disp('      x        arctanh(x)');
fprintf('%12.3e%12.3e\n',[x; result]);

```
```s11aa example results

x        arctanh(x)
-5.000e-01  -5.493e-01
0.000e+00   0.000e+00
5.000e-01   5.493e-01
-9.999e-01  -4.952e+00
```