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_airy_ai_complex (s17dg)

## Purpose

nag_specfun_airy_ai_complex (s17dg) returns the value of the Airy function $\mathrm{Ai}\left(z\right)$ or its derivative ${\mathrm{Ai}}^{\prime }\left(z\right)$ for complex $z$, with an option for exponential scaling.

## Syntax

[ai, nz, ifail] = s17dg(deriv, z, scal)
[ai, nz, ifail] = nag_specfun_airy_ai_complex(deriv, z, scal)

## Description

nag_specfun_airy_ai_complex (s17dg) returns a value for the Airy function $\mathrm{Ai}\left(z\right)$ or its derivative ${\mathrm{Ai}}^{\prime }\left(z\right)$, where $z$ is complex, $-\pi <\mathrm{arg}z\le \pi$. Optionally, the value is scaled by the factor ${e}^{2z\sqrt{z}/3}$.
The function is derived from the function CAIRY in Amos (1986). It is based on the relations $\mathrm{Ai}\left(z\right)=\frac{\sqrt{z}{K}_{1/3}\left(w\right)}{\pi \sqrt{3}}$, and ${\mathrm{Ai}}^{\prime }\left(z\right)=\frac{-z{K}_{2/3}\left(w\right)}{\pi \sqrt{3}}$, where ${K}_{\nu }$ is the modified Bessel function and $w=2z\sqrt{z}/3$.
For very large $\left|z\right|$, argument reduction will cause total loss of accuracy, and so no computation is performed. For slightly smaller $\left|z\right|$, the computation is performed but results are accurate to less than half of machine precision. If $\mathrm{Re}\left(w\right)$ is too large, and the unscaled function is required, there is a risk of overflow and so no computation is performed. In all the above cases, a warning is given by the function.

## References

Abramowitz M and Stegun I A (1972) Handbook of Mathematical Functions (3rd Edition) Dover Publications
Amos D E (1986) Algorithm 644: A portable package for Bessel functions of a complex argument and non-negative order ACM Trans. Math. Software 12 265–273

## Parameters

### Compulsory Input Parameters

1:     $\mathrm{deriv}$ – string (length ≥ 1)
Specifies whether the function or its derivative is required.
${\mathbf{deriv}}=\text{'F'}$
$\mathrm{Ai}\left(z\right)$ is returned.
${\mathbf{deriv}}=\text{'D'}$
${\mathrm{Ai}}^{\prime }\left(z\right)$ is returned.
Constraint: ${\mathbf{deriv}}=\text{'F'}$ or $\text{'D'}$.
2:     $\mathrm{z}$ – complex scalar
The argument $z$ of the function.
3:     $\mathrm{scal}$ – string (length ≥ 1)
The scaling option.
${\mathbf{scal}}=\text{'U'}$
The result is returned unscaled.
${\mathbf{scal}}=\text{'S'}$
The result is returned scaled by the factor ${e}^{2z\sqrt{z}/3}$.
Constraint: ${\mathbf{scal}}=\text{'U'}$ or $\text{'S'}$.

None.

### Output Parameters

1:     $\mathrm{ai}$ – complex scalar
The required function or derivative value.
2:     $\mathrm{nz}$int64int32nag_int scalar
Indicates whether or not ai is set to zero due to underflow. This can only occur when ${\mathbf{scal}}=\text{'U'}$.
${\mathbf{nz}}=0$
ai is not set to zero.
${\mathbf{nz}}=1$
ai is set to zero.
3:     $\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.

${\mathbf{ifail}}=1$
 On entry, ${\mathbf{deriv}}\ne \text{'F'}$ or $\text{'D'}$. or ${\mathbf{scal}}\ne \text{'U'}$ or $\text{'S'}$.
