E04YAF (PDF version)

E04 Chapter Contents

E04 Chapter Introduction

NAG Library Manual

NAG Library Routine Document

E04YAF

▸▿ Contents

1 Purpose

2 Specification

3 Description

4 References

5 Parameters

6 Error Indicators and Warnings

7 Accuracy

8 Parallelism and Performance

9 Further Comments

▸▿ 10 Example

10.1 Program Text

10.2 Program Data

10.3 Program Results

1 Purpose

E04YAF checks that a user-supplied subroutine for evaluating a vector of functions and the matrix of their first derivatives produces derivative values which are consistent with the function values calculated.

2 Specification

SUBROUTINE E04YAF (

M, N, LSQFUN, X, FVEC, FJAC, LDFJAC, IW, LIW, W, LW, IFAIL)

INTEGER	M, N, LDFJAC, IW(LIW), LIW, LW, IFAIL
REAL (KIND=nag_wp)	X(N), FVEC(M), FJAC(LDFJAC,N), W(LW)
EXTERNAL	LSQFUN

3 Description

Routines for minimizing a sum of squares of

m

nonlinear functions (or ‘residuals’),

f_{i} (x_{1}, x_{2}, \dots, x_{n})

, for

i = 1, 2, \dots, m

and

m \geq n

, may require you to supply a subroutine to evaluate the

f_{i}

and their first derivatives. E04YAF checks the derivatives calculated by such user-supplied subroutines, e.g., routines of the form required for E04GBF, E04GDF and E04HEF. As well as the routine to be checked (LSQFUN), you must supply a point

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

at which the check will be made. E04YAF is essentially identical to CHKLSJ in the NPL Algorithms Library.

E04YAF first calls LSQFUN to evaluate the

f_{i} (x)

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

