hide long namesshow long names

Integer type: int32 int64 nag_int show int32 show int32 show int64 show int64 show nag_int show nag_int

PDF version (NAG web site, 64-bit version, 64-bit version)

Chapter Contents

Chapter Introduction

NAG Toolbox

NAG Toolbox: nag_specfun_polygamma_deriv (s14ad)

▸▿ Contents

1 Purpose

2 Syntax

3 Description

4 References

▸▿ 5 Parameters

5.1 Compulsory Input Parameters

5.2 Optional Input Parameters

5.3 Output Parameters

6 Error Indicators and Warnings

7 Accuracy

8 Further Comments

9 Example

Purpose

nag_specfun_polygamma_deriv (s14ad) returns a sequence of values of scaled derivatives of the psi function

ψ (x)

(also known as the digamma function).

Syntax

[ans, ifail] = s14ad(x, n, m)

[ans, ifail] = nag_specfun_polygamma_deriv(x, n, m)

Description

nag_specfun_polygamma_deriv (s14ad) 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.

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

Parameters

Compulsory Input Parameters

1: $x$ – double scalar: The argument $x$ of the function.

Constraint: $x > 0.0$ .
2: $n$ – int64int32nag_int scalar: The index of the first member $n$ of the sequence of functions.

Constraint: $n \geq 0$ .
3: $m$ – int64int32nag_int scalar: The number of members $m$ required in the sequence $w (k, x)$ , for $k = n, \dots, n + m - 1$ .

Constraint: $m \geq 1$ .

Optional Input Parameters

None.

Output Parameters

1: $ans (m)$ – double array: The first $m$ elements of ans contain the required values $w (k, x)$ , for $k = n, \dots, n + m - 1$ .
2: $ifail$ – int64int32nag_int scalar: $ifail = 0$ unless the function detects an error (see Error Indicators and Warnings).

Error Indicators and Warnings

Errors or warnings detected by the function:

$ifail = 1$

On entry,

x \leq 0.0

$ifail = 2$

On entry,

n < 0

$ifail = 3$

On entry,

m < 1

$ifail = 4$: No results are returned because underflow is likely. Either x or $n + m - 1$ is too large. If possible, reduce the value of m and call nag_specfun_polygamma_deriv (s14ad) again.

$ifail = 5$: No results are returned because overflow is likely. Either x is too small, or $n + m - 1$ is too large. If possible, reduce the value of m and call nag_specfun_polygamma_deriv (s14ad) again.

$ifail = 6$: No results are returned because there is not enough internal workspace to continue computation. $n + m - 1$ may be too large. If possible, reduce the value of m and call nag_specfun_polygamma_deriv (s14ad) again.

$ifail = - 99$: An unexpected error has been triggered by this routine. Please contact NAG.

$ifail = - 399$: Your licence key may have expired or may not have been installed correctly.

$ifail = - 999$: Dynamic memory allocation failed.

Accuracy

All constants in nag_specfun_polygamma_deriv (s14ad) 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_specfun_polygamma_deriv (s14ad), 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.

Further Comments

The time taken for a call of nag_specfun_polygamma_deriv (s14ad) is approximately proportional to

m

, plus a constant. In general, it is much cheaper to call nag_specfun_polygamma_deriv (s14ad) 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_specfun_polygamma_deriv (s14ad).

Example

This example reads values of the argument

x

from a file, evaluates the function at each value of

x

and prints the results.

Open in the MATLAB editor: s14ad_example

function s14ad_example


fprintf('s14ad example results\n\n');

x = [0.1    0.5    3.6   8];
n = size(x,2);
k = int64(0);
m = int64(4);
result = zeros(m,n);

for j=1:n
  [result(:,j), ifail] = s14ad(x(j),k,m);
end

disp('  x        psi       -psi''      psi''''/2!   -psi''''''/3!');
for j=1:n
  fprintf('%5.1f',x(j));
  fprintf('%12.4e',result(:,j));
  fprintf('\n');
end

s14ad example results

  x        psi       -psi'      psi''/2!   -psi'''/3!
  0.1  1.0424e+01  1.0143e+02  1.0009e+03  1.0001e+04
  0.5  1.9635e+00  4.9348e+00  8.4144e+00  1.6235e+01
  3.6 -1.1357e+00  3.1988e-01  5.0750e-02  1.0653e-02
  8.0 -2.0156e+00  1.3314e-01  8.8498e-03  7.8321e-04

PDF version (NAG web site, 64-bit version, 64-bit version)

Chapter Contents

Chapter Introduction

NAG Toolbox