NAG Library Routine Document

E04NFF/E04NFA

1  Purpose

2  Specification

2.1  Specification for E04NFF

2.2  Specification for E04NFA

3  Description

4  References

5  Parameters

1:     N – INTEGERInput

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

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

2:     NCLIN – INTEGERInput

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

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

3:     A(LDA,$*$) – REAL (KIND=nag_wp) arrayInput

Note: the second dimension of the array A must be at least $\mathbf{N}$ if $\mathbf{NCLIN}>0$ and at least $1$ if $\mathbf{NCLIN}=0$.

On entry: the $\mathit{i}$th row of A must contain the coefficients of the $\mathit{i}$th general linear constraint, for $\mathit{i}=1,2,\dots ,m_L$.

If $\mathbf{NCLIN}=0$, A is not referenced.

4:     LDA – INTEGERInput

On entry: the first dimension of the array A as declared in the (sub)program from which E04NFF/E04NFA is called.

Constraint: $\mathbf{LDA}\ge \max \left(1,\mathbf{NCLIN}\right)$.

5:     BL($\mathbf{N}+\mathbf{NCLIN}$) – REAL (KIND=nag_wp) arrayInput

6:     BU($\mathbf{N}+\mathbf{NCLIN}$) – REAL (KIND=nag_wp) arrayInput

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, and the next $m_L$ elements the bounds for the general linear 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}$; the default value of $\mathit{bigbnd}$ is ${10}^{20}$, but this may be changed by 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}$;
• if $\mathbf{BL}\left(j\right)=\mathbf{BU}\left(j\right)=\beta$, $\left|\beta \right|<\mathit{bigbnd}$.

7:     CVEC($*$) – REAL (KIND=nag_wp) arrayInput

Note: the dimension of the array CVEC must be at least $\mathbf{N}$ if the problem is of type LP, QP2 (the default) or QP4, and at least $1$ otherwise.

On entry: the coefficients of the explicit linear term of the objective function when the problem is of type LP, QP2 (the default) and QP4.

If the problem is of type FP, QP1, or QP3, CVEC is not referenced.

8:     H(LDH,$*$) – REAL (KIND=nag_wp) arrayInput

Note: the second dimension of the array H must be at least $\mathbf{N}$ if it is to be used to store $H$ explicitly, and at least $1$ otherwise.

On entry: may be used to store the quadratic term $H$ of the QP objective function if desired. In some cases, you need not use H to store $H$ explicitly (see the specification of subroutine QPHESS). The elements of H are referenced only by subroutine QPHESS. The number of rows of $H$ is denoted by $m$, whose default value is $n$. (The optional parameter Hessian Rows may be used to specify a value of $m<n$.)

If the default version of QPHESS is used and the problem is of type QP1 or QP2 (the default), the first $m$ rows and columns of H must contain the leading $m$ by $m$ rows and columns of the symmetric Hessian matrix $H$. Only the diagonal and upper triangular elements of the leading $m$ rows and columns of H are referenced. The remaining elements need not be assigned.

If the default version of QPHESS is used and the problem is of type QP3 or QP4, the first $m$ rows of H must contain an $m$ by $n$ upper trapezoidal factor of the symmetric Hessian matrix $H^{\mathrm{T}}H$. The factor need not be of full rank, i.e., some of the diagonal elements may be zero. However, as a general rule, the larger the dimension of the leading nonsingular sub-matrix of H, the fewer iterations will be required. Elements outside the upper trapezoidal part of the first $m$ rows of H need not be assigned.

If a nondefault version of QPHESS is supplied, then in some cases it may be desirable to use a one-dimensional array to transmit data to QPHESS. (This is illustrated in the example program in Section 9 in E04NGF/E04NGA.) H is then declared as an LDH by $1$ array, where $\mathbf{LDH}\ge \mathbf{N}\times \left(\mathbf{N}+1\right)/2$.

In other situations, it may be desirable to compute $Hx$ or $H^{\mathrm{T}}Hx$ without accessing H – for example, if $H$ or $H^{\mathrm{T}}H$ is sparse or has special structure. The parameters H and LDH may then refer to any convenient array.

If the problem is of type FP or LP, H is not referenced.

9:     LDH – INTEGERInput

On entry: the first dimension of the array H as declared in the (sub)program from which E04NFF/E04NFA is called.

Constraints:

