NAG Library Function Document

1Purpose

nag_opt_check_deriv (e04hcc) checks that a user-defined C function for evaluating an objective function and its first derivatives produces derivative values which are consistent with the function values calculated.

2Specification

 #include #include
void  nag_opt_check_deriv (Integer n,
 void (*objfun)(Integer n, const double x[], double *objf, double g[], Nag_Comm *comm),
const double x[], double *objf, double g[], Nag_Comm *comm, NagError *fail)

3Description

The function nag_opt_bounds_deriv (e04kbc) for minimizing a function of several variables requires you to supply a C function to evaluate the objective function $F\left({x}_{1},{x}_{2},\dots ,{x}_{n}\right)$ and its first derivatives. nag_opt_check_deriv (e04hcc) is designed to check the derivatives calculated by such a user-supplied function. As well as the function to be checked (objfun), you must supply a point $x={\left({x}_{1},{x}_{2},\dots ,{x}_{n}\right)}^{\mathrm{T}}$ at which the check is to be made.
nag_opt_check_deriv (e04hcc) first calls the supplied function objfun to evaluate $F$ and its first derivatives ${g}_{\mathit{j}}=\frac{\partial F}{\partial {x}_{\mathit{j}}}$, for $\mathit{j}=1,2,\dots ,n$ at $x$. The components of the user-supplied derivatives 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.

5Arguments

1:    $\mathbf{n}$IntegerInput
On entry: the number $n$ of independent variables in the objective function.
Constraint: ${\mathbf{n}}\ge 1$.
2:    $\mathbf{objfun}$function, supplied by the userExternal Function
objfun must evaluate the objective function and its first derivatives at a given point. (The minimization function nag_opt_bounds_deriv (e04kbc) gives you the option of resetting an argument, $\mathbf{comm}\mathbf{\to }\mathbf{flag}$, to terminate the minimization process immediately. nag_opt_check_deriv (e04hcc) will also terminate immediately, without finishing the checking process, if the argument in question is reset to a negative value.)
The specification of objfun is:
 void objfun (Integer n, const double x[], double *objf, double g[], Nag_Comm *comm)
1:    $\mathbf{n}$IntegerInput
On entry: the number $n$ of variables.
2:    $\mathbf{x}\left[{\mathbf{n}}\right]$const doubleInput
On entry: the point $x$ at which $F$ and its derivatives are required.
3:    $\mathbf{objf}$double *Output
On exit: objfun must set objf to the value of the objective function $F$ at the current point $x$. If it is not possible to evaluate $F$ then objfun should assign a negative value to $\mathbf{comm}\mathbf{\to }\mathbf{flag}$; nag_opt_check_deriv (e04hcc) will then terminate.
4:    $\mathbf{g}\left[{\mathbf{n}}\right]$doubleOutput
On exit: unless $\mathbf{comm}\mathbf{\to }\mathbf{flag}$ is reset to a negative number, objfun must set ${\mathbf{g}}\left[j-1\right]$ to the value of the first derivative $\frac{\partial F}{\partial {x}_{j}}$ at the current point $x$ for $j=1,2,\dots ,n$
5:    $\mathbf{comm}$Nag_Comm *
Pointer to structure of type Nag_Comm; the following members are relevant to objfun.
flagIntegerInput/Output
On entry: $\mathbf{comm}\mathbf{\to }\mathbf{flag}$ will be set to 2.
On exit: if objfun resets $\mathbf{comm}\mathbf{\to }\mathbf{flag}$ to some negative number then nag_opt_check_deriv (e04hcc) will terminate immediately with the error indicator NE_USER_STOP. If fail is supplied to nag_opt_check_deriv (e04hcc), ${\mathbf{fail}}\mathbf{.}\mathbf{errnum}$ will be set to your setting of $\mathbf{comm}\mathbf{\to }\mathbf{flag}$.
firstNag_BooleanInput
On entry: will be set to Nag_TRUE on the first call to objfun and Nag_FALSE for all subsequent calls.
nfIntegerInput
On entry: the number of calculations of the objective function; this value will be equal to the number of calls made to objfun including the current one.
userdouble *
iuserInteger *
pPointer
The type Pointer will be void * with a C compiler that defines void * and char * otherwise. Before calling nag_opt_check_deriv (e04hcc) these pointers may be allocated memory and initialized with various quantities for use by objfun when called from nag_opt_check_deriv (e04hcc).
Note: objfun should not return floating-point NaN (Not a Number) or infinity values, since these are not handled by nag_opt_check_deriv (e04hcc). If your code inadvertently does return any NaNs or infinities, nag_opt_check_deriv (e04hcc) is likely to produce unexpected results.
The array x must not be changed by objfun.
3:    $\mathbf{x}\left[{\mathbf{n}}\right]$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 objfun. ‘Obvious’ settings, such as 0.0 or 1.0, should not be used since, at such particular points, incorrect terms may take correct values (particularly zero), so that errors could go undetected. Similarly, it is preferable that no two elements of x should be the same.
4:    $\mathbf{objf}$double *Output
On exit: unless you set $\mathbf{comm}\mathbf{\to }\mathbf{flag}$ negative in the first call of objfun, objf contains the value of the objective function $F\left(x\right)$ at the point given in x.
5:    $\mathbf{g}\left[{\mathbf{n}}\right]$doubleOutput
On exit: unless you set $\mathbf{comm}\mathbf{\to }\mathbf{flag}$ negative in the first call of objfun, ${\mathbf{g}}\left[\mathit{j}-1\right]$ contains the value of the derivative $\frac{\partial F}{\partial {x}_{\mathit{j}}}$ at the point given in x, as calculated by objfun, for $\mathit{j}=1,2,\dots ,n$.
6:    $\mathbf{comm}$Nag_Comm *Input/Output
Note: comm is a NAG defined type (see Section 3.3.1.1 in How to Use the NAG Library and its Documentation).
On entry/exit: structure containing pointers for communication with the user-defined function; see the above description of objfun for details. If you do not need to make use of this communication feature the null pointer NAGCOMM_NULL may be used in the call to nag_opt_check_deriv (e04hcc); comm will then be declared internally for use in calls to objfun.
7:    $\mathbf{fail}$NagError *Input/Output
The NAG error argument (see Section 3.7 in How to Use the NAG Library and its Documentation).

