C05 Chapter Contents
C05 Chapter Introduction
NAG Library Manual

NAG Library Routine DocumentC05ZAF

Note:  before using this routine, please read the Users' Note for your implementation to check the interpretation of bold italicised terms and other implementation-dependent details.

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, ${\mathbf{M}}={\mathbf{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 ${\mathbf{MODE}}=2$, FVEC must contain the functions evaluated at $x$.
5:     FJAC(LDFJAC,N) – REAL (KIND=nag_wp) arrayInput
On entry: when ${\mathbf{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: ${\mathbf{LDFJAC}}\ge {\mathbf{M}}$.
7:     XP($*$) – REAL (KIND=nag_wp) arrayOutput
Note: the dimension of the array XP must be at least ${\mathbf{N}}$ if ${\mathbf{MODE}}=1$, and at least $1$ otherwise.
On exit: when ${\mathbf{MODE}}=1$, XP is set to a neighbouring point to X.
8:     FVECP(M) – REAL (KIND=nag_wp) arrayInput
On entry: when ${\mathbf{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 ${\mathbf{M}}$ if ${\mathbf{MODE}}=2$, and at least $1$ otherwise.
On exit: when ${\mathbf{MODE}}=2$, ERR contains measures of correctness of the respective gradients. If there is no loss of significance (see Section 8), then if ${\mathbf{ERR}}\left(i\right)$ is $1.0$ the $i$th user-supplied gradient is correct, whilst if ${\mathbf{ERR}}\left(i\right)$ is $0.0$ the $i$th gradient is incorrect. For values of ${\mathbf{ERR}}\left(i\right)$ between $0.0$ and $1.0$ the categorisation is less certain. In general, a value of ${\mathbf{ERR}}\left(i\right)>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.

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.

9  Example

This example checks the Jacobian matrix for a problem with $15$ functions of $3$ variables (sometimes referred to as the Bard problem).

9.1  Program Text

Program Text (c05zafe.f90)

None.

9.3  Program Results

Program Results (c05zafe.r)