• if the problem is of type QP1, QP2 (the default), QP3 or QP4, $\mathbf{LDH}\ge \mathbf{N}$ or at least the value of the optional parameter Hessian Rows;
• if the problem is of type FP or LP, $\mathbf{LDH}\ge 1$.

10:   QPHESS – SUBROUTINE, supplied by the NAG Library or the user.External Procedure

In general, you need not provide a version of QPHESS, because a ‘default’ subroutine with name E04NFU/E54NFU is included in the Library. However, the algorithm of E04NFF/E04NFA requires only the product of $H$ or $H^{\mathrm{T}}H$ and a vector $x$; and in some cases you may obtain increased efficiency by providing a version of QPHESS that avoids the need to define the elements of the matrices $H$ or $H^{\mathrm{T}}H$ explicitly.

QPHESS is not referenced if the problem is of type FP or LP, in which case QPHESS may be the routine E04NFU/E54NFU.

The specification of QPHESS for E04NFF is:

SUBROUTINE QPHESS ( N, JTHCOL, H, LDH, X, HX) INTEGER  N, JTHCOL, LDH REAL (KIND=nag_wp)  H(LDH,*), X(N), HX(N)

The specification of QPHESS for E04NFA is:

SUBROUTINE QPHESS ( N, JTHCOL, H, LDH, X, HX, IUSER, RUSER, IWSAV) INTEGER  N, JTHCOL, LDH, IUSER(*), IWSAV(610) REAL (KIND=nag_wp)  H(LDH,*), X(N), HX(N), RUSER(*)

1:     N – INTEGERInput

On entry: this is the same parameter as supplied to this routine. See the description for the top level parameter N.

2:     JTHCOL – INTEGERInput

On entry: specifies whether or not the vector $x$ is a column of the identity matrix.

$\mathbf{JTHCOL}=j>0$

The vector $x$ is the $j$th column of the identity matrix, and hence $Hx$ or $H^{\mathrm{T}}Hx$ is the $j$th column of $H$ or $H^{\mathrm{T}}H$, respectively. This may in some cases require very little computation and QPHESS may be coded to take advantage of this. However special code is not necessary because $x$ is always stored explicitly in the array X.

$\mathbf{JTHCOL}=0$

$x$ has no special form.

3:     H(LDH,$*$) – REAL (KIND=nag_wp) arrayInput

On entry: this is the same parameter as supplied to this routine. See the description for the top level parameter H.

4:     LDH – INTEGERInput

On entry: this is the same parameter as supplied to this routine. See the description for the top level parameter LDH.

5:     X(N) – REAL (KIND=nag_wp) arrayInput

On entry: the vector $x$.

6:     HX(N) – REAL (KIND=nag_wp) arrayOutput

On exit: the product $Hx$ if the problem is of type QP1 or QP2 (the default), or the product $H^{\mathrm{T}}Hx$ if the problem is of type QP3 or QP4.

Note: the following are additional parameters for specific use with E04NFA. Users of E04NFF therefore need not read the remainder of this description.

7:     IUSER($*$) – INTEGER arrayUser Workspace

8:     RUSER($*$) – REAL (KIND=nag_wp) arrayUser Workspace

QPHESS is called with the parameters IUSER and RUSER as supplied to E04NFF/E04NFA. You are free to use the arrays IUSER and RUSER to supply information to QPHESS as an alternative to using COMMON global variables.

9:     IWSAV($610$) – INTEGER arrayCommunication Array

IWSAV contains information that is required by the default routine E54NFU.

QPHESS must either be a module subprogram USEd by, or declared as EXTERNAL in, the (sub)program from which E04NFF/E04NFA is called. Parameters denoted as Input must not be changed by this procedure.

11:   ISTATE($\mathbf{N}+\mathbf{NCLIN}$) – INTEGER arrayInput/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, ISTATE specifies the desired status of the constraints at the start of the feasibility phase. More precisely, the first $n$ elements of ISTATE refer to the upper and lower bounds on the variables, and the next $m_L$ elements refer to the general linear constraints (if any). Possible values for $\mathbf{ISTATE}\left(j\right)$ are as follows:

$\mathbf{ISTATE}\left(j\right)$	Meaning
0	The corresponding constraint should not be in the initial working set.
1	The constraint should be in the initial working set at its lower bound.
2	The constraint should be in the initial working set at its upper bound.
3	The constraint should be in the initial working set as an equality. This value must not be specified unless $\mathbf{BL}\left(j\right)=\mathbf{BU}\left(j\right)$.

