TOMLAB Utility Functions

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

In the following subsections the driver routine and the utility functions in TOMLAB will be described.

tomRun

Purpose

General multi-solver driver routine for TOMLAB.

Calling Syntax

Result = tomRun(Solver, Prob, PriLev, ask)	Call Solver on the problem defined in structure Prob
Result = tomRun(Solver, probFile, probNumber, Prob, PriLev, ask)	Call Solver on problem probNumber in Init File probFile.m
Result = tomRun(Solver, probType, probNumber, PriLev, ask)	Call Solver on problem number probNumber in the default Init File for problem type probType
tomRun(probType)	Display all solvers for probType
tomRun	Display all available solvers for all problem types

Description of Inputs

Solver	The name of the solver that should be used to optimize the problem. If the solver may run several different optimization algorithms, then the values of Prob.Solver.Alg and Prob.optParam.Method determines which algorithm and method to be used.
Prob	Problem description structure, see TOMLAB Appendix A.
ask	Flag if questions should be asked during problem definition. ask < 0 Use values in uP if defined or defaults. ask = 0 Use defaults. ask = 1 Ask questions in probFile. ask = [] If uP = [], ask = -1, else ask = 0.
PriLev	Print level when displaying the result of the optimization in the routine PrintResult. See addPwLinFun. PriLev = 0 No output. PriLev = 1 Final result, shorter version. PriLev = 2 Final result. PriLev = 3 Full results. The printing level in the optimization solver is controlled by setting the parameter Prob.PriLevOpt.
probFile	User problem Init File.
probNumber	Problem number in probFile. probNumber = 0 gives a menu in probFile.

Description of Outputs

Result

Structure with result from optimization, see TOMLAB Appendix A.

Description

The driver routine tomRun is called from the command line. If called with less than the required two parameters, a list of available solvers are printed.

M-files Used

PrintResult.m, probInit.m, mkbound.m

addPwLinFun

Purpose

Adds piecewise linear function to a TOMLAB MIP problem.

Calling Syntax

There are two ways to call addPwLinFun:

Syntax 1: function Prob = addPwLinFun(Prob, 1, type, var, funVar, point, slope, a, fa)

Syntax 2: function Prob = addPwLinFun(Prob, 2, type, var, funVar, firstSlope, point, value, lastSlope)

Description of Inputs

Prob	The problem to add the function to.
input	Flag indicating syntax used.
type	A string telling whether to construct a general MIP problem or to construct an MIP problem only solvable by CPLEX. Possible values: 'mip', 'cplex'.
var	The number of the variable on which the piecewise linear function depends. Must exist in the problem already.
funVar	The number of the variable which will be equal to the piecewise linear function. Must exist in the problem already.
firstSlope	Syntax 2 only. The slope of the piecewise linear function left of the first point, point(1).
point	An array of break points. Must be sorted. If two values occur twice, there is a step at that point. Length r.
slope	Syntax 1 only. An array of the slopes of the segments. slope(i) is the slope between point(i-1) and point(i). slope(1) is the slope of the function left of point(1). slope(r+1) is the slope of the function right of point(r). If points(i-1) == points(i), slope(i) is the height of the step.
value	Syntax 2 only. The values of the piecewise linear function at the points given in point. f(point(i)) = value(i). If point(i-1) == point(i), value(i-1) is the right limit of the value at the point, and value(i) is the left limit of the value at the point.
lastSlope	Syntax 2 only. The slope of the piecewise linear function right of the last point, point(r).
a, fa	Syntax 1 only. The value of the piecewise linear function at point a is equal to fa. f(a) = fa, that is.

Description of Outputs

Prob The new problem structure with the piecewise linear function added. New variables and linear constraints added. (MIP problem)

Description

This function will make one already existing variable of the problem to be constrained equal to a piecewise linear function of another already existing variable in the problem. The independent variable must be bounded in both directions.

The variable constrained to be equal to a piecewise linear function can be used like any other variable; in constraints or the objective function.

Depending on how many segments the function consists of, a number of new variables and constraints are added to the problem.

Increasing the upper bound (x U) or decreasing the lower bound (x L) of the independent variable after calling this function will ruin the piecewise linear function.

If the problem is to be solved by CPLEX, set type = 'cplex' to enhance performance. Otherwise, let type = 'mip'. NOTICE! You can not solve a problem with another solver than CPLEX if type = 'cplex'.

binbin2lin

