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 #Table: Information stored in the structure Prob.optParam. Default values in parenthesis. The values are selectively used in Base Module solvers. Refer to individual solver documentation for more information., for the optimization parameters controlling the execution of the optimization solvers.
Subproblems
Many algorithms need subproblems solved as part of the main algorithm. For example, in SQP algorithms for general nonlinear programs, QP problems are solved as subproblems 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 #Table: Information stored in the structure Prob.QP. The three last subfields, always part of the Prob subfields, could optionally be put here to give information to a subproblem QP, LP, dual LP or feasible point (Phase 1) solver.), 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.
Table: Information stored in the problem structure Prob.
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. Offdiagonal 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 nonzero 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 nonzero 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 nonzero 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 mfile 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 subproblems.  
SolverLP  Name of the Solver that should solve LP subproblems.  
SolverFP  Name of the solver that should solve a phase one LP subproblem, 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. 
Table: The fields defining substructures in the problem structure Prob. Default values are in all tables given in parenthesis at the end of each item.
Field  Description 

QP  Structure with special fields for linear and quadratic problems, see #Table: Information stored in the structure Prob.QP. The three last subfields, always part of the Prob subfields, could optionally be put here to give information to a subproblem QP, LP, dual LP or feasible point (Phase 1) solver.. 
LS  Structure with special fields for least squares problems, see Table: Information stored in the structure ''Prob.LS''. 
MIP  Structure with special fields for mixedinteger programming, see #Table: Information stored in the structure Prob.MIP. 
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 #Table: Information stored in the structure Prob.ExpFit. Default values in parenthesis.. 
NTS  Structure with special fields for nonlinear time series. 
LineParam  Structure with special fields for line search optimization parameters, see #Table: Information stored in the structure Prob.LineParam. 
optParam  Structure with special fields for optimization parameters, see #Table: Information stored in the structure Prob.optParam. Default values in parenthesis. The values are selectively used in Base Module solvers. Refer to individual solver documentation for more information.. 
PartSep  Structure with special fields for partially separable functions, see #Table: Information stored in the structure Prob.PartSep. 
SOL  Structure with special fields for SOL (Stanford Optimization Laboratory) solvers, see #Table: Information stored in the structure Prob.SOL. 
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 submethod technique. See the solver descriptions TOMLAB Solver Reference. 
FUNCS  Structure with user defined names of the mfiles computing the objective, gradient, Hessian etc. See #Table: Information stored in the structure Prob.FUNCS. 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. 
Table: Information stored in the structure Prob.QP. The three last subfields, always part of the Prob subfields, could optionally be put here to give information to a subproblem QP, LP, dual LP or feasible point (Phase 1) solver.
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 QRdecomposition. 
R  Upper triangular matrix R in QRdecomposition. 
E  Pivoting matrix E in QRdecomposition. 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 Table: Information stored in the structure ''Prob.optParam''. Default values in parenthesis. The values are selectively used in Base Module solvers. Refer to individual solver documentation for more information.. 
SOL  Structure with special fields for SOL (Stanford Optimization Laboratory) solvers, see #Table: Information stored in the structure Prob.SOL. 
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 submethod technique. See the solver descriptions TOMLAB Solver Reference. 
Table: Information stored in the structure Prob.LS
Field  Description  

weightType  Weighting type:

Table: Information stored in the structure Prob.MIP
Field  Description  

IntVars  Which variables are integer valued  
VarWeight  Priority vector for each variable.  
fIP  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  
xIP  The point x giving the function value fIP.  
PI  See the TOMLAB /CPLEX User's Guide.  
SC  See the TOMLAB /CPLEX User's Guide.  
SI  See the TOMLAB /CPLEX User's Guide.  
sos1  See the TOMLAB /CPLEX User's Guide.  
sos2  See the TOMLAB /CPLEX User's Guide.  
xpcontrol  See the TOMLAB/ Xpress User's Guide.  
callback  See the TOMLAB /CPLEX User's Guide.  
KNAPSACK  See the TOMLAB /CPLEX User's Guide. 
Table: Information stored in the structure Prob.ExpFit. Default values in parenthesis.
Field  Description 

p  Number of exponential terms (2). 
wType  Weighting type (1). 
eType  Type of exponential terms (1). 
infCR  Information criteria for selection of best number of terms (0). 
dType  Differentiation formula (0). 
geoType  Type of equation (0). 
qType  Length q of partial sums (0). 
sigType  Sign to use in (P ± vQ)/D in exp geo for p = 3, 4 (0). 
lambda  Vector of dimension p, intensities. 
alpha  Vector of dimension p, weights. 
beta  Vector of dimension p, weights in generalized exponential models. 
x0Type  Type of starting value algorithm. 
sumType  Type of exponential sum. 
Table: Information stored in the structure Prob.LineParam
Field  Description 

