# 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)[source]

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.

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

https://www.nag.com/numeric/nl/nagdoc_28.5/flhtml/e04/e04nqf.html

Parameters
startstr, length 1

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

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’.

Is the same as but is more meaningful when a Basis file is given.

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

mint

, the number of general linear constraints (or slacks). This is the number of rows in the linear constraint matrix , including the free row (if any; see ). Note that 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 , and ).

ncolhint

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

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

iobjint

If , row of is a free row containing the nonzero elements of the vector appearing in the linear objective term .

If , there is no free row, and the linear objective vector should be supplied in array .

The constant , to be added to the objective for printing purposes. Typically .

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

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

indaint, array-like, shape

must contain the row index of the nonzero element stored in , for . Thus a pair of values 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

must contain the index in and of the start of the th column, for . Thus for , the entries of column are held in and their corresponding row indices are in , where and . To specify the th column as empty, set . Note that the first and last elements of must be and . 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 , , , , and , for . This row is made ‘free’ by setting its bounds to be and , where is the value of the option ‘Infinite Bound Size’.

blfloat, array-like, shape

, the lower bounds for all the variables and general constraints, in the following order. The first elements of must contain the bounds on the variables , and the next elements the bounds for the general linear constraints (which, equivalently, are the bounds for the slacks, ) and the free row (if any). To fix the th variable, set , say, where . To specify a nonexistent lower bound (i.e., ), set . Here, is the value of the option ‘Infinite Bound Size’. To specify the th constraint as an equality, set , say, where . Note that the lower bound corresponding to the free row must be set to and stored in .

bufloat, array-like, shape

, the upper bounds for all the variables and general constraints, in the following order. The first elements of must contain the bounds on the variables , and the next elements the bounds for the general linear constraints (which, equivalently, are the bounds for the slacks, ) and the free row (if any). To specify a nonexistent upper bound (i.e., ), set . Note that the upper bound corresponding to the free row must be set to and stored in .

namesstr, length 8, array-like, shape

The optional column and row names, respectively.

If , is not referenced and the printed output will use default names for the columns and rows.

If , the first elements must contain the names for the columns and the next elements must contain the names for the rows.

Note that the name for the free row (if any) must be stored in .

helastint, array-like, shape

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

Status in elastic mode

Variable is non-elastic and cannot be infeasible

Variable can violate its lower bound

Variable can violate its upper bound

Variable can violate either its lower or upper bound

need not be assigned if option .

hsint, array-like, shape

If or , 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 and need not be set at all.

If or and there is no Basis file, the first elements of and must specify the initial states and values, respectively, of the variables . (The slacks need not be initialized.) An internal Crash procedure is then used to select an initial basis matrix .

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

It is chosen from various rows and columns of .

Possible values for are as follows:

State of during Crash procedure

or

Eligible for the basis

Ignored

Eligible for the basis (given preference over or )

or

Ignored

If nothing special is known about the problem, or there is no wish to provide special information, you may set and , for .

All variables will then be eligible for the initial basis.

Less trivially, to say that the th variable will probably be equal to one of its bounds, set and or and as appropriate.

Following the Crash procedure, variables for which are made superbasic.

Other variables not selected for the basis are then made nonbasic at the value if , or at the value or closest to .

If , and must specify the initial states and values, respectively, of the variables and slacks .

If qpconvex2_sparse_solve has been called previously with the same values of and , already contains satisfactory information.

xfloat, array-like, shape

The initial values of the variables , and, if , the slacks , i.e., . (See the description for argument .)

nsint

, the number of superbasics. For QP problems, need not be specified if , but must retain its value from a previous call when . For FP and LP problems, 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 to compute the matrix product for a given vector .

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

For example, if and only enters the objective quadratically, then

In this case, should be the dimension of , and should compute .

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

Parameters
xfloat, ndarray, shape

The first elements of the vector .

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 , or .

qpconvex2_sparse_solve is calling for the first time.

There is nothing special about the current call of .

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

The current is optimal.

The problem appears to be infeasible.

The problem appears to be unbounded.

The iterations limit was reached.

dataarbitrary, optional, modifiable in place

User-communication data for callback functions.

Returns
hxfloat, array-like, shape

The product . If is less than the input argument , is really the product in [equation].

cNone or float, array-like, shape , optional

