NAG Library Routine Document

C05ZAF

+− Contents

1 Purpose

2 Specification

3 Description

4 References

5 Parameters

6 Error Indicators and Warnings

7 Accuracy

8 Further Comments

+− 9 Example

9.1 Program Text

9.2 Program Data

9.3 Program Results

1 Purpose

C05ZAF checks the user-supplied gradients of a set of nonlinear functions in several variables, for consistency with the functions themselves. The routine must be called twice.

2 Specification

SUBROUTINE C05ZAF (

M, N, X, FVEC, FJAC, LDFJAC, XP, FVECP, MODE, ERR)

INTEGER	M, N, LDFJAC, MODE
REAL (KIND=nag_wp)	X(N), FVEC(M), FJAC(LDFJAC,N), XP(), FVECP(M), ERR()

3 Description

C05ZAF is based on the MINPACK routine CHKDER (see Moré et al. (1980)). It checks the

i

th gradient for consistency with the

i

th function by computing a forward-difference approximation along a suitably chosen direction and comparing this approximation with the user-supplied gradient along the same direction. The principal characteristic of C05ZAF is its invariance under changes in scale of the variables or functions.

4 References

Moré J J, Garbow B S and Hillstrom K E (1980) User guide for MINPACK-1 Technical Report ANL-80-74 Argonne National Laboratory

5 Parameters

1: M – INTEGERInput: On entry: the number of functions.
2: N – INTEGERInput: On entry: the number of variables. For use with C05PBF/C05PBA and C05PCF/C05PCA, $M = N$ .
3: X(N) – REAL (KIND=nag_wp) arrayInput: On entry: the components of a point $x$ , at which the consistency check is to be made. (See Section 8.)
4: FVEC(M) – REAL (KIND=nag_wp) arrayInput: On entry: when $MODE = 2$ , FVEC must contain the functions evaluated at $x$ .
5: FJAC(LDFJAC,N) – REAL (KIND=nag_wp) arrayInput: On entry: when $MODE = 2$ , FJAC must contain the user-supplied gradients. (The $i$ th row of FJAC must contain the gradient of the $i$ th function evaluated at the point $x$ .)
6: LDFJAC – INTEGERInput: On entry: the first dimension of the array FJAC as declared in the (sub)program from which C05ZAF is called.
Constraint: $LDFJAC \geq M$ .
7: XP( $*$ ) – REAL (KIND=nag_wp) arrayOutput: Note: the dimension of the array XP must be at least $N$ if $MODE = 1$ , and at least $1$ otherwise.
On exit: when $MODE = 1$ , XP is set to a neighbouring point to X.
8: FVECP(M) – REAL (KIND=nag_wp) arrayInput: On entry: when $MODE = 2$ , FVECP must contain the functions evaluated at XP.
9: MODE – INTEGERInput: On entry: the value $1$ on the first call and the value $2$ on the second call of C05ZAF.
10: ERR( $*$ ) – REAL (KIND=nag_wp) arrayOutput: Note: the dimension of the array ERR must be at least $M$ if $MODE = 2$ , and at least $1$ otherwise.
On exit: when $MODE = 2$ , ERR contains measures of correctness of the respective gradients. If there is no loss of significance (see Section 8), then if $ERR (i)$ is $1.0$ the $i$ th user-supplied gradient is correct, whilst if $ERR (i)$ is $0.0$ the $i$ th gradient is incorrect. For values of $ERR (i)$ between $0.0$ and $1.0$ the categorisation is less certain. In general, a value of $ERR (i) > 0.5$ indicates that the $i$ th gradient is probably correct.

6 Error Indicators and Warnings

If an error is detected in an input parameter C05ZAF will act as if a soft noisy exit has been requested (see Section 3.3.4 in the Essential Introduction).

7 Accuracy

See Section 8.

8 Further Comments

The time required by C05ZAF increases with M and N.

C05ZAF does not perform reliably if cancellation or rounding errors cause a severe loss of significance in the evaluation of a function. Therefore, none of the components of

x

should be unusually small (in particular, zero) or any other value which may cause loss of significance. The relative differences between corresponding elements of FVECP and FVEC should be at least two orders of magnitude greater than the machine precision.