TomWiki - User contributions [en]

TOMLAB Appendix C

2011-06-28T16:09:53Z

213.114.77.5: Created page with "=''TomSym'' - the Modeling Engine= This appendix describes the details and functions of relevance to the user when modeling optimization and optimal control problems with TomSym..."

=''TomSym'' - the Modeling Engine=

This appendix describes the details and functions of relevance to the user when modeling optimization and optimal control problems with TomSym. It is possible to solve the modeling problems, either with ''ezsolve ''or by converting the problem to a standard TOMLAB ''Prob ''struct with ''sym2prob''. The latter provides for the option of controlling all solver settings per the TOMLAB standard (see the solver manuals for more information). The procedure for using MAD (Matlab Automatic Differentiation) is also described in the sections below.

==Main functions==

The following Matlab functions are used directly by the user when modeling problems for processing by the TOMLAB solvers.

===tom - Generate a tomSym symbol===

<pre>
x = tom creates a scalar tomSym symbol with an automatic name.
x = tom(label) creates a scalar symbol with the provided name.
x = tom(label,m,n) creates a m-by-n matrix symbol.
x = tom(\[\],m,n) creates a matrix symbol with an automatic name.
x = tom(label,m,n,'int') creates an integer matrix symbol.
x = tom(label,m,n,'symmetric') creates a symmetric matrix symbol.
</pre>

Because constructs like <code>"x = tom('x')"</code> are very common, there is the shorthand notation "toms x". See also: toms, tomSym

===toms - Create tomSym objects===

Toms is a shorthand notation, possibly replacing several calls to 'tom'.

A symbol is created in the current workspace for each name listed. If a size is specified on the format "NxM" where N and M are integers, then all subsequent symbols will get that size. If the size specification ends with an exclamation point (as in "3x4!") then a symbolic array of concatenated scalar symbols is created instead of one matrix symbol.

The flags "integer" (or "int") and "symmetric" are recognized. If a flag is encountered, then all subsequent symbols will get the properties of that flag.

-integer: The variable is constrained to integer values, resulting in a

<pre>
mixed-integer problem (which requires a compatible solver.)
</pre>

-symmetric: The variable is symmetric, so that <code>x' == x</code>. This requires that

<pre>
the dimensions be square. An NxN symmetric matrix only contains
N\*(N+1)/2 unknowns, and the resulting symbolic object uses the
setSymmetric function.
</pre>

Examples:

<pre>
toms x y z
is equivalent to
x = tom('x');
y = tom('z');
z = tom('z');

toms 2x3 Q 3x3 -integer R -symmetric S
is equivalent to
Q = tom('Q', 2, 3);
R = tom('R', 3, 3, 'integer');
S = tom('S', 3, 3, 'integer', 'symmetric')

toms 3x1! v
is equivalent to
v1 = tom('v1');
v2 = tom('v2');
v3 = tom('v3');
v = \[v1;v2;v3\];
</pre>

In the last example, with the exclamation point, the result is a vector containing scalar symbols. This works differently from the matrix symbols used in the previous examples. Mathematically this v is equivalent to "toms 3x1 v", but the auto-generated code will be different. Expressions such as <code>v(1)+sin(v(2))*v(3)</code> will be more efficient, while expressions such as <code>A*v</code> will be less efficient.

Note: While the "toms" shorthand is very convenient to use prototyping code, it is recommended to only use the longhand "tom" notation for production code. The reason is that Matlab's internal compiler tries to guess whether a statement like <code>"x(1)"</code> is an index into a vector or a call to a function. Since it does not realize that the call to "toms" creates new variables is will make the wrong guess if that function (named "x" in this example) is on the Matlab path when the script is loaded into memory. This will cause strange and unexpected results.

See also: tom, tomSym, setSymmetric

===tomSym/tomSym - Class constructor===

NOTE: Use toms or tom to create tomSym symbols.

<pre>
p = tomSym(a,m,n,arguments...) creates a tomSym using the operator a.
p = tomSym(const) creates a tomSym constant with the value const.
p = tomSym(struct) converts a struct into a tomSym, if the struct has the required fields.
</pre>

See also: toms, tom, tomSym/funcs, tomSym/tomSym

===ezsolve - Solve a tomSym optimization problem===

