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

Chapter Contents
Chapter Introduction
NAG Toolbox

# NAG Toolbox: nag_opt_check_deriv (e04hc)

## Purpose

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

## Syntax

[f, g, iw, w, ifail] = e04hc(funct, x, iw, w, 'n', n)
[f, g, iw, w, ifail] = nag_opt_check_deriv(funct, x, iw, w, 'n', n)
Note: the interface to this routine has changed since earlier releases of the toolbox:
 At Mark 22: liw and lw were removed from the interface

## Description

Routines for minimizing a function of several variables may require you to supply a function to evaluate the objective function $F\left({x}_{1},{x}_{2},\dots ,{x}_{n}\right)$ and its first derivatives. nag_opt_check_deriv (e04hc) is designed to check the derivatives calculated by such user-supplied functions . As well as the function to be checked ( funct), you must supply a point $x={\left({x}_{1},{x}_{2},\dots ,{x}_{n}\right)}^{\mathrm{T}}$ at which the check will be made. Note that nag_opt_check_deriv (e04hc) checks functions of the form required for nag_opt_bounds_mod_deriv_comp (e04kd) and nag_opt_bounds_mod_deriv2_comp (e04lb).
nag_opt_check_deriv (e04hc) first calls funct 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
 $vk=Fx+hpk-Fxh, 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.

## Parameters

### Compulsory Input Parameters

1:     $\mathrm{funct}$ – function handle or string containing name of m-file
funct must evaluate the function and its first derivatives at a given point. (The minimization functions mentioned in Description gives you the option of resetting arguments of funct to cause the minimization process to terminate immediately. nag_opt_check_deriv (e04hc) will also terminate immediately, without finishing the checking process, if the argument in question is reset.)
[iflag, fc, gc, iw, w] = funct(iflag, n, xc, iw, w)

Input Parameters

1:     $\mathrm{iflag}$int64int32nag_int scalar
Will be set to $2$.
2:     $\mathrm{n}$int64int32nag_int scalar
The number $n$ of variables.
3:     $\mathrm{xc}\left({\mathbf{n}}\right)$ – double array
The point $x$ at which $F$ and its derivatives are required.
4:     $\mathrm{iw}\left(\mathit{liw}\right)$int64int32nag_int array
5:     $\mathrm{w}\left(\mathit{lw}\right)$ – double array
These arguments are present so that funct will be of the form required by the minimization functions mentioned in Description. funct is called with nag_opt_check_deriv (e04hc)'s arguments iw, liw, w, lw as these arguments. If the advice given in the minimization function documents is being followed, you will have no reason to examine or change any elements of iw or w. In any case, funct must not change the first $3×{\mathbf{n}}$ elements of w.

Output Parameters

