nag_check_deriv (c05zbc) (PDF version)
c05 Chapter Contents
c05 Chapter Introduction
NAG C Library Manual

NAG Library Function Document

nag_check_deriv (c05zbc)

+ Contents

    1  Purpose
    7  Accuracy

1  Purpose

nag_check_deriv (c05zbc) checks that a user-supplied C function for evaluating a vector of functions and the matrix of their first derivatives produces derivative values which are consistent with the function values calculated.

2  Specification

#include <nag.h>
#include <nagc05.h>
void  nag_check_deriv (Integer n, const double x[], double fvec[], double fjac[], Integer tdfjac,
void (*f)(Integer n, const double x[], double fvec[], double fjac[], Integer tdfjac, Integer *userflag),
NagError *fail)

3  Description

nag_check_deriv (c05zbc) checks the derivatives calculated by user-supplied C functions, e.g., functions of the form required for nag_zero_nonlin_eqns_deriv (c05pbc). As well as the C function to be checked f, you must supply a point x = x 1 , x 2 ,, x n T  at which the check will be made.
nag_check_deriv (c05zbc) first calls f to evaluate both the f i x  and their first derivatives, and uses these to calculate the sum of squares
F x = i=1 n f i x 2 ,
and its first derivatives
g j = F xj x ,   for ​ j = 1 , 2 , , n .
The components of g  along two orthogonal directions (defined by unit vectors p 1  and p 2 , say) are then calculated; these will be gT p 1  and gT p 2  respectively. The same components are also estimated by finite differences, giving quantities
v k = F x + hp k - F x h ,   k = 1 , 2
where h  is a small positive scalar. If the relative difference between v 1  and gT p 1  or between v 2  and gT p 2  is judged too large, an error indicator is set.

4  References

None.

5  Arguments

1:     nIntegerInput
On entry: n, the number of variables, x j , for use with nag_zero_nonlin_eqns_deriv (c05pbc).
Constraint: n>0 .
2:     x[n]const doubleInput
On entry: x[j-1] , for j=1,2,,n must be set to the coordinates of a suitable point at which to check the derivatives calculated by f. ‘Obvious’ settings, such as 0 or 1, should not be used since, at such particular points, incorrect terms may take correct values (particularly zero), so that errors can go undetected. For a similar reason, it is preferable that no two elements of x should have the same value.
3:     fvec[n]doubleOutput
On exit: unless userflag is set negative when evaluating f i  at the point given in x, fvec[i-1]  contains the value of f i  at the point given by you in x, for i=1,2,,n.
4:     fjac[n×tdfjac]doubleOutput
On exit: unless userflag is set negative when evaluating the Jacobian at the point given in x, fjac[i-1×tdfjac+j-1]  contains the value of the first derivative fi xj  at the point given in x, as calculated by f, for i=1,2,,n and j=1,2,,n.
5:     tdfjacIntegerInput
On entry: the stride separating matrix column elements in the array fjac.
Constraint: tdfjacn .
6:     ffunction, supplied by the userExternal Function
f must calculate the values of the functions at a point x or return the Jacobian at x. nag_zero_nonlin_eqns_deriv (c05pbc) gives you the option of resetting an argument to terminate immediately. nag_check_deriv (c05zbc) will also terminate immediately, without finishing the checking process, if the argument in question is reset.
The specification of f is:
void  f (Integer n, const double x[], double fvec[], double fjac[], Integer tdfjac, Integer *userflag)
1:     nIntegerInput
On entry: n, the number of equations.
2:     x[n]const doubleInput
On entry: the components of the point x  at which the functions or the Jacobian must be evaluated.
3:     fvec[n]doubleOutput
On exit: if userflag=1  on entry, fvec must contain the function values f i x  (unless userflag is set to a negative value by f).
If userflag=2  on entry, fvec must not be changed.
4:     fjac[n×tdfjac]doubleOutput
On exit: if userflag=2  on entry, fjac[ i-1 × tdfjac + j - 1 ]  must contain the value of fi xj  at the point x , for i=1,2,,n and j=1,2,,n (unless userflag is set to a negative value by f).
If userflag=1  on entry, fjac must not be changed.
5:     tdfjacIntegerInput
On entry: the stride separating matrix column elements in the array fjac.
6:     userflagInteger *Input/Output
On entry: userflag=1 or 2.
userflag=1
fvec is to be updated.
userflag=2
fjac is to be updated.
On exit: in general, userflag should not be reset by f. If, however, you wish to terminate execution (perhaps because some illegal point x has been reached), then userflag should be set to a negative integer. This value will be returned through fail.errnum.
7:     failNagError *Input/Output
The NAG error argument (see Section 3.6 in the Essential Introduction).

6  Error Indicators and Warnings

NE_2_INT_ARG_LT
On entry, tdfjac=value  while n=value . These arguments must satisfy tdfjacn .
NE_ALLOC_FAIL
Dynamic memory allocation failed.
NE_DERIV_ERRORS
Large errors were found in the derivatives of the objective function.
You should check carefully the derivation and programming of expressions for the fi xj , because it is very unlikely that f is calculating them correctly.
NE_INT_ARG_LE
On entry, n must not be less or equal to 0: n=value .
NE_USER_STOP
User requested termination, user flag value =value .

7  Accuracy

fail is set to NE_DERIV_ERRORS if
v k - gT p k 2 h × gT p k 2 + 1
for k=1  or 2. (See Section 3 for definitions of the quantities involved.) The scalar h  is set equal to ε , where ε  is the machine precision.

8  Further Comments

Before using nag_check_deriv (c05zbc) to check the calculation of the first derivatives, you should be confident that f is evaluating the functions correctly.

9  Example

This example checks the Jacobian matrix for the problem solved in the example program for nag_zero_nonlin_eqns_deriv (c05pbc).

9.1  Program Text

Program Text (c05zbce.c)

9.2  Program Data

None.

9.3  Program Results

Program Results (c05zbce.r)


nag_check_deriv (c05zbc) (PDF version)
c05 Chapter Contents
c05 Chapter Introduction
NAG C Library Manual

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