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

Syntax

C#
public static void e04hc( int n, E04..::..E04HC_FUNCT funct, double[] x, out double f, double[] g, out int ifail )

Visual Basic
Public Shared Sub e04hc ( _ n As Integer, _ funct As E04..::..E04HC_FUNCT, _ x As Double(), _ <OutAttribute> ByRef f As Double, _ g As Double(), _ <OutAttribute> ByRef ifail As Integer _ )

Visual C++
public: static void e04hc( int n, E04..::..E04HC_FUNCT^ funct, array<double>^ x, [OutAttribute] double% f, array<double>^ g, [OutAttribute] int% ifail )

F#
static member e04hc : n : int * funct : E04..::..E04HC_FUNCT * x : float[] * f : float byref * g : float[] * ifail : int byref -> unit

Parameters

n: Type: System..::..Int32
On entry: the number $n$ of independent variables in the objective function.

Constraint: $n \geq 1$ .

funct: Type: NagLibrary..::..E04..::..E04HC_FUNCT
funct must evaluate the function and its first derivatives at a given point. (The minimization methods mentioned in [Description] gives you the option of resetting parameters of funct to cause the minimization process to terminate immediately. e04hc will also terminate immediately, without finishing the checking process, if the parameter in question is reset.)
A delegate of type E04HC_FUNCT.

x: Type: array<System..::..Double>[]()[][]
An array of size [n]
On entry: $x [j - 1]$ , for $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 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.

f: Type: System..::..Double%
On exit: unless you set iflag negative in the first call of funct, f contains the value of the objective function $F (x)$ at the point given by you in x.

g: Type: array<System..::..Double>[]()[][]
An array of size [n]
On exit: unless you set iflag negative in the first call of funct, $g [j - 1]$ contains the value of the derivative $\frac{\partial F}{\partial x_{j}}$ at the point given in x, as calculated by funct, for $j = 1, 2, \dots, n$ .

ifail: Type: System..::..Int32%
On exit: $ifail = 0$ unless the method detects an error or a warning has been flagged (see [Error Indicators and Warnings]).

Description

Routines for minimizing a function of several variables may require you to supply a method to evaluate the objective function

F (x_{1}, x_{2}, \dots, x_{n})

and its first derivatives. e04hc is designed to check the derivatives calculated by such user-supplied delegates . As well as the method to be checked ( funct), you must supply a point

x = {(x_{1}, x_{2}, \dots, x_{n})}^{T}

at which the check will be made. Note that e04hc checks methods of the form required for e04kd and e04lb.

e04hc first calls funct to evaluate

F

and its first derivatives

g_{j} = \frac{\partial F}{\partial x_{j}}

, for

j = 1, 2, \dots, n

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^{T} p_{1}

and

g^{T} p_{2}

respectively. The same components are also estimated by finite differences, giving quantities

v_{k} = \frac{F (x + h p_{k}) - F (x)}{h}, k = 1, 2

where

h

is a small positive scalar. If the relative difference between

v_{1}

and

g^{T} p_{1}

or between

v_{2}

and

g^{T} p_{2}

is judged too large, an error indicator is set.

References

None.

Error Indicators and Warnings

Note: e04hc may return useful information for one or more of the following detected errors or warnings.

Errors or warnings detected by the method:

$ifail < 0$: A negative value of ifail indicates an exit from 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 = 1$

On entry,	$n < 1$ ,
or	$liw < 1$ ,
or	$lw < 3 \times n$ .

$ifail = 2$: You should check carefully the derivation and programming of expressions for the derivatives of $F (x)$ , because it is very unlikely that funct is calculating them correctly.

$ifail = -9000$: An error occured, see message report.
$ifail = -8000$: Negative dimension for array $〈value〉$
$ifail = -6000$: Invalid Parameters $〈value〉$

Accuracy

ifail is set to

2

{(v_{k} - g^{T} p_{k})}^{2} \geq h \times ({(g^{T} p_{k})}^{2} + 1)

for

k = 1 ​ or ​ 2

. (See [Description] for definitions of the quantities involved.) The scalar

h

is set equal to

\sqrt{ε}

, where

ε

is the machine precision as given by x02aj.

Parallelism and Performance

None.

Further Comments

funct is called

3

times.

Before using e04hc 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 (x)

calculated by funct at nontrivial points

x

with values calculated independently. (‘Non-trivial’ means that, as when setting

x

before calling e04hc, coordinates such as

0.0

1.0

should be avoided.)

e04hc only checks the derivatives calculated when

iflag = 2

. So, if funct is intended for use in conjunction with a minimization method which may set iflag to

1

, you must check that, for given settings of the

xc [j - 1]

, funct produces the same values for the

gc [j - 1]

when iflag is set to

1

as when iflag is set to

2

Example

Example program (C#): e04hce.cs

Example program results: e04hce.r