NAG Library Routine Document

e04ybf (lsq_check_hessian)

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}$ – 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$. (e04hef gives you the option of resetting arguments of lsqfun to cause the minimization process to terminate immediately. e04ybf 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

#include <nagmk26.h> 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}$ – IntegerInput/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 e04ybf, the routine will terminate immediately with ifail set to your setting of iflag.

2:     $\mathbf{m}$ – IntegerInput

On entry: the numbers $m$ of residuals.

3:     $\mathbf{n}$ – IntegerInput

On entry: the numbers $n$ of variables.

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

On entry: the point $x$ 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) arrayOutput

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) arrayOutput

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

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

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

9:     $\mathbf{liw}$ – IntegerInput

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

11:   $\mathbf{lw}$ – IntegerInput

These arguments are present so that lsqfun will be of the form required by e04hef. lsqfun is called with e04ybf's arguments iw, liw, w, lw as these arguments. If the recommendation in e04hef 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 $5\times \mathbf{n}+\mathbf{m}+\mathbf{m}\times \mathbf{n}+\mathbf{n}\times \left(\mathbf{n}-1\right)/2$ (or $6+2\times \mathbf{m}$ if $\mathbf{n}=1$) elements of w.

lsqfun must either be a module subprogram USEd by, or declared as EXTERNAL in, the (sub)program from which e04ybf 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 e04ybf. If your code inadvertently does return any NaNs or infinities, e04ybf is likely to produce unexpected results.

Note:  e04yaf should be used to check the first derivatives calculated by lsqfun before e04ybf is used to check the $b_{jk}$ since e04ybf assumes that the first derivatives are correct.

4:     $\mathbf{lsqhes}$ – Subroutine, supplied by the user.External Procedure

lsqhes must calculate the elements of the symmetric matrix

$$B\left(x\right)=\sum _{i=1}^m{f}_i\left(x\right)G_i\left(x\right)\text{,}$$

at any point $x$, where $G_i\left(x\right)$ is the Hessian matrix of $f_i\left(x\right)$. (As with lsqfun, an argument can be set to cause immediate termination.)

The specification of lsqhes is:

Fortran Interface

Subroutine lsqhes ( iflag, m, n, fvec, xc, b, lb, iw, liw, w, lw) Integer, Intent (In) :: m, n, lb, liw, lw Integer, Intent (Inout) :: iflag, iw(liw) Real (Kind=nag_wp), Intent (In) :: fvec(m), xc(n) Real (Kind=nag_wp), Intent (Inout) :: w(lw) Real (Kind=nag_wp), Intent (Out) :: b(lb)

C Header Interface

#include <nagmk26.h> void  lsqhes (Integer *iflag, const Integer *m, const Integer *n, const double fvec[], const double xc[], double b[], const Integer *lb, Integer iw[], const Integer *liw, double w[], const Integer *lw)

1:     $\mathbf{iflag}$ – IntegerInput/Output

On entry: is set to a non-negative number.

On exit: if lsqhes resets iflag to some negative number, e04ybf will terminate immediately, with ifail set to your setting of iflag.

2:     $\mathbf{m}$ – IntegerInput

On entry: the numbers $m$ of residuals.

3:     $\mathbf{n}$ – IntegerInput

On entry: the numbers $n$ of variables.

4:     $\mathbf{fvec}\left(\mathbf{m}\right)$ – Real (Kind=nag_wp) arrayInput

On entry: the value of the residual $f_{\mathit{i}}$ at the point $x$, for $\mathit{i}=1,2,\dots ,m$, so that the values of the $f_{\mathit{i}}$ can be used in the calculation of the elements of b.

5:     $\mathbf{xc}\left(\mathbf{n}\right)$ – Real (Kind=nag_wp) arrayInput

On entry: the point $x$ at which the elements of b are to be evaluated.

6:     $\mathbf{b}\left(\mathbf{lb}\right)$ – Real (Kind=nag_wp) arrayOutput

On exit: unless iflag is reset to a negative number b must contain the lower triangle of the matrix $B\left(x\right)$, evaluated at the point in xc, stored by rows. (The upper triangle is not needed because the matrix is symmetric.) More precisely, $\mathbf{b}\left(\mathit{j}\left(\mathit{j}-1\right)/2+\mathit{k}\right)$ must contain ${\displaystyle \sum _{\mathit{i}=1}^m}{f}_{\mathit{i}}\frac{{\partial }^2{f}_{\mathit{i}}}{\partial x_{\mathit{j}}\partial x_{\mathit{k}}}$ evaluated at the point $x$, for $\mathit{j}=1,2,\dots ,n$ and $\mathit{k}=1,2,\dots ,\mathit{j}$.

7:     $\mathbf{lb}$ – IntegerInput

On entry: gives the length of the array b.

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

9:     $\mathbf{liw}$ – IntegerInput

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

