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_log_shifted (s01ba)

## Purpose

nag_specfun_log_shifted (s01ba) returns a value of the shifted logarithmic function, $\mathrm{ln}\left(1+x\right)$, via the function name.

## Syntax

[result, ifail] = s01ba(x)
[result, ifail] = nag_specfun_log_shifted(x)

## Description

nag_specfun_log_shifted (s01ba) computes values of $\mathrm{ln}\left(1+x\right)$, retaining full relative precision even when $\left|x\right|$ is small. The function is based on the Chebyshev expansion
 $ln⁡1+p2+2px- 1+p2-2px- =4∑k=0∞p2k+1 2k+1 T2k+1x-.$
Setting $\stackrel{-}{x}=\frac{x\left(1+{p}^{2}\right)}{2p\left(x+2\right)}$, and choosing $p=\frac{q-1}{q+1}$, $q=\sqrt[4]{2}$ the expansion is valid in the domain $x\in \left[\frac{1}{\sqrt{2}}-1,\sqrt{2}-1\right]$.
Outside this domain, $\mathrm{ln}\left(1+x\right)$ is computed by the standard logarithmic function.

## References

Lyusternik L A, Chervonenkis O A and Yanpolskii A R (1965) Handbook for Computing Elementary Functions p. 57 Pergamon Press

## Parameters

### Compulsory Input Parameters

1:     $\mathrm{x}$ – double scalar
The argument $x$ of the function.
Constraint: ${\mathbf{x}}>-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$
On entry, ${\mathbf{x}}\le -1.0$.
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

The returned result should be accurate almost to machine precision, with a limit of about $20$ significant figures due to the precision of internal constants. Note however that if $x$ lies very close to $-1.0$ and is not exact (for example if $x$ is the result of some previous computation and has been rounded), then precision will be lost in the computation of $1+x$, and hence $\mathrm{ln}\left(1+x\right)$, in nag_specfun_log_shifted (s01ba).

Empirical tests show that the time taken for a call of nag_specfun_log_shifted (s01ba) usually lies between about $1.25$ and $2.5$ times the time for a call to the standard logarithm function.

## Example

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

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

x = [2.5  1.25e-1 -9.06e-1  1.29e-3 -7.83e-6  1.00e-9];
n = size(x,2);
result = x;

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

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

```
```s01ba example results

x         log(1+x)
2.5000e+00  1.2528e+00
1.2500e-01  1.1778e-01
-9.0600e-01 -2.3645e+00
1.2900e-03  1.2892e-03
-7.8300e-06 -7.8300e-06
1.0000e-09  1.0000e-09
```