naginterfaces.library.opt.handle_​solve_​ssqp

naginterfaces.library.opt.handle_solve_ssqp(handle, x, objfun=None, objgrd=None, confun=None, congrd=None, hess=None, monit=None, u=None, data=None, io_manager=None)[source]

handle_solve_ssqp is a solver from the NAG optimization modelling suite for large-scale Nonlinear Programming (NLP) problems based on an active-set Sequential Quadratic Programming (SQP) method, using limited-memory quasi-Newton approximations to the Hessian of the Lagrangian.

Note: this function uses optional algorithmic parameters, see also: handle_opt_set(), handle_init(), handle_opt_get().

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

https://www.nag.com/numeric/nl/nagdoc_28.6/flhtml/e04/e04srf.html

Parameters
handleHandle

The handle to the problem. It needs to be initialized (e.g., by handle_init()) and to hold a problem formulation compatible with handle_solve_ssqp. It must not be changed between calls to the NAG optimization modelling suite.

xfloat, array-like, shape

, the initial estimates of the variables, .

objfunNone or callable (fx, inform) = objfun(x, inform, data=None), optional

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

must calculate the value of the nonlinear objective function at a specified point .

If there is no nonlinear objective (i.e., handle_set_nlnobj() was not called), will never be called by handle_solve_ssqp and may be None.

Parameters
xfloat, ndarray, shape

The vector of variable values at which the objective function is to be evaluated.

informint

A non-negative value.

dataarbitrary, optional, modifiable in place

User-communication data for callback functions.

Returns
fxfloat

The value of the objective function at .

informint

May be used to indicate that the function cannot be evaluated at the requested point by setting . The algorithm will try to recover if the objective cannot be evaluated; if recovery is not possible it will stop with = 21 or = 25.

objgrdNone or callable inform = objgrd(x, fdx, inform, data=None), optional

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

must calculate the values of the nonlinear objective function gradient at a specified point .

If there is no nonlinear objective (i.e., handle_set_nlnobj() was not called), will never be called by handle_solve_ssqp and may be None.

If the option or , then after returning from the gradient vector is checked for missing entries which you have not supplied.

Missing entries will be estimated using a finite difference method, see option ‘SSQP Estimate Derivatives’ description for more details.

Note: should not return floating-point NaN (Not a Number) or infinity values, if your code inadvertently returns any NaNs or infinities, handle_solve_ssqp is likely to terminate with = 21, 24 or 25.

Parameters
xfloat, ndarray, shape

The vector of variable values at which the objective function gradient is to be evaluated.

fdxfloat, ndarray, shape , to be modified in place

On entry: the elements should only be assigned and not referenced.

On exit: the values of the nonzero elements in the sparse gradient vector of the objective function, in the order specified by in a previous call to handle_set_nlnobj(). will store the gradient element , where .

informint

A non-negative value.

If , then this is a special presolve call.

This call is used to fill-in the constant elements of the objective gradient, e.g., when there are linear variables in the model.

Note that this call may occur with an iterate that may not be feasible with respect to the linear constraints but it will always be feasible with respect to the variable bounds.

Furthermore, this call only requires to return the constant elements of the gradient, , where is linear in .

If you do not provide these elements, subsequent calls to with may occur in the vicinity of with the purpose of estimating the missing derivatives using finite differences.

dataarbitrary, optional, modifiable in place

User-communication data for callback functions.

Returns
informint

May be used to inform that the gradient cannot be evaluated at the requested point by setting . The algorithm will try to recover if the gradient cannot be evaluated; if recovery is not possible it will stop with = 21 or = 25.

confunNone or callable (gx, inform) = confun(x, ncnln, inform, data=None), optional

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

must calculate the values of the nonlinear constraints at a specified point .

If there are no nonlinear constraints then will never be called by handle_solve_ssqp and it may be None.

Note: should not return floating-point NaN (Not a Number) or infinity values, if your code inadvertently returns any NaNs or infinities, handle_solve_ssqp is likely to terminate with = 21, 24 or 25.

Parameters
xfloat, ndarray, shape

The vector of variable values at which the constraint functions are to be evaluated.

ncnlnint

, the number of nonlinear constraints, as specified in an earlier call to handle_set_nlnconstr().

informint

A non-negative value.

If , then this is a special presolve call.

This call is used to quickly identify if the problem is infeasible, e.g., due to fixed variables.

Note that this call can occur with an iterate that may not be feasible with respect to the linear constraints but it will always be feasible with respect to the variable bounds.