11:   $\mathbf{lw}$ – IntegerInput

As in lsqfun, these arguments correspond to the arguments iw, liw, w, lw of e04ybf. lsqhes must not change the first $5\times \mathbf{n}+\mathbf{m}\times \mathbf{n}+\mathbf{n}\times \left(\mathbf{n}-1\right)/2$ (or $6+2\times \mathbf{m}$ if $\mathbf{n}=1$) elements of w.

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

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

5:     $\mathbf{x}\left(\mathbf{n}\right)$ – Real (Kind=nag_wp) arrayInput

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 $b_{jk}$ calculated by lsqhes. ‘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 could go undetected. For a similar reason, it is preferable that no two elements of x should have the same value.

6:     $\mathbf{fvec}\left(\mathbf{m}\right)$ – Real (Kind=nag_wp) arrayOutput

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

7:     $\mathbf{fjac}\left(\mathbf{ldfjac},\mathbf{n}\right)$ – Real (Kind=nag_wp) arrayOutput

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

8:     $\mathbf{ldfjac}$ – IntegerInput

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

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

9:     $\mathbf{b}\left(\mathbf{lb}\right)$ – Real (Kind=nag_wp) arrayOutput

On exit: unless you set iflag negative in lsqhes, $\mathbf{b}\left(\mathit{j}\times \left(\mathit{j}-1\right)/2+\mathit{k}\right)$ contains the value of $b_{\mathit{j}\mathit{k}}$ at the point given in x as calculated by lsqhes, for $\mathit{j}=1,2,\dots ,n$ and $\mathit{k}=1,2,\dots ,\mathit{j}$.

10:   $\mathbf{lb}$ – IntegerInput

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

Constraint: $\mathbf{lb}\ge \left(\mathbf{n}+1\right)\times \mathbf{n}/2$.

11:   $\mathbf{iw}\left(\mathbf{liw}\right)$ – Integer arrayWorkspace

12:   $\mathbf{liw}$ – IntegerInput

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

On entry: the first dimension of the array iw as declared in the (sub)program from which e04ybf is called. The actual length of iw as declared in the subroutine from which e04ybf is called.

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

13:   $\mathbf{w}\left(\mathbf{lw}\right)$ – Real (Kind=nag_wp) arrayWorkspace

14:   $\mathbf{lw}$ – IntegerInput

On entry: the first dimension of the array w as declared in the (sub)program from which e04ybf is called. The actual length of w as declared in the subroutine from which e04ybf is called.

Constraints:

• if $\mathbf{n}>1$, $\mathbf{lw}\ge 5\times \mathbf{n}+\mathbf{m}+\mathbf{m}\times \mathbf{n}+\mathbf{n}\times \left(\mathbf{n}-1\right)/2$;
• if $\mathbf{n}=1$, $\mathbf{lw}\ge 6+2\times \mathbf{m}$.

15:   $\mathbf{ifail}$ – IntegerInput/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 3.4 in How to Use the NAG Library and its Documentation 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{lb}=〈\mathit{\text{value}}〉$ and $\left(\mathbf{n}+1\right)\times \mathbf{n}/2=〈\mathit{\text{value}}〉$.
Constraint: $\mathbf{lb}\ge \left(\mathbf{n}+1\right)\times \mathbf{n}/2$.

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

On entry, $\mathbf{n}=1$ and $\mathbf{lw}=〈\mathit{\text{value}}〉$.
Constraint: if $\mathbf{n}=1$ then $\mathbf{lw}\ge 6+2\times \mathbf{m}$; that is, $〈\mathit{\text{value}}〉$.

On entry, $\mathbf{n}>1$ and $\mathbf{lw}=〈\mathit{\text{value}}〉$.
Constraint: if $\mathbf{n}>1$ then $\mathbf{lw}\ge 5\times \mathbf{n}+\mathbf{m}+\mathbf{m}\times \mathbf{n}+\left(\mathbf{n}-1\right)\times \mathbf{n}/2$; that is, $〈\mathit{\text{value}}〉$.

$\mathbf{ifail}=2$

It is very likely that you have made an error in setting up b in lsqhes.

$\mathbf{ifail}<0$

User requested termination by setting iflag negative in lsqfun or lsqhes.

$\mathbf{ifail}=-99$

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

See Section 3.9 in How to Use the NAG Library and its Documentation for further information.

$\mathbf{ifail}=-399$

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

See Section 3.8 in How to Use the NAG Library and its Documentation for further information.

$\mathbf{ifail}=-999$

Dynamic memory allocation failed.

See Section 3.7 in How to Use the NAG Library and its Documentation for further information.

7

Accuracy

8

Parallelism and Performance

9

Further Comments

10

Example

10.1

Program Text

Program Text (e04ybfe.f90)

10.2

Program Data

Program Data (e04ybfe.d)

10.3

Program Results

Program Results (e04ybfe.r)