PDF version (NAG web site
, 64bit version, 64bit version)
NAG Toolbox: nag_opt_nlp2_sparse_solve (e04vh)
Purpose
nag_opt_nlp2_sparse_solve (e04vh) solves sparse linear and nonlinear programming problems.
Syntax
[
x,
xstate,
xmul,
f,
fstate,
fmul,
ns,
ninf,
sinf,
cw,
iw,
rw,
user,
ifail] = e04vh(
start,
objadd,
objrow,
prob,
usrfun,
iafun,
javar,
nea,
a,
igfun,
jgvar,
neg,
xlow,
xupp,
xnames,
flow,
fupp,
fnames,
x,
xstate,
f,
fstate,
fmul,
ns,
cw,
iw,
rw, 'nf',
nf, 'n',
n, 'nxname',
nxname, 'nfname',
nfname, 'lena',
lena, 'leng',
leng, 'user',
user)
[
x,
xstate,
xmul,
f,
fstate,
fmul,
ns,
ninf,
sinf,
cw,
iw,
rw,
user,
ifail] = nag_opt_nlp2_sparse_solve(
start,
objadd,
objrow,
prob,
usrfun,
iafun,
javar,
nea,
a,
igfun,
jgvar,
neg,
xlow,
xupp,
xnames,
flow,
fupp,
fnames,
x,
xstate,
f,
fstate,
fmul,
ns,
cw,
iw,
rw, 'nf',
nf, 'n',
n, 'nxname',
nxname, 'nfname',
nfname, 'lena',
lena, 'leng',
leng, 'user',
user)
Note: the interface to this routine has changed since earlier releases of the toolbox:
Mark 22: lencw, leniw, lenrw have been removed from the interface
.
Description
nag_opt_nlp2_sparse_solve (e04vh) is designed to minimize a linear or nonlinear function subject to bounds on the variables and sparse linear or nonlinear constraints. It is suitable for largescale linear and quadratic programming and for linearly constrained optimization, as well as for general nonlinear programs of the form
where
x
$x$ is an
n
$n$vector of variables,
l
$l$ and
u
$u$ are constant lower and upper bounds,
f_{0}
(x)
${f}_{0}\left(x\right)$ is a smooth scalar objective function,
A_{L}
${A}_{L}$ is a sparse matrix, and
f(x)
$f\left(x\right)$ is a vector of smooth nonlinear constraint functions
{f_{i}(x)}
$\left\{{f}_{i}\left(x\right)\right\}$. The optional parameter
Maximize specifies that
f_{0}(x)
${f}_{0}\left(x\right)$ should be maximized instead of minimized.
Ideally, the first derivatives (gradients) of
f_{0}(x)
${f}_{0}\left(x\right)$ and
f_{i}(x)
${f}_{i}\left(x\right)$ should be known and coded by you. If only some of the gradients are known, nag_opt_nlp2_sparse_solve (e04vh) estimates the missing ones by finite differences.
If
f_{0}(x)
${f}_{0}\left(x\right)$ is linear and
f(x)
$f\left(x\right)$ is absent,
(1) is a linear program (LP) and
nag_opt_nlp2_sparse_solve (e04vh) applies the primal simplex method (see
Dantzig (1963)). Sparse basis factors are maintained by LUSOL (see
Gill et al. (1987)) as in MINOS (see
Murtagh and Saunders (1995)).
If only the objective is nonlinear, the problem is linearly constrained (LC) and tends to solve more easily than the general case with nonlinear constraints (NC). For both nonlinear cases,
nag_opt_nlp2_sparse_solve (e04vh) applies a sparse sequential quadratic programming (SQP) method (see
Gill et al. (2002)), using limitedmemory quasiNewton approximations to the Hessian of the Lagrangian. The merit function for steplength control is an augmented Lagrangian, as in the dense SQP solver
nag_opt_nlp2_solve (e04wd) (see
Gill et al. (1986) and
Gill et al. (1992)).
nag_opt_nlp2_sparse_solve (e04vh) is suitable for nonlinear problems with thousands of constraints and variables, and is most efficient if only some of the variables enter nonlinearly, or there are relatively few degrees of freedom at a solution (i.e., many constraints are active). However, there is no limit on the number of degrees of freedom.
nag_opt_nlp2_sparse_solve (e04vh) allows linear and nonlinear constraints and variables to be entered in an arbitrary order, and uses one function to define all the nonlinear functions.
The optimization problem is assumed to be in the form
where the upper and lower bounds are constant,
F(x)
$F\left(x\right)$ is a vector of smooth linear and nonlinear constraint functions
{F_{i}(x)}
$\left\{{F}_{i}\left(x\right)\right\}$, and
F_{obj}
(x)
${F}_{\mathrm{obj}}\left(x\right)$ is one of the components of
F
$F$ to be minimized, as specified by the input parameter
objrow.
nag_opt_nlp2_sparse_solve (e04vh) reorders the variables and constraints so that the problem is in the form
(1).
Upper and lower bounds are specified for all variables and functions. The
j
$j$th constraint may be defined as an equality by setting
l_{j}
=
u_{j}
${l}_{j}={u}_{j}$. If certain bounds are not present, the associated elements of l$l$ or u$u$ should be set to special values that are treated as − ∞$\infty $ or + ∞$+\infty $. Free variables and free constraints (‘free rows’) have both bounds infinite.
In general, the components of
F
$F$ are structured in the sense that they are formed from sums of linear and nonlinear functions of just some of the variables. This structure can be exploited by nag_opt_nlp2_sparse_solve (e04vh).
In many cases, the vector
F(x)
$F\left(x\right)$ is a sum of linear and nonlinear functions.
nag_opt_nlp2_sparse_solve (e04vh) allows these terms to be specified separately, so that the linear part is defined just once by the input arguments
iafun,
javar and
a. Only the nonlinear part is recomputed at each
x
$x$.
Suppose that each component of
F(x)
$F\left(x\right)$ is of the form
where
f_{i}(x)
${f}_{i}\left(x\right)$ is a nonlinear function (possibly zero) and the elements
A_{ij}
${A}_{ij}$ are constant. The
nf
$nf$ by
n
$n$ Jacobian of
F(x)
$F\left(x\right)$ is the sum of two sparse matrices of the same size:
F^{′}(x)
=
G(x)
+
A
${F}^{\prime}\left(x\right)=G\left(x\right)+A$, where
G(x)
=
f^{′}(x)
$G\left(x\right)={f}^{\prime}\left(x\right)$ and
A
$A$ is the matrix with elements
{A_{ij}}
$\left\{{A}_{ij}\right\}$. The two matrices must be
nonoverlapping in the sense that each element of the Jacobian
F^{′}(x)
=
G(x)
+
A
${F}^{\prime}\left(x\right)=G\left(x\right)+A$ comes from
G(x)
$G\left(x\right)$ or
A
$A$, but
not both. The element cannot be split between
G(x)
$G\left(x\right)$ and
A
$A$.
For example, the function
can be written as
in which case
can be written as
F^{′}(x)
=
f^{′}(x)
+
A
=
G(x)
+
A
${F}^{\prime}\left(x\right)={f}^{\prime}\left(x\right)+A=G\left(x\right)+A$, where
Note: the element
e^{x2} + 4
${e}^{{x}_{2}}+4$ of
F^{′}(x)
${F}^{\prime}\left(x\right)$ appears in
G(x)
$G\left(x\right)$ and is not split between
G(x)
$G\left(x\right)$ and
A
$A$ although it contains a linear term.
The nonzero elements of
A
$A$ and
G
$G$ are provided to
nag_opt_nlp2_sparse_solve (e04vh) in coordinate form. The elements of
A
$A$ are entered as triples
(i,j,A_{ij})
$(i,j,{A}_{ij})$ in the arrays
iafun,
javar and
a. The sparsity pattern
G
$G$ is entered as pairs
(i,j)
$(i,j)$ in the arrays
igfun and
jgvar. The corresponding entries
G_{ij}
${G}_{ij}$ (any that are known) are assigned to appropriate array elements
g(k)
${\mathbf{g}}\left(k\right)$ in
usrfun.
The elements of
A
$A$ and
G
$G$ may be stored in any order. Duplicate entries are ignored.
igfun and
jgvar may be defined automatically by function
nag_opt_nlp2_sparse_jacobian (e04vj) when
Derivative Option = 0${\mathbf{Derivative\; Option}}=0$ is specified and
usrfun does not provide any gradients.
Throughout this document the symbol
ε$\epsilon $ is used to represent the
machine precision (see
nag_machine_precision (x02aj)).
nag_opt_nlp2_sparse_solve (e04vh) is based on SNOPTA, which is part of the SNOPT package described in
Gill et al. (2005b).
References
Dantzig G B (1963) Linear Programming and Extensions Princeton University Press
Eldersveld S K (1991) Largescale 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. Programming 23 274–313
Gill P E, Murray W and Saunders M A (2002) SNOPT: An SQP Algorithm for Largescale Constrained Optimization 12 979–1006 SIAM J. Optim.
Gill P E, Murray W and Saunders M A (2005a) Users' guide for SQOPT 7: a Fortran package for largescale linear and quadratic programming
Report NA 051 Department of Mathematics, University of California, San Diego
ftp://www.cam.ucsd.edu/pub/peg/reports/sqdoc7.pdf
Gill P E, Murray W and Saunders M A (2005b) Users' guide for SNOPT 7.1: a Fortran package for largescale linear nonlinear programming
Report NA 052 Department of Mathematics, University of California, San Diego
ftp://www.cam.ucsd.edu/pub/peg/reports/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 862 Department of Operations Research, Stanford University
Gill P E, Murray W, Saunders M A and Wright M H (1987) Maintaining LU factors of a general sparse matrix Linear Algebra and its Applics. 88/89 239–270
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
Hock W and Schittkowski K (1981) Test Examples for Nonlinear Programming Codes. Lecture Notes in Economics and Mathematical Systems 187 Springer–Verlag
Murtagh B A and Saunders M A (1978) Largescale linearly constrained optimization 14 41–72 Math. Programming
Murtagh B A and Saunders M A (1982) A projected Lagrangian algorithm and its implementation for sparse nonlinear constraints Math. Program. Stud. 16 84–118
Murtagh B A and Saunders M A (1995) MINOS 5.4 users' guide Report SOL 8320R Department of Operations Research, Stanford University
Parameters
Compulsory Input Parameters
 1:
start – int64int32nag_int scalar
Indicates how a starting point is to be obtained.
 start = 0${\mathbf{start}}=0$
 Requests that the Crash procedure be used, unless a Basis file is provided via optional parameters Old Basis File, Insert File or Load File.
 start = 1${\mathbf{start}}=1$
 Is the same as start = 0${\mathbf{start}}=0$ but is more meaningful when a Basis file is given.
 start = 2${\mathbf{start}}=2$
 Means that xstate and fstate define a valid starting point (probably from an earlier call, though not necessarily).
Constraint:
start = 0${\mathbf{start}}=0$,
1$1$ or
2$2$.
 2:
objadd – double scalar
Is a constant that will be added to the objective row
F_{obj}${F}_{\mathrm{obj}}$ for printing purposes. Typically,
objadd = 0.0${\mathbf{objadd}}=0.0$.
 3:
objrow – int64int32nag_int scalar
Says which row of
F(x)$F\left(x\right)$ is to act as the objective function. If there is no such row, set
objrow = 0 ${\mathbf{objrow}}=0$. Then
nag_opt_nlp2_sparse_solve (e04vh) will seek a feasible point such that
l_{F} ≤ F(x) ≤ u_{F} ${l}_{F}\le F\left(x\right)\le {u}_{F}$ and
l_{x} ≤ x ≤ u_{x} ${l}_{x}\le x\le {u}_{x}$.
Constraint:
1 ≤ objrow ≤ nf or objrow = 0$1\le {\mathbf{objrow}}\le {\mathbf{nf}}\text{ or}{\mathbf{objrow}}=0$ (or a feasible point problem).
 4:
prob – string (length at least 8) (length ≥ 8)
Is an
8$8$character name for the problem.
prob is used in the printed solution and in some functions that output Basis files. A blank name may be used.
 5:
usrfun – function handle or string containing name of mfile
usrfun must define the nonlinear portion
f(x) $f\left(x\right)$ of the problem functions
F(x) = f(x) + Ax $F\left(x\right)=f\left(x\right)+Ax$, along with its gradient elements
G_{ij} (x) = ( ∂ f_{i}(x) )/( ∂ x_{j} ) ${G}_{ij}\left(x\right)=\frac{\partial {f}_{i}\left(x\right)}{\partial {x}_{j}}$. (A dummy function is needed even if
f ≡ 0 $f\equiv 0$ and all functions are linear.)
In general,
usrfun should return all function and gradient values on every entry except perhaps the last. This provides maximum reliability and corresponds to the default option setting,
Derivative Option = 1${\mathbf{Derivative\; Option}}=1$.
The elements of
G(x) $G\left(x\right)$ are stored in the array
g(1 : leng) ${\mathbf{g}}(1:{\mathbf{leng}})$ in the order specified by the input arrays
igfun and
jgvar.
In practice it is often convenient
not to code gradients.
nag_opt_nlp2_sparse_solve (e04vh) is able to estimate them by finite differences, using a call to
usrfun for each variable
x_{j} ${x}_{j}$ for which some
( ∂ f_{i}(x) )/( ∂ x_{j} ) $\frac{\partial {f}_{i}\left(x\right)}{\partial {x}_{j}}$ needs to be estimated. However, this reduces the reliability of the optimization algorithm, and it can be very expensive if there are many such variables
x_{j} ${x}_{j}$.
As a compromise,
nag_opt_nlp2_sparse_solve (e04vh) allows you to code
as many gradients as you like. This option is implemented as follows. Just before
usrfun is called, each element of the derivative array
g is initialized to a specific value. On exit, any element retaining that value must be estimated by finite differences.
Some rules of thumb follow:
(i) 
for maximum reliability, compute all gradients; 
(ii) 
if the gradients are expensive to compute, specify optional parameter Nonderivative Linesearch and use the value of the input parameter needg to avoid computing them on certain entries. (There is no need to compute gradients if needg = 0${\mathbf{needg}}=0$ on entry to usrfun.); 
(iii) 
if not all gradients are known, you must specify Derivative Option = 0${\mathbf{Derivative\; Option}}=0$. You should still compute as many gradients as you can. (It often happens that some of them are constant or zero.); 
(iv) 
again, if the known gradients are expensive, don't compute them if needg = 0${\mathbf{needg}}=0$ on entry to usrfun; 
(v) 
use the input parameter status to test for special actions on the first or last entries; 
(vi) 
while usrfun is being developed, use the optional parameter Verify Level to check the computation of gradients that are supposedly known; 
(vii) 
usrfun is not called until the linear constraints and bounds on x $x$ are satisfied. This helps confine x $x$ to regions where the functions f_{i}(x) ${f}_{i}\left(x\right)$ are likely to be defined. However, be aware of the optional parameter Minor Feasibility Tolerance if the functions have singularities on the constraint boundaries; 
(viii) 
set status = − 1 ${\mathbf{status}}=1$ if some of the functions are undefined. The linesearch will shorten the step and try again; 
(ix) 
set status ≤ − 2 ${\mathbf{status}}\le 2$ if you want nag_opt_nlp2_sparse_solve (e04vh) to stop. 
[status, f, g, user] = usrfun(status, n, x, needf, nf, f, needg, leng, g, user)
Input Parameters
 1:
status – int64int32nag_int scalar
Indicates the first and last calls to
usrfun.
 status = 0 ${\mathbf{status}}=0$
 There is nothing special about the current call to usrfun.
 status = 1 ${\mathbf{status}}=1$
 nag_opt_nlp2_sparse_solve (e04vh) is calling your function for the first time. You may wish to do something special such as read data from a file.
 status ≥ 2 ${\mathbf{status}}\ge 2$
 nag_opt_nlp2_sparse_solve (e04vh) is calling your function for the last time. This parameter setting allows you to perform some additional computation on the final solution.
 status = 2${\mathbf{status}}=2$
 The current x is optimal.
 status = 3${\mathbf{status}}=3$
 The problem appears to be infeasible.
 status = 4${\mathbf{status}}=4$
 The problem appears to be unbounded.
 status = 5${\mathbf{status}}=5$
 An iterations limit was reached.
