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_exp_complex (s01ea)

## Purpose

nag_specfun_exp_complex (s01ea) evaluates the exponential function ${e}^{z}$, for complex $z$.

## Syntax

[result, ifail] = s01ea(z)
[result, ifail] = nag_specfun_exp_complex(z)

## Description

nag_specfun_exp_complex (s01ea) evaluates the exponential function ${e}^{z}$, 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 ${e}^{z}={e}^{x}\left(\mathrm{cos}y+i\mathrm{sin}y\right)$, where $x$ and $y$ are the real and imaginary parts respectively of $z$.
Since $\mathrm{cos}y$ and $\mathrm{sin}y$ are less than or equal to $1$ in magnitude, it is possible that ${e}^{x}$ may overflow although ${e}^{x}\mathrm{cos}y$ or ${e}^{x}\mathrm{sin}y$ does not. In this case the alternative formula $\mathrm{sign}\left(\mathrm{cos}y\right){e}^{x+\mathrm{ln}\left|\mathrm{cos}y\right|}$ is used for the real part of the result, and $\mathrm{sign}\left(\mathrm{sin}y\right){e}^{x+\mathrm{ln}\left|\mathrm{sin}y\right|}$ for the imaginary part. If either part of the result still overflows, a warning is returned through argument ifail.
If $\mathrm{Im}\left(z\right)$ is too large, precision may be lost in the evaluation of $\mathrm{sin}y$ and $\mathrm{cos}y$. Again, a warning is returned through ifail.

None.

## Parameters

### Compulsory Input Parameters

1:     $\mathrm{z}$ – complex scalar
The argument $z$ of the function.

None.

### Output Parameters

1:     $\mathrm{result}$ – complex 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:

Cases prefixed with W are classified as warnings and do not generate an error of type NAG:error_n. See nag_issue_warnings.

W  ${\mathbf{ifail}}=1$
The real part of the result overflows, and is set to the largest safe number with the correct sign. The imaginary part of the result is meaningful.
W  ${\mathbf{ifail}}=2$
The imaginary part of the result overflows, and is set to the largest safe number with the correct sign. The real part of the result is meaningful.
W  ${\mathbf{ifail}}=3$
Both real and imaginary parts of the result overflow, and are set to the largest safe number with the correct signs.
W  ${\mathbf{ifail}}=4$
The computed result is accurate to less than half precision, due to the size of $\mathrm{Im}\left(z\right)$.
${\mathbf{ifail}}=5$
The computed result has no precision, due to the size of $\mathrm{Im}\left(z\right)$, and is set to 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

Accuracy is limited in general only by the accuracy of the standard functions in the computation of $\mathrm{sin}y$, $\mathrm{cos}y$ and ${e}^{x}$, where $x=\mathrm{Re}\left(z\right)$, $y=\mathrm{Im}\left(z\right)$. 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 ${\mathbf{ifail}}={\mathbf{4}}$ occurs when $y$ gets larger than $\sqrt{1/\epsilon }$, where $\epsilon$ is the machine precision. Note that on some machines, the intrinsic functions SIN and COS will not operate on arguments larger than about $\sqrt{1/\epsilon }$, and so ifail can never return as $4$.
In the comparatively rare event that the result is computed by the formulae $\mathrm{sign}\left(\mathrm{cos}y\right){e}^{x+\mathrm{ln}\left|\mathrm{cos}y\right|}$ and $\mathrm{sign}\left(\mathrm{sin}y\right){e}^{x+\mathrm{ln}\left|\mathrm{sin}y\right|}$, a further small loss of accuracy may be expected due to rounding errors in the logarithmic function.

None.

## Example

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

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

n = 4;
z(1:n) = [1 + 1.e-9i    -0.5 + 2i     0.0 - 2i    -2.5 - 1.5i];
result = z;

for j=1:n
[result(j), ifail] = s01ea(z(j));
end

disp('         z                 exp(z)');
disp([z; result]');

```
```s01ea example results

z                 exp(z)
1.0000 - 0.0000i   2.7183 - 0.0000i
-0.5000 - 2.0000i  -0.2524 - 0.5515i
0.0000 + 2.0000i  -0.4161 + 0.9093i
-2.5000 + 1.5000i   0.0058 + 0.0819i

```