TOMLAB Utility Functions: Difference between revisions

From TomWiki
Jump to navigationJump to search
 
(6 intermediate revisions by the same user not shown)
Line 1: Line 1:
[[Category:Manuals]]
[[Category:Manuals]]
 
{{Part Of Manual|title=the TOMLAB Manual|link=[[TOMLAB|TOMLAB Manual]]}}
{{cleanup|Clean this article. Remove references.}}
 
{{Part Of Manual|title=the TOMLAB Manual|link=[[TOMLAB Manual]]}}
 
=TOMLAB Utility Functions=
 
In the following subsections the driver routine and the utility functions in TOMLAB  will be described.
In the following subsections the driver routine and the utility functions in TOMLAB  will be described.


==tomRun==
==tomRun==
'''Purpose'''


General multi-solver driver routine for TOMLAB.
General multi-solver driver routine for TOMLAB.


'''Calling  Syntax'''
*[[tomRun]]
 
{|
|-valign="top"
|Result = tomRun(Solver, Prob, PriLev, ask)||Call ''Solver'' on the problem defined in structure ''Prob''
|-valign="top"
|Result = tomRun(Solver, probFile, probNumber, Prob, PriLev, ask)||Call ''Solver ''on problem ''probNumber ''in Init File ''probFile.m''
|-valign="top"
|Result = tomRun(Solver, probType, probNumber, PriLev, ask)||Call ''Solver'' on problem    number ''probNumber  ''in  the  default  Init    File for problem type ''probType''
|-valign="top"
|tomRun(probType)||Display all solvers for ''probType''
|-valign="top"
|tomRun||Display all available solvers for all problem types
|}
 
'''Description  of Inputs'''
 
