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 = ψ (x + \frac{1}{2}) - ψ (x)

has an asymptotic behaviour for large

x

given by

d \sim \ln (x + \frac{1}{2}) - \ln x + O (\frac{1}{x^{2}}) \sim \ln (1 + \frac{1}{2 x}) \sim \frac{1}{2 x}

Computing

d

directly would amount to subtracting two large numbers which are close to

\ln (x + \frac{1}{2})

and

\ln x

to produce a small number close to

\frac{1}{2 x}

, resulting in a loss of significant digits. However, using this routine to compute

f (x) = ψ (x) - \ln x

, we can compute

d = f (x + \frac{1}{2}) - f (x) + \ln (1 + \frac{1}{2 x})

, 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 routine is derived from the routine PSIFN in Amos (1983).

4 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

5 Arguments

1: $x$ – Real (Kind=nag_wp) Input: On entry: the argument $x$ of the function.

Constraint: $x > 0.0$ .
2: $ifail$ – Integer Input/Output: On entry: ifail must be set to $0$ , $- 1$ or $1$ to set behaviour on detection of an error; these values have no effect when no error is detected.
A value of $0$ causes the printing of an error message and program execution will be halted; otherwise program execution continues. A value of $- 1$ means that an error message is printed while a value of $1$ means that it is not.

If halting is not appropriate, the value $- 1$ or $1$ is recommended. If message printing is undesirable, then the value $1$ is recommended. Otherwise, the value $0$ is recommended. When the value $- 1$ or $1$ is used it is essential to test the value of ifail on exit.

On exit: $ifail = 0$ unless the routine detects an error or a warning has been flagged (see Section 6).

6 Error Indicators and Warnings

If on entry

ifail = 0

- 1

, explanatory error messages are output on the current error message unit (as defined by x04aaf).

Errors or warnings detected by the routine:

$ifail = 1$: On entry, $x = ⟨ value ⟩$ .
Constraint: $x > 0.0$ .

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

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

$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.

$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.

$ifail = - 999$: Dynamic memory allocation failed.
See Section 9 in the Introduction to the NAG Library FL Interface for further information.

7 Accuracy

All constants in s14acf 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 = \min (t, 18)

With the above proviso, results returned by this routine should be accurate almost to full precision, except at points close to the zero of

ψ (x)

x ≃ 1.461632

, where only absolute rather than relative accuracy can be obtained.

8 Parallelism and Performance

s14acf is not threaded in any implementation.

9 Further Comments

None.

10 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.

s14ac: FL CL CPP AD

NAG FL Interfaces14acf (polygamma)

▸▿ Contents

1 Purpose

2 Specification

3 Description

4 References

5 Arguments

6 Error Indicators and Warnings

7 Accuracy

8 Parallelism and Performance

9 Further Comments

10 Example

10.1 Program Text

10.2 Program Data

10.3 Program Results

NAG FL Interface
s14acf (polygamma)