6Error Indicators and Warnings

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 derivatives of $F\left(x\right)$, because it is very unlikely that objfun is calculating them correctly.
NE_INT_ARG_LT
On entry, ${\mathbf{n}}=〈\mathit{\text{value}}〉$.
Constraint: ${\mathbf{n}}\ge 1$.
NE_USER_STOP
User requested termination, user flag value $\text{}=〈\mathit{\text{value}}〉$.
This exit occurs if you set $\mathbf{comm}\mathbf{\to }\mathbf{flag}$ to a negative value in objfun. If fail is supplied the value of ${\mathbf{fail}}\mathbf{.}\mathbf{errnum}$ will be the same as your setting of $\mathbf{comm}\mathbf{\to }\mathbf{flag}$. The check on objfun will not have been completed.

7Accuracy

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 as given by nag_machine_precision (X02AJC).

8Parallelism and Performance

nag_opt_check_deriv (e04hcc) is not threaded in any implementation.

The user-defined function objfun is called three times.
Before using nag_opt_check_deriv (e04hcc) to check the calculation of first derivatives, you should be confident that objfun is calculating $F$ correctly. The usual way of checking the calculation of the function is to compare values of $F\left(x\right)$ calculated by objfun at non-trivial points $x$ with values calculated independently. (‘Non-trivial’ means that, as when setting $x$ before calling nag_opt_check_deriv (e04hcc), coordinates such as 0.0 or 1.0 should be avoided.)

10Example

Suppose that it is intended to use nag_opt_bounds_deriv (e04kbc) to minimize
 $F = x 1 + 10 x 2 2 + 5 x 3 - x 4 2 + x 2 - 2 x 3 4 + 10 x 1 - x 4 4 .$
The following program could be used to check the first derivatives calculated by the required function objfun. (The test of whether $\mathbf{comm}\mathbf{\to }\mathbf{flag}\ne 0$ in objfun is present for when objfun is called by nag_opt_bounds_deriv (e04kbc). nag_opt_check_deriv (e04hcc) will always call objfun with $\mathbf{comm}\mathbf{\to }\mathbf{flag}$ set to 2.)

10.1Program Text

Program Text (e04hcce.c)

None.

10.3Program Results

Program Results (e04hcce.r)

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