# NAG CL Interfacee04yac (lsq_​check_​deriv)

Note: this function is deprecated. There is no replacement for this function.

Settings help

CL Name Style:

## 1Purpose

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

## 2Specification

 #include
void  e04yac (Integer m, Integer n,
 void (*lsqfun)(Integer m, Integer n, const double x[], double fvec[], double fjac[], Integer tdfjac, Nag_Comm *comm),
const double x[], double fvec[], double fjac[], Integer tdfjac, Nag_Comm *comm, NagError *fail)
The function may be called by the names: e04yac or nag_opt_lsq_check_deriv.

## 3Description

The function e04gbc 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$, requires you to supply a C function to evaluate the ${f}_{i}$ and their first derivatives. e04yac checks the derivatives calculated by such a user-supplied function. As well as the C function 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 is to be made.
e04yac 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)={\sum }_{i=1}^{m}{\left[{f}_{i}\left(x\right)\right]}^{2}$, and its first derivatives ${g}_{\mathit{j}}=\frac{\partial f}{\partial {x}_{\mathit{j}}{\mid }_{x}}$, for $\mathit{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
 $v k = F (x+ hp k ) - F (x) h , k = 1 , 2$
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.

## 5Arguments

1: $\mathbf{m}$Integer Input
2: $\mathbf{n}$Integer Input
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: $\mathbf{lsqfun}$function, supplied by the user External Function
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 function e04gbc gives you the option of resetting an argument, $\mathbf{comm}\mathbf{\to }\mathbf{flag}$, to terminate the minimization process immediately. e04yac will also terminate immediately, without finishing the checking process, if the argument in question is reset to a negative value.)
The specification of lsqfun is:
 void lsqfun (Integer m, Integer n, const double x[], double fvec[], double fjac[], Integer tdfjac, Nag_Comm *comm)
