NAG CL Interface
e04yac (lsq_​check_​deriv)

1 Purpose

2 Specification

3 Description

4 References

5 Arguments

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:

copy

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}\times \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[(\mathit{i}-1)\times \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.

flag – IntegerInput/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}$.

first – Nag_BooleanInput

On entry: will be set to Nag_TRUE on the first call to lsqfun and Nag_FALSE for all subsequent calls.

nf – IntegerInput

On entry: the number of calls made to lsqfun including the current one.

user – double *

iuser – Integer *

p – Pointer 

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}\times \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)\times \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).

6 Error 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 $=⟨\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.

7 Accuracy

8 Parallelism and Performance

9 Further Comments

10 Example

10.1 Program Text

10.2 Program Data

10.3 Program Results