NAG FL Interface
e04lbf (bounds_​mod_​deriv2_​comp)

1 Purpose

2 Specification

3 Description

4 References

5 Arguments

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

On entry: the number $n$ of independent variables.

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

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

funct must evaluate the function $F\left(x\right)$ and its first derivatives $\frac{\partial F}{\partial x_j}$ at any point $x$.

The specification of funct is:

Fortran Interface copy

Subroutine funct ( iflag, n, xc, fc, gc, iw, liw, w, lw) Integer, Intent (In) :: n, liw, lw Integer, Intent (Inout) :: iflag, iw(liw) Real (Kind=nag_wp), Intent (In) :: xc(n) Real (Kind=nag_wp), Intent (Inout) :: w(lw) Real (Kind=nag_wp), Intent (Out) :: fc, gc(n)

C Header Interface copy

void  funct (Integer *iflag, const Integer *n, const double xc[], double *fc, double gc[], Integer iw[], const Integer *liw, double w[], const Integer *lw)

C++ Header Interface copy

#include <nag.h> extern "C" { void  funct (Integer &iflag, const Integer &n, const double xc[], double &fc, double gc[], Integer iw[], const Integer &liw, double w[], const Integer &lw) }

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

On entry: will have been set to $2$.

On exit: if it is not possible to evaluate $F\left(x\right)$ or its first derivatives at the point $x$ given in xc (or if it is wished to stop the calculation for any other reason) you should reset iflag to some negative number and return control to e04lbf. e04lbf will then terminate immediately with ifail set to your setting of iflag.

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

On entry: the number $n$ of variables.

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

On entry: the point $x$ at which $F$ and the $\frac{\partial F}{\partial x_j}$ are required.

4: $\mathbf{fc}$ – Real (Kind=nag_wp) Output

On exit: funct must set fc to the value of the objective function $F$ at the current point $x$.

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

On exit: funct must set $\mathbf{gc}\left(j\right)$ to the value of the first derivative $\frac{\partial F}{\partial x_{\mathit{j}}}$ at the point $x$, for $\mathit{j}=1,2,\dots ,n$.

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

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

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

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

funct is called with the same arguments iw, liw, w and lw as for e04lbf. They are present so that, when other library routines require the solution of a minimization subproblem, constants needed for the function evaluation can be passed through iw and w. Similarly, you could use elements $3,4,\dots ,\mathbf{liw}$ of iw and elements from $\max (8,7\times \mathbf{n}+\mathbf{n}\times (\mathbf{n}-1)/2)+1$ onwards of w for passing quantities to funct from the subroutine which calls e04lbf. However, because of the danger of mistakes in partitioning, it is recommended that you should pass information to funct via COMMON global variables and not use iw or w at all. In any case funct must not change the first $2$ elements of iw or the first $\max (8,7\times \mathbf{n}+\mathbf{n}\times (\mathbf{n}-1)/2)$ elements of w.

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

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

funct should be tested separately before being used in conjunction with e04lbf.

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

h must calculate the second derivatives of $F$ at any point $x$. (As with funct, there is the option of causing e04lbf to terminate immediately.)

The specification of h is:

Fortran Interface copy

Subroutine h ( iflag, n, xc, fhesl, lh, fhesd, iw, liw, w, lw) Integer, Intent (In) :: n, lh, liw, lw Integer, Intent (Inout) :: iflag, iw(liw) Real (Kind=nag_wp), Intent (In) :: xc(n) Real (Kind=nag_wp), Intent (Inout) :: fhesd(n), w(lw) Real (Kind=nag_wp), Intent (Out) :: fhesl(lh)

C Header Interface copy

void  h (Integer *iflag, const Integer *n, const double xc[], double fhesl[], const Integer *lh, double fhesd[], Integer iw[], const Integer *liw, double w[], const Integer *lw)

C++ Header Interface copy

#include <nag.h> extern "C" { void  h (Integer &iflag, const Integer &n, const double xc[], double fhesl[], const Integer &lh, double fhesd[], Integer iw[], const Integer &liw, double w[], const Integer &lw) }

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

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

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

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

On entry: the number $n$ of variables.

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