1:     $\mathrm{iflag}$int64int32nag_int scalar
If you reset iflag to a negative number in funct and return control to nag_opt_check_deriv (e04hc), nag_opt_check_deriv (e04hc) will terminate immediately with ifail set to your setting of iflag.
2:     $\mathrm{fc}$ – double scalar
Unless funct resets iflag, fc must be set to the value of the function $F$ at the current point $x$.
3:     $\mathrm{gc}\left({\mathbf{n}}\right)$ – double array
Unless funct resets iflag, ${\mathbf{gc}}\left(\mathit{j}\right)$ must be set to the value of the first derivative $\frac{\partial F}{\partial {x}_{\mathit{j}}}$ at the point $x$, for $\mathit{j}=1,2,\dots ,n$.
4:     $\mathrm{iw}\left(\mathit{liw}\right)$int64int32nag_int array
5:     $\mathrm{w}\left(\mathit{lw}\right)$ – double array
2:     $\mathrm{x}\left({\mathbf{n}}\right)$ – double array
${\mathbf{x}}\left(\mathit{j}\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 funct. ‘Obvious’ settings, such as $0.0\text{​ 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.
3:     $\mathrm{iw}\left(\mathit{liw}\right)$int64int32nag_int array
liw, the dimension of the array, must satisfy the constraint $\mathit{liw}\ge 1$.
This array is in the argument list so that it can be used by other library functions for passing integer quantities to funct. It is not examined or changed by nag_opt_check_deriv (e04hc). Generally, you must provide an array iw but are advised not to use it.
4:     $\mathrm{w}\left(\mathit{lw}\right)$ – double array
lw, the dimension of the array, must satisfy the constraint $\mathit{lw}\ge 3×{\mathbf{n}}$.
Constraint: $\mathit{lw}\ge 3×{\mathbf{n}}$.

### Optional Input Parameters

1:     $\mathrm{n}$int64int32nag_int scalar
Default: the dimension of the array x.
The number $n$ of independent variables in the objective function.
Constraint: ${\mathbf{n}}\ge 1$.

### Output Parameters

1:     $\mathrm{f}$ – double scalar
Unless you set iflag negative in the first call of funct, f contains the value of the objective function $F\left(x\right)$ at the point given by you in x.
2:     $\mathrm{g}\left({\mathbf{n}}\right)$ – double array
Unless you set iflag negative in the first call of funct, ${\mathbf{g}}\left(\mathit{j}\right)$ contains the value of the derivative $\frac{\partial F}{\partial {x}_{\mathit{j}}}$ at the point given in x, as calculated by funct, for $\mathit{j}=1,2,\dots ,n$.
3:     $\mathrm{iw}\left(\mathit{liw}\right)$int64int32nag_int array
4:     $\mathrm{w}\left(\mathit{lw}\right)$ – double array
$\mathit{lw}=3×{\mathbf{n}}$.
Communication array, used to store information between calls to nag_opt_check_deriv (e04hc).
5:     $\mathrm{ifail}$int64int32nag_int scalar
${\mathbf{ifail}}={\mathbf{0}}$ unless the function detects an error (see Error Indicators and Warnings).

## Error Indicators and Warnings

Note: nag_opt_check_deriv (e04hc) may return useful information for one or more of the following detected errors or warnings.
Errors or warnings detected by the function:

Cases prefixed with W are classified as warnings and do not generate an error of type NAG:error_n. See nag_issue_warnings.

W  ${\mathbf{ifail}}<0$
A negative value of ifail indicates an exit from nag_opt_check_deriv (e04hc) because you have set iflag negative in funct. The setting of ifail will be the same as your setting of iflag. The check on funct will not have been completed.
${\mathbf{ifail}}=1$
 On entry, ${\mathbf{n}}<1$, or $\mathit{liw}<1$, or $\mathit{lw}<3×{\mathbf{n}}$.
W  ${\mathbf{ifail}}=2$
You should check carefully the derivation and programming of expressions for the derivatives of $F\left(x\right)$, because it is very unlikely that funct is calculating them correctly.
${\mathbf{ifail}}=-99$
${\mathbf{ifail}}=-399$
Your licence key may have expired or may not have been installed correctly.
${\mathbf{ifail}}=-999$
Dynamic memory allocation failed.

## Accuracy

ifail is set to $2$ if
 $vk-gTpk 2≥h× gTpk 2+1$
for $k=1\text{​ or ​}2$. (See Description 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 (x02aj).

funct is called $3$ times.
Before using nag_opt_check_deriv (e04hc) to check the calculation of first derivatives, you should be confident that funct 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 funct at nontrivial points $x$ with values calculated independently. (‘Non-trivial’ means that, as when setting $x$ before calling nag_opt_check_deriv (e04hc), coordinates such as $0.0$ or $1.0$ should be avoided.)
nag_opt_check_deriv (e04hc) only checks the derivatives calculated when ${\mathbf{iflag}}=2$. So, if funct is intended for use in conjunction with a minimization function which may set iflag to $1$, you must check that, for given settings of the ${\mathbf{xc}}\left(j\right)$, funct produces the same values for the ${\mathbf{gc}}\left(j\right)$ when iflag is set to $1$ as when iflag is set to $2$.

## Example

Suppose that it is intended to use nag_opt_bounds_mod_deriv_comp (e04kd) to minimize
 $F= x1+10x2 2+5⁢ x3-x4 2+ x2-2x3 4+10⁢ x1-x4 4.$
The following program could be used to check the first derivatives calculated by funct. (The tests of whether ${\mathbf{iflag}}=0$ or $1$ in funct are present ready for when funct is called by nag_opt_bounds_mod_deriv_comp (e04kd). nag_opt_check_deriv (e04hc) will always call funct with iflag set to 2.)
```function e04hc_example

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

x  = [1.46; -0.82;  0.57;  1.21];
fprintf('The test point is: %8.2f%8.2f%8.2f%8.2f\n',x);

iw = [int64(0)];
w  = zeros(12,1);

wstat = warning;
warning('OFF');
[f, g, iw, w, ifail] = e04hc(@funct, x, iw, w);
if (ifail>=0)
if (ifail==0)
fprintf('\n1st derivatives are consistent with function values\n');
else
fprintf('\nProbable error in calculation of 1st derivatives\n');
end
fprintf('At test point, f = %7.3f\n',f)
fprintf('               g = %7.3f %7.3f %7.3f %7.3f\n',g)
end

warning(wstat);

function [iflag, fc, gc, iw, w] = funct(iflag, n, xc, iw, liw, w, lw)
gc = zeros(n, 1);
fc = 0;
a = xc(1) + 10*xc(2);
b = xc(3) -    xc(4);
c = xc(2) -  2*xc(3);
d = xc(1) -    xc(4);
if (iflag ~= 1)
fc = a^2 + 5*b^2 + c^4 + 10*d^4;
end
if (iflag ~= 0)
gc(1) =   2*a + 40*d^3;
gc(2) =  20*a +  4*c^3;
gc(3) =  10*b -  8*c^3;
gc(4) = -10*b - 40*d^3;
end
```
```e04hc example results

The test point is:     1.46   -0.82    0.57    1.21

1st derivatives are consistent with function values
At test point, f =  62.273
g = -12.855 -164.918  53.836   5.775
```