The values $-2$, $-1$ and $4$ are also acceptable but will be reset to zero by the routine. If E04NFF/E04NFA has been called previously with the same values of N and NCLIN, ISTATE already contains satisfactory information. (See also the description of the optional parameter Warm Start.) The routine also adjusts (if necessary) the values supplied in X to be consistent with ISTATE.

Constraint: $-2\le \mathbf{ISTATE}\left(\mathit{j}\right)\le 4$, for $\mathit{j}=1,2,\dots ,\mathbf{N}+\mathbf{NCLIN}$.

On exit: the status of the constraints in the working set at the point returned in X. The significance of each possible value of $\mathbf{ISTATE}\left(j\right)$ is as follows:

$\mathbf{ISTATE}\left(j\right)$	Meaning
$-2$	The constraint violates its lower bound by more than the feasibility tolerance.
$-1$	The constraint violates its upper bound by more than the feasibility tolerance.
$\phantom{-}0$	The constraint is satisfied to within the feasibility tolerance, but is not in the working set.
$\phantom{-}1$	This inequality constraint is included in the working set at its lower bound.
$\phantom{-}2$	This inequality constraint is included in the working set at its upper bound.
$\phantom{-}3$	This constraint is included in the working set as an equality. This value of ISTATE can occur only when $\mathbf{BL}\left(j\right)=\mathbf{BU}\left(j\right)$.
$\phantom{-}4$	This corresponds to optimality being declared with $\mathbf{X}\left(j\right)$ being temporarily fixed at its current value. This value of ISTATE can occur only when $\mathbf{IFAIL}=\mathbf{1}$ on exit.

12:   X(N) – REAL (KIND=nag_wp) arrayInput/Output

On entry: an initial estimate of the solution.

On exit: the point at which E04NFF/E04NFA terminated. If $\mathbf{IFAIL}=\mathbf{0}$, $\mathbf{1}$ or $\mathbf{4}$, X contains an estimate of the solution.

13:   ITER – INTEGEROutput

On exit: the total number of iterations performed.

14:   OBJ – REAL (KIND=nag_wp)Output

On exit: the value of the objective function at $x$ if $x$ is feasible, or the sum of infeasibilities at $x$ otherwise. If the problem is of type FP and $x$ is feasible, OBJ is set to zero.

15:   AX($\max \left(1,\mathbf{NCLIN}\right)$) – REAL (KIND=nag_wp) arrayOutput

On exit: the final values of the linear constraints $Ax$.

If $\mathbf{NCLIN}=0$, AX is not referenced.

16:   CLAMDA($\mathbf{N}+\mathbf{NCLIN}$) – REAL (KIND=nag_wp) arrayOutput

On exit: the values of the Lagrange multipliers for each constraint with respect to the current working set. The first $n$ elements contain the multipliers for the bound constraints on the variables, and the next $m_L$ elements contain the multipliers for the general linear constraints (if any). If $\mathbf{ISTATE}\left(j\right)=0$ (i.e., constraint $j$ is not in the working set), $\mathbf{CLAMDA}\left(j\right)$ is zero. If $x$ is optimal, $\mathbf{CLAMDA}\left(j\right)$ should be non-negative if $\mathbf{ISTATE}\left(j\right)=1$, non-positive if $\mathbf{ISTATE}\left(j\right)=2$ and zero if $\mathbf{ISTATE}\left(j\right)=4$.

17:   IWORK(LIWORK) – INTEGER arrayWorkspace

18:   LIWORK – INTEGERInput

On entry: the dimension of the array IWORK as declared in the (sub)program from which E04NFF/E04NFA is called.

Constraint: $\mathbf{LIWORK}\ge 2\times \mathbf{N}+3$.

19:   WORK(LWORK) – REAL (KIND=nag_wp) arrayWorkspace

20:   LWORK – INTEGERInput

On entry: the dimension of the array WORK as declared in the (sub)program from which E04NFF/E04NFA is called.

Constraints:

• if the problem is of type QP2 (the default) or QP4,
  • if $\mathbf{NCLIN}>0$, $\mathbf{LWORK}\ge 2\times {\mathbf{N}}^2+8\times \mathbf{N}+5\times \mathbf{NCLIN}$;
  • if $\mathbf{NCLIN}=0$, $\mathbf{LWORK}\ge {\mathbf{N}}^2+8\times \mathbf{N}$;
