NAG C Library Function Document

nag_opt_lsq_check_deriv (e04yac)

1

Purpose

2

Specification

3

Description

4

References

5

Arguments

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

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 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}$.

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

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

Program Text (e04yace.c)

10.2

Program Data

Program Data (e04yace.d)

10.3

Program Results

Program Results (e04yace.r)