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:
Mark 22: liw, lw have been 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(x1,x2,,xn)$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 = (x1,x2,,xn)T$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$F$ and its first derivatives gj = (F)/(xj) ${g}_{\mathit{j}}=\frac{\partial F}{\partial {x}_{\mathit{j}}}$, for j = 1,2,,n$\mathit{j}=1,2,\dots ,n$ at x$x$. The components of the user-supplied derivatives along two orthogonal directions (defined by unit vectors p1${p}_{1}$ and p2${p}_{2}$, say) are then calculated; these will be gTp1${g}^{\mathrm{T}}{p}_{1}$ and gTp2${g}^{\mathrm{T}}{p}_{2}$ respectively. The same components are also estimated by finite differences, giving quantities
 vk = (F(x + hpk) − F(x))/h,  k = 1,2 $vk=F(x+hpk)-F(x)h, k=1,2$
where h$h$ is a small positive scalar. If the relative difference between v1${v}_{1}$ and gTp1${g}^{\mathrm{T}}{p}_{1}$ or between v2${v}_{2}$ and gTp2${g}^{\mathrm{T}}{p}_{2}$ is judged too large, an error indicator is set.

None.

## Parameters

### Compulsory Input Parameters

1:     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 Section [Description] gives you the option of resetting parameters 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 parameter in question is reset.)
[iflag, fc, gc, iw, w] = funct(iflag, n, xc, iw, w)

Input Parameters

1:     iflag – int64int32nag_int scalar
Will be set to 2$2$.
2:     n – int64int32nag_int scalar
The number n$n$ of variables.
3:     xc(n) – double array
The point x$x$ at which F$F$ and its derivatives are required.
4:     iw(liw) – int64int32nag_int array
5:     w(lw) – double array
These parameters are present so that funct will be of the form required by the minimization functions mentioned in Section [Description]. funct is called with nag_opt_check_deriv (e04hc)'s parameters iw, liw, w, lw as these parameters. 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 × n$3×{\mathbf{n}}$ elements of w.

Output Parameters

1:     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:     fc – double scalar
Unless funct resets iflag, fc must be set to the value of the function F$F$ at the current point x$x$.
3:     gc(n) – double array
Unless funct resets iflag, gc(j)${\mathbf{gc}}\left(\mathit{j}\right)$ must be set to the value of the first derivative (F)/(xj) $\frac{\partial F}{\partial {x}_{\mathit{j}}}$ at the point x$x$, for j = 1,2,,n$\mathit{j}=1,2,\dots ,n$.
4:     iw(liw) – int64int32nag_int array
5:     w(lw) – double array
2:     x(n) – double array
n, the dimension of the array, must satisfy the constraint n1${\mathbf{n}}\ge 1$.
x(j)${\mathbf{x}}\left(\mathit{j}\right)$, for j = 1,2,,n$\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 ​ or ​ 1.0$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:     iw(liw) – int64int32nag_int array
liw, the dimension of the array, must satisfy the constraint liw1$\mathit{liw}\ge 1$.
This array is in the parameter 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:     w(lw) – double array
lw, the dimension of the array, must satisfy the constraint lw3 × n$\mathit{lw}\ge 3×{\mathbf{n}}$.
Constraint: lw3 × n$\mathit{lw}\ge 3×{\mathbf{n}}$.

### Optional Input Parameters

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

liw lw

### Output Parameters

1:     f – double scalar
Unless you set iflag negative in the first call of funct, f contains the value of the objective function F(x)$F\left(x\right)$ at the point given by you in x.
2:     g(n) – double array
Unless you set iflag negative in the first call of funct, g(j)${\mathbf{g}}\left(\mathit{j}\right)$ contains the value of the derivative (F)/(xj) $\frac{\partial F}{\partial {x}_{\mathit{j}}}$ at the point given in x, as calculated by funct, for j = 1,2,,n$\mathit{j}=1,2,\dots ,n$.
3:     iw(liw) – int64int32nag_int array
4:     w(lw) – double array
lw3 × n$\mathit{lw}\ge 3×{\mathbf{n}}$.
Communication array, used to store information between calls to nag_opt_check_deriv (e04hc).
5:     ifail – int64int32nag_int scalar
${\mathrm{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 ifail < 0${\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.
ifail = 1${\mathbf{ifail}}=1$
 On entry, n < 1${\mathbf{n}}<1$, or liw < 1$\mathit{liw}<1$, or lw < 3 × n$\mathit{lw}<3×{\mathbf{n}}$.
W ifail = 2${\mathbf{ifail}}=2$
You should check carefully the derivation and programming of expressions for the derivatives of F(x)$F\left(x\right)$, because it is very unlikely that funct is calculating them correctly.

## Accuracy

ifail is set to 2$2$ if
 (vk − gTpk)2 ≥ h × ((gTpk)2 + 1) $(vk-gTpk) 2≥h×( (gTpk) 2+1)$
for k = 1​ or ​2$k=1\text{​ or ​}2$. (See Section [Description] for definitions of the quantities involved.) The scalar h$h$ is set equal to sqrt(ε)$\sqrt{\epsilon }$, where ε$\epsilon$ is the machine precision as given by nag_machine_precision (x02aj).

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

## Example

```function nag_opt_check_deriv_example
x = [1.46;
-0.82;
0.57;
1.21];
iw = [int64(0)];
w = zeros(12,1);
[f, g, iwOut, wOut, ifail] = nag_opt_check_deriv(@funct, x, iw, w)

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

f =

62.2726

g =

-12.8550
-164.9181
53.8363
5.7750

iwOut =

0

wOut =

1.4600
-0.8200
0.5700
1.2100
1.4600
-0.8200
0.5700
1.2100
-12.8550
-164.9181
53.8363
5.7750

ifail =

0

```
```function e04hc_example
x = [1.46;
-0.82;
0.57;
1.21];
iw = [int64(0)];
w = zeros(12,1);
[f, g, iwOut, wOut, ifail] = e04hc(@funct, x, iw, w)

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

f =

62.2726

g =

-12.8550
-164.9181
53.8363
5.7750

iwOut =

0

wOut =

1.4600
-0.8200
0.5700
1.2100
1.4600
-0.8200
0.5700
1.2100
-12.8550
-164.9181
53.8363
5.7750

ifail =

0

```