NAG FL Interface
e04wdf (nlp2_​solve)

1 Purpose

2 Specification

3 Description

Call e04wcf (iw, leniw, ...)
Call e04wef (ispecs, iw, ...)
Call e04wdf (n, nclin, ncnln, ...)

Figure 1 illustrates the feasible region for the $j$th pair of constraints $l_j\le r_j\left(x\right)\le u_j$. The quantity of $\delta$ is the Feasibility Tolerance, which can be set by you (see Section 12). The constraints $l_j\le r_j\le u_j$ are considered ‘satisfied’ if $r_j$ lies in Regions 2, 3 or 4, and ‘inactive’ if $r_j$ lies in Region 3. The constraint $r_j\ge l_j$ is considered ‘active’ in Region 2, and ‘violated’ in Region 1. Similarly, $r_j\le u_j$ is active in Region 4, and violated in Region 5. For equality constraints ($l_j=u_j$), Regions 2 and 4 are the same and Region 3 is empty.

Figure 1: Illustration of the constraints $l_j\le r_j\left(x\right)\le u_j$

4 References

5 Arguments

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

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

Constraint: $\mathbf{n}>0$.

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

On entry: $n_L$, the number of general linear constraints.

Constraint: $\mathbf{nclin}\ge 0$.

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

On entry: $n_N$, the number of nonlinear constraints.

Constraint: $\mathbf{ncnln}\ge 0$.

4: $\mathbf{lda}$ – Integer Input

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

Constraint: $\mathbf{lda}\ge \max (1,\mathbf{nclin})$.

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

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

Constraint: $\mathbf{ldcj}\ge \max (1,\mathbf{ncnln})$.

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

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

Constraint: $\mathbf{ldh}\ge \mathbf{n}$ unless optional parameter Hessian Limited Memory is in effect.

7: $\mathbf{a}(\mathbf{lda},*)$ – Real (Kind=nag_wp) array Input

Note: the second dimension of the array a must be at least $\mathbf{n}$ if $\mathbf{nclin}>0$, and at least $1$ otherwise.

On entry: the $\mathit{i}$th row of a contains the $\mathit{i}$th row of the matrix $A_L$ of general linear constraints in (1). That is, the $\mathit{i}$th row contains the coefficients of the $\mathit{i}$th general linear constraint, for $\mathit{i}=1,2,\dots ,\mathbf{nclin}$.

If $\mathbf{nclin}=0$, the array a is not referenced.

8: $\mathbf{bl}\left(\mathbf{n}+\mathbf{nclin}+\mathbf{ncnln}\right)$ – Real (Kind=nag_wp) array Input

9: $\mathbf{bu}\left(\mathbf{n}+\mathbf{nclin}+\mathbf{ncnln}\right)$ – Real (Kind=nag_wp) array Input

On entry: bl must contain the lower bounds and bu the upper bounds for all the constraints, in the following order. The first $n$ elements of each array must contain the bounds on the variables, the next $n_L$ elements the bounds for the general linear constraints (if any) and the next $n_N$ elements the bounds for the general nonlinear constraints (if any). To specify a nonexistent lower bound (i.e., $l_j=-\infty$), set $\mathbf{bl}\left(j\right)\le -\mathit{bigbnd}$, and to specify a nonexistent upper bound (i.e., $u_j=+\infty$), set $\mathbf{bu}\left(j\right)\ge \mathit{bigbnd}$; where $\mathit{bigbnd}$ is the optional parameter Infinite Bound Size. To specify the $j$th constraint as an equality, set $\mathbf{bl}\left(j\right)=\mathbf{bu}\left(j\right)=\beta$, say, where $\left|\beta \right|<\mathit{bigbnd}$.

Constraints:

• $\mathbf{bl}\left(\mathit{j}\right)\le \mathbf{bu}\left(\mathit{j}\right)$, for $\mathit{j}=1,2,\dots ,\mathbf{n}+\mathbf{nclin}+\mathbf{ncnln}$;
• if $\mathbf{bl}\left(j\right)=\mathbf{bu}\left(j\right)=\beta$, $\left|\beta \right|<\mathit{bigbnd}$.

10: $\mathbf{confun}$ – Subroutine, supplied by the NAG Library or the user. External Procedure

confun must calculate the vector $c\left(x\right)$ of nonlinear constraint functions and (optionally) its Jacobian, $\frac{\partial c}{\partial x}$, for a specified $n$-vector $x$. If there are no nonlinear constraints (i.e., $\mathbf{ncnln}=0$), e04wdf will never call confun, so it may be may be the dummy routine e04wdp. (e04wdp is included in the NAG Library.) If there are nonlinear constraints, the first call to confun will occur before the first call to objfun.