<code>[solution, result] = ezsolve(f,c)</code> returns the solution to the minimization problem that is defined by the objective function f and the constraints c. The result structure from tomRun is provided in a second output argument.

Ezsolve can also be used to find least-square solutions to equations. If options.norm is set to 'L2', then f can be a set of equations. (If there are equations both in f and c, then the ones in c are considered as strict, and will be solved to tolerances, while the ones in f are solved in a least-square sense. If f is a vector, then the L2 norm of f is minimized.

Ezsolve is meant to be as simple to use as possible. It automatically determines the problem type and finds a suitable solver.

The returned solution is a struct, where the fields represent the unknown variables. This struct can be used by subs to convert a tomSym to a numeric value.

<code>s = ezsolve(f,c,x0)</code> uses the initial guess x0. The input argument x0 can be a struct containing fields names as the unknown symbols, for example a previously returned solution. Alternatively, x0 can be a cell array of simple tomSym equation that can be converted to a struct using tom2struct.

<code>s = ezsolve(f,c,x0,name)</code> sets the problem name.

<code>s = ezsolve(f,c,x0,OPTIONS)</code> where <code>OPTIONS</code> is a structure sets solver options. The options structure can have the following fields.

<pre>
OPTIONS.name - The name of the problem
OPTIONS.type - The problem type, e.g. 'lp', 'qp', 'con', ...
OPTIONS.solver - The solver to use, e.g. 'snopt', 'knitro', ...
OPTIONS.prilev - The ezsolve and tomRun print level (default 1)
OPTIONS.use_d2c - (boolean) true = compute symbolic d2c
OPTIONS.use_H - (boolean) true = compute symbolic H
</pre>

See also: tomDiagnose, sym2prob, tomRun

===sym2prob - Compile symbolic function/constraints into a Prob struct===

Prob = sym2prob(type,f,c) creates a Prob structure, suitable for tomRun, with the objective of minimizing f, subject to c, with respect to all symbols that they contain.

The problem type can be (among others):

<pre>
'lp' - Linear programming
'qp' - Quadratic programming
'con' - Nonlinear programming
'qpcon' - Quadratic problem with nonlinear constraints
'minlp' - Mixed integer nonlinear programming
'sdp' - Linear semidefinite programming
'bmi' - Bilinear semidefinite programming
</pre>

<codeProb = sym2prob(f,c)</code> calls tomDiagnose to attempt to guess the problem type, and prints a warning.

The objective f must be a tomSym symbolic object, while the constraints list c should be a cell array.

If the objective f is a vector or matrix, then a least-square problem is solved, minimizing 0.5*sum(vec(f)) (Half the sum-of-squares of the elements of f ). If f is an equality on the form lhs == rhs, then the sum-of-squares of the difference (rhs-lhs) is minimized.

<code>sym2prob(type,f,c,x0)</code> supplies an initial guess for one or more of the unknowns. The guess x0 should be a struct, where each field is named as a symbol and contains a numeric array of the correct size.

<code>sym2prob(type,f,c,x0,OPTIONS)</code> where OPTIONS is a structure sets options. The options structure can have the following fields.

<pre>
OPTIONS.name - The name of the problem
OPTIONS.use_d2c - (boolean) true = compute symbolic d2c
OPTIONS.use_H - (boolean) true = compute symbolic H
</pre>

Linear and box constraints will be automatically detected, if they are formulated using simple addition and multiplication. For example,

<pre>
-3*(x+2) <= 4+x
</pre>

is automatically converted to

<pre>
x >= -2.5
</pre>

For nonlinear problems, sym2prob will generate temporary m-files representing the nonlinear functions and their derivatives (These files are usually small and harmless, and many modern operating systems automatically clean up old temporary files). In order to remove these files when they are no longer needed, it is recommended to run tomCleanup(Prob) after the problem has been solved.

<pre>
Overloaded methods:
tomSym/sym2prob
</pre>

===getSolution - Extract variables from a solution retuned by tomRun===

<code>s = getSolution(solution)</code> returns a struct where each field corresponds to one of the symbols used in the tomSym problem formulation.

===tomDiagnose - Determine the type for of tomSym optimization problem===

type = tomDiagnose(f,c) returns a text string, defining the problem type that is represented by the objective function f and the constraints c.

Some possible return values:

<pre>
'lp' - Linear programming
'qp' - Quadratic programming
'cls' - Least squares with linear constraints
'nls' - Nonlinear least squares
'con' - Nonlinear programming
'qpcon' - Quadratic problem with nonlinear constraints
'minlp' - Mixed integer nonlinear programming
'sdp' - Linear semidefinite programming
'bmi' - Bilinear semidefinite programming
</pre>

The objective f must be a tomSym symbolic object, while the constraints list c should be a cell array of tomSym objects.

===tomCleanup - Remove any temporary files created for a tomSym problem.===

<code>tomCleanup(Prob)</code> removes any temporary files (created by sym2prob) that are referenced in the problem structure Prob. This should be done after a problem has been solved, to avoid leaving garbage in the system's "temp" directory (although most modern operating system will clean up these files eventually anyway.)

<code>WARNING: IF THE AUTOGENERATED FILES HAVE BEEN EDITED, THEN RUNNING</code>

<pre>
TOMCLEANUP WILL CAUSE ALL CHANGES TO BE LOST.
</pre>

<code>tomCleanup('all')</code> will remove all files and directories that are judged to be tomSym files from the system's "temp" directory. All files that contain a certain "marker" in the filename will be removed. This might be useful if a large number of temporary files were created accidentally, such as when running sym2prob inside a for-loop without calling <code>tomCleanup(Prob)</code> at the end of the loop.

Note: Under normal circumstances there is never a need to run

<pre>
tomCleanup('all'). The operating system should remove old temporary
files as required.
</pre>

After running tomCleanup, all Prob structures that reference the deleted files will be useless. See also: sym2prob

==Using MAD==

Some models require the use of alternative method for partial derivatives. If TomSym cannot be used, one alternative is to use MAD.

===madWrap - Compute a Jacobian using MAD.===

<code>J = madWrap(FUN,N,...)</code> uses MAD to call <code>FUN(...)</code> and returns the Jacobian matrix with respect to the N:th input argument.

FUN must be the name of an existing function. N must be an integer between one and <code>nargin(FUN)</code>.

<code>J = madWrap(M,FUN,N,...)</code> computes the Jacobian matrix of the Mth output argument, instead of the first one.

<code>J</code> will be a Jacobian matrix on the form that is used by tomSym.

==Sub function details==

Advanced users may need to understand how and what some sub functions execute in TomSym. This section describes how to add functionality to TomSym and some more details "under the hood".

===ifThenElse - Smoothened if/then/else.===

<code>y = ifThenElse(cmp1, op, cmp2, yTrue, yFalse, s)</code> replicates the behavior of the C-language construction <code>y = ( condition ? yTrue : yFalse )</code> but with a smoothing sigmoid function, scaled by s. (Setting s''=''0 gives discontinuous "standard" if-then-else.)

The operand string op must be the name of one of the comparison operators ('eq', 'lt', 'le', etc.)

Example: The absolute value of x is <code>ifThenElse(x,'gt',0,x,-x)</code>

<pre>
Overloaded methods:
tomSym/ifThenElse
</pre>

===tomSym/derivative===

The symbolic derivative of a tomSym object.

<code>df_dx = derivative(f,x)</code> computes the derivative of a tomSym object f with respect to a symbol x.

<code>d2f_dxdy = derivative(f,x,y,..)</code> computes the second (third, ...) derivative of f with respect to the symbols x, y, ...

Both f and x can be matrices.

The symbol x can either be a tomSym symbol, or a concatenation of tomSym symbols.

There exist several conventions for how the elements are arranged in the derivative of a matrix. This function uses the convention that <code>vec(df) = df_dx*vec(dx)</code>. This means that if <code>size(f) = [m n]</code> and <code>size(x) = [p q]<code> then <code>size(df_dx) = [m*n, p*q]</code>. Thus, the derivative of a matrix or vector with respect to a scalar is a column vector, the derivative of a scalar is a row vector, and the derivative of any matrix with respect to itself is an identity matrix.

Examples:

*If f and x are vectors, then <code>J = derivative(f,x)</code> computes the Jacobian matrix.

*If f is scalar and x is a vector, then <code>H = derivative(f,x,x)</code> computes the Hessian matrix.

For functions that tomSym/derivative is unfamiliar with, it assumes that there also exists a derivative function for each argument. For example, when computing the derivative of a function "userfun", it is assumed that "userfunJ1" gives the derivative of userfun with respect to its first input argument. Reference: Brookes, M., "The Matrix Reference Manual"

[http://www.ee.ic.ac.uk/hp/staff/dmb/matrix/intro.html http://www.ee.ic.ac.uk/hp/staff/dmb/matrix/intro.html]

===ppderivative - The derivative of a piecewise polynomial.===

<code>dpp = ppderivative(pp)</code> returns a piecewise polynomial which is the derivative of pp, except at points where pp is discontinuous.

<code>dpp = ppderivative(pp,n)</code> returns the nth derivative. A negative n results in the antiderivative (integral) of pp.

===tomSym/mcode===

Generate m-code from a tomSym object.

<code>[code, data, header] = mcode(f)</code> generates m-code, representing an object f.

All constants are moved to a data object, which needs to be supplied in the function call.

The returned function header lists all symbols alphabetically, and the data input last.

TOMLAB Appendix A

2011-06-28T08:24:36Z

213.114.77.5: Created page with "=A ''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 num..."

=A ''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 141, 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 136), 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 134: Information stored in the problem structure ''Prob''. Fields defining sub-structures are defined in Table 135
|-valign="top"
|'''Field'''<hr />||'''Description'''<hr />
|-valign="top"
|''Tomlab''||TOMLAB Version number.
|-valign="top"
|''A''||Matrix with linear constraints, one constraint per row (dense or sparse).
|-valign="top"
|''ADObj''||Automatic differentiation flag. If 1, -1 MAD is used to obtain gradient and Hessian, respectively.
|-valign="top"
|''ADCons''||Automatic differentiation flag. If 1, -1 MAD is used to obtain the constraint Jacobian and nonlinear constraint Hessian, respectively.
|-valign="top"
|''b_L''||Lower bounds on the linear constraints.
|-valign="top"
|''b_U''||Upper bounds on the linear constraints.
|-valign="top"
|''c_L''||Lower bounds on the general constraints.
|-valign="top"
|''c_U''||Upper bounds on the general constraints.
|-valign="top"
|''CHECK''||If true, no more check is done by ProbCheck. Set to true (=1) after first call to ProbCheck.
|-valign="top"
|''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.
|-valign="top"
|''cName''||Name of each general constraint.
|-valign="top"
|''cols''||The columns in the user computed matrix that will be accessed, and needs to be set.
|-valign="top"
|''ConIx''||A vector with the sequence of calls required to compute the numerical con- straint Jacobian efficiently. See ''findpatt ''for more information.
|-valign="top"
|''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.
|-valign="top"
|''ConsIdx''||Internally used to speed up the SOL solver computations. Used to send linear index from multiple subscripts for nonzero pattern in constraint Jacobian.
|-valign="top"
|''ConsPattern''||Matrix with non-zero pattern in the constraint gradient matrix.
|-valign="top"
|''d2LPattern''||Sparsity pattern of the Hessian of the Lagrangian function.
|-valign="top"
|''f Low''||Lower bound on optimal function value.
|-valign="top"
|''f opt''||Objective function value ''f ''(''x*'') corresponding to the points given in ''x opt''.
|-valign="top"
|''GradTolg''||Size of step length to estimate first order derivatives in the gradient vector. If this field is empty, ''optParam.DiffInt ''is used instead.
|-valign="top"
|''GradTolH''||Size of step length to estimate the Hessian matrix. If this field is empty , ''optParam.DiffInt'' is used instead.
|-valign="top"
|''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.
|-valign="top"
|''HessIx''||A vector with the sequence of calls required to compute the numerical Jacobian efficiently. See ''findpatt ''for more information.
|-valign="top"
|''HessPattern''||Matrix with non-zero pattern in the Hessian matrix.
|-valign="top"
|''JacIx''||A vector with the sequence of calls required to compute the numerical Jacobian efficiently. See ''findpatt ''for more information.
|-valign="top"
|''JacPattern''||Matrix with non-zero pattern in the Jacobian matrix.
|-valign="top"
|''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.
|-valign="top"
|''MaxCPU''||Maximum execution time in seconds for the solver. The feature is available for a limited number of solvers.
|-valign="top"
|''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"
|''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).
|-valign="top"
|||2 = Assign function and known derivatives, unknown derivatives set as -11111.
|-valign="top"
|''nState''||Indicates the first and last calls to the user routines to compute function and derivatives. Used by the SOL solvers.
|-valign="top"
|||1 First call.
|-valign="top"
|||0 Other calls before the last call.
|-valign="top"
|||2 + ''I nf orm ''Last call, see the Inform parameter for the solver used.
|-valign="top"
|''N''||Problem dimension (number of variables).
|-valign="top"
|''mLin''||Number of linear constraints. ''mNonlin ''Number of nonlinear constraints.
|-valign="top"
|''Name''||Problem name.
|-valign="top"
|''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.
|-valign="top"
|''P''||Problem number (1).
|-valign="top"
|''plotLine''||Flag if to do a plot of the line search problem.
|-valign="top"
|''PriLev''||Print level in the driver routines (0).
|-valign="top"-
|''PriLevOpt''||Print level in the TOM solver and the Matlab part of the solver interface ( 0).
|-valign="top"
|''PrintLM''||Flag: controls whether or not ''PrintResult ''should calculate Lagrange multiplirs and reduced (projected) gradient after a solver has been run. Since |''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.
|-valign="top"
|''probFile''||Name of m-file in which the problems are defined.
|-valign="top"
|''probType''||TOMLAB problem type, see Table 1.
|-valign="top"
|''rows''||The rows in the user computed vector/matrix that will be accessed, and needs to be set.
|-valign="top"
|''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.
|-valign="top"
|''smallA''||If 1 then small elements in the linear constraints are removed. The elements have to be smaller than ''eps * max''(''max''(''abs''(''P rob.A''))).
|-valign="top"
|''SolverDLP''||Name of the solver that should solve dual LP sub-problems.
|-valign="top"
|''SolverLP''||Name of the Solver that should solve LP sub-problems.
|-valign="top"
|''SolverFP''||Name of the solver that should solve a phase one LP sub-problem, i.e. finding a feasible point to a convex set.
|-valign="top"
|''SolverQP''||Name of the solver that should solve QP sub problems.
|-valign="top"
|''uP''||User supplied parameters for the problem (Init File Format). Use ''Prob.user'' for extra parameters.
|-valign="top"
|''uPName''||Problem name (''Prob.Name'') connected to the user supplied parameters in ''(''uP).
|-valign="top"
|''user''||User supplied parameters for the problem. Should be stored in subfields, for example ''Prob.user.aParam''.
|-valign="top"
|''WarmStart''||For solver with support for warmstarts, ''WarmStart > ''0 indicates that the solver should do a warm start.
|-valign="top"
|''x_0''||Starting point.
|-valign="top"
|''x_L''||Lower bounds on the variables ''x''.
|-valign="top"
|''x_U ''||Upper bounds on the variables ''x''.
|-valign="top"
|''x_min''||Lower bounds on plot region.
|-valign="top"
|''x_max''||Upper bounds on plot region.
|-valign="top"
|''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''.
|-valign="top"
|''xName''||Name of each decision variable in ''x''.
|-valign="top"
|''Warning''||If 1 (default), some warnings may be issued.
|}