dataarbitrary, optional, modifiable in place

User-communication data for callback functions.

Returns
gxfloat, array-like, shape

The values of the nonlinear constraint functions at .

informint

May be used to inform that the constraint values cannot be evaluated at the requested point by setting . The algorithm will try to recover if the gradient cannot be evaluated; if recovery is not possible it will stop with = 21 or = 25.

congrdNone or callable inform = congrd(x, gdx, inform, data=None), optional

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

must calculate the Jacobian of the nonlinear constraints at a specified point .

If there are no nonlinear constraints, will never be called by handle_solve_ssqp and may be None.

If the option or , then after returning from the Jacobian is checked for missing entries which you have not supplied.

Missing entries will be estimated using a finite difference method, see option ‘SSQP Estimate Derivatives’ description for more details.

Note: should not return floating-point NaN (Not a Number) or infinity values, if your code inadvertently returns any NaNs or infinities, handle_solve_ssqp is likely to terminate with = 21, 24 or 25.

Parameters
xfloat, ndarray, shape

The vector of variable values at which the Jacobian of the constraint functions is to be evaluated.

gdxfloat, ndarray, shape , to be modified in place

On entry: the elements should only be assigned and not referenced.

On exit: the nonzero values of the Jacobian of the nonlinear constraints, in the order specified by and in an earlier call to handle_set_nlnconstr(). will be the gradient , where and .

informint

A non-negative value.

If , then this is a special presolve call.

This call is used to fill-in the constant elements of the Jacobian, e.g., when there are linear variables in the model.

Note that this call may occur with an iterate that may not be feasible with respect to the linear constraints but it will always be feasible with respect to the variable bounds.

Furthermore, this call only requires to return the constant elements of the Jacobian, , where is linear in .

If the user does not provide these elements, subsequent calls to with may occur in the vicinity of with the purpose of estimating the missing derivatives using finite differences.

dataarbitrary, optional, modifiable in place

User-communication data for callback functions.

Returns
informint

May be used to inform that the Jacobian of the constraints cannot be evaluated at the requested point by setting . The algorithm will try to recover if the gradient cannot be evaluated; if recovery is not possible it will stop with = 21 or = 25.

hessNone or callable inform = hess(x, idf, sigma, lamda, hx, inform, data=None), optional

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

is reserved for future releases of the NAG Library which will allow calculation of the second derivatives.

It will never be called in the current implementation and may be None.

Parameters
xfloat, ndarray, shape

The vector of variable values at which the Hessian functions are to be evaluated.

idfint

Specifies the quantities to be computed in .

The values of the Hessian of the Lagrangian will be computed in . This will be the case if handle_set_nlnhess() has been called with of the same value.

The values of the Hessian of the objective function will be computed in . This will be the case if handle_set_nlnhess() has been called with of the same value.

The values of the Hessian of the constraint function with index will be computed in . This will be the case if handle_set_nlnhess() has been called with of the same value.

sigmafloat

If , the value of the quantity in the definition of the Hessian of the Lagrangian. Otherwise, should not be referenced.

lamdafloat, ndarray, shape

If , the values of the quantities in the definition of the Hessian of the Lagrangian. Otherwise, should not be referenced.

hxfloat, ndarray, shape , to be modified in place

On entry: the elements should only be assigned and not referenced.

On exit: the nonzero values of the requested Hessian evaluated at . For each value of , the ordering of nonzeros must follow the sparsity structure registered in the by earlier calls to handle_set_nlnhess() through the arguments and .

informint

A non-negative value.

dataarbitrary, optional, modifiable in place

User-communication data for callback functions.

Returns
informint

Must be set to a value describing the action to be taken by the solver on return from . Specifically, if the value is negative the solution of the current problem will terminate immediately with = 21 or = 25; otherwise, computations will continue.

monitNone or callable monit(x, u, rinfo, stats, data=None), optional

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

is provided to enable you to monitor the progress of the optimization and optionally to terminate the solver early if necessary.

It is invoked at the end of every th major iteration where is given by the ‘SSQP Monitor Frequency’ (the default is , is not called).

may be None.

Parameters
xfloat, ndarray, shape

, the values of the decision variables at the current iteration.

ufloat, ndarray, shape

If , holds the values of Lagrange multipliers (dual variables, see Minor Iterations) for the constraints at the current iteration. See Lagrangian Multipliers for layout information.

rinfofloat, ndarray, shape

Error measures and various indicators at the end of the current iteration as described in .

statsfloat, ndarray, shape

Solver statistics at the end of the current iteration as described in .

