NAG Library Function Document

nag_polygamma_deriv (s14adc)

+− 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_polygamma_deriv (s14adc) returns a sequence of values of scaled derivatives of the psi function

ψ (x)

(also known as the digamma function).

2 Specification

#include <nag.h>

#include <nags.h>

void	nag_polygamma_deriv (double x, Integer n, Integer m, double ans[], NagError *fail)

3 Description

nag_polygamma_deriv (s14adc) computes

m

values of the function

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

for

x > 0

k = n

n + 1, \dots, n + m - 1

, where

ψ

is the psi function

ψ (x) = \frac{d}{d x} \ln Γ (x) = \frac{Γ^{'} (x)}{Γ (x)},

and

ψ^{(k)}

denotes the

k

th derivative of

ψ

The function is derived from the function PSIFN in Amos (1983). The basic method of evaluation of

w (k, x)

is the asymptotic series

w (k, x) \sim ε (k, x) + \frac{1}{2 x^{k + 1}} + \frac{1}{x^{k}} \sum_{j = 1}^{\infty} B_{2 j} \frac{(2 j + k - 1)!}{(2 j)! k! x^{2 j}}

for large

x

greater than a machine-dependent value

x_{\min}

, followed by backward recurrence using

w (k, x) = w (k, x + 1) + x^{- k - 1}

for smaller values of

x

, where

ε (k, x) = - \ln x

when

k = 0

ε (k, x) = \frac{1}{k x^{k}}

when

k > 0

, and

B_{2 j}

j = 1, 2, \dots

, are the Bernoulli numbers.

When

k

is large, the above procedure may be inefficient, and the expansion

w (k, x) = \sum_{j = 1}^{\infty} \frac{1}{{(x + j)}^{k + 1}},

which converges rapidly for large

k

, is used instead.

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 > 0.0$ .
2: n – IntegerInput: On entry: the index of the first member $n$ of the sequence of functions.
Constraint: $n \geq 0$ .
3: m – IntegerInput: On entry: the number of members $m$ required in the sequence $w (k, x)$ , for $k = n, \dots, n + m - 1$ .
Constraint: $m \geq 1$ .
4: ans[m] – doubleOutput: On exit: the first $m$ elements of ans contain the required values $w (k, x)$ , for $k = n, \dots, n + m - 1$ .
5: 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_BAD_PARAM: On entry, argument $⟨value⟩$ had an illegal value.
NE_INT: On entry, $m = ⟨value⟩$ .
Constraint: $m \geq 1$ .
On entry, $n = ⟨value⟩$ .
Constraint: $n \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_INTERNAL_WORKSPACE: There is not enough internal workspace to continue computation. m is probably too large.
NE_OVERFLOW_LIKELY: Computation abandoned due to the likelihood of overflow.
NE_REAL: On entry, $x = ⟨value⟩$ .
Constraint: $x > 0.0$ .
NE_UNDERFLOW_LIKELY: Computation abandoned due to the likelihood of underflow.

7 Accuracy

All constants in nag_polygamma_deriv (s14adc) 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)

. Empirical tests of nag_polygamma_deriv (s14adc), taking values of

x

in the range

0.0 < x < 50.0

, and

n

in the range

1 \leq n \leq 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

- ψ (x)

, have shown somewhat better accuracy, except at points close to the zero of

ψ (x)

x ≃ 1.461632

, where only absolute accuracy can be obtained.

8 Parallelism and Performance

Not applicable.

9 Further Comments

The time taken for a call of nag_polygamma_deriv (s14adc) is approximately proportional to

m

, plus a constant. In general, it is much cheaper to call nag_polygamma_deriv (s14adc) with

m

greater than

1

to evaluate the function

w (k, x)

, for

k = n, \dots, n + m - 1

, rather than to make

m

separate calls of nag_polygamma_deriv (s14adc).

10 Example

This example reads values of the argument

x

from a file, evaluates the function at each value of

x

and prints the results.

NAG Library Function Documentnag_polygamma_deriv (s14adc)