Contains the explicit objective vector (if any). If the problem is of type FP, or if , is not referenced. (In that case, 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

The final states of the variables and slacks . The significance of each possible value of is as follows:

State of variable

Normal value of

Nonbasic

Nonbasic

Superbasic

Between and

Basic

Between and

If , 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 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 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 lies strictly between its bounds.

If , some basic and superbasic variables may be outside their bounds by an arbitrary amount (bounded by if ).

xfloat, ndarray, shape

The final values of the variables and slacks .

pifloat, ndarray, shape

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

rcfloat, ndarray, shape

Contains the reduced costs, . The vector is the gradient of the objective if is feasible; otherwise, it is the gradient of the Phase 1 objective. In the former case, , for , hence .

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 , and is most meaningful when .

objfloat

The value of the objective function.

If , includes the quadratic objective term (if any).

If , is just the linear objective term (if any).

For FP problems, is set to zero.

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

Other Parameters
‘Check Frequency’int

Default

Every th iteration after the most recent basis factorization, a numerical test is made to see if the current solution satisfies the linear constraints . If the largest element of the residual vector is judged to be too large, the current basis is refactorized and the basic variables recomputed to satisfy the constraints more accurately. If , the value is used and effectively no checks are made.

is useful for debugging purposes, but otherwise this option should not be needed.

‘Crash Option’int

Default

Note that these options do not apply when (see Parameters).

If , an internal Crash procedure is used to select an initial basis from various rows and columns of the constraint matrix . The value of determines which rows and columns of are initially eligible for the basis, and how many times the Crash procedure is called. Columns of are used to pad the basis where necessary.

Meaning

The initial basis contains only slack variables: .

The Crash procedure is called once, looking for a triangular basis in all rows and columns of the matrix .

The Crash procedure is called once, looking for a triangular basis in rows.

The Crash procedure is called twice, treating linear equalities and linear inequalities separately.

If , certain slacks on inequality rows are selected for the basis first. (If , numerical values are used to exclude slacks that are close to a bound.) The Crash procedure then makes several passes through the columns of , 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 . If is the largest element in column , other nonzeros in the column are ignored if . (To be meaningful, should be in the range .)

When , 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 and fewer (arbitrary) slacks. A feasible solution may be reached sooner on some problems.

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

‘Crash Tolerance’float

Default

Note that these options do not apply when (see Parameters).

If , an internal Crash procedure is used to select an initial basis from various rows and columns of the constraint matrix . The value of determines which rows and columns of are initially eligible for the basis, and how many times the Crash procedure is called. Columns of are used to pad the basis where necessary.

Meaning

The initial basis contains only slack variables: .

The Crash procedure is called once, looking for a triangular basis in all rows and columns of the matrix .

The Crash procedure is called once, looking for a triangular basis in rows.

The Crash procedure is called twice, treating linear equalities and linear inequalities separately.

If , certain slacks on inequality rows are selected for the basis first. (If , numerical values are used to exclude slacks that are close to a bound.) The Crash procedure then makes several passes through the columns of , 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 . If is the largest element in column , other nonzeros in the column are ignored if . (To be meaningful, should be in the range .)

When , 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 and fewer (arbitrary) slacks. A feasible solution may be reached sooner on some problems.

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

‘Defaults’valueless

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

‘Dump File’int

Default

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 , the last solution obtained will be output to the file with unit number .

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

Default

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 , the last solution obtained will be output to the file with unit number .

If , 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

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

Meaning

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.

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’.

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

This determines the form of the composite objective in Phase 2 (). Three types of composite objectives are available.

Meaning

Include only the true objective in the composite objective. This option sets in the composite objective and allows qpconvex2_sparse_solve to ignore the elastic bounds and find a solution that minimizes 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.

Use a composite objective defined with determined by the value of ‘Elastic Weight’. This value is intended to be used in conjunction with .

Include only the elastic variables in the composite objective. The elastics are weighted by . 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 .

‘Elastic Weight’float

Default

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

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

where for ‘Minimize’, for ‘Maximize’, and is the quadratic objective.

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

‘Expand Frequency’int

Default

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 . Over a period of iterations, the feasibility tolerance actually used by qpconvex2_sparse_solve (i.e., the working feasibility tolerance) increases from to (in steps of ).

Increasing the value of 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 , the value is used and effectively no anti-cycling procedure is invoked.

‘Factorization Frequency’int

Default or

If , at most 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 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 are satisfied. Occasionally, the basis will be refactorized before the limit of updates is reached. If , the default value is used.

‘Feasibility Tolerance’float

Default

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

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 by a factor of or . 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 ), 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 .

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

