ALNREL
This function evaluates the natural logarithm of one plus the argument, or, in the case of complex argument, the principal value of the complex natural logarithm of one plus the argument.
Function Return Value
ALNREL — Function value. (Output)
Required Arguments
X — Argument for the function. (Input)
FORTRAN 90 Interface
Generic: ALNREL (X)
Specific: The specific interface names are S_ALNREL, D_ALNREL, and C_ALNREL.
FORTRAN 77 Interface
Single: ALNREL (X)
Double: The double precision name function is DLNREL.
Complex: The complex name is CLNREL.
Description
For real arguments, the function ALNREL(X) evaluates ln(1 + x) for x > ‑1. The argument x must be greater than –1.0 to avoid evaluating the logarithm of zero or a negative number. In addition, x must not be so close to –1.0 that considerable significance is lost in evaluating 1 + x.
For complex arguments, the function CLNREL(Z) evaluates ln(1 + z). The argument z must not be so close to ‑1 that considerable significance is lost in evaluating 1 + z. If it is, a recoverable error is issued; however, z = ‑1 is a fatal error because ln(1 + z) is infinite. Finally, ∣z∣ must not overflow.
Let ρ = ∣z∣, z = x + iy and r2 = ∣1 + z∣2 = (1 + x)2 + y2 = 1 + 2x + ρ2. Now, if ρ is small, we may evaluate CLNREL(Z) accurately by
log(1 + z) = log r + iArg(z + 1)
= 1/2 log r2 + iArg(z + 1)
= 1/2 ALNREL(2x + ρ2) + iCARG(1 + z)
Comments
Informational Error
|
Type |
Code |
Description |
|
3 |
2 |
Result of ALNREL(X) is accurate to less than one‑half precision because X is too near ‑1.0. |
ALNREL evaluates the natural logarithm of (1 + X) accurate in the sense of relative error even when X is very small. This routine (as opposed to the intrinsic ALOG) should be used to maintain relative accuracy whenever X is small and accurately known.
Examples
Example 1
In this example, ln(1.189) = ALNREL(0.189) is computed and printed.
USE ALNREL_INT
USE UMACH_INT
IMPLICIT NONE
! Declare variables
INTEGER NOUT
REAL VALUE, X
! Compute
X = 0.189
VALUE = ALNREL(X)
! Print the results
CALL UMACH (2, NOUT)
WRITE (NOUT,99999) X, VALUE
99999 FORMAT (' ALNREL(', F6.3, ') = ', F6.3)
END
Output
ALNREL( 0.189) = 0.173
Example 2
In this example, ln(0.0076i) = ALNREL(–1 + 0.0076i) is computed and printed.
USE UMACH_INT
USE ALNREL_INT
IMPLICIT NONE
! Declare variables
INTEGER NOUT
COMPLEX VALUE, Z
! Compute
Z = (-1.0, 0.0076)
VALUE = ALNREL(Z)
! Print the results
CALL UMACH (2, NOUT)
WRITE (NOUT,99999) Z, VALUE
99999 FORMAT (' ALNREL((', F8.4, ',', F8.4, ')) = (', &
F8.4, ',', F8.4, ')')
END
Output
ALNREL(( -1.0000, 0.0076)) = ( -4.8796, 1.5708)
