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.
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 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={\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.
None.
If on entry
${\mathbf{IFAIL}}={\mathbf{0}}$ or
${-{\mathbf{1}}}$, explanatory error messages are output on the current error message unit (as defined by
X04AAF).
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.
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
${\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$.
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.)