If all constraint gradients (Jacobian elements) are known (i.e., $\mathbf{Derivative\; Level}=2$ or $3$), any constant elements may be assigned to cjac once only at the start of the optimization. An element of cjac that is not subsequently assigned in confun will retain its initial value throughout. Constant elements may be loaded in cjac during the first call to confun (signalled by the value of $\mathbf{nstate}=1$). The ability to preload constants is useful when many Jacobian elements are identically zero, in which case cjac may be initialized to zero and nonzero elements may be reset by confun.

It must be emphasized that, if $\mathbf{Derivative\; Level}<2$, unassigned elements of cjac are not treated as constant; they are estimated by finite differences, at nontrivial expense.

The specification of confun is:

Fortran Interface copy

Subroutine confun ( mode, ncnln, n, ldcj, needc, x, ccon, cjac, nstate, iuser, ruser) Integer, Intent (In) :: ncnln, n, ldcj, needc(ncnln), nstate Integer, Intent (Inout) :: mode, iuser(*) Real (Kind=nag_wp), Intent (In) :: x(n) Real (Kind=nag_wp), Intent (Inout) :: cjac(ldcj,n), ruser(*) Real (Kind=nag_wp), Intent (Out) :: ccon(max(1,ncnln))

C Header Interface copy

void  confun (Integer *mode, const Integer *ncnln, const Integer *n, const Integer *ldcj, const Integer needc[], const double x[], double ccon[], double cjac[], const Integer *nstate, Integer iuser[], double ruser[])

C++ Header Interface copy

#include <nag.h> extern "C" { void  confun (Integer &mode, const Integer &ncnln, const Integer &n, const Integer &ldcj, const Integer needc[], const double x[], double ccon[], double cjac[], const Integer &nstate, Integer iuser[], double ruser[]) }

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

On entry: is set by e04wdf to indicate which values must be assigned during each call of confun. Only the following values need be assigned, for each value of $i$ such that $\mathbf{needc}\left(i\right)>0$:

$\mathbf{mode}=0$

The components of ccon corresponding to positive values in needc must be set. Other components and the array cjac are ignored.

$\mathbf{mode}=1$

The known components of the rows of cjac corresponding to positive values in needc must be set. Other rows of cjac and the array ccon will be ignored.

$\mathbf{mode}=2$

Only the elements of ccon corresponding to positive values of needc need to be set (and similarly for the known components of the rows of cjac).

On exit: may be used to indicate that you are unable or unwilling to evaluate the constraint functions at the current $x$.

During the linesearch, the constraint functions are evaluated at points of the form $x=x_k+\alpha p_k$ after they have already been evaluated satisfactorily at $x_k$. At any such $\alpha$, if you set $\mathbf{mode}=-1$, e04wdf will evaluate the functions at some point closer to $x_k$ (where they are more likely to be defined).

If for some reason you wish to terminate the current problem, set $\mathbf{mode}<-1$.

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

On entry: $n_N$, the number of nonlinear constraints.

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

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

4: $\mathbf{ldcj}$ – Integer Input

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

5: $\mathbf{needc}\left(\mathbf{ncnln}\right)$ – Integer array Input

On entry: the indices of the elements of ccon and/or cjac that must be evaluated by confun. If $\mathbf{needc}\left(i\right)>0$, the $i$th element of ccon and/or the available elements of the $i$th row of cjac (see argument mode) must be evaluated at $x$.

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

On entry: $x$, the vector of variables at which the constraint functions and/or the available elements of the constraint Jacobian are to be evaluated.

7: $\mathbf{ccon}\left(\max (1,\mathbf{ncnln})\right)$ – Real (Kind=nag_wp) array Output

On exit: if $\mathbf{needc}\left(i\right)>0$ and $\mathbf{mode}=0$ or $2$, $\mathbf{ccon}\left(i\right)$ must contain the value of the $i$th constraint at $x$. The remaining elements of ccon, corresponding to the non-positive elements of needc, are ignored.

8: $\mathbf{cjac}(\mathbf{ldcj},\mathbf{n})$ – Real (Kind=nag_wp) array Input/Output

On entry: the elements of cjac are set to special values that enable e04wdf to detect whether they are reset by confun.

On exit: if $\mathbf{needc}\left(i\right)>0$ and $\mathbf{mode}=1$ or $2$, the $i$th row of cjac must contain the available elements of the vector $\nabla c_i$ given by

$$\nabla c_i={(\frac{\partial c_i}{\partial x_1},\frac{\partial c_i}{\partial x_2},\dots ,\frac{\partial c_i}{\partial x_n})}^{\mathrm{T}}\text{,}$$

where $\frac{\partial c_i}{\partial x_j}$ is the partial derivative of the $i$th constraint with respect to the $j$th variable, evaluated at the point $x$. See also the argument nstate. The remaining rows of cjac, corresponding to non-positive elements of needc, are ignored.

If all elements of the constraint Jacobian are known (i.e., $\mathbf{Derivative\; Level}=2$ or $3$), any constant elements may be assigned to cjac one time only at the start of the optimization. An element of cjac that is not subsequently assigned in confun will retain its initial value throughout. Constant elements may be loaded into cjac during the first call to confun (signalled by the value $\mathbf{nstate}=1$). The ability to preload constants is useful when many Jacobian elements are identically zero, in which case cjac may be initialized to zero and nonzero elements may be reset by confun.