{|
|+Table 135: 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.
|-valign="top"
|'''Field'''<hr />||Description'''<hr />
|-valign="top"
|''QP''||Structure with special fields for linear and quadratic problems, see Table 136.
|-valign="top"
|''LS''||Structure with special fields for least squares problems, see Table 137.
|-valign="top"
|''MIP''||Structure with special fields for mixed-integer programming, see Table 138.
|-valign="top"
|''GO''||Structure with special fields for global optimization.
|-valign="top"
|''CGO''||Structure with special fields for costly global optimization.
|-valign="top"
|''ExpFit''||Structure with special fields for exponential fitting problems, see Table 139.
|-valign="top"
|''NTS''||Structure with special fields for nonlinear time series.
|-valign="top"
|''LineParam''||Structure with special fields for line search optimization parameters, see Table 140.
|-valign="top"
|''optParam''||Structure with special fields for optimization parameters, see Table 141.
|-valign="top"
|''PartSep''||Structure with special fields for partially separable functions, see Table 142.
|-valign="top"
|''SOL''||Structure with special fields for SOL (Stanford Optimization Laboratory) solvers, see Table 143.
|-valign="top"
|''Solver''||Structure with fields ''Name'', ''Alg ''and ''Method''. ''Name ''is the name of the solver.
|-valign="top"
|''Alg''||is the solver algorithm to be used. ''Method ''is the solver sub-method tech- nique. See the solver descriptions Section 11.
|-valign="top"
|''FUNCS''||Structure with user defined names of the m-files computing the objective, gradient, Hessian etc. See Table 144. These routines are called from the corresponding gateway routine
|-valign="top"
|''DUNDEE''||Structure with special fields for the MINLP solvers (University of Dundee).
|-valign="top"
|''PENOPT''||Structure with special fields for the PENOPT solvers.
|}

{|
|+Table 136: 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'''<hr />||'''Description'''<hr />
|-valign="top"
|''F''||Constant matrix ''F ''in 1 ''x1F x ''+ ''c1x''
|-valign="top"
|''c''||Cost vector ''c ''in 1 ''x1F x ''+ ''c1x''
|-valign="top"
|''B''||Logical vector of the same length as the number of variables. A zero corresponds to a variable in the basis.
|-valign="top"
|''y''||Dual parameters ''y''.
|-valign="top"
|''Q''||Orthogonal matrix ''Q ''in QR-decomposition.
|-valign="top"
|''R''||Upper triangular matrix ''R ''in QR-decomposition.
|-valign="top"
|''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.
|-valign="top"
|''UseHot''||True if to use a crash basis (hot start).
|-valign="top"
|''HotFile''||If nonempty and UseCrash true, read basis from this file.
|-valign="top"
|''HotFreq''||How often to save a crash basis.
|-valign="top"
|''HotN''||The number of crash basis files.
|-valign="top"
|''optParam''||Structure with special fields for optimization parameters, see Table 141.
|-valign="top"
|''SOL''||Structure with special fields for SOL (Stanford Optimization Labo- ratory) solvers, see Table 143.
|-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 Section 11.
|}

