NAG FL Interface
e04yaf (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}$ – Subroutine, supplied by the user. External Procedure

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 routines mentioned in Section 3 give you the option of resetting an argument to terminate immediately. e04yaf will also terminate immediately, without finishing the checking process, if the argument in question is reset.)

The specification of lsqfun is:

Fortran Interface

Subroutine lsqfun ( iflag, m, n, xc, fvec, fjac, ldfjac, iw, liw, w, lw) Integer, Intent (In) :: m, n, ldfjac, liw, lw Integer, Intent (Inout) :: iflag, iw(liw) Real (Kind=nag_wp), Intent (In) :: xc(n) Real (Kind=nag_wp), Intent (Inout) :: fjac(ldfjac,n), w(lw) Real (Kind=nag_wp), Intent (Out) :: fvec(m)

C Header Interface

void  lsqfun_ (Integer *iflag, const Integer *m, const Integer *n, const double xc[], double fvec[], double fjac[], const Integer *ldfjac, Integer iw[], const Integer *liw, double w[], const Integer *lw)

C++ Header Interface

#include <nag.h> extern "C" { void  lsqfun_ (Integer &iflag, const Integer &m, const Integer &n, const double xc[], double fvec[], double fjac[], const Integer &ldfjac, Integer iw[], const Integer &liw, double w[], const Integer &lw) }

1: $\mathbf{iflag}$ – Integer Input/Output

On entry: to lsqfun, iflag will be set to $2$.

On exit: if you reset iflag to some negative number in lsqfun and return control to e04yaf, the routine will terminate immediately with ifail set to your setting of iflag.

2: $\mathbf{m}$ – Integer Input

On entry: the numbers $m$ of residuals.

3: $\mathbf{n}$ – Integer Input

On entry: the numbers $n$ of variables.

4: $\mathbf{xc}\left(\mathbf{n}\right)$ – Real (Kind=nag_wp) array Input

On entry: $x$, the point at which the values of the $f_i$ and the $\frac{\partial f_i}{\partial x_j}$ are required.

5: $\mathbf{fvec}\left(\mathbf{m}\right)$ – Real (Kind=nag_wp) array Output

On exit: unless iflag is reset to a negative number, $\mathbf{fvec}\left(\mathit{i}\right)$ must contain the value of $f_{\mathit{i}}$ at the point $x$, for $\mathit{i}=1,2,\dots ,m$.

6: $\mathbf{fjac}\left(\mathbf{ldfjac},\mathbf{n}\right)$ – Real (Kind=nag_wp) array Output

On exit: unless iflag is reset to a negative number, $\mathbf{fjac}\left(\mathit{i},\mathit{j}\right)$ must contain the value of $\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$.

7: $\mathbf{ldfjac}$ – Integer Input

On entry: the first dimension of the array fjac as declared in the (sub)program from which e04yaf is called.

8: $\mathbf{iw}\left(\mathbf{liw}\right)$ – Integer array Workspace

9: $\mathbf{liw}$ – Integer Input

10: $\mathbf{w}\left(\mathbf{lw}\right)$ – Real (Kind=nag_wp) array Workspace

11: $\mathbf{lw}$ – Integer Input

These arguments are present so that lsqfun will be of the form required by the minimization routines mentioned in Section 3. lsqfun is called with the same arguments iw, liw, w, lw as in the call to e04yaf. If the recommendation in the minimization routine document is followed, you will have no reason to examine or change the elements of iw or w. In any case, lsqfun must not change the first $3\times \mathbf{n}+\mathbf{m}+\mathbf{m}\times \mathbf{n}$ elements of w.

lsqfun must either be a module subprogram USEd by, or declared as EXTERNAL in, the (sub)program from which e04yaf is called. Arguments denoted as Input must not be changed by this procedure.

Note: lsqfun should not return floating-point NaN (Not a Number) or infinity values, since these are not handled by e04yaf. If your code inadvertently does return any NaNs or infinities, e04yaf is likely to produce unexpected results.

4: $\mathbf{x}\left(\mathbf{n}\right)$ – Real (Kind=nag_wp) array Input

On entry: $\mathbf{x}\left(\mathit{j}\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$ or $1$, 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)$ – Real (Kind=nag_wp) array Output

