naginterfaces.library.specfun.hankel_​complex

naginterfaces.library.specfun.hankel_complex(m, fnu, z, n, scal)

hankel_complex returns a sequence of values for the Hankel functions $H_{\nu +n}^{\left(1\right)}\left(z\right)$ or $H_{\nu +n}^{\left(2\right)}\left(z\right)$ for complex $z$, non-negative $\nu$ and $n=0,1,\dots ,N-1$, with an option for exponential scaling.

For full information please refer to the NAG Library document for s17dl

https://support.nag.com/numeric/nl/nagdoc_30.3/flhtml/s/s17dlf.html

Parameters

mint

The kind of functions required.

$m=1$

The functions are $H_{\nu }^{\left(1\right)}\left(z\right)$.

$m=2$

The functions are $H_{\nu }^{\left(2\right)}\left(z\right)$.

fnufloat

$\nu$, the order of the first member of the sequence of functions.

zcomplex

The argument $z$ of the functions.

nint

$N$, the number of members required in the sequence $H_{\nu }^{\left(m\right)}\left(z\right),H_{\nu +1}^{\left(m\right)}\left(z\right),\dots ,H_{\nu +N-1}^{\left(m\right)}\left(z\right)$.

scalstr, length 1

The scaling option.

$scal=\text{'U'}$

The results are returned unscaled.

$scal=\text{'S'}$

The results are returned scaled by the factor $e^{-iz}$ when $m=1$, or by the factor $e^{iz}$ when $m=2$.

Returns

cycomplex, ndarray, shape $\left(n\right)$

The $N$ required function values: $cy[i-1]$ contains $H_{\nu +i-1}^{\left(m\right)}\left(z\right)$, for $\text{i}=1,2,\dots ,N$.

nzint

The number of components of $cy$ that are set to zero due to underflow. If $nz>0$, then if $Im\left(z\right)>0.0$ and $m=1$, or $Im\left(z\right)<0.0$ and $m=2$, elements $cy\left[0\right],cy\left[1\right],\dots ,cy[nz-1]$ are set to zero. In the complementary half-planes, $nz$ simply states the number of underflows, and not which elements they are.

Raises

NagValueError

(errno $1$)

On entry, $z=(0.0,0.0)$.

(errno $1$)

On entry, $fnu=⟨value⟩$.

Constraint: $fnu\ge 0.0$.

(errno $1$)

On entry, $scal$ has an illegal value: $scal=⟨value⟩$.

(errno $1$)

On entry, $n=⟨value⟩$.

Constraint: $n\ge 1$.

(errno $1$)

On entry, $m$ has illegal value: $m=⟨value⟩$.

(errno $2$)

No computation because $\left|z\right|=⟨value⟩<⟨value⟩$.

(errno $3$)

No computation because $fnu+n-1=⟨value⟩$ is too large.

(errno $5$)

No computation because $\left|z\right|=⟨value⟩>⟨value⟩$.

(errno $5$)

No computation because $fnu+n-1=⟨value⟩>⟨value⟩$.

(errno $6$)

No computation – algorithm termination condition not met.

Warns

NagAlgorithmicWarning

(errno $4$)

Results lack precision because $\left|z\right|=⟨value⟩>⟨value⟩$.

(errno $4$)

Results lack precision, $fnu+n-1=⟨value⟩>⟨value⟩$.

Notes

hankel_complex evaluates a sequence of values for the Hankel function $H_{\nu }^{\left(1\right)}\left(z\right)$ or $H_{\nu }^{\left(2\right)}\left(z\right)$, where $z$ is complex, $-\pi <argz\le \pi$, and $\nu$ is the real, non-negative order. The $N$-member sequence is generated for orders $\nu$, $\nu +1,\dots ,\nu +N-1$. Optionally, the sequence is scaled by the factor $e^{-iz}$ if the function is $H_{\nu }^{\left(1\right)}\left(z\right)$ or by the factor $e^{iz}$ if the function is $H_{\nu }^{\left(2\right)}\left(z\right)$.

Note: although the function may not be called with $\nu$ less than zero, for negative orders the formulae $H_{-\nu }^{\left(1\right)}\left(z\right)=e^{\nu \pi i}{H}_{\nu }^{\left(1\right)}\left(z\right)$, and $H_{-\nu }^{\left(2\right)}\left(z\right)=e^{-\nu \pi i}{H}_{\nu }^{\left(2\right)}\left(z\right)$ may be used.

The function is derived from the function CBESH in Amos (1986). It is based on the relation

$$H_{\nu }^{\left(m\right)}\left(z\right)=\frac{1}{p}{e}^{-p\nu }{K}_{\nu }\left(z{e}^{-p}\right)\text{,}$$

where $p=\frac{i\pi }{2}$ if $m=1$ and $p=-\frac{i\pi }{2}$ if $m=2$, and the Bessel function $K_{\nu }\left(z\right)$ is computed in the right half-plane only. Continuation of $K_{\nu }\left(z\right)$ to the left half-plane is computed in terms of the Bessel function $I_{\nu }\left(z\right)$. These functions are evaluated using a variety of different techniques, depending on the region under consideration.

When $N$ is greater than $1$, extra values of $H_{\nu }^{\left(m\right)}\left(z\right)$ are computed using recurrence relations.

For very large $\left|z\right|$ or $(\nu +N-1)$, argument reduction will cause total loss of accuracy, and so no computation is performed. For slightly smaller $\left|z\right|$ or $(\nu +N-1)$, the computation is performed but results are accurate to less than half of machine precision. If $\left|z\right|$ is very small, near the machine underflow threshold, or $(\nu +N-1)$ is too large, 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

NIST Digital Library of Mathematical Functions

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