Note that constant nonzero elements do affect the values of the constraints. Thus, if $\mathbf{cjac}(i,j)$ is set to a constant value, it need not be reset in subsequent calls to confun, but the value $\mathbf{cjac}(i,j)\times \mathbf{x}\left(j\right)$ must nonetheless be added to $\mathbf{ccon}\left(i\right)$. For example, if $\mathbf{cjac}(1,1)=2$ and $\mathbf{cjac}(1,2)=-5$, then the term $2\times \mathbf{x}\left(1\right)-5\times \mathbf{x}\left(2\right)$ must be included in the definition of $\mathbf{ccon}\left(1\right)$.

It must be emphasized that, if $\mathbf{Derivative\; Level}=0$ or $1$, unassigned elements of cjac are not treated as constant; they are estimated by finite differences, at nontrivial expense. If you do not supply a value for the optional parameter Difference Interval, an interval for each element of $x$ is computed automatically at the start of the optimization. The automatic procedure can usually identify constant elements of cjac, which are then computed once only by finite differences.

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

On entry: if $\mathbf{nstate}=1$, then e04wdf is calling confun for the first time. This argument setting allows you to save computation time if certain data must be read or calculated only once.

10: $\mathbf{iuser}\left(*\right)$ – Integer array User Workspace

11: $\mathbf{ruser}\left(*\right)$ – Real (Kind=nag_wp) array User Workspace

confun is called with the arguments iuser and ruser as supplied to e04wdf. You should use the arrays iuser and ruser to supply information to confun.

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

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

confun should be tested separately before being used in conjunction with e04wdf. See also the description of the optional parameter Verify Level.

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

objfun must calculate the objective function $F\left(x\right)$ and (optionally) its gradient $g\left(x\right)=\frac{\partial F}{\partial x}$ for a specified $n$-vector $x$.

The specification of objfun is:

Fortran Interface copy

Subroutine objfun ( mode, n, x, objf, grad, nstate, iuser, ruser) Integer, Intent (In) :: n, nstate Integer, Intent (Inout) :: mode, iuser(*) Real (Kind=nag_wp), Intent (In) :: x(n) Real (Kind=nag_wp), Intent (Inout) :: grad(n), ruser(*) Real (Kind=nag_wp), Intent (Out) :: objf

C Header Interface copy

void  objfun (Integer *mode, const Integer *n, const double x[], double *objf, double grad[], const Integer *nstate, Integer iuser[], double ruser[])

C++ Header Interface copy

#include <nag.h> extern "C" { void  objfun (Integer &mode, const Integer &n, const double x[], double &objf, double grad[], const Integer &nstate, Integer iuser[], double ruser[]) }

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

On entry: is set by e04wdf to indicate which values must be assigned during each call of objfun. Only the following values need be assigned:

$\mathbf{mode}=0$

objf.

$\mathbf{mode}=1$

All available elements of grad.

$\mathbf{mode}=2$

objf and all available elements of grad.

On exit: may be used to indicate that you are unable or unwilling to evaluate the objective function at the current $x$.

During the linesearch, the function is evaluated at points of the form $x=x_k+\alpha p_k$ after they have already been evaluated satisfactorily at $x_k$. For any such $x$, if you set $\mathbf{mode}=-1$, e04wdf will reduce $\alpha$ and evaluate the functions again (closer to $x_k$, where they are more likely to be defined).

If for some reason you wish to terminate the current problem, set $\mathbf{mode}<-1$.

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

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

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

On entry: $x$, the vector of variables at which the objective function and/or all available elements of its gradient are to be evaluated.

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

On exit: if $\mathbf{mode}=0$ or $2$, objf must be set to the value of the objective function at $x$.

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

On entry: the elements of grad are set to special values.

On exit: if $\mathbf{mode}=1$ or $2$, grad must return the available elements of the gradient evaluated at $x$, i.e., $\mathbf{grad}\left(i\right)$ contains the partial derivative $\frac{\partial F}{\partial x_i}$.

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

On entry: if $\mathbf{nstate}=1$, then e04wdf is calling objfun for the first time. This argument setting allows you to save computation time if certain data must be read or calculated only once.

7: $\mathbf{iuser}\left(*\right)$ – Integer array User Workspace

8: $\mathbf{ruser}\left(*\right)$ – Real (Kind=nag_wp) array User Workspace

objfun is called with the arguments iuser and ruser as supplied to e04wdf. You should use the arrays iuser and ruser to supply information to objfun.

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

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

objfun should be tested separately before being used in conjunction with e04wdf. See also the description of the optional parameter Verify Level.

12: $\mathbf{majits}$ – Integer Output

On exit: the number of major iterations performed.