If , defines the ‘infinite’ bound in the definition of the problem constraints. Any upper bound greater than or equal to will be regarded as (and similarly any lower bound less than or equal to will be regarded as ). If , the default value is used.

‘Iterations Limit’int

Default

The value of specifies the maximum number of iterations allowed before termination. Setting and 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 , the default value is used.

‘LU Density Tolerance’float

Default

The density tolerance is used during factorization of the basis matrix. Columns of and rows of 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 , the Markowitz strategy for choosing pivots is terminated. The remaining matrix is factored by a dense procedure. Raising the density tolerance towards may give slightly sparser factors, with a slight increase in factorization time.

If , defines the singularity tolerance used to guard against ill-conditioned basis matrices. After is refactorized, the diagonal elements of are tested as follows. If or , the th column of the basis is replaced by the corresponding slack variable. If , the default value is used.

‘LU Singularity Tolerance’float

Default

The density tolerance is used during factorization of the basis matrix. Columns of and rows of 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 , the Markowitz strategy for choosing pivots is terminated. The remaining matrix is factored by a dense procedure. Raising the density tolerance towards may give slightly sparser factors, with a slight increase in factorization time.

If , defines the singularity tolerance used to guard against ill-conditioned basis matrices. After is refactorized, the diagonal elements of are tested as follows. If or , the th column of the basis is replaced by the corresponding slack variable. If , the default value is used.

‘LU Factor Tolerance’float

Default

The values of and affect the stability and sparsity of the basis factorization , during refactorization and updates respectively. The lower triangular matrix is a product of matrices of the form

where the multipliers will satisfy . The default values of and usually strike a good compromise between stability and sparsity. They must satisfy , .

For large and relatively dense problems, or (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 in order to achieve stability. For example, if the columns of include a sub-matrix of the form

one should set both and to values in the range .

‘LU Update Tolerance’float

Default

The values of and affect the stability and sparsity of the basis factorization , during refactorization and updates respectively. The lower triangular matrix is a product of matrices of the form

where the multipliers will satisfy . The default values of and usually strike a good compromise between stability and sparsity. They must satisfy , .

For large and relatively dense problems, or (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 in order to achieve stability. For example, if the columns of include a sub-matrix of the form

one should set both and to values in the range .

‘LU Partial Pivoting’valueless

Default

The 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 ).

‘LU Complete Pivoting’valueless

The 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 ).

‘LU Rook Pivoting’valueless

The 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 ).