{|
|-valign="top"
|''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.
|-valign="top"
|''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.
|-valign="top"
|''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==
==addPwLinFun==
'''Purpose'''


Adds piecewise linear function to a TOMLAB  MIP problem.
Adds piecewise linear function to a TOMLAB  MIP problem.


'''Calling  Syntax'''
*[[addPwLinFun]]
 
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.
|-valign="top"
|''input''||Flag indicating syntax used.
|-valign="top"
|''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'.
|-valign="top"
|''var''||The number of the variable on which the piecewise linear function depends.  Must exist in the problem already.
|-valign="top"
|''funVar''||The number of the variable which will be equal to the piecewise linear function. Must exist in the problem already.
|-valign="top"
|''firstSlope''||Syntax 2 only. The slope of the piecewise linear function left of the first point, point(1).
|-valign="top"
|''point''||An array of break points. Must be sorted. If two values occur twice, there is a step at that point. Length r.
|-valign="top"
|''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.
|-valign="top"
|''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.
|-valign="top"
|''lastSlope''||Syntax 2 only. The slope of the piecewise linear function right of the last point, point(r).
|-valign="top"
|''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==
==binbin2lin==
'''Purpose'''


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


'''Calling  Syntax'''
*[[binbin2lin]]
 
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'''
 
''b''4 = ''b''1 ''* b''2.  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:
 
''b''4 ''<''= ''b''1
''b''4 ''<''= ''b''2
''b''4 ''>''= ''b''1 + ''b''2 ''- ''1
 
By adding this b4 will always be the product of b1 and b2.
 
The routine also handles products of three binary variables. ''b''4 = ''b''1 ''* b''2 ''* b''3.  The following constraints are then added:
 
''b''4 ''<''= ''b''1
''b''4 ''<''= ''b''2
''b''4 ''<''= ''b''3
''b''4 ''>''= ''b''1 + ''b''2 + ''b''3 ''- ''1


==bincont2lin==
==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.
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'''
*[[bincont2lin]]
 
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==
==checkFuncs==
'''Purpose'''


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


'''Calling  Syntax'''
*[[checkFuncs]]
 
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==
==checkDerivs==
'''Purpose'''


TOMLAB  routine for verifying derivatives of user supplied routines.
TOMLAB  routine for verifying derivatives of user supplied routines.


'''Calling  Syntax'''
*[[checkDerivs]]
 
[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'''
 
{|
|-valign="top"
|''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==
==cpTransf==
'''Purpose'''


Transform general convex programs on the form
Transform general convex programs on the form


 
*[[cpTransf]]
<math>
\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}
</math>
 
 
where <math>x,x_{L},x_{U}\in \MATHSET{R}^{n}</math>, <math>A\in \MATHSET{R}^{m\times n}</math>
and <math>b_{L},b_{U} \in \MATHSET{R}^{m}</math>, 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.
|-valign="top"
|''TransfType''||Type of transformation, see the description below.
|-valign="top"
|''MakeEQ''||Flag, if set true, make standard form (all equalities).
|-valign="top"
|''LowInf ''||Variables equal to ''-I nf ''or variables ''< LowI nf ''are set to ''LowI nf ''before transforming the problem. Default ''-''10''-''4 . ''\|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
 
 
<math>
\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}
</math>
 
where the first ''meq ''constraints are equalities. Translate back with (fixed variables do not change their values):
 
<pre>
x(~x_L==x_U) = (x-x_L) + x_L(~x_L==x_U)
</pre>
 
If ''TransType ''= 2 the program is transformed into the form
 
 
<math>
\begin{array}{cccccl}
\min\limits_{x} & f(x)  &      &  \\s/t &      &      & AA(x) & \leq  & bb  \\& x_{L} & \leq  & x    & \leq  & x_{U} \\
\end{array}
</math>
 
 
where the first ''meq ''constraints are equalities.
 
 
 
If ''TransType'' = 3 the program is transformed into the form
 
 
<math>
\begin{array}{cccc}
\min\limits_{x} & f(x)  &      &  \\s/t            & AA x  & \leq  & bb \\                & x    & \geq  & x_L  \\
\end{array}
</math>
 
 
where the first ''meq''constraints are equalities.


==estBestHessian==
==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.
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]]
 
[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==
==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.
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.


 
*[[lls2qp]]
<math>
\begin{array}{lc}
\min\limits_{x} & f(x) = \frac{1}{2} || C x - 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}
</math>
 
'''Calling  Syntax'''
 
qpProb = lls2qp(Prob, IntVars)
 
'''Description  of Inputs'''
 
{|
|''Prob.LS.C''||The linear matrix in 0''.''5 ''* <nowiki>||y - C_x||</nowiki>''.
|-
|''Prob.LS.y''||The constant vector in 0''.''5 ''* <nowiki>||y - C_x||</nowiki>''.
|}
 
'''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==
==LineSearch==
'''Purpose'''


''LineSearch  ''solves line search problems of the form
''LineSearch  ''solves line search problems of the form


 
*[[LineSearch]]
<math>
\min\limits_{0<\alpha _{\min }\leq \alpha \leq \alpha _{\max
}}f(x^{(k)}+\alpha p)
</math>
 
where <math>x, p \in \MATHSET{R}^{n}</math>.
 
'''Calling  Syntax'''
 
Result = LineSearch(f, g, x, p, f 0, g 0, LineParam, alphaMax, pType, PriLev, varargin)
 
'''Description  of Inputs'''
 
{|
|''f''||colspan="2"|Name of m-file computing the objective function ''f ''(''x'').
|-
|''g''||colspan="2"|Name of m-file computing the gradient vector ''g''(''x'').
|-
|''x''||colspan="2"|Current iterate ''x''.
|-
|''p''||colspan="2"|Search direction ''p''.
|-
|''f_0''||colspan="2"|Function value at ''a ''= 0.
|-
|''g_0''||colspan="2"|Gradient at ''a ''= 0, the directed derivative at the present point.
|-
|''LineParam''||colspan="2"|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||colspan="2"|''Maximal value of step length ''a''.
|-
|''pType''||colspan="2"|Type of problem:
|-
|||0||Normal problem.
|-
|||1||Nonlinear least squares.
|-
|||2||Constrained nonlinear least squares.
|-
|||3||Merit function minimization.
|-
|||4||Penalty function minimization.
|-
|''PriLev''||colspan="2"|Printing level:
|-
|||''PriLev > ''0||Writes a lot of output in ''LineSearch''.
|-
|||''PriLev > ''3||Writes a lot of output in ''intpol2 ''and ''intpol3''.
|-
|''varargin''||colspan="2"|Other parameters directly sent to low level routines.
|}
 
'''Description  of Outputs'''
{|
|''Result''||colspan="2"|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 r''a''(''k'') '', b''(''k'') l whose lengths tend to zero. Each iteration pick a new point ''a''(''k'') in r''a''(''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==
==preSolve==
'''Purpose'''


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


'''Calling  Syntax'''
*[[preSolve]]
 
Prob = preSolve(Prob)
 
'''Description  of Inputs'''
 
{|
|''Prob''||colspan="2"|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''||colspan="2"|Problem description structure. The following fields are changed:
|-valign="top"
|||''A''||Constraint matrix for linear constraints.
|-valign="top"
|||''b_L''||Lower bounds on the linear constraints, set to ''N aN ''for redundant constraints.
|-valign="top"
|||''b_U''||Upper bounds on the linear constraints, set to ''N aN ''for redundant constraints.
|-valign="top"
|||''x_L''||Lower bounds on the variables.
|-valign="top"
|||''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==
==PrintResult==
'''Purpose'''


Prints the result of an optimization.
Prints the result of an optimization.


'''Calling  Syntax'''
*[[PrintResult]]
 
PrintResult(Result, PriLev)
 
'''Description of Inputs'''
 
{|
|''Result''||colspan="2"|Result structure from optimization.
|-
|''PriLev''||colspan="2"|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
|-
|||<pre>
global MAX_x
MAX_x  =  50;
PrintResult(Result);
</pre>
|}


==runtest==
==runtest==
'''Purpose'''


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


'''Calling  Syntax'''
*[[runtest]]
 
runtest(Solver, SolverAlg, probFile, probNumbs, PriLevOpt, wait, PriLev)
 
'''Description  of Inputs'''
 
{|
|''Solver''||Name of solver, default ''conSolve''.
|-valign="top"
|''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.
|-valign="top"
|''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==
==SolverList==
'''Purpose'''


Prints the available solvers for a certain ''solvType''.
Prints the available solvers for a certain ''solvType''.


'''Calling  Syntax'''
*[[SolverList]]
 
[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==
==StatLS==
'''Purpose'''


Compute parameter statistics for least squares problems.
Compute parameter statistics for least squares problems.


'''Calling  Syntax'''
*[[StatLS]]
 
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 <nowiki>J'</nowiki> ∗ ''diag''(1./(r<nowiki>'</nowiki>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<nowiki>'</nowiki>''), where ''CovDiag'' = ''sqrt''(''diag''(''Cov''))
|-
|''StdDev''||Estimated standard deviation in parameters: ''C ovDiag * sqrt''(''sigma''2)
|-
|''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==
==systest==
'''Purpose'''


Run big test to check for bugs in TOMLAB.
Run big test to check for bugs in TOMLAB.


'''Calling  Syntax'''
*[[systest]]
 
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''

Latest revision as of 08:04, 22 July 2011

Notice.png

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

General multi-solver driver routine for TOMLAB.

addPwLinFun

Adds piecewise linear function to a TOMLAB MIP problem.

binbin2lin

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

bincont2lin

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.

checkFuncs

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

checkDerivs

TOMLAB routine for verifying derivatives of user supplied routines.

cpTransf

Transform general convex programs on the form

estBestHessian

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.

lls2qp

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.

LineSearch

LineSearch solves line search problems of the form

preSolve

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

PrintResult

Prints the result of an optimization.

runtest

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

SolverList

Prints the available solvers for a certain solvType.

StatLS

Compute parameter statistics for least squares problems.

systest

Run big test to check for bugs in TOMLAB.

Retrieved from "http://tomwiki.com/index.php?title=TOMLAB_Utility_Functions&oldid=721"