NAG Toolbox: nag_opt_check_deriv2 (e04hd)

Purpose

Syntax

Description

References

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. (nag_opt_bounds_mod_deriv2_comp (e04lb) gives you the option of resetting arguments of funct to cause the minimization process to terminate immediately. nag_opt_check_deriv2 (e04hd) 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

To funct, iflag 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 the function and first 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 nag_opt_bounds_mod_deriv2_comp (e04lb). funct is called with nag_opt_check_deriv2 (e04hd)'s arguments iw, liw, w, lw as these arguments. If the advice given in nag_opt_bounds_mod_deriv2_comp (e04lb) 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 $5\times \mathbf{n}$ elements of w.

Output Parameters

1:     $\mathrm{iflag}$ – int64int32nag_int scalar

If you set iflag to some negative number in funct and return control to nag_opt_check_deriv2 (e04hd), nag_opt_check_deriv2 (e04hd) 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 objective 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

nag_opt_check_deriv (e04hc) should be used to check the first derivatives calculated by funct before nag_opt_check_deriv2 (e04hd) is used to check the second derivatives, since nag_opt_check_deriv2 (e04hd) assumes that the first derivatives are correct.

2:     $\mathrm{h}$ – function handle or string containing name of m-file

h must evaluate the second derivatives of the function at a given point. (As with funct, a argument can be set to cause immediate termination.)

[iflag, fhesl, fhesd, iw, w] = h(iflag, n, xc, lh, fhesd, iw, w)

Input Parameters

1:     $\mathrm{iflag}$ – int64int32nag_int scalar

Is set to a non-negative number.

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 the second derivatives of $F\left(x\right)$ are required.

4:     $\mathrm{lh}$ – int64int32nag_int scalar

The length of the array fhesl.

5:     $\mathrm{fhesd}\left(\mathbf{n}\right)$ – double array

Contains the value of $\frac{\partial F}{\partial x_{\mathit{j}}}$ at the point $x$, for $\mathit{j}=1,2,\dots ,n$. Functions written to take advantage of a similar feature of nag_opt_bounds_mod_deriv2_comp (e04lb) can be tested as they stand by nag_opt_check_deriv2 (e04hd).

6:     $\mathrm{iw}\left(\mathit{liw}\right)$ – int64int32nag_int array

7:     $\mathrm{w}\left(\mathit{lw}\right)$ – double array

As in funct, these arguments correspond to the arguments iw, liw, w and lw of nag_opt_check_deriv2 (e04hd). h must not change the first $5\times \mathbf{n}$ elements of w.

Output Parameters

1:     $\mathrm{iflag}$ – int64int32nag_int scalar

If h resets iflag to a negative number, nag_opt_check_deriv2 (e04hd) will terminate immediately with ifail set to your setting of iflag.

2:     $\mathrm{fhesl}\left(\mathbf{lh}\right)$ – double array

Unless iflag is reset, h must place the strict lower triangle of the second derivative matrix of $F$ (evaluated at the point $x$) in fhesl, stored by rows, i.e., $\mathbf{fhesl}\left(\left(\mathit{i}-1\right)\left(\mathit{i}-2\right)/2+\mathit{j}\right)$ must be set to the value of $\frac{{\partial }^{2}F}{\partial x_{\mathit{i}}\partial x_{\mathit{j}}}$ at the point $x$, for $\mathit{i}=2,3,\dots ,n$ and $\mathit{j}=1,2,\dots ,\mathit{i}-1$. (The upper triangle is not required because the matrix is symmetric.)

3:     $\mathrm{fhesd}\left(\mathbf{n}\right)$ – double array

Unless iflag is reset, h must place the diagonal elements of the second derivative matrix of $F$ (evaluated at the point $x$) in fhesd, i.e., $\mathbf{fhesd}\left(\mathit{j}\right)$ must be set to the value of $\frac{{\partial }^{2}F}{\partial x_{\mathit{j}}^2}$ 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

3:     $\mathrm{x}\left(\mathbf{n}\right)$ – double array

$\mathbf{x}\left(\mathit{j}\right)$, for $\mathit{j}=1,2,\dots ,n$ must contain 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 advisable that no two elements of x should be the same.

4:     $\mathrm{lh}$ – int64int32nag_int scalar

The dimension of the array hesl.

Constraint: $\mathbf{lh}\ge \max \left(1,\mathbf{n}\times \left(\mathbf{n}-1\right)/2\right)$.

5:     $\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 or h. It is not examined or changed by nag_opt_check_deriv2 (e04hd). In general you must provide an array iw, but are advised not to use it.

6:     $\mathrm{w}\left(\mathit{lw}\right)$ – double array

lw, the dimension of the array, must satisfy the constraint $\mathit{lw}\ge 5\times \mathbf{n}$.

Constraint: $\mathit{lw}\ge 5\times \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{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 first derivative $\frac{\partial F}{\partial x_{\mathit{j}}}$ at the point given in x, as calculated by funct, for $\mathit{j}=1,2,\dots ,\mathbf{n}$.

2:     $\mathrm{hesl}\left(\mathbf{lh}\right)$ – double array

Unless you set iflag negative in h, hesl contains the strict lower triangle of the second derivative matrix of $F$, as evaluated by h at the point given in x, stored by rows.

3:     $\mathrm{hesd}\left(\mathbf{n}\right)$ – double array

Unless you set iflag negative in h, hesd contains the diagonal elements of the second derivative matrix of $F$, as evaluated by h at the point given in x.

4:     $\mathrm{iw}\left(\mathit{liw}\right)$ – int64int32nag_int array

5:     $\mathrm{w}\left(\mathit{lw}\right)$ – double array

$\mathit{lw}=5\times \mathbf{n}$.

Communication array, used to store information between calls to nag_opt_check_deriv2 (e04hd).

6:     $\mathrm{ifail}$ – int64int32nag_int scalar

$\mathbf{ifail}=\mathbf{0}$ unless the function detects an error (see Error Indicators and Warnings).

Error Indicators and Warnings

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_deriv2 (e04hd) because you have set iflag negative in funct or h. The value of ifail will be the same as the value you set for iflag. The check on h will not have been completed.

   $\mathbf{ifail}=1$

On entry,	$\mathbf{n}<1$,
or	$\mathbf{lh}<\max \left(1,\mathbf{n}\times \left(\mathbf{n}-1\right)/2\right)$,
or	$\mathit{liw}<1$,
or	$\mathit{lw}<5\times \mathbf{n}$.

W  $\mathbf{ifail}=2$

You should check carefully the derivation and programming of expressions for the second derivatives of $F\left(x\right)$, because it is very unlikely that h is calculating them correctly.

   $\mathbf{ifail}=-99$

An unexpected error has been triggered by this routine. Please contact NAG.

   $\mathbf{ifail}=-399$

Your licence key may have expired or may not have been installed correctly.

   $\mathbf{ifail}=-999$

Dynamic memory allocation failed.

Accuracy

Further Comments

Example

Open in the MATLAB editor: e04hd_example

function e04hd_example


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

x = [1.46  -0.82    0.57   1.21];
n = int64(4);
lh = int64(6);
iw = [int64(0)];
w =  zeros(20,1);
[g, hesl, hesd, iw, w, ifail] = ...
e04hd( ...
       @funct, @hess, x, lh, iw, w);

[iflag, f, gc] = funct(n, n, x);

fprintf('The test point is: %8.2f%8.2f%8.2f%8.2f\n',x);

fprintf('\n2nd derivatives are consistent with 1st derivatives\n');
fprintf('\nAt test point, f = %7.3f\n',f)
fprintf(' 1st derivatives = %7.3f %7.3f %7.3f %7.3f\n',g)

fprintf('\nH gives the lower triangle of the Hessian matrix\n');
fprintf('%12.3e\n', hesd(1));
k = 1;
for i = 2:n
  fprintf('%12.3e', hesl(k:(k+i-2)), hesd(i)); 
  fprintf('\n');
  k = k + i - 1;
end



function [iflag, fc, gc] = funct(iflag, n, xc)
  gc = zeros(n, 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;
  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;


function [iflag, fhesl, fhesd] = hess(iflag, n, xc, lh, fhesd)
  fhesl = zeros(lh, 1);
  fhesd = zeros(n, 1);

  fhesd(1) =   2 + 120*(xc(1)-  xc(4))^2;
  fhesd(2) = 200 +  12*(xc(2)-2*xc(3))^2;
  fhesd(3) =  10 +  48*(xc(2)-2*xc(3))^2;
  fhesd(4) =  10 + 120*(xc(1)-  xc(4))^2;

  fhesl(1) = 20;
  fhesl(2) =  0;
  fhesl(3) = -24*(xc(2)-2*xc(3))^2;
  fhesl(4) = -120*(xc(1)-xc(4))^2;
  fhesl(5) =  0;
  fhesl(6) = -10;

e04hd example results

The test point is:     1.46   -0.82    0.57    1.21

2nd derivatives are consistent with 1st derivatives

At test point, f =  62.273
 1st derivatives = -12.855 -164.918  53.836   5.775

H gives the lower triangle of the Hessian matrix
   9.500e+00
   2.000e+01   2.461e+02
   0.000e+00  -9.220e+01   1.944e+02
  -7.500e+00   0.000e+00  -1.000e+01   1.750e+01