C05ZAF (PDF version)
C05 Chapter Contents
C05 Chapter Introduction
NAG Library Manual

NAG Library Routine Document

C05ZAF

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.

+ Contents

    1  Purpose
    7  Accuracy

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 ith gradient for consistency with the ith 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 ith row of FJAC must contain the gradient of the ith 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: LDFJACM .
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 ERRi  is 1.0 the ith user-supplied gradient is correct, whilst if ERRi  is 0.0 the ith gradient is incorrect. For values of ERRi  between 0.0 and 1.0 the categorisation is less certain. In general, a value of ERRi>0.5  indicates that the ith 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.

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)

9.2  Program Data

None.

9.3  Program Results

Program Results (c05zafe.r)


C05ZAF (PDF version)
C05 Chapter Contents
C05 Chapter Introduction
NAG Library Manual

© The Numerical Algorithms Group Ltd, Oxford, UK. 2012