# NAG Library Routine Document

## 1Purpose

e04hdf checks that a subroutine for calculating second derivatives of an objective function is consistent with a subroutine for calculating the corresponding first derivatives.

## 2Specification

Fortran Interface
 Subroutine e04hdf ( n, h, x, g, hesl, lh, hesd, iw, liw, w, lw,
 Integer, Intent (In) :: n, lh, liw, lw Integer, Intent (Inout) :: iw(liw), ifail Real (Kind=nag_wp), Intent (In) :: x(n) Real (Kind=nag_wp), Intent (Inout) :: w(lw) Real (Kind=nag_wp), Intent (Out) :: g(n), hesl(lh), hesd(n) External :: funct, h
#include nagmk26.h
 void e04hdf_ (const Integer *n, void (NAG_CALL *funct)(Integer *iflag, const Integer *n, const double xc[], double *fc, double gc[], Integer iw[], const Integer *liw, double w[], const Integer *lw),void (NAG_CALL *h)(Integer *iflag, const Integer *n, const double xc[], double fhesl[], const Integer *lh, double fhesd[], Integer iw[], const Integer *liw, double w[], const Integer *lw),const double x[], double g[], double hesl[], const Integer *lh, double hesd[], Integer iw[], const Integer *liw, double w[], const Integer *lw, Integer *ifail)

## 3Description

Routines for minimizing a function $F\left({x}_{1},{x}_{2},\dots ,{x}_{n}\right)$ of the variables ${x}_{1},{x}_{2},\dots ,{x}_{n}$ may require you to provide a subroutine to evaluate the second derivatives of $F$. e04hdf is designed to check the second derivatives calculated by such user-supplied subroutines. As well as the routine to be checked (h), you must supply a subroutine (funct) to evaluate the first derivatives, and a point $x={\left({x}_{1},{x}_{2},\dots ,{x}_{n}\right)}^{\mathrm{T}}$ at which the checks will be made. Note that e04hdf checks routines of the form required for e04lbf.
e04hdf first calls user-supplied subroutines funct and h to evaluate the first and second derivatives of $F$ at $x$. The user-supplied Hessian matrix ($H$, say) is projected onto two orthogonal vectors $y$ and $z$ to give the scalars ${y}^{\mathrm{T}}Hy$ and ${z}^{\mathrm{T}}Hz$ respectively. The same projections of the Hessian matrix are also estimated by finite differences, giving
 $p=yTgx+hy-yTgx/h and q=zTgx+hz-zTgx/h$
respectively, where $g\left(\right)$ denotes the vector of first derivatives at the point in brackets and $h$ is a small positive scalar. If the relative difference between $p$ and ${y}^{\mathrm{T}}Hy$ or between $q$ and ${z}^{\mathrm{T}}Hz$ is judged too large, an error indicator is set.

None.

## 5Arguments

1:     $\mathbf{n}$ – IntegerInput
On entry: the number $n$ of independent variables in the objective function.
Constraint: ${\mathbf{n}}\ge 1$.
2:     $\mathbf{funct}$ – Subroutine, supplied by the user.External Procedure
funct must evaluate the function and its first derivatives at a given point. (e04lbf gives you the option of resetting arguments of funct to cause the minimization process to terminate immediately. e04hdf will also terminate immediately, without finishing the checking process, if the argument in question is reset.)
The specification of funct is:
Fortran Interface
 Subroutine funct ( n, xc, fc, gc, iw, liw, w, lw)
 Integer, Intent (In) :: n, liw, lw Integer, Intent (Inout) :: iflag, iw(liw) Real (Kind=nag_wp), Intent (In) :: xc(n) Real (Kind=nag_wp), Intent (Inout) :: w(lw) Real (Kind=nag_wp), Intent (Out) :: fc, gc(n)
#include nagmk26.h
 void funct (Integer *iflag, const Integer *n, const double xc[], double *fc, double gc[], Integer iw[], const Integer *liw, double w[], const Integer *lw)
1:     $\mathbf{iflag}$ – IntegerInput/Output
On entry: to funct, iflag will be set to $2$.
On exit: if you set iflag to some negative number in funct and return control to e04hdf, e04hdf will terminate immediately with ifail set to your setting of iflag.
2:     $\mathbf{n}$ – IntegerInput
On entry: the number $n$ of variables.
3:     $\mathbf{xc}\left({\mathbf{n}}\right)$ – Real (Kind=nag_wp) arrayInput
On entry: the point $x$ at which the function and first derivatives are required.
4:     $\mathbf{fc}$ – Real (Kind=nag_wp)Output
On exit: unless funct resets iflag, fc must be set to the value of the objective function $F$ at the current point $x$.
5:     $\mathbf{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:     $\mathbf{iw}\left({\mathbf{liw}}\right)$ – Integer arrayWorkspace
7:     $\mathbf{liw}$ – IntegerInput
8:     $\mathbf{w}\left({\mathbf{lw}}\right)$ – Real (Kind=nag_wp) arrayWorkspace
9:     $\mathbf{lw}$ – IntegerInput
These arguments are present so that funct will be of the form required by e04lbf. funct is called with e04hdf's arguments iw, liw, w, lw as these arguments. If the advice given in e04lbf 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×{\mathbf{n}}$ elements of w.
funct must either be a module subprogram USEd by, or declared as EXTERNAL in, the (sub)program from which e04hdf is called. Arguments denoted as Input must not be changed by this procedure.
Note: funct should not return floating-point NaN (Not a Number) or infinity values, since these are not handled by e04hdf. If your code inadvertently does return any NaNs or infinities, e04hdf is likely to produce unexpected results.
e04hcf should be used to check the first derivatives calculated by funct before e04hdf is used to check the second derivatives, since e04hdf assumes that the first derivatives are correct.
3:     $\mathbf{h}$ – Subroutine, supplied by the user.External Procedure
h must evaluate the second derivatives of the function at a given point. (As with funct, an argument can be set to cause immediate termination.)
The specification of h is:
Fortran Interface
 Subroutine h ( n, xc, lh, iw, liw, w, lw)
 Integer, Intent (In) :: n, lh, liw, lw Integer, Intent (Inout) :: iflag, iw(liw) Real (Kind=nag_wp), Intent (In) :: xc(n) Real (Kind=nag_wp), Intent (Inout) :: fhesd(n), w(lw) Real (Kind=nag_wp), Intent (Out) :: fhesl(lh)
#include nagmk26.h
 void h (Integer *iflag, const Integer *n, const double xc[], double fhesl[], const Integer *lh, double fhesd[], Integer iw[], const Integer *liw, double w[], const Integer *lw)
1:     $\mathbf{iflag}$ – IntegerInput/Output
On entry: is set to a non-negative number.
On exit: if h resets iflag to a negative number, e04hdf will terminate immediately with ifail set to your setting of iflag.
2:     $\mathbf{n}$ – IntegerInput
On entry: the number $n$ of variables.
3:     $\mathbf{xc}\left({\mathbf{n}}\right)$ – Real (Kind=nag_wp) arrayInput
On entry: the point $x$ at which the second derivatives of $F\left(x\right)$ are required.
4:     $\mathbf{fhesl}\left({\mathbf{lh}}\right)$ – Real (Kind=nag_wp) arrayOutput
On exit: 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.)
5:     $\mathbf{lh}$ – IntegerInput
On entry: the length of the array fhesl.
6:     $\mathbf{fhesd}\left({\mathbf{n}}\right)$ – Real (Kind=nag_wp) arrayInput/Output
On entry: contains the value of $\frac{\partial F}{\partial {x}_{\mathit{j}}}$ at the point $x$, for $\mathit{j}=1,2,\dots ,n$. Routines written to take advantage of a similar feature of e04lbf can be tested as they stand by e04hdf.
On exit: 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$.
7:     $\mathbf{iw}\left({\mathbf{liw}}\right)$ – Integer arrayWorkspace
8:     $\mathbf{liw}$ – IntegerInput
9:     $\mathbf{w}\left({\mathbf{lw}}\right)$ – Real (Kind=nag_wp) arrayWorkspace
10:   $\mathbf{lw}$ – IntegerInput
As in funct, these arguments correspond to the arguments iw, liw, w and lw of e04hdf. h must not change the first $5×{\mathbf{n}}$ elements of w.
h must either be a module subprogram USEd by, or declared as EXTERNAL in, the (sub)program from which e04hdf is called. Arguments denoted as Input must not be changed by this procedure.
Note: h should not return floating-point NaN (Not a Number) or infinity values, since these are not handled by e04hdf. If your code inadvertently does return any NaNs or infinities, e04hdf is likely to produce unexpected results.
4:     $\mathbf{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 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.
5:     $\mathbf{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 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}}$.
6:     $\mathbf{hesl}\left({\mathbf{lh}}\right)$ – Real (Kind=nag_wp) arrayOutput
On exit: 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.
7:     $\mathbf{lh}$ – IntegerInput
On entry: the dimension of the array hesl as declared in the (sub)program from which e04hdf is called.
Constraint: ${\mathbf{lh}}\ge \mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{n}}×\left({\mathbf{n}}-1\right)/2\right)$.
8:     $\mathbf{hesd}\left({\mathbf{n}}\right)$ – Real (Kind=nag_wp) arrayOutput
On exit: 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.
9:     $\mathbf{iw}\left({\mathbf{liw}}\right)$ – Integer arrayWorkspace
10:   $\mathbf{liw}$ – IntegerInput
This array is in the argument list so that it can be used by other library routines for passing integer quantities to funct or h. It is not examined or changed by e04hdf. In general you must provide an array iw, but are advised not to use it.
On entry: the dimension of the array iw as declared in the (sub)program from which e04hdf is called.
Constraint: ${\mathbf{liw}}\ge 1$.
11:   $\mathbf{w}\left({\mathbf{lw}}\right)$ – Real (Kind=nag_wp) arrayWorkspace
12:   $\mathbf{lw}$ – IntegerInput
On entry: the dimension of the array w as declared in the (sub)program from which e04hdf is called.
Constraint: ${\mathbf{lw}}\ge 5×{\mathbf{n}}$.
13:   $\mathbf{ifail}$ – IntegerInput/Output
On entry: ifail must be set to $0$, $-1\text{​ or ​}1$. If you are unfamiliar with this argument you should refer to Section 3.4 in How to Use the NAG Library and its Documentation 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 arguments 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).