If the functions are expensive to evaluate, it may be desirable to do nothing on the last call. The first executable statement could be
if (status ≥ 2) return; end
 2:
n – int64int32nag_int scalar
n $n$, the number of variables, as defined in the call to nag_opt_nlp2_sparse_solve (e04vh).
 3:
x(n) – double array
The variables x $x$ at which the problem functions are to be calculated. The array x $x$ must not be altered.
 4:
needf – int64int32nag_int scalar
Indicates whether
f must be assigned during this call of
usrfun.
 needf = 0${\mathbf{needf}}=0$
 f is not required and is ignored.
 needf > 0${\mathbf{needf}}>0$
 The components of f(x) $f\left(x\right)$ corresponding to the nonlinear part of F(x) $F\left(x\right)$ must be calculated and assigned to f.
If
F_{i}(x) ${F}_{i}\left(x\right)$ is linear and completely defined by the
i $i$th row of
A $A$,
A_{i}^{ ′ } ${A}_{i}^{\prime}$, then the associated value
f_{i}(x) ${f}_{i}\left(x\right)$ is ignored and need not be assigned. However, if
F_{i}(x) ${F}_{i}\left(x\right)$ has a nonlinear portion
f_{i}(x) ${f}_{i}\left(x\right)$ that happens to be zero at
x $x$, then it is still necessary to set
f_{i}(x) = 0 ${f}_{i}\left(x\right)=0$. If the linear part
A_{i}^{ ′ } ${A}_{i}^{\prime}$ of a nonlinear
F_{i}(x) ${F}_{i}\left(x\right)$ is provided using the arrays
iafun,
javar and
a, then it must not be computed again as part of
f_{i}(x) ${f}_{i}\left(x\right)$.
To simplify the code, you may ignore the value of
needf and compute
f(x) $f\left(x\right)$ on every entry to
usrfun.
needf may also be ignored with
Derivative Linesearch and
Derivative Option = 1${\mathbf{Derivative\; Option}}=1$. In this case,
needf is always
1$1$, and
f must always be assigned.
 5:
nf – int64int32nag_int scalar
Is the length of the full vector F(x) = f(x) + Ax $F\left(x\right)=f\left(x\right)+Ax$ as defined in the call to nag_opt_nlp2_sparse_solve (e04vh).
 6:
f(nf) – double array
Concerns the calculation of f(x) $f\left(x\right)$.
 7:
needg – int64int32nag_int scalar
Indicates whether
g must be assigned during this call of
usrfun.
 needg = 0${\mathbf{needg}}=0$
 g is not required and is ignored.
 needg > 0${\mathbf{needg}}>0$
 The partial derivatives of f(x) $f\left(x\right)$ must be calculated and assigned to g. The value of g(k)${\mathbf{g}}\left(k\right)$ should be ( ∂ f_{i}(x))/( ∂ x_{j})$\frac{\partial {f}_{i}\left(x\right)}{\partial {x}_{j}}$, where i = igfun(k)$i={\mathbf{igfun}}\left(k\right)$, j = jgvar(k)$j={\mathbf{jgvar}}\left(k\right)$ and k = 1,2, … ,leng$k=1,2,\dots ,{\mathbf{leng}}$.
 8:
leng – int64int32nag_int scalar
Is the length of the coordinate arrays
jgvar and
igfun in the call to
nag_opt_nlp2_sparse_solve (e04vh).
 9:
g(leng) – double array
Concerns the calculations of the derivatives of the function f(x) $f\left(x\right)$.
 10:
user – Any MATLAB object
usrfun is called from
nag_opt_nlp2_sparse_solve (e04vh) with the object supplied to
nag_opt_nlp2_sparse_solve (e04vh).
Output Parameters
 1:
status – int64int32nag_int scalar
May be used to indicate that you are unable to evaluate
f $f$ or its gradients at the current
x $x$. (For example, the problem functions may not be defined there.)
During the linesearch,
f(x) $f\left(x\right)$ is evaluated at points
x = x_{k} + α p_{k} $x={x}_{k}+\alpha {p}_{k}$ for various step lengths
α $\alpha $, where
f(x_{k}) $f\left({x}_{k}\right)$ has already been evaluated satisfactorily. For any such
x $x$, if you set
status = − 1 ${\mathbf{status}}=1$,
nag_opt_nlp2_sparse_solve (e04vh) will reduce
α $\alpha $ and evaluate
f $f$ again (closer to
x_{k} ${x}_{k}$, where
f(x_{k}) $f\left({x}_{k}\right)$ is more likely to be defined).
If for some reason you wish to terminate the current problem, set
status ≤ − 2 ${\mathbf{status}}\le 2$.
 2:
f(nf) – double array
f contains the computed functions
f(x) $f\left(x\right)$ (except perhaps if
needf = 0${\mathbf{needf}}=0$).
 3:
g(leng) – double array
Contains the computed derivatives
G(x) $G\left(x\right)$ (unless
needg = 0${\mathbf{needg}}=0$).
These derivative elements must be stored in
g in exactly the same positions as implied by the definitions of arrays
igfun and
jgvar. There is no internal check for consistency (except indirectly via the optional parameter
Verify Level), so great care is essential.
 4:
user – Any MATLAB object
 6:
iafun(lena) – int64int32nag_int array
 7:
javar(lena) – int64int32nag_int array
lena, the dimension of the array, must satisfy the constraint
lena ≥ 1${\mathbf{lena}}\ge 1$.
Define the coordinates
(i,j) $(i,j)$ of the nonzero elements of the linear part
A $A$ of the function
F(x) = f(x) + Ax $F\left(x\right)=f\left(x\right)+Ax$.
In particular,
nea triples
(iafun(k),javar(k),a(k))$({\mathbf{iafun}}\left(k\right),{\mathbf{javar}}\left(k\right),{\mathbf{a}}\left(k\right))$ define the row and column indices
i = iafun(k)$i={\mathbf{iafun}}\left(k\right)$ and
j = javar(k)$j={\mathbf{javar}}\left(k\right)$ of the element
A_{ij} = a(k)${A}_{ij}={\mathbf{a}}\left(k\right)$.
The coordinates may define the elements of A $A$ in any order.
 8:
nea – int64int32nag_int scalar
Is the number of nonzero entries in A $A$ such that F(x) = f(x) + Ax $F\left(x\right)=f\left(x\right)+Ax$.
Constraint:
0 ≤ nea ≤ lena$0\le {\mathbf{nea}}\le {\mathbf{lena}}$.
 9:
a(lena) – double array
lena, the dimension of the array, must satisfy the constraint
lena ≥ 1${\mathbf{lena}}\ge 1$.
Define the values
A_{ij} ${A}_{ij}$ of the nonzero elements of the linear part
A $A$ of the function
F(x) = f(x) + Ax $F\left(x\right)=f\left(x\right)+Ax$.
In particular,
nea triples
(iafun(k),javar(k),a(k))$({\mathbf{iafun}}\left(k\right),{\mathbf{javar}}\left(k\right),{\mathbf{a}}\left(k\right))$ define the row and column indices
i = iafun(k)$i={\mathbf{iafun}}\left(k\right)$ and
j = javar(k)$j={\mathbf{javar}}\left(k\right)$ of the element
A_{ij} = a(k)${A}_{ij}={\mathbf{a}}\left(k\right)$.
The coordinates may define the elements of A $A$ in any order.
 10:
igfun(leng) – int64int32nag_int array
 11:
jgvar(leng) – int64int32nag_int array
leng, the dimension of the array, must satisfy the constraint
leng ≥ 1${\mathbf{leng}}\ge 1$.
Define the coordinates
(i,j) $(i,j)$ of the nonzero elements of
G $G$, the nonlinear part of the derivative
J(x) = G(x) + A $J\left(x\right)=G\left(x\right)+A$ of the function
F(x) = f(x) + Ax $F\left(x\right)=f\left(x\right)+Ax$.
nag_opt_nlp2_sparse_jacobian (e04vj) may be used to define these two arrays.
The coordinates can define the elements of
G $G$ in any order. However,
usrfun must define the actual elements of
g in exactly the same order as defined by the coordinates
(igfun,jgvar) $({\mathbf{igfun}},{\mathbf{jgvar}})$.
 12:
neg – int64int32nag_int scalar
The number of nonzero entries in G $G$.
Constraint:
0 ≤ neg ≤ leng$0\le {\mathbf{neg}}\le {\mathbf{leng}}$.
 13:
xlow(n) – double array
 14:
xupp(n) – double array
n, the dimension of the array, must satisfy the constraint
n > 0${\mathbf{n}}>0$.
Contain the lower and upper bounds
l_{x} ${l}_{x}$ and
u_{x} ${u}_{x}$ on the variables
x $x$.
To specify a nonexistent lower bound
[l_{x}]_{j} = − ∞ ${\left[{l}_{x}\right]}_{j}=\infty $, set
xlow(j) ≤ − bigbnd ${\mathbf{xlow}}\left(j\right)\le \mathit{bigbnd}$, where
bigbnd $\mathit{bigbnd}$ is the optional parameter
Infinite Bound Size. To specify a nonexistent upper bound
[u_{x}]_{j} = ∞ ${\left[{u}_{x}\right]}_{j}=\infty $, set
xupp(j) ≥ bigbnd${\mathbf{xupp}}\left(j\right)\ge \mathit{bigbnd}$.
To fix the
j$j$th variable at
x_{j} = β ${x}_{j}=\beta $, where
β < bigbnd$\left\beta \right<\mathit{bigbnd}$, set
xlow(j) = xupp(j) = β ${\mathbf{xlow}}\left(j\right)={\mathbf{xupp}}\left(j\right)=\beta $.
Constraint:
xlow(i) ≤ xupp(i)${\mathbf{xlow}}\left(\mathit{i}\right)\le {\mathbf{xupp}}\left(\mathit{i}\right)$, for
i = 1,2, … ,n$\mathit{i}=1,2,\dots ,{\mathbf{n}}$.
 15:
xnames(nxname) – cell array of strings
nxname, the dimension of the array, must satisfy the constraint
nxname = 1 or n${\mathbf{nxname}}=1\text{ or}{\mathbf{n}}$.
The optional names for the variables.
If
nxname = 1 ${\mathbf{nxname}}=1$,
xnames is not referenced and default names will be used for output.
If
nxname = n ${\mathbf{nxname}}={\mathbf{n}}$,
xnames(j) ${\mathbf{xnames}}\left(j\right)$ should contain the
8$8$character name of the
j $j$th variable.
 16:
flow(nf) – double array
 17:
fupp(nf) – double array
nf, the dimension of the array, must satisfy the constraint
nf > 0${\mathbf{nf}}>0$.
Contain the lower and upper bounds
l_{F} ${l}_{F}$ and
u_{F} ${u}_{F}$ on
F(x) $F\left(x\right)$.
To specify a nonexistent lower bound
[l_{F}]_{i} = − ∞ ${\left[{l}_{F}\right]}_{i}=\infty $, set
flow(i) ≤ − bigbnd${\mathbf{flow}}\left(i\right)\le \mathit{bigbnd}$. For a nonexistent upper bound
[u_{F}]_{i} = ∞ ${\left[{u}_{F}\right]}_{i}=\infty $, set
fupp(i) ≥ bigbnd ${\mathbf{fupp}}\left(i\right)\ge \mathit{bigbnd}$.
To make the
i $i$th constraint an
equality at
F_{i} = β ${F}_{i}=\beta $, where
β < bigbnd $\left\beta \right<\mathit{bigbnd}$, set
flow(i) = fupp(i) = β${\mathbf{flow}}\left(i\right)={\mathbf{fupp}}\left(i\right)=\beta $.
Constraint:
flow(i) ≤ fupp(i)${\mathbf{flow}}\left(\mathit{i}\right)\le {\mathbf{fupp}}\left(\mathit{i}\right)$, for
i = 1,2, … ,n$\mathit{i}=1,2,\dots ,{\mathbf{n}}$.
 18:
fnames(nfname) – cell array of strings
nfname, the dimension of the array, must satisfy the constraint
nfname = 1 or nf${\mathbf{nfname}}=1\text{ or}{\mathbf{nf}}$Note: if
nxname = 1${\mathbf{nxname}}=1$ then
nfname must also be
1$1$ (and vice versa). Similarly, if
nxname = n${\mathbf{nxname}}={\mathbf{n}}$ then
nfname must be
nf (and vice versa).
.
The optional names for the problem functions.
If
nfname = 1 ${\mathbf{nfname}}=1$,
fnames is not referenced and default names will be used for output.
If
nfname = nf ${\mathbf{nfname}}={\mathbf{nf}}$,
fnames(i) ${\mathbf{fnames}}\left(i\right)$ should contain the
8$8$character name of the
i $i$th row of
F $F$.
 19:
x(n) – double array
n, the dimension of the array, must satisfy the constraint
n > 0${\mathbf{n}}>0$.
An initial estimate of the variables
x $x$. See the following description of
xstate.
 20:
xstate(n) – int64int32nag_int array
n, the dimension of the array, must satisfy the constraint
n > 0${\mathbf{n}}>0$.
The initial state for each variable
x $x$.
If
start = 0${\mathbf{start}}=0$ or
1$1$ and no basis information is provided (the optional parameters
Old Basis File,
Insert File and
Load File are all set to
0$0$; the default)
x and
xstate must be defined.
If nothing special is known about the problem, or if there is no wish to provide special information, you may set
x(j) = 0.0${\mathbf{x}}\left(j\right)=0.0$,
xstate(j) = 0${\mathbf{xstate}}\left(j\right)=0$, for all
j = 1,2, … ,n $j=1,2,\dots ,{\mathbf{n}}$. If you set
x(j) = xlow(j) ${\mathbf{x}}\left(j\right)={\mathbf{xlow}}\left(j\right)$ set
xstate(j) = 4 ${\mathbf{xstate}}\left(j\right)=4$; if you set
x(j) = xupp(j) ${\mathbf{x}}\left(j\right)={\mathbf{xupp}}\left(j\right)$ then set
xstate(j) = 5 ${\mathbf{xstate}}\left(j\right)=5$. In this case a Crash procedure is used to select an initial basis.
If
start = 0${\mathbf{start}}=0$ or
1$1$ and basis information is provided (at least one of the optional parameters
Old Basis File,
Insert File and
Load File is nonzero)
x and
xstate need not be set.
If
start = 2${\mathbf{start}}=2$ (Warm Start),
x and
xstate must be set (probably from a previous call). In this case
xstate(j)${\mathbf{xstate}}\left(\mathit{j}\right)$ must be
0$0$,
1$1$,
2 or 3$2\text{ or}3$, for
j = 1,2, … ,n$\mathit{j}=1,2,\dots ,{\mathbf{n}}$.
Constraint:
0 ≤ xstate(j) ≤ 5, for j = 1,2, … ,n$0\le {\mathbf{xstate}}\left(j\right)\le 5\text{, for}j=1,2,\dots ,{\mathbf{n}}$.
 21:
f(nf) – double array
nf, the dimension of the array, must satisfy the constraint
nf > 0${\mathbf{nf}}>0$.
An initial value for the problem functions
F $F$. See the following description of
fstate.
 22:
fstate(nf) – int64int32nag_int array
nf, the dimension of the array, must satisfy the constraint
nf > 0${\mathbf{nf}}>0$.
The initial state for the problem functions
F$F$.
If
start = 0${\mathbf{start}}=0$ or
1$1$ and no basis information is provided (the optional parameters
Old Basis File,
Insert File and
Load File are all set to
0$0$; the default,
f and
fstate must be defined.
If nothing special is known about the problem, or if there is no wish to provide special information, you may set
f(i) = 0.0${\mathbf{f}}\left(i\right)=0.0$,
fstate(i) = 0${\mathbf{fstate}}\left(i\right)=0$, for all
i = 1,2, … ,nf$i=1,2,\dots ,{\mathbf{nf}}$. Less trivially, to say that the optimal value of function
f(i) ${\mathbf{f}}\left(i\right)$ will probably be equal to one of its bounds, set
f(i) = flow(i)${\mathbf{f}}\left(i\right)={\mathbf{flow}}\left(i\right)$ and
fstate(i) = 4${\mathbf{fstate}}\left(i\right)=4$ or
f(i) = fupp(i)${\mathbf{f}}\left(i\right)={\mathbf{fupp}}\left(i\right)$ and
fstate(i) = 5${\mathbf{fstate}}\left(i\right)=5$ as appropriate. In this case a Crash procedure is used to select an initial basis.
If
start = 0${\mathbf{start}}=0$ or
1$1$ and basis information is provided (at least one of the optional parameters
Old Basis File,
Insert File and
Load File is nonzero),
f and
fstate need not be set.
If
start = 2${\mathbf{start}}=2$ (Warm Start),
f and
fstate must be set (probably from a previous call). In this case
fstate(i) ${\mathbf{fstate}}\left(\mathit{i}\right)$ must be
0$0$,
1$1$,
2$2$ or
3$3$, for
i = 1,2, … ,nf$\mathit{i}=1,2,\dots ,{\mathbf{nf}}$.
Constraint:
0 ≤ fstate(i) ≤ 5, for i = 1,2, … ,nf$0\le {\mathbf{fstate}}\left(i\right)\le 5\text{, for}i=1,2,\dots ,{\mathbf{nf}}$.
 23:
fmul(nf) – double array
nf, the dimension of the array, must satisfy the constraint
nf > 0${\mathbf{nf}}>0$.
An estimate of
γ $\gamma $, the vector of Lagrange multipliers (shadow prices) for the constraints
l_{F} ≤ F(x) ≤ u_{F} ${l}_{F}\le F\left(x\right)\le {u}_{F}$. All
nf components must be defined. If nothing is known about
γ $\gamma $, set
fmul(i) = 0.0 ${\mathbf{fmul}}\left(\mathit{i}\right)=0.0$, for
i = 1,2, … ,nf$\mathit{i}=1,2,\dots ,{\mathbf{nf}}$. For warm start use the values from a previous call.
 24:
ns – int64int32nag_int scalar
The number of superbasic variables.
ns need not be specified for cold starts, but should retain its value from a previous call when warm start is used.
 25:
cw(lencw) – cell array of strings
lencw, the dimension of the array, must satisfy the constraint
lencw ≥ 600$\mathit{lencw}\ge 600$.
Constraint:
lencw ≥ 600$\mathit{lencw}\ge 600$.
 26:
iw(leniw) – int64int32nag_int array
leniw, the dimension of the array, must satisfy the constraint
leniw ≥ 600$\mathit{leniw}\ge 600$.
Constraint:
leniw ≥ 600$\mathit{leniw}\ge 600$.
 27:
rw(lenrw) – double array
lenrw, the dimension of the array, must satisfy the constraint
lenrw ≥ 600$\mathit{lenrw}\ge 600$.
Constraint:
lenrw ≥ 600$\mathit{lenrw}\ge 600$.
Optional Input Parameters
 1:
nf – int64int32nag_int scalar
Default:
For
nf, the dimension of the arrays
f,
fstate,
flow,
fupp,
fmul. (An error is raised if these dimensions are not equal.)
nf$\mathit{nf}$, the number of problem functions in
F(x) $F\left(x\right)$, including the objective function (if any) and the linear and nonlinear constraints. Upper and lower bounds on
x $x$ can be defined using the parameters
xlow and
xupp and should not be included in
F $F$.
Constraint:
nf > 0${\mathbf{nf}}>0$.
 2:
n – int64int32nag_int scalar
Default:
The dimension of the arrays
xlow,
xupp,
x,
xstate. (An error is raised if these dimensions are not equal.)
n$n$, the number of variables.
Constraint:
n > 0${\mathbf{n}}>0$.
 3:
nxname – int64int32nag_int scalar
Default:
The dimension of the array
xnames.
The number of names provided in the array
xnames.
 nxname = 1${\mathbf{nxname}}=1$
 There are no names provided and generic names will be used in the output.
 nxname = n${\mathbf{nxname}}={\mathbf{n}}$
 Names for all variables must be provided and will be used in the output.
Constraint:
nxname = 1 or n${\mathbf{nxname}}=1\text{ or}{\mathbf{n}}$.
 4:
nfname – int64int32nag_int scalar
Default:
The dimension of the array
fnames.
The number of names provided in the array
fnames.
 nfname = 1${\mathbf{nfname}}=1$
 There are no names provided and generic names will be used in the output.
 nfname = nf${\mathbf{nfname}}={\mathbf{nf}}$
 Names for all functions must be provided and will be used in the output.
Constraint:
nfname = 1 or nf${\mathbf{nfname}}=1\text{ or}{\mathbf{nf}}$.
Note: if
nxname = 1${\mathbf{nxname}}=1$ then
nfname must also be
1$1$ (and vice versa). Similarly, if
nxname = n${\mathbf{nxname}}={\mathbf{n}}$ then
nfname must be
nf (and vice versa).
 5:
lena – int64int32nag_int scalar
Default:
The dimension of the arrays
iafun,
javar,
a. (An error is raised if these dimensions are not equal.)
The dimension of the arrays
iafun,
javar and
a that hold
(i,j,A_{ij})$(i,j,{A}_{ij})$ as declared in the (sub)program from which
nag_opt_nlp2_sparse_solve (e04vh) is called.
Constraint:
lena ≥ 1${\mathbf{lena}}\ge 1$.
 6:
leng – int64int32nag_int scalar
Default:
The dimension of the arrays
igfun,
jgvar. (An error is raised if these dimensions are not equal.)
The dimension of the arrays
igfun and
jgvar that define the varying Jacobian elements
(i,j,G_{ij})$(i,j,{G}_{ij})$ as declared in the (sub)program from which
nag_opt_nlp2_sparse_solve (e04vh) is called.
Constraint:
leng ≥ 1${\mathbf{leng}}\ge 1$.
 7:
user – Any MATLAB object
user is not used by
nag_opt_nlp2_sparse_solve (e04vh), but is passed to
usrfun. Note that for large objects it may be more efficient to use a global variable which is accessible from the mfiles than to use
user.
Input Parameters Omitted from the MATLAB Interface
 lencw leniw lenrw cuser iuser ruser
Output Parameters
 1:
x(n) – double array
The final values of the variable x $x$.
 2:
xstate(n) – int64int32nag_int array
The final state of the variables.
xstate(j)${\mathbf{xstate}}\left(j\right)$  State of variable j$j$  Usual value of x(j)${\mathbf{x}}\left(j\right)$ 
0  nonbasic  xlow(j)${\mathbf{xlow}}\left(j\right)$ 
1  nonbasic  xupp(j)${\mathbf{xupp}}\left(j\right)$ 
2  superbasic  Between xlow(j)${\mathbf{xlow}}\left(j\right)$ and xupp(j)${\mathbf{xupp}}\left(j\right)$ 
3  basic  Between xlow(j)${\mathbf{xlow}}\left(j\right)$ and xupp(j)${\mathbf{xupp}}\left(j\right)$ 
Basic and superbasic variables may be outside their bounds by as much as the optional parameter
Minor Feasibility Tolerance. Note that if scaling is specified, the feasibility tolerance applies to the variables of the
scaled problem. In this case, the variables of the original problem may be as much as
0.1$0.1$ outside their bounds, but this is unlikely unless the problem is very badly scaled. Check the value of
Primal infeasibility output to the unit number associated with the optional parameter
Print File.
Very occasionally some nonbasic variables may be outside their bounds by as much as the optional parameter
Minor Feasibility Tolerance, and there may be some nonbasics for which
x(j)${\mathbf{x}}\left(j\right)$ lies strictly between its bounds.
If
ninf > 0 ${\mathbf{ninf}}>0$, some basic and superbasic variables may be outside their bounds by an arbitrary amount (bounded by
sinf if scaling was not used).
 3:
xmul(n) – double array
The vector of the dual variables (Lagrange multipliers) for the simple bounds l_{x} ≤ x ≤ u_{x} ${l}_{x}\le x\le {u}_{x}$.
 4:
f(nf) – double array
The final values for the problem functions
F $F$ (the values
F $F$ at the final point
x).
 5:
fstate(nf) – int64int32nag_int array
The final state of the variables. The elements of
fstate have the following meaning:
fstate(i)${\mathbf{fstate}}\left(i\right)$  State of the corresponding slack variable  Usual value of f(i)${\mathbf{f}}\left(i\right)$ 
0  nonbasic  flow(i)${\mathbf{flow}}\left(i\right)$ 
1  nonbasic  fupp(i)${\mathbf{fupp}}\left(i\right)$ 
2  superbasic  Between flow(i)${\mathbf{flow}}\left(i\right)$ and fupp(i)${\mathbf{fupp}}\left(i\right)$ 
3  basic  Between flow(i)${\mathbf{flow}}\left(i\right)$ and fupp(i)${\mathbf{fupp}}\left(i\right)$ 
Basic and superbasic slack variables may lead to the corresponding functions being outside their bounds by as much as the optional parameter
Minor Feasibility Tolerance.
Very occasionally some functions may be outside their bounds by as much as the optional parameter
Minor Feasibility Tolerance, and there may be some nonbasics for which
f(i) ${\mathbf{f}}\left(i\right)$ lies strictly between its bounds.
If
ninf > 0 ${\mathbf{ninf}}>0$, some basic and superbasic variables may be outside their bounds by an arbitrary amount (bounded by
sinf if scaling was not used).
 6:
fmul(nf) – double array
The vector of the dual variables (Lagrange multipliers) for the general constraints l_{F} ≤ F(x) ≤ u_{F} ${l}_{F}\le F\left(x\right)\le {u}_{F}$
 7:
ns – int64int32nag_int scalar
The final number of superbasic variables.
 8:
ninf – int64int32nag_int scalar
 9:
sinf – double scalar
Are the number and the sum of the infeasibilities of constraints that lie outside one of their bounds by more than the optional parameter
Minor Feasibility Tolerance before the solution is unscaled.
If any
linear constraints are infeasible,
x$x$ minimizes the sum of the infeasibilities of the linear constraints subject to the upper and lower bounds being satisfied. In this case
ninf gives the number of variables and linear constraints lying outside their upper or lower bounds. The nonlinear constraints are not evaluated.
Otherwise,
x$x$ minimizes the sum of infeasibilities of the
nonlinear constraints subject to the linear constraints and upper and lower bounds being satisfied. In this case
ninf gives the number of components of
F(x) $F\left(x\right)$ lying outside their bounds by more than the optional parameter
Minor Feasibility Tolerance. Again this is
before the solution is unscaled.
 10:
cw(lencw) – cell array of strings
cw = state . cw${\mathbf{cw}}=\mathbf{state}.\text{cw}$lencw = 600$\mathit{lencw}=600$.
Communication array, used to store information between calls to nag_opt_nlp2_sparse_solve (e04vh).
 11:
iw(leniw) – int64int32nag_int array
iw = state . iw${\mathbf{iw}}=\mathbf{state}.\text{iw}$leniw = 600$\mathit{leniw}=600$.
Communication array, used to store information between calls to nag_opt_nlp2_sparse_solve (e04vh).
 12:
rw(lenrw) – double array
rw = state . rw${\mathbf{rw}}=\mathbf{state}.\text{rw}$lenrw = 600$\mathit{lenrw}=600$.
Communication array, used to store information between calls to nag_opt_nlp2_sparse_solve (e04vh).
 13:
user – Any MATLAB object
 14:
ifail – int64int32nag_int scalar
ifail = 0${\mathrm{ifail}}={\mathbf{0}}$ unless the function detects an error (see
[Error Indicators and Warnings]).
nag_opt_nlp2_sparse_solve (e04vh) returns with
ifail = 0${\mathbf{ifail}}={\mathbf{0}}$ if the iterates have converged to a point
x$x$ that satisfies the firstorder Kuhn–Tucker (see
Section [Minor Iteration Log]) conditions to the accuracy requested by the optional parameter
Major Optimality Tolerance, i.e., the projected gradient and active constraint residuals are negligible at
x$x$.
You should check whether the following four conditions are satisfied:
If all these conditions hold,
x$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 (see
Section [Description of Monitoring Information]) refers to the largest bound infeasibility and which variable is involved. If it is too large, consider restarting with a smaller
Minor Feasibility Tolerance (say
10$10$ times smaller) and perhaps
Scale Option = 0${\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
$d$th significant digit if optimization could be continued. If
d
$d$ seems too large, consider restarting with a smaller
Major Optimality Tolerance.
Finally,
Nonlinear constraint violn in the Print file shows the maximum infeasibility for nonlinear rows. If it seems too large, consider restarting with a smaller
Major Feasibility Tolerance.
Error Indicators and Warnings
Note: nag_opt_nlp2_sparse_solve (e04vh) may return useful information for one or more of the following detected errors or warnings.
Errors or warnings detected by the function:
Cases prefixed with W are classified as warnings and
do not generate an error of type NAG:error_n. See nag_issue_warnings.
 ifail = 1${\mathbf{ifail}}=1$
The initialization function
nag_opt_nlp2_sparse_init (e04vg) has not been called or at least one of
lencw,
leniw and
lenrw is less than
600$600$.
 ifail = 2${\mathbf{ifail}}=2$
An input parameter is invalid.
 W ifail = 3${\mathbf{ifail}}=3$
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
nag_opt_nlp2_sparse_solve (e04vh) is within
10^{ − 2} ${10}^{2}$ of satisfying the
Major Optimality Tolerance. Check that the
Major Optimality Tolerance is not too small.
 W ifail = 4${\mathbf{ifail}}=4$
The problem appears to be infeasible.
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 $Axs=0$ (see
(6) and
(7) in
Section [Major Iterations]), there is apparently no point that satisfies the bounds on
x $x$ and
s $s$. Violations as small as the
Minor Feasibility Tolerance are ignored, but at least one component of
x $x$ or
s $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, nag_opt_nlp2_sparse_solve (e04vh) 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),
nag_opt_nlp2_sparse_solve (e04vh) enters socalled ‘nonlinear elastic’ mode. The subproblem includes the original QP objective and the sum of the infeasibilities – suitably weighted using the optional parameter
Elastic Weight. In elastic mode, some of the bounds on the nonlinear rows are ‘elastic’ – i.e., they are allowed to violate their specific bounds. Variables subject to elastic bounds are known as
elastic variables. An elastic variable is free to violate one or both of its original upper or lower bounds. If the original problem has a feasible solution and the elastic weight is sufficiently large, a feasible point eventually will be obtained for the perturbed constraints, and optimization can continue on the subproblem. If the nonlinear problem has no feasible solution,
nag_opt_nlp2_sparse_solve (e04vh) will tend to determine a ‘good’ infeasible point if the elastic weight is sufficiently large. (If the elastic weight were infinite,
nag_opt_nlp2_sparse_solve (e04vh) would locally minimize the nonlinear constraint violations subject to the linear constraints and bounds.)
Unfortunately, even though nag_opt_nlp2_sparse_solve (e04vh) 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.
 W ifail = 5${\mathbf{ifail}}=5$
The problem appears to be unbounded (or badly scaled).
For linear problems, unboundedness is detected by the simplex method when a nonbasic variable can be increased or decreased by an arbitrary amount without causing a basic variable to violate a bound. Consider adding an upper or lower bound to the variable. Also, examine the constraints that have nonzeros in the associated column, to see if they have been formulated as intended.
Very rarely, the scaling of the problem could be so poor that numerical error will give an erroneous indication of unboundedness. Consider using the optional parameter
Scale Option.
For nonlinear problems,
nag_opt_nlp2_sparse_solve (e04vh) 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 [Major Iteration Log])), the problem is terminated and declared unbounded. To avoid large function values, it may be necessary to impose bounds on some of the variables in order to keep them away from singularities in the nonlinear functions.
The message may indicate an abnormal termination while enforcing the limit on the constraint violations. This exit implies that the objective is not bounded below in the feasible region defined by expanding the bounds by the value of the
Violation Limit.
 ifail = 6${\mathbf{ifail}}=6$