13: $\mathbf{istate}\left(\mathbf{n}+\mathbf{nclin}+\mathbf{ncnln}\right)$ – Integer array Input/Output

On entry: is an integer array that need not be initialized if e04wdf is called with the Cold Start option (the default).

If optional parameter Warm Start has been chosen, every element of istate must be set. If e04wdf has just been called on a problem with the same dimensions, istate already contains valid values. Otherwise, $\mathbf{istate}\left(j\right)$ should indicate whether either of the constraints $r_j\left(x\right)\ge l_j$ or $r_j\left(x\right)\le u_j$ is expected to be active at a solution of (1).

The ordering of istate is the same as for bl, bu and $r\left(x\right)$, i.e., the first n components of istate refer to the upper and lower bounds on the variables, the next nclin refer to the bounds on $A_{L}x$, and the last ncnln refer to the bounds on $c\left(x\right)$. Possible values of $\mathbf{istate}\left(i\right)$ follow:

$0$	Neither $r_j\left(x\right)\ge l_j$ nor $r_j\left(x\right)\le u_j$ is expected to be active.
$1$	$r_j\left(x\right)\ge l_j$ is expected to be active.
$2$	$r_j\left(x\right)\le u_j$ is expected to be active.
$3$	This may be used if $l_j=u_j$. Normally an equality constraint $r_j\left(x\right)=l_j=u_j$ is active at a solution.

The values $1$, $2$ or $3$ all have the same effect when $\mathbf{bl}\left(j\right)=\mathbf{bu}\left(j\right)$. If necessary, e04wdf will override your specification of istate, so that a poor choice will not cause the algorithm to fail.

On exit: describes the status of the constraints $l\le r\left(x\right)\le u$. For the $j$th lower or upper bound, $j=1,2,\dots ,\mathbf{n}+\mathbf{nclin}+\mathbf{ncnln}$, the possible values of $\mathbf{istate}\left(j\right)$ are as follows (see Figure 1). $\delta$ is the appropriate feasibility tolerance.

$-2$	(Region 1) The lower bound is violated by more than $\delta$.
$-1$	(Region 5) The upper bound is violated by more than $\delta$.
$\phantom{-}0$	(Region 3) Both bounds are satisfied by more than $\delta$.
$\phantom{-}1$	(Region 2) The lower bound is active (to within $\delta$).
$\phantom{-}2$	(Region 4) The upper bound is active (to within $\delta$).
$\phantom{-}3$	($\text{Region 2}=\text{Region 4}$) The bounds are equal and the equality constraint is satisfied (to within $\delta$).

These values of istate are labelled in the printed solution according to Table 1.

Table 1
Labels used in the printed solution for the regions in Figure 1

Region	$1$	$2$	$3$	$4$	$5$	$2\equiv 4$
$\mathbf{istate}\left(j\right)$	$-2$	$1$	$0$	$2$	$-1$	$3$
Printed solution	--	LL	FR	UL	++	EQ

14: $\mathbf{ccon}\left(\max (1,\mathbf{ncnln})\right)$ – Real (Kind=nag_wp) array Input/Output

On entry: ccon need not be initialized if the (default) optional parameter Cold Start is used.

For a Warm Start, and if $\mathbf{ncnln}>0$, ccon contains values of the nonlinear constraint functions $c_{\mathit{i}}$, for $\mathit{i}=1,2,\dots ,\mathbf{ncnln}$, calculated in a previous call to e04wdf.

On exit: if $\mathbf{ncnln}>0$, $\mathbf{ccon}\left(\mathit{i}\right)$ contains the value of the $\mathit{i}$th nonlinear constraint function $c_{\mathit{i}}$ at the final iterate, for $\mathit{i}=1,2,\dots ,\mathbf{ncnln}$.

If $\mathbf{ncnln}=0$, the array ccon is not referenced.

15: $\mathbf{cjac}(\mathbf{ldcj},*)$ – Real (Kind=nag_wp) array Input/Output

Note: the second dimension of the array cjac must be at least $\mathbf{n}$ if $\mathbf{ncnln}>0$, and at least $1$ otherwise.

On entry: in general, cjac need not be initialized before the call to e04wdf. However, if $\mathbf{Derivative\; Level}=2$ or $3$, any constant elements of cjac may be initialized. Such elements need not be reassigned on subsequent calls to confun.

On exit: if $\mathbf{ncnln}>0$, cjac contains the Jacobian matrix of the nonlinear constraint functions at the final iterate, i.e., $\mathbf{cjac}(\mathit{i},\mathit{j})$ contains the partial derivative of the $\mathit{i}$th constraint function with respect to the $\mathit{j}$th variable, for $\mathit{i}=1,2,\dots ,\mathbf{ncnln}$ and $\mathit{j}=1,2,\dots ,\mathbf{n}$. (See the discussion of argument cjac under confun.)

If $\mathbf{ncnln}=0$, the array cjac is not referenced.

