naginterfaces.library.opt.qpconvex2_​sparse_​solve

naginterfaces.library.opt.qpconvex2_sparse_solve(start, m, ncolh, iobj, objadd, prob, acol, inda, loca, bl, bu, names, helast, hs, x, ns, comm, qphx=None, c=None, data=None, io_manager=None)

qpconvex2_sparse_solve solves sparse linear programming or convex quadratic programming problems. The initialization function qpconvex2_sparse_init() must have been called before calling qpconvex2_sparse_solve.

Note: this function uses optional algorithmic parameters, see also: qpconvex2_sparse_option_file(), qpconvex2_sparse_option_string(), qpconvex2_sparse_option_integer_set(), qpconvex2_sparse_option_double_set(), qpconvex2_sparse_init(), qpconvex2_sparse_option_integer_get(), qpconvex2_sparse_option_double_get().

For full information please refer to the NAG Library document for e04nq

https://support.nag.com/numeric/nl/nagdoc_30/flhtml/e04/e04nqf.html

Parameters

startstr, length 1

Indicates how a starting basis (and certain other items) will be obtained.

$start=\text{'C'}$

Requests that an internal Crash procedure be used to choose an initial basis, unless a Basis file is provided via options ‘Old Basis File’, ‘Insert File’ or ‘Load File’.

$start=\text{'B'}$

Is the same as $start=\text{'C'}$ but is more meaningful when a Basis file is given.

$start=\text{'W'}$

Means that a basis is already defined in $hs$ and a start point is already defined in $x$ (probably from an earlier call).

mint

$m$, the number of general linear constraints (or slacks). This is the number of rows in the linear constraint matrix $A$, including the free row (if any; see $iobj$). Note that $A$ must have at least one row. If your problem has no constraints, or only upper or lower bounds on the variables, then you must include a dummy row with sufficiently wide upper and lower bounds (see also $acol$, $inda$ and $loca$).

ncolhint

$n_H$, the number of leading nonzero columns of the Hessian matrix $H$. For FP and LP problems, $ncolh$ must be set to zero.

The first $ncolh$ elements of $x$ belong to variables corresponding to the nonzero block of the QP Hessian.

iobjint

If $iobj>0$, row $iobj$ of $A$ is a free row containing the nonzero elements of the vector $c$ appearing in the linear objective term $c^{T}x$.

If $iobj=0$, there is no free row, and the linear objective vector should be supplied in array $c$.

objaddfloat

The constant $q$, to be added to the objective for printing purposes. Typically $objadd=0.0e0$.

probstr, length 8

The name for the problem. It is used in the printed solution and in some functions that output Basis files. A blank name may be used.

acolfloat, array-like, shape $\left(\text{ne}\right)$

The nonzero elements of $A$, ordered by increasing column index. Note that all elements must be assigned a value in the calling program.

indaint, array-like, shape $\left(\text{ne}\right)$

$inda[\text{i}-1]$ must contain the row index of the nonzero element stored in $acol[\text{i}-1]$, for $\text{i}=1,2,\dots ,\text{ne}$. Thus a pair of values $\left(acol\right[i-1],inda[i-1\left]\right)$ contains a matrix element and its corresponding row index.

Note that the row indices for a column may be supplied in any order.

locaint, array-like, shape $(n+1)$

$loca[\text{j}-1]$ must contain the index in $acol$ and $inda$ of the start of the $\text{j}$th column, for $\text{j}=1,2,\dots ,n$. Thus for $j=1:n$, the entries of column $j$ are held in $acol[k-1:l]$ and their corresponding row indices are in $inda[k-1:l]$, where $k=loca[j-1]$ and $l=loca\left[j\right]-1$. To specify the $j$th column as empty, set $loca[j-1]=loca\left[j\right]$. Note that the first and last elements of $loca$ must be $loca\left[0\right]=1$ and $loca\left[n\right]=\text{ne}+1$. If your problem has no constraints, or just bounds on the variables, you may include a dummy ‘free’ row with a single (zero) element by setting $\text{ne}=1$, $acol\left[0\right]=0.0$, $inda\left[0\right]=1$, $loca\left[0\right]=1$, and $loca[j-1]=2$, for $j=2:n+1$. This row is made ‘free’ by setting its bounds to be $bl\left[n\right]=-\text{bigbnd}$ and $bu\left[n\right]=\text{bigbnd}$, where $\text{bigbnd}$ is the value of the option ‘Infinite Bound Size’.

blfloat, array-like, shape $(n+m)$

$l$, the lower bounds for all the variables and general constraints, in the following order. The first $\text{n}$ elements of $bl$ must contain the bounds on the variables $x$, and the next $m$ elements the bounds for the general linear constraints $Ax$ (which, equivalently, are the bounds for the slacks, $s$) and the free row (if any). To fix the $j$th variable, set $bl[j-1]=bu[j-1]=\beta$, say, where $\left|\beta \right|<\text{bigbnd}$. To specify a nonexistent lower bound (i.e., $l_j=-\infty$), set $bl[j-1]\le -\text{bigbnd}$. Here, $\text{bigbnd}$ is the value of the option ‘Infinite Bound Size’. To specify the $j$th constraint as an equality, set $bl[n+j-1]=bu[n+j-1]=\beta$, say, where $\left|\beta \right|<\text{bigbnd}$. Note that the lower bound corresponding to the free row must be set to $-\infty$ and stored in $bl[n+iobj-1]$.

bufloat, array-like, shape $(n+m)$

$u$, the upper bounds for all the variables and general constraints, in the following order. The first $\text{n}$ elements of $bu$ must contain the bounds on the variables $x$, and the next $m$ elements the bounds for the general linear constraints $Ax$ (which, equivalently, are the bounds for the slacks, $s$) and the free row (if any). To specify a nonexistent upper bound (i.e., $u_j=+\infty$), set $bu[j-1]\ge \text{bigbnd}$. Note that the upper bound corresponding to the free row must be set to $+\infty$ and stored in $bu[n+iobj-1]$.

namesstr, length 8, array-like, shape $\left(\text{nname}\right)$

The optional column and row names, respectively.

If $\text{nname}=1$, $names$ is not referenced and the printed output will use default names for the columns and rows.

If $\text{nname}=n+m$, the first $\text{n}$ elements must contain the names for the columns and the next $m$ elements must contain the names for the rows.

Note that the name for the free row (if any) must be stored in $names[n+iobj-1]$.

helastint, array-like, shape $(n+m)$

Defines which variables are to be treated as being elastic in elastic mode. The allowed values of $helast$ are:

$helast[j-1]$	Status in elastic mode
$0$	Variable $j$ is non-elastic and cannot be infeasible
$1$	Variable $j$ can violate its lower bound
$2$	Variable $j$ can violate its upper bound
$3$	Variable $j$ can violate either its lower or upper bound