LineAlg  Line search algorithm. 0 = quadratic interpolation, 1 = cubic inter polation, 2 = curvilinear quadratic interpolation (not robust), 3 = curvilinear cubic interpolation (not robust) ( LineAlg = 1). 
sigma  Line search accuracy; 0 < sigma < 1. sigma = 0.9 inaccurate line search. sigma = 0.1 accurate line search (0.9). 
InitStepLength  Initial length of step (1.0). 
MaxIter  Maximum number of line search iterations. 
fLowBnd  Lower bound on optimal function value. Used in the line search by Fletcher, mfile LineSearch (= realmax). 
rho  Determines the ? line (0.01). 
tau1  Determines how fast step grows in phase 1 (9). 
tau2  How near end point of [a, b] (0.1). 
tau3  Choice in [a, b] phase 2 (0.5). 
eps1  Minimal length for interval [a, b] (107 ). 
eps2  Minimal reduction (100 × E). 
Table: Information stored in the structure Prob.optParam. Default values in parenthesis. The values are selectively used in Base Module solvers. Refer to individual solver documentation for more information.
Field  Description 

PriLev  Solver major print level in file output. PriFreq Print frequency in optimization solver. 
SummFreq  Summary frequency in optimization solver. 
MinorPriLev  Minor print level in file output in subproblem solver. 
IterPrint  Flag for onerowperiteration printout during optimization (0). 
wait  Flag, if true use pause statements after output in each iteration (0). 
MaxFunc  Maximal number of function evaluations. 
MaxIter  Maximum number of iterations. 
MajorIter  Maximum number of iterations in major problem. 
MinorIter  Maximum number of iterations in minor problem. 
eps_f  Relative convergence tolerance in f (108 ). 
eps_absf  Absolute convergence tolerance for the function value ( realmax). 
eps_x  Relative convergence tolerance in parameter solution x. 
eps_dirg  Convergence tolerance for the directed derivative (108 ). 
eps_c  Feasibility tolerance for nonlinear constraints. 
eps_g  Gradient (or reduced gradient) convergence tolerance (107 ). 
eps_Rank  Rank test tolerance. 
EpsGlob  Global/local weight parameter in global optimization (104 ). 
fTol  Relative accuracy in the computation of the function value. 
xTol  If x ? [x L, x L + bT ol] or [x U  bT ol, x U ], fix x on bound (100 * E =2.2204 · 1013 ). 
bTol  Feasibility tolerance for linear constraints. 
cTol  Feasibility tolerance for nonlinear constraints. 
MinorTolX  Relative convergence tolerance in parameters x in subproblem. 
size_x  Size at optimum for the variables x, used in the convergence tests ( 1). Only changed if scale very different, x >> 1. 
size_f  Size at optimum for the function f , used in the convergence tests ( 1). Only changed if scale very different, f >> 1. 
size_c  Size at optimum for the constraints c, used in the convergence tests ( 1). Only changed if scale very different, c >> 1. 
PreSolve  Flag if presolve analysis is to be applied on linear constraints (0). 
DerLevel  Derivative Level, knowledge about nonlinear derivatives: 0 = Some compo nents of the objective gradient are unknown and some components of the constraint gradient are unknown, 1 = The objective gradient is known but some or all components of the constraint gradient are unknown, 2 = All constraint gradients are known but some or all components of the objec tive gradient are unknown, 3 = All objective and constraint gradients are known. 
GradCheck  0, 1, 2, 3 gives increasing level of usersupplied gradient checks. 
DiffInt  Difference interval in derivative estimates. 
CentralDiff  Central difference interval in derivative estimates. 
QN InitMatrix  Initial matrix for QuasiNewton, may be set by the user. When 
QN InitMatrix  is empty, the identity matrix is used. 
splineSmooth  Smoothness parameter sent to the SPLINE Toolbox routine csaps.m when computing numerical approximations of the derivatives (1 default). 0 means least squares straight line fit. 1 means natural (variational) cubic spline interpolant. The transition range in [0,1] is small, suggested tries are 0.2 or 0.4. < 0 lets the routine csaps make the choice (default) 
splineTol  Tolerance parameter sent to the SPLINE Toolbox routine spaps.m when computing numerical approximations of the derivatives (103 ). Should be set in the order of the noise level. 
BigStep  Unbounded step size. Used to detect unbounded nonlinear problems. 
BigObj  Unbounded objective value. Used to detect unbounded nonlinear problems. 
CHECK  If true, no more check is done on the structure. Set to true (=1) after first call to optParamSet. 
Table: Information stored in the structure Prob.PartSep
Field  Description 

pSepFunc  Number of partially separable functions. 
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. 
Table: Information stored in the structure Prob.SOL
Field  Description 

