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_bessel_y1_real_vector (s17ar)

## Purpose

nag_specfun_bessel_y1_real_vector (s17ar) returns an array of values of the Bessel function ${Y}_{1}\left(x\right)$.

## Syntax

[f, ivalid, ifail] = s17ar(x, 'n', n)
[f, ivalid, ifail] = nag_specfun_bessel_y1_real_vector(x, 'n', n)

## Description

nag_specfun_bessel_y1_real_vector (s17ar) evaluates an approximation to the Bessel function of the second kind ${Y}_{1}\left({x}_{i}\right)$ for an array of arguments ${x}_{\mathit{i}}$, for $\mathit{i}=1,2,\dots ,n$.
Note:  ${Y}_{1}\left(x\right)$ is undefined for $x\le 0$ and the function will fail for such arguments.
The function is based on four Chebyshev expansions:
For $0,
 $Y1 x = 2π ln⁡x x8 ∑′r=0 ar Tr t - 2πx + x8 ∑′r=0 br Tr t , with ​ t = 2 x8 2 - 1 .$
For $x>8$,
 $Y1 x = 2πx P1 x sin x - 3 π4 + Q1 x cos x - 3 π4$
where ${P}_{1}\left(x\right)=\underset{r=0}{{\sum }^{\prime }}\phantom{\rule{0.25em}{0ex}}{c}_{r}{T}_{r}\left(t\right)$,
and ${Q}_{1}\left(x\right)=\frac{8}{x}\underset{r=0}{{\sum }^{\prime }}\phantom{\rule{0.25em}{0ex}}{d}_{r}{T}_{r}\left(t\right)$, with $t=2{\left(\frac{8}{x}\right)}^{2}-1$.
For $x$ near zero, ${Y}_{1}\left(x\right)\simeq -\frac{2}{\pi x}$. This approximation is used when $x$ is sufficiently small for the result to be correct to machine precision. For extremely small $x$, there is a danger of overflow in calculating $-\frac{2}{\pi x}$ and for such arguments the function will fail.
For very large $x$, it becomes impossible to provide results with any reasonable accuracy (see Accuracy), hence the function fails. Such arguments contain insufficient information to determine the phase of oscillation of ${Y}_{1}\left(x\right)$; only the amplitude, $\sqrt{\frac{2}{\pi x}}$, can be determined and this is returned on soft failure. The range for which this occurs is roughly related to machine precision; the function will fail if .

## References

Abramowitz M and Stegun I A (1972) Handbook of Mathematical Functions (3rd Edition) Dover Publications
Clenshaw C W (1962) Chebyshev Series for Mathematical Functions Mathematical tables HMSO

## Parameters

### Compulsory Input Parameters

1:     $\mathrm{x}\left({\mathbf{n}}\right)$ – double array
The argument ${x}_{\mathit{i}}$ of the function, for $\mathit{i}=1,2,\dots ,{\mathbf{n}}$.
Constraint: ${\mathbf{x}}\left(\mathit{i}\right)>0.0$, for $\mathit{i}=1,2,\dots ,{\mathbf{n}}$.

### Optional Input Parameters

1:     $\mathrm{n}$int64int32nag_int scalar
Default: the dimension of the array x.
$n$, the number of points.
Constraint: ${\mathbf{n}}\ge 0$.

### Output Parameters

1:     $\mathrm{f}\left({\mathbf{n}}\right)$ – double array
${Y}_{1}\left({x}_{i}\right)$, the function values.
2:     $\mathrm{ivalid}\left({\mathbf{n}}\right)$int64int32nag_int array
${\mathbf{ivalid}}\left(\mathit{i}\right)$ contains the error code for ${x}_{\mathit{i}}$, for $\mathit{i}=1,2,\dots ,{\mathbf{n}}$.
${\mathbf{ivalid}}\left(i\right)=0$
No error.
${\mathbf{ivalid}}\left(i\right)=1$
 On entry, ${x}_{i}$ is too large. ${\mathbf{f}}\left(\mathit{i}\right)$ contains the amplitude of the ${Y}_{1}$ oscillation, $\sqrt{\frac{2}{\pi {x}_{i}}}$.
${\mathbf{ivalid}}\left(i\right)=2$
 On entry, ${x}_{i}\le 0.0$, ${Y}_{1}$ is undefined. ${\mathbf{f}}\left(\mathit{i}\right)$ contains $0.0$.
${\mathbf{ivalid}}\left(i\right)=3$
${x}_{i}$ is too close to zero, there is a danger of overflow. On soft failure, ${\mathbf{f}}\left(\mathit{i}\right)$ contains the value of ${Y}_{1}\left(x\right)$ at the smallest valid argument.
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.

W  ${\mathbf{ifail}}=1$
On entry, at least one value of x was invalid.
${\mathbf{ifail}}=2$
Constraint: ${\mathbf{n}}\ge 0$.
${\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

Let $\delta$ be the relative error in the argument and $E$ be the absolute error in the result. (Since ${Y}_{1}\left(x\right)$ oscillates about zero, absolute error and not relative error is significant, except for very small $x$.)
If $\delta$ is somewhat larger than the machine precision (e.g., if $\delta$ is due to data errors etc.), then $E$ and $\delta$ are approximately related by:
 $E ≃ x Y0 x - Y1 x δ$
(provided $E$ is also within machine bounds). Figure 1 displays the behaviour of the amplification factor $\left|x{Y}_{0}\left(x\right)-{Y}_{1}\left(x\right)\right|$.
However, if $\delta$ is of the same order as machine precision, then rounding errors could make $E$ slightly larger than the above relation predicts.
For very small $x$, absolute error becomes large, but the relative error in the result is of the same order as $\delta$.
For very large $x$, the above relation ceases to apply. In this region, ${Y}_{1}\left(x\right)\simeq \sqrt{\frac{2}{\pi x}}\mathrm{sin}\left(x-\frac{3\pi }{4}\right)$. The amplitude $\sqrt{\frac{2}{\pi x}}$ can be calculated with reasonable accuracy for all $x$, but $\mathrm{sin}\left(x-\frac{3\pi }{4}\right)$ cannot. If $x-\frac{3\pi }{4}$ is written as $2N\pi +\theta$ where $N$ is an integer and $0\le \theta <2\pi$, then $\mathrm{sin}\left(x-\frac{3\pi }{4}\right)$ is determined by $\theta$ only. If $x>{\delta }^{-1}$, $\theta$ cannot be determined with any accuracy at all. Thus if $x$ is greater than, or of the order of, the inverse of the machine precision, it is impossible to calculate the phase of ${Y}_{1}\left(x\right)$ and the function must fail.
Figure 1

None.

## Example

This example reads values of x from a file, evaluates the function at each value of ${x}_{i}$ and prints the results.
```function s17ar_example

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

x = [0.5; 1; 3; 6; 8; 10; 1000];

[f, ivalid, ifail] = s17ar(x);

fprintf('     x          Y_1(x)   ivalid\n');
for i=1:numel(x)
fprintf('%12.3e%12.3e%5d\n', x(i), f(i), ivalid(i));
end

```
```s17ar example results

x          Y_1(x)   ivalid
5.000e-01  -1.471e+00    0
1.000e+00  -7.812e-01    0
3.000e+00   3.247e-01    0
6.000e+00  -1.750e-01    0
8.000e+00  -1.581e-01    0
1.000e+01   2.490e-01    0
1.000e+03  -2.478e-02    0
```