# NAG FL Interfaces11acf (arccosh)

## ▸▿ Contents

Settings help

FL Name Style:

FL Specification Language:

## 1Purpose

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

## 2Specification

Fortran Interface
 Function s11acf ( x,
 Real (Kind=nag_wp) :: s11acf Integer, Intent (Inout) :: ifail Real (Kind=nag_wp), Intent (In) :: x
#include <nag.h>
 double s11acf_ (const double *x, Integer *ifail)
The routine may be called by the names s11acf or nagf_specfun_arccosh.

## 3Description

s11acf calculates an approximate value for the inverse hyperbolic cosine, $\mathrm{arccosh}x$. It is based on the relation
 $arccosh⁡x=ln(x+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.$

## 4References

NIST Digital Library of Mathematical Functions

## 5Arguments

1: $\mathbf{x}$Real (Kind=nag_wp) Input
On entry: the argument $x$ of the function.
Constraint: ${\mathbf{x}}\ge 1.0$.
2: $\mathbf{ifail}$Integer Input/Output
On entry: ifail must be set to $0$, $-1$ or $1$ to set behaviour on detection of an error; these values have no effect when no error is detected.
A value of $0$ causes the printing of an error message and program execution will be halted; otherwise program execution continues. A value of $-1$ means that an error message is printed while a value of $1$ means that it is not.
If halting is not appropriate, the value $-1$ or $1$ is recommended. If message printing is undesirable, then the value $1$ is recommended. Otherwise, the value $0$ is recommended. When the value $-\mathbf{1}$ or $\mathbf{1}$ is used it is essential to test the value of ifail on exit.
On exit: ${\mathbf{ifail}}={\mathbf{0}}$ unless the routine detects an error or a warning has been flagged (see Section 6).

## 6Error Indicators and Warnings

If on entry ${\mathbf{ifail}}=0$ or $-1$, explanatory error messages are output on the current error message unit (as defined by x04aaf).
Errors or warnings detected by the routine:
${\mathbf{ifail}}=1$
On entry, ${\mathbf{x}}=⟨\mathit{\text{value}}⟩$.
Constraint: ${\mathbf{x}}\ge 1.0$.
The routine has been called with an argument less than $1.0$, for which $\mathrm{arccosh}x$ is not defined.
${\mathbf{ifail}}=-99$
See Section 7 in the Introduction to the NAG Library FL Interface for further information.
${\mathbf{ifail}}=-399$
Your licence key may have expired or may not have been installed correctly.
See Section 8 in the Introduction to the NAG Library FL Interface for further information.
${\mathbf{ifail}}=-999$
Dynamic memory allocation failed.
See Section 9 in the Introduction to the NAG Library FL Interface for further information.

## 7Accuracy

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:
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.

## 8Parallelism and Performance

s11acf is not threaded in any implementation.

None.

## 10Example

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

### 10.1Program Text

Program Text (s11acfe.f90)

### 10.2Program Data

Program Data (s11acfe.d)

### 10.3Program Results

Program Results (s11acfe.r)