16: $\mathbf{clamda}\left(\mathbf{n}+\mathbf{nclin}+\mathbf{ncnln}\right)$ – Real (Kind=nag_wp) array Input/Output

On entry: need not be set if the (default) optional parameter Cold Start is used.

If the optional parameter Warm Start has been chosen, $\mathbf{clamda}\left(\mathit{j}\right)$ must contain a multiplier estimate for each nonlinear constraint, with a sign that matches the status of the constraint specified by the istate array, for $\mathit{j}=\mathbf{n}+\mathbf{nclin}+1,\dots ,\mathbf{n}+\mathbf{nclin}+\mathbf{ncnln}$. The remaining elements need not be set. If the $j$th constraint is defined as ‘inactive’ by the initial value of the istate array (i.e., $\mathbf{istate}\left(j\right)=0$), $\mathbf{clamda}\left(j\right)$ should be zero; if the $j$th constraint is an inequality active at its lower bound (i.e., $\mathbf{istate}\left(j\right)=1$), $\mathbf{clamda}\left(j\right)$ should be non-negative; if the $j$th constraint is an inequality active at its upper bound (i.e., $\mathbf{istate}\left(j\right)=2$), $\mathbf{clamda}\left(j\right)$ should be non-positive. If necessary, the routine will modify clamda to match these rules.

On exit: the values of the QP multipliers from the last QP subproblem. $\mathbf{clamda}\left(j\right)$ should be non-negative if $\mathbf{istate}\left(j\right)=1$ and non-positive if $\mathbf{istate}\left(j\right)=2$.

17: $\mathbf{objf}$ – Real (Kind=nag_wp) Output

On exit: the value of the objective function at the final iterate.

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

On exit: the gradient of the objective function (or its finite difference approximation) at the final iterate.

19: $\mathbf{h}(\mathbf{ldh},*)$ – Real (Kind=nag_wp) array Input/Output

Note: the second dimension of the array h must be at least $\mathbf{n}$ unless the optional parameter Hessian Limited Memory is in effect. If Hessian Limited Memory is in effect, array h is not referenced.

On entry: h need not be initialized if the (default) optional parameter Cold Start is used, and will be set to the identity.

If the optional parameter Warm Start has been chosen, h provides the initial approximation of the Hessian of the Lagrangian, i.e., $\mathbf{h}(i,j)\approx \frac{{\partial }^2\mathcal{L}(x,\lambda )}{\partial x_i\partial x_j}$, where $\mathcal{L}(x,\lambda )=F\left(x\right)-{c\left(x\right)}^{\mathrm{T}}\lambda$ and $\lambda$ is an estimate of the Lagrange multipliers. h must be a positive definite matrix.

On exit: contains the Hessian of the Lagrangian at the final estimate $x$.

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

On entry: an initial estimate of the solution.

On exit: the final estimate of the solution.

21: $\mathbf{iw}\left(\mathbf{leniw}\right)$ – Integer array Communication Array

22: $\mathbf{leniw}$ – Integer Input

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

Constraint: $\mathbf{leniw}\ge 600$.

23: $\mathbf{rw}\left(\mathbf{lenrw}\right)$ – Real (Kind=nag_wp) array Communication Array

24: $\mathbf{lenrw}$ – Integer Input

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

Constraint: $\mathbf{lenrw}\ge 600$.

25: $\mathbf{iuser}\left(*\right)$ – Integer array User Workspace

26: $\mathbf{ruser}\left(*\right)$ – Real (Kind=nag_wp) array User Workspace

iuser and ruser are not used by e04wdf, but are passed directly to confun and objfun and may be used to pass information to these routines.

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

On entry: ifail must be set to $0$, $-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 $-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 $-1$ or $1$ is recommended. If message printing is undesirable, then the value $1$ is recommended. Otherwise, the value $-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).

e04wdf returns with $\mathbf{ifail}=\mathbf{0}$ if the iterates have converged to a point $x$ that satisfies the first-order Kuhn–Tucker (see Section 13.2) conditions to the accuracy requested by the Major Optimality Tolerance, i.e., the projected gradient and active constraint residuals are negligible at $x$.

You should check whether the following four conditions are satisfied:

1. (i)the final value of rgNorm (see Section 13.2) is significantly less than that at the starting point;
2. (ii)during the final major iterations, the values of Step and Minors (see Section 13.1) are both one;
3. (iii)the last few values of both rgNorm and SumInf (see Section 13.2) become small at a fast linear rate; and
4. (iv)condHz (see Section 13.1) is small.

If all these conditions hold, $x$ is almost certainly a local minimum of (1).

One caution about ‘Optimal solutions’. Some of the variables or slacks may lie outside their bounds more than desired, especially if scaling was requested. Max Primal infeas in the Print file refers to the largest bound infeasibility and which variable is involved. If it is too large, consider restarting with a smaller Minor Feasibility Tolerance (say $10$ times smaller) and perhaps $\mathbf{Scale\; Option}=0$.

