SOL

Welcome to the TOMLAB /SOL User's Guide. TOMLAB /SOL includes a wide range of solver and interfaces between The MathWorks' MATLAB and all solvers developed by Stanford Systems Optimization Laboratory. The solver package includes binaries for the following solvers: MINOS - For large-scale sparse general nonlinear programming problems.

LP-MINOS - For large-scale sparse linear programming problems.

QP-MINOS - For large-scale sparse quadratic programming problems.

LPOPT - For dense linear programming problems.

QPOPT - For dense convex quadratic programming problems.

LSSOL - For dense linear and convex quadratic programs, and constrained linear least squares problems.

NLSSOL - For nonlinear least squares with linear and nonlinear constraints.

NPSOL - For dense linear, quadratic and nonlinear programming.

SNOPT - For large-scale, sparse, linear and nonlinear programming.

SQOPT - For sparse linear and quadratic programming.

Please visit http://tomopt.com/tomlab/products/sol/ for more information. The interface between TOMLAB /SOL, Matlab and TOMLAB consists of two layers. The first layer gives direct access from Matlab to SOL, via calling a Matlab function that calls a pre-compiled MEX file (DLL under Windows, shared library in UNIX) that defines and solves the problem in SOL. The second layer is a Matlab function that takes the input in the TOMLAB format, and calls the first layer function. On return the function creates the output in the TOMLAB format.

Contents of this Manual

• Section gives the basic information needed to run the Matlab interface.
• Section provides all the solver references for MINOS, LP-MINOS, QP-MINOS, LPOPT, QPOPT, LSSOL, NLSSOL, NPSOL, SNOPT, and SQOPT.
• Section discusses the use of TOMLAB /SOL in more detail.

Prerequisites

In this manual we assume that the user is familiar with SOL, the various SOL Reference Manuals, TOMLAB and the Matlab language.

Using the Matlab Interface

The main routines in the two-layer design of the interface are shown in Table . Page and section references are given to detailed descriptions on how to use the routines.

Table 1: The interface routines.
Function	Description	Section	Page
Table 2: The interface routines, continued
Function	Description	Section	Page
minos	The layer one Matlab interface routine, calls the MEX-file interface minos.dll
minosTL	The layer two interface routine called by the TOMLAB driver routine tomRun. This routine then calls minos.m.
minosLPTL	The layer two TOMLAB interface routine that calls minosLPTL.m. Converts the input Prob format before calling minos.m and converts back to the output Result structure. This option only handles linear programming problems
minosQPTL	The layer two TOMLAB interface routine that calls minosQPTL.m. Converts the input Prob format before calling minos.m and converts back to the output Result structure. This option only handles quadratic programming problems
lpopt	The layer one Matlab interface routine, calls the MEX-file interface lpopt.dll
lpoptTL	The layer two interface routine called by the TOMLAB driver routine tomRun. This routine then calls lpopt.m.
qpopt	The layer one Matlab interface routine, calls the MEX-file interface qpopt.dll
qpoptTL	The layer two interface routine called by the TOMLAB driver routine tomRun. This routine then calls qpopt.m.
lssol	The layer one Matlab interface routine, calls the MEX-file interface lssol.dll
lssolTL	The layer two interface routine called by the TOMLAB driver routine tomRun. This routine then calls lssol.m.
nlssol	The layer one Matlab interface routine, calls the MEX-file interface nlssol.dll
nlssolTL	The layer two interface routine called by the TOMLAB driver routine tomRun. This routine then calls nlssol.m.
npsol	The layer one Matlab interface routine, calls the MEX-file interface npsol.dll
npsolTL	The layer two interface routine called by the TOMLAB driver routine tomRun. This routine then calls npsol.m.
snopt	The layer one Matlab interface routine, calls the MEX-file interface snopt.dll
snoptTL	The layer two interface routine called by the TOMLAB driver routine tomRun. This routine then calls snopt.m.
sqopt	The layer one Matlab interface routine, calls the MEX-file interface sqopt.dll
sqoptTL	The layer two interface routine called by the TOMLAB driver routine tomRun. This routine then calls sqopt.m.

The SOL control parameters are possible to set from Matlab.

They can be set as inputs to the interface routine minos for example and the others. The user sets fields in a structure called Prob.SOL.optPar, where the subfield names follow the SOL standard for setting solver options. The following example shows how to set the maximum number of iterations.