F (x) = \sum_{i = 1}^{m} {[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.

4 References

None.

5 Parameters

1: $M$ – INTEGERInput

2: $N$ – INTEGERInput

On entry: the number

m

of residuals,

f_{i} (x)

, and the number

n

of variables,

x_{j}

.

Constraint:

1 \leq N \leq M

.

3: $LSQFUN$ – SUBROUTINE, supplied by the user.External Procedure

LSQFUN must calculate the vector of values

f_{i} (x)

and their first derivatives

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

at any point

x

. (The minimization routines mentioned in Section 3 give you the option of resetting a parameter to terminate immediately. E04YAF will also terminate immediately, without finishing the checking process, if the parameter in question is reset.)

The specification of LSQFUN is:

SUBROUTINE LSQFUN (

IFLAG, M, N, XC, FVEC, FJAC, LDFJAC, IW, LIW, W, LW)

INTEGER	IFLAG, M, N, LDFJAC, IW(LIW), LIW, LW
REAL (KIND=nag_wp)	XC(N), FVEC(M), FJAC(LDFJAC,N), W(LW)

1: $IFLAG$ – INTEGERInput/Output: On entry: to LSQFUN, IFLAG will be set to $2$ .

On exit: if you reset IFLAG to some negative number in LSQFUN and return control to E04YAF, the routine will terminate immediately with IFAIL set to your setting of IFLAG.
2: $M$ – INTEGERInput: On entry: the numbers $m$ of residuals.
3: $N$ – INTEGERInput: On entry: the numbers $n$ of variables.
4: $XC (N)$ – REAL (KIND=nag_wp) arrayInput: On entry: $x$ , the point at which the values of the $f_{i}$ and the $\frac{\partial f_{i}}{\partial x_{j}}$ are required.
5: $FVEC (M)$ – REAL (KIND=nag_wp) arrayOutput: On exit: unless IFLAG is reset to a negative number, $FVEC (i)$ must contain the value of $f_{i}$ at the point $x$ , for $i = 1, 2, \dots, m$ .
6: $FJAC (LDFJAC, N)$ – REAL (KIND=nag_wp) arrayOutput: On exit: unless IFLAG is reset to a negative number, $FJAC (i, j)$ must contain the value of $\frac{\partial f_{i}}{\partial x_{j}}$ at the point $x$ , for $i = 1, 2, \dots, m$ and $j = 1, 2, \dots, n$ .
7: $LDFJAC$ – INTEGERInput: On entry: the first dimension of the array FJAC as declared in the (sub)program from which E04YAF is called.
8: $IW (LIW)$ – INTEGER arrayWorkspace
9: $LIW$ – INTEGERInput
10: $W (LW)$ – REAL (KIND=nag_wp) arrayWorkspace
11: $LW$ – INTEGERInput: These parameters are present so that LSQFUN will be of the form required by the minimization routines mentioned in Section 3. LSQFUN is called with the same parameters IW, LIW, W, LW as in the call to E04YAF. If the recommendation in the minimization routine document is followed, you will have no reason to examine or change the elements of IW or W. In any case, LSQFUN must not change the first $3 \times N + M + M \times N$ elements of W.

LSQFUN must either be a module subprogram USEd by, or declared as EXTERNAL in, the (sub)program from which E04YAF is called. Parameters denoted as Input must not be changed by this procedure.

4: $X (N)$ – REAL (KIND=nag_wp) arrayInput

On entry:

X (j)

, for

j = 1, 2, \dots, n

, must be set to the coordinates of a suitable point at which to check the derivatives calculated by LSQFUN. ‘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.

5: $FVEC (M)$ – REAL (KIND=nag_wp) arrayOutput

On exit: unless you set IFLAG negative in the first call of LSQFUN,

FVEC (i)

contains the value of

f_{i}

at the point supplied by you in X, for

i = 1, 2, \dots, m

.

6: $FJAC (LDFJAC, N)$ – REAL (KIND=nag_wp) arrayOutput

On exit: unless you set IFLAG negative in the first call of LSQFUN,

FJAC (i, j)

contains the value of the first derivative

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

at the point given in X, as calculated by LSQFUN, for

i = 1, 2, \dots, m

and

j = 1, 2, \dots, n

.

7: $LDFJAC$ – INTEGERInput

On entry: the first dimension of the array FJAC as declared in the (sub)program from which E04YAF is called.

Constraint:

LDFJAC \geq M

.

8: $IW (LIW)$ – INTEGER arrayCommunication Array

This array appears in the parameter list purely so that, if E04YAF is called by another library routine, the library routine can pass quantities to LSQFUN via IW. IW is not examined or changed by E04YAF. In general you must provide an array IW, but are advised not to use it.

9: $LIW$ – INTEGERInput

On entry: the dimension of the array IW as declared in the (sub)program from which E04YAF is called.

Constraint:

LIW \geq 1

.

10: $W (LW)$ – REAL (KIND=nag_wp) arrayCommunication Array

11: $LW$ – INTEGERInput

On entry: the dimension of the array W as declared in the (sub)program from which E04YAF is called.

Constraint:

LW \geq 3 \times N + M + M \times N

.

12: $IFAIL$ – INTEGERInput/Output

On entry: IFAIL must be set to

0

,

- 1 ​ or ​ 1

. If you are unfamiliar with this parameter you should refer to Section 3.3 in the Essential Introduction for details.

For environments where it might be inappropriate to halt program execution when an error is detected, the value

- 1 ​ or ​ 1

is recommended. If the output of error messages is undesirable, then the value

1

is recommended. Otherwise, because for this routine the values of the output parameters may be useful even if

IFAIL \neq 0

on exit, the recommended value is

- 1

. When the value $- 1 or 1$ is used it is essential to test the value of IFAIL on exit.

On exit:

IFAIL = 0

unless the routine detects an error or a warning has been flagged (see Section 6).

6 Error Indicators and Warnings

If on entry

IFAIL = 0

or

- 1

, explanatory error messages are output on the current error message unit (as defined by X04AAF).

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

Errors or warnings detected by the routine:

$IFAIL < 0$: A negative value of IFAIL indicates an exit from E04YAF because you have set IFLAG negative in LSQFUN. The setting of IFAIL will be the same as your setting of IFLAG. The check on LSQFUN will not have been completed.

$IFAIL = 1$

On entry,	$M < N$ ,
or	$N < 1$ ,
or	$LDFJAC < M$ ,
or	$LIW < 1$ ,
or	$LW < 3 \times N + M + M \times N$ .

$IFAIL = 2$: 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 LSQFUN is calculating them correctly.

$IFAIL = - 99$: An unexpected error has been triggered by this routine. Please contact NAG.
See Section 3.8 in the Essential Introduction for further information.

$IFAIL = - 399$: Your licence key may have expired or may not have been installed correctly.
See Section 3.7 in the Essential Introduction for further information.

$IFAIL = - 999$: Dynamic memory allocation failed.
See Section 3.6 in the Essential Introduction for further information.

7 Accuracy

IFAIL is set to

2

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 as given by X02AJF.

8 Parallelism and Performance

Not applicable.

9 Further Comments

E04YAF calls LSQFUN three times.

Before using E04YAF to check the calculation of the first derivatives, you should be confident that LSQFUN is calculating the residuals correctly.

E04YAF only checks the derivatives calculated by a user-supplied routine when

IFLAG = 2

. So, if LSQFUN is intended for use in conjunction with a minimization routine which may set IFLAG to

1

, you must check that, for given settings of the

XC (j)

, LSQFUN produces the same values for the

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

when IFLAG is set to

1

as when IFLAG is set to

2

.

10 Example

Suppose that it is intended to use E04GBF or E04GDF to find least squares estimates of

x_{1}, x_{2}

and

x_{3}

in the model

y = x_{1} + \frac{t_{1}}{x_{2} t_{2} + x_{3} t_{3}}

using the

15

sets of data given in the following table.

\begin{array}{r} y & t_{1} & t_{2} & t_{3} \\ 0.14 & 1.0 & 15.0 & 1.0 \\ 0.18 & 2.0 & 14.0 & 2.0 \\ 0.22 & 3.0 & 13.0 & 3.0 \\ 0.25 & 4.0 & 12.0 & 4.0 \\ 0.29 & 5.0 & 11.0 & 5.0 \\ 0.32 & 6.0 & 10.0 & 6.0 \\ 0.35 & 7.0 & 9.0 & 7.0 \\ 0.39 & 8.0 & 8.0 & 8.0 \\ 0.37 & 9.0 & 7.0 & 7.0 \\ 0.58 & 10.0 & 6.0 & 6.0 \\ 0.73 & 11.0 & 5.0 & 5.0 \\ 0.96 & 12.0 & 4.0 & 4.0 \\ 1.34 & 13.0 & 3.0 & 3.0 \\ 2.10 & 14.0 & 2.0 & 2.0 \\ 4.39 & 15.0 & 1.0 & 1.0 \end{array}

The following program could be used to check the first derivatives calculated by LSQFUN. (The tests of whether

IFLAG = 0

or

1

in LSQFUN are present ready for when LSQFUN is called by E04GBF or E04GDF. E04YAF will always call LSQFUN with IFLAG set to 2.)

10.1 Program Text

Program Text (e04yafe.f90)

10.2 Program Data

Program Data (e04yafe.d)

10.3 Program Results

Program Results (e04yafe.r)

E04YAF (PDF version)

E04 Chapter Contents

E04 Chapter Introduction

NAG Library Manual

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