dataarbitrary, optional, modifiable in place

User-communication data for callback functions.

uNone or float, array-like, shape , optional

Note: if , holds Lagrange multipliers (dual variables) for the constraints. See Lagrangian Multipliers for layout information. If , will not be referenced.

Optionally provides the initial estimates of Lagrange multipliers, . These values are only referenced if a warm start is requested (Warm Starting). If there are no initial estimates available, then set to zero.

dataarbitrary, optional

User-communication data for callback functions.

io_managerFileObjManager, optional

Manager for I/O in this routine.

Returns
xfloat, ndarray, shape

The final values of the variables, .

uNone or float, ndarray, shape

The final value of Lagrange multipliers , see Minor Iterations.

rinfofloat, ndarray, shape

Error measures and various indicators at the end of the final iteration as given in the table below:

Objective function value .

Constraint violation (primal infeasibility), see Accuracy.

Dual infeasibility.

Reserved for future use.

Step size for the primal variables, see Iteration log in Description of the Printed Output.

Estimate of the condition number of , itself an estimate of , the reduced Hessian of the Lagrangian. See Description of the Printed Output.

Largest nonlinear constraint violation.

Largest nonlinear constraint violation, normalized using , with the latest iterate. See (2).

Sum of the infeasibilities of constraints that lie outside one of their bounds by more than the option ‘SSQP Minor Feasibility Tol’ before the solution is unscaled.

Description

0

none of the conditions are satisfied;

1

condition on primal infeasibility satisfied, is within ‘SSQP Major Feasibility Tol’ tolerance;

2

condition on dual infeasibility satisfied, is within ‘SSQP Minor Feasibility Tol’ tolerance; and

3

both conditions are satisfied.

The size of the penalty parameter of (8). See The Merit Function.

Flag indicating whether the current iterate is feasible with respect to the linear constraints, if any. A nonzero value indicates feasibility.

Reserved for future use.

statsfloat, ndarray, shape

Solver statistics at the end of the final iteration as given in the table below:

Number of major iterations.

Total number of minor iterations.

Number of minor iterations performed on the last major iteration.

Number of Hessian evaluations.

Number of gradient evaluations.

Number of infeasibilities of constraints that lie outside one of their bounds by more than the option ‘SSQP Minor Feasibility Tol’ before the solution is unscaled. If any linear constraints are infeasible, it contains the number of variables and linear constraints lying outside their upper or lower bounds. The nonlinear constraints are not evaluated. Otherwise, it contains the number of components of lying outside their bounds by more than the option ‘SSQP Minor Feasibility Tol’. Again this is before the solution is unscaled.

Total time spent in presolver (including user-supplied function calls).

Total time spent in solver (including user-supplied function calls).

Total time spent evaluating constraint function.

Total time spent evaluating constraint Jacobian.

Total time spent evaluating objective function.

Total time spent evaluating objective gradient.

Total time spent evaluating Hessian.

Reserved for future use.

Number of function evaluations.

Number of constraint function evaluations.

Number of constraint Jacobian evaluations.

Reserved for future use.

Number of superbasic variables.

Number of column swaps between and .

Number of elements in the factorization of .

Reserved for future use.

Number of slack variables. See Algorithmic Details.

Reserved for future use.

Other Parameters
‘Defaults’valueless

This special keyword may be used to reset all options to their default values. Any value given with this keyword will be ignored.

‘Infinite Bound Size’float

Default

This 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 ). Note that a modification of this option does not influence constraints which have already been defined; only the constraints formulated after the change will be affected.

Constraint: .

‘Monitoring File’int

Default

If , the unit number for the secondary (monitoring) output. If set to , no secondary output is provided. The following information is output to the unit:

  • a listing of the options;

  • problem statistics, the iteration log and the final status as set by ‘Monitoring Level’;

  • the solution if set by ‘Print Solution’.

Constraint: .

‘Monitoring Level’int

Default

This argument sets the amount of information detail that will be printed by the solver to the secondary output. The meaning of the levels is the same as with ‘Print Level’.

Constraint: .

‘Print File’int

Default

If , the unit number for the primary output of the solver. If , the primary output is completely turned off independently of other settings. The default value is the advisory message unit number at the time of the options initialization, e.g., at the initialization of the handle. The following information is output to the unit:

  • a listing of options if set by ‘Print Options’;

  • problem statistics, the iteration log and the final status from the solver as set by ‘Print Level’;

  • the solution if set by ‘Print Solution’.

Constraint: .

‘Print Level’int

