NAG FL Interface
e04hdf (check_​deriv2)

1 Purpose

2 Specification

3 Description

4 References

5 Arguments

1: $\mathbf{n}$ – Integer Input

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 copy

Subroutine funct ( iflag, 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)

C Header Interface copy

void  funct (Integer *iflag, const Integer *n, const double xc[], double *fc, double gc[], Integer iw[], const Integer *liw, double w[], const Integer *lw)

C++ Header Interface copy

#include <nag.h> extern "C" { 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}$ – Integer Input/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}$ – Integer Input

On entry: the number $n$ of variables.

3: $\mathbf{xc}\left(\mathbf{n}\right)$ – Real (Kind=nag_wp) array Input

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) array Output

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 array Workspace

7: $\mathbf{liw}$ – Integer Input

8: $\mathbf{w}\left(\mathbf{lw}\right)$ – Real (Kind=nag_wp) array Workspace

9: $\mathbf{lw}$ – Integer Input

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\times \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 copy

Subroutine h ( iflag, n, xc, fhesl, lh, fhesd, 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)

C Header Interface copy

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)

C++ Header Interface copy

#include <nag.h> extern "C" { 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}$ – Integer Input/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}$ – Integer Input

On entry: the number $n$ of variables.

3: $\mathbf{xc}\left(\mathbf{n}\right)$ – Real (Kind=nag_wp) array Input

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) array Output

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((\mathit{i}-1)(\mathit{i}-2)/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}$ – Integer Input

On entry: the length of the array fhesl.

6: $\mathbf{fhesd}\left(\mathbf{n}\right)$ – Real (Kind=nag_wp) array Input/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 array Workspace

8: $\mathbf{liw}$ – Integer Input

9: $\mathbf{w}\left(\mathbf{lw}\right)$ – Real (Kind=nag_wp) array Workspace

10: $\mathbf{lw}$ – Integer Input

As in funct, these arguments correspond to the arguments iw, liw, w and lw of e04hdf. h must not change the first $5\times \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) array Input

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$ 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) array Output

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) array Output

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}$ – Integer Input

On entry: the dimension of the array hesl as declared in the (sub)program from which e04hdf is called.

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

8: $\mathbf{hesd}\left(\mathbf{n}\right)$ – Real (Kind=nag_wp) array Output

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 array Workspace

10: $\mathbf{liw}$ – Integer Input

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) array Workspace

12: $\mathbf{lw}$ – Integer Input

On entry: the dimension of the array w as declared in the (sub)program from which e04hdf is called.

Constraint: $\mathbf{lw}\ge 5\times \mathbf{n}$.

13: $\mathbf{ifail}$ – Integer Input/Output

On entry: ifail must be set to $0$, $-1$ or $1$ to set behaviour on detection of an error; these values have no effect when no error is detected.

A value of $0$ causes the printing of an error message and program execution will be halted; otherwise program execution continues. A value of $-1$ means that an error message is printed while a value of $1$ means that it is not.

If halting is not appropriate, the value $-1$ or $1$ is recommended. If message printing is undesirable, then the value $1$ is recommended. Otherwise, the value $-1$ is recommended since useful values can be provided in some output arguments even when $\mathbf{ifail}\ne \mathbf{0}$ on exit. When the value $-\mathbf{1}$ or $\mathbf{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

$\mathbf{ifail}=1$

On entry, $\mathbf{lh}=⟨\mathit{\text{value}}⟩$ and $\mathbf{n}=⟨\mathit{\text{value}}⟩$.
Constraint: $\mathbf{lh}\ge \max (1,\mathbf{n}\times \frac{\mathbf{n}-1}{2})$.

On entry, $\mathbf{liw}=⟨\mathit{\text{value}}⟩$.
Constraint: $\mathbf{liw}\ge 1$.

On entry, $\mathbf{lw}=⟨\mathit{\text{value}}⟩$ and $\mathbf{n}=⟨\mathit{\text{value}}⟩$.
Constraint: $\mathbf{lw}\ge 5\times \mathbf{n}$.

On entry, $\mathbf{n}=⟨\mathit{\text{value}}⟩$.
Constraint: $\mathbf{n}\ge 1$.

$\mathbf{ifail}=2$

Large errors were found in the derivatives of $F$ computed by funct.

$\mathbf{ifail}<0$

User requested termination by setting iflag negative in funct.

$\mathbf{ifail}=-99$

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

See Section 7 in the Introduction to the NAG Library FL Interface for further information.

$\mathbf{ifail}=-399$

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

See Section 8 in the Introduction to the NAG Library FL Interface for further information.

$\mathbf{ifail}=-999$

Dynamic memory allocation failed.

See Section 9 in the Introduction to the NAG Library FL Interface for further information.

7 Accuracy

8 Parallelism and Performance

9 Further Comments

10 Example

10.1 Program Text

10.2 Program Data

10.3 Program Results