Prob.SOL.optPar(30)   = 500;    % Setting maximum number of iterations

TOMLAB /SOL Solver Reference

The SOL solvers are a set of Fortran solvers that were developed by the Stanford Systems Optimization Laboratory (SOL). Table lists the solvers included in TOMLAB /SOL. The solvers are called using a set of MEX-file interfaces developed as part of TOMLAB. All functionality of the SOL solvers are available and changeable in the TOMLAB framework in Matlab.

Detailed descriptions of the TOMLAB /SOL solvers are given in the following sections. Also see the M-file help for each solver.

The solvers reference guides for the TOMLAB /SOL solvers are available for download from the TOMLAB home page http://tomopt.com. There is also detailed instruction for using the solvers in Section . Extensive TOMLAB m-file help is also available, for example help snoptTL in Matlab will display the features of the SNOPT solver using the TOMLAB format. TOMLAB /SOL solves nonlinear optimization problems (con) defined as

minx f(x) s/t xL ≤ x ≤ xU, bL ≤ A x ≤ bU cL ≤ c(x) ≤ cU

(1)

where x, x_L, x_U ∈ ℜⁿ, f(x) ∈ ℜ, A ∈ ℜ^{m₁ ×n}, b_L,b_U ∈ ℜ^m₁ and c_L,c(x),c_U ∈ ℜ^m₂. quadratic programming (qp) problems defined as

minx f(x) = 1 2 xT F x + cT x s/t xL ≤ x ≤ xU, bL ≤ A x ≤ bU

(2)

where c, x, x_L, x_U ∈ ℜⁿ, F ∈ ℜ^n×n, A ∈ ℜ^{m₁ ×n}, and b_L,b_U ∈ ℜ^m₁. linear programming (lp) problems defined as

minx f(x) = cT x s/t xL ≤ x ≤ xU, bL ≤ A x ≤ bU

(3)

where c, x, x_L, x_U ∈ ℜⁿ, A ∈ ℜ^m₁×n, and b_L,b_U ∈ ℜ^m₁. linear least squares (lls) problems defined as

minx f(x) = 1 2 || C x − d || s/t xL ≤ x ≤ xU, bL ≤ A x ≤ bU

(4)

where x, x_L, x_U ∈ ℜⁿ, d ∈ ℜ^M, C ∈ ℜ^{M ×n}, A ∈ ℜ^{m₁ ×n}, b_L,b_U ∈ ℜ^m₁. and constrained nonlinear least squares problems defined as

minx f(x) = 1 2 r(x)T r(x) s/t xL ≤ x ≤ xU, bL ≤ A x ≤ bU cL ≤ c(x) ≤ cU

(5)

where x, x_L, x_U ∈ ℜⁿ, r(x) ∈ ℜ^M, A ∈ ℜ^{m₁ ×n}, b_L,b_U ∈ ℜ^m₁ and c_L,c(x),c_U ∈ ℜ^m₂.

Table 3: The SOL optimization solvers in TOMLAB /SOL.

Function	Description	Reference	Page
MINOS 5.5	Sparse linear and nonlinear programming with linear and nonlinear constraints.	[]
LP-MINOS	A special version of the MINOS 5.5 MEX-file interface for sparse linear programming.	[]
QP-MINOS	A special version of the MINOS 5.5 MEX-file interface for sparse quadratic programming.	[]
LPOPT 1.0-10	Dense linear programming.	[]
QPOPT 1.0-10	Non-convex quadratic programming with dense constraint matrix and sparse or dense quadratic matrix.	[]
LSSOL 1.05-4	Dense linear and quadratic programs (convex), and constrained linear least squares problems.	[]
NLSSOL 5.0-2	Constrained nonlinear least squares. NLSSOL is based on NPSOL. No reference except for general NPSOL reference.	[]
NPSOL 5.02	Dense linear and nonlinear programming with linear and nonlinear constraints.	[]
SNOPT 7.1-1	Large, sparse linear and nonlinear programming with linear and nonlinear constraints.	[,]
SQOPT 7.1-1	Sparse convex quadratic programming.	[]

MINOS

Direct Solver Call

A direct solver call is not recommended unless the user is 100 % sure that no other solvers will be used for the problem. Please refer to Section for information on how to use MINOS with TOMLAB.

Purpose

minos solves nonlinear optimization problems defined as

minx f(x) s/t x , bL ≤ A x ≤ bU c(x)

