TOMLAB Appendix E

This page is part of the TOMLAB Manual. See TOMLAB Manual.

External Interfaces

Some users may have been used to work with MathWorks Optimization Toolbox, or have code written for use with these toolboxes. For that reason TOMLAB contains interfaces to simplify the transfer of code to TOMLAB. There are two ways in which the MathWorks Optimization Toolbox may be used in TOMLAB. One way is to use the same type of call to the main solvers as in MathWorks Optimization TB, but the solution is obtained by converting the problem into the TOMLAB format and calling a TOMLAB solver. The other way is to formulate the problem in any of the TOMLAB formats, but when solving the problem calling the driver routine with the name of the Optimization Toolbox solver. Which way to use is determined by setting if 0 or if 1 in startup.m in the addpath for the variable OPTIM. If setting if 1 then the TOMLAB versions are put first and MathWorks Optimization TB is not accessible.

Solver Call Compatible with Optimization Toolbox

TOMLAB is call compatible with MathWorks Optimization TB. This means that the same syntax could be used, but the solver is a TOMLAB solver instead. TOMLAB normally adds one extra input, the Prob structure, and one extra output argument, the Result structure. Both extra parameters are optional, but if the user are adding extra input arguments in his call to the MathWorks Optimization TB solver, to use the TOMLAB equivalents, the extra input must be shifted one step right, and the variable Prob be put first among the extra arguments. #Table: Call compatible interfaces to MathWorks Optimization TB. gives a list of the solvers with compatible interfaces.

Table: Call compatible interfaces to MathWorks Optimization TB.

Function	Type of problem solved
bintprog	Binary programming.
fmincon	Constrained minimization.
fminsearch	Unconstrained minimization using Nelder-Mead type simplex search method.
fminunc	Unconstrained minimization using gradient search.
linprog	Linear programming.
lsqcurvefit	Nonlinear least squares curve fitting.
lsqlin	Linear least squares.
lsqnonlin	Linear least squares with nonnegative variable constraints.
lsqnonneg	Nonlinear least squares.
quadprog	Quadratic programming.

In #Table: Testroutines for the call compatible interfaces to MathWorks Optimization TB present in the examples directory in the TOMLAB distribution. a list is given with the demonstration files available in the directory examples that exemplify the usage of the call compatible interfaces. In the next sections the usage of some of the solvers are further discussed and exemplified.

Solving LP Similar to Optimization Toolbox

For linear programs the MathWorks Optimization TB solver is linprog. The TOMLAB linprog solver adds one extra input argument, the Prob structure, and one extra output argument, the Result structure. Both extra parameters are optional, but means that the additional functionality of the TOMLAB LP solver is accessible.

An example of the use of the TOMLAB linprog solver to solve test problem (13) illustrates the basic usage

Table: Testroutines for the call compatible interfaces to MathWorks Optimization TB present in the examples directory in the TOMLAB distribution.

Function	Type of problem solved
testbintprog	Test of binary programming.
testfmincon	Test of constrained minimization.
testfminsearch	Test of unconstrained minimization using a Nelder-Mead type simplex search method.
testfminunc	Test of unconstrained minimization using gradient search.
testlinprog	Test of linear programming.
testlsqcurvefit	Test of nonlinear least squares curve fitting.
testlsqlin	Test of linear least squares.
testlsqnonlin	Test of linear least squares with nonnegative variable constraints.
testlsqnonneg	Test of nonlinear least squares.
testquadprog	Test of quadratic programming.

File: tomlab/usersguide/lpTest2.m

lpExample;

% linprog needs linear inequalities and equalities to  be given  separately
% If the  problem  has both  linear inequalities (only upper  bounded)
% and equalities we  can easily detect which  ones doing  the  following calls

ix = b_L==b_U; 
E = find(ix);
I = find(~ix);

[x, fVal, ExitFlag, Out,  Lambda] = linprog(c, A(I,:),b_U(I),...
    A(E,:), b_U(E),  x_L,  x_U, x_0);

% If the  problem  has linear inequalites with  different lower  and upper  bounds
% the  problem  can be transformed using  the  TOMLAB  routine  cpTransf.
% See the  example file tomlab\examples\testlinprog.m for  an example.

fprintf('n');
fprintf('n');
disp('Run TOMLAB linprog on LP Example');
fprintf('n');
xprinte(A*x-b_U,               'Constraints Ax-b_U '); 
xprinte(Lambda.lower,    'Lambda.lower:    '); 
xprinte(Lambda.upper,    'Lambda.upper:    '); 
xprinte(Lambda.eqlin,    'Lambda.eqlin:    '); 
xprinte(Lambda.ineqlin,  'Lambda.ineqlin:  '); 
xprinte(x,                'x:              '); 
format  compact
disp('Output Structure')
disp(Out)
fprintf('Function value  %30.20f.  ExitFlag %d\n',fVal,ExitFlag);

The results from this test show the same results as previous runs in Section 5, because the same solver is called.

File: tomlab/usersguide/lpTest2.out

linprog (CPLEX): Optimization terminated successfully

Run TOMLAB  linprog on LP Example

