E04 Chapter Contents
E04 Chapter Introduction
NAG Library Manual

# NAG Library Routine DocumentE04HCF

Note:  before using this routine, please read the Users' Note for your implementation to check the interpretation of bold italicised terms and other implementation-dependent details.

## 1  Purpose

E04HCF checks that a subroutine for evaluating an objective function and its first derivatives produces derivative values which are consistent with the function values calculated.

## 2  Specification

 SUBROUTINE E04HCF ( N, FUNCT, X, F, G, IW, LIW, W, LW, IFAIL)
 INTEGER N, IW(LIW), LIW, LW, IFAIL REAL (KIND=nag_wp) X(N), F, G(N), W(LW) EXTERNAL FUNCT

## 3  Description

Routines for minimizing a function of several variables may require you to supply a subroutine to evaluate the objective function $F\left({x}_{1},{x}_{2},\dots ,{x}_{n}\right)$ and its first derivatives. E04HCF is designed to check the derivatives calculated by such user-supplied subroutines . As well as the routine 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 E04HCF checks routines of the form required for E04KDF and E04LBF.
E04HCF 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.

## 5  Parameters

1:     $\mathrm{N}$ – INTEGERInput
On entry: the number $n$ of independent variables in the objective function.
Constraint: ${\mathbf{N}}\ge 1$.
2:     $\mathrm{FUNCT}$ – SUBROUTINE, supplied by the user.External Procedure
FUNCT must evaluate the function and its first derivatives at a given point. (The minimization routines mentioned in Section 3 gives you the option of resetting parameters of FUNCT to cause the minimization process to terminate immediately. E04HCF will also terminate immediately, without finishing the checking process, if the parameter in question is reset.)
The specification of FUNCT is:
 SUBROUTINE FUNCT ( IFLAG, N, XC, FC, GC, IW, LIW, W, LW)
 INTEGER IFLAG, N, IW(LIW), LIW, LW REAL (KIND=nag_wp) XC(N), FC, GC(N), W(LW)
1:     $\mathrm{IFLAG}$ – INTEGERInput/Output
On entry: will be set to $2$.
On exit: if you reset IFLAG to a negative number in FUNCT and return control to E04HCF, E04HCF will terminate immediately with IFAIL set to your setting of IFLAG.
2:     $\mathrm{N}$ – INTEGERInput
On entry: the number $n$ of variables.
3:     $\mathrm{XC}\left({\mathbf{N}}\right)$ – REAL (KIND=nag_wp) arrayInput
On entry: the point $x$ at which $F$ and its derivatives are required.
4:     $\mathrm{FC}$ – REAL (KIND=nag_wp)Output
On exit: unless FUNCT resets IFLAG, FC must be set to the value of the function $F$ at the current point $x$.
5:     $\mathrm{GC}\left({\mathbf{N}}\right)$ – REAL (KIND=nag_wp) arrayOutput
On exit: 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$.
6:     $\mathrm{IW}\left({\mathbf{LIW}}\right)$ – INTEGER arrayWorkspace
7:     $\mathrm{LIW}$ – INTEGERInput
8:     $\mathrm{W}\left({\mathbf{LW}}\right)$ – REAL (KIND=nag_wp) arrayWorkspace
9:     $\mathrm{LW}$ – INTEGERInput
These parameters are present so that FUNCT will be of the form required by the minimization routines mentioned in Section 3. FUNCT is called with E04HCF's parameters IW, LIW, W, LW as these parameters. If the advice given in the minimization routine 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.
FUNCT must either be a module subprogram USEd by, or declared as EXTERNAL in, the (sub)program from which E04HCF is called. Parameters denoted as Input must not be changed by this procedure.
3:     $\mathrm{X}\left({\mathbf{N}}\right)$ – REAL (KIND=nag_wp) arrayInput
On entry: ${\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.
4:     $\mathrm{F}$ – REAL (KIND=nag_wp)Output
On exit: 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.
5:     $\mathrm{G}\left({\mathbf{N}}\right)$ – REAL (KIND=nag_wp) arrayOutput
On exit: 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$.
6:     $\mathrm{IW}\left({\mathbf{LIW}}\right)$ – INTEGER arrayCommunication Array
This array is in the parameter list so that it can be used by other library routines for passing integer quantities to FUNCT. It is not examined or changed by E04HCF. Generally, you must provide an array IW but are advised not to use it.
7:     $\mathrm{LIW}$ – INTEGERInput
On entry: the dimension of the array IW as declared in the (sub)program from which E04HCF is called.
Constraint: ${\mathbf{LIW}}\ge 1$.
8:     $\mathrm{W}\left({\mathbf{LW}}\right)$ – REAL (KIND=nag_wp) arrayCommunication Array
9:     $\mathrm{LW}$ – INTEGERInput
On entry: the dimension of the array W as declared in the (sub)program from which E04HCF is called.
Constraint: ${\mathbf{LW}}\ge 3×{\mathbf{N}}$.
10:   $\mathrm{IFAIL}$ – INTEGERInput/Output
On entry: IFAIL must be set to $0$, $-1\text{​ or ​}1$. If you are unfamiliar with this parameter you should refer to Section 3.3 in the Essential Introduction for details.
For environments where it might be inappropriate to halt program execution when an error is detected, the value $-1\text{​ or ​}1$ is recommended. If the output of error messages is undesirable, then the value $1$ is recommended. Otherwise, because for this routine the values of the output parameters may be useful even if ${\mathbf{IFAIL}}\ne {\mathbf{0}}$ on exit, the recommended value is $-1$. When the value $-\mathbf{1}\text{​ or ​}1$ is used it is essential to test the value of IFAIL on exit.
On exit: ${\mathbf{IFAIL}}={\mathbf{0}}$ unless the routine detects an error or a warning has been flagged (see Section 6).

## 6  Error Indicators and Warnings

If on entry ${\mathbf{IFAIL}}={\mathbf{0}}$ or $-{\mathbf{1}}$, explanatory error messages are output on the current error message unit (as defined by X04AAF).
Note: E04HCF may return useful information for one or more of the following detected errors or warnings.
Errors or warnings detected by the routine:
${\mathbf{IFAIL}}<0$
A negative value of IFAIL indicates an exit from E04HCF 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 ${\mathbf{LIW}}<1$, or ${\mathbf{LW}}<3×{\mathbf{N}}$.
${\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$
See Section 3.8 in the Essential Introduction for further information.
${\mathbf{IFAIL}}=-399$
Your licence key may have expired or may not have been installed correctly.
See Section 3.7 in the Essential Introduction for further information.
${\mathbf{IFAIL}}=-999$
Dynamic memory allocation failed.
See Section 3.6 in the Essential Introduction for further information.

## 7  Accuracy

IFAIL is set to $2$ if
 $vk-gTpk 2≥h× gTpk 2+1$
for $k=1\text{​ 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 X02AJF.

## 8  Parallelism and Performance

Not applicable.

FUNCT is called $3$ times.
Before using E04HCF 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 E04HCF, coordinates such as $0.0$ or $1.0$ should be avoided.)
E04HCF only checks the derivatives calculated when ${\mathbf{IFLAG}}=2$. So, if FUNCT is intended for use in conjunction with a minimization routine 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$.

## 10  Example

Suppose that it is intended to use E04KDF 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 E04KDF. E04HCF will always call FUNCT with IFLAG set to 2.)

### 10.1  Program Text

Program Text (e04hcfe.f90)

None.

### 10.3  Program Results

Program Results (e04hcfe.r)