TOMLAB Appendix A
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> |