Iteration limit reached.
Either the
Iterations Limit or the
Major Iterations Limit was exceeded before the required solution could be found. Check the iteration log to be sure that progress was being made. If so, and if you caused a basis file to be saved by using the optional parameter
New Basis File, consider restarting the run using the optional parameter
Old Basis File to see whether further progress can be made. If you have no basis file available, you might rerun the problem after increasing the optional parameters
Minor Iterations Limit and/or
Major Iterations Limit.
If none of the above limits have been reached, this error may mean that the problem appears to be more nonlinear than anticipated. The current set of basic and superbasic variables have been optimized as much as possible and a pricing operation (where a nonbasic variable is selected to become superbasic) is necessary to continue, but it can't continue as the number of superbasic variables has already reached the limit specified by the optional parameter
Superbasics Limit. In general, raise the
Superbasics Limit s $s$ by a reasonable amount, bearing in mind the storage needed for the reduced Hessian.
 ifail = 7${\mathbf{ifail}}=7$
Numerical difficulties have been encountered and no further progress can be made.
Several circumstances could lead to this exit.
 usrfun could be returning accurate function values but inaccurate gradients (or vice versa). This is the most likely cause. Study the comments given for ifail = 8${\mathbf{ifail}}={\mathbf{8}}$, and do your best to ensure that the coding is correct.
 The function and gradient values could be consistent, but their precision could be too low. For example, accidental use of a low precision data type when a higher precision was intended would lead to a relative function precision of about 10^{ − 6} ${10}^{6}$ instead of something like 10^{ − 15} ${10}^{15}$. The default Major Optimality Tolerance of 2 × 10^{ − 6} $2\times {10}^{6}$ would need to be raised to about 10^{ − 3} ${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.
 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 $t$ is as large as 10^{ − 5} ${10}^{5}$ or 10^{ − 6} ${10}^{6}$ (only 5$5$ or 6$6$ significant figures), the same exit condition may occur. At present the only remedy is to increase the accuracy of the function calculation.
 An LU $LU$ factorization of the basis has just been obtained and used to recompute the basic variables x_{B} ${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} ${x}_{B}$. However, a row check has revealed that the resulting solution does not satisfy the current constraints Ax − s = 0 $Axs=0$ sufficiently well.
This probably means that the current basis is very illconditioned. If there are some linear constraints and variables, try
Scale Option = 1${\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 $U$. Consult the description of
Umax and
Growth in
Section [Basis Factorization Statistics] and set the
LU Factor Tolerance to
2.0$2.0$ (or possibly even smaller, but not less than
1.0$1.0$).
 The first factorization attempt will have found the basis to be structurally or numerically singular. (Some diagonals of the triangular matrix U $U$ were respectively zero or smaller than a certain tolerance.) The associated variables are replaced by slacks and the modified basis is refactorized, but singularity persists. This must mean that the problem is badly scaled, or the LU Factor Tolerance is too much larger than 1.0$1.0$. This is highly unlikely to occur.
 ifail = 8${\mathbf{ifail}}=8$
Derivative appears to be incorrect.
A check has been made on some elements of the Jacobian as returned in the parameter
g of
usrfun. At least one value disagrees remarkably with its associated forward difference estimate (the relative difference between the computed and estimated values is
1.0$1.0$ or more). This exit is a safeguard, since
nag_opt_nlp2_sparse_solve (e04vh) will usually fail to make progress when the computed gradients are seriously inaccurate. In the process it may expend considerable effort before terminating with
ifail = 7${\mathbf{ifail}}={\mathbf{7}}$.
Check the function and Jacobian computation
very carefully in
usrfun. A simple omission could explain everything. If a component is very large, then give serious thought to scaling the function or the nonlinear variables.
If you feel
certain that the computed Jacobian is correct (and that the forwarddifference estimate is therefore wrong), you can specify
Verify Level = 0${\mathbf{Verify\; Level}}=0$ to prevent individual elements from being checked. However, the optimization procedure may have difficulty.
 ifail = 9${\mathbf{ifail}}=9$
Undefined usersupplied function.
You have indicated that the problem functions are undefined by assigning the value
status = − 1 ${\mathbf{status}}=1$ on exit from
usrfun.
nag_opt_nlp2_sparse_solve (e04vh) attempts to evaluate the problem functions closer to a point at which the functions are already known to be defined. This exit occurs if
nag_opt_nlp2_sparse_solve (e04vh) 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. 
 W ifail = 10${\mathbf{ifail}}=10$
User requested termination.
You have indicated the wish to terminate solution of the current problem by setting
status to a value
< − 1 $<1$ on exit from
usrfun.
 ifail = 11${\mathbf{ifail}}=11$
Internal memory allocation failed when attempting to obtain the required workspace. Please contact
NAG.
 ifail = 12${\mathbf{ifail}}=12$
Internal memory allocation was insufficient. Please contact
NAG.
 ifail = 13${\mathbf{ifail}}=13$
An error has occurred in the basis package, perhaps indicating incorrect setup of arrays. Set the optional parameter
Print File and examine the output carefully for further information.
 ifail = 14${\mathbf{ifail}}=14$
An unexpected error has occurred. Set the optional parameter
Print File and examine the output carefully for further information.
Accuracy
If the value of the optional parameter
Major Optimality Tolerance is set to
10^{ − d}${10}^{d}$ (
default value = sqrt(ε)$\text{default value}=\sqrt{\epsilon}$) and
ifail = 0${\mathbf{ifail}}={\mathbf{0}}$ on exit, then the final value of
f(x)$f\left(x\right)$ should have approximately
d$d$ correct significant digits.
Further Comments
This section describes the final output produced by
nag_opt_nlp2_sparse_solve (e04vh). Intermediate and other output are given in
Section [Description of Monitoring Information].
The Final Output
If
Print File
>
0
${\mathbf{Print\; File}}>0$,
the final output, including a listing of the status of every variable and constraint will be sent to the
channel numbers associated with
Print File. The following describes the output for each constraint (row) and variable (column).
The ROWS section
General linear constraints take the form
l ≤ A_{L}x ≤ u
$l\le {A}_{L}x\le u$. The
i
$i$th constraint is therefore of the form
where
ν_{i}
${\nu}_{i}$ is the
i$i$th row of
A_{L}
${A}_{L}$.
Internally, the constraints take the form
A_{L}x − s = 0
${A}_{L}xs=0$, where s$s$ is the set of slack variables (which satisfy the bounds
l ≤ s ≤ u
$l\le s\le u$). For the i$i$th row it is the slack variable
s_{i}
${s}_{i}$ that is directly available and it is sometimes convenient to refer to its state. Nonlinear constraints
α ≤ f_{i}(x) + ν_{i}x ≤ β
$\alpha \le {f}_{i}\left(x\right)+{\nu}_{i}x\le \beta $ are treated similarly, except that the row activity and degree of infeasibility are computed directly from
f_{i}(x)
+
ν_{i}x
${f}_{i}\left(x\right)+{\nu}_{i}x$, rather than
s_{i}
${s}_{i}$.
A full stop (.) is printed for any numerical value that is exactly zero.
Label 
Description 
Number 
is the value of n + i$n+i$. (This is used internally to refer to s_{i}${s}_{i}$ in the intermediate output.)

Row 
gives the name of the i$i$th row. 
State 
the state of the i$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}
${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}
${s}_{i}$ is basic. 
SBS 
s_{i}
${s}_{i}$ is superbasic. 
A key is sometimes printed before State.
Note that unless the optional parameter Scale Option = 0${\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 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 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
ν_{i}x
${\nu}_{i}x$ (or
f_{i}(x)
+
ν_{i}x
${f}_{i}\left(x\right)+{\nu}_{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 π_{i}${\pi}_{i}$ (the Lagrange multiplier for the
i
$i$th constraint). The full vector
π
$\pi $ always satisfies
B^{T}π
=
g_{B}
${B}^{\mathrm{T}}\pi ={g}_{B}$, where
B
$B$ is the current basis matrix and
g_{B}
${g}_{B}$ contains the associated gradients for the current objective function. For FP problems, π_{i}${\pi}_{i}$ is set to zero. 
i 
gives the index i$i$ of the i$i$th row.

The COLUMNS section
Let the
j
$j$th component of
x
$x$ be the variable
x_{j}
${x}_{j}$ and assume that it satisfies the bounds
α
≤
x_{j}
≤
β
$\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$j$. (This is used internally to refer to x_{j}${x}_{j}$ in the intermediate output.)

Column 
gives the name of x_{j}${x}_{j}$.

State 
the state of
x_{j}
${x}_{j}$ relative to the bounds
α
$\alpha $ and
β
$\beta $. The various states possible are as follows:
LL 
x_{j}
${x}_{j}$ is nonbasic at its lower limit,
α
$\alpha $. 
UL 
x_{j}
${x}_{j}$ is nonbasic at its upper limit,
β
$\beta $. 
EQ 
x_{j}
${x}_{j}$ is nonbasic and fixed at the value
α
=
β
$\alpha =\beta $. 
FR 
x_{j}
${x}_{j}$ is nonbasic at some value strictly between its bounds:
α <
x_{j} <
β
$\alpha <{x}_{j}<\beta $. 
BS 
x_{j}
${x}_{j}$ is basic. Usually
α <
x_{j} <
β
$\alpha <{x}_{j}<\beta $. 
SBS 
x_{j}
${x}_{j}$ is superbasic. Usually
α <
x_{j} <
β
$\alpha <{x}_{j}<\beta $. 
A key is sometimes printed before State.
Note that unless the optional parameter Scale Option = 0${\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 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 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}${x}_{j}$ at the final iterate.

Obj Gradient 
is the value of g_{j}${g}_{j}$ at the final iterate. For FP problems, g_{j}${g}_{j}$ is set to zero.

Lower Limit 
is the lower bound specified for the variable. None indicates that xlow(j) ≤ − infbnd${\mathbf{xlow}}\left(j\right)\le \mathit{infbnd}$. 
Upper Limit 
is the upper bound specified for the variable. None indicates that xupp(j) ≥ infbnd${\mathbf{xupp}}\left(j\right)\ge \mathit{infbnd}$. 
Reduced Gradnt 
is the value of the reduced gradient
d_{j}
=
g_{j}
−
π^{T}
a_{j}
${d}_{j}={g}_{j}{\pi}^{\mathrm{T}}{a}_{j}$ where
a_{j}
${a}_{j}$ is the
j
$j$th column of the constraint matrix. For FP problems, d_{j}${d}_{j}$ is set to zero. 
m + j 
is the value of m + j$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.
Example
Open in the MATLAB editor:
nag_opt_nlp2_sparse_solve_example
function nag_opt_nlp2_sparse_solve_example
start = int64(0);
objadd = 0;
objrow = int64(6);
prob = ' ';
iafun = [int64(1);2;4;4;5;5;6;6];
javar = [int64(3);4;1;2;1;2;3;4];
nea = int64(8);
a = [1;
1;
1;
1;
1;
1;
3;
2];
igfun = [int64(1);1;2;2;3;3;6;6];
jgvar = [int64(1);2;1;2;1;2;3;4];
neg = int64(8);
xlow = [0.55;
0.55;
0;
0];
xupp = [0.55;
0.55;
1200;
1200];
xnames = {'X1 '; 'X2 '; 'X3 '; 'X4 '};
flow = [894.8;
894.8;
1294.8;
0.55;
0.55;
1e25];
fupp = [894.8;
894.8;
1294.8;
1e25;
1e25;
1e25];
fnames = {'NlnCon 1'; 'NlnCon 2'; 'NlnCon 3'; 'LinCon 1'; 'LinCon 2'; 'Objectiv'};
x = [0;
0;
0;
0];
xstate = zeros(4, 1, 'int64');
f = [0;
0;
0;
0;
0;
0];
fstate = zeros(6, 1, 'int64');
fmul = [0;
0;
0;
0;
0;
0];
ns = int64(0);
[cw, iw, rw, ifail] = nag_opt_nlp2_sparse_init();
[xOut, xstateOut, xmul, fOut, fstateOut, fmulOut, nsOut, ninf, sinf, ...
cwOut, iwOut, rwOut, cuser, ifail] = ...
nag_opt_nlp2_sparse_solve(start, objadd, objrow, prob, @usrfun, iafun, javar, ...
nea, a, igfun, jgvar, neg, xlow, xupp, xnames, flow, fupp, ...
fnames, x, xstate, f, fstate, fmul, ns, cw, iw, rw);
xOut, xstateOut, xmul, fOut, fstateOut, fmulOut, nsOut, ninf, sinf, ifail
function [status, f, g, user] = usrfun(status, n, x, needf, nf, f, needg, leng, g, user)
if (needf > 0)
f(1) = 1000*sin(x(1)0.25) + 1000*sin(x(2) 0.25);
f(2) = 1000*sin(x(1)0.25) + 1000*sin(x(1)x(2) 0.25);
f(3) = 1000*sin(x(2)x(1)0.25) + 1000*sin(x(2) 0.25);
f(6) = 1.0d6*x(3)^3 + 2.0d6*x(4)^3/3;
end
if (needg > 0)
g(1) = 1000*cos(x(1)0.25);
g(2) = 1000*cos(x(2)0.25);
g(3) = 1000*cos(x(1)0.25) + 1000*cos(x(1)x(2) 0.25);
g(4) = 1000*cos(x(1)x(2)0.25);
g(5) = 1000*cos(x(2)x(1)0.25);
g(6) = 1000*cos(x(2)x(1)0.25) + 1000*cos(x(2) 0.25);
g(7) = 3.0d6*x(3)^2;
g(8) = 2.0d6*x(4)^2;
end
xOut =
1.0e+03 *
0.0001
0.0004
0.6799
1.0261
xstateOut =
3
3
2
3
xmul =
1.0e07 *
0.4568
0.0139
0.0008
0.0008
fOut =
1.0e+03 *
0.8948
0.8948
1.2948
0.0005
0.0005
5.1265
fstateOut =
0
0
0
0
0
0
fmulOut =
4.3870
4.1056
5.4633
0
0
0
nsOut =
1
ninf =
0
sinf =
0
ifail =
0
Open in the MATLAB editor:
e04vh_example
function e04vh_example
start = int64(0);
objadd = 0;
objrow = int64(6);
prob = ' ';
iafun = [int64(1);2;4;4;5;5;6;6];
javar = [int64(3);4;1;2;1;2;3;4];
nea = int64(8);
a = [1;
1;
1;
1;
1;
1;
3;
2];
igfun = [int64(1);1;2;2;3;3;6;6];
jgvar = [int64(1);2;1;2;1;2;3;4];
neg = int64(8);
xlow = [0.55;
0.55;
0;
0];
xupp = [0.55;
0.55;
1200;
1200];
xnames = {'X1 '; 'X2 '; 'X3 '; 'X4 '};
flow = [894.8;
894.8;
1294.8;
0.55;
0.55;
1e25];
fupp = [894.8;
894.8;
1294.8;
1e25;
1e25;
1e25];
fnames = {'NlnCon 1'; 'NlnCon 2'; 'NlnCon 3'; 'LinCon 1'; 'LinCon 2'; 'Objectiv'};
x = [0;
0;
0;
0];
xstate = zeros(4, 1, 'int64');
f = [0;
0;
0;
0;
0;
0];
fstate = zeros(6, 1, 'int64');
fmul = [0;
0;
0;
0;
0;
0];
ns = int64(0);
[cw, iw, rw, ifail] = e04vg;
[xOut, xstateOut, xmul, fOut, fstateOut, fmulOut, nsOut, ninf, sinf, ...
cwOut, iwOut, rwOut, cuser, ifail] = ...
e04vh(start, objadd, objrow, prob, @usrfun, iafun, javar, ...
nea, a, igfun, jgvar, neg, xlow, xupp, xnames, flow, fupp, ...
fnames, x, xstate, f, fstate, fmul, ns, cw, iw, rw);
xOut, xstateOut, xmul, fOut, fstateOut, fmulOut, nsOut, ninf, sinf, ifail
function [status, f, g, user] = usrfun(status, n, x, needf, nf, f, needg, leng, g, user)
if (needf > 0)
f(1) = 1000*sin(x(1)0.25) + 1000*sin(x(2) 0.25);
f(2) = 1000*sin(x(1)0.25) + 1000*sin(x(1)x(2) 0.25);
f(3) = 1000*sin(x(2)x(1)0.25) + 1000*sin(x(2) 0.25);
f(6) = 1.0d6*x(3)^3 + 2.0d6*x(4)^3/3;
end
if (needg > 0)
g(1) = 1000*cos(x(1)0.25);
g(2) = 1000*cos(x(2)0.25);
g(3) = 1000*cos(x(1)0.25) + 1000*cos(x(1)x(2) 0.25);
g(4) = 1000*cos(x(1)x(2)0.25);
g(5) = 1000*cos(x(2)x(1)0.25);
g(6) = 1000*cos(x(2)x(1)0.25) + 1000*cos(x(2) 0.25);
g(7) = 3.0d6*x(3)^2;
g(8) = 2.0d6*x(4)^2;
end
xOut =
1.0e+03 *
0.0001
0.0004
0.6799
1.0261
xstateOut =
3
3
2
3
xmul =
1.0e07 *
0.4568
0.0139
0.0008
0.0008
fOut =
1.0e+03 *
0.8948
0.8948
1.2948
0.0005
0.0005
5.1265
fstateOut =
0
0
0
0
0
0
fmulOut =
4.3870
4.1056
5.4633
0
0
0
nsOut =
1
ninf =
0
sinf =
0
ifail =
0
the remainder of this document is intended for more advanced users. Section [Algorithmic Details] contains a detailed description of the algorithm which may be needed in order to understand Sections [Optional Parameters] and [Description of Monitoring Information]. Section [Optional Parameters] describes the optional parameters which may be set by calls to nag_opt_nlp2_sparse_option_string (e04vl), nag_opt_nlp2_sparse_option_integer_set (e04vm) and/or nag_opt_nlp2_sparse_option_double_set (e04vn). Section [Description of Monitoring Information] describes the quantities which can be requested to monitor the course of the computation.
Algorithmic Details
Here we summarise the main features of the SQP algorithm used in
nag_opt_nlp2_sparse_solve (e04vh) 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).
Constraints and Slack Variables
Problem
(1) contains
n
$n$ variables in
x
$x$. Let
m
$m$ be the number of components of
f(x)
$f\left(x\right)$ and
A_{L}x
${A}_{L}x$ combined. The upper and lower bounds on those terms define the
general constraints of the problem.
nag_opt_nlp2_sparse_solve (e04vh) converts the general constraints to equalities by introducing a set of
slack variables
s
=
(s_{1},s_{2}, … ,s_{m})^{T}
$s={({s}_{1},{s}_{2},\dots ,{s}_{m})}^{\mathrm{T}}$. For example, the linear constraint
5
≤
2x_{1}
+
3x_{2}
≤
∞
$5\le 2{x}_{1}+3{x}_{2}\le \infty $ is replaced by
2x_{1}
+
3x_{2}
−
s_{1}
=
0
$2{x}_{1}+3{x}_{2}{s}_{1}=0$ together with the bounded slack
5
≤
s_{1}
≤
∞
$5\le {s}_{1}\le \infty $. The minimization problem
(1) can therefore be written in the equivalent form
The general constraints become the equalities
f(x)
−
s_{N}
=
0
$f\left(x\right){s}_{N}=0$ and
A_{L}x
−
s_{L}
=
0
${A}_{L}x{s}_{L}=0$, where
s_{L}
${s}_{L}$ and
s_{N}
${s}_{N}$ are the linear and nonlinear slacks.
Major Iterations
The basic structure of the SQP algorithm involves
major and
minor iterations. The major iterations generate a sequence of iterates
{x_{k}}
$\left\{{x}_{k}\right\}$ that satisfy the linear constraints and converge to a point that satisfies the nonlinear constraints and the firstorder conditions for optimality. At each iterate
x_{k}
${x}_{k}$ a QP subproblem is used to generate a search direction towards the next iterate
x_{k + 1}
${x}_{k+1}$. The constraints of the subproblem are formed from the linear constraints
A_{L}x
−
s_{L}
=
0
${A}_{L}x{s}_{L}=0$ and the linearized constraint
where
f^{′}
(x_{k})
${f}^{\prime}\left({x}_{k}\right)$ denotes the
Jacobian matrix, whose elements are the first derivatives of
f(x)
$f\left(x\right)$ evaluated at
x_{k}
${x}_{k}$. The QP constraints therefore comprise the
m
$m$ linear constraints
where
x
$x$ and
s
$s$ are bounded above and below by
u
$u$ and
l
$l$ as before. If the
m
$m$ by
n
$n$ matrix
A
$A$ and
m
$m$vector
b
$b$ are defined as
then the QP subproblem can be written as
where
q(x,x_{k})
$q(x,{x}_{k})$ is a quadratic approximation to a modified Lagrangian function (see
Gill et al. (2002)). The matrix
H_{k}
${H}_{k}$ is a quasiNewton approximation to the Hessian of the Lagrangian. A BFGS 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
n_{1}
${n}_{1}$ rows and columns of the Hessian need to be approximated, where
n_{1}
${n}_{1}$ is the number of nonlinear variables. This quantity is determined by the implicit values of the number of nonlinear objective and Jacobian variables determined after the constraints and variables are reordered.
Minor Iterations
Solving the QP subproblem is itself an iterative procedure. Here, the iterations of the QP solver
nag_opt_qpconvex2_sparse_solve (e04nq) form the
minor iterations of the SQP method.
nag_opt_qpconvex2_sparse_solve (e04nq) uses a reducedHessian activeset method implemented as a reducedgradient method. At each minor iteration, the constraints
Ax − s = b
$Axs=b$ are partitioned into the form
where the
basis matrix
B
$B$ is square and nonsingular, and the matrices
S$S$ and
N$N$ are the remaining columns of
$\left(\begin{array}{cc}A& I\end{array}\right)$. The vectors
x_{B}
${x}_{B}$,
x_{S}${x}_{S}$ and
x_{N}
${x}_{N}$ are the associated
basic,
superbasic and
nonbasic variables respectively; they are a permutation of the elements of
x
$x$ and
s
$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}
${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)
$(x,s)$ continues to satisfy
Ax − s = b
$Axs=b$. The number of superbasic variables (
n_{S}
${n}_{S}$, say) therefore indicates the number of degrees of freedom remaining after the constraints have been satisfied. In broad terms,
n_{S}
${n}_{S}$ is a measure of
how nonlinear the problem is. In particular,
n_{S}
${n}_{S}$ will always be zero for LP problems.
If it appears that no improvement can be made with the current definition of
B
$B$,
S
$S$ and
N
$N$, a nonbasic variable is selected to be added to
S
$S$, and the process is repeated with the value of
n_{S}
${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}
${n}_{S}$ is decreased by one.
Associated with each of the
m
$m$ equality constraints
Ax − s = b
$Axs=b$ are the dual variables
π
$\pi $. Similarly, each variable in
(x,s)
$(x,s)$ has an associated reduced gradient
d_{j}
${d}_{j}$. The reduced gradients for the variables
x
$x$ are the quantities
g − A^{T}π
$g{A}^{\mathrm{T}}\pi $, where
g
$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} ≥ 0
${d}_{j}\ge 0$ for all nonbasic variables at their lower bounds,
d_{j} ≤ 0
${d}_{j}\le 0$ for all nonbasic variables at their upper bounds, and
d_{j} = 0
${d}_{j}=0$ for other variables, including superbasics. In practice, an approximate QP solution
(x̂_{k},ŝ_{k},π̂_{k})
$({\hat{x}}_{k},{\hat{s}}_{k},{\hat{\pi}}_{k})$ is found by relaxing these conditions.
The 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
$D$ is a diagonal matrix of penalty parameters
(D_{ii} ≥ 0)
$({D}_{ii}\ge 0)$, and
π$\pi $ now refers to dual variables for the nonlinear constraints in
(1). If
(x_{k},s_{k},π_{k})
$({x}_{k},{s}_{k},{\pi}_{k})$ denotes the current solution estimate and
(x̂_{k},ŝ_{k},π̂_{k})
$({\hat{x}}_{k},{\hat{s}}_{k},{\hat{\pi}}_{k})$ denotes the QP solution, the linesearch determines a step
α_{k}
${\alpha}_{k}$
(0 < α_{k} ≤ 1)
$(0<{\alpha}_{k}\le 1)$ such that the new point
gives a
sufficient decrease in the merit function
M$\mathcal{M}$. When necessary, the penalties in
D
$D$ are increased by the minimumnorm perturbation that ensures descent for
M
$\mathcal{M}$ (see
Gill et al. (1992)). The value of
s_{N}
${s}_{N}$ is adjusted to minimize the merit function as a function of
s
$s$ before the solution of the QP subproblem (see
Gill et al. (1986) and
Eldersveld (1991)).
Treatment of Constraint Infeasibilities
nag_opt_nlp2_sparse_solve (e04vh) makes explicit allowance for infeasible constraints. First, infeasible
linear constraints are detected by solving the linear program
where
e
$e$ is a vector of ones, and the nonlinear constraint bounds are temporarily excluded from
l
$l$ and
u
$u$. This is equivalent to minimizing the sum of the general linear constraint violations subject to the bounds on
x
$x$. (The sum is the
ℓ_{1}
${\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
(11) has
v ≠ 0
$v\ne 0$ or
w ≠ 0
$w\ne 0$.
nag_opt_nlp2_sparse_solve (e04vh) 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.)
nag_opt_nlp2_sparse_solve (e04vh) proceeds to solve nonlinear problems as given, using search directions obtained from the sequence of QP subproblems (see
(7)).
If a QP subproblem proves to be infeasible or unbounded (or if the dual variables
π
$\pi $ for the nonlinear constraints become large),
nag_opt_nlp2_sparse_solve (e04vh) enters ‘elastic’ mode and thereafter solves the problem
where
γ
$\gamma $ is a nonnegative parameter (the
elastic weight), and
f_{0}(x)
+
γ
e^{T}
(v + w)
${f}_{0}\left(x\right)+\gamma {e}^{\mathrm{T}}(v+w)$ is called a
composite objective (the
ℓ_{1}
${\ell}_{1}$ penalty function for the nonlinear constraints).
The value of
γ
$\gamma $ may increase automatically by multiples of 10$10$ if the optimal
v
$v$ and
w
$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
Elastic Weight.
Optional Parameters
Several optional parameters in nag_opt_nlp2_sparse_solve (e04vh) define choices in the problem specification or the algorithm logic. In order to reduce the number of formal parameters of nag_opt_nlp2_sparse_solve (e04vh) 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 [Description of the optional parameters].
Optional parameters may be specified by calling one, or more, of the functions
nag_opt_nlp2_sparse_option_string (e04vl),
nag_opt_nlp2_sparse_option_integer_set (e04vm) and
nag_opt_nlp2_sparse_option_double_set (e04vn) before a call to
nag_opt_nlp2_sparse_solve (e04vh).
nag_opt_nlp2_sparse_option_string (e04vl),
nag_opt_nlp2_sparse_option_integer_set (e04vm) and
nag_opt_nlp2_sparse_option_double_set (e04vn) can be called to supply options directly, one call being necessary for each optional parameter. For example,
[cw, iw, rw, ifail] = e04vl('Print Level = 5', cw, iw, rw);
nag_opt_nlp2_sparse_option_string (e04vl),
nag_opt_nlp2_sparse_option_integer_set (e04vm) and
nag_opt_nlp2_sparse_option_double_set (e04vn) should be consulted for a full description of this method of supplying optional parameters.
All optional parameters you do not specify are set to their default values. Optional parameters you specify are unaltered by nag_opt_nlp2_sparse_solve (e04vh) (unless they define invalid values) and so remain in effect for subsequent calls to nag_opt_nlp2_sparse_solve (e04vh), unless you alter them.
Description 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$a$, i and r$i\text{ and}r$ denote options that take character, integer and real values respectively;
 the default value, where the symbol ε$\epsilon $ is a generic notation for machine precision (see nag_machine_precision (x02aj)), and ε_{r}${\epsilon}_{r}$ denotes the relative precision of the objective function Function Precision, and bigbnd$\mathit{bigbnd}$ signifies the value of Infinite Bound Size.
Keywords and character values are case and white space insensitive.
Central Difference Interval r$r$Default = ε_{r}^{(1/3)}$\text{}={\epsilon}_{r}^{\frac{1}{3}}$When
Derivative Option = 0${\mathbf{Derivative\; Option}}=0$, the centraldifference interval
r $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 $j$th variable is
h_{j} = r (1 + x_{j}) ${h}_{j}=r(1+\left{x}_{j}\right)$. The resulting derivative estimates should be accurate to
O(r^{2}) $\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$0.0$ and 1.0$1.0$ is appropriate.
Check Frequency i$i$Default = 60$\text{}=60$Every i $i$th minor iteration after the most recent basis factorization, a numerical test is made to see if the current solution x $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 $Axs=b$, where s $s$ is the set of slack variables. To perform the numerical test, the residual vector r = b − Ax + s $r=bAx+s$ is computed. If the largest component of r $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 ≤ 0$i\le 0$, the value of i = 99999999$i=99999999$ is used and effectively no checks are made.
Check Frequency = 1${\mathbf{Check\; Frequency}}=1$ is useful for debugging purposes, but otherwise this option should not be needed.
Crash Option i$i$Default = 3$\text{}=3$Crash Tolerance r$r$Default = 0.1$\text{}=0.1$Except on restarts, 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
Crash Option i $i$ determines which rows and columns of
A $A$ are eligible initially, and how many times the Crash procedure is called. Columns of
− I $I$ are used to pad the basis where necessary.
i$i$ 
Meaning 
0$0$ 
The initial basis contains only slack variables: B = I$B=I$. 
1$1$ 
The Crash procedure is called once, looking for a triangular basis in all rows and columns of A$A$. 
2$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$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 ≥ 1 $i\ge 1$, certain slacks on inequality rows are selected for the basis first. (If i ≥ 2 $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 $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
Crash Tolerance r $r$ allows the starting Crash procedure to ignore certain ‘small’ nonzeros in each column of
A $A$. If
a_{max} ${a}_{\mathrm{max}}$ is the largest element in column
j $j$, other nonzeros of
a_{ij} ${a}_{ij}$ in the columns are ignored if
a_{ij} ≤ a_{max} × r $\left{a}_{ij}\right\le {a}_{\mathrm{max}}\times r$. (To be meaningful,
r $r$ should be in the range
0 ≤ r < 1 $0\le r<1$.)
When r > 0.0 $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 $A$ and fewer (arbitrary) slacks. A feasible solution may be reached sooner on some problems.
For example, suppose the first
m$m$ columns of
A$A$ form the matrix shown under
LU Factor Tolerance; i.e., a tridiagonal matrix with entries
− 1$1$,
4$4$,
− 1$1$. To help the Crash procedure choose all
m$m$ columns for the initial basis, we would specify a
Crash Tolerance of
r$r$ for some value of
r > 0.5$r>0.5$.
Defaults This special keyword may be used to reset all optional parameters to their default values.
Derivative Option i$i$Default = 1$\text{}=1$Optional parameter
Derivative Option specifies which nonlinear function gradients are known analytically and will be supplied to
nag_opt_nlp2_sparse_solve (e04vh) by
usrfun.
i$i$ 
Meaning 
0$0$ 
Some problem derivatives are unknown. 
1$1$ 
All problem derivatives are known. 
The value i = 1 $i=1$ should be used whenever possible. It is the most reliable and will usually be the most efficient.
If
i = 0 $i=0$,
nag_opt_nlp2_sparse_solve (e04vh) will
estimate the missing components of
G(x) $G\left(x\right)$ using finite differences. This may simplify the coding of
usrfun. However, it could increase the total runtime substantially (since a special call to
usrfun is required for each column of the Jacobian that has a 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 nonstandard optional parameter
Difference Interval.
For each column of the Jacobian, one call to
usrfun is needed to estimate all missing elements in that column, if any.
At times, central differences are used rather than forward differences. Twice as many calls to
usrfun are needed. (This is not under your control.)
Derivative Linesearch DefaultNonderivative Linesearch At each major iteration a linesearch is used to improve the merit function. Optional parameter
Derivative Linesearch uses safeguarded cubic interpolation and requires both function and gradient values to compute estimates of the step
α_{k} ${\alpha}_{k}$. If some analytic derivatives are not provided, or optional parameter
Nonderivative Linesearch is specified,
nag_opt_nlp2_sparse_solve (e04vh) 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
Nonderivative Linesearch is selected,
nag_opt_nlp2_sparse_solve (e04vh) signals the evaluation of the linesearch by calling
usrfun with
needg = 0${\mathbf{needg}}=0$. Once the linesearch is completed, the problem functions are called again with
needf = 0${\mathbf{needf}}=0$ and
needg = 0${\mathbf{needg}}=0$. If the potential saving provided by a nonderivative linesearch is to be realised, it is essential that
usrfun be coded so that derivatives are not computed when
needg = 0${\mathbf{needg}}=0$.
Difference Interval r$r$Default = sqrt(ε_{r})$\text{}=\sqrt{{\epsilon}_{r}}$This alters the interval
r $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} ${x}_{j}$ is estimated by perturbing that component of x $x$ to the value x_{j} + r (1 + x_{j}) ${x}_{j}+r(1+\left{x}_{j}\right)$, and then evaluating F_{obj}(x) ${F}_{\mathrm{obj}}\left(x\right)$ or f(x) $f\left(x\right)$ at the perturbed point. The resulting gradient estimates should be accurate to O(r) $\mathit{O}\left(r\right)$ unless the functions are badly scaled. Judicious alteration of r $r$ may sometimes lead to greater accuracy.
If you supply a value for this optional parameter, a small value between 0.0$0.0$ and 1.0$1.0$ is appropriate.
Dump File i_{1}${i}_{1}$Default = 0$\text{}=0$Load File i_{2}${i}_{2}$Default = 0$\text{}=0$Optional parameters
Dump File and
Load File are similar to optional parameters
Punch File and
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
Dump File and
Load File is given in
Gill et al. (2005a).
If i_{1} > 0 ${i}_{1}>0$, the last solution obtained will be output to the file with unit number i_{1} ${i}_{1}$.
If
i_{2} > 0 ${i}_{2}>0$, the
Load File,
containing basis information, will be read. The file will usually have been output previously as a
Dump File. The file will not be accessed if optional parameters
Old Basis File or
Insert File are specified.
Elastic Weight r$r$Default = 10^{4}$\text{}={10}^{4}$This keyword determines the initial weight
γ $\gamma $ associated with the problem
(12) (see
Section [Treatment of Constraint Infeasibilities]).
At major iteration k $k$, if elastic mode has not yet started, a scale factor σ_{k} = 1 + ‖g(x_{k})‖_{∞} ${\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 σ_{k}r ${\sigma}_{k}\text{}r$. The QP is resolved in elastic mode with γ = σ_{k}r $\gamma ={\sigma}_{k}\text{}r$.
Thereafter, major iterations continue in elastic mode until they converge to a point that is optimal for
(12) (see
Section [Treatment of Constraint Infeasibilities]). If the point is feasible for equation
(1) (v = w = 0) $(v=w=0)$, it is declared locally optimal. Otherwise,
γ $\gamma $ is increased by a factor of
10$10$ and major iterations continue. If
γ$\gamma $ has already reached a maximum allowable value, equation
(1) is declared locally infeasible.
Expand Frequency i$i$Default = 10000$\text{}=10000$This option is part of the anticycling 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
Minor Feasibility Tolerance is
δ $\delta $. Over a period of
i $i$ iterations, the tolerance actually used by
nag_opt_nlp2_sparse_solve (e04vh) increases from
0.5δ $0.5\delta $ to
δ $\delta $ (in steps of
0.5δ / i $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 $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
Pivot Tolerance).
Factorization Frequency i$i$Default = 50$\text{}=50$At most i $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 $i$ is reasonable for typical problems. Higher values up to i = 100 $i=100$ (say) may be more efficient on wellscaled 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
Check Frequency) to ensure that the general constraints are satisfied. If necessary the basis will be refactorized before the limit of
i $i$ updates is reached.
Function Precision r$r$Default = ε^{0.8}$\text{}={\epsilon}^{0.8}$The relative function precision ε_{r} ${\epsilon}_{r}$ is intended to be a measure of the relative accuracy with which the nonlinear functions can be computed. For example, if f(x) $f\left(x\right)$ is computed as 1000.56789$1000.56789$ for some relevant x $x$ and if the first 6$6$ significant digits are known to be correct, the appropriate value for ε_{r} ${\epsilon}_{r}$ would be 1.0e−6 $\text{1.0e\u22126}$.
Ideally the functions f_{i}(x) ${f}_{i}\left(x\right)$ should have magnitude of order 1$1$. If all functions are substantially less than 1$1$ in magnitude, ε_{r} ${\epsilon}_{r}$ should be the absolute precision. For example, if f(x) = 1.23456789e−4 $f\left(x\right)=\text{1.23456789e\u22124}$ at some point and if the first 6$6$ significant digits are known to be correct, the appropriate value for ε_{r} ${\epsilon}_{r}$ would be 1.0e−10 $\text{1.0e\u221210}$.)
The default value of ε_{r} ${\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
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_{1} ≤ 75${n}_{1}\le 75$Hessian Limited Memory Default if n_{1} > 75${n}_{1}>75$These options select the method for storing and updating the approximate Hessian. (nag_opt_nlp2_sparse_solve (e04vh) uses a quasiNewton approximation to the Hessian of the Lagrangian. A BFGS update is applied after each major iteration.)
If
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$n$ is not too large (say, less than
75$75$). In this case, the storage requirement is fixed and one can expect
1$1$step Qsuperlinear convergence to the solution.
Hessian Limited Memory should be used on problems where
n$n$ is very large. In this case a limitedmemory procedure is used to update a diagonal Hessian approximation
H_{r} ${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} ${H}_{r}$ has been reset to their diagonal.)
Hessian Frequency i$i$Default = 99999999$\text{}=99999999$If optional parameter
Hessian Full Memory is in effect and
i $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.)
Hessian Full Memory and
Hessian Frequency = 10 ${\mathbf{Hessian\; Frequency}}=10$ have a similar effect to
Hessian Limited Memory and
Hessian Updates = 10 ${\mathbf{Hessian\; Updates}}=10$ (except that the latter retains the current diagonal during resets).
Hessian Updates i$i$Default = Hessian Frequency$\text{}={\mathbf{Hessian\; Frequency}}$ if Hessian Full Memory, 10$10$ otherwiseIf optional parameter
Hessian Limited Memory is in effect and
i $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 $i=5$).
Infinite Bound Size r$r$Default = 10^{20}$\text{}={10}^{20}$If r ≥ 0$r\ge 0$, r$r$ defines the ‘infinite’ bound bigbnd$\mathit{bigbnd}$ in the definition of the problem constraints. Any upper bound greater than or equal to bigbnd$\mathit{bigbnd}$ will be regarded as + ∞$+\infty $ (and similarly any lower bound less than or equal to − bigbnd$\mathit{bigbnd}$ will be regarded as − ∞$\infty $). If r < 0$r<0$, the default value is used.
Iterations Limit i$i$Default =
max (10000,
10
max (n,nf)
)
$\text{}=\mathrm{max}\phantom{\rule{0.125em}{0ex}}(10000,10\mathrm{max}\phantom{\rule{0.125em}{0ex}}({\mathbf{n}},{\mathbf{nf}}))$The value of
i$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
Minor Iterations Limit.)
Linesearch Tolerance r$r$Default = 0.9$=0.9$This tolerance, r $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 ≤ r ≤ 1.0 $0.0\le r\le 1.0$.
The default value r = 0.9 $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 , 0.01 or 0.001 $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 $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$1$–5 function values (typically), but many function calls will then be needed to estimate missing gradients for the next iteration.
LU Density Tolerance r_{1}${r}_{1}$Default = 0.6$\text{}=0.6$LU Singularity Tolerance r_{2}${r}_{2}$Default = ε^{(2/3)}$\text{}={\epsilon}^{\frac{2}{3}}$The density tolerance, r_{1} ${r}_{1}$, is used during LU $LU$ factorization of the basis matrix B$B$. Columns of L $L$ and rows of U $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} ${r}_{1}$, the Markowitz strategy for choosing pivots is terminated, and the remaining matrix is factored by a dense LU$LU$ procedure. Raising the density tolerance towards 1.0$1.0$ may give slightly sparser LU $LU$ factors, with a slight increase in factorization time.
The singularity tolerance, r_{2} ${r}_{2}$, helps guard against illconditioned basis matrices. After B$B$ is refactorized, the diagonal elements of U $U$ are tested as follows: if u_{jj} ≤ r_{2} $\left{u}_{jj}\right\le {r}_{2}$ or u_{jj} < r_{2} max_{i} u_{ij} $\left{u}_{jj}\right<{r}_{2}{\displaystyle \underset{i}{\mathrm{max}}}\phantom{\rule{0.25em}{0ex}}\left{u}_{ij}\right$, the j $j$th column of the basis is replaced by the corresponding slack variable. (This is most likely to occur after a restart.)
LU Factor Tolerance r_{1}${r}_{1}$Default = 3.99$\text{}=3.99$LU Update Tolerance r_{2}${r}_{2}$Default = 3.99$\text{}=3.99$The values of
r_{1}${r}_{1}$ and
r_{2}${r}_{2}$ affect the stability of the basis factorization
B = LU$B=LU$, during refactorization and updates respectively. The lower triangular matrix
L$L$ is a product of matrices of the form
where the multipliers
μ$\mu $ will satisfy
μ ≤ r_{i}$\left\mu \right\le {r}_{i}$. The default values of
r_{1}${r}_{1}$ and
r_{2}${r}_{2}$ usually strike a good compromise between stability and sparsity. They must satisfy
r_{1}${r}_{1}$,
r_{2} ≥ 1.0${r}_{2}\ge 1.0$.
For large and relatively dense problems, r_{1} = 10.0 or 5.0${r}_{1}=10.0\text{ 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} and/or r_{2}${r}_{1}\text{ and/or}{r}_{2}$ in order to achieve stability. For example, if the columns of
A$A$ include a submatrix of the form
one should set both
r_{1}${r}_{1}$ and
r_{2}${r}_{2}$ to values in the range
1.0 ≤ r_{i} < 4.0$1.0\le {r}_{i}<4.0$.
LU Partial Pivoting DefaultLU Complete Pivoting LU Rook Pivoting The
LU $LU$ factorization implements a Markowitztype search for pivots that locally minimize the fillin subject to a threshold pivoting stability criterion. The default option is to use threshhold partial pivoting. The optional parameters
LU Rook Pivoting and
LU Complete Pivoting are more expensive than partial pivoting but are more stable and better at revealing rank, as long as
LU Factor Tolerance is not too large (say
< 2.0$<2.0$). When numerical difficulties are encountered,
nag_opt_nlp2_sparse_solve (e04vh) automatically reduces the
LU$LU$ tolerance towards
1.0$1.0$ and switches (if necessary) to rook or complete pivoting, before reverting to the default or specified options at the next refactorization (with
System Information Yes, relevant messages are output to the
Print File).
Major Feasibility Tolerance r$r$Default =
max (10^{ − 6},sqrt(ε))
$\text{}=\mathrm{max}\phantom{\rule{0.125em}{0ex}}({10}^{6},\sqrt{\epsilon})$This tolerance, r $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_{max}${v}_{\mathrm{max}}$ be the maximum nonlinear constraint violation, normalized by the size of the solution, which is required to satisfy
where
v_{i} ${v}_{\mathit{i}}$ is the violation of the
i $\mathit{i}$th nonlinear constraint, for
i = 1,2, … ,nf$\mathit{i}=1,2,\dots ,{\mathbf{nf}}$.
In the major iteration log (see
Section [Minor Iteration Log]),
v_{max}${v}_{\mathrm{max}}$ appears as the quantity labelled ‘Feasible’. If some of the problem functions are known to be of low accuracy, a larger
Major Feasibility Tolerance may be appropriate.
Major Optimality Tolerance r$r$Default = 2
max (10^{ − 6},sqrt(ε))
$\text{}=2\mathrm{max}\phantom{\rule{0.125em}{0ex}}({10}^{6},\sqrt{\epsilon})$This tolerance,
r $r$, specifies the final accuracy of the dual variables. On successful termination,
nag_opt_nlp2_sparse_solve (e04vh) will have computed a solution
(x,s,π) $(x,s,\pi )$ such that
where
c_{j} ${c}_{\mathit{j}}$ is an estimate of the complementarity slackness for variable
j $\mathit{j}$, for
j = 1,2, … ,n + nf$\mathit{j}=1,2,\dots ,n+\mathit{nf}$. The values
c_{i} ${c}_{i}$ are computed from the final QP solution using the reduced gradients
d_{j} = g_{j} − π^{T} a_{j} ${d}_{j}={g}_{j}{\pi}^{\mathrm{T}}{a}_{j}$ (where
g_{j} ${g}_{j}$ is the
j $j$th component of the objective gradient,
a_{j} ${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):
In the
Print File,
c_{max}${c}_{\mathrm{max}}$ appears as the quantity labelled ‘Optimal’.
Major Iterations Limit i$i$Default =
max (1000,
3
max (n,nf)
)
$\text{}=\mathrm{max}\phantom{\rule{0.125em}{0ex}}(1000,3\mathrm{max}\phantom{\rule{0.125em}{0ex}}(n,\mathit{nf}))$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$i=0$, optimality and feasibility are checked.
Major Print Level i$i$Default = 000001$\text{}=000001$This controls the amount of output to the optional parameters
Print File and
Summary File at each major iteration.
Major Print Level = 0${\mathbf{Major\; Print\; Level}}=0$ suppresses most output, except for error messages.
Major Print Level = 1${\mathbf{Major\; Print\; Level}}=1$ gives normal output for linear and nonlinear problems, and
Major Print Level = 11${\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
where each letter stands for a digit that is either
0$0$ or
1$1$ as follows:
s$s$ 
a single line that gives a summary of each major iteration. (This entry in JFDXbs $JFDXbs$ is not strictly binary since the summary line is printed whenever JFDXbs ≥ 1 $JFDXbs\ge 1$); 
b$b$ 
basis statistics, i.e., information relating to the basis matrix whenever it is refactorized. (This output is always provided if JFDXbs ≥ 10 $JFDXbs\ge 10$); 
X$X$ 
x_{k} ${x}_{k}$, the nonlinear variables involved in the objective function or the constraints. These appear under the heading ‘Jacobian variables’; 
D$D$ 
π_{k} ${\pi}_{k}$, the dual variables for the nonlinear constraints. These appear under the heading ‘Multiplier estimates’; 
F$F$ 
f(x_{k}) $f\left({x}_{k}\right)$, the values of the nonlinear constraint functions; 
J$J$ 
J(x_{k}) $J\left({x}_{k}\right)$, the Jacobian matrix. This appears under the heading ‘x$x$ and Jacobian’. 
To obtain output of any items JFDXbs $JFDXbs$, set the corresponding digit to 1$1$, otherwise to 0$0$.
If
J = 1 $J=1$, the Jacobian matrix will be output columnwise at the start of each major iteration. Column
j $j$ will be preceded by the value of the corresponding variable
x_{j} ${x}_{j}$ and a key to indicate whether the variable is basic, superbasic or nonbasic. (Hence if
J = 1 $J=1$, there is no reason to specify
X = 1 $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} ${x}_{3}$ is basic at value
12.5$12.5$, and the third column of the Jacobian has elements of
1.0$1.0$ and
2.0$2.0$ in rows
1$1$ and
4$4$.
Major Step Limit r$r$Default = 2.0$\text{}=2.0$This parameter limits the change in
x $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 < α ≤ β $0<\alpha \le \beta $, where β $\beta $ is 1$1$ if there are nonlinear constraints or is the step to the nearest upper or lower bound on x $x$ if all the constraints are linear. Normally, the first step length tried is
α_{1}
=
min (1,β)
${\alpha}_{1}=\mathrm{min}\phantom{\rule{0.125em}{0ex}}(1,\beta )$.
 In some cases, such as f(x) = a e^{bx} $f\left(x\right)=a{e}^{bx}$ or f(x) = a x^{b} $f\left(x\right)=a{x}^{b}$, even a moderate change in the components of x $x$ can lead to floating point overflow. The parameter r $r$ is therefore used to define a limit β = r(1 + ‖x‖) / ‖p‖ $\stackrel{}{\beta}=r(1+\Vert x\Vert )/\Vert p\Vert $ (where p $p$ is the search direction), and the first evaluation of f(x) $f\left(x\right)$ is at the potentially smaller step length
α_{1}
=
min (1,β,β)
${\alpha}_{1}=\mathrm{min}\phantom{\rule{0.125em}{0ex}}(1,\stackrel{}{\beta},\beta )$.
 Wherever possible, upper and lower bounds on x $x$ should be used to prevent evaluation of nonlinear functions at meaningless points. The optional parameter Major Step Limit provides an additional safeguard. The default value r = 2.0 $r=2.0$ should not affect progress on well behaved problems, but setting r = 0.1 or 0.01 $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.
 In cases where several local optima exist, specifying a small value for r $r$ may help locate an optimum near the starting point.
Minimize DefaultMaximize Feasible Point The keywords
Minimize and
Maximize specify the required direction of optimization. It applies to both linear and nonlinear terms in the objective.
The keyword
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
nag_opt_nlp2_sparse_solve (e04vh).
Minor Feasibility Tolerance r$r$Default =
max (10^{ − 6},sqrt(ε))
$\text{}=\mathrm{max}\phantom{\rule{0.125em}{0ex}}({10}^{6},\sqrt{\epsilon})$Feasibility Tolerance r$r$Default =
max {10^{ − 6},sqrt(ε)}
$\text{}=\mathrm{max}\phantom{\rule{0.125em}{0ex}}\{{10}^{6},\sqrt{\epsilon}\}$nag_opt_nlp2_sparse_solve (e04vh) tries to ensure that all variables eventually satisfy their upper and lower bounds to within this tolerance, r $r$. This includes slack variables. Hence, general linear constraints should also be satisfied to within r $r$.
Feasibility with respect to nonlinear constraints is judged by the optional parameter
Major Feasibility Tolerance (not by
r $r$).
If the bounds and linear constraints cannot be satisfied to within
r $r$, the problem is declared
infeasible. If
sinf
is quite small, it may be appropriate to raise
r $r$ by a factor of
10$10$ or
100$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(x) = sqrt(x_{1}) + log(x_{2}) $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 = 1.0e−6 $r=\text{1.0e\u22126}$, the bounds x_{1} ≥ 10^{ − 5} ${x}_{1}\ge {10}^{5}$ and x_{2} ≥ 10^{ − 4} ${x}_{2}\ge {10}^{4}$ might be appropriate. (The log singularity is more serious. In general, keep x $x$ as far away from singularities as possible.)
If
Scale Option ≥ 1 ${\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,
nag_opt_nlp2_sparse_solve (e04vh) uses
r $r$ as a feasibility tolerance for satisfying the bounds on
x $x$ and
s $s$ in each QP subproblem. If the sum of infeasibilities cannot be reduced to zero, the QP subproblem is declared infeasible.
nag_opt_nlp2_sparse_solve (e04vh) is then in
elastic mode thereafter (with only the linearized nonlinear constraints defined to be elastic). See the description of the optional parameter
Elastic Weight.
Minor Iterations Limit i$i$Default = 500$\text{}=500$If the number of minor iterations for the optimality phase of the QP subproblem exceeds i $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 $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 [Minor Iteration Log]) a
t at the end of a line indicates that the corresponding QP was artificially terminated using the limit
i $i$.
Compare with the optional parameter
Iterations Limit, which defines an independent
absolute limit on the
total number of minor iterations (summed over all QP subproblems).
Minor Print Level i$i$Default = 1$\text{}=1$This controls the amount of output to the
Print File and
Summary File during solution of the QP subproblems. The value of
i $i$ has the following effect:
i$i$ 
Meaning 
0$0$ 
No minor iteration output except error messages. 
≥ 1$\ge 1$ 
A single line of output at each minor iteration (controlled by optional parameters Print Frequency and Summary Frequency. 
≥ 10$\ge 10$ 
Basis factorization statistics generated during the periodic refactorization of the basis (see the optional parameter Factorization Frequency). Statistics for the first factorization each major iteration are controlled by the optional parameter Major Print Level. 
New Basis File i_{1}${i}_{1}$Default = 0$\text{}=0$Backup Basis File i_{2}${i}_{2}$Default = 0$\text{}=0$Save Frequency i_{3}${i}_{3}$Default = 100$\text{}=100$New Basis File and
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 i_{1} > 0 ${i}_{1}>0$, a basis map will be saved in the file associated with unit i_{1} ${i}_{1}$ every i_{3} ${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.
Use of
i_{2} > 0 ${i}_{2}>0$ is intended as a safeguard against losing the results of a long run. Suppose that a
New Basis File is being saved every
100$100$ (
Save Frequency) iterations, and that
nag_opt_nlp2_sparse_solve (e04vh) is about to save such a basis at iteration
2000$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
New Basis File and a
Backup Basis File may be specified. The following would be suitable for the above example:
Backup Basis File 11New Basis File 12
The current basis will then be saved every 100$100$ iterations, first in the file associated with unit 12$12$ and then immediately in the file associated with unit 11$11$. If the run is interrupted at iteration 2000$2000$ during the save in the file associated with unit 12$12$, there will still be a usable basis in the file associated with unit 11$11$ (corresponding to iteration 1900$1900$).
Note that a new basis will be saved in
New Basis File at the end of a run if it terminates normally, but it will not be saved in
Backup Basis File. In the above example, if an optimum solution is found at iteration
2050$2050$ (or if the iteration limit is
2050$2050$), the final basis in the file associated with unit
12$12$ will correspond to iteration
2050$2050$, but the last basis saved in the file associated with unit
11$11$ will be the one for iteration
2000$2000$.
A full description of information recorded in
New Basis File and
Backup Basis File is given in
Gill et al. (2005a).
New Superbasics Limit i$i$Default = 99$\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 $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 [Major Iteration Log]), a
t at the end of a line indicates that the QP was terminated early in this way.
Nolist DefaultList For
nag_opt_nlp2_sparse_solve (e04vh), normally each optional parameter specification is printed as it is supplied. Optional parameter
Nolist may be used to suppress the printing and optional parameter
List may be used to turn on printing.
Old Basis File i$i$Default = 0$\text{}=0$
If
i > 0 $i>0$, the basis maps information will be obtained from this file.
The file will usually have been output previously as a
New Basis File or
Backup Basis File.
A full description of information recorded in
New Basis File and
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$i$Default = 1$\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 $i=1$, all columns of the constraint matrix
$\left(\begin{array}{cc}A& I\end{array}\right)$ are searched. Otherwise,
A $A$ and
I $I$ are partitioned to give
i $i$ roughly equal segments
A_{j} ${A}_{\mathit{j}}$ and
I_{j} ${I}_{\mathit{j}}$, for
j = 1,2, … ,i$\mathit{j}=1,2,\dots ,i$. If the previous pricing search was successful on
A_{j − 1} ${A}_{j1}$ and
I_{j − 1} ${I}_{j1}$, the next search begins on the segments
A_{j} ${A}_{j}$ and
I_{j} ${I}_{j}$. (All subscripts here are modulo
i $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} ${A}_{j+1}$ and
I_{j + 1} ${I}_{j+1}$, and so on.
For timestage models having
t $t$ time periods,
Partial Price t $t$ (or
t / 2 $t/2$ or
t / 3 $t/3$) may be appropriate.
Pivot Tolerance r$r$Default = ε^{(2/3)}$\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 $x$ changes to x + αp $x+\alpha p$ for some search direction p $p$, a ‘ratio test’ determines which component of x $x$ reaches an upper or lower bound first. The corresponding element of p $p$ is called the pivot element. Elements of p $p$ are ignored (and therefore cannot be pivot elements) if they are smaller than the pivot tolerance r $r$.
It is common for two or more variables to reach a bound at essentially the same time. In such cases, the
Minor Feasibility Tolerance (say,
t $t$) provides some freedom to maximize the pivot element and thereby improve numerical stability. Excessively small values of
t $t$ should therefore not be specified. To a lesser extent, the
Expand Frequency (say,
f $f$) also provides some freedom to maximize the pivot element. Excessively
large values of
f $f$ should therefore not be specified.
Print File i$i$Default = 0$\text{}=0$
If
i > 0 $i>0$,
the following information is output to a file associated with
unit
i$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 $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 ifail condition and some statistics about the solution obtained; 
– 
the printed solution, if requested. 
These items are described in
Sections [Further Comments] and
[Description of Monitoring Information]. Further brief output may be directed to the
Summary File.
Print Frequency i$i$Default = 100$\text{}=100$If i > 0 $i>0$, one line of the iteration log will be printed every i $i$th iteration. A value such as i = 10 $i=10$ is suggested for those interested only in the final solution. If i ≤ 0$i\le 0$, the value of i = 99999999$i=99999999$ is used and effectively no checks are made.
Proximal Point Method i$i$Default = 1$\text{}=1$ i = 1 or 2 $i=1\text{ or}2$ specifies minimization of ‖x − x_{0}‖_{1} ${\Vert x{x}_{0}\Vert}_{1}$ or (1/2) ‖x − x_{0}‖_{2}^{2}$\frac{1}{2}{\Vert x{x}_{0}\Vert}_{2}^{2}$ when the starting point x_{0} ${x}_{0}$ is changed to satisfy the linear constraints (where x_{0} ${x}_{0}$ refers to nonlinear variables).
Punch File i_{1}${i}_{1}$Default = 0$=0$Insert File i_{2}${i}_{2}$Default = 0$=0$The
Punch File from a previous run may be used as an
Insert File for a later run on the same problem. A full description of information recorded in
Insert File and
Punch File is given in
Gill et al. (2005a).
If i_{1} > 0 ${i}_{1}>0$, the final solution obtained will be output to the file.
For linear programs, this format is compatible with various commercial systems.
If
i_{2} > 0 ${i}_{2}>0$ the
Insert File containing basis information will be read from unit
i_{2} ${i}_{2}$.
The file will usually have been output previously as a
Punch File. The file will not be accessed if
Old Basis File is specified.
Scale Option i$i$Default = 0$\text{}=0$Scale Tolerance r$r$Default = 0.9$\text{}=0.9$Scale Print Three scale options are available as follows:
i$i$ 
Meaning 
0 
No scaling. This is recommended if it is known that x $x$ and the constraint matrix never have very large elements (say, larger than 100$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$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 righthand side b $b$ or the solution x $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
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
max_{j} ρ_{j}$\underset{j}{\mathrm{max}}}\phantom{\rule{0.25em}{0ex}}{\rho}_{j$ is less than
r $r$ times its previous value, another scaling pass is performed to adjust the row and column scales. Raising
r $r$ from
0.9$0.9$ to
0.99$0.99$ (say) usually increases the number of scaling passes through
A $A$. At most
10$10$ passes are made. The value of
r$r$ should lie in the range
0 < r < 1$0<r<1$.
Scale Print causes the row scales
r(i)$r\left(i\right)$ and column scales
c(j)$c\left(j\right)$ to be printed to
Print File, if
System Information Yes has been specified. The scaled matrix coefficients are
a_{ij}
=
a_{ij}
c(j)
/
r(i)${\stackrel{}{a}}_{ij}={a}_{ij}c\left(j\right)/r\left(i\right)$, and the scaled bounds on the variables and slacks are
l_{j}
=
l_{j}
/
c(j)
${\stackrel{}{l}}_{j}={l}_{j}/c\left(j\right)$,
u_{j}
=
u_{j}
/
c(j)
${\stackrel{}{u}}_{j}={u}_{j}/c\left(j\right)$, where
c(j)
=
r(j − n)
$c\left(j\right)=r(jn)$ if
j > n$j>n$.
Solution File i$i$Default = 0$\text{}=0$If i > 0 $i>0$, the final solution will be output to file i $i$ (whether optimal or not). All numbers are printed in 1pe16.6 format.
To see more significant digits in the printed solution, it will sometimes be useful to
make
i $i$ refer to
Print File.
Summary File i_{1}${i}_{1}$Default = 0$\text{}=0$Summary Frequency i_{2}${i}_{2}$Default = 100$\text{}=100$
If
i_{1} > 0 ${i}_{1}>0$, a brief log will be output to the file associated with unit
i_{1} ${i}_{1}$,
including one line of information every
i_{2} ${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 [The Summary File].
Superbasics Limit i$i$Default
=
n_{1}
$\text{}={n}_{1}$This option places a limit on the storage allocated for superbasic variables. Ideally, i $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 $i$ need not be greater than n + 1 $n+1$, where n_{1} ${n}_{1}$ is the number of nonlinear variables. For many problems, i $i$ may be considerably smaller than n$n$. This will save storage if n$n$ is very large.
Suppress Parameters Normally
nag_opt_nlp2_sparse_solve (e04vh) 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
Suppress Parameters tells
nag_opt_nlp2_sparse_solve (e04vh) not to print the full list.
System Information No DefaultSystem Information Yes This option prints additional information on the progress of major and minor iterations, and Crash statistics. See
Section [Description of Monitoring Information].
Timing Level i$i$Default = 0$\text{}=0$If
i > 0 $i>0$, some timing information will be output to the Print file, if
Print File > 0${\mathbf{Print\; File}}>0$.
Unbounded Objective r_{1}${r}_{1}$Default = 1.0e+15$\text{}=\text{1.0e+15}$Unbounded Step Size r_{2}${r}_{2}$Default = infbnd$\text{}=\mathit{infbnd}$These parameters are intended to detect unboundedness in nonlinear problems. During a linesearch,
F_{obj}${F}_{\mathrm{obj}}$ is evaluated at points of the form
x + αp $x+\alpha p$, where
x $x$ and
p $p$ are fixed and
α $\alpha $ varies. If
F_{obj} $\left{F}_{\mathrm{obj}}\right$ exceeds
r_{1} ${r}_{1}$ or
α $\alpha $ exceeds
r_{2} ${r}_{2}$, iterations are terminated with the exit message
ifail = 5${\mathbf{ifail}}={\mathbf{5}}$.
If singularities are present, unboundedness in F_{obj}(x)${F}_{\mathrm{obj}}\left(x\right)$ may be manifested by a floating point overflow (during the evaluation of F_{obj}(x + αp) ${F}_{\mathrm{obj}}(x+\alpha p)$), before the test against r_{1} ${r}_{1}$ can be made.
Unboundedness in x $x$ is best avoided by placing finite upper and lower bounds on the variables.
Verify Level i$i$Default = 0$\text{}=0$This option refers to finite difference checks on the derivatives computed by the usersupplied functions. Derivatives are checked at the first point that satisfies all bounds and linear constraints.
i$i$ 
Meaning 
0$0$ 
Only a ‘cheap’ test will be performed, requiring two calls to usrfun. 
1$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$2$ 
Individual columns of the problem Jacobian will be checked. 
3$3$ 
Options 2 and 1 will both occur (in that order). 
− 1$1$ 
Derivative checking is disabled. 
Verify Level = 3${\mathbf{Verify\; Level}}=3$ should be specified whenever a new
usrfun is being developed.
Violation Limit r$r$Default = 1.0e+6$\text{}=\text{1.0e+6}$This keyword defines an absolute limit on the magnitude of the maximum constraint violation,
r $r$, after the linesearch. On completion of the linesearch, the new iterate
x_{k + 1} ${x}_{k+1}$ satisfies the condition
where
x_{0} ${x}_{0}$ is the point at which the nonlinear constraints are first evaluated and
v_{i}(x) ${v}_{i}\left(x\right)$ is the
i $i$th nonlinear constraint violation
v_{i}(x)
=
max (0,
l_{i}
−
f_{i}(x)
,
f_{i}(x)
−
u_{i}
)
${v}_{i}\left(x\right)=\mathrm{max}\phantom{\rule{0.125em}{0ex}}(0,{l}_{i}{f}_{i}\left(x\right),{f}_{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 $r$. This makes it possible to keep the iterates within a region where the objective is expected to be welldefined and bounded below. If the objective is bounded below for all values of the variables, then r $r$ may be any large positive value.
Description of Monitoring Information
nag_opt_nlp2_sparse_solve (e04vh) produces monitoring information, statistical information and information about the solution.
Section [The Final Output] contains details of the final output information sent to the unit specified by the optional parameter
Print File. This section contains other details of output information.
Major Iteration Log
This section describes the output to unit
Print File if
Major Print Level
>
0
${\mathbf{Major\; Print\; Level}}>0$. One line of information is output every
k
$k$th major iteration, where
k
$k$ is
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$1$ in the later iterations, since theoretical analysis predicts that the correct active set will be identified near the solution (see Section [Algorithmic Details]). 
Step 
is the step length
α
$\alpha $ taken along the current search direction
p
$p$. The variables
x
$x$ have just been changed to
x
+
α
p
$x+\alpha p$. On reasonably wellbehaved problems, the unit step will be taken as the solution is approached. 
nCon 
the number of times usrfun 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. 
Feasible 
is the value of v_{max}${v}_{\mathrm{max}}$ (see (13)), the maximum component of the scaled nonlinear constraint residual (see optional parameter Major Feasibility Tolerance). The solution is regarded as acceptably feasible if Feasible is less than the 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_{max}${c}_{\mathrm{max}}$ (see (14)), the maximum complementary gap (see optional parameter 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 
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 [The Merit Function]). 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
$L$ and
U
$U$ on completion of the QP subproblem.
If nonlinear constraints are present, the basis factorization
B
=
LU
$B=LU$ is computed at the start of the first minor iteration. At this stage,
L+U
=
lenL+lenU
$\mathtt{L+U}=\mathtt{lenL+lenU}$, where lenL (see Section [Basis Factorization Statistics]) is the number of subdiagonal elements in the columns of a lower triangular matrix and lenU (see Section [Basis Factorization Statistics]) is the number of diagonal and superdiagonal elements in the rows of an uppertriangular matrix.
As columns of
B
$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
$LU$ factors at the start of the QP subproblem.
If the constraints are linear, refactorization is subject only to the Factorization Frequency, and L+U will tend to increase between factorizations. 
BSwap 
is the number of columns of the basis matrix
B
$B$ that were swapped with columns of
S
$S$ to improve the condition of
B
$B$. The swaps are determined by an
LU
$LU$ factorization of the rectangular matrix
B_{S}
=
(B S)^{T}
${B}_{S}={\left(B\text{}S\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^{T}R
${R}^{\mathrm{T}}R$, itself an estimate of
Z^{T}HZ
${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
$R$, this being a lower bound on the condition number of
R^{T}R
${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
ε^{ − 1 / 2}
≈
10^{8}
${\epsilon}^{1/2}\approx {10}^{8}$, and will probably fail to find a better solution if condHz reaches
ε^{ − 3 / 4}
≈
10^{12}
${\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
$x$ is close to being optimal. In some cases, it may be necessary to resolve 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 the optional parameter Violation Limit. 
D 
you set
status = − 1
${\mathbf{status}}=1$ on exit from usrfun, 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 optional parameter Major Step Limit. If this output occurs repeatedly during later iterations, it may be worthwhile increasing the value of the optional parameter Major Step Limit. 
i 
if nag_opt_nlp2_sparse_solve (e04vh) 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 (12) (see Section [Treatment of Constraint Infeasibilities]).
If nag_opt_nlp2_sparse_solve (e04vh) 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 quasiNewton 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 Hessian Frequency and Hessian Updates keywords. However, it may also be necessary to reset an illconditioned 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 selfscaled 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 Minor Iterations Limit. 
T 
the minor iterations were terminated because of the New Superbasics Limit. 
u 
the QP subproblem was unbounded. 
w 
a weak solution of the QP subproblem was found. 
z 
the Superbasics Limit was reached. 
Minor Iteration Log
If
Minor Print Level
>
0
${\mathbf{Minor\; Print\; Level}}>0$, one line of information is output to the Print file every
k
$k$th minor iteration, where
k
$k$ is the specified
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
Partial Price is in effect, variable
jq is selected from
A_{pp}
${A}_{\mathtt{pp}}$ or
I_{pp}
${I}_{\mathtt{pp}}$, the
pp
$\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}
−
π^{T}
a_{j}
${d}_{j}={g}_{j}{\pi}^{\mathrm{T}}{a}_{j}$ for
j
=
jq
$j=\mathtt{jq}$, where
g_{j}
${g}_{j}$ is the gradient of the current objective function,
π
$\pi $ is the vector of dual variables for the QP subproblem, and
a_{j}
${a}_{j}$ is the
j
$j$th column of
$\left(\begin{array}{cc}A& I\end{array}\right)$.
Note that the reduced cost is the 1$1$norm of the reducedgradient 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
$p$. The variables
x
$x$ have just been changed to
x
+
α
p
$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 (
+SBS > 0
$\mathtt{+SBS}>0$), Step will be the step to the nearest bound. During Phase 2, the step can be greater than one 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 nInf > 0$\mathtt{nInf}>0$. The value usually decreases at each nonzero Step, but if it decreases by 2$2$ or more, SumInf may occasionally increase. 
rgNorm 
is the norm of the reducedgradient vector at the start of the iteration. (It is the norm of the vector with elements
d_{j}
${d}_{j}$ for variables
j
$j$ in the superbasic set.) During Phase 2 this norm will be approximately zero after a unit step. (The heading is not printed if the problem is linear.) 
LPobjective or QPobjective 
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}
${a}_{q}$ replaces the
r
$r$th column of the basis
B
$B$, Pivot is the
r
$r$th element of a vector
y
$y$ satisfying
By = a_{q}
$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 Pivot Tolerance to exclude very small elements of
y
$y$ from consideration during the computation of Step. 
L+U 
is the number of nonzeros representing the basis factors
L
$L$ and
U
$U$. Immediately after a basis factorization
B = LU
$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 uppertriangular matrix. Further nonzeros are added to L when various columns of
B
$B$ are later replaced. As columns of
B
$B$ are replaced, the matrix
U
$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
$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 [Major Iteration Log]. (The heading is not printed if the problem is linear.) 
Crash Statistics
If
Major Print Level
≥
10
${\mathbf{Major\; Print\; Level}}\ge 10$ and
System Information Yes has been specified, the following items are output to the Print file when
start = 0${\mathbf{start}}=0$ and no Basis file is loaded. They refer to the number of columns that the Crash procedure selects during selected passes through
A
$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.,
xstate(j) = 3
${\mathbf{xstate}}\left(j\right)=3$ for some
j ≤ n
$j\le n$). 
Unit 
is the number of unit columns in the basis. 
Double 
is the number of columns in the basis containing 2$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). 
Basis Factorization Statistics
If
Major Print Level
≥
10
${\mathbf{Major\; Print\; Level}}\ge 10$, the first seven items listed below are output to the Print file whenever the basis
B
$B$ or the rectangular matrix
B_{S}
=
(B S)^{T}
${B}_{S}={\left(B\text{}S\right)}^{\mathrm{T}}$ is factorized before solution of the next QP subproblem (see
Section [Description of the optional parameters]).
Note that B_{S}${B}_{S}$ may be factorized at the start of just some of the major iterations. It is immediately followed by a factorization of B$B$ itself.
Gaussian elimination is used to compute a sparse
LU
$LU$ factorization of
B
$B$ or
B_{S}
${B}_{S}$, where
PLP^{T}
$PL{P}^{\mathrm{T}}$ and
PUQ
$PUQ$ are lower and upper triangular matrices, for some permutation matrices
P
$P$ and
Q
$Q$. Stability is ensured as described under optional parameter
LU Factor Tolerance.
If
Minor Print Level
≥
10
${\mathbf{Minor\; Print\; Level}}\ge 10$, the same items are printed during the QP solution whenever the current
B
$B$ is factorized. In addition, if
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
$LU$ factorization. 
1 
The number of updates reached the Factorization Frequency. 
2 
The nonzeros in the updated factors have increased significantly. 
7 
Not enough storage to update factors. 
10 
Row residuals are too large (see the description of the optional parameter Check Frequency). 
11 
Illconditioning has caused inconsistent results. 

Itn 
is the current minor iteration number. 
Nonlin 
is the number of nonlinear variables in the current basis
B
$B$. 
Linear 
is the number of linear variables in
B
$B$. 
Slacks 
is the number of slack variables in
B
$B$. 
B, BR, BS or BT factorize 
is the type of
LU
$LU$ factorization.
B 
periodic factorization of the basis
B
$B$. 
BR 
more careful rankrevealing factorization of
B
$B$ using threshold rook pivoting. This occurs mainly at the start, if the first basis factors seem singular or illconditioned. Followed by a normal B factorize. 
BS 
B_{S}
${B}_{S}$ is factorized to choose a wellconditioned
B
$B$ from the current
(B S)
$\left(B\text{}S\right)$. Followed by a normal B factorize. 
BT 
same as BS except the current
B
$B$ is tried first and accepted if it appears to be not much more illconditioned than after the previous BS factorize. 

m 
is the number of rows in
B
$B$ or
B_{S}
${B}_{S}$. 
n 
is the number of columns in
B
$B$ or
B_{S}
${B}_{S}$. Preceded by ‘=’ or ‘>’ respectively. 
Elems 
is the number of nonzero elements in
B
$B$ or
B_{S}
${B}_{S}$. 
Amax 
is the largest nonzero in
B
$B$ or
B_{S}
${B}_{S}$. 
Density 
is the percentage nonzero density of
B
$B$ or
B_{S}
${B}_{S}$. 
Merit/MerRP/MerCP 
Merit is the average Markowitz merit count for the elements chosen to be the diagonals of
PUQ
$PUQ$. Each merit count is defined to be
(c − 1)
(r − 1)
$(c1)(r1)$ where
c
$c$ and
r
$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 LU Complete Pivoting or LU Rook Pivoting has been selected, this heading is changed to MerCP, respectively MerRP. 
lenL 
is the number of nonzeros in
L
$L$. 
L+U 
is the number of nonzeros representing the basis factors
L
$L$ and
U
$U$. Immediately after a basis factorization
B = LU
$B=LU$, this 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 uppertriangular matrix. Further nonzeros are added to L when various columns of
B
$B$ are later replaced. As columns of
B
$B$ are replaced, the matrix
U
$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$3$ or 4$4$, the amount of workspace available to nag_opt_nlp2_sparse_solve (e04vh) should be increased for efficiency. 
Incres 
is the percentage increase in the number of nonzeros in
L
$L$ and
U
$U$ relative to the number of nonzeros in
B
$B$ or
B_{S}
${B}_{S}$. 
Utri 
is the number of triangular rows of
B
$B$ or
B_{S}
${B}_{S}$ at the top of
U
$U$. 
lenU 
the number of nonzeros in
U
$U$, including its diagonals. 
Ltol 
is the largest subdiagonal element allowed in
L
$L$. This is the specified LU Factor Tolerance or a smaller value that is currently being used for greater stability. 
Umax 
the maximum nonzero element in
U
$U$. 
Ugrwth 
is the ratio
Umax / Amax
$\mathtt{Umax}/\mathtt{Amax}$, which ideally should not be substantially larger than 10.0$10.0$ or 100.0$100.0$. If it is orders of magnitude larger, it may be advisable to reduce the LU Factor Tolerance to 5.0$5.0$, 4.0$4.0$, 3.0$3.0$ or 2.0$2.0$, say (but bigger than 1.0$1.0$).
As long as Lmax is not large (say 5.0$5.0$ or less),
max (Amax,Umax)
/
DUmin
$\mathrm{max}\phantom{\rule{0.125em}{0ex}}(\mathtt{Amax},\mathtt{Umax})/\mathtt{DUmin}$ gives an estimate of the condition number
B
$B$. If this is extremely large, the basis is nearly singular. Slacks are used to replace suspect columns of
B
$B$ and the modified basis is refactored. 
Ltri 
is the number of triangular columns of
B
$B$ or
B_{S}
${B}_{S}$ at the left of
L
$L$. 
dense1 
is the number of columns remaining when the density of the basis matrix being factorized reached 0.3$0.3$. 
Lmax 
is the actual maximum subdiagonal element in
L
$L$ (bounded by Ltol). 
Akmax 
is the largest nonzero generated at any stage of the
LU
$LU$ factorization. (Values much larger than Amax indicate instability.) Akmax is not printed if LU Partial Pivoting is selected. 
Agrwth 
is the ratio
Akmax / Amax
$\mathtt{Akmax}/\mathtt{Amax}$. Values much larger than 100$100$ (say) indicate instability. Agrwth is not printed if LU Partial Pivoting is selected. 
bump 
is the size of the block to be factorized nontrivially after the triangular rows and columns of
B
$B$ or
B_{S}
${B}_{S}$ have been removed. 
dense2 
is the number of columns remaining when the density of the basis matrix being factorized reached 0.6$0.6$. (The Markowitz pivot strategy searches fewer columns at that stage.) 
DUmax 
is the largest diagonal of
PUQ
$PUQ$. 
DUmin 
is the smallest diagonal of
PUQ
$PUQ$. 
condU 
the ratio
DUmax / DUmin
$\mathtt{DUmax}/\mathtt{DUmin}$, which estimates the condition number of
U
$U$ (and of
B
$B$ if Ltol is less than 5.0$5.0$, say). 
The Solution File
At the end of a run, the final solution may be output as a Solution file, according to
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.
In general, numerical values are output with format f16.5.
The maximum record length is 111$111$ characters, including the first (carriagecontrol) character.
To reduce clutter, a full stop (.) is printed for any numerical value that is exactly zero. The values
± 1
$\pm 1$ are also printed specially as
1.0
$1.0$ and
− 1.0
$1.0$. Infinite bounds (
±
10^{20}
$\pm {10}^{20}$ or larger) are printed as None.
A Solution file is intended to be read from disk by a selfcontained program that extracts and saves certain values as required for possible further computation. Typically, the first 14$14$ records would be ignored.
The end of the ROWS section is marked by a record that starts with a 1$1$ and is otherwise blank. If this and the next 4$4$ records are skipped, the COLUMNS section can then be read under the same format.
(There should be no need for backspace statements.)
A full description of the ROWS section and the COLUMNS section is given in
Sections [The ROWS section] and
[The COLUMNS section].
The Summary File
If
Summary File
>
0
${\mathbf{Summary\; File}}>0$, the following information is output to the unit number associated with
Summary File.
(It is a brief summary of the output directed to unit
Print File):
PDF version (NAG web site
, 64bit version, 64bit version)
© The Numerical Algorithms Group Ltd, Oxford, UK. 2009–2013