On exit: unless you set iflag negative in the first call of lsqfun, $\mathbf{fvec}\left(\mathit{i}\right)$ contains the value of $f_{\mathit{i}}$ at the point supplied by you in x, for $\mathit{i}=1,2,\dots ,m$.

6: $\mathbf{fjac}\left(\mathbf{ldfjac},\mathbf{n}\right)$ – Real (Kind=nag_wp) array Output

On exit: unless you set iflag negative in the first call of lsqfun, $\mathbf{fjac}\left(\mathit{i},\mathit{j}\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{ldfjac}$ – Integer Input

On entry: the first dimension of the array fjac as declared in the (sub)program from which e04yaf is called.

Constraint: $\mathbf{ldfjac}\ge \mathbf{m}$.

8: $\mathbf{iw}\left(\mathbf{liw}\right)$ – Integer array Workspace

9: $\mathbf{liw}$ – Integer Input

This array appears in the argument list purely so that, if e04yaf is called by another library routine, the library routine can pass quantities to lsqfun via iw. iw is not examined or changed by e04yaf. In general you must provide an array iw, but are advised not to use it.

On entry: the dimension of the array iw as declared in the (sub)program from which e04yaf is called.

Constraint: $\mathbf{liw}\ge 1$.

10: $\mathbf{w}\left(\mathbf{lw}\right)$ – Real (Kind=nag_wp) array Workspace

11: $\mathbf{lw}$ – Integer Input

On entry: the dimension of the array w as declared in the (sub)program from which e04yaf is called.

Constraint: $\mathbf{lw}\ge 3\times \mathbf{n}+\mathbf{m}+\mathbf{m}\times \mathbf{n}$.

12: $\mathbf{ifail}$ – Integer Input/Output

On entry: ifail must be set to $0$, $-1\text{ or }1$. If you are unfamiliar with this argument you should refer to Section 4 in the Introduction to the NAG Library FL Interface for details.

For environments where it might be inappropriate to halt program execution when an error is detected, the value $-1\text{ or }1$ is recommended. If the output of error messages is undesirable, then the value $1$ is recommended. Otherwise, because for this routine the values of the output arguments may be useful even if $\mathbf{ifail}\ne \mathbf{0}$ on exit, the recommended value is $-1$. When the value $-\mathbf{1}\text{ or }1$ is used it is essential to test the value of ifail on exit.

On exit: $\mathbf{ifail}=\mathbf{0}$ unless the routine detects an error or a warning has been flagged (see Section 6).

6 Error Indicators and Warnings

$\mathbf{ifail}=1$

On entry, $\mathbf{ldfjac}=〈\mathit{\text{value}}〉$ and $\mathbf{m}=〈\mathit{\text{value}}〉$.
Constraint: $\mathbf{ldfjac}\ge \mathbf{m}$.

On entry, $\mathbf{liw}=〈\mathit{\text{value}}〉$.
Constraint: $\mathbf{liw}\ge 1$.

On entry, $\mathbf{lw}=〈\mathit{\text{value}}〉$.
Constraint: $\mathbf{lw}\ge 3\times \mathbf{n}+\mathbf{m}+\mathbf{m}\times \mathbf{n}$; that is, $〈\mathit{\text{value}}〉$.

On entry, $\mathbf{m}=〈\mathit{\text{value}}〉$ and $\mathbf{n}=〈\mathit{\text{value}}〉$.
Constraint: $\mathbf{m}\ge \mathbf{n}$.

On entry, $\mathbf{n}=〈\mathit{\text{value}}〉$.
Constraint: $\mathbf{n}\ge 1$.

$\mathbf{ifail}=2$

It is very likely that you have made an error in forming the derivatives in lsqfun.

$\mathbf{ifail}<0$

User requested termination by setting iflag negative in lsqfun.

$\mathbf{ifail}=-99$

An unexpected error has been triggered by this routine. Please contact NAG.

See Section 7 in the Introduction to the NAG Library FL Interface for further information.

$\mathbf{ifail}=-399$

Your licence key may have expired or may not have been installed correctly.

See Section 8 in the Introduction to the NAG Library FL Interface for further information.

$\mathbf{ifail}=-999$

Dynamic memory allocation failed.

See Section 9 in the Introduction to the NAG Library FL Interface for further information.

7 Accuracy

8 Parallelism and Performance

9 Further Comments

10 Example

10.1 Program Text

10.2 Program Data

10.3 Program Results