NAG Library Routine Document

e04hcf (check_deriv)

1

Purpose

2

Specification

3

Description

4

References

5

Arguments

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. (The minimization routines mentioned in Section 3 gives you the option of resetting arguments of funct to cause the minimization process to terminate immediately. e04hcf 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 ( 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

#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: 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:     $\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 $F$ and its 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 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 the minimization routines mentioned in Section 3. funct is called with e04hcf's arguments iw, liw, w, lw as these arguments. 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\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 e04hcf 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 e04hcf. If your code inadvertently does return any NaNs or infinities, e04hcf is likely to produce unexpected results.

3:     $\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 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:     $\mathbf{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:     $\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 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:     $\mathbf{iw}\left(\mathbf{liw}\right)$ – Integer arrayWorkspace

7:     $\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. It is not examined or changed by e04hcf. Generally, you must provide an array iw but are advised not to use it.

Constraint: $\mathbf{liw}\ge 1$.

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

9:     $\mathbf{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\times \mathbf{n}$.

10:   $\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).

6

Error Indicators and Warnings

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

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

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.

7

Accuracy

8

Parallelism and Performance

9

Further Comments

10

Example

10.1

Program Text

Program Text (e04hcfe.f90)

10.2

Program Data

10.3

Program Results

Program Results (e04hcfe.r)