On entry: the point $x$ at which the second derivatives of $F$ are required.

4: $\mathbf{fhesl}\left(\mathbf{lh}\right)$ – Real (Kind=nag_wp) array Output

On exit: h must place the strict lower triangle of the second derivative matrix of $F$ (evaluated at the point $x$) in fhesl, stored by rows, i.e., set $\mathbf{fhesl}\left((\mathit{i}-1)(\mathit{i}-2)/2+\mathit{j}\right)={\frac{{\partial }^{2}F}{\partial x_{\mathit{i}}\partial x_{\mathit{j}}}|}_{\mathbf{xc}}$, for $\mathit{i}=2,3,\dots ,n$ and $\mathit{j}=1,2,\dots ,i-1$. (The upper triangle is not required because the matrix is symmetric.)

5: $\mathbf{lh}$ – Integer Input

On entry: the length of the array fhesl.

6: $\mathbf{fhesd}\left(\mathbf{n}\right)$ – Real (Kind=nag_wp) array Input/Output

On entry: the value of $\frac{\partial F}{\partial x_{\mathit{j}}}$ at the point $x$, for $\mathit{j}=1,2,\dots ,n$.

These values may be useful in the evaluation of the second derivatives.

On exit: h must place the diagonal elements of the second derivative matrix of $F$ (evaluated at the point $x$) in fhesd, i.e., set $\mathbf{fhesd}\left(j\right)={\frac{{\partial }^{2}F}{\partial x_j^2}|}_{\mathbf{xc}}$, $j=1,2,\dots ,n$.

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

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

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

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

As in funct, these arguments correspond to the arguments iw, liw, w, lw of e04lbf. h must not change the first two elements of iw or the first $\max (8,7\times \mathbf{n}+\mathbf{n}\times (\mathbf{n}-1)/2)$ elements of w. Again, it is recommended that you should pass quantities to h via COMMON global variables and not use iw or w at all.

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

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

h should be tested separately before being used in conjunction with e04lbf.

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

If $\mathbf{iprint}\ge 0$, you must supply monit which is suitable for monitoring the minimization process. monit must not change the values of any of its arguments.

If $\mathbf{iprint}<0$, a monit with the correct argument list should still be supplied, although it will not be called.

The specification of monit is:

Fortran Interface copy

Subroutine monit ( n, xc, fc, gc, istate, gpjnrm, cond, posdef, niter, nf, iw, liw, w, lw) Integer, Intent (In) :: n, istate(n), niter, nf, liw, lw Integer, Intent (Inout) :: iw(liw) Real (Kind=nag_wp), Intent (In) :: xc(n), fc, gc(n), gpjnrm, cond Real (Kind=nag_wp), Intent (Inout) :: w(lw) Logical, Intent (In) :: posdef

C Header Interface copy

void  monit (const Integer *n, const double xc[], const double *fc, const double gc[], const Integer istate[], const double *gpjnrm, const double *cond, const logical *posdef, const Integer *niter, const Integer *nf, Integer iw[], const Integer *liw, double w[], const Integer *lw)

C++ Header Interface copy

#include <nag.h> extern "C" { void  monit (const Integer &n, const double xc[], const double &fc, const double gc[], const Integer istate[], const double &gpjnrm, const double &cond, const logical &posdef, const Integer &niter, const Integer &nf, Integer iw[], const Integer &liw, double w[], const Integer &lw) }

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

On entry: the number $n$ of variables.

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

On entry: the coordinates of the current point $x$.

3: $\mathbf{fc}$ – Real (Kind=nag_wp) Input

On entry: the value of $F\left(x\right)$ at the current point $x$.

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

On entry: the value of $\frac{\partial F}{\partial x_{\mathit{j}}}$ at the current point $x$, for $\mathit{j}=1,2,\dots ,n$.

5: $\mathbf{istate}\left(\mathbf{n}\right)$ – Integer array Input

On entry: information about which variables are currently fixed on their bounds and which are free.

If $\mathbf{istate}\left(j\right)$ is negative, $x_j$ is currently:

