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

## Purpose

nag_specfun_polygamma_deriv (s14ad) returns a sequence of values of scaled derivatives of the psi function $\psi \left(x\right)$ (also known as the digamma function).

## Syntax

[ans, ifail] = s14ad(x, n, m)
[ans, ifail] = nag_specfun_polygamma_deriv(x, n, m)

## Description

nag_specfun_polygamma_deriv (s14ad) computes $m$ values of the function
 $wk,x=-1k+1ψ k x k! ,$
for $x>0$, $k=n$, $n+1,\dots ,n+m-1$, where $\psi$ is the psi function
 $ψx=ddx ln⁡Γx=Γ′x Γx ,$
and ${\psi }^{\left(k\right)}$ denotes the $k$th derivative of $\psi$.
The function is derived from the function PSIFN in Amos (1983). The basic method of evaluation of $w\left(k,x\right)$ is the asymptotic series
 $wk,x∼εk,x+12xk+1 +1xk∑j=1∞B2j2j+k-1! 2j!k!x2j$
for large $x$ greater than a machine-dependent value ${x}_{\mathrm{min}}$, followed by backward recurrence using
 $wk,x=wk,x+1+x-k-1$
for smaller values of $x$, where $\epsilon \left(k,x\right)=-\mathrm{ln}x$ when $k=0$, $\epsilon \left(k,x\right)=\frac{1}{k{x}^{k}}$ when $k>0$, and ${B}_{2j}$, $j=1,2,\dots$, are the Bernoulli numbers.
When $k$ is large, the above procedure may be inefficient, and the expansion
 $wk,x=∑j=1∞1x+jk+1,$
which converges rapidly for large $k$, is used instead.

## References

Abramowitz M and Stegun I A (1972) Handbook of Mathematical Functions (3rd Edition) Dover Publications
Amos D E (1983) Algorithm 610: A portable FORTRAN subroutine for derivatives of the psi function ACM Trans. Math. Software 9 494–502

## Parameters

### Compulsory Input Parameters

1:     $\mathrm{x}$ – double scalar
The argument $x$ of the function.
Constraint: ${\mathbf{x}}>0.0$.
2:     $\mathrm{n}$int64int32nag_int scalar
The index of the first member $n$ of the sequence of functions.
Constraint: ${\mathbf{n}}\ge 0$.
3:     $\mathrm{m}$int64int32nag_int scalar
The number of members $m$ required in the sequence $w\left(\mathit{k},x\right)$, for $\mathit{k}=n,\dots ,n+m-1$.
Constraint: ${\mathbf{m}}\ge 1$.

None.

### Output Parameters

1:     $\mathrm{ans}\left({\mathbf{m}}\right)$ – double array
The first $m$ elements of ans contain the required values $w\left(\mathit{k},x\right)$, for $\mathit{k}=n,\dots ,n+m-1$.
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:
${\mathbf{ifail}}=1$
 On entry, ${\mathbf{x}}\le 0.0$.
${\mathbf{ifail}}=2$
 On entry, ${\mathbf{n}}<0$.
${\mathbf{ifail}}=3$
 On entry, ${\mathbf{m}}<1$.
${\mathbf{ifail}}=4$
No results are returned because underflow is likely. Either x or ${\mathbf{n}}+{\mathbf{m}}-1$ is too large. If possible, reduce the value of m and call nag_specfun_polygamma_deriv (s14ad) again.
${\mathbf{ifail}}=5$
No results are returned because overflow is likely. Either x is too small, or ${\mathbf{n}}+{\mathbf{m}}-1$ is too large. If possible, reduce the value of m and call nag_specfun_polygamma_deriv (s14ad) again.
${\mathbf{ifail}}=6$
No results are returned because there is not enough internal workspace to continue computation. ${\mathbf{n}}+{\mathbf{m}}-1$ may be too large. If possible, reduce the value of m and call nag_specfun_polygamma_deriv (s14ad) again.
${\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_polygamma_deriv (s14ad) 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)$. Empirical tests of nag_specfun_polygamma_deriv (s14ad), taking values of $x$ in the range $0.0, and $n$ in the range $1\le n\le 50$, have shown that the maximum relative error is a loss of approximately two decimal places of precision. Tests with $n=0$, i.e., testing the function $-\psi \left(x\right)$, have shown somewhat better accuracy, except at points close to the zero of $\psi \left(x\right)$, $x\simeq 1.461632$, where only absolute accuracy can be obtained.

The time taken for a call of nag_specfun_polygamma_deriv (s14ad) is approximately proportional to $m$, plus a constant. In general, it is much cheaper to call nag_specfun_polygamma_deriv (s14ad) with $m$ greater than $1$ to evaluate the function $w\left(\mathit{k},x\right)$, for $\mathit{k}=n,\dots ,n+m-1$, rather than to make $m$ separate calls of nag_specfun_polygamma_deriv (s14ad).

## Example

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

x = [0.1    0.5    3.6   8];
n = size(x,2);
k = int64(0);
m = int64(4);
result = zeros(m,n);

for j=1:n
end

disp('  x        psi       -psi''      psi''''/2!   -psi''''''/3!');
for j=1:n
fprintf('%5.1f',x(j));
fprintf('%12.4e',result(:,j));
fprintf('\n');
end

```
```s14ad example results

x        psi       -psi'      psi''/2!   -psi'''/3!
0.1  1.0424e+01  1.0143e+02  1.0009e+03  1.0001e+04
0.5  1.9635e+00  4.9348e+00  8.4144e+00  1.6235e+01
3.6 -1.1357e+00  3.1988e-01  5.0750e-02  1.0653e-02
8.0 -2.0156e+00  1.3314e-01  8.8498e-03  7.8321e-04
```