Similarly, Max Dual infeas in the Print file indicates which variable is most likely to be at a nonoptimal value. Broadly speaking, if

$$\mathtt{Max\; Dual\; infeas}/\mathtt{Max\; pi}={10}^{-d}\text{,}$$

then the objective function would probably change in the $d$th significant digit if optimization could be continued. If $d$ seems too large, consider restarting with a smaller Major Optimality Tolerance.

Finally, Nonlinear constraint violn in the Print file shows the maximum infeasibility for nonlinear rows. If it seems too large, consider restarting with a smaller Major Feasibility Tolerance.

6 Error Indicators and Warnings

$\mathbf{ifail}=1$

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

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

The initialization routine e04wcf has not been called.

$\mathbf{ifail}=2$

Basis file dimensions do not match this problem.

On entry, bounds bl and bu for $⟨\mathit{\text{value}}⟩$ are equal and infinite. $\mathbf{bl}=\mathbf{bu}=⟨\mathit{\text{value}}⟩$ and $\mathit{bigbnd}=⟨\mathit{\text{value}}⟩$.

On entry, bounds for $⟨\mathit{\text{value}}⟩$ are inconsistent. $\mathbf{bl}=⟨\mathit{\text{value}}⟩$ and $\mathbf{bu}=⟨\mathit{\text{value}}⟩$.

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

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

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

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

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

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

$\mathbf{ifail}=3$

The requested accuracy could not be achieved.

A feasible solution has been found, but the requested accuracy in the dual infeasibilities could not be achieved. An abnormal termination has occurred, but e04wdf is within ${10}^{-2}$ of satisfying the Major Optimality Tolerance. Check that the Major Optimality Tolerance is not too small.

$\mathbf{ifail}=4$

The linear constraints appear to be infeasible.

The problem appears to be infeasible. Infeasibilites have been minimized.

The problem appears to be infeasible. Nonlinear infeasibilites have been minimized.

The problem appears to be infeasible. The linear equality constraints could not be satisfied.

When the constraints are linear, this message is based on a relatively reliable indicator of infeasibility. Feasibility is measured with respect to the upper and lower bounds on the variables and slacks. Among all the points satisfying the general constraints $Ax-s=0$ (see (5) and (6) in Section 11.2), there is apparently no point that satisfies the bounds on $x$ and $s$. Violations as small as the Minor Feasibility Tolerance are ignored, but at least one component of $x$ or $s$ violates a bound by more than the tolerance.

When nonlinear constraints are present, infeasibility is much harder to recognize correctly. Even if a feasible solution exists, the current linearization of the constraints may not contain a feasible point. In an attempt to deal with this situation, when solving each QP subproblem, e04wdf is prepared to relax the bounds on the slacks associated with nonlinear rows.

If a QP subproblem proves to be infeasible or unbounded (or if the Lagrange multiplier estimates for the nonlinear constraints become large), e04wdf enters so-called ‘nonlinear elastic’ mode. The subproblem includes the original QP objective and the sum of the infeasibilities – suitably weighted using the optional parameter Elastic Weight. In elastic mode, some of the bounds on the nonlinear rows are ‘elastic’ – i.e., they are allowed to violate their specific bounds. Variables subject to elastic bounds are known as elastic variables. An elastic variable is free to violate one or both of its original upper or lower bounds. If the original problem has a feasible solution and the elastic weight is sufficiently large, a feasible point eventually will be obtained for the perturbed constraints, and optimization can continue on the subproblem. If the nonlinear problem has no feasible solution, e04wdf will tend to determine a ‘good’ infeasible point if the elastic weight is sufficiently large. (If the elastic weight were infinite, e04wdf would locally minimize the nonlinear constraint violations subject to the linear constraints and bounds.)

Unfortunately, even though e04wdf locally minimizes the nonlinear constraint violations, there may still exist other regions in which the nonlinear constraints are satisfied. Wherever possible, nonlinear constraints should be defined in such a way that feasible points are known to exist when the constraints are linearized.

$\mathbf{ifail}=5$

The problem appears to be unbounded. The constraint violation limit has been reached.

The problem appears to be unbounded. The objective function is unbounded.

The problem appears to be unbounded (or badly scaled).

For linear problems, unboundedness is detected by the simplex method when a nonbasic variable can be increased or decreased by an arbitrary amount without causing a basic variable to violate a bound. Consider adding an upper or lower bound to the variable. Also, examine the constraints that have nonzeros in the associated column, to see if they have been formulated as intended.

Very rarely, the scaling of the problem could be so poor that numerical error will give an erroneous indication of unboundedness. Consider using the optional parameter Scale Option.

For nonlinear problems, e04wdf monitors both the size of the current objective function and the size of the change in the variables at each step. If either of these is very large (as judged by the ‘Unbounded’ parameters (see Section 12)), the problem is terminated and declared unbounded. To avoid large function values, it may be necessary to impose bounds on some of the variables in order to keep them away from singularities in the nonlinear functions.