Default

This argument defines how detailed information should be printed by the solver to the primary output.

Output

No output from the solver

Only the final status and the objective value

Problem statistics, one line per iteration showing the progress of the solution with respect to the convergence measures, final status and statistics

As level and additionally inner QP iteration log is reported every ‘SSQP Print Frequency’

As level but further details of each minor and major iteration are presented

Constraint: .

‘Print Options’str

Default

If , a listing of options will be printed to the primary output.

Constraint: or .

‘Print Solution’str

Default

If , the final values of the solution vector are printed on the primary and secondary outputs.

Constraint: or .

‘SSQP Crash Option’str

Default

Except on restarts , a crash procedure is used to select an initial basis (see (7) in Minor Iterations) from certain rows and columns of the constraint matrix . The ‘SSQP Crash Option’ determines which rows and columns of (see (5) in Major Iterations) are eligible initially, and how many times crash is called. Columns of are used to pad the basis where necessary.

Meaning

‘ONLY-SLACKS’

The initial basis contains only slack variables: (see (7) in Minor Iterations).

‘SINGLE-PASS’

crash is called once, looking for a triangular basis in all rows and columns of .

‘DOUBLE-PASS’

crash is called twice (if there are nonlinear constraints). The first call looks for a triangular basis in linear rows, and the iteration proceeds with simplex iterations until the linear constraints are satisfied. The Jacobian is then evaluated for the first major iteration and crash is called again to find a triangular basis in the nonlinear rows (retaining the current basis for linear rows).

‘TRIPLE-PASS’

crash is called up to three times (if there are nonlinear constraints). The first two calls treat linear equalities and linear inequalities separately. As before, the last call treats nonlinear rows before the first major iteration.

If , certain slacks on inequality rows are selected for the basis first, furthermore if or , numerical values are used to exclude slacks that are close to a bound. crash 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.

Note: Each crash pass is counted as a minor iteration..

Constraint: , , or .

‘SSQP Crash Tolerance’float

Default

The ‘SSQP Crash Tolerance’ allows the starting procedure crash to ignore certain small nonzeros in each column of (see (5) in Major Iterations). If is the largest element in column , other nonzeros in the column are ignored if . To be meaningful, needs to be in the range .)

When , the basis obtained by crash 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 (columns of ). A feasible solution may be reached sooner on some problems.

When (or ) the solver will automatically choose an appropriate tolerance.

Constraint: ‘SSQP Crash Tolerance’ or ‘SSQP Crash Tolerance’.

‘SSQP Estimate Derivatives’str

Default

This option specifies which nonlinear function gradients (objective and nonlinear constraints) are known analytically and will be supplied to the solver by you functions and . This option has the following alternatives:

Meaning

‘NO’ (default)

Indicates to the solver that you are providing full derivative information, that is, all objective and constraint gradients are known.

‘ONLYOBJ’

Indicates that some or all components of the objective gradient will be missing but all constraint gradients are known.

‘ONLYCON’

Conversely to ‘ONLYOBJ’, this indicated that some or all of the constraint gradients will be missing but the objective gradient is known.

‘YES’

Indicates that the user is not providing derivatives.

The value should be used whenever possible. It is the most reliable and will usually be the most efficient.

If or , handle_solve_ssqp will estimate the missing components of the objective gradient, using finite differences. This may simplify the coding of function . However, it could increase the total run-time substantially (since a special call to is required for each missing element), and there is less assurance that an acceptable solution will be located. If the nonlinear variables are not well scaled, it may be necessary to specify a nonstandard difference interval changing ‘SSQP Finite Diff Ctrl Interval’ or ‘SSQP Finite Diff Interval’.

Conversely, if or , handle_solve_ssqp will estimate missing elements of the Jacobian. For each column of the Jacobian, one call to is needed to estimate all missing elements in that column, if any.

At times, central differences are used rather than forward differences. Twice as many calls to and are then needed. (This is not under your control.)

Note: If , or and the user does not provide one or more of the required gradient (or Jacobian) elements then these will be assumed to be constant, this might not be the desired behaviour. Under this circumstance, handle_solve_ssqp will inform the user with a message.

Constraint: , , or .

‘SSQP Finite Diff Ctrl Interval’float

Default

When , or , the central-difference interval is used near an optimal solution to obtain more accurate (but more expensive) estimates of gradients. Twice as many function evaluations are required compared to forward differencing. The interval used for the th variable is . The resulting derivative estimates should be accurate to , unless the functions are badly scaled.

Constraint: .

