hide long namesshow long names
hide short namesshow short names
Integer type:  int32  int64  nag_int  show int32  show int32  show int64  show int64  show nag_int  show nag_int

PDF version (NAG web site, 64-bit version, 64-bit version)
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(x1,x2,,xn) 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)Tx=(x1,x2,,xn)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 FF and its first derivatives gj = (F)/(xj) gj= F xj , for j = 1,2,,nj=1,2,,n at xx. The components of the user-supplied derivatives along two orthogonal directions (defined by unit vectors p1p1 and p2p2, say) are then calculated; these will be gTp1gTp1 and gTp2gTp2 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 hh is a small positive scalar. If the relative difference between v1v1 and gTp1gTp1 or between v2v2 and gTp2gTp2 is judged too large, an error indicator is set.

References

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 22.
2:     n – int64int32nag_int scalar
The number nn of variables.
3:     xc(n) – double array
The point xx at which FF 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 × n3×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 FF at the current point xx.
3:     gc(n) – double array
Unless funct resets iflag, gc(j)gcj must be set to the value of the first derivative (F)/(xj) F xj at the point xx, for j = 1,2,,nj=1,2,,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 n1n1.
x(j)xj, for j = 1,2,,nj=1,2,,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.00.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.
3:     iw(liw) – int64int32nag_int array
liw, the dimension of the array, must satisfy the constraint liw1liw1.
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 × nlw3×n.
Constraint: lw3 × nlw3×n.

Optional Input Parameters

1:     n – int64int32nag_int scalar
Default: The dimension of the array x.
The number nn of independent variables in the objective function.
Constraint: n1n1.

Input Parameters Omitted from the MATLAB Interface

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(x) 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)gj contains the value of the derivative (F)/(xj) F xj at the point given in x, as calculated by funct, for j = 1,2,,nj=1,2,,n.
3:     iw(liw) – int64int32nag_int array
4:     w(lw) – double array
lw3 × nlw3×n.
Communication array, used to store information between calls to nag_opt_check_deriv (e04hc).
5:     ifail – int64int32nag_int scalar
ifail = 0ifail=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 < 0ifail<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 = 1ifail=1
On entry,n < 1n<1,
orliw < 1liw<1,
orlw < 3 × nlw<3×n.
W ifail = 2ifail=2
You should check carefully the derivation and programming of expressions for the derivatives of F(x)F(x), because it is very unlikely that funct is calculating them correctly.

Accuracy

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

Further Comments

funct is called 33 times.
Before using nag_opt_check_deriv (e04hc) to check the calculation of first derivatives, you should be confident that funct is calculating FF correctly. The usual way of checking the calculation of the function is to compare values of F(x)F(x) calculated by funct at nontrivial points xx with values calculated independently. (‘Non-trivial’ means that, as when setting xx before calling nag_opt_check_deriv (e04hc), coordinates such as 0.00.0 or 1.01.0 should be avoided.)
nag_opt_check_deriv (e04hc) only checks the derivatives calculated when iflag = 2iflag=2. So, if funct is intended for use in conjunction with a minimization function which may set iflag to 11, you must check that, for given settings of the xc(j)xcj, funct produces the same values for the gc(j)gcj when iflag is set to 11 as when iflag is set to 22.

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



PDF version (NAG web site, 64-bit version, 64-bit version)
Chapter Contents
Chapter Introduction
NAG Toolbox

© The Numerical Algorithms Group Ltd, Oxford, UK. 2009–2013