NAG FL Interface
s17adf (bessel_y1_real)
1
Purpose
s17adf returns the value of the Bessel function ${Y}_{1}\left(x\right)$, via the function name.
2
Specification
Fortran Interface
Real (Kind=nag_wp) 
:: 
s17adf 
Integer, Intent (Inout) 
:: 
ifail 
Real (Kind=nag_wp), Intent (In) 
:: 
x 

C Header Interface
#include <nag.h>
double 
s17adf_ (const double *x, Integer *ifail) 

C++ Header Interface
#include <nag.h> extern "C" {
double 
s17adf_ (const double &x, Integer &ifail) 
}

The routine may be called by the names s17adf or nagf_specfun_bessel_y1_real.
3
Description
s17adf evaluates an approximation to the Bessel function of the second kind ${Y}_{1}\left(x\right)$.
Note: ${Y}_{1}\left(x\right)$ is undefined for $x\le 0$ and the routine will fail for such arguments.
The routine is based on four Chebyshev expansions:
For
$x>8$,
where
${P}_{1}\left(x\right)={\displaystyle \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}{\displaystyle \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 routine will fail.
For very large
$x$, it becomes impossible to provide results with any reasonable accuracy (see
Section 7), hence the routine 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 routine will fail if
$x\gtrsim 1/\mathit{machineprecision}$ (see the
Users' Note for your implementation for details).
4
References
Clenshaw C W (1962) Chebyshev Series for Mathematical Functions Mathematical tables HMSO
5
Arguments

1:
$\mathbf{x}$ – Real (Kind=nag_wp)
Input

On entry: the argument $x$ of the function.
Constraint:
${\mathbf{x}}>0.0$.

2:
$\mathbf{ifail}$ – Integer
Input/Output

On entry:
ifail must be set to
$0$,
$1\text{or}1$. If you are unfamiliar with this argument you should refer to
Section 4 in the Introduction to the NAG Library FL Interface for details.
For environments where it might be inappropriate to halt program execution when an error is detected, the value
$1\text{or}1$ is recommended. If the output of error messages is undesirable, then the value
$1$ is recommended. Otherwise, if you are not familiar with this argument, the recommended value is
$0$.
When the value $\mathbf{1}\text{or}\mathbf{1}$ is used it is essential to test the value of ifail on exit.
On exit:
${\mathbf{ifail}}={\mathbf{0}}$ unless the routine detects an error or a warning has been flagged (see
Section 6).
6
Error Indicators and Warnings
If on entry
${\mathbf{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:
 ${\mathbf{ifail}}=1$

On entry, ${\mathbf{x}}=\u2329\mathit{\text{value}}\u232a$.
Constraint: ${\mathbf{x}}\le \u2329\mathit{\text{value}}\u232a$.
$x$ is too large, the function returns the amplitude of the ${Y}_{1}$ oscillation, $\sqrt{2/\left(\pi x\right)}$.
 ${\mathbf{ifail}}=2$

On entry, ${\mathbf{x}}=\u2329\mathit{\text{value}}\u232a$.
Constraint: ${\mathbf{x}}>0.0$.
${Y}_{1}$ is undefined, the function returns zero.
 ${\mathbf{ifail}}=3$

x is too close to zero and there is danger of overflow,
${\mathbf{x}}=\u2329\mathit{\text{value}}\u232a$.
Constraint:
${\mathbf{x}}>\u2329\mathit{\text{value}}\u232a$.
The function returns the value of
${Y}_{1}\left(x\right)$ at the smallest valid argument.
 ${\mathbf{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.
 ${\mathbf{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.
 ${\mathbf{ifail}}=999$
Dynamic memory allocation failed.
See
Section 9 in the Introduction to the NAG Library FL Interface for further information.
7
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:
(provided
$E$ is also within machine bounds).
Figure 1 displays the behaviour of the amplification factor
$\leftx{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 routine must fail.
8
Parallelism and Performance
s17adf is not threaded in any implementation.
None.
10
Example
This example reads values of the argument $x$ from a file, evaluates the function at each value of $x$ and prints the results.
10.1
Program Text
10.2
Program Data
10.3
Program Results