‘SSQP Finite Diff Interval’float

Default

This alters the interval used to estimate gradients by forward differences. It does so in the following circumstances:

  • in the ‘cheap’ phase of verifying the problem derivatives, when ;

  • for verifying the problem derivatives ();

  • for estimating missing derivatives.

In all cases, a derivative with respect to is estimated by perturbing that component of to the value , and then evaluating the objective or constraint functions at the perturbed point. The resulting gradient estimates should be accurate to unless the functions are badly scaled. Judicious alteration of may sometimes lead to greater accuracy.

Constraint: .

‘SSQP Function Precision’float

Default

The relative function precision is intended to be a measure of the relative accuracy with which the nonlinear functions can be computed. For example, if is computed as for some relevant and if the first significant digits are known to be correct, the appropriate value for would be .

Ideally, the functions and should have a magnitude of order . If all functions are substantially less than in magnitude, should be the absolute precision. For example, if at some point and if the first significant digits are known to be correct, the appropriate value for would be .)

The default value of is appropriate for simple analytic functions.

In some cases the function values will be the result of extensive computation, possibly involving a costly iterative procedure that can provide few digits of precision. Specifying an appropriate ‘SSQP Function Precision’ may lead to savings, by allowing the linesearch procedure to terminate when the difference between function values along the search direction becomes as small as the absolute error in the values.

Constraint: .

‘SSQP Hessian’str

Default

This option selects the method for storing and updating the approximate Hessian. (handle_solve_ssqp uses a quasi-Newton approximation to the Hessian of the Lagrangian. A BFGS update is applied after each major iteration.)

If is specified, the approximate Hessian is treated as a dense matrix and the BFGS updates are applied explicitly. This option is most efficient when the number of variables is not too large (say, less than ). In this case, the storage requirement is fixed and one can expect -step Q-superlinear convergence to the solution.

should be used on problems where is very large. In this case, a limited-memory procedure is used to update a diagonal Hessian approximation a limited number of times. Updates are accumulated as a list of vector pairs. They are discarded at regular intervals after has been reset to their diagonal, see option ‘SSQP Hessian Updates’.

If is specified, then the quasi-Newton method used is chosen based on a heuristic involving the number of nonlinear variables (see Note regarding nonlinear functions) in the problem.

Constraint: , or .

‘SSQP Hessian Updates’int

Default

If option is in effect and BFGS updates have already been carried out, all but the diagonal elements of the accumulated updates are discarded and the updating process starts again.

Broadly speaking, the more updates stored, the better the quality of the approximate Hessian. However, the more vectors stored, the greater the cost of each QP iteration. The default value is likely to give a robust algorithm without significant expense, but faster convergence can sometimes be obtained with significantly fewer updates (e.g., ).

Constraint: .

‘SSQP Iteration Limit’int

Default

The value of specifies the maximum number of minor iterations allowed (i.e., iterations of the simplex method or the QP algorithm), summed over all major iterations. (See also the description of the option ‘SSQP Minor Iteration Limit’.) For the default value, is the number of linear, quadratic and nonlinear constraints defined in the model.

Constraint: .

‘SSQP Major Feasibility Tol’float

Default

This tolerance, , specifies how accurately the nonlinear constraints should be satisfied. The default value is appropriate when the linear and nonlinear constraints contain data to about that accuracy.

Let be the maximum nonlinear constraint violation, normalized by the size of the solution, which is required to satisfy

where is the violation of the th nonlinear constraint, for .

In the major iteration log (see Description of the Printed Output), appears as the quantity labelled ‘Feasible’. If some of the problem functions are known to be of low accuracy, a larger ‘SSQP Major Feasibility Tol’ may be appropriate.

Constraint: .

‘SSQP Major Iteration Limit’int

Default

This is the maximum number of major iterations allowed. It is intended to guard against an excessive number of linearizations of the constraints. For the default value, is the number of linear, quadratic and nonlinear constraints defined in the model.

Constraint: .

‘SSQP Major Optimality Tol’float

Default

This tolerance, , specifies the final accuracy of the dual variables. On successful termination, handle_solve_ssqp will have computed a solution such that

where is an estimate of the complementarity slackness for variable , for . Here represents the number of constraints. The values are computed from the final QP solution using the reduced gradients (where is the th component of the objective gradient, is the associated column of the constraint matrix , and is the set of QP dual variables):

In the major iteration log, appears as the quantity labelled ‘Optimal’, See section Major Iteration Log.

Constraint: .

‘SSQP Minor Feasibility Tol’float