• if the problem is of type QP1 or QP3,
  • if $\mathbf{NCLIN}>0$, $\mathbf{LWORK}\ge 2\times {\mathbf{N}}^2+7\times \mathbf{N}+5\times \mathbf{NCLIN}$;
  • if $\mathbf{NCLIN}=0$, $\mathbf{LWORK}\ge {\mathbf{N}}^2+7\times \mathbf{N}$;
• if the problem is of type LP,
  • if $\mathbf{NCLIN}=0$, $\mathbf{LWORK}\ge 8\times \mathbf{N}+1$;
  • if $\mathbf{NCLIN}\ge \mathbf{N}$, $\mathbf{LWORK}\ge 2\times {\mathbf{N}}^2+8\times \mathbf{N}+5\times \mathbf{NCLIN}$;
  • otherwise $\mathbf{LWORK}\ge 2\times {\left(\mathbf{NCLIN}+1\right)}^2+8\times \mathbf{N}+5\times \mathbf{NCLIN}$;
• if the problem is of type FP,
  • if $\mathbf{NCLIN}=0$, $\mathbf{LWORK}\ge 7\times \mathbf{N}+1$;
  • if $\mathbf{NCLIN}\ge \mathbf{N}$, $\mathbf{LWORK}\ge 2\times {\mathbf{N}}^2+7\times \mathbf{N}+5\times \mathbf{NCLIN}$;
  • otherwise $\mathbf{LWORK}\ge 2\times {\left(\mathbf{NCLIN}+1\right)}^2+7\times \mathbf{N}+5\times \mathbf{NCLIN}$.

The amounts of workspace provided and required are (by default) output on the current advisory message unit (as defined by X04ABF). As an alternative to computing LIWORK and LWORK from the formulas given above, you may prefer to obtain appropriate values from the output of a preliminary run with LIWORK and LWORK set to $1$. (E04NFF/E04NFA will then terminate with $\mathbf{IFAIL}=\mathbf{6}$.)

21:   IFAIL – INTEGERInput/Output

Note: for E04NFA, IFAIL does not occur in this position in the parameter list. See the additional parameters described below.

On entry: IFAIL must be set to $0$, $-1\text{ or }1$. If you are unfamiliar with this parameter you should refer to Section 3.3 in the Essential Introduction 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 parameters 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).

E04NFF/E04NFA returns with $\mathbf{IFAIL}=\mathbf{0}$ if $x$ is a strong local minimizer, i.e., the reduced gradient (Norm Gz; see Section 8.2) is negligible, the Lagrange multipliers (Lagr Mult; see Section 8.2) are optimal and $H_R$ (the reduced Hessian of $f\left(x\right)$; see Section 10.2) is positive semidefinite.

Note: the following are additional parameters for specific use with E04NFA. Users of E04NFF therefore need not read the remainder of this description.

21:   IUSER($*$) – INTEGER arrayUser Workspace

22:   RUSER($*$) – REAL (KIND=nag_wp) arrayUser Workspace

IUSER and RUSER are not used by E04NFF/E04NFA, but are passed directly to QPHESS and may be used to pass information to this routine as an alternative to using COMMON global variables.

23:   LWSAV($120$) – LOGICAL arrayCommunication Array

24:   IWSAV($610$) – INTEGER arrayCommunication Array

25:   RWSAV($475$) – REAL (KIND=nag_wp) arrayCommunication Array

The arrays LWSAV, IWSAV and RWSAV must not be altered between calls to any of the routines E04NFA, E04NGA or E04NHA.

26:   IFAIL – INTEGERInput/Output

Note: see the parameter description for IFAIL above.

6  Error Indicators and Warnings

$\mathbf{IFAIL}=1$

The iterations were terminated at a dead-point. The necessary conditions for optimality are satisfied but the sufficient conditions are not. (The reduced gradient is negligible, the Lagrange multipliers are optimal, but $H_R$ is singular or there are some very small multipliers.) If ${\nabla }^{2}f\left(x\right)$ is not positive definite, $x$ is not necessarily a local solution of the problem and verification of optimality requires further information. If ${\nabla }^{2}f\left(x\right)$ is positive semidefinite or the problem is of type LP, $x$ gives the global minimum value of the objective function, but the final $x$ is not unique.

$\mathbf{IFAIL}=2$

