Note:this function usesoptional parametersto define choices in the problem specification and in the details of the algorithm. If you wish to use default settings for all of the optional parameters, you need only read Sections 1 to 10 of this document. If, however, you wish to reset some or all of the settings please refer to Section 11 for a detailed description of the algorithm, to Section 12 for a detailed description of the specification of the optional parameters and to Section 13 for a detailed description of the monitoring information produced by the function.
e04wdc is designed to minimize an arbitrary smooth function subject to constraints (which may include simple bounds on the variables, linear constraints and smooth nonlinear constraints) using a
Sequential Quadratic Programming (SQP)
method. As many first derivatives as possible should be supplied by you; any unspecified derivatives are approximated by finite differences. It is not intended for large sparse problems.
e04wdc may also be used for unconstrained, bound-constrained and linearly constrained optimization.
e04wdc uses forwardcommunication for evaluating the objective function, the nonlinear constraint functions, and any of their derivatives.
The initialization function e04wccmust have been called before to calling e04wdc.
e04wdc is designed to solve nonlinear programming problems – the minimization of a smooth nonlinear function subject to a set of constraints on the variables. e04wdc is suitable for small dense problems. The problem is assumed to be stated in the following form:
$$\underset{x\in {R}^{n}}{\mathrm{minimize}}\phantom{\rule{0.25em}{0ex}}F\left(x\right)\text{\hspace{1em} subject to \hspace{1em}}l\le \left(\begin{array}{c}x\\ {A}_{L}x\\ c\left(x\right)\end{array}\right)\le u\text{,}$$
(1)
where $F\left(x\right)$ (the objective function) is a nonlinear scalar function, ${A}_{L}$ is an ${n}_{L}\times n$ constant matrix, and $c\left(x\right)$ is an ${n}_{N}$-vector of nonlinear constraint functions. (The matrix ${A}_{L}$ and the vector $c\left(x\right)$ may be empty.) The objective function and the constraint functions are assumed to be smooth, here meaning at least twice-continuously differentiable. (The method of e04wdc will usually solve (1) if there are only isolated discontinuities away from the solution.) We also write $r\left(x\right)$ for the vector of combined functions:
Note that although the bounds on the variables could be included in the definition of the linear constraints, we prefer to distinguish between them for reasons of computational efficiency. For the same reason, the linear constraints should not be included in the definition of the nonlinear constraints. Upper and lower bounds are specified for all the variables and for all the constraints. An equality constraint on ${r}_{i}$ can be specified by setting ${l}_{i}={u}_{i}$. If certain bounds are not present, the associated elements of $l$ or $u$ can be set to special values that will be treated as $-\infty $ or $+\infty $. (See the description of the optional parameter ${\mathbf{Infinite\; Bound\; Size}}$.)
where e04wec reads
a file of optional definitions.
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 ${\mathbf{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}$
If there are no nonlinear constraints in (1) and $F$ is linear or quadratic, then it will generally be more efficient to use one of e04mfc,e04nccore04nfc. If the problem is large and sparse and does have nonlinear constraints, then e04vhc should be used, since e04wdc treats all matrices as dense.
You must supply an initial estimate of the solution to (1), together with functions that define $F\left(x\right)$ and $c\left(x\right)$ with as many first partial derivatives as possible; unspecified derivatives are approximated by finite differences; see Section 12.1 for a discussion of the optional parameter ${\mathbf{Derivative\; Level}}$.
The objective function is defined by objfun, and the nonlinear constraints are defined by confun. Note that if there are any nonlinear constraints then the first call to confun will precede the first call to objfun.
For maximum reliability, it is preferable for you to provide all partial derivatives (see Chapter 8 of Gill et al. (1981), for a detailed discussion). If all gradients cannot be provided, it is similarly advisable to provide as many as possible. While developing objfun and confun, the optional parameter ${\mathbf{Verify\; Level}}$ should be used to check the calculation of any known gradients.
The method used by e04wdc is based on NPOPT, which is part of the SNOPT package described in Gill et al. (2005b), and the algorithm it uses is described in detail in Section 11.
4References
Eldersveld S K (1991) Large-scale sequential quadratic programming algorithms PhD Thesis Department of Operations Research, Stanford University, Stanford
Fourer R (1982) Solving staircase linear programs by the simplex method Math. Programming23 274–313
Gill P E, Murray W and Saunders M A (2002) SNOPT: An SQP Algorithm for Large-scale Constrained Optimization12 979–1006 SIAM J. Optim.
Gill P E, Murray W and Saunders M A (2005a) Users' guide for SQOPT 7: a Fortran package for large-scale linear and quadratic programming Report NA 05-1 Department of Mathematics, University of California, San Diego https://www.ccom.ucsd.edu/~peg/papers/sqdoc7.pdf
Gill P E, Murray W and Saunders M A (2005b) Users' guide for SNOPT 7.1: a Fortran package for large-scale linear nonlinear programming Report NA 05-2 Department of Mathematics, University of California, San Diego https://www.ccom.ucsd.edu/~peg/papers/sndoc7.pdf
Gill P E, Murray W, Saunders M A and Wright M H (1986) Users' guide for NPSOL (Version 4.0): a Fortran package for nonlinear programming Report SOL 86-2 Department of Operations Research, Stanford University
Gill P E, Murray W, Saunders M A and Wright M H (1992) Some theoretical properties of an augmented Lagrangian merit function Advances in Optimization and Parallel Computing (ed P M Pardalos) 101–128 North Holland
Gill P E, Murray W and Wright M H (1981) Practical Optimization Academic Press
Hock W and Schittkowski K (1981) Test Examples for Nonlinear Programming Codes. Lecture Notes in Economics and Mathematical Systems187 Springer–Verlag
5Arguments
1: $\mathbf{n}$ – IntegerInput
On entry: $n$, the number of variables.
Constraint:
${\mathbf{n}}>0$.
2: $\mathbf{nclin}$ – IntegerInput
On entry: ${n}_{L}$, the number of general linear constraints.
Constraint:
${\mathbf{nclin}}\ge 0$.
3: $\mathbf{ncnln}$ – IntegerInput
On entry: ${n}_{N}$, the number of nonlinear constraints.
Constraint:
${\mathbf{ncnln}}\ge 0$.
4: $\mathbf{tda}$ – IntegerInput
On entry: the stride separating matrix column elements in the array a.
Constraints:
if ${\mathbf{nclin}}>0$,
${\mathbf{tda}}\ge {\mathbf{n}}$;
otherwise ${\mathbf{tda}}\ge 1$.
5: $\mathbf{tdcj}$ – IntegerInput
On entry: the stride separating matrix column elements in the array cjac.
Constraints:
if ${\mathbf{ncnln}}>0$,
${\mathbf{tdcj}}\ge {\mathbf{n}}$;
otherwise ${\mathbf{tdcj}}\ge 1$.
6: $\mathbf{tdh}$ – IntegerInput
On entry: the stride separating matrix column elements in the array h.
Constraint:
${\mathbf{tdh}}\ge {\mathbf{n}}$ unless the optional parameter ${\mathbf{Hessian\; Limited\; Memory}}$ is in effect. If ${\mathbf{Hessian\; Limited\; Memory}}$ is in effect, array h is not referenced
Note: the dimension, dim, of the array a
must be at least
$\mathrm{max}\phantom{\rule{0.125em}{0ex}}(1,{\mathbf{nclin}}\times {\mathbf{tda}})$.
The $(i,j)$th element of the matrix $A$ is stored in ${\mathbf{a}}\left[(i-1)\times {\mathbf{tda}}+j-1\right]$.
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.
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-1\right]\le -\mathit{bigbnd}$, and to specify a nonexistent upper bound (i.e., ${u}_{j}=+\infty $), set ${\mathbf{bu}}\left[j-1\right]\ge \mathit{bigbnd}$; where $\mathit{bigbnd}$ is the optional parameter ${\mathbf{Infinite\; Bound\; Size}}$. To specify the $j$th constraint as an equality, set ${\mathbf{bl}}\left[j-1\right]={\mathbf{bu}}\left[j-1\right]=\beta $, say, where $\left|\beta \right|<\mathit{bigbnd}$.
Constraints:
${\mathbf{bl}}\left[\mathit{j}-1\right]\le {\mathbf{bu}}\left[\mathit{j}-1\right]$, for $\mathit{j}=1,2,\dots ,{\mathbf{n}}+{\mathbf{nclin}}+{\mathbf{ncnln}}$;
if ${\mathbf{bl}}\left[j-1\right]={\mathbf{bu}}\left[j-1\right]=\beta $, $\left|\beta \right|<\mathit{bigbnd}$.
10: $\mathbf{confun}$ – function, supplied by the userExternal Function
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$), e04wdc will never call confun, so it may be specified as NULLFN. 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.
On entry: is set by e04wdc 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-1\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$, e04wdc 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}$ – IntegerInput
On entry: ${n}_{N}$, the number of nonlinear constraints.
On entry: the indices of the elements of ccon and/or cjac that must be evaluated by confun. If ${\mathbf{needc}}\left[i-1\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$.
On exit: if ${\mathbf{needc}}\left[i-1\right]>0$ and ${\mathbf{mode}}=0$ or $2$, ${\mathbf{ccon}}\left[i-1\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.
On entry: the elements of cjac are set to special values that enable e04wdc to detect whether they are reset by confun.
On exit: if ${\mathbf{needc}}\left[i-1\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
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}}\left[\left(i-1\right)\times {\mathbf{tdcj}}+j-1\right]$ is set to a constant value, it need not be reset in subsequent calls to confun, but the value ${\mathbf{cjac}}\left[\left(i-1\right)\times {\mathbf{tdcj}}+j-1\right]\times {\mathbf{x}}\left[j-1\right]$ must nonetheless be added to ${\mathbf{ccon}}\left[i-1\right]$. For example, if ${\mathbf{cjac}}\left[0\right]=2$ and ${\mathbf{cjac}}\left[1\right]=-5$, then the term $2\times {\mathbf{x}}\left[0\right]-5\times {\mathbf{x}}\left[1\right]$ must be included in the definition of ${\mathbf{ccon}}\left[0\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 ${\mathbf{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}$ – IntegerInput
On entry: if ${\mathbf{nstate}}=1$, then e04wdc 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{comm}$ – Nag_Comm *
Pointer to structure of type Nag_Comm; the following members are relevant to confun.
user – double *
iuser – Integer *
p – Pointer
The type Pointer will be void *. Before calling e04wdc you may allocate memory and initialize these pointers with various quantities for use by confun when called from e04wdc (see Section 3.1.1 in the Introduction to the NAG Library CL Interface).
Note:confun should not return floating-point NaN (Not a Number) or infinity values, since these are not handled by e04wdc. If your code inadvertently does return any NaNs or infinities, e04wdc is likely to produce unexpected results.
confun should be tested separately before being used in conjunction with e04wdc. See also the description of the optional parameter ${\mathbf{Verify\; Level}}$.
11: $\mathbf{objfun}$ – function, supplied by the userExternal Function
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$.
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$, e04wdc 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$.
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-1\right]$ contains the partial derivative $\frac{\partial F}{\partial {x}_{i}}$.
6: $\mathbf{nstate}$ – IntegerInput
On entry: if ${\mathbf{nstate}}=1$, then e04wdc 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{comm}$ – Nag_Comm *
Pointer to structure of type Nag_Comm; the following members are relevant to objfun.
user – double *
iuser – Integer *
p – Pointer
The type Pointer will be void *. Before calling e04wdc you may allocate memory and initialize these pointers with various quantities for use by objfun when called from e04wdc (see Section 3.1.1 in the Introduction to the NAG Library CL Interface).
Note:objfun should not return floating-point NaN (Not a Number) or infinity values, since these are not handled by e04wdc. If your code inadvertently does return any NaNs or infinities, e04wdc is likely to produce unexpected results.
objfun should be tested separately before being used in conjunction with e04wdc. See also the description of the optional parameter ${\mathbf{Verify\; Level}}$.
12: $\mathbf{majits}$ – Integer *Output
On exit: the number of major iterations performed.
On entry: is an integer array that need not be initialized if e04wdc is called with the ${\mathbf{Cold\; Start}}$ option (the default).
If optional parameter ${\mathbf{Warm\; Start}}$ has been chosen, every element of istate must be set. If e04wdc has just been called on a problem with the same dimensions, istate already contains valid values. Otherwise, ${\mathbf{istate}}\left[j-1\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-1\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-1\right]={\mathbf{bu}}\left[j-1\right]$. If necessary, e04wdc 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-1\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
On entry: ccon need not be initialized if the (default) optional parameter ${\mathbf{Cold\; Start}}$ is used.
For a ${\mathbf{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 e04wdc.
On exit: if ${\mathbf{ncnln}}>0$,
${\mathbf{ccon}}\left[\mathit{i}-1\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.
Note: the dimension, dim, of the array cjac
must be at least
$\mathrm{max}\phantom{\rule{0.125em}{0ex}}(1,{\mathbf{ncnln}}\times {\mathbf{tdcj}})$.
On entry: in general, cjac need not be initialized before the call to e04wdc. 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}}\left[\left(\mathit{i}-1\right)\times {\mathbf{tdcj}}+\mathit{j}-1\right]$ 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.
On entry: need not be set if the (default) optional parameter ${\mathbf{Cold\; Start}}$ is used.
If the optional parameter ${\mathbf{Warm\; Start}}$ has been chosen,
${\mathbf{clamda}}\left[\mathit{j}-1\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-1\right]=0$), ${\mathbf{clamda}}\left[j-1\right]$ should be zero; if the $j$th constraint is an inequality active at its lower bound (i.e., ${\mathbf{istate}}\left[j-1\right]=1$), ${\mathbf{clamda}}\left[j-1\right]$ should be non-negative; if the $j$th constraint is an inequality active at its upper bound (i.e., ${\mathbf{istate}}\left[j-1\right]=2$), ${\mathbf{clamda}}\left[j-1\right]$ should be non-positive. If necessary, the function will modify clamda to match these rules.
On exit: the values of the QP multipliers from the last QP subproblem. ${\mathbf{clamda}}\left[j-1\right]$ should be non-negative if ${\mathbf{istate}}\left[j-1\right]=1$ and non-positive if ${\mathbf{istate}}\left[j-1\right]=2$.
17: $\mathbf{objf}$ – double *Output
On exit: the value of the objective function at the final iterate.
Note: the dimension, dim, of the array h
must be at least
${\mathbf{n}}\times {\mathbf{tdh}}$.
On entry: h need not be initialized if the (default) optional parameter ${\mathbf{Cold\; Start}}$ is used, and will be set to the identity.
If the optional parameter ${\mathbf{Warm\; Start}}$ has been chosen, h provides the initial approximation of the Hessian of the Lagrangian, i.e., ${\mathbf{h}}\left[\left(i-1\right)\times {\mathbf{tdh}}+j-1\right]\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$.
state contains internal information required for functions in this suite. It must not be modified in any way.
22: $\mathbf{comm}$ – Nag_Comm *
The NAG communication argument (see Section 3.1.1 in the Introduction to the NAG Library CL Interface).
23: $\mathbf{fail}$ – NagError *Input/Output
The NAG error argument (see Section 7 in the Introduction to the NAG Library CL Interface).
e04wdc returns with ${\mathbf{fail}}\mathbf{.}\mathbf{code}=$ NE_NOERROR 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 ${\mathbf{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:
(i)the final value of rgNorm (see Section 13.2) is significantly less than that at the starting point;
(ii)during the final major iterations, the values of Step and Minors (see Section 13.1) are both one;
(iii)the last few values of both rgNorm and SumInf (see Section 13.2) become small at a fast linear rate; and
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 ${\mathbf{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
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 ${\mathbf{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 ${\mathbf{Major\; Feasibility\; Tolerance}}$.
6Error Indicators and Warnings
NE_ALLOC_FAIL
Dynamic memory allocation failed.
See Section 3.1.2 in the Introduction to the NAG Library CL Interface for further information.
Internal error: memory allocation failed when attempting to allocate workspace sizes $\u27e8\mathit{\text{value}}\u27e9$ and $\u27e8\mathit{\text{value}}\u27e9$. Please contact NAG.
NE_ALLOC_INSUFFICIENT
Internal memory allocation was insufficient. Please contact NAG.
NE_BAD_PARAM
Basis file dimensions do not match this problem.
On entry, argument $\u27e8\mathit{\text{value}}\u27e9$ had an illegal value.
NE_BASIS_FAILURE
An error has occurred in the basis package, perhaps indicating incorrect setup of arrays. Set the optional parameter ${\mathbf{Print\; File}}$ and examine the output carefully for further information.
NE_DERIV_ERRORS
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-1$ 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 e04wdc 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{fail}}\mathbf{.}\mathbf{code}=$NE_NUM_DIFFICULTIES.
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-1\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.
NE_E04WCC_NOT_INIT
The initialization function e04wcc has not been called.
NE_INT
On entry, ${\mathbf{n}}=\u27e8\mathit{\text{value}}\u27e9$.
Constraint: ${\mathbf{n}}>0$.
On entry, ${\mathbf{nclin}}=\u27e8\mathit{\text{value}}\u27e9$.
Constraint: ${\mathbf{nclin}}\ge 0$.
On entry, ${\mathbf{ncnln}}=\u27e8\mathit{\text{value}}\u27e9$.
Constraint: ${\mathbf{ncnln}}\ge 0$.
On entry, ${\mathbf{tda}}=\u27e8\mathit{\text{value}}\u27e9$. Constraint: ${\mathbf{tda}}>0$.
On entry, ${\mathbf{tdcj}}=\u27e8\mathit{\text{value}}\u27e9$. Constraint: ${\mathbf{tdcj}}>0$.
On entry, ${\mathbf{tdh}}=\u27e8\mathit{\text{value}}\u27e9$. Constraint: ${\mathbf{tdh}}>0$.
NE_INT_2
On entry, ${\mathbf{nclin}}=\u27e8\mathit{\text{value}}\u27e9$ and ${\mathbf{n}}=\u27e8\mathit{\text{value}}\u27e9$.
Constraint: ${\mathbf{n}}>0$.
On entry, ${\mathbf{ncnln}}=\u27e8\mathit{\text{value}}\u27e9$ and ${\mathbf{n}}=\u27e8\mathit{\text{value}}\u27e9$.
Constraint: ${\mathbf{n}}>0$.
On entry, ${\mathbf{tda}}=\u27e8\mathit{\text{value}}\u27e9$ and ${\mathbf{nclin}}=\u27e8\mathit{\text{value}}\u27e9$.
Constraint: ${\mathbf{tda}}\ge {\mathbf{nclin}}$.
On entry, ${\mathbf{tdcj}}=\u27e8\mathit{\text{value}}\u27e9$ and ${\mathbf{ncnln}}=\u27e8\mathit{\text{value}}\u27e9$.
Constraint: ${\mathbf{tdcj}}\ge {\mathbf{ncnln}}$.
On entry, ${\mathbf{tdh}}=\u27e8\mathit{\text{value}}\u27e9$ and ${\mathbf{n}}=\u27e8\mathit{\text{value}}\u27e9$.
Constraint: ${\mathbf{tdh}}\ge {\mathbf{n}}$.
NE_INT_3
On entry, ${\mathbf{tda}}=\u27e8\mathit{\text{value}}\u27e9$, ${\mathbf{nclin}}=\u27e8\mathit{\text{value}}\u27e9$ and ${\mathbf{n}}=\u27e8\mathit{\text{value}}\u27e9$.
Constraint: if ${\mathbf{nclin}}>0$,
${\mathbf{tda}}\ge {\mathbf{n}}$; otherwise ${\mathbf{tda}}\ge 1$.
On entry, ${\mathbf{tdcj}}=\u27e8\mathit{\text{value}}\u27e9$, ${\mathbf{ncnln}}=\u27e8\mathit{\text{value}}\u27e9$ and ${\mathbf{n}}=\u27e8\mathit{\text{value}}\u27e9$.
Constraint: if ${\mathbf{ncnln}}>0$,
${\mathbf{tdcj}}\ge {\mathbf{n}}$; otherwise ${\mathbf{tdcj}}\ge 1$.
NE_INTERNAL_ERROR
An internal error has occurred in this function. Check the function call and any array sizes. If the call is correct then please contact NAG for assistance.
See Section 7.5 in the Introduction to the NAG Library CL Interface for further information.
An unexpected error has occurred. Set the optional parameter ${\mathbf{Print\; File}}$ and examine the output carefully for further information.
NE_NO_LICENCE
Your licence key may have expired or may not have been installed correctly.
See Section 8 in the Introduction to the NAG Library CL Interface for further information.
NE_NOT_REQUIRED_ACC
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 e04wdc is within ${10}^{-2}$ of satisfying the ${\mathbf{Major\; Optimality\; Tolerance}}$. Check that the ${\mathbf{Major\; Optimality\; Tolerance}}$ is not too small.
NE_NUM_DIFFICULTIES
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.The user-supplied functions 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{fail}}\mathbf{.}\mathbf{code}=$NE_DERIV_ERRORS, and do your best to ensure that the coding is correct.
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 ${\mathbf{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.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
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.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 ${\mathbf{LU\; Factor\; Tolerance}}$ to $2.0$ (or possibly even smaller, but not less than $1.0$).
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 ${\mathbf{LU\; Factor\; Tolerance}}$ is too much larger than $1.0$. This is highly unlikely to occur.
NE_REAL_2
On entry, bounds bl and bu for $\u27e8\mathit{\text{value}}\u27e9$ are equal and infinite. ${\mathbf{bl}}={\mathbf{bu}}=\u27e8\mathit{\text{value}}\u27e9$ and $\mathit{bigbnd}=\u27e8\mathit{\text{value}}\u27e9$.
On entry, bounds for $\u27e8\mathit{\text{value}}\u27e9$ are inconsistent. ${\mathbf{bl}}=\u27e8\mathit{\text{value}}\u27e9$ and ${\mathbf{bu}}=\u27e8\mathit{\text{value}}\u27e9$.
NE_UNBOUNDED
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 ${\mathbf{Scale\; Option}}$.
For nonlinear problems, e04wdc 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 ${\mathbf{Violation\; Limit}}$.
NE_USER_STOP
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.
NE_USRFUN_UNDEFINED
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. e04wdc attempts to evaluate the problem functions closer to a point at which the functions are already known to be defined. This exit occurs if e04wdc 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.
NW_LIMIT_REACHED
Iteration limit reached.
Major iteration limit reached.
The value of the optional parameter ${\mathbf{Superbasics\; Limit}}$ is too small.
Either the ${\mathbf{Iterations\; Limit}}$ or the ${\mathbf{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 ${\mathbf{New\; Basis\; File}}$, consider restarting the run using the optional parameter ${\mathbf{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 ${\mathbf{Minor\; Iterations\; Limit}}$ and/or ${\mathbf{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 ${\mathbf{Superbasics\; Limit}}$. In general, raise the ${\mathbf{Superbasics\; Limit}}$$s$ by a reasonable amount, bearing in mind the storage needed for the reduced Hessian. (The ${\mathbf{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.
NW_NOT_FEASIBLE
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 ${\mathbf{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, e04wdc 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), e04wdc 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 ${\mathbf{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, e04wdc will tend to determine a ‘good’ infeasible point if the elastic weight is sufficiently large. (If the elastic weight were infinite, e04wdc would locally minimize the nonlinear constraint violations subject to the linear constraints and bounds.)
Unfortunately, even though e04wdc 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.
7Accuracy
If ${\mathbf{fail}}\mathbf{.}\mathbf{code}=$ NE_NOERROR on exit, then the vector returned in the array x is an estimate of the solution to an accuracy of approximately ${\mathbf{Major\; Optimality\; Tolerance}}$.
8Parallelism and Performance
e04wdc makes calls to BLAS and/or LAPACK routines, which may be threaded within the vendor library used by this implementation. Consult the documentation for the vendor library for further information.
Please consult the X06 Chapter Introduction for information on how to control and interrogate the OpenMP environment used within this function. Please also consult the Users' Note for your implementation for any additional implementation-specific information.
9Further Comments
This section describes the final output produced by e04wdc. Intermediate and other output are given in Section 13.
9.1The Final Output
If ${\mathbf{Print\; File}}=0$,
the final output, including a listing of the status of every variable and constraint will be sent to the ${\mathbf{Print\; File}}$. The following describes the output for each variable. A full stop (.) is printed for any numerical value that is zero.
Variable
gives the name (Variable) and index $\mathit{j}$, for $\mathit{j}=1,2,\dots ,n$, of the variable.
State
gives the state of the variable (FR if neither bound is in the working set, EQ if a fixed variable, LL if on its lower bound, UL if on its upper bound, TF if temporarily fixed at its current value). If Value lies outside the upper or lower bounds by more than the ${\mathbf{Feasibility\; Tolerance}}$, State will be ++ or -- respectively.
(The latter situation can occur only when there is no feasible point for the bounds and linear constraints.)
A key is sometimes printed before State.
A
Alternative optimum possible. The variable is active at one of its bounds, but its Lagrange multiplier is essentially zero. This means that if the variable were allowed to start moving away from its bound then there would be no change to the objective function. The values of the other free variables might change, giving a genuine alternative solution. However, if there are any degenerate variables (labelled D), the actual change might prove to be zero, since one of them could encounter a bound immediately. In either case the values of the Lagrange multipliers might also change.
D
Degenerate. The variable is free, but it is equal to (or very close to) one of its bounds.
I
Infeasible. The variable is currently violating one of its bounds by more than the ${\mathbf{Feasibility\; Tolerance}}$.
Value
is the value of the variable at the final iteration.
Lower bound
is the lower bound specified for the variable. None indicates that ${\mathbf{bl}}\left[j-1\right]\le -\mathit{bigbnd}$.
Upper bound
is the upper bound specified for the variable. None indicates that ${\mathbf{bu}}\left[j-1\right]\ge \mathit{bigbnd}$.
Lagr multiplier
is the Lagrange multiplier for the associated bound. This will be zero if State is FR unless ${\mathbf{bl}}\left[j-1\right]\le -\mathit{bigbnd}$ and ${\mathbf{bu}}\left[j-1\right]\ge \mathit{bigbnd}$, in which case the entry will be blank. If $x$ is optimal, the multiplier should be non-negative if State is LL and non-positive if State is UL.
Slack
is the difference between the variable Value and the nearer of its (finite) bounds ${\mathbf{bl}}\left[j-1\right]$ and ${\mathbf{bu}}\left[j-1\right]$. A blank entry indicates that the associated variable is not bounded (i.e., ${\mathbf{bl}}\left[j-1\right]\le -\mathit{bigbnd}$ and ${\mathbf{bu}}\left[j-1\right]\ge \mathit{bigbnd}$).
The meaning of the output for linear and nonlinear constraints is the same as that given above for variables, with ${\mathbf{bl}}\left[j-1\right]$ and ${\mathbf{bu}}\left[j-1\right]$ replaced by ${\mathbf{bl}}\left[n+j-1\right]$ and ${\mathbf{bu}}\left[n+j-1\right]$ respectively, and with the following changes in the heading:
Linear constrnt
gives the name (lincon) and index $\mathit{j}$, for $\mathit{j}=1,2,\dots ,{n}_{L}$, of the linear constraint.
Nonlin constrnt
gives the name (nlncon) and index ($\mathit{j}-{n}_{L}$), for $\mathit{j}={n}_{L}+1,\dots ,{n}_{L}+{n}_{N}$, of the nonlinear constraint.
Note that movement off a constraint (as opposed to a variable moving away from its bound) can be interpreted as allowing the entry in the Slack column to become positive.
Numerical values are output with a fixed number of digits; they are not guaranteed to be accurate to this precision.
10Example
This example is based on Problem 71 in Hock and Schittkowski (1981) and involves the minimization of the nonlinear function
Note: the remainder of this document is intended for more advanced users. Section 11 contains a detailed description of the algorithm which may be needed in order to understand Sections 12 and 13. Section 12 describes the optional parameters which may be set by calls to e04wfc,e04wgcand/ore04whc. Section 13 describes the quantities which can be requested to monitor the course of the computation.
11Algorithmic Details
Here we summarise the main features of the SQP algorithm used in e04wdc and introduce some terminology used in the description of the function and its arguments. The SQP algorithm is fully described in Gill et al. (2002).
11.1Constraints and Slack Variables
The upper and lower bounds on the ${n}_{L}+{n}_{N}$ components of $\left(\begin{array}{c}{A}_{L}x\\ c\left(x\right)\end{array}\right)$ are said to define the general constraints of the problem. e04wdc converts the general constraints to equalities by introducing a set of slack variables$s={({s}_{1},{s}_{2},\dots ,{s}_{{n}_{L}+{n}_{N}})}^{\mathrm{T}}$. For example, the linear constraint $5\le 2{x}_{1}+3{x}_{2}\le \infty $ is replaced by $2{x}_{1}+3{x}_{2}-{s}_{1}=0$ together with the bounded slack $5\le {s}_{1}\le \infty $. The minimization problem (1) can, therefore, be written in the equivalent form
The general constraints become the equalities ${A}_{L}x-{s}_{L}=0$ and $c\left(x\right)-{s}_{N}=0$, where ${s}_{L}$ and ${s}_{N}$ are the linear and nonlinear slacks.
11.2Major Iterations
The basic structure of the SQP algorithm involves major and minor iterations. The major iterations generate a sequence of iterates $\left\{{x}_{k}\right\}$ that satisfy the linear constraints and converge to a point that satisfies the nonlinear constraints and the first-order conditions for optimality. At each iterate ${x}_{k}$ a QP subproblem is used to generate a search direction towards the next iterate ${x}_{k+1}$. The constraints of the subproblem are formed from the linear constraints ${A}_{L}x-{s}_{L}=0$ and the linearized constraint
where ${c}^{\prime}\left({x}_{k}\right)$ denotes the Jacobian matrix, whose elements are the first derivatives of $c\left(x\right)$ evaluated at ${x}_{k}$. The QP constraints, therefore, comprise the ${n}_{L}+{n}_{N}$ linear constraints
where $x$ and $s$ are bounded above and below by $u$ and $l$ as before. If the $({n}_{L}+{n}_{N})\times n$ matrix $A$ and $({n}_{L}+{n}_{N})$-vector $b$ are defined as
where $q(x,{x}_{k})$ is a quadratic approximation to a modified Lagrangian function (see Gill et al. (2002)). The matrix ${H}_{k}$ is a quasi-Newton approximation to the Hessian of the Lagrangian. A BGFS update is applied after each major iteration. If some of the variables enter the Lagrangian linearly the Hessian will have some zero rows and columns. If the nonlinear variables appear first, then only the leading ${n}_{N}$ rows and columns of the Hessian need to be approximated.
11.3Minor Iterations
Solving the QP subproblem is itself an iterative procedure. Here, the iterations of the QP solver e04nqc form the minor iterations of the SQP method. e04nqc uses a reduced-Hessian active-set method implemented as a reduced-gradient method. At each minor iteration, the constraints $Ax-s=b$ are partitioned into the form
$$B{x}_{B}+S{x}_{S}+N{x}_{N}=b\text{,}$$
(7)
where the basis matrix$B$ is square and nonsingular, and the matrices $S$ and $N$ are the remaining columns of $\left(\begin{array}{cc}A& -I\end{array}\right)$. The vectors ${x}_{B}$, ${x}_{S}$ and ${x}_{N}$ are the associated basic, superbasic and nonbasic variables respectively; they are a permutation of the elements of $x$ and $s$. At a QP subproblem, the basic and superbasic variables will lie somewhere between their bounds, while the nonbasic variables will normally be equal to one of their bounds. At each iteration, ${x}_{S}$ is regarded as a set of independent variables that are free to move in any desired direction, namely one that will improve the value of the QP objective (or the sum of infeasibilities). The basic variables are then adjusted in order to ensure that $(x,s)$ continues to satisfy $Ax-s=b$. The number of superbasic variables (${n}_{S}$, say), therefore, indicates the number of degrees of freedom remaining after the constraints have been satisfied. In broad terms, ${n}_{S}$ is a measure of how nonlinear the problem is. In particular, ${n}_{S}$ will always be zero for LP problems.
If it appears that no improvement can be made with the current definition of $B$, $S$ and $N$, a nonbasic variable is selected to be added to $S$, and the process is repeated with the value of ${n}_{S}$ increased by one. At all stages, if a basic or superbasic variable encounters one of its bounds, the variable is made nonbasic and the value of ${n}_{S}$ is decreased by one.
Associated with each of the ${n}_{L}+{n}_{N}$ equality constraints $Ax-s=b$ are the dual variables$\pi $. Similarly, each variable in $(x,s)$ has an associated reduced gradient${d}_{j}$. The reduced gradients for the variables $x$ are the quantities $g-{A}^{\mathrm{T}}\pi $, where $g$ is the gradient of the QP objective, and the reduced gradients for the slacks are the dual variables $\pi $. The QP subproblem is optimal if ${d}_{j}\ge 0$ for all nonbasic variables at their lower bounds, ${d}_{j}\le 0$ for all nonbasic variables at their upper bounds, and ${d}_{j}=0$ for other variables, including superbasics. In practice, an approximate QP solution $({\hat{x}}_{k},{\hat{s}}_{k},{\hat{\pi}}_{k})$ is found by relaxing these conditions.
11.4The Merit Function
After a QP subproblem has been solved, new estimates of the solution are computed using a linesearch on the augmented Lagrangian merit function
where $D$ is a diagonal matrix of penalty parameters $({D}_{ii}\ge 0)$, and $\pi $ now refers to dual variables for the nonlinear constraints in (1). If $({x}_{k},{s}_{k},{\pi}_{k})$ denotes the current solution estimate and $({\hat{x}}_{k},{\hat{s}}_{k},{\hat{\pi}}_{k})$ denotes the QP solution, the linesearch determines a step ${\alpha}_{k}$$(0<{\alpha}_{k}\le 1)$ such that the new point
gives a sufficient decrease in the merit function $\mathcal{M}$. When necessary, the penalties in $D$ are increased by the minimum-norm perturbation that ensures descent for $\mathcal{M}$ (see Gill et al. (1992)). The value of ${s}_{N}$ is adjusted to minimize the merit function as a function of $s$ before the solution of the QP subproblem (see Gill et al. (1986) and Eldersveld (1991)).
11.5Treatment of Constraint Infeasibilities
e04wdc makes explicit allowance for infeasible constraints. First, infeasible linear constraints are detected by solving the linear program
where $e$ is a vector of ones, and the nonlinear constraint bounds are temporarily excluded from $l$ and $u$. This is equivalent to minimizing the sum of the general linear constraint violations subject to the bounds on $x$. (The sum is the ${\ell}_{1}$-norm of the linear constraint violations. In the linear programming literature, the approach is called elastic programming.)
The linear constraints are infeasible if the optimal solution of (10) has $v\ne 0$ or $w\ne 0$. e04wdc then terminates without computing the nonlinear functions.
Otherwise, all subsequent iterates satisfy the linear constraints. (Such a strategy allows linear constraints to be used to define a region in which the functions can be safely evaluated.) e04wdc proceeds to solve nonlinear problems as given, using search directions obtained from the sequence of QP subproblems (see (6)).
If a QP subproblem proves to be infeasible or unbounded (or if the dual variables $\pi $ for the nonlinear constraints become large), e04wdc enters ‘elastic’ mode and thereafter solves the problem
where $\gamma $ is a non-negative argument (the elastic weight), and $F\left(x\right)+\gamma {e}^{\mathrm{T}}(v+w)$ is called a composite objective (the ${\ell}_{1}$ penalty function for the nonlinear constraints).
The value of $\gamma $ may increase automatically by multiples of $10$ if the optimal $v$ and $w$ continue to be nonzero. If $\gamma $ is sufficiently large, this is equivalent to minimizing the sum of the nonlinear constraint violations subject to the linear constraints and bounds.
The initial value of $\gamma $ is controlled by the optional parameter ${\mathbf{Elastic\; Weight}}$.
12Optional Parameters
Several optional parameters in e04wdc define choices in the problem specification or the algorithm logic. In order to reduce the number of formal arguments of e04wdc these optional parameters have associated default values that are appropriate for most problems. Therefore, you need only specify those optional parameters whose values are to be different from their default values.
The remainder of this section can be skipped if you wish to use the default values for all optional parameters.
The following is a list of the optional parameters available. A full description of each optional parameter is provided in Section 12.1.
Optional parameters may be specified by calling one, or more, of the functions
e04wec,e04wfcande04wgc
before a call to e04wdc.
e04wec reads options from an external options file, with Begin and End as the first and last lines respectively and each intermediate line defining a single optional parameter. For example,
Begin
Print Level = 5
End
The call
nag_opt_nlp2_option_file(ioptns, &state, &fail);
can then be used to read the file on
the descriptor ioptns as returned by a call of x04acc. ${\mathbf{fail}}\mathbf{.}\mathbf{code}=$ NE_NOERROR
on successful exit. e04wec should be consulted for a full description of this method of supplying optional parameters.
e04wfc,e04wgcore04whc can be called to supply options directly, one call being necessary for each optional parameter. e04wfc,e04wgcore04whc should be consulted for a full description of this method of supplying optional parameters.
All optional parameters not specified by you are set to their default values. Optional parameters specified by you are unaltered by e04wdc (unless they define invalid values) and so remain in effect for subsequent calls to e04wdc, unless altered by you.
12.1Description of the Optional Parameters
For each option, we give a summary line, a description of the optional parameter and details of constraints.
The summary line contains:
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 X02AJC), and ${\epsilon}_{r}$ denotes the relative precision of the objective function ${\mathbf{Function\; Precision}}$, and $\mathit{bigbnd}$ signifies the value of ${\mathbf{Infinite\; Bound\; Size}}$.
Keywords and character values are case and white space insensitive.
Optional parameters used to specify files (e.g., optional parameters ${\mathbf{Dump\; File}}$ and ${\mathbf{Print\; File}}$) have type Nag_FileID (see Section 3.1.1 in the Introduction to the NAG Library CL Interface). This ID value must either be set to $0$ (the default value) in which case there will be no output, or will be as returned by a call of x04acc.
Central Difference Interval
$r$
Default $\text{}={\epsilon}_{r}^{\frac{1}{3}}$
When ${\mathbf{Derivative\; Level}}<3$, the central-difference interval $r$ is used near an optimal solution to obtain more accurate (but more expensive) estimates of gradients. Twice as many function evaluations are required compared to forward differencing. The interval used for the $j$th variable is ${h}_{j}=r(1+\left|{x}_{j}\right|)$. The resulting derivative estimates should be accurate to $\mathit{O}\left({r}^{2}\right)$, unless the functions are badly scaled.
If you supply a value for this optional parameter, a small value between $0.0$ and $1.0$ is appropriate.
Check Frequency
$i$
Default $\text{}=60$
Every $i$th minor iteration after the most recent basis factorization, a numerical test is made to see if the current solution $x$ satisfies the general linear constraints (the linear constraints and the linearized nonlinear constraints, if any). The constraints are of the form $Ax-s=b$, where $s$ is the set of slack variables. To perform the numerical test, the residual vector $r=b-Ax+s$ is computed. If the largest component of $r$ is judged to be too large, the current basis is refactorized and the basic variables are recomputed to satisfy the general constraints more accurately. If $i\le 0$, the value of $i=99999999$ is used and effectively no checks are made.
${\mathbf{Check\; Frequency}}=1$ is useful for debugging purposes, but otherwise this option should not be needed.
Cold Start
Default
Warm Start
This option controls the specification of the initial working set in the procedure for finding a feasible point for the linear constraints and bounds and in the first QP subproblem thereafter. With a ${\mathbf{Cold\; Start}}$, the first working set is chosen by e04wdc based on the values of the variables and constraints at the initial point. Broadly speaking, the initial working set will include equality constraints and bounds or inequality constraints that violate or ‘nearly’ satisfy their bounds (to within ${\mathbf{Crash\; Tolerance}}$).
With a ${\mathbf{Warm\; Start}}$, you must set the istate array and define clamda and h as discussed in Section 5. istate values associated with bounds and linear constraints determine the initial working set of the procedure to find a feasible point with respect to the bounds and linear constraints. istate values associated with nonlinear constraints determine the initial working set of the first QP subproblem after such a feasible point has been found. e04wdc will override your specification of istate if necessary, so that a poor choice of the working set will not cause a fatal error. For instance, any elements of istate which are set to $-2$, $-1$ or $4$ will be reset to zero, as will any elements which are set to $3$ when the corresponding elements of bl and bu are not equal. A warm start will be advantageous if a good estimate of the initial working set is available – for example, when e04wdc is called repeatedly to solve related problems.
Crash Option
$i$
Default $\text{}=3$
Crash Tolerance
$r$
Default $\text{}=0.1$
If a ${\mathbf{Cold\; Start}}$ is specified, an internal Crash procedure is used to select an initial basis from certain rows and columns of the constraint matrix $\left(\begin{array}{cc}A& -I\end{array}\right)$. The optional parameter ${\mathbf{Crash\; Option}}$$i$ determines which rows and columns of $A$ are eligible initially, and how many times the Crash procedure is called. Columns of $-I$ are used to pad the basis where necessary.
$\mathit{i}$
Meaning
$0$
The initial basis contains only slack variables: $B=I$.
$1$
The Crash procedure is called once, looking for a triangular basis in all rows and columns of $A$.
$2$
The Crash procedure is called twice (if there are nonlinear constraints). The first call looks for a triangular basis in linear rows, and the iteration proceeds with simplex iterations until the linear constraints are satisfied. The Jacobian is then evaluated for the first major iteration and the Crash procedure is called again to find a triangular basis in the nonlinear rows (retaining the current basis for linear rows).
$3$
The Crash procedure is called up to three times (if there are nonlinear constraints). The first two calls treat linear equalities and linear inequalities separately. As before, the last call treats nonlinear rows before the first major iteration.
If $i\ge 1$, certain slacks on inequality rows are selected for the basis first. (If $i\ge 2$, numerical values are used to exclude slacks that are close to a bound). The Crash procedure then makes several passes through the columns of $A$, searching for a basis matrix that is essentially triangular. A column is assigned to ‘pivot’ on a particular row if the column contains a suitably large element in a row that has not yet been assigned. (The pivot elements ultimately form the diagonals of the triangular basis.) For remaining unassigned rows, slack variables are inserted to complete the basis.
The ${\mathbf{Crash\; Tolerance}}$$r$ allows the starting Crash procedure to ignore certain ‘small’ nonzeros in each column of $A$. If ${a}_{\mathrm{max}}$ is the largest element in column $j$, other nonzeros of ${a}_{ij}$ in the columns are ignored if $\left|{a}_{ij}\right|\le {a}_{\mathrm{max}}\times r$. (To be meaningful, $r$ must be in the range $0\le r<1$.)
When $r>0.0$, the basis obtained by the Crash procedure may not be strictly triangular, but it is likely to be nonsingular and almost triangular. The intention is to obtain a starting basis containing more columns of $A$ and fewer (arbitrary) slacks. A feasible solution may be reached sooner on some problems.
For example, suppose the first $m$ columns of $A$ form the matrix shown under ${\mathbf{LU\; Factor\; Tolerance}}$; i.e., a tridiagonal matrix with entries $-1$, $4$, $-1$. To help the Crash procedure choose all $m$ columns for the initial basis, we would specify a ${\mathbf{Crash\; Tolerance}}$ of $r$ for some value of $r>0.5$.
Defaults
This special keyword may be used to reset all optional parameters to their default values.
Derivative Level
$i$
Default $\text{}=3$
Optional parameter ${\mathbf{Derivative\; Level}}$ specifies which nonlinear function gradients are known analytically and will be supplied to e04wdc by user-supplied functions objfun and confun.
$\mathit{i}$
Meaning
$3$
All objective and constraint gradients are known.
$2$
All constraint gradients are known, but some or all components of the objective gradient are unknown.
$1$
The objective gradient is known, but some or all of the constraint gradients are unknown.
$0$
Some components of the objective gradient are unknown and some of the constraint gradients are unknown.
The value $i=3$ should be used whenever possible. It is the most reliable and will usually be the most efficient.
If $i=0$ or $2$, e04wdc will estimate the missing components of the objective gradient, using finite differences. This may simplify the coding of objfun. However, it could increase the total run-time substantially (since a special call to objfun is required for each missing element), and there is less assurance that an acceptable solution will be located. If the nonlinear variables are not well scaled, it may be necessary to specify a non-default optional parameter ${\mathbf{Difference\; Interval}}$.
If $i=0$ or $1$, e04wdc will estimate missing elements of the Jacobian. For each column of the Jacobian, one call to confun is needed to estimate all missing elements in that column, if any.
At times, central differences are used rather than forward differences. (This is not under your control.)
Derivative Linesearch
Default
Nonderivative Linesearch
At each major iteration a linesearch is used to improve the merit function. Optional parameter ${\mathbf{Derivative\; Linesearch}}$ uses safeguarded cubic interpolation and requires both function and gradient values to compute estimates of the step ${\alpha}_{k}$. If some analytic derivatives are not provided, or optional parameter ${\mathbf{Nonderivative\; Linesearch}}$ is specified, e04wdc employs a linesearch based upon safeguarded quadratic interpolation, which does not require gradient evaluations.
A nonderivative linesearch can be slightly less robust on difficult problems, and it is recommended that the default be used if the functions and derivatives can be computed at approximately the same cost. If the gradients are very expensive relative to the functions, a nonderivative linesearch may give a significant decrease in computation time.
If ${\mathbf{Nonderivative\; Linesearch}}$ is selected, e04wdc signals the evaluation of the linesearch by calling objfun with ${\mathbf{mode}}=0$. If the potential saving provided by a nonderivative linesearch is to be realised, it is essential that objfun be coded so that derivatives are not computed when ${\mathbf{mode}}=0$.
Difference Interval
$r$
Default $\text{}=\sqrt{{\epsilon}_{r}}$
This alters the interval $r$ used to estimate gradients by forward differences. It does so in the following circumstances:
–in the interval (‘cheap’) phase of verifying the problem derivatives;
–for verifying the problem derivatives;
–for estimating missing derivatives.
In all cases, a derivative with respect to ${x}_{j}$ is estimated by perturbing that component of $x$ to the value ${x}_{j}+r(1+\left|{x}_{j}\right|)$, and then evaluating $F\left(x\right)$ or $c\left(x\right)$ at the perturbed point. The resulting gradient estimates should be accurate to $\mathit{O}\left(r\right)$ unless the functions are badly scaled. Judicious alteration of $r$ may sometimes lead to greater accuracy.
If you supply a value for this optional parameter, a small value between $0.0$ and $1.0$ is appropriate.
Dump File
${i}_{1}$
Default $\text{}=0$
Load File
${i}_{2}$
Default $\text{}=0$
(See Section 3.1.1 in the Introduction to the NAG Library CL Interface for further information on NAG data types.)
Optional parameters ${\mathbf{Dump\; File}}$ and ${\mathbf{Load\; File}}$ are similar to optional parameters ${\mathbf{Punch\; File}}$ and ${\mathbf{Insert\; File}}$, but they record solution information in a manner that is more direct and more easily modified. A full description of information recorded in optional parameters ${\mathbf{Dump\; File}}$ and ${\mathbf{Load\; File}}$ is given in Gill et al. (2005a).
If ${\mathbf{Dump\; File}}>0$, the last solution obtained will be output to the file associated with ID ${i}_{1}$.
If ${\mathbf{Load\; File}}>0$, the file associated with ID ${i}_{2}$, containing basis information, will be read. The file will usually have been output previously as a ${\mathbf{Dump\; File}}$. The file will not be accessed if optional parameters ${\mathbf{Old\; Basis\; File}}$ or ${\mathbf{Insert\; File}}$ are specified.
Elastic Weight
$r$
Default $\text{}={10}^{4}$
This keyword determines the initial weight $\gamma $ associated with the problem (11) (see Section 11.5).
At major iteration $k$, if elastic mode has not yet started, a scale factor ${\sigma}_{k}=1+{\Vert g\left({x}_{k}\right)\Vert}_{\infty}$ is defined from the current objective gradient. Elastic mode is then started if the QP subproblem is infeasible, or the QP dual variables are larger in magnitude than ${\sigma}_{k}\text{}r$. The QP is resolved in elastic mode with $\gamma ={\sigma}_{k}\text{}r$.
Thereafter, major iterations continue in elastic mode until they converge to a point that is optimal for (11) (see Section 11.5). If the point is feasible for equation (1)$(v=w=0)$, it is declared locally optimal. Otherwise, $\gamma $ is increased by a factor of $10$ and major iterations continue. If $\gamma $ has already reached a maximum allowable value, equation (1) is declared locally infeasible.
Expand Frequency
$i$
Default $\text{}=10000$
This option is part of the anti-cycling procedure designed to make progress even on highly degenerate problems.
For linear models, the strategy is to force a positive step at every iteration, at the expense of violating the bounds on the variables by a small amount. Suppose that the optional parameter ${\mathbf{Minor\; Feasibility\; Tolerance}}$ is $\delta $. Over a period of $i$ iterations, the tolerance actually used by e04wdc increases from $0.5\delta $ to $\delta $ (in steps of $0.5\delta /i$).
For nonlinear models, the same procedure is used for iterations in which there is only one superbasic variable. (Cycling can occur only when the current solution is at a vertex of the feasible region.) Thus, zero steps are allowed if there is more than one superbasic variable, but otherwise positive steps are enforced.
Increasing $i$ helps reduce the number of slightly infeasible nonbasic variables (most of which are eliminated during a resetting procedure). However, it also diminishes the freedom to choose a large pivot element (see optional parameter ${\mathbf{Pivot\; Tolerance}}$).
Factorization Frequency
$i$
Default $\text{}=50$
At most $i$ basis changes will occur between factorizations of the basis matrix.
With linear programs, the basis factors are usually updated every iteration. The default $i$ is reasonable for typical problems. Higher values up to $i=100$ (say) may be more efficient on well-scaled problems.
When the objective function is nonlinear, fewer basis updates will occur as an optimum is approached. The number of iterations between basis factorizations will, therefore, increase. During these iterations a test is made regularly (according to the optional parameter ${\mathbf{Check\; Frequency}}$) to ensure that the general constraints are satisfied. If necessary the basis will be refactorized before the limit of $i$ updates is reached.
Function Precision
$r$
Default $\text{}={\epsilon}^{0.8}$
The relative function precision${\epsilon}_{r}$ is intended to be a measure of the relative accuracy with which the functions can be computed. For example, if $F\left(x\right)$ is computed as $1000.56789$ for some relevant $x$ and if the first $6$ significant digits are known to be correct, the appropriate value for ${\epsilon}_{r}$ would be $\text{1.0e\u22126}$.
(Ideally the functions $F\left(x\right)$ or ${c}_{i}\left(x\right)$ should have magnitude of order $1$. If all functions are substantially less than $1$ in magnitude, ${\epsilon}_{r}$ should be the absolute precision. For example, if $F\left(x\right)=\text{1.23456789e\u22124}$ at some point and if the first $6$ significant digits are known to be correct, the appropriate value for ${\epsilon}_{r}$ would be $\text{1.0e\u221210}$.)
The default value of ${\epsilon}_{r}$ is appropriate for simple analytic functions.
In some cases the function values will be the result of extensive computation, possibly involving a costly iterative procedure that can provide few digits of precision. Specifying an appropriate ${\mathbf{Function\; Precision}}$ may lead to savings, by allowing the linesearch procedure to terminate when the difference between function values along the search direction becomes as small as the absolute error in the values.
Hessian Full Memory
Default if $n\le 75$
Hessian Limited Memory
Default if $n>75$
These options select the method for storing and updating the approximate Hessian. (e04wdc uses a quasi-Newton approximation to the Hessian of the Lagrangian. A BFGS update is applied after each major iteration.)
If ${\mathbf{Hessian\; Full\; Memory}}$ is specified, the approximate Hessian is treated as a dense matrix and the BFGS updates are applied explicitly. This option is most efficient when the number of variables $n$ is not too large (say, less than $75$). In this case, the storage requirement is fixed and one can expect $1$-step Q-superlinear convergence to the solution.
${\mathbf{Hessian\; Limited\; Memory}}$ should be used on problems where $n$ is very large. In this case a limited-memory procedure is used to update a diagonal Hessian approximation ${H}_{r}$ a limited number of times. (Updates are accumulated as a list of vector pairs. They are discarded at regular intervals after ${H}_{r}$ has been reset to their diagonal.)
Hessian Frequency
$i$
Default $\text{}=99999999$
If optional parameter ${\mathbf{Hessian\; Full\; Memory}}$ is in effect and $i$ BFGS updates have already been carried out, the Hessian approximation is reset to the identity matrix. (For certain problems, occasional resets may improve convergence, but in general they should not be necessary.)
${\mathbf{Hessian\; Full\; Memory}}$ and ${\mathbf{Hessian\; Frequency}}=10$ have a similar effect to ${\mathbf{Hessian\; Limited\; Memory}}$ and ${\mathbf{Hessian\; Updates}}=10$ (except that the latter retains the current diagonal during resets).
Hessian Updates
$i$
Default $\text{}={\mathbf{Hessian\; Frequency}}$ if ${\mathbf{Hessian\; Full\; Memory}}$, $10$ otherwise
If optional parameter ${\mathbf{Hessian\; Limited\; Memory}}$ is in effect and $i$ BFGS updates have already been carried out, all but the diagonal elements of the accumulated updates are discarded and the updating process starts again.
Broadly speaking, the more updates stored, the better the quality of the approximate Hessian. However, the more vectors stored, the greater the cost of each QP iteration. The default value is likely to give a robust algorithm without significant expense, but faster convergence can sometimes be obtained with significantly fewer updates (e.g., $i=5$).
Infinite Bound Size
$r$
Default $\text{}={10}^{20}$
If $r>0$, $r$ defines the ‘infinite’ bound $\mathit{bigbnd}$ in the definition of the problem constraints. Any upper bound greater than or equal to $\mathit{bigbnd}$ will be regarded as $+\infty $ (and similarly any lower bound less than or equal to $-\mathit{bigbnd}$ will be regarded as $-\infty $). If $r<0$, the default value is used.
The value of $i$ specifies the maximum number of minor iterations allowed (i.e., iterations of the simplex method or the QP algorithm), summed over all major iterations. (See also the description of the optional parameter ${\mathbf{Minor\; Iterations\; Limit}}$.)
Linesearch Tolerance
$r$
Default $=0.9$
This tolerance, $r$, controls the accuracy with which a step length will be located along the direction of search each iteration. At the start of each linesearch a target directional derivative for the merit function is identified. This parameter determines the accuracy to which this target value is approximated, and it must be a value in the range $0.0\le r\le 1.0$.
The default value $r=0.9$ requests just moderate accuracy in the linesearch.
If the nonlinear functions are cheap to evaluate, a more accurate search may be appropriate; try $r=0.1\text{,}0.01\text{ or}0.001$.
If the nonlinear functions are expensive to evaluate, a less accurate search may be appropriate. If all gradients are known, try $r=0.99$. (The number of major iterations might increase, but the total number of function evaluations may decrease enough to compensate.)
If not all gradients are known, a moderately accurate search remains appropriate. Each search will require only $1$–5 function values (typically), but many function calls will then be needed to estimate missing gradients for the next iteration.
Nolist
Default
List
Optional parameter ${\mathbf{List}}$ enables printing of each optional parameter specification as it is supplied. ${\mathbf{Nolist}}$ suppresses this printing.
LUDensity Tolerance
${r}_{1}$
Default $\text{}=0.6$
LUSingularity Tolerance
${r}_{2}$
Default $\text{}={\epsilon}^{\frac{2}{3}}$
The density tolerance, ${r}_{1}$, is used during $LU$ factorization of the basis matrix $B$. Columns of $L$ and rows of $U$ are formed one at a time, and the remaining rows and columns of the basis are altered appropriately. At any stage, if the density of the remaining matrix exceeds ${r}_{1}$, the Markowitz strategy for choosing pivots is terminated, and the remaining matrix is factored by a dense $LU$ procedure. Raising the density tolerance towards $1.0$ may give slightly sparser $LU$ factors, with a slight increase in factorization time.
The singularity tolerance, ${r}_{2}$, helps guard against ill-conditioned basis matrices. After $B$ is refactorized, the diagonal elements of $U$ are tested as follows: if $\left|{u}_{jj}\right|\le {r}_{2}$ or $\left|{u}_{jj}\right|<{r}_{2}{\displaystyle \underset{i}{\mathrm{max}}}\phantom{\rule{0.25em}{0ex}}\left|{u}_{ij}\right|$, the $j$th column of the basis is replaced by the corresponding slack variable. (This is most likely to occur after a restart.)
LUFactor Tolerance
${r}_{1}$
Default $\text{}=1.10$
LUUpdate Tolerance
${r}_{2}$
Default $\text{}=1.10$
The values of ${r}_{1}$ and ${r}_{2}$ affect the stability of the basis factorization $B=LU$, during refactorization and updates respectively. The lower triangular matrix $L$ is a product of matrices of the form
where the multipliers $\mu $ will satisfy $\left|\mu \right|\le {r}_{i}$. The default values of ${r}_{1}$ and ${r}_{2}$ usually strike a good compromise between stability and sparsity. They must satisfy ${r}_{1}$, ${r}_{2}\ge 1.0$.
For large and relatively dense problems, ${r}_{1}=10.0$ or $5.0$ (say) may give a useful improvement in stability without impairing sparsity to a serious degree.
For certain very regular structures (e.g., band matrices) it may be necessary to reduce ${r}_{1}\text{ and/or}{r}_{2}$ in order to achieve stability. For example, if the columns of $A$ include a sub-matrix of the form
one should set both ${r}_{1}$ and ${r}_{2}$ to values in the range $1.0\le {r}_{i}<4.0$.
LUPartial Pivoting
Default
LUComplete Pivoting
LURook Pivoting
The $LU$ factorization implements a Markowitz-type search for pivots that locally minimize the fill-in subject to a threshold pivoting stability criterion. The default option is to use threshhold partial pivoting. The optional parameters ${\mathbf{LU\; Rook\; Pivoting}}$ and ${\mathbf{LU\; Complete\; Pivoting}}$ are more expensive than partial pivoting but are more stable and better at revealing rank, as long as ${\mathbf{LU\; Factor\; Tolerance}}$ is not too large (say $<2.0$). When numerical difficulties are encountered, e04wdc automatically reduces the $LU$ tolerance towards $1.0$ and switches (if necessary) to rook or complete pivoting, before reverting to the default or specified options at the next refactorization (with ${\mathbf{System\; Information\; Yes}}$, relevant messages are output to the ${\mathbf{Print\; File}}$).
This tolerance, $r$, specifies how accurately the nonlinear constraints should be satisfied. The default value is appropriate when the linear and nonlinear constraints contain data to about that accuracy.
Let ${v}_{\mathrm{max}}$ be the maximum nonlinear constraint violation, normalized by the size of the solution, which is required to satisfy
where ${v}_{i}$ is the violation of the $i$th nonlinear constraint $(i=1:{n}_{L})$.
In the major iteration log (see Section 13.2, ${v}_{\mathrm{max}}$ appears as the quantity labelled ‘Feasible’. If some of the problem functions are known to be of low accuracy, a larger ${\mathbf{Major\; Feasibility\; Tolerance}}$ may be appropriate.
This tolerance, $r$, specifies the final accuracy of the dual variables. On successful termination, e04wdc will have computed a solution $(x,s,\pi )$ such that
where ${c}_{j}$ is an estimate of the complementarity slackness for variable $j$ where $j=1:n+{n}_{L}+{n}_{N}$. The values ${c}_{i}$ are computed from the final QP solution using the reduced gradients ${d}_{j}={g}_{j}-{\pi}^{\mathrm{T}}{a}_{j}$ (where ${g}_{j}$ is the $j$th component of the objective gradient, ${a}_{j}$ is the associated column of the constraint matrix $\left(\begin{array}{cc}A& -I\end{array}\right)$, and $\pi $ is the set of QP dual variables):
This is the maximum number of major iterations allowed. It is intended to guard against an excessive number of linearizations of the constraints. If $i=0$, optimality and feasibility are checked.
Major Print Level
$i$
Default $\text{}=000001$
This controls the amount of output to the optional parameters ${\mathbf{Print\; File}}$ and ${\mathbf{Summary\; File}}$ at each major iteration. ${\mathbf{Major\; Print\; Level}}=0$ suppresses most output, except for error messages. ${\mathbf{Major\; Print\; Level}}=1$ gives normal output for linear and nonlinear problems, and ${\mathbf{Major\; Print\; Level}}=11$ gives additional details of the Jacobian factorization that commences each major iteration.
In general, the value being specified may be thought of as a binary number of the form
$${\mathbf{Major\; Print\; Level}}\text{}JFDXbs$$
where each letter stands for a digit that is either $0$ or $1$ as follows:
$s$
a single line that gives a summary of each major iteration. (This entry in $JFDXbs$ is not strictly binary since the summary line is printed whenever $JFDXbs\ge 1$);
$b$
basis statistics, i.e., information relating to the basis matrix whenever it is refactorized. (This output is always provided if $JFDXbs\ge 10$);
$X$
${x}_{k}$, the nonlinear variables involved in the objective function or the constraints. These appear under the heading ‘Jacobian variables’;
$D$
${\pi}_{k}$, the dual variables for the nonlinear constraints. These appear under the heading ‘Multiplier estimates’;
$F$
$c\left({x}_{k}\right)$, the values of the nonlinear constraint functions;
$J$
$J\left({x}_{k}\right)$, the Jacobian matrix. This appears under the heading ‘$x$ and Jacobian’.
To obtain output of any items $JFDXbs$, set the corresponding digit to $1$, otherwise to $0$.
If $J=1$, the Jacobian matrix will be output column-wise at the start of each major iteration. Column $j$ will be preceded by the value of the corresponding variable ${x}_{j}$ and a key to indicate whether the variable is basic, superbasic or nonbasic. (Hence if $J=1$, there is no reason to specify $X=1$ unless the objective contains more nonlinear variables than the Jacobian.) A typical line of output is
3 1.250000e+01 BS 1 1.00000e+00 4 2.00000e+00
which would mean that ${x}_{3}$ is basic at value $12.5$, and the third column of the Jacobian has elements of $1.0$ and $2.0$ in rows $1$ and $4$.
Major Step Limit
$r$
Default $\text{}=2.0$
This parameter limits the change in $x$ during a linesearch. It applies to all nonlinear problems, once a ‘feasible solution’ or ‘feasible subproblem’ has been found. A linesearch determines a step $\alpha $ over the range $0<\alpha \le \beta $, where $\beta $ is $1$ if there are nonlinear constraints, or is the step to the nearest upper or lower bound on $x$ if all the constraints are linear. Normally, the first step length tried is ${\alpha}_{1}=\mathrm{min}\phantom{\rule{0.125em}{0ex}}(1,\beta )$.
1.In some cases, such as $f\left(x\right)=a{e}^{bx}$ or $f\left(x\right)=a{x}^{b}$, even a moderate change in the components of $x$ can lead to floating-point overflow. The parameter $r$ is, therefore, used to define a limit $\overline{\beta}=r(1+\Vert x\Vert )/\Vert p\Vert $ (where $p$ is the search direction), and the first evaluation of $f\left(x\right)$ is at the potentially smaller step length ${\alpha}_{1}=\mathrm{min}\phantom{\rule{0.125em}{0ex}}(1,\overline{\beta},\beta )$.
2.Wherever possible, upper and lower bounds on $x$ should be used to prevent evaluation of nonlinear functions at meaningless points. The optional parameter ${\mathbf{Major\; Step\; Limit}}$ provides an additional safeguard. The default value $r=2.0$ should not affect progress on well behaved problems, but setting $r=0.1\text{ or}0.01$ may be helpful when rapidly varying functions are present. A ‘good’ starting point may be required. An important application is to the class of nonlinear least squares problems.
3.In cases where several local optima exist, specifying a small value for $r$ may help locate an optimum near the starting point.
Minimize
Default
Maximize
Feasible Point
The keywords ${\mathbf{Minimize}}$ and ${\mathbf{Maximize}}$ specify the required direction of optimization. It applies to both linear and nonlinear terms in the objective.
The keyword ${\mathbf{Feasible\; Point}}$ means ‘Ignore the objective function, while finding a feasible point for the linear and nonlinear constraints’. It can be used to check that the nonlinear constraints are feasible without altering the call to e04wdc.
e04wdc tries to ensure that all variables eventually satisfy their upper and lower bounds to within this tolerance, $r$. This includes slack variables. Hence, general linear constraints should also be satisfied to within $r$.
Feasibility with respect to nonlinear constraints is judged by the optional parameter ${\mathbf{Major\; Feasibility\; Tolerance}}$ (not by $r$).
If the bounds and linear constraints cannot be satisfied to within $r$, the problem is declared infeasible. If
the corresponding sum of infeasibilities
is quite small, it may be appropriate to raise $r$ by a factor of $10$ or $100$. Otherwise, some error in the data should be suspected.
Nonlinear functions will be evaluated only at points that satisfy the bounds and linear constraints. If there are regions where a function is undefined, every attempt should be made to eliminate these regions from the problem.
For example, if $f\left(x\right)=\sqrt{{x}_{1}}+\mathrm{log}\left({x}_{2}\right)$, it is essential to place lower bounds on both variables. If $r=\text{1.0e\u22126}$, the bounds ${x}_{1}\ge {10}^{-5}$ and ${x}_{2}\ge {10}^{-4}$ might be appropriate. (The log singularity is more serious. In general, keep $x$ as far away from singularities as possible.)
If ${\mathbf{Scale\; Option}}\ge 1$, feasibility is defined in terms of the scaled problem (since it is then more likely to be meaningful).
In reality, e04wdc uses $r$ as a feasibility tolerance for satisfying the bounds on $x$ and $s$ in each QP subproblem. If the sum of infeasibilities cannot be reduced to zero, the QP subproblem is declared infeasible. e04wdc is then in elastic mode thereafter (with only the linearized nonlinear constraints defined to be elastic). See the description of the optional parameter ${\mathbf{Elastic\; Weight}}$.
Minor Iterations Limit
$i$
Default $\text{}=500$
If the number of minor iterations for the optimality phase of the QP subproblem exceeds $i$, then all nonbasic QP variables that have not yet moved are frozen at their current values and the reduced QP is solved to optimality.
Note that more than $i$ minor iterations may be necessary to solve the reduced QP to optimality. These extra iterations are necessary to ensure that the terminated point gives a suitable direction for the linesearch.
In the major iteration log (see Section 13.2) a t at the end of a line indicates that the corresponding QP was artificially terminated using the limit $i$.
Compare with the optional parameter ${\mathbf{Iterations\; Limit}}$, which defines an independent absolute limit on the total number of minor iterations (summed over all QP subproblems).
Minor Print Level
$i$
Default $\text{}=1$
This controls the amount of output to the ${\mathbf{Print\; File}}$ and the ${\mathbf{Summary\; File}}$ during solution of the QP subproblems. The value of $i$ has the following effect:
$\mathit{i}$
Output
$0$
No minor iteration output except error messages.
$\ge 1$
A single line of output at each minor iteration (controlled by optional parameters ${\mathbf{Print\; Frequency}}$ and ${\mathbf{Summary\; Frequency}}$.
$\ge 10$
Basis factorization statistics generated during the periodic refactorization of the basis (see the optional parameter ${\mathbf{Factorization\; Frequency}}$). Statistics for the first factorization each major iteration are controlled by the optional parameter ${\mathbf{Major\; Print\; Level}}$.
New Basis File
${i}_{1}$
Default $\text{}=0$
Backup Basis File
${i}_{2}$
Default $\text{}=0$
Save Frequency
${i}_{3}$
Default $\text{}=100$
(See Section 3.1.1 in the Introduction to the NAG Library CL Interface for further information on NAG data types.)
${\mathbf{New\; Basis\; File}}$ and ${\mathbf{Backup\; Basis\; File}}$ are sometimes referred to as basis maps. They contain the most compact representation of the state of each variable. They are intended for restarting the solution of a problem at a point that was reached by an earlier run. For nontrivial problems, it is advisable to save basis maps at the end of a run, in order to restart the run if necessary.
If ${\mathbf{New\; Basis\; File}}>0$,
a basis map will be saved on the
${\mathbf{New\; Basis\; File}}$
every ${i}_{3}$th iteration. The first record of the file will contain the word PROCEEDING if the run is still in progress. A basis map will also be saved at the end of a run, with some other word indicating the final solution status.
If ${\mathbf{Backup\; Basis\; File}}>0$, it
is intended as a safeguard against losing the results of a long run. Suppose that a ${\mathbf{New\; Basis\; File}}$ is being saved every $100$ (${\mathbf{Save\; Frequency}}$) iterations, and that e04wdc is about to save such a basis at iteration $2000$. It is conceivable that the run may be interrupted during the next few milliseconds (in the middle of the save). In this case the Basis file will be corrupted and the run will have been essentially wasted.
To eliminate this risk, both a ${\mathbf{New\; Basis\; File}}$ and a ${\mathbf{Backup\; Basis\; File}}$ may be
specified using calls of x04acc.
The current basis will then be saved every $100$ iterations, first on the
${\mathbf{New\; Basis\; File}}$
and then immediately on the
${\mathbf{Backup\; Basis\; File}}$.
If the run is interrupted at iteration $2000$ during the save on the
${\mathbf{New\; Basis\; File}}$,
there will still be a usable basis on the
${\mathbf{Backup\; Basis\; File}}$
(corresponding to iteration $1900$).
Note that a new basis will be saved in ${\mathbf{New\; Basis\; File}}$ at the end of a run if it terminates normally, but it will not be saved in ${\mathbf{Backup\; Basis\; File}}$. In the above example, if an optimum solution is found at iteration $2050$ (or if the iteration limit is $2050$), the final basis in the
${\mathbf{New\; Basis\; File}}$
will correspond to iteration $2050$, but the last basis saved in the
${\mathbf{Backup\; Basis\; File}}$
will be the one for iteration $2000$.
A full description of information recorded in ${\mathbf{New\; Basis\; File}}$ and ${\mathbf{Backup\; Basis\; File}}$ is given in Gill et al. (2005a).
New Superbasics Limit
$i$
Default $\text{}=99$
This option causes early termination of the QP subproblems if the number of free variables has increased significantly since the first feasible point. If the number of new superbasics is greater than $i$, the nonbasic variables that have not yet moved are frozen and the resulting smaller QP is solved to optimality.
In the major iteration log (see Section 13.1), a t at the end of a line indicates that the QP was terminated early in this way.
Old Basis File
$i$
Default $\text{}=0$
(See Section 3.1.1 in the Introduction to the NAG Library CL Interface for further information on NAG data types.)
If ${\mathbf{Old\; Basis\; File}}>0$, the basis maps information will be obtained from the file associated with ID $i$.
The file will usually have been output previously as a ${\mathbf{New\; Basis\; File}}$ or ${\mathbf{Backup\; Basis\; File}}$.
A full description of information recorded in ${\mathbf{New\; Basis\; File}}$ and ${\mathbf{Backup\; Basis\; File}}$ is given in Gill et al. (2005a).
The file will not be acceptable if the number of rows or columns in the problem has been altered.
Partial Price
$i$
Default $\text{}=1$
This parameter is recommended for large problems that have significantly more variables than constraints. It reduces the work required for each ‘pricing’ operation (where a nonbasic variable is selected to become superbasic). When $i=1$, all columns of the constraint matrix $\left(\begin{array}{cc}A& -I\end{array}\right)$ are searched. Otherwise, $A$ and $I$ are partitioned to give $i$ roughly equal segments ${A}_{\mathit{j}}$ and ${I}_{\mathit{j}}$, for $\mathit{j}=1,2,\dots ,i$. If the previous pricing search was successful on ${A}_{j-1}$ and ${I}_{j-1}$, the next search begins on the segments ${A}_{j}$ and ${I}_{j}$. (All subscripts here are modulo $i$.) If a reduced gradient is found that is larger than some dynamic tolerance, the variable with the largest such reduced gradient (of appropriate sign) is selected to become superbasic. If nothing is found, the search continues on the next segments ${A}_{j+1}$ and ${I}_{j+1}$, and so on.
For time-stage models having $t$ time periods, ${\mathbf{Partial\; Price}}$$t$ (or $t/2$ or $t/3$) may be appropriate.
Pivot Tolerance
$r$
Default $\text{}={\epsilon}^{\frac{2}{3}}$
During the solution of QP subproblems, the pivot tolerance is used to prevent columns entering the basis if they would cause the basis to become almost singular.
When $x$ changes to $x+\alpha p$ for some search direction $p$, a ‘ratio test’ determines which component of $x$ reaches an upper or lower bound first. The corresponding element of $p$ is called the pivot element. Elements of $p$ are ignored (and, therefore, cannot be pivot elements) if they are smaller than the pivot tolerance $r$.
It is common for two or more variables to reach a bound at essentially the same time. In such cases, the ${\mathbf{Minor\; Feasibility\; Tolerance}}$ (say, $t$) provides some freedom to maximize the pivot element and thereby improve numerical stability. Excessively small values of $t$ should, therefore, not be specified. To a lesser extent, the ${\mathbf{Expand\; Frequency}}$ (say, $f$) also provides some freedom to maximize the pivot element. Excessively large values of $f$ should, therefore, not be specified.
Print File
$i$
Default $\text{}=0$
(See Section 3.1.1 in the Introduction to the NAG Library CL Interface for further information on NAG data types.)
If ${\mathbf{Print\; File}}>0$,
the following information is output to a file associated with
ID
$i$ during the solution of each problem:
–a listing of the optional parameters;
–some statistics about the problem;
–the amount of storage available for the $LU$ factorization of the basis matrix;
–notes about the initial basis resulting from a Crash procedure or a Basis file;
–the iteration log;
–basis factorization statistics;
–the exit fail condition and some statistics about the solution obtained;
–the printed solution, if requested.
These items are described in Sections 9 and 13. Further brief output may be directed to the ${\mathbf{Summary\; File}}$.
Print Frequency
$i$
Default $\text{}=100$
If $i>0$, one line of the iteration log will be printed every $i$th iteration. A value such as $i=10$ is suggested for those interested only in the final solution. If $i\le 0$, the value of $i=99999999$ is used and effectively no checks are made.
Proximal Point Method
$i$
Default $\text{}=1$
$i=1\text{ or}2$ specifies minimization of ${\Vert x-{x}_{0}\Vert}_{1}$ or $\frac{1}{2}{\Vert x-{x}_{0}\Vert}_{2}^{2}$ when the starting point ${x}_{0}$ is changed to satisfy the linear constraints (where ${x}_{0}$ refers to nonlinear variables).
Punch File
${i}_{1}$
Default $=0$
Insert File
${i}_{2}$
Default $=0$
(See Section 3.1.1 in the Introduction to the NAG Library CL Interface for further information on NAG data types.)
The ${\mathbf{Punch\; File}}$ from a previous run may be used as an ${\mathbf{Insert\; File}}$ for a later run on the same problem. A full description of information recorded in ${\mathbf{Insert\; File}}$ and ${\mathbf{Punch\; File}}$ is given in Gill et al. (2005a).
If ${\mathbf{Punch\; File}}>0$, the final solution obtained will be output to the file associated with ID ${i}_{1}$.
For linear programs, this format is compatible with various commercial systems.
If ${\mathbf{Insert\; File}}>0$, the file associated with ID ${i}_{2}$, containing basis information, will be read.
The file will usually have been output previously as a ${\mathbf{Punch\; File}}$. The file will not be accessed if ${\mathbf{Old\; Basis\; File}}$ is specified.
QPSolver Cholesky
Default
QPSolver CG
QPSolver QN
Specifies the active-set algorithm used to solve subproblem (11) (see Section 11.5). ${\mathbf{QPSolver\; Cholesky}}$ holds the full Cholesky factor $R$ of the reduced Hessian ${Z}^{\mathrm{T}}HZ$. As the QP iterations proceed, the dimension of $R$ changes with the number of superbasic variables. If the number of superbasic variables needs to increase beyond the value of ${\mathbf{Reduced\; Hessian\; Dimension}}$, the reduced Hessian cannot be stored and the solver switches to ${\mathbf{QPSolver\; CG}}$. The Cholesky solver is reactivated if the number of superbasics stabilizes at a value less than ${\mathbf{Reduced\; Hessian\; Dimension}}$.
${\mathbf{QPSolver\; QN}}$ solves the QP using a quasi-Newton method. In this case, $R$ is the factor of a quasi-Newton approximate Hessian.
${\mathbf{QPSolver\; CG}}$ uses an active-set method similar to ${\mathbf{QPSolver\; QN}}$, but uses the conjugate-gradient method to solve all systems involving the reduced Hessian.
The Cholesky QP solver is the most robust, but may require a significant amount of computation if there are many superbasics.
The quasi-Newton QP solver does not require computation of the exact $R$ at the start of the subproblem in (11). It may be appropriate when the number of superbasics is large but relatively few iterations are needed to reach a solution (e.g., if e04wdc is called with a Warm Start).
The conjugate-gradient QP solver is appropriate for problems with many degrees of freedom (say, more than $2000$ superbasics).
This specifies that an $i\times i$ triangular matrix $R$ (to define the reduced Hessian according to ${R}^{\mathrm{T}}R={Z}^{\mathrm{T}}HZ$) is to be available for use by the Cholesky QP solver.
Scale Option
$i$
Default $\text{}=0$
Scale Tolerance
$r$
Default $\text{}=0.9$
Scale Print
Three scale options are available as follows:
$\mathit{i}$
Meaning
0
No scaling. This is recommended if it is known that $x$ and the constraint matrix never have very large elements (say, larger than $100$).
1
The constraints and variables are scaled by an iterative procedure that attempts to make the matrix coefficients as close as possible to $1.0$ (see Fourer (1982)). This will sometimes improve the performance of the solution procedures.
2
The constraints and variables are scaled by the iterative procedure. Also, a certain additional scaling is performed that may be helpful if the right-hand side $b$ or the solution $x$ is large. This takes into account columns of $\left(\begin{array}{cc}A& -I\end{array}\right)$ that are fixed or have positive lower bounds or negative upper bounds.
Optional parameter ${\mathbf{Scale\; Tolerance}}$ affects how many passes might be needed through the constraint matrix. On each pass, the scaling procedure computes the ratio of the largest and smallest nonzero coefficients in each column:
If $\underset{j}{\mathrm{max}}}\phantom{\rule{0.25em}{0ex}}{\rho}_{j$ is less than $r$ times its previous value, another scaling pass is performed to adjust the row and column scales. Raising $r$ from $0.9$ to $0.99$ (say) usually increases the number of scaling passes through $A$. At most $10$ passes are made. The value of $r$ should lie in the range $0<r<1$.
${\mathbf{Scale\; Print}}$ causes the row scales $r\left(i\right)$ and column scales $c\left(j\right)$ to be printed to ${\mathbf{Print\; File}}$, if ${\mathbf{System\; Information\; Yes}}$ has been specified. The scaled matrix coefficients are ${\overline{a}}_{ij}={a}_{ij}c\left(j\right)/r\left(i\right)$, and the scaled bounds on the variables and slacks are ${\overline{l}}_{j}={l}_{j}/c\left(j\right)$, ${\overline{u}}_{j}={u}_{j}/c\left(j\right)$, where $c\left(j\right)=r(j-n)$ if $j>n$.
Solution File
$i$
Default $\text{}=0$
(See Section 3.1.1 in the Introduction to the NAG Library CL Interface for further information on NAG data types.)
If ${\mathbf{Solution\; File}}>0$, the final solution will be output to the file associated with ID $i$.
To see more significant digits in the printed solution, it will sometimes be useful to
specify that the ${\mathbf{Solution\; File}}$ refers to the ${\mathbf{Print\; File}}$.
Start Objective Check At Variable
$i$
Default $\text{}=1$
Stop Objective Check At Variable
$i$
Default $\text{}=n$
Start Constraint Check At Variable
$i$
Default $\text{}=1$
Stop Constraint Check At Variable
$i$
Default $\text{}=n$
These keywords take effect only if ${\mathbf{Verify\; Level}}>0$. They may be used to contol the verification of gradient elements computed by function objfun and/or Jacobian elements computed by function confun. For eample, if the first $30$ elements of the objective gradient appeared to be correct in an earlier run, so that only element $31$ remains questionable, it is reasonable to specify ${\mathbf{Start\; Objective\; Check\; At\; Variable}}=31$. If the first $30$ variables appear linearly in the objective, so that the corresponding gradient elements are constant, the above choice would also be appropriate.
Summary File
${i}_{1}$
Default $\text{}=0$
Summary Frequency
${i}_{2}$
Default $\text{}=100$
(See Section 3.1.1 in the Introduction to the NAG Library CL Interface for further information on NAG data types.)
If ${\mathbf{Summary\; File}}>0$, a brief log will be output to the file associated with ${i}_{1}$,
including one line of information every ${i}_{2}$th iteration. In an interactive environment, it is useful to direct this output to the terminal, to allow a run to be monitored online. (If something looks wrong, the run can be manually terminated.) Further details are given in Section 13.6.
Superbasics Limit
$i$
Default $\text{}=n$
This option places a limit on the storage allocated for superbasic variables. Ideally, $i$ should be set slightly larger than the ‘number of degrees of freedom’ expected at an optimal solution.
For nonlinear problems, the number of degrees of freedom is often called the ‘number of independent variables’. Normally, $i$ need not be greater than ${n}_{N}+1$, where ${n}_{N}$ is the number of nonlinear variables. For many problems, $i$ may be considerably smaller than ${n}_{N}$. This will save storage if ${n}_{N}$ is very large.
Suppress Parameters
Normally e04wdc prints the options file as it is being read, and then prints a complete list of the available keywords and their final values. The optional parameter ${\mathbf{Suppress\; Parameters}}$ tells e04wdc not to print the full list.
System Information No
Default
System Information Yes
This option prints additional information on the progress of major and minor iterations, and Crash statistics. See Section 13.
Timing Level
$i$
Default $\text{}=0$
If $i>0$, some timing information will be output to the Print file, if ${\mathbf{Print\; File}}>0$.
Unbounded Objective
${r}_{1}$
Default $\text{}=\text{1.0e+15}$
Unbounded Step Size
${r}_{2}$
Default $\text{}=\mathit{bigbnd}$
These parameters are intended to detect unboundedness in nonlinear problems. During a linesearch, $F$ is evaluated at points of the form $x+\alpha p$, where $x$ and $p$ are fixed and $\alpha $ varies. If $\left|F\right|$ exceeds ${r}_{1}$ or $\alpha $ exceeds ${r}_{2}$, iterations are terminated with the exit message ${\mathbf{fail}}\mathbf{.}\mathbf{code}=$NE_UNBOUNDED.
If singularities are present, unboundedness in $F\left(x\right)$ may be manifested by a floating-point overflow (during the evaluation of $F(x+\alpha p)$), before the test against ${r}_{1}$ can be made.
Unboundedness in $x$ is best avoided by placing finite upper and lower bounds on the variables.
Verify Level
$i$
Default $\text{}=0$
This option refers to finite difference checks on the derivatives computed by the user-supplied functions. Derivatives are checked at the first point that satisfies all bounds and linear constraints.
$\mathit{i}$
Meaning
$0$
Only a ‘cheap’ test will be performed, requiring two calls to confun.
$1$
Individual gradients will be checked (with a more reliable test). A key of the form OK or Bad? indicates whether or not each component appears to be correct.
$2$
Individual columns of the problem Jacobian will be checked.
$3$
Options 2 and 1 will both occur (in that order).
$-1$
Derivative checking is disabled.
${\mathbf{Verify\; Level}}=3$ should be specified whenever a new
user
function is being developed. Missing derivatives are not checked, so they result in no overhead.
Violation Limit
$r$
Default $\text{}=\text{1.0e+6}$
This keyword defines an absolute limit on the magnitude of the maximum constraint violation, $r$, after the linesearch. On completion of the linesearch, the new iterate ${x}_{k+1}$ satisfies the condition
where ${x}_{0}$ is the point at which the nonlinear constraints are first evaluated and ${v}_{i}\left(x\right)$ is the $i$th nonlinear constraint violation ${v}_{i}\left(x\right)=\mathrm{max}\phantom{\rule{0.125em}{0ex}}(0,{l}_{i}-{c}_{i}\left(x\right),{c}_{i}\left(x\right)-{u}_{i})$.
The effect of this violation limit is to restrict the iterates to lie in an expanded feasible region whose size depends on the magnitude of $r$. This makes it possible to keep the iterates within a region where the objective is expected to be well defined and bounded below. If the obective is bounded below for all values of the variables, $r$ may be any large positive value.
13Description of Monitoring Information
e04wdc produces monitoring information, statistical information and information about the solution. Section 9.1 contains the final output information sent to unit ${\mathbf{Print\; File}}$. This section contains other output information.
13.1Major Iteration Log
This section describes the output to unit ${\mathbf{Print\; File}}$ if ${\mathbf{Major\; Print\; Level}}>0$. One line of information is output every $k$th major iteration, where $k$ is ${\mathbf{Print\; Frequency}}$.
Label
Description
Itns
is the cumulative number of minor iterations.
Major
is the current major iteration number.
Minors
is the number of iterations required by both the feasibility and optimality phases of the QP subproblem. Generally, Minors will be $1$ in the later iterations, since theoretical analysis predicts that the correct active set will be identified near the solution (see Section 11).
Step
is the step length $\alpha $ taken along the current search direction $p$. The variables $x$ have just been changed to $x+\alpha p$. On reasonably well-behaved problems, the unit step will be taken as the solution is approached.
nCon or nObj
nCon is the number of times confun has been called to evaluate the nonlinear problem functions. Evaluations needed for the estimation of the derivatives by finite differences are not included. nCon is printed as a guide to the amount of work required for the linesearch. If ${n}_{N}$, the number of nonlinear constraints, is zero, nCon does not appear, but is replaced by nObj. This quantity is the number of calls made to objfun.
Feasible
is the value of ${v}_{\mathrm{max}}$ (see (12)), the maximum component of the scaled nonlinear constraint residual (see the description of the optional parameter ${\mathbf{Major\; Feasibility\; Tolerance}}$). The solution is regarded as acceptably feasible if Feasible is less than the ${\mathbf{Major\; Feasibility\; Tolerance}}$. In this case, the entry is contained in parentheses.
If the constraints are linear, all iterates are feasible and this entry is not printed.
Optimal
is the value of ${c}_{\mathrm{max}}$ (see (13)), the maximum complementary gap (see the description of the optional parameter ${\mathbf{Major\; Optimality\; Tolerance}}$). It is an estimate of the degree of nonoptimality of the reduced costs. Both Feasible and Optimal are small in the neighbourhood of a solution.
MeritFunction or Objective
is the value of the augmented Lagrangian merit function (see (8)). This function will decrease at each iteration unless it was necessary to increase the penalty parameters (see Section 11.4). As the solution is approached, MeritFunction will converge to the value of the objective at the solution.
In elastic mode, the merit function is a composite function involving the constraint violations weighted by the elastic weight.
If the constraints are linear, this item is labelled Objective, the value of the objective function. It will decrease monotonically to its optimal value.
L+U
is the number of nonzeros representing the basis factors $L$ and $U$ on completion of the QP subproblem.
If nonlinear constraints are present, the basis factorization $B=LU$ is computed at the start of the first minor iteration. At this stage, $\mathtt{L+U}=\mathtt{lenL}+\mathtt{lenU}$, where lenL (see Section 13.4) is the number of subdiagonal elements in the columns of a lower triangular matrix and lenU (see Section 13.4) is the number of diagonal and superdiagonal elements in the rows of an upper-triangular matrix.
As columns of $B$ are replaced during the minor iterations, L+U may fluctuate up or down but, in general, will tend to increase. As the solution is approached and the minor iterations decrease towards zero, L+U will reflect the number of nonzeros in the $LU$ factors at the start of the QP subproblem.
If the constraints are linear, refactorization is subject only to the ${\mathbf{Factorization\; Frequency}}$, and L+U will tend to increase between factorizations.
BSwap
is the number of columns of the basis matrix $B$ that were swapped with columns of $S$ to improve the condition of $B$. The swaps are determined by an $LU$ factorization of the rectangular matrix ${B}_{S}={\left(\begin{array}{cc}B& S\end{array}\right)}^{\mathrm{T}}$ with stability being favoured more than sparsity.
nS
is the current number of superbasic variables.
condHz
is an estimate of the condition number of ${R}^{\mathrm{T}}R$, itself an estimate of ${Z}^{\mathrm{T}}HZ$, the reduced Hessian of the Lagrangian. The condition number is the square of the ratio of the largest and smallest diagonals of the upper triangular matrix $R$, this being a lower bound on the condition number of ${R}^{\mathrm{T}}R$. condHz gives a rough indication of whether or not the optimization procedure is having difficulty. If $\epsilon $ is the relative machine precision being used, the SQP algorithm will make slow progress if condHz becomes as large as ${\epsilon}^{-1/2}\approx {10}^{8}$, and will probably fail to find a better solution if condHz reaches ${\epsilon}^{-3/4}\approx {10}^{12}$.
To guard against high values of condHz, attention should be given to the scaling of the variables and the constraints. In some cases it may be necessary to add upper or lower bounds to certain variables to keep them a reasonable distance from singularities in the nonlinear functions or their derivatives.
Penalty
is the Euclidean norm of the vector of penalty parameters used in the augmented Lagrangian merit function (not printed if there are no nonlinear constraints).
The summary line may include additional code characters that indicate what happened during the course of the major iteration. These will follow the separator ‘_’ in the output.
Label
Description
c
central differences have been used to compute the unknown components of the objective and constraint gradients. A switch to central differences is made if either the linesearch gives a small step, or $x$ is close to being optimal. In some cases, it may be necessary to re-solve the QP subproblem with the central difference gradient and Jacobian.
d
during the linesearch it was necessary to decrease the step in order to obtain a maximum constraint violation conforming to the value of ${\mathbf{Violation\; Limit}}$.
D
you set ${\mathbf{mode}}=-1$ on exit from objfun, indicating that the linesearch needed to be done with a smaller value of the step length $\alpha $.
l
the norm wise change in the variables was limited by the value of the ${\mathbf{Major\; Step\; Limit}}$. If this output occurs repeatedly during later iterations, it may be worthwhile increasing the value of ${\mathbf{Major\; Step\; Limit}}$.
i
if e04wdc is not in elastic mode, an i signifies that the QP subproblem is infeasible. This event triggers the start of nonlinear elastic mode, which remains in effect for all subsequent iterations. Once in elastic mode, the QP subproblems are associated with the elastic problem (11) (see Section 11.5).
If e04wdc is already in elastic mode, an i indicates that the minimizer of the elastic subproblem does not satisfy the linearized constraints. (In this case, a feasible point for the usual QP subproblem may or may not exist.)
M
an extra evaluation of the problem functions was needed to define an acceptable positive definite quasi-Newton update to the Lagrangian Hessian. This modification is only done when there are nonlinear constraints.
m
this is the same as M except that it was also necessary to modify the update to include an augmented Lagrangian term.
n
no positive definite BFGS update could be found. The approximate Hessian is unchanged from the previous iteration.
R
the approximate Hessian has been reset by discarding all but the diagonal elements. This reset will be forced periodically by the ${\mathbf{Hessian\; Frequency}}$ and ${\mathbf{Hessian\; Updates}}$ keywords. However, it may also be necessary to reset an ill-conditioned Hessian from time to time.
r
the approximate Hessian was reset after ten consecutive major iterations in which no BFGS update could be made. The diagonals of the approximate Hessian are retained if at least one update has been done since the last reset. Otherwise, the approximate Hessian is reset to the identity matrix.
s
a self-scaled BFGS update was performed. This update is used when the Hessian approximation is diagonal, and hence always follows a Hessian reset.
t
the minor iterations were terminated because of the ${\mathbf{Minor\; Iterations\; Limit}}$.
T
the minor iterations were terminated because of the ${\mathbf{New\; Superbasics\; Limit}}$.
u
the QP subproblem was unbounded.
w
a weak solution of the QP subproblem was found.
z
the ${\mathbf{Superbasics\; Limit}}$ was reached.
13.2Minor Iteration Log
If ${\mathbf{Minor\; Print\; Level}}>0$, one line of information is output to the Print file every $k$th minor iteration, where $k$ is the specified ${\mathbf{Print\; Frequency}}$. A heading is printed before the first such line following a basis factorization. The heading contains the items described below. In this description, a pricing operation is the process by which a nonbasic variable is selected to become superbasic (in addition to those already in the superbasic set). The selected variable is denoted by jq. Variable jq often becomes basic immediately. Otherwise it remains superbasic, unless it reaches its opposite bound and returns to the nonbasic set.
If ${\mathbf{Partial\; Price}}$ is in effect, variable jq is selected from ${A}_{\mathtt{pp}}$ or ${I}_{\mathtt{pp}}$, the $\mathtt{pp}$th segments of the constraint matrix $\left(\begin{array}{cc}A& -I\end{array}\right)$.
Label
Description
Itn
the current iteration number.
LPmult or QPmult
is the reduced cost (or reduced gradient) of the variable jq selected by the pricing procedure at the start of the present iteration. Algebraically, the reduced gradient is ${d}_{j}={g}_{j}-{\pi}^{\mathrm{T}}{a}_{j}$ for $j=\mathtt{jq}$, where ${g}_{j}$ is the gradient of the current objective function, $\pi $ is the vector of dual variables for the QP subproblem, and ${a}_{j}$ is the $j$th column of $\left(\begin{array}{cc}A& -I\end{array}\right)$.
Note that the reduced cost is the $1$-norm of the reduced-gradient vector at the start of the iteration, just after the pricing procedure.
LPstep or QPstep
is the step length $\alpha $ taken along the current search direction $p$. The variables $x$ have just been changed to $x+\alpha p$. Write Step to stand for LPStep or QPStep, depending on the problem. If a variable is made superbasic during the current iteration ($\mathtt{+SBS}>0$), Step will be the step to the nearest bound. During the solution of (11), the step can be greater than $1$ only if the reduced Hessian is not positive definite.
nInf
is the number of infeasibilities after the present iteration. This number will not increase unless the iterations are in elastic mode.
SumInf
is the sum of infeasibilities after the present iteration, if $\mathtt{nInf}>0$. The value usually decreases at each nonzero Step, but if it decreases by $2$ or more, SumInf may occasionally increase.
rgNorm
is the norm of the reduced-gradient vector at the start of the iteration. (It is the norm of the vector with elements ${d}_{j}$ for variables $j$ in the superbasic set.) During the solution of subproblem (11) this norm will be approximately zero after a unit step. (The heading is not printed if the problem is linear.)
LPobjective, QPobjective or Elastic QPobj
the QP objective function after the present iteration. In elastic mode, the heading is changed to Elastic QPobj. In either case, the value printed decreases monotonically.
+SBS
is the variable jq selected by the pricing operation to be added to the superbasic set.
-SBS
is the superbasic variable chosen to become nonbasic.
-BS
is the basis variable removed (if any) to become nonbasic.
Pivot
if column ${a}_{q}$ replaces the $r$th column of the basis $B$, Pivot is the $r$th element of a vector $y$ satisfying $By={a}_{q}$. Wherever possible, Step is chosen to avoid extremely small values of Pivot (since they cause the basis to be nearly singular). In rare cases, it may be necessary to increase the ${\mathbf{Pivot\; Tolerance}}$ to exclude very small elements of $y$ from consideration during the computation of Step.
L+U
is the number of nonzeros representing the basis factors $L$ and $U$. Immediately after a basis factorization $B=LU$, L+U is lenL+lenU, the number of subdiagonal elements in the columns of a lower triangular matrix and the number of diagonal and superdiagonal elements in the rows of an upper-triangular matrix. Further nonzeros are added to L when various columns of $B$ are later replaced. As columns of $B$ are replaced, the matrix $U$ is maintained explicitly (in sparse form). The value of L will steadily increase, whereas the value of U may fluctuate up or down. Thus the value of L+U may fluctuate up or down (in general, it will tend to increase).
ncp
is the number of compressions required to recover storage in the data structure for $U$. This includes the number of compressions needed during the previous basis factorization.
nS
is the current number of superbasic variables. (The heading is not printed if the problem is linear.)
condHz
see Section 13.1. (The heading is not printed if the problem is linear.)
13.3Crash Statistics
If ${\mathbf{Major\; Print\; Level}}\ge 10$ and ${\mathbf{System\; Information\; Yes}}$ has been specified, the following items are output to the Print file when ${\mathbf{Cold\; Start}}$ and no Backup Basis file is loaded. They refer to the number of columns that the Crash procedure selects during selected passes through $A$ while searching for a triangular basis matrix.
Label
Description
Slacks
is the number of slacks selected initially.
Free cols
is the number of free columns in the basis.
Preferred
is the number of ‘preferred’ columns in the basis (i.e., ${\mathbf{istate}}\left[j-1\right]=3$ for some $j\le n$).
Unit
is the number of unit columns in the basis.
Double
is the number of columns in the basis containing $2$ nonzeros.
Triangle
is the number of triangular columns in the basis.
Pad
is the number of slacks used to pad the basis (to make it a nonsingular triangle).
13.4Basis Factorization Statistics
If ${\mathbf{Major\; Print\; Level}}\ge 10$, the first seven items in the list below are output to the Print file whenever the basis $B$ or the rectangular matrix ${B}_{S}={\left(\begin{array}{cc}B& S\end{array}\right)}^{\mathrm{T}}$ is factorized before solution of the next QP subproblem. See Section 12.1 for a full description of an optional parameter.
Gaussian elimination is used to compute a sparse $LU$ factorization of $B$ or ${B}_{S}$, where $PL{P}^{\mathrm{T}}$ and $PUQ$ are lower and upper triangular matrices for some permutation matrices $P$ and $Q$. Stability is ensured as described under the optional parameter ${\mathbf{LU\; Factor\; Tolerance}}$.
If ${\mathbf{Minor\; Print\; Level}}\ge 10$, the same items are printed during the QP solution whenever the current $B$ is factorized. In addition, if ${\mathbf{System\; Information\; Yes}}$ has been specified, the entries from Elems onwards are also printed.
Label
Description
Factor
the number of factorizations since the start of the run.
Demand
a code giving the reason for the present factorization, as follows:
Code
Meaning
0
First $LU$ factorization.
1
The number of updates reached the ${\mathbf{Factorization\; Frequency}}$.
2
The nonzeros in the updated factors have increased significantly.
7
Not enough storage to update factors.
10
Row residuals too large (see the description of the optional parameter ${\mathbf{Check\; Frequency}}$).
11
Ill-conditioning has caused inconsistent results.
Itn
is the current minor iteration number.
Nonlin
is the number of nonlinear variables in the current basis $B$.
Linear
is the number of linear variables in $B$.
Slacks
is the number of slack variables in $B$.
BBRBS or BT factorize
is the type of $LU$ factorization.
B
periodic factorization of the basis $B$.
BR
more careful rank-revealing factorization of $B$ using threshold rook pivoting. This occurs mainly at the start, if the first basis factors seem singular or ill-conditioned. Followed by a normal B factorize.
BS
${B}_{S}$ is factorized to choose a well-conditioned $B$ from the current $\left(B\text{}S\right)$. Followed by a normal B factorize.
BT
same as BS except the current $B$ is tried first and accepted if it appears to be not much more ill-conditioned than after the previous BS factorize.
m
is the number of rows in $B$ or ${B}_{S}$.
n
is the number of columns in $B$ or ${B}_{S}$. Preceded by ‘=’ or ‘>’ respectively.
Elems
is the number of nonzero elements in $B$ or ${B}_{S}$.
Amax
is the largest nonzero in $B$ or ${B}_{S}$.
Density
is the percentage nonzero density of $B$ or ${B}_{S}$.
Merit/MerRP/MerCP
is the average Markowitz merit count for the elements chosen to be the diagonals of $PUQ$. Each merit count is defined to be $(c-1)(r-1)$ where $c$ and $r$ are the number of nonzeros in the column and row containing the element at the time it is selected to be the next diagonal. Merit is the average of n such quantities. It gives an indication of how much work was required to preserve sparsity during the factorization. If ${\mathbf{LU\; Complete\; Pivoting}}$ or ${\mathbf{LU\; Rook\; Pivoting}}$ has been selected, this heading is changed to MerCP, respectively MerRP.
lenL
is the number of nonzeros in $L$.
L+U
is the number of nonzeros representing the basis factors $L$ and $U$. Immediately after a basis factorization $B=LU$, L+U is lenL+lenU, the number of subdiagonal elements in the columns of a lower triangular matrix and the number of diagonal and superdiagonal elements in the rows of an upper-triangular matrix. Further nonzeros are added to L when various columns of $B$ are later replaced. As columns of $B$ are replaced, the matrix $U$ is maintained explicitly (in sparse form). The value of L will steadily increase, whereas the value of U may fluctuate up or down. Thus the value of L+U may fluctuate up or down (in general, it will tend to increase).
Cmpressns
is the number of times the data structure holding the partially factored matrix needed to be compressed to recover unused storage. Ideally this number should be zero. If it is more than $3$ or $4$, the amount of workspace available to e04wdc should be increased for efficiency.
Incres
is the percentage increase in the number of nonzeros in $L$ and $U$ relative to the number of nonzeros in $B$ or ${B}_{S}$.
Utri
is the number of triangular rows of $B$ or ${B}_{S}$ at the top of $U$.
lenU
the number of nonzeros in $U$, including its diagonals.
Ltol
is the largest subdiagonal element allowed in $L$. This is the specified ${\mathbf{LU\; Factor\; Tolerance}}$ or a smaller value that is currently being used for greater stability.
Umax
the maximum nonzero element in $U$.
Ugrwth
is the ratio $\mathtt{Umax}/\mathtt{Amax}$, which ideally should not be substantially larger than $10.0$ or $100.0$. If it is orders of magnitude larger, it may be advisable to reduce the ${\mathbf{LU\; Factor\; Tolerance}}$ to $5.0$, $4.0$, $3.0$ or $2.0$, say (but bigger than $1.0$).
As long as Lmax is not large (say $5.0$ or less), $\mathrm{max}\phantom{\rule{0.125em}{0ex}}(\mathtt{Amax},\mathtt{Umax})/\mathtt{DUmin}$ gives an estimate of the condition number $B$. If this is extremely large, the basis is nearly singular. Slacks are used to replace suspect columns of $B$ and the modified basis is refactored.
Ltri
is the number of triangular columns of $B$ or ${B}_{S}$ at the left of $L$.
dense1
is the number of columns remaining when the density of the basis matrix being factorized reached $0.3$.
Lmax
is the actual maximum subdiagonal element in $L$ (bounded by Ltol).
Akmax
is the largest nonzero generated at any stage of the $LU$ factorization. (Values much larger than Amax indicate instability.) Akmax is not printed if ${\mathbf{LU\; Partial\; Pivoting}}$ is selected.
Agrwth
is the ratio $\mathtt{Akmax}/\mathtt{Amax}$. Values much larger than $100$ (say) indicate instability. Growth is not printed if ${\mathbf{LU\; Partial\; Pivoting}}$ is selected.
bump
is the size of the block to be factorized nontrivially after the triangular rows and columns of $B$ or ${B}_{S}$ have been removed.
dense2
is the number of columns remaining when the density of the basis matrix being factorized reached $0.6$. (The Markowitz pivot strategy searches fewer columns at that stage.)
DUmax
is the largest diagonal of $PUQ$.
DUmin
is the smallest diagonal of $PUQ$.
condU
the ratio $\mathtt{DUmax}/\mathtt{DUmin}$, which estimates the condition number of $U$ (and of $B$ if Ltol is less than $5.0$, say).
13.5The Solution File
At the end of a run, the final solution may be output as a Solution file, according to ${\mathbf{Solution\; File}}$. Some header information appears first to identify the problem and the final state of the optimization procedure. A ROWS section and a COLUMNS section then follow, giving one line of information for each row and column. The format used is similar to certain commercial systems, though there is no industry standard.
The maximum record length is $111$ characters.
To reduce clutter, a full stop (.) is printed for any numerical value that is exactly zero. The values $\pm 1$ are also printed specially as $1.0$ and $-1.0$. Infinite bounds ($\pm {10}^{20}$ or larger) are printed as None.
A Solution file is intended to be read from disk by a self-contained program that extracts and saves certain values as required for possible further computation. Typically, the first $14$ records would be ignored.
The end of the ROWS section is marked by a record that starts with a $1$ and is otherwise blank. If this and the next $4$ records are skipped, the COLUMNS section can then be read
in the same manner.
13.5.1The ROWS section
General linear constraints take the form $l\le Ax\le u$. The $i$th constraint is, therefore, of the form
$$\alpha \le {\nu}_{i}x\le \beta \text{,}$$
where ${\nu}_{i}$ is the $i$th row of $A$.
Internally, the constraints take the form $Ax-s=0$, where $s$ is the set of slack variables (which happen to satisfy the bounds $l\le s\le u$). For the $i$th constraint it is the slack variable ${s}_{i}$ that is directly available, and it is sometimes convenient to refer to its state. Nonlinear constraints $\alpha \le {c}_{i}\left(x\right)+{v}_{i}x\le \beta $ are treated similarly, except that the row activity and degree of infeasibility are computed directly from ${c}_{i}\left(x\right)+{v}_{i}x$ rather than ${s}_{i}$. A fullstop (.) is printed for any numerical value that is exactly zero.
Label
Description
Number
is the value of $n+i$. (This is used internally to refer to ${s}_{i}$ in the intermediate output.)
Row
gives the name of the $i$th row.
State
the state of the $i$th row relative to the bounds $\alpha $ and $\beta $. The various states possible are as follows:
LL
the row is at its lower limit, $\alpha $.
UL
the row is at its upper limit, $\beta $.
EQ
the limits are the same ($\alpha =\beta $).
FR
${s}_{i}$ is nonbasic and currently zero, even though it is free to take any value between its bounds $\alpha $ and $\beta $.
BS
${s}_{i}$ is basic.
SBS
${s}_{i}$ is superbasic.
A key is sometimes printed before State.
Note that unless the optional parameter ${\mathbf{Scale\; Option}}=0$ is specified, the tests for assigning a key are applied to the variables of the scaled problem.
A
Alternative optimum possible. The variable is nonbasic, but its reduced gradient is essentially zero. This means that if the variable were allowed to start moving away from its bound, there would be no change in the value of the objective function. The values of the other free variables might change, giving a genuine alternative solution. However, if there are any degenerate variables (labelled D), the actual change might prove to be zero, since one of them could encounter a bound immediately. In either case, the values of the Lagrange multipliers might also change.
D
Degenerate. The variable is basic or superbasic, but it is equal (or very close) to one of its bounds.
I
Infeasible. The variable is basic or superbasic and is currently violating one of its bounds by more than the value of the ${\mathbf{Feasibility\; Tolerance}}$.
N
Not precisely optimal. The variable is nonbasic or superbasic. If the value of the reduced gradient for the variable exceeds the value of the optional parameter ${\mathbf{Major\; Optimality\; Tolerance}}$, the solution would not be declared optimal because the reduced gradient for the variable would not be considered negligible.
Activity
is the value of ${v}_{i}x$ (or ${c}_{i}\left(x\right)+{v}_{i}x$ for nonlinear rows) at the final iterate.
Slack Activity
is the value by which the row differs from its nearest bound. (For the free row (if any), it is set to Activity.)
Lower Limit
is $\alpha $, the lower bound on the row.
Upper Limit
is $\beta $, the upper bound on the row.
Dual Activity
is the value of the dual variable ${\pi}_{i}$ (the Lagrange multiplier for the $i$th constraint). The full vector $\pi $ always satisfies ${B}^{\mathrm{T}}\pi ={g}_{B}$, where $B$ is the current basis matrix and ${g}_{B}$ contains the associated gradients for the current objective function. For FP problems, ${\pi}_{i}$ is set to zero.
i
gives the index $i$ of the $i$th row.
13.5.2The COLUMNS section
Let the $j$th component of $x$ be the variable ${x}_{j}$ and assume that it satisfies the bounds $\alpha \le {x}_{j}\le \beta $. A fullstop (.) is printed for any numerical value that is exactly zero.
Label
Description
Number
is the column number $j$. (This is used internally to refer to ${x}_{j}$ in the intermediate output.)
Column
gives the name of ${x}_{j}$.
State
the state of ${x}_{j}$ relative to the bounds $\alpha $ and $\beta $. The various states possible are as follows:
LL
${x}_{j}$ is nonbasic at its lower limit, $\alpha $.
UL
${x}_{j}$ is nonbasic at its upper limit, $\beta $.
EQ
${x}_{j}$ is nonbasic and fixed at the value $\alpha =\beta $.
FR
${x}_{j}$ is nonbasic at some value strictly between its bounds: $\alpha <{x}_{j}<\beta $.
BS
${x}_{j}$ is basic. Usually $\alpha <{x}_{j}<\beta $.
SBS
${x}_{j}$ is superbasic. Usually $\alpha <{x}_{j}<\beta $.
A key is sometimes printed before State.
Note that unless the optional parameter ${\mathbf{Scale\; Option}}=0$ is specified, the tests for assigning a key are applied to the variables of the scaled problem.
A
Alternative optimum possible. The variable is nonbasic, but its reduced gradient is essentially zero. This means that if the variable were allowed to start moving away from its bound, there would be no change in the value of the objective function. The values of the other free variables might change, giving a genuine alternative solution. However, if there are any degenerate variables (labelled D), the actual change might prove to be zero, since one of them could encounter a bound immediately. In either case, the values of the Lagrange multipliers might also change.
D
Degenerate. The variable is basic or superbasic, but it is equal (or very close) to one of its bounds.
I
Infeasible. The variable is basic or superbasic and is currently violating one of its bounds by more than the value of the ${\mathbf{Feasibility\; Tolerance}}$.
N
Not precisely optimal. The variable is nonbasic or superbasic. If the value of the reduced gradient for the variable exceeds the value of the optional parameter ${\mathbf{Major\; Optimality\; Tolerance}}$, the solution would not be declared optimal because the reduced gradient for the variable would not be considered negligible.
Activity
is the value of ${x}_{j}$ at the final iterate.
Obj Gradient
is the value of ${g}_{j}$ at the final iterate. For FP problems, ${g}_{j}$ is set to zero.
Lower Limit
is the lower bound specified for the variable. None indicates that ${\mathbf{bl}}\left[j-1\right]\le -\mathit{bigbnd}$.
Upper Limit
is the upper bound specified for the variable. None indicates that ${\mathbf{bu}}\left[j-1\right]\ge \mathit{bigbnd}$.
Reduced Gradnt
is the value of the reduced gradient ${d}_{j}={g}_{j}-{\pi}^{\mathrm{T}}{a}_{j}$ where ${a}_{j}$ is the $j$th column of the constraint matrix. For FP problems, ${d}_{j}$ is set to zero.
m + j
is the value of $m+j$.
Note that movement off a constraint (as opposed to a variable moving away from its bound) can be interpreted as allowing the entry in the Slack Activity column to become positive.
Numerical values are output with a fixed number of digits; they are not guaranteed to be accurate to this precision.
13.6The Summary File
If ${\mathbf{Summary\; File}}>0$,
the following information is output to the
${\mathbf{Summary\; File}}$. (It is a brief summary of the output directed to unit ${\mathbf{Print\; File}}$):
–the optional parameters supplied via the option setting functions, if any;