c05 Chapter Contents
c05 Chapter Introduction
NAG C Library Manual

# NAG Library Function Documentnag_check_deriv_1 (c05zcc)

## 1  Purpose

nag_check_deriv_1 (c05zcc) 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 #include
void  nag_check_deriv_1 (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, Nag_User *comm),
Nag_User *comm, NagError *fail)

## 3  Description

nag_check_deriv_1 (c05zcc) checks the derivatives calculated by user-supplied C functions, e.g., functions of the form required for nag_zero_nonlin_eqns_deriv_1 (c05ubc). As well as the C function to be checked f, you must supply a point $x={\left({x}_{1},{x}_{2},\dots ,{x}_{n}\right)}^{\mathrm{T}}$ at which the check will be made.
nag_check_deriv_1 (c05zcc) first calls f to evaluate both the ${f}_{i}\left(x\right)$ 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 ${g}^{\mathrm{T}}{p}_{1}$ and ${g}^{\mathrm{T}}{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 ${g}^{\mathrm{T}}{p}_{1}$ or between ${v}_{2}$ and ${g}^{\mathrm{T}}{p}_{2}$ is judged too large, an error indicator is set.

None.

## 5  Arguments

1:     nIntegerInput
On entry: $n$, the number of variables, ${x}_{j}$, for use with nag_zero_nonlin_eqns_deriv_1 (c05ubc).
Constraint: ${\mathbf{n}}>0$.
2:     x[n]const doubleInput
On entry: ${\mathbf{x}}\left[\mathit{j}-1\right]$, for $\mathit{j}=1,2,\dots ,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}_{\mathit{i}}$ at the point given in x, ${\mathbf{fvec}}\left[\mathit{i}-1\right]$ contains the value of ${f}_{\mathit{i}}$ at the point given by you in x, for $\mathit{i}=1,2,\dots ,n$.
4:     fjac[${\mathbf{n}}×{\mathbf{tdfjac}}$]doubleOutput
On exit: unless userflag is set negative when evaluating the Jacobian at the point given in x, ${\mathbf{fjac}}\left[\left(\mathit{i}-1\right)×{\mathbf{tdfjac}}+\mathit{j}-1\right]$ contains the value of the first derivative $\frac{\partial {f}_{\mathit{i}}}{\partial {x}_{\mathit{j}}}$ at the point given in x, as calculated by f, for $\mathit{i}=1,2,\dots ,n$ and $\mathit{j}=1,2,\dots ,n$.
5:     tdfjacIntegerInput
On entry: the stride separating matrix column elements in the array fjac.
Constraint: ${\mathbf{tdfjac}}\ge {\mathbf{n}}$.
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_1 (c05ubc) gives you the option of resetting an argument to terminate immediately. nag_check_deriv_1 (c05zcc) 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, Nag_User *comm)
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 ${\mathbf{userflag}}=1$ on entry, fvec must contain the function values ${f}_{i}\left(x\right)$ (unless userflag is set to a negative value by f).
If ${\mathbf{userflag}}=2$ on entry, fvec must not be changed.
4:     fjac[${\mathbf{n}}×{\mathbf{tdfjac}}$]doubleOutput
On exit: if ${\mathbf{userflag}}=2$ on entry, ${\mathbf{fjac}}\left[\left(\mathit{i}-1\right)×{\mathbf{tdfjac}}+\mathit{j}-1\right]$ must contain the value of $\frac{\partial {f}_{\mathit{i}}}{\partial {x}_{\mathit{j}}}$ at the point $x$, for $\mathit{i}=1,2,\dots ,n$ and $\mathit{j}=1,2,\dots ,n$ (unless userflag is set to a negative value by f).
If ${\mathbf{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: ${\mathbf{userflag}}=1$ or $2$.
${\mathbf{userflag}}=1$
fvec is to be updated.
${\mathbf{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 ${\mathbf{fail}}\mathbf{.}\mathbf{errnum}$.
7:     commNag_User *
Pointer to a structure of type Nag_User with the following member:
pPointer
On entry/exit: the pointer $\mathbf{comm}\mathbf{\to }\mathbf{f}\mathbf{\to }\mathbf{p}$ should be cast to the required type, e.g., struct user *s = (struct user *)comm → p, to obtain the original object's address with appropriate type. (See the argument comm below.)
7:     commNag_User *
Pointer to a structure of type Nag_User with the following member:
pPointer
On entry/exit: the pointer $\mathbf{comm}\mathbf{\to }\mathbf{p}$, of type Pointer, allows you to communicate information to and from f(). You must declare an object of the required type, e.g., a structure, and its address assigned to the pointer $\mathbf{comm}\mathbf{\to }\mathbf{p}$ by means of a cast to Pointer in the calling program, e.g., comm.p = (Pointer)&s. The type pointer will be void * with a C compiler that defines void * and char * otherwise.
8:     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, ${\mathbf{tdfjac}}=〈\mathit{\text{value}}〉$ while ${\mathbf{n}}=〈\mathit{\text{value}}〉$. These arguments must satisfy ${\mathbf{tdfjac}}\ge {\mathbf{n}}$.
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 $\frac{\partial {f}_{i}}{\partial {x}_{j}}$, 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: ${\mathbf{n}}=〈\mathit{\text{value}}〉$.
NE_USER_STOP
User requested termination, user flag value $\text{}=〈\mathit{\text{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 $\sqrt{\epsilon }$, where $\epsilon$ is the machine precision.

Before using nag_check_deriv_1 (c05zcc) 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_1 (c05ubc).

### 9.1  Program Text

Program Text (c05zcce.c)

None.

### 9.3  Program Results

Program Results (c05zcce.r)