{|
|+Table 137: Information stored in the structure ''Prob.LS''
|-
|'''Field'''<hr />||colspan="2"|'''Description'''<hr />
|-
|''weightType''||colspan="2"|Weighting type:
|-
|||''0''||No weighting.
|-valign="top"
|||''1''||Weight with data in ''y''. If ''y''(''t'') = 0, the weighting is 0, i.e. deleting this residual element.
|-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"
|||''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''.
|-
|''t''||colspan="2"|Time vector ''t''.
|-
|''y''||colspan="2"|Vector or matrix with observations ''y''(''t'').
|-
|''E''||colspan="2"|Fixed matrix, in linear least squares problem ''E * x - y''.
|-valign="top"
|''yUse''||colspan="2"|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'').
|-valign="top"
|''SepAlg''||colspan="2"|If ''SepAlg'' = 1, use separable non linear least squares formulation (default 0).
|}

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

{|
|+Table 139: Information stored in the structure ''Prob.ExpFit''. Default values in parenthesis.
|-
|'''Field'''<hr />||'''Description'''<hr />
|-
|''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 140: Information stored in the structure ''Prob.LineParam''
|-
|'''Field'''<hr />||Description'''<hr />
|-valign="top"
|''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).
|-valign="top"
|''sigma''||Line search accuracy; 0 ''< sigma < ''1. ''sigma ''= 0''.''9 inaccurate line search. ''sigma ''= 0''.''1 accurate line search (0''.''9).
|-valign="top"
|''InitStepLength''||Initial length of step (1''.''0).
|-valign="top"
|''MaxIter''||Maximum number of line search iterations.
|-valign="top"
|''fLowBnd''||Lower bound on optimal function value. Used in the line search by Fletcher, m-file ''LineSearch ''(= ''-realmax'').
|-valign="top"
|''rho''||Determines the ''? ''line (0''.''01).
|-valign="top"
|''tau1''||Determines how fast step grows in phase 1 (9).
|-valign="top"
|''tau2''||How near end point of \[''a, b''\] (0''.''1).
|-valign="top"
|''tau3''||Choice in \[''a, b''\] phase 2 (0''.''5).
|-valign="top"
|''eps1''||Minimal length for interval \[''a, b''\] (10''-''7 ).
|-valign="top"
|''eps2''||Minimal reduction (100 ''× E'').
|}

{|
|+Table 141: 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'''<hr />||'''Description'''<hr />
|-valign="top"
|''PriLev''||Solver major print level in file output. ''PriFreq ''Print frequency in optimization solver.
|-valign="top"
|''SummFreq''||Summary frequency in optimization solver.
|-valign="top"
|''MinorPriLev''||Minor print level in file output in sub-problem solver.
|-valign="top"
|''IterPrint''||Flag for one-row-per-iteration printout during optimization (0).
|-valign="top"
|''wait''||Flag, if true use pause statements after output in each iteration (0).
|-valign="top"
|''MaxFunc''||Maximal number of function evaluations.
|-valign="top"
|''MaxIter''||Maximum number of iterations.
|-valign="top"
|''MajorIter''||Maximum number of iterations in major problem.
|-valign="top"
|''MinorIter''||Maximum number of iterations in minor problem.
|-valign="top"
|''eps_f''||Relative convergence tolerance in ''f ''(10''-''8 ).
|-valign="top"
|''eps_absf''||Absolute convergence tolerance for the function value ( ''-realmax'').
|-valign="top"
|''eps_x''||Relative convergence tolerance in parameter solution ''x''.
|-valign="top"
|''eps_dirg''||Convergence tolerance for the directed derivative (10''-''8 ).
|-valign="top"
|''eps_c''||Feasibility tolerance for nonlinear constraints.
|-valign="top"
|''eps_g''||Gradient (or reduced gradient) convergence tolerance (10''-''7 ).
|-valign="top"
|''eps_Rank''||Rank test tolerance.
|-valign="top"
|''EpsGlob''||Global/local weight parameter in global optimization (10''-''4 ).
|-valign="top"
|''fTol''||Relative accuracy in the computation of the function value.
|-valign="top"
|''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 ).
|-valign="top"
|''bTol''||Feasibility tolerance for linear constraints.
|-valign="top"
|''cTol''||Feasibility tolerance for nonlinear constraints.
|-valign="top"
|''MinorTolX''||Relative convergence tolerance in parameters ''x ''in sub-problem.
|-valign="top"
|''size_x''||Size at optimum for the variables ''x'', used in the convergence tests ( 1). Only changed if scale very different, ''x >> ''1.
|-valign="top"
|''size_f''||Size at optimum for the function ''f '', used in the convergence tests ( 1). Only changed if scale very different, ''f >> ''1.
|-valign="top"
|''size_c''||Size at optimum for the constraints ''c'', used in the convergence tests ( 1). Only changed if scale very different, ''c >> ''1.
|-valign="top"
|''PreSolve''||Flag if presolve analysis is to be applied on linear constraints (0).
|}