## 6Error Indicators and Warnings

If on entry ${\mathbf{ifail}}=0$ or $-1$, explanatory error messages are output on the current error message unit (as defined by x04aaf).
Note: e04hdf 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 e04hdf 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}}<\mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{n}}×\left({\mathbf{n}}-1\right)/2\right)$, or ${\mathbf{liw}}<1$, or ${\mathbf{lw}}<5×{\mathbf{n}}$.
${\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$
See Section 3.9 in How to Use the NAG Library and its Documentation for further information.
${\mathbf{ifail}}=-399$
Your licence key may have expired or may not have been installed correctly.
See Section 3.8 in How to Use the NAG Library and its Documentation for further information.
${\mathbf{ifail}}=-999$
Dynamic memory allocation failed.
See Section 3.7 in How to Use the NAG Library and its Documentation for further information.

## 7Accuracy

ifail is set to $2$ if
 $yTHy-p≥h×yTHy+1.0 or ​ zTHz-q≥h×zTHz+1.0$
where $h$ is set equal to $\sqrt{\epsilon }$ ($\epsilon$ being the machine precision as given by x02ajf) and other quantities are as defined in Section 3.

## 8Parallelism and Performance

e04hdf makes calls to BLAS and/or LAPACK routines, which may be threaded within the vendor library used by this implementation. Consult the documentation for the vendor library for further information.
Please consult the X06 Chapter Introduction for information on how to control and interrogate the OpenMP environment used within this routine. Please also consult the Users' Note for your implementation for any additional implementation-specific information.

e04hdf calls h once and funct three times.

## 10Example

Suppose that it is intended to use e04lbf 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 second derivatives calculated by h required. (The call of e04hdf is preceded by a call of e04hcf to check funct which calculates the first derivatives.)

### 10.1Program Text

Program Text (e04hdfe.f90)

None.

### 10.3Program Results

Program Results (e04hdfe.r)

© The Numerical Algorithms Group Ltd, Oxford, UK. 2017