Purpose

Adds constraints when modeling with binary variables which is the product of two other variables.

Calling Syntax

Prob = binbin2lin(Prob, idx4, idx1, idx2, idx3)

Description of Inputs

Prob	Problem structure to be converted.
idx4	Indices for b4 variables.
idx1	Indices for b1 variables.
idx2	Indices for b2 variables.
idx3	Indices for b3 variables.

Description of Outputs

Prob	Problem structure with added constraints.

Description

b4 = b1 * b2. The problem should be built with the extra variable b4 in place of the b1*b2 products. The indices of the unique product variables are needed to convert the problem properly.

Three inequalities are added to the problem:

b4 <= b1 b4 <= b2 b4 >= b1 + b2 - 1

By adding this b4 will always be the product of b1 and b2.

The routine also handles products of three binary variables. b4 = b1 * b2 * b3. The following constraints are then added:

b4 <= b1 b4 <= b2 b4 <= b3 b4 >= b1 + b2 + b3 - 1

bincont2lin

Purpose

Adds constraints when modeling with binary variables which are multiplied by integer or continuous variables. This is the most efficient way to get rid off quadratic objectives or constraints.

Calling Syntax

Prob = bincont2lin(Prob, idx prod, idx bin, idx cont)

Description of Inputs

Prob	Problem structure to be converted.
idx prod	Indices for product variables.
idx bin	Indices for binary variables.
idx cont	Indices for continuous/integer variables.

Description of Outputs

Prob	Problem structure with added constraints.

Description

prod = bin * cont. The problem should be built with the extra variables prod in place of the bin * cont products. The indices of the unique product variables are needed to convert the problem properly.

Three inequalities are added to the problem:

prod <= cont prod >= cont - xU * (1 - bin) prod <= xU * bin

By adding this prod will always equal bin * cont.

checkFuncs

Purpose

TOMLAB routine for verifying user supplied routines. The routine could be used for general debugging.

Calling Syntax

exitFlag = checkFuncs(Prob, Solver, PriLev)

Description of Inputs

Prob	Problem structure created with assign routine.
Solver	Solver that will be used. For example 'knitro' (default).
PriLev	0 - suppress warnings (info), 1 - full printing (default).

Description of Outputs

exitFlag

0 if no errors.

checkDerivs

Purpose

TOMLAB routine for verifying derivatives of user supplied routines.

Calling Syntax

[exitFlag,output] = checkDerivs(Prob, x k, PriLev, ObjDerLev, ConsDerLev, AbsTol)

Description of Inputs

Prob	Problem structure created with assign routine.
x_k	Point the check derivatives for. Default x 0 or (xL + xU )/2. x L and x U have to be within 1e5.
PriLev	Print Level, default 1. (0-1 valid).
ObjDerLev	Depth for objective derivative check, 1 - checks gradient, 2 checks gradient and Hessian. Default 2 or level of derivatives supplied.
ConsDerLev	Depth for constraint derivative check, 1 - checks Jacobian, 2 checks Jacobian and 2nd part of the Hessian to the Lagrangian function. Default 2 or level of derivatives supplied.
AbsTol	Absolute tolerance for errors. Default [1e-5 1e-3 1e-4 1e-3 1e-4] (g H dc d2c J).

Description of Outputs

exitFlag	If exitFlag = 0 a problem exist. See output for more information. Binary indicates where problem is: 01011. 1 + 2 + 8 = 13. Problems everywhere but 'dc', 'J'. 11111 = 'J' 'd2c' 'dc' 'H' 'g'.
output	Structure containing analysis information.
	g,H,dc,d2c,J Structure with results.
	minErr: The smallest error.
	avgErr: The average error.
	maxErr: The largest error.
	idx: Index for elements with errors.
	exitFlag: 1 if problem with the function.

See Also

runtest

cpTransf

Purpose

Transform general convex programs on the form

${\begin{array}{cccccl}\min \limits _{x}&f(x)&&&&\\s/t&x_{L}&\leq &x&\leq &x_{U}\\&b_{L}&\leq &Ax&\leq &b_{U}\\\end{array}}$

