TOMLAB Appendix A: Difference between revisions
No edit summary |
No edit summary |
||
Line 80: | Line 80: | ||
|''MENU''||Flag used to tell if a menu, the GUI or a driver is calling, to avoid unnecessary checks of the fields in ''Prob ''(0). | |''MENU''||Flag used to tell if a menu, the GUI or a driver is calling, to avoid unnecessary checks of the fields in ''Prob ''(0). | ||
|-valign="top" | |-valign="top" | ||
|''Mode''||Indicates whether the user should return function values and/or derivatives. Is best used when the user computes both function values and derivatives at the same time to save CPU time. 0 = Assign function values. 1 = Assign known derivatives, unknown derivative values set as -11111 (=missing value). | |''Mode''||Indicates whether the user should return function values and/or derivatives. Is best used when the user computes both function values and derivatives at the same time to save CPU time. 0 = Assign function values. 1 = Assign known derivatives, unknown derivative values set as -11111 (=missing value). 2 = Assign function and known derivatives, unknown derivatives set as -11111. | ||
|-valign="top" | |-valign="top" | ||
|''nState''||Indicates the first and last calls to the user routines to compute function and derivatives. Used by the SOL solvers. | |''nState''||Indicates the first and last calls to the user routines to compute function and derivatives. Used by the SOL solvers. | ||
| | {| | ||
||| | |1||First call. | ||
|- | |- | ||
||| | |0||Other calls before the last call. | ||
|- | |- | ||
|2 + ''Inform''||Last call, see the Inform parameter for the solver used. | |||
|} | |||
|-valign="top" | |-valign="top" | ||
|''N''||Problem dimension (number of variables). | |''N''||Problem dimension (number of variables). | ||
Line 112: | Line 111: | ||
|''probFile''||Name of m-file in which the problems are defined. | |''probFile''||Name of m-file in which the problems are defined. | ||
|-valign="top" | |-valign="top" | ||
|''probType''||TOMLAB | |''probType''||TOMLAB problem type, see [[TOMLAB_Overall_Design#label-tab:probType|TOMLAB Overall Design]]. | ||
|-valign="top" | |-valign="top" | ||
|''rows''||The rows in the user computed vector/matrix that will be accessed, and needs to be set. | |''rows''||The rows in the user computed vector/matrix that will be accessed, and needs to be set. | ||
Line 223: | Line 222: | ||
|''HotN''||The number of crash basis files. | |''HotN''||The number of crash basis files. | ||
|-valign="top" | |-valign="top" | ||
|''optParam''||Structure with special fields for optimization parameters, | |''optParam''||Structure with special fields for optimization parameters, see <xr id="tab:optParam" />. | ||
|-valign="top" | |-valign="top" | ||
|''SOL''||Structure with special fields for SOL (Stanford Optimization Laboratory) solvers, see | |''SOL''||Structure with special fields for SOL (Stanford Optimization Laboratory) solvers, see <xr id="tab:probSOL" />. | ||
|-valign="top" | |-valign="top" | ||
|''Solver''||Structure with fields ''Name'', ''Alg ''and ''Method''. ''Name ''is the name of the solver. ''Alg ''is the solver algorithm to be used. ''Method ''is the solver sub-method technique. See the solver descriptions [[TOMLAB Solver Reference]]. | |''Solver''||Structure with fields ''Name'', ''Alg ''and ''Method''. ''Name ''is the name of the solver. ''Alg ''is the solver algorithm to be used. ''Method ''is the solver sub-method technique. See the solver descriptions [[TOMLAB Solver Reference]]. | ||
Line 237: | Line 236: | ||
!Field | !Field | ||
!colspan="2"|Description | !colspan="2"|Description | ||
|- | |-valign="top" | ||
|''weightType''||colspan="2"|Weighting type: | |''weightType''||colspan="2"|Weighting type: | ||
| | {| | ||
|''0''||No weighting. | |||
|-valign="top" | |-valign="top" | ||
|''1''||Weight with data in ''y''. If ''y''(''t'') = 0, the weighting is 0, i.e. deleting this residual element. | |||
|-valign="top" | |-valign="top" | ||
|''2''||colspan="2"|Weight with weight vector or matrix in ''weightY''. If ''weightY ''is a vector then weighting by ''weigthY.*r ''(element wise multipli- cation). If ''weightY ''is a matrix then weighting by ''weigthY * r'' (matrix multiplication). | |||
|-valign="top" | |-valign="top" | ||
|''3''||colspan="2"|''nlp_r'' calls the routine ''weightY ''(must be a string with the routine name) to compute the residuals. | |||
|- | |- | ||
|''weightY''||colspan="2"|Either empty, a vector, a matrix or a string, see ''weightType''. | |''weightY''||colspan="2"|Either empty, a vector, a matrix or a string, see ''weightType''. | ||
Line 272: | Line 271: | ||
|- | |- | ||
|''VarWeight''||Priority vector for each variable. | |''VarWeight''||Priority vector for each variable. | ||
|- | |-valing="top" | ||
|''fIP''||colspan="2"|Function value for point defined in ''xIP''. Gives an upper bound on the IP value wanted. Makes it possible to cut branches and avoid node computations | |''fIP''||colspan="2"|Function value for point defined in ''xIP''. Gives an upper bound on the IP value wanted. Makes it possible to cut branches and avoid node computations | ||
|- | |- | ||
Line 453: | Line 452: | ||
|''pSepFunc''||Number of partially separable functions. | |''pSepFunc''||Number of partially separable functions. | ||
|-valign="top" | |-valign="top" | ||
|''index''||Index for the partially separable function to compute, i.e. if ''i ''= ''index'', compute ''fi ''(''x''). If ''index ''= 0, compute the sum of all, i.e. | |''index''||Index for the partially separable function to compute, i.e. if ''i ''= ''index'', compute ''fi ''(''x''). If ''index ''= 0, compute the sum of all, i.e. <math>f(x)=\sum\limits_{i=1}^{M}f_{i}(x)</math> | ||
|} | |} | ||
</figtable> | </figtable> | ||
Line 507: | Line 506: | ||
|''dc''||Name of m-file computing the matrix of constraint normals ''?c''(''x'')''/dx''. | |''dc''||Name of m-file computing the matrix of constraint normals ''?c''(''x'')''/dx''. | ||
|-valign="top" | |-valign="top" | ||
|''d2c''||Name of m-file computing the 2nd part of 2nd derivative matrix of the Lagrangian function, | |''d2c''||Name of m-file computing the 2nd part of 2nd derivative matrix of the Lagrangian function, <math>\sum_i \lambda_i \partial^2c(x)/dx^2</math>. | ||
|-valign="top" | |-valign="top" | ||
|''r''||Name of m-file computing the residual vector ''r''(''x''). | |''r''||Name of m-file computing the residual vector ''r''(''x''). | ||
Line 513: | Line 512: | ||
|''J''||Name of m-file computing the Jacobian matrix ''J ''(''x''). | |''J''||Name of m-file computing the Jacobian matrix ''J ''(''x''). | ||
|-valign="top" | |-valign="top" | ||
|''d2r''||Name of m-file computing the 2nd part of the Hessian for nonlinear least squares problem, i.e. | |''d2r''||Name of m-file computing the 2nd part of the Hessian for nonlinear least squares problem, i.e. <math>\sum\limits_{i=1}^m r_i(x)\frac{\partial^2r_i(x) }{ \partial x_j \partial x_k}</math>. | ||
|} | |} | ||
</figtable> | </figtable> | ||
Line 546: | Line 545: | ||
|''PrintFile''||Name of print file. Amount/print type is determined by ''Prob.DUNDEE.optPar(1)''. | |''PrintFile''||Name of print file. Amount/print type is determined by ''Prob.DUNDEE.optPar(1)''. | ||
|-valign="top" | |-valign="top" | ||
|''optPar''||Vector with optimization parameters. Described in | |''optPar''||Vector with optimization parameters. Described in <xr id="tab:probDUNDEEOptPar" />. | ||
|} | |} | ||
</figtable> | </figtable> | ||
Line 571: | Line 570: | ||
|3||emin||1||1/0: Use/do not use constraint scaling in BQPD||O||O||O||O | |3||emin||1||1/0: Use/do not use constraint scaling in BQPD||O||O||O||O | ||
|- | |- | ||
|4||sgnf||5 ''· ''10''-''4||Maximum relative error in two numbers equal in exact arithmetic.||O||O||O||O | |4||sgnf||5''·''10''-''4||Maximum relative error in two numbers equal in exact arithmetic.||O||O||O||O | ||
|- | |- | ||
|5||nrep||2||Maximum number of refinement steps.||O||O||O||O | |5||nrep||2||Maximum number of refinement steps.||O||O||O||O |
Revision as of 12:12, 8 August 2011
This page is part of the TOMLAB Manual. See TOMLAB Manual. |
Prob - the Input Problem Structure
The Input Problem Structure, here referred to as Prob, is one of the most central aspects of working with TOMLAB. It contains numerous fields and substructures that influence the behavior and performance of the solvers.
There are default values for everything that is possible to set defaults for, and all routines are written in a way that makes it possible for the user to just set an input argument empty ([ ]) and get the default.
TOMLAB is using the structure variable optParam, see <xr id="tab:optParam" />, for the optimization parameters controlling the execution of the optimization solvers.
Subproblems
Many algorithms need sub-problems solved as part of the main algorithm. For example, in SQP algorithms for general nonlinear programs, QP problems are solved as sub-problems in each iteration. As QP solver any solver, even a general NLP solver, may be used. To send parameter information to the QP subsolver, the fields Prob.optParam, Prob.Solver and Prob.SOL could be put as subfields to the Prob.QP field (see <xr id="tab:probQP" />), i.e. as fields Prob.QP.optParam, Prob.QP.Solver. The field Prob.QP.optParam need not have all subfields, the missing ones are filled with default values for the particular QP solver.
The same Prob.QP subfield is used for the other types of subproblems recognized, i.e. Phase 1 feasibility problems, LP and dual LP problems. Note that the fields Prob.SolverQP, Prob.SolverFP Prob.SolverLP and Prob.SolverDLP are set to the name of the solver that should solve the subproblem. If the field is left empty, a suitable default solver is used, dependent on the license for TOMLAB.
<figtable id="tab:infoProb">
Field | Description | ||||||
---|---|---|---|---|---|---|---|
Tomlab | TOMLAB Version number. | ||||||
A | Matrix with linear constraints, one constraint per row (dense or sparse). | ||||||
ADObj | Automatic differentiation flag. If 1, -1 MAD is used to obtain gradient and Hessian, respectively. | ||||||
ADCons | Automatic differentiation flag. If 1, -1 MAD is used to obtain the constraint Jacobian and nonlinear constraint Hessian, respectively. | ||||||
b_L | Lower bounds on the linear constraints. | ||||||
b_U | Upper bounds on the linear constraints. | ||||||
c_L | Lower bounds on the general constraints. | ||||||
c_U | Upper bounds on the general constraints. | ||||||
CHECK | If true, no more check is done by ProbCheck. Set to true (=1) after first call to ProbCheck. | ||||||
CheckNaN | If Prob.CheckNaN = 0, nlp_d2c, nlp_H, nlp_d2r checks for NaN elements and estimates the corresponding derivatives numerically. If Prob.CheckNaN > 0, the same applies for nlp_dc, nlp_g, nlp_J. Off-diagonal elements in symmetric Hessians should both be set as NaN. fdng, fdng2, fdng3, only estimate NaN elements in gradient, if gradient vector is input. | ||||||
cName | Name of each general constraint. | ||||||
cols | The columns in the user computed matrix that will be accessed, and needs to be set. | ||||||
ConIx | A vector with the sequence of calls required to compute the numerical con- straint Jacobian efficiently. See findpatt for more information. | ||||||
ConsDiff | Numerical approximation of the constraint derivatives. If set to 1, the classical approach with forward or backward differences together with automatic step selection will be used. If set to 2, 3 or 4 the spline routines csapi, csaps or spaps in the SPLINE Toolbox will be used. If set to 5, derivatives will be estimated by use of complex variables. For the SOL solvers, the value 6 gives the internal derivative approximation. | ||||||
ConsIdx | Internally used to speed up the SOL solver computations. Used to send linear index from multiple subscripts for nonzero pattern in constraint Jacobian. | ||||||
ConsPattern | Matrix with non-zero pattern in the constraint gradient matrix. | ||||||
d2LPattern | Sparsity pattern of the Hessian of the Lagrangian function. | ||||||
f_Low | Lower bound on optimal function value. | ||||||
f_opt | Objective function value f (x*) corresponding to the points given in x opt. | ||||||
GradTolg | Size of step length to estimate first order derivatives in the gradient vector. If this field is empty, optParam.DiffInt is used instead. | ||||||
GradTolH | Size of step length to estimate the Hessian matrix. If this field is empty , optParam.DiffInt is used instead. | ||||||
GradTolJ | Size of step length to estimate the Jacobian matrix or the constraint gradient matrix. If this field is empty, optParam.DiffInt is used instead. | ||||||
HessIx | A vector with the sequence of calls required to compute the numerical Jacobian efficiently. See findpatt for more information. | ||||||
HessPattern | Matrix with non-zero pattern in the Hessian matrix. | ||||||
JacIx | A vector with the sequence of calls required to compute the numerical Jacobian efficiently. See findpatt for more information. | ||||||
JacPattern | Matrix with non-zero pattern in the Jacobian matrix. | ||||||
LargeScale | Flag if the problem is large scale. If this flag is set no collection of search steps are made. Also, for some solvers, LargeScale chooses between dense (=0) or sparse (=1) versions of the solver. This flag also controls several other features in TOMLAB such as estimation of patterns. | ||||||
MaxCPU | Maximum execution time in seconds for the solver. The feature is available for a limited number of solvers. | ||||||
MENU | Flag used to tell if a menu, the GUI or a driver is calling, to avoid unnecessary checks of the fields in Prob (0). | ||||||
Mode | Indicates whether the user should return function values and/or derivatives. Is best used when the user computes both function values and derivatives at the same time to save CPU time. 0 = Assign function values. 1 = Assign known derivatives, unknown derivative values set as -11111 (=missing value). 2 = Assign function and known derivatives, unknown derivatives set as -11111. | ||||||
nState | Indicates the first and last calls to the user routines to compute function and derivatives. Used by the SOL solvers.
| ||||||
N | Problem dimension (number of variables). | ||||||
mLin | Number of linear constraints. mNonlin Number of nonlinear constraints. | ||||||
Name | Problem name. | ||||||
NumDiff | Numerical approximation of the derivatives of the objective function. If set to 1, the classical approach with forward or backward differences together with automatic step selection will be used. If set to 2, 3 or 4 either the standard Matlab spline function or the spline routines csapi, csaps or spaps in the SPLINE Toolbox will be used. If set to 5, derivatives will be estimated by use of complex variables. For the some solvers, the value 6 gives the internal derivative approximation. | ||||||
P | Problem number (1). | ||||||
plotLine | Flag if to do a plot of the line search problem. | ||||||
PriLev | Print level in the driver routines (0). | ||||||
PriLevOpt | Print level in the TOM solver and the Matlab part of the solver interface ( 0). | ||||||
PrintLM | PrintResult operates on a Result structure, and not on Prob, this flag is accessed as Result.Prob.PrintLM, but of course it is possible to set it before solving the problem. | ||||||
probFile | Name of m-file in which the problems are defined. | ||||||
probType | TOMLAB problem type, see TOMLAB Overall Design. | ||||||
rows | The rows in the user computed vector/matrix that will be accessed, and needs to be set. | ||||||
simType | A flag indicating when the TOMLAB simulation format is used. The objective and constraints are calculated at the same function. The gradient and Jacobian are also calculated in the same function. | ||||||
smallA | If 1 then small elements in the linear constraints are removed. The elements have to be smaller than eps * max(max(abs(Prob.A))). | ||||||
SolverDLP | Name of the solver that should solve dual LP sub-problems. | ||||||
SolverLP | Name of the Solver that should solve LP sub-problems. | ||||||
SolverFP | Name of the solver that should solve a phase one LP sub-problem, i.e. finding a feasible point to a convex set. | ||||||
SolverQP | Name of the solver that should solve QP sub problems. | ||||||
uP | User supplied parameters for the problem (Init File Format). Use Prob.user for extra parameters. | ||||||
uPName | Problem name (Prob.Name) connected to the user supplied parameters in (uP). | ||||||
user | User supplied parameters for the problem. Should be stored in subfields, for example Prob.user.aParam. | ||||||
WarmStart | For solver with support for warmstarts, WarmStart > 0 indicates that the solver should do a warm start. | ||||||
x_0 | Starting point. | ||||||
x_L | Lower bounds on the variables x. | ||||||
x_U | Upper bounds on the variables x. | ||||||
x_min | Lower bounds on plot region. | ||||||
x_max | Upper bounds on plot region. | ||||||
x_opt | Stationary points x*, one per row (if known). It is possible to define an extra column, in which a zero (0) indicates a minimum point, a one (1) a saddle point, and a two (2) a maximum. As default, minimum points are assumed. The corresponding function values for each row in x opt should be given in Prob.f opt. | ||||||
xName | Name of each decision variable in x. | ||||||
Warning | If 1 (default), some warnings may be issued. |
</figtable>
<figtable id="tab:subProb">
Field | Description |
---|---|
QP | Structure with special fields for linear and quadratic problems, see <xr id="tab:probQP" />. |
LS | Structure with special fields for least squares problems, see <xr id="tab:probLS" />. |
MIP | Structure with special fields for mixed-integer programming, see <xr id="tab:probMIP" />. |
GO | Structure with special fields for global optimization. |
CGO | Structure with special fields for costly global optimization. |
ExpFit | Structure with special fields for exponential fitting problems, see <xr id="tab:probExpFit" />. |
NTS | Structure with special fields for nonlinear time series. |
LineParam | Structure with special fields for line search optimization parameters, see <xr id="tab:structLineParam" />. |
optParam | Structure with special fields for optimization parameters, see <xr id="tab:optParam" />. |
PartSep | Structure with special fields for partially separable functions, see <xr id="tab:probPartSep" />. |
SOL | Structure with special fields for SOL (Stanford Optimization Laboratory) solvers, see <xr id="tab:probSOL" />. |
Solver | Structure with fields Name, Alg and Method. Name is the name of the solver. |
Alg | is the solver algorithm to be used. Method is the solver sub-method technique. See the solver descriptions TOMLAB Solver Reference. |
FUNCS | Structure with user defined names of the m-files computing the objective, gradient, Hessian etc. See <xr id="tab:probFUNCS" />. These routines are called from the corresponding gateway routine |
DUNDEE | Structure with special fields for the MINLP solvers (University of Dundee). |
PENOPT | Structure with special fields for the PENOPT solvers. |
</figtable>
<figtable id="tab:probQP">
Field | Description |
---|---|
F | Constant matrix F in 1 x1F x + c1x |
c | Cost vector c in 1 x1F x + c1x |
B | Logical vector of the same length as the number of variables. A zero corresponds to a variable in the basis. |
y | Dual parameters y. |
Q | Orthogonal matrix Q in QR-decomposition. |
R | Upper triangular matrix R in QR-decomposition. |
E | Pivoting matrix E in QR-decomposition. Stored sparse. Ascale Flag if to scale the A matrix, the linear constraints. DualLimit Stop limit on the dual objective. |
UseHot | True if to use a crash basis (hot start). |
HotFile | If nonempty and UseCrash true, read basis from this file. |
HotFreq | How often to save a crash basis. |
HotN | The number of crash basis files. |
optParam | Structure with special fields for optimization parameters, see <xr id="tab:optParam" />. |
SOL | Structure with special fields for SOL (Stanford Optimization Laboratory) solvers, see <xr id="tab:probSOL" />. |
Solver | Structure with fields Name, Alg and Method. Name is the name of the solver. Alg is the solver algorithm to be used. Method is the solver sub-method technique. See the solver descriptions TOMLAB Solver Reference. |
</figtable>
<figtable id="tab:probLS">
Field | Description | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
weightType | Weighting type:
</figtable> <figtable id="tab:probMIP">
</figtable> <figtable id="tab:probExpFit">
</figtable> <figtable id="tab:structLineParam">
</figtable> <figtable id="tab:optParam">
</figtable> <figtable id="tab:probPartSep">
</figtable> <figtable id="tab:probSOL">
</figtable> <figtable id="tab:probFUNCS">
</figtable> <figtable id="tab:probDUNDEE">
</figtable> <figtable id="tab:probDUNDEEOptPar">
</figtable> |