${\mathbf{ifail}}=2$
No computation has been performed due to the likelihood of overflow, because $\mathrm{Re}\left(w\right)$ is too large, where $w=2{\mathbf{z}}\sqrt{{\mathbf{z}}}/3$ – how large depends on z and the overflow threshold of the machine. This error exit can only occur when ${\mathbf{scal}}=\text{'U'}$.
W  ${\mathbf{ifail}}=3$
The computation has been performed, but the errors due to argument reduction in elementary functions make it likely that the result returned by nag_specfun_airy_ai_complex (s17dg) is accurate to less than half of machine precision. This error exit may occur if $\mathrm{abs}\left({\mathbf{z}}\right)$ is greater than a machine-dependent threshold value.
${\mathbf{ifail}}=4$
No computation has been performed because the errors due to argument reduction in elementary functions mean that all precision in the result returned by nag_specfun_airy_ai_complex (s17dg) would be lost. This error exit may occur if $\mathrm{abs}\left({\mathbf{z}}\right)$ is greater than a machine-dependent threshold value.
${\mathbf{ifail}}=5$
No result is returned because the algorithm termination condition has not been met. This may occur because the arguments supplied to nag_specfun_airy_ai_complex (s17dg) would have caused overflow or underflow.
${\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

All constants in nag_specfun_airy_ai_complex (s17dg) are given to approximately $18$ digits of precision. Calling the number of digits of precision in the floating-point arithmetic being used $t$, then clearly the maximum number of correct digits in the results obtained is limited by $p=\mathrm{min}\phantom{\rule{0.125em}{0ex}}\left(t,18\right)$. Because of errors in argument reduction when computing elementary functions inside nag_specfun_airy_ai_complex (s17dg), the actual number of correct digits is limited, in general, by $p-s$, where $s\approx \mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,\left|{\mathrm{log}}_{10}\left|z\right|\right|\right)$ represents the number of digits lost due to the argument reduction. Thus the larger the value of $\left|z\right|$, the less the precision in the result.
Empirical tests with modest values of $z$, checking relations between Airy functions $\mathrm{Ai}\left(z\right)$, ${\mathrm{Ai}}^{\prime }\left(z\right)$, $\mathrm{Bi}\left(z\right)$ and ${\mathrm{Bi}}^{\prime }\left(z\right)$, have shown errors limited to the least significant $3$ – $4$ digits of precision.

Note that if the function is required to operate on a real argument only, then it may be much cheaper to call nag_specfun_airy_ai_real (s17ag) or nag_specfun_airy_ai_deriv (s17aj).

## Example

This example prints a caption and then proceeds to read sets of data from the input data stream. The first datum is a value for the argument deriv, the second is a complex value for the argument, z, and the third is a character value to set the argument scal. The program calls the function and prints the results. The process is repeated until the end of the input data stream is encountered.
```function s17dg_example

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

z  = [0.3 + 0.4i;  0.2 + 0i;  1.1 - 6.6i;  1.1 - 6.6i; -1 + 0i];
deriv = {'F';      'F';       'F';         'F';         'D'};
scal  = {'U';      'U';       'U';         'S';         'U'};

fprintf('deriv        z        scaled?         Ai(z)       nz\n');
for i=1:numel(z)

[cy, nz, ifail] = s17dg(deriv{i}, complex(z(i)), scal{i});

fprintf('  %s  %7.3f%+7.3fi', deriv{i}, real(z(i)), imag(z(i)));
if scal{i} == 'U'
fprintf('  unscaled');
else
fprintf('    scaled');
end
fprintf(' %7.3f%+8.3fi %3d\n', real(cy), imag(cy), nz);
end

```
```s17dg example results

deriv        z        scaled?         Ai(z)       nz
F    0.300 +0.400i  unscaled   0.272  -0.100i   0
F    0.200 +0.000i  unscaled   0.304  +0.000i   0
F    1.100 -6.600i  unscaled -43.663 -47.903i   0
F    1.100 -6.600i    scaled   0.165  +0.060i   0
D   -1.000 +0.000i  unscaled  -0.010  +0.000i   0
```