‘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 and the other maximizes , their solutions will be the same but the signs of the dual variables and the reduced gradients (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 and the other maximizes , their solutions will be the same but the signs of the dual variables and the reduced gradients (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 and the other maximizes , their solutions will be the same but the signs of the dual variables and the reduced gradients (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

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 , a basis map will be saved on file every th iteration, where 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 is intended as a safeguard against losing the results of a long run. Suppose that a ‘New Basis File’ is being saved every (‘Save Frequency’) iterations, and that qpconvex2_sparse_solve is about to save such a basis at iteration . 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 iterations, first on ‘New Basis File’ and then immediately on ‘Backup Basis File’. If the run is interrupted at iteration during the save on ‘New Basis File’, there will still be a usable basis on ‘Backup Basis File’ (corresponding to iteration ).

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 (or if the iteration limit is ), the final basis on ‘New Basis File’ will correspond to iteration , but the last basis saved on ‘Backup Basis File’ will be the one for iteration .

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

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 , a basis map will be saved on file every th iteration, where 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 is intended as a safeguard against losing the results of a long run. Suppose that a ‘New Basis File’ is being saved every (‘Save Frequency’) iterations, and that qpconvex2_sparse_solve is about to save such a basis at iteration . 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 iterations, first on ‘New Basis File’ and then immediately on ‘Backup Basis File’. If the run is interrupted at iteration during the save on ‘New Basis File’, there will still be a usable basis on ‘Backup Basis File’ (corresponding to iteration ).

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 (or if the iteration limit is ), the final basis on ‘New Basis File’ will correspond to iteration , but the last basis saved on ‘Backup Basis File’ will be the one for iteration .

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

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 , a basis map will be saved on file every th iteration, where 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 is intended as a safeguard against losing the results of a long run. Suppose that a ‘New Basis File’ is being saved every (‘Save Frequency’) iterations, and that qpconvex2_sparse_solve is about to save such a basis at iteration . 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 iterations, first on ‘New Basis File’ and then immediately on ‘Backup Basis File’. If the run is interrupted at iteration during the save on ‘New Basis File’, there will still be a usable basis on ‘Backup Basis File’ (corresponding to iteration ).

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 (or if the iteration limit is ), the final basis on ‘New Basis File’ will correspond to iteration , but the last basis saved on ‘Backup Basis File’ will be the one for iteration .

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

If , 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

This is used to judge the size of the reduced gradients , where is the th component of the gradient, is the associated column of the constraint matrix , and 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

respectively, and if for superbasic variables.

In the above tests, 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 actually used is defined by

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 against .

‘Partial Price’int

Default or

This option is recommended for large FP or LP problems that have significantly more variables than constraints (i.e., ). It reduces the work required for each pricing operation (i.e., when a nonbasic variable is selected to enter the basis). If , all columns of the constraint matrix are searched. If , and are partitioned to give roughly equal segments , for (modulo ). If the previous pricing search was successful on , the next search begins on the segments and . 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 , and so on. If , the default value is used.

‘Pivot Tolerance’float

Default

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

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

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 ) provides some freedom to maximize the pivot element and thereby improve numerical stability. Excessively small values of should, therefore, not be specified. To a lesser extent, the option ‘Expand Frequency’ (say ) also provides some freedom to maximize the pivot element. Excessively large values of should, therefore, not be specified.

‘Print File’int

Default

If , the following information is output to during the solution of each problem:

• a listing of the options;

• some statistics about the problem;

• the amount of storage available for the 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 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

If , one line of the iteration log will be printed every th iteration. A value such as is suggested for those interested only in the final solution. If , the value of is used and effectively no checks are made.

‘Print Level’int

Default

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

Meaning

0

No output except error messages. If you want to suppress all output, set .

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.

Basis factorization statistics.

‘Punch File’int

Default

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 , the final solution obtained will be output to file . For linear programs, this format is compatible with various commercial systems.

If , 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

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 , the final solution obtained will be output to file . For linear programs, this format is compatible with various commercial systems.

If , 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 (). ‘QPSolver Cholesky’ holds the full Cholesky factor of the reduced Hessian . As the QP iterations proceed, the dimension of 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, 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 at the start of Phase 2 (). 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 superbasics).

‘QPSolver CG’valueless

Specifies the active-set algorithm used to solve the quadratic program in Phase 2 (). ‘QPSolver Cholesky’ holds the full Cholesky factor of the reduced Hessian . As the QP iterations proceed, the dimension of 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, 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 at the start of Phase 2 (). 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 superbasics).

‘QPSolver QN’valueless

Specifies the active-set algorithm used to solve the quadratic program in Phase 2 (). ‘QPSolver Cholesky’ holds the full Cholesky factor of the reduced Hessian . As the QP iterations proceed, the dimension of 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, 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 at the start of Phase 2 (). 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 superbasics).

‘Reduced Hessian Dimension’int

Default

This specifies that an triangular matrix (to define the reduced Hessian according to ). is to be available for use by the Cholesky QP solver.

‘Scale Option’int

Default

Three scale options are available as follows:

Meaning

0

No scaling. This is recommended if it is known that and the constraint matrix never have very large elements (say, larger than ).

1