where Failed to parse (SVG with PNG fallback (MathML can be enabled via browser plugin): Invalid response ("Math extension cannot connect to Restbase.") from server "https://wikimedia.org/api/rest_v1/":): {\displaystyle x,x_{L},x_{U}\in \MATHSET{R}^{n}} , Failed to parse (SVG with PNG fallback (MathML can be enabled via browser plugin): Invalid response ("Math extension cannot connect to Restbase.") from server "https://wikimedia.org/api/rest_v1/":): {\displaystyle A\in \MATHSET{R}^{m\times n}} and Failed to parse (unknown function "\MATHSET"): {\displaystyle b_{L},b_{U} \in \MATHSET{R}^{m}} , to other forms.

Calling Syntax

[AA, bb, meq] = cpTransf(Prob, TransfType, makeEQ, LowInf)

Description of Inputs

Prob	Problem description structure. The following fields are used:
	QP.c Constant vector c in cT x.
	A Constraint matrix for linear constraints.
	b_L Lower bounds on the linear constraints.
	b U Upper bounds on the linear constraints.
	x_L Lower bounds on the variables.
	x_U Upper bounds on the variables.
TransfType	Type of transformation, see the description below.
MakeEQ	Flag, if set true, make standard form (all equalities).
LowInf	LowI nf \| are limit if upper bound variables are to be used.

Description of Outputs

AA	The expanded linear constraint matrix.
bb	The expanded upper bounds for the linear constraints.
meq	The first meq equations are equalities.

Description

If TransType = 1 the program is transformed into the form

${\begin{array}{cccc}\min \limits _{x}&f(x-x_{L})&&\\s/t&AA(x-x_{L})&\leq &bb\\&x-x_{L}&\geq &0\\\end{array}}$

where the first meq constraints are equalities. Translate back with (fixed variables do not change their values):

x(~x_L==x_U) = (x-x_L) + x_L(~x_L==x_U)

If TransType = 2 the program is transformed into the form

${\begin{array}{cccccl}\min \limits _{x}&f(x)&&\\s/t&&&AA(x)&\leq &bb\\&x_{L}&\leq &x&\leq &x_{U}\\\end{array}}$

where the first meq constraints are equalities.

If TransType = 3 the program is transformed into the form

${\begin{array}{cccc}\min \limits _{x}&f(x)&&\\s/t&AAx&\leq &bb\\&x&\geq &x_{L}\\\end{array}}$

where the first meqconstraints are equalities.

estBestHessian

Purpose

estBestHessian estimates the best Hessian. Result.x k(:,1) will be used for the estimation. The best step-size is estimated by TOMLAB. If the gradient is given it will be used. The analytical hessian is returned if given.

Calling Syntax

[g k, H k] = estBestHessian(Result);

Description of Inputs

Result

Problem structure to be converted.

Description of Outputs

g_k	The gradient at Result.x k(:,1).
H_k	Hessian of the objective at Result.x k(:,1).

lls2qp

Purpose

Converts an lls problem to a new problem based on the formula below. Only the objective function is affected. The problem can be of any type with an LLS objective.

${\begin{array}{lc}\min \limits _{x}&f(x)={\frac {1}{2}}||Cx-d||=\\&0.5*(y-Cx)'*(y-Cx)=0.5*(y'y-2y'Cx+x'C'Cx)=\\&0.5*y'y+0.5*x'Fx+c'x\\\\&F=C'C\\&c'=-y'C\\&const={\frac {1}{2}}y'y\\\end{array}}$

Calling Syntax

qpProb = lls2qp(Prob, IntVars)

Description of Inputs

Prob.LS.C	The linear matrix in 0.5 * ||y - C_x||.
Prob.LS.y	The constant vector in 0.5 * ||y - C_x||.

Description of Outputs

qpProb

The converted problem.

Description

If the problem is a linear least squares problem a qp problem is created. The new problem may have integer variables. Create the problem with llsAssign then use this routine.

If the problem has nonlinear constraints an nlp is created. The new problem may have integer variables. Create the problem with conAssign or minlpAssign, the set the fields Prob.LS.C and Prob.LS.y

LineSearch

Purpose

LineSearch solves line search problems of the form

$\min \limits _{0<\alpha _{\min }\leq \alpha \leq \alpha _{\max }}f(x^{(k)}+\alpha p)$

where Failed to parse (unknown function "\MATHSET"): {\displaystyle x, p \in \MATHSET{R}^{n}} .

Calling Syntax

Result = LineSearch(f, g, x, p, f 0, g 0, LineParam, alphaMax, pType, PriLev, varargin)

Description of Inputs

