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 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 #Table: Information stored in the structure Prob.QP. The three last sub-fields, 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. 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. 1 First call. 0 Other calls before the last call. 2 + Inform Last call, see the Inform parameter for the solver used.
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.

Table: The fields defining sub-structures 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 sub-fields, 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 mixed-integer 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 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 #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 sub-fields, 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 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 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 sub-method technique. See the solver descriptions TOMLAB Solver Reference.

Table: Information stored in the structure Prob.LS

Field

Description

weightType

Weighting type: 0 No weighting. 1 Weight with data in y. If y(t) = 0, the weighting is 0, i.e. deleting this residual element. 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). 3 nlp_r calls the routine weightY (must be a string with the routine name) to compute the residuals. weightY Either empty, a vector, a matrix or a string, see weightType. t Time vector t. y Vector or matrix with observations y(t). E Fixed matrix, in linear least squares problem E * x - y. yUse If yU se= 0 compute residual as f (x, t) - y(t) (default), otherwise y(t) should be treated separately by the solver and the residual routines just return f (x, t). SepAlg If SepAlg = 1, use separable non linear least squares formulation (default 0).

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, m-file 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] (10-7 ).
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 sub-problem solver.
IterPrint	Flag for one-row-per-iteration 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 (10-8 ).
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 (10-8 ).
eps_c	Feasibility tolerance for nonlinear constraints.
eps_g	Gradient (or reduced gradient) convergence tolerance (10-7 ).
eps_Rank	Rank test tolerance.
EpsGlob	Global/local weight parameter in global optimization (10-4 ).
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 · 10-13 ).
bTol	Feasibility tolerance for linear constraints.
cTol	Feasibility tolerance for nonlinear constraints.
MinorTolX	Relative convergence tolerance in parameters x in sub-problem.
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 user-supplied gradient checks.
DiffInt	Difference interval in derivative estimates.
CentralDiff	Central difference interval in derivative estimates.
QN InitMatrix	Initial matrix for Quasi-Newton, 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 (10-3 ). 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. $f(x)=\sum \limits _{i=1}^{M}f_{i}(x)$

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 matrix-vector 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 m-file computing the objective function f (x).
g	Name of m-file computing the gradient vector g(x). If Prob.FUNCS.g is empty then numerical derivatives will be used.
H	Name of m-file computing the Hessian matrix H (x).
c	Name of m-file computing the vector of constraint functions c(x).
dc	Name of m-file computing the matrix of constraint normals ?c(x)/dx.
d2c	Name of m-file computing the 2nd part of 2nd derivative matrix of the Lagrangian function, $\sum _{i}\lambda _{i}\partial ^{2}c(x)/dx^{2}$.
r	Name of m-file computing the residual vector r(x).
J	Name of m-file computing the Jacobian matrix J (x).
d2r	Name of m-file computing the 2nd part of the Hessian for nonlinear least squares problem, i.e. $\sum \limits _{i=1}^{m}r_{i}(x){\frac {\partial ^{2}r_{i}(x)}{\partial x_{j}\partial x_{k}}}$.

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	Steepest-edge 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	10-10	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·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
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	10-6	Relative tolerance for NLP solutions	-	-	O	O
12	epsilon	10-6	Accuracy for x tests	O	O	O	O
13	MIopttol	10-4	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