1: $\mathbf{m}$Integer Input
2: $\mathbf{n}$Integer Input
On entry: the numbers $m$ and $n$ of residuals and variables, respectively.
3: $\mathbf{x}\left[{\mathbf{n}}\right]$const double Input
On entry: the point $x$ at which the values of the ${f}_{i}$ and the $\frac{\partial {f}_{i}}{\partial {x}_{j}}$ are required.
4: $\mathbf{fvec}\left[{\mathbf{m}}\right]$double Output
On exit: unless $\mathbf{comm}\mathbf{\to }\mathbf{flag}$ is reset to a negative number, then ${\mathbf{fvec}}\left[\mathit{i}-1\right]$ must contain the value of ${f}_{\mathit{i}}$ at the point $x$, for $\mathit{i}=1,2,\dots ,m$.
5: $\mathbf{fjac}\left[{\mathbf{m}}×{\mathbf{tdfjac}}\right]$double Output
On exit: unless $\mathbf{comm}\mathbf{\to }\mathbf{flag}$ is reset to a negative number, then the value in ${\mathbf{fjac}}\left[\left(\mathit{i}-1\right)×{\mathbf{tdfjac}}+\mathit{j}-1\right]$ must be the first derivative $\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$.
6: $\mathbf{tdfjac}$Integer Input
On entry: the stride separating matrix column elements in the array fjac.
7: $\mathbf{comm}$Nag_Comm *
Pointer to structure of type Nag_Comm; the following members are relevant to lsqfun.
flagIntegerInput/Output
On entry: $\mathbf{comm}\mathbf{\to }\mathbf{flag}$ will be set to 2.
On exit: if lsqfun resets $\mathbf{comm}\mathbf{\to }\mathbf{flag}$ to some negative number then e04yac will terminate immediately with the error indicator NE_USER_STOP. If fail is supplied to e04yac, ${\mathbf{fail}}\mathbf{.}\mathbf{errnum}$ will be set to your setting of $\mathbf{comm}\mathbf{\to }\mathbf{flag}$.
firstNag_BooleanInput
On entry: will be set to Nag_TRUE on the first call to lsqfun and Nag_FALSE for all subsequent calls.
nfIntegerInput
On entry: the number of calls made to lsqfun including the current one.
userdouble *
iuserInteger *
pPointer
The type Pointer will be void * with a C compiler that defines void * and char * otherwise. Before calling e04yac these pointers may be allocated memory and initialized with various quantities for use by lsqfun when called from e04yac.
Note: lsqfun should not return floating-point NaN (Not a Number) or infinity values, since these are not handled by e04yac. If your code inadvertently does return any NaNs or infinities, e04yac is likely to produce unexpected results.
The array x must not be changed within lsqfun.
4: $\mathbf{x}\left[{\mathbf{n}}\right]$const double Input
On entry: ${\mathbf{x}}\left[\mathit{j}-1\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.0$ or $1.0$, 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: $\mathbf{fvec}\left[{\mathbf{m}}\right]$double Output
On exit: unless $\mathbf{comm}\mathbf{\to }\mathbf{flag}$ is set negative in the first call of lsqfun, ${\mathbf{fvec}}\left[\mathit{i}-1\right]$ contains the value of ${f}_{\mathit{i}}$ at the point given in x, for $\mathit{i}=1,2,\dots ,m$.
6: $\mathbf{fjac}\left[{\mathbf{m}}×{\mathbf{tdfjac}}\right]$double Output
On exit: unless $\mathbf{comm}\mathbf{\to }\mathbf{flag}$ is set negative in the first call of lsqfun, ${\mathbf{fjac}}\left[\left(\mathit{i}-1\right)×{\mathbf{tdfjac}}+\mathit{j}-1\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: $\mathbf{tdfjac}$Integer Input
On entry: the stride separating matrix column elements in the array fjac.
Constraint: ${\mathbf{tdfjac}}\ge {\mathbf{n}}$.
8: $\mathbf{comm}$Nag_Comm * Input/Output
Note: comm is a NAG defined type (see Section 3.1.1 in the Introduction to the NAG Library CL Interface).
On entry/exit: structure containing pointers for communication to the user-defined function; see the above description of lsqfun for details. If you do not need to make use of this communication feature the null pointer NAGCOMM_NULL may be used in the call to e04yac; comm will then be declared internally for use in calls to lsqfun.
9: $\mathbf{fail}$NagError * Input/Output
The NAG error argument (see Section 7 in the Introduction to the NAG Library CL Interface).

## 6Error Indicators and Warnings

NE_2_INT_ARG_LT
On entry, ${\mathbf{m}}=⟨\mathit{\text{value}}⟩$ while ${\mathbf{n}}=⟨\mathit{\text{value}}⟩$. These arguments must satisfy ${\mathbf{m}}\ge {\mathbf{n}}$.
On entry, ${\mathbf{tdfjac}}=⟨\mathit{\text{value}}⟩$ while ${\mathbf{n}}=⟨\mathit{\text{value}}⟩$. These arguments must satisfy ${\mathbf{tdfjac}}\ge {\mathbf{n}}$.
NE_ALLOC_FAIL
Dynamic memory allocation failed.
NE_DERIV_ERRORS
Large errors were found in the derivatives of the objective function. 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.
NE_INT_ARG_LT
On entry, ${\mathbf{n}}=⟨\mathit{\text{value}}⟩$.
Constraint: ${\mathbf{n}}\ge 1$.
NE_USER_STOP
User requested termination, user flag value $\text{}=⟨\mathit{\text{value}}⟩$.
This exit occurs if you set $\mathbf{comm}\mathbf{\to }\mathbf{flag}$ to a negative value in lsqfun. If fail is supplied the value of ${\mathbf{fail}}\mathbf{.}\mathbf{errnum}$ will be the same as your setting of $\mathbf{comm}\mathbf{\to }\mathbf{flag}$. The check on lsqfun will not have been completed.

## 7Accuracy

fail.code is set to NE_DERIV_ERRORS if
 $(vk-gTpk) 2 ≥ h× ( (gTpk) 2 +1)$
for $k=1$ 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 X02AJC.

## 8Parallelism and Performance

e04yac is not threaded in any implementation.

e04yac calls lsqfun three times.
Before using e04yac to check the calculation of the first derivatives, you should be confident that lsqfun is calculating the residuals correctly.

## 10Example

Suppose that it is intended to use e04gbc to find least squares estimates of ${x}_{1}$, ${x}_{2}$ and ${x}_{3}$ in the model
 $y = x 1 + t 1 x 2 t 2 + x 3 t 3$
using the 15 sets of data given in the following table:
 $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$
The following program could be used to check the first derivatives calculated by the required function lsqfun. (The tests of whether $\mathbf{comm}\mathbf{\to }\mathbf{flag}\ne 0$ or 1 in lsqfun are present for when lsqfun is called by e04gbc. e04yac will always call lsqfun with $\mathbf{comm}\mathbf{\to }\mathbf{flag}$ set to 2.)

### 10.1Program Text

Program Text (e04yace.c)

### 10.2Program Data

Program Data (e04yace.d)

### 10.3Program Results

Program Results (e04yace.r)