« Previous « Start » Next »
12 TOMLAB Utility Functions
In the following subsections the driver routine and the utility
functions in TOMLAB will be described.
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. |
| |
| |
| 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.11. |
| |
| |
| 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
B. |
Description
The driver routine
tomRun is called from the command line,
or called from the menu routine
tomMenu or from the
graphical user interface
tomGUI to solve any problem
defined in the TOMLAB format or TOMLAB Init File format.
If called with less than the required two parameters, a list of
available solvers are printed.
M-files Used
xxxRun.m ,
xxxRun2.m ,
PrintResult.m ,
probInit.m ,
mkbound.m
12.2 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
12.3 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.
12.4 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
12.5 checkDerivs
Purpose
TOMLAB routine for verifying derivatives of user supplied routines.
Calling Syntax
= 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: 0 1 0 1 1.
1+2+8 = 13. Problems everywhere but 'dc', 'J'. 1 1 1 1 1 = '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
12.6 cpTransf
Purpose
Transform general convex programs on the form
|
|
|
f(x) |
|
|
|
|
| s/t |
xL |
≤ |
x |
≤ |
xU |
| |
bL |
≤ |
Ax |
≤ |
bU |
|
where
x,
xL,
xU
Rn,
A Rm× n
and
bL,
bU Rm, to other forms.
Calling Syntax
= cpTransf(Prob, TransfType, makeEQ, LowInf)
Description of Inputs
| Prob |
Problem description structure.
The following fields are used:
| QP.c |
Constant vector c in cTx. |
| 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 |
Variables equal to −Inf or variables <LowInf are
set to LowInf before transforming the problem.
Default −10−4. |LowInf | 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
|
|
|
f(x−xL) |
|
|
| s/t |
AA(x−xL) |
≤ |
bb |
| |
x−xL |
≥ |
0 |
|
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
|
|
|
f(x) |
|
|
| s/t |
|
|
AA(x) |
≤ |
bb |
| |
xL |
≤ |
x |
≤ |
xU |
|
where the first
meq constraints are equalities.
If
TransType=3 the program is transformed into the form
|
|
|
f(x) |
|
|
| s/t |
AA x |
≤ |
bb |
| |
x |
≥ |
xL |
|
where the first
meq constraints are equalities.
12.7 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
= 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). |
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.
|
|
|
|
| |
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 |
| |
|
| |
|
(21) |
qpProb = lls2qp(Prob, IntVars)
Description of Inputs
| Prob.LS.C |
The linear matrix in 0.5 * ||y − Cx||. |
| Prob.LS.y |
The constant vector in 0.5 * ||y − Cx||. |
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
12.9 LineSearch
Purpose
LineSearch solves line search problems of the form
where
x,
p Rn.
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 α=0. |
| g_0 |
Gradient at α=0, the directed derivative at the
present point. |
| LineParam |
Structure with line search
parameters 19,
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 19. |
|
| alphaMax |
Maximal value of step length α. |
| 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 α. |
| f_alpha |
Optimal function value at line search step
α. |
| g_alpha |
Optimal gradient value at line search step
α. |
| 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+α p. |
| g_k |
Gradient value at x+α p. |
| c_k |
Constraint value at x+α p. |
| dc_k |
Constraint gradient value at x+α p. |
|
Description
The function
LineSearch together with the routines
intpol2 and
intpol3 implements a modified version of a line search algorithm by
Fletcher [
23]. 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(α). More precisely it is assumed that the user is
prepared to accept any value of
f(α) for which
f(α) ≤
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 α
(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 [
a(k),
b(k)] whose lengths
tend to zero. Each iteration pick a new point
α
(k) in [
a(k),
b(k)]
by minimizing a quadratic or a cubic polynomial which interpolates
f(
a(k)),
f′(
a(k)),
f(
b(k)
) and
f′(
b(k)) if it is known. The sectioning
phase terminates when α
(k) is an acceptable point.
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 NaN for
redundant constraints. |
| b_U |
Upper bounds on the linear constraints, set to NaN 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 [
39], 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)=
NaN
and leaves to the calling routine to decide what to do with those constraints.
12.11 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);
|
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
12.13 SolverList
Purpose
Prints the available solvers for a certain
solvType .
Calling Syntax
= SolverList(solvType)
Description of Inputs
| solvType |
Either a string 'uc', 'con' etc. or the corresponding
solvType number. See Table 2.2. |
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 Optimization 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
2.2.
Examples
See Section
3.
M-files Used
SolverList.m
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: rk'*rk |
| Covar |
Covariance matrix: Inverse of J' *diag(1./(rk'*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./(CovDiag*CovDiag'), where CovDiag = sqrt(diag(Cov)) |
| StdDev |
Estimated standard deviation in parameters:
CovDiag*sqrt(sigma2) |
| x |
=x_k, the input x |
| ConfLim |
95 % Confidence limit (roughly) assuming normal
distribution of errors ConfLim = 2*LS.StdDev |
| CoeffVar |
The coefficients of variation of estimates: StdDev./xk |
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
« Previous « Start » Next »
TOMLAB