Default

handle_solve_ssqp tries to ensure that all variables eventually satisfy their upper and lower bounds to within this tolerance, . This includes slack variables. Hence, general linear constraints should also be satisfied to within .

Feasibility with respect to nonlinear constraints is judged by the option ‘SSQP Major Feasibility Tol’ (not by ‘SSQP Minor Feasibility Tol’).

If the bounds and linear constraints cannot be satisfied to within , the problem is declared infeasible. If is quite small, it may be appropriate to raise by a factor of or . Otherwise, some error in the data should be suspected.

Nonlinear functions will be evaluated only at points that satisfy the bounds and linear constraints, except perhaps in presolve where the solver may require to evaluate , or at a bound-feasible point. If there are regions where a function is undefined, every attempt should be made to eliminate these regions from the problem.

For example, if , it is essential to place lower bounds on both variables. If , the bounds and might be appropriate. (The log singularity is more serious. In general, keep as far away from singularities as possible.)

If or , feasibility is defined in terms of the scaled problem (since it is then more likely to be meaningful).

In reality, handle_solve_ssqp uses as a feasibility tolerance for satisfying the bounds on and in each QP subproblem. If the sum of infeasibilities cannot be reduced to zero, the QP subproblem is declared infeasible. handle_solve_ssqp then activates elastic mode for the rest of the solving process (with only the linearized nonlinear constraints defined to be elastic). For further details see Treatment of Constraint Infeasibilities.

Constraint: .

‘SSQP Minor Iteration Limit’int

Default

If the number of minor iterations for the optimality phase of the QP subproblem exceeds , then all nonbasic QP variables that have not yet moved are frozen at their current values and the reduced QP is solved to optimality.

Note that more than minor iterations may be necessary to solve the reduced QP to optimality. These extra iterations are necessary to ensure that the terminated point gives a suitable direction for the linesearch.

In the major iteration log (see Description of the Printed Output) the flag t at the end of a line indicates that the corresponding QP was artificially terminated using the limit .

Compare with the option ‘SSQP Iteration Limit’, which defines an independent absolute limit on the total number of minor iterations (summed over all QP subproblems).

Constraint: .

‘SSQP Monitor Frequency’int

Default

This argument specifies the frequency on which to call the monitor function . If zero, the monitor function will not be called.

Constraint: .

‘SSQP Penalty Parameter’float

Default

Defines the initial value of the penalty parameter and sets in (8).

Constraint: .

‘SSQP Print Frequency’int

Default

Defines how frequently to print log information for the inner iterations. Only relevant if ‘Print Level’ (with ‘Print File’) or ‘Monitoring Level’ (with ‘Monitoring File’)

Constraint: .

‘SSQP Scale Option’str

Default

Three scale options are available as follows:

Meaning

‘NONE’

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

‘VARS AND LC’

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.

‘ALL’

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.

Constraint: , or .

‘SSQP Scale Print’str

Default

Defines whether to print the row scales and column scales . The scaled matrix coefficients are and the scaled bounds on the variables and slacks are , if .

Constraint: or .

‘SSQP Scale Tolerance’float

Default

This argument 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 .

Constraint: .

‘SSQP Start Type’str

Default

Defines whether to perform a cold or warm start. If warm start data is not provided or is considered to have an unexpected size or content, then the solver will revert to perform a cold start on the problem. See Warm Starting on how to correctly warm start a problem.

Constraint: or .

‘SSQP Superbasics Limit’int

Default

This option 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 nonlinear problems, the number of degrees of freedom is often called the ‘number of independent variables’. Normally, need not be greater than .

If (the default), then handle_solve_ssqp automatically sets the limit to the number of nonlinear variables. For many problems, may be considerably smaller than . This will save storage if is very large.

If the limit set is too low then the solver will terminate with = 27 error message.

Constraint: .

‘Stats Time’str

Default

This argument allows you to turn on the timings of various parts of the algorithm to give a better overview of where most of the time is spent. This might be helpful for a choice of different solving approaches. It is possible to choose between CPU and wall clock time. Choice ‘YES’ is equivalent to ‘WALL CLOCK’.

Constraint: , , or .

‘Task’str

Default

This argument specifies the required direction of the optimization. If , the objective function (if set) is ignored and the algorithm stops as soon as a feasible point is found. If no objective function is set, ‘Task’ reverts to ‘FEASIBLE POINT’ automatically.

Constraint: , or .

‘Time Limit’float

Default

This argument specifies a limit in seconds that the solver can use to solve one problem. If during the convergence check this limit is exceeded, the solver will terminate with = 23 error message.