SpecsFile  If nonempty gives the name of a file which is written in the SOL SPECS file format. 
PrintFile  If nonempty gives the name of a file which the SOL solver should print information on. The amount printed is dependent on the print level in Prob.SOL.optPar(1). 
SummFile  If nonempty gives the name of a file which the SOL solver prints summary information on. 
xs  Vector with solution x and slack variables s. Used for warm starts. 
hs  Vector with basis information in the SOL sparse solver format. Used for warm starts. 
nS  Number of superbasics. Used for warm starts. 
hElastic  Elastic variable information in SQOPT. 
iState  Vector with basis information in the SOL dense solver format. Used for warm starts. 
cLamda  Vector with Lagrange multiplier information in the SOL dense solver format. Used for warm starts. 
H  Cholesky factor of Hessian Approximation. Either in natural order (Hessian Yes) or reordered (Hessian No). Used for warm starts using natural order with NPSOL and NLSSOL. 
callback  For large dense or nearly dense quadratic problems (probType ==qp) it is more efficient to use a callback function from the MEX routine to compute the matrixvector product F ·x. Then Prob.QP.F is never copied into the MEX solver. This option applies to SQOPT only. 
optPar  Vector with optParN elements with parameter information for SOL solvers. Initialized to missing value, 999. The elements used aredescribed in the help for each solver. If running TOMLAB format, also see the help of the TOMLAB solver interface routine whos name always has the letters TL added, e.g. minosTL. optParN Number of elements in optPar, defined as 62. 
Table: Information stored in the structure Prob.FUNCS
Field  Description 

f  Name of mfile computing the objective function f (x). 
g  Name of mfile computing the gradient vector g(x). If Prob.FUNCS.g is empty then numerical derivatives will be used. 
H  Name of mfile computing the Hessian matrix H (x). 
c  Name of mfile computing the vector of constraint functions c(x). 
dc  Name of mfile computing the matrix of constraint normals ?c(x)/dx. 
d2c  Name of mfile computing the 2nd part of 2nd derivative matrix of the Lagrangian function, . 
r  Name of mfile computing the residual vector r(x). 
J  Name of mfile computing the Jacobian matrix J (x). 
d2r  Name of mfile computing the 2nd part of the Hessian for nonlinear least squares problem, i.e. . 
Table: Information stored in the structure Prob.DUNDEE
Field  Description 

callback  If 1, use a callback to Matlab to compute QP.F · x in BQPD and miqpBB Faster when F is large and nearly dense. Avoids copying the matrix to the MEX solvers. 
kmax  Maximum dimension of the reduced space (k), default equal to dimension of problem. Set to 0 if solving an LP problem. 
mlp  Maximum number of levels of recursion. 
mode  Mode of operation, default set as 2 * Prob.WarmStart. 
x  Solution (warmstart). 
k  Dimension of reduced space (warmstart). 
e  Steepestedge normalization coefficient (warmstart). 
ls  Indices of active constraints, first n  k. (warmstart). 
lp  List of pointers to recursion information in ls (warmstart). 
peq  Pointer to end of equality constraint indices in ls (warmstart). 
PrintFile  Name of print file. Amount/print type is determined by Prob.DUNDEE.optPar(1). 
optPar  Vector with optimization parameters. Described in #Table: Prob.DUNDEE.optPar values used by TOMLAB /MINLP solvers . 999 in any element gives default value.. 
Table: Prob.DUNDEE.optPar values used by TOMLAB /MINLP solvers . 999 in any element gives default value.
Used by:  

Index  Name  Default  Description  BQPD  miqpBB  filterSQP  minlpBB  
1  iprint  0  Print level in DUNDEE solvers.  O  O  O  O  
2  tol  1010  Relative accuracy in BQPD solution.  O  O  O  O  
3  emin  1  1/0: Use/do not use constraint scaling in BQPD  O  O  O  O  
4  sgnf  5·104  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  
6  npiv  3  No repeat of more than npiv steps were taken.  O  O  O  O  
7  nres  2  Maximum number of restarts if unsuccessful.  O  O  O  O  
8  nfreq  500  Maximum interval between refactorizations.  O  O  O  O  
9  ubd  100  Constraint violation parameter I      O  O  
10  tt  0.125  Constraint violation parameter II      O  O  
11  NLP_eps  106  Relative tolerance for NLP solutions      O  O  
12  epsilon  106  Accuracy for x tests  O  O  O  O  
13  MIopttol  104  Accuracy for f tests    O    O  
14  fIP  1020  Upper bound on the IP value wanted.    O    O  
15  timing  0  1/0: Use/do not use timing    O      
16  max time  4000  Maximum time (sec's) allowed for the run    O      
17  branchtype  1  Branching strategy (1, 2, 3)    O      
18  ifsFirst  0  Exit when first IP solution is found    O      
19  infty  1020  Large value used to represent infinity  O  O  O  O  
20  Nonlin  0  Treat all constraints as nonlinear if 1      O  O 