• –fixed on its upper bound if $\mathbf{istate}\left(j\right)=\mathrm{-1}$;
• –fixed on its lower bound if $\mathbf{istate}\left(j\right)=\mathrm{-2}$;
• –effectively a constant (i.e., $l_j=u_j$) if $\mathbf{istate}\left(j\right)=\mathrm{-3}$.

If istate is positive, its value gives the position of $x_j$ in the sequence of free variables.

6: $\mathbf{gpjnrm}$ – Real (Kind=nag_wp) Input

On entry: the Euclidean norm of the projected gradient vector $g_z$.

7: $\mathbf{cond}$ – Real (Kind=nag_wp) Input

On entry: the ratio of the largest to the smallest elements of the diagonal factor $D$ of the projected Hessian matrix (see specification of h). This quantity is usually a good estimate of the condition number of the projected Hessian matrix. (If no variables are currently free, cond is set to zero.)

8: $\mathbf{posdef}$ – Logical Input

On entry: is set .TRUE. or .FALSE. according to whether the second derivative matrix for the current subspace, $H$, is positive definite or not.

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

On entry: the number of iterations (as outlined in Section 3) which have been performed by e04lbf so far.

10: $\mathbf{nf}$ – Integer Input

On entry: the number of times that funct has been called so far. Thus nf is the number of function and gradient evaluations made so far.

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

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

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

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

As in funct, and h, these arguments correspond to the arguments iw, liw, w, lw of e04lbf. They are included in monit's argument list primarily for when e04lbf is called by other library routines.

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

Note:  you should normally print out fc, gpjnrm and cond so as to be able to compare the quantities mentioned in Section 7. It is normally helpful to examine xc, posdef and nf as well.

5: $\mathbf{iprint}$ – Integer Input

On entry: the frequency with which monit is to be called.

$\mathbf{iprint}>0$

monit is called once every iprint iterations and just before exit from e04lbf.

$\mathbf{iprint}=0$

monit is just called at the final point.

$\mathbf{iprint}<0$

monit is not called at all.

iprint should normally be set to a small positive number.

Suggested value: $\mathbf{iprint}=1$.

6: $\mathbf{maxcal}$ – Integer Input

On entry: the maximum permitted number of evaluations of $F\left(x\right)$, i.e., the maximum permitted number of calls of funct.

Suggested value: $\mathbf{maxcal}=50\times \mathbf{n}$.

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

7: $\mathbf{eta}$ – Real (Kind=nag_wp) Input

On entry: every iteration of e04lbf involves a linear minimization (i.e., minimization of $F(x+\alpha p)$ with respect to $\alpha$). eta specifies how accurately these linear minimizations are to be performed. The minimum with respect to $\alpha$ will be located more accurately for small values of eta (say, $0.01$) than for large values (say, $0.9$).

Although accurate linear minimizations will generally reduce the number of iterations of e04lbf, this usually results in an increase in the number of function and gradient evaluations required for each iteration. On balance, it is usually more efficient to perform a low accuracy linear minimization.

Suggested value: $\mathbf{eta}=0.9$ is usually a good choice although a smaller value may be warranted if the matrix of second derivatives is expensive to compute compared with the function and first derivatives.

If $\mathbf{n}=1$, eta should be set to $0.0$ (also when the problem is effectively one-dimensional even though $n>1$; i.e., if for all except one of the variables the lower and upper bounds are equal).

Constraint: $0.0\le \mathbf{eta}<1.0$.

8: $\mathbf{xtol}$ – Real (Kind=nag_wp) Input

On entry: the accuracy in $x$ to which the solution is required.

If $x_{\mathrm{true}}$ is the true value of $x$ at the minimum, then $x_{\mathrm{sol}}$, the estimated position before a normal exit, is such that $\Vert x_{\mathrm{sol}}-x_{\mathrm{true}}\Vert <\mathbf{xtol}\times (1.0+\Vert x_{\mathrm{true}}\Vert )$, where $\Vert y\Vert =\sqrt{{\displaystyle \sum _{j=1}^n}{y}_j^2}$. For example, if the elements of $x_{\mathrm{sol}}$ are not much larger than $1.0$ in modulus, and if xtol is set to ${10}^{\mathrm{-5}}$, then $x_{\mathrm{sol}}$ is usually accurate to about five decimal places. (For further details see Section 7.)

