nag_polygamma_deriv (s14adc) (PDF version)
s Chapter Contents
s Chapter Introduction
NAG Library Manual

NAG Library Function Document

nag_polygamma_deriv (s14adc)

+ Contents

    1  Purpose
    7  Accuracy

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
wk,x=-1k+1ψ k x k! ,
for x>0, k=n, n+1,,n+m-1, where ψ is the psi function
ψx=ddx lnΓx=Γx Γx ,
and ψ k  denotes the kth derivative of ψ.
The function is derived from the function PSIFN in Amos (1983). The basic method of evaluation of wk,x is the asymptotic series
wk,xεk,x+12xk+1 +1xkj=1B2j2j+k-1! 2j!k!x2j
for large x greater than a machine-dependent value xmin, followed by backward recurrence using
wk,x=wk,x+1+x-k-1
for smaller values of x, where εk,x=-lnx when k=0, εk,x= 1kxk  when k>0, and B2j, j=1,2,, are the Bernoulli numbers.
When k is large, the above procedure may be inefficient, and the expansion
wk,x=j=11x+jk+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:     xdoubleInput
On entry: the argument x of the function.
Constraint: x>0.0.
2:     nIntegerInput
On entry: the index of the first member n of the sequence of functions.
Constraint: n0.
3:     mIntegerInput
On entry: the number of members m required in the sequence wk,x, for k=n,,n+m-1.
Constraint: m1.
4:     ans[m]doubleOutput
On exit: the first m elements of ans contain the required values wk,x, for k=n,,n+m-1.
5:     failNagError *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: m1.
On entry, n=value.
Constraint: n0.
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=mint,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 1n50, 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, x1.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 wk,x, for k=n,,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.

10.1  Program Text

Program Text (s14adce.c)

10.2  Program Data

Program Data (s14adce.d)

10.3  Program Results

Program Results (s14adce.r)


nag_polygamma_deriv (s14adc) (PDF version)
s Chapter Contents
s Chapter Introduction
NAG Library Manual

© The Numerical Algorithms Group Ltd, Oxford, UK. 2014