(6)

where x ∈ ℜⁿ, f(x) ∈ ℜ, A ∈ ℜ^{m₁ ×n}, b_L,b_U ∈ ℜ^n+m₁+m₂ and c(x) ∈ ℜ^m₂.

or quadratic optimization problems defined as

minx f(x) = 1 2 xT F x + cT x s/t x , bL ≤ g(x) ≤ bU A x

(7)

where c, x ∈ ℜⁿ, F ∈ ℜ^{n ×n}, A ∈ ℜ^{m₁ ×n}, and b_L,b_U ∈ ℜ^m₁.

The full input matrix A has three parts A = [d/dx g(x); A; c'];

Calling Syntax

The file 'funfdf.m' must be defined and contain: function [mode, f, g] = funfdf(x, Prob, mode, nstate) to compute the objective function f and the gradient g at the point x.

The file 'funcdc.m' must be defined and contain: function [mode ,c ,dcS] = funcdc(x, Prob, mode, nstate) to compute the nonlinear constraint value c and the constraint Jacobian dcS for the nonlinear constraints at the point x.

NOTE: The matrix dcS MUST be a SPARSE MATLAB matrix. Do dcS = sparse(dcS); after dcS has been computed.

[hs, xs, pi, rc, Inform, nS, nInf, sInf, Obj, iwCount, gObj, fCon, gCon] = minos(H, A, bl, bu, nnCon, nnObj, nnJac, Prob, iObj, optPar, Warm, hs, xs, pi, nS, SpecsFile, PrintFile, SummFile, PriLev, ObjAdd, moremem, ProbName );

Description of Inputs

The following fields are used:
The following fields are used:, continued
H	Matrix n x n in a quadratic programming (QP) problem. DENSE or SPARSE. Leave empty if LP, or NLP problem.
A	Constraint matrix, m x n SPARSE (nonlinear, linear and objective) m > 0 always!!! Define dummy constraint for unconstrained problems.
bl	Lower bounds on (x,g(x),Ax,c').
bu	Upper bounds on (x,g(x),Ax,c').
	NOTE! The bl and bu values for the last nonlinear constraint c must have reverse signs and be put in each other places: If cL < = c(x) < = cU , then bl = −cU and bu = −cL. This is because the bounds acts as the constraints on the slack variables for the nonlinear constraints.
nnCon	Number of nonlinear constraints.
nnObj	Number of nonlinear objective variables.
nnJac	Number of nonlinear Jacobian variables.
Prob	Must be a structure. No check is made in the MEX interface. If TOMLAB calls minos, then Prob is the standard TOMLAB problem structure, otherwise the user should set:
	Prob.P = ProblemNumber, where ProblemNumber is some integer.
	If the problem is a LP or QP problem (H defined), the user does not have to specify anything else in the structure.
	For a general nonlinear objective or nonlinear constraints names of two user written routines must be given:
	funfdf, actual name stored in Prob.FUNCS.fg, with syntax [mode, f, g] = funfdf(x, Prob, mode, nstate).
	funcdc, actual name stored in Prob.FUNCS.cdc, with syntax [mode, c, dcS] = funcdc(x, Prob, mode, nstate).
	MINOS is calling the TOMLAB routines nlp_fg.m and nlp_cdcS.m in the callback, and they call funfdf and funcdc, respectively.
	If these fields in Prob are empty (Prob.FUNCS.fg, Prob.FUNCS.cdc), the TOMLAB callback routines calls the usual function routines. Then the Prob struct should be normally defined, and the fields Prob.FUNCS.f, Prob.FUNCS.g, Prob.FUNCS.c, Prob.FUNCS.dc be set in the normal way (e.g. by the routine mFiles.m, or one of the Assign-routines like conAssign.m).
	If the mode parameter is 0, funfdf should return f, otherwise both f and the gradient vector g. If the mode parameter is 0, funcdc should return c, otherwise both c and dcS. Note that each row in dcS corresponds to a constraint, and that dcS must be a SPARSE matrix.
	The user could also write his own versions of the routines nlp_fg.m and nlp_cdcS.m and put them before in the path.
iObj	Says which row of A is a free row containing a linear objective vector c. If there is no such vector, iObj = 0. Otherwise, this row must come after any nonlinear rows, so that nnCon < = iObj < = m.
optPar	Vector with optimization parameters overriding defaults and the optionally specified SPECS file. If using only default options, set optPar as an empty matrix.
Warm	Flag, if true: warm start. Default cold start (if empty). If 'Warm Start' xs, nS and hs must be supplied with correct values.
hs	Basis status of variables + constraints (n+m x 1 vector). State of variables: 0=nonbasic (on bl), 1=nonbasic (on bu) 2=superbasic (between bounds), 3=basic (between bounds).
xs	Initial vector, optionally including m slacks at the end. If warm start, full xs must be supplied.
pi	Lagrangian multipliers for the nnCon nonlinear constraints. If empty, set as 0.
nS	# of superbasics. Only used if calling again with a Warm Start.
SpecsFile	Name of the SPECS input parameter file, see TOMLAB Guide.
PrintFile	Name of the Print file. Name includes the path, maximal number of characters = 500.
SummFile	Name of the Summary file. Name includes the path, maximal number of characters = 500.
PriLev	Printing level in the minos m-file and minos MEX-interface.
	= 0 Silent
	= 1 Summary information
	= 2 More detailed information
ObjAdd	Constant added to the objective for printing purposes, typically 0.
moremem	Add extra memory for the sparse LU, might speed up the optimization. 1E6 is 10MB of memory. If empty, set as 0.
ProbName	Name of the problem. <=100 characters are used in the MEX interface. In the MINOS solver the first 8 characters are used in the printed solution and in some routines that output BASIS files. Blank is OK.

Description of Outputs

The following fields are used:
The following fields are used:, continued
hs	Basis status of variables + constraints (n+m x 1 vector). State of variables: 0=nonbasic (on bl), 1=nonbasic (on bu) 2=superbasic (between bounds), 3=basic (between bounds).
	Basic and superbasic variables may be outside their bounds by as much as the Feasibility tolerance. Note that if scaling is specified, the Feasibility tolerance applies to the variables of the scaled problem. In this case, the variables of the original problem may be as much as 0.1 outside their bounds, but this is unlikely unless the problem is very badly scaled. Check the "Primal infeasibility" printed after the EXIT message.
	Very occasionally some nonbasic variables may be outside their bounds by as much as the Feasibility tolerance, and there may be some nonbasics for which xn(j) lies strictly between its bounds.
	If ninf > 0, some basic and superbasic variables may be outside their bounds by an arbitrary amount (bounded by sinf if scaling was not used).
xs	Solution vector (n+m by 1) with n decision variable values together with the m slack variables.
pi	Lagrangian multipliers (dual solution vector) (m x 1 vector)
rc	Vector of reduced costs, g − ( A I )Tp, where g is the gradient of the objective function if xn is feasible, or the gradient of the Phase-1 objective otherwise. If ninf = 0, the last m entries are −p. Reduced costs vector is of n+m length.
Inform	Result of MINOS run.
	0 Optimal solution found.
	1 The problem is infeasible.
	2 The problem is unbounded (or badly scaled).
	3 Too many iterations.
	4 Apparent stall. The solution has not changed for a large number of iterations (e.g. 1000).
	5 The Superbasics limit is too small.
	6 User requested termination (by returning bad value).
	7 Gradient seems to be giving incorrect derivatives.
	8 Jacobian seems to be giving incorrect derivatives.
	9 The current point cannot be improved.
	10 Numerical error in trying to satisfy the linear constraints (or the linearized nonlinear constraints). The basis is very ill-conditioned.
	11 Cannot find a superbasic to replace a basic variable.
	12 Basis factorization requested twice in a row. Should probably be treated as inform = 9.
	13 Near-optimal solution found. Should probably be treated as inform = 9.
	20 Not enough storage for the basis factorization.
	21 Error in basis package.
	22 The basis is singular after several attempts to factorize it (and add slacks where necessary).
	30 An OLD BASIS file had dimensions that did not match the current problem.
	32 System error. Wrong number of basic variables.
	40 Fatal errors in the MPS file.
	41 Not enough storage to read the MPS file.
	42 Not enough storage to solve the problem.
nS	# of superbasics.
nInf	Number of infeasibilities.
sInf	Sum of infeasibilities.
Obj	Objective function value at optimum.
iwCount	Number of iterations (major and minor), function and constraint calls.
gObj	Gradient of the nonlinear objective.
fCon	Nonlinear constraint vector.
gCon	Gradient vector (non-zeros) of the nonlinear constraint vector.