If the problem is scaled roughly as described in Section 9 and $\epsilon$ is the machine precision, then $\sqrt{\epsilon }$ is probably the smallest reasonable choice for xtol. (This is because, normally, to machine accuracy, $F(x+\sqrt{\epsilon },e_j)=F\left(x\right)$ where $e_j$ is any column of the identity matrix.)

If you set xtol to $0.0$ (or any positive value less than $\epsilon$), e04lbf will use $10.0\times \sqrt{\epsilon }$ instead of xtol.

Suggested value: $\mathbf{xtol}=0.0$.

Constraint: $\mathbf{xtol}\ge 0.0$.

9: $\mathbf{stepmx}$ – Real (Kind=nag_wp) Input

On entry: an estimate of the Euclidean distance between the solution and the starting point supplied by you. (For maximum efficiency a slight overestimate is preferable.)

e04lbf will ensure that, for each iteration,

$$\sqrt{\sum _{j=1}^n{[x_j^{\left(k\right)}-x_j^{(k-1)}]}^2}\le \mathbf{stepmx}$$

where $k$ is the iteration number. Thus, if the problem has more than one solution, e04lbf is most likely to find the one nearest to the starting point. On difficult problems, a realistic choice can prevent the sequence of $x^{\left(k\right)}$ entering a region where the problem is ill-behaved and can also help to avoid possible overflow in the evaluation of $F\left(x\right)$. However, an underestimate of stepmx can lead to inefficiency.

Suggested value: $\mathbf{stepmx}=100000.0$.

Constraint: $\mathbf{stepmx}\ge \mathbf{xtol}$.

10: $\mathbf{ibound}$ – Integer Input

On entry: specifies whether the problem is unconstrained or bounded. If there are bounds on the variables, ibound can be used to indicate whether the facility for dealing with bounds of special forms is to be used. It must be set to one of the following values:

$\mathbf{ibound}=0$

If the variables are bounded and you are supplying all the $l_j$ and $u_j$ individually.

$\mathbf{ibound}=1$

If the problem is unconstrained.

$\mathbf{ibound}=2$

If the variables are bounded, but all the bounds are of the form $0\le x_j$.

$\mathbf{ibound}=3$

If all the variables are bounded, and $l_1=l_2=\cdots =l_n$ and $u_1=u_2=\cdots =u_n$.

$\mathbf{ibound}=4$

If the problem is unconstrained. (The $\mathbf{ibound}=4$ option is provided purely for consistency with other routines. In e04lbf it produces the same effect as $\mathbf{ibound}=1$.)

Constraint: $0\le \mathbf{ibound}\le 4$.

11: $\mathbf{bl}\left(\mathbf{n}\right)$ – Real (Kind=nag_wp) array Input/Output

On entry: the fixed lower bounds $l_j$.

If ibound is set to $0$, you must set $\mathbf{bl}\left(\mathit{j}\right)$ to $l_{\mathit{j}}$, for $\mathit{j}=1,2,\dots ,n$. (If a lower bound is not specified for any $x_j$, the corresponding $\mathbf{bl}\left(j\right)$ should be set to a large negative number, e.g., $-{10}^6$.)

If ibound is set to $3$, you must set $\mathbf{bl}\left(1\right)$ to $l_1$; e04lbf will then set the remaining elements of bl equal to $\mathbf{bl}\left(1\right)$.

If ibound is set to $1$, $2$ or $4$, bl will be initialized by e04lbf.

On exit: the lower bounds actually used by e04lbf, e.g., if $\mathbf{ibound}=2$, $\mathbf{bl}\left(1\right)=\mathbf{bl}\left(2\right)=\cdots =\mathbf{bl}\left(n\right)=0.0$.

12: $\mathbf{bu}\left(\mathbf{n}\right)$ – Real (Kind=nag_wp) array Input/Output

On entry: the fixed upper bounds $u_j$.

If ibound is set to $0$, you must set $\mathbf{bu}\left(\mathit{j}\right)$ to $u_{\mathit{j}}$, for $\mathit{j}=1,2,\dots ,n$. (If an upper bound is not specified for any variable, the corresponding $\mathbf{bu}\left(j\right)$ should be set to a large positive number, e.g., ${10}^6$.)