The constraints and variables are scaled by an iterative procedure that attempts to make the matrix coefficients as close as possible to (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 or the solution is large. This takes into account columns of 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:

If is less than times its previous value, another scaling pass is performed to adjust the row and column scales. Raising from to (say) usually increases the number of scaling passes through . At most passes are made. The value of should lie in the range .

‘Scale Print’ causes the row scales and column scales to be printed to ‘Print File’, if ‘System Information Yes’ has been specified. The scaled matrix coefficients are , and the scaled bounds on the variables and slacks are , , where if .

‘Scale Tolerance’float

Default

Three scale options are available as follows:

Meaning

0

No scaling. This is recommended if it is known that and the constraint matrix never have very large elements (say, larger than ).

1

The constraints and variables are scaled by an iterative procedure that attempts to make the matrix coefficients as close as possible to (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 or the solution is large. This takes into account columns of 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:

If is less than times its previous value, another scaling pass is performed to adjust the row and column scales. Raising from to (say) usually increases the number of scaling passes through . At most passes are made. The value of should lie in the range .

‘Scale Print’ causes the row scales and column scales to be printed to ‘Print File’, if ‘System Information Yes’ has been specified. The scaled matrix coefficients are , and the scaled bounds on the variables and slacks are , , where if .

‘Scale Print’valueless

Three scale options are available as follows:

Meaning

0

No scaling. This is recommended if it is known that and the constraint matrix never have very large elements (say, larger than ).

1

The constraints and variables are scaled by an iterative procedure that attempts to make the matrix coefficients as close as possible to (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 or the solution is large. This takes into account columns of 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:

If is less than times its previous value, another scaling pass is performed to adjust the row and column scales. Raising from to (say) usually increases the number of scaling passes through . At most passes are made. The value of should lie in the range .

‘Scale Print’ causes the row scales and column scales to be printed to ‘Print File’, if ‘System Information Yes’ has been specified. The scaled matrix coefficients are , and the scaled bounds on the variables and slacks are , , where if .

‘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

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

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

‘Summary File’int

Default

If , the ‘Summary File’ is output to file , including a line of the iteration log every 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 , the value of is used and effectively no checks are made.

‘Summary Frequency’int

Default

If , the ‘Summary File’ is output to file , including a line of the iteration log every 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 , the value of is used and effectively no checks are made.

‘Superbasics Limit’int

Default

This places a limit on the storage allocated for superbasic variables. Ideally, 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 , the number of general constraints.) The default value of is, therefore, .

For quadratic problems, the number of degrees of freedom is often called the ‘number of independent variables’. Normally, need not be greater than , where is the number of leading nonzero columns of . For many problems, may be considerably smaller than . This will save storage if 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

If , some timing information will be output to the Print file, if .

‘Unbounded Step Size’float

Default

If , 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 during an iteration would exceed the value of , the objective function is considered to be unbounded below in the feasible region. If , the default value is used. See ‘Infinite Bound Size’ for the definition of .

Raises
NagValueError
(errno )

The initialization function qpconvex2_sparse_init() has not been called.

(errno )

On entry, .

Constraint: , or .

(errno )

On entry, , and .

Constraint: .

(errno )

On entry, and .

Constraint: .

(errno )

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

(errno )

On entry, and .

Constraint: .

(errno )

On entry, , and .

Constraint: or .

(errno )

On entry, and .

Constraint: .

(errno )

On entry, , , .

Constraint: or .

(errno )

On entry, row index in is outside the range to .

(errno )

On entry, is not equal to the number of nonzeros in . , nonzeros in .

(errno )

On entry, bounds and for are equal and infinite: and .

(errno )

On entry, bounds for are inconsistent. and .

(errno )

On entry, bounds and for are equal and infinite. and .

(errno )

On entry, bounds for are inconsistent. and .

(errno )

Basis file dimensions do not match this problem.

(errno )

On entry, .

Constraint: .

(errno )

On entry, .

Constraint: .

(errno )

(errno )

(errno )

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

(errno )

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

Warns
NagAlgorithmicWarning
(errno )

Weak solution found – the solution is not unique.

(errno )

The linear constraints appear to be infeasible.

(errno )

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

(errno )

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

(errno )

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

(errno )

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

(errno )

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

NagAlgorithmicMajorWarning
(errno )

The requested accuracy could not be achieved.

(errno )

Iteration limit reached.

(errno )

Major iteration limit reached.

(errno )

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

(errno )

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

(errno )

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

(errno )

Error in : the QP Hessian is indefinite.

Notes

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

where is an -vector of variables, and are constant lower and upper bounds, is an sparse matrix and 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 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 th constraint may be defined as an equality by setting . If certain bounds are not present, the associated elements of or may be set to special values that are treated as or .

The possible forms for the function are summarised in Table [label omitted]. The most general form for is

where is a constant, is a constant -vector and is a constant symmetric matrix with elements . In this form, is a quadratic function of 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 must be positive semidefinite, i.e., it must satisfy for all . If not, is nonconvex and qpconvex2_sparse_solve will terminate with the error indicator = 11. If is nonconvex it may be more appropriate to call handle_solve_ssqp() instead.

Problem type

Objective function

Hessian matrix

FP

Not applicable

LP

QP

Symmetric positive semidefinite

If , then and the problem is known as a linear program (LP). In this case, rather than defining an with zero elements, you can define to have no columns by setting (see Parameters).

If , , and , 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 . 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 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 is input to qpconvex2_sparse_solve by means of the three array arguments , and . This allows you to specify the pattern of nonzero elements in .

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

For problems in which 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 in Table [label omitted]. The vector defining the linear term can be input in three ways: as a sparse row of ; as an explicit dense vector ; or as both a sparse row and an explicit vector (in which case, will be the sum of two linear terms). When stored in , is the th row of , which is known as the objective row. The objective row must always be a free row of in the sense that its lower and upper bounds must be and . Storing as part of is recommended if is a sparse vector. Storing as an explicit vector is recommended for a sequence of problems, each with a different objective (see arguments and ).

The upper and lower bounds on the elements of 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 , where . For example, the linear constraint is replaced by , together with the bounded slack . The problem defined by (1) can, therefore, be re-written in the following equivalent form:

Since the slack variables are subject to the same upper and lower bounds as the elements of , the bounds on and can simply be thought of as bounds on the combined vector . (In order to indicate their special role in QP problems, the original variables are sometimes known as ‘column variables’, and the slack variables 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 and is minimized to find a feasible point that satisfies all constraints within a specified feasibility tolerance; and an optimality phase (Phase 2), in which 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 minimizex,s,v,w∑n+mj=1(vj+wj) subject to Ax−s=0, l≤(xs)−v+w≤u, v≥0, w≥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 and are zero. Then the associated value of satisfies the original constraints and is used as the starting point for the Phase 2 iterations for minimizing .

If the constraints are infeasible (i.e., or 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 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 in Parameters).

To make the relaxed problem meaningful, qpconvex2_sparse_solve minimizes 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 (γ) minimizex,s,v,wf(x)+γ∑n+mj=1(vj+wj) subject to Ax−s=0, l≤(xs)−v+w≤u, v≥0, w≥0,

where is a non-negative argument known as the elastic weight (see the description of the option ‘Elastic Weight’), and is called the composite objective. In the more general situation where only a subset of the bounds are elastic, the ’s and ’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 , the sum of infeasibilities, or anything in-between. If , qpconvex2_sparse_solve will attempt to minimize 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 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 and are done implicitly in the sense that an elastic variable is allowed to violate its lower bound (say) and an explicit value of can be recovered as .

A constraint is said to be active or binding at if the associated element of either or is equal to one of its upper or lower bounds. Since an active constraint in 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 . 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 are (conceptually) partitioned into the form

where consists of the nonbasic elements of and the basis matrix is square and nonsingular. The elements of and are called the basic and superbasic variables respectively; with they are a permutation of the elements of and . 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, 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 continues to satisfy . The number of superbasic variables ( say), therefore, indicates the number of degrees of freedom remaining after the constraints have been satisfied. In broad terms, is a measure of how nonlinear the problem is. In particular, will always be zero for FP and LP problems.

If it appears that no improvement can be made with the current definition of , and , a nonbasic variable is selected to be added to , and the process is repeated with the value of 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 is decreased by one.

Associated with each of the equality constraints is a dual variable . Similarly, each variable in has an associated reduced gradient (also known as a reduced cost). The reduced gradients for the variables are the quantities , where is the gradient of the QP objective function, and the reduced gradients for the slack variables are the dual variables . The QP subproblem is optimal if for all nonbasic variables at their lower bounds, for all nonbasic variables at their upper bounds and for all superbasic variables. In practice, an approximate QP solution is found by slightly relaxing these conditions on (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 means that the reduced gradient associated with the relevant active upper or lower bound on is computed via the formula , where is the th column of . (The variable selected by such a process and the corresponding value of (i.e., its reduced gradient) are the quantities +SBS and dj in the monitoring file output; see Further Comments.) If has significantly more columns than rows (i.e., ), 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 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 factors of the basis matrix ), 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 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