{|
|+Table 141: Information stored in the structure ''Prob.optParam'', continued.
|-
|'''Field'''<hr />||'''Description'''<hr />
|-valign="top"
|''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.
|-valign="top"
|''GradCheck''||''0'', ''1'', ''2'', ''3 gives increasing level of user-supplied gradient checks.
|-valign="top"
|''DiffInt''||Difference interval in derivative estimates.
|-valign="top"
|''CentralDiff''||Central difference interval in derivative estimates.
|-valign="top"
|''QN InitMatrix''||Initial matrix for Quasi-Newton, may be set by the user. When
|-valign="top"
|''QN InitMatrix''||is empty, the identity matrix is used.
|-valign="top"
|''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)
|-valign="top"
|''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.
|-valign="top"
|''BigStep''||Unbounded step size. Used to detect unbounded nonlinear problems.
|-valign="top"
|''BigObj''||Unbounded objective value. Used to detect unbounded nonlinear problems.
|-valign="top"
|''CHECK''||If true, no more check is done on the structure. Set to true (=1) after first call to ''optParamSet''.
|}

{|
|+Table 142: Information stored in the structure ''Prob.PartSep''
|-
|'''Field'''<hr />||'''Description'''<hr />
|-valign="top"
|''pSepFunc''||Number of partially separable functions.
|-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. ''f ''(''x'') = ? ''fi ''(''x''). i''=1
|}