If ibound is set to $3$, you must set $\mathbf{bu}\left(1\right)$ to $u_1$; e04lbf will then set the remaining elements of bu equal to $\mathbf{bu}\left(1\right)$.

If ibound is set to $1$, $2$ or $4$, bu will then be initialized by e04lbf.

On exit: the upper bounds actually used by e04lbf, e.g., if $\mathbf{ibound}=2$, $\mathbf{bu}\left(1\right)=\mathbf{bu}\left(2\right)=\cdots =\mathbf{bu}\left(\mathbf{n}\right)={10}^6$.

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

On entry: $\mathbf{x}\left(\mathit{j}\right)$ must be set to a guess at the $\mathit{j}$th component of the position of the minimum, for $\mathit{j}=1,2,\dots ,n$.

On exit: the final point $x^{\left(k\right)}$. Thus, if $\mathbf{ifail}=\mathbf{0}$ on exit, $\mathbf{x}\left(j\right)$ is the $j$th component of the estimated position of the minimum.

14: $\mathbf{hesl}\left(\mathbf{lh}\right)$ – Real (Kind=nag_wp) array Output

On exit: during the determination of a direction $p_z$ (see Section 3), $H+E$ is decomposed into the product $LD{L}^{\mathrm{T}}$, where $L$ is a unit lower triangular matrix and $D$ is a diagonal matrix. (The matrices $H$, $E$, $L$ and $D$ are all of dimension $n_z$, where $n_z$ is the number of variables free from their bounds. $H$ consists of those rows and columns of the full estimated second derivative matrix which relate to free variables. $E$ is chosen so that $H+E$ is positive definite.)

hesl and hesd are used to store the factors $L$ and $D$. The elements of the strict lower triangle of $L$ are stored row by row in the first $n_z(n_z-1)/2$ positions of hesl. The diagonal elements of $D$ are stored in the first $n_z$ positions of hesd. In the last factorization before a normal exit, the matrix $E$ will be zero, so that hesl and hesd will contain, on exit, the factors of the final estimated second derivative matrix $H$. The elements of hesd are useful for deciding whether to accept the results produced by e04lbf (see Section 7).

15: $\mathbf{lh}$ – Integer Input

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

Constraint: $\mathbf{lh}\ge \max (\mathbf{n}\times (\mathbf{n}-1)/2,1)$.

16: $\mathbf{hesd}\left(\mathbf{n}\right)$ – Real (Kind=nag_wp) array Output

On exit: during the determination of a direction $p_z$ (see Section 3), $H+E$ is decomposed into the product $LD{L}^{\mathrm{T}}$, where $L$ is a unit lower triangular matrix and $D$ is a diagonal matrix. (The matrices $H$, $E$, $L$ and $D$ are all of dimension $n_z$, where $n_z$ is the number of variables free from their bounds. $H$ consists of those rows and columns of the full second derivative matrix which relate to free variables. $E$ is chosen so that $H+E$ is positive definite.)

hesl and hesd are used to store the factors $L$ and $D$. The elements of the strict lower triangle of $L$ are stored row by row in the first $n_z(n_z-1)/2$ positions of hesl. The diagonal elements of $D$ are stored in the first $n_z$ positions of hesd.

In the last factorization before a normal exit, the matrix $E$ will be zero, so that hesl and hesd will contain, on exit, the factors of the final second derivative matrix $H$. The elements of hesd are useful for deciding whether to accept the result produced by e04lbf (see Section 7).

17: $\mathbf{istate}\left(\mathbf{n}\right)$ – Integer array Output

On exit: information about which variables are currently on their bounds and which are free. If $\mathbf{istate}\left(j\right)$ is:

• –equal to $\mathrm{-1}$, $x_j$ is fixed on its upper bound;
• –equal to $\mathrm{-2}$, $x_j$ is fixed on its lower bound;
• –equal to $\mathrm{-3}$, $x_j$ is effectively a constant (i.e., $l_j=u_j$);
• –positive, $\mathbf{istate}\left(j\right)$ gives the position of $x_j$ in the sequence of free variables.

