TOMLAB Utility Functions: Difference between revisions
m (moved TOMLAB Manual Utility Functions to TOMLAB Utility Functions) |
No edit summary |
||
Line 3: | Line 3: | ||
{{cleanup|Clean this article. Remove references.}} | {{cleanup|Clean this article. Remove references.}} | ||
{{Part Of Manual|title=the TOMLAB Manual|link=[[TOMLAB Manual]]}} | {{Part Of Manual|title=the TOMLAB Manual|link=[[TOMLAB|TOMLAB Manual]]}} | ||
=TOMLAB Utility Functions= | =TOMLAB Utility Functions= |
Revision as of 10:48, 8 July 2011
{{#switch:
| left =
| #default =
}} {{#if:{{#if: | {{{smallimageright}}} | }} | {{#ifeq:{{#if: | {{{smallimageright}}} | }}|none | | }} }}{{
#switch:left | left =| #default = }} {{#if:{{#if: | {{{smallimage}}} | }} | {{#if: | {{{smallimage}}} | }} | [[File:{{#switch:caution | critical = Ambox speedy deletion.png | important = Ambox deletion.png | warning = Ambox content.png | caution = Cleanup.png | move = Ambox move.png | protection = Ambox protection.png | notice | #default = Cleanup.png }} | {{#switch:left | left = 20x20px | #default = 40x40px }} |link=|alt=]] }}{{#switch:left | left =| #default = | {{#if:
| {{{smalltext}}} | Cleanup is needed}} | {{#switch:left
| left = {{#if: | {{{smallimageright}}} | }}| #default = {{#if:
}}| {{{smallimageright}}} |}} |
| #default =
{{#switch: | none =| #default =
}}{{#if: | {{#ifeq:|none
|| }} }}
{{
#switch: | left =| #default = }} {{#if: | | [[File:{{#switch:caution | critical = Ambox speedy deletion.png | important = Ambox deletion.png | warning = Ambox content.png | caution = Cleanup.png | move = Ambox move.png | protection = Ambox protection.png | notice | #default = Cleanup.png }} | {{#switch: | left = 20x20px | #default = 40x40px }} |link=|alt=]] }}{{#switch: | left =| #default = | Cleanup is needed Clean this article. Remove references. |
{{#switch:
| left =| #default = |
}}
This page is part of the TOMLAB Manual. See TOMLAB Manual. |
TOMLAB Utility Functions
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 Table 134, page 220. |
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 Section 12.12 page 199. |
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 Table 149. |
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
where Failed to parse (unknown function "\MATHSET"): {\displaystyle x,x_{L},x_{U}\in \MATHSET{R}^{n}}
, Failed to parse (unknown function "\MATHSET"): {\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
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
where the first meq constraints are equalities.
If TransType = 3 the program is transformed into the form
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.
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
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 Table 140. | ||
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. See \[7\] for a more detailed presentation.
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 Syntax
[SolvList, SolvTypeList, SolvDriver] = SolverList(solvType)
Description of Inputs
solvType | Either a string 'uc', 'con' etc. or the corresponding solvType number. See Table 1. |
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