f	Name of m-file computing the objective function f (x).
g	Name of m-file computing the gradient vector g(x).
x	Current iterate x.
p	Search direction p.
f_0	Function value at a = 0.
g_0	Gradient at a = 0, the directed derivative at the present point.
LineParam	Structure with line search parameters 140, the following fields are used:
	LineAlg	Type of line search algorithm, 0 = quadratic interpolation, 1 = cubic interpolation.
	fLowBnd	Lower bound on the function value at optimum.
		sigma InitStepLength rho tau1 tau2 tau3 eps1 eps2 see TOMLAB Appendix A.
alphaMax	Maximal value of step length a.
pType	Type of problem:
	0	Normal problem.
	1	Nonlinear least squares.
	2	Constrained nonlinear least squares.
	3	Merit function minimization.
	4	Penalty function minimization.
PriLev	Printing level:
	PriLev > 0	Writes a lot of output in LineSearch.
	PriLev > 3	Writes a lot of output in intpol2 and intpol3.
varargin	Other parameters directly sent to low level routines.

Description of Outputs

Result	Result structure with fields:
	alpha	Optimal line search step a.
	f_alpha	Optimal function value at line search step a.
	g_alpha	Optimal gradient value at line search step a.
	alphaVec	Vector of trial step length values.
	r_k	Residual vector if Least Squares problem, otherwise empty.
	J_k	Jacobian matrix if Least Squares problem, otherwise empty.
	f_k	Function value at x + ap.
	g_k	Gradient value at x + ap.
	c_k	Constraint value at x + ap.
	dc_k	Constraint gradient value at x + ap.

Description

The function LineSearch together with the routines intpol2 and intpol3 implements a modified version of a line search algorithm by Fletcher [20]. The algorithm is based on the Wolfe-Powell conditions and therefore the availability of first order derivatives is an obvious demand. It is also assumed that the user is able to supply a lower bound fLow on f (a). More precisely it is assumed that the user is prepared to accept any value of f (a) for which f (a) = fLow . For example in a nonlinear least squares problem fLow = 0 would be appropriate.

LineSearch consists of two parts, the bracketing phase and the sectioning phase. In the bracketing phase the iterates a(k) moves out in an increasingly large jumps until either f = fLow is detected or a bracket on an interval of acceptable points is located. The sectioning phase generates a sequence of brackets ra(k) , b(k) l whose lengths tend to zero. Each iteration pick a new point a(k) in ra(k) , b(k) l by minimizing a quadratic or a cubic polynomial which interpolates f a(k) ), f 1 a(k) ), f b(k) ) and f 1 b(k) ) if it is known. The sectioning phase terminates when a(k) is an acceptable point.

preSolve

Purpose

Simplify the structure of the constraints and the variable bounds in a linear constrained program.

Calling Syntax

Prob = preSolve(Prob)

Description of Inputs

Prob	Problem description structure. The following fields are used:
	A	Constraint matrix for linear constraints.
	b_L	Lower bounds on the linear constraints.
	b_U	Upper bounds on the linear constraints.
	x_L	Lower bounds on the variables.
	x_U	Upper bounds on the variables.

Description of Outputs

Prob	Problem description structure. The following fields are changed:
	A	Constraint matrix for linear constraints.
	b_L	Lower bounds on the linear constraints, set to N aN for redundant constraints.
	b_U	Upper bounds on the linear constraints, set to N aN for redundant constraints.
	x_L	Lower bounds on the variables.
	x_U	Upper bounds on the variables.

Description

The routine preSolve is an implementation of those presolve analysis techniques described by Gondzio in [36], which is applicable to general linear constrained problems.

preSolve consists of the two routines clean and mksp. They are called in the sequence clean, mksp, clean. The second call to clean is skipped if the mksp routine could not remove a single nonzero entry from A.

clean consists of two routines, r rw sng that removes singleton rows and el cnsts that improves variable bounds and uses them to eliminate redundant and forcing constraints. Both r rw sng and el cnsts check if empty rows appear and eliminate them if so. That is handled by the routine emptyrow. In clean the calls to r rw sng and el cnsts are repeated (in given order) until no further reduction is obtained.

Note that rows are actually not deleted or removed, instead preSolve indicates that constraint i is redundant by setting b L(i) = b U (i) = N aN and leaves to the calling routine to decide what to do with those constraints.

PrintResult

Purpose

Prints the result of an optimization.

Calling Syntax

PrintResult(Result, PriLev)

Description of Inputs

