naginterfaces.library.specfun.polygamma

naginterfaces.library.specfun.polygamma(x)

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

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

https://www.nag.com/numeric/nl/nagdoc_29.3/flhtml/s/s14acf.html

Parameters

xfloat

The argument $x$ of the function.

Returns

pgxfloat

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

Raises

NagValueError

(errno $1$)

On entry, $x=⟨value⟩$.

Constraint: $x>0.0$.

(errno $2$)

Computation halted due to likelihood of underflow. $x$ may be too large. $x=⟨value⟩$.

(errno $3$)

Computation halted due to likelihood of overflow. $x$ may be too small. $x=⟨value⟩$.

Notes

polygamma returns a value of the function $\psi \left(x\right)-ln\left(x\right)$. 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 (x+\frac{1}{2})-\psi \left(x\right)$ has an asymptotic behaviour for large $x$ given by $d\sim ln(x+\frac{1}{2})-ln\left(x\right)+O\left(\frac{1}{x^2}\right)\sim ln(1+\frac{1}{2x})\sim \frac{1}{2x}$.

Computing $d$ directly would amount to subtracting two large numbers which are close to $ln(x+\frac{1}{2})$ and $ln\left(x\right)$ 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)-ln\left(x\right)$, we can compute $d=f(x+\frac{1}{2})-f\left(x\right)+ln(1+\frac{1}{2x})$, 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).

References

NIST Digital Library of Mathematical Functions

Amos, D E, 1983, Algorithm 610: A portable FORTRAN subroutine for derivatives of the psi function, ACM Trans. Math. Software (9), 494–502