The message may indicate an abnormal termination while enforcing the limit on the constraint violations. This exit implies that the objective is not bounded below in the feasible region defined by expanding the bounds by the value of the Violation Limit.

$\mathbf{ifail}=6$

Iteration limit reached.

Major iteration limit reached.

The value of the optional parameter Superbasics Limit is too small.

Either the Iterations Limit or the Major Iterations Limit was exceeded before the required solution could be found. Check the iteration log to be sure that progress was being made. If so, and if you caused a basis file to be saved by using the optional parameter New Basis File, consider restarting the run using the optional parameter Old Basis File to see whether further progress can be made. If you have no basis file available, you might rerun the problem after increasing the optional parameters Minor Iterations Limit and/or Major Iterations Limit.

If none of the above limits have been reached, this error may mean that the problem appears to be more nonlinear than anticipated. The current set of basic and superbasic variables have been optimized as much as possible and a pricing operation (where a nonbasic variable is selected to become superbasic) is necessary to continue, but it can't continue as the number of superbasic variables has already reached the limit specified by the optional parameter Superbasics Limit. In general, raise the Superbasics Limit $s$ by a reasonable amount, bearing in mind the storage needed for the reduced Hessian. (The Reduced Hessian Dimension $h$ will also increase to $s$ unless specified otherwise, and the associated storage will be about $\frac{1}{2}{s}^2$ words.) In some cases you may have to set $h<s$ to conserve storage, but beware that the rate of convergence will probably fall off severely.

$\mathbf{ifail}=7$

Numerical difficulties have been encountered and no further progress can be made.

Numerical difficulties have been encountered and no further progress can be made.

Several circumstances could lead to this exit.

1. 1.The user-supplied subroutines objfun or confun could be returning accurate function values but inaccurate gradients (or vice versa). This is the most likely cause. Study the comments given for $\mathbf{ifail}=\mathbf{8}$, and do your best to ensure that the coding is correct.
2. 2.The function and gradient values could be consistent, but their precision could be too low. For example, accidental use of a real data type when double precision was intended would lead to a relative function precision of about ${10}^{-6}$ instead of something like ${10}^{-15}$. The default Major Optimality Tolerance of $2\times {10}^{-6}$ would need to be raised to about ${10}^{-3}$ for optimality to be declared (at a rather suboptimal point). Of course, it is better to revise the function coding to obtain as much precision as economically possible.
3. 3.If function values are obtained from an expensive iterative process, they may be accurate to rather few significant figures, and gradients will probably not be available. One should specify
   • Function Precision $t$
   • Major Optimality Tolerance $\sqrt{t}$
   but even then, if $t$ is as large as ${10}^{-5}$ or ${10}^{-6}$ (only $5$ or $6$ significant figures), the same exit condition may occur. At present the only remedy is to increase the accuracy of the function calculation.
4. 4.An $LU$ factorization of the basis has just been obtained and used to recompute the basic variables $x_B$, given the present values of the superbasic and nonbasic variables. A step of ‘iterative refinement’ has also been applied to increase the accuracy of $x_B$. However, a row check has revealed that the resulting solution does not satisfy the current constraints $Ax-s=0$ sufficiently well.
   This probably means that the current basis is very ill-conditioned. If there are some linear constraints and variables, try $\mathbf{Scale\; Option}=1$ if scaling has not yet been used.
   For certain highly structured basis matrices (notably those with band structure), a systematic growth may occur in the factor $U$. Consult the description of Umax and Growth in Section 13.4 and set the LU Factor Tolerance to $2.0$ (or possibly even smaller, but not less than $1.0$).
5. 5.The first factorization attempt will have found the basis to be structurally or numerically singular. (Some diagonals of the triangular matrix $U$ were respectively zero or smaller than a certain tolerance.) The associated variables are replaced by slacks and the modified basis is refactorized, but singularity persists. This must mean that the problem is badly scaled, or the LU Factor Tolerance is too much larger than $1.0$. This is highly unlikely to occur.

$\mathbf{ifail}=8$

User-supplied function computes incorrect constraint derivatives.

User-supplied function computes incorrect objective derivatives.

If the message refers to the derivatives of the objective function, then a check has been made on some individual elements of the objective gradient array at the first point that satisfies the linear constraints. At least one component $\mathbf{grad}j$ is being set to a value that disagrees markedly with its associated forward-difference estimate $\frac{\partial F}{\partial x_j}$. (The relative difference between the computed and estimated values is $1.0$ or more.) This exit is a safeguard, since e04wdf will usually fail to make progress when the computed gradients are seriously inaccurate. In the process it may expend considerable effort before terminating with $\mathbf{ifail}=\mathbf{7}$.

Check the function and gradient computation very carefully in objfun. A simple omission could explain everything. If $F$ or a component $\frac{\partial F}{\partial x_j}$ is very large, then give serious thought to scaling the function or the nonlinear variables.

