NAG Library Function Document

nag_real_polygamma (s14aec)

+− 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

1 Purpose

nag_real_polygamma (s14aec) returns the value of the

k

th derivative of the psi function

ψ (x)

for real

x

and

k = 0, 1, \dots, 6

2 Specification

#include <nag.h>

#include <nags.h>

double

nag_real_polygamma (double x, Integer k, NagError *fail)

3 Description

nag_real_polygamma (s14aec) evaluates an approximation to the

k

th derivative of the psi function

ψ (x)

given by

ψ^{(k)} (x) = \frac{d^{k}}{d x^{k}} ψ (x) = \frac{d^{k}}{d x^{k}} (\frac{d}{d x} \log_{e} Γ (x)),

where

x

is real with

x \neq 0, - 1, - 2, \dots

and

k = 0, 1, \dots, 6

. For negative noninteger values of

x

, the recurrence relationship

ψ^{(k)} (x + 1) = ψ^{(k)} (x) + \frac{d^{k}}{d x^{k}} (\frac{1}{x})

is used. The value of

\frac{{(- 1)}^{k + 1} ψ^{(k)} (x)}{k!}

is obtained by a call to nag_polygamma_deriv (s14adc), which is based on the function PSIFN in Amos (1983).

Note that

ψ^{(k)} (x)

is also known as the polygamma function. Specifically,

ψ^{(0)} (x)

is often referred to as the digamma function and

ψ^{(1)} (x)

as the trigamma function in the literature. Further details can be found in Abramowitz and Stegun (1972).

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: x – doubleInput: On entry: the argument $x$ of the function.
Constraint: $x$ must not be ‘too close’ (see Section 6) to a non-positive integer.
2: k – IntegerInput: On entry: the function $ψ^{(k)} (x)$ to be evaluated.
Constraint: $0 \leq k \leq 6$ .
3: fail – NagError *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_INT: On entry, $k = ⟨value⟩$ .
Constraint: $k \leq 6$ .
On entry, $k = ⟨value⟩$ .
Constraint: $k \geq 0$ .
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: Evaluation abandoned due to likelihood of overflow.
NE_REAL: On entry, x is ‘too close’ to a non-positive integer: $x = ⟨value⟩$ and $nint (x) = ⟨value⟩$ .
NE_UNDERFLOW_LIKELY: Evaluation abandoned due to likelihood of underflow.

7 Accuracy

All constants in nag_polygamma_deriv (s14adc) are given to approximately

18

digits of precision. If

t

denotes the number of digits of precision in the floating-point arithmetic being used, then clearly the maximum number in the results obtained is limited by

p = \min (t, 18)

. Empirical tests by Amos (1983) have shown that the maximum relative error is a loss of approximately two decimal places of precision. Further tests with the function

- ψ^{(0)} (x)

have shown somewhat improved accuracy, except at points near the positive zero of

ψ^{(0)} (x)

x = 1.46 \dots

, where only absolute accuracy can be obtained.

8 Parallelism and Performance

Not applicable.

9 Further Comments

None.

10 Example

This example evaluates

ψ^{(2)} (x)

x = 2.5

, and prints the results.

NAG Library Function Documentnag_real_polygamma (s14aec)