Constraint: .

‘Verify Derivatives’str

Default

This argument specifies whether the function should perform numerical checks on the consistency of the user-supplied gradient functions and . If any discrepancies are found, = 26 is returned. It is recommended that such checks are enabled when first developing the formulation of the problem, however, the verification process results in a significant increase in the number of the function evaluations and thus it shouldn’t be used in production code.

a

Meaning

Only a ‘cheap’ test will be performed.

Individual columns of the problem Jacobian, as well as individual gradient elements, will be checked (with a more reliable test). A key of the form OK or Bad? indicates whether or not each component appears to be correct.

Derivative checking is disabled.

should be specified whenever a new or is being developed.

Constraint: , or .

Raises
NagValueError
(errno )

has not been initialized.

(errno )

does not belong to the NAG optimization modelling suite, has not been initialized properly or is corrupted.

(errno )

has not been initialized properly or is corrupted.

(errno )

The problem is already being solved.

(errno )

This solver does not support the model defined in the handle.

(errno )

On entry, , expected .

Constraint: must match the current number of variables of the model in the .

(errno )

On entry, .

Constraint: or .

(errno )

On entry, .

Constraint: no constraints present, so must be .

(errno )

Please provide a proper function.

(errno )

Please provide a proper function.

(errno )

Please provide a proper function.

(errno )

Please provide a proper function.

(errno )

Please provide a proper function.

Warns
NagAlgorithmicWarning
(errno )

User requested termination during a monitoring step.

(errno )

Problem was solved to an acceptable level, full accuracy was not achieved.

(errno )

The problem was found to be infeasible during preprocessing.

(errno )

The problem seems to be infeasible, the algorithm was stopped.

(errno )

The problem seems to be unbounded and the algorithm was stopped.

NagAlgorithmicMajorWarning
(errno )

The current starting point is unusable.

(errno )

Maximum number of iterations reached.

(errno )

The solver terminated after the maximum time allowed was exhausted.

(errno )

The solver was terminated because no further progress could be achieved.

(errno )

Invalid value detected in user function and recovery failed.

(errno )

User-provided derivatives are likely to be incorrect.

(errno )

Maximum number of superbasic variables reached. Increase value of the option ‘SSQP Superbasics Limit’.

(errno )

Memory limit is too small.

Notes

handle_solve_ssqp is designed to minimize (maximize) a linear or nonlinear function possibly subject to a set of constraints including bounds on the variables and sparse linear and nonlinear constraints. It is suitable for large-scale general nonlinear programming (NLP) problems, as well as for linearly constrained optimization. It is particularly efficient if only some of the variables enter nonlinearly, or there are relatively few degrees of freedom at a solution (i.e., many constraints are active). However, there is no limit on the number of degrees of freedom.

handle_solve_ssqp solves a nonlinear programming problem in the following form

where

is the number of the decision variables,

is the number of the nonlinear constraints and , and are -dimensional vectors,

is the number of the quadratic constraints,

is the number of the linear constraints and is an matrix, and are -dimensional vectors,

there are box constraints and and are -dimensional vectors.

handle_solve_ssqp serves as a solver for problems stored as a handle. The handle points to an internal data structure which defines the problem and serves as a means of communication for functions in the NAG optimization modelling suite. First, the problem handle is initialized, typically by calling handle_init(). Then some of the components of the model need to be defined by calling one or more of the following routines based on the component type:

the objective function : linear (handle_set_linobj() or handle_set_quadobj()), quadratic (handle_set_quadobj(), handle_set_qconstr() or handle_set_qconstr_fac()) or nonlinear (handle_set_nlnobj()),

bound constraints on the variables (handle_set_simplebounds()),

one or more blocks of linear constraints (handle_set_linconstr()),

quadratic constraints (handle_set_qconstr() and handle_set_qconstr_fac() for quadratics in a factorized form),

general nonlinear constraints (handle_set_nlnconstr()).

Once the problem is fully described, the handle may be passed to the solver handle_solve_ssqp. When the handle is no longer needed, handle_free() should be called to destroy it and deallocate the memory held within. There are other ways that the problem model can be defined and/or updated, see the E04 Introduction for more details about the NAG optimization modelling suite.

The algorithm behaviour can be modified by various options (see Other Parameters) which can be set by handle_opt_set() and handle_opt_set_file() anytime between the initialization of the handle and a call to the solver. Once the solver has finished, options or the model may be modified for the next solve. The solver may be called repeatedly with various starting points and/or options. Option getter handle_opt_get() can be called to retrieve the current value of any option.