18: $\mathbf{f}$ – Real (Kind=nag_wp) Output

On exit: the function value at the final point given in x.

19: $\mathbf{g}\left(\mathbf{n}\right)$ – Real (Kind=nag_wp) array Output

On exit: the first derivative vector corresponding to the final point given in x. The components of g corresponding to free variables should normally be close to zero.

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

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

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

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

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

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

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

Constraint: $\mathbf{lw}\ge \max (7\times \mathbf{n}+\mathbf{n}\times (\mathbf{n}-1)/2,8)$.

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

On entry: ifail must be set to $0$, $\mathrm{-1}$ or $1$ to set behaviour on detection of an error; these values have no effect when no error is detected.

A value of $0$ causes the printing of an error message and program execution will be halted; otherwise program execution continues. A value of $\mathrm{-1}$ means that an error message is printed while a value of $1$ means that it is not.

If halting is not appropriate, the value $\mathrm{-1}$ or $1$ is recommended. If message printing is undesirable, then the value $1$ is recommended. Otherwise, the value $\mathrm{-1}$ is recommended since useful values can be provided in some output arguments even when $\mathbf{ifail}\ne \mathbf{0}$ on exit. When the value $-\mathbf{1}$ or $\mathbf{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{eta}=⟨\mathit{\text{value}}⟩$.
Constraint: $0.0\le \mathbf{eta}<1.0$.

On entry, $\mathbf{ibound}=⟨\mathit{\text{value}}⟩$.
Constraint: $0\le \mathbf{ibound}\le 4$.

On entry, $\mathbf{ibound}=0$ and $\mathbf{bl}\left(\mathit{j}\right)>\mathbf{bu}\left(\mathit{j}\right)$ for some $j$.

On entry, $\mathbf{ibound}=3$ and $\mathbf{bl}\left(1\right)>\mathbf{bu}\left(1\right)$.

On entry, $\mathbf{lh}=⟨\mathit{\text{value}}⟩$.
Constraint: $\mathbf{lh}\ge ⟨\mathit{\text{value}}⟩$.

On entry, $\mathbf{liw}=⟨\mathit{\text{value}}⟩$.
Constraint: $\mathbf{liw}\ge 2$.

On entry, $\mathbf{lw}=⟨\mathit{\text{value}}⟩$.
Constraint: $\mathbf{lw}\ge ⟨\mathit{\text{value}}⟩$.

On entry, $\mathbf{maxcal}=⟨\mathit{\text{value}}⟩$.
Constraint: $\mathbf{maxcal}\ge 1$.

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

On entry, $\mathbf{stepmx}=⟨\mathit{\text{value}}⟩$ and $\mathbf{xtol}=⟨\mathit{\text{value}}⟩$.
Constraint: $\mathbf{stepmx}\ge \mathbf{xtol}$.

On entry, $\mathbf{xtol}=⟨\mathit{\text{value}}⟩$.
Constraint: $\mathbf{xtol}\ge 0.0$.

$\mathbf{ifail}=2$

There have been maxcal function evaluations.

If steady reductions in $F\left(x\right)$ were monitored up to the point where this exit occurred, then the exit probably occurred simply because maxcal was set too small, so the calculations should be restarted from the final point held in x. This exit may also indicate that $F\left(x\right)$ has no minimum.

The error may also be caused by mistakes in funct or h, by the formulation of the problem or by an awkward function. If there are no such mistakes, it is worth restarting the calculations from a different starting point (not the point at which the failure occurred) in order to avoid the region which caused the failure.

$\mathbf{ifail}=3$

The conditions for a minimum have not all been satisfied, but a lower point could not be found. See Section 7 for further information.

The error may also be caused by mistakes in funct or h, by the formulation of the problem or by an awkward function. If there are no such mistakes, it is worth restarting the calculations from a different starting point (not the point at which the failure occurred) in order to avoid the region which caused the failure.

$\mathbf{ifail}=5$

No further progress can be made.

All the Lagrange multiplier estimates which are not indisputably positive lie relatively close to zero, but it is impossible either to continue minimizing on the current subspace or to find a feasible lower point by releasing and perturbing any of the fixed variables. You should investigate as for $\mathbf{ifail}=\mathbf{3}$.

The error may also be caused by mistakes in funct or h, by the formulation of the problem or by an awkward function. If there are no such mistakes, it is worth restarting the calculations from a different starting point (not the point at which the failure occurred) in order to avoid the region which caused the failure.

$\mathbf{ifail}<0$

User requested termination by setting iflag negative in funct or h.

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

9.1 Timing

9.2 Scaling

9.3 Unconstrained Minimization

      Subroutine unclbf(n,funct,h,monit,iprint,maxcal,eta,xtol,          &
                        stepmx,x,hesl,lh,hesd,f,g,iwork,liwork,work,     &
                        lwork,ifail)

!     A ROUTINE TO APPLY E04LBF TO UNCONSTRAINED PROBLEMS.

!     THE REAL ARRAY WORK MUST BE OF DIMENSION AT LEAST
!     (9*N + max(1, N*(N-1)/2)).  ITS FIRST 7*N + max(1, N*(N-1)/2)
!     ELEMENTS WILL BE USED BY E04LBF AS THE ARRAY W.  ITS LAST
!     2*N ELEMENTS WILL BE USED AS THE ARRAYS BL AND BU.

!     THE INTEGER ARRAY IWORK MUST BE OF DIMENSION AT LEAST (N+2)
!     ITS FIRST 2 ELEMENTS WILL BE USED BY E04LBF AS THE ARRAY IW.
!     ITS LAST N ELEMENTS WILL BE USED AS THE ARRAY ISTATE.

!     LIWORK AND LWORK MUST BE SET TO THE ACTUAL LENGTHS OF IWORK
!     AND WORK RESPECTIVELY, AS DECLARED IN THE CALLING SEGMENT.

!     OTHER PARAMETERS ARE AS FOR E04LBF.

!     ..  Parameters ..
      Integer nout
      Parameter (nout=6)
!     ..  Scalar Arguments ..
      Real (Kind=nag_wp) eta, f, stepmx, xtol
      Integer            ifail, iprint, lh, liwork, lwork, maxcal, n
!     ..  Array Arguments ..
      Real (Kind=nag_wp) g(n), hesd(n), hesl(lh), work(lwork), x(n)
      Integer            iwork(liwork)
!     ..  Subroutine Arguments ..
      External funct, h, monit
!     ..  Local Scalars ..
      Integer ibound, j, jbl, jbu, nh
      Logical toobig
!     ..  External Subroutines ..
      External e04lbf
!     ..  Executable Statements ..
!     CHECK THAT SUFFICIENT WORKSPACE HAS BEEN SUPPLIED
      nh = n*(n-1)/2
      If (nh.eq.0) nh = 1
      If (lwork.lt.9*n+nh .or.  liwork.lt.n+2) Then
      Write (nout,fmt=99999)
      Stop
      End If
!     JBL AND JBU SPECIFY THE PARTS OF WORK USED AS BL AND BU
      jbl = 7*n + nh + 1
      jbu = jbl + n
!     SPECIFY THAT THE PROBLEM IS UNCONSTRAINED
      ibound = 4
      Call e04lbf(n,funct,h,monit,iprint,maxcal,eta,xtol,stepmx,         &
                  ibound,work(jbl),work(jbu),x,hesl,lh,hesd,iwork(3),    &
     		  f,g,iwork,liwork,work,lwork,ifail)
!     CHECK THE PART OF IWORK WHICH WAS USED AS ISTATE IN CASE
!     THE MODULUS OF SOME X(J) HAS REACHED E+6
      toobig = .false.
      Do 20 j = 1, n
         If (iwork(2+j).lt.0) toobig = .true.
   20 Continue
      If ( .not.  toobig) Return
      Write (nout,fmt=99998)
      Stop

99999 Format (' ***** INSUFFICIENT WORKSPACE HAS BEEN SUPPLIED *****')
99998 Format (' ***** A VARIABLE HAS REACHED E+6 IN MODULUS - NO UNCON', &
              'STRAINED MINIMUM HAS BEEN FOUND *****')
      End

10 Example

10.1 Program Text

10.2 Program Data

10.3 Program Results