Constraints Ax-b_U    0.000000e+000   0.000000e+000
Lambda.lower:         0.000000e+000   0.000000e+000
Lambda.upper:         0.000000e+000   0.000000e+000
Lambda.eqlin:
Lambda.ineqlin:	     -1.857143e+000   -1.285714e+000 
x:	              2.571429e+000    1.714286e+000
Output  Structure 
       iterations: 2
       algorithm: 'CPLEX: CPLEX  Dual Simplex  LP solver'
     cgiterations: 0
Function value       -26.57142857142857300000. ExitFlag 1

Solving QP Similar to Optimization Toolbox

For quadratic programs the MathWorks Optimization TB solver is quadprog. The TOMLAB quadprog solver adds one extra input argument, the Prob structure, and one extra output argument, the Result structure. Both extra parameters are optional, but means that the additional functionality of the TOMLAB QP solver is accessible.

An example of the use of the TOMLAB quadprog solver to solve test problem (15) illustrates the basic usage

File: tomlab/usersguide/qpTest2.m

qpExample;

% quadprog needs linear equalities and equalities to  be given  separately
% If the  problem  has both  linear inequalities (only upper  bounded)
% and equalities we  can easily detect which  ones doing  the  following calls

ix = b_L==b_U; 
E  = find(ix);
I  = find(~ix);

[x, fVal, ExitFlag, Out,  Lambda] = quadprog(F,  c, A(I,:),b_U(I),...
    A(E,:), b_U(E),  x_L,  x_U, x_0);

% If A  has linear inequalites with  different lower  and upper  bounds
% the  problem  can be transformed using  the  TOMLAB  routine  cpTransf.
% See the  example file tomlab\examples\testquadprog.m for  an example.

fprintf('\n');
fprintf('\n');
disp('Run TOMLAB  quadprog on QP  Example');
fprintf('\n');
xprinte(A*x-b_U,            'Constraints Ax-b_U ');
xprinte(Lambda.lower,        'Lambda.lower:      '); 
xprinte(Lambda.upper,        'Lambda.upper:      '); 
xprinte(Lambda.eqlin,        'Lambda.eqlin:      '); 
xprinte(Lambda.ineqlin,      'Lambda.ineqlin:    '); 
xprinte(x,                   'x:                 '); 
format  compact
disp('Output Structure')
disp(Out)
fprintf('Function value %30.20f. ExitFlag %d\n',fVal,ExitFlag);

The restricted problem formulation in MathWorks Optimization TB sometimes makes it necessary to transform the problem. See the comments in the above example and the test problem file tomlab/examples/testquadprog.m. The results from this test show the same results as previous runs

File: tomlab/usersguide/qpTest2.out

Run TOMLAB  quadprog on QP  Example

Constraints Ax-b_U   -4.888889e+000   0.000000e+000
Lambda.lower:         0.000000e+000   0.000000e+000
Lambda.upper:         0.000000e+000   0.000000e+000
Lambda.eqlin:        -3.500000e+000
Lambda.ineqlin:      -5.102800e-016
x:                    5.555556e-002   5.555556e-002
Output  Structure 
        iterations: 1
         algorithm: 'qpopt: QPOPT  1.0  QP/LP code'
      cgiterations: []
     firstorderopt: []
Function value         -0.02777777777777779000. ExitFlag 1

The Matlab Optimization Toolbox Interface

Included in TOMLAB is an interface to a number of the solvers in the MathWorks Optimization TB v1.5. and MathWorks Optimization TB. The solvers that are directly possible to use, when a problem is generated in the TOMLAB format, are listed in #Table: Optimization toolbox routines with a TOMLAB interface.. The user must of course have a valid license. The TOMLAB interface routines are opt15Run and opt20Run, but the user does not need to call these directly, but can use the standard multi-solver driver interface routine tomRun.

Several low-level interface routines have been written. For example, the constr solver needs both the objective function and the vector of constraint functions in the same call, which nlp fc supplies. Also the gradient vector and the matrix of constraint normals should be supplied in one call. These parameters are returned by the routine nlp gdc.

MathWorks Optimization TB v1.5 is using a parameter vector OPTIONS of length 18, that the routine foptions is setting up the default values for. MathWorks Optimization TB is instead using a structure.

Table: Optimization toolbox routines with a TOMLAB interface.

Function	Type of problem solved
bintprog	Binary programming.
fmincon	Constrained minimization.
fminsearch	Unconstrained minimization using Nelder-Mead type simplex search method.
fminunc	Unconstrained minimization using gradient search.
linprog	Linear programming.
lsqcurvefit	Nonlinear least squares curve fitting.
lsqlin	Linear least squares.
lsqnonlin	Linear least squares with nonnegative variable constraints.
lsqnonneg	Nonlinear least squares.
quadprog	Quadratic programming.
constr	Constrained minimization.
fmins	Unconstrained minimization using Nelder-Mead type simplex search method.
fminu	Unconstrained minimization using gradient search.
leastsq	Nonlinear least squares.
lp	Linear programming.
qp	Quadratic programming.

The AMPL Interface

The AMPL interface is described in a separate manual. Enter help amplAssign in MATLAB to see the function­ality.