# NAG C Library Function Document

## 1Purpose

nag_opt_lsq_check_deriv (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 #include
void  nag_opt_lsq_check_deriv (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)

## 3Description

The function nag_opt_lsq_deriv (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. nag_opt_lsq_check_deriv (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.
nag_opt_lsq_check_deriv (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}$IntegerInput
2:    $\mathbf{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:    $\mathbf{lsqfun}$function, supplied by the userExternal 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 nag_opt_lsq_deriv (e04gbc) gives you the option of resetting an argument, $\mathbf{comm}\mathbf{\to }\mathbf{flag}$, to terminate the minimization process immediately. nag_opt_lsq_check_deriv (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}$IntegerInput
2:    $\mathbf{n}$IntegerInput
On entry: the numbers $m$ and $n$ of residuals and variables, respectively.
3:    $\mathbf{x}\left[{\mathbf{n}}\right]$const doubleInput
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]$doubleOutput
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]$doubleOutput
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}$IntegerInput
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 nag_opt_lsq_check_deriv (e04yac) will terminate immediately with the error indicator NE_USER_STOP. If fail is supplied to nag_opt_lsq_check_deriv (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 nag_opt_lsq_check_deriv (e04yac) these pointers may be allocated memory and initialized with various quantities for use by lsqfun when called from nag_opt_lsq_check_deriv (e04yac).
Note: lsqfun should not return floating-point NaN (Not a Number) or infinity values, since these are not handled by nag_opt_lsq_check_deriv (e04yac). If your code inadvertently does return any NaNs or infinities, nag_opt_lsq_check_deriv (e04yac) is likely to produce unexpected results.
The array x must not be changed within lsqfun.
4:    $\mathbf{x}\left[{\mathbf{n}}\right]$const doubleInput
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]$doubleOutput
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]$doubleOutput
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}$IntegerInput
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.3.1.1 in How to Use the NAG Library and its Documentation).
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 nag_opt_lsq_check_deriv (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 3.7 in How to Use the NAG Library and its Documentation).

## 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 - gT pk 2 ≥ h× gT pk 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 nag_machine_precision (X02AJC).

## 8Parallelism and Performance

nag_opt_lsq_check_deriv (e04yac) is not threaded in any implementation.

nag_opt_lsq_check_deriv (e04yac) calls lsqfun three times.
Before using nag_opt_lsq_check_deriv (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 nag_opt_lsq_deriv (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 nag_opt_lsq_deriv (e04gbc). nag_opt_lsq_check_deriv (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)