The solution appears to be unbounded, i.e., the objective function is not bounded below in the feasible region. This value of IFAIL occurs if a step larger than Infinite Step Size ($\text{default value}={10}^{20}$) would have to be taken in order to continue the algorithm, or the next step would result in an element of $x$ having magnitude larger than Infinite Bound Size ($\text{default value}={10}^{20}$).

$\mathbf{IFAIL}=3$

No feasible point was found, i.e., it was not possible to satisfy all the constraints to within the feasibility tolerance. In this case, the constraint violations at the final $x$ will reveal a value of the tolerance for which a feasible point will exist – for example, when the feasibility tolerance for each violated constraint exceeds its Slack (see Section 8.2) at the final point. The modified problem (with an altered feasibility tolerance) may then be solved using a Warm Start. You should check that there are no constraint redundancies. If the data for the constraints are accurate only to the absolute precision $\sigma$, you should ensure that the value of the optional parameter Feasibility Tolerance ($\text{default value}=\sqrt{\epsilon }$, where $\epsilon$ is the machine precision) is greater than $\sigma$. For example, if all elements of $A$ are of order unity and are accurate only to three decimal places, the Feasibility Tolerance should be at least ${10}^{-3}$.

$\mathbf{IFAIL}=4$

The limiting number of iterations was reached before normal termination occurred.

The values of the optional parameters Feasibility Phase Iteration Limit ($\text{default value}=\max \left(50,5\left(n+m_L\right)\right)$) and Optimality Phase Iteration Limit ($\text{default value}=\max \left(50,5\left(n+m_L\right)\right)$) may be too small. If the method appears to be making progress (e.g., the objective function is being satisfactorily reduced), either increase the iterations limit and rerun E04NFF/E04NFA or, alternatively, rerun E04NFF/E04NFA using the Warm Start facility to specify the initial working set.

$\mathbf{IFAIL}=5$

The reduced Hessian exceeds its assigned dimension. The algorithm needed to expand the reduced Hessian when it was already at its maximum dimension, as specified by the optional parameter Maximum Degrees of Freedom ($\text{default value}=n$).

The value of the optional parameter Maximum Degrees of Freedom is too small. Rerun E04NFF/E04NFA with a larger value (possibly using the Warm Start facility to specify the initial working set).

$\mathbf{IFAIL}=6$

An input parameter is invalid.

$\mathbf{IFAIL}=7$

The designated problem type was not FP, LP, QP1, QP2, QP3 or QP4. Rerun E04NFF/E04NFA with the optional parameter Problem Type set to one of these values.

$\mathbf{\text{Overflow}}$

If the printed output before the overflow error contains a warning about serious ill-conditioning in the working set when adding the $j$th constraint, it may be possible to avoid the difficulty by increasing the magnitude of the Feasibility Tolerance ($\text{default value}=\sqrt{\epsilon }$, where $\epsilon$ is the machine precision) and rerunning the program. If the message recurs even after this change, the offending linearly dependent constraint (with index ‘$j$’) must be removed from the problem.

7  Accuracy

8  Further Comments

8.1  Scaling

8.2  Description of the Printed Output

9  Example

9.1  Program Text

Program Text (e04nffe.f90)

Program Text (e04nfae.f90)

9.2  Program Data

Program Data (e04nffe.d)

Program Data (e04nfae.d)

9.3  Program Results

Program Results (e04nffe.r)

Program Results (e04nfae.r)

10  Algorithmic Details

10.1  Overview

10.2  Definition of Search Direction

10.3  Main Iteration

10.4  Choosing the Initial Working Set

11  Optional Parameters

• Check Frequency
• Cold Start
• Crash Tolerance
• Defaults
• Expand Frequency
• Feasibility Phase Iteration Limit
• Feasibility Tolerance
• Hessian Rows
• Infinite Bound Size
• Infinite Step Size
• Iteration Limit
• Iters
• Itns
• List
• Maximum Degrees of Freedom
• Minimum Sum of Infeasibilities
• Monitoring File
• Nolist
• Optimality Phase Iteration Limit
• Optimality Tolerance
• Print Level
• Problem Type
• Rank Tolerance
• Warm Start

Begin 
  Print Level = 5 
End

 CALL E04NGF (IOPTNS, INFORM)

 CALL E04NHF ('Print Level = 5')

11.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\text{ 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).

12  Description of Monitoring Information