NAG Library Routine Document
E04YAF
1 Purpose
E04YAF checks that a usersupplied 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}_{\mathit{i}}\left({x}_{1},{x}_{2},\dots ,{x}_{n}\right)$, for
$\mathit{i}=1,2,\dots ,m$ and
$m\ge n$, may require you to supply a subroutine to evaluate the
${f}_{i}$ and their first derivatives. E04YAF checks the derivatives calculated by such usersupplied 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={\left({x}_{1},{x}_{2},\dots ,{x}_{n}\right)}^{\mathrm{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}\left(x\right)$ and their first derivatives, and uses these to calculate the sum of squares
$F\left(x\right)={\displaystyle \sum _{i=1}^{m}}{\left[{f}_{i}\left(x\right)\right]}^{2}$,
and its first derivatives
${g}_{j}={\left.\frac{\partial F}{\partial {x}_{j}}\right}_{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}^{\mathrm{T}}{p}_{1}$ and
${g}^{\mathrm{T}}{p}_{2}$ respectively. The same components are also estimated by finite differences, giving quantities
where
$h$ is a small positive scalar. If the relative difference between
${v}_{1}$ and
${g}^{\mathrm{T}}{p}_{1}$ or between
${v}_{2}$ and
${g}^{\mathrm{T}}{p}_{2}$ is judged too large, an error indicator is set.
4 References
None.
5 Arguments
 1: $\mathrm{M}$ – INTEGERInput
 2: $\mathrm{N}$ – INTEGERInput

On entry: the number $m$ of residuals, ${f}_{i}\left(x\right)$, and the number $n$ of variables, ${x}_{j}$.
Constraint:
$1\le {\mathbf{N}}\le {\mathbf{M}}$.
 3: $\mathrm{LSQFUN}$ – SUBROUTINE, supplied by the user.External Procedure

LSQFUN must calculate the vector of values
${f}_{i}\left(x\right)$ 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 an argument to terminate immediately. E04YAF will also terminate immediately, without finishing the checking process, if the argument 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: $\mathrm{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: $\mathrm{M}$ – INTEGERInput

On entry: the numbers $m$ of residuals.
 3: $\mathrm{N}$ – INTEGERInput

On entry: the numbers $n$ of variables.
 4: $\mathrm{XC}\left({\mathbf{N}}\right)$ – 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: $\mathrm{FVEC}\left({\mathbf{M}}\right)$ – REAL (KIND=nag_wp) arrayOutput

On exit: unless
IFLAG is reset to a negative number,
${\mathbf{FVEC}}\left(\mathit{i}\right)$ must contain the value of
${f}_{\mathit{i}}$ at the point
$x$, for
$\mathit{i}=1,2,\dots ,m$.
 6: $\mathrm{FJAC}\left({\mathbf{LDFJAC}},{\mathbf{N}}\right)$ – REAL (KIND=nag_wp) arrayOutput

On exit: unless
IFLAG is reset to a negative number,
${\mathbf{FJAC}}\left(\mathit{i},\mathit{j}\right)$ must contain the value of
$\frac{\partial {f}_{\mathit{i}}}{\partial {x}_{\mathit{j}}}$ at the point
$x$, for
$\mathit{i}=1,2,\dots ,m$ and
$\mathit{j}=1,2,\dots ,n$.
 7: $\mathrm{LDFJAC}$ – INTEGERInput

On entry: the first dimension of the array
FJAC as declared in the (sub)program from which E04YAF is called.
 8: $\mathrm{IW}\left({\mathbf{LIW}}\right)$ – INTEGER arrayWorkspace
 9: $\mathrm{LIW}$ – INTEGERInput
 10: $\mathrm{W}\left({\mathbf{LW}}\right)$ – REAL (KIND=nag_wp) arrayWorkspace
 11: $\mathrm{LW}$ – INTEGERInput

These arguments 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 arguments
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 {\mathbf{N}}+{\mathbf{M}}+{\mathbf{M}}\times {\mathbf{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. Arguments denoted as
Input must
not be changed by this procedure.
 4: $\mathrm{X}\left({\mathbf{N}}\right)$ – REAL (KIND=nag_wp) arrayInput

On entry:
${\mathbf{X}}\left(\mathit{j}\right)$, for
$\mathit{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: $\mathrm{FVEC}\left({\mathbf{M}}\right)$ – REAL (KIND=nag_wp) arrayOutput

On exit: unless you set
IFLAG negative in the first call of
LSQFUN,
${\mathbf{FVEC}}\left(\mathit{i}\right)$ contains the value of
${f}_{\mathit{i}}$ at the point supplied by you in
X, for
$\mathit{i}=1,2,\dots ,m$.
 6: $\mathrm{FJAC}\left({\mathbf{LDFJAC}},{\mathbf{N}}\right)$ – REAL (KIND=nag_wp) arrayOutput

On exit: unless you set
IFLAG negative in the first call of
LSQFUN,
${\mathbf{FJAC}}\left(\mathit{i},\mathit{j}\right)$ contains the value of the first derivative
$\frac{\partial {f}_{\mathit{i}}}{\partial {x}_{\mathit{j}}}$ at the point given in
X, as calculated by
LSQFUN, for
$\mathit{i}=1,2,\dots ,m$ and
$\mathit{j}=1,2,\dots ,n$.
 7: $\mathrm{LDFJAC}$ – INTEGERInput

On entry: the first dimension of the array
FJAC as declared in the (sub)program from which E04YAF is called.
Constraint:
${\mathbf{LDFJAC}}\ge {\mathbf{M}}$.
 8: $\mathrm{IW}\left({\mathbf{LIW}}\right)$ – INTEGER arrayCommunication Array

This array appears in the argument 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: $\mathrm{LIW}$ – INTEGERInput

On entry: the dimension of the array
IW as declared in the (sub)program from which E04YAF is called.
Constraint:
${\mathbf{LIW}}\ge 1$.
 10: $\mathrm{W}\left({\mathbf{LW}}\right)$ – REAL (KIND=nag_wp) arrayCommunication Array
 11: $\mathrm{LW}$ – INTEGERInput

On entry: the dimension of the array
W as declared in the (sub)program from which E04YAF is called.
Constraint:
${\mathbf{LW}}\ge 3\times {\mathbf{N}}+{\mathbf{M}}+{\mathbf{M}}\times {\mathbf{N}}$.
 12: $\mathrm{IFAIL}$ – INTEGERInput/Output

On entry:
IFAIL must be set to
$0$,
$1\text{ or}1$. If you are unfamiliar with this argument you should refer to
Section 3.4 in How to Use the NAG Library and its Documentation for details.
For environments where it might be inappropriate to halt program execution when an error is detected, the value
$1\text{ 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 arguments may be useful even if
${\mathbf{IFAIL}}\ne {\mathbf{0}}$ on exit, the recommended value is
$1$.
When the value $\mathbf{1}\text{ or}1$ is used it is essential to test the value of IFAIL on exit.
On exit:
${\mathbf{IFAIL}}={\mathbf{0}}$ unless the routine detects an error or a warning has been flagged (see
Section 6).
6 Error Indicators and Warnings
If on entry
${\mathbf{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:
 ${\mathbf{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.
 ${\mathbf{IFAIL}}=1$

On entry,  ${\mathbf{M}}<{\mathbf{N}}$, 
or  ${\mathbf{N}}<1$, 
or  ${\mathbf{LDFJAC}}<{\mathbf{M}}$, 
or  ${\mathbf{LIW}}<1$, 
or  ${\mathbf{LW}}<3\times {\mathbf{N}}+{\mathbf{M}}+{\mathbf{M}}\times {\mathbf{N}}$. 
 ${\mathbf{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.
 ${\mathbf{IFAIL}}=99$
An unexpected error has been triggered by this routine. Please
contact
NAG.
See
Section 3.9 in How to Use the NAG Library and its Documentation for further information.
 ${\mathbf{IFAIL}}=399$
Your licence key may have expired or may not have been installed correctly.
See
Section 3.8 in How to Use the NAG Library and its Documentation for further information.
 ${\mathbf{IFAIL}}=999$
Dynamic memory allocation failed.
See
Section 3.7 in How to Use the NAG Library and its Documentation for further information.
7 Accuracy
IFAIL is set to
$2$ if
for
$k=1\text{ or}2$. (See
Section 3 for definitions of the quantities involved.) The scalar
$h$ is set equal to
$\sqrt{\epsilon}$, where
$\epsilon $ is the
machine precision as given by
X02AJF.
8 Parallelism and Performance
E04YAF is not threaded in any implementation.
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 usersupplied routine when
${\mathbf{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
${\mathbf{XC}}\left(j\right)$,
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
using the
$15$ sets of data given in the following table.
The following program could be used to check the first derivatives calculated by
LSQFUN. (The tests of whether
${\mathbf{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)