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_arccosh (s11ac)

## Purpose

nag_specfun_arccosh (s11ac) returns the value of the inverse hyperbolic cosine, $\mathrm{arccosh}x$, via the function name. The result is in the principal positive branch.

## Syntax

[result, ifail] = s11ac(x)
[result, ifail] = nag_specfun_arccosh(x)

## Description

nag_specfun_arccosh (s11ac) calculates an approximate value for the inverse hyperbolic cosine, $\mathrm{arccosh}x$. It is based on the relation
 $arccosh⁡x=lnx+x2-1.$
This form is used directly for $1, where $k=n/2+1$, and the machine uses approximately $n$ decimal place arithmetic.
For $x\ge {10}^{k}$, $\sqrt{{x}^{2}-1}$ is equal to $\sqrt{x}$ to within the accuracy of the machine and hence we can guard against premature overflow and, without loss of accuracy, calculate
 $arccosh⁡x=ln⁡2+ln⁡x.$

## 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: ${\mathbf{x}}\ge 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 less than $1.0$, for which $\mathrm{arccosh}x$ is not defined. The result returned is 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 x2-1 arccosh⁡x ×δ .$
That is the relative error in the argument is amplified by a factor at least $\frac{x}{\sqrt{{x}^{2}-1}\mathrm{arccosh}x}$ in the result. The equality should apply if $\delta$ is greater than the machine precision ($\delta$ due to data errors etc.) but if $\delta$ is simply a result of round-off in the machine representation it is possible that an extra figure may be lost in internal calculation and round-off. The behaviour of the amplification factor is shown in the following graph: Figure 1
It should be noted that for $x>2$ the factor is always less than $1.0$. For large $x$ we have the absolute error $E$ in the result, in principle, given by
 $E∼δ.$
This means that eventually accuracy is limited by machine precision. More significantly for $x$ close to $1$, $x-1\sim \delta$, the above analysis becomes inapplicable due to the fact that both function and argument are bounded, $x\ge 1$, $\mathrm{arccosh}x\ge 0$. In this region we have
 $E∼δ.$
That is, there will be approximately half as many decimal places correct in the result as there were correct figures in the argument.

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 s11ac_example

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

x = [1   2     5     10];
n = size(x,2);
result = x;

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

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

```
```s11ac example results

x        arccosh(x)
1.000e+00   0.000e+00
2.000e+00   1.317e+00
5.000e+00   2.292e+00
1.000e+01   2.993e+00
```