{|
|+Table 143: Information stored in the structure ''Prob.SOL''
|-
|'''Field'''||'''Description'''
|-valign="top"
|''SpecsFile''||If nonempty gives the name of a file which is written in the SOL SPECS file format.
|-valign="top"
|''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)''.
|-valign="top"
|''SummFile''||If nonempty gives the name of a file which the SOL solver prints summary information on.
|-valign="top"
|''xs''||Vector with solution ''x ''and slack variables ''s''. Used for warm starts.
|-valign="top"
|''hs''||Vector with basis information in the SOL sparse solver format. Used for warm starts.
|-valign="top"
|''nS''||Number of superbasics. Used for warm starts.
|-valign="top"
|''hElastic''||Elastic variable information in ''SQOPT''.
|-valign="top"
|''iState''||Vector with basis information in the SOL dense solver format. Used for warm starts.
|-valign="top"
|''cLamda''||Vector with Lagrange multiplier information in the SOL dense solver format. Used for warm starts.
|-valign="top"
|''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''.
|-valign="top"
|''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.
|-valign="top"
|''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 144: Information stored in the structure ''Prob.FUNCS''
|-
|'''Field'''<hr />||'''Description'''<hr />
|-valign="top"
|''f''||Name of m-file computing the objective function ''f ''(''x'').
|-valign="top"
|''g''||Name of m-file computing the gradient vector ''g''(''x''). If ''Prob.FUNCS.g'' is empty then numerical derivatives will be used.
|-valign="top"
|''H''||Name of m-file computing the Hessian matrix ''H ''(''x'').
|-valign="top"
|''c''||Name of m-file computing the vector of constraint functions ''c''(''x'').
|-valign="top"
|''dc''||Name of m-file computing the matrix of constraint normals ''?c''(''x'')''/dx''.
|-valign="top"
|''d2c''||Name of m-file computing the 2nd part of 2nd derivative matrix of the Lagrangian function, ?''i ?i ?''2 ''c''(''x'')''/dx''2 .
|-valign="top"
|''r''||Name of m-file computing the residual vector ''r''(''x'').
|-valign="top"
|''J''||Name of m-file computing the Jacobian matrix ''J ''(''x'').
|-valign="top"
|''d2r''||Name of m-file computing the 2nd part of the Hessian for nonlinear least squares problem, i.e. ? ''ri ''(''x'') ''? ri ''(''x'') .
|}

