NAG FL Interface
s01baf (log_​shifted)

1 Purpose

s01baf returns a value of the shifted logarithmic function, ln1+x, via the function name.

2 Specification

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

3 Description

s01baf computes values of ln1+x, retaining full relative precision even when x is small. The routine is based on the Chebyshev expansion
ln1+p2+2px¯ 1+p2-2px¯ =4k=0p2k+1 2k+1 T2k+1x¯.  
Setting x¯= x1+p2 2px+2 , and choosing p= q-1 q+1 , q=24 the expansion is valid in the domain x 12-1,2-1 .
Outside this domain, ln1+x is computed by the standard logarithmic function.

4 References

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

5 Arguments

1: x Real (Kind=nag_wp) Input
On entry: the argument x of the function.
Constraint: x>-1.0.
2: 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 -1 or 1 is used it is essential to test the value of ifail on exit.
On exit: ifail=0 unless the routine detects an error or a warning has been flagged (see Section 6).

6 Error Indicators and Warnings

If on entry 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:
ifail=1
On entry, x=value.
Constraint: x>-1.0.
ifail=-99
An unexpected error has been triggered by this routine. Please contact NAG.
See Section 7 in the Introduction to the NAG Library FL Interface for further information.
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.
ifail=-999
Dynamic memory allocation failed.
See Section 9 in the Introduction to the NAG Library FL Interface for further information.

7 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 ln1+x, in s01baf.

8 Parallelism and Performance

s01baf is not threaded in any implementation.

9 Further Comments

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

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

10.1 Program Text

Program Text (s01bafe.f90)

10.2 Program Data

Program Data (s01bafe.d)

10.3 Program Results

Program Results (s01bafe.r)