nag_check_deriv (c05zbc) : NAG Library, Mark 23

3 Description

nag_check_deriv (c05zbc) checks the derivatives calculated by user-supplied C functions, e.g., functions of the form required for nag_zero_nonlin_eqns_deriv (c05pbc). As well as the C function to be checked f, you must supply a point

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

at which the check will be made.

nag_check_deriv (c05zbc) first calls f to evaluate both the

f_{i} (x)

and their first derivatives, and uses these to calculate the sum of squares

F (x) = \sum_{i = 1}^{n} {[f_{i} (x)]}^{2},

and its first derivatives

g_{j} = {\frac{\partial F}{\partial x_{j}}|}_{x},   for ​ j = 1, 2, \dots, n .

The components of

g

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.

5 Arguments

1: n – IntegerInput

On entry:

n

, the number of variables,

x_{j}

, for use with nag_zero_nonlin_eqns_deriv (c05pbc).

Constraint:

n > 0

2: x[n] – const doubleInput

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 f. ‘Obvious’ settings, such as 0 or 1, should not be used since, at such particular points, incorrect terms may take correct values (particularly zero), so that errors can go undetected. For a similar reason, it is preferable that no two elements of x should have the same value.

3: fvec[n] – doubleOutput

On exit: unless userflag is set negative when evaluating

f_{i}

at the point given in x,

fvec [i - 1]

contains the value of

f_{i}

at the point given by you in x, for

i = 1, 2, \dots, n

4: fjac[

n \times tdfjac

] – doubleOutput

On exit: unless userflag is set negative when evaluating the Jacobian at the point given in x,

fjac [(i - 1) \times tdfjac + j - 1]

contains the value of the first derivative

\frac{\partial f_{i}}{\partial x_{j}}

at the point given in x, as calculated by f, for

i = 1, 2, \dots, n

and

j = 1, 2, \dots, n

5: tdfjac – IntegerInput

On entry: the stride separating matrix column elements in the array fjac.

Constraint:

tdfjac \geq n

6: f – function, supplied by the userExternal Function

f must calculate the values of the functions at a point x or return the Jacobian at x. nag_zero_nonlin_eqns_deriv (c05pbc) gives you the option of resetting an argument to terminate immediately. nag_check_deriv (c05zbc) will also terminate immediately, without finishing the checking process, if the argument in question is reset.

The specification of f is:

void	f (Integer n, const double x[], double fvec[], double fjac[], Integer tdfjac, Integer *userflag)

1: n – IntegerInput

On entry:

n

, the number of equations.

2: x[n] – const doubleInput

On entry: the components of the point

x

at which the functions or the Jacobian must be evaluated.

3: fvec[n] – doubleOutput

On exit: if

userflag = 1

on entry, fvec must contain the function values

f_{i} (x)

(unless userflag is set to a negative value by f).

userflag = 2

on entry, fvec must not be changed.

4: fjac[ $n \times tdfjac$ ] – doubleOutput

On exit: if

userflag = 2

on entry,

fjac [(i - 1) \times tdfjac + j - 1]

must contain the value of

\frac{\partial f_{i}}{\partial x_{j}}

at the point

x

, for

i = 1, 2, \dots, n

and

j = 1, 2, \dots, n

(unless userflag is set to a negative value by f).

userflag = 1

on entry, fjac must not be changed.

5: tdfjac – IntegerInput

On entry: the stride separating matrix column elements in the array fjac.

6: userflag – Integer *Input/Output

On entry:

userflag = 1

2

$userflag = 1$: fvec is to be updated.
$userflag = 2$: fjac is to be updated.

On exit: in general, userflag should not be reset by f. If, however, you wish to terminate execution (perhaps because some illegal point x has been reached), then userflag should be set to a negative integer. This value will be returned through

fail . errnum

7: fail – NagError *Input/Output

The NAG error argument (see Section 3.6 in the Essential Introduction).

6 Error Indicators and Warnings

NE_2_INT_ARG_LT

On entry,

tdfjac = 〈value〉

while

n = 〈value〉

. These arguments must satisfy

tdfjac \geq n

NE_ALLOC_FAIL

Dynamic memory allocation failed.

NE_DERIV_ERRORS

Large errors were found in the derivatives of the objective function.
You should check carefully the derivation and programming of expressions for the

\frac{\partial f_{i}}{\partial x_{j}}

, because it is very unlikely that f is calculating them correctly.

NE_INT_ARG_LE

On entry, n must not be less or equal to 0:

n = 〈value〉

NE_USER_STOP

User requested termination, user flag value

= 〈value〉

7 Accuracy

fail is set to NE_DERIV_ERRORS if

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

for

k = 1

or 2. (See Section 3 for definitions of the quantities involved.) The scalar

h

is set equal to

\sqrt{ε}

, where

ε

is the machine precision.

NAG Library Function Document

nag_check_deriv (c05zbc)

+− Contents

1 Purpose

2 Specification

3 Description

4 References

5 Arguments

6 Error Indicators and Warnings

7 Accuracy

8 Further Comments

9 Example

9.1 Program Text

9.2 Program Data

9.3 Program Results

NAG Library Function Documentnag_check_deriv (c05zbc)

+− Contents

1 Purpose

2 Specification

3 Description

4 References

5 Arguments

6 Error Indicators and Warnings

7 Accuracy

8 Further Comments

9 Example

9.1 Program Text

9.2 Program Data

9.3 Program Results

NAG Library Function Document

nag_check_deriv (c05zbc)