{|
|+Table 145: Information stored in the structure ''Prob.DUNDEE''
|-
|'''Field'''<hr />||Description'''<hr />
|-valign="top"
|''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.
|-valign="top"
|''kmax''||Maximum dimension of the reduced space (''k''), default equal to dimension of problem. Set to 0 if solving an LP problem.
|-valign="top"
|''mlp''||Maximum number of levels of recursion.
|-valign="top"
|''mode''||Mode of operation, default set as 2 ''* P rob.W armStart''.
|-valign="top"
|''x''||Solution (warmstart).
|-valign="top"
|''k''||Dimension of reduced space (warmstart).
|-valign="top"
|''e''||Steepest-edge normalization coefficient (warmstart).
|-valign="top"
|''ls''||Indices of active constraints, first ''n - k''. (warmstart).
|-valign="top"
|''lp''||List of pointers to recursion information in ''ls ''(warmstart).
|-valign="top"
|''peq''||Pointer to end of equality constraint indices in ''ls ''(warmstart).
|-valign="top"
|''PrintFile''||Name of print file. Amount/print type is determined by ''Prob.DUNDEE.optPar(1)''.
|-valign="top"
|''optPar''||Vector with optimization parameters. Described in Table 146.
|}

{|
|+Table 146: ''Prob.DUNDEE.optPar ''values used by TOMLAB /MINLP solvers . ''-''999 in any element gives default value.
|-
|||||||||colspan="4"|'''Used by:'''||
|-
|'''Index'''<hr />||'''Name'''<hr />||'''Default'''<hr />||'''Description'''<hr />||BQPD||miqpBB<hr />||filterSQP<hr />||minlpBB<hr />
|-
|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
|}