NAG FL Interface
s01eaf (exp_​complex)

1 Purpose

s01eaf evaluates the exponential function ez, for complex z.

2 Specification

Fortran Interface
Function s01eaf ( z, ifail)
Complex (Kind=nag_wp) :: s01eaf
Integer, Intent (Inout) :: ifail
Complex (Kind=nag_wp), Intent (In) :: z
C Header Interface
#include <nag.h>
Complex  s01eaf_ (const Complex *z, Integer *ifail)
The routine may be called by the names s01eaf or nagf_specfun_exp_complex.

3 Description

s01eaf evaluates the exponential function ez, taking care to avoid machine overflow, and giving a warning if the result cannot be computed to more than half precision. The function is evaluated as ez=excosy+isiny, where x and y are the real and imaginary parts respectively of z.
Since cosy and siny are less than or equal to 1 in magnitude, it is possible that ex may overflow although excosy or exsiny does not. In this case the alternative formula signcosyex+lncosy is used for the real part of the result, and signsinyex+lnsiny for the imaginary part. If either part of the result still overflows, a warning is returned through argument ifail.
If Imz is too large, precision may be lost in the evaluation of siny and cosy. Again, a warning is returned through ifail.

4 References

None.

5 Arguments

1: z Complex (Kind=nag_wp) Input
On entry: the argument z of the function.
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
Argument z causes overflow in real part of result: z=value,value.
ifail=2
Argument z causes overflow in imaginary part of result: z=value,value.
ifail=3
Argument z causes overflow in both real and imaginary parts of result: z=value,value.
ifail=4
The imaginary part of argument z is so large that the result is accurate to less than half precision: z=value,value.
ifail=5
The imaginary part of argument z is so large that the result has no precision: z=value,value.
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

Accuracy is limited in general only by the accuracy of the standard functions in the computation of siny, cosy and ex, where x=Rez, y=Imz. As y gets larger, precision will probably be lost due to argument reduction in the evaluation of the sine and cosine functions, until the warning error ifail=4 occurs when y gets larger than 1/ε, where ε is the machine precision. Note that on some machines, the intrinsic functions SIN and COS will not operate on arguments larger than about 1/ε, and so ifail can never return as 4.
In the comparatively rare event that the result is computed by the formulae signcosyex+lncosy and signsinyex+lnsiny, a further small loss of accuracy may be expected due to rounding errors in the logarithmic function.

8 Parallelism and Performance

s01eaf is not threaded in any implementation.

9 Further Comments

None.

10 Example

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

10.1 Program Text

Program Text (s01eafe.f90)

10.2 Program Data

Program Data (s01eafe.d)

10.3 Program Results

Program Results (s01eafe.r)