s Chapter Contents
s Chapter Introduction
NAG C Library Manual

# NAG Library Function Documentnag_polygamma_fun (s14acc)

## 1  Purpose

nag_polygamma_fun (s14acc) returns a value of the function $\psi \left(x\right)-\mathrm{ln}x$, where $\psi$ is the psi function $\psi \left(x\right)=\frac{d}{dx}\mathrm{ln}\Gamma \left(x\right)=\frac{{\Gamma }^{\prime }\left(x\right)}{\Gamma \left(x\right)}$.

## 2  Specification

 #include #include
 double nag_polygamma_fun (double x, NagError *fail)

## 3  Description

nag_polygamma_fun (s14acc) returns a value of the function $\psi \left(x\right)-\mathrm{ln}x$. The psi function is computed without the logarithmic term so that when $x$ is large, sums or differences of psi functions may be computed without unnecessary loss of precision, by analytically combining the logarithmic terms. For example, the difference $d=\psi \left(x+\frac{1}{2}\right)-\psi \left(x\right)$ has an asymptotic behaviour for large $x$ given by $d\sim \mathrm{ln}\left(x+\frac{1}{2}\right)-\mathrm{ln}x+\mathit{O}\left(\frac{1}{{x}^{2}}\right)\sim \mathrm{ln}\left(1+\frac{1}{2x}\right)\sim \frac{1}{2x}$.
Computing $d$ directly would amount to subtracting two large numbers which are close to $\mathrm{ln}\left(x+\frac{1}{2}\right)$ and $\mathrm{ln}x$ to produce a small number close to $\frac{1}{2x}$, resulting in a loss of significant digits. However, using this function to compute $f\left(x\right)=\psi \left(x\right)-\mathrm{ln}x$, we can compute $d=f\left(x+\frac{1}{2}\right)-f\left(x\right)+\mathrm{ln}\left(1+\frac{1}{2x}\right)$, and the dominant logarithmic term may be computed accurately from its power series when $x$ is large. Thus we avoid the unnecessary loss of precision.
The function is derived from the function PSIFN in Amos (1983).

## 4  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

## 5  Arguments

1:     xdoubleInput
On entry: the argument $x$ of the function.
Constraint: ${\mathbf{x}}>0.0$.
2:     failNagError *Input/Output
The NAG error argument (see Section 3.6 in the Essential Introduction).

## 6  Error Indicators and Warnings

NE_ALLOC_FAIL
Dynamic memory allocation failed.
NE_INTERNAL_ERROR
An internal error has occurred in this function. Check the function call and any array sizes. If the call is correct then please contact NAG for assistance.
NE_OVERFLOW_LIKELY
Computation halted due to likelihood of overflow. x may be too small. ${\mathbf{x}}=〈\mathit{\text{value}}〉$.
NE_REAL
On entry, ${\mathbf{x}}=〈\mathit{\text{value}}〉$.
Constraint: ${\mathbf{x}}>0.0$.
NE_UNDERFLOW_LIKELY
Computation halted due to likelihood of underflow. x may be too large. ${\mathbf{x}}=〈\mathit{\text{value}}〉$.

## 7  Accuracy

All constants in nag_polygamma_fun (s14acc) 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)$.
With the above proviso, results returned by this function should be accurate almost to full precision, except at points close to the zero of $\psi \left(x\right)$, $x\simeq 1.461632$, where only absolute rather than relative accuracy can be obtained.

None.

## 9  Example

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

### 9.1  Program Text

Program Text (s14acce.c)

### 9.2  Program Data

Program Data (s14acce.d)

### 9.3  Program Results

Program Results (s14acce.r)