s14ad: FL CL CPP AD

NAG FL Interface
s14adf (polygamma_deriv)

Keyword Search:

NAG Library Manual, Mark 27.3

Interfaces: FL CL CPP AD

NAG FL Interface Introduction

S (Specfun) Chapter Contents

S (Specfun) Chapter Introduction

s14ad: FL CL CPP AD

▸▿ 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

s14adf returns a sequence of values of scaled derivatives of the psi function

ψ (x)

(also known as the digamma function).

2 Specification

Fortran Interface

Subroutine s14adf (

x, n, m, ans, ifail)

Integer, Intent (In)	::	n, m
Integer, Intent (Inout)	::	ifail
Real (Kind=nag_wp), Intent (In)	::	x
Real (Kind=nag_wp), Intent (Out)	::	ans(m)

C Header Interface

#include <nag.h>

void	s14adf_ (const double x, const Integer n, const Integer m, double ans[], Integer ifail)

The routine may be called by the names s14adf or nagf_specfun_polygamma_deriv.

3 Description

s14adf 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 routine is derived from the routine 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

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: $n$ – Integer Input: On entry: the index of the first member $n$ of the sequence of functions.

Constraint: $n \geq 0$ .
3: $m$ – Integer Input: 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)$ – Real (Kind=nag_wp) array Output: On exit: the first $m$ elements of ans contain the required values $w (k, x)$ , for $k = n, \dots, n + m - 1$ .
5: $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$: On entry, $n = ⟨ value ⟩$ .
Constraint: $n \geq 0$ .

$ifail = 3$: On entry, $m = ⟨ value ⟩$ .
Constraint: $m \geq 1$ .

$ifail = 4$: Computation abandoned due to the likelihood of underflow.

$ifail = 5$: Computation abandoned due to the likelihood of overflow.

$ifail = 6$: There is not enough internal workspace to continue computation. m is probably too large.

$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 s14adf 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 s14adf, 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

s14adf is not threaded in any implementation.

9 Further Comments

The time taken for a call of s14adf is approximately proportional to

m

, plus a constant. In general, it is much cheaper to call s14adf 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 s14adf.

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.

s14ad: FL CL CPP AD

NAG FL Interfaces14adf (polygamma_​deriv)

▸▿ 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
s14adf (polygamma_deriv)