Result	Result structure from optimization.
PriLev	Printing level: (default 3)
	0	Silent.
	1	Problem number and name.
		Function value at the solution and at start.
		Known optimal function value (if given).
	2	As PriLev =1 and:
		Optimal point x and starting point x 0.
		Number of evaluations of the function, gradient etc.
		Lagrange multipliers, both returned and TOMLAB estimate.
		Distance from start to solution.
		The residual, gradient and projected gradient. (*)
		ExitFlag and Inform.
		(*) The calculation and output of these fields is controlled by
		Result.Prob.PrintLM.
	3	As PriLev =2 and:
		Jacobian, Hessian or Quasi-Newton Hessian approximation.

Global Parameters Used

To avoid too many variables, constraints and residuals in the output, three global variables are limiting the number printed:

MAX_x	Maximum number of variables
MAX_c	Maximum number of constraints
MAX_r	Maximum number of residuals in least squares problems
Example:	To increase the number of variables printed by PrintResult to 50, do
	global MAX_x MAX_x = 50; PrintResult(Result);

runtest

Purpose

Run all selected problems defined in a problem file for a given solver.

Calling Syntax

runtest(Solver, SolverAlg, probFile, probNumbs, PriLevOpt, wait, PriLev)

Description of Inputs

Solver	Name of solver, default conSolve.
SolverAlg	A vector of numbers defining which of the Solver algorithms to try. For each element in SolverAlg, all probNumbs are solved. Leave empty, or set 0 if to use the default algorithm.
probFile	Problem definition file. probFile is by default set to con prob if Solver is conSolve, uc prob if Solver is ucSolve and so on.
probNumbs	A vector with problem numbers to run. If empty, run all problems in probFile.
PriLevOpt	Printing level in Solver. Default 2, short information from each iteration.
wait	Set wait to 1 if pause after each problem. Default 1.
PriLev	Printing level in PrintResult. Default 5, full information.

´===M-files Used===

SolverList.m

See Also

systest

SolverList

Purpose

Prints the available solvers for a certain solvType.

Calling Synta

[SolvList, SolvTypeList, SolvDriver] = SolverList(solvType)

Description of Inputs

solvType

Either a string 'uc', 'con' etc. or the corresponding solvType number. See table in TOMLAB Overall Design.

Description of Outputs

SolvList	String matrix with the names of the solvers for the given solvType.
SolvTypeList	Integer vector with the solvType for each of the solvers.
SolvDriver	String matrix with the names of the driver routine for each different solvType.

Description

The routine SolverList prints all available solvers for a given solvType, including Fortran, C and Matlab Optimiza- tion Toolbox solvers. If solvType is not specified then SolverList lists all available solvers for all different solvType. The input argument could either be a string such as 'uc', 'con' etc. or a number corresponding to the type of solver, see Table 1.

Examples

See Section 3.

M-files Used

SolverList.m

StatLS

Purpose

Compute parameter statistics for least squares problems.

Calling Syntax

LS = StatLS(x k, r k, J k);

Description of Inputs

x_k	Optimal parameter vector, length n.
r_k	Residual vector, length m.
J_k	Jacobian matrix, length m by n.

Description of Outputs

Structure LS with fields:

SSQ	Sum of squares: r1 * rk
covar	Covariance matrix: Inverse of J' * diag(1./(r'k * rk ))* J
sigma2	Estimate squared standard deviation of problem, SSQ / Degrees of freedom, i.e. SSQ/(m-n)
Corr	Correlation matrix: Normalized Covariance matrix
	Cov./(C ovDiag * CovDiag'), where CovDiag = sqrt(diag(Cov))
StdDev	Estimated standard deviation in parameters: C ovDiag * sqrt(sigma2)
x	=x_k, the input x
ConfLim	95 % Confidence limit (roughly) assuming normal distribution of errors Conf Lim = 2 * LS.StdDev
CoeffVar	The coefficients of variation of estimates: StdDev./xk

systest

Purpose

Run big test to check for bugs in TOMLAB.

Calling Syntax

systest(solvTypes, PriLevOpt, PriLev, wait)

Description of Inputs

solvTypes	A vector of numbers defining which solvType to test.
PriLevOpt	Printing level in the solver. Default 2, short information from each iteration.
wait	Set wait to 1 if pause after each problem. Default 1.
PriLev	Printing level in PrintResult. Default 5, full information.

See Also

runtest