$helast$ need not be assigned if option $\text{‘Elastic Mode'}=0$.

hsint, array-like, shape $(n+m)$

If $start=\text{'C'}$ or $\text{'B'}$, and a Basis file of some sort is to be input (see the description of the options ‘Old Basis File’, ‘Insert File’ or ‘Load File’), then $hs$ and $x$ need not be set at all.

If $start=\text{'C'}$ or $\text{'B'}$ and there is no Basis file, the first $\text{n}$ elements of $hs$ and $x$ must specify the initial states and values, respectively, of the variables $x$. (The slacks $s$ need not be initialized.) An internal Crash procedure is then used to select an initial basis matrix $B$.

The initial basis matrix will be triangular (neglecting certain small elements in each column).

It is chosen from various rows and columns of $\left(\begin{array}{cc}A& -I\end{array}\right)$.

Possible values for $hs[j-1]$ are as follows:

$hs[j-1]$	State of $x[j-1]$ during Crash procedure
$0$ or $1$	Eligible for the basis
$2$	Ignored
$3$	Eligible for the basis (given preference over $0$ or $1$)
$4$ or $5$	Ignored

If nothing special is known about the problem, or there is no wish to provide special information, you may set $hs[\text{j}-1]=0$ and $x[\text{j}-1]=0.0$, for $\text{j}=1,2,\dots ,n$.

All variables will then be eligible for the initial basis.

Less trivially, to say that the $j$th variable will probably be equal to one of its bounds, set $hs[j-1]=4$ and $x[j-1]=bl[j-1]$ or $hs[j-1]=5$ and $x[j-1]=bu[j-1]$ as appropriate.

Following the Crash procedure, variables for which $hs[j-1]=2$ are made superbasic.

Other variables not selected for the basis are then made nonbasic at the value $x[j-1]$ if $bl[j-1]\le x[j-1]\le bu[j-1]$, or at the value $bl[j-1]$ or $bu[j-1]$ closest to $x[j-1]$.

If $start=\text{'W'}$, $hs$ and $x$ must specify the initial states and values, respectively, of the variables and slacks $(x,s)$.

If qpconvex2_sparse_solve has been called previously with the same values of $\text{n}$ and $m$, $hs$ already contains satisfactory information.

xfloat, array-like, shape $(n+m)$

The initial values of the variables $x$, and, if $start=\text{'W'}$, the slacks $s$, i.e., $(x,s)$. (See the description for argument $hs$.)

nsint

$n_S$, the number of superbasics. For QP problems, $ns$ need not be specified if $start=\text{'C'}$, but must retain its value from a previous call when $start=\text{'W'}$. For FP and LP problems, $ns$ need not be initialized.

commdict, communication object, modified in place

Communication structure.

This argument must have been initialized by a prior call to qpconvex2_sparse_init().

qphxNone or callable hx = qphx(x, nstate, data=None), optional

Note: if this argument is None then a NAG-supplied facility will be used.

For QP problems, you must supply a version of $qphx$ to compute the matrix product $Hx$ for a given vector $x$.

If $H$ has rows and columns of zeros, it is most efficient to order $x$ so that the nonlinear variables appear first.

For example, if $x={(y,z)}^T$ and only $y$ enters the objective quadratically, then

$$\begin{array}{c}Hx=\left(\begin{array}{cc}{H}_1& 0\\ 0& 0\end{array}\right)\left(\begin{array}{c}y\\ z\end{array}\right)=\left(\begin{array}{c}{H}_{1}y\\ 0\end{array}\right)\text{.}\end{array}$$

In this case, $ncolh$ should be the dimension of $y$, and $qphx$ should compute $H_{1}y$.

For FP and LP problems, $qphx$ will never be called by qpconvex2_sparse_solve and hence $qphx$ may be None.

Parameters

xfloat, ndarray, shape $\left(\text{ncolh}\right)$

The first $ncolh$ elements of the vector $x$.

nstateint

Allows you to save computation time if certain data must be read or calculated only once. To preserve this data for a subsequent calculation place it in one of $cuser$, $ruser$ or $iuser$.

$nstate=1$

qpconvex2_sparse_solve is calling $qphx$ for the first time.

$nstate=0$

There is nothing special about the current call of $qphx$.

$nstate\ge 2$

qpconvex2_sparse_solve is calling $qphx$ for the last time. This argument setting allows you to perform some additional computation on the final solution.

$nstate=2$

The current $x$ is optimal.

$nstate=3$

The problem appears to be infeasible.

$nstate=4$

The problem appears to be unbounded.

$nstate=5$

The iterations limit was reached.

dataarbitrary, optional, modifiable in place

User-communication data for callback functions.

Returns

hxfloat, array-like, shape $\left(\text{ncolh}\right)$

The product $Hx$. If $ncolh$ is less than the input argument $\text{n}$, $Hx$ is really the product $H_{1}y$ in [equation].

cNone or float, array-like, shape $\left(\text{lenc}\right)$, optional

Contains the explicit objective vector $c$ (if any). If the problem is of type FP, or if $\text{lenc}=0$, $c$ is not referenced. (In that case, $c$ may be dimensioned (1), or it could be any convenient array.)

dataarbitrary, optional

User-communication data for callback functions.

io_managerFileObjManager, optional

Manager for I/O in this routine.

Returns

hsint, ndarray, shape $(n+m)$

The final states of the variables and slacks $(x,s)$. The significance of each possible value of $hs[j-1]$ is as follows:

$hs[j-1]$	State of variable $j$	Normal value of $x[j-1]$
$0$	Nonbasic	$bl[j-1]$
$1$	Nonbasic	$bu[j-1]$
$2$	Superbasic	Between $bl[j-1]$ and $bu[j-1]$
$3$	Basic	Between $bl[j-1]$ and $bu[j-1]$

If $ninf=0$, basic and superbasic variables may be outside their bounds by as much as the value of the option ‘Feasibility Tolerance’.

Note that unless the option $\text{‘Scale Option'}=0$ is specified, the option ‘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$ outside their bounds, but this is unlikely unless the problem is very badly scaled.

Very occasionally some nonbasic variables may be outside their bounds by as much as the option ‘Feasibility Tolerance’, and there may be some nonbasic variables for which $x[j-1]$ lies strictly between its bounds.

If $ninf>0$, some basic and superbasic variables may be outside their bounds by an arbitrary amount (bounded by $sinf$ if $\text{‘Scale Option'}=0$).

xfloat, ndarray, shape $(n+m)$

The final values of the variables and slacks $(x,s)$.

pifloat, ndarray, shape $\left(m\right)$

Contains the dual variables $\pi$ (a set of Lagrange multipliers (shadow prices) for the general constraints).

rcfloat, ndarray, shape $(n+m)$

Contains the reduced costs, $g-{\left(\begin{array}{cc}A& -I\end{array}\right)}^T\pi$. The vector $g$ is the gradient of the objective if $x$ is feasible; otherwise, it is the gradient of the Phase 1 objective. In the former case, $g\left(i\right)=0$, for $i=n+1:m$, hence $rc[n+1:m-1]=\pi$.

nsint

The final number of superbasics. This will be zero for FP and LP problems.

ninfint

The number of infeasibilities.

sinffloat

The sum of the scaled infeasibilities. This will be zero if $ninf=0$, and is most meaningful when $\text{‘Scale Option'}=0$.

objfloat

The value of the objective function.

If $ninf=0$, $obj$ includes the quadratic objective term $\frac{1}{2}{x}^{T}Hx$ (if any).

If $ninf>0$, $obj$ is just the linear objective term $c^{T}x$ (if any).

For FP problems, $obj$ is set to zero.

Note that $obj$ does not include contributions from the constant term $objadd$ or the objective row, if any.

Other Parameters

‘Check Frequency’int

Default $=60$

Every $i$th iteration after the most recent basis factorization, a numerical test is made to see if the current solution $(x,s)$ satisfies the linear constraints $Ax-s=0$. If the largest element of the residual vector $r=Ax-s$ is judged to be too large, the current basis is refactorized and the basic variables recomputed to satisfy the constraints more accurately. If $i\le 0$, the value $i=99999999$ is used and effectively no checks are made.

$\text{‘Check Frequency'}=1$ is useful for debugging purposes, but otherwise this option should not be needed.

‘Crash Option’int

Default $=3$

Note that these options do not apply when $start=\text{'W'}$ (see Parameters).

If $start=\text{'C'}$, an internal Crash procedure is used to select an initial basis from various rows and columns of the constraint matrix $\left(\begin{array}{cc}A& -I\end{array}\right)$. The value of $i$ determines which rows and columns of $A$ are initially eligible for the basis, and how many times the Crash procedure is called. Columns of $-I$ are used to pad the basis where necessary.

$i$	Meaning
$0$	The initial basis contains only slack variables: $B=I$.
$1$	The Crash procedure is called once, looking for a triangular basis in all rows and columns of the matrix $A$.
$2$	The Crash procedure is called once, looking for a triangular basis in rows.
$3$	The Crash procedure is called twice, treating linear equalities and linear inequalities separately.

If $i\ge 1$, certain slacks on inequality rows are selected for the basis first. (If $i\ge 2$, numerical values are used to exclude slacks that are close to a bound.) The Crash procedure then makes several passes through the columns of $A$, searching for a basis matrix that is essentially triangular. A column is assigned to ‘pivot’ on a particular row if the column contains a suitably large element in a row that has not yet been assigned. (The pivot elements ultimately form the diagonals of the triangular basis.) For remaining unassigned rows, slack variables are inserted to complete the basis.

The ‘Crash Tolerance’ allows the Crash procedure to ignore certain ‘small’ nonzero elements in each column of $A$. If $a_{max}$ is the largest element in column $j$, other nonzeros $a_{ij}$ in the column are ignored if $\left|a_{ij}\right|\le a_{max}\times r$. (To be meaningful, $r$ should be in the range $0\le r<1$.)

When $r>0.0$, the basis obtained by the Crash procedure may not be strictly triangular, but it is likely to be nonsingular and almost triangular. The intention is to obtain a starting basis containing more columns of $A$ and fewer (arbitrary) slacks. A feasible solution may be reached sooner on some problems.

For example, suppose the first $m$ columns of $A$ form the matrix shown under ‘LU Factor Tolerance’; i.e., a tridiagonal matrix with entries $-1$, $4$, $-1$. To help the Crash procedure choose all $m$ columns for the initial basis, we would specify a ‘Crash Tolerance’ of $r$ for some value of $r>0.5$.

‘Crash Tolerance’float

Default $=0.1$

Note that these options do not apply when $start=\text{'W'}$ (see Parameters).

If $start=\text{'C'}$, an internal Crash procedure is used to select an initial basis from various rows and columns of the constraint matrix $\left(\begin{array}{cc}A& -I\end{array}\right)$. The value of $i$ determines which rows and columns of $A$ are initially eligible for the basis, and how many times the Crash procedure is called. Columns of $-I$ are used to pad the basis where necessary.

$i$	Meaning
$0$	The initial basis contains only slack variables: $B=I$.
$1$	The Crash procedure is called once, looking for a triangular basis in all rows and columns of the matrix $A$.
$2$	The Crash procedure is called once, looking for a triangular basis in rows.
$3$	The Crash procedure is called twice, treating linear equalities and linear inequalities separately.

If $i\ge 1$, certain slacks on inequality rows are selected for the basis first. (If $i\ge 2$, numerical values are used to exclude slacks that are close to a bound.) The Crash procedure then makes several passes through the columns of $A$, searching for a basis matrix that is essentially triangular. A column is assigned to ‘pivot’ on a particular row if the column contains a suitably large element in a row that has not yet been assigned. (The pivot elements ultimately form the diagonals of the triangular basis.) For remaining unassigned rows, slack variables are inserted to complete the basis.

The ‘Crash Tolerance’ allows the Crash procedure to ignore certain ‘small’ nonzero elements in each column of $A$. If $a_{max}$ is the largest element in column $j$, other nonzeros $a_{ij}$ in the column are ignored if $\left|a_{ij}\right|\le a_{max}\times r$. (To be meaningful, $r$ should be in the range $0\le r<1$.)

When $r>0.0$, the basis obtained by the Crash procedure may not be strictly triangular, but it is likely to be nonsingular and almost triangular. The intention is to obtain a starting basis containing more columns of $A$ and fewer (arbitrary) slacks. A feasible solution may be reached sooner on some problems.

For example, suppose the first $m$ columns of $A$ form the matrix shown under ‘LU Factor Tolerance’; i.e., a tridiagonal matrix with entries $-1$, $4$, $-1$. To help the Crash procedure choose all $m$ columns for the initial basis, we would specify a ‘Crash Tolerance’ of $r$ for some value of $r>0.5$.

‘Defaults’valueless

This special keyword may be used to reset all options to their default values.

‘Dump File’int

Default $=0$

Options ‘Dump File’ and ‘Load File’ are similar to options ‘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 options ‘Dump File’ and ‘Load File’ is given in Gill et al. (2005a).

If $i_1>0$, the last solution obtained will be output to the file with unit number $i$.

If $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 options ‘Old Basis File’ or ‘Insert File’ are specified.

‘Load File’int

Default $=0$

Options ‘Dump File’ and ‘Load File’ are similar to options ‘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 options ‘Dump File’ and ‘Load File’ is given in Gill et al. (2005a).

If $i_1>0$, the last solution obtained will be output to the file with unit number $i$.

If $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 options ‘Old Basis File’ or ‘Insert File’ are specified.

‘Elastic Mode’int

Default $=1$

This argument determines if (and when) elastic mode is to be started. Three elastic modes are available as follows:

$i$	Meaning
$0$	Elastic mode is never invoked. qpconvex2_sparse_solve will terminate as soon as infeasibility is detected. There may be other points with significantly smaller sums of infeasibilities.
$1$	Elastic mode is invoked only if the constraints are found to be infeasible (the default). If the constraints are infeasible, continue in elastic mode with the composite objective determined by the values of the options ‘Elastic Objective’ and ‘Elastic Weight’.
$2$	The iterations start and remain in elastic mode. This option allows you to minimize the composite objective function directly without first performing Phase 1 iterations. The success of this option will depend critically on your choice of ‘Elastic Weight’. If ‘Elastic Weight’ is sufficiently large and the constraints are feasible, the minimizer of the composite objective and the solution of the original problem are identical. However, if the ‘Elastic Weight’ is not sufficiently large, the minimizer of the composite function may be infeasible, even if a feasible point exists.

‘Elastic Objective’int

Default $=1$

This determines the form of the composite objective $f\left(x\right)+\gamma {\sum }_j(v_j+w_j)$ in Phase 2 ($\gamma$). Three types of composite objectives are available.

$i$	Meaning
$0$	Include only the true objective $f\left(x\right)$ in the composite objective. This option sets $\gamma =0$ in the composite objective and allows qpconvex2_sparse_solve to ignore the elastic bounds and find a solution that minimizes $f\left(x\right)$ subject to the non-elastic constraints. This option is useful if there are some ‘soft’ constraints that you would like to ignore if the constraints are infeasible.
$1$	Use a composite objective defined with $\gamma$ determined by the value of ‘Elastic Weight’. This value is intended to be used in conjunction with $\text{‘Elastic Mode'}=2$.
$2$	Include only the elastic variables in the composite objective. The elastics are weighted by $\gamma =1$. This choice minimizes the violations of the elastic variables at the expense of possibly increasing the true objective. This option can be used to find a point that minimizes the sum of the violations of a subset of constraints specified by the input array $helast$.

‘Elastic Weight’float

Default $=1.0$

This defines the value of $\gamma$ in the composite objective in Phase 2 ($\gamma$).

At each iteration of elastic mode, the composite objective is defined to be

$$minimize\sigma f\left(x\right)+\gamma \text{(sum of infeasibilities);}$$

where $\sigma =1$ for ‘Minimize’, $\sigma =-1$ for ‘Maximize’, and $f\left(x\right)$ is the quadratic objective.

Note that the effect of $\gamma$ is not disabled once a feasible point is obtained.

‘Expand Frequency’int

Default $=10000$

This option is part of an anti-cycling procedure (see Miscellaneous) designed to allow progress even on highly degenerate problems.

The strategy is to force a positive step at every iteration, at the expense of violating the constraints by a small amount. Suppose that the value of the option ‘Feasibility Tolerance’ is $\delta$. Over a period of $i$ iterations, the feasibility tolerance actually used by qpconvex2_sparse_solve (i.e., the working feasibility tolerance) increases from $0.5\delta$ to $\delta$ (in steps of $0.5\delta /i$).

Increasing the value of $i$ helps reduce the number of slightly infeasible nonbasic variables (most of which are eliminated during the resetting procedure). However, it also diminishes the freedom to choose a large pivot element (see the description of the option ‘Pivot Tolerance’).

If $i\le 0$, the value $i=99999999$ is used and effectively no anti-cycling procedure is invoked.

‘Factorization Frequency’int

Default $=100\left(LP\right)$ or $50\left(QP\right)$

If $i>0$, at most $i$ basis changes will occur between factorizations of the basis matrix.

For LP problems, the basis factors are usually updated at every iteration. Higher values of $i$ may be more efficient on problems that are extremely sparse and well scaled.

For QP problems, fewer basis updates will occur as the solution is approached. The number of iterations between basis factorizations will, therefore, increase. During these iterations a test is made regularly according to the value of option ‘Check Frequency’ to ensure that the linear constraints $Ax-s=0$ are satisfied. Occasionally, the basis will be refactorized before the limit of $i$ updates is reached. If $i\le 0$, the default value is used.

‘Feasibility Tolerance’float

Default $=max\{{10}^{-6},\sqrt{ϵ}\}$

A feasible problem is one in which all variables satisfy their upper and lower bounds to within the absolute tolerance $r$. (This includes slack variables. Hence, the general constraints are also satisfied to within $r$.)

qpconvex2_sparse_solve attempts to find a feasible solution before optimizing the objective function. If the sum of infeasibilities cannot be reduced to zero, the problem is assumed to be infeasible. Let sInf be the corresponding sum of infeasibilities. If sInf is quite small, it may be appropriate to raise $r$ by a factor of $10$ or $100$. Otherwise, some error in the data should be suspected.

Note that if sInf is not small and you have not asked qpconvex2_sparse_solve to minimize the violations of the elastic variables (i.e., you have not specified $\text{‘Elastic Objective'}=2$), there may be other points that have a significantly smaller sum of infeasibilities. qpconvex2_sparse_solve will not attempt to find the solution that minimizes the sum unless $\text{‘Elastic Objective'}=2$.

If the constraints and variables have been scaled (see the description of the option ‘Scale Option’), then feasibility is defined in terms of the scaled problem (since it is more likely to be meaningful).

‘Infinite Bound Size’float

Default $={10}^{20}$

If $r\ge 0$, $r$ defines the ‘infinite’ bound $\text{infbnd}$ in the definition of the problem constraints. Any upper bound greater than or equal to $\text{infbnd}$ will be regarded as $+\infty$ (and similarly any lower bound less than or equal to $-\text{infbnd}$ will be regarded as $-\infty$). If $r<0$, the default value is used.

‘Iterations Limit’int

Default $=max\{10000,10max\{m,n\}\}$

The value of $i$ specifies the maximum number of iterations allowed before termination. Setting $i=0$ and $\text{‘Print Level'}>0$ means that: the workspace needed to start solving the problem will be computed and printed; and feasibility and optimality will be checked. No iterations will be performed. If $i<0$, the default value is used.

‘LU Density Tolerance’float

Default $=0.6$

The density tolerance $r_1$ is used during $LU$ factorization of the basis matrix. Columns of $L$ and rows of $U$ are formed one at a time, and the remaining rows and columns of the basis are altered appropriately. At any stage, if the density of the remaining matrix exceeds $r_1$, the Markowitz strategy for choosing pivots is terminated. The remaining matrix is factored by a dense $LU$ procedure. Raising the density tolerance towards $1.0$ may give slightly sparser $LU$ factors, with a slight increase in factorization time.

If $r_2>0$, $r_2$ defines the singularity tolerance used to guard against ill-conditioned basis matrices. After $B$ is refactorized, the diagonal elements of $U$ are tested as follows. If $\left|u_{jj}\right|\le r_2$ or $\left|u_{jj}\right|<r_2{max}_i\left|u_{ij}\right|$, the $j$th column of the basis is replaced by the corresponding slack variable. If $r_2\le 0$, the default value is used.

‘LU Singularity Tolerance’float

Default $={ϵ}^{\frac{2}{3}}$

The density tolerance $r_1$ is used during $LU$ factorization of the basis matrix. Columns of $L$ and rows of $U$ are formed one at a time, and the remaining rows and columns of the basis are altered appropriately. At any stage, if the density of the remaining matrix exceeds $r_1$, the Markowitz strategy for choosing pivots is terminated. The remaining matrix is factored by a dense $LU$ procedure. Raising the density tolerance towards $1.0$ may give slightly sparser $LU$ factors, with a slight increase in factorization time.

If $r_2>0$, $r_2$ defines the singularity tolerance used to guard against ill-conditioned basis matrices. After $B$ is refactorized, the diagonal elements of $U$ are tested as follows. If $\left|u_{jj}\right|\le r_2$ or $\left|u_{jj}\right|<r_2{max}_i\left|u_{ij}\right|$, the $j$th column of the basis is replaced by the corresponding slack variable. If $r_2\le 0$, the default value is used.

‘LU Factor Tolerance’float

Default $=100.0$

The values of $r_1$ and $r_2$ affect the stability and sparsity of the basis factorization $B=LU$, during refactorization and updates respectively. The lower triangular matrix $L$ is a product of matrices of the form

$$\begin{array}{c}\left(\begin{array}{cc}1& \\ \mu & 1\end{array}\right)\end{array}$$

where the multipliers $\mu$ will satisfy $\left|\mu \right|\le r_i$. The default values of $r_1$ and $r_2$ usually strike a good compromise between stability and sparsity. They must satisfy $r_1$, $r_2\ge 1.0$.

For large and relatively dense problems, $r_1=10.0$ or $5.0$ (say) may give a useful improvement in stability without impairing sparsity to a serious degree.

For certain very regular structures (e.g., band matrices) it may be necessary to reduce $r_1\text{and/or}{r}_2$ in order to achieve stability. For example, if the columns of $A$ include a sub-matrix of the form

$$\begin{array}{c}\left(\begin{array}{cccccc}4& -1& & & & \\ -1& 4& -1& & & \\ & -1& 4& -1& & \\ & & \dots & \dots & \dots & \\ & & & -1& 4& -1\\ & & & & -1& 4\end{array}\right)\text{,}\end{array}$$

one should set both $r_1$ and $r_2$ to values in the range $1.0\le r_i<4.0$.

‘LU Update Tolerance’float

Default $=10.0$

The values of $r_1$ and $r_2$ affect the stability and sparsity of the basis factorization $B=LU$, during refactorization and updates respectively. The lower triangular matrix $L$ is a product of matrices of the form

$$\begin{array}{c}\left(\begin{array}{cc}1& \\ \mu & 1\end{array}\right)\end{array}$$

where the multipliers $\mu$ will satisfy $\left|\mu \right|\le r_i$. The default values of $r_1$ and $r_2$ usually strike a good compromise between stability and sparsity. They must satisfy $r_1$, $r_2\ge 1.0$.

For large and relatively dense problems, $r_1=10.0$ or $5.0$ (say) may give a useful improvement in stability without impairing sparsity to a serious degree.

For certain very regular structures (e.g., band matrices) it may be necessary to reduce $r_1\text{and/or}{r}_2$ in order to achieve stability. For example, if the columns of $A$ include a sub-matrix of the form

$$\begin{array}{c}\left(\begin{array}{cccccc}4& -1& & & & \\ -1& 4& -1& & & \\ & -1& 4& -1& & \\ & & \dots & \dots & \dots & \\ & & & -1& 4& -1\\ & & & & -1& 4\end{array}\right)\text{,}\end{array}$$

one should set both $r_1$ and $r_2$ to values in the range $1.0\le r_i<4.0$.

‘LU Partial Pivoting’valueless

Default

The $LU$ factorization implements a Markowitz-type search for pivots that locally minimize the fill-in subject to a threshold pivoting stability criterion. The default option is to use threshold partial pivoting. The options ‘LU Complete Pivoting’ and ‘LU Rook Pivoting’ are more expensive but more stable and better at revealing rank, as long as the ‘LU Factor Tolerance’ is not too large (say $<2.0$).

‘LU Complete Pivoting’valueless

The $LU$ factorization implements a Markowitz-type search for pivots that locally minimize the fill-in subject to a threshold pivoting stability criterion. The default option is to use threshold partial pivoting. The options ‘LU Complete Pivoting’ and ‘LU Rook Pivoting’ are more expensive but more stable and better at revealing rank, as long as the ‘LU Factor Tolerance’ is not too large (say $<2.0$).

‘LU Rook Pivoting’valueless

The $LU$ factorization implements a Markowitz-type search for pivots that locally minimize the fill-in subject to a threshold pivoting stability criterion. The default option is to use threshold partial pivoting. The options ‘LU Complete Pivoting’ and ‘LU Rook Pivoting’ are more expensive but more stable and better at revealing rank, as long as the ‘LU Factor Tolerance’ is not too large (say $<2.0$).

‘Minimize’valueless

Default

This option specifies the required direction of the optimization. It applies to both linear and nonlinear terms (if any) in the objective function. Note that if two problems are the same except that one minimizes $f\left(x\right)$ and the other maximizes $-f\left(x\right)$, their solutions will be the same but the signs of the dual variables ${\pi }_i$ and the reduced gradients $d_j$ (see Main Iteration) will be reversed.

The option ‘Feasible Point’ means ‘ignore the objective function, while finding a feasible point for the linear constraints’. It can be used to check that the constraints are feasible without altering the call to qpconvex2_sparse_solve.

‘Maximize’valueless

This option specifies the required direction of the optimization. It applies to both linear and nonlinear terms (if any) in the objective function. Note that if two problems are the same except that one minimizes $f\left(x\right)$ and the other maximizes $-f\left(x\right)$, their solutions will be the same but the signs of the dual variables ${\pi }_i$ and the reduced gradients $d_j$ (see Main Iteration) will be reversed.

The option ‘Feasible Point’ means ‘ignore the objective function, while finding a feasible point for the linear constraints’. It can be used to check that the constraints are feasible without altering the call to qpconvex2_sparse_solve.

‘Feasible Point’valueless

This option specifies the required direction of the optimization. It applies to both linear and nonlinear terms (if any) in the objective function. Note that if two problems are the same except that one minimizes $f\left(x\right)$ and the other maximizes $-f\left(x\right)$, their solutions will be the same but the signs of the dual variables ${\pi }_i$ and the reduced gradients $d_j$ (see Main Iteration) will be reversed.

The option ‘Feasible Point’ means ‘ignore the objective function, while finding a feasible point for the linear constraints’. It can be used to check that the constraints are feasible without altering the call to qpconvex2_sparse_solve.

‘New Basis File’int

Default $=0$

Options ‘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$, a basis map will be saved on file $i_1$ every $i_3$th iteration, where $i_3$ is the ‘Save Frequency’. 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$ is intended as a safeguard against losing the results of a long run. Suppose that a ‘New Basis File’ is being saved every $100$ (‘Save Frequency’) iterations, and that qpconvex2_sparse_solve is about to save such a basis at iteration $2000$. It is conceivable that the run may be interrupted during the next few milliseconds (in the middle of the save). In this case the Basis file will be corrupted and the run will have been essentially wasted.

To eliminate this risk, both a ‘New Basis File’ and a ‘Backup Basis File’ may be specified.

The current basis will then be saved every $100$ iterations, first on ‘New Basis File’ and then immediately on ‘Backup Basis File’. If the run is interrupted at iteration $2000$ during the save on ‘New Basis File’, there will still be a usable basis on ‘Backup Basis File’ (corresponding to iteration $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$ (or if the iteration limit is $2050$), the final basis on ‘New Basis File’ will correspond to iteration $2050$, but the last basis saved on ‘Backup Basis File’ will be the one for iteration $2000$.

A full description of information recorded in ‘New Basis File’ and ‘Backup Basis File’ is given in Gill et al. (2005a).

‘Backup Basis File’int

Default $=0$

Options ‘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$, a basis map will be saved on file $i_1$ every $i_3$th iteration, where $i_3$ is the ‘Save Frequency’. 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$ is intended as a safeguard against losing the results of a long run. Suppose that a ‘New Basis File’ is being saved every $100$ (‘Save Frequency’) iterations, and that qpconvex2_sparse_solve is about to save such a basis at iteration $2000$. It is conceivable that the run may be interrupted during the next few milliseconds (in the middle of the save). In this case the Basis file will be corrupted and the run will have been essentially wasted.

To eliminate this risk, both a ‘New Basis File’ and a ‘Backup Basis File’ may be specified.

The current basis will then be saved every $100$ iterations, first on ‘New Basis File’ and then immediately on ‘Backup Basis File’. If the run is interrupted at iteration $2000$ during the save on ‘New Basis File’, there will still be a usable basis on ‘Backup Basis File’ (corresponding to iteration $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$ (or if the iteration limit is $2050$), the final basis on ‘New Basis File’ will correspond to iteration $2050$, but the last basis saved on ‘Backup Basis File’ will be the one for iteration $2000$.

A full description of information recorded in ‘New Basis File’ and ‘Backup Basis File’ is given in Gill et al. (2005a).

‘Save Frequency’int

Default $=100$

Options ‘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$, a basis map will be saved on file $i_1$ every $i_3$th iteration, where $i_3$ is the ‘Save Frequency’. 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$ is intended as a safeguard against losing the results of a long run. Suppose that a ‘New Basis File’ is being saved every $100$ (‘Save Frequency’) iterations, and that qpconvex2_sparse_solve is about to save such a basis at iteration $2000$. It is conceivable that the run may be interrupted during the next few milliseconds (in the middle of the save). In this case the Basis file will be corrupted and the run will have been essentially wasted.

To eliminate this risk, both a ‘New Basis File’ and a ‘Backup Basis File’ may be specified.

The current basis will then be saved every $100$ iterations, first on ‘New Basis File’ and then immediately on ‘Backup Basis File’. If the run is interrupted at iteration $2000$ during the save on ‘New Basis File’, there will still be a usable basis on ‘Backup Basis File’ (corresponding to iteration $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$ (or if the iteration limit is $2050$), the final basis on ‘New Basis File’ will correspond to iteration $2050$, but the last basis saved on ‘Backup Basis File’ will be the one for iteration $2000$.

A full description of information recorded in ‘New Basis File’ and ‘Backup Basis File’ is given in Gill et al. (2005a).

‘Nolist’valueless

Default

Option ‘List’ enables printing of each option specification as it is supplied. ‘Nolist’ suppresses this printing.

‘List’valueless

Option ‘List’ enables printing of each option specification as it is supplied. ‘Nolist’ suppresses this printing.

‘Old Basis File’int

Default $=0$

If $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.

‘Optimality Tolerance’float

Default $=max\{{10}^{-6},\sqrt{ϵ}\}$

This is used to judge the size of the reduced gradients $d_j=g_j-a_j^T\pi$, where $g_j$ is the $j$th component of the gradient, $a_j$ is the associated column of the constraint matrix $\left(\begin{array}{cc}A& -I\end{array}\right)$, and $\pi$ is the set of dual variables.

By construction, the reduced gradients for basic variables are always zero. The problem will be declared optimal if the reduced gradients for nonbasic variables at their lower or upper bounds satisfy

$$d_j/\parallel \pi \parallel \ge -r\text{or}{d}_j/\parallel \pi \parallel \le r$$

respectively, and if $\left|d_j\right|/\parallel \pi \parallel \le r$ for superbasic variables.

In the above tests, $\parallel \pi \parallel$ is a measure of the size of the dual variables. It is included to make the tests independent of a scale factor on the objective function. The quantity $\parallel \pi \parallel$ actually used is defined by

$$\parallel \pi \parallel =max(\sigma /\sqrt{m},1)\text{, where}\sigma =\sum _{i=1}^m\left|{\pi }_i\right|\text{,}$$

so that only large scale factors are allowed for.

If the objective is scaled down to be very small, the optimality test reduces to comparing $d_j$ against $0.01r$.

‘Partial Price’int

Default $=10\left(LP\right)$ or $1\left(QP\right)$

This option is recommended for large FP or LP problems that have significantly more variables than constraints (i.e., $n\gg m$). It reduces the work required for each pricing operation (i.e., when a nonbasic variable is selected to enter the basis). If $i=1$, all columns of the constraint matrix $\left(\begin{array}{cc}A& -I\end{array}\right)$ are searched. If $i>1$, $A$ and $I$ are partitioned to give $i$ roughly equal segments $A_{\text{j}},I_{\text{j}}$, for $\text{j}=1,2,\dots ,i$ (modulo $i$). If the previous pricing search was successful on $A_{j-1},I_{j-1}$, the next search begins on the segments $A_j$ and $I_j$. 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 enter the basis. If nothing is found, the search continues on the next segments $A_{j+1},I_{j+1}$, and so on. If $i\le 0$, the default value is used.

‘Pivot Tolerance’float

Default $={ϵ}^{\frac{2}{3}}$

Broadly speaking, the pivot tolerance is used to prevent columns entering the basis if they would cause the basis to become almost singular.

When $x$ changes to $x+\alpha p$ for some search direction $p$, a ‘ratio test’ determines which component of $x$ reaches an upper or lower bound first. The corresponding element of $p$ is called the pivot element. Elements of $p$ are ignored (and, therefore, cannot be pivot elements) if they are smaller than the pivot tolerance $r$.

It is common for two or more variables to reach a bound at essentially the same time. In such cases, the option ‘Feasibility Tolerance’ (say $t$) provides some freedom to maximize the pivot element and thereby improve numerical stability. Excessively small values of $t$ should, therefore, not be specified. To a lesser extent, the option ‘Expand Frequency’ (say $f$) also provides some freedom to maximize the pivot element. Excessively large values of $f$ should, therefore, not be specified.

‘Print File’int

Default $=0$

If $i>0$, the following information is output to $i$ during the solution of each problem:

• a listing of the options;

• some statistics about the problem;

• the amount of storage available for the $LU$ factorization of the basis matrix;

• notes about the initial basis resulting from a Crash procedure or a Basis file;

• the iteration log;

• basis factorization statistics;

• the exit $\text{errno}$ condition and some statistics about the solution obtained;

• the printed solution, if requested.

The last four items are described in Further Comments and Monitoring Information. Further brief output may be directed to the ‘Summary File’.

‘Print Frequency’int

Default $=100$

If $i>0$, one line of the iteration log will be printed every $i$th iteration. A value such as $i=10$ is suggested for those interested only in the final solution. If $i\le 0$, the value of $i=99999999$ is used and effectively no checks are made.

‘Print Level’int

Default $=1$

This controls the amount of printing produced by qpconvex2_sparse_solve as follows.

$i$	Meaning
0	No output except error messages. If you want to suppress all output, set $\text{‘Print File'}=0$.
$=1$	The set of selected options, problem statistics, summary of the scaling procedure, information about the initial basis resulting from a Crash or a Basis file, a single line of output at each iteration (controlled by the option ‘Print Frequency’), and the exit condition with a summary of the final solution.
$\ge 10$	Basis factorization statistics.

‘Punch File’int

Default $=0$

These files provide compatibility with commercial mathematical programming systems. 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$, the final solution obtained will be output to file $i_1$. For linear programs, this format is compatible with various commercial systems.

If $i_2>0$, the ‘Insert File’ containing basis information will be read. The file will usually have been output previously as a ‘Punch File’. The file will not be accessed if ‘Old Basis File’ is specified.

‘Insert File’int

Default $=0$

These files provide compatibility with commercial mathematical programming systems. 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$, the final solution obtained will be output to file $i_1$. For linear programs, this format is compatible with various commercial systems.

If $i_2>0$, the ‘Insert File’ containing basis information will be read. The file will usually have been output previously as a ‘Punch File’. The file will not be accessed if ‘Old Basis File’ is specified.

‘QPSolver Cholesky’valueless

Default

Specifies the active-set algorithm used to solve the quadratic program in Phase 2 ($\gamma$). ‘QPSolver Cholesky’ holds the full Cholesky factor $R$ of the reduced Hessian $Z^{T}HZ$. As the QP iterations proceed, the dimension of $R$ changes with the number of superbasic variables. If the number of superbasic variables needs to increase beyond the value of ‘Reduced Hessian Dimension’, the reduced Hessian cannot be stored and the solver switches to ‘QPSolver CG’. The Cholesky solver is reactivated if the number of superbasics stabilizes at a value less than ‘Reduced Hessian Dimension’.

‘QPSolver QN’ solves the QP using a quasi-Newton method. In this case, $R$ is the factor of a quasi-Newton approximate Hessian.

‘QPSolver CG’ uses an active-set method similar to ‘QPSolver QN’, but uses the conjugate-gradient method to solve all systems involving the reduced Hessian.

The Cholesky QP solver is the most robust, but may require a significant amount of computation if there are many superbasics.

The quasi-Newton QP solver does not require computation of the exact $R$ at the start of Phase 2 ($\gamma$). It may be appropriate when the number of superbasics is large but relatively few iterations are needed to reach a solution (e.g., if qpconvex2_sparse_solve is called with a Warm Start).

The conjugate-gradient QP solver is appropriate for problems with many degrees of freedom (say, more than $2000$ superbasics).

‘QPSolver CG’valueless

Specifies the active-set algorithm used to solve the quadratic program in Phase 2 ($\gamma$). ‘QPSolver Cholesky’ holds the full Cholesky factor $R$ of the reduced Hessian $Z^{T}HZ$. As the QP iterations proceed, the dimension of $R$ changes with the number of superbasic variables. If the number of superbasic variables needs to increase beyond the value of ‘Reduced Hessian Dimension’, the reduced Hessian cannot be stored and the solver switches to ‘QPSolver CG’. The Cholesky solver is reactivated if the number of superbasics stabilizes at a value less than ‘Reduced Hessian Dimension’.

‘QPSolver QN’ solves the QP using a quasi-Newton method. In this case, $R$ is the factor of a quasi-Newton approximate Hessian.

‘QPSolver CG’ uses an active-set method similar to ‘QPSolver QN’, but uses the conjugate-gradient method to solve all systems involving the reduced Hessian.

The Cholesky QP solver is the most robust, but may require a significant amount of computation if there are many superbasics.

The quasi-Newton QP solver does not require computation of the exact $R$ at the start of Phase 2 ($\gamma$). It may be appropriate when the number of superbasics is large but relatively few iterations are needed to reach a solution (e.g., if qpconvex2_sparse_solve is called with a Warm Start).

The conjugate-gradient QP solver is appropriate for problems with many degrees of freedom (say, more than $2000$ superbasics).

‘QPSolver QN’valueless

Specifies the active-set algorithm used to solve the quadratic program in Phase 2 ($\gamma$). ‘QPSolver Cholesky’ holds the full Cholesky factor $R$ of the reduced Hessian $Z^{T}HZ$. As the QP iterations proceed, the dimension of $R$ changes with the number of superbasic variables. If the number of superbasic variables needs to increase beyond the value of ‘Reduced Hessian Dimension’, the reduced Hessian cannot be stored and the solver switches to ‘QPSolver CG’. The Cholesky solver is reactivated if the number of superbasics stabilizes at a value less than ‘Reduced Hessian Dimension’.

‘QPSolver QN’ solves the QP using a quasi-Newton method. In this case, $R$ is the factor of a quasi-Newton approximate Hessian.

‘QPSolver CG’ uses an active-set method similar to ‘QPSolver QN’, but uses the conjugate-gradient method to solve all systems involving the reduced Hessian.

The Cholesky QP solver is the most robust, but may require a significant amount of computation if there are many superbasics.

The quasi-Newton QP solver does not require computation of the exact $R$ at the start of Phase 2 ($\gamma$). It may be appropriate when the number of superbasics is large but relatively few iterations are needed to reach a solution (e.g., if qpconvex2_sparse_solve is called with a Warm Start).

The conjugate-gradient QP solver is appropriate for problems with many degrees of freedom (say, more than $2000$ superbasics).

‘Reduced Hessian Dimension’int

Default $=1\left(LP\right)\text{or}min(2000,n_H+1,n)\left(QP\right)$

This specifies that an $i\times i$ triangular matrix $R$ (to define the reduced Hessian according to $R^{T}R=Z^{T}HZ$). is to be available for use by the Cholesky QP solver.

‘Scale Option’int

Default $=2$

Three scale options are available as follows:

$i$	Meaning
0	No scaling. This is recommended if it is known that $x$ and the constraint matrix never have very large elements (say, larger than $100$).
1	The constraints and variables are scaled by an iterative procedure that attempts to make the matrix coefficients as close as possible to $1.0$ (see Fourer (1982)). This will sometimes improve the performance of the solution procedures.
2	The constraints and variables are scaled by the iterative procedure. Also, a certain additional scaling is performed that may be helpful if the right-hand side $b$ or the solution $x$ is large. This takes into account columns of $\left(\begin{array}{cc}A& -I\end{array}\right)$ that are fixed or have positive lower bounds or negative upper bounds.

Option ‘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:

$${\rho }_j={max}_j\left|a_{ij}\right|/{min}_i\left|a_{ij}\right|(a_{ij}\ne 0)\text{.}$$

If ${max}_j{\rho }_j$ is less than $r$ times its previous value, another scaling pass is performed to adjust the row and column scales. Raising $r$ from $0.9$ to $0.99$ (say) usually increases the number of scaling passes through $A$. At most $10$ passes are made. The value of $r$ should lie in the range $0<r<1$.

‘Scale Print’ causes the row scales $r\left(i\right)$ and column scales $c\left(j\right)$ to be printed to ‘Print File’, if ‘System Information Yes’ has been specified. The scaled matrix coefficients are ${\overline{a}}_{ij}=a_{ij}c\left(j\right)/r\left(i\right)$, and the scaled bounds on the variables and slacks are ${\overline{l}}_j=l_j/c\left(j\right)$, ${\overline{u}}_j=u_j/c\left(j\right)$, where $c\left(j\right)=r(j-n)$ if $j>n$.

‘Scale Tolerance’float

Default $=0.9$

Three scale options are available as follows:

$i$	Meaning
0	No scaling. This is recommended if it is known that $x$ and the constraint matrix never have very large elements (say, larger than $100$).
1	The constraints and variables are scaled by an iterative procedure that attempts to make the matrix coefficients as close as possible to $1.0$ (see Fourer (1982)). This will sometimes improve the performance of the solution procedures.
2	The constraints and variables are scaled by the iterative procedure. Also, a certain additional scaling is performed that may be helpful if the right-hand side $b$ or the solution $x$ is large. This takes into account columns of $\left(\begin{array}{cc}A& -I\end{array}\right)$ that are fixed or have positive lower bounds or negative upper bounds.

Option ‘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:

$${\rho }_j={max}_j\left|a_{ij}\right|/{min}_i\left|a_{ij}\right|(a_{ij}\ne 0)\text{.}$$

If ${max}_j{\rho }_j$ is less than $r$ times its previous value, another scaling pass is performed to adjust the row and column scales. Raising $r$ from $0.9$ to $0.99$ (say) usually increases the number of scaling passes through $A$. At most $10$ passes are made. The value of $r$ should lie in the range $0<r<1$.

‘Scale Print’ causes the row scales $r\left(i\right)$ and column scales $c\left(j\right)$ to be printed to ‘Print File’, if ‘System Information Yes’ has been specified. The scaled matrix coefficients are ${\overline{a}}_{ij}=a_{ij}c\left(j\right)/r\left(i\right)$, and the scaled bounds on the variables and slacks are ${\overline{l}}_j=l_j/c\left(j\right)$, ${\overline{u}}_j=u_j/c\left(j\right)$, where $c\left(j\right)=r(j-n)$ if $j>n$.

‘Scale Print’valueless

Three scale options are available as follows:

$i$	Meaning
0	No scaling. This is recommended if it is known that $x$ and the constraint matrix never have very large elements (say, larger than $100$).
1	The constraints and variables are scaled by an iterative procedure that attempts to make the matrix coefficients as close as possible to $1.0$ (see Fourer (1982)). This will sometimes improve the performance of the solution procedures.
2	The constraints and variables are scaled by the iterative procedure. Also, a certain additional scaling is performed that may be helpful if the right-hand side $b$ or the solution $x$ is large. This takes into account columns of $\left(\begin{array}{cc}A& -I\end{array}\right)$ that are fixed or have positive lower bounds or negative upper bounds.

Option ‘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:

$${\rho }_j={max}_j\left|a_{ij}\right|/{min}_i\left|a_{ij}\right|(a_{ij}\ne 0)\text{.}$$

If ${max}_j{\rho }_j$ is less than $r$ times its previous value, another scaling pass is performed to adjust the row and column scales. Raising $r$ from $0.9$ to $0.99$ (say) usually increases the number of scaling passes through $A$. At most $10$ passes are made. The value of $r$ should lie in the range $0<r<1$.

‘Scale Print’ causes the row scales $r\left(i\right)$ and column scales $c\left(j\right)$ to be printed to ‘Print File’, if ‘System Information Yes’ has been specified. The scaled matrix coefficients are ${\overline{a}}_{ij}=a_{ij}c\left(j\right)/r\left(i\right)$, and the scaled bounds on the variables and slacks are ${\overline{l}}_j=l_j/c\left(j\right)$, ${\overline{u}}_j=u_j/c\left(j\right)$, where $c\left(j\right)=r(j-n)$ if $j>n$.

‘Solution Yes’valueless

Default

This option determines if the final obtained solution is to be output to the ‘Print File’. Note that the ‘Solution File’ option operates independently.

‘Solution No’valueless

This option determines if the final obtained solution is to be output to the ‘Print File’. Note that the ‘Solution File’ option operates independently.

‘Solution File’int

Default $=0$

If $i>0$, the final solution will be output to file $i$ (whether optimal or not).

To see more significant digits in the printed solution, it will sometimes be useful to make $i$ refer to the system ‘Print File’.

‘Summary File’int

Default $=0$

If $i_1>0$, the ‘Summary File’ is output to file $i_1$, including a line of the iteration log every $i_2$th iteration. In an interactive environment, it is useful to direct this output to the terminal, to allow a run to be monitored online. (If something looks wrong, the run can be manually terminated.) Further details are given in Monitoring Information. If $i_2\le 0$, the value of $i_2=99999999$ is used and effectively no checks are made.

‘Summary Frequency’int

Default $=100$

If $i_1>0$, the ‘Summary File’ is output to file $i_1$, including a line of the iteration log every $i_2$th iteration. In an interactive environment, it is useful to direct this output to the terminal, to allow a run to be monitored online. (If something looks wrong, the run can be manually terminated.) Further details are given in Monitoring Information. If $i_2\le 0$, the value of $i_2=99999999$ is used and effectively no checks are made.

‘Superbasics Limit’int

Default $=1\left(LP\right)\text{or}min\{n_H+1,n\}\left(QP\right)$

This places a limit on the storage allocated for superbasic variables. Ideally, $i$ should be set slightly larger than the ‘number of degrees of freedom’ expected at an optimal solution.

For linear programs, an optimum is normally a basic solution with no degrees of freedom. (The number of variables lying strictly between their bounds is no more than $m$, the number of general constraints.) The default value of $i$ is, therefore, $1$.

For quadratic problems, the number of degrees of freedom is often called the ‘number of independent variables’. Normally, $i$ need not be greater than $n_H+1$, where $n_H$ is the number of leading nonzero columns of $H$. For many problems, $i$ may be considerably smaller than $n_H$. This will save storage if $n_H$ is very large.

‘Suppress Parameters’valueless

Normally qpconvex2_sparse_solve prints the options file as it is being read, and then prints a complete list of the available keywords and their final values. The option ‘Suppress Parameters’ tells qpconvex2_sparse_solve not to print the full list.

‘System Information No’valueless

Default

This option prints additional information on the progress of major and minor iterations, and Crash statistics. See Monitoring Information.

‘System Information Yes’valueless

This option prints additional information on the progress of major and minor iterations, and Crash statistics. See Monitoring Information.

‘Timing Level’int

Default $=0$

If $i>0$, some timing information will be output to the Print file, if $\text{‘Print File'}>0$.

‘Unbounded Step Size’float

Default $=\text{infbnd}$

If $r>0$, $r$ specifies the magnitude of the change in variables that will be considered a step to an unbounded solution. (Note that an unbounded solution can occur only when the Hessian is not positive definite.) If the change in $x$ during an iteration would exceed the value of $r$, the objective function is considered to be unbounded below in the feasible region. If $r\le 0$, the default value is used. See ‘Infinite Bound Size’ for the definition of $\text{infbnd}$.

Raises

NagValueError

(errno $1$)

The initialization function qpconvex2_sparse_init() has not been called.

(errno $2$)

On entry, $start=⟨value⟩$.

Constraint: $start=\text{'B'}$, $\text{'C'}$ or $\text{'W'}$.

(errno $2$)

On entry, $\text{ne}=⟨value⟩$, $n=⟨value⟩$ and $m=⟨value⟩$.

Constraint: $1\le \text{ne}\le n\times m$.

(errno $2$)

On entry, $\text{lenc}=⟨value⟩$ and $n=⟨value⟩$.

Constraint: $0\le \text{lenc}\le n$.

(errno $2$)

An error has occurred in the basis package, perhaps indicating incorrect setup of arrays $inda$ and $loca$. Set the option ‘Print File’ and examine the output carefully for further information.

(errno $2$)

On entry, $ncolh=⟨value⟩$ and $n=⟨value⟩$.

Constraint: $0\le ncolh\le n$.

(errno $2$)

On entry, $\text{nname}=⟨value⟩$, $n=⟨value⟩$ and $m=⟨value⟩$.

Constraint: $\text{nname}=1$ or $n+m$.

(errno $2$)

On entry, $iobj=⟨value⟩$ and $m=⟨value⟩$.

Constraint: $0\le iobj\le m$.

(errno $2$)

On entry, $loca\left[0\right]=⟨value⟩$, $loca[⟨value⟩]=⟨value⟩$, $\text{ne}=⟨value⟩$.

Constraint: $loca\left[0\right]=1$ or $loca[⟨value⟩]=\text{ne}+1$.

(errno $2$)

On entry, row index $⟨value⟩$ in $inda[⟨value⟩]$ is outside the range $1$ to $m=⟨value⟩$.

(errno $2$)

On entry, $\text{ne}$ is not equal to the number of nonzeros in $acol$. $\text{ne}=⟨value⟩$, nonzeros in $acol=⟨value⟩$.

(errno $2$)

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

(errno $2$)

On entry, bounds for $⟨value⟩$ are inconsistent. $bl=⟨value⟩$ and $bu=⟨value⟩$.

(errno $2$)

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

(errno $2$)

On entry, bounds for $⟨value⟩$$⟨value⟩$ are inconsistent. $bl=⟨value⟩$ and $bu=⟨value⟩$.

(errno $2$)

Basis file dimensions do not match this problem.

(errno $2$)

On entry, $m=⟨value⟩$.

Constraint: $m\ge ⟨value⟩$.

(errno $2$)

On entry, $n=⟨value⟩$.

Constraint: $n\ge ⟨value⟩$.

(errno $12$)

Internal memory allocation failed when attempting to obtain workspace sizes $⟨value⟩$, $⟨value⟩$ and $⟨value⟩$. Please contact NAG.

(errno $13$)

Internal memory allocation was insufficient. Please contact NAG.

(errno $14$)

An error has occurred in the basis package, perhaps indicating incorrect setup of arrays $inda$ and $loca$. Set the option ‘Print File’ and examine the output carefully for further information.

(errno $15$)

An unexpected error has occurred. Set the option ‘Print File’ and examine the output carefully for further information.

Warns

NagAlgorithmicWarning

(errno $4$)

Weak solution found – the solution is not unique.

(errno $5$)

The linear constraints appear to be infeasible.

(errno $5$)

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

(errno $5$)

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

(errno $5$)

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

(errno $6$)

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

(errno $6$)

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

NagAlgorithmicMajorWarning

(errno $3$)

The requested accuracy could not be achieved.

(errno $7$)

Iteration limit reached.

(errno $7$)

Major iteration limit reached.

(errno $8$)

The value of the option ‘Superbasics Limit’ is too small.

(errno $9$)

The basis is singular after several attempts to factorize it (and add slacks where necessary).

(errno $10$)

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

(errno $11$)

Error in $qphx$: the QP Hessian is indefinite.

Notes

qpconvex2_sparse_solve is designed to solve large-scale linear or quadratic programming problems of the form:

$$\begin{array}{c}{minimize}_{x\in R^n}f\left(x\right)\text{subject to}l\le \left(\begin{array}{c}x\\ Ax\end{array}\right)\le u\text{,}\end{array}$$

where $x$ is an $n$-vector of variables, $l$ and $u$ are constant lower and upper bounds, $A$ is an $m\times n$ sparse matrix and $f\left(x\right)$ is a linear or quadratic objective function that may be specified in a variety of ways, depending upon the particular problem being solved. The option ‘Maximize’ may be used to specify a problem in which $f\left(x\right)$ is maximized instead of minimized.

Upper and lower bounds are specified for all variables and constraints. This form allows full generality in specifying various types of constraint. In particular, the $j$th constraint may be defined as an equality by setting $l_j=u_j$. If certain bounds are not present, the associated elements of $l$ or $u$ may be set to special values that are treated as $-\infty$ or $+\infty$.

The possible forms for the function $f\left(x\right)$ are summarised in Table [label omitted]. The most general form for $f\left(x\right)$ is

$$f\left(x\right)=q+c^{T}x+\frac{1}{2}{x}^{T}Hx=q+\sum _{j=1}^n{c}_j{x}_j+\frac{1}{2}\sum _{i=1}^n\sum _{j=1}^n{x}_i{H}_{ij}{x}_j$$

where $q$ is a constant, $c$ is a constant $n$-vector and $H$ is a constant symmetric $n\times n$ matrix with elements $\left\{H_{ij}\right\}$. In this form, $f$ is a quadratic function of $x$ and (1) is known as a quadratic program (QP). qpconvex2_sparse_solve is suitable for all convex quadratic programs. The defining feature of a convex QP is that the matrix $H$ must be positive semidefinite, i.e., it must satisfy $x^{T}Hx\ge 0$ for all $x$. If not, $f\left(x\right)$ is nonconvex and qpconvex2_sparse_solve will terminate with the error indicator $errno$ = 11. If $f\left(x\right)$ is nonconvex it may be more appropriate to call handle_solve_ssqp() instead.

Problem type	Objective function $f\left(x\right)$	Hessian matrix $H$
FP	Not applicable	$q=c=H=0$
LP	$q+c^{T}x$	$H=0$
QP	$q+c^{T}x+\frac{1}{2}{x}^{T}Hx$	Symmetric positive semidefinite

If $H=0$, then $f\left(x\right)=q+c^{T}x$ and the problem is known as a linear program (LP). In this case, rather than defining an $H$ with zero elements, you can define $H$ to have no columns by setting $ncolh=0$ (see Parameters).

If $H=0$, $q=0$, and $c=0$, there is no objective function and the problem is a feasible point problem (FP), which is equivalent to finding a point that satisfies the constraints on $x$. In the situation where no feasible point exists, several options are available for finding a point that minimizes the constraint violations (see the description of the option ‘Elastic Mode’).

qpconvex2_sparse_solve is suitable for large LPs and QPs in which the matrix $A$ is sparse, i.e., when the number of zero elements is sufficiently large that it is worthwhile using algorithms which avoid computations and storage involving zero elements. The matrix $A$ is input to qpconvex2_sparse_solve by means of the three array arguments $acol$, $inda$ and $loca$. This allows you to specify the pattern of nonzero elements in $A$.

qpconvex2_sparse_solve exploits structure in $H$ by requiring $H$ to be defined implicitly in a function that computes the product $Hx$ for any given vector $x$. In many cases, the product $Hx$ can be computed very efficiently for any given $x$, e.g., $H$ may be a sparse matrix, or a sum of matrices of rank-one.

For problems in which $A$ can be treated as a dense matrix, it is usually more efficient to use lp_solve(), lsq_lincon_solve() or qp_dense_solve().

There is considerable flexibility allowed in the definition of $f\left(x\right)$ in Table [label omitted]. The vector $c$ defining the linear term $c^{T}x$ can be input in three ways: as a sparse row of $A$; as an explicit dense vector $c$; or as both a sparse row and an explicit vector (in which case, $c^{T}x$ will be the sum of two linear terms). When stored in $A$, $c$ is the $iobj$th row of $A$, which is known as the objective row. The objective row must always be a free row of $A$ in the sense that its lower and upper bounds must be $-\infty$ and $+\infty$. Storing $c$ as part of $A$ is recommended if $c$ is a sparse vector. Storing $c$ as an explicit vector is recommended for a sequence of problems, each with a different objective (see arguments $c$ and $\text{lenc}$).

The upper and lower bounds on the $m$ elements of $Ax$ are said to define the general constraints of the problem. Internally, qpconvex2_sparse_solve converts the general constraints to equalities by introducing a set of slack variables $s$, where $s={(s_1,s_2,\dots ,s_m)}^T$. For example, the linear constraint $5\le 2x_1+3x_2\le +\infty$ is replaced by $2x_1+3x_2-s_1=0$, together with the bounded slack $5\le s_1\le +\infty$. The problem defined by (1) can, therefore, be re-written in the following equivalent form:

$$\begin{array}{c}{minimize}_{x\in R^n,s\in R^m}f\left(x\right)\text{subject to}Ax-s=0\text{,}l\le \left(\begin{array}{c}x\\ s\end{array}\right)\le u\text{.}\end{array}$$

Since the slack variables $s$ are subject to the same upper and lower bounds as the elements of $Ax$, the bounds on $x$ and $Ax$ can simply be thought of as bounds on the combined vector $(x,s)$. (In order to indicate their special role in QP problems, the original variables $x$ are sometimes known as ‘column variables’, and the slack variables $s$ are known as ‘row variables’.)

Each LP or QP problem is solved using a two-phase iterative procedure (in which the general constraints are satisfied throughout): a feasibility phase (Phase 1), in which the sum of infeasibilities with respect to the bounds on $x$ and $s$ is minimized to find a feasible point that satisfies all constraints within a specified feasibility tolerance; and an optimality phase (Phase 2), in which $f\left(x\right)$ is minimized (or maximized) by constructing a sequence of iterates that lies within the feasible region.

Phase 1 involves solving a linear program of the form

Phase 1
	${minimize}_{x,s,v,w}{\sum }_{j=1}^{n+m}\left(v_j+w_j\right)$
	$\text{subject to}Ax-s=0\text{,}l\le \left(\begin{array}{c}x\\ s\end{array}\right)-v+w\le u\text{,}v\ge 0\text{,}w\ge 0$

which is equivalent to minimizing the sum of the constraint violations. If the constraints are feasible (i.e., at least one feasible point exists), eventually a point will be found at which both $v$ and $w$ are zero. Then the associated value of $(x,s)$ satisfies the original constraints and is used as the starting point for the Phase 2 iterations for minimizing $f\left(x\right)$.

If the constraints are infeasible (i.e., $v\ne 0$ or $w\ne 0$ at the end of Phase 1), no solution exists for (1) and you have the option of either terminating or continuing in so-called elastic mode (see the discussion of the option ‘Elastic Mode’). In elastic mode, a ‘relaxed’ or ‘perturbed’ problem is solved in which $f\left(x\right)$ is minimized while allowing some of the bounds to become ‘elastic’, i.e., to change from their specified values. 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. You are able to assign which bounds will become elastic if elastic mode is ever started (see the argument $helast$ in Parameters).

To make the relaxed problem meaningful, qpconvex2_sparse_solve minimizes $f\left(x\right)$ while (in some sense) finding the ‘smallest’ violation of the elastic variables. In the situation where all the variables are elastic, the relaxed problem has the form

Phase 2 ($\gamma$)
	${minimize}_{x,s,v,w}f\left(x\right)+\gamma {\sum }_{j=1}^{n+m}\left(v_j+w_j\right)$
	$\text{subject to}Ax-s=0\text{,}l\le \left(\begin{array}{c}x\\ s\end{array}\right)-v+w\le u\text{,}v\ge 0\text{,}w\ge 0$,

where $\gamma$ is a non-negative argument known as the elastic weight (see the description of the option ‘Elastic Weight’), and $f\left(x\right)+\gamma {\sum }_j(v_j+w_j)$ is called the composite objective. In the more general situation where only a subset of the bounds are elastic, the $v$’s and $w$’s for the non-elastic bounds are fixed at zero.

The elastic weight can be chosen to make the composite objective behave like the original objective $f\left(x\right)$, the sum of infeasibilities, or anything in-between. If $\gamma =0$, qpconvex2_sparse_solve will attempt to minimize $f$ subject to the (true) upper and lower bounds on the non-elastic variables (and declare the problem infeasible if the non-elastic variables cannot be made feasible).

At the other extreme, choosing $\gamma$ sufficiently large will have the effect of minimizing the sum of the violations of the elastic variables subject to the original constraints on the non-elastic variables. Choosing a large value of the elastic weight is useful for defining a ‘least-infeasible’ point for an infeasible problem.

In Phase 1 and elastic mode, all calculations involving $v$ and $w$ are done implicitly in the sense that an elastic variable $x_j$ is allowed to violate its lower bound (say) and an explicit value of $v$ can be recovered as $v_j=l_j-x_j$.

A constraint is said to be active or binding at $x$ if the associated element of either $x$ or $Ax$ is equal to one of its upper or lower bounds. Since an active constraint in $Ax$ has its associated slack variable at a bound, the status of both simple and general upper and lower bounds can be conveniently described in terms of the status of the variables $(x,s)$. A variable is said to be nonbasic if it is temporarily fixed at its upper or lower bound. It follows that regarding a general constraint as being active is equivalent to thinking of its associated slack as being nonbasic.

At each iteration of an active-set method, the constraints $Ax-s=0$ are (conceptually) partitioned into the form

$$B{x}_B+S{x}_S+N{x}_N=0\text{,}$$

where $x_N$ consists of the nonbasic elements of $(x,s)$ and the basis matrix $B$ is square and nonsingular. The elements of $x_B$ and $x_S$ are called the basic and superbasic variables respectively; with $x_N$ they are a permutation of the elements of $x$ and $s$. At a QP solution, the basic and superbasic variables will lie somewhere between their upper or lower bounds, while the nonbasic variables will be equal to one of their bounds. At each iteration, $x_S$ is regarded as a set of independent variables that are free to move in any desired direction, namely one that will improve the value of the objective function (or sum of infeasibilities). The basic variables are then adjusted in order to ensure that $(x,s)$ continues to satisfy $Ax-s=0$. The number of superbasic variables ($n_S$ say), therefore, indicates the number of degrees of freedom remaining after the constraints have been satisfied. In broad terms, $n_S$ is a measure of how nonlinear the problem is. In particular, $n_S$ will always be zero for FP and LP problems.

If it appears that no improvement can be made with the current definition of $B$, $S$ and $N$, a nonbasic variable is selected to be added to $S$, and the process is repeated with the value of $n_S$ increased by one. At all stages, if a basic or superbasic variable encounters one of its bounds, the variable is made nonbasic and the value of $n_S$ is decreased by one.

Associated with each of the $m$ equality constraints $Ax-s=0$ is a dual variable ${\pi }_i$. Similarly, each variable in $(x,s)$ has an associated reduced gradient $d_j$ (also known as a reduced cost). The reduced gradients for the variables $x$ are the quantities $g-A^T\pi$, where $g$ is the gradient of the QP objective function, and the reduced gradients for the slack variables $s$ are the dual variables $\pi$. The QP subproblem is optimal if $d_j\ge 0$ for all nonbasic variables at their lower bounds, $d_j\le 0$ for all nonbasic variables at their upper bounds and $d_j=0$ for all superbasic variables. In practice, an approximate QP solution is found by slightly relaxing these conditions on $d_j$ (see the description of the option ‘Optimality Tolerance’).

The process of computing and comparing reduced gradients is known as pricing (a term first introduced in the context of the simplex method for linear programming). To ‘price’ a nonbasic variable $x_j$ means that the reduced gradient $d_j$ associated with the relevant active upper or lower bound on $x_j$ is computed via the formula $d_j=g_j-a_j^T\pi$, where $a_j$ is the $j$th column of $\left(\begin{array}{cc}A& -I\end{array}\right)$. (The variable selected by such a process and the corresponding value of $d_j$ (i.e., its reduced gradient) are the quantities +SBS and dj in the monitoring file output; see Further Comments.) If $A$ has significantly more columns than rows (i.e., $n\gg m$), pricing can be computationally expensive. In this case, a strategy known as partial pricing can be used to compute and compare only a subset of the $d_j$s.

qpconvex2_sparse_solve is based on SQOPT, which is part of the SNOPT package described in Gill et al. (2005a). It uses stable numerical methods throughout and includes a reliable basis package (for maintaining sparse $LU$ factors of the basis matrix $B$), a practical anti-degeneracy procedure, efficient handling of linear constraints and bounds on the variables (by an active-set strategy), as well as automatic scaling of the constraints. Further details can be found in Algorithmic Details.

References

Fourer, R, 1982, Solving staircase linear programs by the simplex method, Math. Programming (23), 274–313

Gill, P E and Murray, W, 1978, Numerically stable methods for quadratic programming, Math. Programming (14), 349–372

Gill, P E, Murray, W and Saunders, M A, 1995, User’s guide for QPOPT 1.0: a Fortran package for quadratic programming, Report SOL 95-4, Department of Operations Research, Stanford University

Gill, P E, Murray, W and Saunders, M A, 2005, Users’ guide for SQOPT 7: a Fortran package for large-scale linear and quadratic programming, Report NA 05-1, Department of Mathematics, University of California, San Diego, https://www.ccom.ucsd.edu/~peg/papers/sqdoc7.pdf

Gill, P E, Murray, W and Saunders, M A, 2005, Users’ guide for SNOPT 7.1: a Fortran package for large-scale linear nonlinear programming, Report NA 05-2, Department of Mathematics, University of California, San Diego, https://www.ccom.ucsd.edu/~peg/papers/sndoc7.pdf

Gill, P E, Murray, W, Saunders, M A and Wright, M H, 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, 1989, A practical anti-cycling procedure for linearly constrained optimization, Math. Programming (45), 437–474

Gill, P E, Murray, W, Saunders, M A and Wright, M H, 1991, Inertia-controlling methods for general quadratic programming, SIAM Rev. (33), 1–36

Hall, J A J and McKinnon, K I M, 1996, The simplest examples where the simplex method cycles and conditions where EXPAND fails to prevent cycling, Report MS, 96–100, Department of Mathematics and Statistics, University of Edinburgh

See also

naginterfaces.library.examples.opt.qpconvex2_sparse_solve_ex.main()