The option ‘Task’ may be used to switch the problem to maximization.

In certain situations the solver can be sped up by warm starting, see Warm Starting and option ‘SSQP Start Type’ for details.

Several options may have a significant impact on the performance of the solver. Even if the defaults were chosen to suit the majority of problems, it is recommended that you experiment in order to find the most suitable set of options for a particular problem, see Algorithmic Details and Other Parameters for further details.

Note regarding nonlinear functions

In the presence of a nonlinear objective function or constraint function, the structure (sparsity pattern) of these functions are defined by handle_set_nlnobj() and handle_set_nlnconstr() respectively; the function values and the first derivatives (gradients) are computed at requested points by the corresponding supplied functions , , and . Ideally, the first derivatives should be known and coded but handle_solve_ssqp estimates any missing ones by finite differences, see ‘SSQP Estimate Derivatives’.

The solver can strongly benefit from the correct identification of linear variables; these are the variables which appear only in linear expressions in the whole optimization model. The solver cannot autodetect if any variable present in nonlinear constraints or the nonlinear objective is linear thus there is a mechanism to declare the variable as linear by handle_set_property() and it is highly recommended to do so whenever possible. See Linearity of the Variables for handle_set_property for a detailed explanation and examples. The main advantage is that linear variables have constant first partial derivatives and must be zero in second derivatives, thus the internal approximation of the Hessian doesn’t need to take them into account which speeds up the solver.

Alternative solvers

handle_solve_ssqp is a generic solver which can solve a great variety of problems, however, a dedicated solver might work better in the following cases. See the E04 Introduction.

If is linear, , and is absent, (1) is a linear program (LP) and handle_solve_lp_ipm() is recommended.

If the problem is a convex quadratic or quadratically constrained problem, try handle_solve_socp_ipm().

If the problem is unconstrained or only box-constrained, see handle_solve_bounds_foas(), or handle_solve_dfno() if the problem is small and derivatives cannot be provided.

A general nonlinear problem lacking the sparse structure (which is typically the case for problems with a relatively small number of variables and constraints) might be better handled by nlp1_solve() or nlp2_solve().

An alternative solver for the same class of problems but based on a different algorithm (interior point method) is handle_solve_ipopt(), see the E04 Introduction for a discussion of the advantages of each approach.

References

Dantzig, G B, 1963, Linear Programming and Extensions, Princeton University Press

Eldersveld, S K, 1991, Large-scale sequential quadratic programming algorithms, PhD Thesis, Department of Operations Research, Stanford University, Stanford

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

Gill, P E, Murray, W and Saunders, M A, 2002, SNOPT: An SQP Algorithm for Large-scale Constrained Optimization (12), 979–1006, SIAM J. Optim.

Gill, P E, Murray, W and Saunders, M A, 2015, Users’ guide for SNOPT 7.5: Software for large-scale linear nonlinear programming, Report SNOPT, Department of Mathematics, University of California, San Diego, https://www.ccom.ucsd.edu/~peg/papers/sndoc7.pdf

Gill, P E, Murray, W and Saunders, M A, 2016, Users’ guide for SQOPT 7.5: Software for large-scale linear and quadratic programming, Report SQOPT, Department of Mathematics, University of California, San Diego, https://www.ccom.ucsd.edu/~peg/papers/sqdoc7.pdf

Gill, P E, Murray, W, Saunders, M A and Wright, M H, 1986, Users’ guide for NPSOL (Version 4.0): a Fortran package for nonlinear programming, Report SOL 86-2, Department of Operations Research, Stanford University

Gill, P E, Murray, W, Saunders, M A and Wright, M H, 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, 1992, Some theoretical properties of an augmented Lagrangian merit function, Advances in Optimization and Parallel Computing, (ed P M Pardalos), 101–128, North Holland

Hock, W and Schittkowski, K, 1981, Test Examples for Nonlinear Programming Codes. Lecture Notes in Economics and Mathematical Systems (187), Springer–Verlag

Murtagh, B A and Saunders, M A, 1978, Large-scale linearly constrained optimization, 14, 41–72, Math. Programming

Murtagh, B A and Saunders, M A, 1982, A projected Lagrangian algorithm and its implementation for sparse nonlinear constraints, Math. Program. Stud. (16), 84–118

Murtagh, B A and Saunders, M A, 1995, MINOS 5.4 users’ guide, Report SOL 83-20R, Department of Operations Research, Stanford University