If you feel certain that the computed $\mathbf{grad}\left(j\right)$ is correct (and that the forward-difference estimate is, therefore, wrong), you can specify $\mathbf{Verify\; Level}=0$ to prevent individual elements from being checked. However, the optimization procedure may have difficulty.

If the message refers to derivatives of the constraints, then at least one of the computed constraint derivatives is significantly different from an estimate obtained by forward-differencing the vector $c\left(x\right)$. Follow the advice given above, trying to ensure that the arrays ccon and cjac are being set correctly in confun.

$\mathbf{ifail}=9$

Unable to proceed into undefined region of user-supplied function.

User-supplied function is undefined at the first feasible point.

User-supplied function is undefined at the initial point.

You have indicated that the problem functions are undefined by assigning the value $\mathbf{mode}=-1$ on exit from objfun or confun. e04wdf attempts to evaluate the problem functions closer to a point at which the functions are already known to be defined. This exit occurs if e04wdf is unable to find a point at which the functions are defined. This will occur in the case of:

• –undefined functions with no recovery possible;
• –undefined functions at the first point;
• –undefined functions at the first feasible point; or
• –undefined functions when checking derivatives.

$\mathbf{ifail}=10$

User-supplied constraint function requested termination.

User-supplied objective function requested termination.

You have indicated the wish to terminate solution of the current problem by setting mode to a value $<-1$ on exit from objfun or confun.

$\mathbf{ifail}=11$

Internal error: memory allocation failed when attempting to allocate workspace sizes $⟨\mathit{\text{value}}⟩$ and $⟨\mathit{\text{value}}⟩$. Please contact NAG.

$\mathbf{ifail}=12$

Internal memory allocation was insufficient. Please contact NAG.

$\mathbf{ifail}=13$

An error has occurred in the basis package, perhaps indicating incorrect setup of arrays. Set the optional parameter Print File and examine the output carefully for further information.

$\mathbf{ifail}=14$

An unexpected error has occurred. Set the optional parameter Print File and examine the output carefully for further information.

$\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 The Final Output

10 Example

10.1 Program Text

10.2 Program Data

10.3 Program Results

11 Algorithmic Details

11.1 Constraints and Slack Variables

11.2 Major Iterations

11.3 Minor Iterations

11.4 The Merit Function

11.5 Treatment of Constraint Infeasibilities

12 Optional Parameters

• Backup Basis File
• Central Difference Interval
• Check Frequency
• Cold Start
• Crash Option
• Crash Tolerance
• Defaults
• Derivative Level
• Derivative Linesearch
• Difference Interval
• Dump File
• Elastic Weight
• Expand Frequency
• Factorization Frequency
• Feasibility Tolerance
• Feasible Point
• Function Precision
• Hessian Frequency
• Hessian Full Memory
• Hessian Limited Memory
• Hessian Updates
• Infinite Bound Size
• Insert File
• Iterations Limit
• Linesearch Tolerance
• List
• Load File
• LU Complete Pivoting
• LU Density Tolerance
• LU Factor Tolerance
• LU Partial Pivoting
• LU Rook Pivoting
• LU Singularity Tolerance
• LU Update Tolerance
• Major Feasibility Tolerance
• Major Iterations Limit
• Major Optimality Tolerance
• Major Print Level
• Major Step Limit
• Maximize
• Minimize
• Minor Feasibility Tolerance
• Minor Iterations Limit
• Minor Print Level
• New Basis File
• New Superbasics Limit
• Nolist
• Nonderivative Linesearch
• Old Basis File
• Partial Price
• Pivot Tolerance
• Print File
• Print Frequency
• Proximal Point Method
• Punch File
• QPSolver CG
• QPSolver Cholesky
• QPSolver QN
• Reduced Hessian Dimension
• Save Frequency
• Scale Option
• Scale Print
• Scale Tolerance
• Solution File
• Start Constraint Check At Variable
• Start Objective Check At Variable
• Stop Constraint Check At Variable
• Stop Objective Check At Variable
• Summary File
• Summary Frequency
• Superbasics Limit
• Suppress Parameters
• System Information No
• System Information Yes
• Timing Level
• Unbounded Objective
• Unbounded Step Size
• Verify Level
• Violation Limit
• Warm Start

Begin
   Print Level = 5
End

Call e04wef (ispecs, iw, rw, ifail)

12.1 Description of the Optional Parameters

• the keywords, where the minimum abbreviation of each keyword is underlined (if no characters of an optional qualifier are underlined, the qualifier may be omitted);
• a parameter value, where the letters $a$, $i$ and $r$ denote options that take character, integer and real values respectively;
• the default value, where the symbol $\epsilon$ is a generic notation for machine precision (see x02ajf), and ${\epsilon }_r$ denotes the relative precision of the objective function Function Precision, and $\mathit{bigbnd}$ signifies the value of Infinite Bound Size.