TomWiki - User contributions [en]

MIPNLP stoaMINLP

2015-03-09T14:34:29Z

Bjorn: /* Prob structure */

{{Part Of Manual|title=the MIPNLP Manual|link=[[MIPNLP|MIPNLP Manual]]}}
==Purpose==

stoaMINLP solves convex mixed-integer nonlinear programming problems (MINLP).

''stoaMINLP ''solves problems of the form

<math>
\begin{array}{cccccc}
\min\limits_{x} & f(x) \\s/t & x_{L} & \leq & x & \leq & x_{U} \\& b_{L} & \leq & Ax & \leq & b_{U} \\& c_{L} & \leq & c(x) & \leq & c_{U} \\& & & {x_{j} \in \mathbb{N} \ \ \forall j \in I} \\
\end{array}
</math>

where <math>x,x_{L},x_{U}\in \mathbb{R}^{n}</math> , <math>c(x),c_{L},c_{U}\in
\mathbb{R}^{m_{1}}</math> , <math>A\in \mathbb{R}^{m_{2}\times n}</math> and
<math>b_{L},b_{U}\in \mathbb{R}^{m_{2}}</math>. The variables <math>x \in I</math> , the
index subset of <math>1,...,n</math> are restricted to be integers.

==Calling Syntax==

Recommended is to first set IterPrint, to get information each iteration
<source lang="matlab">
Prob.optParam.IterPrint = 1;
</source>
Driver call, including printing with level 2:
<source lang="matlab">
Result = tomRun('stoaMINLP',Prob,2);
</source>
Direct solver call:
<source lang="matlab">
Result = stoaMINLP(Prob);
PrintResult(Result);
Result = tomRun('stoaMINLP',Prob,...)
</source>

=== Warm Start ===
To make a restart (warm start), just set the warm start flag, and call stoaMINLP once again:

<source lang="matlab">
Prob.WarmStart = 1;
Result = tomRun('stoaMINLP', Prob, 2);
</source>

stoaMINLP will read warm start information from the stoaMINLPSave.mat file. Another warm start (with same MaxFunc) is made by just calling tomRun again:

<source lang="matlab">
Result = tomRun('stoaMINLP', Prob, 2);
</source>

To make a restart from the warm start information in the Result structure, make a call to WarmDefGLOBAL before calling stoaMINLP. WarmDefGLOBAL moves information from the Result structure to the Prob structure and sets the warm start flag, <code>Prob.WarmStart = 1;</code>

<source lang="matlab">
Prob = WarmDefGLOBAL('stoaMINLP', Prob, Result);
</source>

where Result is the result structure returned by the previous run. A warm start (with same MaxIter) is done by just calling tomRun again:

<source lang="matlab">
Result = tomRun('stoaMINLP', Prob, 2);
</source>

To make another warm start with new MaxIter 100, say, redefine MaxIter as:

<source lang="matlab">
Prob.optParam.MaxIter = 100;
</source>

Then repeat the two lines:

<source lang="matlab">
Prob = WarmDefGLOBAL('stoaMINLP', Prob, Result);
Result = tomRun('stoaMINLP', Prob, 2);
</source>

==Inputs==

===Prob structure===
The '''TOMLAB''' problem structure

{| class="wikitable"
!colspan="2"|The following fields are used in ''Prob'':
|-
|'''Field'''||'''Description'''
|-
|''x_L''||Lower bounds on x.
|-
|''x_U''||Upper bounds on x.
|-
|''A''||The linear constraint matrix.
|-
|''b_L''||Lower bounds on linear constraints.
|-
|''b_U''||Upper bounds on linear constraints.
|-
|''c_L''||Lower bounds on nonlinear constraints.
|-
|''c_U''||Upper bounds on nonlinear constraints.
|-
|''x_0''||Starting point.
|-valign="top"
|''Convex''||If Convex==1, assume NLP problems are convex, and only one local NLP solver call is used at each node. If Convex==0 (Default), [[multiMin]] is used to do many calls to a local solver to determine the global minima at each node. The global minimum with most components integer valued is chosen.
|-valign="top"
|''MaxCPU''||Maximal CPU Time (in seconds) to be used by stoaMINLP, stops with best point found
|-valign="top"
|''PriLev''||Print level in stoaMINLP (default 1). Also see optParam.IterPrint
|-valign="top"
|''PriLevOpt''||Print level in sub-solvers ([[SOL_SNOPT|SNOPT]] and other NLP solvers): =0 No output; ''>''0 Convergence results. ''>''1 Output every iteration, ''>''2 Output each step in the NLP alg For other NLP solvers, see the documentation for the solver
|-valign="top"
|''WarmStart''||If true, ''>''0, stoaMINLP reads the output from the last run from Prob.stoaMINLP, if it exists. If it doesn't exist, stoaMINLP attempts to open and read warm start data from mat-file stoaMINLPSave.mat. stoaMINLP uses the warm start information to continue from the last run. The mat-file minlp- SolveSave.mat is saved every Prob.MIP.SaveFreq iteration.
|-valign="top"
|''SolverNLP''||Name of the solver used for NLP subproblems. If empty, the default solver is found calling GetSolver('con',1); If TOMLAB /SOL installed, [[SOL_SNOPT|SNOPT]] is the default solver. If SolverNLP is a SOL solver ([[SOL_SNOPT|SNOPT]], [[SOL_MINOS|MINOS]] or [[SOL_NPSOL|NPSOL]]), the SOL.optPar and SOL.PrintFile is used: See help minosTL.m, npsolTL.m or snoptTL.m for how to set these parameters
|-
|''SolverNLP0''||Name of the solver used for the initial NLP-problem. If empty, SolverNLP is used.
|-valign="top"
|''SolverLP''||Name of the solver used for LP subproblems. If empty, the default solver is found calling GetSolver('lp',1). If TOMLAB /[[SOL]] or /[[SOL_SNOPT|SNOPT]] or /[[SOL_NPSOL|NPSOL]] installed, [[SOL_MINOS|MINOS]] is the default solver. If SolverLP is a [[SOL]] solver ([[SOL_MINOS|MINOS]], [[SOL_SNOPT|SNOPT]] or [[SOL_NPSOL|NPSOL]]), the SOL.optPar and SOL.PrintFile is used: See the wiki-manuals or the in-MATLAB help of minosTL.m, npsolTL.m or snoptTL.m for how to set these parameters.
|-valign="top"
|''RandState''||See help rngset for how to initialize the random generator. Default is RandState = -1 If Convex == 0 and globalSolver == 'multiMin', RandState is sent to [[multiMin]] to initizalize the random generator.
|-valign="top"
|''xInit''||Parameter sent to the solver [[multiMin]] which is used to solve relaxed sub-problems for nonconvex problems (with Prob.Convex set to false). xInit determines the way initial points are generated and is set as follows: 
 
Either 
1x1 number - 
If > 0, the number of random initial points, default min(3000,30*n); 
If < 0, generate |xInit| points with Latin Hypercube design 
 
d x m matrix - Every column is an initial point (of length d = Prob.N) 
 
Default value for xInit is min(3000,max(60,N*6)) at all nodes except the root node 
|-valign="top"
|''xInit0''||Parameter sent to the solver [[multiMin]] when solving the initial relaxed NLP problem at the root node. 
Default value for xInit0 is min(3000,max(100,N*10)) 
See xInit for more information. 
|-valign="top"
|''MIP''||Structure defining integer optimization parameters. See the table below for a description of each field used in ''Prob.MIP''.
|-valign="top"
|''STOAMINLP''||Structure with solver-specific options. See the table below with descriptions of the fields used in ''Prob.STOAMINLP''.
|-valign="top"
|''optParam''||Structure with general optimization parameters. See the table below with descriptions of the fields used in ''Prob.optParam''.
|}

===MIP structure===

Substructure in Prob with parameters related to mixed integer programming.

{|class="wikitable"
!colspan="2"|fields used in '''Prob.MIP'''
|-
|'''Field'''||'''Description'''
|-valign="top"
|''IntVars''||If empty, all variables are assumed non-integer. If islogical(IntVars) (=all elements are 0/1), then 1 = integer variable, 0 = continuous variable. If any element ''>''1, IntVars is the indices for integer variables.
|-valign="top"
|''VarWeight''||Weight for each variable in the variable selection phase. A lower value gives higher priority. Setting Prob.MIP.VarWeight might improve convergence. 
VarWeight must be of length N, but the values corresponding to noninteger variables will be ignored.
|-valign="top"
|''DualGap''||''stoaMINLP ''stops if the duality gap is less than DualGap. DualGap = 1, stop at first integer solution e.g. DualGap = 0.01, stop if solution ''< ''1% from optimal solution. Note that a finite lower bound will only be set by the solver and thus generating a gap when Prob.Convex is set to true. If Prob.Convex is set to false, the lower bound will be -Inf.
|-valign="top"
|''fIP''||An upper bound on the IP value wanted. Makes it possible to cut branches and avoid node computations. Used even if xIP not given.
|-valign="top"
|''xIP''||The x-values giving the fIP value, if a solution (xIP,fIP) is known.
|-valign="top"
|''NodeSel''||Node selection method: = 1 Depth First. Priority on nodes with more integer components. Default = 2 Breadth First. Priority on nodes with more integer components. = 3 Pure LIFO (Last in, first out) Depth First. = 4 Pure FIFO (First in, first out) Breadth First. = 5 Maximize integer components. = 6 Best bound. = 7 Best estimate using pseudo-costs. = 8 Best projection.
|-valign="top"
|''Backtrack''||Switch node selection method during branch and bound. 
When set to any of the NodeSel methods, node selection method is changed to the Backtrack value when the backtracking criterion (see parameter BackCrit below) is fulfilled. For available choices, see NodeSel above. Default is 2, Breadth First.
|-valign="top"
|''BackCrit''||Backtracking criterion, used when Backtrack > 0. 
= 0. Integer solution found. Default. 
= 1. Current node worse than best estimate of active nodes.
|-valign="top"
|''VarSel''||Variable selection method in branch and bound. = 1 Use variable with most fractional value. = 2 Use gradient and distance to nearest integer value. = 3 Pseudo-cost-based branching.
|-valign="top"
|''KNAPSACK''||If = 1, use a knapsack heuristic. Default 0.
|-valign="top"
|''ROUNDH''||If = 1, use a rounding heuristic. Default 0.
|-valign="top"
|''SaveFreq''||Warm start info saved on stoaMINLPSave.mat every SaveFreq iteration (default -1, i.e. no warm start info is saved)
|}

===STOAMINLP structure===

Substructure in Prob with solver-specific options

{|class="wikitable"
!colspan="2"|fields used in Prob.STOAMINLP
|-
|'''Field'''||'''Description'''
|-valign="top"
|''USE_CUTS''||Flag to use cutting plane algorithm described in [[StoaMINLP#Algorithm]]. Using cuts is not recommended for nonconvex problems. Set nonzero to enable, zero to disable. By default, STOAMINLP.USE_CUTS is set to Prob.Convex.
|-valign="top"
|''LoL_ecp''||Parameter regulating likelihood of linearization using extended cutting plane. See [[StoaMINLP#Algorithm]] for more information. Default 10.
|-valign="top"
|''TOD_ecp''||Parameter regulating "tailing off" detection for extended cutting plane linearizations. See [[StoaMINLP#Algorithm]] for more information. Default 0.001.
|-valign="top"
|''BCB_ecp''||Parameter regulating the balance between branching the search tree and adding linearizations using extended cutting plane. See [[StoaMINLP#Algorithm]] for more information. Default 10.
|-valign="top"
|''LoL_ff''||Parameter regulating likelihood of linearization using fixed fractional integer decision variables. See [[StoaMINLP#Algorithm]] for more information. Default 10.
|-valign="top"
|''TOD_ff''||Parameter regulating "tailing off" detection for linearizations using fixed fractional integer decision variables. See [[StoaMINLP#Algorithm]] for more information. Default 0.001.
|-valign="top"
|''BCB_ff''||Parameter regulating the balance between branching the search tree and adding linearizations using fixed fractional integer decision variables. See [[StoaMINLP#Algorithm]] for more information. Default 10.
|-valign="top"
|''LoL_nlpr''||Parameter regulating likelihood of linearization using the solution of the relaxed NLP problem. See [[StoaMINLP#Algorithm]] for more information. Default 10.
|-valign="top"
|''TOD_nlpr''||Parameter regulating "tailing off" detection for linearizations using the solution of the relaxed NLP problem. See [[StoaMINLP#Algorithm]] for more information. Default 0.001.
|-valign="top"
|''BCB_nlpr''||Parameter regulating the balance between branching the search tree and adding linearizations using the solution of the relaxed NLP problem. See [[StoaMINLP#Algorithm]] for more information. Default 10.
|-valign="top"
|''rTYPE''||= 0 r is fixed to the value in rVALUE. = 1 r is a uniformly distributed random number in the interval [0,1]. Default.
|-valign="top"
|''rVALUE''||Defines the value of r when rTYPE is set to zero. Default is 0.5.
|-valign="top"
|''CUTPOOL''||= 0 All linearizations constraints are kept in the master problem. = 1 Manage a pool with inactive linearization constraints. If an inactive constraint gets violated, it is brought back from the pool. Default.
|-valign="top"
|''CutDelBnd''||The number of consecutive times a linearization can be inactive before it gets removed and put into the inactive pool. Default is 15 times.
|-valign="top"
|''LIM_DEL_CUT''||= 0 No extra deletion of cuts. Default when Prob.Convex == 1. = 1 Delete any cuts limiting the true feasible region whenever detected. Such cuts will appear if the problem has nonlinear constraints. Default when Prob.Convex == 0.
|-valign="top"
|''PsCoItLim''||Limit on time spent per node calculating initial pseudo costs when MIP.VarSel == 3. Default is 120 (s).
|-valign="top"
|''PrintLin''||Set nonzero to print short information about the type of linearization added. Default 0. Enabled when IterPrint > 3.
|-valign="top"
|''PRINTPOOL''||Set nonzero to print Set nonzero to print the decisions taken in the cutpool management.Default 0. Enabled when IterPrint > 4.
|}

===optParam structure===

Substructure in Prob with general optimization parameters.

{|class="wikitable"
!colspan="2"|fields used in Prob.optParam:
|-
|'''Field'''||'''Description'''
|-valign="top"
|''MaxIter''||Maximal number of iterations, default 10000
|-valign="top"
|''IterPrint''||Print short information each iteration. Setting PriLev > 1 also enables IterPrint, setting it to 1. 
The information printed for different levels is as follows: 

>0 Two lines at each node with an improved integer solution: 
Iteration number: 
* Depth in tree (symbol L[] - empty list, symbol Gap - Dual Gap convergence) 
* fNLP (Optimal f(x) current node) 
* fIPMin (Best integer feasible f(x) found) 
* LowBnd (Lower bound on optimal integer feasible f(x)) 
* Dual Gap in absolut value and percent 
* The length of the node list L, -L- 
* The Inform and ExitFlag the solver returned at the current node 
* FuEv (Number of function evaluations used by solver at current node) 
* Date and time stamp. 
* Outer approximation linearizations, number of cuts in active/inactive pool (|C| #A #I). 

> 1 Two lines at each evaluated node with the information described above. 
Moreover, with IterPrint enabled a notice is printed whenever the algorithm switches node selection methods. 
Setting a higher value of IterPrint gives more detailed information. 

>2 Depth, number of integer components and lower bound on objective for each node in L. 
>3 Sets LINPRINT = 1, print info about linearizations added (if used). 
>4 Sets POOLPRINT = 1, print info about cut-pool management (if used).
|-valign="top"
|''bTol''||Linear constraint violation convergence tolerance. Default 1.0e-6
|-valign="top"
|''cTol''||Constraint violation convergence tolerance. Default 1.0e-6
|-valign="top"
|''fTol''||Optimality tolerance. Default 3.0e-13
|-valign="top"
|''xTol''||Variable convergence tolerance. Default 2.2204e-13
|}

==Outputs==

{| class="wikitable"
!''Result''||colspan="2"|Structure with result from optimization. The following fields are changed:
|-
|||''Iter ''||Number of iterations.
|-valign="top"
|||''ExitFlag ''||Exit flag. 0: Global optimal solution found, or integer solution with duality gap less than user tolerance. 1: Maximal number of iterations reached. 2: Empty feasible set, no integer solution found. 4: No feasible point found running NLP relaxation. 5: Illegal x_0 found in NLP relaxation. 99: Maximal CPU Time used (cputime ''> ''Prob.MaxCPU).
|-
|||''Inform''||Code telling type of convergence, returned from subsolver.
|-
|||''ExitText''||Text string giving ''ExitFlag'' and ''Inform'' information.
|-valign="top"
|||''DualGap''||Relative duality gap, max(0,fIPMin-fLB)/-fIPMin-, if fIPMin =0; max(0,fIPMin-fLB) if fIPMin == 0. If fIPMin =0: Scale with 100, 100*Dual- Gap, to get the percentage duality gap. For absolute value duality gap: scale with fIPMin, fIPMin * DualGap
|-
|||''x_k''||Solution.
|-valign="top"
|||''v_k''||Lagrange multipliers. Bounds, Linear and Nonlinear Constraints, size n + mLin + mNonLin.
|-
|||''f_k''||Function value at optimum.
|-
|||''g_k''||Gradient vector at optimum.
|-
|||''x_0''||Starting point x_0.
|-
|||''f_0''||Function value at start.
|-
|||''c_k''||Constraint values at optimum.
|-
|||''cJac''||Constraint derivative values at optimum.
|-
|||''xState''||State of each variable, described in [[TOMLAB_Appendix_B#Table:_The_state_variable_xState_for_the_variable.|TOMLAB Appendix B]].
|-
|||''bState''||State of each constraint, described in [[TOMLAB_Appendix_B#Table:_The_state_variable_bState_for_each_linear_constraint.|TOMLAB Appendix B]].
|-
|||''cState''||State of each general constraint, described in [[TOMLAB_Appendix_B#Table:_The_state_variable_cState_for_each_nonlinear_constraint.|TOMLAB Appendix B]].
|-
|||''Solver''||Solver used ('stoaMINLP').
|-
|||''SolverAlgorithm''||Description of method used.
|-
|||''Prob''||Problem structure used.
|-valign="top"
|||''stoaMINLP''||A structure with warm start information. Use with WarmDefGLOBAL, see example [[StoaMINLP#Warm_Start|here]].
|}

[[Category:MIPNLP]]

MIPNLP ecpMINLP

2015-03-09T14:25:38Z

Bjorn: /* ECPMINLP structure */

{{Part Of Manual|title=the MIPNLP Manual|link=[[MIPNLP|MIPNLP Manual]]}}
==Purpose==

ecpMINLP solves convex mixed-integer nonlinear programming problems (MINLP).

''ecpMINLP ''solves problems of the form

<math>
\begin{array}{cccccc}
\min\limits_{x} & f(x) \\s/t & x_{L} & \leq & x & \leq & x_{U} \\& b_{L} & \leq & Ax & \leq & b_{U} \\& c_{L} & \leq & c(x) & \leq & c_{U} \\& & & {x_{j} \in \mathbb{N} \ \ \forall j \in I} \\
\end{array}
</math>

where <math>x,x_{L},x_{U}\in \mathbb{R}^{n}</math> , <math>c(x),c_{L},c_{U}\in
\mathbb{R}^{m_{1}}</math> , <math>A\in \mathbb{R}^{m_{2}\times n}</math> and
<math>b_{L},b_{U}\in \mathbb{R}^{m_{2}}</math>. The variables <math>x \in I</math> , the
index subset of <math>1,...,n</math> are restricted to be integers but can be either continuously differentiable or not. An initalization routine will detect strict integer variables in the problem.

==Calling Syntax==

Driver call, including printing with level 2:
<source lang="matlab">
Result = tomRun('ecpMINLP',Prob,2);
</source>
Direct solver call:
<source lang="matlab">
Result = ecpMINLP(Prob);
PrintResult(Result);
Result = tomRun('ecpMINLP',Prob,...)
</source>

=== Warm Start ===
Warm start is currently not supported, but might be included in a future release.

==Inputs==

===Prob structure===
The '''TOMLAB''' problem structure

{|class="wikitable"
!colspan="2"|The following fields are used in the problem description structure Prob
|-
|'''Field'''||'''Description'''
|-
|''x_L''||Lower bounds on x.
|-
|''x_U''||Upper bounds on x.
|-
|''A''||The linear constraint matrix.
|-
|''b_L''||Lower bounds on linear constraints.
|-
|''b_U''||Upper bounds on linear constraints.
|-
|''c_L''||Lower bounds on nonlinear constraints.
|-
|''c_U''||Upper bounds on nonlinear constraints.
|-
|''f_Low''||Lower bound on solution.
|-
|''x_0''||Starting point.
|-valign="top"
|''MaxCPU''||Maximal CPU Time (in seconds) to be used by ecpMINLP, stops with best point found
|-valign="top"
|''PriLev''||Print level in ecpMINLP (default 1). Also see optParam.IterPrint
{|class="wikitable"
!value||output
|-
|=0||Silent.
|-
|>0||Initial information and convergence results.
|-
|>1||Output a line whenever the solution has improved, containing:
nIterations, nCuts, nCuts with criteria fulfilled, nLinearizations, nSpecialCuts, best solution.
|-
|>2||Output a line every iteration with the following information:
{|class="wikitable"
!label||description
|-
|It ||Iterations
|-
|nECP ||Number of extended cutting planes (ECP)
|-
|nAlpha>=lim||Number of ECP with criteria fulfilled
|-
|nL ||Number of linearizations
|-
|nSECP ||Number of special case ECP (created from constraint on bound)
|-
|fIPMin ||Objective of best solution at current iteration
|}
|-
|>3||Output a description of each step in the MINLP algorithm
|-
|>4||Output additional numerical information in some algorithm steps
|-
|>5||Output information in substeps (preprocessing, line search)
|}
|-valign="top"
|''PriLevOptMIP''||Print level in MIP sub-solvers, (CPLEX and others, see the documentation for the solver used). 
Usually: 
=0 No output 
>0 Convergence results 
>1 Output every iteration 
>2 Output each step in the algorithm
|-valign="top"
|''PriLevOptNLP''||Print level in NLP sub-solvers, (SNOPT and others, see the documentation for the solver used). 
Usually: 
=0 No output 
>0 Convergence results 
>1 Output every iteration 
>2 Output each step in the algorithm
|-valign="top"
|''SolverMIP''||Name of the solver used for MIP subproblems. If TOMLAB /gurobi is installed, gurobi is the default solver. If TOMLAB /CPLEX is installed, CPLEX is second choice as default. Otherwise the default solver is found calling GetSolver('mip',1); Supported as subsolvers are gurobi, CPLEX, mipSolve, milpSolve and cutplane.
|-valign="top"
|''SolverNLP''||
Name of the solver used for NLP subproblems. If packages /SOL or /SNOTP is installed, snopt is the default solver. Otherwise the default solver is found calling GetSolver('con',1);
|-
|''SolverLP''||Name of the solver used for LP subproblems when SolverMIP == mipSolve
|-
|''MIP''||Structure with parameters specific to mixed integer optimization. See the table below describing the fields used in the MIP structure.
|-
|''ECPMINLP''||Structure with parameters specific to the ecpMINLP solver. See the table below describing the fields used in the ECPMINLP structure.
|-
|''optParam''||Structure with general optimization parameters. See the table below describing the fields used in the optParam structure.
|}

===MIP structure===
Substructure in Prob with parameters related to mixed integer programming.

{|class="wikitable"
!colspan="2"|'''fields used in Prob.MIP''':
|-
|'''Field'''||'''Description'''
|-valign="top"
|''IntVars''||If empty, all variables are assumed non-integer. If islogical(IntVars) (=all elements are 0/1), then 1 = integer variable, 0 = continuous variable. If any element ''>''1, IntVars is the indices for integer variables.
|-valign="top"
|''fIP''||An upper bound on the IP value wanted. Makes it possible to cut branches and avoid node computations. Used even if xIP not given.
|-valign="top"
|''xIP''||The x-values giving the fIP value, if a solution (xIP,fIP) is known.
|-valign="top"
|''DualGap''||ecpMINLP stops if the duality gap is less than DualGap
DualGap = 1, stop at first integer solution, e.g. DualGap = 0.01,stop if solution < 1% from optimal solution.
 The lower bound Prob.f_Low is used, (default -1.0e300), which can also be set by the user. If f_Low has not been changed from default the lower bound is obtained from the initial solution of a relaxed problem, but only when ECPMINLP.INIT_BND is 1 or 2 (default).
 Default DualGap is -1, not used.
|-valign="top"
|''PPP''||Pre-processing and probing, default is 0. 
0 Not used. Default. 
1 Apply initially on MINLP problem. 
2 Apply each iteration before solving MILP sub-problem.
|-
|''ROUNDH''||If nonzero, a rounding heuristics will be used on the initial NLP solution in order to obtain an initial integer solution. Requires ECPMINLP.InitBndType enabled. Default is 1, enabled.
|}

===ECPMINLP structure===
Substructure in ''Prob'' with solver-specific options.

{|class="wikitable"
!colspan="2"|fields used in Prob.ECPMINLP
|-
|'''Field'''||'''Description'''
|-valign="top"
|''beta''||Multiplier when increasing alpha after an infeasible MILP solution.
 Alpha is a parameter individually adjusting each cutting plane, starting at 1.0 and increasing until meeting a certain criterion. Default value for beta is 1.3.
|-valign="top"
|''gamma''||Multiplier when increasing alpha when MILP solution does not violate any nonlinear contraints, but still does not decrease the upper bound of the objective.
 Alpha is a parameter individually adjusting each cutting plane, starting at 1.0 and increasing until meeting a certain criterion. Default value for gamma is 2.0.
|-valign="top"
|''PREALLOC''||Flag enabling preallocation of memory for cutting planes and linearizations.
 0 No preallocation, dynamic growth of arrays. Current default.
 1 Preallocate arrays.
|-valign="top"
|''InitBndType''||Selects method for setting lower bound when f_Low not changed from default.
{|class="wikitable"
!value||method
|-valign="top"
|0 ||No extra initial lower bound.
|-valign="top"
|1 ||Use default TOMLAB NLP solver on problem with relaxed integer constraints. Add a linearization if a feasible MINLP solution was found.
|-valign="top"
|2 ||Add an initial linearization as long as a feasible NLP solution was found. The linearization is a simple lower bound on the MILP objective. Default.
|}
|-valign="top"
|''SET_TOL''||Flag enabling changing tolerances, described below under optParam.eps_x, optParam.eps_x and optParam.eps_f.
 0 Default. Using the recommended solver default values, 1.0e-3.
 1 Tolerances can be changed, taken from Prob.optParam.
|-valign="top"
|''IntSolLimIncr''||Integer option when using [[CPLEX]] as MIP subsolver.
 Define how much the [[CPLEX]] parameter IntSolLimIncr increases when a feasible solution is not optimal and all alpha values have met their criteria.
 When set to zero, the optimal strategy will instead be used immediately, without any gradual increase of INTSOLLIM.
 Default is 1.
|-valign="top"
|''USE_CUTPOOL''||Set nonzero to use a pool for the alpha-regulated extended cutting planes.
 Cuts not active in the MILP-solution for CutDelBound iterations in a row will be inactivated (removed from the MILP-problem) until they are violated in a new solution.
 Default is 0, not used.
|-valign="top"
|''CutDelBound''||The number of consecutive times an extended cutting plane can be inactive before it gets removed and put into the inactive pool, if the option USE_CUTPOOL is set nonzero.
 Default is 15 times.
|-valign="top"
|''MaxIterWoImpr''||Limit on the number of successive iterations allowed without any improvements at all to neither objective nor solution point before the solver terminates
 Default is 2.
|-valign="top"
|''USE_NLP''||=1 User and NLP sub-solver on the initial integer-relaxed original problem, as well as the NLP problem with fixed integer values during the main iteration. 
=2 Use a global sub-solver on the initial integer-relaxed problem, as well as the NLP problem with fixed integer values during the main iterations. Setting UseNLP = can increase the likelihood of finding a global optimal solution for nonconvex problems.
 Default is 1 
 

{|class="wikitable"
!colspan="2"|If UseNLP is set to 2, the following parameters in the Prob-struct are used:
|-
|'''Field'''||'''Description'''
|-valign="top"
|''Prob.RandState''||See help rngset for how to initialize the random generator. 
Default randState = -1 
If Convex == 0 and globalSolver == 'multiMin', RandState is sent to [[multiMin]] to initialize the random generator.
|-valign="top"
|''Prob.xInit''||Parameter sent to the solver [[multiMin]] which is used to solve relaxed sub-problems for nonconvex problems (with Prob.Convex set to false). 
xInit determines the way initial points are generated and is set as follows: 
 
Either 
1x1 number 
If > 0, the number of random initial points, default min(3000,30*n); 
If < 0, generate |xInit| points with Latin Hypercube design 
 
d x m matrix - Every column is an initial point (of length d = Prob.N) 
 
Default value for xInit is min(3000,max(60,N*6)) except for the initial problem.
|-valign="top"
|''Prob.xInit0''||Parameter sent to the solver [[multiMin]] when solving the initial relaxed NLP problem. Default value for xInit0 is min(3000,max(100,N*10)). 
See xInit for more information.
|-valign="top"
|''Prob.globalSolver''||Used to solve the NLP subproblem for nonconvex problems (when Prob.Convex set to false). Default is [[multiMin]]. 
[[multiMin]] is using SolverNLP and SolverNLP0 as the NLP sub-solver.
|}

|-valign="top"
|''RESELECT_CUTS''||Set nonzero to enable cut reselection heuristics. Default is 1, enabled.
|-valign="top"
|''SCALE_CUTS''||Set nonzero to scale cuts before they are added to the MILP problem. Scaling is done by dividing the cut with its norm. Default is 1, enabled.
|}

===optParam Structure===
Substructure in ''Prob'' with general optimization parameters.

{|class="wikitable"
!colspan="2"|fields used in Prob.optParam
|-
|'''Field'''||'''Value'''
|-valign="top"
|''MaxIter''||Maximal number of iterations, default 10000
|-valign="top"
|''IterPrint''||Print short information each iteration. Setting PriLev > 2 also enables IterPrint, setting it to 1.
|-valign="top"
|''eps_x''||Linear constraint violation convergence tolerance. Default is 2.0e-6
|-valign="top"
|''eps_g''||Constraint violation convergence tolerance. Default is 1.0e-7
|-valign="top"
|''eps_f''||Optimality tolerance. Default is 1.0e-8
|}

''NOTE:'' For the solver to use these tolerances, the flag ''ECPMINLP.SET_TOL'' must be set to nonzero.

==Outputs==

{| class="wikitable"
!''Result''||colspan="2"|Structure with result from optimization. The following fields are used:
|-
|||''Iter ''||Number of iterations.
|-valign="top"
|||''ExitFlag ''||Exit flag.
 0: Solution found, or integer solution with duality gap less than user tolerance.
 1: Maximal number of iterations reached.
 2: Empty feasible set, no integer solution found.
 3: Problem in subsolver, see Inform value.
 99: Maximal CPU Time used (cputime > Prob.maxCPU
|-
|||''Inform''||Inform for ExitFlag != 3
 0: Global solution found.
 1: Local solution found.
 2: No solution found.
 >2: Inform value from subsolver.
|-
|||''ExitText''||Text string giving ''ExitFlag'' and ''Inform'' information.
|-valign="top"
|||''DualGap''||Relative duality gap, set as follows:

{| class="wikitable"
!''Condition fulfilled''||DualGap value set
|-
||fIPMin ~= 0||max(0,fIPMin-fLB)/|fIPMin|
|-
||fIPMin == 0||max(0,fIPMin-fLB)
|}
To get the percentage duality gap, scale with 100. 
PercentageGap = 100*Dual- Gap. 
To get the absolute value duality gap, scale with fIPMin. 
AbsoluteGap = fIPMin * DualGap
|-
|||''x_k''||Solution.
|-
|||''x''||Vector of solution points, sorted on ascending order based on the correcsponding objective values returned in f. x(:,1) is always equal to x_k.
|-valign="top"
|||''f_k''||Function value at optimum.
|-
|||''f''||The objective vales at all encountered solution points in x. Sorted in ascending order.
|-
|||''g_k''||Gradient vector at optimum.
|-
|||''c_k''||Constraint values at optimum.
|-
|||''cJac''||Constraint derivative values at optimum.
|-
|||''xState''||State of each variable, described in [[TOMLAB_Appendix_B#Table:_The_state_variable_xState_for_the_variable.|TOMLAB Appendix B]].
|-
|||''bState''||State of each constraint, described in [[TOMLAB_Appendix_B#Table:_The_state_variable_bState_for_each_linear_constraint.|TOMLAB Appendix B]].
|-
|||''cState''||State of each general constraint, described in [[TOMLAB_Appendix_B#Table:_The_state_variable_cState_for_each_nonlinear_constraint.|TOMLAB Appendix B]].
|-
|||''x_0''||Starting point x_0.
|-
|||''Solver''||Solver used ('ecpMINLP').
|-
|||''SolverAlgorithm''||Description of method used.
|-
|||''Prob''||Problem structure used.
|}

== Algorithm==
ecpMINLP Solves convex or pseudo-convex mixed-integer nonlinear programming problems using an extended cutting plane algorithm with cuts regulated by a parameter-vector alpha. Cuts and linearizations are added to MIP subproblem which is then solved by a subsolver in each iteration.

The solver algorithm is mainly based on the paper 'Solving Pseudo-Convex Mixed Integer Optimization Problems by Cutting Plane Techniques' by Tapio Westerlund and Ray Pörn, published in Optimization and Engineering 3, 253-280, 2002, with some modifications.

Most prominent features in addition to the ones described in the main reference above are
* Solving the relaxed NLP problem initially to obtain a lower bound on the solution.
* A rounding heuristics performed on the initial NLP solution in order to obtain an initial upper bound on the initial solutions.
* Optional use of a cutpool for the alpha-regulated extended cutting planes.
* Special treatment of problems with integer variables which are not continuously differentiable.
[[Category:MIPNLP]]

TOMLAB Problem Types and Solver Routines

2015-03-09T14:20:57Z

Bjorn: /* Table: The optimization solvers in TOMLAB Base Module. */

[[Category:Manuals]]
{{Part Of Manual|title=the TOMLAB Manual|link=[[TOMLAB|TOMLAB Manual]]}}
Section [[#Problem Types Defined in TOMLAB|Problem Types Defined in TOMLAB]] defines all problem types in TOMLAB. Each problem definition is accompanied by brief suggestions on suitable solvers. This is followed in [[#Solver Routines in TOMLAB|Solver Routines in TOMLAB]] by a complete list of the available solver routines in TOMLAB and the various available extensions, such as /SOL and /CGO.

==Problem Types Defined in TOMLAB==

===Unconstrained Optimization Problem===

The '''unconstrained optimization '''('''uc''') problem is defined as

<math>
\begin{array}{ll}
\min\limits_{x} & f(x) \\
& \\
s/t & \begin{array}{lcccl}
x_{L} & \leq & x & \leq & x_{U}, \\
\end{array}
\end{array}
</math>

where <math>x, x_L, x_U \in \mathbb{R}^n</math> and <math>f(x) \in \mathbb{R}</math> . For unbounded variables, the corresponding elements of <math>x_L,x_U</math> may be set to <math>\pm \infty</math>.

Recommended solvers: '''TOMLAB /KNITRO and TOMLAB /SNOPT'''.

The TOMLAB Base Module routine ''ucSolve ''includes several of the most popular search step methods for unconstrained optimization. The search step methods for unconstrained optimization included in ''ucSolve ''are: the Newton method, the quasi-Newton BFGS and DFP method, the Fletcher-Reeves and Polak-Ribiere conjugate-gradient method, and the Fletcher conjugate descent method. The quasi-Newton methods may either update the inverse Hessian (standard) or the Hessian itself. The Newton method and the quasi-Newton methods updating the Hessian use a subspace minimization technique to handle rank problems. The quasi-Newton algorithms also use safe guarding techniques to avoid rank problem in the updated matrix.

Another TOMLAB Base Module solver suitable for unconstrained problems is the structural trust region algorithm ''sTrustr'', combined with an initial trust region radius algorithm. It treats partially separable functions. Safeguarded BFGS or DFP are used for the quasi-Newton update, if the analytical Hessian is not used. The set of constrained nonlinear solvers could also be used for unconstrained problems.

===Quadratic Programming Problem===

The '''quadratic programming '''('''qp''') problem is defined as

<math>
\begin{array}{ll}
\min\limits_{x} & f(x) = \frac{1}{2} x^T F x + c^T x \\
& \\
s/t & \begin{array}{lcccl}
x_{L} & \leq & x & \leq & x_{U}, \\
b_{L} & \leq & A x & \leq & b_{U} \\
\end{array}
\end{array}
</math>

where <math>c, x, x_L, x_U \in \mathbb{R}^n</math>, <math>F \in \mathbb{R}^{n \times n}</math>, <math>A \in \mathbb{R}^{m_1 \times n}</math>, and <math>b_L,b_U \in \mathbb{R}^{m_1}</math>.

Recommended solvers: '''TOMLAB /KNITRO, TOMLAB /SNOPT and TOMLAB /MINLP'''.

A positive semidefinite ''F ''-matrix gives a convex QP, otherwise the problem is nonconvex. Nonconvex quadratic programs are solved with a standard active-set method, implemented in the TOM routine ''qpSolve''. ''qpSolve ''explicitly treats both inequality and equality constraints, as well as lower and upper bounds on the variables (simple bounds). It converges to a local minimum for indefinite quadratic programs.

In TOMLAB ''MINOS ''in the general or the QP-version (''QP-MINOS''), or the dense QP solver ''QPOPT ''may be used. In the TOMLAB /SOL extension the ''SQOPT ''solver is suitable for both dense and large, sparse convex QP and ''SNOPT ''works fine for dense or sparse nonconvex QP.

For very large-scale problems, an interior point solver is recommended, such as TOMLAB /KNITRO or TOMLAB /BARNLP.

TOMLAB /CPLEX, TOMLAB /Xpress and TOMLAB /XA should always be considered for large-scale QP problems.

===Constrained Nonlinear Optimization Problem===

The '''constrained nonlinear optimization '''problem ('''con''') is defined as

<math>
\begin{array}{ll}
\min\limits_{x} & f(x) \\
& \\
s/t & \begin{array}{lcccl}
x_{L} & \leq & x & \leq & x_{U}, \\
b_{L} & \leq & A x & \leq & b_{U} \\
c_{L} & \leq & c(x) & \leq & c_{U} \\
\end{array}
\end{array}
</math>

where <math>x, x_L, x_U \in \mathbb{R}^n</math>, <math>f(x) \in \mathbb{R}</math>, <math>A
\in \mathbb{R}^{m_1 \times n}</math>, <math>b_L,b_U \in \mathbb{R}^{m_1}</math>
and <math>c_L,c(x),c_U \in \mathbb{R}^{m_2}</math>.

Recommended solvers: '''TOMLAB /SNOPT, TOMLAB /NPSOL and TOMLAB /KNITRO'''.

For general constrained nonlinear optimization a sequential quadratic programming (SQP) method by Schittkowski is implemented in the TOMLAB Base Module solver ''conSolve''. ''conSolve ''also includes an implementation of the Han-Powell SQP method. There are also a TOMLAB Base Module routine ''nlpSolve ''implementing the Filter SQP by Fletcher and Leyffer.

Another constrained solver in TOMLAB is the structural trust region algorithm ''sTrustr'', described above. Currently, ''sTrustr ''only solves problems where the feasible region, defined by the constraints, is convex. TOMLAB /MINOS solves constrained nonlinear programs. The TOMLAB /SOL extension gives an additional set of general solvers for dense or sparse problems.

''sTrustr'', ''pdco ''and ''pdsco ''in TOMLAB Base Module handle nonlinear problems with ''linear ''constraints only.

There are many other options for large-scale nonlinear optimization to consider in TOMLAB. TOMLAB /CONOPT, TOMLAB /BARNLP, TOMLAB /MINLP, TOMLAB /NLPQL and TOMLAB /SPRNLP.

===Box-bounded Global Optimization Problem===

The '''box-bounded global optimization '''('''glb''') problem is defined as

<math>
\begin{array}{ll}
\min\limits_{x} & f(x) \\
& \\
s/t & \begin{array}{llcccll}
-\infty < &x_{L} & \leq & x & \leq & x_{U}& < \infty , \\
\end{array}
\end{array}
</math>

where <math>x, x_L, x_U \in \mathbb{R}^n</math>, <math>f(x) \in \mathbb{R}</math>, i.e. problems that have finite simple bounds on all variables.

Recommended solvers: '''TOMLAB /LGO and TOMLAB /CGO with TOMLAB /SOL'''.

The TOM solver ''glbSolve ''implements the DIRECT algorithm, which is a modification of the standard Lipschitzian approach that eliminates the need to specify a Lipschitz constant. In ''glbSolve ''no derivative information is used. For global optimization problems with expensive function evaluations the TOMLAB /CGO routine ''ego ''implements the Efficient Global Optimization (EGO) algorithm. The idea of the EGO algorithm is to first fit a response surface to data collected by evaluating the objective function at a few points. Then, EGO balances between finding the minimum of the surface and improving the approximation by sampling where the prediction error may be high.

===Global Mixed-integer Nonlinear Programming Problem===

The '''global mixed-integer nonlinear programming '''('''glc''') problem is defined as

<math>
\begin{array}{ll}
\min\limits_{x} & f(x) \\
& \\
s/t & \begin{array}{llcccll}
-\infty < &x_{L} & \leq & x & \leq & x_{U}& < \infty \\
&b_{L} & \leq & A x & \leq & b_{U}& \\
&c_{L} & \leq & c(x) & \leq & c_{U},& x_{j} \in \mathbb{N}\ ~~\forall j \in I
\end{array}
\end{array}
</math>

where <math>x, x_L, x_U \in \mathbb{R}^n</math>, <math>f(x) \in \mathbb{R}</math>, <math>A \in \mathbb{R}^{m_1 \times n}</math>, <math>b_L,b_U \in \mathbb{R}^{m_1}</math> and <math>c_L,c(x),c_U \in \mathbb{R}^{m_2}</math>.
The variables <math>x \in I</math>, the index subset of <math>1,...,n</math>, are restricted to be integers.

Recommended solvers: '''TOMLAB /OQNLP'''.

The TOMLAB Base Module solver ''glcSolve ''implements an extended version of the DIRECT algorithm, that handles problems with both nonlinear and integer constraints.

===Linear Programming Problem===

The '''linear programming '''('''lp''') problem is defined as

<math>
\begin{array}{ll}
\min\limits_{x} & f(x) = c^T x \\
& \\
s/t & \begin{array}{lcccl}
x_{L} & \leq & x & \leq & x_{U}, \\
b_{L} & \leq & A x & \leq & b_{U} \\
\end{array}
\end{array}
</math>

where <math>c, x, x_L, x_U \in \mathbb{R}^n</math>,
<math>A \in \mathbb{R}^{m_1 \times n}</math>, and <math>b_L,b_U \in \mathbb{R}^{m_1}</math>.

Recommended solvers: '''TOMLAB /CPLEX, TOMLAB /Xpress and TOMLAB /XA'''.
The TOMLAB Base Module solver ''lpSimplex ''implements a simplex algorithm for '''lp '''problems.

When a dual feasible point is known in (6) it is efficient to use the dual simplex algorithm implemented in the TOMLAB Base Module solver ''DualSolve''. In TOMLAB /MINOS the LP interface to ''MINOS'', called ''LP-MINOS ''is efficient for solving large, sparse LP problems. Dense problems are solved by ''LPOPT''. The TOMLAB /SOL extension gives the additional possibility of using ''SQOPT ''to solve large, sparse LP.

The recommended solvers normally outperforms all other solvers.

===Mixed-integer Programming Problem===

The '''mixed-integer programming problem '''('''mip''') is defined as

<math>
\begin{array}{ll}
\min\limits_{x} & f(x) = c^T x \\
& \\
s/t & \begin{array}{lcccl}
x_{L} & \leq & x & \leq & x_{U}, \\
b_{L} & \leq & A x & \leq & b_{U}, ~x_{j} \in \mathbb{N}\ ~~\forall j \in I \\
\end{array}
\end{array}
</math>

where <math>c, x, x_L, x_U \in \mathbb{R}^n</math>, <math>A \in \mathbb{R}^{m_1
\times n}</math>, and <math>b_L,b_U \in \mathbb{R}^{m_1}</math>. The variables <math>x
\in I</math>, the index subset of <math>1,...,n</math> are restricted to be
integers. Equality constraints are defined by setting the lower
bound equal to the upper bound, i.e. for constraint <math>i: b_{L}(i)
= b_{U}(i)</math>.

Recommended solvers: '''TOMLAB /CPLEX, TOMLAB /Xpress and TOMLAB /XA'''.

Mixed-integer programs can be solved using the TOMLAB Base Module routine ''mipSolve ''that implements a standard branch-and-bound algorithm. When dual feasible solutions are available, mipSolve is using the TOMLAB dual simplex solver DualSolve to solve subproblems, which is significantly faster than using an ordinary linear programming solver, like the TOMLAB lpSimplex. ''mipSolve ''also implements user defined priorities for variable selection, and different tree search strategies. For 0/1 - knapsack problems a round-down primal heuristic is included. Another TOMLAB Base Module solver is the cutting plane routine ''cutplane'', using Gomory cuts. It is recommended to use ''mipSolve ''with the LP version of ''MINOS ''with warm starts for the subproblems, giving great speed improvement. The TOMLAB /Xpress extension gives access to the state-of-the-art LP, QP, MILP and MIQP solver Xpress-MP. For many MIP problems, it is necessary to use such a powerful solver, if the solution should be obtained in any reasonable time frame. TOMLAB /CPLEX is equally powerful as TOMLAB /Xpress and also includes a network solver.

===Linear Least Squares Problem===

The '''linear least squares '''('''lls''') problem is defined as

<math>
\begin{array}{ll}
\min\limits_{x} & f(x) = \frac{1}{2} || C x - d || \\
& \\
s/t & \begin{array}{lcccl}
x_{L} & \leq & x & \leq & x_{U}, \\
b_{L} & \leq & A x & \leq & b_{U} \\
\end{array}
\end{array}
</math>

where <math>x, x_L, x_U \in \mathbb{R}^n</math>, <math>d \in \mathbb{R}^M</math>,
<math>C \in \mathbb{R}^{M \times n}</math>,
<math>A \in \mathbb{R}^{m_1 \times n}</math>, <math>b_L,b_U \in \mathbb{R}^{m_1}</math> and <math>c_L,c(x),c_U \in \mathbb{R}^{m_2}</math>.

Recommended solvers: '''TOMLAB /LSSOL'''.

''Tlsqr ''solves unconstrained sparse '''lls '''problems. ''lsei ''solves the general dense problems. ''Tnnls ''is

a fast and robust replacement for the Matlab nnls. The general least squares solver ''clsSolve ''may also be used.

In the TOMLAB

/NPSOL or TOMLAB /SOL extension the ''LSSOL ''solver is suitable for dense linear least squares problems.

===Constrained Nonlinear Least Squares Problem===

The '''constrained nonlinear least squares '''('''cls''') problem is defined as

<math>
\begin{array}{ll}
\min\limits_{x} & f(x) = \frac{1}{2} r(x)^T r(x) \\
& \\
s/t & \begin{array}{lcccl}
x_{L} & \leq & x & \leq & x_{U}, \\
b_{L} & \leq & A x & \leq & b_{U} \\
c_{L} & \leq & c(x) & \leq & c_{U} \\
\end{array}
\end{array}
</math>

where <math>x, x_L, x_U \in \mathbb{R}^n</math>, <math>r(x) \in \mathbb{R}^M</math>,
<math>A \in \mathbb{R}^{m_1 \times n}</math>, <math>b_L,b_U \in \mathbb{R}^{m_1}</math>
and <math>c_L,c(x),c_U \in \mathbb{R}^{m_2}</math>.

Recommended solvers: '''TOMLAB /NLSSOL'''.

The TOMLAB Base Module nonlinear least squares solver ''clsSolve ''treats problems with bound constraints in a similar way as the routine ''ucSolve''. This strategy is combined with an active-set strategy to handle linear equality and inequality constraints.

''clsSolve ''includes seven optimization methods for nonlinear least squares problems, among them: the Gauss-Newton method, the Al-Baali-Fletcher and the Fletcher-Xu hybrid method, and the Huschens TSSM method. If rank problems occur, the solver uses subspace minimization. The line search algorithm used is the same as for unconstrained problems.

Another fast and robust solver is ''NLSSOL'', available in the TOMLAB /NPSOL or the TOMLAB /SOL extension toolbox.

One important utility routine is the TOMLAB Base Module line search algorithm ''LineSearch'', used by the solvers ''conSolve'', ''clsSolve ''and ''ucSolve''. It implements a modified version of an algorithm by Fletcher. The line search algorithm uses quadratic and cubic interpolation. Another TOMLAB Base Module routine, ''preSolve'', is running a presolve analysis on a system of linear qualities, linear inequalities and simple bounds. An algorithm by Gondzio, somewhat modified, is implemented in ''preSolve''.

===Linear Semi-definite Programming Problem===

The '''linear semi-definite programming problem with linear matrix inequalities '''('''sdp''') is defined as

<math>
\begin{array}{rccccl}
\min\limits_{x} & {f(x) = {c^T}x} \\
& \\s/t & x_{L} & \leq & x & \leq & x_{U}\\
& b_{L} & \leq & Ax & \leq & b_{U} \\
& {r}{Q^{i}_0 + Q^{i}_{k}x_{k} \sum{k=1}^{n} \preccurlyeq 0,\qquad i=1,\ldots,m.} \\
\end{array}
</math>

where <math>c, x, x_L, x_U \in \mathbb{R}^n</math>, <math>A \in \mathbb{R}^{m_l\times n}</math>, <math>b_L,b_U \in \mathbb{R}^{m_l}</math> and <math>Q^{i}_{k}</math> are symmetric matrices of similar dimensions in each constraint <math>i</math>. If there are several LMI constraints, each may have it's own dimension.

Recommended solvers: '''TOMLAB /PENSDP and TOMLAB /PENBMI'''.

The '''linear semi-definite programming problem with bilinear matrix inequalities '''('''bmi''') is defined similarly to but with the matrix inequality

<math>
Q^{i}_0 + \sum_{k=1}^{n} Q^{i}_{k} x_{k} + \sum_{k=1}^{n} \sum_{l=1}^{n} x_{k}x_{l} K^{i}_{kl} \preccurlyeq 0
</math>

The MEX solvers ''pensdp ''and ''penbmi ''treat '''sdp '''and '''bmi '''problems, respectively. These are available in the TOMLAB /PENSDP and TOMLAB /PENBMI toolboxes.

The MEX-file solver ''pensdp ''available in the TOMLAB /PENSDP toolbox implements a penalty method aimed at large-scale dense and sparse '''sdp '''problems. The interface to the solver allows for data input in the sparse SDPA input format as well as a TOMLAB specific format corresponding to.

The MEX-file solver ''penbmi ''available in the TOMLAB /PENBMI toolbox is similar to ''pensdp'', with added support for the bilinear matrix inequalities.

==Solver Routines in TOMLAB==

===TOMLAB Base Module===

TOMLAB includes a large set of optimization solvers. Most of them were originally developed by the Applied Optimization and Modeling group (TOM). Since then they have been improved e.g. to handle Matlab sparse arrays and been further developed. [[#Table: The optimization solvers in TOMLAB Base Module.]]. lists the main set of TOM optimization solvers in all versions of TOMLAB.

====Table: The optimization solvers in TOMLAB Base Module.====

{| class="wikitable"
!Function
!Description
|- valign="top"
|[[clsSolve]]||Constrained nonlinear least squares. Handles simple bounds and linear equality and inequality constraints using an active-set strategy. Implements Gauss-Newton, and hybrid quasi-Newton and Gauss-Newton methods.
|- valign="top"
|[[conSolve]]||Constrained nonlinear minimization solver using two different sequential quadratic programming methods.
|- valign="top"
|[[cutPlane]]||Mixed-integer programming using a cutting plane algorithm.
|- valign="top"
|[[DualSolve]]||Solves a linear program with a dual feasible starting point.
|- valign="top"
|[[glbSolve]]||Box-bounded global optimization, using only function values.
|- valign="top"
|[[glcCluster]]||Hybrid algorithm for constrained mixed-integer global optimization. Uses a combination of ''glcFast ''(DIRECT) and a clustering algorithm.
|- valign="top"
|[[glcSolve]]||Global mixed-integer nonlinear programming, using no derivatives.
|- valign="top"
|[[infSolve]]||Constrained minimax optimization. Reformulates problem and calls any suitable nonlinear solver.
|- valign="top"
|[[lpSimplex]]||Linear programming using a simplex algorithm.
|- valign="top"
|[[MilpSolve]]||Mixed-integer programming using branch and bound.
|- valign="top"
|[[multiMin]]||General constrained mixed-integer global optimization problems.
|- valign="top"
|[[multiMINLP]]||General constrained mixed-integer global optimization problems where the number of integer combinations nMax is huge and relaxation of the integer constraint is possible.
|- valign="top"
|[[L1Solve]]||Constrained L1 optimization. Reformulates problem and calls any suitable nonlinear solver.
|- valign="top"
|[[mipSolve]]||Mixed-integer programming using a branch-and-bound algorithm.
|- valign="top"
|[[nlpSolve]]||Constrained nonlinear minimization solver using a filter SQP algorithm.
|- valign="top"
|[[pdcoTL]]||Linearly constrained nonlinear minimization solver using a primal- dual barrier algorithm.
|- valign="top"
|[[pdscoTL]]||Linearly constrained nonlinear minimization solver using a primal- dual barrier algorithm, for separable functions.
|- valign="top"
|[[qpSolve]]||Non-convex quadratic programming.
|- valign="top"
|[[slsSolve]]||Sparse constrained nonlinear least squares. Reformulates problem and calls any suitable sparse nonlinear solver.
|- valign="top"
|[[sTrustr]]||Constrained convex optimization of partially separable functions, using a structural trust region algorithm.
|- valign="top"
|[[ucSolve]]||Unconstrained optimization with simple bounds on the parameters. Implements Newton, quasi-Newton and conjugate-gradient methods.
|}

Additional Fortran solvers in TOMLAB are listed in [[#Table: Additional solvers in TOMLAB.]]. They are called using a set of MEX-file interfaces developed in TOMLAB.

====Table: Additional solvers in TOMLAB.====

{| class="wikitable"
!Function
!Description
|-
|''goalSolve''||Solves sparse multi-objective goal attainment problems
|-
|''lsei''||Dense constrained linear least squares
|-
|''qld''||Convex quadratic programming
|-
|''Tfzero''||Finding a zero to f(x) in an interval, ''x '' is one-dimensional.
|-
|''Tlsqr''|| Sparse linear least squares.
|-
|''Tnnls''||Nonnegative constrained linear least squares
|}

===TOMLAB /BARNLP===

The add-on toolbox TOMLAB /BARNLP solves large-scale nonlinear programming problems using a sparse primal-dual interior point algorithm, in conjunction with a filter for globalization. The solver package was developed in co-operation with Boeing Phantom Works. The TOMLAB /BARNLP package is described in a separate manual available at [http://tomopt.com/ http://tomopt.com].

===TOMLAB /CGO===

The add-on toolbox TOMLAB /CGO solves costly global optimization problems. The solvers are listed in [[#Table: Additional solvers in TOMLAB /CGO.]]. They are written in a combination of Matlab and Fortran code, where the Fortran code is called using a set of
MEX-file interfaces developed in TOMLAB.

====Table: Additional solvers in TOMLAB /CGO.====

{| class="wikitable"
!Function
!Description
|-
|''rbfSolve||''Costly constrained box-bounded optimization using a RBF algorithm.
|-
|''ego''||Costly constrained box-bounded optimization using the Efficient Global Optimization (EGO) algorithm.
|}

===TOMLAB /CONOPT===

The add-on toolbox TOMLAB /CONOPT solves large-scale nonlinear programming problems with a feasible path GRG method . The solver package was developed in co-operation with Arki Consulting and Development A/S. The TOMLAB /CONOPT is described in a separate manual available at [http://tomopt.com/ http://tomopt.com]. There is also m-file help available.

===TOMLAB /CPLEX===

The add-on toolbox TOMLAB /CPLEX solves large-scale mixed-integer linear and quadratic programming prob- lems. The solver package was developed in co-operation with ILOG S.A. The TOMLAB /CPLEX solver package and interface are described in a manual available at [http://tomopt.com/ http://tomopt.com].

===TOMLAB /KNITRO===

The add-on toolbox TOMLAB /KNITRO solves large-scale nonlinear programming problems with interior (barrier) point trust-region methods. The solver package was developed in co-operation with Ziena Optimization Inc. The TOMLAB /KNITRO manual is available at [http://tomopt.com/ http://tomopt.com].

===TOMLAB /LGO===

The add-on toolbox TOMLAB /LGO solves global nonlinear programming problems. The LGO solver package is developed by Pint´er Consulting Services, Inc. The TOMLAB /LGO manual is available at [http://tomopt.com/ http://tomopt.com/].

===TOMLAB /MINLP===

The add-on toolbox TOMLAB /MINLP provides solvers for continuous and mixed-integer quadratic programming

('''qp''','''miqp''') and continuous and mixed-integer nonlinear constrained optimization ('''con''', '''minlp''').

All four solvers, written by Roger Fletcher and Sven Leyffer, University of Dundee, Scotland, are available in sparse and dense versions. The solvers are listed in [[#Table: Solver routines in TOMLAB /MINLP.]].

The TOMLAB /MINLP manual is available at [http://tomopt.com/ http://tomopt.com].

====Table: Solver routines in TOMLAB /MINLP.====

{| class="wikitable"
!Function
!Description
|-
|''bqpd''||Quadratic programming using a null-space method.
|-
|''miqpBB''||Mixed-integer quadratic programming using ''bqpd ''as subsolver.
|-
|''filterSQP''||Constrained nonlinear minimization using a Filtered Sequential QP method.
|-valign="top"
|''minlpBB''||Constrained, mixed-integer nonlinear minimization using a branch- and-bound search scheme. ''filterSQP ''is used as NLP solver.
|}

===TOMLAB /MINOS===

Another set of Fortran solvers were developed by the Stanford Optimization Laboratory (SOL). [[#Table: The SOL optimization solvers in TOMLAB /MINOS.]] lists the solvers included in TOMLAB /MINOS. The solvers are called using a set of MEX-file interfaces developed as part of TOMLAB. All functionality of the SOL solvers are available and changeable in the TOMLAB framework in Matlab.

====Table: The SOL optimization solvers in TOMLAB /MINOS.====

{| class="wikitable"
!Function
!Description
|-
|''MINOS 5.51||''Sparse linear and nonlinear programming with linear and nonlin- ear constraints.
|-
|''LP-MINOS||''A special version of the ''MINOS 5.5 ''MEX-file interface for sparse linear programming.
|-
|''QP-MINOS''||A special version of the ''MINOS 5.5 ''MEX-file interface for sparse quadratic programming.
|-
|''LPOPT 1.0-10''||Dense linear programming.
|-
|''QPOPT 1.0-10 ''||Non-convex quadratic programming with dense constraint matrix and sparse or dense quadratic matrix.
|}

===TOMLAB /OQNLP===

The add-on toolbox TOMLAB /OQNLP uses a multistart heuristic algorithm to find global optima of smooth constrained nonlinear programs (NLPs) and mixed-integer nonlinear programs (MINLPs). The solver package was developed in co-operation with Optimal Methods Inc. The TOMLAB /OQNLP manual is available at [http://tomopt.com/ http://tomopt.com/]

===TOMLAB /NLPQL===

The add-on toolbox TOMLAB /NLPQL solves dense nonlinear programming problems, multi criteria optimiza- tion problems and nonlinear fitting problems. The solver package was developed in co-operation with Klaus Schittkowski. The TOMLAB /NLPQL manual is available at [http://tomopt.com/ http://tomopt.com].

===TOMLAB /NPSOL===

The add-on toolbox TOMLAB /NPSOL is a sub package of TOMLAB /SOL. The package includes the MINOS solvers as well as NPSOL, LSSOL and NLSSOL. The TOMLAB /NPSOL manual is available at [http://tomopt.com/ http://tomopt].

===TOMLAB /PENBMI===

The add-on toolbox TOMLAB /PENBMI solves linear semi-definite programming problems with linear and bilinear matrix inequalities. The solvers are listed in [[#Additional solvers in TOMLAB /PENBMI.]]. They are written in a combination of Matlab and C code. The TOMLAB /PENBMI manual is available at [http://tomopt.com/ http://tomopt.com].

====Additional solvers in TOMLAB /PENBMI.====

{| class="wikitable"
!Function
!Description
|-
|''penbmi''||Sparse and dense linear semi-definite programming using a penalty algorithm.
|-
|''penfeas bmi''||Feasibility check of systems of linear matrix inequalities, using ''penbmi''.
|}

===TOMLAB /PENSDP===

The add-on toolbox TOMLAB /PENSDP solves linear semi-definite programming problems with linear matrix inequalities. The solvers are listed in [[#Table: Additional solvers in TOMLAB /PENSDP.]]. They are written in a combination of Matlab and C code. The TOMLAB /PENSDP manual is available at [http://tomopt.com/ http://tomopt.com].

====Table: Additional solvers in TOMLAB /PENSDP.====

{| class="wikitable"
!Function
!Description
|-
|''pensdp''||Sparse and dense linear semi-definite programming using a penalty algorithm.
|-
|''penfeas_sdp''||Feasibility check of systems of linear matrix inequalities, using ''pensdp''.
|}

===TOMLAB /SNOPT===

The add-on toolbox TOMLAB /SNOPT is a sub package of TOMLAB /SOL. The package includes the MINOS solvers as well as SNOPT and SQOPT. The TOMLAB /SNOPT manual is available at [http://tomopt.com/ http://tomopt.com].

===TOMLAB /SOL===

The extension toolbox TOMLAB /SOL gives access to the complete set of Fortran solvers developed by the Stanford Systems Optimization Laboratory (SOL). These solvers are listed in [[#Table: The SOL optimization solvers in TOMLAB /MINOS.]] and [[#Table: The optimization solvers in the TOMLAB /SOL toolbox.]].

====Table: The optimization solvers in the TOMLAB /SOL toolbox.====

{| class="wikitable"
!Function
!Description
|-
|''NPSOL 5.02''||Dense linear and nonlinear programming with linear and nonlinear constraints.
|-
|''SNOPT 6.2-2''||Large, sparse linear and nonlinear programming with linear and nonlinear constraints.
|-
|''SQOPT 6.2-2''||Sparse convex quadratic programming.
|-
|''NLSSOL 5.0-2''||Constrained nonlinear least squares. NLSSOL is based on NPSOL. No reference except for general NPSOL reference.
|-
|''LSSOL 1.05-4''||Dense linear and quadratic programs (convex), and constrained linear least squares problems.
|}

===TOMLAB /SPRNLP===

The add-on toolbox TOMLAB /SPRNLP solves large-scale nonlinear programming problems. SPRNLP is a state- of-the-art sequential quadratic programming (SQP) method, using an augmented Lagrangian merit function and safeguarded line search. The solver package was developed in co-operation with Boeing Phantom Works. The TOMLAB /SPRNLP package is described in a separate manual available at [http://tomopt.com/ http://tomopt.com].

===TOMLAB /XA===

The add-on toolbox TOMLAB /XA solves large-scale linear, binary, integer and semi-continuous linear program- ming problems, as well as quadratic programming problems. The solver package was developed in co-operation with Sunset Software Technology. The TOMLAB /XA package is described in a separate manual available at [http://tomopt.com/ http://tomopt.com].

===TOMLAB /Xpress===

The add-on toolbox TOMLAB /Xpress solves large-scale mixed-integer linear and quadratic programming prob- lems. The solver package was developed in co-operation with Dash Optimization Ltd. The TOMLAB /Xpress solver package and interface are described in the html manual that comes with the installation package. There is also a TOMLAB /Xpress manual available at [http://tomopt.com/ http://tomopt.com].

===Finding Available Solvers===

To get a list of all available solvers, including Fortran, C and Matlab Optimization Toolbox solvers, for a certain ''solvType'', call the routine ''SolverList ''with ''solvType ''as argument. ''solvType ''should either be a string ('uc', 'con' etc.) or the corresponding ''solvType ''number as given in following [[#Table: solvProbType]]. For example, if wanting a list of all available solvers of ''solvType '''''con''', then

<source lang="matlab">
SolverList('con')
</source>

gives the output

<pre>
>> SolverList('con');

Tomlab recommended choice for Constrained Nonlinear Programming (NLP)

npsol

Other solvers for NLP

Licensed:

nlpSolve
conSolve
sTrustr
constr
minos
PDCO
snopt
fmincon
filterSQP
PDSCO
knitro
conopt
nlpqlp

Non-licensed:

NONE

Solvers also handling NLP

Licensed:

glcSolve
glcFast
glcCluster
lgo
minlpBB
ego
rbfSolve
arbfmip

Non-licensed:

NONE
</pre>

''SolverList ''also returns two output arguments: all available solvers as a string matrix and a vector with the corresponding ''solvType ''for each solver.

Note that solvers for a more general problem type may be used to solve the problem. In [[#Table: solvProbType]] an attempt has been made to classify these relations.

====Table: solvProbType====

The problem classes (''probType'') possible to solve with each type of solver (''solvType'') is marked with an ''x''. When the solver is in theory possible to use, but from a practical point of view is probably not suitable, parenthesis are added (''x'').

{| class="wikitable"
!|| colspan="10" align="center" border="2" | solvType
|-
!probType||uc||qp||con||ls||lls||cls||mip||lp||glb||glc
|-
|'''uc'''||x||||x||||||||||||x||(x)
|-
|'''qp'''||||x||x||||||||||||||(x)
|-
|'''con'''||||||x||||||||||||||(x)
|-
|'''ls'''||||||x||x||||x||||||||(x)
|-
|'''lls'''||||x||x||x||x||x||||||||(x)
|-
|'''cls'''||||||x||||||x||||||||(x)
|-
|'''mip'''||||||||||||||x||||||(x)
|-
|'''lp'''||||x||x||||||||x||x||||(x)
|-
|'''glb'''||||||(x)||||||||||||x||x
|-
|'''glc'''||||||(x)||||||||||||||x
|-
|'''exp'''||x||||x||(x)||||x||||||||(x)
|-
|}

MultiMINLP

2015-03-09T14:16:29Z

Bjorn:

[[Category:Solvers]]
==Purpose==

multiMINLP solves general constrained mixed-integer global nonlinear optimization problems.

It is aimed for problems where the number of integer combinations nMax is huge and relaxation of the integer constraint is possible.

If no integer variables, multiMINLP calls multiMin. If nMax ''<''= min(Prob.optParam.MaxFunc,5000), glcDirect is used. Otherwise, multiMINLP first finds a set M of local minima calling multiMin with no integer restriction on any variable. The best local minimum is selected. glcDirect is called to find the best integer feasible solution fIP in a small area (''< ''+- 2 units) around the best local minimum found.

The other local minima are pruned, if fOpt(i) ''> ''fIP, no integer feasible solution could be found close to this local minimum i.

The area close to the remaining candidate local minima are searched one by one by calling glcDirect to find any fIPi ''< ''fIP.

''multiMINLP ''solves problems of the form

<math>
\begin{array}{cccccc}
\min\limits_{x} & f(x) \\
s/t & x_{L} & \leq & x & \leq & x_{U} \\
& b_{L} & \leq & Ax & \leq & b_{U} \\
& c_{L} & \leq & c(x) & \leq & c_{U} \\
& & & {x_{j} \in \mathbb{N} \ \ \forall j \in I} \\
\end{array}
</math>

where <math>x,x_{L},x_{U}\in \mathbb{R}^{n}</math> , <math>c(x),c_{L},c_{U}\in
\mathbb{R}^{m_{1}}</math>, <math>A\in \mathbb{R}^{m_{2}\times n}</math> and
<math>b_{L},b_{U}\in \mathbb{R}^{m_{2}}</math> . The variables <math>x \in I</math>, the index subset of <math>1,...,n</math> are restricted to be integers.

==Calling Syntax==

<source lang="matlab">
Result = tomRun('multiMINLP',Prob,...)
</source>

==Inputs==

{| class="wikitable"
!''Prob''||colspan="2"|Problem description structure. The following fields are used:
|-
Prob is a structure, defined as to solve a standard MINLP problem. The Prob structure is fed to the localSolver. See e.g. minlpAssign.

See multiMin and glcDirect for input to the subsolvers e.g. Prob.xInit is used in multiMin (and fCut, RandState, xEQTol).
|-valign="top"
|||''x_L''||Lower bounds for each element in x. If generating random points, -inf elements of x_L are set to min(-L,xMin,x U-L) xMin is the minimum of the finite x_L values.
|-valign="top"
|||''x_U''||Upper bounds for each element in x. If generating random points, inf elements of x_U are set to max(L,xMax,x L+L) xMax is the maximum of the finite x_U values.

L is 100 for nonlinear least squares, otherwise 1000.
|-
|||''b_L''||Lower bounds on linear constraints.
|-
|||''b_U''||Upper bounds on linear constraints.
|-
|||''A''||The linear constraint matrix.
|-
|||''c_L''||Lower bounds on nonlinear constraints.
|-
|||''c_U''||Upper bounds on nonlinear constraints.
|-valign="top"
|||''PriLev''||Print Level:

0 = Silent

1 = Display 2 summary rows

2 = Display some extra summary rows

5 = Print level 1 in tomRun call

6 = Print level 2 in tomRun call

7 = Print level 3 in tomRun call
|-
|||''xInit''||Used in multiMin. See help for multiMin.
|-valign="top"
|||''GO.localSolver ''||The local solver used to run all local optimizations. Default is the license dependent output of GetSolver('con',1,0).
|-valign="top"
|||''optParam''||Structure in Prob, Prob.optParam. Defines optimization parameters. Fields used:
|-
|||''MaxFunc''||Max number of function evaluations in each subproblem
|-
|||''fGoal''||Goal for function value f(x), if empty not used. If fGoal is reached, no further local optimizations are done
|-valign="top"
|||''eps_f''||Relative accuracy for function value, fTol == eps_f. Stop if abs(f-fGoal) ''<''= abs(fGoal) * fTol , if fGoal = 0. Stop if abs(f-fGoal) ''<''= fTol , if fGoal ==0. Default 1e-8.
|-
|||''bTol''||Linear constraint feasibility tolerance. Default 1e-6
|-
|||''cTol''||Nonlinear constraint feasibility tolerance. Default 1e-6
|-valign="top"
|||''MIP''||Structure in Prob, Prob.MIP. Defines integer optimization parameters. Fields used:
|-valign="top"
|||''IntVars''||If empty, all variables are assumed non-integer. If islogical(IntVars) (=all el- ements are 0/1), then 1 = integer variable, 0 = continuous variable. If any element ''>''1, IntVars is the indices for integer variables.
|-
|||''nMax''||Number of integer combinations possible, if empty multiMINLP computes nMax.
|-
|||''Rfac''||Reduction factor for real variables in MINLP subproblem close to local multiMINLP minimum. Bounds set to x_L = max(x_L,x-Rfac*(x_U-x_L)) and x_U= min(x_U,x+Rfac*(x_U-x_L)). Default 0.25.
|}

==Outputs==

{|class="wikitable"
!''Result''||colspan="2"|Structure with result from optimization. The following fields are changed:
|-
|||||Result structure from the last good optimization step giving the best f(x) value, the possible global MINLP minimum.

The following fields in Result are changed by multiMINLP before return:
|-valign="top"
|||''ExitFlag''||= 0 normal output, of if fGoal set and found.

= 1 A solution reaching the user defined fGoal was not found.

= 2 Unbounded problem.

=4 Infeasible problem.

The Solver, SolverAlgorithm and ExitText fields are also reset.

A special field in Result is also returned, Result.multiMINLP:
|-
|||''xOpt''||Prob.N x k matrix with k distinct local optima, the test being norm(x k- xOpt(:,i)) ''<''= xEqTol*max(1,norm(x k)) that if fulfilled assumes x_k to be to close to xOpt(:,i).
|-
|||''fOpt''||The k function values in the local optima xOpt(:,i),i=1,...,k.
|-
|||''Inform''||The Inform value returned by the local solver when finding each of the local optima xOpt(:,i); i=1,...,k. The Inform value can be used to judge the validity of the local minimum reported.
|-
|||''localTry''||Total number of local searches.
|-
|||''Iter''||Total number of iterations.
|-
|||''FuncEv''||Total number of function evaluations.
|-
|||''GradEv''||Total number of gradient evaluations.
|-
|||''HessEv''||Total number of Hessian evaluations.
|-
|||''ConstrEv''||Total number of constraint function evaluations.
|-
|||''ExitText''||Text string giving Inform information.
|}

MultiMin

2015-03-09T14:16:06Z

Bjorn:

[[Category:Solvers]]
==Purpose==

multiMin solves general constrained mixed-integer global optimization problems. It tries to find all local minima by a multi-start method using a suitable nonlinear programming subsolver.

''multiMin ''solves problems of the form

<math>
\begin{array}{cccccc}
\min\limits_{x} & f(x) & & & & \\
s/t & x_{L} & \leq & x & \leq & x_{U} \\
& b_{L} & \leq & Ax & \leq & b_{U} \\
& c_{L} & \leq & c(x) & \leq & c_{U} \\
& & & {x_i \in \mathbb{N} \; \forall i \in I} \\
\end{array}
</math>

where <math>x,x_{L},x_{U}\in \mathbb{R}^{n}</math> , <math>c(x),c_{L},c_{U}\in \mathbb{R}^{m_{1}}</math> , <math>A\in \mathbb{R}^{m_{2}\times n}</math> and <math>b_{L},b_{U}\in \mathbb{R}^{m_{2}}</math>.

The variables <math>x \in I</math> , the index subset of <math>1,...,n</math> are restricted to be integers.

The integer components of every x_0 is rounded to the nearest integer value inside simple bounds, and these components are fixed during the nonlinear local search.

If generating random points and there are linear constraints, multiMin checks feasibility with respect to the linear constraints, and for each initial point tries 100 times to get linear feasibility before accepting the initial point.

==Calling Syntax==

<source lang="matlab">
Result = multiMin(Prob, xInit)
Result = tomRun('multiMin', Prob, PriLev) (driver call)
</source>

==Inputs==

{| class="wikitable"
!''Prob''||colspan="2"|Problem description structure. The following fields are used:
|-
|''xInit''||colspan="2"|Either, 1x1 number - The number of random initial points, default 10*Prob.N dxm matrix - Every column is an initial point (of length d=Prob.N). May also be set as Prob.xInit.
|-
|||''fCut''||If initial f(x_0) ''> ''fCut, no local optimization is done.
|-valign="top"
|||''WarmStart''||If true, ''> ''0, multiMin assumes the field multiMin defined with the output from a previous run on the same problem. See the Output fields of Result.multiMin. Use WarmDefGLOBAL to set the correct fields in the Prob structure. Nec- essary fields are fOpt and xOpt. If any of the other fields are missing, the corresponding variables are initialized to 0. These other fields are: localTry, Iter, FuncEv, GradEv, HessEv, ConstrEv Inform (is set to zeros(length(fOpt,1) if not defined).

In WarmDefGLOBAL the Result structure for the optimal run will be fed back to multiMin as Prob.multiMin.ResOpt In case this field is not defined, and no better point is found during the runs, a special call to the localSolver is used to generate a proper Result structure.
|-valign="top"
|||''RandState''||If ''WarmStart ''and isscalar(xInit), RandState is used as follows: If ''> ''0, rand('state',RandState) is set to initialize the pseudo-random generator if ''< ''0, rand('state',sum(100*clock)) is set to give a new set of random values each run if RandState == 0, rand('state',) is not called Default RandState = -1
|-valign="top"
|||''xEqTol''||Tolerance to test if new point x_k already defined as optimum: ''norm(xk - xOpt(:, i))'' <= ''xEqTol * max(1, norm(xk))'' If test fulfilled x_k is assumed to be too close to xOpt(:,i) Default xEqTol = 1E-5
|-
|||''x_L''||Lower bounds for each element in x. If generating random points, -inf elements of x L are set to -10000.
|-valign="top"
|||''x_U''||Upper bounds for each element in x. If generating random points, inf elements of x U are set to 10000.
|-
|||''A''||Constraint matrix for linear constraints.
|-
|||''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.
|-valign="top"
|||''PriLevOpt''||0 = silent.

1 = Display one row for each unique local minima found. The minima are sorted, lowest value first (possibly the global minima)

The following 4 information values are displayed:
# Order #
# Function value f(x) at local minima
# Point x at local minima. Only up to 10 values are displayed
# Inform value returned from local Solver (normally 0)

2 = One row of output from each multiMin local optimization trial

The following 6 information values are displayed:

# Step #
# Text Old (previously found local minima), FAIL (solver failed to verify local minima) or blank (solver success, new local minima found)
# Inform value from local solver
# f(x_0) - function value f(x_0) for initial x_0
# f(x) - best f(x) value found in this local search
# x - point for which best f(x) value was found in this local search. Only up to 10 values are displayed.

3 = tomRun (PrintResult) output from every optimization, print level 1.

4 = tomRun (PrintResult) output from every optimization, print level 2. For constrained problems output of sum(-constr-) and information if optimal point was accepted w.r.t. feasibility.

5 = tomRun (PrintResult) output from every optimization, print level 3.
|-
|||''GO''||Structure in ''Prob'', ''Prob.GO''. Fields used:
|-valign="top"
|||''localSolver''||The local solver used to run all local optimizations. Default is the license dependent output of GetSolver('con',1,0).
|-
|||''optParam''||Defines optimization parameters. Fields used:
|-valign="top"
|||''fGoal''||Goal for function value f(x), if empty not used. If fGoal is reached, no further local optimizations are done.
|-
|||''eps_f''||Relative accuracy for function value, fTol == eps_f. Stop if abs(f-fGoal) ''<''= abs(fGoal) * fTol , if fGoal = 0. Stop if abs(f-fGoal) ''<''= fTol , if fGoal ==0.
|-valign="top"
|||''bTol''||The local solver used to run all local optimizations. Default is the license dependent output of GetSolver('con',1,0).
|-valign="top"
|||''MIP.IntVars''||Structure in Prob, Prob.MIP. If empty, all variables are assumed non-integer (LP problem). If ''length''(''I ntV ars'') ''> ''1 ==''> length''(''I ntV ars'') == ''length''(''c'') should hold. Then ''I ntV ars''(''i'') == 1 ==''> x''(''i'') integer. ''I ntV ars''(''i'') == 0 ==''> x''(''i'') real. If ''length''(''I ntV ars'') ''< n'', IntVars is assumed to be a set of indices. It is advised to number the integer values as the first variables, before the continuous. The tree search will then be done more efficiently.
|-
|''varargin''||colspan="2"|Other parameters directly sent to low level routines.
|}

==Outputs==

{| class="wikitable"
!''Result''||colspan="2"|Structure with result from optimization. The following fields are changed:
|-
|||colspan="2"|The following fields in Result are changed by multiMin before return:
|-valign="top"
|||''ExitFlag''||= 0 normal output, of if fGoal set and found.

= 1 A solution reaching the user defined fGoal was not found
|-
|||colspan="2"|The Solver, SolverAlgorithm and ExitText fields are also reset.
|-
|||colspan="2"|A special field in Result is also returned, Result.multiMin:
|-valign="top"
|||''xOpt''||Prob.N x k matrix with k distinct local optima, the test being ''norm''(''xk -xOpt''(:'', i'')) ''<''= ''xEqTol * max''(1'', norm''(''xk '')) that if fulfilled assumes x_k to be to closeto xOpt(:,i)
|-valign="top"
|||''fOpt''||The k function values in the local optima xOpt(:,i),i=1,...,k.
|-valign="top"
|||''Inform''||The Inform value returned by the local solver when finding each of the local optima xOpt(:,i); i=1,...,k. The Inform value can be used to judge the validity of the local minimum reported.
|-
|||''localTry''||Total number of local searches.
|-
|||''Iter''||Total number of iterations.
|-
|||''FuncEv''||Total number of function evaluations.
|-
|||''GradEv''||Total number of gradient evaluations.
|-
|||''HessEv''||Total number of Hessian evaluations.
|-
|||''ConstrEv''||Total number of constraint function evaluations.
|-
|||''ExitText''||Text string giving ExitFlag and Inform information.
|}

MIPNLP

2015-03-09T13:59:56Z

Bjorn: /* TOMLAB /MIPNLP Solver References */

= Overview =

Welcome to the TOMLAB /MIPNLP User's Guide. TOMLAB /MIPNLP includes four solvers for mixed integer programming problems. The solvers take advantage of the wide array of subsolvers for LP, NLP and MILP in TOMLAB.

The solver package includes the following solvers:

[[MIPNLP_ecpMINLP|ecpMINLP]] - Solves convex or pseudo-convex mixed-integer nonlinear programming problems using an extended cutting plane algorithm with cuts regulated by a parameter-vector alpha. Cuts and linearizations are added to a MIP subproblem solved by a subsolver in each iteration. The solver algorithm is an implementation based on the publication 'Solving Pseudo-Convex Mixed Integer Optimization Problems by Cutting Plane Techniques' by Tapio Westerlund and Ray Pörn, Optimization and Engineering 3, 253-280, 2002, but with modifications.

[[MIPNLP_ecpMINLP|stoaMINLP]] - Single-search Tree Outer Approximation Solver for Mixed-Integer NonLinear Programming (MINLP). Is best suited for solving convex problems. The solver is mainly based on 'FilMINT: An Outer-Approximation-Based Solver for Nonlinear Mixed Integer Programs' by Kumar Abhishek, Sven Leyffer, and Jeffrey T. Linderoth at the Mathematics and Computer Science Division, Preprint ANL/MCS-P1374-0906, March 28, 2008, but with some differences.

==TOMLAB /MIPNLP Solver References==

* [[MIPNLP_ecpMINLP|ecpMINLP]]
* [[MIPNLP_stoaMINLP|stoaMINLP]]

MIPNLP

2015-03-09T13:59:42Z

Bjorn: /* Overview */

= Overview =

Welcome to the TOMLAB /MIPNLP User's Guide. TOMLAB /MIPNLP includes four solvers for mixed integer programming problems. The solvers take advantage of the wide array of subsolvers for LP, NLP and MILP in TOMLAB.

The solver package includes the following solvers:

[[MIPNLP_ecpMINLP|ecpMINLP]] - Solves convex or pseudo-convex mixed-integer nonlinear programming problems using an extended cutting plane algorithm with cuts regulated by a parameter-vector alpha. Cuts and linearizations are added to a MIP subproblem solved by a subsolver in each iteration. The solver algorithm is an implementation based on the publication 'Solving Pseudo-Convex Mixed Integer Optimization Problems by Cutting Plane Techniques' by Tapio Westerlund and Ray Pörn, Optimization and Engineering 3, 253-280, 2002, but with modifications.

[[MIPNLP_ecpMINLP|stoaMINLP]] - Single-search Tree Outer Approximation Solver for Mixed-Integer NonLinear Programming (MINLP). Is best suited for solving convex problems. The solver is mainly based on 'FilMINT: An Outer-Approximation-Based Solver for Nonlinear Mixed Integer Programs' by Kumar Abhishek, Sven Leyffer, and Jeffrey T. Linderoth at the Mathematics and Computer Science Division, Preprint ANL/MCS-P1374-0906, March 28, 2008, but with some differences.

==TOMLAB /MIPNLP Solver References==

* [[multiMin]]
* [[MIPNLP_ecpMINLP|ecpMINLP]]
* [[MIPNLP_stoaMINLP|stoaMINLP]]
* [[MultiMINLP|multiMINLP]]

MIPNLP ecpMINLP

2015-02-13T13:42:47Z

Bjorn: /* Outputs */

{{Part Of Manual|title=the MIPNLP Manual|link=[[MIPNLP|MIPNLP Manual]]}}
==Purpose==

ecpMINLP solves convex mixed-integer nonlinear programming problems (MINLP).

''ecpMINLP ''solves problems of the form

<math>
\begin{array}{cccccc}
\min\limits_{x} & f(x) \\s/t & x_{L} & \leq & x & \leq & x_{U} \\& b_{L} & \leq & Ax & \leq & b_{U} \\& c_{L} & \leq & c(x) & \leq & c_{U} \\& & & {x_{j} \in \mathbb{N} \ \ \forall j \in I} \\
\end{array}
</math>

where <math>x,x_{L},x_{U}\in \mathbb{R}^{n}</math> , <math>c(x),c_{L},c_{U}\in
\mathbb{R}^{m_{1}}</math> , <math>A\in \mathbb{R}^{m_{2}\times n}</math> and
<math>b_{L},b_{U}\in \mathbb{R}^{m_{2}}</math>. The variables <math>x \in I</math> , the
index subset of <math>1,...,n</math> are restricted to be integers but can be either continuously differentiable or not. An initalization routine will detect strict integer variables in the problem.

==Calling Syntax==

Driver call, including printing with level 2:
<source lang="matlab">
Result = tomRun('ecpMINLP',Prob,2);
</source>
Direct solver call:
<source lang="matlab">
Result = ecpMINLP(Prob);
PrintResult(Result);
Result = tomRun('ecpMINLP',Prob,...)
</source>

=== Warm Start ===
Warm start is currently not supported, but might be included in a future release.

==Inputs==

===Prob structure===
The '''TOMLAB''' problem structure

{|class="wikitable"
!colspan="2"|The following fields are used in the problem description structure Prob
|-
|'''Field'''||'''Description'''
|-
|''x_L''||Lower bounds on x.
|-
|''x_U''||Upper bounds on x.
|-
|''A''||The linear constraint matrix.
|-
|''b_L''||Lower bounds on linear constraints.
|-
|''b_U''||Upper bounds on linear constraints.
|-
|''c_L''||Lower bounds on nonlinear constraints.
|-
|''c_U''||Upper bounds on nonlinear constraints.
|-
|''f_Low''||Lower bound on solution.
|-
|''x_0''||Starting point.
|-valign="top"
|''MaxCPU''||Maximal CPU Time (in seconds) to be used by ecpMINLP, stops with best point found
|-valign="top"
|''PriLev''||Print level in ecpMINLP (default 1). Also see optParam.IterPrint
{|class="wikitable"
!value||output
|-
|=0||Silent.
|-
|>0||Initial information and convergence results.
|-
|>1||Output a line whenever the solution has improved, containing:
nIterations, nCuts, nCuts with criteria fulfilled, nLinearizations, nSpecialCuts, best solution.
|-
|>2||Output a line every iteration with the following information:
{|class="wikitable"
!label||description
|-
|It ||Iterations
|-
|nECP ||Number of extended cutting planes (ECP)
|-
|nAlpha>=lim||Number of ECP with criteria fulfilled
|-
|nL ||Number of linearizations
|-
|nSECP ||Number of special case ECP (created from constraint on bound)
|-
|fIPMin ||Objective of best solution at current iteration
|}
|-
|>3||Output a description of each step in the MINLP algorithm
|-
|>4||Output additional numerical information in some algorithm steps
|-
|>5||Output information in substeps (preprocessing, line search)
|}
|-valign="top"
|''PriLevOptMIP''||Print level in MIP sub-solvers, (CPLEX and others, see the documentation for the solver used). 
Usually: 
=0 No output 
>0 Convergence results 
>1 Output every iteration 
>2 Output each step in the algorithm
|-valign="top"
|''PriLevOptNLP''||Print level in NLP sub-solvers, (SNOPT and others, see the documentation for the solver used). 
Usually: 
=0 No output 
>0 Convergence results 
>1 Output every iteration 
>2 Output each step in the algorithm
|-valign="top"
|''SolverMIP''||Name of the solver used for MIP subproblems. If TOMLAB /gurobi is installed, gurobi is the default solver. If TOMLAB /CPLEX is installed, CPLEX is second choice as default. Otherwise the default solver is found calling GetSolver('mip',1); Supported as subsolvers are gurobi, CPLEX, mipSolve, milpSolve and cutplane.
|-valign="top"
|''SolverNLP''||
Name of the solver used for NLP subproblems. If packages /SOL or /SNOTP is installed, snopt is the default solver. Otherwise the default solver is found calling GetSolver('con',1);
|-
|''SolverLP''||Name of the solver used for LP subproblems when SolverMIP == mipSolve
|-
|''MIP''||Structure with parameters specific to mixed integer optimization. See the table below describing the fields used in the MIP structure.
|-
|''ECPMINLP''||Structure with parameters specific to the ecpMINLP solver. See the table below describing the fields used in the ECPMINLP structure.
|-
|''optParam''||Structure with general optimization parameters. See the table below describing the fields used in the optParam structure.
|}

===MIP structure===
Substructure in Prob with parameters related to mixed integer programming.

{|class="wikitable"
!colspan="2"|'''fields used in Prob.MIP''':
|-
|'''Field'''||'''Description'''
|-valign="top"
|''IntVars''||If empty, all variables are assumed non-integer. If islogical(IntVars) (=all elements are 0/1), then 1 = integer variable, 0 = continuous variable. If any element ''>''1, IntVars is the indices for integer variables.
|-valign="top"
|''fIP''||An upper bound on the IP value wanted. Makes it possible to cut branches and avoid node computations. Used even if xIP not given.
|-valign="top"
|''xIP''||The x-values giving the fIP value, if a solution (xIP,fIP) is known.
|-valign="top"
|''DualGap''||ecpMINLP stops if the duality gap is less than DualGap
DualGap = 1, stop at first integer solution, e.g. DualGap = 0.01,stop if solution < 1% from optimal solution.
 The lower bound Prob.f_Low is used, (default -1.0e300), which can also be set by the user. If f_Low has not been changed from default the lower bound is obtained from the initial solution of a relaxed problem, but only when ECPMINLP.INIT_BND is 1 or 2 (default).
 Default DualGap is -1, not used.
|-valign="top"
|''PPP''||Pre-processing and probing, default is 0. 
0 Not used. Default. 
1 Apply initially on MINLP problem. 
2 Apply each iteration before solving MILP sub-problem.
|-
|''ROUNDH''||If nonzero, a rounding heuristics will be used on the initial NLP solution in order to obtain an initial integer solution. Requires ECPMINLP.InitBndType enabled. Default is 1, enabled.
|}

===ECPMINLP structure===
Substructure in ''Prob'' with solver-specific options.

{|class="wikitable"
!colspan="2"|fields used in Prob.ECPMINLP
|-
|'''Field'''||'''Description'''
|-valign="top"
|''beta''||Multiplier when increasing alpha after an infeasible MILP solution.
 Alpha is a parameter individually adjusting each cutting plane, starting at 1.0 and increasing until meeting a certain criterion. Default value for beta is 1.3.
|-valign="top"
|''gamma''||Multiplier when increasing alpha when MILP solution does not violate any nonlinear contraints, but still does not decrease the upper bound of the objective.
 Alpha is a parameter individually adjusting each cutting plane, starting at 1.0 and increasing until meeting a certain criterion. Default value for gamma is 2.0.
|-valign="top"
|''PREALLOC''||Flag enabling preallocation of memory for cutting planes and linearizations.
 0 No preallocation, dynamic growth of arrays. Current default.
 1 Preallocate arrays.
|-valign="top"
|''InitBndType''||Selects method for setting lower bound when f_Low not changed from default.
{|class="wikitable"
!value||method
|-valign="top"
|0 ||No extra initial lower bound.
|-valign="top"
|1 ||Use default TOMLAB NLP solver on problem with relaxed integer constraints. Add a linearization if a feasible MINLP solution was found.
|-valign="top"
|2 ||Add an initial linearization as long as a feasible NLP solution was found. The linearization is a simple lower bound on the MILP objective. Default.
|}
|-valign="top"
|''SET_TOL''||Flag enabling changing tolerances, described below under optParam.eps_x, optParam.eps_x and optParam.eps_f.
 0 Default. Using the recommended solver default values, 1.0e-3.
 1 Tolerances can be changed, taken from Prob.optParam.
|-valign="top"
|''IntSolLimIncr''||Integer option when using CPLEX as MIP subsolver.
 Define how much the CPLEX parameter IntSolLimIncr increases when a feasible solution is not optimal and all alpha values have met their criteria.
 When set to zero, the optimal strategy will instead be used immediately, without any gradual increase of INTSOLLIM.
 Default is 1.
|-valign="top"
|''USE_CUTPOOL''||Set nonzero to use a pool for the alpha-regulated extended cutting planes.
 Cuts not active in the MILP-solution for CutDelBound iterations in a row will be inactivated (removed from the MILP-problem) until they are violated in a new solution.
 Default is 0, not used.
|-valign="top"
|''CutDelBound''||The number of consecutive times an extended cutting plane can be inactive before it gets removed and put into the inactive pool, if the option USE_CUTPOOL is set nonzero.
 Default is 15 times.
|-valign="top"
|''MaxIterWoImpr''||Limit on the number of successive iterations allowed without any improvements at all to neither objective nor solution point before the solver terminates
 Default is 2.
|-valign="top"
|''USE_NLP''||Set nonzero to use an NLP sub-solver on the original problem with the integer variables fixed at values from the latest MILP solution. Default is 1, enabled.
|-valign="top"
|''RESELECT_CUTS''||Set nonzero to enable cut reselection heuristics. Default is 1, enabled.
|-valign="top"
|''SCALE_CUTS''||Set nonzero to scale cuts before they are added to the MILP problem. Scaling is done by dividing the cut with its norm. Default is 1, enabled.
|}

===optParam Structure===
Substructure in ''Prob'' with general optimization parameters.

{|class="wikitable"
!colspan="2"|fields used in Prob.optParam
|-
|'''Field'''||'''Value'''
|-valign="top"
|''MaxIter''||Maximal number of iterations, default 10000
|-valign="top"
|''IterPrint''||Print short information each iteration. Setting PriLev > 2 also enables IterPrint, setting it to 1.
|-valign="top"
|''eps_x''||Linear constraint violation convergence tolerance. Default is 2.0e-6
|-valign="top"
|''eps_g''||Constraint violation convergence tolerance. Default is 1.0e-7
|-valign="top"
|''eps_f''||Optimality tolerance. Default is 1.0e-8
|}

''NOTE:'' For the solver to use these tolerances, the flag ''ECPMINLP.SET_TOL'' must be set to nonzero.

==Outputs==

{| class="wikitable"
!''Result''||colspan="2"|Structure with result from optimization. The following fields are used:
|-
|||''Iter ''||Number of iterations.
|-valign="top"
|||''ExitFlag ''||Exit flag.
 0: Solution found, or integer solution with duality gap less than user tolerance.
 1: Maximal number of iterations reached.
 2: Empty feasible set, no integer solution found.
 3: Problem in subsolver, see Inform value.
 99: Maximal CPU Time used (cputime > Prob.maxCPU
|-
|||''Inform''||Inform for ExitFlag != 3
 0: Global solution found.
 1: Local solution found.
 2: No solution found.
 >2: Inform value from subsolver.
|-
|||''ExitText''||Text string giving ''ExitFlag'' and ''Inform'' information.
|-valign="top"
|||''DualGap''||Relative duality gap, set as follows:

{| class="wikitable"
!''Condition fulfilled''||DualGap value set
|-
||fIPMin ~= 0||max(0,fIPMin-fLB)/|fIPMin|
|-
||fIPMin == 0||max(0,fIPMin-fLB)
|}
To get the percentage duality gap, scale with 100. 
PercentageGap = 100*Dual- Gap. 
To get the absolute value duality gap, scale with fIPMin. 
AbsoluteGap = fIPMin * DualGap
|-
|||''x_k''||Solution.
|-
|||''x''||Vector of solution points, sorted on ascending order based on the correcsponding objective values returned in f. x(:,1) is always equal to x_k.
|-valign="top"
|||''f_k''||Function value at optimum.
|-
|||''f''||The objective vales at all encountered solution points in x. Sorted in ascending order.
|-
|||''g_k''||Gradient vector at optimum.
|-
|||''c_k''||Constraint values at optimum.
|-
|||''cJac''||Constraint derivative values at optimum.
|-
|||''xState''||State of each variable, described in [[TOMLAB_Appendix_B#Table:_The_state_variable_xState_for_the_variable.|TOMLAB Appendix B]].
|-
|||''bState''||State of each constraint, described in [[TOMLAB_Appendix_B#Table:_The_state_variable_bState_for_each_linear_constraint.|TOMLAB Appendix B]].
|-
|||''cState''||State of each general constraint, described in [[TOMLAB_Appendix_B#Table:_The_state_variable_cState_for_each_nonlinear_constraint.|TOMLAB Appendix B]].
|-
|||''x_0''||Starting point x_0.
|-
|||''Solver''||Solver used ('ecpMINLP').
|-
|||''SolverAlgorithm''||Description of method used.
|-
|||''Prob''||Problem structure used.
|}

== Algorithm==
ecpMINLP Solves convex or pseudo-convex mixed-integer nonlinear programming problems using an extended cutting plane algorithm with cuts regulated by a parameter-vector alpha. Cuts and linearizations are added to MIP subproblem which is then solved by a subsolver in each iteration.

The solver algorithm is mainly based on the paper 'Solving Pseudo-Convex Mixed Integer Optimization Problems by Cutting Plane Techniques' by Tapio Westerlund and Ray Pörn, published in Optimization and Engineering 3, 253-280, 2002, with some modifications.

Most prominent features in addition to the ones described in the main reference above are
* Solving the relaxed NLP problem initially to obtain a lower bound on the solution.
* A rounding heuristics performed on the initial NLP solution in order to obtain an initial upper bound on the initial solutions.
* Optional use of a cutpool for the alpha-regulated extended cutting planes.
* Special treatment of problems with integer variables which are not continuously differentiable.
[[Category:MIPNLP]]

MIPNLP ecpMINLP

2015-02-13T13:39:35Z

Bjorn: /* Algorithm */

{{Part Of Manual|title=the MIPNLP Manual|link=[[MIPNLP|MIPNLP Manual]]}}
==Purpose==

ecpMINLP solves convex mixed-integer nonlinear programming problems (MINLP).

''ecpMINLP ''solves problems of the form

<math>
\begin{array}{cccccc}
\min\limits_{x} & f(x) \\s/t & x_{L} & \leq & x & \leq & x_{U} \\& b_{L} & \leq & Ax & \leq & b_{U} \\& c_{L} & \leq & c(x) & \leq & c_{U} \\& & & {x_{j} \in \mathbb{N} \ \ \forall j \in I} \\
\end{array}
</math>

where <math>x,x_{L},x_{U}\in \mathbb{R}^{n}</math> , <math>c(x),c_{L},c_{U}\in
\mathbb{R}^{m_{1}}</math> , <math>A\in \mathbb{R}^{m_{2}\times n}</math> and
<math>b_{L},b_{U}\in \mathbb{R}^{m_{2}}</math>. The variables <math>x \in I</math> , the
index subset of <math>1,...,n</math> are restricted to be integers but can be either continuously differentiable or not. An initalization routine will detect strict integer variables in the problem.

==Calling Syntax==

Driver call, including printing with level 2:
<source lang="matlab">
Result = tomRun('ecpMINLP',Prob,2);
</source>
Direct solver call:
<source lang="matlab">
Result = ecpMINLP(Prob);
PrintResult(Result);
Result = tomRun('ecpMINLP',Prob,...)
</source>

=== Warm Start ===
Warm start is currently not supported, but might be included in a future release.

==Inputs==

===Prob structure===
The '''TOMLAB''' problem structure

{|class="wikitable"
!colspan="2"|The following fields are used in the problem description structure Prob
|-
|'''Field'''||'''Description'''
|-
|''x_L''||Lower bounds on x.
|-
|''x_U''||Upper bounds on x.
|-
|''A''||The linear constraint matrix.
|-
|''b_L''||Lower bounds on linear constraints.
|-
|''b_U''||Upper bounds on linear constraints.
|-
|''c_L''||Lower bounds on nonlinear constraints.
|-
|''c_U''||Upper bounds on nonlinear constraints.
|-
|''f_Low''||Lower bound on solution.
|-
|''x_0''||Starting point.
|-valign="top"
|''MaxCPU''||Maximal CPU Time (in seconds) to be used by ecpMINLP, stops with best point found
|-valign="top"
|''PriLev''||Print level in ecpMINLP (default 1). Also see optParam.IterPrint
{|class="wikitable"
!value||output
|-
|=0||Silent.
|-
|>0||Initial information and convergence results.
|-
|>1||Output a line whenever the solution has improved, containing:
nIterations, nCuts, nCuts with criteria fulfilled, nLinearizations, nSpecialCuts, best solution.
|-
|>2||Output a line every iteration with the following information:
{|class="wikitable"
!label||description
|-
|It ||Iterations
|-
|nECP ||Number of extended cutting planes (ECP)
|-
|nAlpha>=lim||Number of ECP with criteria fulfilled
|-
|nL ||Number of linearizations
|-
|nSECP ||Number of special case ECP (created from constraint on bound)
|-
|fIPMin ||Objective of best solution at current iteration
|}
|-
|>3||Output a description of each step in the MINLP algorithm
|-
|>4||Output additional numerical information in some algorithm steps
|-
|>5||Output information in substeps (preprocessing, line search)
|}
|-valign="top"
|''PriLevOptMIP''||Print level in MIP sub-solvers, (CPLEX and others, see the documentation for the solver used). 
Usually: 
=0 No output 
>0 Convergence results 
>1 Output every iteration 
>2 Output each step in the algorithm
|-valign="top"
|''PriLevOptNLP''||Print level in NLP sub-solvers, (SNOPT and others, see the documentation for the solver used). 
Usually: 
=0 No output 
>0 Convergence results 
>1 Output every iteration 
>2 Output each step in the algorithm
|-valign="top"
|''SolverMIP''||Name of the solver used for MIP subproblems. If TOMLAB /gurobi is installed, gurobi is the default solver. If TOMLAB /CPLEX is installed, CPLEX is second choice as default. Otherwise the default solver is found calling GetSolver('mip',1); Supported as subsolvers are gurobi, CPLEX, mipSolve, milpSolve and cutplane.
|-valign="top"
|''SolverNLP''||
Name of the solver used for NLP subproblems. If packages /SOL or /SNOTP is installed, snopt is the default solver. Otherwise the default solver is found calling GetSolver('con',1);
|-
|''SolverLP''||Name of the solver used for LP subproblems when SolverMIP == mipSolve
|-
|''MIP''||Structure with parameters specific to mixed integer optimization. See the table below describing the fields used in the MIP structure.
|-
|''ECPMINLP''||Structure with parameters specific to the ecpMINLP solver. See the table below describing the fields used in the ECPMINLP structure.
|-
|''optParam''||Structure with general optimization parameters. See the table below describing the fields used in the optParam structure.
|}

===MIP structure===
Substructure in Prob with parameters related to mixed integer programming.

{|class="wikitable"
!colspan="2"|'''fields used in Prob.MIP''':
|-
|'''Field'''||'''Description'''
|-valign="top"
|''IntVars''||If empty, all variables are assumed non-integer. If islogical(IntVars) (=all elements are 0/1), then 1 = integer variable, 0 = continuous variable. If any element ''>''1, IntVars is the indices for integer variables.
|-valign="top"
|''fIP''||An upper bound on the IP value wanted. Makes it possible to cut branches and avoid node computations. Used even if xIP not given.
|-valign="top"
|''xIP''||The x-values giving the fIP value, if a solution (xIP,fIP) is known.
|-valign="top"
|''DualGap''||ecpMINLP stops if the duality gap is less than DualGap
DualGap = 1, stop at first integer solution, e.g. DualGap = 0.01,stop if solution < 1% from optimal solution.
 The lower bound Prob.f_Low is used, (default -1.0e300), which can also be set by the user. If f_Low has not been changed from default the lower bound is obtained from the initial solution of a relaxed problem, but only when ECPMINLP.INIT_BND is 1 or 2 (default).
 Default DualGap is -1, not used.
|-valign="top"
|''PPP''||Pre-processing and probing, default is 0. 
0 Not used. Default. 
1 Apply initially on MINLP problem. 
2 Apply each iteration before solving MILP sub-problem.
|-
|''ROUNDH''||If nonzero, a rounding heuristics will be used on the initial NLP solution in order to obtain an initial integer solution. Requires ECPMINLP.InitBndType enabled. Default is 1, enabled.
|}

===ECPMINLP structure===
Substructure in ''Prob'' with solver-specific options.

{|class="wikitable"
!colspan="2"|fields used in Prob.ECPMINLP
|-
|'''Field'''||'''Description'''
|-valign="top"
|''beta''||Multiplier when increasing alpha after an infeasible MILP solution.
 Alpha is a parameter individually adjusting each cutting plane, starting at 1.0 and increasing until meeting a certain criterion. Default value for beta is 1.3.
|-valign="top"
|''gamma''||Multiplier when increasing alpha when MILP solution does not violate any nonlinear contraints, but still does not decrease the upper bound of the objective.
 Alpha is a parameter individually adjusting each cutting plane, starting at 1.0 and increasing until meeting a certain criterion. Default value for gamma is 2.0.
|-valign="top"
|''PREALLOC''||Flag enabling preallocation of memory for cutting planes and linearizations.
 0 No preallocation, dynamic growth of arrays. Current default.
 1 Preallocate arrays.
|-valign="top"
|''InitBndType''||Selects method for setting lower bound when f_Low not changed from default.
{|class="wikitable"
!value||method
|-valign="top"
|0 ||No extra initial lower bound.
|-valign="top"
|1 ||Use default TOMLAB NLP solver on problem with relaxed integer constraints. Add a linearization if a feasible MINLP solution was found.
|-valign="top"
|2 ||Add an initial linearization as long as a feasible NLP solution was found. The linearization is a simple lower bound on the MILP objective. Default.
|}
|-valign="top"
|''SET_TOL''||Flag enabling changing tolerances, described below under optParam.eps_x, optParam.eps_x and optParam.eps_f.
 0 Default. Using the recommended solver default values, 1.0e-3.
 1 Tolerances can be changed, taken from Prob.optParam.
|-valign="top"
|''IntSolLimIncr''||Integer option when using CPLEX as MIP subsolver.
 Define how much the CPLEX parameter IntSolLimIncr increases when a feasible solution is not optimal and all alpha values have met their criteria.
 When set to zero, the optimal strategy will instead be used immediately, without any gradual increase of INTSOLLIM.
 Default is 1.
|-valign="top"
|''USE_CUTPOOL''||Set nonzero to use a pool for the alpha-regulated extended cutting planes.
 Cuts not active in the MILP-solution for CutDelBound iterations in a row will be inactivated (removed from the MILP-problem) until they are violated in a new solution.
 Default is 0, not used.
|-valign="top"
|''CutDelBound''||The number of consecutive times an extended cutting plane can be inactive before it gets removed and put into the inactive pool, if the option USE_CUTPOOL is set nonzero.
 Default is 15 times.
|-valign="top"
|''MaxIterWoImpr''||Limit on the number of successive iterations allowed without any improvements at all to neither objective nor solution point before the solver terminates
 Default is 2.
|-valign="top"
|''USE_NLP''||Set nonzero to use an NLP sub-solver on the original problem with the integer variables fixed at values from the latest MILP solution. Default is 1, enabled.
|-valign="top"
|''RESELECT_CUTS''||Set nonzero to enable cut reselection heuristics. Default is 1, enabled.
|-valign="top"
|''SCALE_CUTS''||Set nonzero to scale cuts before they are added to the MILP problem. Scaling is done by dividing the cut with its norm. Default is 1, enabled.
|}

===optParam Structure===
Substructure in ''Prob'' with general optimization parameters.

{|class="wikitable"
!colspan="2"|fields used in Prob.optParam
|-
|'''Field'''||'''Value'''
|-valign="top"
|''MaxIter''||Maximal number of iterations, default 10000
|-valign="top"
|''IterPrint''||Print short information each iteration. Setting PriLev > 2 also enables IterPrint, setting it to 1.
|-valign="top"
|''eps_x''||Linear constraint violation convergence tolerance. Default is 2.0e-6
|-valign="top"
|''eps_g''||Constraint violation convergence tolerance. Default is 1.0e-7
|-valign="top"
|''eps_f''||Optimality tolerance. Default is 1.0e-8
|}

''NOTE:'' For the solver to use these tolerances, the flag ''ECPMINLP.SET_TOL'' must be set to nonzero.

==Outputs==

{| class="wikitable"
!''Result''||colspan="2"|Structure with result from optimization. The following fields are changed:
|-
|||''Iter ''||Number of iterations.
|-valign="top"
|||''ExitFlag ''||Exit flag.
 0: Solution found, or integer solution with duality gap less than user tolerance.
 1: Maximal number of iterations reached.
 2: Empty feasible set, no integer solution found.
 3: Problem in subsolver, see Inform value.
 99: Maximal CPU Time used (cputime > Prob.maxCPU
|-
|||''Inform''||Inform for ExitFlag != 3
 0: Global solution found.
 1: Local solution found.
 2: No solution found.
 >2: Inform value from subsolver.
|-
|||''ExitText''||Text string giving ''ExitFlag'' and ''Inform'' information.
|-valign="top"
|||''DualGap''||Relative duality gap, set as follows:

{| class="wikitable"
!''Condition fulfilled''||DualGap value set
|-
||fIPMin ~= 0||max(0,fIPMin-fLB)/|fIPMin|
|-
||fIPMin == 0||max(0,fIPMin-fLB)
|}
To get the percentage duality gap, scale with 100. 
PercentageGap = 100*Dual- Gap. 
To get the absolute value duality gap, scale with fIPMin. 
AbsoluteGap = fIPMin * DualGap
|-
|||''x_k''||Solution.
|-
|||''x''||Vector of solution points, sorted on ascending order based on the correcsponding objective values returned in f. x(:,1) is always equal to x_k.
|-valign="top"
|||''f_k''||Function value at optimum.
|-
|||''f''||The objective vales at all encountered solution points in x. Sorted in ascending order.
|-
|||''g_k''||Gradient vector at optimum.
|-
|||''c_k''||Constraint values at optimum.
|-
|||''cJac''||Constraint derivative values at optimum.
|-
|||''xState''||State of each variable, described in [[TOMLAB_Appendix_B#Table:_The_state_variable_xState_for_the_variable.|TOMLAB Appendix B]].
|-
|||''bState''||State of each constraint, described in [[TOMLAB_Appendix_B#Table:_The_state_variable_bState_for_each_linear_constraint.|TOMLAB Appendix B]].
|-
|||''cState''||State of each general constraint, described in [[TOMLAB_Appendix_B#Table:_The_state_variable_cState_for_each_nonlinear_constraint.|TOMLAB Appendix B]].
|-
|||''x_0''||Starting point x_0.
|-
|||''Solver''||Solver used ('ecpMINLP').
|-
|||''SolverAlgorithm''||Description of method used.
|-
|||''Prob''||Problem structure used.
|}

== Algorithm==
ecpMINLP Solves convex or pseudo-convex mixed-integer nonlinear programming problems using an extended cutting plane algorithm with cuts regulated by a parameter-vector alpha. Cuts and linearizations are added to MIP subproblem which is then solved by a subsolver in each iteration.

The solver algorithm is mainly based on the paper 'Solving Pseudo-Convex Mixed Integer Optimization Problems by Cutting Plane Techniques' by Tapio Westerlund and Ray Pörn, published in Optimization and Engineering 3, 253-280, 2002, with some modifications.

Most prominent features in addition to the ones described in the main reference above are
* Solving the relaxed NLP problem initially to obtain a lower bound on the solution.
* A rounding heuristics performed on the initial NLP solution in order to obtain an initial upper bound on the initial solutions.
* Optional use of a cutpool for the alpha-regulated extended cutting planes.
* Special treatment of problems with integer variables which are not continuously differentiable.
[[Category:MIPNLP]]

MIPNLP ecpMINLP

2015-02-13T13:38:34Z

Bjorn: /* Outputs */

{{Part Of Manual|title=the MIPNLP Manual|link=[[MIPNLP|MIPNLP Manual]]}}
==Purpose==

ecpMINLP solves convex mixed-integer nonlinear programming problems (MINLP).

''ecpMINLP ''solves problems of the form

<math>
\begin{array}{cccccc}
\min\limits_{x} & f(x) \\s/t & x_{L} & \leq & x & \leq & x_{U} \\& b_{L} & \leq & Ax & \leq & b_{U} \\& c_{L} & \leq & c(x) & \leq & c_{U} \\& & & {x_{j} \in \mathbb{N} \ \ \forall j \in I} \\
\end{array}
</math>

where <math>x,x_{L},x_{U}\in \mathbb{R}^{n}</math> , <math>c(x),c_{L},c_{U}\in
\mathbb{R}^{m_{1}}</math> , <math>A\in \mathbb{R}^{m_{2}\times n}</math> and
<math>b_{L},b_{U}\in \mathbb{R}^{m_{2}}</math>. The variables <math>x \in I</math> , the
index subset of <math>1,...,n</math> are restricted to be integers but can be either continuously differentiable or not. An initalization routine will detect strict integer variables in the problem.

==Calling Syntax==

Driver call, including printing with level 2:
<source lang="matlab">
Result = tomRun('ecpMINLP',Prob,2);
</source>
Direct solver call:
<source lang="matlab">
Result = ecpMINLP(Prob);
PrintResult(Result);
Result = tomRun('ecpMINLP',Prob,...)
</source>

=== Warm Start ===
Warm start is currently not supported, but might be included in a future release.

==Inputs==

===Prob structure===
The '''TOMLAB''' problem structure

{|class="wikitable"
!colspan="2"|The following fields are used in the problem description structure Prob
|-
|'''Field'''||'''Description'''
|-
|''x_L''||Lower bounds on x.
|-
|''x_U''||Upper bounds on x.
|-
|''A''||The linear constraint matrix.
|-
|''b_L''||Lower bounds on linear constraints.
|-
|''b_U''||Upper bounds on linear constraints.
|-
|''c_L''||Lower bounds on nonlinear constraints.
|-
|''c_U''||Upper bounds on nonlinear constraints.
|-
|''f_Low''||Lower bound on solution.
|-
|''x_0''||Starting point.
|-valign="top"
|''MaxCPU''||Maximal CPU Time (in seconds) to be used by ecpMINLP, stops with best point found
|-valign="top"
|''PriLev''||Print level in ecpMINLP (default 1). Also see optParam.IterPrint
{|class="wikitable"
!value||output
|-
|=0||Silent.
|-
|>0||Initial information and convergence results.
|-
|>1||Output a line whenever the solution has improved, containing:
nIterations, nCuts, nCuts with criteria fulfilled, nLinearizations, nSpecialCuts, best solution.
|-
|>2||Output a line every iteration with the following information:
{|class="wikitable"
!label||description
|-
|It ||Iterations
|-
|nECP ||Number of extended cutting planes (ECP)
|-
|nAlpha>=lim||Number of ECP with criteria fulfilled
|-
|nL ||Number of linearizations
|-
|nSECP ||Number of special case ECP (created from constraint on bound)
|-
|fIPMin ||Objective of best solution at current iteration
|}
|-
|>3||Output a description of each step in the MINLP algorithm
|-
|>4||Output additional numerical information in some algorithm steps
|-
|>5||Output information in substeps (preprocessing, line search)
|}
|-valign="top"
|''PriLevOptMIP''||Print level in MIP sub-solvers, (CPLEX and others, see the documentation for the solver used). 
Usually: 
=0 No output 
>0 Convergence results 
>1 Output every iteration 
>2 Output each step in the algorithm
|-valign="top"
|''PriLevOptNLP''||Print level in NLP sub-solvers, (SNOPT and others, see the documentation for the solver used). 
Usually: 
=0 No output 
>0 Convergence results 
>1 Output every iteration 
>2 Output each step in the algorithm
|-valign="top"
|''SolverMIP''||Name of the solver used for MIP subproblems. If TOMLAB /gurobi is installed, gurobi is the default solver. If TOMLAB /CPLEX is installed, CPLEX is second choice as default. Otherwise the default solver is found calling GetSolver('mip',1); Supported as subsolvers are gurobi, CPLEX, mipSolve, milpSolve and cutplane.
|-valign="top"
|''SolverNLP''||
Name of the solver used for NLP subproblems. If packages /SOL or /SNOTP is installed, snopt is the default solver. Otherwise the default solver is found calling GetSolver('con',1);
|-
|''SolverLP''||Name of the solver used for LP subproblems when SolverMIP == mipSolve
|-
|''MIP''||Structure with parameters specific to mixed integer optimization. See the table below describing the fields used in the MIP structure.
|-
|''ECPMINLP''||Structure with parameters specific to the ecpMINLP solver. See the table below describing the fields used in the ECPMINLP structure.
|-
|''optParam''||Structure with general optimization parameters. See the table below describing the fields used in the optParam structure.
|}

===MIP structure===
Substructure in Prob with parameters related to mixed integer programming.

{|class="wikitable"
!colspan="2"|'''fields used in Prob.MIP''':
|-
|'''Field'''||'''Description'''
|-valign="top"
|''IntVars''||If empty, all variables are assumed non-integer. If islogical(IntVars) (=all elements are 0/1), then 1 = integer variable, 0 = continuous variable. If any element ''>''1, IntVars is the indices for integer variables.
|-valign="top"
|''fIP''||An upper bound on the IP value wanted. Makes it possible to cut branches and avoid node computations. Used even if xIP not given.
|-valign="top"
|''xIP''||The x-values giving the fIP value, if a solution (xIP,fIP) is known.
|-valign="top"
|''DualGap''||ecpMINLP stops if the duality gap is less than DualGap
DualGap = 1, stop at first integer solution, e.g. DualGap = 0.01,stop if solution < 1% from optimal solution.
 The lower bound Prob.f_Low is used, (default -1.0e300), which can also be set by the user. If f_Low has not been changed from default the lower bound is obtained from the initial solution of a relaxed problem, but only when ECPMINLP.INIT_BND is 1 or 2 (default).
 Default DualGap is -1, not used.
|-valign="top"
|''PPP''||Pre-processing and probing, default is 0. 
0 Not used. Default. 
1 Apply initially on MINLP problem. 
2 Apply each iteration before solving MILP sub-problem.
|-
|''ROUNDH''||If nonzero, a rounding heuristics will be used on the initial NLP solution in order to obtain an initial integer solution. Requires ECPMINLP.InitBndType enabled. Default is 1, enabled.
|}

===ECPMINLP structure===
Substructure in ''Prob'' with solver-specific options.

{|class="wikitable"
!colspan="2"|fields used in Prob.ECPMINLP
|-
|'''Field'''||'''Description'''
|-valign="top"
|''beta''||Multiplier when increasing alpha after an infeasible MILP solution.
 Alpha is a parameter individually adjusting each cutting plane, starting at 1.0 and increasing until meeting a certain criterion. Default value for beta is 1.3.
|-valign="top"
|''gamma''||Multiplier when increasing alpha when MILP solution does not violate any nonlinear contraints, but still does not decrease the upper bound of the objective.
 Alpha is a parameter individually adjusting each cutting plane, starting at 1.0 and increasing until meeting a certain criterion. Default value for gamma is 2.0.
|-valign="top"
|''PREALLOC''||Flag enabling preallocation of memory for cutting planes and linearizations.
 0 No preallocation, dynamic growth of arrays. Current default.
 1 Preallocate arrays.
|-valign="top"
|''InitBndType''||Selects method for setting lower bound when f_Low not changed from default.
{|class="wikitable"
!value||method
|-valign="top"
|0 ||No extra initial lower bound.
|-valign="top"
|1 ||Use default TOMLAB NLP solver on problem with relaxed integer constraints. Add a linearization if a feasible MINLP solution was found.
|-valign="top"
|2 ||Add an initial linearization as long as a feasible NLP solution was found. The linearization is a simple lower bound on the MILP objective. Default.
|}
|-valign="top"
|''SET_TOL''||Flag enabling changing tolerances, described below under optParam.eps_x, optParam.eps_x and optParam.eps_f.
 0 Default. Using the recommended solver default values, 1.0e-3.
 1 Tolerances can be changed, taken from Prob.optParam.
|-valign="top"
|''IntSolLimIncr''||Integer option when using CPLEX as MIP subsolver.
 Define how much the CPLEX parameter IntSolLimIncr increases when a feasible solution is not optimal and all alpha values have met their criteria.
 When set to zero, the optimal strategy will instead be used immediately, without any gradual increase of INTSOLLIM.
 Default is 1.
|-valign="top"
|''USE_CUTPOOL''||Set nonzero to use a pool for the alpha-regulated extended cutting planes.
 Cuts not active in the MILP-solution for CutDelBound iterations in a row will be inactivated (removed from the MILP-problem) until they are violated in a new solution.
 Default is 0, not used.
|-valign="top"
|''CutDelBound''||The number of consecutive times an extended cutting plane can be inactive before it gets removed and put into the inactive pool, if the option USE_CUTPOOL is set nonzero.
 Default is 15 times.
|-valign="top"
|''MaxIterWoImpr''||Limit on the number of successive iterations allowed without any improvements at all to neither objective nor solution point before the solver terminates
 Default is 2.
|-valign="top"
|''USE_NLP''||Set nonzero to use an NLP sub-solver on the original problem with the integer variables fixed at values from the latest MILP solution. Default is 1, enabled.
|-valign="top"
|''RESELECT_CUTS''||Set nonzero to enable cut reselection heuristics. Default is 1, enabled.
|-valign="top"
|''SCALE_CUTS''||Set nonzero to scale cuts before they are added to the MILP problem. Scaling is done by dividing the cut with its norm. Default is 1, enabled.
|}

===optParam Structure===
Substructure in ''Prob'' with general optimization parameters.

{|class="wikitable"
!colspan="2"|fields used in Prob.optParam
|-
|'''Field'''||'''Value'''
|-valign="top"
|''MaxIter''||Maximal number of iterations, default 10000
|-valign="top"
|''IterPrint''||Print short information each iteration. Setting PriLev > 2 also enables IterPrint, setting it to 1.
|-valign="top"
|''eps_x''||Linear constraint violation convergence tolerance. Default is 2.0e-6
|-valign="top"
|''eps_g''||Constraint violation convergence tolerance. Default is 1.0e-7
|-valign="top"
|''eps_f''||Optimality tolerance. Default is 1.0e-8
|}

''NOTE:'' For the solver to use these tolerances, the flag ''ECPMINLP.SET_TOL'' must be set to nonzero.

==Outputs==

{| class="wikitable"
!''Result''||colspan="2"|Structure with result from optimization. The following fields are changed:
|-
|||''Iter ''||Number of iterations.
|-valign="top"
|||''ExitFlag ''||Exit flag.
 0: Solution found, or integer solution with duality gap less than user tolerance.
 1: Maximal number of iterations reached.
 2: Empty feasible set, no integer solution found.
 3: Problem in subsolver, see Inform value.
 99: Maximal CPU Time used (cputime > Prob.maxCPU
|-
|||''Inform''||Inform for ExitFlag != 3
 0: Global solution found.
 1: Local solution found.
 2: No solution found.
 >2: Inform value from subsolver.
|-
|||''ExitText''||Text string giving ''ExitFlag'' and ''Inform'' information.
|-valign="top"
|||''DualGap''||Relative duality gap, set as follows:

{| class="wikitable"
!''Condition fulfilled''||DualGap value set
|-
||fIPMin ~= 0||max(0,fIPMin-fLB)/|fIPMin|
|-
||fIPMin == 0||max(0,fIPMin-fLB)
|}
To get the percentage duality gap, scale with 100. 
PercentageGap = 100*Dual- Gap. 
To get the absolute value duality gap, scale with fIPMin. 
AbsoluteGap = fIPMin * DualGap
|-
|||''x_k''||Solution.
|-
|||''x''||Vector of solution points, sorted on ascending order based on the correcsponding objective values returned in f. x(:,1) is always equal to x_k.
|-valign="top"
|||''f_k''||Function value at optimum.
|-
|||''f''||The objective vales at all encountered solution points in x. Sorted in ascending order.
|-
|||''g_k''||Gradient vector at optimum.
|-
|||''c_k''||Constraint values at optimum.
|-
|||''cJac''||Constraint derivative values at optimum.
|-
|||''xState''||State of each variable, described in [[TOMLAB_Appendix_B#Table:_The_state_variable_xState_for_the_variable.|TOMLAB Appendix B]].
|-
|||''bState''||State of each constraint, described in [[TOMLAB_Appendix_B#Table:_The_state_variable_bState_for_each_linear_constraint.|TOMLAB Appendix B]].
|-
|||''cState''||State of each general constraint, described in [[TOMLAB_Appendix_B#Table:_The_state_variable_cState_for_each_nonlinear_constraint.|TOMLAB Appendix B]].
|-
|||''x_0''||Starting point x_0.
|-
|||''Solver''||Solver used ('ecpMINLP').
|-
|||''SolverAlgorithm''||Description of method used.
|-
|||''Prob''||Problem structure used.
|}

== Algorithm==
ecpMINLP Solves convex or pseudo-convex mixed-integer nonlinear programming problems using an extended cutting plane algorithm with cuts regulated by a parameter-vector alpha. Cuts and linearizations are added to MIP subproblem which is then solved by a subsolver in each iteration.

The solver algorithm is mainly based on the paper 'Solving Pseudo-Convex Mixed Integer Optimization Problems by Cutting Plane Techniques' by Tapio Westerlund and Ray Pörn, published in Optimization and Engineering 3, 253-280, 2002, with some modifications.

Most prominent features in addition to the ones described in the main reference above are
* Solving the relaxed NLP problem initially to obtain a lower bound on the solution.
* A rounding heuristics performed on the initial NLP solution in order to obtain an initial upper bound on the initial solutions.
* Optional use of a cutpool for the alpha-regulated extended cutting planes.

[[Category:MIPNLP]]

MIPNLP ecpMINLP

2015-02-13T13:22:20Z

Bjorn: /* optParam Structure */

{{Part Of Manual|title=the MIPNLP Manual|link=[[MIPNLP|MIPNLP Manual]]}}
==Purpose==

ecpMINLP solves convex mixed-integer nonlinear programming problems (MINLP).

''ecpMINLP ''solves problems of the form

<math>
\begin{array}{cccccc}
\min\limits_{x} & f(x) \\s/t & x_{L} & \leq & x & \leq & x_{U} \\& b_{L} & \leq & Ax & \leq & b_{U} \\& c_{L} & \leq & c(x) & \leq & c_{U} \\& & & {x_{j} \in \mathbb{N} \ \ \forall j \in I} \\
\end{array}
</math>

where <math>x,x_{L},x_{U}\in \mathbb{R}^{n}</math> , <math>c(x),c_{L},c_{U}\in
\mathbb{R}^{m_{1}}</math> , <math>A\in \mathbb{R}^{m_{2}\times n}</math> and
<math>b_{L},b_{U}\in \mathbb{R}^{m_{2}}</math>. The variables <math>x \in I</math> , the
index subset of <math>1,...,n</math> are restricted to be integers but can be either continuously differentiable or not. An initalization routine will detect strict integer variables in the problem.

==Calling Syntax==

Driver call, including printing with level 2:
<source lang="matlab">
Result = tomRun('ecpMINLP',Prob,2);
</source>
Direct solver call:
<source lang="matlab">
Result = ecpMINLP(Prob);
PrintResult(Result);
Result = tomRun('ecpMINLP',Prob,...)
</source>

=== Warm Start ===
Warm start is currently not supported, but might be included in a future release.

==Inputs==

===Prob structure===
The '''TOMLAB''' problem structure

{|class="wikitable"
!colspan="2"|The following fields are used in the problem description structure Prob
|-
|'''Field'''||'''Description'''
|-
|''x_L''||Lower bounds on x.
|-
|''x_U''||Upper bounds on x.
|-
|''A''||The linear constraint matrix.
|-
|''b_L''||Lower bounds on linear constraints.
|-
|''b_U''||Upper bounds on linear constraints.
|-
|''c_L''||Lower bounds on nonlinear constraints.
|-
|''c_U''||Upper bounds on nonlinear constraints.
|-
|''f_Low''||Lower bound on solution.
|-
|''x_0''||Starting point.
|-valign="top"
|''MaxCPU''||Maximal CPU Time (in seconds) to be used by ecpMINLP, stops with best point found
|-valign="top"
|''PriLev''||Print level in ecpMINLP (default 1). Also see optParam.IterPrint
{|class="wikitable"
!value||output
|-
|=0||Silent.
|-
|>0||Initial information and convergence results.
|-
|>1||Output a line whenever the solution has improved, containing:
nIterations, nCuts, nCuts with criteria fulfilled, nLinearizations, nSpecialCuts, best solution.
|-
|>2||Output a line every iteration with the following information:
{|class="wikitable"
!label||description
|-
|It ||Iterations
|-
|nECP ||Number of extended cutting planes (ECP)
|-
|nAlpha>=lim||Number of ECP with criteria fulfilled
|-
|nL ||Number of linearizations
|-
|nSECP ||Number of special case ECP (created from constraint on bound)
|-
|fIPMin ||Objective of best solution at current iteration
|}
|-
|>3||Output a description of each step in the MINLP algorithm
|-
|>4||Output additional numerical information in some algorithm steps
|-
|>5||Output information in substeps (preprocessing, line search)
|}
|-valign="top"
|''PriLevOptMIP''||Print level in MIP sub-solvers, (CPLEX and others, see the documentation for the solver used). 
Usually: 
=0 No output 
>0 Convergence results 
>1 Output every iteration 
>2 Output each step in the algorithm
|-valign="top"
|''PriLevOptNLP''||Print level in NLP sub-solvers, (SNOPT and others, see the documentation for the solver used). 
Usually: 
=0 No output 
>0 Convergence results 
>1 Output every iteration 
>2 Output each step in the algorithm
|-valign="top"
|''SolverMIP''||Name of the solver used for MIP subproblems. If TOMLAB /gurobi is installed, gurobi is the default solver. If TOMLAB /CPLEX is installed, CPLEX is second choice as default. Otherwise the default solver is found calling GetSolver('mip',1); Supported as subsolvers are gurobi, CPLEX, mipSolve, milpSolve and cutplane.
|-valign="top"
|''SolverNLP''||
Name of the solver used for NLP subproblems. If packages /SOL or /SNOTP is installed, snopt is the default solver. Otherwise the default solver is found calling GetSolver('con',1);
|-
|''SolverLP''||Name of the solver used for LP subproblems when SolverMIP == mipSolve
|-
|''MIP''||Structure with parameters specific to mixed integer optimization. See the table below describing the fields used in the MIP structure.
|-
|''ECPMINLP''||Structure with parameters specific to the ecpMINLP solver. See the table below describing the fields used in the ECPMINLP structure.
|-
|''optParam''||Structure with general optimization parameters. See the table below describing the fields used in the optParam structure.
|}

===MIP structure===
Substructure in Prob with parameters related to mixed integer programming.

{|class="wikitable"
!colspan="2"|'''fields used in Prob.MIP''':
|-
|'''Field'''||'''Description'''
|-valign="top"
|''IntVars''||If empty, all variables are assumed non-integer. If islogical(IntVars) (=all elements are 0/1), then 1 = integer variable, 0 = continuous variable. If any element ''>''1, IntVars is the indices for integer variables.
|-valign="top"
|''fIP''||An upper bound on the IP value wanted. Makes it possible to cut branches and avoid node computations. Used even if xIP not given.
|-valign="top"
|''xIP''||The x-values giving the fIP value, if a solution (xIP,fIP) is known.
|-valign="top"
|''DualGap''||ecpMINLP stops if the duality gap is less than DualGap
DualGap = 1, stop at first integer solution, e.g. DualGap = 0.01,stop if solution < 1% from optimal solution.
 The lower bound Prob.f_Low is used, (default -1.0e300), which can also be set by the user. If f_Low has not been changed from default the lower bound is obtained from the initial solution of a relaxed problem, but only when ECPMINLP.INIT_BND is 1 or 2 (default).
 Default DualGap is -1, not used.
|-valign="top"
|''PPP''||Pre-processing and probing, default is 0. 
0 Not used. Default. 
1 Apply initially on MINLP problem. 
2 Apply each iteration before solving MILP sub-problem.
|-
|''ROUNDH''||If nonzero, a rounding heuristics will be used on the initial NLP solution in order to obtain an initial integer solution. Requires ECPMINLP.InitBndType enabled. Default is 1, enabled.
|}

===ECPMINLP structure===
Substructure in ''Prob'' with solver-specific options.

{|class="wikitable"
!colspan="2"|fields used in Prob.ECPMINLP
|-
|'''Field'''||'''Description'''
|-valign="top"
|''beta''||Multiplier when increasing alpha after an infeasible MILP solution.
 Alpha is a parameter individually adjusting each cutting plane, starting at 1.0 and increasing until meeting a certain criterion. Default value for beta is 1.3.
|-valign="top"
|''gamma''||Multiplier when increasing alpha when MILP solution does not violate any nonlinear contraints, but still does not decrease the upper bound of the objective.
 Alpha is a parameter individually adjusting each cutting plane, starting at 1.0 and increasing until meeting a certain criterion. Default value for gamma is 2.0.
|-valign="top"
|''PREALLOC''||Flag enabling preallocation of memory for cutting planes and linearizations.
 0 No preallocation, dynamic growth of arrays. Current default.
 1 Preallocate arrays.
|-valign="top"
|''InitBndType''||Selects method for setting lower bound when f_Low not changed from default.
{|class="wikitable"
!value||method
|-valign="top"
|0 ||No extra initial lower bound.
|-valign="top"
|1 ||Use default TOMLAB NLP solver on problem with relaxed integer constraints. Add a linearization if a feasible MINLP solution was found.
|-valign="top"
|2 ||Add an initial linearization as long as a feasible NLP solution was found. The linearization is a simple lower bound on the MILP objective. Default.
|}
|-valign="top"
|''SET_TOL''||Flag enabling changing tolerances, described below under optParam.eps_x, optParam.eps_x and optParam.eps_f.
 0 Default. Using the recommended solver default values, 1.0e-3.
 1 Tolerances can be changed, taken from Prob.optParam.
|-valign="top"
|''IntSolLimIncr''||Integer option when using CPLEX as MIP subsolver.
 Define how much the CPLEX parameter IntSolLimIncr increases when a feasible solution is not optimal and all alpha values have met their criteria.
 When set to zero, the optimal strategy will instead be used immediately, without any gradual increase of INTSOLLIM.
 Default is 1.
|-valign="top"
|''USE_CUTPOOL''||Set nonzero to use a pool for the alpha-regulated extended cutting planes.
 Cuts not active in the MILP-solution for CutDelBound iterations in a row will be inactivated (removed from the MILP-problem) until they are violated in a new solution.
 Default is 0, not used.
|-valign="top"
|''CutDelBound''||The number of consecutive times an extended cutting plane can be inactive before it gets removed and put into the inactive pool, if the option USE_CUTPOOL is set nonzero.
 Default is 15 times.
|-valign="top"
|''MaxIterWoImpr''||Limit on the number of successive iterations allowed without any improvements at all to neither objective nor solution point before the solver terminates
 Default is 2.
|-valign="top"
|''USE_NLP''||Set nonzero to use an NLP sub-solver on the original problem with the integer variables fixed at values from the latest MILP solution. Default is 1, enabled.
|-valign="top"
|''RESELECT_CUTS''||Set nonzero to enable cut reselection heuristics. Default is 1, enabled.
|-valign="top"
|''SCALE_CUTS''||Set nonzero to scale cuts before they are added to the MILP problem. Scaling is done by dividing the cut with its norm. Default is 1, enabled.
|}

===optParam Structure===
Substructure in ''Prob'' with general optimization parameters.

{|class="wikitable"
!colspan="2"|fields used in Prob.optParam
|-
|'''Field'''||'''Value'''
|-valign="top"
|''MaxIter''||Maximal number of iterations, default 10000
|-valign="top"
|''IterPrint''||Print short information each iteration. Setting PriLev > 2 also enables IterPrint, setting it to 1.
|-valign="top"
|''eps_x''||Linear constraint violation convergence tolerance. Default is 2.0e-6
|-valign="top"
|''eps_g''||Constraint violation convergence tolerance. Default is 1.0e-7
|-valign="top"
|''eps_f''||Optimality tolerance. Default is 1.0e-8
|}

''NOTE:'' For the solver to use these tolerances, the flag ''ECPMINLP.SET_TOL'' must be set to nonzero.

==Outputs==

{| class="wikitable"
!''Result''||colspan="2"|Structure with result from optimization. The following fields are changed:
|-
|||''Iter ''||Number of iterations.
|-valign="top"
|||''ExitFlag ''||Exit flag.
 0: Solution found, or integer solution with duality gap less than user tolerance.
 1: Maximal number of iterations reached.
 2: Empty feasible set, no integer solution found.
 3: Problem in subsolver, see Inform value.
 99: Maximal CPU Time used (cputime > Prob.maxCPU
|-
|||''Inform''||Inform for ExitFlag != 3
 0: Global solution found.
 1: Local solution found.
 2: No solution found.
 >2: Inform value from subsolver.
|-
|||''ExitText''||Text string giving ''ExitFlag'' and ''Inform'' information.
|-valign="top"
|||''DualGap''||Relative duality gap, max(0,fIPMin-fLB)/-fIPMin-, if fIPMin =0; max(0,fIPMin-fLB) if fIPMin == 0. If fIPMin =0: Scale with 100, 100*Dual- Gap, to get the percentage duality gap. For absolute value duality gap: scale with fIPMin, fIPMin * DualGap
|-
|||''x_k''||Solution.
|-valign="top"
|||''f_k''||Function value at optimum.
|-
|||''g_k''||Gradient vector at optimum.
|-
|||''c_k''||Constraint values at optimum.
|-
|||''cJac''||Constraint derivative values at optimum.
|-
|||''xState''||State of each variable, described in [[TOMLAB_Appendix_B#Table:_The_state_variable_xState_for_the_variable.|TOMLAB Appendix B]].
|-
|||''bState''||State of each constraint, described in [[TOMLAB_Appendix_B#Table:_The_state_variable_bState_for_each_linear_constraint.|TOMLAB Appendix B]].
|-
|||''cState''||State of each general constraint, described in [[TOMLAB_Appendix_B#Table:_The_state_variable_cState_for_each_nonlinear_constraint.|TOMLAB Appendix B]].
|-
|||''x_0''||Starting point x_0.
|-
|||''Solver''||Solver used ('ecpMINLP').
|-
|||''SolverAlgorithm''||Description of method used.
|-
|||''Prob''||Problem structure used.
|}

== Algorithm==
ecpMINLP Solves convex or pseudo-convex mixed-integer nonlinear programming problems using an extended cutting plane algorithm with cuts regulated by a parameter-vector alpha. Cuts and linearizations are added to MIP subproblem which is then solved by a subsolver in each iteration.

The solver algorithm is mainly based on the paper 'Solving Pseudo-Convex Mixed Integer Optimization Problems by Cutting Plane Techniques' by Tapio Westerlund and Ray Pörn, published in Optimization and Engineering 3, 253-280, 2002, with some modifications.

Most prominent features in addition to the ones described in the main reference above are
* Solving the relaxed NLP problem initially to obtain a lower bound on the solution.
* A rounding heuristics performed on the initial NLP solution in order to obtain an initial upper bound on the initial solutions.
* Optional use of a cutpool for the alpha-regulated extended cutting planes.

[[Category:MIPNLP]]

MIPNLP ecpMINLP

2015-02-13T13:21:02Z

Bjorn: /* ECPMINLP structure */

{{Part Of Manual|title=the MIPNLP Manual|link=[[MIPNLP|MIPNLP Manual]]}}
==Purpose==

ecpMINLP solves convex mixed-integer nonlinear programming problems (MINLP).

''ecpMINLP ''solves problems of the form

<math>
\begin{array}{cccccc}
\min\limits_{x} & f(x) \\s/t & x_{L} & \leq & x & \leq & x_{U} \\& b_{L} & \leq & Ax & \leq & b_{U} \\& c_{L} & \leq & c(x) & \leq & c_{U} \\& & & {x_{j} \in \mathbb{N} \ \ \forall j \in I} \\
\end{array}
</math>

where <math>x,x_{L},x_{U}\in \mathbb{R}^{n}</math> , <math>c(x),c_{L},c_{U}\in
\mathbb{R}^{m_{1}}</math> , <math>A\in \mathbb{R}^{m_{2}\times n}</math> and
<math>b_{L},b_{U}\in \mathbb{R}^{m_{2}}</math>. The variables <math>x \in I</math> , the
index subset of <math>1,...,n</math> are restricted to be integers but can be either continuously differentiable or not. An initalization routine will detect strict integer variables in the problem.

==Calling Syntax==

Driver call, including printing with level 2:
<source lang="matlab">
Result = tomRun('ecpMINLP',Prob,2);
</source>
Direct solver call:
<source lang="matlab">
Result = ecpMINLP(Prob);
PrintResult(Result);
Result = tomRun('ecpMINLP',Prob,...)
</source>

=== Warm Start ===
Warm start is currently not supported, but might be included in a future release.

==Inputs==

===Prob structure===
The '''TOMLAB''' problem structure

{|class="wikitable"
!colspan="2"|The following fields are used in the problem description structure Prob
|-
|'''Field'''||'''Description'''
|-
|''x_L''||Lower bounds on x.
|-
|''x_U''||Upper bounds on x.
|-
|''A''||The linear constraint matrix.
|-
|''b_L''||Lower bounds on linear constraints.
|-
|''b_U''||Upper bounds on linear constraints.
|-
|''c_L''||Lower bounds on nonlinear constraints.
|-
|''c_U''||Upper bounds on nonlinear constraints.
|-
|''f_Low''||Lower bound on solution.
|-
|''x_0''||Starting point.
|-valign="top"
|''MaxCPU''||Maximal CPU Time (in seconds) to be used by ecpMINLP, stops with best point found
|-valign="top"
|''PriLev''||Print level in ecpMINLP (default 1). Also see optParam.IterPrint
{|class="wikitable"
!value||output
|-
|=0||Silent.
|-
|>0||Initial information and convergence results.
|-
|>1||Output a line whenever the solution has improved, containing:
nIterations, nCuts, nCuts with criteria fulfilled, nLinearizations, nSpecialCuts, best solution.
|-
|>2||Output a line every iteration with the following information:
{|class="wikitable"
!label||description
|-
|It ||Iterations
|-
|nECP ||Number of extended cutting planes (ECP)
|-
|nAlpha>=lim||Number of ECP with criteria fulfilled
|-
|nL ||Number of linearizations
|-
|nSECP ||Number of special case ECP (created from constraint on bound)
|-
|fIPMin ||Objective of best solution at current iteration
|}
|-
|>3||Output a description of each step in the MINLP algorithm
|-
|>4||Output additional numerical information in some algorithm steps
|-
|>5||Output information in substeps (preprocessing, line search)
|}
|-valign="top"
|''PriLevOptMIP''||Print level in MIP sub-solvers, (CPLEX and others, see the documentation for the solver used). 
Usually: 
=0 No output 
>0 Convergence results 
>1 Output every iteration 
>2 Output each step in the algorithm
|-valign="top"
|''PriLevOptNLP''||Print level in NLP sub-solvers, (SNOPT and others, see the documentation for the solver used). 
Usually: 
=0 No output 
>0 Convergence results 
>1 Output every iteration 
>2 Output each step in the algorithm
|-valign="top"
|''SolverMIP''||Name of the solver used for MIP subproblems. If TOMLAB /gurobi is installed, gurobi is the default solver. If TOMLAB /CPLEX is installed, CPLEX is second choice as default. Otherwise the default solver is found calling GetSolver('mip',1); Supported as subsolvers are gurobi, CPLEX, mipSolve, milpSolve and cutplane.
|-valign="top"
|''SolverNLP''||
Name of the solver used for NLP subproblems. If packages /SOL or /SNOTP is installed, snopt is the default solver. Otherwise the default solver is found calling GetSolver('con',1);
|-
|''SolverLP''||Name of the solver used for LP subproblems when SolverMIP == mipSolve
|-
|''MIP''||Structure with parameters specific to mixed integer optimization. See the table below describing the fields used in the MIP structure.
|-
|''ECPMINLP''||Structure with parameters specific to the ecpMINLP solver. See the table below describing the fields used in the ECPMINLP structure.
|-
|''optParam''||Structure with general optimization parameters. See the table below describing the fields used in the optParam structure.
|}

===MIP structure===
Substructure in Prob with parameters related to mixed integer programming.

{|class="wikitable"
!colspan="2"|'''fields used in Prob.MIP''':
|-
|'''Field'''||'''Description'''
|-valign="top"
|''IntVars''||If empty, all variables are assumed non-integer. If islogical(IntVars) (=all elements are 0/1), then 1 = integer variable, 0 = continuous variable. If any element ''>''1, IntVars is the indices for integer variables.
|-valign="top"
|''fIP''||An upper bound on the IP value wanted. Makes it possible to cut branches and avoid node computations. Used even if xIP not given.
|-valign="top"
|''xIP''||The x-values giving the fIP value, if a solution (xIP,fIP) is known.
|-valign="top"
|''DualGap''||ecpMINLP stops if the duality gap is less than DualGap
DualGap = 1, stop at first integer solution, e.g. DualGap = 0.01,stop if solution < 1% from optimal solution.
 The lower bound Prob.f_Low is used, (default -1.0e300), which can also be set by the user. If f_Low has not been changed from default the lower bound is obtained from the initial solution of a relaxed problem, but only when ECPMINLP.INIT_BND is 1 or 2 (default).
 Default DualGap is -1, not used.
|-valign="top"
|''PPP''||Pre-processing and probing, default is 0. 
0 Not used. Default. 
1 Apply initially on MINLP problem. 
2 Apply each iteration before solving MILP sub-problem.
|-
|''ROUNDH''||If nonzero, a rounding heuristics will be used on the initial NLP solution in order to obtain an initial integer solution. Requires ECPMINLP.InitBndType enabled. Default is 1, enabled.
|}

===ECPMINLP structure===
Substructure in ''Prob'' with solver-specific options.

{|class="wikitable"
!colspan="2"|fields used in Prob.ECPMINLP
|-
|'''Field'''||'''Description'''
|-valign="top"
|''beta''||Multiplier when increasing alpha after an infeasible MILP solution.
 Alpha is a parameter individually adjusting each cutting plane, starting at 1.0 and increasing until meeting a certain criterion. Default value for beta is 1.3.
|-valign="top"
|''gamma''||Multiplier when increasing alpha when MILP solution does not violate any nonlinear contraints, but still does not decrease the upper bound of the objective.
 Alpha is a parameter individually adjusting each cutting plane, starting at 1.0 and increasing until meeting a certain criterion. Default value for gamma is 2.0.
|-valign="top"
|''PREALLOC''||Flag enabling preallocation of memory for cutting planes and linearizations.
 0 No preallocation, dynamic growth of arrays. Current default.
 1 Preallocate arrays.
|-valign="top"
|''InitBndType''||Selects method for setting lower bound when f_Low not changed from default.
{|class="wikitable"
!value||method
|-valign="top"
|0 ||No extra initial lower bound.
|-valign="top"
|1 ||Use default TOMLAB NLP solver on problem with relaxed integer constraints. Add a linearization if a feasible MINLP solution was found.
|-valign="top"
|2 ||Add an initial linearization as long as a feasible NLP solution was found. The linearization is a simple lower bound on the MILP objective. Default.
|}
|-valign="top"
|''SET_TOL''||Flag enabling changing tolerances, described below under optParam.eps_x, optParam.eps_x and optParam.eps_f.
 0 Default. Using the recommended solver default values, 1.0e-3.
 1 Tolerances can be changed, taken from Prob.optParam.
|-valign="top"
|''IntSolLimIncr''||Integer option when using CPLEX as MIP subsolver.
 Define how much the CPLEX parameter IntSolLimIncr increases when a feasible solution is not optimal and all alpha values have met their criteria.
 When set to zero, the optimal strategy will instead be used immediately, without any gradual increase of INTSOLLIM.
 Default is 1.
|-valign="top"
|''USE_CUTPOOL''||Set nonzero to use a pool for the alpha-regulated extended cutting planes.
 Cuts not active in the MILP-solution for CutDelBound iterations in a row will be inactivated (removed from the MILP-problem) until they are violated in a new solution.
 Default is 0, not used.
|-valign="top"
|''CutDelBound''||The number of consecutive times an extended cutting plane can be inactive before it gets removed and put into the inactive pool, if the option USE_CUTPOOL is set nonzero.
 Default is 15 times.
|-valign="top"
|''MaxIterWoImpr''||Limit on the number of successive iterations allowed without any improvements at all to neither objective nor solution point before the solver terminates
 Default is 2.
|-valign="top"
|''USE_NLP''||Set nonzero to use an NLP sub-solver on the original problem with the integer variables fixed at values from the latest MILP solution. Default is 1, enabled.
|-valign="top"
|''RESELECT_CUTS''||Set nonzero to enable cut reselection heuristics. Default is 1, enabled.
|-valign="top"
|''SCALE_CUTS''||Set nonzero to scale cuts before they are added to the MILP problem. Scaling is done by dividing the cut with its norm. Default is 1, enabled.
|}

===optParam Structure===
Substructure in ''Prob'' with general optimization parameters.

{|class="wikitable"
!colspan="2"|fields used in Prob.optParam
|-
|'''Field'''||'''Value'''
|-valign="top"
|''MaxIter''||Maximal number of iterations, default 10000
|-valign="top"
|''IterPrint''||Print short information each iteration. Setting PriLev > 1 also enables IterPrint, setting it to 1.
|-valign="top"
|''eps_x''||Linear constraint violation convergence tolerance. Default is 2.0e-6
|-valign="top"
|''eps_g''||Constraint violation convergence tolerance. Default is 1.0e-7
|-valign="top"
|''eps_f''||Optimality tolerance. Default is 1.0e-8
|}

''NOTE:'' For the solver to use these tolerances, the flag ''ECPMINLP.SETTOL'' must be set to nonzero.

==Outputs==

{| class="wikitable"
!''Result''||colspan="2"|Structure with result from optimization. The following fields are changed:
|-
|||''Iter ''||Number of iterations.
|-valign="top"
|||''ExitFlag ''||Exit flag.
 0: Solution found, or integer solution with duality gap less than user tolerance.
 1: Maximal number of iterations reached.
 2: Empty feasible set, no integer solution found.
 3: Problem in subsolver, see Inform value.
 99: Maximal CPU Time used (cputime > Prob.maxCPU
|-
|||''Inform''||Inform for ExitFlag != 3
 0: Global solution found.
 1: Local solution found.
 2: No solution found.
 >2: Inform value from subsolver.
|-
|||''ExitText''||Text string giving ''ExitFlag'' and ''Inform'' information.
|-valign="top"
|||''DualGap''||Relative duality gap, max(0,fIPMin-fLB)/-fIPMin-, if fIPMin =0; max(0,fIPMin-fLB) if fIPMin == 0. If fIPMin =0: Scale with 100, 100*Dual- Gap, to get the percentage duality gap. For absolute value duality gap: scale with fIPMin, fIPMin * DualGap
|-
|||''x_k''||Solution.
|-valign="top"
|||''f_k''||Function value at optimum.
|-
|||''g_k''||Gradient vector at optimum.
|-
|||''c_k''||Constraint values at optimum.
|-
|||''cJac''||Constraint derivative values at optimum.
|-
|||''xState''||State of each variable, described in [[TOMLAB_Appendix_B#Table:_The_state_variable_xState_for_the_variable.|TOMLAB Appendix B]].
|-
|||''bState''||State of each constraint, described in [[TOMLAB_Appendix_B#Table:_The_state_variable_bState_for_each_linear_constraint.|TOMLAB Appendix B]].
|-
|||''cState''||State of each general constraint, described in [[TOMLAB_Appendix_B#Table:_The_state_variable_cState_for_each_nonlinear_constraint.|TOMLAB Appendix B]].
|-
|||''x_0''||Starting point x_0.
|-
|||''Solver''||Solver used ('ecpMINLP').
|-
|||''SolverAlgorithm''||Description of method used.
|-
|||''Prob''||Problem structure used.
|}

== Algorithm==
ecpMINLP Solves convex or pseudo-convex mixed-integer nonlinear programming problems using an extended cutting plane algorithm with cuts regulated by a parameter-vector alpha. Cuts and linearizations are added to MIP subproblem which is then solved by a subsolver in each iteration.

The solver algorithm is mainly based on the paper 'Solving Pseudo-Convex Mixed Integer Optimization Problems by Cutting Plane Techniques' by Tapio Westerlund and Ray Pörn, published in Optimization and Engineering 3, 253-280, 2002, with some modifications.

Most prominent features in addition to the ones described in the main reference above are
* Solving the relaxed NLP problem initially to obtain a lower bound on the solution.
* A rounding heuristics performed on the initial NLP solution in order to obtain an initial upper bound on the initial solutions.
* Optional use of a cutpool for the alpha-regulated extended cutting planes.

[[Category:MIPNLP]]

MIPNLP ecpMINLP

2015-02-13T13:20:17Z

Bjorn: /* ECPMINLP structure */

{{Part Of Manual|title=the MIPNLP Manual|link=[[MIPNLP|MIPNLP Manual]]}}
==Purpose==

ecpMINLP solves convex mixed-integer nonlinear programming problems (MINLP).

''ecpMINLP ''solves problems of the form

<math>
\begin{array}{cccccc}
\min\limits_{x} & f(x) \\s/t & x_{L} & \leq & x & \leq & x_{U} \\& b_{L} & \leq & Ax & \leq & b_{U} \\& c_{L} & \leq & c(x) & \leq & c_{U} \\& & & {x_{j} \in \mathbb{N} \ \ \forall j \in I} \\
\end{array}
</math>

where <math>x,x_{L},x_{U}\in \mathbb{R}^{n}</math> , <math>c(x),c_{L},c_{U}\in
\mathbb{R}^{m_{1}}</math> , <math>A\in \mathbb{R}^{m_{2}\times n}</math> and
<math>b_{L},b_{U}\in \mathbb{R}^{m_{2}}</math>. The variables <math>x \in I</math> , the
index subset of <math>1,...,n</math> are restricted to be integers but can be either continuously differentiable or not. An initalization routine will detect strict integer variables in the problem.

==Calling Syntax==

Driver call, including printing with level 2:
<source lang="matlab">
Result = tomRun('ecpMINLP',Prob,2);
</source>
Direct solver call:
<source lang="matlab">
Result = ecpMINLP(Prob);
PrintResult(Result);
Result = tomRun('ecpMINLP',Prob,...)
</source>

=== Warm Start ===
Warm start is currently not supported, but might be included in a future release.

==Inputs==

===Prob structure===
The '''TOMLAB''' problem structure

{|class="wikitable"
!colspan="2"|The following fields are used in the problem description structure Prob
|-
|'''Field'''||'''Description'''
|-
|''x_L''||Lower bounds on x.
|-
|''x_U''||Upper bounds on x.
|-
|''A''||The linear constraint matrix.
|-
|''b_L''||Lower bounds on linear constraints.
|-
|''b_U''||Upper bounds on linear constraints.
|-
|''c_L''||Lower bounds on nonlinear constraints.
|-
|''c_U''||Upper bounds on nonlinear constraints.
|-
|''f_Low''||Lower bound on solution.
|-
|''x_0''||Starting point.
|-valign="top"
|''MaxCPU''||Maximal CPU Time (in seconds) to be used by ecpMINLP, stops with best point found
|-valign="top"
|''PriLev''||Print level in ecpMINLP (default 1). Also see optParam.IterPrint
{|class="wikitable"
!value||output
|-
|=0||Silent.
|-
|>0||Initial information and convergence results.
|-
|>1||Output a line whenever the solution has improved, containing:
nIterations, nCuts, nCuts with criteria fulfilled, nLinearizations, nSpecialCuts, best solution.
|-
|>2||Output a line every iteration with the following information:
{|class="wikitable"
!label||description
|-
|It ||Iterations
|-
|nECP ||Number of extended cutting planes (ECP)
|-
|nAlpha>=lim||Number of ECP with criteria fulfilled
|-
|nL ||Number of linearizations
|-
|nSECP ||Number of special case ECP (created from constraint on bound)
|-
|fIPMin ||Objective of best solution at current iteration
|}
|-
|>3||Output a description of each step in the MINLP algorithm
|-
|>4||Output additional numerical information in some algorithm steps
|-
|>5||Output information in substeps (preprocessing, line search)
|}
|-valign="top"
|''PriLevOptMIP''||Print level in MIP sub-solvers, (CPLEX and others, see the documentation for the solver used). 
Usually: 
=0 No output 
>0 Convergence results 
>1 Output every iteration 
>2 Output each step in the algorithm
|-valign="top"
|''PriLevOptNLP''||Print level in NLP sub-solvers, (SNOPT and others, see the documentation for the solver used). 
Usually: 
=0 No output 
>0 Convergence results 
>1 Output every iteration 
>2 Output each step in the algorithm
|-valign="top"
|''SolverMIP''||Name of the solver used for MIP subproblems. If TOMLAB /gurobi is installed, gurobi is the default solver. If TOMLAB /CPLEX is installed, CPLEX is second choice as default. Otherwise the default solver is found calling GetSolver('mip',1); Supported as subsolvers are gurobi, CPLEX, mipSolve, milpSolve and cutplane.
|-valign="top"
|''SolverNLP''||
Name of the solver used for NLP subproblems. If packages /SOL or /SNOTP is installed, snopt is the default solver. Otherwise the default solver is found calling GetSolver('con',1);
|-
|''SolverLP''||Name of the solver used for LP subproblems when SolverMIP == mipSolve
|-
|''MIP''||Structure with parameters specific to mixed integer optimization. See the table below describing the fields used in the MIP structure.
|-
|''ECPMINLP''||Structure with parameters specific to the ecpMINLP solver. See the table below describing the fields used in the ECPMINLP structure.
|-
|''optParam''||Structure with general optimization parameters. See the table below describing the fields used in the optParam structure.
|}

===MIP structure===
Substructure in Prob with parameters related to mixed integer programming.

{|class="wikitable"
!colspan="2"|'''fields used in Prob.MIP''':
|-
|'''Field'''||'''Description'''
|-valign="top"
|''IntVars''||If empty, all variables are assumed non-integer. If islogical(IntVars) (=all elements are 0/1), then 1 = integer variable, 0 = continuous variable. If any element ''>''1, IntVars is the indices for integer variables.
|-valign="top"
|''fIP''||An upper bound on the IP value wanted. Makes it possible to cut branches and avoid node computations. Used even if xIP not given.
|-valign="top"
|''xIP''||The x-values giving the fIP value, if a solution (xIP,fIP) is known.
|-valign="top"
|''DualGap''||ecpMINLP stops if the duality gap is less than DualGap
DualGap = 1, stop at first integer solution, e.g. DualGap = 0.01,stop if solution < 1% from optimal solution.
 The lower bound Prob.f_Low is used, (default -1.0e300), which can also be set by the user. If f_Low has not been changed from default the lower bound is obtained from the initial solution of a relaxed problem, but only when ECPMINLP.INIT_BND is 1 or 2 (default).
 Default DualGap is -1, not used.
|-valign="top"
|''PPP''||Pre-processing and probing, default is 0. 
0 Not used. Default. 
1 Apply initially on MINLP problem. 
2 Apply each iteration before solving MILP sub-problem.
|-
|''ROUNDH''||If nonzero, a rounding heuristics will be used on the initial NLP solution in order to obtain an initial integer solution. Requires ECPMINLP.InitBndType enabled. Default is 1, enabled.
|}

===ECPMINLP structure===
Substructure in ''Prob'' with solver-specific options.

{|class="wikitable"
!colspan="2"|fields used in Prob.ECPMINLP
|-
|'''Field'''||'''Description'''
|-valign="top"
|''beta''||Multiplier when increasing alpha after an infeasible MILP solution.
 Alpha is a parameter individually adjusting each cutting plane, starting at 1.0 and increasing until meeting a certain criterion. Default value for beta is 1.3.
|-valign="top"
|''gamma''||Multiplier when increasing alpha when MILP solution does not violate any nonlinear contraints, but still does not decrease the upper bound of the objective.
 Alpha is a parameter individually adjusting each cutting plane, starting at 1.0 and increasing until meeting a certain criterion. Default value for gamma is 2.0.
|-valign="top"
|''PREALLOC''||Flag enabling preallocation of memory for cutting planes and linearizations.
 0 No preallocation, dynamic growth of arrays. Current default.
 1 Preallocate arrays.
|-valign="top"
|''InitBndType''||Selects method for setting lower bound when f_Low not changed from default.
{|class="wikitable"
!value||method
|-valign="top"
|0 ||No extra initial lower bound.
|-valign="top"
|1 ||Use default TOMLAB NLP solver on problem with relaxed integer constraints. Add a linearization if a feasible MINLP solution was found.
|-valign="top"
|2 ||Add an initial linearization as long as a feasible NLP solution was found. The linearization is a simple lower bound on the MILP objective. Default.
|}
|-valign="top"
|''SET_TOL''||Flag enabling changing tolerances, described below under optParam.eps_x, optParam.eps_x and optParam.eps_f.
 0 Default. Using the recommended solver default values, 1.0e-3.
 1 Tolerances can be changed, taken from Prob.optParam.
|-valign="top"
|''IntSolLimIncr''||Integer option when using CPLEX as MIP subsolver.
 Define how much the CPLEX parameter INTSOLLIM increases when a feasible solution is not optimal and all alpha values have met their criteria.
 When set to zero, the optimal strategy will instead be used immediately, without any gradual increase of INTSOLLIM.
 Default is 1.
|-valign="top"
|''USE_CUTPOOL''||Set nonzero to use a pool for the alpha-regulated extended cutting planes.
 Cuts not active in the MILP-solution for CUTDELBND iterations in a row will be inactivated (removed from the MILP-problem) until they are violated in a new solution.
 Default is 0, not used.
|-valign="top"
|''CutDelBound''||The number of consecutive times an extended cutting plane can be inactive before it gets removed and put into the inactive pool, if the option USE_CUTPOOL is set nonzero.
 Default is 15 times.
|-valign="top"
|''MaxIterWoImpr''||Limit on the number of successive iterations allowed without any improvements at all to neither objective nor solution point before the solver terminates
 Default is 2.
|-valign="top"
|''USE_NLP''||Set nonzero to use an NLP sub-solver on the original problem with the integer variables fixed at values from the latest MILP solution. Default is 1, enabled.
|-valign="top"
|''RESELECT_CUTS''||Set nonzero to enable cut reselection heuristics. Default is 1, enabled.
|-valign="top"
|''SCALE_CUTS''||Set nonzero to scale cuts before they are added to the MILP problem. Scaling is done by dividing the cut with its norm. Default is 1, enabled.
|}

===optParam Structure===
Substructure in ''Prob'' with general optimization parameters.

{|class="wikitable"
!colspan="2"|fields used in Prob.optParam
|-
|'''Field'''||'''Value'''
|-valign="top"
|''MaxIter''||Maximal number of iterations, default 10000
|-valign="top"
|''IterPrint''||Print short information each iteration. Setting PriLev > 1 also enables IterPrint, setting it to 1.
|-valign="top"
|''eps_x''||Linear constraint violation convergence tolerance. Default is 2.0e-6
|-valign="top"
|''eps_g''||Constraint violation convergence tolerance. Default is 1.0e-7
|-valign="top"
|''eps_f''||Optimality tolerance. Default is 1.0e-8
|}

''NOTE:'' For the solver to use these tolerances, the flag ''ECPMINLP.SETTOL'' must be set to nonzero.

==Outputs==

{| class="wikitable"
!''Result''||colspan="2"|Structure with result from optimization. The following fields are changed:
|-
|||''Iter ''||Number of iterations.
|-valign="top"
|||''ExitFlag ''||Exit flag.
 0: Solution found, or integer solution with duality gap less than user tolerance.
 1: Maximal number of iterations reached.
 2: Empty feasible set, no integer solution found.
 3: Problem in subsolver, see Inform value.
 99: Maximal CPU Time used (cputime > Prob.maxCPU
|-
|||''Inform''||Inform for ExitFlag != 3
 0: Global solution found.
 1: Local solution found.
 2: No solution found.
 >2: Inform value from subsolver.
|-
|||''ExitText''||Text string giving ''ExitFlag'' and ''Inform'' information.
|-valign="top"
|||''DualGap''||Relative duality gap, max(0,fIPMin-fLB)/-fIPMin-, if fIPMin =0; max(0,fIPMin-fLB) if fIPMin == 0. If fIPMin =0: Scale with 100, 100*Dual- Gap, to get the percentage duality gap. For absolute value duality gap: scale with fIPMin, fIPMin * DualGap
|-
|||''x_k''||Solution.
|-valign="top"
|||''f_k''||Function value at optimum.
|-
|||''g_k''||Gradient vector at optimum.
|-
|||''c_k''||Constraint values at optimum.
|-
|||''cJac''||Constraint derivative values at optimum.
|-
|||''xState''||State of each variable, described in [[TOMLAB_Appendix_B#Table:_The_state_variable_xState_for_the_variable.|TOMLAB Appendix B]].
|-
|||''bState''||State of each constraint, described in [[TOMLAB_Appendix_B#Table:_The_state_variable_bState_for_each_linear_constraint.|TOMLAB Appendix B]].
|-
|||''cState''||State of each general constraint, described in [[TOMLAB_Appendix_B#Table:_The_state_variable_cState_for_each_nonlinear_constraint.|TOMLAB Appendix B]].
|-
|||''x_0''||Starting point x_0.
|-
|||''Solver''||Solver used ('ecpMINLP').
|-
|||''SolverAlgorithm''||Description of method used.
|-
|||''Prob''||Problem structure used.
|}

== Algorithm==
ecpMINLP Solves convex or pseudo-convex mixed-integer nonlinear programming problems using an extended cutting plane algorithm with cuts regulated by a parameter-vector alpha. Cuts and linearizations are added to MIP subproblem which is then solved by a subsolver in each iteration.

The solver algorithm is mainly based on the paper 'Solving Pseudo-Convex Mixed Integer Optimization Problems by Cutting Plane Techniques' by Tapio Westerlund and Ray Pörn, published in Optimization and Engineering 3, 253-280, 2002, with some modifications.

Most prominent features in addition to the ones described in the main reference above are
* Solving the relaxed NLP problem initially to obtain a lower bound on the solution.
* A rounding heuristics performed on the initial NLP solution in order to obtain an initial upper bound on the initial solutions.
* Optional use of a cutpool for the alpha-regulated extended cutting planes.

[[Category:MIPNLP]]

MIPNLP ecpMINLP

2015-02-13T13:10:07Z

Bjorn: /* MIP structure */

{{Part Of Manual|title=the MIPNLP Manual|link=[[MIPNLP|MIPNLP Manual]]}}
==Purpose==

ecpMINLP solves convex mixed-integer nonlinear programming problems (MINLP).

''ecpMINLP ''solves problems of the form

<math>
\begin{array}{cccccc}
\min\limits_{x} & f(x) \\s/t & x_{L} & \leq & x & \leq & x_{U} \\& b_{L} & \leq & Ax & \leq & b_{U} \\& c_{L} & \leq & c(x) & \leq & c_{U} \\& & & {x_{j} \in \mathbb{N} \ \ \forall j \in I} \\
\end{array}
</math>

where <math>x,x_{L},x_{U}\in \mathbb{R}^{n}</math> , <math>c(x),c_{L},c_{U}\in
\mathbb{R}^{m_{1}}</math> , <math>A\in \mathbb{R}^{m_{2}\times n}</math> and
<math>b_{L},b_{U}\in \mathbb{R}^{m_{2}}</math>. The variables <math>x \in I</math> , the
index subset of <math>1,...,n</math> are restricted to be integers but can be either continuously differentiable or not. An initalization routine will detect strict integer variables in the problem.

==Calling Syntax==

Driver call, including printing with level 2:
<source lang="matlab">
Result = tomRun('ecpMINLP',Prob,2);
</source>
Direct solver call:
<source lang="matlab">
Result = ecpMINLP(Prob);
PrintResult(Result);
Result = tomRun('ecpMINLP',Prob,...)
</source>

=== Warm Start ===
Warm start is currently not supported, but might be included in a future release.

==Inputs==

===Prob structure===
The '''TOMLAB''' problem structure

{|class="wikitable"
!colspan="2"|The following fields are used in the problem description structure Prob
|-
|'''Field'''||'''Description'''
|-
|''x_L''||Lower bounds on x.
|-
|''x_U''||Upper bounds on x.
|-
|''A''||The linear constraint matrix.
|-
|''b_L''||Lower bounds on linear constraints.
|-
|''b_U''||Upper bounds on linear constraints.
|-
|''c_L''||Lower bounds on nonlinear constraints.
|-
|''c_U''||Upper bounds on nonlinear constraints.
|-
|''f_Low''||Lower bound on solution.
|-
|''x_0''||Starting point.
|-valign="top"
|''MaxCPU''||Maximal CPU Time (in seconds) to be used by ecpMINLP, stops with best point found
|-valign="top"
|''PriLev''||Print level in ecpMINLP (default 1). Also see optParam.IterPrint
{|class="wikitable"
!value||output
|-
|=0||Silent.
|-
|>0||Initial information and convergence results.
|-
|>1||Output a line whenever the solution has improved, containing:
nIterations, nCuts, nCuts with criteria fulfilled, nLinearizations, nSpecialCuts, best solution.
|-
|>2||Output a line every iteration with the following information:
{|class="wikitable"
!label||description
|-
|It ||Iterations
|-
|nECP ||Number of extended cutting planes (ECP)
|-
|nAlpha>=lim||Number of ECP with criteria fulfilled
|-
|nL ||Number of linearizations
|-
|nSECP ||Number of special case ECP (created from constraint on bound)
|-
|fIPMin ||Objective of best solution at current iteration
|}
|-
|>3||Output a description of each step in the MINLP algorithm
|-
|>4||Output additional numerical information in some algorithm steps
|-
|>5||Output information in substeps (preprocessing, line search)
|}
|-valign="top"
|''PriLevOptMIP''||Print level in MIP sub-solvers, (CPLEX and others, see the documentation for the solver used). 
Usually: 
=0 No output 
>0 Convergence results 
>1 Output every iteration 
>2 Output each step in the algorithm
|-valign="top"
|''PriLevOptNLP''||Print level in NLP sub-solvers, (SNOPT and others, see the documentation for the solver used). 
Usually: 
=0 No output 
>0 Convergence results 
>1 Output every iteration 
>2 Output each step in the algorithm
|-valign="top"
|''SolverMIP''||Name of the solver used for MIP subproblems. If TOMLAB /gurobi is installed, gurobi is the default solver. If TOMLAB /CPLEX is installed, CPLEX is second choice as default. Otherwise the default solver is found calling GetSolver('mip',1); Supported as subsolvers are gurobi, CPLEX, mipSolve, milpSolve and cutplane.
|-valign="top"
|''SolverNLP''||
Name of the solver used for NLP subproblems. If packages /SOL or /SNOTP is installed, snopt is the default solver. Otherwise the default solver is found calling GetSolver('con',1);
|-
|''SolverLP''||Name of the solver used for LP subproblems when SolverMIP == mipSolve
|-
|''MIP''||Structure with parameters specific to mixed integer optimization. See the table below describing the fields used in the MIP structure.
|-
|''ECPMINLP''||Structure with parameters specific to the ecpMINLP solver. See the table below describing the fields used in the ECPMINLP structure.
|-
|''optParam''||Structure with general optimization parameters. See the table below describing the fields used in the optParam structure.
|}

===MIP structure===
Substructure in Prob with parameters related to mixed integer programming.

{|class="wikitable"
!colspan="2"|'''fields used in Prob.MIP''':
|-
|'''Field'''||'''Description'''
|-valign="top"
|''IntVars''||If empty, all variables are assumed non-integer. If islogical(IntVars) (=all elements are 0/1), then 1 = integer variable, 0 = continuous variable. If any element ''>''1, IntVars is the indices for integer variables.
|-valign="top"
|''fIP''||An upper bound on the IP value wanted. Makes it possible to cut branches and avoid node computations. Used even if xIP not given.
|-valign="top"
|''xIP''||The x-values giving the fIP value, if a solution (xIP,fIP) is known.
|-valign="top"
|''DualGap''||ecpMINLP stops if the duality gap is less than DualGap
DualGap = 1, stop at first integer solution, e.g. DualGap = 0.01,stop if solution < 1% from optimal solution.
 The lower bound Prob.f_Low is used, (default -1.0e300), which can also be set by the user. If f_Low has not been changed from default the lower bound is obtained from the initial solution of a relaxed problem, but only when ECPMINLP.INIT_BND is 1 or 2 (default).
 Default DualGap is -1, not used.
|-valign="top"
|''PPP''||Pre-processing and probing, default is 0. 
0 Not used. Default. 
1 Apply initially on MINLP problem. 
2 Apply each iteration before solving MILP sub-problem.
|-
|''ROUNDH''||If nonzero, a rounding heuristics will be used on the initial NLP solution in order to obtain an initial integer solution. Requires ECPMINLP.InitBndType enabled. Default is 1, enabled.
|}

===ECPMINLP structure===
Substructure in ''Prob'' with solver-specific options.

{|class="wikitable"
!colspan="2"|fields used in Prob.ECPMINLP
|-
|'''Field'''||'''Description'''
|-valign="top"
|''beta''||Multiplier when increasing alpha after an infeasible MILP solution.
 Alpha is a parameter individually adjusting each cutting plane, starting at 1.0 and increasing until meeting a certain criterion. Default value for beta is 1.3.
|-valign="top"
|''gamma''||Multiplier when increasing alpha when MILP solution does not violate any nonlinear contraints, but still does not decrease the upper bound of the objective.
 Alpha is a parameter individually adjusting each cutting plane, starting at 1.0 and increasing until meeting a certain criterion. Default value for gamma is 2.0.
|-valign="top"
|''PREALLOC''||Flag enabling preallocation of memory for cutting planes and linearizations.
 0 No preallocation, dynamic growth of arrays. Current default.
 1 Preallocate arrays.
|-valign="top"
|''INIT_BND''||Selects method for setting lower bound when f_Low not changed from default.
{|class="wikitable"
!value||method
|-valign="top"
|0 ||No extra initial lower bound.
|-valign="top"
|1 ||Use default TOMLAB NLP solver on problem with relaxed integer constraints. Add a linearization if a feasible MINLP solution was found.
|-valign="top"
|2 ||Add an initial linearization as long as a feasdbile NLP solution was found. The linearization is a simple lower bound on the MILP objective. Default.
|-valign="top"
|3 ||Same as 2, but also use the gradient in the linearization. This might improve the solution process for some problems where no solution can be found otherwise. But for many problems, using this initial linearization cuts off a feasbiel region and slows down or even hinders the solver completely. Recommended to only use as a last resort.
|}
|-valign="top"
|''SETTOL''||Flag enabling changing tolerances, described below under optParam.eps_x, optParam.eps_x and optParam.eps_f.
 0 Default. Using the recommended solver default values, 1.0e-3.
 1 Tolerances can be changed, taken from Prob.optParam.
|-valign="top"
|''INTSOLLIM_INCR''||Integer option when using CPLEX as MIP subsolver.
 Define how much the CPLEX parameter INTSOLLIM increases when a feasible solution is not optimal and all alpha values have met their criteria.
 If set to zero, optimal strategy will be used immediately instead, without any gradual increase of INTSOLLIM.
 Default is 1.
|-valign="top"
|''USECUTPOOL''||Set nonzero to use a pool for the alpha-regulated extended cutting planes.
 Cuts not active in the MILP-solution for CUTDELBND iterations in a row will be inactivated (removed from the MILP-problem) until they are violated in a new solution.
 Default is 0, not used.
|-valign="top"
|''CUTDELBND''||The number of consecutive times an extended cutting plane can be inactive before it gets removed and put into the inactive pool, if the option USECUTPOOL is set nonzero.
 Default is 15 times.
|-valign="top"
|''MAXITNOIMP''||Limit on the number of successive iterations allowed without any improvements at all to neither objective nor solution point before the solver terminates
 Default is 2.
|-valign="top"
|''USENLP''||Set nonzero to use an NLP sub-solver on the original problem with the integer variables fixed at values from the latest MILP solution. Default is 1, enabled.
|-valign="top"
|''USERESELECT''||Set nonzero to enable cut reselection heuristics. Default is 1, enabled.
|-valign="top"
|''SCALECUTS''||Set nonzero to scale cuts before they are added to the MILP problem. Scaling is done by dividing the cut with its norm. Default is 1, enabled.
|}

===optParam Structure===
Substructure in ''Prob'' with general optimization parameters.

{|class="wikitable"
!colspan="2"|fields used in Prob.optParam
|-
|'''Field'''||'''Value'''
|-valign="top"
|''MaxIter''||Maximal number of iterations, default 10000
|-valign="top"
|''IterPrint''||Print short information each iteration. Setting PriLev > 1 also enables IterPrint, setting it to 1.
|-valign="top"
|''eps_x''||Linear constraint violation convergence tolerance. Default is 2.0e-6
|-valign="top"
|''eps_g''||Constraint violation convergence tolerance. Default is 1.0e-7
|-valign="top"
|''eps_f''||Optimality tolerance. Default is 1.0e-8
|}

''NOTE:'' For the solver to use these tolerances, the flag ''ECPMINLP.SETTOL'' must be set to nonzero.

==Outputs==

{| class="wikitable"
!''Result''||colspan="2"|Structure with result from optimization. The following fields are changed:
|-
|||''Iter ''||Number of iterations.
|-valign="top"
|||''ExitFlag ''||Exit flag.
 0: Solution found, or integer solution with duality gap less than user tolerance.
 1: Maximal number of iterations reached.
 2: Empty feasible set, no integer solution found.
 3: Problem in subsolver, see Inform value.
 99: Maximal CPU Time used (cputime > Prob.maxCPU
|-
|||''Inform''||Inform for ExitFlag != 3
 0: Global solution found.
 1: Local solution found.
 2: No solution found.
 >2: Inform value from subsolver.
|-
|||''ExitText''||Text string giving ''ExitFlag'' and ''Inform'' information.
|-valign="top"
|||''DualGap''||Relative duality gap, max(0,fIPMin-fLB)/-fIPMin-, if fIPMin =0; max(0,fIPMin-fLB) if fIPMin == 0. If fIPMin =0: Scale with 100, 100*Dual- Gap, to get the percentage duality gap. For absolute value duality gap: scale with fIPMin, fIPMin * DualGap
|-
|||''x_k''||Solution.
|-valign="top"
|||''f_k''||Function value at optimum.
|-
|||''g_k''||Gradient vector at optimum.
|-
|||''c_k''||Constraint values at optimum.
|-
|||''cJac''||Constraint derivative values at optimum.
|-
|||''xState''||State of each variable, described in [[TOMLAB_Appendix_B#Table:_The_state_variable_xState_for_the_variable.|TOMLAB Appendix B]].
|-
|||''bState''||State of each constraint, described in [[TOMLAB_Appendix_B#Table:_The_state_variable_bState_for_each_linear_constraint.|TOMLAB Appendix B]].
|-
|||''cState''||State of each general constraint, described in [[TOMLAB_Appendix_B#Table:_The_state_variable_cState_for_each_nonlinear_constraint.|TOMLAB Appendix B]].
|-
|||''x_0''||Starting point x_0.
|-
|||''Solver''||Solver used ('ecpMINLP').
|-
|||''SolverAlgorithm''||Description of method used.
|-
|||''Prob''||Problem structure used.
|}

== Algorithm==
ecpMINLP Solves convex or pseudo-convex mixed-integer nonlinear programming problems using an extended cutting plane algorithm with cuts regulated by a parameter-vector alpha. Cuts and linearizations are added to MIP subproblem which is then solved by a subsolver in each iteration.

The solver algorithm is mainly based on the paper 'Solving Pseudo-Convex Mixed Integer Optimization Problems by Cutting Plane Techniques' by Tapio Westerlund and Ray Pörn, published in Optimization and Engineering 3, 253-280, 2002, with some modifications.

Most prominent features in addition to the ones described in the main reference above are
* Solving the relaxed NLP problem initially to obtain a lower bound on the solution.
* A rounding heuristics performed on the initial NLP solution in order to obtain an initial upper bound on the initial solutions.
* Optional use of a cutpool for the alpha-regulated extended cutting planes.

[[Category:MIPNLP]]

MIPNLP ecpMINLP

2015-02-13T13:09:43Z

Bjorn: /* MIP structure */

{{Part Of Manual|title=the MIPNLP Manual|link=[[MIPNLP|MIPNLP Manual]]}}
==Purpose==

ecpMINLP solves convex mixed-integer nonlinear programming problems (MINLP).

''ecpMINLP ''solves problems of the form

<math>
\begin{array}{cccccc}
\min\limits_{x} & f(x) \\s/t & x_{L} & \leq & x & \leq & x_{U} \\& b_{L} & \leq & Ax & \leq & b_{U} \\& c_{L} & \leq & c(x) & \leq & c_{U} \\& & & {x_{j} \in \mathbb{N} \ \ \forall j \in I} \\
\end{array}
</math>

where <math>x,x_{L},x_{U}\in \mathbb{R}^{n}</math> , <math>c(x),c_{L},c_{U}\in
\mathbb{R}^{m_{1}}</math> , <math>A\in \mathbb{R}^{m_{2}\times n}</math> and
<math>b_{L},b_{U}\in \mathbb{R}^{m_{2}}</math>. The variables <math>x \in I</math> , the
index subset of <math>1,...,n</math> are restricted to be integers but can be either continuously differentiable or not. An initalization routine will detect strict integer variables in the problem.

==Calling Syntax==

Driver call, including printing with level 2:
<source lang="matlab">
Result = tomRun('ecpMINLP',Prob,2);
</source>
Direct solver call:
<source lang="matlab">
Result = ecpMINLP(Prob);
PrintResult(Result);
Result = tomRun('ecpMINLP',Prob,...)
</source>

=== Warm Start ===
Warm start is currently not supported, but might be included in a future release.

==Inputs==

===Prob structure===
The '''TOMLAB''' problem structure

{|class="wikitable"
!colspan="2"|The following fields are used in the problem description structure Prob
|-
|'''Field'''||'''Description'''
|-
|''x_L''||Lower bounds on x.
|-
|''x_U''||Upper bounds on x.
|-
|''A''||The linear constraint matrix.
|-
|''b_L''||Lower bounds on linear constraints.
|-
|''b_U''||Upper bounds on linear constraints.
|-
|''c_L''||Lower bounds on nonlinear constraints.
|-
|''c_U''||Upper bounds on nonlinear constraints.
|-
|''f_Low''||Lower bound on solution.
|-
|''x_0''||Starting point.
|-valign="top"
|''MaxCPU''||Maximal CPU Time (in seconds) to be used by ecpMINLP, stops with best point found
|-valign="top"
|''PriLev''||Print level in ecpMINLP (default 1). Also see optParam.IterPrint
{|class="wikitable"
!value||output
|-
|=0||Silent.
|-
|>0||Initial information and convergence results.
|-
|>1||Output a line whenever the solution has improved, containing:
nIterations, nCuts, nCuts with criteria fulfilled, nLinearizations, nSpecialCuts, best solution.
|-
|>2||Output a line every iteration with the following information:
{|class="wikitable"
!label||description
|-
|It ||Iterations
|-
|nECP ||Number of extended cutting planes (ECP)
|-
|nAlpha>=lim||Number of ECP with criteria fulfilled
|-
|nL ||Number of linearizations
|-
|nSECP ||Number of special case ECP (created from constraint on bound)
|-
|fIPMin ||Objective of best solution at current iteration
|}
|-
|>3||Output a description of each step in the MINLP algorithm
|-
|>4||Output additional numerical information in some algorithm steps
|-
|>5||Output information in substeps (preprocessing, line search)
|}
|-valign="top"
|''PriLevOptMIP''||Print level in MIP sub-solvers, (CPLEX and others, see the documentation for the solver used). 
Usually: 
=0 No output 
>0 Convergence results 
>1 Output every iteration 
>2 Output each step in the algorithm
|-valign="top"
|''PriLevOptNLP''||Print level in NLP sub-solvers, (SNOPT and others, see the documentation for the solver used). 
Usually: 
=0 No output 
>0 Convergence results 
>1 Output every iteration 
>2 Output each step in the algorithm
|-valign="top"
|''SolverMIP''||Name of the solver used for MIP subproblems. If TOMLAB /gurobi is installed, gurobi is the default solver. If TOMLAB /CPLEX is installed, CPLEX is second choice as default. Otherwise the default solver is found calling GetSolver('mip',1); Supported as subsolvers are gurobi, CPLEX, mipSolve, milpSolve and cutplane.
|-valign="top"
|''SolverNLP''||
Name of the solver used for NLP subproblems. If packages /SOL or /SNOTP is installed, snopt is the default solver. Otherwise the default solver is found calling GetSolver('con',1);
|-
|''SolverLP''||Name of the solver used for LP subproblems when SolverMIP == mipSolve
|-
|''MIP''||Structure with parameters specific to mixed integer optimization. See the table below describing the fields used in the MIP structure.
|-
|''ECPMINLP''||Structure with parameters specific to the ecpMINLP solver. See the table below describing the fields used in the ECPMINLP structure.
|-
|''optParam''||Structure with general optimization parameters. See the table below describing the fields used in the optParam structure.
|}

===MIP structure===
Substructure in Prob with parameters related to mixed integer programming.

{|class="wikitable"
!colspan="2"|'''fields used in Prob.MIP''':
|-
|'''Field'''||'''Description'''
|-valign="top"
|''IntVars''||If empty, all variables are assumed non-integer. If islogical(IntVars) (=all elements are 0/1), then 1 = integer variable, 0 = continuous variable. If any element ''>''1, IntVars is the indices for integer variables.
|-valign="top"
|''fIP''||An upper bound on the IP value wanted. Makes it possible to cut branches and avoid node computations. Used even if xIP not given.
|-valign="top"
|''xIP''||The x-values giving the fIP value, if a solution (xIP,fIP) is known.
|-valign="top"
|''DualGap''||ecpMINLP stops if the duality gap is less than DualGap
DualGap = 1, stop at first integer solution, e.g. DualGap = 0.01,stop if solution < 1% from optimal solution.
 The lower bound Prob.f_Low is used, (default -1.0e300), which can also be set by the user. If f_Low has not been changed from default the lower bound is obtained from the initial solution of a relaxed problem, but only when ECPMINLP.INIT_BND is 1 or 2 (default).
 Default DualGap is -1, not used.
|-valign="top"
|''PPP''||Pre-processing and probing, default is 0. 
0 Not used. Default. 
1 Apply initially on MINLP problem. 
2 Apply each iteration before solving MILP sub-problem.
|-
|''ROUNDH''||If nonzero, a rounding heuristics will be used on the initial NLP solution in order to obtain an initial integer solution. Requires ECPMINLP.INIT_BND enabled. Default is 1, enabled.
|}

===ECPMINLP structure===
Substructure in ''Prob'' with solver-specific options.

{|class="wikitable"
!colspan="2"|fields used in Prob.ECPMINLP
|-
|'''Field'''||'''Description'''
|-valign="top"
|''beta''||Multiplier when increasing alpha after an infeasible MILP solution.
 Alpha is a parameter individually adjusting each cutting plane, starting at 1.0 and increasing until meeting a certain criterion. Default value for beta is 1.3.
|-valign="top"
|''gamma''||Multiplier when increasing alpha when MILP solution does not violate any nonlinear contraints, but still does not decrease the upper bound of the objective.
 Alpha is a parameter individually adjusting each cutting plane, starting at 1.0 and increasing until meeting a certain criterion. Default value for gamma is 2.0.
|-valign="top"
|''PREALLOC''||Flag enabling preallocation of memory for cutting planes and linearizations.
 0 No preallocation, dynamic growth of arrays. Current default.
 1 Preallocate arrays.
|-valign="top"
|''INIT_BND''||Selects method for setting lower bound when f_Low not changed from default.
{|class="wikitable"
!value||method
|-valign="top"
|0 ||No extra initial lower bound.
|-valign="top"
|1 ||Use default TOMLAB NLP solver on problem with relaxed integer constraints. Add a linearization if a feasible MINLP solution was found.
|-valign="top"
|2 ||Add an initial linearization as long as a feasdbile NLP solution was found. The linearization is a simple lower bound on the MILP objective. Default.
|-valign="top"
|3 ||Same as 2, but also use the gradient in the linearization. This might improve the solution process for some problems where no solution can be found otherwise. But for many problems, using this initial linearization cuts off a feasbiel region and slows down or even hinders the solver completely. Recommended to only use as a last resort.
|}
|-valign="top"
|''SETTOL''||Flag enabling changing tolerances, described below under optParam.eps_x, optParam.eps_x and optParam.eps_f.
 0 Default. Using the recommended solver default values, 1.0e-3.
 1 Tolerances can be changed, taken from Prob.optParam.
|-valign="top"
|''INTSOLLIM_INCR''||Integer option when using CPLEX as MIP subsolver.
 Define how much the CPLEX parameter INTSOLLIM increases when a feasible solution is not optimal and all alpha values have met their criteria.
 If set to zero, optimal strategy will be used immediately instead, without any gradual increase of INTSOLLIM.
 Default is 1.
|-valign="top"
|''USECUTPOOL''||Set nonzero to use a pool for the alpha-regulated extended cutting planes.
 Cuts not active in the MILP-solution for CUTDELBND iterations in a row will be inactivated (removed from the MILP-problem) until they are violated in a new solution.
 Default is 0, not used.
|-valign="top"
|''CUTDELBND''||The number of consecutive times an extended cutting plane can be inactive before it gets removed and put into the inactive pool, if the option USECUTPOOL is set nonzero.
 Default is 15 times.
|-valign="top"
|''MAXITNOIMP''||Limit on the number of successive iterations allowed without any improvements at all to neither objective nor solution point before the solver terminates
 Default is 2.
|-valign="top"
|''USENLP''||Set nonzero to use an NLP sub-solver on the original problem with the integer variables fixed at values from the latest MILP solution. Default is 1, enabled.
|-valign="top"
|''USERESELECT''||Set nonzero to enable cut reselection heuristics. Default is 1, enabled.
|-valign="top"
|''SCALECUTS''||Set nonzero to scale cuts before they are added to the MILP problem. Scaling is done by dividing the cut with its norm. Default is 1, enabled.
|}

===optParam Structure===
Substructure in ''Prob'' with general optimization parameters.

{|class="wikitable"
!colspan="2"|fields used in Prob.optParam
|-
|'''Field'''||'''Value'''
|-valign="top"
|''MaxIter''||Maximal number of iterations, default 10000
|-valign="top"
|''IterPrint''||Print short information each iteration. Setting PriLev > 1 also enables IterPrint, setting it to 1.
|-valign="top"
|''eps_x''||Linear constraint violation convergence tolerance. Default is 2.0e-6
|-valign="top"
|''eps_g''||Constraint violation convergence tolerance. Default is 1.0e-7
|-valign="top"
|''eps_f''||Optimality tolerance. Default is 1.0e-8
|}

''NOTE:'' For the solver to use these tolerances, the flag ''ECPMINLP.SETTOL'' must be set to nonzero.

==Outputs==

{| class="wikitable"
!''Result''||colspan="2"|Structure with result from optimization. The following fields are changed:
|-
|||''Iter ''||Number of iterations.
|-valign="top"
|||''ExitFlag ''||Exit flag.
 0: Solution found, or integer solution with duality gap less than user tolerance.
 1: Maximal number of iterations reached.
 2: Empty feasible set, no integer solution found.
 3: Problem in subsolver, see Inform value.
 99: Maximal CPU Time used (cputime > Prob.maxCPU
|-
|||''Inform''||Inform for ExitFlag != 3
 0: Global solution found.
 1: Local solution found.
 2: No solution found.
 >2: Inform value from subsolver.
|-
|||''ExitText''||Text string giving ''ExitFlag'' and ''Inform'' information.
|-valign="top"
|||''DualGap''||Relative duality gap, max(0,fIPMin-fLB)/-fIPMin-, if fIPMin =0; max(0,fIPMin-fLB) if fIPMin == 0. If fIPMin =0: Scale with 100, 100*Dual- Gap, to get the percentage duality gap. For absolute value duality gap: scale with fIPMin, fIPMin * DualGap
|-
|||''x_k''||Solution.
|-valign="top"
|||''f_k''||Function value at optimum.
|-
|||''g_k''||Gradient vector at optimum.
|-
|||''c_k''||Constraint values at optimum.
|-
|||''cJac''||Constraint derivative values at optimum.
|-
|||''xState''||State of each variable, described in [[TOMLAB_Appendix_B#Table:_The_state_variable_xState_for_the_variable.|TOMLAB Appendix B]].
|-
|||''bState''||State of each constraint, described in [[TOMLAB_Appendix_B#Table:_The_state_variable_bState_for_each_linear_constraint.|TOMLAB Appendix B]].
|-
|||''cState''||State of each general constraint, described in [[TOMLAB_Appendix_B#Table:_The_state_variable_cState_for_each_nonlinear_constraint.|TOMLAB Appendix B]].
|-
|||''x_0''||Starting point x_0.
|-
|||''Solver''||Solver used ('ecpMINLP').
|-
|||''SolverAlgorithm''||Description of method used.
|-
|||''Prob''||Problem structure used.
|}

== Algorithm==
ecpMINLP Solves convex or pseudo-convex mixed-integer nonlinear programming problems using an extended cutting plane algorithm with cuts regulated by a parameter-vector alpha. Cuts and linearizations are added to MIP subproblem which is then solved by a subsolver in each iteration.

The solver algorithm is mainly based on the paper 'Solving Pseudo-Convex Mixed Integer Optimization Problems by Cutting Plane Techniques' by Tapio Westerlund and Ray Pörn, published in Optimization and Engineering 3, 253-280, 2002, with some modifications.

Most prominent features in addition to the ones described in the main reference above are
* Solving the relaxed NLP problem initially to obtain a lower bound on the solution.
* A rounding heuristics performed on the initial NLP solution in order to obtain an initial upper bound on the initial solutions.
* Optional use of a cutpool for the alpha-regulated extended cutting planes.

[[Category:MIPNLP]]

MIPNLP ecpMINLP

2015-02-13T13:08:51Z

Bjorn: /* Prob structure */

{{Part Of Manual|title=the MIPNLP Manual|link=[[MIPNLP|MIPNLP Manual]]}}
==Purpose==

ecpMINLP solves convex mixed-integer nonlinear programming problems (MINLP).

''ecpMINLP ''solves problems of the form

<math>
\begin{array}{cccccc}
\min\limits_{x} & f(x) \\s/t & x_{L} & \leq & x & \leq & x_{U} \\& b_{L} & \leq & Ax & \leq & b_{U} \\& c_{L} & \leq & c(x) & \leq & c_{U} \\& & & {x_{j} \in \mathbb{N} \ \ \forall j \in I} \\
\end{array}
</math>

where <math>x,x_{L},x_{U}\in \mathbb{R}^{n}</math> , <math>c(x),c_{L},c_{U}\in
\mathbb{R}^{m_{1}}</math> , <math>A\in \mathbb{R}^{m_{2}\times n}</math> and
<math>b_{L},b_{U}\in \mathbb{R}^{m_{2}}</math>. The variables <math>x \in I</math> , the
index subset of <math>1,...,n</math> are restricted to be integers but can be either continuously differentiable or not. An initalization routine will detect strict integer variables in the problem.

==Calling Syntax==

Driver call, including printing with level 2:
<source lang="matlab">
Result = tomRun('ecpMINLP',Prob,2);
</source>
Direct solver call:
<source lang="matlab">
Result = ecpMINLP(Prob);
PrintResult(Result);
Result = tomRun('ecpMINLP',Prob,...)
</source>

=== Warm Start ===
Warm start is currently not supported, but might be included in a future release.

==Inputs==

===Prob structure===
The '''TOMLAB''' problem structure

{|class="wikitable"
!colspan="2"|The following fields are used in the problem description structure Prob
|-
|'''Field'''||'''Description'''
|-
|''x_L''||Lower bounds on x.
|-
|''x_U''||Upper bounds on x.
|-
|''A''||The linear constraint matrix.
|-
|''b_L''||Lower bounds on linear constraints.
|-
|''b_U''||Upper bounds on linear constraints.
|-
|''c_L''||Lower bounds on nonlinear constraints.
|-
|''c_U''||Upper bounds on nonlinear constraints.
|-
|''f_Low''||Lower bound on solution.
|-
|''x_0''||Starting point.
|-valign="top"
|''MaxCPU''||Maximal CPU Time (in seconds) to be used by ecpMINLP, stops with best point found
|-valign="top"
|''PriLev''||Print level in ecpMINLP (default 1). Also see optParam.IterPrint
{|class="wikitable"
!value||output
|-
|=0||Silent.
|-
|>0||Initial information and convergence results.
|-
|>1||Output a line whenever the solution has improved, containing:
nIterations, nCuts, nCuts with criteria fulfilled, nLinearizations, nSpecialCuts, best solution.
|-
|>2||Output a line every iteration with the following information:
{|class="wikitable"
!label||description
|-
|It ||Iterations
|-
|nECP ||Number of extended cutting planes (ECP)
|-
|nAlpha>=lim||Number of ECP with criteria fulfilled
|-
|nL ||Number of linearizations
|-
|nSECP ||Number of special case ECP (created from constraint on bound)
|-
|fIPMin ||Objective of best solution at current iteration
|}
|-
|>3||Output a description of each step in the MINLP algorithm
|-
|>4||Output additional numerical information in some algorithm steps
|-
|>5||Output information in substeps (preprocessing, line search)
|}
|-valign="top"
|''PriLevOptMIP''||Print level in MIP sub-solvers, (CPLEX and others, see the documentation for the solver used). 
Usually: 
=0 No output 
>0 Convergence results 
>1 Output every iteration 
>2 Output each step in the algorithm
|-valign="top"
|''PriLevOptNLP''||Print level in NLP sub-solvers, (SNOPT and others, see the documentation for the solver used). 
Usually: 
=0 No output 
>0 Convergence results 
>1 Output every iteration 
>2 Output each step in the algorithm
|-valign="top"
|''SolverMIP''||Name of the solver used for MIP subproblems. If TOMLAB /gurobi is installed, gurobi is the default solver. If TOMLAB /CPLEX is installed, CPLEX is second choice as default. Otherwise the default solver is found calling GetSolver('mip',1); Supported as subsolvers are gurobi, CPLEX, mipSolve, milpSolve and cutplane.
|-valign="top"
|''SolverNLP''||
Name of the solver used for NLP subproblems. If packages /SOL or /SNOTP is installed, snopt is the default solver. Otherwise the default solver is found calling GetSolver('con',1);
|-
|''SolverLP''||Name of the solver used for LP subproblems when SolverMIP == mipSolve
|-
|''MIP''||Structure with parameters specific to mixed integer optimization. See the table below describing the fields used in the MIP structure.
|-
|''ECPMINLP''||Structure with parameters specific to the ecpMINLP solver. See the table below describing the fields used in the ECPMINLP structure.
|-
|''optParam''||Structure with general optimization parameters. See the table below describing the fields used in the optParam structure.
|}

===MIP structure===
Substructure in Prob with parameters related to mixed integer programming.

{|class="wikitable"
!colspan="2"|'''fields used in Prob.MIP''':
|-
|'''Field'''||'''Description'''
|-valign="top"
|''IntVars''||If empty, all variables are assumed non-integer. If islogical(IntVars) (=all elements are 0/1), then 1 = integer variable, 0 = continuous variable. If any element ''>''1, IntVars is the indices for integer variables.
|-valign="top"
|''fIP''||An upper bound on the IP value wanted. Makes it possible to cut branches and avoid node computations. Used even if xIP not given.
|-valign="top"
|''xIP''||The x-values giving the fIP value, if a solution (xIP,fIP) is known.
|-valign="top"
|''DualGap''||ecpMINLP stops if the duality gap is less than DualGap
DualGap = 1, stop at first integer solution, e.g. DualGap = 0.01,stop if solution < 1% from optimal solution.
 The lower bound Prob.f_Low is used, (default -1.0e300), which can also be set by the user. If f_Low has not been changed from default the lower bound is obtained from the initial solution of a relaxed problem, but only when ECPMINLP.INIT_BND is 1 or 2 (default).
 Default DualGap is -1, not used.
|-valign="top"
|''PPP''||Pre-processing and probing, default is 0. 
0 Not used. Default. 
1 Apply initially on MINLP problem. 
2 Apply each iteration before solving MILP subproblem.
|-
|''ROUNDH''||If nonzero, a rounding heuristics will be used on the initial NLP solution in order to obtain an initial integer solution. Requires ECPMINLP.INIT_BND enabled. Default is 1, enabled.
|}

===ECPMINLP structure===
Substructure in ''Prob'' with solver-specific options.

{|class="wikitable"
!colspan="2"|fields used in Prob.ECPMINLP
|-
|'''Field'''||'''Description'''
|-valign="top"
|''beta''||Multiplier when increasing alpha after an infeasible MILP solution.
 Alpha is a parameter individually adjusting each cutting plane, starting at 1.0 and increasing until meeting a certain criterion. Default value for beta is 1.3.
|-valign="top"
|''gamma''||Multiplier when increasing alpha when MILP solution does not violate any nonlinear contraints, but still does not decrease the upper bound of the objective.
 Alpha is a parameter individually adjusting each cutting plane, starting at 1.0 and increasing until meeting a certain criterion. Default value for gamma is 2.0.
|-valign="top"
|''PREALLOC''||Flag enabling preallocation of memory for cutting planes and linearizations.
 0 No preallocation, dynamic growth of arrays. Current default.
 1 Preallocate arrays.
|-valign="top"
|''INIT_BND''||Selects method for setting lower bound when f_Low not changed from default.
{|class="wikitable"
!value||method
|-valign="top"
|0 ||No extra initial lower bound.
|-valign="top"
|1 ||Use default TOMLAB NLP solver on problem with relaxed integer constraints. Add a linearization if a feasible MINLP solution was found.
|-valign="top"
|2 ||Add an initial linearization as long as a feasdbile NLP solution was found. The linearization is a simple lower bound on the MILP objective. Default.
|-valign="top"
|3 ||Same as 2, but also use the gradient in the linearization. This might improve the solution process for some problems where no solution can be found otherwise. But for many problems, using this initial linearization cuts off a feasbiel region and slows down or even hinders the solver completely. Recommended to only use as a last resort.
|}
|-valign="top"
|''SETTOL''||Flag enabling changing tolerances, described below under optParam.eps_x, optParam.eps_x and optParam.eps_f.
 0 Default. Using the recommended solver default values, 1.0e-3.
 1 Tolerances can be changed, taken from Prob.optParam.
|-valign="top"
|''INTSOLLIM_INCR''||Integer option when using CPLEX as MIP subsolver.
 Define how much the CPLEX parameter INTSOLLIM increases when a feasible solution is not optimal and all alpha values have met their criteria.
 If set to zero, optimal strategy will be used immediately instead, without any gradual increase of INTSOLLIM.
 Default is 1.
|-valign="top"
|''USECUTPOOL''||Set nonzero to use a pool for the alpha-regulated extended cutting planes.
 Cuts not active in the MILP-solution for CUTDELBND iterations in a row will be inactivated (removed from the MILP-problem) until they are violated in a new solution.
 Default is 0, not used.
|-valign="top"
|''CUTDELBND''||The number of consecutive times an extended cutting plane can be inactive before it gets removed and put into the inactive pool, if the option USECUTPOOL is set nonzero.
 Default is 15 times.
|-valign="top"
|''MAXITNOIMP''||Limit on the number of successive iterations allowed without any improvements at all to neither objective nor solution point before the solver terminates
 Default is 2.
|-valign="top"
|''USENLP''||Set nonzero to use an NLP sub-solver on the original problem with the integer variables fixed at values from the latest MILP solution. Default is 1, enabled.
|-valign="top"
|''USERESELECT''||Set nonzero to enable cut reselection heuristics. Default is 1, enabled.
|-valign="top"
|''SCALECUTS''||Set nonzero to scale cuts before they are added to the MILP problem. Scaling is done by dividing the cut with its norm. Default is 1, enabled.
|}

===optParam Structure===
Substructure in ''Prob'' with general optimization parameters.

{|class="wikitable"
!colspan="2"|fields used in Prob.optParam
|-
|'''Field'''||'''Value'''
|-valign="top"
|''MaxIter''||Maximal number of iterations, default 10000
|-valign="top"
|''IterPrint''||Print short information each iteration. Setting PriLev > 1 also enables IterPrint, setting it to 1.
|-valign="top"
|''eps_x''||Linear constraint violation convergence tolerance. Default is 2.0e-6
|-valign="top"
|''eps_g''||Constraint violation convergence tolerance. Default is 1.0e-7
|-valign="top"
|''eps_f''||Optimality tolerance. Default is 1.0e-8
|}

''NOTE:'' For the solver to use these tolerances, the flag ''ECPMINLP.SETTOL'' must be set to nonzero.

==Outputs==

{| class="wikitable"
!''Result''||colspan="2"|Structure with result from optimization. The following fields are changed:
|-
|||''Iter ''||Number of iterations.
|-valign="top"
|||''ExitFlag ''||Exit flag.
 0: Solution found, or integer solution with duality gap less than user tolerance.
 1: Maximal number of iterations reached.
 2: Empty feasible set, no integer solution found.
 3: Problem in subsolver, see Inform value.
 99: Maximal CPU Time used (cputime > Prob.maxCPU
|-
|||''Inform''||Inform for ExitFlag != 3
 0: Global solution found.
 1: Local solution found.
 2: No solution found.
 >2: Inform value from subsolver.
|-
|||''ExitText''||Text string giving ''ExitFlag'' and ''Inform'' information.
|-valign="top"
|||''DualGap''||Relative duality gap, max(0,fIPMin-fLB)/-fIPMin-, if fIPMin =0; max(0,fIPMin-fLB) if fIPMin == 0. If fIPMin =0: Scale with 100, 100*Dual- Gap, to get the percentage duality gap. For absolute value duality gap: scale with fIPMin, fIPMin * DualGap
|-
|||''x_k''||Solution.
|-valign="top"
|||''f_k''||Function value at optimum.
|-
|||''g_k''||Gradient vector at optimum.
|-
|||''c_k''||Constraint values at optimum.
|-
|||''cJac''||Constraint derivative values at optimum.
|-
|||''xState''||State of each variable, described in [[TOMLAB_Appendix_B#Table:_The_state_variable_xState_for_the_variable.|TOMLAB Appendix B]].
|-
|||''bState''||State of each constraint, described in [[TOMLAB_Appendix_B#Table:_The_state_variable_bState_for_each_linear_constraint.|TOMLAB Appendix B]].
|-
|||''cState''||State of each general constraint, described in [[TOMLAB_Appendix_B#Table:_The_state_variable_cState_for_each_nonlinear_constraint.|TOMLAB Appendix B]].
|-
|||''x_0''||Starting point x_0.
|-
|||''Solver''||Solver used ('ecpMINLP').
|-
|||''SolverAlgorithm''||Description of method used.
|-
|||''Prob''||Problem structure used.
|}

== Algorithm==
ecpMINLP Solves convex or pseudo-convex mixed-integer nonlinear programming problems using an extended cutting plane algorithm with cuts regulated by a parameter-vector alpha. Cuts and linearizations are added to MIP subproblem which is then solved by a subsolver in each iteration.

The solver algorithm is mainly based on the paper 'Solving Pseudo-Convex Mixed Integer Optimization Problems by Cutting Plane Techniques' by Tapio Westerlund and Ray Pörn, published in Optimization and Engineering 3, 253-280, 2002, with some modifications.

Most prominent features in addition to the ones described in the main reference above are
* Solving the relaxed NLP problem initially to obtain a lower bound on the solution.
* A rounding heuristics performed on the initial NLP solution in order to obtain an initial upper bound on the initial solutions.
* Optional use of a cutpool for the alpha-regulated extended cutting planes.

[[Category:MIPNLP]]

MIPNLP stoaMINLP

2015-02-13T12:30:33Z

Bjorn: /* optParam structure */

{{Part Of Manual|title=the MIPNLP Manual|link=[[MIPNLP|MIPNLP Manual]]}}
==Purpose==

stoaMINLP solves convex mixed-integer nonlinear programming problems (MINLP).

''stoaMINLP ''solves problems of the form

<math>
\begin{array}{cccccc}
\min\limits_{x} & f(x) \\s/t & x_{L} & \leq & x & \leq & x_{U} \\& b_{L} & \leq & Ax & \leq & b_{U} \\& c_{L} & \leq & c(x) & \leq & c_{U} \\& & & {x_{j} \in \mathbb{N} \ \ \forall j \in I} \\
\end{array}
</math>

where <math>x,x_{L},x_{U}\in \mathbb{R}^{n}</math> , <math>c(x),c_{L},c_{U}\in
\mathbb{R}^{m_{1}}</math> , <math>A\in \mathbb{R}^{m_{2}\times n}</math> and
<math>b_{L},b_{U}\in \mathbb{R}^{m_{2}}</math>. The variables <math>x \in I</math> , the
index subset of <math>1,...,n</math> are restricted to be integers.

==Calling Syntax==

Recommended is to first set IterPrint, to get information each iteration
<source lang="matlab">
Prob.optParam.IterPrint = 1;
</source>
Driver call, including printing with level 2:
<source lang="matlab">
Result = tomRun('stoaMINLP',Prob,2);
</source>
Direct solver call:
<source lang="matlab">
Result = stoaMINLP(Prob);
PrintResult(Result);
Result = tomRun('stoaMINLP',Prob,...)
</source>

=== Warm Start ===
To make a restart (warm start), just set the warm start flag, and call stoaMINLP once again:

<source lang="matlab">
Prob.WarmStart = 1;
Result = tomRun('stoaMINLP', Prob, 2);
</source>

stoaMINLP will read warm start information from the stoaMINLPSave.mat file. Another warm start (with same MaxFunc) is made by just calling tomRun again:

<source lang="matlab">
Result = tomRun('stoaMINLP', Prob, 2);
</source>

To make a restart from the warm start information in the Result structure, make a call to WarmDefGLOBAL before calling stoaMINLP. WarmDefGLOBAL moves information from the Result structure to the Prob structure and sets the warm start flag, <code>Prob.WarmStart = 1;</code>

<source lang="matlab">
Prob = WarmDefGLOBAL('stoaMINLP', Prob, Result);
</source>

where Result is the result structure returned by the previous run. A warm start (with same MaxIter) is done by just calling tomRun again:

<source lang="matlab">
Result = tomRun('stoaMINLP', Prob, 2);
</source>

To make another warm start with new MaxIter 100, say, redefine MaxIter as:

<source lang="matlab">
Prob.optParam.MaxIter = 100;
</source>

Then repeat the two lines:

<source lang="matlab">
Prob = WarmDefGLOBAL('stoaMINLP', Prob, Result);
Result = tomRun('stoaMINLP', Prob, 2);
</source>

==Inputs==

===Prob structure===
The '''TOMLAB''' problem structure

{| class="wikitable"
!colspan="2"|The following fields are used in ''Prob'':
|-
|'''Field'''||'''Description'''
|-
|''x_L''||Lower bounds on x.
|-
|''x_U''||Upper bounds on x.
|-
|''A''||The linear constraint matrix.
|-
|''b_L''||Lower bounds on linear constraints.
|-
|''b_U''||Upper bounds on linear constraints.
|-
|''c_L''||Lower bounds on nonlinear constraints.
|-
|''c_U''||Upper bounds on nonlinear constraints.
|-
|''x_0''||Starting point.
|-valign="top"
|''Convex''||If Convex==1, assume NLP problems are convex, and only one local NLP solver call is used at each node. If Convex==0 (Default), multiMin is used to do many calls to a local solver to determine the global minima at each node. The global minimum with most components integer valued is chosen.
|-valign="top"
|''MaxCPU''||Maximal CPU Time (in seconds) to be used by stoaMINLP, stops with best point found
|-valign="top"
|''PriLev''||Print level in stoaMINLP (default 1). Also see optParam.IterPrint
|-valign="top"
|''PriLevOpt''||Print level in sub-solvers (SNOPT and other NLP solvers): =0 No output; ''>''0 Convergence results. ''>''1 Output every iteration, ''>''2 Output each step in the NLP alg For other NLP solvers, see the documentation for the solver
|-valign="top"
|''WarmStart''||If true, ''>''0, stoaMINLP reads the output from the last run from Prob.stoaMINLP, if it exists. If it doesn't exist, stoaMINLP attempts to open and read warm start data from mat-file stoaMINLPSave.mat. stoaMINLP uses the warm start information to continue from the last run. The mat-file minlp- SolveSave.mat is saved every Prob.MIP.SaveFreq iteration.
|-valign="top"
|''SolverNLP''||Name of the solver used for NLP subproblems. If empty, the default solver is found calling GetSolver('con',1); If TOMLAB /SOL installed, SNOPT is the default solver. If SolverNLP is a SOL solver (SNOPT, MINOS or NPSOL), the SOL.optPar and SOL.PrintFile is used: See help minosTL.m, npsolTL.m or snoptTL.m for how to set these parameters
|-
|''SolverNLP0''||Name of the solver used for the initial NLP-problem. If empty, SolverNLP is used.
|-valign="top"
|''SolverLP''||Name of the solver used for LP subproblems. If empty, the default solver is found calling GetSolver('lp',1). If TOMLAB /SOL or /SNOPT or /NPSOL installed, MINOS is the default solver. If SolverLP is a SOL solver (MINOS, SNOPT or NPSOL), the SOL.optPar and SOL.PrintFile is used: See help minosTL.m, npsolTL.m or snoptTL.m for how to set these parameters.
|-valign="top"
|''RandState''||See help rngset for how to initialize the random generator. Default is RandState = -1 If Convex == 0 and globalSolver == 'multiMin', RandState is sent to multiMin to initizalize the random generator.
|-valign="top"
|''xInit''||Parameter sent to the solver multiMin which is used to solve relaxed sub-problems for nonconvex problems (with Prob.Convex set to false). xInit determines the way initial points are generated and is set as follows: 
 
Either 
1x1 number - 
If > 0, the number of random initial points, default min(3000,30*n); 
If < 0, generate |xInit| points with Latin Hypercube design 
 
d x m matrix - Every column is an initial point (of length d = Prob.N) 
 
Default value for xInit is min(3000,max(60,N*6)) at all nodes except the root node 
|-valign="top"
|''xInit0''||Parameter sent to the solver multiMin when solving the initial relaxed NLP problem at the root node. 
Default value for xInit0 is min(3000,max(100,N*10)) 
See xInit for more information. 
|-valign="top"
|''MIP''||Structure defining integer optimization parameters. See the table below for a description of each field used in ''Prob.MIP''.
|-valign="top"
|''STOAMINLP''||Structure with solver-specific options. See the table below with descriptions of the fields used in ''Prob.STOAMINLP''.
|-valign="top"
|''optParam''||Structure with general optimization parameters. See the table below with descriptions of the fields used in ''Prob.optParam''.
|}

===MIP structure===

Substructure in Prob with parameters related to mixed integer programming.

{|class="wikitable"
!colspan="2"|fields used in '''Prob.MIP'''
|-
|'''Field'''||'''Description'''
|-valign="top"
|''IntVars''||If empty, all variables are assumed non-integer. If islogical(IntVars) (=all elements are 0/1), then 1 = integer variable, 0 = continuous variable. If any element ''>''1, IntVars is the indices for integer variables.
|-valign="top"
|''VarWeight''||Weight for each variable in the variable selection phase. A lower value gives higher priority. Setting Prob.MIP.VarWeight might improve convergence. 
VarWeight must be of length N, but the values corresponding to noninteger variables will be ignored.
|-valign="top"
|''DualGap''||''stoaMINLP ''stops if the duality gap is less than DualGap. DualGap = 1, stop at first integer solution e.g. DualGap = 0.01, stop if solution ''< ''1% from optimal solution. Note that a finite lower bound will only be set by the solver and thus generating a gap when Prob.Convex is set to true. If Prob.Convex is set to false, the lower bound will be -Inf.
|-valign="top"
|''fIP''||An upper bound on the IP value wanted. Makes it possible to cut branches and avoid node computations. Used even if xIP not given.
|-valign="top"
|''xIP''||The x-values giving the fIP value, if a solution (xIP,fIP) is known.
|-valign="top"
|''NodeSel''||Node selection method: = 1 Depth First. Priority on nodes with more integer components. Default = 2 Breadth First. Priority on nodes with more integer components. = 3 Pure LIFO (Last in, first out) Depth First. = 4 Pure FIFO (First in, first out) Breadth First. = 5 Maximize integer components. = 6 Best bound. = 7 Best estimate using pseudo-costs. = 8 Best projection.
|-valign="top"
|''Backtrack''||Switch node selection method during branch and bound. 
When set to any of the NodeSel methods, node selection method is changed to the Backtrack value when the backtracking criterion (see parameter BackCrit below) is fulfilled. For available choices, see NodeSel above. Default is 2, Breadth First.
|-valign="top"
|''BackCrit''||Backtracking criterion, used when Backtrack > 0. 
= 0. Integer solution found. Default. 
= 1. Current node worse than best estimate of active nodes.
|-valign="top"
|''VarSel''||Variable selection method in branch and bound. = 1 Use variable with most fractional value. = 2 Use gradient and distance to nearest integer value. = 3 Pseudo-cost-based branching.
|-valign="top"
|''KNAPSACK''||If = 1, use a knapsack heuristic. Default 0.
|-valign="top"
|''ROUNDH''||If = 1, use a rounding heuristic. Default 0.
|-valign="top"
|''SaveFreq''||Warm start info saved on stoaMINLPSave.mat every SaveFreq iteration (default -1, i.e. no warm start info is saved)
|}

===STOAMINLP structure===

Substructure in Prob with solver-specific options

{|class="wikitable"
!colspan="2"|fields used in Prob.STOAMINLP
|-
|'''Field'''||'''Description'''
|-valign="top"
|''USE_CUTS''||Flag to use cutting plane algorithm described in [[StoaMINLP#Algorithm]]. Using cuts is not recommended for nonconvex problems. Set nonzero to enable, zero to disable. By default, STOAMINLP.USE_CUTS is set to Prob.Convex.
|-valign="top"
|''LoL_ecp''||Parameter regulating likelihood of linearization using extended cutting plane. See [[StoaMINLP#Algorithm]] for more information. Default 10.
|-valign="top"
|''TOD_ecp''||Parameter regulating "tailing off" detection for extended cutting plane linearizations. See [[StoaMINLP#Algorithm]] for more information. Default 0.001.
|-valign="top"
|''BCB_ecp''||Parameter regulating the balance between branching the search tree and adding linearizations using extended cutting plane. See [[StoaMINLP#Algorithm]] for more information. Default 10.
|-valign="top"
|''LoL_ff''||Parameter regulating likelihood of linearization using fixed fractional integer decision variables. See [[StoaMINLP#Algorithm]] for more information. Default 10.
|-valign="top"
|''TOD_ff''||Parameter regulating "tailing off" detection for linearizations using fixed fractional integer decision variables. See [[StoaMINLP#Algorithm]] for more information. Default 0.001.
|-valign="top"
|''BCB_ff''||Parameter regulating the balance between branching the search tree and adding linearizations using fixed fractional integer decision variables. See [[StoaMINLP#Algorithm]] for more information. Default 10.
|-valign="top"
|''LoL_nlpr''||Parameter regulating likelihood of linearization using the solution of the relaxed NLP problem. See [[StoaMINLP#Algorithm]] for more information. Default 10.
|-valign="top"
|''TOD_nlpr''||Parameter regulating "tailing off" detection for linearizations using the solution of the relaxed NLP problem. See [[StoaMINLP#Algorithm]] for more information. Default 0.001.
|-valign="top"
|''BCB_nlpr''||Parameter regulating the balance between branching the search tree and adding linearizations using the solution of the relaxed NLP problem. See [[StoaMINLP#Algorithm]] for more information. Default 10.
|-valign="top"
|''rTYPE''||= 0 r is fixed to the value in rVALUE. = 1 r is a uniformly distributed random number in the interval [0,1]. Default.
|-valign="top"
|''rVALUE''||Defines the value of r when rTYPE is set to zero. Default is 0.5.
|-valign="top"
|''CUTPOOL''||= 0 All linearizations constraints are kept in the master problem. = 1 Manage a pool with inactive linearization constraints. If an inactive constraint gets violated, it is brought back from the pool. Default.
|-valign="top"
|''CutDelBnd''||The number of consecutive times a linearization can be inactive before it gets removed and put into the inactive pool. Default is 15 times.
|-valign="top"
|''LIM_DEL_CUT''||= 0 No extra deletion of cuts. Default when Prob.Convex == 1. = 1 Delete any cuts limiting the true feasible region whenever detected. Such cuts will appear if the problem has nonlinear constraints. Default when Prob.Convex == 0.
|-valign="top"
|''PsCoItLim''||Limit on time spent per node calculating initial pseudo costs when MIP.VarSel == 3. Default is 120 (s).
|-valign="top"
|''PrintLin''||Set nonzero to print short information about the type of linearization added. Default 0. Enabled when IterPrint > 3.
|-valign="top"
|''PRINTPOOL''||Set nonzero to print Set nonzero to print the decisions taken in the cutpool management.Default 0. Enabled when IterPrint > 4.
|}

===optParam structure===

Substructure in Prob with general optimization parameters.

{|class="wikitable"
!colspan="2"|fields used in Prob.optParam:
|-
|'''Field'''||'''Description'''
|-valign="top"
|''MaxIter''||Maximal number of iterations, default 10000
|-valign="top"
|''IterPrint''||Print short information each iteration. Setting PriLev > 1 also enables IterPrint, setting it to 1. 
The information printed for different levels is as follows: 

>0 Two lines at each node with an improved integer solution: 
Iteration number: 
* Depth in tree (symbol L[] - empty list, symbol Gap - Dual Gap convergence) 
* fNLP (Optimal f(x) current node) 
* fIPMin (Best integer feasible f(x) found) 
* LowBnd (Lower bound on optimal integer feasible f(x)) 
* Dual Gap in absolut value and percent 
* The length of the node list L, -L- 
* The Inform and ExitFlag the solver returned at the current node 
* FuEv (Number of function evaluations used by solver at current node) 
* Date and time stamp. 
* Outer approximation linearizations, number of cuts in active/inactive pool (|C| #A #I). 

> 1 Two lines at each evaluated node with the information described above. 
Moreover, with IterPrint enabled a notice is printed whenever the algorithm switches node selection methods. 
Setting a higher value of IterPrint gives more detailed information. 

>2 Depth, number of integer components and lower bound on objective for each node in L. 
>3 Sets LINPRINT = 1, print info about linearizations added (if used). 
>4 Sets POOLPRINT = 1, print info about cut-pool management (if used).
|-valign="top"
|''bTol''||Linear constraint violation convergence tolerance. Default 1.0e-6
|-valign="top"
|''cTol''||Constraint violation convergence tolerance. Default 1.0e-6
|-valign="top"
|''fTol''||Optimality tolerance. Default 3.0e-13
|-valign="top"
|''xTol''||Variable convergence tolerance. Default 2.2204e-13
|}

==Outputs==

{| class="wikitable"
!''Result''||colspan="2"|Structure with result from optimization. The following fields are changed:
|-
|||''Iter ''||Number of iterations.
|-valign="top"
|||''ExitFlag ''||Exit flag. 0: Global optimal solution found, or integer solution with duality gap less than user tolerance. 1: Maximal number of iterations reached. 2: Empty feasible set, no integer solution found. 4: No feasible point found running NLP relaxation. 5: Illegal x_0 found in NLP relaxation. 99: Maximal CPU Time used (cputime ''> ''Prob.MaxCPU).
|-
|||''Inform''||Code telling type of convergence, returned from subsolver.
|-
|||''ExitText''||Text string giving ''ExitFlag'' and ''Inform'' information.
|-valign="top"
|||''DualGap''||Relative duality gap, max(0,fIPMin-fLB)/-fIPMin-, if fIPMin =0; max(0,fIPMin-fLB) if fIPMin == 0. If fIPMin =0: Scale with 100, 100*Dual- Gap, to get the percentage duality gap. For absolute value duality gap: scale with fIPMin, fIPMin * DualGap
|-
|||''x_k''||Solution.
|-valign="top"
|||''v_k''||Lagrange multipliers. Bounds, Linear and Nonlinear Constraints, size n + mLin + mNonLin.
|-
|||''f_k''||Function value at optimum.
|-
|||''g_k''||Gradient vector at optimum.
|-
|||''x_0''||Starting point x_0.
|-
|||''f_0''||Function value at start.
|-
|||''c_k''||Constraint values at optimum.
|-
|||''cJac''||Constraint derivative values at optimum.
|-
|||''xState''||State of each variable, described in [[TOMLAB_Appendix_B#Table:_The_state_variable_xState_for_the_variable.|TOMLAB Appendix B]].
|-
|||''bState''||State of each constraint, described in [[TOMLAB_Appendix_B#Table:_The_state_variable_bState_for_each_linear_constraint.|TOMLAB Appendix B]].
|-
|||''cState''||State of each general constraint, described in [[TOMLAB_Appendix_B#Table:_The_state_variable_cState_for_each_nonlinear_constraint.|TOMLAB Appendix B]].
|-
|||''Solver''||Solver used ('stoaMINLP').
|-
|||''SolverAlgorithm''||Description of method used.
|-
|||''Prob''||Problem structure used.
|-valign="top"
|||''stoaMINLP''||A structure with warm start information. Use with WarmDefGLOBAL, see example [[StoaMINLP#Warm_Start|here]].
|}

[[Category:MIPNLP]]

MIPNLP stoaMINLP

2015-02-13T12:24:17Z

Bjorn: /* STOAMINLP structure */

{{Part Of Manual|title=the MIPNLP Manual|link=[[MIPNLP|MIPNLP Manual]]}}
==Purpose==

stoaMINLP solves convex mixed-integer nonlinear programming problems (MINLP).

''stoaMINLP ''solves problems of the form

<math>
\begin{array}{cccccc}
\min\limits_{x} & f(x) \\s/t & x_{L} & \leq & x & \leq & x_{U} \\& b_{L} & \leq & Ax & \leq & b_{U} \\& c_{L} & \leq & c(x) & \leq & c_{U} \\& & & {x_{j} \in \mathbb{N} \ \ \forall j \in I} \\
\end{array}
</math>

where <math>x,x_{L},x_{U}\in \mathbb{R}^{n}</math> , <math>c(x),c_{L},c_{U}\in
\mathbb{R}^{m_{1}}</math> , <math>A\in \mathbb{R}^{m_{2}\times n}</math> and
<math>b_{L},b_{U}\in \mathbb{R}^{m_{2}}</math>. The variables <math>x \in I</math> , the
index subset of <math>1,...,n</math> are restricted to be integers.

==Calling Syntax==

Recommended is to first set IterPrint, to get information each iteration
<source lang="matlab">
Prob.optParam.IterPrint = 1;
</source>
Driver call, including printing with level 2:
<source lang="matlab">
Result = tomRun('stoaMINLP',Prob,2);
</source>
Direct solver call:
<source lang="matlab">
Result = stoaMINLP(Prob);
PrintResult(Result);
Result = tomRun('stoaMINLP',Prob,...)
</source>

=== Warm Start ===
To make a restart (warm start), just set the warm start flag, and call stoaMINLP once again:

<source lang="matlab">
Prob.WarmStart = 1;
Result = tomRun('stoaMINLP', Prob, 2);
</source>

stoaMINLP will read warm start information from the stoaMINLPSave.mat file. Another warm start (with same MaxFunc) is made by just calling tomRun again:

<source lang="matlab">
Result = tomRun('stoaMINLP', Prob, 2);
</source>

To make a restart from the warm start information in the Result structure, make a call to WarmDefGLOBAL before calling stoaMINLP. WarmDefGLOBAL moves information from the Result structure to the Prob structure and sets the warm start flag, <code>Prob.WarmStart = 1;</code>

<source lang="matlab">
Prob = WarmDefGLOBAL('stoaMINLP', Prob, Result);
</source>

where Result is the result structure returned by the previous run. A warm start (with same MaxIter) is done by just calling tomRun again:

<source lang="matlab">
Result = tomRun('stoaMINLP', Prob, 2);
</source>

To make another warm start with new MaxIter 100, say, redefine MaxIter as:

<source lang="matlab">
Prob.optParam.MaxIter = 100;
</source>

Then repeat the two lines:

<source lang="matlab">
Prob = WarmDefGLOBAL('stoaMINLP', Prob, Result);
Result = tomRun('stoaMINLP', Prob, 2);
</source>

==Inputs==

===Prob structure===
The '''TOMLAB''' problem structure

{| class="wikitable"
!colspan="2"|The following fields are used in ''Prob'':
|-
|'''Field'''||'''Description'''
|-
|''x_L''||Lower bounds on x.
|-
|''x_U''||Upper bounds on x.
|-
|''A''||The linear constraint matrix.
|-
|''b_L''||Lower bounds on linear constraints.
|-
|''b_U''||Upper bounds on linear constraints.
|-
|''c_L''||Lower bounds on nonlinear constraints.
|-
|''c_U''||Upper bounds on nonlinear constraints.
|-
|''x_0''||Starting point.
|-valign="top"
|''Convex''||If Convex==1, assume NLP problems are convex, and only one local NLP solver call is used at each node. If Convex==0 (Default), multiMin is used to do many calls to a local solver to determine the global minima at each node. The global minimum with most components integer valued is chosen.
|-valign="top"
|''MaxCPU''||Maximal CPU Time (in seconds) to be used by stoaMINLP, stops with best point found
|-valign="top"
|''PriLev''||Print level in stoaMINLP (default 1). Also see optParam.IterPrint
|-valign="top"
|''PriLevOpt''||Print level in sub-solvers (SNOPT and other NLP solvers): =0 No output; ''>''0 Convergence results. ''>''1 Output every iteration, ''>''2 Output each step in the NLP alg For other NLP solvers, see the documentation for the solver
|-valign="top"
|''WarmStart''||If true, ''>''0, stoaMINLP reads the output from the last run from Prob.stoaMINLP, if it exists. If it doesn't exist, stoaMINLP attempts to open and read warm start data from mat-file stoaMINLPSave.mat. stoaMINLP uses the warm start information to continue from the last run. The mat-file minlp- SolveSave.mat is saved every Prob.MIP.SaveFreq iteration.
|-valign="top"
|''SolverNLP''||Name of the solver used for NLP subproblems. If empty, the default solver is found calling GetSolver('con',1); If TOMLAB /SOL installed, SNOPT is the default solver. If SolverNLP is a SOL solver (SNOPT, MINOS or NPSOL), the SOL.optPar and SOL.PrintFile is used: See help minosTL.m, npsolTL.m or snoptTL.m for how to set these parameters
|-
|''SolverNLP0''||Name of the solver used for the initial NLP-problem. If empty, SolverNLP is used.
|-valign="top"
|''SolverLP''||Name of the solver used for LP subproblems. If empty, the default solver is found calling GetSolver('lp',1). If TOMLAB /SOL or /SNOPT or /NPSOL installed, MINOS is the default solver. If SolverLP is a SOL solver (MINOS, SNOPT or NPSOL), the SOL.optPar and SOL.PrintFile is used: See help minosTL.m, npsolTL.m or snoptTL.m for how to set these parameters.
|-valign="top"
|''RandState''||See help rngset for how to initialize the random generator. Default is RandState = -1 If Convex == 0 and globalSolver == 'multiMin', RandState is sent to multiMin to initizalize the random generator.
|-valign="top"
|''xInit''||Parameter sent to the solver multiMin which is used to solve relaxed sub-problems for nonconvex problems (with Prob.Convex set to false). xInit determines the way initial points are generated and is set as follows: 
 
Either 
1x1 number - 
If > 0, the number of random initial points, default min(3000,30*n); 
If < 0, generate |xInit| points with Latin Hypercube design 
 
d x m matrix - Every column is an initial point (of length d = Prob.N) 
 
Default value for xInit is min(3000,max(60,N*6)) at all nodes except the root node 
|-valign="top"
|''xInit0''||Parameter sent to the solver multiMin when solving the initial relaxed NLP problem at the root node. 
Default value for xInit0 is min(3000,max(100,N*10)) 
See xInit for more information. 
|-valign="top"
|''MIP''||Structure defining integer optimization parameters. See the table below for a description of each field used in ''Prob.MIP''.
|-valign="top"
|''STOAMINLP''||Structure with solver-specific options. See the table below with descriptions of the fields used in ''Prob.STOAMINLP''.
|-valign="top"
|''optParam''||Structure with general optimization parameters. See the table below with descriptions of the fields used in ''Prob.optParam''.
|}

===MIP structure===

Substructure in Prob with parameters related to mixed integer programming.

{|class="wikitable"
!colspan="2"|fields used in '''Prob.MIP'''
|-
|'''Field'''||'''Description'''
|-valign="top"
|''IntVars''||If empty, all variables are assumed non-integer. If islogical(IntVars) (=all elements are 0/1), then 1 = integer variable, 0 = continuous variable. If any element ''>''1, IntVars is the indices for integer variables.
|-valign="top"
|''VarWeight''||Weight for each variable in the variable selection phase. A lower value gives higher priority. Setting Prob.MIP.VarWeight might improve convergence. 
VarWeight must be of length N, but the values corresponding to noninteger variables will be ignored.
|-valign="top"
|''DualGap''||''stoaMINLP ''stops if the duality gap is less than DualGap. DualGap = 1, stop at first integer solution e.g. DualGap = 0.01, stop if solution ''< ''1% from optimal solution. Note that a finite lower bound will only be set by the solver and thus generating a gap when Prob.Convex is set to true. If Prob.Convex is set to false, the lower bound will be -Inf.
|-valign="top"
|''fIP''||An upper bound on the IP value wanted. Makes it possible to cut branches and avoid node computations. Used even if xIP not given.
|-valign="top"
|''xIP''||The x-values giving the fIP value, if a solution (xIP,fIP) is known.
|-valign="top"
|''NodeSel''||Node selection method: = 1 Depth First. Priority on nodes with more integer components. Default = 2 Breadth First. Priority on nodes with more integer components. = 3 Pure LIFO (Last in, first out) Depth First. = 4 Pure FIFO (First in, first out) Breadth First. = 5 Maximize integer components. = 6 Best bound. = 7 Best estimate using pseudo-costs. = 8 Best projection.
|-valign="top"
|''Backtrack''||Switch node selection method during branch and bound. 
When set to any of the NodeSel methods, node selection method is changed to the Backtrack value when the backtracking criterion (see parameter BackCrit below) is fulfilled. For available choices, see NodeSel above. Default is 2, Breadth First.
|-valign="top"
|''BackCrit''||Backtracking criterion, used when Backtrack > 0. 
= 0. Integer solution found. Default. 
= 1. Current node worse than best estimate of active nodes.
|-valign="top"
|''VarSel''||Variable selection method in branch and bound. = 1 Use variable with most fractional value. = 2 Use gradient and distance to nearest integer value. = 3 Pseudo-cost-based branching.
|-valign="top"
|''KNAPSACK''||If = 1, use a knapsack heuristic. Default 0.
|-valign="top"
|''ROUNDH''||If = 1, use a rounding heuristic. Default 0.
|-valign="top"
|''SaveFreq''||Warm start info saved on stoaMINLPSave.mat every SaveFreq iteration (default -1, i.e. no warm start info is saved)
|}

===STOAMINLP structure===

Substructure in Prob with solver-specific options

{|class="wikitable"
!colspan="2"|fields used in Prob.STOAMINLP
|-
|'''Field'''||'''Description'''
|-valign="top"
|''USE_CUTS''||Flag to use cutting plane algorithm described in [[StoaMINLP#Algorithm]]. Using cuts is not recommended for nonconvex problems. Set nonzero to enable, zero to disable. By default, STOAMINLP.USE_CUTS is set to Prob.Convex.
|-valign="top"
|''LoL_ecp''||Parameter regulating likelihood of linearization using extended cutting plane. See [[StoaMINLP#Algorithm]] for more information. Default 10.
|-valign="top"
|''TOD_ecp''||Parameter regulating "tailing off" detection for extended cutting plane linearizations. See [[StoaMINLP#Algorithm]] for more information. Default 0.001.
|-valign="top"
|''BCB_ecp''||Parameter regulating the balance between branching the search tree and adding linearizations using extended cutting plane. See [[StoaMINLP#Algorithm]] for more information. Default 10.
|-valign="top"
|''LoL_ff''||Parameter regulating likelihood of linearization using fixed fractional integer decision variables. See [[StoaMINLP#Algorithm]] for more information. Default 10.
|-valign="top"
|''TOD_ff''||Parameter regulating "tailing off" detection for linearizations using fixed fractional integer decision variables. See [[StoaMINLP#Algorithm]] for more information. Default 0.001.
|-valign="top"
|''BCB_ff''||Parameter regulating the balance between branching the search tree and adding linearizations using fixed fractional integer decision variables. See [[StoaMINLP#Algorithm]] for more information. Default 10.
|-valign="top"
|''LoL_nlpr''||Parameter regulating likelihood of linearization using the solution of the relaxed NLP problem. See [[StoaMINLP#Algorithm]] for more information. Default 10.
|-valign="top"
|''TOD_nlpr''||Parameter regulating "tailing off" detection for linearizations using the solution of the relaxed NLP problem. See [[StoaMINLP#Algorithm]] for more information. Default 0.001.
|-valign="top"
|''BCB_nlpr''||Parameter regulating the balance between branching the search tree and adding linearizations using the solution of the relaxed NLP problem. See [[StoaMINLP#Algorithm]] for more information. Default 10.
|-valign="top"
|''rTYPE''||= 0 r is fixed to the value in rVALUE. = 1 r is a uniformly distributed random number in the interval [0,1]. Default.
|-valign="top"
|''rVALUE''||Defines the value of r when rTYPE is set to zero. Default is 0.5.
|-valign="top"
|''CUTPOOL''||= 0 All linearizations constraints are kept in the master problem. = 1 Manage a pool with inactive linearization constraints. If an inactive constraint gets violated, it is brought back from the pool. Default.
|-valign="top"
|''CutDelBnd''||The number of consecutive times a linearization can be inactive before it gets removed and put into the inactive pool. Default is 15 times.
|-valign="top"
|''LIM_DEL_CUT''||= 0 No extra deletion of cuts. Default when Prob.Convex == 1. = 1 Delete any cuts limiting the true feasible region whenever detected. Such cuts will appear if the problem has nonlinear constraints. Default when Prob.Convex == 0.
|-valign="top"
|''PsCoItLim''||Limit on time spent per node calculating initial pseudo costs when MIP.VarSel == 3. Default is 120 (s).
|-valign="top"
|''PrintLin''||Set nonzero to print short information about the type of linearization added. Default 0. Enabled when IterPrint > 3.
|-valign="top"
|''PRINTPOOL''||Set nonzero to print Set nonzero to print the decisions taken in the cutpool management.Default 0. Enabled when IterPrint > 4.
|}

===optParam structure===

Substructure in Prob with general optimization parameters.

{|class="wikitable"
!colspan="2"|fields used in Prob.optParam:
|-
|'''Field'''||'''Description'''
|-valign="top"
|''MaxIter''||Maximal number of iterations, default 10000
|-valign="top"
|''IterPrint''||Print short information each iteration. Setting PriLev > 1 also enables IterPrint, setting it to 1. 
The information printed for different levels is as follows: 

>0 A line at each evaluated node with the following: 
Iteration number: 
Depth in tree (symbol L[] - empty list, symbol Gap - Dual Gap convergence), fNLP (Optimal f(x) current node), fIPMin (Best integer feasible f(x) found), LowBnd (Lower bound on optimal integer feasible f(x)), Dual Gap in absolut value and percent, The length of the node list L, -L-, The Inform and ExitFlag the solver returned at the current node, FuEv (Number of function evaluations used by solver at current node), date/time stamp. Outer approximation linearizations, number of cuts in active/inactive pool (|C| #A #I). 

> 1 A line at each evaluated node with the information described above. 
Moreover, with IterPrint enabled a notice is printed whenever the algorithm switches node selection methods. 
Setting a higher value of IterPrint gives more detailed information. 

>2 Depth, number of integer components and lower bound on objective for each node in L. 
>3 Sets LINPRINT = 1, print info about linearizations added (if used). 
>4 Sets POOLPRINT = 1, print info about cut-pool management (if used).
|-valign="top"
|''bTol''||Linear constraint violation convergence tolerance.
|-valign="top"
|''cTol''||Constraint violation convergence tolerance.
|-valign="top"
|''fTol''||Optimality tolerance.
|}

==Outputs==

{| class="wikitable"
!''Result''||colspan="2"|Structure with result from optimization. The following fields are changed:
|-
|||''Iter ''||Number of iterations.
|-valign="top"
|||''ExitFlag ''||Exit flag. 0: Global optimal solution found, or integer solution with duality gap less than user tolerance. 1: Maximal number of iterations reached. 2: Empty feasible set, no integer solution found. 4: No feasible point found running NLP relaxation. 5: Illegal x_0 found in NLP relaxation. 99: Maximal CPU Time used (cputime ''> ''Prob.MaxCPU).
|-
|||''Inform''||Code telling type of convergence, returned from subsolver.
|-
|||''ExitText''||Text string giving ''ExitFlag'' and ''Inform'' information.
|-valign="top"
|||''DualGap''||Relative duality gap, max(0,fIPMin-fLB)/-fIPMin-, if fIPMin =0; max(0,fIPMin-fLB) if fIPMin == 0. If fIPMin =0: Scale with 100, 100*Dual- Gap, to get the percentage duality gap. For absolute value duality gap: scale with fIPMin, fIPMin * DualGap
|-
|||''x_k''||Solution.
|-valign="top"
|||''v_k''||Lagrange multipliers. Bounds, Linear and Nonlinear Constraints, size n + mLin + mNonLin.
|-
|||''f_k''||Function value at optimum.
|-
|||''g_k''||Gradient vector at optimum.
|-
|||''x_0''||Starting point x_0.
|-
|||''f_0''||Function value at start.
|-
|||''c_k''||Constraint values at optimum.
|-
|||''cJac''||Constraint derivative values at optimum.
|-
|||''xState''||State of each variable, described in [[TOMLAB_Appendix_B#Table:_The_state_variable_xState_for_the_variable.|TOMLAB Appendix B]].
|-
|||''bState''||State of each constraint, described in [[TOMLAB_Appendix_B#Table:_The_state_variable_bState_for_each_linear_constraint.|TOMLAB Appendix B]].
|-
|||''cState''||State of each general constraint, described in [[TOMLAB_Appendix_B#Table:_The_state_variable_cState_for_each_nonlinear_constraint.|TOMLAB Appendix B]].
|-
|||''Solver''||Solver used ('stoaMINLP').
|-
|||''SolverAlgorithm''||Description of method used.
|-
|||''Prob''||Problem structure used.
|-valign="top"
|||''stoaMINLP''||A structure with warm start information. Use with WarmDefGLOBAL, see example [[StoaMINLP#Warm_Start|here]].
|}

[[Category:MIPNLP]]

MIPNLP stoaMINLP

2015-02-13T12:22:34Z

Bjorn: /* STOAMINLP structure */

{{Part Of Manual|title=the MIPNLP Manual|link=[[MIPNLP|MIPNLP Manual]]}}
==Purpose==

stoaMINLP solves convex mixed-integer nonlinear programming problems (MINLP).

''stoaMINLP ''solves problems of the form

<math>
\begin{array}{cccccc}
\min\limits_{x} & f(x) \\s/t & x_{L} & \leq & x & \leq & x_{U} \\& b_{L} & \leq & Ax & \leq & b_{U} \\& c_{L} & \leq & c(x) & \leq & c_{U} \\& & & {x_{j} \in \mathbb{N} \ \ \forall j \in I} \\
\end{array}
</math>

where <math>x,x_{L},x_{U}\in \mathbb{R}^{n}</math> , <math>c(x),c_{L},c_{U}\in
\mathbb{R}^{m_{1}}</math> , <math>A\in \mathbb{R}^{m_{2}\times n}</math> and
<math>b_{L},b_{U}\in \mathbb{R}^{m_{2}}</math>. The variables <math>x \in I</math> , the
index subset of <math>1,...,n</math> are restricted to be integers.

==Calling Syntax==

Recommended is to first set IterPrint, to get information each iteration
<source lang="matlab">
Prob.optParam.IterPrint = 1;
</source>
Driver call, including printing with level 2:
<source lang="matlab">
Result = tomRun('stoaMINLP',Prob,2);
</source>
Direct solver call:
<source lang="matlab">
Result = stoaMINLP(Prob);
PrintResult(Result);
Result = tomRun('stoaMINLP',Prob,...)
</source>

=== Warm Start ===
To make a restart (warm start), just set the warm start flag, and call stoaMINLP once again:

<source lang="matlab">
Prob.WarmStart = 1;
Result = tomRun('stoaMINLP', Prob, 2);
</source>

stoaMINLP will read warm start information from the stoaMINLPSave.mat file. Another warm start (with same MaxFunc) is made by just calling tomRun again:

<source lang="matlab">
Result = tomRun('stoaMINLP', Prob, 2);
</source>

To make a restart from the warm start information in the Result structure, make a call to WarmDefGLOBAL before calling stoaMINLP. WarmDefGLOBAL moves information from the Result structure to the Prob structure and sets the warm start flag, <code>Prob.WarmStart = 1;</code>

<source lang="matlab">
Prob = WarmDefGLOBAL('stoaMINLP', Prob, Result);
</source>

where Result is the result structure returned by the previous run. A warm start (with same MaxIter) is done by just calling tomRun again:

<source lang="matlab">
Result = tomRun('stoaMINLP', Prob, 2);
</source>

To make another warm start with new MaxIter 100, say, redefine MaxIter as:

<source lang="matlab">
Prob.optParam.MaxIter = 100;
</source>

Then repeat the two lines:

<source lang="matlab">
Prob = WarmDefGLOBAL('stoaMINLP', Prob, Result);
Result = tomRun('stoaMINLP', Prob, 2);
</source>

==Inputs==

===Prob structure===
The '''TOMLAB''' problem structure

{| class="wikitable"
!colspan="2"|The following fields are used in ''Prob'':
|-
|'''Field'''||'''Description'''
|-
|''x_L''||Lower bounds on x.
|-
|''x_U''||Upper bounds on x.
|-
|''A''||The linear constraint matrix.
|-
|''b_L''||Lower bounds on linear constraints.
|-
|''b_U''||Upper bounds on linear constraints.
|-
|''c_L''||Lower bounds on nonlinear constraints.
|-
|''c_U''||Upper bounds on nonlinear constraints.
|-
|''x_0''||Starting point.
|-valign="top"
|''Convex''||If Convex==1, assume NLP problems are convex, and only one local NLP solver call is used at each node. If Convex==0 (Default), multiMin is used to do many calls to a local solver to determine the global minima at each node. The global minimum with most components integer valued is chosen.
|-valign="top"
|''MaxCPU''||Maximal CPU Time (in seconds) to be used by stoaMINLP, stops with best point found
|-valign="top"
|''PriLev''||Print level in stoaMINLP (default 1). Also see optParam.IterPrint
|-valign="top"
|''PriLevOpt''||Print level in sub-solvers (SNOPT and other NLP solvers): =0 No output; ''>''0 Convergence results. ''>''1 Output every iteration, ''>''2 Output each step in the NLP alg For other NLP solvers, see the documentation for the solver
|-valign="top"
|''WarmStart''||If true, ''>''0, stoaMINLP reads the output from the last run from Prob.stoaMINLP, if it exists. If it doesn't exist, stoaMINLP attempts to open and read warm start data from mat-file stoaMINLPSave.mat. stoaMINLP uses the warm start information to continue from the last run. The mat-file minlp- SolveSave.mat is saved every Prob.MIP.SaveFreq iteration.
|-valign="top"
|''SolverNLP''||Name of the solver used for NLP subproblems. If empty, the default solver is found calling GetSolver('con',1); If TOMLAB /SOL installed, SNOPT is the default solver. If SolverNLP is a SOL solver (SNOPT, MINOS or NPSOL), the SOL.optPar and SOL.PrintFile is used: See help minosTL.m, npsolTL.m or snoptTL.m for how to set these parameters
|-
|''SolverNLP0''||Name of the solver used for the initial NLP-problem. If empty, SolverNLP is used.
|-valign="top"
|''SolverLP''||Name of the solver used for LP subproblems. If empty, the default solver is found calling GetSolver('lp',1). If TOMLAB /SOL or /SNOPT or /NPSOL installed, MINOS is the default solver. If SolverLP is a SOL solver (MINOS, SNOPT or NPSOL), the SOL.optPar and SOL.PrintFile is used: See help minosTL.m, npsolTL.m or snoptTL.m for how to set these parameters.
|-valign="top"
|''RandState''||See help rngset for how to initialize the random generator. Default is RandState = -1 If Convex == 0 and globalSolver == 'multiMin', RandState is sent to multiMin to initizalize the random generator.
|-valign="top"
|''xInit''||Parameter sent to the solver multiMin which is used to solve relaxed sub-problems for nonconvex problems (with Prob.Convex set to false). xInit determines the way initial points are generated and is set as follows: 
 
Either 
1x1 number - 
If > 0, the number of random initial points, default min(3000,30*n); 
If < 0, generate |xInit| points with Latin Hypercube design 
 
d x m matrix - Every column is an initial point (of length d = Prob.N) 
 
Default value for xInit is min(3000,max(60,N*6)) at all nodes except the root node 
|-valign="top"
|''xInit0''||Parameter sent to the solver multiMin when solving the initial relaxed NLP problem at the root node. 
Default value for xInit0 is min(3000,max(100,N*10)) 
See xInit for more information. 
|-valign="top"
|''MIP''||Structure defining integer optimization parameters. See the table below for a description of each field used in ''Prob.MIP''.
|-valign="top"
|''STOAMINLP''||Structure with solver-specific options. See the table below with descriptions of the fields used in ''Prob.STOAMINLP''.
|-valign="top"
|''optParam''||Structure with general optimization parameters. See the table below with descriptions of the fields used in ''Prob.optParam''.
|}

===MIP structure===

Substructure in Prob with parameters related to mixed integer programming.

{|class="wikitable"
!colspan="2"|fields used in '''Prob.MIP'''
|-
|'''Field'''||'''Description'''
|-valign="top"
|''IntVars''||If empty, all variables are assumed non-integer. If islogical(IntVars) (=all elements are 0/1), then 1 = integer variable, 0 = continuous variable. If any element ''>''1, IntVars is the indices for integer variables.
|-valign="top"
|''VarWeight''||Weight for each variable in the variable selection phase. A lower value gives higher priority. Setting Prob.MIP.VarWeight might improve convergence. 
VarWeight must be of length N, but the values corresponding to noninteger variables will be ignored.
|-valign="top"
|''DualGap''||''stoaMINLP ''stops if the duality gap is less than DualGap. DualGap = 1, stop at first integer solution e.g. DualGap = 0.01, stop if solution ''< ''1% from optimal solution. Note that a finite lower bound will only be set by the solver and thus generating a gap when Prob.Convex is set to true. If Prob.Convex is set to false, the lower bound will be -Inf.
|-valign="top"
|''fIP''||An upper bound on the IP value wanted. Makes it possible to cut branches and avoid node computations. Used even if xIP not given.
|-valign="top"
|''xIP''||The x-values giving the fIP value, if a solution (xIP,fIP) is known.
|-valign="top"
|''NodeSel''||Node selection method: = 1 Depth First. Priority on nodes with more integer components. Default = 2 Breadth First. Priority on nodes with more integer components. = 3 Pure LIFO (Last in, first out) Depth First. = 4 Pure FIFO (First in, first out) Breadth First. = 5 Maximize integer components. = 6 Best bound. = 7 Best estimate using pseudo-costs. = 8 Best projection.
|-valign="top"
|''Backtrack''||Switch node selection method during branch and bound. 
When set to any of the NodeSel methods, node selection method is changed to the Backtrack value when the backtracking criterion (see parameter BackCrit below) is fulfilled. For available choices, see NodeSel above. Default is 2, Breadth First.
|-valign="top"
|''BackCrit''||Backtracking criterion, used when Backtrack > 0. 
= 0. Integer solution found. Default. 
= 1. Current node worse than best estimate of active nodes.
|-valign="top"
|''VarSel''||Variable selection method in branch and bound. = 1 Use variable with most fractional value. = 2 Use gradient and distance to nearest integer value. = 3 Pseudo-cost-based branching.
|-valign="top"
|''KNAPSACK''||If = 1, use a knapsack heuristic. Default 0.
|-valign="top"
|''ROUNDH''||If = 1, use a rounding heuristic. Default 0.
|-valign="top"
|''SaveFreq''||Warm start info saved on stoaMINLPSave.mat every SaveFreq iteration (default -1, i.e. no warm start info is saved)
|}

===STOAMINLP structure===

Substructure in Prob with solver-specific options

{|class="wikitable"
!colspan="2"|fields used in Prob.STOAMINLP
|-
|'''Field'''||'''Description'''
|-valign="top"
|''USE_CUTS''||Flag to use cutting plane algorithm described in [[StoaMINLP#Algorithm]]. Using cuts is not recommended for nonconvex problems. Set nonzero to enable, zero to disable. By default, STOAMINLP.USE_CUTS is set to Prob.Convex.
|-valign="top"
|''LoL_ecp''||Parameter regulating likelihood of linearization using extended cutting plane. See [[StoaMINLP#Algorithm]] for more information. Default 10.
|-valign="top"
|''TOD_ecp''||Parameter regulating "tailing off" detection for extended cutting plane linearizations. See [[StoaMINLP#Algorithm]] for more information. Default 0.001.
|-valign="top"
|''BCB_ecp''||Parameter regulating the balance between branching the search tree and adding linearizations using extended cutting plane. See [[StoaMINLP#Algorithm]] for more information. Default 10.
|-valign="top"
|''LoL_ff''||Parameter regulating likelihood of linearization using fixed fractional integer decision variables. See [[StoaMINLP#Algorithm]] for more information. Default 10.
|-valign="top"
|''TOD_ff''||Parameter regulating "tailing off" detection for linearizations using fixed fractional integer decision variables. See [[StoaMINLP#Algorithm]] for more information. Default 0.001.
|-valign="top"
|''BCB_ff''||Parameter regulating the balance between branching the search tree and adding linearizations using fixed fractional integer decision variables. See [[StoaMINLP#Algorithm]] for more information. Default 10.
|-valign="top"
|''LoL_nlpr''||Parameter regulating likelihood of linearization using the solution of the relaxed NLP problem. See [[StoaMINLP#Algorithm]] for more information. Default 10.
|-valign="top"
|''TOD_nlpr''||Parameter regulating "tailing off" detection for linearizations using the solution of the relaxed NLP problem. See [[StoaMINLP#Algorithm]] for more information. Default 0.001.
|-valign="top"
|''BCB_nlpr''||Parameter regulating the balance between branching the search tree and adding linearizations using the solution of the relaxed NLP problem. See [[StoaMINLP#Algorithm]] for more information. Default 10.
|-valign="top"
|''rTYPE''||= 0 r is fixed to the value in rVALUE. = 1 r is a uniformly distributed random number in the interval [0,1]. Default.
|-valign="top"
|''rVALUE''||Defines the value of r when rTYPE is set to zero. Default is 0.5.
|-valign="top"
|''CUTPOOL''||= 0 All linearizations constraints are kept in the master problem. = 1 Manage a pool with inactive linearization constraints. If an inactive constraint gets violated, it is brought back from the pool. Default.
|-valign="top"
|''CutDelBnd''||The number of consecutive times a linearization can be inactive before it gets removed and put into the inactive pool. Default is 15 times.
|-valign="top"
|''LIM_DEL_CUT''||= 0 No extra deletion of cuts. Default when Prob.Convex == 1. = 1 Delete any cuts limiting the true feasible region whenever detected. Such cuts will appear if the problem has nonlinear constraints. Default when Prob.Convex == 0.
|-valign="top"
|''PsCoItLim''||Limit on time spent per node calculating initial pseudo costs when MIP.VarSel == 3. Default is 120 (s).
|-valign="top"
|''PrintLin''||Set nonzero to print short information about the type of linearization added. Default 0. Enabled when IterPrint > 3.
|-valign="top"
|''PRINTPOOL''||Set nonzero to print information about the cutpool management. Default 0. Enabled when IterPrint > 4.
|}

===optParam structure===

Substructure in Prob with general optimization parameters.

{|class="wikitable"
!colspan="2"|fields used in Prob.optParam:
|-
|'''Field'''||'''Description'''
|-valign="top"
|''MaxIter''||Maximal number of iterations, default 10000
|-valign="top"
|''IterPrint''||Print short information each iteration. Setting PriLev > 1 also enables IterPrint, setting it to 1. 
The information printed for different levels is as follows: 

>0 A line at each evaluated node with the following: 
Iteration number: 
Depth in tree (symbol L[] - empty list, symbol Gap - Dual Gap convergence), fNLP (Optimal f(x) current node), fIPMin (Best integer feasible f(x) found), LowBnd (Lower bound on optimal integer feasible f(x)), Dual Gap in absolut value and percent, The length of the node list L, -L-, The Inform and ExitFlag the solver returned at the current node, FuEv (Number of function evaluations used by solver at current node), date/time stamp. Outer approximation linearizations, number of cuts in active/inactive pool (|C| #A #I). 

> 1 A line at each evaluated node with the information described above. 
Moreover, with IterPrint enabled a notice is printed whenever the algorithm switches node selection methods. 
Setting a higher value of IterPrint gives more detailed information. 

>2 Depth, number of integer components and lower bound on objective for each node in L. 
>3 Sets LINPRINT = 1, print info about linearizations added (if used). 
>4 Sets POOLPRINT = 1, print info about cut-pool management (if used).
|-valign="top"
|''bTol''||Linear constraint violation convergence tolerance.
|-valign="top"
|''cTol''||Constraint violation convergence tolerance.
|-valign="top"
|''fTol''||Optimality tolerance.
|}

==Outputs==

{| class="wikitable"
!''Result''||colspan="2"|Structure with result from optimization. The following fields are changed:
|-
|||''Iter ''||Number of iterations.
|-valign="top"
|||''ExitFlag ''||Exit flag. 0: Global optimal solution found, or integer solution with duality gap less than user tolerance. 1: Maximal number of iterations reached. 2: Empty feasible set, no integer solution found. 4: No feasible point found running NLP relaxation. 5: Illegal x_0 found in NLP relaxation. 99: Maximal CPU Time used (cputime ''> ''Prob.MaxCPU).
|-
|||''Inform''||Code telling type of convergence, returned from subsolver.
|-
|||''ExitText''||Text string giving ''ExitFlag'' and ''Inform'' information.
|-valign="top"
|||''DualGap''||Relative duality gap, max(0,fIPMin-fLB)/-fIPMin-, if fIPMin =0; max(0,fIPMin-fLB) if fIPMin == 0. If fIPMin =0: Scale with 100, 100*Dual- Gap, to get the percentage duality gap. For absolute value duality gap: scale with fIPMin, fIPMin * DualGap
|-
|||''x_k''||Solution.
|-valign="top"
|||''v_k''||Lagrange multipliers. Bounds, Linear and Nonlinear Constraints, size n + mLin + mNonLin.
|-
|||''f_k''||Function value at optimum.
|-
|||''g_k''||Gradient vector at optimum.
|-
|||''x_0''||Starting point x_0.
|-
|||''f_0''||Function value at start.
|-
|||''c_k''||Constraint values at optimum.
|-
|||''cJac''||Constraint derivative values at optimum.
|-
|||''xState''||State of each variable, described in [[TOMLAB_Appendix_B#Table:_The_state_variable_xState_for_the_variable.|TOMLAB Appendix B]].
|-
|||''bState''||State of each constraint, described in [[TOMLAB_Appendix_B#Table:_The_state_variable_bState_for_each_linear_constraint.|TOMLAB Appendix B]].
|-
|||''cState''||State of each general constraint, described in [[TOMLAB_Appendix_B#Table:_The_state_variable_cState_for_each_nonlinear_constraint.|TOMLAB Appendix B]].
|-
|||''Solver''||Solver used ('stoaMINLP').
|-
|||''SolverAlgorithm''||Description of method used.
|-
|||''Prob''||Problem structure used.
|-valign="top"
|||''stoaMINLP''||A structure with warm start information. Use with WarmDefGLOBAL, see example [[StoaMINLP#Warm_Start|here]].
|}

[[Category:MIPNLP]]

MIPNLP stoaMINLP

2015-02-13T12:16:17Z

Bjorn: /* Prob structure */

{{Part Of Manual|title=the MIPNLP Manual|link=[[MIPNLP|MIPNLP Manual]]}}
==Purpose==

stoaMINLP solves convex mixed-integer nonlinear programming problems (MINLP).

''stoaMINLP ''solves problems of the form

<math>
\begin{array}{cccccc}
\min\limits_{x} & f(x) \\s/t & x_{L} & \leq & x & \leq & x_{U} \\& b_{L} & \leq & Ax & \leq & b_{U} \\& c_{L} & \leq & c(x) & \leq & c_{U} \\& & & {x_{j} \in \mathbb{N} \ \ \forall j \in I} \\
\end{array}
</math>

where <math>x,x_{L},x_{U}\in \mathbb{R}^{n}</math> , <math>c(x),c_{L},c_{U}\in
\mathbb{R}^{m_{1}}</math> , <math>A\in \mathbb{R}^{m_{2}\times n}</math> and
<math>b_{L},b_{U}\in \mathbb{R}^{m_{2}}</math>. The variables <math>x \in I</math> , the
index subset of <math>1,...,n</math> are restricted to be integers.

==Calling Syntax==

Recommended is to first set IterPrint, to get information each iteration
<source lang="matlab">
Prob.optParam.IterPrint = 1;
</source>
Driver call, including printing with level 2:
<source lang="matlab">
Result = tomRun('stoaMINLP',Prob,2);
</source>
Direct solver call:
<source lang="matlab">
Result = stoaMINLP(Prob);
PrintResult(Result);
Result = tomRun('stoaMINLP',Prob,...)
</source>

=== Warm Start ===
To make a restart (warm start), just set the warm start flag, and call stoaMINLP once again:

<source lang="matlab">
Prob.WarmStart = 1;
Result = tomRun('stoaMINLP', Prob, 2);
</source>

stoaMINLP will read warm start information from the stoaMINLPSave.mat file. Another warm start (with same MaxFunc) is made by just calling tomRun again:

<source lang="matlab">
Result = tomRun('stoaMINLP', Prob, 2);
</source>

To make a restart from the warm start information in the Result structure, make a call to WarmDefGLOBAL before calling stoaMINLP. WarmDefGLOBAL moves information from the Result structure to the Prob structure and sets the warm start flag, <code>Prob.WarmStart = 1;</code>

<source lang="matlab">
Prob = WarmDefGLOBAL('stoaMINLP', Prob, Result);
</source>

where Result is the result structure returned by the previous run. A warm start (with same MaxIter) is done by just calling tomRun again:

<source lang="matlab">
Result = tomRun('stoaMINLP', Prob, 2);
</source>

To make another warm start with new MaxIter 100, say, redefine MaxIter as:

<source lang="matlab">
Prob.optParam.MaxIter = 100;
</source>

Then repeat the two lines:

<source lang="matlab">
Prob = WarmDefGLOBAL('stoaMINLP', Prob, Result);
Result = tomRun('stoaMINLP', Prob, 2);
</source>

==Inputs==

===Prob structure===
The '''TOMLAB''' problem structure

{| class="wikitable"
!colspan="2"|The following fields are used in ''Prob'':
|-
|'''Field'''||'''Description'''
|-
|''x_L''||Lower bounds on x.
|-
|''x_U''||Upper bounds on x.
|-
|''A''||The linear constraint matrix.
|-
|''b_L''||Lower bounds on linear constraints.
|-
|''b_U''||Upper bounds on linear constraints.
|-
|''c_L''||Lower bounds on nonlinear constraints.
|-
|''c_U''||Upper bounds on nonlinear constraints.
|-
|''x_0''||Starting point.
|-valign="top"
|''Convex''||If Convex==1, assume NLP problems are convex, and only one local NLP solver call is used at each node. If Convex==0 (Default), multiMin is used to do many calls to a local solver to determine the global minima at each node. The global minimum with most components integer valued is chosen.
|-valign="top"
|''MaxCPU''||Maximal CPU Time (in seconds) to be used by stoaMINLP, stops with best point found
|-valign="top"
|''PriLev''||Print level in stoaMINLP (default 1). Also see optParam.IterPrint
|-valign="top"
|''PriLevOpt''||Print level in sub-solvers (SNOPT and other NLP solvers): =0 No output; ''>''0 Convergence results. ''>''1 Output every iteration, ''>''2 Output each step in the NLP alg For other NLP solvers, see the documentation for the solver
|-valign="top"
|''WarmStart''||If true, ''>''0, stoaMINLP reads the output from the last run from Prob.stoaMINLP, if it exists. If it doesn't exist, stoaMINLP attempts to open and read warm start data from mat-file stoaMINLPSave.mat. stoaMINLP uses the warm start information to continue from the last run. The mat-file minlp- SolveSave.mat is saved every Prob.MIP.SaveFreq iteration.
|-valign="top"
|''SolverNLP''||Name of the solver used for NLP subproblems. If empty, the default solver is found calling GetSolver('con',1); If TOMLAB /SOL installed, SNOPT is the default solver. If SolverNLP is a SOL solver (SNOPT, MINOS or NPSOL), the SOL.optPar and SOL.PrintFile is used: See help minosTL.m, npsolTL.m or snoptTL.m for how to set these parameters
|-
|''SolverNLP0''||Name of the solver used for the initial NLP-problem. If empty, SolverNLP is used.
|-valign="top"
|''SolverLP''||Name of the solver used for LP subproblems. If empty, the default solver is found calling GetSolver('lp',1). If TOMLAB /SOL or /SNOPT or /NPSOL installed, MINOS is the default solver. If SolverLP is a SOL solver (MINOS, SNOPT or NPSOL), the SOL.optPar and SOL.PrintFile is used: See help minosTL.m, npsolTL.m or snoptTL.m for how to set these parameters.
|-valign="top"
|''RandState''||See help rngset for how to initialize the random generator. Default is RandState = -1 If Convex == 0 and globalSolver == 'multiMin', RandState is sent to multiMin to initizalize the random generator.
|-valign="top"
|''xInit''||Parameter sent to the solver multiMin which is used to solve relaxed sub-problems for nonconvex problems (with Prob.Convex set to false). xInit determines the way initial points are generated and is set as follows: 
 
Either 
1x1 number - 
If > 0, the number of random initial points, default min(3000,30*n); 
If < 0, generate |xInit| points with Latin Hypercube design 
 
d x m matrix - Every column is an initial point (of length d = Prob.N) 
 
Default value for xInit is min(3000,max(60,N*6)) at all nodes except the root node 
|-valign="top"
|''xInit0''||Parameter sent to the solver multiMin when solving the initial relaxed NLP problem at the root node. 
Default value for xInit0 is min(3000,max(100,N*10)) 
See xInit for more information. 
|-valign="top"
|''MIP''||Structure defining integer optimization parameters. See the table below for a description of each field used in ''Prob.MIP''.
|-valign="top"
|''STOAMINLP''||Structure with solver-specific options. See the table below with descriptions of the fields used in ''Prob.STOAMINLP''.
|-valign="top"
|''optParam''||Structure with general optimization parameters. See the table below with descriptions of the fields used in ''Prob.optParam''.
|}

===MIP structure===

Substructure in Prob with parameters related to mixed integer programming.

{|class="wikitable"
!colspan="2"|fields used in '''Prob.MIP'''
|-
|'''Field'''||'''Description'''
|-valign="top"
|''IntVars''||If empty, all variables are assumed non-integer. If islogical(IntVars) (=all elements are 0/1), then 1 = integer variable, 0 = continuous variable. If any element ''>''1, IntVars is the indices for integer variables.
|-valign="top"
|''VarWeight''||Weight for each variable in the variable selection phase. A lower value gives higher priority. Setting Prob.MIP.VarWeight might improve convergence. 
VarWeight must be of length N, but the values corresponding to noninteger variables will be ignored.
|-valign="top"
|''DualGap''||''stoaMINLP ''stops if the duality gap is less than DualGap. DualGap = 1, stop at first integer solution e.g. DualGap = 0.01, stop if solution ''< ''1% from optimal solution. Note that a finite lower bound will only be set by the solver and thus generating a gap when Prob.Convex is set to true. If Prob.Convex is set to false, the lower bound will be -Inf.
|-valign="top"
|''fIP''||An upper bound on the IP value wanted. Makes it possible to cut branches and avoid node computations. Used even if xIP not given.
|-valign="top"
|''xIP''||The x-values giving the fIP value, if a solution (xIP,fIP) is known.
|-valign="top"
|''NodeSel''||Node selection method: = 1 Depth First. Priority on nodes with more integer components. Default = 2 Breadth First. Priority on nodes with more integer components. = 3 Pure LIFO (Last in, first out) Depth First. = 4 Pure FIFO (First in, first out) Breadth First. = 5 Maximize integer components. = 6 Best bound. = 7 Best estimate using pseudo-costs. = 8 Best projection.
|-valign="top"
|''Backtrack''||Switch node selection method during branch and bound. 
When set to any of the NodeSel methods, node selection method is changed to the Backtrack value when the backtracking criterion (see parameter BackCrit below) is fulfilled. For available choices, see NodeSel above. Default is 2, Breadth First.
|-valign="top"
|''BackCrit''||Backtracking criterion, used when Backtrack > 0. 
= 0. Integer solution found. Default. 
= 1. Current node worse than best estimate of active nodes.
|-valign="top"
|''VarSel''||Variable selection method in branch and bound. = 1 Use variable with most fractional value. = 2 Use gradient and distance to nearest integer value. = 3 Pseudo-cost-based branching.
|-valign="top"
|''KNAPSACK''||If = 1, use a knapsack heuristic. Default 0.
|-valign="top"
|''ROUNDH''||If = 1, use a rounding heuristic. Default 0.
|-valign="top"
|''SaveFreq''||Warm start info saved on stoaMINLPSave.mat every SaveFreq iteration (default -1, i.e. no warm start info is saved)
|}

===STOAMINLP structure===

Substructure in Prob with solver-specific options

{|class="wikitable"
!colspan="2"|fields used in Prob.STOAMINLP
|-
|'''Field'''||'''Description'''
|-valign="top"
|''USECUTS''||Flag to use cutting plane algorithm described in [[StoaMINLP#Algorithm]]. Using cuts is not recommended for nonconvex problems. Set nonzero to enable, zero to disable. By default, USECUTS = Prob.Convex.
|-valign="top"
|''B_ecp''||Parameter regulating likelihood of linearization using extended cutting plane. See [[StoaMINLP#Algorithm]] for more information. Default 10.
|-valign="top"
|''K_ecp''||Parameter regulating "tailing off" detection for extended cutting plane linearizations. See [[StoaMINLP#Algorithm]] for more information. Default 0.001.
|-valign="top"
|''M_ecp''||Parameter regulating the balance between branching the search tree and adding linearizations using extended cutting plane. See [[StoaMINLP#Algorithm]] for more information. Default 10.
|-valign="top"
|''B_ff''||Parameter regulating likelihood of linearization using fixed fractional integer decision variables. See [[StoaMINLP#Algorithm]] for more information. Default 10.
|-valign="top"
|''K_ff''||Parameter regulating "tailing off" detection for linearizations using fixed fractional integer decision variables. See [[StoaMINLP#Algorithm]] for more information. Default 0.001.
|-valign="top"
|''M_ff''||Parameter regulating the balance between branching the search tree and adding linearizations using fixed fractional integer decision variables. See [[StoaMINLP#Algorithm]] for more information. Default 10.
|-valign="top"
|''B_nlpr''||Parameter regulating likelihood of linearization using the solution of the relaxed NLP problem. See [[StoaMINLP#Algorithm]] for more information. Default 10.
|-valign="top"
|''K_nlpr''||Parameter regulating "tailing off" detection for linearizations using the solution of the relaxed NLP problem. See [[StoaMINLP#Algorithm]] for more information. Default 0.001.
|-valign="top"
|''M_nlpr''||Parameter regulating the balance between branching the search tree and adding linearizations using the solution of the relaxed NLP problem. See [[StoaMINLP#Algorithm]] for more information. Default 10.
|-valign="top"
|''rTYPE''||= 0 r is fixed to the value in rVALUE. = 1 r is a uniformly distributed random number in the interval [0,1]. Default.
|-valign="top"
|''rVALUE''||Defines the value of r when rTYPE is set to zero. Default is 0.5.
|-valign="top"
|''CUTPOOL''||= 0 All linearizations constraints are kept in the master problem. = 1 Manage a pool with inactive linearization constraints. If an inactive constraint gets violated, it is brought back from the pool. Default.
|-valign="top"
|''CUTDELBND''||The number of consecutive times a linearization can be inactive before it gets removed and put into the inactive pool. Default 15.
|-valign="top"
|''CUTLIMDEL''||= 0 No extra deletion of cuts. Default when Prob.Convex == 1. = 1 Delete any cuts limiting the true feasible region when detected. Such cuts will appear if the problem has nonlinear constraints. Default when Prob.Convex == 0.
|-valign="top"
|''PCITL''||Limit on time spent per node calculating initial pseudo costs when VarSel == 3. Default is 120 (s).
|-valign="top"
|''LINPRINT''||Set nonzero to print short information about the type of linearization added. Default 0. enabled when IterPrint > 3.
|-valign="top"
|''POOLPRINT''||Set nonzero to print information about the cutpool management. Default 0. Enabled when IterPrint > 4.
|}

===optParam structure===

Substructure in Prob with general optimization parameters.

{|class="wikitable"
!colspan="2"|fields used in Prob.optParam:
|-
|'''Field'''||'''Description'''
|-valign="top"
|''MaxIter''||Maximal number of iterations, default 10000
|-valign="top"
|''IterPrint''||Print short information each iteration. Setting PriLev > 1 also enables IterPrint, setting it to 1. 
The information printed for different levels is as follows: 

>0 A line at each evaluated node with the following: 
Iteration number: 
Depth in tree (symbol L[] - empty list, symbol Gap - Dual Gap convergence), fNLP (Optimal f(x) current node), fIPMin (Best integer feasible f(x) found), LowBnd (Lower bound on optimal integer feasible f(x)), Dual Gap in absolut value and percent, The length of the node list L, -L-, The Inform and ExitFlag the solver returned at the current node, FuEv (Number of function evaluations used by solver at current node), date/time stamp. Outer approximation linearizations, number of cuts in active/inactive pool (|C| #A #I). 

> 1 A line at each evaluated node with the information described above. 
Moreover, with IterPrint enabled a notice is printed whenever the algorithm switches node selection methods. 
Setting a higher value of IterPrint gives more detailed information. 

>2 Depth, number of integer components and lower bound on objective for each node in L. 
>3 Sets LINPRINT = 1, print info about linearizations added (if used). 
>4 Sets POOLPRINT = 1, print info about cut-pool management (if used).
|-valign="top"
|''bTol''||Linear constraint violation convergence tolerance.
|-valign="top"
|''cTol''||Constraint violation convergence tolerance.
|-valign="top"
|''fTol''||Optimality tolerance.
|}

==Outputs==

{| class="wikitable"
!''Result''||colspan="2"|Structure with result from optimization. The following fields are changed:
|-
|||''Iter ''||Number of iterations.
|-valign="top"
|||''ExitFlag ''||Exit flag. 0: Global optimal solution found, or integer solution with duality gap less than user tolerance. 1: Maximal number of iterations reached. 2: Empty feasible set, no integer solution found. 4: No feasible point found running NLP relaxation. 5: Illegal x_0 found in NLP relaxation. 99: Maximal CPU Time used (cputime ''> ''Prob.MaxCPU).
|-
|||''Inform''||Code telling type of convergence, returned from subsolver.
|-
|||''ExitText''||Text string giving ''ExitFlag'' and ''Inform'' information.
|-valign="top"
|||''DualGap''||Relative duality gap, max(0,fIPMin-fLB)/-fIPMin-, if fIPMin =0; max(0,fIPMin-fLB) if fIPMin == 0. If fIPMin =0: Scale with 100, 100*Dual- Gap, to get the percentage duality gap. For absolute value duality gap: scale with fIPMin, fIPMin * DualGap
|-
|||''x_k''||Solution.
|-valign="top"
|||''v_k''||Lagrange multipliers. Bounds, Linear and Nonlinear Constraints, size n + mLin + mNonLin.
|-
|||''f_k''||Function value at optimum.
|-
|||''g_k''||Gradient vector at optimum.
|-
|||''x_0''||Starting point x_0.
|-
|||''f_0''||Function value at start.
|-
|||''c_k''||Constraint values at optimum.
|-
|||''cJac''||Constraint derivative values at optimum.
|-
|||''xState''||State of each variable, described in [[TOMLAB_Appendix_B#Table:_The_state_variable_xState_for_the_variable.|TOMLAB Appendix B]].
|-
|||''bState''||State of each constraint, described in [[TOMLAB_Appendix_B#Table:_The_state_variable_bState_for_each_linear_constraint.|TOMLAB Appendix B]].
|-
|||''cState''||State of each general constraint, described in [[TOMLAB_Appendix_B#Table:_The_state_variable_cState_for_each_nonlinear_constraint.|TOMLAB Appendix B]].
|-
|||''Solver''||Solver used ('stoaMINLP').
|-
|||''SolverAlgorithm''||Description of method used.
|-
|||''Prob''||Problem structure used.
|-valign="top"
|||''stoaMINLP''||A structure with warm start information. Use with WarmDefGLOBAL, see example [[StoaMINLP#Warm_Start|here]].
|}

[[Category:MIPNLP]]

MIPNLP stoaMINLP

2015-02-11T15:38:53Z

Bjorn: /* MIP structure */

{{Part Of Manual|title=the MIPNLP Manual|link=[[MIPNLP|MIPNLP Manual]]}}
==Purpose==

stoaMINLP solves convex mixed-integer nonlinear programming problems (MINLP).

''stoaMINLP ''solves problems of the form

<math>
\begin{array}{cccccc}
\min\limits_{x} & f(x) \\s/t & x_{L} & \leq & x & \leq & x_{U} \\& b_{L} & \leq & Ax & \leq & b_{U} \\& c_{L} & \leq & c(x) & \leq & c_{U} \\& & & {x_{j} \in \mathbb{N} \ \ \forall j \in I} \\
\end{array}
</math>

where <math>x,x_{L},x_{U}\in \mathbb{R}^{n}</math> , <math>c(x),c_{L},c_{U}\in
\mathbb{R}^{m_{1}}</math> , <math>A\in \mathbb{R}^{m_{2}\times n}</math> and
<math>b_{L},b_{U}\in \mathbb{R}^{m_{2}}</math>. The variables <math>x \in I</math> , the
index subset of <math>1,...,n</math> are restricted to be integers.

==Calling Syntax==

Recommended is to first set IterPrint, to get information each iteration
<source lang="matlab">
Prob.optParam.IterPrint = 1;
</source>
Driver call, including printing with level 2:
<source lang="matlab">
Result = tomRun('stoaMINLP',Prob,2);
</source>
Direct solver call:
<source lang="matlab">
Result = stoaMINLP(Prob);
PrintResult(Result);
Result = tomRun('stoaMINLP',Prob,...)
</source>

=== Warm Start ===
To make a restart (warm start), just set the warm start flag, and call stoaMINLP once again:

<source lang="matlab">
Prob.WarmStart = 1;
Result = tomRun('stoaMINLP', Prob, 2);
</source>

stoaMINLP will read warm start information from the stoaMINLPSave.mat file. Another warm start (with same MaxFunc) is made by just calling tomRun again:

<source lang="matlab">
Result = tomRun('stoaMINLP', Prob, 2);
</source>

To make a restart from the warm start information in the Result structure, make a call to WarmDefGLOBAL before calling stoaMINLP. WarmDefGLOBAL moves information from the Result structure to the Prob structure and sets the warm start flag, <code>Prob.WarmStart = 1;</code>

<source lang="matlab">
Prob = WarmDefGLOBAL('stoaMINLP', Prob, Result);
</source>

where Result is the result structure returned by the previous run. A warm start (with same MaxIter) is done by just calling tomRun again:

<source lang="matlab">
Result = tomRun('stoaMINLP', Prob, 2);
</source>

To make another warm start with new MaxIter 100, say, redefine MaxIter as:

<source lang="matlab">
Prob.optParam.MaxIter = 100;
</source>

Then repeat the two lines:

<source lang="matlab">
Prob = WarmDefGLOBAL('stoaMINLP', Prob, Result);
Result = tomRun('stoaMINLP', Prob, 2);
</source>

==Inputs==

===Prob structure===
The '''TOMLAB''' problem structure

{| class="wikitable"
!colspan="2"|The following fields are used in ''Prob'':
|-
|'''Field'''||'''Description'''
|-
|''x_L''||Lower bounds on x.
|-
|''x_U''||Upper bounds on x.
|-
|''A''||The linear constraint matrix.
|-
|''b_L''||Lower bounds on linear constraints.
|-
|''b_U''||Upper bounds on linear constraints.
|-
|''c_L''||Lower bounds on nonlinear constraints.
|-
|''c_U''||Upper bounds on nonlinear constraints.
|-
|''x_0''||Starting point.
|-valign="top"
|''Convex''||If Convex==1, assume NLP problems are convex, and only one local NLP solver call is used at each node. If Convex==0 (Default), multiMin is used to do many calls to a local solver to determine the global minima at each node. The global minimum with most components integer valued is chosen.
|-valign="top"
|''MaxCPU''||Maximal CPU Time (in seconds) to be used by stoaMINLP, stops with best point found
|-valign="top"
|''PriLev''||Print level in stoaMINLP (default 1). Also see optParam.IterPrint
|-valign="top"
|''PriLevOpt''||Print level in sub-solvers (SNOPT and other NLP solvers): =0 No output; ''>''0 Convergence results. ''>''1 Output every iteration, ''>''2 Output each step in the NLP alg For other NLP solvers, see the documentation for the solver
|-valign="top"
|''WarmStart''||If true, ''>''0, stoaMINLP reads the output from the last run from Prob.stoaMINLP, if it exists. If it doesn't exist, stoaMINLP attempts to open and read warm start data from mat-file stoaMINLPSave.mat. stoaMINLP uses the warm start information to continue from the last run. The mat-file minlp- SolveSave.mat is saved every Prob.MIP.SaveFreq iteration.
|-valign="top"
|''SolverNLP''||Name of the solver used for NLP subproblems. If empty, the default solver is found calling GetSolver('con',1); If TOMLAB /SOL installed, SNOPT is the default solver. If SolverNLP is a SOL solver (SNOPT, MINOS or NPSOL), the SOL.optPar and SOL.PrintFile is used: See help minosTL.m, npsolTL.m or snoptTL.m for how to set these parameters
|-
|''SolverNLP0''||Name of the solver used for the initial NLP-problem. If empty, SolverNLP is used.
|-valign="top"
|''SolverLP''||Name of the solver used for LP subproblems. If empty, the default solver is found calling GetSolver('lp',1). If TOMLAB /SOL or /SNOPT or /NPSOL installed, MINOS is the default solver. If SolverLP is a SOL solver (MINOS, SNOPT or NPSOL), the SOL.optPar and SOL.PrintFile is used: See help minosTL.m, npsolTL.m or snoptTL.m for how to set these parameters.
|-valign="top"
|''RandState''||If Convex == 0, RandState is sent to multiMin to initialize the random generator. RandState is used as follows: If ''> ''0, rand('state',RandState) is set to initialize the pseudo-random generator. If ''< ''0, rand('state',sum(100*clock)) is set to give a new set of random values each run. If RandState == 0, rand('state',) is not called. Default is RandState = -1
|-valign="top"
|''xInit''||Parameter sent to the solver multiMin which is used to solve relaxed sub-problems for nonconvex problems (with Prob.Convex set to false). xInit determines the way initial points are generated and is set as follows: 
 
Either 
1x1 number - 
If > 0, the number of random initial points, default min(3000,30*n); 
If < 0, generate |xInit| points with Latin Hypercube design 
 
d x m matrix - Every column is an initial point (of length d = Prob.N) 
 
Default value for xInit is min(3000,max(60,N*6)) at all nodes except the root node 
|-valign="top"
|''xInit0''||Parameter sent to the solver multiMin when solving the initial relaxed NLP problem at the root node. 
Default value for xInit0 is min(3000,max(100,N*10)) 
See xInit for more information. 
|-valign="top"
|''MIP''||Structure defining integer optimization parameters. See the table below for a description of each field used in ''Prob.MIP''.
|-valign="top"
|''STOAMINLP''||Structure with solver-specific options. See the table below with descriptions of the fields used in ''Prob.STOAMINLP''.
|-valign="top"
|''optParam''||Structure with general optimization parameters. See the table below with descriptions of the fields used in ''Prob.optParam''.
|}

===MIP structure===

Substructure in Prob with parameters related to mixed integer programming.

{|class="wikitable"
!colspan="2"|fields used in '''Prob.MIP'''
|-
|'''Field'''||'''Description'''
|-valign="top"
|''IntVars''||If empty, all variables are assumed non-integer. If islogical(IntVars) (=all elements are 0/1), then 1 = integer variable, 0 = continuous variable. If any element ''>''1, IntVars is the indices for integer variables.
|-valign="top"
|''VarWeight''||Weight for each variable in the variable selection phase. A lower value gives higher priority. Setting Prob.MIP.VarWeight might improve convergence. 
VarWeight must be of length N, but the values corresponding to noninteger variables will be ignored.
|-valign="top"
|''DualGap''||''stoaMINLP ''stops if the duality gap is less than DualGap. DualGap = 1, stop at first integer solution e.g. DualGap = 0.01, stop if solution ''< ''1% from optimal solution. Note that a finite lower bound will only be set by the solver and thus generating a gap when Prob.Convex is set to true. If Prob.Convex is set to false, the lower bound will be -Inf.
|-valign="top"
|''fIP''||An upper bound on the IP value wanted. Makes it possible to cut branches and avoid node computations. Used even if xIP not given.
|-valign="top"
|''xIP''||The x-values giving the fIP value, if a solution (xIP,fIP) is known.
|-valign="top"
|''NodeSel''||Node selection method: = 1 Depth First. Priority on nodes with more integer components. Default = 2 Breadth First. Priority on nodes with more integer components. = 3 Pure LIFO (Last in, first out) Depth First. = 4 Pure FIFO (First in, first out) Breadth First. = 5 Maximize integer components. = 6 Best bound. = 7 Best estimate using pseudo-costs. = 8 Best projection.
|-valign="top"
|''Backtrack''||Switch node selection method during branch and bound. 
When set to any of the NodeSel methods, node selection method is changed to the Backtrack value when the backtracking criterion (see parameter BackCrit below) is fulfilled. For available choices, see NodeSel above. Default is 2, Breadth First.
|-valign="top"
|''BackCrit''||Backtracking criterion, used when Backtrack > 0. 
= 0. Integer solution found. Default. 
= 1. Current node worse than best estimate of active nodes.
|-valign="top"
|''VarSel''||Variable selection method in branch and bound. = 1 Use variable with most fractional value. = 2 Use gradient and distance to nearest integer value. = 3 Pseudo-cost-based branching.
|-valign="top"
|''KNAPSACK''||If = 1, use a knapsack heuristic. Default 0.
|-valign="top"
|''ROUNDH''||If = 1, use a rounding heuristic. Default 0.
|-valign="top"
|''SaveFreq''||Warm start info saved on stoaMINLPSave.mat every SaveFreq iteration (default -1, i.e. no warm start info is saved)
|}

===STOAMINLP structure===

Substructure in Prob with solver-specific options

{|class="wikitable"
!colspan="2"|fields used in Prob.STOAMINLP
|-
|'''Field'''||'''Description'''
|-valign="top"
|''USECUTS''||Flag to use cutting plane algorithm described in [[StoaMINLP#Algorithm]]. Using cuts is not recommended for nonconvex problems. Set nonzero to enable, zero to disable. By default, USECUTS = Prob.Convex.
|-valign="top"
|''B_ecp''||Parameter regulating likelihood of linearization using extended cutting plane. See [[StoaMINLP#Algorithm]] for more information. Default 10.
|-valign="top"
|''K_ecp''||Parameter regulating "tailing off" detection for extended cutting plane linearizations. See [[StoaMINLP#Algorithm]] for more information. Default 0.001.
|-valign="top"
|''M_ecp''||Parameter regulating the balance between branching the search tree and adding linearizations using extended cutting plane. See [[StoaMINLP#Algorithm]] for more information. Default 10.
|-valign="top"
|''B_ff''||Parameter regulating likelihood of linearization using fixed fractional integer decision variables. See [[StoaMINLP#Algorithm]] for more information. Default 10.
|-valign="top"
|''K_ff''||Parameter regulating "tailing off" detection for linearizations using fixed fractional integer decision variables. See [[StoaMINLP#Algorithm]] for more information. Default 0.001.
|-valign="top"
|''M_ff''||Parameter regulating the balance between branching the search tree and adding linearizations using fixed fractional integer decision variables. See [[StoaMINLP#Algorithm]] for more information. Default 10.
|-valign="top"
|''B_nlpr''||Parameter regulating likelihood of linearization using the solution of the relaxed NLP problem. See [[StoaMINLP#Algorithm]] for more information. Default 10.
|-valign="top"
|''K_nlpr''||Parameter regulating "tailing off" detection for linearizations using the solution of the relaxed NLP problem. See [[StoaMINLP#Algorithm]] for more information. Default 0.001.
|-valign="top"
|''M_nlpr''||Parameter regulating the balance between branching the search tree and adding linearizations using the solution of the relaxed NLP problem. See [[StoaMINLP#Algorithm]] for more information. Default 10.
|-valign="top"
|''rTYPE''||= 0 r is fixed to the value in rVALUE. = 1 r is a uniformly distributed random number in the interval [0,1]. Default.
|-valign="top"
|''rVALUE''||Defines the value of r when rTYPE is set to zero. Default is 0.5.
|-valign="top"
|''CUTPOOL''||= 0 All linearizations constraints are kept in the master problem. = 1 Manage a pool with inactive linearization constraints. If an inactive constraint gets violated, it is brought back from the pool. Default.
|-valign="top"
|''CUTDELBND''||The number of consecutive times a linearization can be inactive before it gets removed and put into the inactive pool. Default 15.
|-valign="top"
|''CUTLIMDEL''||= 0 No extra deletion of cuts. Default when Prob.Convex == 1. = 1 Delete any cuts limiting the true feasible region when detected. Such cuts will appear if the problem has nonlinear constraints. Default when Prob.Convex == 0.
|-valign="top"
|''PCITL''||Limit on time spent per node calculating initial pseudo costs when VarSel == 3. Default is 120 (s).
|-valign="top"
|''LINPRINT''||Set nonzero to print short information about the type of linearization added. Default 0. enabled when IterPrint > 3.
|-valign="top"
|''POOLPRINT''||Set nonzero to print information about the cutpool management. Default 0. Enabled when IterPrint > 4.
|}

===optParam structure===

Substructure in Prob with general optimization parameters.

{|class="wikitable"
!colspan="2"|fields used in Prob.optParam:
|-
|'''Field'''||'''Description'''
|-valign="top"
|''MaxIter''||Maximal number of iterations, default 10000
|-valign="top"
|''IterPrint''||Print short information each iteration. Setting PriLev > 1 also enables IterPrint, setting it to 1. 
The information printed for different levels is as follows: 

>0 A line at each evaluated node with the following: 
Iteration number: 
Depth in tree (symbol L[] - empty list, symbol Gap - Dual Gap convergence), fNLP (Optimal f(x) current node), fIPMin (Best integer feasible f(x) found), LowBnd (Lower bound on optimal integer feasible f(x)), Dual Gap in absolut value and percent, The length of the node list L, -L-, The Inform and ExitFlag the solver returned at the current node, FuEv (Number of function evaluations used by solver at current node), date/time stamp. Outer approximation linearizations, number of cuts in active/inactive pool (|C| #A #I). 

> 1 A line at each evaluated node with the information described above. 
Moreover, with IterPrint enabled a notice is printed whenever the algorithm switches node selection methods. 
Setting a higher value of IterPrint gives more detailed information. 

>2 Depth, number of integer components and lower bound on objective for each node in L. 
>3 Sets LINPRINT = 1, print info about linearizations added (if used). 
>4 Sets POOLPRINT = 1, print info about cut-pool management (if used).
|-valign="top"
|''bTol''||Linear constraint violation convergence tolerance.
|-valign="top"
|''cTol''||Constraint violation convergence tolerance.
|-valign="top"
|''fTol''||Optimality tolerance.
|}

==Outputs==

{| class="wikitable"
!''Result''||colspan="2"|Structure with result from optimization. The following fields are changed:
|-
|||''Iter ''||Number of iterations.
|-valign="top"
|||''ExitFlag ''||Exit flag. 0: Global optimal solution found, or integer solution with duality gap less than user tolerance. 1: Maximal number of iterations reached. 2: Empty feasible set, no integer solution found. 4: No feasible point found running NLP relaxation. 5: Illegal x_0 found in NLP relaxation. 99: Maximal CPU Time used (cputime ''> ''Prob.MaxCPU).
|-
|||''Inform''||Code telling type of convergence, returned from subsolver.
|-
|||''ExitText''||Text string giving ''ExitFlag'' and ''Inform'' information.
|-valign="top"
|||''DualGap''||Relative duality gap, max(0,fIPMin-fLB)/-fIPMin-, if fIPMin =0; max(0,fIPMin-fLB) if fIPMin == 0. If fIPMin =0: Scale with 100, 100*Dual- Gap, to get the percentage duality gap. For absolute value duality gap: scale with fIPMin, fIPMin * DualGap
|-
|||''x_k''||Solution.
|-valign="top"
|||''v_k''||Lagrange multipliers. Bounds, Linear and Nonlinear Constraints, size n + mLin + mNonLin.
|-
|||''f_k''||Function value at optimum.
|-
|||''g_k''||Gradient vector at optimum.
|-
|||''x_0''||Starting point x_0.
|-
|||''f_0''||Function value at start.
|-
|||''c_k''||Constraint values at optimum.
|-
|||''cJac''||Constraint derivative values at optimum.
|-
|||''xState''||State of each variable, described in [[TOMLAB_Appendix_B#Table:_The_state_variable_xState_for_the_variable.|TOMLAB Appendix B]].
|-
|||''bState''||State of each constraint, described in [[TOMLAB_Appendix_B#Table:_The_state_variable_bState_for_each_linear_constraint.|TOMLAB Appendix B]].
|-
|||''cState''||State of each general constraint, described in [[TOMLAB_Appendix_B#Table:_The_state_variable_cState_for_each_nonlinear_constraint.|TOMLAB Appendix B]].
|-
|||''Solver''||Solver used ('stoaMINLP').
|-
|||''SolverAlgorithm''||Description of method used.
|-
|||''Prob''||Problem structure used.
|-valign="top"
|||''stoaMINLP''||A structure with warm start information. Use with WarmDefGLOBAL, see example [[StoaMINLP#Warm_Start|here]].
|}

[[Category:MIPNLP]]

MIPNLP stoaMINLP

2015-02-11T15:31:00Z

Bjorn: /* Prob structure */

{{Part Of Manual|title=the MIPNLP Manual|link=[[MIPNLP|MIPNLP Manual]]}}
==Purpose==

stoaMINLP solves convex mixed-integer nonlinear programming problems (MINLP).

''stoaMINLP ''solves problems of the form

<math>
\begin{array}{cccccc}
\min\limits_{x} & f(x) \\s/t & x_{L} & \leq & x & \leq & x_{U} \\& b_{L} & \leq & Ax & \leq & b_{U} \\& c_{L} & \leq & c(x) & \leq & c_{U} \\& & & {x_{j} \in \mathbb{N} \ \ \forall j \in I} \\
\end{array}
</math>

where <math>x,x_{L},x_{U}\in \mathbb{R}^{n}</math> , <math>c(x),c_{L},c_{U}\in
\mathbb{R}^{m_{1}}</math> , <math>A\in \mathbb{R}^{m_{2}\times n}</math> and
<math>b_{L},b_{U}\in \mathbb{R}^{m_{2}}</math>. The variables <math>x \in I</math> , the
index subset of <math>1,...,n</math> are restricted to be integers.

==Calling Syntax==

Recommended is to first set IterPrint, to get information each iteration
<source lang="matlab">
Prob.optParam.IterPrint = 1;
</source>
Driver call, including printing with level 2:
<source lang="matlab">
Result = tomRun('stoaMINLP',Prob,2);
</source>
Direct solver call:
<source lang="matlab">
Result = stoaMINLP(Prob);
PrintResult(Result);
Result = tomRun('stoaMINLP',Prob,...)
</source>

=== Warm Start ===
To make a restart (warm start), just set the warm start flag, and call stoaMINLP once again:

<source lang="matlab">
Prob.WarmStart = 1;
Result = tomRun('stoaMINLP', Prob, 2);
</source>

stoaMINLP will read warm start information from the stoaMINLPSave.mat file. Another warm start (with same MaxFunc) is made by just calling tomRun again:

<source lang="matlab">
Result = tomRun('stoaMINLP', Prob, 2);
</source>

To make a restart from the warm start information in the Result structure, make a call to WarmDefGLOBAL before calling stoaMINLP. WarmDefGLOBAL moves information from the Result structure to the Prob structure and sets the warm start flag, <code>Prob.WarmStart = 1;</code>

<source lang="matlab">
Prob = WarmDefGLOBAL('stoaMINLP', Prob, Result);
</source>

where Result is the result structure returned by the previous run. A warm start (with same MaxIter) is done by just calling tomRun again:

<source lang="matlab">
Result = tomRun('stoaMINLP', Prob, 2);
</source>

To make another warm start with new MaxIter 100, say, redefine MaxIter as:

<source lang="matlab">
Prob.optParam.MaxIter = 100;
</source>

Then repeat the two lines:

<source lang="matlab">
Prob = WarmDefGLOBAL('stoaMINLP', Prob, Result);
Result = tomRun('stoaMINLP', Prob, 2);
</source>

==Inputs==

===Prob structure===
The '''TOMLAB''' problem structure

{| class="wikitable"
!colspan="2"|The following fields are used in ''Prob'':
|-
|'''Field'''||'''Description'''
|-
|''x_L''||Lower bounds on x.
|-
|''x_U''||Upper bounds on x.
|-
|''A''||The linear constraint matrix.
|-
|''b_L''||Lower bounds on linear constraints.
|-
|''b_U''||Upper bounds on linear constraints.
|-
|''c_L''||Lower bounds on nonlinear constraints.
|-
|''c_U''||Upper bounds on nonlinear constraints.
|-
|''x_0''||Starting point.
|-valign="top"
|''Convex''||If Convex==1, assume NLP problems are convex, and only one local NLP solver call is used at each node. If Convex==0 (Default), multiMin is used to do many calls to a local solver to determine the global minima at each node. The global minimum with most components integer valued is chosen.
|-valign="top"
|''MaxCPU''||Maximal CPU Time (in seconds) to be used by stoaMINLP, stops with best point found
|-valign="top"
|''PriLev''||Print level in stoaMINLP (default 1). Also see optParam.IterPrint
|-valign="top"
|''PriLevOpt''||Print level in sub-solvers (SNOPT and other NLP solvers): =0 No output; ''>''0 Convergence results. ''>''1 Output every iteration, ''>''2 Output each step in the NLP alg For other NLP solvers, see the documentation for the solver
|-valign="top"
|''WarmStart''||If true, ''>''0, stoaMINLP reads the output from the last run from Prob.stoaMINLP, if it exists. If it doesn't exist, stoaMINLP attempts to open and read warm start data from mat-file stoaMINLPSave.mat. stoaMINLP uses the warm start information to continue from the last run. The mat-file minlp- SolveSave.mat is saved every Prob.MIP.SaveFreq iteration.
|-valign="top"
|''SolverNLP''||Name of the solver used for NLP subproblems. If empty, the default solver is found calling GetSolver('con',1); If TOMLAB /SOL installed, SNOPT is the default solver. If SolverNLP is a SOL solver (SNOPT, MINOS or NPSOL), the SOL.optPar and SOL.PrintFile is used: See help minosTL.m, npsolTL.m or snoptTL.m for how to set these parameters
|-
|''SolverNLP0''||Name of the solver used for the initial NLP-problem. If empty, SolverNLP is used.
|-valign="top"
|''SolverLP''||Name of the solver used for LP subproblems. If empty, the default solver is found calling GetSolver('lp',1). If TOMLAB /SOL or /SNOPT or /NPSOL installed, MINOS is the default solver. If SolverLP is a SOL solver (MINOS, SNOPT or NPSOL), the SOL.optPar and SOL.PrintFile is used: See help minosTL.m, npsolTL.m or snoptTL.m for how to set these parameters.
|-valign="top"
|''RandState''||If Convex == 0, RandState is sent to multiMin to initialize the random generator. RandState is used as follows: If ''> ''0, rand('state',RandState) is set to initialize the pseudo-random generator. If ''< ''0, rand('state',sum(100*clock)) is set to give a new set of random values each run. If RandState == 0, rand('state',) is not called. Default is RandState = -1
|-valign="top"
|''xInit''||Parameter sent to the solver multiMin which is used to solve relaxed sub-problems for nonconvex problems (with Prob.Convex set to false). xInit determines the way initial points are generated and is set as follows: 
 
Either 
1x1 number - 
If > 0, the number of random initial points, default min(3000,30*n); 
If < 0, generate |xInit| points with Latin Hypercube design 
 
d x m matrix - Every column is an initial point (of length d = Prob.N) 
 
Default value for xInit is min(3000,max(60,N*6)) at all nodes except the root node 
|-valign="top"
|''xInit0''||Parameter sent to the solver multiMin when solving the initial relaxed NLP problem at the root node. 
Default value for xInit0 is min(3000,max(100,N*10)) 
See xInit for more information. 
|-valign="top"
|''MIP''||Structure defining integer optimization parameters. See the table below for a description of each field used in ''Prob.MIP''.
|-valign="top"
|''STOAMINLP''||Structure with solver-specific options. See the table below with descriptions of the fields used in ''Prob.STOAMINLP''.
|-valign="top"
|''optParam''||Structure with general optimization parameters. See the table below with descriptions of the fields used in ''Prob.optParam''.
|}

===MIP structure===

Substructure in Prob with parameters related to mixed integer programming.

{|class="wikitable"
!colspan="2"|fields used in '''Prob.MIP'''
|-
|'''Field'''||'''Description'''
|-valign="top"
|''IntVars''||If empty, all variables are assumed non-integer. If islogical(IntVars) (=all elements are 0/1), then 1 = integer variable, 0 = continuous variable. If any element ''>''1, IntVars is the indices for integer variables.
|-valign="top"
|''VarWeight''||Weight for each variable in the variable selection phase. A lower value gives higher priority. Setting Prob.MIP.VarWeight might improve convergence.
|-valign="top"
|''DualGap''||''stoaMINLP ''stops if the duality gap is less than DualGap. DualGap = 1, stop at first integer solution e.g. DualGap = 0.01, stop if solution ''< ''1% from optimal solution.
|-valign="top"
|''fIP''||An upper bound on the IP value wanted. Makes it possible to cut branches and avoid node computations. Used even if xIP not given.
|-valign="top"
|''xIP''||The x-values giving the fIP value, if a solution (xIP,fIP) is known.
|-valign="top"
|''NodeSel''||Node selection method: = 1 Depth First. Priority on nodes with more integer components. Default = 2 Breadth First. Priority on nodes with more integer components. = 3 Pure LIFO (Last in, first out) Depth First. = 4 Pure FIFO (First in, first out) Breadth First. = 5 Maximize integer components. = 6 Best bound. = 7 Best estimate using pseudo-costs. = 8 Best projection.
|-valign="top"
|''Backtrack''||Node selection method to use after an integer solution has been found. Available choices are the same as for NodeSel. Default is 2, Breadth First.
|-valign="top"
|''VarSel''||Variable selection method in branch and bound. = 1 Use variable with most fractional value. = 2 Use gradient and distance to nearest integer value. = 3 Pseudo-cost-based branching.
|-valign="top"
|''KNAPSACK''||If = 1, use a knapsack heuristic. Default 0.
|-valign="top"
|''ROUNDH''||If = 1, use a rounding heuristic. Default 0.
|-valign="top"
|''SaveFreq''||Warm start info saved on stoaMINLPSave.mat every SaveFreq iteration (default -1, i.e. no warm start info is saved)
|}

===STOAMINLP structure===

Substructure in Prob with solver-specific options

{|class="wikitable"
!colspan="2"|fields used in Prob.STOAMINLP
|-
|'''Field'''||'''Description'''
|-valign="top"
|''USECUTS''||Flag to use cutting plane algorithm described in [[StoaMINLP#Algorithm]]. Using cuts is not recommended for nonconvex problems. Set nonzero to enable, zero to disable. By default, USECUTS = Prob.Convex.
|-valign="top"
|''B_ecp''||Parameter regulating likelihood of linearization using extended cutting plane. See [[StoaMINLP#Algorithm]] for more information. Default 10.
|-valign="top"
|''K_ecp''||Parameter regulating "tailing off" detection for extended cutting plane linearizations. See [[StoaMINLP#Algorithm]] for more information. Default 0.001.
|-valign="top"
|''M_ecp''||Parameter regulating the balance between branching the search tree and adding linearizations using extended cutting plane. See [[StoaMINLP#Algorithm]] for more information. Default 10.
|-valign="top"
|''B_ff''||Parameter regulating likelihood of linearization using fixed fractional integer decision variables. See [[StoaMINLP#Algorithm]] for more information. Default 10.
|-valign="top"
|''K_ff''||Parameter regulating "tailing off" detection for linearizations using fixed fractional integer decision variables. See [[StoaMINLP#Algorithm]] for more information. Default 0.001.
|-valign="top"
|''M_ff''||Parameter regulating the balance between branching the search tree and adding linearizations using fixed fractional integer decision variables. See [[StoaMINLP#Algorithm]] for more information. Default 10.
|-valign="top"
|''B_nlpr''||Parameter regulating likelihood of linearization using the solution of the relaxed NLP problem. See [[StoaMINLP#Algorithm]] for more information. Default 10.
|-valign="top"
|''K_nlpr''||Parameter regulating "tailing off" detection for linearizations using the solution of the relaxed NLP problem. See [[StoaMINLP#Algorithm]] for more information. Default 0.001.
|-valign="top"
|''M_nlpr''||Parameter regulating the balance between branching the search tree and adding linearizations using the solution of the relaxed NLP problem. See [[StoaMINLP#Algorithm]] for more information. Default 10.
|-valign="top"
|''rTYPE''||= 0 r is fixed to the value in rVALUE. = 1 r is a uniformly distributed random number in the interval [0,1]. Default.
|-valign="top"
|''rVALUE''||Defines the value of r when rTYPE is set to zero. Default is 0.5.
|-valign="top"
|''CUTPOOL''||= 0 All linearizations constraints are kept in the master problem. = 1 Manage a pool with inactive linearization constraints. If an inactive constraint gets violated, it is brought back from the pool. Default.
|-valign="top"
|''CUTDELBND''||The number of consecutive times a linearization can be inactive before it gets removed and put into the inactive pool. Default 15.
|-valign="top"
|''CUTLIMDEL''||= 0 No extra deletion of cuts. Default when Prob.Convex == 1. = 1 Delete any cuts limiting the true feasible region when detected. Such cuts will appear if the problem has nonlinear constraints. Default when Prob.Convex == 0.
|-valign="top"
|''PCITL''||Limit on time spent per node calculating initial pseudo costs when VarSel == 3. Default is 120 (s).
|-valign="top"
|''LINPRINT''||Set nonzero to print short information about the type of linearization added. Default 0. enabled when IterPrint > 3.
|-valign="top"
|''POOLPRINT''||Set nonzero to print information about the cutpool management. Default 0. Enabled when IterPrint > 4.
|}

===optParam structure===

Substructure in Prob with general optimization parameters.

{|class="wikitable"
!colspan="2"|fields used in Prob.optParam:
|-
|'''Field'''||'''Description'''
|-valign="top"
|''MaxIter''||Maximal number of iterations, default 10000
|-valign="top"
|''IterPrint''||Print short information each iteration. Setting PriLev > 1 also enables IterPrint, setting it to 1. 
The information printed for different levels is as follows: 

>0 A line at each evaluated node with the following: 
Iteration number: 
Depth in tree (symbol L[] - empty list, symbol Gap - Dual Gap convergence), fNLP (Optimal f(x) current node), fIPMin (Best integer feasible f(x) found), LowBnd (Lower bound on optimal integer feasible f(x)), Dual Gap in absolut value and percent, The length of the node list L, -L-, The Inform and ExitFlag the solver returned at the current node, FuEv (Number of function evaluations used by solver at current node), date/time stamp. Outer approximation linearizations, number of cuts in active/inactive pool (|C| #A #I). 

> 1 A line at each evaluated node with the information described above. 
Moreover, with IterPrint enabled a notice is printed whenever the algorithm switches node selection methods. 
Setting a higher value of IterPrint gives more detailed information. 

>2 Depth, number of integer components and lower bound on objective for each node in L. 
>3 Sets LINPRINT = 1, print info about linearizations added (if used). 
>4 Sets POOLPRINT = 1, print info about cut-pool management (if used).
|-valign="top"
|''bTol''||Linear constraint violation convergence tolerance.
|-valign="top"
|''cTol''||Constraint violation convergence tolerance.
|-valign="top"
|''fTol''||Optimality tolerance.
|}

==Outputs==

{| class="wikitable"
!''Result''||colspan="2"|Structure with result from optimization. The following fields are changed:
|-
|||''Iter ''||Number of iterations.
|-valign="top"
|||''ExitFlag ''||Exit flag. 0: Global optimal solution found, or integer solution with duality gap less than user tolerance. 1: Maximal number of iterations reached. 2: Empty feasible set, no integer solution found. 4: No feasible point found running NLP relaxation. 5: Illegal x_0 found in NLP relaxation. 99: Maximal CPU Time used (cputime ''> ''Prob.MaxCPU).
|-
|||''Inform''||Code telling type of convergence, returned from subsolver.
|-
|||''ExitText''||Text string giving ''ExitFlag'' and ''Inform'' information.
|-valign="top"
|||''DualGap''||Relative duality gap, max(0,fIPMin-fLB)/-fIPMin-, if fIPMin =0; max(0,fIPMin-fLB) if fIPMin == 0. If fIPMin =0: Scale with 100, 100*Dual- Gap, to get the percentage duality gap. For absolute value duality gap: scale with fIPMin, fIPMin * DualGap
|-
|||''x_k''||Solution.
|-valign="top"
|||''v_k''||Lagrange multipliers. Bounds, Linear and Nonlinear Constraints, size n + mLin + mNonLin.
|-
|||''f_k''||Function value at optimum.
|-
|||''g_k''||Gradient vector at optimum.
|-
|||''x_0''||Starting point x_0.
|-
|||''f_0''||Function value at start.
|-
|||''c_k''||Constraint values at optimum.
|-
|||''cJac''||Constraint derivative values at optimum.
|-
|||''xState''||State of each variable, described in [[TOMLAB_Appendix_B#Table:_The_state_variable_xState_for_the_variable.|TOMLAB Appendix B]].
|-
|||''bState''||State of each constraint, described in [[TOMLAB_Appendix_B#Table:_The_state_variable_bState_for_each_linear_constraint.|TOMLAB Appendix B]].
|-
|||''cState''||State of each general constraint, described in [[TOMLAB_Appendix_B#Table:_The_state_variable_cState_for_each_nonlinear_constraint.|TOMLAB Appendix B]].
|-
|||''Solver''||Solver used ('stoaMINLP').
|-
|||''SolverAlgorithm''||Description of method used.
|-
|||''Prob''||Problem structure used.
|-valign="top"
|||''stoaMINLP''||A structure with warm start information. Use with WarmDefGLOBAL, see example [[StoaMINLP#Warm_Start|here]].
|}

[[Category:MIPNLP]]

MIPNLP stoaMINLP

2015-02-11T15:30:03Z

Bjorn: /* Prob structure */

{{Part Of Manual|title=the MIPNLP Manual|link=[[MIPNLP|MIPNLP Manual]]}}
==Purpose==

stoaMINLP solves convex mixed-integer nonlinear programming problems (MINLP).

''stoaMINLP ''solves problems of the form

<math>
\begin{array}{cccccc}
\min\limits_{x} & f(x) \\s/t & x_{L} & \leq & x & \leq & x_{U} \\& b_{L} & \leq & Ax & \leq & b_{U} \\& c_{L} & \leq & c(x) & \leq & c_{U} \\& & & {x_{j} \in \mathbb{N} \ \ \forall j \in I} \\
\end{array}
</math>

where <math>x,x_{L},x_{U}\in \mathbb{R}^{n}</math> , <math>c(x),c_{L},c_{U}\in
\mathbb{R}^{m_{1}}</math> , <math>A\in \mathbb{R}^{m_{2}\times n}</math> and
<math>b_{L},b_{U}\in \mathbb{R}^{m_{2}}</math>. The variables <math>x \in I</math> , the
index subset of <math>1,...,n</math> are restricted to be integers.

==Calling Syntax==

Recommended is to first set IterPrint, to get information each iteration
<source lang="matlab">
Prob.optParam.IterPrint = 1;
</source>
Driver call, including printing with level 2:
<source lang="matlab">
Result = tomRun('stoaMINLP',Prob,2);
</source>
Direct solver call:
<source lang="matlab">
Result = stoaMINLP(Prob);
PrintResult(Result);
Result = tomRun('stoaMINLP',Prob,...)
</source>

=== Warm Start ===
To make a restart (warm start), just set the warm start flag, and call stoaMINLP once again:

<source lang="matlab">
Prob.WarmStart = 1;
Result = tomRun('stoaMINLP', Prob, 2);
</source>

stoaMINLP will read warm start information from the stoaMINLPSave.mat file. Another warm start (with same MaxFunc) is made by just calling tomRun again:

<source lang="matlab">
Result = tomRun('stoaMINLP', Prob, 2);
</source>

To make a restart from the warm start information in the Result structure, make a call to WarmDefGLOBAL before calling stoaMINLP. WarmDefGLOBAL moves information from the Result structure to the Prob structure and sets the warm start flag, <code>Prob.WarmStart = 1;</code>

<source lang="matlab">
Prob = WarmDefGLOBAL('stoaMINLP', Prob, Result);
</source>

where Result is the result structure returned by the previous run. A warm start (with same MaxIter) is done by just calling tomRun again:

<source lang="matlab">
Result = tomRun('stoaMINLP', Prob, 2);
</source>

To make another warm start with new MaxIter 100, say, redefine MaxIter as:

<source lang="matlab">
Prob.optParam.MaxIter = 100;
</source>

Then repeat the two lines:

<source lang="matlab">
Prob = WarmDefGLOBAL('stoaMINLP', Prob, Result);
Result = tomRun('stoaMINLP', Prob, 2);
</source>

==Inputs==

===Prob structure===
The '''TOMLAB''' problem structure

{| class="wikitable"
!colspan="2"|The following fields are used in ''Prob'':
|-
|'''Field'''||'''Description'''
|-
|''x_L''||Lower bounds on x.
|-
|''x_U''||Upper bounds on x.
|-
|''A''||The linear constraint matrix.
|-
|''b_L''||Lower bounds on linear constraints.
|-
|''b_U''||Upper bounds on linear constraints.
|-
|''c_L''||Lower bounds on nonlinear constraints.
|-
|''c_U''||Upper bounds on nonlinear constraints.
|-
|''x_0''||Starting point.
|-valign="top"
|''Convex''||If Convex==1, assume NLP problems are convex, and only one local NLP solver call is used at each node. If Convex==0 (Default), multiMin is used to do many calls to a local solver to determine the global minima at each node. The global minimum with most components integer valued is chosen.
|-valign="top"
|''MaxCPU''||Maximal CPU Time (in seconds) to be used by stoaMINLP, stops with best point found
|-valign="top"
|''PriLev''||Print level in stoaMINLP (default 1). Also see optParam.IterPrint
|-valign="top"
|''PriLevOpt''||Print level in sub-solvers (SNOPT and other NLP solvers): =0 No output; ''>''0 Convergence results. ''>''1 Output every iteration, ''>''2 Output each step in the NLP alg For other NLP solvers, see the documentation for the solver
|-valign="top"
|''WarmStart''||If true, ''>''0, stoaMINLP reads the output from the last run from Prob.stoaMINLP, if it exists. If it doesn't exist, stoaMINLP attempts to open and read warm start data from mat-file stoaMINLPSave.mat. stoaMINLP uses the warm start information to continue from the last run. The mat-file minlp- SolveSave.mat is saved every Prob.MIP.SaveFreq iteration.
|-valign="top"
|''SolverNLP''||Name of the solver used for NLP subproblems. If empty, the default solver is found calling GetSolver('con',1); If TOMLAB /SOL installed, SNOPT is the default solver. If SolverNLP is a SOL solver (SNOPT, MINOS or NPSOL), the SOL.optPar and SOL.PrintFile is used: See help minosTL.m, npsolTL.m or snoptTL.m for how to set these parameters
|-
|''SolverNLP0''||Name of the solver used for the initial NLP-problem. If empty, SolverNLP is used.
|-valign="top"
|''SolverLP''||Name of the solver used for LP subproblems. If empty, the default solver is found calling GetSolver('lp',1). If TOMLAB /SOL or /SNOPT or /NPSOL installed, MINOS is the default solver. If SolverLP is a SOL solver (MINOS, SNOPT or NPSOL), the SOL.optPar and SOL.PrintFile is used: See help minosTL.m, npsolTL.m or snoptTL.m for how to set these parameters.
|-valign="top"
|''RandState''||If Convex == 0, RandState is sent to multiMin to initialize the random generator. RandState is used as follows: If ''> ''0, rand('state',RandState) is set to initialize the pseudo-random generator. If ''< ''0, rand('state',sum(100*clock)) is set to give a new set of random values each run. If RandState == 0, rand('state',) is not called. Default is RandState = -1
|-valign="top"
|''xInit''||Parameter sent to the solver multiMin which is used to solve relaxed sub-problems for nonconvex problems (with Prob.Convex set to false). xInit determines the way initial points are generated and is set as follows: 
 
Either 
1x1 number - 
If > 0, the number of random initial points, default min(3000,30*n); 
If < 0, generate |xInit| points with Latin Hypercube design 
 
dxm matrix - Every column is an initial point (of length d = Prob.N) 
 
Default value for xInit is min(3000,max(60,N*6)) at all nodes except the root node 
|-valign="top"
|''xInit0''||Parameter sent to the solver multiMin when solving the initial relaxed NLP problem at the root node. 
Default value for xInit0 is min(3000,max(100,N*10)) 
See xInit for more information. 
|-valign="top"
|''MIP''||Structure defining integer optimization parameters. See the table below for a description of each field used in ''Prob.MIP''.
|-valign="top"
|''STOAMINLP''||Structure with solver-specific options. See the table below with descriptions of the fields used in ''Prob.STOAMINLP''.
|-valign="top"
|''optParam''||Structure with general optimization parameters. See the table below with descriptions of the fields used in ''Prob.optParam''.
|}

===MIP structure===

Substructure in Prob with parameters related to mixed integer programming.

{|class="wikitable"
!colspan="2"|fields used in '''Prob.MIP'''
|-
|'''Field'''||'''Description'''
|-valign="top"
|''IntVars''||If empty, all variables are assumed non-integer. If islogical(IntVars) (=all elements are 0/1), then 1 = integer variable, 0 = continuous variable. If any element ''>''1, IntVars is the indices for integer variables.
|-valign="top"
|''VarWeight''||Weight for each variable in the variable selection phase. A lower value gives higher priority. Setting Prob.MIP.VarWeight might improve convergence.
|-valign="top"
|''DualGap''||''stoaMINLP ''stops if the duality gap is less than DualGap. DualGap = 1, stop at first integer solution e.g. DualGap = 0.01, stop if solution ''< ''1% from optimal solution.
|-valign="top"
|''fIP''||An upper bound on the IP value wanted. Makes it possible to cut branches and avoid node computations. Used even if xIP not given.
|-valign="top"
|''xIP''||The x-values giving the fIP value, if a solution (xIP,fIP) is known.
|-valign="top"
|''NodeSel''||Node selection method: = 1 Depth First. Priority on nodes with more integer components. Default = 2 Breadth First. Priority on nodes with more integer components. = 3 Pure LIFO (Last in, first out) Depth First. = 4 Pure FIFO (First in, first out) Breadth First. = 5 Maximize integer components. = 6 Best bound. = 7 Best estimate using pseudo-costs. = 8 Best projection.
|-valign="top"
|''Backtrack''||Node selection method to use after an integer solution has been found. Available choices are the same as for NodeSel. Default is 2, Breadth First.
|-valign="top"
|''VarSel''||Variable selection method in branch and bound. = 1 Use variable with most fractional value. = 2 Use gradient and distance to nearest integer value. = 3 Pseudo-cost-based branching.
|-valign="top"
|''KNAPSACK''||If = 1, use a knapsack heuristic. Default 0.
|-valign="top"
|''ROUNDH''||If = 1, use a rounding heuristic. Default 0.
|-valign="top"
|''SaveFreq''||Warm start info saved on stoaMINLPSave.mat every SaveFreq iteration (default -1, i.e. no warm start info is saved)
|}

===STOAMINLP structure===

Substructure in Prob with solver-specific options

{|class="wikitable"
!colspan="2"|fields used in Prob.STOAMINLP
|-
|'''Field'''||'''Description'''
|-valign="top"
|''USECUTS''||Flag to use cutting plane algorithm described in [[StoaMINLP#Algorithm]]. Using cuts is not recommended for nonconvex problems. Set nonzero to enable, zero to disable. By default, USECUTS = Prob.Convex.
|-valign="top"
|''B_ecp''||Parameter regulating likelihood of linearization using extended cutting plane. See [[StoaMINLP#Algorithm]] for more information. Default 10.
|-valign="top"
|''K_ecp''||Parameter regulating "tailing off" detection for extended cutting plane linearizations. See [[StoaMINLP#Algorithm]] for more information. Default 0.001.
|-valign="top"
|''M_ecp''||Parameter regulating the balance between branching the search tree and adding linearizations using extended cutting plane. See [[StoaMINLP#Algorithm]] for more information. Default 10.
|-valign="top"
|''B_ff''||Parameter regulating likelihood of linearization using fixed fractional integer decision variables. See [[StoaMINLP#Algorithm]] for more information. Default 10.
|-valign="top"
|''K_ff''||Parameter regulating "tailing off" detection for linearizations using fixed fractional integer decision variables. See [[StoaMINLP#Algorithm]] for more information. Default 0.001.
|-valign="top"
|''M_ff''||Parameter regulating the balance between branching the search tree and adding linearizations using fixed fractional integer decision variables. See [[StoaMINLP#Algorithm]] for more information. Default 10.
|-valign="top"
|''B_nlpr''||Parameter regulating likelihood of linearization using the solution of the relaxed NLP problem. See [[StoaMINLP#Algorithm]] for more information. Default 10.
|-valign="top"
|''K_nlpr''||Parameter regulating "tailing off" detection for linearizations using the solution of the relaxed NLP problem. See [[StoaMINLP#Algorithm]] for more information. Default 0.001.
|-valign="top"
|''M_nlpr''||Parameter regulating the balance between branching the search tree and adding linearizations using the solution of the relaxed NLP problem. See [[StoaMINLP#Algorithm]] for more information. Default 10.
|-valign="top"
|''rTYPE''||= 0 r is fixed to the value in rVALUE. = 1 r is a uniformly distributed random number in the interval [0,1]. Default.
|-valign="top"
|''rVALUE''||Defines the value of r when rTYPE is set to zero. Default is 0.5.
|-valign="top"
|''CUTPOOL''||= 0 All linearizations constraints are kept in the master problem. = 1 Manage a pool with inactive linearization constraints. If an inactive constraint gets violated, it is brought back from the pool. Default.
|-valign="top"
|''CUTDELBND''||The number of consecutive times a linearization can be inactive before it gets removed and put into the inactive pool. Default 15.
|-valign="top"
|''CUTLIMDEL''||= 0 No extra deletion of cuts. Default when Prob.Convex == 1. = 1 Delete any cuts limiting the true feasible region when detected. Such cuts will appear if the problem has nonlinear constraints. Default when Prob.Convex == 0.
|-valign="top"
|''PCITL''||Limit on time spent per node calculating initial pseudo costs when VarSel == 3. Default is 120 (s).
|-valign="top"
|''LINPRINT''||Set nonzero to print short information about the type of linearization added. Default 0. enabled when IterPrint > 3.
|-valign="top"
|''POOLPRINT''||Set nonzero to print information about the cutpool management. Default 0. Enabled when IterPrint > 4.
|}

===optParam structure===

Substructure in Prob with general optimization parameters.

{|class="wikitable"
!colspan="2"|fields used in Prob.optParam:
|-
|'''Field'''||'''Description'''
|-valign="top"
|''MaxIter''||Maximal number of iterations, default 10000
|-valign="top"
|''IterPrint''||Print short information each iteration. Setting PriLev > 1 also enables IterPrint, setting it to 1. 
The information printed for different levels is as follows: 

>0 A line at each evaluated node with the following: 
Iteration number: 
Depth in tree (symbol L[] - empty list, symbol Gap - Dual Gap convergence), fNLP (Optimal f(x) current node), fIPMin (Best integer feasible f(x) found), LowBnd (Lower bound on optimal integer feasible f(x)), Dual Gap in absolut value and percent, The length of the node list L, -L-, The Inform and ExitFlag the solver returned at the current node, FuEv (Number of function evaluations used by solver at current node), date/time stamp. Outer approximation linearizations, number of cuts in active/inactive pool (|C| #A #I). 

> 1 A line at each evaluated node with the information described above. 
Moreover, with IterPrint enabled a notice is printed whenever the algorithm switches node selection methods. 
Setting a higher value of IterPrint gives more detailed information. 

>2 Depth, number of integer components and lower bound on objective for each node in L. 
>3 Sets LINPRINT = 1, print info about linearizations added (if used). 
>4 Sets POOLPRINT = 1, print info about cut-pool management (if used).
|-valign="top"
|''bTol''||Linear constraint violation convergence tolerance.
|-valign="top"
|''cTol''||Constraint violation convergence tolerance.
|-valign="top"
|''fTol''||Optimality tolerance.
|}

==Outputs==

{| class="wikitable"
!''Result''||colspan="2"|Structure with result from optimization. The following fields are changed:
|-
|||''Iter ''||Number of iterations.
|-valign="top"
|||''ExitFlag ''||Exit flag. 0: Global optimal solution found, or integer solution with duality gap less than user tolerance. 1: Maximal number of iterations reached. 2: Empty feasible set, no integer solution found. 4: No feasible point found running NLP relaxation. 5: Illegal x_0 found in NLP relaxation. 99: Maximal CPU Time used (cputime ''> ''Prob.MaxCPU).
|-
|||''Inform''||Code telling type of convergence, returned from subsolver.
|-
|||''ExitText''||Text string giving ''ExitFlag'' and ''Inform'' information.
|-valign="top"
|||''DualGap''||Relative duality gap, max(0,fIPMin-fLB)/-fIPMin-, if fIPMin =0; max(0,fIPMin-fLB) if fIPMin == 0. If fIPMin =0: Scale with 100, 100*Dual- Gap, to get the percentage duality gap. For absolute value duality gap: scale with fIPMin, fIPMin * DualGap
|-
|||''x_k''||Solution.
|-valign="top"
|||''v_k''||Lagrange multipliers. Bounds, Linear and Nonlinear Constraints, size n + mLin + mNonLin.
|-
|||''f_k''||Function value at optimum.
|-
|||''g_k''||Gradient vector at optimum.
|-
|||''x_0''||Starting point x_0.
|-
|||''f_0''||Function value at start.
|-
|||''c_k''||Constraint values at optimum.
|-
|||''cJac''||Constraint derivative values at optimum.
|-
|||''xState''||State of each variable, described in [[TOMLAB_Appendix_B#Table:_The_state_variable_xState_for_the_variable.|TOMLAB Appendix B]].
|-
|||''bState''||State of each constraint, described in [[TOMLAB_Appendix_B#Table:_The_state_variable_bState_for_each_linear_constraint.|TOMLAB Appendix B]].
|-
|||''cState''||State of each general constraint, described in [[TOMLAB_Appendix_B#Table:_The_state_variable_cState_for_each_nonlinear_constraint.|TOMLAB Appendix B]].
|-
|||''Solver''||Solver used ('stoaMINLP').
|-
|||''SolverAlgorithm''||Description of method used.
|-
|||''Prob''||Problem structure used.
|-valign="top"
|||''stoaMINLP''||A structure with warm start information. Use with WarmDefGLOBAL, see example [[StoaMINLP#Warm_Start|here]].
|}

[[Category:MIPNLP]]

MIPNLP

2015-02-11T15:24:23Z

Bjorn: /* TOMLAB /MIPNLP Solver References */

= Overview =

Welcome to the TOMLAB /MIPNLP User's Guide. TOMLAB /MIPNLP includes four solvers for mixed integer programming problems. The solvers take advantage of the wide array of subsolvers for LP, NLP and MILP in TOMLAB.

The solver package includes the following solvers:

[[multiMin]] - Solves general constrained mixed-integer global optimization problems. It tries to find all local minima by a multi-start method using a suitable nonlinear programming subsolver.

[[multiMINLP]] - Solves general constrained mixed-integer global nonlinear optimization problems. It is aimed for problems where the number of integer combinations nMax is huge and relaxation of the integer constraint is possible.

[[MIPNLP_ecpMINLP|ecpMINLP]] - Solves convex or pseudo-convex mixed-integer nonlinear programming problems using an extended cutting plane algorithm with cuts regulated by a parameter-vector alpha. Cuts and linearizations are added to a MIP subproblem solved by a subsolver in each iteration. The solver algorithm is an implementation based on the publication 'Solving Pseudo-Convex Mixed Integer Optimization Problems by Cutting Plane Techniques' by Tapio Westerlund and Ray Pörn, Optimization and Engineering 3, 253-280, 2002, but with modifications.

[[MIPNLP_ecpMINLP|stoaMINLP]] - Single-search Tree Outer Approximation Solver for Mixed-Integer NonLinear Programming (MINLP). Is best suited for solving convex problems. The solver is mainly based on 'FilMINT: An Outer-Approximation-Based Solver for Nonlinear Mixed Integer Programs' by Kumar Abhishek, Sven Leyffer, and Jeffrey T. Linderoth at the Mathematics and Computer Science Division, Preprint ANL/MCS-P1374-0906, March 28, 2008, but with some differences.

==TOMLAB /MIPNLP Solver References==

* [[multiMin]]
* [[MIPNLP_ecpMINLP|ecpMINLP]]
* [[MIPNLP_stoaMINLP|stoaMINLP]]
* [[MultiMINLP|multiMINLP]]

Welcome

2014-12-12T13:58:27Z

Bjorn: /* Standalone */

The TOMLAB Environment is a modeling platform for solving applied optimization problems in [http://en.wikipedia.org/wiki/MATLAB MATLAB].

==Description==
TOMLAB is a general purpose development and modeling environment in MATLAB for research, teaching and practical solution of optimization problems. It enables a wider range of problems to be solved in MATLAB and provides many additional solvers.

==Optimization problems supported==
TOMLAB handles a wide range of problem types, among them:
* Linear programming
* Quadratic programming
* Nonlinear programming
* Mixed-integer programming
* Mixed-integer quadratic programming with or without convex quadratic constraints
* Mixed-integer nonlinear programming
* Linear and nonlinear least squares with L1, L2 and infinity norm
* Exponential data fitting
* Global optimization
* Semi-definite programming problem with bilinear matrix inequalities
* Constrained goal attainment
* Geometric programming
* Genetic programming
* Costly or expensive black-box global optimization
* Nonlinear complementarity problems

==TOMLAB Manuals==

===TOMLAB Manual===
Includes general TOMLAB information and solver reference for the TOMLAB Base Module.
* [[TOMLAB|TOMLAB Manual]]

===Quickguide===
Basics associated with solving problems using the TOMLAB Optimization Environment.
* [[Quickguide]]

===Models===
A short introduction to the TOMLAB Models.
* [[Models]]

===SAL===
Standalone execution of TOMLAB. Compilation instructions.
* [[SAL]]

===Installation===
Guide for installation of demos and permanently licensed TOMLAB components.
* [[Installation]]

==Product User's Guides==

====Included in the [[SOL|TOMLAB /SOL manual]]====
<table>
<tr>
<td>
*[[MINOS]]
</td>
<td>
*[[SOL_NPSOL|NPSOL]]
</td>
<td>
* [[SNOPT]]
</td>
</tr>
</table>

====Standalone====

<table>
<tr>
<td>
* [[AMPL]]</td>
<td>
* [[CGO]]</td>
<td>
* [[CONOPT]]</td>
<td>
* [[CPLEX]]</td>
<td>
* [[GP]]</td>
</tr>
<tr>
<td>
* [[GENO]]</td>
<td>
* [[GUROBI]]</td>
<td>
* [[KNITRO]]</td>
<td>
* [[LGO]]</td>
<td>
* [[MAD]]</td>
</tr>
<tr>
<td>
* [[MINLP]]</td>
<td>
* [[MIPNLP]]</td>
<td>
* [[MISQP]]</td>
<td>
* [[NLPQL]]</td>
<td>
* [[OQNLP]]</td>
</tr>
<tr>
<td>
* [[PENOPT]]</td>
<td>
* [[PROPT]]</td>
<td>
* [[SOL]]</td>
<td>
* [[TomSym]]</td>
<td>
* [[Xpress]]</td>
</tr>
</table>

==PDF==

*[[PDF|Manuals in PDF format]]

==Links==

* http://tomopt.com/

Welcome

2014-12-12T13:38:22Z

Bjorn: Reverted edits by Bjorn (talk) to last revision by Elias

The TOMLAB Environment is a modeling platform for solving applied optimization problems in [http://en.wikipedia.org/wiki/MATLAB MATLAB].

==Description==
TOMLAB is a general purpose development and modeling environment in MATLAB for research, teaching and practical solution of optimization problems. It enables a wider range of problems to be solved in MATLAB and provides many additional solvers.

==Optimization problems supported==
TOMLAB handles a wide range of problem types, among them:
* Linear programming
* Quadratic programming
* Nonlinear programming
* Mixed-integer programming
* Mixed-integer quadratic programming with or without convex quadratic constraints
* Mixed-integer nonlinear programming
* Linear and nonlinear least squares with L1, L2 and infinity norm
* Exponential data fitting
* Global optimization
* Semi-definite programming problem with bilinear matrix inequalities
* Constrained goal attainment
* Geometric programming
* Genetic programming
* Costly or expensive black-box global optimization
* Nonlinear complementarity problems

==TOMLAB Manuals==

===TOMLAB Manual===
Includes general TOMLAB information and solver reference for the TOMLAB Base Module.
* [[TOMLAB|TOMLAB Manual]]

===Quickguide===
Basics associated with solving problems using the TOMLAB Optimization Environment.
* [[Quickguide]]

===Models===
A short introduction to the TOMLAB Models.
* [[Models]]

===SAL===
Standalone execution of TOMLAB. Compilation instructions.
* [[SAL]]

===Installation===
Guide for installation of demos and permanently licensed TOMLAB components.
* [[Installation]]

==Product User's Guides==

====Included in the [[SOL|TOMLAB /SOL manual]]====
<table>
<tr>
<td>
*[[MINOS]]
</td>
<td>
*[[SOL_NPSOL|NPSOL]]
</td>
<td>
* [[SNOPT]]
</td>
</tr>
</table>

====Standalone====

<table>
<tr>
<td>
* [[SOL]]
</td>
<td>
* [[CGO]]
</td>
<td>
* [[Xpress]]
</td>
<td>
* [[CPLEX]]
</td>
<td>
* [[GUROBI]]
</td>
<td>
* [[MINLP]]
</td>
</tr>
<tr>
<td>
* [[PENOPT]]
</td>
<td>
* [[KNITRO]]
</td>
<td>
* [[OQNLP]]
</td>
<td>
* [[CONOPT]]
</td>
<td>
* [[NLPQL]]
</td>
<td>
* [[LGO]]
</td>
</tr>
<tr>
<td>
* [[GP]]
</td>
<td>
* [[GENO]]
</td>
<td>
* [[MAD]]
</td>
<td>
* [[AMPL]]
</td>
<td>
* [[PROPT]]
</td>
<td>
* [[TomSym]]
</td>
</tr>
<tr>
<td>
* [[MISQP]]
</td>
</tr>
</table>

==PDF==

*[[PDF|Manuals in PDF format]]

==Links==

* http://tomopt.com/

Welcome

2014-12-12T13:38:09Z

Bjorn: /* Standalone */

The TOMLAB Environment is a modeling platform for solving applied optimization problems in [http://en.wikipedia.org/wiki/MATLAB MATLAB].

==Description==
TOMLAB is a general purpose development and modeling environment in MATLAB for research, teaching and practical solution of optimization problems. It enables a wider range of problems to be solved in MATLAB and provides many additional solvers.

==Optimization problems supported==
TOMLAB handles a wide range of problem types, among them:
* Linear programming
* Quadratic programming
* Nonlinear programming
* Mixed-integer programming
* Mixed-integer quadratic programming with or without convex quadratic constraints
* Mixed-integer nonlinear programming
* Linear and nonlinear least squares with L1, L2 and infinity norm
* Exponential data fitting
* Global optimization
* Semi-definite programming problem with bilinear matrix inequalities
* Constrained goal attainment
* Geometric programming
* Genetic programming
* Costly or expensive black-box global optimization
* Nonlinear complementarity problems

==TOMLAB Manuals==

===TOMLAB Manual===
Includes general TOMLAB information and solver reference for the TOMLAB Base Module.
* [[TOMLAB|TOMLAB Manual]]

===Quickguide===
Basics associated with solving problems using the TOMLAB Optimization Environment.
* [[Quickguide]]

===Models===
A short introduction to the TOMLAB Models.
* [[Models]]

===SAL===
Standalone execution of TOMLAB. Compilation instructions.
* [[SAL]]

===Installation===
Guide for installation of demos and permanently licensed TOMLAB components.
* [[Installation]]

==Product User's Guides==

====Included in the [[SOL|TOMLAB /SOL manual]]====
<table>
<tr>
<td>
*[[MINOS]]
</td>
<td>
*[[SOL_NPSOL|NPSOL]]
</td>
<td>
* [[SNOPT]]
</td>
</tr>
</table>

====Standalone====

<table>
<tr>
<td>
* [[SOL]]
</td>
<td>
* [[CGO]]
</td>
<td>
* [[Xpress]]
</td>
<td>
* [[CPLEX]]
</td>
<td>
* [[GUROBI]]
</td>
<td>
* [[MINLP]]
</td>
</tr>
<tr>
<td>
* [[MIPNLP]]
</td>
</tr>
<td>
* [[PENOPT]]
</td>
<td>
* [[KNITRO]]
</td>
<td>
* [[OQNLP]]
</td>
<td>
* [[CONOPT]]
</td>
<td>
* [[NLPQL]]
</td>
<td>
* [[LGO]]
</td>
</tr>
<tr>
<td>
* [[GP]]
</td>
<td>
* [[GENO]]
</td>
<td>
* [[MAD]]
</td>
<td>
* [[AMPL]]
</td>
<td>
* [[PROPT]]
</td>
<td>
* [[TomSym]]
</td>
</tr>
<tr>
<td>
* [[MISQP]]
</td>
</tr>
</table>

==PDF==

*[[PDF|Manuals in PDF format]]

==Links==

* http://tomopt.com/

MIPNLP ecpMINLP

2014-12-05T12:39:11Z

Bjorn: /* Purpose */

{{Part Of Manual|title=the MIPNLP Manual|link=[[MIPNLP|MIPNLP Manual]]}}
==Purpose==

ecpMINLP solves convex mixed-integer nonlinear programming problems (MINLP).

''ecpMINLP ''solves problems of the form

<math>
\begin{array}{cccccc}
\min\limits_{x} & f(x) \\s/t & x_{L} & \leq & x & \leq & x_{U} \\& b_{L} & \leq & Ax & \leq & b_{U} \\& c_{L} & \leq & c(x) & \leq & c_{U} \\& & & {x_{j} \in \mathbb{N} \ \ \forall j \in I} \\
\end{array}
</math>

where <math>x,x_{L},x_{U}\in \mathbb{R}^{n}</math> , <math>c(x),c_{L},c_{U}\in
\mathbb{R}^{m_{1}}</math> , <math>A\in \mathbb{R}^{m_{2}\times n}</math> and
<math>b_{L},b_{U}\in \mathbb{R}^{m_{2}}</math>. The variables <math>x \in I</math> , the
index subset of <math>1,...,n</math> are restricted to be integers but can be either continuously differentiable or not. An initalization routine will detect strict integer variables in the problem.

==Calling Syntax==

Driver call, including printing with level 2:
<source lang="matlab">
Result = tomRun('ecpMINLP',Prob,2);
</source>
Direct solver call:
<source lang="matlab">
Result = ecpMINLP(Prob);
PrintResult(Result);
Result = tomRun('ecpMINLP',Prob,...)
</source>

=== Warm Start ===
Warm start is currently not supported, but might be included in a future release.

==Inputs==

===Prob structure===
The '''TOMLAB''' problem structure

{|class="wikitable"
!colspan="2"|The following fields are used in the problem description structure Prob
|-
|'''Field'''||'''Description'''
|-
|''x_L''||Lower bounds on x.
|-
|''x_U''||Upper bounds on x.
|-
|''A''||The linear constraint matrix.
|-
|''b_L''||Lower bounds on linear constraints.
|-
|''b_U''||Upper bounds on linear constraints.
|-
|''c_L''||Lower bounds on nonlinear constraints.
|-
|''c_U''||Upper bounds on nonlinear constraints.
|-
|''f_Low''||Lower bound on solution.
|-
|''x_0''||Starting point.
|-valign="top"
|''MaxCPU''||Maximal CPU Time (in seconds) to be used by ecpMINLP, stops with best point found
|-valign="top"
|''PriLev''||Print level in ecpMINLP (default 1). Also see optParam.IterPrint
{|class="wikitable"
!value||output
|-
|=0||Silent.
|-
|>0||Initial information and convergence results.
|-
|>1||Output a line whenever the solution has improved, containing:
nIterations, nCuts, nCuts with criteria fulfilled, nLinearizations, nSpecialCuts, best solution.
|-
|>2||Output a line every iteration with the following information:
{|class="wikitable"
!label||description
|-
|It ||Iterations
|-
|nECP ||Number of extended cutting planes (ECP)
|-
|nAlpha>=lim||Number of ECP with criteria fulfilled
|-
|nL ||Number of linearizations
|-
|nSECP ||Number of special case ECP (created from constraint on bound)
|-
|fIPMin ||Objective of best solution at current iteration
|}
|-
|>3||Output a description of each step in the MINLP algorithm
|-
|>4||Output additional numerical information in some algorithm steps
|-
|>5||Output information in substeps (preprocessing, line search)
|}
|-valign="top"
|''PriLevOpt''||Print level in sub-solvers, see the documentation for the solver
|-valign="top"
|''SolverMIP''||Name of the solver used for MIP subproblems. If TOMLAB /gurobi is installed, gurobi is the default solver. If TOMLAB /CPLEX is installed, CPLEX is second choice as default. Otherwise the default solver is found calling GetSolver('mip',1); Supported as subsolvers are gurobi, CPLEX, mipSolve, milpSolve and cutplane.
|-
|''SolverLP''||Name of the solver used for LP subproblems when SolverMIP == mipSolve
|-
|''MIP''||Structure with parameters specific to mixed integer optimization. See the table below describing the fields used in the MIP structure.
|-
|''ECPMINLP''||Structure with parameters specific to the ecpMINLP solver. See the table below describing the fields used in the ECPMINLP structure.
|-
|''optParam''||Structure with general optimization parameters. See the table below describing the fields used in the optParam structure.
|}

===MIP structure===
Substructure in Prob with parameters related to mixed integer programming.

{|class="wikitable"
!colspan="2"|'''fields used in Prob.MIP''':
|-
|'''Field'''||'''Description'''
|-valign="top"
|''IntVars''||If empty, all variables are assumed non-integer. If islogical(IntVars) (=all elements are 0/1), then 1 = integer variable, 0 = continuous variable. If any element ''>''1, IntVars is the indices for integer variables.
|-valign="top"
|''fIP''||An upper bound on the IP value wanted. Makes it possible to cut branches and avoid node computations. Used even if xIP not given.
|-valign="top"
|''xIP''||The x-values giving the fIP value, if a solution (xIP,fIP) is known.
|-valign="top"
|''DualGap''||ecpMINLP stops if the duality gap is less than DualGap
DualGap = 1, stop at first integer solution, e.g. DualGap = 0.01,stop if solution < 1% from optimal solution.
 The lower bound Prob.f_Low is used, (default -1.0e300), which can also be set by the user. If f_Low has not been changed from default the lower bound is obtained from the initial solution of a relaxed problem, but only when ECPMINLP.INIT_BND is 1 or 2 (default).
 Default DualGap is -1, not used.
|-valign="top"
|''PPP''||Pre-processing and probing, default is 0. 
0 Not used. Default. 
1 Apply initially on MINLP problem. 
2 Apply each iteration before solving MILP subproblem.
|-
|''ROUNDH''||If nonzero, a rounding heuristics will be used on the initial NLP solution in order to obtain an initial integer solution. Requires ECPMINLP.INIT_BND enabled. Default is 1, enabled.
|}

===ECPMINLP structure===
Substructure in ''Prob'' with solver-specific options.

{|class="wikitable"
!colspan="2"|fields used in Prob.ECPMINLP
|-
|'''Field'''||'''Description'''
|-valign="top"
|''beta''||Multiplier when increasing alpha after an infeasible MILP solution.
 Alpha is a parameter individually adjusting each cutting plane, starting at 1.0 and increasing until meeting a certain criterion. Default value for beta is 1.3.
|-valign="top"
|''gamma''||Multiplier when increasing alpha when MILP solution does not violate any nonlinear contraints, but still does not decrease the upper bound of the objective.
 Alpha is a parameter individually adjusting each cutting plane, starting at 1.0 and increasing until meeting a certain criterion. Default value for gamma is 2.0.
|-valign="top"
|''PREALLOC''||Flag enabling preallocation of memory for cutting planes and linearizations.
 0 No preallocation, dynamic growth of arrays. Current default.
 1 Preallocate arrays.
|-valign="top"
|''INIT_BND''||Selects method for setting lower bound when f_Low not changed from default.
{|class="wikitable"
!value||method
|-valign="top"
|0 ||No extra initial lower bound.
|-valign="top"
|1 ||Use default TOMLAB NLP solver on problem with relaxed integer constraints. Add a linearization if a feasible MINLP solution was found.
|-valign="top"
|2 ||Add an initial linearization as long as a feasdbile NLP solution was found. The linearization is a simple lower bound on the MILP objective. Default.
|-valign="top"
|3 ||Same as 2, but also use the gradient in the linearization. This might improve the solution process for some problems where no solution can be found otherwise. But for many problems, using this initial linearization cuts off a feasbiel region and slows down or even hinders the solver completely. Recommended to only use as a last resort.
|}
|-valign="top"
|''SETTOL''||Flag enabling changing tolerances, described below under optParam.eps_x, optParam.eps_x and optParam.eps_f.
 0 Default. Using the recommended solver default values, 1.0e-3.
 1 Tolerances can be changed, taken from Prob.optParam.
|-valign="top"
|''INTSOLLIM_INCR''||Integer option when using CPLEX as MIP subsolver.
 Define how much the CPLEX parameter INTSOLLIM increases when a feasible solution is not optimal and all alpha values have met their criteria.
 If set to zero, optimal strategy will be used immediately instead, without any gradual increase of INTSOLLIM.
 Default is 1.
|-valign="top"
|''USECUTPOOL''||Set nonzero to use a pool for the alpha-regulated extended cutting planes.
 Cuts not active in the MILP-solution for CUTDELBND iterations in a row will be inactivated (removed from the MILP-problem) until they are violated in a new solution.
 Default is 0, not used.
|-valign="top"
|''CUTDELBND''||The number of consecutive times an extended cutting plane can be inactive before it gets removed and put into the inactive pool, if the option USECUTPOOL is set nonzero.
 Default is 15 times.
|-valign="top"
|''MAXITNOIMP''||Limit on the number of successive iterations allowed without any improvements at all to neither objective nor solution point before the solver terminates
 Default is 2.
|-valign="top"
|''USENLP''||Set nonzero to use an NLP sub-solver on the original problem with the integer variables fixed at values from the latest MILP solution. Default is 1, enabled.
|-valign="top"
|''USERESELECT''||Set nonzero to enable cut reselection heuristics. Default is 1, enabled.
|-valign="top"
|''SCALECUTS''||Set nonzero to scale cuts before they are added to the MILP problem. Scaling is done by dividing the cut with its norm. Default is 1, enabled.
|}

===optParam Structure===
Substructure in ''Prob'' with general optimization parameters.

{|class="wikitable"
!colspan="2"|fields used in Prob.optParam
|-
|'''Field'''||'''Value'''
|-valign="top"
|''MaxIter''||Maximal number of iterations, default 10000
|-valign="top"
|''IterPrint''||Print short information each iteration. Setting PriLev > 1 also enables IterPrint, setting it to 1.
|-valign="top"
|''eps_x''||Linear constraint violation convergence tolerance. Default is 2.0e-6
|-valign="top"
|''eps_g''||Constraint violation convergence tolerance. Default is 1.0e-7
|-valign="top"
|''eps_f''||Optimality tolerance. Default is 1.0e-8
|}

''NOTE:'' For the solver to use these tolerances, the flag ''ECPMINLP.SETTOL'' must be set to nonzero.

==Outputs==

{| class="wikitable"
!''Result''||colspan="2"|Structure with result from optimization. The following fields are changed:
|-
|||''Iter ''||Number of iterations.
|-valign="top"
|||''ExitFlag ''||Exit flag.
 0: Solution found, or integer solution with duality gap less than user tolerance.
 1: Maximal number of iterations reached.
 2: Empty feasible set, no integer solution found.
 3: Problem in subsolver, see Inform value.
 99: Maximal CPU Time used (cputime > Prob.maxCPU
|-
|||''Inform''||Inform for ExitFlag != 3
 0: Global solution found.
 1: Local solution found.
 2: No solution found.
 >2: Inform value from subsolver.
|-
|||''ExitText''||Text string giving ''ExitFlag'' and ''Inform'' information.
|-valign="top"
|||''DualGap''||Relative duality gap, max(0,fIPMin-fLB)/-fIPMin-, if fIPMin =0; max(0,fIPMin-fLB) if fIPMin == 0. If fIPMin =0: Scale with 100, 100*Dual- Gap, to get the percentage duality gap. For absolute value duality gap: scale with fIPMin, fIPMin * DualGap
|-
|||''x_k''||Solution.
|-valign="top"
|||''f_k''||Function value at optimum.
|-
|||''g_k''||Gradient vector at optimum.
|-
|||''c_k''||Constraint values at optimum.
|-
|||''cJac''||Constraint derivative values at optimum.
|-
|||''xState''||State of each variable, described in [[TOMLAB_Appendix_B#Table:_The_state_variable_xState_for_the_variable.|TOMLAB Appendix B]].
|-
|||''bState''||State of each constraint, described in [[TOMLAB_Appendix_B#Table:_The_state_variable_bState_for_each_linear_constraint.|TOMLAB Appendix B]].
|-
|||''cState''||State of each general constraint, described in [[TOMLAB_Appendix_B#Table:_The_state_variable_cState_for_each_nonlinear_constraint.|TOMLAB Appendix B]].
|-
|||''x_0''||Starting point x_0.
|-
|||''Solver''||Solver used ('ecpMINLP').
|-
|||''SolverAlgorithm''||Description of method used.
|-
|||''Prob''||Problem structure used.
|}

== Algorithm==
ecpMINLP Solves convex or pseudo-convex mixed-integer nonlinear programming problems using an extended cutting plane algorithm with cuts regulated by a parameter-vector alpha. Cuts and linearizations are added to MIP subproblem which is then solved by a subsolver in each iteration.

The solver algorithm is mainly based on the paper 'Solving Pseudo-Convex Mixed Integer Optimization Problems by Cutting Plane Techniques' by Tapio Westerlund and Ray Pörn, published in Optimization and Engineering 3, 253-280, 2002, with some modifications.

Most prominent features in addition to the ones described in the main reference above are
* Solving the relaxed NLP problem initially to obtain a lower bound on the solution.
* A rounding heuristics performed on the initial NLP solution in order to obtain an initial upper bound on the initial solutions.
* Optional use of a cutpool for the alpha-regulated extended cutting planes.

[[Category:MIPNLP]]

MultiMINLP

2014-10-09T14:39:19Z

Bjorn:

{{Part Of Manual|title=the MIPNLP Manual|link=[[MIPNLP|MIPNLP]]}}
[[Category:Solvers]]
==Purpose==

multiMINLP solves general constrained mixed-integer global nonlinear optimization problems.

It is aimed for problems where the number of integer combinations nMax is huge and relaxation of the integer constraint is possible.

If no integer variables, multiMINLP calls multiMin. If nMax ''<''= min(Prob.optParam.MaxFunc,5000), glcDirect is used. Otherwise, multiMINLP first finds a set M of local minima calling multiMin with no integer restriction on any variable. The best local minimum is selected. glcDirect is called to find the best integer feasible solution fIP in a small area (''< ''+- 2 units) around the best local minimum found.

The other local minima are pruned, if fOpt(i) ''> ''fIP, no integer feasible solution could be found close to this local minimum i.

The area close to the remaining candidate local minima are searched one by one by calling glcDirect to find any fIPi ''< ''fIP.

''multiMINLP ''solves problems of the form

<math>
\begin{array}{cccccc}
\min\limits_{x} & f(x) \\
s/t & x_{L} & \leq & x & \leq & x_{U} \\
& b_{L} & \leq & Ax & \leq & b_{U} \\
& c_{L} & \leq & c(x) & \leq & c_{U} \\
& & & {x_{j} \in \mathbb{N} \ \ \forall j \in I} \\
\end{array}
</math>

where <math>x,x_{L},x_{U}\in \mathbb{R}^{n}</math> , <math>c(x),c_{L},c_{U}\in
\mathbb{R}^{m_{1}}</math>, <math>A\in \mathbb{R}^{m_{2}\times n}</math> and
<math>b_{L},b_{U}\in \mathbb{R}^{m_{2}}</math> . The variables <math>x \in I</math>, the index subset of <math>1,...,n</math> are restricted to be integers.

==Calling Syntax==

<source lang="matlab">
Result = tomRun('multiMINLP',Prob,...)
</source>

==Inputs==

{| class="wikitable"
!''Prob''||colspan="2"|Problem description structure. The following fields are used:
|-
Prob is a structure, defined as to solve a standard MINLP problem. The Prob structure is fed to the localSolver. See e.g. minlpAssign.

See multiMin and glcDirect for input to the subsolvers e.g. Prob.xInit is used in multiMin (and fCut, RandState, xEQTol).
|-valign="top"
|||''x_L''||Lower bounds for each element in x. If generating random points, -inf elements of x_L are set to min(-L,xMin,x U-L) xMin is the minimum of the finite x_L values.
|-valign="top"
|||''x_U''||Upper bounds for each element in x. If generating random points, inf elements of x_U are set to max(L,xMax,x L+L) xMax is the maximum of the finite x_U values.

L is 100 for nonlinear least squares, otherwise 1000.
|-
|||''b_L''||Lower bounds on linear constraints.
|-
|||''b_U''||Upper bounds on linear constraints.
|-
|||''A''||The linear constraint matrix.
|-
|||''c_L''||Lower bounds on nonlinear constraints.
|-
|||''c_U''||Upper bounds on nonlinear constraints.
|-valign="top"
|||''PriLev''||Print Level:

0 = Silent

1 = Display 2 summary rows

2 = Display some extra summary rows

5 = Print level 1 in tomRun call

6 = Print level 2 in tomRun call

7 = Print level 3 in tomRun call
|-
|||''xInit''||Used in multiMin. See help for multiMin.
|-valign="top"
|||''GO.localSolver ''||The local solver used to run all local optimizations. Default is the license dependent output of GetSolver('con',1,0).
|-valign="top"
|||''optParam''||Structure in Prob, Prob.optParam. Defines optimization parameters. Fields used:
|-
|||''MaxFunc''||Max number of function evaluations in each subproblem
|-
|||''fGoal''||Goal for function value f(x), if empty not used. If fGoal is reached, no further local optimizations are done
|-valign="top"
|||''eps_f''||Relative accuracy for function value, fTol == eps_f. Stop if abs(f-fGoal) ''<''= abs(fGoal) * fTol , if fGoal = 0. Stop if abs(f-fGoal) ''<''= fTol , if fGoal ==0. Default 1e-8.
|-
|||''bTol''||Linear constraint feasibility tolerance. Default 1e-6
|-
|||''cTol''||Nonlinear constraint feasibility tolerance. Default 1e-6
|-valign="top"
|||''MIP''||Structure in Prob, Prob.MIP. Defines integer optimization parameters. Fields used:
|-valign="top"
|||''IntVars''||If empty, all variables are assumed non-integer. If islogical(IntVars) (=all el- ements are 0/1), then 1 = integer variable, 0 = continuous variable. If any element ''>''1, IntVars is the indices for integer variables.
|-
|||''nMax''||Number of integer combinations possible, if empty multiMINLP computes nMax.
|-
|||''Rfac''||Reduction factor for real variables in MINLP subproblem close to local multiMINLP minimum. Bounds set to x_L = max(x_L,x-Rfac*(x_U-x_L)) and x_U= min(x_U,x+Rfac*(x_U-x_L)). Default 0.25.
|}

==Outputs==

{|class="wikitable"
!''Result''||colspan="2"|Structure with result from optimization. The following fields are changed:
|-
|||||Result structure from the last good optimization step giving the best f(x) value, the possible global MINLP minimum.

The following fields in Result are changed by multiMINLP before return:
|-valign="top"
|||''ExitFlag''||= 0 normal output, of if fGoal set and found.

= 1 A solution reaching the user defined fGoal was not found.

= 2 Unbounded problem.

=4 Infeasible problem.

The Solver, SolverAlgorithm and ExitText fields are also reset.

A special field in Result is also returned, Result.multiMINLP:
|-
|||''xOpt''||Prob.N x k matrix with k distinct local optima, the test being norm(x k- xOpt(:,i)) ''<''= xEqTol*max(1,norm(x k)) that if fulfilled assumes x_k to be to close to xOpt(:,i).
|-
|||''fOpt''||The k function values in the local optima xOpt(:,i),i=1,...,k.
|-
|||''Inform''||The Inform value returned by the local solver when finding each of the local optima xOpt(:,i); i=1,...,k. The Inform value can be used to judge the validity of the local minimum reported.
|-
|||''localTry''||Total number of local searches.
|-
|||''Iter''||Total number of iterations.
|-
|||''FuncEv''||Total number of function evaluations.
|-
|||''GradEv''||Total number of gradient evaluations.
|-
|||''HessEv''||Total number of Hessian evaluations.
|-
|||''ConstrEv''||Total number of constraint function evaluations.
|-
|||''ExitText''||Text string giving Inform information.
|}

MultiMin

2014-10-09T14:39:05Z

Bjorn:

{{Part Of Manual|title=the MIPNLP Manual|link=[[MIPNLP|MIPNLP]]}}
[[Category:Solvers]]
==Purpose==

multiMin solves general constrained mixed-integer global optimization problems. It tries to find all local minima by a multi-start method using a suitable nonlinear programming subsolver.

''multiMin ''solves problems of the form

<math>
\begin{array}{cccccc}
\min\limits_{x} & f(x) & & & & \\
s/t & x_{L} & \leq & x & \leq & x_{U} \\
& b_{L} & \leq & Ax & \leq & b_{U} \\
& c_{L} & \leq & c(x) & \leq & c_{U} \\
& & & {x_i \in \mathbb{N} \; \forall i \in I} \\
\end{array}
</math>

where <math>x,x_{L},x_{U}\in \mathbb{R}^{n}</math> , <math>c(x),c_{L},c_{U}\in \mathbb{R}^{m_{1}}</math> , <math>A\in \mathbb{R}^{m_{2}\times n}</math> and <math>b_{L},b_{U}\in \mathbb{R}^{m_{2}}</math>.

The variables <math>x \in I</math> , the index subset of <math>1,...,n</math> are restricted to be integers.

The integer components of every x_0 is rounded to the nearest integer value inside simple bounds, and these components are fixed during the nonlinear local search.

If generating random points and there are linear constraints, multiMin checks feasibility with respect to the linear constraints, and for each initial point tries 100 times to get linear feasibility before accepting the initial point.

==Calling Syntax==

<source lang="matlab">
Result = multiMin(Prob, xInit)
Result = tomRun('multiMin', Prob, PriLev) (driver call)
</source>

==Inputs==

{| class="wikitable"
!''Prob''||colspan="2"|Problem description structure. The following fields are used:
|-
|''xInit''||colspan="2"|Either, 1x1 number - The number of random initial points, default 10*Prob.N dxm matrix - Every column is an initial point (of length d=Prob.N). May also be set as Prob.xInit.
|-
|||''fCut''||If initial f(x_0) ''> ''fCut, no local optimization is done.
|-valign="top"
|||''WarmStart''||If true, ''> ''0, multiMin assumes the field multiMin defined with the output from a previous run on the same problem. See the Output fields of Result.multiMin. Use WarmDefGLOBAL to set the correct fields in the Prob structure. Nec- essary fields are fOpt and xOpt. If any of the other fields are missing, the corresponding variables are initialized to 0. These other fields are: localTry, Iter, FuncEv, GradEv, HessEv, ConstrEv Inform (is set to zeros(length(fOpt,1) if not defined).

In WarmDefGLOBAL the Result structure for the optimal run will be fed back to multiMin as Prob.multiMin.ResOpt In case this field is not defined, and no better point is found during the runs, a special call to the localSolver is used to generate a proper Result structure.
|-valign="top"
|||''RandState''||If ''WarmStart ''and isscalar(xInit), RandState is used as follows: If ''> ''0, rand('state',RandState) is set to initialize the pseudo-random generator if ''< ''0, rand('state',sum(100*clock)) is set to give a new set of random values each run if RandState == 0, rand('state',) is not called Default RandState = -1
|-valign="top"
|||''xEqTol''||Tolerance to test if new point x_k already defined as optimum: ''norm(xk - xOpt(:, i))'' <= ''xEqTol * max(1, norm(xk))'' If test fulfilled x_k is assumed to be too close to xOpt(:,i) Default xEqTol = 1E-5
|-
|||''x_L''||Lower bounds for each element in x. If generating random points, -inf elements of x L are set to -10000.
|-valign="top"
|||''x_U''||Upper bounds for each element in x. If generating random points, inf elements of x U are set to 10000.
|-
|||''A''||Constraint matrix for linear constraints.
|-
|||''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.
|-valign="top"
|||''PriLevOpt''||0 = silent.

1 = Display one row for each unique local minima found. The minima are sorted, lowest value first (possibly the global minima)

The following 4 information values are displayed:
# Order #
# Function value f(x) at local minima
# Point x at local minima. Only up to 10 values are displayed
# Inform value returned from local Solver (normally 0)

2 = One row of output from each multiMin local optimization trial

The following 6 information values are displayed:

# Step #
# Text Old (previously found local minima), FAIL (solver failed to verify local minima) or blank (solver success, new local minima found)
# Inform value from local solver
# f(x_0) - function value f(x_0) for initial x_0
# f(x) - best f(x) value found in this local search
# x - point for which best f(x) value was found in this local search. Only up to 10 values are displayed.

3 = tomRun (PrintResult) output from every optimization, print level 1.

4 = tomRun (PrintResult) output from every optimization, print level 2. For constrained problems output of sum(-constr-) and information if optimal point was accepted w.r.t. feasibility.

5 = tomRun (PrintResult) output from every optimization, print level 3.
|-
|||''GO''||Structure in ''Prob'', ''Prob.GO''. Fields used:
|-valign="top"
|||''localSolver''||The local solver used to run all local optimizations. Default is the license dependent output of GetSolver('con',1,0).
|-
|||''optParam''||Defines optimization parameters. Fields used:
|-valign="top"
|||''fGoal''||Goal for function value f(x), if empty not used. If fGoal is reached, no further local optimizations are done.
|-
|||''eps_f''||Relative accuracy for function value, fTol == eps_f. Stop if abs(f-fGoal) ''<''= abs(fGoal) * fTol , if fGoal = 0. Stop if abs(f-fGoal) ''<''= fTol , if fGoal ==0.
|-valign="top"
|||''bTol''||The local solver used to run all local optimizations. Default is the license dependent output of GetSolver('con',1,0).
|-valign="top"
|||''MIP.IntVars''||Structure in Prob, Prob.MIP. If empty, all variables are assumed non-integer (LP problem). If ''length''(''I ntV ars'') ''> ''1 ==''> length''(''I ntV ars'') == ''length''(''c'') should hold. Then ''I ntV ars''(''i'') == 1 ==''> x''(''i'') integer. ''I ntV ars''(''i'') == 0 ==''> x''(''i'') real. If ''length''(''I ntV ars'') ''< n'', IntVars is assumed to be a set of indices. It is advised to number the integer values as the first variables, before the continuous. The tree search will then be done more efficiently.
|-
|''varargin''||colspan="2"|Other parameters directly sent to low level routines.
|}

==Outputs==

{| class="wikitable"
!''Result''||colspan="2"|Structure with result from optimization. The following fields are changed:
|-
|||colspan="2"|The following fields in Result are changed by multiMin before return:
|-valign="top"
|||''ExitFlag''||= 0 normal output, of if fGoal set and found.

= 1 A solution reaching the user defined fGoal was not found
|-
|||colspan="2"|The Solver, SolverAlgorithm and ExitText fields are also reset.
|-
|||colspan="2"|A special field in Result is also returned, Result.multiMin:
|-valign="top"
|||''xOpt''||Prob.N x k matrix with k distinct local optima, the test being ''norm''(''xk -xOpt''(:'', i'')) ''<''= ''xEqTol * max''(1'', norm''(''xk '')) that if fulfilled assumes x_k to be to closeto xOpt(:,i)
|-valign="top"
|||''fOpt''||The k function values in the local optima xOpt(:,i),i=1,...,k.
|-valign="top"
|||''Inform''||The Inform value returned by the local solver when finding each of the local optima xOpt(:,i); i=1,...,k. The Inform value can be used to judge the validity of the local minimum reported.
|-
|||''localTry''||Total number of local searches.
|-
|||''Iter''||Total number of iterations.
|-
|||''FuncEv''||Total number of function evaluations.
|-
|||''GradEv''||Total number of gradient evaluations.
|-
|||''HessEv''||Total number of Hessian evaluations.
|-
|||''ConstrEv''||Total number of constraint function evaluations.
|-
|||''ExitText''||Text string giving ExitFlag and Inform information.
|}

MIPNLP

2014-10-09T14:38:45Z

Bjorn:

= Overview =

Welcome to the TOMLAB /MIPNLP User's Guide. TOMLAB /MIPNLP includes four solvers for mixed integer programming problems. The solvers take advantage of the wide array of subsolvers for LP, NLP and MILP in TOMLAB.

The solver package includes the following solvers:

[[multiMin]] - Solves general constrained mixed-integer global optimization problems. It tries to find all local minima by a multi-start method using a suitable nonlinear programming subsolver.

[[multiMINLP]] - Solves general constrained mixed-integer global nonlinear optimization problems. It is aimed for problems where the number of integer combinations nMax is huge and relaxation of the integer constraint is possible.

[[MIPNLP_ecpMINLP|ecpMINLP]] - Solves convex or pseudo-convex mixed-integer nonlinear programming problems using an extended cutting plane algorithm with cuts regulated by a parameter-vector alpha. Cuts and linearizations are added to a MIP subproblem solved by a subsolver in each iteration. The solver algorithm is an implementation based on the publication 'Solving Pseudo-Convex Mixed Integer Optimization Problems by Cutting Plane Techniques' by Tapio Westerlund and Ray Pörn, Optimization and Engineering 3, 253-280, 2002, but with modifications.

[[MIPNLP_ecpMINLP|stoaMINLP]] - Single-search Tree Outer Approximation Solver for Mixed-Integer NonLinear Programming (MINLP). Is best suited for solving convex problems. The solver is mainly based on 'FilMINT: An Outer-Approximation-Based Solver for Nonlinear Mixed Integer Programs' by Kumar Abhishek, Sven Leyffer, and Jeffrey T. Linderoth at the Mathematics and Computer Science Division, Preprint ANL/MCS-P1374-0906, March 28, 2008, but with some differences.

==TOMLAB /MIPNLP Solver References==

* [[multiMin]]
* [[MIPNLP_ecpMINLP|ecpMINLP]]
* [[MIPNLP_ecpMINLP|stoaMINLP]]
* [[MultiMINLP|multiMINLP]]

MIPNLP

2014-10-09T14:36:49Z

Bjorn: /* TOMLAB /MIPNLP Solver References */

{{Part Of Manual|title=the MIPNLP Manual|link=[[MIPNLP|MIPNLP]]}}
= Overview =

Welcome to the TOMLAB /MIPNLP User's Guide. TOMLAB /MIPNLP includes four solvers for mixed integer programming problems. The solvers take advantage of the wide array of subsolvers for LP, NLP and MILP in TOMLAB.

The solver package includes the following solvers:

[[multiMin]] - Solves general constrained mixed-integer global optimization problems. It tries to find all local minima by a multi-start method using a suitable nonlinear programming subsolver.

[[multiMINLP]] - Solves general constrained mixed-integer global nonlinear optimization problems. It is aimed for problems where the number of integer combinations nMax is huge and relaxation of the integer constraint is possible.

[[MIPNLP_ecpMINLP|ecpMINLP]] - Solves convex or pseudo-convex mixed-integer nonlinear programming problems using an extended cutting plane algorithm with cuts regulated by a parameter-vector alpha. Cuts and linearizations are added to a MIP subproblem solved by a subsolver in each iteration. The solver algorithm is an implementation based on the publication 'Solving Pseudo-Convex Mixed Integer Optimization Problems by Cutting Plane Techniques' by Tapio Westerlund and Ray Pörn, Optimization and Engineering 3, 253-280, 2002, but with modifications.

[[MIPNLP_ecpMINLP|stoaMINLP]] - Single-search Tree Outer Approximation Solver for Mixed-Integer NonLinear Programming (MINLP). Is best suited for solving convex problems. The solver is mainly based on 'FilMINT: An Outer-Approximation-Based Solver for Nonlinear Mixed Integer Programs' by Kumar Abhishek, Sven Leyffer, and Jeffrey T. Linderoth at the Mathematics and Computer Science Division, Preprint ANL/MCS-P1374-0906, March 28, 2008, but with some differences.

==TOMLAB /MIPNLP Solver References==

* [[multiMin]]
* [[MIPNLP_ecpMINLP|ecpMINLP]]
* [[MIPNLP_ecpMINLP|stoaMINLP]]
* [[MultiMINLP|multiMINLP]]

MIPNLP

2014-10-09T14:35:18Z

Bjorn: Created page with "{{Part Of Manual|title=the MIPNLP Manual|link=MIPNLP}} = Overview = Welcome to the TOMLAB /MIPNLP User's Guide. TOMLAB /MIPNLP includes four solvers for mixed integer..."

MINLP

2014-10-09T14:25:32Z

Bjorn: /* Overview */

==Overview==

Welcome to the TOMLAB /MINLP User's Guide. TOMLAB /MINLP includes a suite of 4 solvers in dense and sparse version and interfaces between The MathWorks' MATLAB and the MINLP solver package. The solver package includes the following solvers:

bqpd - For sparse and dense linear and quadratic programming (nonconvex).

filterSQP - For sparse and dense linear, quadratic and nonlinear programming.

minlpBB - For sparse and dense mixed-integer linear, quadratic and nonlinear programming.

miqpBB - For sparse and dense mixed-integer linear and quadratic.

Please visit [http://tomopt.com/tomlab/products/minlp/ http://tomopt.com/tomlab/products/minlp/] for more information.

The interface between TOMLAB /MINLP, Matlab and TOMLAB consists of two layers. The first layer gives direct access from Matlab to MINLP, via calling one Matlab function that calls a pre-compiled MEX file (DLL under Windows, shared library in UNIX) that defines and solves the problem in MINLP. The second layer is a Matlab function that takes the input in the TOMLAB format, and calls the first layer function. On return the function creates the output in the TOMLAB format.

===Contents of this Manual===

*[[MINLP Using the Matlab Interface|Using the Matlab Interface]] gives the basic information needed to run the Matlab interface.
*[[MINLP Solver Reference|Solver Reference]] provides all the solver references for bqpd, filterSQP, minlpBB, and miqpBB.
*[[MINLP the DUNDEE structure|the DUNDEE structure]] presents the fields used in the special structure ''Prob.DUNDEE''.

===Prerequisites===

In this manual we assume that the user is familiar with MINLP, TOMLAB and the Matlab language.

==Using the Matlab Interface==

*[[MINLP Using the Matlab Interface|Using the Matlab Interface]]

==TOMLAB /MINLP Solver Reference==

*[[MINLP Solver Reference|Solver Reference]]

==the DUNDEE structure==

*[[MINLP the DUNDEE structure|the DUNDEE structure]]

==Algorithmic description==

*[[MINLP Algorithmic description|Algorithmic description]]

MISQP

2014-10-09T13:54:31Z

Bjorn: /* Overview */

==Introduction==
===Overview===

Welcome to the TOMLAB /MISQP User's Guide. TOMLAB /MISQP includes the MISQP and MIQL solvers from Klaus Schittkowski and an interface to The MathWorks' MATLAB.

MISQP solves mixed-integer nonlinear mathematical programming problems with equality and inequality constraints. It is assumed that integer variables have a ''smooth'' influence on the model functions, i.e., that function values do not change drastically when in- or decrementing an integer value.

The internal algorithm uses a modified sequential quadratic approximation method, stabilized by a trust region method including Yuan's second order corrections. The Hessian of the Lagrangian function is approximated by BFGS updates subject to the continous and integer variables.

MIQL solves strictly convex mixed-integer quadratic mathematical programming problems with linear equality and inequality constraints. The mixed-integer problem is solved by a branch-and-cut algorithm.

===Contents of this Manual===

*[[#Introduction]] provides a basic overview of the TOMLAB /MISQP solver package.
*[[#Using the Matlab Interface]] provides an overview of the Matlab interface to MISQP.
*[[#Setting MISQP Options]] describes how to set MISQP solver options from Matlab.
*[[#MISQP Solver Reference]] gives detailed information about the interface routine misqpTL.
*[[#MIQL Solver Reference]] gives detailed information about the interface routine miqlTL.
*[[#QL Solver Reference]] gives detailed information about the interface routine qlTL.

===More information===

Please visit the following links for more information:
* [http://tomopt.com/tomlab/products/misqp/ http://tomopt.com/tomlab/products/misqp/]

===Prerequisites===

In this manual we assume that the user is familiar with mixed-integer nonlinear programming, setting up problems in TOMLAB (in particular unconstrained and constrained mixed-integer nonlinear programming ('''minlp''') problems) and the Matlab language in general.

==Using the Matlab Interface==

The MISQP solver is accessed via the ''tomRun ''driver routine, which calls the ''misqpTL ''interface routine. The solver itself is located in the MEX file ''misqp''. The same applies for the other two solvers.

Observe that ''miqpAssign'' should be used when defining the problem for MIQL and ''qpAssign'' for QL.

{|class="wikitable"
!Function||Description
|-valign="top"
|''misqpTL''||The interface routine called by the TOMLAB driver routine ''tomRun''.

This routine then calls the MEX file ''misqp''
|-valign="top"
|''miqlTL''||The interface routine called by the TOMLAB driver routine ''tomRun''.

This routine then calls the MEX file ''miql''
|-valign="top"
|''qlTL''||The interface routine called by the TOMLAB driver routine ''tomRun''.

This routine then calls the MEX file ''ql''
|}

==Setting MISQP Options==

All MISQP control parameters are possible to set from Matlab.

===Setting options using the Prob.MISQP structure===

The parameters can be set as subfields in the ''Prob.MISQP ''structure. The following example shows how to set a limit on the maximum number of iterations.

<pre style="font-size: 12px">
Prob = minlpAssign(...) % Setup problem, see help minlpAssign for more information
Prob.MISQP.maxit = 2000; % Setting maximum number of iterations
</pre>

The maximum number of iterations can also be done through the TOMLAB parameter ''MaxIter'':

<pre style="font-size: 12px">
Prob.optParam.MaxIter = 200;
</pre>

In the cases where a solver specific parameter has a corresponding TOMLAB general parameter, the latter is used only if the user has not given the solver specific parameter.

A complete description of the available MISQP parameters can be found in [[#misqpTL]].

===Setting options using the Prob.MIQL structure===

Options can be set for MIQL in the same way as for MISQP as described above in [[#Setting options using the Prob.MISQP structure]].
The only difference is in the name of the structure (MIQL instead of MISQP) and the assign-routine (miqpAssign instead of minlpAssign).

===Setting options using the Prob.QL structure===

Options can be set for QL in the same way as for MISQP as described above in [[#Setting options using the Prob.MISQP structure]].
The only difference is in the name of the structure (QL instead of MISQP) and the assign-routine (qpAssign instead of minlpAssign).

==MISQP Solver References==

====Table: Solver routines in TOMLAB /MISQP.====

{|class="wikitable"
!Function||Description||Reference
|-valign="top"
|''ql''||Quadratic programming using a primal-dual method with cholesky decomposition.||''qlTL.m''
|-valign="top"
|''miql''||Mixed-integer quadratic programming using a branch-and-cut method with ''ql'' as subsolver.||''miqlTL.m''
|-valign="top"
|''misqp''||Constrained, mixed-integer nonlinear minimization using a sequential quadratic approximation method. ''miql'' is used as MIQP subsolver.||''misqpTL.m''
|}

A detailed description of the TOMLAB /MISQP solver interfaces is given below. Also see the M-file help for ''misqpTL.m'', ''miqlTL.m'' and ''qlTL.m''.

===misqpTL===

====Purpose====

Solves mixed-integer nonlinear optimization problems.

MISQP solves problems of the form

<div class="center">
<math>
\begin{array}{cccccc}
\min\limits_{x} & f(x) \\
& \\
s/t & x_{L} & \leq & x & \leq & x_{U} \\
& b_{L} & \leq & Ax & \leq & b_{U} \\
& c_{L} & \leq & c(x) & \leq & c_{U}
\end{array}
</math>
</div>

where <math>x,x_{L},x_{U}\in \mathbb{R}^{n}</math>, <math>A\in \mathbb{R}^{m_{1}\times n}</math> and <math>b_{L},b_{U}\in \mathbb{R}^{m_{1}}</math> and <math>c(x),c_{L},c_{U}\in \mathbb{R} ^{m_{2}}</math>, Furthermore, <math>x_i,\, i\in\mathbb{I}</math> are restricted to integer values only.

====Calling Syntax====

<pre style="font-size: 12px">
Prob = minlpAssign( ... );
Result = tomRun('misqp',Prob,...);
</pre>

====Description of Inputs====

''Prob ''Problem description structure. The following fields are used:

{|class="wikitable"
!Field||Description
|-valign="top"
|''x_L, x_U''||Bounds on variables.
|-valign="top"
|''b_L, b_U''||Bounds on linear constraints.
|-valign="top"
|''A''||Linear constraint matrix.
|-valign="top"
|''PriLevOpt''||Print Level in solver
|-valign="top"
|''MIP.IntVars''||If empty, all variables are assumed non-integer

If islogical(IntVars) (i.e. all elements are 0/1), then 1 = integer variable, 0 = continuous variable.

If any element >1, IntVars is the indices for integer variables
|-valign="top"
|''MISQP.PrintFile ''||Name of MISQP print file. Amount and type of printing determined by PriLevOpt. Default name ''misqp_printfile.txt''.
|-valign="top"
|''MISQP.maxit''||Maximum number of outer iterations, where one iteration corresponds to one formulation and solution of the quadratic programming subproblem, or, alternatively, one evaluation of gradients (default is to use optParam.MaxIter if set, otherwise set maxit to 1000).
|-valign="top"
|''MISQP.mnfs''||Maximum number of feasible steps without improvements, where the relative change of objective function values is measured by acc and feasibility is measured by sqrt(acc), must be greater than 1 (default maxit).
|-valign="top"
|''MISQP.maxnde''||Maximum number of branch-and-bound steps for solving MIQP. Default is (2*n+m+4)^2, where n is the number of variables and m is the number of constraints.
|-valign="top"
|''MISQP.nonmon''||Maximum number of successive iterations, which are to be considered for the non-monotone trust region algorithm (default 2).
|-valign="top"
|''MISQP.acc''||Desired final accuracy. The termination accuracy should not be smaller than the accuracy by which gradients are computed. If acc<=0, the machine precision is computed by MISQP and subsequently multiplied by 1.0e4 (default 1e-6).
|-valign="top"
|''MISQP.accqp''||The tolerance is needed for the QP solver to perform several tests, for example whether optimality conditions are satisfied or whether a number is considered as zero or not. If accqp is less or equal to zero, then the machine precision is computed by MISQP and subsequently multiplied by 1.0E4 (default 1e-9).
|-valign="top"
|''MISQP.rpen''||Factor for increasing a penalty parameter (sigma), must be greater than one (default 10).
|-valign="top"
|''MISQP.dltdec''||Factor for decreasing the internal descent parameter DELTA. dltdec must be less than than one (default 0.1).
|-valign="top"
|''MISQP.sigma''||Initial penalty parameter, greater than one (default 1000).
|-valign="top"
|''MISQP.delta''||Initial scaling parameter (default 0.05).
|-valign="top"
|''MISQP.trustc''||Initial trust region radius for continuous variables, must be greater than or equal to one (default 10.0).
|-valign="top"
|''MISQP.trusti''||Initial trust region radius for integer variables (default 10.0).
|-valign="top"
|''MISQP.scbnd''||Scaling bound in case of fscale=1, i.e., function values are scaled only if their absolute initial values are greater than the bound (default 1.0).
|-valign="top"
|''MISQP.mrs''||Maximum number of internal restarts without improving solution. Setting might lead to better results, but increases the number of function evaluations. The value must be less than 15 (default 2).
|-valign="top"
|''MISQP.fscale''||MISQP internally scales function values.

0 - No scaling.

1 - Subject to their absolute values, if greater than 1.0 or scbnd, respectively (default).
|-valign="top"
|''MISQP.scale''||MISQP internally scales continuous variables.

0 - No scaling.

1 - Scaling enabled (default).
|-valign="top"
|''MISQP.bmod''||MISQP modifies the Hessian approximation in order to get more accurate search directions. Calculation time is increased in case of integer variables.

0 - No modification

1 - (default 1).
|-
|''||

''Options for the MIQP subsolver MIQL:''

|-valign="top"
|''MISQP.iprqp''||Print level of subsolver MIQL (default 0).
|-valign="top"
|''MISQP.ibr''||Branching rule for MIQP subproblem
1 - Maximal fractional branching (default).

2 - Minimal fractional branching.
|-valign="top"
|''MISQP.ins''||Node selection rule for MIQP subproblem.
1 - Best of all.

2 - Best of two.

3 - Depth first (default).
|-valign="top"
|''MISQP.wstart''||Maximal number of successive warmstarts. Default 100.
|-valign="top"
|''MISQP.impb''||Set nonzero to calculate improved bounds when Best-of-All node selection strategy is used (default 0).
|-valign="top"
|''MISQP.dfdir''||Set nonzero to select direction for Depth-First according to value of Lagrange function (default 0).
|-valign="top"
|''MISQP.cholm''||Cholesky decomposition mode.

0 - Calculate Cholesky decomposition once and reuse it.

1 - Calculate new Cholesky decomposition whenever warmstart is not active (default).
|-valign="top"
|''MISQP.cut''||Control the cutting process.
0 - No cuts (default).

1 - Use disjunctive cuts only.

2 - Complemented mixed integer rounding (CMIR) cuts only.

3 - Both disjunctive cuts and CMIR cuts.
|-valign="top"
|''MISQP.maxdc''||Maximal number of rounds for disjunctive cuts. Default 5.
|-valign="top"
|''MISQP.maxcm''||Maximal number of cuts for CMIR cuts. Default 5.
|-valign="top"
|''MISQP.phm''||Primal heuristic mode.

0 - No primal heuristics (default).

1 - Nearest integer.

2 - Feasibility pump.
|}

====Description of Outputs====

''Result'' Structure with result from optimization. The following fields are set:

{|class="wikitable"
!Output||Description
|-valign="top"
|''Result''||The structure with results (see ResultDef.m).
|-valign="top"
|''x_k''||Solution vector.
|-valign="top"
|''x_0''||Initial solution vector.
|-valign="top"
|''f_k''||Function value at optimum.
|-valign="top"
|''g_k''||Gradient of the objective function.
|-valign="top"
|''c_k''||Nonlinear constraint residuals.
|-valign="top"
|''cJac''||Nonlinear constraint gradients.
|-valign="top"
|''xState''||State of variables. Free == 0; On lower == 1; On upper == 2; Fixed == 3;
|-valign="top"
|''bState''||State of linear constraints. Free == 0; Lower == 1; Upper == 2; Equality == 3;
|-valign="top"
|''cState''||State of nonlinear constraints. Free == 0; Lower == 1; Upper == 2; Equality == 3;
|-valign="top"
|''ExitFlag''||Exit status from misqp.m (similar to TOMLAB).
|-valign="top"
|''ExitText''||Exit text from solver.
|-valign="top"
|''Inform''||MISQP information parameter.

0 - The optimality conditions are satisfied.

1 - Termination after maxit iterations.

2 - Trust region radius lower than termination tolerance of the QP solver.

3 - Penalty parameter sigma tends to infinity.

4 - Termination at infeasible iterate.

5 - Termination with zero trust region for integer variables.

6 - Length of a working array is too short.

7 - There are false dimensions.

8 - Lower or upper bound of variable violates initial value.

9 - Linear constraints are inconsistent.

11 - QL could not solver the QP after 40*(n+m) iterations.

12 - The termination accuracy is insufficient for QL.

13 - QL terminated due to internal inconsistency, division by zero.

14 - Numerical instabilities in QL.

15 - More than mnfs steps without improvements of feasible function values.

> 90 - QP sub problem error.
|-valign="top"
||''FuncEv''||Number of function evaluations.
|-valign="top"
|''GradEv''||Number of gradient evaluations.
|-valign="top"
||''ConstrEv''||Number of constraint evaluations.
|-valign="top"
|''QP.B''||Basis vector in TOMLAB QP standard.
|-valign="top"
|''Solver''||Name of solver (misqp).
|-valign="top"
|''SolverAlgorithm''||Description of the solver.
|}

===miqlTL===
====Purpose====

Solves strictly convex mixed-integer quadratic programming problems.

MIQL solves problems of the form

<div class="center">
<math>
\begin{array}{ll}
\min\limits_{x} & f(x) = \frac{1}{2} x^T F x + c^T x\\
& \\
s/t & \begin{array}{lcccl}
x_{L} & \leq & x & \leq & x_{U} \\
b_{L} & \leq & A x & \leq & b_{U} \\
\end{array}
\end{array}
</math>
</div>

where <math>c, x, x_L, x_U \in \mathbb{R}^n</math>, <math>F \in \mathbb{R}^{n \times n}</math> and positive definite, <math>A \in \mathbb{R}^{m_1 \times n}</math>, and <math>b_L,b_U \in \mathbb{R}^{m_1}</math>.

The variables <math>x \in I</math>, the index subset of <math>1,...,n</math>, are restricted to be integers.

If F is empty, an LP or MILP problem is solved.

====Calling Syntax====

<pre style="font-size: 12px">
Prob = miqpAssign( ... );
Result = tomRun('miql',Prob,...);
</pre>

====Description of Inputs====

''Prob ''Problem description structure. The following fields are used:

{|class="wikitable"
!Field||Description
|-valign="top"
|''x_L, x_U''||Bounds on variables.
|-valign="top"
|''b_L, b_U''||Bounds on linear constraints.
|-valign="top"
|''A''||Linear constraint matrix.
|-valign="top"
|''QP.c ''||Linear coefficients in objective function.
|-valign="top"
|''QP.F ''||Quadratic matrix of size n x n.
|-valign="top"
|''PriLevOpt''||Print Level in solver (0-4)
0 - No output. Default

1 - Root QP and final performance summary.

2 - Additional branch and bound iterations counter.

3 - Additional total output from all generated subproblems.

4 - Additional formal details.
|-valign="top"
|''MIP.IntVars''||Vector of indices of the integer variables.
|-valign="top"
|''MIQL.PrintFile ''||Name of MIQL print file. Amount and type of printing determined by PriLevOpt. Default name ''miql.txt''.
|-valign="top"
|''MIQL.eps''||Desired final accuracy. The parameter value should not be smaller than the underlying machine precision.
|-valign="top"
|''MIQL.acc''||The accuracy to identify integer values for integer variables. If acc is less than machine precision, e.g., acc = 0, then acc is set to the machine precision.
|-valign="top"
|''MIQL.ibr''||Branching rule
1 - Maximal fractional branching (default).

2 - Minimal fractional branching.
|-valign="top"
|''MIQL.ins''||Node selection strategy
1 - Best of all (large search trees) (default).

2 - Best of two (warmstarts, less memory for search tree.)

3 - Depth first (good warmstarts, smallest memory, many QPs.)
|-valign="top"
|''MIQL.maxnde''||Maximal number of nodes, e.g., 100,000.
Default: (2*n + 2*m + 6)^2 for cut == 1,3), (2*n + m + 4)^2 otherwise.
|-valign="top"
|''MIQL.wstart''||Maximal number of successive warmstarts to avoid numerical instabilities. Default 100.
|-valign="top"
|''MIQL.impb''||1 - Calculate improved bounds when best-of-all node selection strategy (ins = 1) is used.

0 - Default.
|-valign="top"
|''MIQL.dfdir''||1 Select direction for depth-first node selection strategy (ins = 3) according to value of Lagrange function.

0 - Default.
|-valign="top"
|''MIQL.cholm''||Cholesky decomposition mode.

0 - Calculate Cholesky decomposition once and reuse it.

1 - Calculate new Cholesky decomposition whenever warmstart is not active. Default.
|-valign="top"
|''MIQL.cut''||Control the cutting process.
0 - No cuts. Default

1 - Use disjunctive cuts only.

2 - Complemented mixed integer rounding (CMIR) cuts only.

3 - Both disjunctive cuts and CMIR cuts.
|-valign="top"
|''MIQL.maxdc''||Maximal number of rounds for disjunctive cuts. Default 1, if disjunctive cuts should be generated.
|-valign="top"
|''MIQL.maxcm''||Maximal number of cuts for CMIR cuts. Default 1, if CMIR cuts should be generated.
|-valign="top"
|''MIQL.phm''||Primal heuristic mode.

0 - No primal heuristics. Default

1 - Nearest integer.

2 - Feasibility pump.
|}

====Description of Outputs====

''Result'' Structure with result from optimization. The following fields are set:

{|class="wikitable"
!Output||Description
|-valign="top"
|''Result''||The structure with results (see ResultDef.m).
|-valign="top"
|''f_k''||Function value at optimum.
|-valign="top"
|''x_k''||Solution vector.
|-valign="top"
|''x_0''||Initial solution vector.
|-valign="top"
|''g_k''||Exact gradient computed at optimum.
|-valign="top"
|''xState''||State of variables. Free == 0; On lower == 1; On upper == 2; Fixed == 3;
|-valign="top"
|''bState''||State of linear constraints. Free == 0; Lower == 1; Upper == 2; Equality == 3;
|-valign="top"
|''v_k''||Lagrangian multipliers (for bounds + dual solution vector).
|-valign="top"
|''ExitFlag''||Exit status from miql.m (similar to TOMLAB).
|-valign="top"
|''Inform''||MIQL information parameter.

-4 - Branch and Bound root QP could not be solved.

-3 - Relaxed QP without feasible solution.

-2 - A feasible solution could not be computed by maxnde subproblems.

-1 - A feasible solution does not exist.

0 - The optimal solution is found.

1 - A feasible solution is found, but tree search is terminated because of reaching maxnde nodes.

2 - Index in Prob.MIP.intVars out of bounds.

3 - Internal inconsistency of continuous QP.

4 - Length of a work array is too short.

5 - Sizes are incorrectly set.

6 - An integer option for Branch and Bound is incorrectly set.

7 - Independent Lagrangian multipliers could not be calculated, working arrays are too small, increase maxnde.

8 - Print file or print level is incorrectly set.

9 - Lower variable bound greater than upper variable bound.

11 - Subsolver QL could not solve QP after a maximal number of 40*(n+m) iterations.

12 - The termination accuracy is insufficient for QL to satisfy its convergence criteria.

13 - QL terminated due to an internal inconsistency, e.g., division by zero.

14 - Numerical instabilities prevent successful termination of QL.

> 90 - Constraints are inconsistent and constraint number Inform - 100 is causing the conflict. The problem has no feasible solution.
|-valign="top"
|''rc''||Reduced costs. If ninf=0, last m == -v_k.
|-valign="top"
|''Iter''||Number of iterations.
|-valign="top"
||''FuncEv''||Number of function evaluations. Set to Iter.
|-valign="top"
|''GradEv''||Number of gradient evaluations. Set to Iter.
|-valign="top"
||''ConstrEv''||Number of constraint evaluations. Set to 0.
|-valign="top"
|''QP.B''||Basis vector in TOMLAB QP standard.
|-valign="top"
|''MinorIter''||Number of minor iterations. NOT SET.
|-valign="top"
|''Solver''||Name of solver (miql).
|-valign="top"
|''SolverAlgorithm''||Description of the solver.
|-valign="top"
|''MIQL.cutges''||Total number of cutting planes.
|-valign="top"
|''MIQL.nodes''||Total number of branch and bound nodes.
|-valign="top"
|''MIQL.ctime''||Time spent generating cutting planes.
|-valign="top"
|''MIQL.bbtime''||Time spent for branch and bound process.
|-valign="top"
|''MIQL.cutgap''||Gap reduced by cutting planes compared to original relaxed solution.
|-valign="top"
|''MIQL.rlxopt''||Relaxed optimal value.
|-valign="top"
|''MIQL.gencut''||Nonzero if cuts were generated.
|}

===qlTL===

====Purpose====
Solves strictly convex quadratic programming problems.

QL solves problems of the form

<div class="center">
<math>
\begin{array}{ll}
\min\limits_{x} & f(x) = \frac{1}{2} x^T F x + c^T x\\
& \\
s/t & \begin{array}{lcccl}
x_{L} & \leq & x & \leq & x_{U} \\
b_{L} & \leq & A x & \leq & b_{U} \\
\end{array}
\end{array}
</math>
</div>

where <math>c, x, x_L, x_U \in \mathbb{R}^n</math>, <math>F \in \mathbb{R}^{n \times n}</math> and positive definite,
<math>A \in \mathbb{R}^{m_1 \times n}</math>, and <math>b_L,b_U \in \mathbb{R}^{m_1}</math>.

====Calling Syntax====

<pre style="font-size: 12px">
Prob = qpAssign( ... );
Result = tomRun('ql',Prob,...);
</pre>

====Description of Inputs====

''Prob ''Problem description structure. The following fields are used:

{|class="wikitable"
!Field||Description
|-valign="top"
|''x_L, x_U''||Bounds on variables.
|-valign="top"
|''b_L, b_U''||Bounds on linear constraints.
|-valign="top"
|''A''||Linear constraint matrix.
|-valign="top"
|''QP.c ''||Linear coefficients in objective function.
|-valign="top"
|''QP.F ''||Quadratic matrix of size n x n.
|-valign="top"
|''PriLevOpt''||Print Level in solver (0 = off, 1 = only final error message).
|-valign="top"
|''QL.eps''||Desired final accuracy. The parameter value should not be smaller than the underlying machine precision.
|-valign="top"
|''QL.PrintFile ''||Name of print file. Amount/print type determined by optPar(1). Default name ''ql.txt''.
|}

====Description of Outputs====

''Result'' Structure with result from optimization. The following fields are set:

{|class="wikitable"
!Output||Description
|-valign="top"
|''Result''||The structure with results (see ResultDef.m).
|-valign="top"
|''f_k''||Function value at optimum.
|-valign="top"
|''x_k''||Solution vector.
|-valign="top"
|''x_0''||Initial solution vector.
|-valign="top"
|''g_k''||Exact gradient computed at optimum.
|-valign="top"
|''xState''||State of variables. Free == 0; On lower == 1; On upper == 2; Fixed == 3;
|-valign="top"
|''bState''||State of linear constraints. Free == 0; Lower == 1; Upper == 2; Equality == 3;
|-valign="top"
|''v_k''||Lagrangian multipliers (for bounds + dual solution vector).
|-valign="top"
|''ExitFlag''||Exit status from ql.m (similar to TOMLAB).
|-valign="top"
|''Inform''||QL information parameter.

0 - Optimal solution with unique minimizer found

1 - Too many iterations

2 - Accuracy insufficient to attain convergence

3 - Internal inconsistency, division by zero

5 - An input parameter was invalide

> 100 - Constraints are inconsistent and Inform=100+iCon where iCon denotes the index of the constraint causing the conflict. The problem has no feasible solution.
|-valign="top"
|''rc''||Reduced costs. If ninf=0, last m == -v_k.
|-valign="top"
|''Iter''||Number of iterations.
|-valign="top"
||''FuncEv''||Number of function evaluations. Set to Iter.
|-valign="top"
|''GradEv''||Number of gradient evaluations. Set to Iter.
|-valign="top"
||''ConstrEv''||Number of constraint evaluations. Set to 0.
|-valign="top"
|''QP.B''||Basis vector in TOMLAB QP standard.
|-valign="top"
|''MinorIter''||Number of minor iterations. NOT SET.
|-valign="top"
|''Solver''||Name of solver (ql).
|-valign="top"
|''SolverAlgorithm''||Description of the solver.
|}

MIPNLP ecpMINLP

2014-10-09T13:31:38Z

Bjorn: /* Prob structure */

{{Part Of Manual|title=the MIPNLP Manual|link=[[MIPNLP|MIPNLP Manual]]}}
==Purpose==

ecpMINLP solves convex mixed-integer nonlinear programming problems (MINLP).

''ecpMINLP ''solves problems of the form

<math>
\begin{array}{cccccc}
\min\limits_{x} & f(x) \\s/t & x_{L} & \leq & x & \leq & x_{U} \\& b_{L} & \leq & Ax & \leq & b_{U} \\& c_{L} & \leq & c(x) & \leq & c_{U} \\& & & {x_{j} \in \mathbb{N} \ \ \forall j \in I} \\
\end{array}
</math>

where <math>x,x_{L},x_{U}\in \mathbb{R}^{n}</math> , <math>c(x),c_{L},c_{U}\in
\mathbb{R}^{m_{1}}</math> , <math>A\in \mathbb{R}^{m_{2}\times n}</math> and
<math>b_{L},b_{U}\in \mathbb{R}^{m_{2}}</math>. The variables <math>x \in I</math> , the
index subset of <math>1,...,n</math> are restricted to be integers.

==Calling Syntax==

Driver call, including printing with level 2:
<source lang="matlab">
Result = tomRun('ecpMINLP',Prob,2);
</source>
Direct solver call:
<source lang="matlab">
Result = ecpMINLP(Prob);
PrintResult(Result);
Result = tomRun('ecpMINLP',Prob,...)
</source>

=== Warm Start ===
Warm start is currently not supported, but might be included in a future release.

==Inputs==

===Prob structure===
The '''TOMLAB''' problem structure

{|class="wikitable"
!colspan="2"|The following fields are used in the problem description structure Prob
|-
|'''Field'''||'''Description'''
|-
|''x_L''||Lower bounds on x.
|-
|''x_U''||Upper bounds on x.
|-
|''A''||The linear constraint matrix.
|-
|''b_L''||Lower bounds on linear constraints.
|-
|''b_U''||Upper bounds on linear constraints.
|-
|''c_L''||Lower bounds on nonlinear constraints.
|-
|''c_U''||Upper bounds on nonlinear constraints.
|-
|''f_Low''||Lower bound on solution.
|-
|''x_0''||Starting point.
|-valign="top"
|''MaxCPU''||Maximal CPU Time (in seconds) to be used by ecpMINLP, stops with best point found
|-valign="top"
|''PriLev''||Print level in ecpMINLP (default 1). Also see optParam.IterPrint
{|class="wikitable"
!value||output
|-
|=0||Silent.
|-
|>0||Initial information and convergence results.
|-
|>1||Output a line whenever the solution has improved, containing:
nIterations, nCuts, nCuts with criteria fulfilled, nLinearizations, nSpecialCuts, best solution.
|-
|>2||Output a line every iteration with the following information:
{|class="wikitable"
!label||description
|-
|It ||Iterations
|-
|nECP ||Number of extended cutting planes (ECP)
|-
|nAlpha>=lim||Number of ECP with criteria fulfilled
|-
|nL ||Number of linearizations
|-
|nSECP ||Number of special case ECP (created from constraint on bound)
|-
|fIPMin ||Objective of best solution at current iteration
|}
|-
|>3||Output a description of each step in the MINLP algorithm
|-
|>4||Output additional numerical information in some algorithm steps
|-
|>5||Output information in substeps (preprocessing, line search)
|}
|-valign="top"
|''PriLevOpt''||Print level in sub-solvers, see the documentation for the solver
|-valign="top"
|''SolverMIP''||Name of the solver used for MIP subproblems. If TOMLAB /gurobi is installed, gurobi is the default solver. If TOMLAB /CPLEX is installed, CPLEX is second choice as default. Otherwise the default solver is found calling GetSolver('mip',1); Supported as subsolvers are gurobi, CPLEX, mipSolve, milpSolve and cutplane.
|-
|''SolverLP''||Name of the solver used for LP subproblems when SolverMIP == mipSolve
|-
|''MIP''||Structure with parameters specific to mixed integer optimization. See the table below describing the fields used in the MIP structure.
|-
|''ECPMINLP''||Structure with parameters specific to the ecpMINLP solver. See the table below describing the fields used in the ECPMINLP structure.
|-
|''optParam''||Structure with general optimization parameters. See the table below describing the fields used in the optParam structure.
|}

===MIP structure===
Substructure in Prob with parameters related to mixed integer programming.

{|class="wikitable"
!colspan="2"|'''fields used in Prob.MIP''':
|-
|'''Field'''||'''Description'''
|-valign="top"
|''IntVars''||If empty, all variables are assumed non-integer. If islogical(IntVars) (=all elements are 0/1), then 1 = integer variable, 0 = continuous variable. If any element ''>''1, IntVars is the indices for integer variables.
|-valign="top"
|''fIP''||An upper bound on the IP value wanted. Makes it possible to cut branches and avoid node computations. Used even if xIP not given.
|-valign="top"
|''xIP''||The x-values giving the fIP value, if a solution (xIP,fIP) is known.
|-valign="top"
|''DualGap''||ecpMINLP stops if the duality gap is less than DualGap
DualGap = 1, stop at first integer solution, e.g. DualGap = 0.01,stop if solution < 1% from optimal solution.
 The lower bound Prob.f_Low is used, (default -1.0e300), which can also be set by the user. If f_Low has not been changed from default the lower bound is obtained from the initial solution of a relaxed problem, but only when ECPMINLP.INIT_BND is 1 or 2 (default).
 Default DualGap is -1, not used.
|-valign="top"
|''PPP''||Pre-processing and probing, default is 0. 
0 Not used. Default. 
1 Apply initially on MINLP problem. 
2 Apply each iteration before solving MILP subproblem.
|-
|''ROUNDH''||If nonzero, a rounding heuristics will be used on the initial NLP solution in order to obtain an initial integer solution. Requires ECPMINLP.INIT_BND enabled. Default is 1, enabled.
|}

===ECPMINLP structure===
Substructure in ''Prob'' with solver-specific options.

{|class="wikitable"
!colspan="2"|fields used in Prob.ECPMINLP
|-
|'''Field'''||'''Description'''
|-valign="top"
|''beta''||Multiplier when increasing alpha after an infeasible MILP solution.
 Alpha is a parameter individually adjusting each cutting plane, starting at 1.0 and increasing until meeting a certain criterion. Default value for beta is 1.3.
|-valign="top"
|''gamma''||Multiplier when increasing alpha when MILP solution does not violate any nonlinear contraints, but still does not decrease the upper bound of the objective.
 Alpha is a parameter individually adjusting each cutting plane, starting at 1.0 and increasing until meeting a certain criterion. Default value for gamma is 2.0.
|-valign="top"
|''PREALLOC''||Flag enabling preallocation of memory for cutting planes and linearizations.
 0 No preallocation, dynamic growth of arrays. Current default.
 1 Preallocate arrays.
|-valign="top"
|''INIT_BND''||Selects method for setting lower bound when f_Low not changed from default.
{|class="wikitable"
!value||method
|-valign="top"
|0 ||No extra initial lower bound.
|-valign="top"
|1 ||Use default TOMLAB NLP solver on problem with relaxed integer constraints. Add a linearization if a feasible MINLP solution was found.
|-valign="top"
|2 ||Add an initial linearization as long as a feasdbile NLP solution was found. The linearization is a simple lower bound on the MILP objective. Default.
|-valign="top"
|3 ||Same as 2, but also use the gradient in the linearization. This might improve the solution process for some problems where no solution can be found otherwise. But for many problems, using this initial linearization cuts off a feasbiel region and slows down or even hinders the solver completely. Recommended to only use as a last resort.
|}
|-valign="top"
|''SETTOL''||Flag enabling changing tolerances, described below under optParam.eps_x, optParam.eps_x and optParam.eps_f.
 0 Default. Using the recommended solver default values, 1.0e-3.
 1 Tolerances can be changed, taken from Prob.optParam.
|-valign="top"
|''INTSOLLIM_INCR''||Integer option when using CPLEX as MIP subsolver.
 Define how much the CPLEX parameter INTSOLLIM increases when a feasible solution is not optimal and all alpha values have met their criteria.
 If set to zero, optimal strategy will be used immediately instead, without any gradual increase of INTSOLLIM.
 Default is 1.
|-valign="top"
|''USECUTPOOL''||Set nonzero to use a pool for the alpha-regulated extended cutting planes.
 Cuts not active in the MILP-solution for CUTDELBND iterations in a row will be inactivated (removed from the MILP-problem) until they are violated in a new solution.
 Default is 0, not used.
|-valign="top"
|''CUTDELBND''||The number of consecutive times an extended cutting plane can be inactive before it gets removed and put into the inactive pool, if the option USECUTPOOL is set nonzero.
 Default is 15 times.
|-valign="top"
|''MAXITNOIMP''||Limit on the number of successive iterations allowed without any improvements at all to neither objective nor solution point before the solver terminates
 Default is 2.
|-valign="top"
|''USENLP''||Set nonzero to use an NLP sub-solver on the original problem with the integer variables fixed at values from the latest MILP solution. Default is 1, enabled.
|-valign="top"
|''USERESELECT''||Set nonzero to enable cut reselection heuristics. Default is 1, enabled.
|-valign="top"
|''SCALECUTS''||Set nonzero to scale cuts before they are added to the MILP problem. Scaling is done by dividing the cut with its norm. Default is 1, enabled.
|}

===optParam Structure===
Substructure in ''Prob'' with general optimization parameters.

{|class="wikitable"
!colspan="2"|fields used in Prob.optParam
|-
|'''Field'''||'''Value'''
|-valign="top"
|''MaxIter''||Maximal number of iterations, default 10000
|-valign="top"
|''IterPrint''||Print short information each iteration. Setting PriLev > 1 also enables IterPrint, setting it to 1.
|-valign="top"
|''eps_x''||Linear constraint violation convergence tolerance. Default is 2.0e-6
|-valign="top"
|''eps_g''||Constraint violation convergence tolerance. Default is 1.0e-7
|-valign="top"
|''eps_f''||Optimality tolerance. Default is 1.0e-8
|}

''NOTE:'' For the solver to use these tolerances, the flag ''ECPMINLP.SETTOL'' must be set to nonzero.

==Outputs==

{| class="wikitable"
!''Result''||colspan="2"|Structure with result from optimization. The following fields are changed:
|-
|||''Iter ''||Number of iterations.
|-valign="top"
|||''ExitFlag ''||Exit flag.
 0: Solution found, or integer solution with duality gap less than user tolerance.
 1: Maximal number of iterations reached.
 2: Empty feasible set, no integer solution found.
 3: Problem in subsolver, see Inform value.
 99: Maximal CPU Time used (cputime > Prob.maxCPU
|-
|||''Inform''||Inform for ExitFlag != 3
 0: Global solution found.
 1: Local solution found.
 2: No solution found.
 >2: Inform value from subsolver.
|-
|||''ExitText''||Text string giving ''ExitFlag'' and ''Inform'' information.
|-valign="top"
|||''DualGap''||Relative duality gap, max(0,fIPMin-fLB)/-fIPMin-, if fIPMin =0; max(0,fIPMin-fLB) if fIPMin == 0. If fIPMin =0: Scale with 100, 100*Dual- Gap, to get the percentage duality gap. For absolute value duality gap: scale with fIPMin, fIPMin * DualGap
|-
|||''x_k''||Solution.
|-valign="top"
|||''f_k''||Function value at optimum.
|-
|||''g_k''||Gradient vector at optimum.
|-
|||''c_k''||Constraint values at optimum.
|-
|||''cJac''||Constraint derivative values at optimum.
|-
|||''xState''||State of each variable, described in [[TOMLAB_Appendix_B#Table:_The_state_variable_xState_for_the_variable.|TOMLAB Appendix B]].
|-
|||''bState''||State of each constraint, described in [[TOMLAB_Appendix_B#Table:_The_state_variable_bState_for_each_linear_constraint.|TOMLAB Appendix B]].
|-
|||''cState''||State of each general constraint, described in [[TOMLAB_Appendix_B#Table:_The_state_variable_cState_for_each_nonlinear_constraint.|TOMLAB Appendix B]].
|-
|||''x_0''||Starting point x_0.
|-
|||''Solver''||Solver used ('ecpMINLP').
|-
|||''SolverAlgorithm''||Description of method used.
|-
|||''Prob''||Problem structure used.
|}

== Algorithm==
ecpMINLP Solves convex or pseudo-convex mixed-integer nonlinear programming problems using an extended cutting plane algorithm with cuts regulated by a parameter-vector alpha. Cuts and linearizations are added to MIP subproblem which is then solved by a subsolver in each iteration.

The solver algorithm is mainly based on the paper 'Solving Pseudo-Convex Mixed Integer Optimization Problems by Cutting Plane Techniques' by Tapio Westerlund and Ray Pörn, published in Optimization and Engineering 3, 253-280, 2002, with some modifications.

Most prominent features in addition to the ones described in the main reference above are
* Solving the relaxed NLP problem initially to obtain a lower bound on the solution.
* A rounding heuristics performed on the initial NLP solution in order to obtain an initial upper bound on the initial solutions.
* Optional use of a cutpool for the alpha-regulated extended cutting planes.

[[Category:MIPNLP]]

MilpSolve

2014-08-12T14:58:22Z

Bjorn: /* MIP structure, substructure of Prob */

[[Category:Solvers]]
==Purpose==

Solve mixed integer linear programming problems (MILP).

''MILPSOLVE'' solves problems of the form

<math>
\begin{array}{cccccc}
\min\limits_{x} & f(x) & = & c^{T}x & \\s/t & x_{L} & \leq & x & \leq & x_{U} \\& b_{L} & \leq & Ax & \leq & b_{U} \\& & & {x_{j} \in \mathbb{N} \ \ \forall j \in I} \\
\end{array}
</math>

where <math>c, x, x_L, x_U \in \mathbb{R}^{n}</math> , <math>A\in\mathbb{R}^{m\times n}</math> and <math>b_L, b_U \in \mathbb{R}^{m}</math>. The variables <math>x \in I</math> , the index subset of <math>1,...,n</math> are restricted to
be integers.

==Calling Syntax==

<source lang="matlab">
Result = tomRun('MILPSOLVE',Prob, 1); or
Prob = ProbCheck(Prob, 'MILPSOLVE');
Result = milpsolveTL(Prob);
PrintResult(Result,1);
</source>

==Inputs==

===Prob structure===

{| class="wikitable"
!colspan="2"|The following fields are used in ''Prob'':
|-valign="top"
||'''FieldName'''||'''Value'''
|-
||''x_L, x_U''||Lower and upper bounds on variables. (Must be dense).
|-
||''b_L, b_U''||Lower and upper bounds on linear constraints. (Must be dense).
|-
||''A''||Linear constraint matrix. (Sparse or dense).
|-
||''QP.c''||Linear objective function coefficients, size ''nx''1.
|-
||''BIG''||Definition of infinity. Default is 1e30.
|-valign="top"
||''LargeScale''||Defines if milpsolveTL will convert the A matrix to a sparse matrix or not.

Largescale ! = 0 - sparse

LargeScale = 0 - dense

Default is to use the A matrix just as it is defined.
|-valign="top"
||''PriLevOpt''||Specifies the printlevel that will be used by MILPSOLVE.

0 (NONE) No outputs

1 (NEUTRAL) Only some specific debug messages in debug print rou- tines are reported.

2 (CRITICAL) Only critical messages are reported. Hard errors like instability, out of memory.

3 (SEVERE) Only severe messages are reported. Errors.

4 (IMPORTANT) Only important messages are reported. Warnings and Errors.

5 (NORMAL) Normal messages are reported.

6 (DETAILED) Detailed messages are reported. Like model size, con- tinuing B&B improvements.

7 (FULL) All messages are reported. Useful for debugging purposes and small models.

Default print level is 0, no outputs. PriLevOpt ''< ''0 is interpreted as 0, and larger than 7 is interpreted as 7.
|-valign="top"
||''MaxCPU''||Maximal CPU Time (in seconds) to be used by MILPSOLVE, stops with best point found.
|-valign="top"
||''MILPSOLVE''||Substructure defininig milpSolve specific options, see the table below.
|-valign="top"
||''MIP''||Substructure with parameters specific to mixed integer programming problems in TOMLAB, see the table below.
|}

===MILPSOLVE structure, substructure of [[MilpSolve#Prob structure|Prob]]===
Solver specific options structure.
{| class="wikitable"
!''MILPSOLVE''||colspan="2"|The following fields are used in ''Prob.MILPSOLVE'':
|-valign="top"
|||'''Field'''||'''Value'''
|-valign="top"
|||''ANTI_DEGEN''||Binary vector. If empty, no anti-degeneracy handling is applied. If the length (i) of the vector is less than 8 elements,only the i first modes are considered. Also if i is longer than 8 elements, the elements after element8 are ignored.

ANTI_DEGEN specifies if special handling must be done to reduce de- generacy/cycling while solving. Setting this flag can avoid cycling, but can also increase numerical instability.

ANTIDEGEN FIXEDVARS ! = 0 Check if there are equality slacks in the basis and try to drive them out in order to reduce chance of degeneracy in Phase 1.

ANTIDEGEN COLUMNCHECK != 0

ANTIDEGEN STALLING != 0

ANTIDEGEN NUMFAILURE != 0

ANTIDEGEN LOSTFEAS != 0

ANTIDEGEN INFEASIBLE != 0

ANTIDEGEN DYNAMIC != 0

ANTIDEGEN DURINGBB != 0
|-valign="top"
|||''basis''||If empty or erroneous, default basis is used. Default start base is the all slack basis (the default simplex starting basis).

Prob.MILPSOLVE.basis stores the basic variables. If an element is less then zero then it means on lower bound, else on upper bound. Element 0 of the array is unused. The default initial basis is bascolumn[x] = -x. By MILPSOLVE convention, a basic variable is always on its lower bound, meaning that basic variables is always represented with a minus sign.

When a restart is done, the basis vector must be assigned a correct starting basis.
|-valign="top"
|||''BASIS_CRASH''||The set_basiscrash function specifies which basis crash mode MILP- SOLVE will used.

When no base crash is done (the default), the initial basis from which MILPSOLVE starts to solve the model is the basis containing all slack or artificial variables that is automatically associates with each constraint.

When base crash is enabled, a heuristic "crash procedure" is executed before the first simplex iteration to quickly choose a basis matrix that has fewer artificial variables. This procedure tends to reduce the num- ber of iterations to optimality since a number of iterations are skipped. MILPSOLVE starts iterating from this basis until optimality.

BASIS_CRASH ! = 2 - No basis crash

BASIS_CRASH = 2 - Most feasible basis

Default is no basis crash.
|-valign="top"
|||''BB_DEPTH_LIMIT''||Sets the maximum branch-and-bound depth. This value makes sense only if there are integer, semi-continuous or SOS variables in the model so that the branch-and-bound algorithm is used to solve the model. The branch-and-bound algorithm will not go deeper than this level. When BB DEPTH LIMIT i set to 0 then there is no limit to the depth. The default value is -50. A positive value means that the depth is absolute. A negative value means a relative B&B depth. The "order" of a MIP problem is defined to be 2 times the number of binary variables plus the number of SC and SOS variables. A relative value of -x results in a maximum depth of x times the order of the MIP problem.
|-valign="top"
|||''BB_FLOOR_FIRST''||Specifies which branch to take first in branch-and-bound algorithm. Default value is 1.

BB_FLOOR_FIRST = 0 (BRANCH CEILING) Take ceiling branch first

BB_FLOOR_FIRST = 1 (BRANCH FLOOR) Take floor branch first

BB_FLOOR_FIRST = 2 (BRANCH AUTOMATIC) MILPSOLVE decides which branch being taken first
|-valign="top"
|||''BB_RULE''||Specifies the branch-and-bound rule. Default value is 0.

BB_RULE = 0 (NODE_FIRSTSELECT) Select lowest indexed non- integer column

BB_RULE = 1 (NODE_GAPSELECT) Selection based on distance from the current bounds

BB_RULE = 2 (NODE_RANGESELECT) Selection based on the largest current bound

BB_RULE = 3 (NODE_FRACTIONSELECT) Selection based on largest fractional value

BB_RULE = 4 (NODE_PSEUDOCOSTSELECT4) Simple, unweighted pseudo-cost of a variable

BB_RULE = 5 (NODE_PSEUDONONINTSELECT) This is an ex- tended pseudo-costing strategy based on minimizing the number of in- teger infeasibilities.

BB RULE = 6 (NODE_PSEUDORATIOSELECT) This is an extended pseudo-costing strategy based on maximizing the normal pseudo-cost divided by the number of infeasibilities. Effectively, it is similar to (the reciprocal of ) a cost/benefit ratio.

BB_RULE = 7 (NODE_USERSELECT)
|-valign="top"
|||''BB_RULE_ADD''||Additional values for the BB RULE. BB RULE is a vector. If the length i of the vector is less than 10 elements, only the i first modes are considered. Also if i is longer than 10 elements, the elements after element 10 is ignored.

BB_RULE ADD(1) ! = 0 (NODE_WEIGHTREVERSEMODE)

BB_RULE ADD(2) ! = 0 (NODE BRANCHREVERSEMODE) In case when get bb floorfirst is BRANCH AUTOMATIC, select the opposite direction (lower/upper branch) that BRANCH AUTOMATIC had cho- sen.

BB_RULE_ADD(3) ! = 0 (NODE_GREEDYMODE)

BB_RULE_ADD(4) ! = 0 (NODE_PSEUDOCOSTMODE)

BB_RULE_ADD(5) ! = 0 (NODE_DEPTHFIRSTMODE) Select the node that has already been selected before the number of times

BB_RULE_ADD(6) ! = 0 (NODE_RANDOMIZEMODE)

BB_RULE_ADD(7) ! = 0 (NODE_DYNAMICMODE) When NODE DEPTHFIRSTMODE is selected, switch off this mode when a first solution is found.

BB_RULE_ADD(8) ! = 0 (NODE_RESTARTMODE)

BB_RULE_ADD(9) ! = 0 (NODE_BREADTHFIRSTMODE) Select the node that has been selected before the fewest number of times or not at all BB RULE ADD(10) ! = 0 (NODE_AUTOORDER)
|-valign="top"
|||''BFP''||Defines which Basis Factorization Package that will be used by MILP- SOLVE.

BFP = 0 : LUSOL

BFP = 1 : built in etaPHI from MILPSOLVE v3.2

BFP = 2 : Additional etaPHI BFP = 3 : GLPK

Default BFP is LUSOL.
|-valign="top"
|||''BREAK_AT_FIRST''||Specifies if the branch-and-bound algorithm stops at the first found so- lution (BREAK_AT_FIRST != 0) or not (BREAK_AT_FIRST = 0). De- fault is not to stop at the first found solution.
|-valign="top"
|||''BREAK_AT_VALUE''||Specifies if the branch-and-bound algorithm stops when the object value is better than a given value. The default value is (-) infinity.
|-valign="top"
|||''EPAGAP''||Specifies the absolute MIP gap tolerance for the branch and bound algo- rithm. This tolerance is the difference between the best-found solution yet and the current solution. If the difference is smaller than this toler- ance then the solution (and all the sub-solutions) is rejected. The default value is 1e-9.
|-valign="top"
|||''EPGAP''||Specifies the relative MIP gap tolerance for the branch and bound algo- rithm. The default value is 1e-9.
|-valign="top"
|||''EPSB''||Specifies the value that is used as a tolerance for the Right Hand Side (RHS) to determine whether a value should be considered as 0. The default epsb value is 1.0e-10
|-valign="top"
|||''EPSD''||Specifies the value that is used as a tolerance for reduced costs to deter- mine whether a value should be considered as 0. The default epsd value is 1e-9. If EPSD is empty, EPSD is read from ''Prob.optParam.eps f''.
|-valign="top"
|||''EPSEL''||Specifies the value that is used as a tolerance for rounding values to zero. The default epsel value is 1e-12.
|-valign="top"
|||''EPSINT''||Specifies the tolerance that is used to determine whether a floating- point number is in fact an integer. The default value for epsint is 1e-7. Changing this tolerance value can result in faster solving times, but the solution is less integer.
|-valign="top"
|||''EPSPERTURB''||Specifies the value that is used as perturbation scalar for degenerative problems. The default epsperturb value is 1e-5.
|-valign="top"
|||''EPSPIVOT''||Specifies the value that is used as a tolerance pivot element to determine whether a value should be considered as 0. The default epspivot value is 2e-7
|-valign="top"
|||''IMPROVEMENT_LEVEL''||Specifies the iterative improvement level.

IMPROVEMENT LEVEL = 0 (IMPROVE NONE) improve none

IMPROVEMENT LEVEL = 1 (IMPROVE FTRAN) improve FTRAN

IMPROVEMENT LEVEL = 2 (IMPROVE BTRAN) improve BTRAN

IMPROVEMENT LEVEL = 3 (IMPROVE SOLVE) improve FTRAN + BTRAN.

IMPROVEMENT LEVEL = 4 (IMPROVE INVERSE) triggers automatic inverse accuracy control in the dual simplex, and when an error gap is exceeded the basis is reinverted

Choice 1,2,3 should not be used with MILPSOLVE 5.1.1.3, because of problems with the solver. Default is 0.
|-valign="top"
|||''LoadFile''||File that contains the model. If LoadFile is a nonempty string which corresponds to actual file, then the model is read from this file rather than from the Prob struct.
|-valign="top"
|||''LoadMode''||1 - LP - MILPSOLVE LP format

2 - MPS - MPS format

3 - FMPS - Free MPS format

A default value for this field does not exist. Both LoadFile and Load- Mode must be set if a problem will be loaded.

If there is something wrong with LoadMode or LoadFile, an error mes- sage will be printed and MILPSOLVE will be terminated. Leave Load- Mode and LoadFile empty if the problem not will be loaded from file.
|-
|||''LogFile''||Name of file to print MILPSOLVE log on.
|-
|||''MAXIMIZE ''||If MAXIMIZE ! = 0, MILPSOLVE is set to maximize the objective function, default is to minimize.
|-
|||''MAX_PIVOT''||Sets the maximum number of pivots between a re-inversion of the matrix. Default is 42.
|-valign="top"
|||''NEG_RANGE''||Specifies the negative value below which variables are split into a negative and a positive part. This value must always be zero or negative. If a positive value is specified, then 0 is taken. The default value is -1e6.
|-valign="top"
|||''PRESOLVE''||Vector containing possible presolve options. If the length i of the vector is less than 7 elements, only the i first modes are considered. Also if i is longer than 7 elements, the elements after element 7 is ignored.

PRESOLVE(1) ! = 0 (PRESOLVE ROWS) Presolve rows

PRESOLVE(2) ! = 0 (PRESOLVE COLS) Presolve columns

PRESOLVE(3) ! = 0 (PRESOLVE LINDEP) Eliminate linearly depen- dent rows

PRESOLVE(4) ! = 0 (PRESOLVE SOS) Convert constraints to SOSes (only SOS1 handled)

PRESOLVE(5) ! = 0 (PRESOLVE REDUCEMIP) If the phase 1 solu- tion process finds that a constraint is redundant then this constraint is deleted.

PRESOLVE(6) ! = 0 (PRESOLVE DUALS) Calculate duals PRESOLVE(7) ! = 0 (PRESOLVE SENSDUALS) Calculate sensitivity if there are integer variables

Default is not to do any presolve.
|-valign="top"
|||''PRICING_RULE''||The pricing rule can be one of the following rules.

PRICING_RULE = 0 Select first (PRICER_FIRSTINDEX)

PRICING_RULE = 1 Select according to Dantzig (PRICER_DANTZIG)

PRICING_RULE = 2 Devex pricing from Paula Harris (PRICER_DEVEX)

PRICING_RULE = 3 Steepest Edge (PRICER STEEPESTEDGE)
|-valign="top"
|||''PRICING_MODE''||Additional pricing settings, any combination of the modes below. This is a binary vector. If the length i of the vector is less than 7 elements, only the i first modes are considered. Also if i is longer than 7 elements, the elements after element 7 is ignored.

PRICE_PRIMALFALLBACK ! = 0 In case of Steepest Edge, fall back to DEVEX in primal.

PRICE_MULTIPLE ! = 0 Preliminary implementation of the multiple pricing scheme. This means that attractive candidate entering columns from one iteration may be used in the subsequent iteration, avoiding full updating of reduced costs. In the current implementation, MILPSOLVE only reuses the 2nd best entering column alternative.

PRICE_PARTIAL ! = 0 Enable partial pricing

PRICE_ADAPTIVE ! = 0 Temporarily use First Index if cycling is detected

PRICE_RANDOMIZE ! = 0 Adds a small randomization effect to the selected pricer

PRICE_LOOPLEFT ! = 0 Scan entering/leaving columns left rather than right

PRICE_LOOPALTERNATE ! = 0 Scan entering/leaving columns alternatingly left/right

Default basis is PRICER DEVEX combined with PRICE ADAPTIVE.
|-valign="top"
|||''sa''||Struct containing information of the sensitivity analysis (SA) MILPSOLVE will perform.

sa.obj =! 0 Perform sensitivity analysis on the objective function

sa.obj = 0 Do not perform sensitivity analysis on the objective function

sa.rhs =! 0 Perform sensitivity analysis on the right hand sides.

sa.rhs = 0 Do not perform sensitivity analysis on the right hand sides.
|-valign="top"
|||''SaveFileAfter''||Name of a file to save the MILPSOLVE object after presolve.The name must be of type string (char), Example: Prob.MILPSOLVE.SaveFileAfter = 'save2' If the type is not char SaveFileBefore is set to save2.[file extension].
|-valign="top"
|||''SaveFileBefore''||Name of a file to save the MILPSOLVE object before presolve. The name must be of type string (char), Example: Prob.MILPSOLVE.SaveFileBefore = 'save1'. If the type is not char SaveFileBefore is set to save1.[file extension].
|-valign="top"
|||''SaveMode''||1 - LP - MILPSOLVE LP format

2 - MPS - MPS format

3 - FMPS - Free MPS format

If empty, the default format LP is used.
|-valign="top"
|||''SCALE_LIMIT''||Sets the relative scaling convergence criterion to the absolute value of SCALE_LIMIT for the active scaling mode. The integer part of SCALE_LIMIT specifies the maximum number of iterations. Default is 5.
|-valign="top"
|||''SCALING_ALG''||Specifies which scaling algorithm will be used by MILPSOLVE.

0 No scaling algorithm

1 (SCALE EXTREME) Scale to convergence using largest absolute value

2 (SCALE RANGE) Scale based on the simple numerical range

3 (SCALE MEAN) Numerical range-based scaling

4 (SCALE GEOMETRIC) Geometric scaling

7 (SCALE CURTISREID) Curtis-reid scaling

Default is 0, no scaling algorithm.
|-valign="top"
|||''SCALING_ADD''||Vector containing possible additional scaling parameters. If the length (i) of the vector is less than 7 elements, only the i first modes are considered. Also if i is longer than 7 elements, the elements after element 7 is ignored. SCALING ADD ! = 0 (SCALE_QUADRATIC)

SCALING ADD ! = 0 (SCALE_LOGARITHMIC) Scale to convergence using logarithmic mean of all values

SCALING_ADD ! = 0 (SCALE_USERWEIGHT) User can specify scalars

SCALING_ADD ! = 0 (SCALE_POWER2) also do Power scaling

SCALING_ADD ! = 0 (SCALE_EQUILIBRATE) Make sure that no scaled number is above 1

SCALING_ADD ! = 0 (SCALE_INTEGERS) Also scaling integer vari- ables

SCALING_ADD ! = 0 (SCALE_DYNUPDATE) Dynamic update

Default is 0, no additional mode.

Settings SCALE_DYNUPDATE is a way to make sure that scaling factors are recomputed. In that case, the scaling factors are recomputed also when a restart is done.
|-valign="top"
|||''SIMPLEX_TYPE''||Sets the desired combination of primal and dual simplex algorithms.

5 (SIMPLEX_PRIMAL_PRIMAL) Phase1 Primal, Phase2 Primal

6 (SIMPLEX_DUAL_PRIMAL) Phase1 Dual, Phase2 Primal

9 (SIMPLEX_PRIMAL_DUAL) Phase1 Primal, Phase2 Dual

10 (SIMPLEX_DUAL_DUAL) Phase1 Dual, Phase2 Dual

Default is SIMPLEX DUAL PRIMAL (6).
|-valign="top"
|||''SOLUTION_LIMIT''||Sets the solution number that will be returned. This value is only consid- ered if there are integer, semi-continuous or SOS variables in the model so that the branch-and-bound algorithm is used. If there are more solutions with the same objective value, then this number specifies which solution must be returned. Default is 1.
|-valign="top"
|||''sos''||List of structs containing data about Special Ordered Sets (SOS). See below for further description.
|}

===MIP structure, substructure of [[MilpSolve#Prob structure|Prob]]===
Options specific to mixed integer programming problems.
{| class="wikitable"
!colspan="2"|The following fields are used in ''Prob.MIP'':
|-valign="top"
||'''FieldName'''||'''Value'''
|-valign="top"
||''IntVars''||Defines which variables are integers, of general type I or binary type B Variable indices should be in the range [1,...,n].

IntVars is a logical vector ==''> x''(''find''(''IntVars > ''0)) are integers

IntVars is a vector of indices ==''> x''(''IntVars'') are integers (if [], then no integers of type I or B are defined) variables with x L=0 and x U=1, is are set to binary. It is possible to combine integer and semi-continuous type to obtain the semi-integer type.
|-valign="top"
||''fIP''||This parameter specifies the initial "at least better than" guess for objective function. This is only used in the branch-and-bound algorithm when integer variables exist in the model. All solutions with a worse objective value than this value are immediately rejected. The default is infinity.
|-valign="top"
||''SC''||A vector with indices for variables of type semi-continuous (SC), a logical vector or a scalar (see MIP.IntVars). A semi-continuous variable i takes either the value 0 or some value in the range [x L(i), x U(i)]. It is possible to combine integer and semi-continuous type to obtain the semi-integer type.
|-valign="top"
||''sos1''||List of structures defining the Special Ordered Sets of Order One (SOS1). For SOS1 set k, sos1(k).var is a vector of indices for variables of type SOS1 in set k, sos1(k).row is the priority of SOS k in the set of SOS1 and sos1(k).weight is a vector of the same length as sos1(k).var and it describes the order MILPSOLVE will weight the variables in SOS1 set k.

a low number of a row and a weight means high priority.
|-valign="top"
||''sos2''||List of n structures defining the Special Ordered Sets (SOS) of Order Two (SOS2). (see MIP.sos1)
|}

==Outputs==

{|class="wikitable"
!''Result''||colspan="2"|Structure with result from optimization. The following fields are changed:
|-
|||''x_k''||Optimal solution (or some other solution if optimum could not been found)
|-
|||''f_k''||Optimal objective value.
|-
|||''v_k''||[rc; duals]. If Reduced cost and dual variables are not available, then v_k is empty.
|-valign="top"
|||''ExitFlag''||TOMLAB information parameter.

0 = Optimal solution found.

1 = Suboptimal solution or user abort.

2 = Unbounded solution.

3 = Numerical failure.

4 = Infeasible model.

10 = Out of memory.

11 = Branch and bound stopped.
|-
|||''ExitText''||Status text from MILPSOLVE.
|-valign="top"
|||''Inform''||MILPSOLVE information parameter.

-2 = Out of memory.

0 = Optimal solution found.

1 = Suboptimal solution.

2 = Infeasible model.

3 = Unbounded solution.

4 = Degenerate solution.

5 = Numerical failure.

6 = User abort.

7 = Timeout.

10 = Branch and bound failed.

11 = Branch and bound stopped.

12 = Feasible branch and bound solution.

13 = No feasible branch and bound solution. Other = Unknown status.
|-valign="top"
|||''Iter''||The total number of nodes processed in the branch-and-bound algorithm. Is only applicable if the model contains integer variables. In the case of an LP model Result.Iter contains the number of iterations. This is however not documented.
|-
|||''MinorIter''||The total number of Branch-and-bound iterations. When the problem is LP, MinorIter equals Result.Iter
|-
|||''MILPSOLVE.basis''||Optimal basis, on the format described above under Prob.MILPSOLVE.basis.
|-
|||''MILPSOLVE.MaxLevel''||The deepest Branch-and-bound level of the last solution. Is only applicable if the model contains integer variables.
|-valign="top"
|||''MILPSOLVE.sa.objStatus''||1 successful

0 SA not requested

-1 Error: error from MILPSOLVE

-3 no SA available
|-
|||''MILPSOLVE.sa.ObjLower''||An array that will contain the values of the lower limits on the objective function.
|-
|||''MILPSOLVE.sa.ObjUpper''||An array that will contain the values of the upper limits on the objective function.
|-
|||''MILPSOLVE.sa.RhsStatus''||see MILPSOLVE.sa.objStatus.
|-
|||''MILPSOLVE.sa.RhsLower''||An array that will contain the values of the lower limits on the RHS.
|-
|||''MILPSOLVE.sa.RhsUpper''||An array that will contain the values of the upper limits on the RHS.
|-valign="top"
|||''xState''||State of each variable

0 - free variable,

1 - variable on lower bound,

2 - variable on upper bound,

3 - variable is fixed, lower bound = upper bound.
|-valign="top"
|||''bState''||State of each linear constraint

0 - Inactive constraint,

1 - Linear constraint on lower bound,

2 - Linear constraint on upper bound,

3 - Linear equality constraint.
|}

MilpSolve

2014-08-12T14:55:41Z

Bjorn: /* Prob structure */

[[Category:Solvers]]
==Purpose==

Solve mixed integer linear programming problems (MILP).

''MILPSOLVE'' solves problems of the form

<math>
\begin{array}{cccccc}
\min\limits_{x} & f(x) & = & c^{T}x & \\s/t & x_{L} & \leq & x & \leq & x_{U} \\& b_{L} & \leq & Ax & \leq & b_{U} \\& & & {x_{j} \in \mathbb{N} \ \ \forall j \in I} \\
\end{array}
</math>

where <math>c, x, x_L, x_U \in \mathbb{R}^{n}</math> , <math>A\in\mathbb{R}^{m\times n}</math> and <math>b_L, b_U \in \mathbb{R}^{m}</math>. The variables <math>x \in I</math> , the index subset of <math>1,...,n</math> are restricted to
be integers.

==Calling Syntax==

<source lang="matlab">
Result = tomRun('MILPSOLVE',Prob, 1); or
Prob = ProbCheck(Prob, 'MILPSOLVE');
Result = milpsolveTL(Prob);
PrintResult(Result,1);
</source>

==Inputs==

===Prob structure===

{| class="wikitable"
!colspan="2"|The following fields are used in ''Prob'':
|-valign="top"
||'''FieldName'''||'''Value'''
|-
||''x_L, x_U''||Lower and upper bounds on variables. (Must be dense).
|-
||''b_L, b_U''||Lower and upper bounds on linear constraints. (Must be dense).
|-
||''A''||Linear constraint matrix. (Sparse or dense).
|-
||''QP.c''||Linear objective function coefficients, size ''nx''1.
|-
||''BIG''||Definition of infinity. Default is 1e30.
|-valign="top"
||''LargeScale''||Defines if milpsolveTL will convert the A matrix to a sparse matrix or not.

Largescale ! = 0 - sparse

LargeScale = 0 - dense

Default is to use the A matrix just as it is defined.
|-valign="top"
||''PriLevOpt''||Specifies the printlevel that will be used by MILPSOLVE.

0 (NONE) No outputs

1 (NEUTRAL) Only some specific debug messages in debug print rou- tines are reported.

2 (CRITICAL) Only critical messages are reported. Hard errors like instability, out of memory.

3 (SEVERE) Only severe messages are reported. Errors.

4 (IMPORTANT) Only important messages are reported. Warnings and Errors.

5 (NORMAL) Normal messages are reported.

6 (DETAILED) Detailed messages are reported. Like model size, con- tinuing B&B improvements.

7 (FULL) All messages are reported. Useful for debugging purposes and small models.

Default print level is 0, no outputs. PriLevOpt ''< ''0 is interpreted as 0, and larger than 7 is interpreted as 7.
|-valign="top"
||''MaxCPU''||Maximal CPU Time (in seconds) to be used by MILPSOLVE, stops with best point found.
|-valign="top"
||''MILPSOLVE''||Substructure defininig milpSolve specific options, see the table below.
|-valign="top"
||''MIP''||Substructure with parameters specific to mixed integer programming problems in TOMLAB, see the table below.
|}

===MILPSOLVE structure, substructure of [[MilpSolve#Prob structure|Prob]]===
Solver specific options structure.
{| class="wikitable"
!''MILPSOLVE''||colspan="2"|The following fields are used in ''Prob.MILPSOLVE'':
|-valign="top"
|||'''Field'''||'''Value'''
|-valign="top"
|||''ANTI_DEGEN''||Binary vector. If empty, no anti-degeneracy handling is applied. If the length (i) of the vector is less than 8 elements,only the i first modes are considered. Also if i is longer than 8 elements, the elements after element8 are ignored.

ANTI_DEGEN specifies if special handling must be done to reduce de- generacy/cycling while solving. Setting this flag can avoid cycling, but can also increase numerical instability.

ANTIDEGEN FIXEDVARS ! = 0 Check if there are equality slacks in the basis and try to drive them out in order to reduce chance of degeneracy in Phase 1.

ANTIDEGEN COLUMNCHECK != 0

ANTIDEGEN STALLING != 0

ANTIDEGEN NUMFAILURE != 0

ANTIDEGEN LOSTFEAS != 0

ANTIDEGEN INFEASIBLE != 0

ANTIDEGEN DYNAMIC != 0

ANTIDEGEN DURINGBB != 0
|-valign="top"
|||''basis''||If empty or erroneous, default basis is used. Default start base is the all slack basis (the default simplex starting basis).

Prob.MILPSOLVE.basis stores the basic variables. If an element is less then zero then it means on lower bound, else on upper bound. Element 0 of the array is unused. The default initial basis is bascolumn[x] = -x. By MILPSOLVE convention, a basic variable is always on its lower bound, meaning that basic variables is always represented with a minus sign.

When a restart is done, the basis vector must be assigned a correct starting basis.
|-valign="top"
|||''BASIS_CRASH''||The set_basiscrash function specifies which basis crash mode MILP- SOLVE will used.

When no base crash is done (the default), the initial basis from which MILPSOLVE starts to solve the model is the basis containing all slack or artificial variables that is automatically associates with each constraint.

When base crash is enabled, a heuristic "crash procedure" is executed before the first simplex iteration to quickly choose a basis matrix that has fewer artificial variables. This procedure tends to reduce the num- ber of iterations to optimality since a number of iterations are skipped. MILPSOLVE starts iterating from this basis until optimality.

BASIS_CRASH ! = 2 - No basis crash

BASIS_CRASH = 2 - Most feasible basis

Default is no basis crash.
|-valign="top"
|||''BB_DEPTH_LIMIT''||Sets the maximum branch-and-bound depth. This value makes sense only if there are integer, semi-continuous or SOS variables in the model so that the branch-and-bound algorithm is used to solve the model. The branch-and-bound algorithm will not go deeper than this level. When BB DEPTH LIMIT i set to 0 then there is no limit to the depth. The default value is -50. A positive value means that the depth is absolute. A negative value means a relative B&B depth. The "order" of a MIP problem is defined to be 2 times the number of binary variables plus the number of SC and SOS variables. A relative value of -x results in a maximum depth of x times the order of the MIP problem.
|-valign="top"
|||''BB_FLOOR_FIRST''||Specifies which branch to take first in branch-and-bound algorithm. Default value is 1.

BB_FLOOR_FIRST = 0 (BRANCH CEILING) Take ceiling branch first

BB_FLOOR_FIRST = 1 (BRANCH FLOOR) Take floor branch first

BB_FLOOR_FIRST = 2 (BRANCH AUTOMATIC) MILPSOLVE decides which branch being taken first
|-valign="top"
|||''BB_RULE''||Specifies the branch-and-bound rule. Default value is 0.

BB_RULE = 0 (NODE_FIRSTSELECT) Select lowest indexed non- integer column

BB_RULE = 1 (NODE_GAPSELECT) Selection based on distance from the current bounds

BB_RULE = 2 (NODE_RANGESELECT) Selection based on the largest current bound

BB_RULE = 3 (NODE_FRACTIONSELECT) Selection based on largest fractional value

BB_RULE = 4 (NODE_PSEUDOCOSTSELECT4) Simple, unweighted pseudo-cost of a variable

BB_RULE = 5 (NODE_PSEUDONONINTSELECT) This is an ex- tended pseudo-costing strategy based on minimizing the number of in- teger infeasibilities.

BB RULE = 6 (NODE_PSEUDORATIOSELECT) This is an extended pseudo-costing strategy based on maximizing the normal pseudo-cost divided by the number of infeasibilities. Effectively, it is similar to (the reciprocal of ) a cost/benefit ratio.

BB_RULE = 7 (NODE_USERSELECT)
|-valign="top"
|||''BB_RULE_ADD''||Additional values for the BB RULE. BB RULE is a vector. If the length i of the vector is less than 10 elements, only the i first modes are considered. Also if i is longer than 10 elements, the elements after element 10 is ignored.

BB_RULE ADD(1) ! = 0 (NODE_WEIGHTREVERSEMODE)

BB_RULE ADD(2) ! = 0 (NODE BRANCHREVERSEMODE) In case when get bb floorfirst is BRANCH AUTOMATIC, select the opposite direction (lower/upper branch) that BRANCH AUTOMATIC had cho- sen.

BB_RULE_ADD(3) ! = 0 (NODE_GREEDYMODE)

BB_RULE_ADD(4) ! = 0 (NODE_PSEUDOCOSTMODE)

BB_RULE_ADD(5) ! = 0 (NODE_DEPTHFIRSTMODE) Select the node that has already been selected before the number of times

BB_RULE_ADD(6) ! = 0 (NODE_RANDOMIZEMODE)

BB_RULE_ADD(7) ! = 0 (NODE_DYNAMICMODE) When NODE DEPTHFIRSTMODE is selected, switch off this mode when a first solution is found.

BB_RULE_ADD(8) ! = 0 (NODE_RESTARTMODE)

BB_RULE_ADD(9) ! = 0 (NODE_BREADTHFIRSTMODE) Select the node that has been selected before the fewest number of times or not at all BB RULE ADD(10) ! = 0 (NODE_AUTOORDER)
|-valign="top"
|||''BFP''||Defines which Basis Factorization Package that will be used by MILP- SOLVE.

BFP = 0 : LUSOL

BFP = 1 : built in etaPHI from MILPSOLVE v3.2

BFP = 2 : Additional etaPHI BFP = 3 : GLPK

Default BFP is LUSOL.
|-valign="top"
|||''BREAK_AT_FIRST''||Specifies if the branch-and-bound algorithm stops at the first found so- lution (BREAK_AT_FIRST != 0) or not (BREAK_AT_FIRST = 0). De- fault is not to stop at the first found solution.
|-valign="top"
|||''BREAK_AT_VALUE''||Specifies if the branch-and-bound algorithm stops when the object value is better than a given value. The default value is (-) infinity.
|-valign="top"
|||''EPAGAP''||Specifies the absolute MIP gap tolerance for the branch and bound algo- rithm. This tolerance is the difference between the best-found solution yet and the current solution. If the difference is smaller than this toler- ance then the solution (and all the sub-solutions) is rejected. The default value is 1e-9.
|-valign="top"
|||''EPGAP''||Specifies the relative MIP gap tolerance for the branch and bound algo- rithm. The default value is 1e-9.
|-valign="top"
|||''EPSB''||Specifies the value that is used as a tolerance for the Right Hand Side (RHS) to determine whether a value should be considered as 0. The default epsb value is 1.0e-10
|-valign="top"
|||''EPSD''||Specifies the value that is used as a tolerance for reduced costs to deter- mine whether a value should be considered as 0. The default epsd value is 1e-9. If EPSD is empty, EPSD is read from ''Prob.optParam.eps f''.
|-valign="top"
|||''EPSEL''||Specifies the value that is used as a tolerance for rounding values to zero. The default epsel value is 1e-12.
|-valign="top"
|||''EPSINT''||Specifies the tolerance that is used to determine whether a floating- point number is in fact an integer. The default value for epsint is 1e-7. Changing this tolerance value can result in faster solving times, but the solution is less integer.
|-valign="top"
|||''EPSPERTURB''||Specifies the value that is used as perturbation scalar for degenerative problems. The default epsperturb value is 1e-5.
|-valign="top"
|||''EPSPIVOT''||Specifies the value that is used as a tolerance pivot element to determine whether a value should be considered as 0. The default epspivot value is 2e-7
|-valign="top"
|||''IMPROVEMENT_LEVEL''||Specifies the iterative improvement level.

IMPROVEMENT LEVEL = 0 (IMPROVE NONE) improve none

IMPROVEMENT LEVEL = 1 (IMPROVE FTRAN) improve FTRAN

IMPROVEMENT LEVEL = 2 (IMPROVE BTRAN) improve BTRAN

IMPROVEMENT LEVEL = 3 (IMPROVE SOLVE) improve FTRAN + BTRAN.

IMPROVEMENT LEVEL = 4 (IMPROVE INVERSE) triggers automatic inverse accuracy control in the dual simplex, and when an error gap is exceeded the basis is reinverted

Choice 1,2,3 should not be used with MILPSOLVE 5.1.1.3, because of problems with the solver. Default is 0.
|-valign="top"
|||''LoadFile''||File that contains the model. If LoadFile is a nonempty string which corresponds to actual file, then the model is read from this file rather than from the Prob struct.
|-valign="top"
|||''LoadMode''||1 - LP - MILPSOLVE LP format

2 - MPS - MPS format

3 - FMPS - Free MPS format

A default value for this field does not exist. Both LoadFile and Load- Mode must be set if a problem will be loaded.

If there is something wrong with LoadMode or LoadFile, an error mes- sage will be printed and MILPSOLVE will be terminated. Leave Load- Mode and LoadFile empty if the problem not will be loaded from file.
|-
|||''LogFile''||Name of file to print MILPSOLVE log on.
|-
|||''MAXIMIZE ''||If MAXIMIZE ! = 0, MILPSOLVE is set to maximize the objective function, default is to minimize.
|-
|||''MAX_PIVOT''||Sets the maximum number of pivots between a re-inversion of the matrix. Default is 42.
|-valign="top"
|||''NEG_RANGE''||Specifies the negative value below which variables are split into a negative and a positive part. This value must always be zero or negative. If a positive value is specified, then 0 is taken. The default value is -1e6.
|-valign="top"
|||''PRESOLVE''||Vector containing possible presolve options. If the length i of the vector is less than 7 elements, only the i first modes are considered. Also if i is longer than 7 elements, the elements after element 7 is ignored.

PRESOLVE(1) ! = 0 (PRESOLVE ROWS) Presolve rows

PRESOLVE(2) ! = 0 (PRESOLVE COLS) Presolve columns

PRESOLVE(3) ! = 0 (PRESOLVE LINDEP) Eliminate linearly depen- dent rows

PRESOLVE(4) ! = 0 (PRESOLVE SOS) Convert constraints to SOSes (only SOS1 handled)

PRESOLVE(5) ! = 0 (PRESOLVE REDUCEMIP) If the phase 1 solu- tion process finds that a constraint is redundant then this constraint is deleted.

PRESOLVE(6) ! = 0 (PRESOLVE DUALS) Calculate duals PRESOLVE(7) ! = 0 (PRESOLVE SENSDUALS) Calculate sensitivity if there are integer variables

Default is not to do any presolve.
|-valign="top"
|||''PRICING_RULE''||The pricing rule can be one of the following rules.

PRICING_RULE = 0 Select first (PRICER_FIRSTINDEX)

PRICING_RULE = 1 Select according to Dantzig (PRICER_DANTZIG)

PRICING_RULE = 2 Devex pricing from Paula Harris (PRICER_DEVEX)

PRICING_RULE = 3 Steepest Edge (PRICER STEEPESTEDGE)
|-valign="top"
|||''PRICING_MODE''||Additional pricing settings, any combination of the modes below. This is a binary vector. If the length i of the vector is less than 7 elements, only the i first modes are considered. Also if i is longer than 7 elements, the elements after element 7 is ignored.

PRICE_PRIMALFALLBACK ! = 0 In case of Steepest Edge, fall back to DEVEX in primal.

PRICE_MULTIPLE ! = 0 Preliminary implementation of the multiple pricing scheme. This means that attractive candidate entering columns from one iteration may be used in the subsequent iteration, avoiding full updating of reduced costs. In the current implementation, MILPSOLVE only reuses the 2nd best entering column alternative.

PRICE_PARTIAL ! = 0 Enable partial pricing

PRICE_ADAPTIVE ! = 0 Temporarily use First Index if cycling is detected

PRICE_RANDOMIZE ! = 0 Adds a small randomization effect to the selected pricer

PRICE_LOOPLEFT ! = 0 Scan entering/leaving columns left rather than right

PRICE_LOOPALTERNATE ! = 0 Scan entering/leaving columns alternatingly left/right

Default basis is PRICER DEVEX combined with PRICE ADAPTIVE.
|-valign="top"
|||''sa''||Struct containing information of the sensitivity analysis (SA) MILPSOLVE will perform.

sa.obj =! 0 Perform sensitivity analysis on the objective function

sa.obj = 0 Do not perform sensitivity analysis on the objective function

sa.rhs =! 0 Perform sensitivity analysis on the right hand sides.

sa.rhs = 0 Do not perform sensitivity analysis on the right hand sides.
|-valign="top"
|||''SaveFileAfter''||Name of a file to save the MILPSOLVE object after presolve.The name must be of type string (char), Example: Prob.MILPSOLVE.SaveFileAfter = 'save2' If the type is not char SaveFileBefore is set to save2.[file extension].
|-valign="top"
|||''SaveFileBefore''||Name of a file to save the MILPSOLVE object before presolve. The name must be of type string (char), Example: Prob.MILPSOLVE.SaveFileBefore = 'save1'. If the type is not char SaveFileBefore is set to save1.[file extension].
|-valign="top"
|||''SaveMode''||1 - LP - MILPSOLVE LP format

2 - MPS - MPS format

3 - FMPS - Free MPS format

If empty, the default format LP is used.
|-valign="top"
|||''SCALE_LIMIT''||Sets the relative scaling convergence criterion to the absolute value of SCALE_LIMIT for the active scaling mode. The integer part of SCALE_LIMIT specifies the maximum number of iterations. Default is 5.
|-valign="top"
|||''SCALING_ALG''||Specifies which scaling algorithm will be used by MILPSOLVE.

0 No scaling algorithm

1 (SCALE EXTREME) Scale to convergence using largest absolute value

2 (SCALE RANGE) Scale based on the simple numerical range

3 (SCALE MEAN) Numerical range-based scaling

4 (SCALE GEOMETRIC) Geometric scaling

7 (SCALE CURTISREID) Curtis-reid scaling

Default is 0, no scaling algorithm.
|-valign="top"
|||''SCALING_ADD''||Vector containing possible additional scaling parameters. If the length (i) of the vector is less than 7 elements, only the i first modes are considered. Also if i is longer than 7 elements, the elements after element 7 is ignored. SCALING ADD ! = 0 (SCALE_QUADRATIC)

SCALING ADD ! = 0 (SCALE_LOGARITHMIC) Scale to convergence using logarithmic mean of all values

SCALING_ADD ! = 0 (SCALE_USERWEIGHT) User can specify scalars

SCALING_ADD ! = 0 (SCALE_POWER2) also do Power scaling

SCALING_ADD ! = 0 (SCALE_EQUILIBRATE) Make sure that no scaled number is above 1

SCALING_ADD ! = 0 (SCALE_INTEGERS) Also scaling integer vari- ables

SCALING_ADD ! = 0 (SCALE_DYNUPDATE) Dynamic update

Default is 0, no additional mode.

Settings SCALE_DYNUPDATE is a way to make sure that scaling factors are recomputed. In that case, the scaling factors are recomputed also when a restart is done.
|-valign="top"
|||''SIMPLEX_TYPE''||Sets the desired combination of primal and dual simplex algorithms.

5 (SIMPLEX_PRIMAL_PRIMAL) Phase1 Primal, Phase2 Primal

6 (SIMPLEX_DUAL_PRIMAL) Phase1 Dual, Phase2 Primal

9 (SIMPLEX_PRIMAL_DUAL) Phase1 Primal, Phase2 Dual

10 (SIMPLEX_DUAL_DUAL) Phase1 Dual, Phase2 Dual

Default is SIMPLEX DUAL PRIMAL (6).
|-valign="top"
|||''SOLUTION_LIMIT''||Sets the solution number that will be returned. This value is only consid- ered if there are integer, semi-continuous or SOS variables in the model so that the branch-and-bound algorithm is used. If there are more solutions with the same objective value, then this number specifies which solution must be returned. Default is 1.
|-valign="top"
|||''sos''||List of structs containing data about Special Ordered Sets (SOS). See below for further description.
|}

===MIP structure, substructure of [[MilpSolve#Prob structure|Prob]]===
Options specific to mixed integer programming problems.
{| class="wikitable"
!|''MIP''||colspan="2"|The following fields are used in ''Prob.MILPSOLVE'':
|-valign="top"
|||'''Field'''||'''Value'''
|-valign="top"
|||''IntVars''||Defines which variables are integers, of general type I or binary type B Variable indices should be in the range [1,...,n].

IntVars is a logical vector ==''> x''(''find''(''IntVars > ''0)) are integers

IntVars is a vector of indices ==''> x''(''IntVars'') are integers (if [], then no integers of type I or B are defined) variables with x L=0 and x U=1, is are set to binary. It is possible to combine integer and semi-continuous type to obtain the semi-integer type.
|-valign="top"
|||''fIP''||This parameter specifies the initial "at least better than" guess for objective function. This is only used in the branch-and-bound algorithm when integer variables exist in the model. All solutions with a worse objective value than this value are immediately rejected. The default is infinity.
|-valign="top"
|||''SC''||A vector with indices for variables of type semi-continuous (SC), a logical vector or a scalar (see MIP.IntVars). A semi-continuous variable i takes either the value 0 or some value in the range [x L(i), x U(i)]. It is possible to combine integer and semi-continuous type to obtain the semi-integer type.
|-valign="top"
|||''sos1''||List of structures defining the Special Ordered Sets of Order One (SOS1). For SOS1 set k, sos1(k).var is a vector of indices for variables of type SOS1 in set k, sos1(k).row is the priority of SOS k in the set of SOS1 and sos1(k).weight is a vector of the same length as sos1(k).var and it describes the order MILPSOLVE will weight the variables in SOS1 set k.

a low number of a row and a weight means high priority.
|-valign="top"
|||''sos2''||List of n structures defining the Special Ordered Sets (SOS) of Order Two (SOS2). (see MIP.sos1)
|}

==Outputs==

{|class="wikitable"
!''Result''||colspan="2"|Structure with result from optimization. The following fields are changed:
|-
|||''x_k''||Optimal solution (or some other solution if optimum could not been found)
|-
|||''f_k''||Optimal objective value.
|-
|||''v_k''||[rc; duals]. If Reduced cost and dual variables are not available, then v_k is empty.
|-valign="top"
|||''ExitFlag''||TOMLAB information parameter.

0 = Optimal solution found.

1 = Suboptimal solution or user abort.

2 = Unbounded solution.

3 = Numerical failure.

4 = Infeasible model.

10 = Out of memory.

11 = Branch and bound stopped.
|-
|||''ExitText''||Status text from MILPSOLVE.
|-valign="top"
|||''Inform''||MILPSOLVE information parameter.

-2 = Out of memory.

0 = Optimal solution found.

1 = Suboptimal solution.

2 = Infeasible model.

3 = Unbounded solution.

4 = Degenerate solution.

5 = Numerical failure.

6 = User abort.

7 = Timeout.

10 = Branch and bound failed.

11 = Branch and bound stopped.

12 = Feasible branch and bound solution.

13 = No feasible branch and bound solution. Other = Unknown status.
|-valign="top"
|||''Iter''||The total number of nodes processed in the branch-and-bound algorithm. Is only applicable if the model contains integer variables. In the case of an LP model Result.Iter contains the number of iterations. This is however not documented.
|-
|||''MinorIter''||The total number of Branch-and-bound iterations. When the problem is LP, MinorIter equals Result.Iter
|-
|||''MILPSOLVE.basis''||Optimal basis, on the format described above under Prob.MILPSOLVE.basis.
|-
|||''MILPSOLVE.MaxLevel''||The deepest Branch-and-bound level of the last solution. Is only applicable if the model contains integer variables.
|-valign="top"
|||''MILPSOLVE.sa.objStatus''||1 successful

0 SA not requested

-1 Error: error from MILPSOLVE

-3 no SA available
|-
|||''MILPSOLVE.sa.ObjLower''||An array that will contain the values of the lower limits on the objective function.
|-
|||''MILPSOLVE.sa.ObjUpper''||An array that will contain the values of the upper limits on the objective function.
|-
|||''MILPSOLVE.sa.RhsStatus''||see MILPSOLVE.sa.objStatus.
|-
|||''MILPSOLVE.sa.RhsLower''||An array that will contain the values of the lower limits on the RHS.
|-
|||''MILPSOLVE.sa.RhsUpper''||An array that will contain the values of the upper limits on the RHS.
|-valign="top"
|||''xState''||State of each variable

0 - free variable,

1 - variable on lower bound,

2 - variable on upper bound,

3 - variable is fixed, lower bound = upper bound.
|-valign="top"
|||''bState''||State of each linear constraint

0 - Inactive constraint,

1 - Linear constraint on lower bound,

2 - Linear constraint on upper bound,

3 - Linear equality constraint.
|}

MilpSolve

2014-08-12T14:52:36Z

Bjorn: /* Inputs */

[[Category:Solvers]]
==Purpose==

Solve mixed integer linear programming problems (MILP).

''MILPSOLVE'' solves problems of the form

<math>
\begin{array}{cccccc}
\min\limits_{x} & f(x) & = & c^{T}x & \\s/t & x_{L} & \leq & x & \leq & x_{U} \\& b_{L} & \leq & Ax & \leq & b_{U} \\& & & {x_{j} \in \mathbb{N} \ \ \forall j \in I} \\
\end{array}
</math>

where <math>c, x, x_L, x_U \in \mathbb{R}^{n}</math> , <math>A\in\mathbb{R}^{m\times n}</math> and <math>b_L, b_U \in \mathbb{R}^{m}</math>. The variables <math>x \in I</math> , the index subset of <math>1,...,n</math> are restricted to
be integers.

==Calling Syntax==

<source lang="matlab">
Result = tomRun('MILPSOLVE',Prob, 1); or
Prob = ProbCheck(Prob, 'MILPSOLVE');
Result = milpsolveTL(Prob);
PrintResult(Result,1);
</source>

==Inputs==

===Prob structure===

{| class="wikitable"
!''Prob''||colspan="2"|Problem description structure. The following fields are used:
|-valign="top"
|||'''Field'''||'''Value'''
|-
|||''x_L, x_U''||Lower and upper bounds on variables. (Must be dense).
|-
|||''b_L, b_U''||Lower and upper bounds on linear constraints. (Must be dense).
|-
|||''A''||Linear constraint matrix. (Sparse or dense).
|-
|||''QP.c''||Linear objective function coefficients, size ''nx''1.
|-
|||''BIG''||Definition of infinity. Default is 1e30.
|-valign="top"
|||''LargeScale''||Defines if milpsolveTL will convert the A matrix to a sparse matrix or not.

Largescale ! = 0 - sparse

LargeScale = 0 - dense

Default is to use the A matrix just as it is defined.
|-valign="top"
|||''PriLevOpt''||Specifies the printlevel that will be used by MILPSOLVE.

0 (NONE) No outputs

1 (NEUTRAL) Only some specific debug messages in debug print rou- tines are reported.

2 (CRITICAL) Only critical messages are reported. Hard errors like instability, out of memory.

3 (SEVERE) Only severe messages are reported. Errors.

4 (IMPORTANT) Only important messages are reported. Warnings and Errors.

5 (NORMAL) Normal messages are reported.

6 (DETAILED) Detailed messages are reported. Like model size, con- tinuing B&B improvements.

7 (FULL) All messages are reported. Useful for debugging purposes and small models.

Default print level is 0, no outputs. PriLevOpt ''< ''0 is interpreted as 0, and larger than 7 is interpreted as 7.
|-valign="top"
|||''MaxCPU''||Maximal CPU Time (in seconds) to be used by MILPSOLVE, stops with best point found.
|-valign="top"
|||''MILPSOLVE''||Defines milpSolve specific options, see the table below.
|-valign="top"
|||''MIP''||Structure with parameters specific to mixed integer programming problems in TOMLAB, see the table below.
|}
===MILPSOLVE structure, substructure of [[MilpSolve#Prob structure|Prob]]===
Solver specific options structure.
{| class="wikitable"
!''MILPSOLVE''||colspan="2"|The following fields are used in ''Prob.MILPSOLVE'':
|-valign="top"
|||'''Field'''||'''Value'''
|-valign="top"
|||''ANTI_DEGEN''||Binary vector. If empty, no anti-degeneracy handling is applied. If the length (i) of the vector is less than 8 elements,only the i first modes are considered. Also if i is longer than 8 elements, the elements after element8 are ignored.

ANTI_DEGEN specifies if special handling must be done to reduce de- generacy/cycling while solving. Setting this flag can avoid cycling, but can also increase numerical instability.

ANTIDEGEN FIXEDVARS ! = 0 Check if there are equality slacks in the basis and try to drive them out in order to reduce chance of degeneracy in Phase 1.

ANTIDEGEN COLUMNCHECK != 0

ANTIDEGEN STALLING != 0

ANTIDEGEN NUMFAILURE != 0

ANTIDEGEN LOSTFEAS != 0

ANTIDEGEN INFEASIBLE != 0

ANTIDEGEN DYNAMIC != 0

ANTIDEGEN DURINGBB != 0
|-valign="top"
|||''basis''||If empty or erroneous, default basis is used. Default start base is the all slack basis (the default simplex starting basis).

Prob.MILPSOLVE.basis stores the basic variables. If an element is less then zero then it means on lower bound, else on upper bound. Element 0 of the array is unused. The default initial basis is bascolumn[x] = -x. By MILPSOLVE convention, a basic variable is always on its lower bound, meaning that basic variables is always represented with a minus sign.

When a restart is done, the basis vector must be assigned a correct starting basis.
|-valign="top"
|||''BASIS_CRASH''||The set_basiscrash function specifies which basis crash mode MILP- SOLVE will used.

When no base crash is done (the default), the initial basis from which MILPSOLVE starts to solve the model is the basis containing all slack or artificial variables that is automatically associates with each constraint.

When base crash is enabled, a heuristic "crash procedure" is executed before the first simplex iteration to quickly choose a basis matrix that has fewer artificial variables. This procedure tends to reduce the num- ber of iterations to optimality since a number of iterations are skipped. MILPSOLVE starts iterating from this basis until optimality.

BASIS_CRASH ! = 2 - No basis crash

BASIS_CRASH = 2 - Most feasible basis

Default is no basis crash.
|-valign="top"
|||''BB_DEPTH_LIMIT''||Sets the maximum branch-and-bound depth. This value makes sense only if there are integer, semi-continuous or SOS variables in the model so that the branch-and-bound algorithm is used to solve the model. The branch-and-bound algorithm will not go deeper than this level. When BB DEPTH LIMIT i set to 0 then there is no limit to the depth. The default value is -50. A positive value means that the depth is absolute. A negative value means a relative B&B depth. The "order" of a MIP problem is defined to be 2 times the number of binary variables plus the number of SC and SOS variables. A relative value of -x results in a maximum depth of x times the order of the MIP problem.
|-valign="top"
|||''BB_FLOOR_FIRST''||Specifies which branch to take first in branch-and-bound algorithm. Default value is 1.

BB_FLOOR_FIRST = 0 (BRANCH CEILING) Take ceiling branch first

BB_FLOOR_FIRST = 1 (BRANCH FLOOR) Take floor branch first

BB_FLOOR_FIRST = 2 (BRANCH AUTOMATIC) MILPSOLVE decides which branch being taken first
|-valign="top"
|||''BB_RULE''||Specifies the branch-and-bound rule. Default value is 0.

BB_RULE = 0 (NODE_FIRSTSELECT) Select lowest indexed non- integer column

BB_RULE = 1 (NODE_GAPSELECT) Selection based on distance from the current bounds

BB_RULE = 2 (NODE_RANGESELECT) Selection based on the largest current bound

BB_RULE = 3 (NODE_FRACTIONSELECT) Selection based on largest fractional value

BB_RULE = 4 (NODE_PSEUDOCOSTSELECT4) Simple, unweighted pseudo-cost of a variable

BB_RULE = 5 (NODE_PSEUDONONINTSELECT) This is an ex- tended pseudo-costing strategy based on minimizing the number of in- teger infeasibilities.

BB RULE = 6 (NODE_PSEUDORATIOSELECT) This is an extended pseudo-costing strategy based on maximizing the normal pseudo-cost divided by the number of infeasibilities. Effectively, it is similar to (the reciprocal of ) a cost/benefit ratio.

BB_RULE = 7 (NODE_USERSELECT)
|-valign="top"
|||''BB_RULE_ADD''||Additional values for the BB RULE. BB RULE is a vector. If the length i of the vector is less than 10 elements, only the i first modes are considered. Also if i is longer than 10 elements, the elements after element 10 is ignored.

BB_RULE ADD(1) ! = 0 (NODE_WEIGHTREVERSEMODE)

BB_RULE ADD(2) ! = 0 (NODE BRANCHREVERSEMODE) In case when get bb floorfirst is BRANCH AUTOMATIC, select the opposite direction (lower/upper branch) that BRANCH AUTOMATIC had cho- sen.

BB_RULE_ADD(3) ! = 0 (NODE_GREEDYMODE)

BB_RULE_ADD(4) ! = 0 (NODE_PSEUDOCOSTMODE)

BB_RULE_ADD(5) ! = 0 (NODE_DEPTHFIRSTMODE) Select the node that has already been selected before the number of times

BB_RULE_ADD(6) ! = 0 (NODE_RANDOMIZEMODE)

BB_RULE_ADD(7) ! = 0 (NODE_DYNAMICMODE) When NODE DEPTHFIRSTMODE is selected, switch off this mode when a first solution is found.

BB_RULE_ADD(8) ! = 0 (NODE_RESTARTMODE)

BB_RULE_ADD(9) ! = 0 (NODE_BREADTHFIRSTMODE) Select the node that has been selected before the fewest number of times or not at all BB RULE ADD(10) ! = 0 (NODE_AUTOORDER)
|-valign="top"
|||''BFP''||Defines which Basis Factorization Package that will be used by MILP- SOLVE.

BFP = 0 : LUSOL

BFP = 1 : built in etaPHI from MILPSOLVE v3.2

BFP = 2 : Additional etaPHI BFP = 3 : GLPK

Default BFP is LUSOL.
|-valign="top"
|||''BREAK_AT_FIRST''||Specifies if the branch-and-bound algorithm stops at the first found so- lution (BREAK_AT_FIRST != 0) or not (BREAK_AT_FIRST = 0). De- fault is not to stop at the first found solution.
|-valign="top"
|||''BREAK_AT_VALUE''||Specifies if the branch-and-bound algorithm stops when the object value is better than a given value. The default value is (-) infinity.
|-valign="top"
|||''EPAGAP''||Specifies the absolute MIP gap tolerance for the branch and bound algo- rithm. This tolerance is the difference between the best-found solution yet and the current solution. If the difference is smaller than this toler- ance then the solution (and all the sub-solutions) is rejected. The default value is 1e-9.
|-valign="top"
|||''EPGAP''||Specifies the relative MIP gap tolerance for the branch and bound algo- rithm. The default value is 1e-9.
|-valign="top"
|||''EPSB''||Specifies the value that is used as a tolerance for the Right Hand Side (RHS) to determine whether a value should be considered as 0. The default epsb value is 1.0e-10
|-valign="top"
|||''EPSD''||Specifies the value that is used as a tolerance for reduced costs to deter- mine whether a value should be considered as 0. The default epsd value is 1e-9. If EPSD is empty, EPSD is read from ''Prob.optParam.eps f''.
|-valign="top"
|||''EPSEL''||Specifies the value that is used as a tolerance for rounding values to zero. The default epsel value is 1e-12.
|-valign="top"
|||''EPSINT''||Specifies the tolerance that is used to determine whether a floating- point number is in fact an integer. The default value for epsint is 1e-7. Changing this tolerance value can result in faster solving times, but the solution is less integer.
|-valign="top"
|||''EPSPERTURB''||Specifies the value that is used as perturbation scalar for degenerative problems. The default epsperturb value is 1e-5.
|-valign="top"
|||''EPSPIVOT''||Specifies the value that is used as a tolerance pivot element to determine whether a value should be considered as 0. The default epspivot value is 2e-7
|-valign="top"
|||''IMPROVEMENT_LEVEL''||Specifies the iterative improvement level.

IMPROVEMENT LEVEL = 0 (IMPROVE NONE) improve none

IMPROVEMENT LEVEL = 1 (IMPROVE FTRAN) improve FTRAN

IMPROVEMENT LEVEL = 2 (IMPROVE BTRAN) improve BTRAN

IMPROVEMENT LEVEL = 3 (IMPROVE SOLVE) improve FTRAN + BTRAN.

IMPROVEMENT LEVEL = 4 (IMPROVE INVERSE) triggers automatic inverse accuracy control in the dual simplex, and when an error gap is exceeded the basis is reinverted

Choice 1,2,3 should not be used with MILPSOLVE 5.1.1.3, because of problems with the solver. Default is 0.
|-valign="top"
|||''LoadFile''||File that contains the model. If LoadFile is a nonempty string which corresponds to actual file, then the model is read from this file rather than from the Prob struct.
|-valign="top"
|||''LoadMode''||1 - LP - MILPSOLVE LP format

2 - MPS - MPS format

3 - FMPS - Free MPS format

A default value for this field does not exist. Both LoadFile and Load- Mode must be set if a problem will be loaded.

If there is something wrong with LoadMode or LoadFile, an error mes- sage will be printed and MILPSOLVE will be terminated. Leave Load- Mode and LoadFile empty if the problem not will be loaded from file.
|-
|||''LogFile''||Name of file to print MILPSOLVE log on.
|-
|||''MAXIMIZE ''||If MAXIMIZE ! = 0, MILPSOLVE is set to maximize the objective function, default is to minimize.
|-
|||''MAX_PIVOT''||Sets the maximum number of pivots between a re-inversion of the matrix. Default is 42.
|-valign="top"
|||''NEG_RANGE''||Specifies the negative value below which variables are split into a negative and a positive part. This value must always be zero or negative. If a positive value is specified, then 0 is taken. The default value is -1e6.
|-valign="top"
|||''PRESOLVE''||Vector containing possible presolve options. If the length i of the vector is less than 7 elements, only the i first modes are considered. Also if i is longer than 7 elements, the elements after element 7 is ignored.

PRESOLVE(1) ! = 0 (PRESOLVE ROWS) Presolve rows

PRESOLVE(2) ! = 0 (PRESOLVE COLS) Presolve columns

PRESOLVE(3) ! = 0 (PRESOLVE LINDEP) Eliminate linearly depen- dent rows

PRESOLVE(4) ! = 0 (PRESOLVE SOS) Convert constraints to SOSes (only SOS1 handled)

PRESOLVE(5) ! = 0 (PRESOLVE REDUCEMIP) If the phase 1 solu- tion process finds that a constraint is redundant then this constraint is deleted.

PRESOLVE(6) ! = 0 (PRESOLVE DUALS) Calculate duals PRESOLVE(7) ! = 0 (PRESOLVE SENSDUALS) Calculate sensitivity if there are integer variables

Default is not to do any presolve.
|-valign="top"
|||''PRICING_RULE''||The pricing rule can be one of the following rules.

PRICING_RULE = 0 Select first (PRICER_FIRSTINDEX)

PRICING_RULE = 1 Select according to Dantzig (PRICER_DANTZIG)

PRICING_RULE = 2 Devex pricing from Paula Harris (PRICER_DEVEX)

PRICING_RULE = 3 Steepest Edge (PRICER STEEPESTEDGE)
|-valign="top"
|||''PRICING_MODE''||Additional pricing settings, any combination of the modes below. This is a binary vector. If the length i of the vector is less than 7 elements, only the i first modes are considered. Also if i is longer than 7 elements, the elements after element 7 is ignored.

PRICE_PRIMALFALLBACK ! = 0 In case of Steepest Edge, fall back to DEVEX in primal.

PRICE_MULTIPLE ! = 0 Preliminary implementation of the multiple pricing scheme. This means that attractive candidate entering columns from one iteration may be used in the subsequent iteration, avoiding full updating of reduced costs. In the current implementation, MILPSOLVE only reuses the 2nd best entering column alternative.

PRICE_PARTIAL ! = 0 Enable partial pricing

PRICE_ADAPTIVE ! = 0 Temporarily use First Index if cycling is detected

PRICE_RANDOMIZE ! = 0 Adds a small randomization effect to the selected pricer

PRICE_LOOPLEFT ! = 0 Scan entering/leaving columns left rather than right

PRICE_LOOPALTERNATE ! = 0 Scan entering/leaving columns alternatingly left/right

Default basis is PRICER DEVEX combined with PRICE ADAPTIVE.
|-valign="top"
|||''sa''||Struct containing information of the sensitivity analysis (SA) MILPSOLVE will perform.

sa.obj =! 0 Perform sensitivity analysis on the objective function

sa.obj = 0 Do not perform sensitivity analysis on the objective function

sa.rhs =! 0 Perform sensitivity analysis on the right hand sides.

sa.rhs = 0 Do not perform sensitivity analysis on the right hand sides.
|-valign="top"
|||''SaveFileAfter''||Name of a file to save the MILPSOLVE object after presolve.The name must be of type string (char), Example: Prob.MILPSOLVE.SaveFileAfter = 'save2' If the type is not char SaveFileBefore is set to save2.[file extension].
|-valign="top"
|||''SaveFileBefore''||Name of a file to save the MILPSOLVE object before presolve. The name must be of type string (char), Example: Prob.MILPSOLVE.SaveFileBefore = 'save1'. If the type is not char SaveFileBefore is set to save1.[file extension].
|-valign="top"
|||''SaveMode''||1 - LP - MILPSOLVE LP format

2 - MPS - MPS format

3 - FMPS - Free MPS format

If empty, the default format LP is used.
|-valign="top"
|||''SCALE_LIMIT''||Sets the relative scaling convergence criterion to the absolute value of SCALE_LIMIT for the active scaling mode. The integer part of SCALE_LIMIT specifies the maximum number of iterations. Default is 5.
|-valign="top"
|||''SCALING_ALG''||Specifies which scaling algorithm will be used by MILPSOLVE.

0 No scaling algorithm

1 (SCALE EXTREME) Scale to convergence using largest absolute value

2 (SCALE RANGE) Scale based on the simple numerical range

3 (SCALE MEAN) Numerical range-based scaling

4 (SCALE GEOMETRIC) Geometric scaling

7 (SCALE CURTISREID) Curtis-reid scaling

Default is 0, no scaling algorithm.
|-valign="top"
|||''SCALING_ADD''||Vector containing possible additional scaling parameters. If the length (i) of the vector is less than 7 elements, only the i first modes are considered. Also if i is longer than 7 elements, the elements after element 7 is ignored. SCALING ADD ! = 0 (SCALE_QUADRATIC)

SCALING ADD ! = 0 (SCALE_LOGARITHMIC) Scale to convergence using logarithmic mean of all values

SCALING_ADD ! = 0 (SCALE_USERWEIGHT) User can specify scalars

SCALING_ADD ! = 0 (SCALE_POWER2) also do Power scaling

SCALING_ADD ! = 0 (SCALE_EQUILIBRATE) Make sure that no scaled number is above 1

SCALING_ADD ! = 0 (SCALE_INTEGERS) Also scaling integer vari- ables

SCALING_ADD ! = 0 (SCALE_DYNUPDATE) Dynamic update

Default is 0, no additional mode.

Settings SCALE_DYNUPDATE is a way to make sure that scaling factors are recomputed. In that case, the scaling factors are recomputed also when a restart is done.
|-valign="top"
|||''SIMPLEX_TYPE''||Sets the desired combination of primal and dual simplex algorithms.

5 (SIMPLEX_PRIMAL_PRIMAL) Phase1 Primal, Phase2 Primal

6 (SIMPLEX_DUAL_PRIMAL) Phase1 Dual, Phase2 Primal

9 (SIMPLEX_PRIMAL_DUAL) Phase1 Primal, Phase2 Dual

10 (SIMPLEX_DUAL_DUAL) Phase1 Dual, Phase2 Dual

Default is SIMPLEX DUAL PRIMAL (6).
|-valign="top"
|||''SOLUTION_LIMIT''||Sets the solution number that will be returned. This value is only consid- ered if there are integer, semi-continuous or SOS variables in the model so that the branch-and-bound algorithm is used. If there are more solutions with the same objective value, then this number specifies which solution must be returned. Default is 1.
|-valign="top"
|||''sos''||List of structs containing data about Special Ordered Sets (SOS). See below for further description.
|}

===MIP structure, substructure of [[MilpSolve#Prob structure|Prob]]===
Options specific to mixed integer programming problems.
{| class="wikitable"
!|''MIP''||colspan="2"|The following fields are used in ''Prob.MILPSOLVE'':
|-valign="top"
|||'''Field'''||'''Value'''
|-valign="top"
|||''IntVars''||Defines which variables are integers, of general type I or binary type B Variable indices should be in the range [1,...,n].

IntVars is a logical vector ==''> x''(''find''(''IntVars > ''0)) are integers

IntVars is a vector of indices ==''> x''(''IntVars'') are integers (if [], then no integers of type I or B are defined) variables with x L=0 and x U=1, is are set to binary. It is possible to combine integer and semi-continuous type to obtain the semi-integer type.
|-valign="top"
|||''fIP''||This parameter specifies the initial "at least better than" guess for objective function. This is only used in the branch-and-bound algorithm when integer variables exist in the model. All solutions with a worse objective value than this value are immediately rejected. The default is infinity.
|-valign="top"
|||''SC''||A vector with indices for variables of type semi-continuous (SC), a logical vector or a scalar (see MIP.IntVars). A semi-continuous variable i takes either the value 0 or some value in the range [x L(i), x U(i)]. It is possible to combine integer and semi-continuous type to obtain the semi-integer type.
|-valign="top"
|||''sos1''||List of structures defining the Special Ordered Sets of Order One (SOS1). For SOS1 set k, sos1(k).var is a vector of indices for variables of type SOS1 in set k, sos1(k).row is the priority of SOS k in the set of SOS1 and sos1(k).weight is a vector of the same length as sos1(k).var and it describes the order MILPSOLVE will weight the variables in SOS1 set k.

a low number of a row and a weight means high priority.
|-valign="top"
|||''sos2''||List of n structures defining the Special Ordered Sets (SOS) of Order Two (SOS2). (see MIP.sos1)
|}

==Outputs==

{|class="wikitable"
!''Result''||colspan="2"|Structure with result from optimization. The following fields are changed:
|-
|||''x_k''||Optimal solution (or some other solution if optimum could not been found)
|-
|||''f_k''||Optimal objective value.
|-
|||''v_k''||[rc; duals]. If Reduced cost and dual variables are not available, then v_k is empty.
|-valign="top"
|||''ExitFlag''||TOMLAB information parameter.

0 = Optimal solution found.

1 = Suboptimal solution or user abort.

2 = Unbounded solution.

3 = Numerical failure.

4 = Infeasible model.

10 = Out of memory.

11 = Branch and bound stopped.
|-
|||''ExitText''||Status text from MILPSOLVE.
|-valign="top"
|||''Inform''||MILPSOLVE information parameter.

-2 = Out of memory.

0 = Optimal solution found.

1 = Suboptimal solution.

2 = Infeasible model.

3 = Unbounded solution.

4 = Degenerate solution.

5 = Numerical failure.

6 = User abort.

7 = Timeout.

10 = Branch and bound failed.

11 = Branch and bound stopped.

12 = Feasible branch and bound solution.

13 = No feasible branch and bound solution. Other = Unknown status.
|-valign="top"
|||''Iter''||The total number of nodes processed in the branch-and-bound algorithm. Is only applicable if the model contains integer variables. In the case of an LP model Result.Iter contains the number of iterations. This is however not documented.
|-
|||''MinorIter''||The total number of Branch-and-bound iterations. When the problem is LP, MinorIter equals Result.Iter
|-
|||''MILPSOLVE.basis''||Optimal basis, on the format described above under Prob.MILPSOLVE.basis.
|-
|||''MILPSOLVE.MaxLevel''||The deepest Branch-and-bound level of the last solution. Is only applicable if the model contains integer variables.
|-valign="top"
|||''MILPSOLVE.sa.objStatus''||1 successful

0 SA not requested

-1 Error: error from MILPSOLVE

-3 no SA available
|-
|||''MILPSOLVE.sa.ObjLower''||An array that will contain the values of the lower limits on the objective function.
|-
|||''MILPSOLVE.sa.ObjUpper''||An array that will contain the values of the upper limits on the objective function.
|-
|||''MILPSOLVE.sa.RhsStatus''||see MILPSOLVE.sa.objStatus.
|-
|||''MILPSOLVE.sa.RhsLower''||An array that will contain the values of the lower limits on the RHS.
|-
|||''MILPSOLVE.sa.RhsUpper''||An array that will contain the values of the upper limits on the RHS.
|-valign="top"
|||''xState''||State of each variable

0 - free variable,

1 - variable on lower bound,

2 - variable on upper bound,

3 - variable is fixed, lower bound = upper bound.
|-valign="top"
|||''bState''||State of each linear constraint

0 - Inactive constraint,

1 - Linear constraint on lower bound,

2 - Linear constraint on upper bound,

3 - Linear equality constraint.
|}

PROPT

2014-08-07T07:27:35Z

Bjorn: /* Modeling */

==Overview==

The following sections describe the functionality of PROPT. It is recommended to get familiar with a few examples (included with software) to get accustomed with the notations used.

===Installation===

The PROPT software is included in the general TOMLAB installation executable. Please refer to the TOMLAB Installation manual for further information. The following Matlab commands can be used to verify a successful installation.

<pre>
>> cd c:\tomlab\
>> startup
>> vanDerPol
</pre>

After a few seconds two graphs should display the state and control variables for the example.

===Foreword to the software===

The software is provided without limitations to all registered customers in order to demonstrated what PROPT is capable of. The implementation of the extensive example library (more then 100 test cases are included) has eliminated most bugs, but there may still be a few that has escaped attention.

If problems are encountered please email a copy of the problem for debugging. (All examples and data are treated as strictly confidential unless other instructions are given.) A status report can be expected within 24 hours.

===Initial remarks===

PROPT is a combined modeling, compilation and solver engine for generation of highly complex optimal control problems. The users will need to have licenses for the TOMLAB Base Module, TOMLAB /SNOPT (or other suitable nonlinear TOMLAB solver) (always included with a demo license).

It is highly recommended to take a look at the example collection included with the software before building a new problem (Tip: Copy one of the examples and use as a starting-point).

The brysonDenham problems in the examples folder contain very extensive documentation, explanations and general information about the usage and software design.

PROPT aims to encompass all areas of optimal control including:

*Aerodynamic trajectory control

*Bang bang control

*Chemical engineering

*Dynamic systems

*General optimal control

*Large-scale linear control

*Multi-phase system control

*Mechanical engineering design

*Non-differentiable control

*Parameters estimation for dynamic systems

*Singular control

At least one example from each area is included in the example suite.

==Introduction to PROPT==

PROPT is a software package intended to solve dynamic optimization problems. Such problems are usually described by

*A state-space model of a system. This can be either a set of ordinary differential equations ('''ODE''') or differential algebraic equations ('''DAE''').

*Initial and/or final conditions (sometimes also conditions at other points).

*A cost functional, i.e. a scalar value that depends on the state trajectories and the control function.

*Sometimes, additional equations and variables that, for example, relate the initial and final conditions to each other.

The goal of PROPT is to enable the formulation of such problem descriptions as seamlessly as possible, without having to worry about the mathematics of the actual solver. Once a problem has been properly defined, PROPT will take care of all the necessary steps in order to return a solution.2

PROPT uses pseudospectral collocation methods (and other options) for solving optimal control problems. This means that the solution takes the form of a polynomial, and this polynomial satisfies the DAE and the path constraints at the collocation points (Note that both the DAE and the path constraints can be violated between collocation points). The default choice is to use Gauss points as collocation points, although the user can specify any set of points to use.

It should be noted that the code is written in a general way, allowing for a DAE rather than just an ODE formulation with path constraints.

Parameter estimation for dynamic systems is intrinsically supported by the framework as scalar decision variables can be introduced in the formulation.

===Overview of PROPT syntax===

A PROPT problem is defined with tomSym objects and standard Matlab expressions (usually in cell arrays), which contain information about different aspects of the problem.

In general an optimal control consists of the following:

*'''Phases: '''A problem may contain several different phases, each with its own set of variables and equations.

*'''Independent: '''Variables that are independent (normally time).

*'''States: '''(Could also be called "dependent") States (short for ''state variables '') are continuous functions of the independent variable. Control variables are (possibly) discontinuous functions of the same variable.

*'''Controls: '''Control variables (states that may be discontinuous).

*'''Scalars: '''A problem may also contain unknown scalar variables that are solved for at the same time as the controls and state trajectories.

*'''Parameters: '''Numeric constants that are used to define a problem.

2 This is accomplished by translating the dynamic problem into a nonlinear programming problem, generating Matlab function files and a TOMLAB problem, that can be passed to a numeric solver.

*'''Expressions: '''Intermediate results in computations.

*'''Equations and inequalities: '''The core of the problem definition.

*'''Cost: '''A performance index or objective function to be minimized.

'''PROPT has many built-in features:'''

*Computation of the constant matrices used for the differentiation and integration of the polynomials used to approximate the solution to the trajectory optimization problem.

*Code manipulation to turn user-supplied expressions into Matlab code for the cost function ''f ''and constraint function ''c ''(with two levels of analytical derivative and sparsity patterns). The files are passed to a nonlinear programming solver (by default) in TOMLAB for final processing.

*Functionality for plotting and computing a variety of information for the solution to the problem.

*Integrated support for non-smooth (hybrid) optimal control problems.

Note: The tomSym and PROPT softwares are the first Matlab modules to enable complete source transformation for optimal control problem.

===Vector representation===

In PROPT, each state is represented by a scalar <math>x_0</math> and a vector <math>\mathbf{x} = \left[ \begin{array}{c}x_1 \\ \vdots \\ x_N
\end{array} \right]</math>, such that <math>x_i</math> corresponds to the value of the state at the i:th collocation point.

State equations are written on vector form, and hence apply at all
collocation points. The initial point is treated separately, so the
state equations do not apply at the initial point.

The final state is not a free variable. Instead, it is computed via the interpolating polynomial.

===Global optimality===

PROPT does not use Pontryagin's maximum principle, rather it uses a pseudospectral method, however the results are mathematically equivalent. This means that if the solver prints "an optimal solution was found", the solution satisfies necessary, but not sufficient, conditions of optimality. It is guaranteed that the returned solution cannot be improved by an infinitesimal change in the trajectory, but there may exist completely different trajectories that are better.

A recommended procedure for finding other solutions is to set conservative bounds for all variables (states, controls and parameters) and change the solver to "multiMin". This will run a large number of optimizations from random starting points. If they all converge to the same minimum, this is an indication, but no guarantee, that the solution is indeed the global optimum.

In order guarantee that the global optimum is obtained, one must either solve the Hamilton-Jacobi-Bellman equation (which PROPT does not) or show that the problem is convex and therefore only has one optimum (which 3 The final state could be computed by integrating the ODE, however, as we use a DAE, it is more convenient to go via the interpolating polynomial. Proofs that these methods are mathematically equivalent have been published.

may not be the case). If ezsolve claims that the problem type is "LP" or "QP", the problem is convex, and the solution is a global optimum.

It is also worth mentioning that a solution computed by PROPT only satisfies the ODE and constraints in the specified collocation points. There is no guarantee that the solution holds between those points. A common way of testing the integrity of a solution is to re-run the computation using twice as many collocation points. If nothing changes, then there was probably enough points in the first computation.

==Modeling optimal control problems==

In order to understand the basic modeling features in PROPT it is best to start with a simple example. Open the file called ''brysonDenham.m ''located in /tomlab/propt/examples.

There are also ''brysonDenhamShort.m'', ''brysonDenhamDetailed.m'', ''brysonDenhamTwoPhase.m ''that solve the same problem, utilizing different features of PROPT.

To solve the problem, simply enter the following in the Matlab command prompt:

<pre>
>> brysonDenham
</pre>

==A simple example==

The following example can be found in ''vanDerPol.m ''in /tomlab/propt/examples. The objective is to solve the following problem:

minimize:

<math>
\begin{array}{ccc}
J &=& x_3(t_f)
\end{array}
</math>

subject to:

<math>
\begin{array}{lll}
\frac{dx_1}{dt} &=& (1-x_2^2)*x_1-x_2+u \\
\frac{dx_2}{dt} &=& x_1 \\
\frac{dx_3}{dt} &=& x_1^2+x_2^2+u^2 \\
\\
-0.3 <= &u& <= 1.0 \\
x(t_0) &=& [0 \ 1 \ 0]' \\
t_f &=& 5
\end{array}
</math>

To solve the problem with PROPT the following compact code can be used:

<pre>
toms t
p = tomPhase('p', t, 0, 5, 60);
setPhase(p);

tomStates x1 x2 x3
tomControls u

% Initial guess
x0 = {icollocate({x1 == 0; x2 == 1; x3 == 0})
collocate(u == -0.01)};

% Box constraints
cbox = {-10 <= icollocate(x1) <= 10
-10 <= icollocate(x2) <= 10
-10 <= icollocate(x3) <= 10
-0.3 <= collocate(u) <= 1};

% Boundary constraints
cbnd = initial({x1 == 0; x2 == 1; x3 == 0});

% ODEs and path constraints
ceq = collocate({dot(x1) == (1-x2.^2).*x1-x2+u
dot(x2) == x1; dot(x3) == x1.^2+x2.^2+u.^2});

% Objective
objective = final(x3);

% Solve the problem
options = struct;
options.name = 'Van Der Pol';
solution = ezsolve(objective, {cbox, cbnd, ceq}, x0, options);
</pre>

===Code generation===

It is possible to compile permanently, in order to keep the autogenerated code:

<pre>
>> Prob = sym2prob('lpcon',objective, {cbox, cbnd, ceq}, x0, options);
>> Prob.FUNCS

ans =

f: 'lp_f'
g: 'lp_g'
H: 'lp_H'
c: 'c_AFBHVT'
dc: 'dc_AFBHVT'
d2c: 'd2c_AFBHVT'
r: []
J: []
d2r: []
fc: []
gdc: []
fg: []
cdc: []
rJ: []

>> edit c_AFBHVT
</pre>

The code that was generated can be found in the $TEMP directory. The objective in this case is linear and can found in the Prob structure (''Prob.QP.c'').

Here is what the auto generated constraint code may look like:

<pre>
function out = c_AFBHVT(tempX,Prob)
% c_AFBHVT - Autogenerated file.
tempD=Prob.tomSym.c;
x3_p = reshape(tempX(183:243),61,1);
u_p = reshape(tempX(1:60),60,1);
x2_p = reshape(tempX(122:182),61,1);
x1_p = reshape(tempX(61:121),61,1);
tempC7 = tempD{2}*x2_p;
tempC8 = tempC7.^2;
tempC10 = tempD{2}*x1_p;
out = [(tempD{3}-tempC8).*tempC10-tempC7+u_p-0.2*(tempD{1}*x1_p);...
tempC10.^2+tempC8+u_p.^2-0.2*(tempD{1}*x3_p)];
</pre>

And the objective function to optimize (in this case a simple linear objective already available in TOMLAB (hence not auto generated, but defined by the ''Prob ''field used)):

<pre>
function f = lp_f(x, Prob)
f = Prob.QP.c'*x(:);
</pre>

===Modeling===

The PROPT system uses equations and expressions (collected in cells) to model optimal control problems. Equations must be written either using (== ''<''= ''>''=) equality/inequality markers.

It is possible to include more than one equation on the same line. For example:

<pre>
toms a b c
cnbd = {a <= b <= c};
</pre>

does the same job as:

<pre>
toms a b c
cnbd = {a <= b
b <= c};
</pre>

(The same is true for equalities.)

Be careful! This syntax is allowed in tomSym and PROPT because it is very common in mathematical notation, and allows for more compact code. Since it is not correct MATLAB notation, it will give unexpected results if the middle object is not a symbol. For example:

<pre>
a = 1;
b = 2;
toms c
cbnd = {a <= b <= c} % This gives an error!
</pre>

When working with optimal control problems, one typically work with expressions that are valid for all collocation points. The functions ''collocate ''and ''icollocate ''can be used to extend an arbitrary expressions to the necessary collocation points.

Consider for example the starting points:

<pre>
tomStates x1
tomControls u1
x0 = {icollocate(x1==1); collocate(u1==1)};
</pre>

Note: icollocate, as it is working with a state variable, also includes the starting point.

'''Scale the problem:'''

Proper scaling may speed up convergence, and conversely, improperly scaled problems may converge slowly or not at all. Both unknowns and equations can be scaled.

'''Don't use inf in equations:'''

It is strongly discouraged to use -inf/inf in equations. This is because the equation may be evaluated by subtracting its left-hand side from the right-hand side and comparing the result to zero, which could have unexpected consequences.

Equations like ''x <= Inf '' are better left out completely (Although in many cases tomSym will know to ignore them anyway).

'''Avoid using non-smooth functions:'''

Because the optimization routines rely on derivatives, non-smooth functions should be avoided. A common exam- ple of a non-smooth function is the Heaviside function ''H '', defined as ''H ''(''x'') = 1 for ''x > ''0, and ''H ''(''x'') = 0 for ''x = ''0,

which in Matlab code can be written as (''x > ''0). A smoother expression, which has the same behavior for ''x >> a ''is:

<math>
H_s = \frac{1}{2} \left( 1 + \tanh ( x/a ) \right)
</math>

When the problems are non-smooth in the independent variable (time, t), the problem should normally be separated into phases.

'''Use descriptive names for equations, states, controls, and variables:'''

The names used for states, controls, and variables make the code easier to read. Consider using names such as

"speed", "position", "concentration", etc. instead of "x1", "x2", "x3".

The names used for equations do not matter in most cases. However, they will be useful when accessing Lagrange multipliers.

'''Re-solve on successively finer grids:'''

If a very fine grid is needed in order to obtain a good solution, it is usually a good idea to solve the problem on a less dense grid first, and then re-solve, by using the obtained solution as a starting point. The following code will do the trick:

<pre>
for n=[10 40]
p = tomPhase('p', t, 0, 6, n);
setPhase(p);
tomStates x1 x2

% Initial guess
if n == 10
x0 = {p1 == 0; p2 == 0};
else
x0 = {p1 == p1opt; p2 == p2opt
icollocate({x1 == x1opt; x2 == x2opt})};
end
...
...
...
solution = ezsolve(objective, {cbox, cbnd, ceq}, x0, options);

% Optimal x, p for starting point
x1opt = subs(x1, solution);
x2opt = subs(x2, solution);
p1opt = subs(p1, solution);
p2opt = subs(p2, solution);
end
</pre>

See for example ''denbighSystem.m ''and ''drugScheduling.m''.

====Modeling notes====

The examples included with the software in many cases just scratch the surface of the capabilities of PROPT. The software is designed for maximum user flexibility and with many "hidden" features. The following notes are worth keeping in mind when modeling optimal control problems.

'''Left-hand side treatment:'''

The left hand side of equations do not have to be a single time-derivative. Things like ''collocate''(''m * dot''(''v'') == ''F '') work just fine, even if m is a state variable (A constraint that prevents m from becoming to small may improve convergence).

'''Second derivatives:'''

Second derivatives are allowed, as in ''collocate''(''dot''(''dot''(''x'')) == ''a''), although convergence is almost always better when including extra states to avoid this.

'''Equations:'''

Equations do not have to include any time-derivative. For example ''collocate''(0''.''5 ''* m * v''2 + ''m * g * h'') == ''initial''(0''.''5 ''* m * v''2 + ''m * g * h'') will work just fine in the PROPT framework.

'''Fixed end times:'''

Problems with fixed end-times enables the use of any form of expression involving the collocation points in time since the collocation points are pre-determined.

The following illustrates how t can (should) be used.

<pre>
toms t
% Will cause an error if myfunc is undefined for tomSym
myfunc(t);

% This works since collocate(t) is a double vector and not a
% tomSym object.
myfunc(collocate(t))
</pre>

It is also worth noting that feval bypasses tomSym, so it is possible to call any function, at the expense of slower derivatives. In the case of a fixed end time, there are no derivatives:

<pre>
toms t
% Works since tomSym is bypassed.
collocate(feval('myfunc',t))
</pre>

'''Segmented constraints:'''

With PROPT is it possible to define constraints that are valid for only a part of phase. In addition, it is possible to define constraints for other points than the collocation points which could assist in avoiding constraint violations in between the collocation points.

''mcollocate ''automates this process for the entire phase and imposes twice the number of constraints, i.e. the solution will be constrained in between each collocation point as well.

The following example shows how to set segmented constraints (valid for a part of the phase) for time-free and time-fixed problems.

<pre>
% For variable end time (the number of constraints need to be fixed)
% Relax all constraints below the cutoff, while 0 above
con = {collocate((8*(t-0.5).^2-0.5-x2) >= -1e6*(t<0.4))};

% When the end time is fixed there are many possible solutions.
% One can use custom points or a set of collocation points if needed.
tsteps = collocate(t);
n = length(tsteps);
y = atPoints(p,tsteps(round(n/3):round(n/2)),(8*(t-0.5).^2-0.5-x2));
con = {y >= 0};

% Alternatively one could write for custom points.
con = atPoints(p,linspace(0.4, 0.5, 10),(8*(t-0.5).^2-0.5-x2) >= 0);
</pre>

'''Constant unknowns:'''

It is possible to mix constant unknowns (created with "toms") into the equations, and those will become part of the solution: ''icollocate''(0''.''5 ''* m * v''2 + ''m * g * h ''== ''Etot'').

'''Higher-index DAEs:'''

Higher-index DAEs usually converge nicely with PROPT. One can use dot() on entire expressions to get symbolic time derivatives to use when creating lower index DAEs.

'''Lagrangian equations:'''

Deducing Lagrangian equations manually is usually not necessary, but if needed, one can use tomSym for derivatives. TomSym allows for computation of symbolic derivatives with respect to constant scalars and matrices using the "derivative" function, but this does not work for tomStates or tomControls. The current implementation is therefore to create expressions using normal tomSym variables (created with the "toms" command), use the derivative function and then use "subs" function to replace the constants with states and controls before calling collocate.

===Independent variables, scalars and constants===

Independent variables can be defined as follows (yes, it is that simple!):

<pre>
toms t % Time
toms tf % Final time
% Phase name, time, start, end, number of nodes
p = tomPhase('p', t, 0, tf, 25);
cbox = {20 <= tf <= 30}; % Bounds on end time
x0 = {tf == 22); % Starting point for end time (must be set before used
% in other expressions)
</pre>

It is also possible use scalar variables within the PROPT framework:

<pre>
toms p1
cbox = {1 <= p1 <= 2};
x0 = {p1 == 1.3);
</pre>

where the variables define lower, upper bound and a suitable guess.

A constant variable ki0 can be defined with the following statement (i.e. no difference from normal Matlab code):

<pre>
ki0 = [1e3; 1e7; 10; 1e-3];
</pre>

===State and control variables===

The difference between state and control variables is that states are continuous between phases, while control variables can be discontinuous.

Examples:

Unconstrained state variable ''x''1 with a starting guess from 0 to 1:

<pre>
tomStates x1
x0 = icollocate(x1 == t/tf);
</pre>

State variable ''x''1 with bounds of 0.5 and 10. The starting guess should be set as well to avoid any potential singularities:

<pre>
tomStates x1
cbox = {0.5 <= icollocate(x1) <= 10};
</pre>

Control variable T with a "table" defining the starting point:

<pre>
tomControls T
x0 = collocate(T==273*(t<100)+415*(t>=100));
</pre>

===Boundary, path, event and integral constraints===

Boundary constraints are defined as expressions since the problem size is reduced. For example if state variable

''x''1 has to start in 1 and end in 1 and ''x''2 has to travel from 0 to 2 define:

<pre>
cbnd1 = initial(x1 == 1);
cbnd2 = initial(x2 == 0);
cbnd3 = final(x1 == 1);
cbnd4 = final(x2 == 2);
</pre>

A variety of path, event and integral constraints are shown below:
<pre>
x3min = icollocate(x3 >= 0.5); % Path constraint
integral1 = {integrate(x3) - 1 == 0}; % Integral constraint
final3 = final(x3) >= 0.5; % Final event constraint
init1 = initial(x1) <= 2.0; % Initial event constraint
</pre>

'''NOTE''': When defining integral constraints that span over several phase, use either of the following notations:

<pre>
integrate(p1,x3p1) + integrate(p2,x3p1) + integrate(p3,x3p1) <= 2.1e3
</pre>

or with expressions:

<pre>
p1qx3 == integrate(p1,x3p1);
p2qx3 == integrate(p2,x3p1);
p3qx3 == integrate(p3,x3p1);

qx2sum = {p1qx3 + p2qx3 + p3qx3 <= 2.1e3};
</pre>

==Multi-phase optimal control==

''brysonDenhamTwoPhase.m ''is a good example for multi-phase optimal control. The user simply have to link the states to complete the problem formulation.

<pre>
link = {final(p1,x1p1) == initial(p2,x1p2)
final(p1,x2p1) == initial(p2,x2p2)};
</pre>

It is important to keep in mind that the costs have to be individually defined for the phases in the case that a integrating function is used.

==Scaling of optimal control problems==

Scaling of optimal control problems are best done after they are defined. The level of the cost function, variables, states and controls should be balanced around 1.

PROPT does however, have an automated scaling feature that could be tested if needed. The option can be activated by setting:

<pre>
options.scale = 'auto';
</pre>

''shuttleEntry.m ''and ''minimumClimbEng.m ''exemplify how to use and enable the scaling of optimal control problems.

==Setting solver and options==

The solver options can be set in ''options.*''. See ''help ezsolve ''for more information. The following code exemplifies some basic settings:

<pre>
options.solver = 'knitro'; % Change the solver
options.type = 'lpcon'; % Set the problem type to avoid identification
% Nonlinear problem with linear objective
</pre>

It is also possible to gain complete control over the solver by bypassing the ''ezsolve ''command and converting the problem to a standard TOMLAB Prob structure.

The following code will, for example, run vanDerPol (it is possible to edit the example directly of course), then convert the problem and run it with ALG 3 (SLQP) in KNITRO, and finally extract the standard solution.

<pre>
vanDerPol;
Prob = sym2prob(objective, {cbox, cbnd, ceq}, x0, options);
Prob.KNITRO.options.ALG = 3;
Result = tomRun('knitro', Prob, 1);
solution = getSolution(Result);
</pre>

==Solving optimal control problems==

The preceding sections show how to setup and define an optimal control problem using PROPT. Many addi- tional features have been implemented, such as advanced input error identification, to facilitate fast modeling and debugging.

[[PROPT functions for setting upp an ODE]]

===Advanced functions and operators===

Some user may wish to use more advanced function of PROPT as well. The following function can be useful in many situations.

====atPoints - Expand a propt tomSym to a set of points on a phase.====

y = atPoints(phase, t, x) for a m-by-n tomSym object x, and a vector t of length p, returns an p-by-m*n tomSym with values of x for each value of t (this is done via substitution).

If x is a cell array of tomSym objects, then atPoints is applied recursively to each element in the array.

If x is an equality or inequality, and the left-hand-side is divided by a symbolic phase.tdelta, then both sides are multiplied by phase.tdelta

See also: tomPhase

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

====interp1p - Polynomial interpolation.====

yi = interp1p(x,y,xi) fits a polynomial to the points (x,y) and evaluates that polynomial at xi to compute yi. The behavior of interp1p is different from that of interp1 in that the same high-degree polynomial is fitted to all points. This is usually not a good idea, and for general interpolation interp1 is to be preferred. However, it works well in some cases, such as when the points x are the roots of a Legendre polynomial.

Overloaded methods: tomSym/interp1p tomSym/interp1p

====proptGausspoints - Generate a list of gauss points.====

[r, w] = gausspoints(nquad) = proptGausspoints(n)

Input: n - The number of points requested

Output r - The Gauss points (roots of a Legendre polynomial of order n.) w - The weights for Gaussian quadrature.

====proptDiffMatrix - Differentiation matrix for interpPoly.====

M = proptDiffMatrix(X,XI,N) creates a matrix M of the values of the N:th derivatives of the interpolating polynomials defined by the roots X, at the points XI. Each column of M corresponds to a specific root, and each row corresponds to a component of XI.

===Screen output===

The screen output depends on the functionality of the nonlinear programming solver. In most cases screen output can be generated with the following command:

<pre>
options.PriLevOpt = 1; % or higher for more output
</pre>

A print level of 3 is recommended when using the global NLP solver ''multiMin''.

===Solution structure===

The solution structure from PROPT contains the relevant results.

It is possible to use the solution information to evaluate any custom expressions. For example:

<pre>
subs(x1.*x2,solution);
</pre>

===Plotting===

See [[Plotting and Evaluating PROPT Results]]

For a quick way to do a simple plot, see ''help tomSym/ezplot''.

==Optimal Control Examples==

*[[PROPT Optimal Control Examples|Optimal Control Examples]]

[[Category:PROPT]]

PdcoTL

2014-08-06T14:55:05Z

Bjorn: /* Description */

[[Category:Solvers]]
==Purpose==

''pdcoTL ''solves linearly constrained convex nonlinear optimization problems of the kind

====Equation: pdcoTL====
<math>
\begin{array}{cccccc}
\min\limits_x & f(x) \\
\mathrm{s/t} & x_L & \leq & x & \leq & x_U \\
{} & b_L & \leq & Ax & \leq & b_U \\
\end{array}
</math>

where <math>f(x)</math> is a convex nonlinear function, <math>x,x_L,x_U \in \mathbb{R}^{n}</math> , <math>A\in \mathbb{R}^{m \times n}</math> and <math>b_L, b_U \in \mathbb{R}^{m}</math>.

==Calling Syntax==

<source lang="matlab">
Result=tomRun('pdco',Prob,...);
</source>

==Inputs==

{| class="wikitable"
!''Prob''||colspan="2"|Problem description structure. The following fields are used:
|-
|||''x_0''||Initial ''x ''vector, used if non-empty.
|-
|||''A''||The linear constraint matrix.
|-
|||''b_L,b_U''||Lower and upper bounds for the linear constraints.
|-
|||''PriLevOpt''||Print level in ''pdsco ''solver. If ''> ''0: prints summary information.
|-
|||''SOL''||Structure with SOL special parameters:
|-
|||''pdco''||Options structure with fields as defined by ''pdcoSet''.
|-valign="top"
|||''d1''||Primal regularization vector. Must be a positive vector (length ''n'') or scalar, in which case ''D''1 = ''diag''(''d''1) is used. Default: 10''-''4 .
|-valign="top"
|||''d2''||Dual regularization vector. Must be a positive vector (length ''m'') or a scalar value, in which case ''D''2 = ''diag''(''d''2) is used. Default: 10''-''4 .
|-
|||''y0''||Initial dual parameters for linear constraints (default 0)
|-valign="top"
|||''z0''||Initial dual parameters for simple bounds (default 1''/N '')
''xsize'',''zsize ''are used to scale (''x, y, z''). Good estimates should improve the performance of the barrier method.
|-
|||''xsize''||Estimate of the biggest x at the solution. (default 1''/N '')
|-
|||''zsize''||Estimate of the biggest z at the solution. (default 1''/N '')
|-
|||''optParam''||Structure with optimization parameters. The following fields are used:
|-
|||''MaxIter''||Maximum number of iterations. (''Prob.SOL.pdco.MaxIter'').
|-valign="top"
|||''MinorIter''||Maximum number of iterations in ''LSQR'' (''Prob.SOL.pdco.LSQRMaxIter'').
|-
|||''eps_x''||Accuracy for satisfying ''x''1 ''. * z''1 = 0'', x''2 ''.z''1 = 0, where ''z ''= ''z''1 ''- z''2 and ''z''1 '', z''2 ''> ''0.(''Prob.SOL.pdco.OptTol'')
|-valign="top"
|||''bTol''||Accuracy for satisfying ''Ax ''+ ''D''2''r ''= ''b'', ''AT y ''+ ''z ''= ''∇f ''(''x'') and ''x - x''1 = ''bL , x ''+''x''2 = ''bU '', where ''x''1 '', x''2 ''> ''0 (''Prob.SOL.pdco.FeaTol'')
|-
|||''wait''||0 - solve the problem with default internal parameters; 1 - pause: allows interactive resetting of parameters. (''Prob.SOL.pdco.wait'')
|}

==Outputs==

{| class="wikitable"
!''Result''||colspan="2"|Structure with result from optimization. The following fields are set by ''pdcoTL''
|-
|||''x_k''||Solution vector
|-
|||''f_k''||Function value at optimum
|-
|||''g_k''||Gradient of the function at the solution
|-
|||''H_k''||Hessian of the function at the solution, diagonal only
|-
|||''x_0''||Initial solution vector
|-
|||''f_0''||Function value at start, x = x_0
|-
|||''xState''||State of variables. Free == 0; On lower == 1; On upper == 2; Fixed == 3;
|-valign="top"
|||''bState''||State of linear constraints. Free == 0; Lower == 1; Upper == 2; Equality == 3;
|-
|||''v_k''||Lagrangian multipliers (orignal bounds + constraints )
|-valign="top"
|||''y_k''||Lagrangian multipliers (for bounds + dual solution vector) The full [''z''; ''y''] vector as returned from ''pdco'', including slacks and extra linear constraints after rewriting constraints: ''-inf < b_L < A * x < b_U < inf ''; non-inf lower AND upper bounds
|-
|||''ExitFlag''||Tomlab Exit status from ''pdco ''MEX
|-
|||''Inform''||''pdco''information parameter: 0 = Solution found;
|-
|||0||Solution found
|-
|||1||Too many iterations
|-
|||2||Linesearch failed too often
|-
|||''Iter''||Number of iterations
|-
|||''FuncEv''||Number of function evaluations
|-
|||''GradEv''||Number of gradient evaluations
|-
|||''HessEv''||Number of Hessian evaluations
|-
|||''Solver''||Name of the solver ('pdco')
|-
|||''SolverAlgorithm''||Description of the solver
|}

==Description==

''pdco ''implements an primal-dual barrier method developed at Stanford Systems Optimization Laboratory (SOL).

The problem ([[#Equation: pdcoTL]]) is first reformulated into SOL PDCO form:

<math>
\begin{array}{cccccc}
\min\limits_x & f(x) \\
\mathrm{s/t} & x_L & \leq & x & \leq & x_U \\
{} & & & Ax & = & b \\
{} & {r \mathrm{\ unconstrained}} \\
\end{array}
</math>

The problem actually solved by ''pdco ''is

<math>
\begin{array}{lllcll}
\min\limits_{x,r} &
{\phi(x) + \frac{1}{2}\|D_1 x\|^2 + \frac{1}{2}\|r\|^2 } \\
\end{array}
</math>

<math>
\begin{array}{lllcll}
\mathrm{s/t} & x_L & \leq & x & \leq & x_U \\
{} & Ax & + & D_{2}r & = & b \\
\end{array}
</math>

where <math>D_1</math> and <math>D_2</math> are positive-definite diagonal matrices defined from <math>d_1</math>, <math>d_2</math> given in Prob.SOL.d1 and Prob.SOL.d2.

In particular, <math>d_2</math> indicates the accuracy required for satisfying each row of <math>Ax=b</math>. See ''pdco.m'' for a detailed discussion of <math>D_1</math> and <math>D_2</math>. Note that in ''pdco'', the objective <math>f(x)</math> is denoted <math>\phi(x)</math>, <math>bl == x\_L</math> and <math>bu == x\_U</math>.

==Examples==

Problem 14 and 15 in ''tomlab/testprob/con prob.m ''are good examples of the use of ''pdcoTL''.

==M-files Used==

''pdcoSet.m'', ''pdco.m'', ''Tlsqrmat.m''

==See Also==

''pdscoTL.m''

TOMLAB Overall Design

2014-08-05T14:20:45Z

Bjorn: /* Table: Generally constrained nonlinear (con) test problems. */

{{Part Of Manual|title=the TOMLAB Manual|link=[[TOMLAB|TOMLAB Manual]]}}
[[Category:Manuals]]
The scope of TOMLAB is large and broad, and therefore there is a need of a well-designed system. It is also natural to use the power of the Matlab language, to make the system flexible and easy to use and maintain. The concept of structure arrays is used and the ability in Matlab to execute Matlab code defined as string expressions and to execute functions specified by a string.

==Structure Input and Output==

Normally, when solving an optimization problem, a direct call to a solver is made with a long list of parameters in the call. The parameter list is solver-dependent and makes it difficult to make additions and changes to the system.

TOMLAB solves the problem in two steps. First the problem is defined and stored in a Matlab structure. Then the solver is called with a single argument, the problem structure. Solvers that were not originally developed for the TOMLAB environment needs the usual long list of parameters. This is handled by the driver routine ''tomRun.m'' which can call any available solver, hiding the details of the call from the user. The solver output is collected in a standardized result structure and returned to the user.

==Introduction to Solver and Problem Types==

TOMLAB solves a number of different types of optimization problems. The currently defined types are listed in [[#Table: The different types of optimization problems defined in TOMLAB.]].

The global variable ''probType ''contains the current type of optimization problem to be solved. An optimization solver is defined to be of type ''solvType'', where ''solvType ''is any of the ''probType ''entries in [[#Table: The different types of optimization problems defined in TOMLAB.]]. It is clear that a solver of a certain ''solvType ''is able to solve a problem defined to be of another type. For example, a constrained nonlinear programming solver should be able to solve unconstrained problems, linear and quadratic programs and constrained nonlinear least squares problems. In the graphical user interface and menu system an additional variable ''optType ''is defined to keep track of what type of problem is defined as the main subject. As an example, the user may select the type of optimization to be quadratic programming (''optType ''== 2), then select a particular problem that is a linear programming problem (''probType ''== 8) and then as the solver choose a constrained NLP solver like MINOS (''solvType ''== 3).

====Table: The different types of optimization problems defined in TOMLAB.====

{| class="wikitable"
!probType
!
!Type of optimization problem
|-
|'''uc'''||1||Unconstrained optimization (incl. bound constraints).
|-
|'''qp'''||2||Quadratic programming.
|-
|'''con'''||3||Constrained nonlinear optimization.
|-
|'''ls'''||4||Nonlinear least squares problems (incl. bound constraints).
|-
|'''lls'''||5||Linear least squares problems.
|-
|'''cls'''||6||Constrained nonlinear least squares problems.
|-
|'''mip'''||7||Mixed-Integer programming.
|-
|'''lp'''||8||Linear programming.
|-
|'''glb'''||9||Box-bounded global optimization.
|-
|'''glc'''||10||Global mixed-integer nonlinear programming.
|-
|'''miqp'''||11||Constrained mixed-integer quadratic programming.
|-
|'''minlp'''||12||Constrained mixed-integer nonlinear optimization.
|-
|'''lmi'''||13||Semi-definite programming with Linear Matrix Inequalities.
|-
|'''bmi'''||14||Semi-definite programming with Bilinear Matrix Inequalities.
|-
|'''exp'''||15||Exponential fitting problems.
|-
|'''nts'''||16||Nonlinear Time Series.
|-
|'''lcp'''||22||Linear Mixed-Complimentary Problems.
|-
|'''mcp'''||23||Nonlinear Mixed-Complimentary Problems.
|-
|}

Please note that since the actual numbers used for ''probType ''may change in future releases, it is recommended to use the text abbreviations. See help for ''checkType ''for further information.

Define ''probSet ''to be a set of defined optimization problems belonging to a certain class of problems of type ''probType''. Each ''probSet ''is physically stored in one file, an ''Init File''. In [[#Table: Defined test problem sets in TOMLAB. probSets marked with * are not part of the standard distribution]] the currently defined problem sets are listed, and new ''probSet ''sets are easily added.

====Table: Defined test problem sets in TOMLAB. probSets marked with * are not part of the standard distribution====

{| class="wikitable"
!probSet
!probType
!Description of test problem set
|-
|'''uc'''||1||Unconstrained test problems.
|-
|'''qp'''||2||Quadratic programming test problems.
|-
|'''con'''||3||Constrained test problems.
|-
|'''ls'''||4||Nonlinear least squares test problems.
|-
|'''lls'''||5||Linear least squares problems.
|-
|'''cls'''||6||Linear constrained nonlinear least squares problems.
|-
|'''mip'''||7||Mixed-integer programming problems.
|-
|'''lp'''||8||Linear programming problems.
|-
|'''glb'''||9||Box-bounded global optimization test problems.
|-
|'''glc'''||10||Global MINLP test problems.
|-
|'''miqp'''||11||Constrained mixed-integer quadratic problems.
|-
|'''minlp'''||12||Constrained mixed-integer nonlinear problems.
|-
|'''lmi'''||13||Semi-definite programming with Linear Matrix Inequalities.
|-
|'''bmi'''||14||Semi-definite programming with Bilinear Matrix Inequalities.
|-
|'''exp'''||15||Exponential fitting problems.
|-
|'''nts'''||16||Nonlinear time series problems.
|-
|'''lcp'''||22||Linear mixed-complimentary problems.
|-
|'''mcp'''||23||Nonlinear mixed-complimentary problems.
|-
|'''mgh'''||4||More, Garbow, Hillstrom nonlinear least squares problems.
|-
|'''chs'''||3||Hock-Schittkowski constrained test problems.
|-
|'''uhs'''||1||Hock-Schittkowski unconstrained test problems.
|-
|}

The names of the predefined Init Files that do the problem setup, and the corresponding low level routines are constructed as two parts. The first part being the abbreviation of the relevant ''probSet'', see [[#Table: Defined test problem sets in TOMLAB. probSets marked with * are not part of the standard distribution]], and the second part denotes the computed task, shown in [[#Table: Names for predefined Init Files and low level m-files in TOMLAB.]] The user normally does not have to define the more complicated functions ''o_d2c ''and ''o_d2r''. It is recommended to supply this information when using solvers which can utilize second order information, such as TOMLAB /KNITRO and TOMLAB /CONOPT.

====Table: Names for predefined Init Files and low level m-files in TOMLAB.====
{| class="wikitable" style="background-color:#ffffff;"
!Generic name
!Purpose (''o'' is any probSet, e.g. ''o''=con)
|-
|''o_''prob||Init File that either defines a string matrix with problem names
|-
|''o_''f||Compute objective function <math>f(x)</math>.
|-
|''o_''g||Compute the gradient vector <math>g(x)</math>.
|-
|''o_''H||Compute the Hessian matrix <math>H(x)</math>.
|-
|''o_''c||Compute the vector of constraint functions <math>c(x)</math>.
|-
|''o_''dc||Compute the matrix of constraint normals, <math>\partial c(x) /dx</math>.
|-
|''o_''d2c||Compute the 2nd part of 2nd derivative matrix of the Lagrangian function, <math>\sum_i \lambda_i \partial^2 c_i(x) / dx^2</math> .
|-
|''o_''r||Compute the residual vector <math>r(x)</math>.
|-
|''o_''J ||Compute the Jacobian matrix <math>J(x)</math>.
|-
|''o_''d2r||Compute the 2nd part of the Hessian matrix, <math>\sum_i r_i(x) \partial^2 r_i(x) / dx^2</math>
|-
|}

The Init File has two modes of operation; either return a string matrix with the names of the problems in the ''probSet ''or a structure with all information about the selected problem. All fields in the structure, named ''Prob'', are presented in tables in [[TOMLAB Appendix A|Appendix A]]. Using a structure makes it easy to add new items without too many changes in the rest of the system. For further discussion about the definition of optimization problems in TOMLAB, see [[TOMLAB Defining Problems in TOMLAB|Defining Problems in TOMLAB]].

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.

==The Process of Solving Optimization Problems==

A flow-chart of the process of optimization in TOMLAB is shown in [[#Figure: The process of optimization in TOMLAB.]]. It is inefficient to use an interactive system. This is symbolized with the ''Standard User'' box in the figure, which directly runs the ''Optimization Driver'', ''tomRun''. The direct solver call is possible for all TOMLAB solvers, if the user has executed ''ProbCheck ''prior to the call. See [[TOMLAB Problem Types and Solver Routines]] for a list of the TOMLAB solvers.

Depending on the type of problem, the user needs to supply the ''low-level ''routines that calculate the objective function, constraint functions for constrained problems, and also if possible, derivatives. To simplify this coding process so that the work has to be performed only once, TOMLAB provides ''gateway ''routines that ensure that any solver can obtain the values in the correct format.

For example, when working with a least squares problem, it is natural to code the function that computes the vector of residual functions <math>r_i(x_1,x_2,\ldots)</math>, since a dedicated least squares solver probably operates on the residual while a general nonlinear solver needs a scalar function, in this case <math>f(x) = \frac{1}{2} r^T(x)r(x)</math>. Such issues are automatically handled by the gateway functions.

====Figure: The process of optimization in TOMLAB.====
[[File:The process of optimization in TOMLAB.png|thumb|550px|none|alt=The process of optimization in TOMLAB|<caption>The process of optimization in TOMLAB.</caption>]]

==Low Level Routines and Gateway Routines==

''Low level routines ''are the routines that compute:

*The objective function value

*The gradient vector

*The Hessian matrix (second derivative matrix)

*The residual vector (for nonlinear least squares problems)

*The Jacobian matrix (for nonlinear least squares problems)

*The vector of constraint functions

*The matrix of constraint normals (the constraint Jacobian)

*The second part of the second derivative of the Lagrangian function. The last three routines are only needed for constrained problems.

The names of these routines are defined in the structure fields ''Prob.FUNCS.f'', ''Prob.FUNCS.g'', ''Prob.FUNCS.H ''etc.

It is the task for the ''Assign ''routine to set the names of the low level m-files. This is done by a call to the routine ''conAssign ''with the names as arguments for example. There are ''Assign ''routines for all problem types handled by TOMLAB. As an example, see 'help conAssign' in MATLAB.

<source lang="matlab">
Prob = conAssign('f', 'g', 'H', HessPattern, x_L, x_U, Name,x_0,...
pSepFunc, fLowBnd, A, b_L, b_U, 'c', 'dc', 'd2c', ConsPattern,...
c_L, c_U, x_min, x_max, f_opt, x_opt);
</source>

Only the low level routines relevant for a certain type of optimization problem need to be coded. There are dummy routines for the others. Numerical differentiation is automatically used for gradient, Jacobian and constraint gradient if the corresponding user routine is non present or left out when calling ''conAssign''. However, the solver always needs more time to estimate the derivatives compared to if the user supplies a code for them. Also the numerical accuracy is lower for estimated derivatives, so it is recommended that the user always tries to code the derivatives, if it is possible. Another option is automatic differentiation with TOMLAB /MAD.

TOMLAB uses gateway routines (''nlp_f'', ''nlp_g'', ''nlp_H'', ''nlp_c'', ''nlp_dc'', ''nlp_d2c'', ''nlp_r'', ''nlp_J'', ''nlp_d2r''). These routines extract the search directions and line search steps, count iterations, handle separable functions, keep track of the kind of differentiation wanted etc. They also handle the separable NLLS case and NLLS weighting. By the use of global variables, unnecessary evaluations of the user supplied routines are avoided.

To get a picture of how the low-level routines are used in the system, consider [[#The chain of calls when computing the objective function value in ucSolve for a nonlinear least squares problem defined in mgh_prob, mgh_r and mgh_J.]] and [[#The chain of calls when computing the numerical approximation of the gradient in ''ucSolve'' for an unconstrained problem defined in uc_prob and uc_f.]]. [[#The chain of calls when computing the objective function value in ucSolve for a nonlinear least squares problem defined in mgh_prob, mgh_r and mgh_J.]] illustrates the chain of calls when computing the objective function value in ''ucSolve ''for a nonlinear least squares problem defined in ''mgh prob'', ''mgh r ''and ''mgh J''. [[#The chain of calls when computing the numerical approximation of the gradient in ucSolve for an unconstrained problem defined in uc_prob and uc_f.]] illustrates the chain of calls when computing the numerical approximation of the gradient (by use of the routine ''fdng'') in ''ucSolve ''for an unconstrained problem defined in ''uc_prob ''and ''uc_f''. Information about a problem is stored in the structure variable ''Prob'', described in detail in the tables in Appendix A. This variable is an argument to all low level routines. In the field element ''Prob.user'', problem specific information

====The chain of calls when computing the objective function value in ''ucSolve'' for a nonlinear least squares problem defined in ''mgh_prob'', ''mgh_r ''and ''mgh_J''.====
<source lang="matlab">
ucSolve <==> nlp_f <==> ls_f <==> nlp_r <==> mgh_r
</source>

====The chain of calls when computing the numerical approximation of the gradient in ''ucSolve'' for an unconstrained problem defined in ''uc_prob ''and ''uc_f''.====
<source lang="matlab">
ucSolve <==> nlp_g <==> fdng <==> nlp_r <==> uc_f
</source>

needed to evaluate the low level routines are stored. This field is most often used if problem related questions are asked when generating the problem. It is often the case that the user wants to supply the low-level routines with additional information besides the variables ''x'' that are optimized. Any unused fields could be defined in the structure ''Prob'' for that purpose. To avoid potential conflicts with future TOMLAB releases, it is recommended to use subfields of ''Prob.user''. It the user wants to send some variables a, B and C, then, after creating the ''Prob'' structure, these extra variables are added to the structure:

<source lang="matlab">
Prob.user.a=a;
Prob.user.B=B;
Prob.user.C=C;
</source>

Then, because the ''Prob'' structure is sent to all low-level routines, in any of these routines the variables are picked out from the structure:

<source lang="matlab">
a = Prob.user.a;
B = Prob.user.B;
C = Prob.user.C;
</source>

A more detailed description of how to define new problems is given in sections [[TOMLAB Solving Linear Quadratic and Integer Programming Problems]], [[TOMLAB Solving Unconstrained and Constrained Optimization Problems]] and [[TOMLAB Solving Global Optimization Problems]]. The usage of ''Prob.user'' is described in [[TOMLAB Utility Functions#User Supplied Problem Parameters]].

Different solvers all have different demand on how information should be supplied, i.e. the function to optimize, the gradient vector, the Hessian matrix etc. To be able to code the problem only once, and then use this formulation to run all types of solvers, interface routines that returns information in the format needed for the relevant solver were developed.

[[#Table: Generally constrained nonlinear (con) test problems.]] describes the low level test functions and the corresponding Init File routine needed for the predefined constrained optimization ('''con''') problems. For the predefined unconstrained optimization ('''uc''') problems, the global optimization ('''glb, glc''') problems and the quadratic programming problems ('''qp''') similar routines have been defined.

To conclude, the system design is flexible and easy to expand in many different ways.

====Table: Generally constrained nonlinear (con) test problems.====

{| class="wikitable" style="background-color:#ffffff;"
!Function
!Description
|-
|''con_prob''||Init File. Does the initialization of the '''con '''test problems.
|-
|''con_f''||Compute the objective function <math>f(x)</math> for '''con''' test problems.
|-
|''con_g''||Compute the gradient <math>g(x)</math> for '''con''' test problems.
|-
|''con_H''||Compute the Hessian matrix <math>H(x)</math> of <math>f(x)</math> for '''con ''' test problems.
|-
|''con_c''||Compute the constraint residuals <math>c(x)</math> for '''con''' test problems.
|-
|''con_dc''||Compute the derivative of the constraint residuals for '''con''' test problems.
|-
|''con_d2c''||Compute the 2nd part of 2nd derivative matrix of the Lagrangian function, <math>\sum_i \lambda_i \partial^2 c_i(x) / dx^2</math> for '''con ''' test problems.
|-
|''con_fm''||Compute merit function <math>\theta(x_k)</math>.
|-
|''con_gm''||Compute gradient of merit function <math>\theta(x_k)</math>.
|}

TOMLAB Overall Design

2014-08-05T14:20:27Z

Bjorn: /* Table: Names for predefined Init Files and low level m-files in TOMLAB. */

{{Part Of Manual|title=the TOMLAB Manual|link=[[TOMLAB|TOMLAB Manual]]}}
[[Category:Manuals]]
The scope of TOMLAB is large and broad, and therefore there is a need of a well-designed system. It is also natural to use the power of the Matlab language, to make the system flexible and easy to use and maintain. The concept of structure arrays is used and the ability in Matlab to execute Matlab code defined as string expressions and to execute functions specified by a string.

==Structure Input and Output==

Normally, when solving an optimization problem, a direct call to a solver is made with a long list of parameters in the call. The parameter list is solver-dependent and makes it difficult to make additions and changes to the system.

TOMLAB solves the problem in two steps. First the problem is defined and stored in a Matlab structure. Then the solver is called with a single argument, the problem structure. Solvers that were not originally developed for the TOMLAB environment needs the usual long list of parameters. This is handled by the driver routine ''tomRun.m'' which can call any available solver, hiding the details of the call from the user. The solver output is collected in a standardized result structure and returned to the user.

==Introduction to Solver and Problem Types==

TOMLAB solves a number of different types of optimization problems. The currently defined types are listed in [[#Table: The different types of optimization problems defined in TOMLAB.]].

The global variable ''probType ''contains the current type of optimization problem to be solved. An optimization solver is defined to be of type ''solvType'', where ''solvType ''is any of the ''probType ''entries in [[#Table: The different types of optimization problems defined in TOMLAB.]]. It is clear that a solver of a certain ''solvType ''is able to solve a problem defined to be of another type. For example, a constrained nonlinear programming solver should be able to solve unconstrained problems, linear and quadratic programs and constrained nonlinear least squares problems. In the graphical user interface and menu system an additional variable ''optType ''is defined to keep track of what type of problem is defined as the main subject. As an example, the user may select the type of optimization to be quadratic programming (''optType ''== 2), then select a particular problem that is a linear programming problem (''probType ''== 8) and then as the solver choose a constrained NLP solver like MINOS (''solvType ''== 3).

====Table: The different types of optimization problems defined in TOMLAB.====

{| class="wikitable"
!probType
!
!Type of optimization problem
|-
|'''uc'''||1||Unconstrained optimization (incl. bound constraints).
|-
|'''qp'''||2||Quadratic programming.
|-
|'''con'''||3||Constrained nonlinear optimization.
|-
|'''ls'''||4||Nonlinear least squares problems (incl. bound constraints).
|-
|'''lls'''||5||Linear least squares problems.
|-
|'''cls'''||6||Constrained nonlinear least squares problems.
|-
|'''mip'''||7||Mixed-Integer programming.
|-
|'''lp'''||8||Linear programming.
|-
|'''glb'''||9||Box-bounded global optimization.
|-
|'''glc'''||10||Global mixed-integer nonlinear programming.
|-
|'''miqp'''||11||Constrained mixed-integer quadratic programming.
|-
|'''minlp'''||12||Constrained mixed-integer nonlinear optimization.
|-
|'''lmi'''||13||Semi-definite programming with Linear Matrix Inequalities.
|-
|'''bmi'''||14||Semi-definite programming with Bilinear Matrix Inequalities.
|-
|'''exp'''||15||Exponential fitting problems.
|-
|'''nts'''||16||Nonlinear Time Series.
|-
|'''lcp'''||22||Linear Mixed-Complimentary Problems.
|-
|'''mcp'''||23||Nonlinear Mixed-Complimentary Problems.
|-
|}

Please note that since the actual numbers used for ''probType ''may change in future releases, it is recommended to use the text abbreviations. See help for ''checkType ''for further information.

Define ''probSet ''to be a set of defined optimization problems belonging to a certain class of problems of type ''probType''. Each ''probSet ''is physically stored in one file, an ''Init File''. In [[#Table: Defined test problem sets in TOMLAB. probSets marked with * are not part of the standard distribution]] the currently defined problem sets are listed, and new ''probSet ''sets are easily added.

====Table: Defined test problem sets in TOMLAB. probSets marked with * are not part of the standard distribution====

{| class="wikitable"
!probSet
!probType
!Description of test problem set
|-
|'''uc'''||1||Unconstrained test problems.
|-
|'''qp'''||2||Quadratic programming test problems.
|-
|'''con'''||3||Constrained test problems.
|-
|'''ls'''||4||Nonlinear least squares test problems.
|-
|'''lls'''||5||Linear least squares problems.
|-
|'''cls'''||6||Linear constrained nonlinear least squares problems.
|-
|'''mip'''||7||Mixed-integer programming problems.
|-
|'''lp'''||8||Linear programming problems.
|-
|'''glb'''||9||Box-bounded global optimization test problems.
|-
|'''glc'''||10||Global MINLP test problems.
|-
|'''miqp'''||11||Constrained mixed-integer quadratic problems.
|-
|'''minlp'''||12||Constrained mixed-integer nonlinear problems.
|-
|'''lmi'''||13||Semi-definite programming with Linear Matrix Inequalities.
|-
|'''bmi'''||14||Semi-definite programming with Bilinear Matrix Inequalities.
|-
|'''exp'''||15||Exponential fitting problems.
|-
|'''nts'''||16||Nonlinear time series problems.
|-
|'''lcp'''||22||Linear mixed-complimentary problems.
|-
|'''mcp'''||23||Nonlinear mixed-complimentary problems.
|-
|'''mgh'''||4||More, Garbow, Hillstrom nonlinear least squares problems.
|-
|'''chs'''||3||Hock-Schittkowski constrained test problems.
|-
|'''uhs'''||1||Hock-Schittkowski unconstrained test problems.
|-
|}

The names of the predefined Init Files that do the problem setup, and the corresponding low level routines are constructed as two parts. The first part being the abbreviation of the relevant ''probSet'', see [[#Table: Defined test problem sets in TOMLAB. probSets marked with * are not part of the standard distribution]], and the second part denotes the computed task, shown in [[#Table: Names for predefined Init Files and low level m-files in TOMLAB.]] The user normally does not have to define the more complicated functions ''o_d2c ''and ''o_d2r''. It is recommended to supply this information when using solvers which can utilize second order information, such as TOMLAB /KNITRO and TOMLAB /CONOPT.

====Table: Names for predefined Init Files and low level m-files in TOMLAB.====
{| class="wikitable" style="background-color:#ffffff;"
!Generic name
!Purpose (''o'' is any probSet, e.g. ''o''=con)
|-
|''o_''prob||Init File that either defines a string matrix with problem names
|-
|''o_''f||Compute objective function <math>f(x)</math>.
|-
|''o_''g||Compute the gradient vector <math>g(x)</math>.
|-
|''o_''H||Compute the Hessian matrix <math>H(x)</math>.
|-
|''o_''c||Compute the vector of constraint functions <math>c(x)</math>.
|-
|''o_''dc||Compute the matrix of constraint normals, <math>\partial c(x) /dx</math>.
|-
|''o_''d2c||Compute the 2nd part of 2nd derivative matrix of the Lagrangian function, <math>\sum_i \lambda_i \partial^2 c_i(x) / dx^2</math> .
|-
|''o_''r||Compute the residual vector <math>r(x)</math>.
|-
|''o_''J ||Compute the Jacobian matrix <math>J(x)</math>.
|-
|''o_''d2r||Compute the 2nd part of the Hessian matrix, <math>\sum_i r_i(x) \partial^2 r_i(x) / dx^2</math>
|-
|}

The Init File has two modes of operation; either return a string matrix with the names of the problems in the ''probSet ''or a structure with all information about the selected problem. All fields in the structure, named ''Prob'', are presented in tables in [[TOMLAB Appendix A|Appendix A]]. Using a structure makes it easy to add new items without too many changes in the rest of the system. For further discussion about the definition of optimization problems in TOMLAB, see [[TOMLAB Defining Problems in TOMLAB|Defining Problems in TOMLAB]].

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.

==The Process of Solving Optimization Problems==

A flow-chart of the process of optimization in TOMLAB is shown in [[#Figure: The process of optimization in TOMLAB.]]. It is inefficient to use an interactive system. This is symbolized with the ''Standard User'' box in the figure, which directly runs the ''Optimization Driver'', ''tomRun''. The direct solver call is possible for all TOMLAB solvers, if the user has executed ''ProbCheck ''prior to the call. See [[TOMLAB Problem Types and Solver Routines]] for a list of the TOMLAB solvers.

Depending on the type of problem, the user needs to supply the ''low-level ''routines that calculate the objective function, constraint functions for constrained problems, and also if possible, derivatives. To simplify this coding process so that the work has to be performed only once, TOMLAB provides ''gateway ''routines that ensure that any solver can obtain the values in the correct format.

For example, when working with a least squares problem, it is natural to code the function that computes the vector of residual functions <math>r_i(x_1,x_2,\ldots)</math>, since a dedicated least squares solver probably operates on the residual while a general nonlinear solver needs a scalar function, in this case <math>f(x) = \frac{1}{2} r^T(x)r(x)</math>. Such issues are automatically handled by the gateway functions.

====Figure: The process of optimization in TOMLAB.====
[[File:The process of optimization in TOMLAB.png|thumb|550px|none|alt=The process of optimization in TOMLAB|<caption>The process of optimization in TOMLAB.</caption>]]

==Low Level Routines and Gateway Routines==

''Low level routines ''are the routines that compute:

*The objective function value

*The gradient vector

*The Hessian matrix (second derivative matrix)

*The residual vector (for nonlinear least squares problems)

*The Jacobian matrix (for nonlinear least squares problems)

*The vector of constraint functions

*The matrix of constraint normals (the constraint Jacobian)

*The second part of the second derivative of the Lagrangian function. The last three routines are only needed for constrained problems.

The names of these routines are defined in the structure fields ''Prob.FUNCS.f'', ''Prob.FUNCS.g'', ''Prob.FUNCS.H ''etc.

It is the task for the ''Assign ''routine to set the names of the low level m-files. This is done by a call to the routine ''conAssign ''with the names as arguments for example. There are ''Assign ''routines for all problem types handled by TOMLAB. As an example, see 'help conAssign' in MATLAB.

<source lang="matlab">
Prob = conAssign('f', 'g', 'H', HessPattern, x_L, x_U, Name,x_0,...
pSepFunc, fLowBnd, A, b_L, b_U, 'c', 'dc', 'd2c', ConsPattern,...
c_L, c_U, x_min, x_max, f_opt, x_opt);
</source>

Only the low level routines relevant for a certain type of optimization problem need to be coded. There are dummy routines for the others. Numerical differentiation is automatically used for gradient, Jacobian and constraint gradient if the corresponding user routine is non present or left out when calling ''conAssign''. However, the solver always needs more time to estimate the derivatives compared to if the user supplies a code for them. Also the numerical accuracy is lower for estimated derivatives, so it is recommended that the user always tries to code the derivatives, if it is possible. Another option is automatic differentiation with TOMLAB /MAD.

TOMLAB uses gateway routines (''nlp_f'', ''nlp_g'', ''nlp_H'', ''nlp_c'', ''nlp_dc'', ''nlp_d2c'', ''nlp_r'', ''nlp_J'', ''nlp_d2r''). These routines extract the search directions and line search steps, count iterations, handle separable functions, keep track of the kind of differentiation wanted etc. They also handle the separable NLLS case and NLLS weighting. By the use of global variables, unnecessary evaluations of the user supplied routines are avoided.

To get a picture of how the low-level routines are used in the system, consider [[#The chain of calls when computing the objective function value in ucSolve for a nonlinear least squares problem defined in mgh_prob, mgh_r and mgh_J.]] and [[#The chain of calls when computing the numerical approximation of the gradient in ''ucSolve'' for an unconstrained problem defined in uc_prob and uc_f.]]. [[#The chain of calls when computing the objective function value in ucSolve for a nonlinear least squares problem defined in mgh_prob, mgh_r and mgh_J.]] illustrates the chain of calls when computing the objective function value in ''ucSolve ''for a nonlinear least squares problem defined in ''mgh prob'', ''mgh r ''and ''mgh J''. [[#The chain of calls when computing the numerical approximation of the gradient in ucSolve for an unconstrained problem defined in uc_prob and uc_f.]] illustrates the chain of calls when computing the numerical approximation of the gradient (by use of the routine ''fdng'') in ''ucSolve ''for an unconstrained problem defined in ''uc_prob ''and ''uc_f''. Information about a problem is stored in the structure variable ''Prob'', described in detail in the tables in Appendix A. This variable is an argument to all low level routines. In the field element ''Prob.user'', problem specific information

====The chain of calls when computing the objective function value in ''ucSolve'' for a nonlinear least squares problem defined in ''mgh_prob'', ''mgh_r ''and ''mgh_J''.====
<source lang="matlab">
ucSolve <==> nlp_f <==> ls_f <==> nlp_r <==> mgh_r
</source>

====The chain of calls when computing the numerical approximation of the gradient in ''ucSolve'' for an unconstrained problem defined in ''uc_prob ''and ''uc_f''.====
<source lang="matlab">
ucSolve <==> nlp_g <==> fdng <==> nlp_r <==> uc_f
</source>

needed to evaluate the low level routines are stored. This field is most often used if problem related questions are asked when generating the problem. It is often the case that the user wants to supply the low-level routines with additional information besides the variables ''x'' that are optimized. Any unused fields could be defined in the structure ''Prob'' for that purpose. To avoid potential conflicts with future TOMLAB releases, it is recommended to use subfields of ''Prob.user''. It the user wants to send some variables a, B and C, then, after creating the ''Prob'' structure, these extra variables are added to the structure:

<source lang="matlab">
Prob.user.a=a;
Prob.user.B=B;
Prob.user.C=C;
</source>

Then, because the ''Prob'' structure is sent to all low-level routines, in any of these routines the variables are picked out from the structure:

<source lang="matlab">
a = Prob.user.a;
B = Prob.user.B;
C = Prob.user.C;
</source>

A more detailed description of how to define new problems is given in sections [[TOMLAB Solving Linear Quadratic and Integer Programming Problems]], [[TOMLAB Solving Unconstrained and Constrained Optimization Problems]] and [[TOMLAB Solving Global Optimization Problems]]. The usage of ''Prob.user'' is described in [[TOMLAB Utility Functions#User Supplied Problem Parameters]].

Different solvers all have different demand on how information should be supplied, i.e. the function to optimize, the gradient vector, the Hessian matrix etc. To be able to code the problem only once, and then use this formulation to run all types of solvers, interface routines that returns information in the format needed for the relevant solver were developed.

[[#Table: Generally constrained nonlinear (con) test problems.]] describes the low level test functions and the corresponding Init File routine needed for the predefined constrained optimization ('''con''') problems. For the predefined unconstrained optimization ('''uc''') problems, the global optimization ('''glb, glc''') problems and the quadratic programming problems ('''qp''') similar routines have been defined.

To conclude, the system design is flexible and easy to expand in many different ways.

====Table: Generally constrained nonlinear (con) test problems.====

{| class="wikitable"
!Function
!Description
|-
|''con_prob''||Init File. Does the initialization of the '''con '''test problems.
|-
|''con_f''||Compute the objective function <math>f(x)</math> for '''con''' test problems.
|-
|''con_g''||Compute the gradient <math>g(x)</math> for '''con''' test problems.
|-
|''con_H''||Compute the Hessian matrix <math>H(x)</math> of <math>f(x)</math> for '''con ''' test problems.
|-
|''con_c''||Compute the constraint residuals <math>c(x)</math> for '''con''' test problems.
|-
|''con_dc''||Compute the derivative of the constraint residuals for '''con''' test problems.
|-
|''con_d2c''||Compute the 2nd part of 2nd derivative matrix of the Lagrangian function, <math>\sum_i \lambda_i \partial^2 c_i(x) / dx^2</math> for '''con ''' test problems.
|-
|''con_fm''||Compute merit function <math>\theta(x_k)</math>.
|-
|''con_gm''||Compute gradient of merit function <math>\theta(x_k)</math>.
|}

TOMLAB Solving Least Squares and Parameter Estimation Problems

2014-08-05T14:18:56Z

Bjorn: /* Table: Exponential fitting test problems. */

{{Part Of Manual|title=the TOMLAB Manual|link=[[TOMLAB|TOMLAB Manual]]}}
[[Category:Manuals]]
This section describes how to define and solve different types of linear and nonlinear least squares and parameter estimation problems. Several examples are given on how to proceed, depending on if a quick solution is wanted, or more advanced tests are needed. TOMLAB is also compatible with MathWorks Optimization TB. See [[TOMLAB Appendix E]] for more information and test examples.

All demonstration examples that are using the TOMLAB format are collected in the directory ''examples''. The examples relevant to this section are ''lsDemo ''and ''llsDemo''. The full path to these files are always given in the text.

[[TOMLAB_Solving_Least_Squares_and_Parameter_Estimation_Problems#Large_Scale_LS_problems_with_Tlsqr|Large Scale LS problems with Tlsqr]] contains information on solving extreme large-scale '''ls '''problems with ''Tlsqr''.

==Linear Least Squares Problems==

This section shows examples how to define and solve linear least squares problems using the TOMLAB format. As a first illustration, the example ''lls1Demo ''in file ''llsDemo ''shows how to fit a linear least squares model with linear constraints to given data. This test problem is taken from the User's Guide of ''LSSOL''.

<source lang="matlab">
Name='LSSOL test example';

% In TOMLAB it is best to use Inf and -Inf, not big numbers.
n = 9; % Number of unknown parameters
x_L = [-2 -2 -Inf, -2*ones(1,6)]';
x_U = 2*ones(n,1);

A = [ ones(1,8) 4; 1:4,-2,1 1 1 1; 1 -1 1 -1, ones(1,5)];
b_L = [2 -Inf -4]';
b_U = [Inf -2 -2]';

y = ones(10,1);
C = [ ones(1,n); 1 2 1 1 1 1 2 0 0; 1 1 3 1 1 1 -1 -1 -3; ...
1 1 1 4 1 1 1 1 1;1 1 1 3 1 1 1 1 1; 1 1 2 1 1 0 0 0 -1; ...
1 1 1 1 0 1 1 1 1;1 1 1 0 1 1 1 1 1; 1 1 0 1 1 1 2 2 3; ...
1 0 1 1 1 1 0 2 2];

x_0 = 1./[1:n]';

t = []; % No time set for y(t) (used for plotting)
weightY = []; % No weighting
weightType = []; % No weighting type set

x_min = []; % No lower bound for plotting
x_max = []; % No upper bound for plotting

Prob = llsAssign(C, y, x_L, x_U, Name, x_0, t, weightType, weightY, ...
A, b_L, b_U, x_min, x_max); Result = tomRun('lsei',Prob,2);
</source>

It is trivial to change the solver in the call to ''tomRun'' to a nonlinear least squares solver, e.g. ''clsSolve'', or a general nonlinear programming solver.

==Linear Least Squares Problems using the SOL Solver LSSOL==

The example ''lls2Demo'' in file ''llsDemo'' shows how to fit a linear least squares model with linear constraints to given data using a direct call to the SOL solver ''LSSOL''. The test problem is taken from the User's Guide of ''LSSOL''.

<source lang="matlab">
% Note that when calling the LSSOL MEX interface directly, avoid using
% Inf and -Inf. Instead use big numbers that indicate Inf.
% The standard for the MEX interfaces is 1E20 and -1E20, respectively.

n = 9; % There are nine unknown parameters, and 10 equations
x_L = [-2 -2 -1E20, -2*ones(1,6)]';
x_U = 2*ones(n,1);

A = [ ones(1,8) 4; 1:4,-2,1 1 1 1; 1 -1 1 -1, ones(1,5)];
b_L = [2 -1E20 -4]';
b_U = [1E20 -2 -2]';
% Must put lower and upper bounds on variables and constraints together
bl = [x_L;b_L];
bu = [x_U;b_U];

H = [ ones(1,n); 1 2 1 1 1 1 2 0 0; 1 1 3 1 1 1 -1 -1 -3; ...
1 1 1 4 1 1 1 1 1;1 1 1 3 1 1 1 1 1;1 1 2 1 1 0 0 0 -1; ...
1 1 1 1 0 1 1 1 1;1 1 1 0 1 1 1 1 1;1 1 0 1 1 1 2 2 3; ...
1 0 1 1 1 1 0 2 2];
y = ones(10,1);

x_0 = 1./[1:n]';

% Set empty indicating default values for most variables
c = []; % No linear coefficients, they are for LP/QP
Warm = []; % No warm start
iState = []; % No warm start
Upper = []; % C is not factorized
kx = []; % No warm start
SpecsFile = []; % No parameter settings in a SPECS file
PriLev = []; % PriLev is not really used in LSSOL
ProbName = []; % ProbName is not really used in LSSOL
optPar(1) = 50; % Set print level at maximum
PrintFile = 'lssol.txt'; % Print result on the file with name lssol.txt

z0 = (y-H*x_0);
f0 = 0.5*z0'*z0;
fprintf('Initial function value %f\n',f0);

[x, Inform, iState, cLamda, Iter, fObj, r, kx] = ...
lssol( A, bl, bu, c, x_0, optPar, H, y, Warm, ...
iState, Upper, kx, SpecsFile, PrintFile, PriLev, ProbName );

% We could equally well call with the following shorter call:
% [x, Inform, iState, cLamda, Iter, fObj, r, kx] = ...
% lssol( A, bl, bu, c, x, optPar, H, y);

z = (y-H*x);
f = 0.5*z'*z;
fprintf('Optimal function value %f\n',f);
</source>

==Nonlinear Least Squares Problems==

This section shows examples how to define and solve nonlinear least squares problems using the TOMLAB format. As a first illustration, the example ''ls1Demo ''in file ''lsDemo ''shows how to fit a nonlinear model of exponential type with three unknown parameters to experimental data. This problem, ''Gisela'', is also defined as problem three in ''ls_prob''. A weighting parameter ''K ''is sent to the residual and Jacobian routine using the ''Prob ''structure. The solver ''clsSolve ''is called directly. Note that the user only defines the routine to compute the residual vector and the Jacobian matrix of derivatives. TOMLAB has special routines ''ls f'', ''ls g ''and ''ls H ''that computes the nonlinear least squares objective function value, given the residuals, as well as the gradient and the approximative Hessian, see [[#Table: Constrained nonlinear least squares (cls) test problems.]]. The residual routine for this problem is defined in file ''ls1_r ''in the directory ''example'' with the statements

<source lang="matlab">
function r = ls_r(x, Prob)

% Compute residuals to nonlinear least squares problem Gisela

% US_A is the standard TOMLAB global parameter to be used in the
% communication between the residual and the Jacobian routine

global US_A

% The extra weight parameter K is sent as part of the structure
K = Prob.user.K;
t = Prob.LS.t(:); % Pick up the time points

% Exponential expressions to be later used when computing the Jacobian
US_A.e1 = exp(-x(1)*t); US_A.e2 = exp(-x(2)*t);

r = K*x(1)*(US_A.e2 - US_A.e1) / (x(3)*(x(1)-x(2))) - Prob.LS.y;
</source>

Note that this example also shows how to communicate information between the residual and the Jacobian routine. It is best to use any of the predefined global variables ''US_A'' and ''US_B'', because then there will be no conflicts with respect to global variables if recursive calls are used. In this example the global variable ''US_A'' is used as structure array storing two vectors with exponential expressions. The Jacobian routine for this problem is defined in the file ''ls1_J '' in the directory ''example''. The global variable ''US_A'' is accessed to obtain the exponential expressions, see the statements below.

<source lang="matlab">
function J = ls1_J(x, Prob)

% Computes the Jacobian to least squares problem Gisela. J(i,j) is dr_i/d_x_j
% Parameter K is input in the structure
Prob a = Prob.user.K * x(1)/(x(3)*(x(1)-x(2)));
b = x(1)-x(2);
t = Prob.LS.t;

% Pick up the globally saved exponential computations
global US_A
e1 = US_A.e1; e2 = US_A.e2;

% Compute the three columns in the Jacobian, one for each of variable
J = a * [ t.*e1+(e2-e1)*(1-1/b), -t.*e2+(e2-e1)/b, (e1-e2)/x(3) ];

The following statements solve the ''Gisela ''problem.
% ---------------------------------------------------------------------
function ls1Demo - Nonlinear parameter estimation with 3 unknowns
% ---------------------------------------------------------------------

Name='Gisela';

% Time values
t = [0.25; 0.5; 0.75; 1; 1.5; 2; 3; 4; 6; 8; 12; 24; 32; 48; 54; 72; 80;...
96; 121; 144; 168; 192; 216; 246; 276; 324; 348; 386];

% Observations
y = [30.5; 44; 43; 41.5; 38.6; 38.6; 39; 41; 37; 37; 24; 32; 29; 23; 21;...
19; 17; 14; 9.5; 8.5; 7; 6; 6; 4.5; 3.6; 3; 2.2; 1.6];

x_0 = [6.8729,0.0108,0.1248]'; % Initial values for unknown x

% Generate the problem structure using the TOMLAB format (short call)
% Prob = clsAssign(r, J, JacPattern, x_L, x_U, Name, x_0, ...
% y, t, weightType, weightY, SepAlg, fLowBnd, ...
% A, b_L, b_U, c, dc, ConsPattern, c_L, c_U, ...
% x_min, x_max, f_opt, x_opt);

Prob = clsAssign('ls1_r', 'ls1_J', [], [], [], Name, x_0, y, t);

% Weighting parameter K in model is sent to r and J computation using Prob
Prob.user.K = 5;

Result = tomRun('clsSolve', Prob, 2);
</source>

The second example ''ls2Demo ''in file ''lsDemo ''solves the same problem as ''ls1Demo'', but using numerical differences to compute the Jacobian matrix in each iteration. To make TOMLAB avoid using the Jacobian routine, the variable ''Prob.NumDiff ''has to be set nonzero. Also in this example the flag ''Prob.optParam.IterPrint ''is set to enable one line of printing for each iteration. The changed statements are

<source lang="matlab">
...
Prob.NumDiff = 1; % Use standard numerical differences
Prob.optParam.IterPrint = 1; % Print one line each iteration

Result = tomRun('clsSolve',Prob,2);
</source>

The third example ''ls3Demo ''in file ''lsDemo ''solves the same problem as ''ls1Demo'', but six times for different values of the parameter ''K ''in the range [3''.''8'', ''5''.''0]. It illustrates that it is not necessary to remake the problem structure ''Prob ''for each optimization, but instead just change the parameters needed. The ''Result ''structure is saved as an vector of structure arrays, to enable post analysis of the results. The changed statements are

<source lang="matlab">
for i=1:6
Prob.user.K = 3.8 + 0.2*i;
Result(i) = tomRun('clsSolve',Prob,2);
end

fprintf('\nWEIGHT PARAMETER K is %9.3f\n\n\n',Prob.user.K);
</source>

[[#Table: Constrained nonlinear least squares (cls) test problems.]] describes the low level routines and the initialization routines needed for the predefined constrained nonlinear least squares ('''cls''') test problems. Similar routines are needed for the nonlinear least squares ('''ls''') test problems (here no constraint routines are needed).

====Table: Constrained nonlinear least squares (cls) test problems.====

{| class="wikitable" style="background-color:#ffffff;"
!Function
!Description
|-
|''cls_prob''||Initialization of '''cls '''test problems.
|-
|''cls_r''||Compute the residual vector <math>r_i(x), i = 1,...,m.~ x \in \mathbb{R}^n</math> ''for '''cls ''' test problems.
|-
|''cls_J''||Compute the Jacobian matrix <math>J_{ij}(x)=\partial r_i / d x_j,
i=1,...,m, j=1,...,n</math> ''for '''cls ''' test problems.
|-
|''cls_c''||Compute the vector of constraint functions ''c''(''x'') for '''cls '''test problems.
|-
|''cls_dc''||Compute the matrix of constraint normals <math>\partial
c(x)/dx</math> ''for '''cls '''test problems.
|-
|''cls_d2c''||Compute the second part of the second derivative of the Lagrangian function for '''cls '''test problems.
|-
|''ls_f''||General routine to compute the objective function value <math>f(x) =
{1\over2} r(x)^T r(x)</math> for nonlinear least squares type of problems.
|-
|''ls_g''||General routine to compute the gradient <math>g(x) = J(x)^T r(x)</math> for nonlinear least squares type of problems.
|-
|''ls_H''||General routine to compute the Hessian approximation <math>H(x) = J(x)^T * J(x)</math> for nonlinear least squares type of problems.
|}

==Fitting Sums of Exponentials to Empirical Data==

In TOMLAB the problem of fitting sums of positively weighted exponential functions to empirical data may be formulated either as a nonlinear least squares problem or a separable nonlinear least squares problem. Several empirical data series are predefined and artificial data series may also be generated. There are five different types of exponential models with special treatment in TOMLAB, shown in [[#Table: Exponential models treated in TOMLAB.]]. In research in cooperation with Todd Walton, Vicksburg, USA, TOMLAB has been used to estimate parameters using maximum likelihood in simulated Weibull distributions, and Gumbel and Gamma distributions with real data. TOMLAB has also been useful for parameter estimation in stochastic hydrology using real-life data.

====Table: Exponential models treated in TOMLAB.====

{| class="wikitable" cellpadding="5" style="background-color:#ffffff;"
|<math>f(t) = \sum\limits_i^p \alpha_i e^{-\beta_i t}</math>, || <math>\alpha_i \geq 0</math>, || <math>0\leq\beta_1<\beta_2< ... <\beta_p</math>.
|-
|<math>f(t) = \sum\limits_i^p \alpha_i e^{-\beta_i t}</math>, || <math>\alpha_i \geq 0</math>, || <math>0\leq\beta_1<\beta_2< ... <\beta_p</math>.
|-
|<math>f(t) = \sum\limits_i^p \alpha_i(1-e^{-\beta_i t})</math>, || <math>\alpha_i \geq 0</math>, || <math>0\leq\beta_1<\beta_2< ... <\beta_p</math>.
|-
|<math>f(t) = \sum\limits_i^p t \alpha_i e^{-\beta_i t}</math>, || <math>\alpha_i \geq 0</math>, || <math>0\leq\beta_1<\beta_2< ... <\beta_p</math>.
|-
|<math>f(t) = \sum\limits_i^p (t \alpha_i-\gamma_i) e^{-\beta_i t}</math>, || <math>\alpha_i,\gamma_i \geq 0</math>, || <math>0\leq\beta_1<\beta_2< ... >\beta_p</math>.
|-
|<math>f(t) = \sum\limits_i^p t \alpha_i e^{-\beta_i (t - \gamma_i)}</math>, || <math>\alpha_i \geq 0</math>, || <math>0\leq\beta_1<\beta_2< ... <\beta_p</math>.
|}

Algorithms to find starting values for different number of exponential terms are implemented. Test results show that these initial value algorithms are very close to the true solution for equidistant problems and fairly good for non-equidistant problems. Good initial values are extremely important when solving real life exponential fitting problems, because they are so ill-conditioned. [[#Table: Exponential fitting test problems.]] shows the relevant routines.

====Table: Exponential fitting test problems.====

{| class="wikitable" style="background-color:#ffffff;"
!Function
!Description
|-
|''expAssign''||Assign exponential fitting problem.
|-
|''exp_ArtP''||Generate artificial exponential sum problems.
|-
|''expInit''||Find starting values for the exponential parameters <math>\lambda</math>.
|-
|''expSolve''||Solve exponential fitting problems.
|-
|''exp_prob''||Defines a exponential fitting type of problem, with data series (''t, y''). The file includes data from several different empirical test series.
|-
|''Helax_prob''||Defines 335 medical research problems supplied by Helax AB, Uppsala, Sweden, where an exponential model is fitted to data. The actual data series (''t, y'') are stored on one file each, i.e. 335 data files, 8MB large, and are not distributed. A sample of five similar files are part of ''exp prob''.
|-
|''exp_r''||Compute the residual vector <math>r_i(x), i = 1,...,m.~ x \in \mathbb{R}^n</math>
|-
|''exp_J''||Compute the Jacobian matrix <math>\partial r_i / d x_j, i=1,...,m, j=1,...,n</math>
|-
|''exp_d2r''||Compute the 2nd part of the second derivative for the nonlinear least squares exponential fitting problem.
|-
|''exp_c''||Compute the constraints <math>\lambda_1 < \lambda_2 < ...</math> on the exponential parameters <math>\lambda_i, i=1,...,p</math>.
|-
|''exp_dc''||Compute matrix of constraint normals for constrained exponential fitting problem.
|-
|''exp_d2c''||Compute second part of second derivative matrix of the Lagrangian function for constrained exponential fitting problem. This is a zero matrix, because the constraints are linear.
|-
|''exp_q''||Find starting values for exponential parameters <math>\lambda_i, i=1,...,p</math>.
|-
|''exp_p''||Find optimal number of exponential terms, ''p''.
|}

==Large Scale LS problems with Tlsqr==

The ''Tlsqr ''MEX solver provides special parameters for advanced memory handling, enabling the user to solve extremely large linear least squares problems.

We'll take the problem of solving ''Ax ''= ''b ''in the least squares sense as a prototype problem for this section. Here, ''A ? ''R''m×n ''is a dense or sparse matrix and ''b ? ''R''m ''.

'''Controlling memory allocation in '''''Tlsqr''

The normal mode of operation of ''Tlsqr ''is that memory for the ''A ''matrix is allocated and deallocated each time the solver is called. In a real-life situation with a very large ''A ''and where the solver is called repeatedly, this may become inefficient and even cause problems getting memory because of memory fragmenting.

The ''Tlsqr ''solver provides a parameter ''Alloc'', given as the second element of the first input parameter to control the memory handling. The possible values of ''Alloc ''and their meanings are given in [[#Table: Alloc values for Tlsqr]].

====Table: ''Alloc ''values for ''Tlsqr''====

{| class="wikitable"
!Alloc (m(2))
!Meaning
|-
|0||Normal operation: allocate - solve - deallocate
|-
|1||Only allocate, no results returned
|-
|2||Allocate and solve, no deallocate
|-
|3||Only solve, no allocate/deallocate
|-
|4||Solve and deallocate
|-
|5||Deallocate only, no results returned
|}

An example of the calling sequence is given below.

<pre>
>> m = 60000; n = 1000; d = 0.01; % Size and density of A
>> A = sprand(m,n,d); % Sparse random matrix
>> b = ones(m,1); % Right hand side
>> whos A

Name Size Bytes Class
A 60000x500 3584784 sparse array

Grand total is 298565 elements using 3584784 bytes

% =======================================================================
% Simple standard call to Tlsqr, Alloc is set to default 0 if m is scalar

>> x=Tlsqr(m,n,A,[],[],b);

% =======================================================================
% To solve repeatedly with e.g. the same A but different b,
% the user may do:

% Indicate to Tlsqr to allocate and solve the problem

>> m(2) = 2
m =
60000 2

>> x = Tlsqr(m,n,A,[],[],b); % First solution

% Indicate to Tlsqr that memory is already allocated,
% and that no deallocation should occur on exit

>> m(2) = 3
m =
60000 3

% Loop 100 times, calling Tlsqr each time - without re-allocation of memory

>> for k=1:100
>> b = (...); % E.g. alter the right hand side each time
>> x = Tlsqr(m,n,A,[],[],b); % Call Tlsqr, now with m(2)=3
>> end

% Final call, with m(2) = 4: Solve and deallocate

>> m(2) = 4
m =
60000 4

>> x=Tlsqr(m,n,A,[],[],b);

% Alternatively, to just deallocate, the user could do
>> m(2) = 5;
>> Tlsqr(m,n,A,[],[],b); % Nothing is returned
</pre>

'''Further Memory Control: The maxneA Parameter'''

If the number of non-zero elements in a sparse ''A ''matrix increases in the middle of a ''Tlsqr''-calling loop, the initially allocated space will not be sufficient. One solution is that the user checks this prior to calling ''Tlsqr ''and reallocating if necessary. The other solution is to set ''m''(3) to an upper limit (''maxneA'') of the number of nonzero elements in ''A ''in the first allocation call. For example:

<pre>
>> m = [ 60000 1 1E6 ]

m =
60000 1 1000000
</pre>

will initiate a ''Tlsqr ''session, allocating sufficient memory to allow ''A'' matrices with up to 1.000.000 nonzeros. If the allocated memory is still insufficient, ''Tlsqr'' will try to reallocate enough space for the operation to continue.

'''Using Global Variables with Tlsqr and Tlsqrglob.m'''

For cases where it is not possible to send the ''A'' matrix to ''Tlsqr'' because it is simply too large, the user may choose to use the ''tomlab/mex/Tlsqrglob.m ''routine.

This function, which more often than not needs to be customized to the application in mind, should provide the following functionality:

<source lang="matlab">
function y = Tlsqrglob( mode, m, n, x, Aname, rw )

global A

if mode==1
y = A*x;
else
y = A'*x;
end
</source>

The purpose is to provide the possibility to define a global variable ''A ''and perform the multiplication without transferring this potentially very large matrix to the MEX function ''Tlsqr''.

If several matrices are involved, for example if ''A ''= [''A''1 ; ''A''2 ], this approach can be used to eliminate the need to explicitly repeatedly form the composite matrix ''A ''during a run. ''Tlsqrglob.m ''should then be (copied and) modified as:

<source lang="matlab">
function y = Tlsqrglob( mode, m, n, x, Aname, rw )

global A1 A2

if mode==1
y = A1*x;
y = [y ; A2*x];
else
M = size(A1,1);
y = A1' * x(1:M) + ...
A2' * x(M+1:end);
end
</source>

To use the global approach, ''Tlsqr ''must be called with the name of the global multiplication routine, for example:

<source lang="matlab">
[ x, ... ] = Tlsqr(m,n,'Tlsqrglob',...);
</source>

TOMLAB Solving Least Squares and Parameter Estimation Problems

2014-08-05T14:18:41Z

Bjorn: /* Table: Exponential models treated in TOMLAB. */

{{Part Of Manual|title=the TOMLAB Manual|link=[[TOMLAB|TOMLAB Manual]]}}
[[Category:Manuals]]
This section describes how to define and solve different types of linear and nonlinear least squares and parameter estimation problems. Several examples are given on how to proceed, depending on if a quick solution is wanted, or more advanced tests are needed. TOMLAB is also compatible with MathWorks Optimization TB. See [[TOMLAB Appendix E]] for more information and test examples.

All demonstration examples that are using the TOMLAB format are collected in the directory ''examples''. The examples relevant to this section are ''lsDemo ''and ''llsDemo''. The full path to these files are always given in the text.

[[TOMLAB_Solving_Least_Squares_and_Parameter_Estimation_Problems#Large_Scale_LS_problems_with_Tlsqr|Large Scale LS problems with Tlsqr]] contains information on solving extreme large-scale '''ls '''problems with ''Tlsqr''.

==Linear Least Squares Problems==

This section shows examples how to define and solve linear least squares problems using the TOMLAB format. As a first illustration, the example ''lls1Demo ''in file ''llsDemo ''shows how to fit a linear least squares model with linear constraints to given data. This test problem is taken from the User's Guide of ''LSSOL''.

<source lang="matlab">
Name='LSSOL test example';

% In TOMLAB it is best to use Inf and -Inf, not big numbers.
n = 9; % Number of unknown parameters
x_L = [-2 -2 -Inf, -2*ones(1,6)]';
x_U = 2*ones(n,1);

A = [ ones(1,8) 4; 1:4,-2,1 1 1 1; 1 -1 1 -1, ones(1,5)];
b_L = [2 -Inf -4]';
b_U = [Inf -2 -2]';

y = ones(10,1);
C = [ ones(1,n); 1 2 1 1 1 1 2 0 0; 1 1 3 1 1 1 -1 -1 -3; ...
1 1 1 4 1 1 1 1 1;1 1 1 3 1 1 1 1 1; 1 1 2 1 1 0 0 0 -1; ...
1 1 1 1 0 1 1 1 1;1 1 1 0 1 1 1 1 1; 1 1 0 1 1 1 2 2 3; ...
1 0 1 1 1 1 0 2 2];

x_0 = 1./[1:n]';

t = []; % No time set for y(t) (used for plotting)
weightY = []; % No weighting
weightType = []; % No weighting type set

x_min = []; % No lower bound for plotting
x_max = []; % No upper bound for plotting

Prob = llsAssign(C, y, x_L, x_U, Name, x_0, t, weightType, weightY, ...
A, b_L, b_U, x_min, x_max); Result = tomRun('lsei',Prob,2);
</source>

It is trivial to change the solver in the call to ''tomRun'' to a nonlinear least squares solver, e.g. ''clsSolve'', or a general nonlinear programming solver.

==Linear Least Squares Problems using the SOL Solver LSSOL==

The example ''lls2Demo'' in file ''llsDemo'' shows how to fit a linear least squares model with linear constraints to given data using a direct call to the SOL solver ''LSSOL''. The test problem is taken from the User's Guide of ''LSSOL''.

<source lang="matlab">
% Note that when calling the LSSOL MEX interface directly, avoid using
% Inf and -Inf. Instead use big numbers that indicate Inf.
% The standard for the MEX interfaces is 1E20 and -1E20, respectively.

n = 9; % There are nine unknown parameters, and 10 equations
x_L = [-2 -2 -1E20, -2*ones(1,6)]';
x_U = 2*ones(n,1);

A = [ ones(1,8) 4; 1:4,-2,1 1 1 1; 1 -1 1 -1, ones(1,5)];
b_L = [2 -1E20 -4]';
b_U = [1E20 -2 -2]';
% Must put lower and upper bounds on variables and constraints together
bl = [x_L;b_L];
bu = [x_U;b_U];

H = [ ones(1,n); 1 2 1 1 1 1 2 0 0; 1 1 3 1 1 1 -1 -1 -3; ...
1 1 1 4 1 1 1 1 1;1 1 1 3 1 1 1 1 1;1 1 2 1 1 0 0 0 -1; ...
1 1 1 1 0 1 1 1 1;1 1 1 0 1 1 1 1 1;1 1 0 1 1 1 2 2 3; ...
1 0 1 1 1 1 0 2 2];
y = ones(10,1);

x_0 = 1./[1:n]';

% Set empty indicating default values for most variables
c = []; % No linear coefficients, they are for LP/QP
Warm = []; % No warm start
iState = []; % No warm start
Upper = []; % C is not factorized
kx = []; % No warm start
SpecsFile = []; % No parameter settings in a SPECS file
PriLev = []; % PriLev is not really used in LSSOL
ProbName = []; % ProbName is not really used in LSSOL
optPar(1) = 50; % Set print level at maximum
PrintFile = 'lssol.txt'; % Print result on the file with name lssol.txt

z0 = (y-H*x_0);
f0 = 0.5*z0'*z0;
fprintf('Initial function value %f\n',f0);

[x, Inform, iState, cLamda, Iter, fObj, r, kx] = ...
lssol( A, bl, bu, c, x_0, optPar, H, y, Warm, ...
iState, Upper, kx, SpecsFile, PrintFile, PriLev, ProbName );

% We could equally well call with the following shorter call:
% [x, Inform, iState, cLamda, Iter, fObj, r, kx] = ...
% lssol( A, bl, bu, c, x, optPar, H, y);

z = (y-H*x);
f = 0.5*z'*z;
fprintf('Optimal function value %f\n',f);
</source>

==Nonlinear Least Squares Problems==

This section shows examples how to define and solve nonlinear least squares problems using the TOMLAB format. As a first illustration, the example ''ls1Demo ''in file ''lsDemo ''shows how to fit a nonlinear model of exponential type with three unknown parameters to experimental data. This problem, ''Gisela'', is also defined as problem three in ''ls_prob''. A weighting parameter ''K ''is sent to the residual and Jacobian routine using the ''Prob ''structure. The solver ''clsSolve ''is called directly. Note that the user only defines the routine to compute the residual vector and the Jacobian matrix of derivatives. TOMLAB has special routines ''ls f'', ''ls g ''and ''ls H ''that computes the nonlinear least squares objective function value, given the residuals, as well as the gradient and the approximative Hessian, see [[#Table: Constrained nonlinear least squares (cls) test problems.]]. The residual routine for this problem is defined in file ''ls1_r ''in the directory ''example'' with the statements

<source lang="matlab">
function r = ls_r(x, Prob)

% Compute residuals to nonlinear least squares problem Gisela

% US_A is the standard TOMLAB global parameter to be used in the
% communication between the residual and the Jacobian routine

global US_A

% The extra weight parameter K is sent as part of the structure
K = Prob.user.K;
t = Prob.LS.t(:); % Pick up the time points

% Exponential expressions to be later used when computing the Jacobian
US_A.e1 = exp(-x(1)*t); US_A.e2 = exp(-x(2)*t);

r = K*x(1)*(US_A.e2 - US_A.e1) / (x(3)*(x(1)-x(2))) - Prob.LS.y;
</source>

Note that this example also shows how to communicate information between the residual and the Jacobian routine. It is best to use any of the predefined global variables ''US_A'' and ''US_B'', because then there will be no conflicts with respect to global variables if recursive calls are used. In this example the global variable ''US_A'' is used as structure array storing two vectors with exponential expressions. The Jacobian routine for this problem is defined in the file ''ls1_J '' in the directory ''example''. The global variable ''US_A'' is accessed to obtain the exponential expressions, see the statements below.

<source lang="matlab">
function J = ls1_J(x, Prob)

% Computes the Jacobian to least squares problem Gisela. J(i,j) is dr_i/d_x_j
% Parameter K is input in the structure
Prob a = Prob.user.K * x(1)/(x(3)*(x(1)-x(2)));
b = x(1)-x(2);
t = Prob.LS.t;

% Pick up the globally saved exponential computations
global US_A
e1 = US_A.e1; e2 = US_A.e2;

% Compute the three columns in the Jacobian, one for each of variable
J = a * [ t.*e1+(e2-e1)*(1-1/b), -t.*e2+(e2-e1)/b, (e1-e2)/x(3) ];

The following statements solve the ''Gisela ''problem.
% ---------------------------------------------------------------------
function ls1Demo - Nonlinear parameter estimation with 3 unknowns
% ---------------------------------------------------------------------

Name='Gisela';

% Time values
t = [0.25; 0.5; 0.75; 1; 1.5; 2; 3; 4; 6; 8; 12; 24; 32; 48; 54; 72; 80;...
96; 121; 144; 168; 192; 216; 246; 276; 324; 348; 386];

% Observations
y = [30.5; 44; 43; 41.5; 38.6; 38.6; 39; 41; 37; 37; 24; 32; 29; 23; 21;...
19; 17; 14; 9.5; 8.5; 7; 6; 6; 4.5; 3.6; 3; 2.2; 1.6];

x_0 = [6.8729,0.0108,0.1248]'; % Initial values for unknown x

% Generate the problem structure using the TOMLAB format (short call)
% Prob = clsAssign(r, J, JacPattern, x_L, x_U, Name, x_0, ...
% y, t, weightType, weightY, SepAlg, fLowBnd, ...
% A, b_L, b_U, c, dc, ConsPattern, c_L, c_U, ...
% x_min, x_max, f_opt, x_opt);

Prob = clsAssign('ls1_r', 'ls1_J', [], [], [], Name, x_0, y, t);

% Weighting parameter K in model is sent to r and J computation using Prob
Prob.user.K = 5;

Result = tomRun('clsSolve', Prob, 2);
</source>

The second example ''ls2Demo ''in file ''lsDemo ''solves the same problem as ''ls1Demo'', but using numerical differences to compute the Jacobian matrix in each iteration. To make TOMLAB avoid using the Jacobian routine, the variable ''Prob.NumDiff ''has to be set nonzero. Also in this example the flag ''Prob.optParam.IterPrint ''is set to enable one line of printing for each iteration. The changed statements are

<source lang="matlab">
...
Prob.NumDiff = 1; % Use standard numerical differences
Prob.optParam.IterPrint = 1; % Print one line each iteration

Result = tomRun('clsSolve',Prob,2);
</source>

The third example ''ls3Demo ''in file ''lsDemo ''solves the same problem as ''ls1Demo'', but six times for different values of the parameter ''K ''in the range [3''.''8'', ''5''.''0]. It illustrates that it is not necessary to remake the problem structure ''Prob ''for each optimization, but instead just change the parameters needed. The ''Result ''structure is saved as an vector of structure arrays, to enable post analysis of the results. The changed statements are

<source lang="matlab">
for i=1:6
Prob.user.K = 3.8 + 0.2*i;
Result(i) = tomRun('clsSolve',Prob,2);
end

fprintf('\nWEIGHT PARAMETER K is %9.3f\n\n\n',Prob.user.K);
</source>

[[#Table: Constrained nonlinear least squares (cls) test problems.]] describes the low level routines and the initialization routines needed for the predefined constrained nonlinear least squares ('''cls''') test problems. Similar routines are needed for the nonlinear least squares ('''ls''') test problems (here no constraint routines are needed).

====Table: Constrained nonlinear least squares (cls) test problems.====

{| class="wikitable" style="background-color:#ffffff;"
!Function
!Description
|-
|''cls_prob''||Initialization of '''cls '''test problems.
|-
|''cls_r''||Compute the residual vector <math>r_i(x), i = 1,...,m.~ x \in \mathbb{R}^n</math> ''for '''cls ''' test problems.
|-
|''cls_J''||Compute the Jacobian matrix <math>J_{ij}(x)=\partial r_i / d x_j,
i=1,...,m, j=1,...,n</math> ''for '''cls ''' test problems.
|-
|''cls_c''||Compute the vector of constraint functions ''c''(''x'') for '''cls '''test problems.
|-
|''cls_dc''||Compute the matrix of constraint normals <math>\partial
c(x)/dx</math> ''for '''cls '''test problems.
|-
|''cls_d2c''||Compute the second part of the second derivative of the Lagrangian function for '''cls '''test problems.
|-
|''ls_f''||General routine to compute the objective function value <math>f(x) =
{1\over2} r(x)^T r(x)</math> for nonlinear least squares type of problems.
|-
|''ls_g''||General routine to compute the gradient <math>g(x) = J(x)^T r(x)</math> for nonlinear least squares type of problems.
|-
|''ls_H''||General routine to compute the Hessian approximation <math>H(x) = J(x)^T * J(x)</math> for nonlinear least squares type of problems.
|}

==Fitting Sums of Exponentials to Empirical Data==

In TOMLAB the problem of fitting sums of positively weighted exponential functions to empirical data may be formulated either as a nonlinear least squares problem or a separable nonlinear least squares problem. Several empirical data series are predefined and artificial data series may also be generated. There are five different types of exponential models with special treatment in TOMLAB, shown in [[#Table: Exponential models treated in TOMLAB.]]. In research in cooperation with Todd Walton, Vicksburg, USA, TOMLAB has been used to estimate parameters using maximum likelihood in simulated Weibull distributions, and Gumbel and Gamma distributions with real data. TOMLAB has also been useful for parameter estimation in stochastic hydrology using real-life data.

====Table: Exponential models treated in TOMLAB.====

{| class="wikitable" cellpadding="5" style="background-color:#ffffff;"
|<math>f(t) = \sum\limits_i^p \alpha_i e^{-\beta_i t}</math>, || <math>\alpha_i \geq 0</math>, || <math>0\leq\beta_1<\beta_2< ... <\beta_p</math>.
|-
|<math>f(t) = \sum\limits_i^p \alpha_i e^{-\beta_i t}</math>, || <math>\alpha_i \geq 0</math>, || <math>0\leq\beta_1<\beta_2< ... <\beta_p</math>.
|-
|<math>f(t) = \sum\limits_i^p \alpha_i(1-e^{-\beta_i t})</math>, || <math>\alpha_i \geq 0</math>, || <math>0\leq\beta_1<\beta_2< ... <\beta_p</math>.
|-
|<math>f(t) = \sum\limits_i^p t \alpha_i e^{-\beta_i t}</math>, || <math>\alpha_i \geq 0</math>, || <math>0\leq\beta_1<\beta_2< ... <\beta_p</math>.
|-
|<math>f(t) = \sum\limits_i^p (t \alpha_i-\gamma_i) e^{-\beta_i t}</math>, || <math>\alpha_i,\gamma_i \geq 0</math>, || <math>0\leq\beta_1<\beta_2< ... >\beta_p</math>.
|-
|<math>f(t) = \sum\limits_i^p t \alpha_i e^{-\beta_i (t - \gamma_i)}</math>, || <math>\alpha_i \geq 0</math>, || <math>0\leq\beta_1<\beta_2< ... <\beta_p</math>.
|}

Algorithms to find starting values for different number of exponential terms are implemented. Test results show that these initial value algorithms are very close to the true solution for equidistant problems and fairly good for non-equidistant problems. Good initial values are extremely important when solving real life exponential fitting problems, because they are so ill-conditioned. [[#Table: Exponential fitting test problems.]] shows the relevant routines.

====Table: Exponential fitting test problems.====

{| class="wikitable"
!Function
!Description
|-
|''expAssign''||Assign exponential fitting problem.
|-
|''exp_ArtP''||Generate artificial exponential sum problems.
|-
|''expInit''||Find starting values for the exponential parameters <math>\lambda</math>.
|-
|''expSolve''||Solve exponential fitting problems.
|-
|''exp_prob''||Defines a exponential fitting type of problem, with data series (''t, y''). The file includes data from several different empirical test series.
|-
|''Helax_prob''||Defines 335 medical research problems supplied by Helax AB, Uppsala, Sweden, where an exponential model is fitted to data. The actual data series (''t, y'') are stored on one file each, i.e. 335 data files, 8MB large, and are not distributed. A sample of five similar files are part of ''exp prob''.
|-
|''exp_r''||Compute the residual vector <math>r_i(x), i = 1,...,m.~ x \in \mathbb{R}^n</math>
|-
|''exp_J''||Compute the Jacobian matrix <math>\partial r_i / d x_j, i=1,...,m, j=1,...,n</math>
|-
|''exp_d2r''||Compute the 2nd part of the second derivative for the nonlinear least squares exponential fitting problem.
|-
|''exp_c''||Compute the constraints <math>\lambda_1 < \lambda_2 < ...</math> on the exponential parameters <math>\lambda_i, i=1,...,p</math>.
|-
|''exp_dc''||Compute matrix of constraint normals for constrained exponential fitting problem.
|-
|''exp_d2c''||Compute second part of second derivative matrix of the Lagrangian function for constrained exponential fitting problem. This is a zero matrix, because the constraints are linear.
|-
|''exp_q''||Find starting values for exponential parameters <math>\lambda_i, i=1,...,p</math>.
|-
|''exp_p''||Find optimal number of exponential terms, ''p''.
|}

==Large Scale LS problems with Tlsqr==

The ''Tlsqr ''MEX solver provides special parameters for advanced memory handling, enabling the user to solve extremely large linear least squares problems.

We'll take the problem of solving ''Ax ''= ''b ''in the least squares sense as a prototype problem for this section. Here, ''A ? ''R''m×n ''is a dense or sparse matrix and ''b ? ''R''m ''.

'''Controlling memory allocation in '''''Tlsqr''

The normal mode of operation of ''Tlsqr ''is that memory for the ''A ''matrix is allocated and deallocated each time the solver is called. In a real-life situation with a very large ''A ''and where the solver is called repeatedly, this may become inefficient and even cause problems getting memory because of memory fragmenting.

The ''Tlsqr ''solver provides a parameter ''Alloc'', given as the second element of the first input parameter to control the memory handling. The possible values of ''Alloc ''and their meanings are given in [[#Table: Alloc values for Tlsqr]].

====Table: ''Alloc ''values for ''Tlsqr''====

{| class="wikitable"
!Alloc (m(2))
!Meaning
|-
|0||Normal operation: allocate - solve - deallocate
|-
|1||Only allocate, no results returned
|-
|2||Allocate and solve, no deallocate
|-
|3||Only solve, no allocate/deallocate
|-
|4||Solve and deallocate
|-
|5||Deallocate only, no results returned
|}

An example of the calling sequence is given below.

<pre>
>> m = 60000; n = 1000; d = 0.01; % Size and density of A
>> A = sprand(m,n,d); % Sparse random matrix
>> b = ones(m,1); % Right hand side
>> whos A

Name Size Bytes Class
A 60000x500 3584784 sparse array

Grand total is 298565 elements using 3584784 bytes

% =======================================================================
% Simple standard call to Tlsqr, Alloc is set to default 0 if m is scalar

>> x=Tlsqr(m,n,A,[],[],b);

% =======================================================================
% To solve repeatedly with e.g. the same A but different b,
% the user may do:

% Indicate to Tlsqr to allocate and solve the problem

>> m(2) = 2
m =
60000 2

>> x = Tlsqr(m,n,A,[],[],b); % First solution

% Indicate to Tlsqr that memory is already allocated,
% and that no deallocation should occur on exit

>> m(2) = 3
m =
60000 3

% Loop 100 times, calling Tlsqr each time - without re-allocation of memory

>> for k=1:100
>> b = (...); % E.g. alter the right hand side each time
>> x = Tlsqr(m,n,A,[],[],b); % Call Tlsqr, now with m(2)=3
>> end

% Final call, with m(2) = 4: Solve and deallocate

>> m(2) = 4
m =
60000 4

>> x=Tlsqr(m,n,A,[],[],b);

% Alternatively, to just deallocate, the user could do
>> m(2) = 5;
>> Tlsqr(m,n,A,[],[],b); % Nothing is returned
</pre>

'''Further Memory Control: The maxneA Parameter'''

If the number of non-zero elements in a sparse ''A ''matrix increases in the middle of a ''Tlsqr''-calling loop, the initially allocated space will not be sufficient. One solution is that the user checks this prior to calling ''Tlsqr ''and reallocating if necessary. The other solution is to set ''m''(3) to an upper limit (''maxneA'') of the number of nonzero elements in ''A ''in the first allocation call. For example:

<pre>
>> m = [ 60000 1 1E6 ]

m =
60000 1 1000000
</pre>

will initiate a ''Tlsqr ''session, allocating sufficient memory to allow ''A'' matrices with up to 1.000.000 nonzeros. If the allocated memory is still insufficient, ''Tlsqr'' will try to reallocate enough space for the operation to continue.

'''Using Global Variables with Tlsqr and Tlsqrglob.m'''

For cases where it is not possible to send the ''A'' matrix to ''Tlsqr'' because it is simply too large, the user may choose to use the ''tomlab/mex/Tlsqrglob.m ''routine.

This function, which more often than not needs to be customized to the application in mind, should provide the following functionality:

<source lang="matlab">
function y = Tlsqrglob( mode, m, n, x, Aname, rw )

global A

if mode==1
y = A*x;
else
y = A'*x;
end
</source>

The purpose is to provide the possibility to define a global variable ''A ''and perform the multiplication without transferring this potentially very large matrix to the MEX function ''Tlsqr''.

If several matrices are involved, for example if ''A ''= [''A''1 ; ''A''2 ], this approach can be used to eliminate the need to explicitly repeatedly form the composite matrix ''A ''during a run. ''Tlsqrglob.m ''should then be (copied and) modified as:

<source lang="matlab">
function y = Tlsqrglob( mode, m, n, x, Aname, rw )

global A1 A2

if mode==1
y = A1*x;
y = [y ; A2*x];
else
M = size(A1,1);
y = A1' * x(1:M) + ...
A2' * x(M+1:end);
end
</source>

To use the global approach, ''Tlsqr ''must be called with the name of the global multiplication routine, for example:

<source lang="matlab">
[ x, ... ] = Tlsqr(m,n,'Tlsqrglob',...);
</source>

TOMLAB Solving Least Squares and Parameter Estimation Problems

2014-08-05T14:18:18Z

Bjorn: /* Table: Constrained nonlinear least squares (cls) test problems. */

{{Part Of Manual|title=the TOMLAB Manual|link=[[TOMLAB|TOMLAB Manual]]}}
[[Category:Manuals]]
This section describes how to define and solve different types of linear and nonlinear least squares and parameter estimation problems. Several examples are given on how to proceed, depending on if a quick solution is wanted, or more advanced tests are needed. TOMLAB is also compatible with MathWorks Optimization TB. See [[TOMLAB Appendix E]] for more information and test examples.

All demonstration examples that are using the TOMLAB format are collected in the directory ''examples''. The examples relevant to this section are ''lsDemo ''and ''llsDemo''. The full path to these files are always given in the text.

[[TOMLAB_Solving_Least_Squares_and_Parameter_Estimation_Problems#Large_Scale_LS_problems_with_Tlsqr|Large Scale LS problems with Tlsqr]] contains information on solving extreme large-scale '''ls '''problems with ''Tlsqr''.

==Linear Least Squares Problems==

This section shows examples how to define and solve linear least squares problems using the TOMLAB format. As a first illustration, the example ''lls1Demo ''in file ''llsDemo ''shows how to fit a linear least squares model with linear constraints to given data. This test problem is taken from the User's Guide of ''LSSOL''.

<source lang="matlab">
Name='LSSOL test example';

% In TOMLAB it is best to use Inf and -Inf, not big numbers.
n = 9; % Number of unknown parameters
x_L = [-2 -2 -Inf, -2*ones(1,6)]';
x_U = 2*ones(n,1);

A = [ ones(1,8) 4; 1:4,-2,1 1 1 1; 1 -1 1 -1, ones(1,5)];
b_L = [2 -Inf -4]';
b_U = [Inf -2 -2]';

y = ones(10,1);
C = [ ones(1,n); 1 2 1 1 1 1 2 0 0; 1 1 3 1 1 1 -1 -1 -3; ...
1 1 1 4 1 1 1 1 1;1 1 1 3 1 1 1 1 1; 1 1 2 1 1 0 0 0 -1; ...
1 1 1 1 0 1 1 1 1;1 1 1 0 1 1 1 1 1; 1 1 0 1 1 1 2 2 3; ...
1 0 1 1 1 1 0 2 2];

x_0 = 1./[1:n]';

t = []; % No time set for y(t) (used for plotting)
weightY = []; % No weighting
weightType = []; % No weighting type set

x_min = []; % No lower bound for plotting
x_max = []; % No upper bound for plotting

Prob = llsAssign(C, y, x_L, x_U, Name, x_0, t, weightType, weightY, ...
A, b_L, b_U, x_min, x_max); Result = tomRun('lsei',Prob,2);
</source>

It is trivial to change the solver in the call to ''tomRun'' to a nonlinear least squares solver, e.g. ''clsSolve'', or a general nonlinear programming solver.

==Linear Least Squares Problems using the SOL Solver LSSOL==

The example ''lls2Demo'' in file ''llsDemo'' shows how to fit a linear least squares model with linear constraints to given data using a direct call to the SOL solver ''LSSOL''. The test problem is taken from the User's Guide of ''LSSOL''.

<source lang="matlab">
% Note that when calling the LSSOL MEX interface directly, avoid using
% Inf and -Inf. Instead use big numbers that indicate Inf.
% The standard for the MEX interfaces is 1E20 and -1E20, respectively.

n = 9; % There are nine unknown parameters, and 10 equations
x_L = [-2 -2 -1E20, -2*ones(1,6)]';
x_U = 2*ones(n,1);

A = [ ones(1,8) 4; 1:4,-2,1 1 1 1; 1 -1 1 -1, ones(1,5)];
b_L = [2 -1E20 -4]';
b_U = [1E20 -2 -2]';
% Must put lower and upper bounds on variables and constraints together
bl = [x_L;b_L];
bu = [x_U;b_U];

H = [ ones(1,n); 1 2 1 1 1 1 2 0 0; 1 1 3 1 1 1 -1 -1 -3; ...
1 1 1 4 1 1 1 1 1;1 1 1 3 1 1 1 1 1;1 1 2 1 1 0 0 0 -1; ...
1 1 1 1 0 1 1 1 1;1 1 1 0 1 1 1 1 1;1 1 0 1 1 1 2 2 3; ...
1 0 1 1 1 1 0 2 2];
y = ones(10,1);

x_0 = 1./[1:n]';

% Set empty indicating default values for most variables
c = []; % No linear coefficients, they are for LP/QP
Warm = []; % No warm start
iState = []; % No warm start
Upper = []; % C is not factorized
kx = []; % No warm start
SpecsFile = []; % No parameter settings in a SPECS file
PriLev = []; % PriLev is not really used in LSSOL
ProbName = []; % ProbName is not really used in LSSOL
optPar(1) = 50; % Set print level at maximum
PrintFile = 'lssol.txt'; % Print result on the file with name lssol.txt

z0 = (y-H*x_0);
f0 = 0.5*z0'*z0;
fprintf('Initial function value %f\n',f0);

[x, Inform, iState, cLamda, Iter, fObj, r, kx] = ...
lssol( A, bl, bu, c, x_0, optPar, H, y, Warm, ...
iState, Upper, kx, SpecsFile, PrintFile, PriLev, ProbName );

% We could equally well call with the following shorter call:
% [x, Inform, iState, cLamda, Iter, fObj, r, kx] = ...
% lssol( A, bl, bu, c, x, optPar, H, y);

z = (y-H*x);
f = 0.5*z'*z;
fprintf('Optimal function value %f\n',f);
</source>

==Nonlinear Least Squares Problems==

This section shows examples how to define and solve nonlinear least squares problems using the TOMLAB format. As a first illustration, the example ''ls1Demo ''in file ''lsDemo ''shows how to fit a nonlinear model of exponential type with three unknown parameters to experimental data. This problem, ''Gisela'', is also defined as problem three in ''ls_prob''. A weighting parameter ''K ''is sent to the residual and Jacobian routine using the ''Prob ''structure. The solver ''clsSolve ''is called directly. Note that the user only defines the routine to compute the residual vector and the Jacobian matrix of derivatives. TOMLAB has special routines ''ls f'', ''ls g ''and ''ls H ''that computes the nonlinear least squares objective function value, given the residuals, as well as the gradient and the approximative Hessian, see [[#Table: Constrained nonlinear least squares (cls) test problems.]]. The residual routine for this problem is defined in file ''ls1_r ''in the directory ''example'' with the statements

<source lang="matlab">
function r = ls_r(x, Prob)

% Compute residuals to nonlinear least squares problem Gisela

% US_A is the standard TOMLAB global parameter to be used in the
% communication between the residual and the Jacobian routine

global US_A

% The extra weight parameter K is sent as part of the structure
K = Prob.user.K;
t = Prob.LS.t(:); % Pick up the time points

% Exponential expressions to be later used when computing the Jacobian
US_A.e1 = exp(-x(1)*t); US_A.e2 = exp(-x(2)*t);

r = K*x(1)*(US_A.e2 - US_A.e1) / (x(3)*(x(1)-x(2))) - Prob.LS.y;
</source>

Note that this example also shows how to communicate information between the residual and the Jacobian routine. It is best to use any of the predefined global variables ''US_A'' and ''US_B'', because then there will be no conflicts with respect to global variables if recursive calls are used. In this example the global variable ''US_A'' is used as structure array storing two vectors with exponential expressions. The Jacobian routine for this problem is defined in the file ''ls1_J '' in the directory ''example''. The global variable ''US_A'' is accessed to obtain the exponential expressions, see the statements below.

<source lang="matlab">
function J = ls1_J(x, Prob)

% Computes the Jacobian to least squares problem Gisela. J(i,j) is dr_i/d_x_j
% Parameter K is input in the structure
Prob a = Prob.user.K * x(1)/(x(3)*(x(1)-x(2)));
b = x(1)-x(2);
t = Prob.LS.t;

% Pick up the globally saved exponential computations
global US_A
e1 = US_A.e1; e2 = US_A.e2;

% Compute the three columns in the Jacobian, one for each of variable
J = a * [ t.*e1+(e2-e1)*(1-1/b), -t.*e2+(e2-e1)/b, (e1-e2)/x(3) ];

The following statements solve the ''Gisela ''problem.
% ---------------------------------------------------------------------
function ls1Demo - Nonlinear parameter estimation with 3 unknowns
% ---------------------------------------------------------------------

Name='Gisela';

% Time values
t = [0.25; 0.5; 0.75; 1; 1.5; 2; 3; 4; 6; 8; 12; 24; 32; 48; 54; 72; 80;...
96; 121; 144; 168; 192; 216; 246; 276; 324; 348; 386];

% Observations
y = [30.5; 44; 43; 41.5; 38.6; 38.6; 39; 41; 37; 37; 24; 32; 29; 23; 21;...
19; 17; 14; 9.5; 8.5; 7; 6; 6; 4.5; 3.6; 3; 2.2; 1.6];

x_0 = [6.8729,0.0108,0.1248]'; % Initial values for unknown x

% Generate the problem structure using the TOMLAB format (short call)
% Prob = clsAssign(r, J, JacPattern, x_L, x_U, Name, x_0, ...
% y, t, weightType, weightY, SepAlg, fLowBnd, ...
% A, b_L, b_U, c, dc, ConsPattern, c_L, c_U, ...
% x_min, x_max, f_opt, x_opt);

Prob = clsAssign('ls1_r', 'ls1_J', [], [], [], Name, x_0, y, t);

% Weighting parameter K in model is sent to r and J computation using Prob
Prob.user.K = 5;

Result = tomRun('clsSolve', Prob, 2);
</source>

The second example ''ls2Demo ''in file ''lsDemo ''solves the same problem as ''ls1Demo'', but using numerical differences to compute the Jacobian matrix in each iteration. To make TOMLAB avoid using the Jacobian routine, the variable ''Prob.NumDiff ''has to be set nonzero. Also in this example the flag ''Prob.optParam.IterPrint ''is set to enable one line of printing for each iteration. The changed statements are

<source lang="matlab">
...
Prob.NumDiff = 1; % Use standard numerical differences
Prob.optParam.IterPrint = 1; % Print one line each iteration

Result = tomRun('clsSolve',Prob,2);
</source>

The third example ''ls3Demo ''in file ''lsDemo ''solves the same problem as ''ls1Demo'', but six times for different values of the parameter ''K ''in the range [3''.''8'', ''5''.''0]. It illustrates that it is not necessary to remake the problem structure ''Prob ''for each optimization, but instead just change the parameters needed. The ''Result ''structure is saved as an vector of structure arrays, to enable post analysis of the results. The changed statements are

<source lang="matlab">
for i=1:6
Prob.user.K = 3.8 + 0.2*i;
Result(i) = tomRun('clsSolve',Prob,2);
end

fprintf('\nWEIGHT PARAMETER K is %9.3f\n\n\n',Prob.user.K);
</source>

[[#Table: Constrained nonlinear least squares (cls) test problems.]] describes the low level routines and the initialization routines needed for the predefined constrained nonlinear least squares ('''cls''') test problems. Similar routines are needed for the nonlinear least squares ('''ls''') test problems (here no constraint routines are needed).

====Table: Constrained nonlinear least squares (cls) test problems.====

{| class="wikitable" style="background-color:#ffffff;"
!Function
!Description
|-
|''cls_prob''||Initialization of '''cls '''test problems.
|-
|''cls_r''||Compute the residual vector <math>r_i(x), i = 1,...,m.~ x \in \mathbb{R}^n</math> ''for '''cls ''' test problems.
|-
|''cls_J''||Compute the Jacobian matrix <math>J_{ij}(x)=\partial r_i / d x_j,
i=1,...,m, j=1,...,n</math> ''for '''cls ''' test problems.
|-
|''cls_c''||Compute the vector of constraint functions ''c''(''x'') for '''cls '''test problems.
|-
|''cls_dc''||Compute the matrix of constraint normals <math>\partial
c(x)/dx</math> ''for '''cls '''test problems.
|-
|''cls_d2c''||Compute the second part of the second derivative of the Lagrangian function for '''cls '''test problems.
|-
|''ls_f''||General routine to compute the objective function value <math>f(x) =
{1\over2} r(x)^T r(x)</math> for nonlinear least squares type of problems.
|-
|''ls_g''||General routine to compute the gradient <math>g(x) = J(x)^T r(x)</math> for nonlinear least squares type of problems.
|-
|''ls_H''||General routine to compute the Hessian approximation <math>H(x) = J(x)^T * J(x)</math> for nonlinear least squares type of problems.
|}

==Fitting Sums of Exponentials to Empirical Data==

In TOMLAB the problem of fitting sums of positively weighted exponential functions to empirical data may be formulated either as a nonlinear least squares problem or a separable nonlinear least squares problem. Several empirical data series are predefined and artificial data series may also be generated. There are five different types of exponential models with special treatment in TOMLAB, shown in [[#Table: Exponential models treated in TOMLAB.]]. In research in cooperation with Todd Walton, Vicksburg, USA, TOMLAB has been used to estimate parameters using maximum likelihood in simulated Weibull distributions, and Gumbel and Gamma distributions with real data. TOMLAB has also been useful for parameter estimation in stochastic hydrology using real-life data.

====Table: Exponential models treated in TOMLAB.====

{| class="wikitable" cellpadding="5"
|<math>f(t) = \sum\limits_i^p \alpha_i e^{-\beta_i t}</math>, || <math>\alpha_i \geq 0</math>, || <math>0\leq\beta_1<\beta_2< ... <\beta_p</math>.
|-
|<math>f(t) = \sum\limits_i^p \alpha_i e^{-\beta_i t}</math>, || <math>\alpha_i \geq 0</math>, || <math>0\leq\beta_1<\beta_2< ... <\beta_p</math>.
|-
|<math>f(t) = \sum\limits_i^p \alpha_i(1-e^{-\beta_i t})</math>, || <math>\alpha_i \geq 0</math>, || <math>0\leq\beta_1<\beta_2< ... <\beta_p</math>.
|-
|<math>f(t) = \sum\limits_i^p t \alpha_i e^{-\beta_i t}</math>, || <math>\alpha_i \geq 0</math>, || <math>0\leq\beta_1<\beta_2< ... <\beta_p</math>.
|-
|<math>f(t) = \sum\limits_i^p (t \alpha_i-\gamma_i) e^{-\beta_i t}</math>, || <math>\alpha_i,\gamma_i \geq 0</math>, || <math>0\leq\beta_1<\beta_2< ... >\beta_p</math>.
|-
|<math>f(t) = \sum\limits_i^p t \alpha_i e^{-\beta_i (t - \gamma_i)}</math>, || <math>\alpha_i \geq 0</math>, || <math>0\leq\beta_1<\beta_2< ... <\beta_p</math>.
|}

Algorithms to find starting values for different number of exponential terms are implemented. Test results show that these initial value algorithms are very close to the true solution for equidistant problems and fairly good for non-equidistant problems. Good initial values are extremely important when solving real life exponential fitting problems, because they are so ill-conditioned. [[#Table: Exponential fitting test problems.]] shows the relevant routines.

====Table: Exponential fitting test problems.====

{| class="wikitable"
!Function
!Description
|-
|''expAssign''||Assign exponential fitting problem.
|-
|''exp_ArtP''||Generate artificial exponential sum problems.
|-
|''expInit''||Find starting values for the exponential parameters <math>\lambda</math>.
|-
|''expSolve''||Solve exponential fitting problems.
|-
|''exp_prob''||Defines a exponential fitting type of problem, with data series (''t, y''). The file includes data from several different empirical test series.
|-
|''Helax_prob''||Defines 335 medical research problems supplied by Helax AB, Uppsala, Sweden, where an exponential model is fitted to data. The actual data series (''t, y'') are stored on one file each, i.e. 335 data files, 8MB large, and are not distributed. A sample of five similar files are part of ''exp prob''.
|-
|''exp_r''||Compute the residual vector <math>r_i(x), i = 1,...,m.~ x \in \mathbb{R}^n</math>
|-
|''exp_J''||Compute the Jacobian matrix <math>\partial r_i / d x_j, i=1,...,m, j=1,...,n</math>
|-
|''exp_d2r''||Compute the 2nd part of the second derivative for the nonlinear least squares exponential fitting problem.
|-
|''exp_c''||Compute the constraints <math>\lambda_1 < \lambda_2 < ...</math> on the exponential parameters <math>\lambda_i, i=1,...,p</math>.
|-
|''exp_dc''||Compute matrix of constraint normals for constrained exponential fitting problem.
|-
|''exp_d2c''||Compute second part of second derivative matrix of the Lagrangian function for constrained exponential fitting problem. This is a zero matrix, because the constraints are linear.
|-
|''exp_q''||Find starting values for exponential parameters <math>\lambda_i, i=1,...,p</math>.
|-
|''exp_p''||Find optimal number of exponential terms, ''p''.
|}

==Large Scale LS problems with Tlsqr==

The ''Tlsqr ''MEX solver provides special parameters for advanced memory handling, enabling the user to solve extremely large linear least squares problems.

We'll take the problem of solving ''Ax ''= ''b ''in the least squares sense as a prototype problem for this section. Here, ''A ? ''R''m×n ''is a dense or sparse matrix and ''b ? ''R''m ''.

'''Controlling memory allocation in '''''Tlsqr''

The normal mode of operation of ''Tlsqr ''is that memory for the ''A ''matrix is allocated and deallocated each time the solver is called. In a real-life situation with a very large ''A ''and where the solver is called repeatedly, this may become inefficient and even cause problems getting memory because of memory fragmenting.

The ''Tlsqr ''solver provides a parameter ''Alloc'', given as the second element of the first input parameter to control the memory handling. The possible values of ''Alloc ''and their meanings are given in [[#Table: Alloc values for Tlsqr]].

====Table: ''Alloc ''values for ''Tlsqr''====

{| class="wikitable"
!Alloc (m(2))
!Meaning
|-
|0||Normal operation: allocate - solve - deallocate
|-
|1||Only allocate, no results returned
|-
|2||Allocate and solve, no deallocate
|-
|3||Only solve, no allocate/deallocate
|-
|4||Solve and deallocate
|-
|5||Deallocate only, no results returned
|}

An example of the calling sequence is given below.

<pre>
>> m = 60000; n = 1000; d = 0.01; % Size and density of A
>> A = sprand(m,n,d); % Sparse random matrix
>> b = ones(m,1); % Right hand side
>> whos A

Name Size Bytes Class
A 60000x500 3584784 sparse array

Grand total is 298565 elements using 3584784 bytes

% =======================================================================
% Simple standard call to Tlsqr, Alloc is set to default 0 if m is scalar

>> x=Tlsqr(m,n,A,[],[],b);

% =======================================================================
% To solve repeatedly with e.g. the same A but different b,
% the user may do:

% Indicate to Tlsqr to allocate and solve the problem

>> m(2) = 2
m =
60000 2

>> x = Tlsqr(m,n,A,[],[],b); % First solution

% Indicate to Tlsqr that memory is already allocated,
% and that no deallocation should occur on exit

>> m(2) = 3
m =
60000 3

% Loop 100 times, calling Tlsqr each time - without re-allocation of memory

>> for k=1:100
>> b = (...); % E.g. alter the right hand side each time
>> x = Tlsqr(m,n,A,[],[],b); % Call Tlsqr, now with m(2)=3
>> end

% Final call, with m(2) = 4: Solve and deallocate

>> m(2) = 4
m =
60000 4

>> x=Tlsqr(m,n,A,[],[],b);

% Alternatively, to just deallocate, the user could do
>> m(2) = 5;
>> Tlsqr(m,n,A,[],[],b); % Nothing is returned
</pre>

'''Further Memory Control: The maxneA Parameter'''

If the number of non-zero elements in a sparse ''A ''matrix increases in the middle of a ''Tlsqr''-calling loop, the initially allocated space will not be sufficient. One solution is that the user checks this prior to calling ''Tlsqr ''and reallocating if necessary. The other solution is to set ''m''(3) to an upper limit (''maxneA'') of the number of nonzero elements in ''A ''in the first allocation call. For example:

<pre>
>> m = [ 60000 1 1E6 ]

m =
60000 1 1000000
</pre>

will initiate a ''Tlsqr ''session, allocating sufficient memory to allow ''A'' matrices with up to 1.000.000 nonzeros. If the allocated memory is still insufficient, ''Tlsqr'' will try to reallocate enough space for the operation to continue.

'''Using Global Variables with Tlsqr and Tlsqrglob.m'''

For cases where it is not possible to send the ''A'' matrix to ''Tlsqr'' because it is simply too large, the user may choose to use the ''tomlab/mex/Tlsqrglob.m ''routine.

This function, which more often than not needs to be customized to the application in mind, should provide the following functionality:

<source lang="matlab">
function y = Tlsqrglob( mode, m, n, x, Aname, rw )

global A

if mode==1
y = A*x;
else
y = A'*x;
end
</source>

The purpose is to provide the possibility to define a global variable ''A ''and perform the multiplication without transferring this potentially very large matrix to the MEX function ''Tlsqr''.

If several matrices are involved, for example if ''A ''= [''A''1 ; ''A''2 ], this approach can be used to eliminate the need to explicitly repeatedly form the composite matrix ''A ''during a run. ''Tlsqrglob.m ''should then be (copied and) modified as:

<source lang="matlab">
function y = Tlsqrglob( mode, m, n, x, Aname, rw )

global A1 A2

if mode==1
y = A1*x;
y = [y ; A2*x];
else
M = size(A1,1);
y = A1' * x(1:M) + ...
A2' * x(M+1:end);
end
</source>

To use the global approach, ''Tlsqr ''must be called with the name of the global multiplication routine, for example:

<source lang="matlab">
[ x, ... ] = Tlsqr(m,n,'Tlsqrglob',...);
</source>

TOMLAB Problem Types and Solver Routines

2014-07-31T11:38:23Z

Bjorn: /* Solver Routines in TOMLAB */

[[Category:Manuals]]
{{Part Of Manual|title=the TOMLAB Manual|link=[[TOMLAB|TOMLAB Manual]]}}
Section [[#Problem Types Defined in TOMLAB|Problem Types Defined in TOMLAB]] defines all problem types in TOMLAB. Each problem definition is accompanied by brief suggestions on suitable solvers. This is followed in [[#Solver Routines in TOMLAB|Solver Routines in TOMLAB]] by a complete list of the available solver routines in TOMLAB and the various available extensions, such as /SOL and /CGO.

==Problem Types Defined in TOMLAB==

===Unconstrained Optimization Problem===

The '''unconstrained optimization '''('''uc''') problem is defined as

<math>
\begin{array}{ll}
\min\limits_{x} & f(x) \\
& \\
s/t & \begin{array}{lcccl}
x_{L} & \leq & x & \leq & x_{U}, \\
\end{array}
\end{array}
</math>

where <math>x, x_L, x_U \in \mathbb{R}^n</math> and <math>f(x) \in \mathbb{R}</math> . For unbounded variables, the corresponding elements of <math>x_L,x_U</math> may be set to <math>\pm \infty</math>.

Recommended solvers: '''TOMLAB /KNITRO and TOMLAB /SNOPT'''.

The TOMLAB Base Module routine ''ucSolve ''includes several of the most popular search step methods for unconstrained optimization. The search step methods for unconstrained optimization included in ''ucSolve ''are: the Newton method, the quasi-Newton BFGS and DFP method, the Fletcher-Reeves and Polak-Ribiere conjugate-gradient method, and the Fletcher conjugate descent method. The quasi-Newton methods may either update the inverse Hessian (standard) or the Hessian itself. The Newton method and the quasi-Newton methods updating the Hessian use a subspace minimization technique to handle rank problems. The quasi-Newton algorithms also use safe guarding techniques to avoid rank problem in the updated matrix.

Another TOMLAB Base Module solver suitable for unconstrained problems is the structural trust region algorithm ''sTrustr'', combined with an initial trust region radius algorithm. It treats partially separable functions. Safeguarded BFGS or DFP are used for the quasi-Newton update, if the analytical Hessian is not used. The set of constrained nonlinear solvers could also be used for unconstrained problems.

===Quadratic Programming Problem===

The '''quadratic programming '''('''qp''') problem is defined as

<math>
\begin{array}{ll}
\min\limits_{x} & f(x) = \frac{1}{2} x^T F x + c^T x \\
& \\
s/t & \begin{array}{lcccl}
x_{L} & \leq & x & \leq & x_{U}, \\
b_{L} & \leq & A x & \leq & b_{U} \\
\end{array}
\end{array}
</math>

where <math>c, x, x_L, x_U \in \mathbb{R}^n</math>, <math>F \in \mathbb{R}^{n \times n}</math>, <math>A \in \mathbb{R}^{m_1 \times n}</math>, and <math>b_L,b_U \in \mathbb{R}^{m_1}</math>.

Recommended solvers: '''TOMLAB /KNITRO, TOMLAB /SNOPT and TOMLAB /MINLP'''.

A positive semidefinite ''F ''-matrix gives a convex QP, otherwise the problem is nonconvex. Nonconvex quadratic programs are solved with a standard active-set method, implemented in the TOM routine ''qpSolve''. ''qpSolve ''explicitly treats both inequality and equality constraints, as well as lower and upper bounds on the variables (simple bounds). It converges to a local minimum for indefinite quadratic programs.

In TOMLAB ''MINOS ''in the general or the QP-version (''QP-MINOS''), or the dense QP solver ''QPOPT ''may be used. In the TOMLAB /SOL extension the ''SQOPT ''solver is suitable for both dense and large, sparse convex QP and ''SNOPT ''works fine for dense or sparse nonconvex QP.

For very large-scale problems, an interior point solver is recommended, such as TOMLAB /KNITRO or TOMLAB /BARNLP.

TOMLAB /CPLEX, TOMLAB /Xpress and TOMLAB /XA should always be considered for large-scale QP problems.

===Constrained Nonlinear Optimization Problem===

The '''constrained nonlinear optimization '''problem ('''con''') is defined as

<math>
\begin{array}{ll}
\min\limits_{x} & f(x) \\
& \\
s/t & \begin{array}{lcccl}
x_{L} & \leq & x & \leq & x_{U}, \\
b_{L} & \leq & A x & \leq & b_{U} \\
c_{L} & \leq & c(x) & \leq & c_{U} \\
\end{array}
\end{array}
</math>

where <math>x, x_L, x_U \in \mathbb{R}^n</math>, <math>f(x) \in \mathbb{R}</math>, <math>A
\in \mathbb{R}^{m_1 \times n}</math>, <math>b_L,b_U \in \mathbb{R}^{m_1}</math>
and <math>c_L,c(x),c_U \in \mathbb{R}^{m_2}</math>.

Recommended solvers: '''TOMLAB /SNOPT, TOMLAB /NPSOL and TOMLAB /KNITRO'''.

For general constrained nonlinear optimization a sequential quadratic programming (SQP) method by Schittkowski is implemented in the TOMLAB Base Module solver ''conSolve''. ''conSolve ''also includes an implementation of the Han-Powell SQP method. There are also a TOMLAB Base Module routine ''nlpSolve ''implementing the Filter SQP by Fletcher and Leyffer.

Another constrained solver in TOMLAB is the structural trust region algorithm ''sTrustr'', described above. Currently, ''sTrustr ''only solves problems where the feasible region, defined by the constraints, is convex. TOMLAB /MINOS solves constrained nonlinear programs. The TOMLAB /SOL extension gives an additional set of general solvers for dense or sparse problems.

''sTrustr'', ''pdco ''and ''pdsco ''in TOMLAB Base Module handle nonlinear problems with ''linear ''constraints only.

There are many other options for large-scale nonlinear optimization to consider in TOMLAB. TOMLAB /CONOPT, TOMLAB /BARNLP, TOMLAB /MINLP, TOMLAB /NLPQL and TOMLAB /SPRNLP.

===Box-bounded Global Optimization Problem===

The '''box-bounded global optimization '''('''glb''') problem is defined as

<math>
\begin{array}{ll}
\min\limits_{x} & f(x) \\
& \\
s/t & \begin{array}{llcccll}
-\infty < &x_{L} & \leq & x & \leq & x_{U}& < \infty , \\
\end{array}
\end{array}
</math>

where <math>x, x_L, x_U \in \mathbb{R}^n</math>, <math>f(x) \in \mathbb{R}</math>, i.e. problems that have finite simple bounds on all variables.

Recommended solvers: '''TOMLAB /LGO and TOMLAB /CGO with TOMLAB /SOL'''.

The TOM solver ''glbSolve ''implements the DIRECT algorithm, which is a modification of the standard Lipschitzian approach that eliminates the need to specify a Lipschitz constant. In ''glbSolve ''no derivative information is used. For global optimization problems with expensive function evaluations the TOMLAB /CGO routine ''ego ''implements the Efficient Global Optimization (EGO) algorithm. The idea of the EGO algorithm is to first fit a response surface to data collected by evaluating the objective function at a few points. Then, EGO balances between finding the minimum of the surface and improving the approximation by sampling where the prediction error may be high.

===Global Mixed-integer Nonlinear Programming Problem===

The '''global mixed-integer nonlinear programming '''('''glc''') problem is defined as

<math>
\begin{array}{ll}
\min\limits_{x} & f(x) \\
& \\
s/t & \begin{array}{llcccll}
-\infty < &x_{L} & \leq & x & \leq & x_{U}& < \infty \\
&b_{L} & \leq & A x & \leq & b_{U}& \\
&c_{L} & \leq & c(x) & \leq & c_{U},& x_{j} \in \mathbb{N}\ ~~\forall j \in I
\end{array}
\end{array}
</math>

where <math>x, x_L, x_U \in \mathbb{R}^n</math>, <math>f(x) \in \mathbb{R}</math>, <math>A \in \mathbb{R}^{m_1 \times n}</math>, <math>b_L,b_U \in \mathbb{R}^{m_1}</math> and <math>c_L,c(x),c_U \in \mathbb{R}^{m_2}</math>.
The variables <math>x \in I</math>, the index subset of <math>1,...,n</math>, are restricted to be integers.

Recommended solvers: '''TOMLAB /OQNLP'''.

The TOMLAB Base Module solver ''glcSolve ''implements an extended version of the DIRECT algorithm, that handles problems with both nonlinear and integer constraints.

===Linear Programming Problem===

The '''linear programming '''('''lp''') problem is defined as

<math>
\begin{array}{ll}
\min\limits_{x} & f(x) = c^T x \\
& \\
s/t & \begin{array}{lcccl}
x_{L} & \leq & x & \leq & x_{U}, \\
b_{L} & \leq & A x & \leq & b_{U} \\
\end{array}
\end{array}
</math>

where <math>c, x, x_L, x_U \in \mathbb{R}^n</math>,
<math>A \in \mathbb{R}^{m_1 \times n}</math>, and <math>b_L,b_U \in \mathbb{R}^{m_1}</math>.

Recommended solvers: '''TOMLAB /CPLEX, TOMLAB /Xpress and TOMLAB /XA'''.
The TOMLAB Base Module solver ''lpSimplex ''implements a simplex algorithm for '''lp '''problems.

When a dual feasible point is known in (6) it is efficient to use the dual simplex algorithm implemented in the TOMLAB Base Module solver ''DualSolve''. In TOMLAB /MINOS the LP interface to ''MINOS'', called ''LP-MINOS ''is efficient for solving large, sparse LP problems. Dense problems are solved by ''LPOPT''. The TOMLAB /SOL extension gives the additional possibility of using ''SQOPT ''to solve large, sparse LP.

The recommended solvers normally outperforms all other solvers.

===Mixed-integer Programming Problem===

The '''mixed-integer programming problem '''('''mip''') is defined as

<math>
\begin{array}{ll}
\min\limits_{x} & f(x) = c^T x \\
& \\
s/t & \begin{array}{lcccl}
x_{L} & \leq & x & \leq & x_{U}, \\
b_{L} & \leq & A x & \leq & b_{U}, ~x_{j} \in \mathbb{N}\ ~~\forall j \in I \\
\end{array}
\end{array}
</math>

where <math>c, x, x_L, x_U \in \mathbb{R}^n</math>, <math>A \in \mathbb{R}^{m_1
\times n}</math>, and <math>b_L,b_U \in \mathbb{R}^{m_1}</math>. The variables <math>x
\in I</math>, the index subset of <math>1,...,n</math> are restricted to be
integers. Equality constraints are defined by setting the lower
bound equal to the upper bound, i.e. for constraint <math>i: b_{L}(i)
= b_{U}(i)</math>.

Recommended solvers: '''TOMLAB /CPLEX, TOMLAB /Xpress and TOMLAB /XA'''.

Mixed-integer programs can be solved using the TOMLAB Base Module routine ''mipSolve ''that implements a standard branch-and-bound algorithm. When dual feasible solutions are available, mipSolve is using the TOMLAB dual simplex solver DualSolve to solve subproblems, which is significantly faster than using an ordinary linear programming solver, like the TOMLAB lpSimplex. ''mipSolve ''also implements user defined priorities for variable selection, and different tree search strategies. For 0/1 - knapsack problems a round-down primal heuristic is included. Another TOMLAB Base Module solver is the cutting plane routine ''cutplane'', using Gomory cuts. It is recommended to use ''mipSolve ''with the LP version of ''MINOS ''with warm starts for the subproblems, giving great speed improvement. The TOMLAB /Xpress extension gives access to the state-of-the-art LP, QP, MILP and MIQP solver Xpress-MP. For many MIP problems, it is necessary to use such a powerful solver, if the solution should be obtained in any reasonable time frame. TOMLAB /CPLEX is equally powerful as TOMLAB /Xpress and also includes a network solver.

===Linear Least Squares Problem===

The '''linear least squares '''('''lls''') problem is defined as

<math>
\begin{array}{ll}
\min\limits_{x} & f(x) = \frac{1}{2} || C x - d || \\
& \\
s/t & \begin{array}{lcccl}
x_{L} & \leq & x & \leq & x_{U}, \\
b_{L} & \leq & A x & \leq & b_{U} \\
\end{array}
\end{array}
</math>

where <math>x, x_L, x_U \in \mathbb{R}^n</math>, <math>d \in \mathbb{R}^M</math>,
<math>C \in \mathbb{R}^{M \times n}</math>,
<math>A \in \mathbb{R}^{m_1 \times n}</math>, <math>b_L,b_U \in \mathbb{R}^{m_1}</math> and <math>c_L,c(x),c_U \in \mathbb{R}^{m_2}</math>.

Recommended solvers: '''TOMLAB /LSSOL'''.

''Tlsqr ''solves unconstrained sparse '''lls '''problems. ''lsei ''solves the general dense problems. ''Tnnls ''is

a fast and robust replacement for the Matlab nnls. The general least squares solver ''clsSolve ''may also be used.

In the TOMLAB

/NPSOL or TOMLAB /SOL extension the ''LSSOL ''solver is suitable for dense linear least squares problems.

===Constrained Nonlinear Least Squares Problem===

The '''constrained nonlinear least squares '''('''cls''') problem is defined as

<math>
\begin{array}{ll}
\min\limits_{x} & f(x) = \frac{1}{2} r(x)^T r(x) \\
& \\
s/t & \begin{array}{lcccl}
x_{L} & \leq & x & \leq & x_{U}, \\
b_{L} & \leq & A x & \leq & b_{U} \\
c_{L} & \leq & c(x) & \leq & c_{U} \\
\end{array}
\end{array}
</math>

where <math>x, x_L, x_U \in \mathbb{R}^n</math>, <math>r(x) \in \mathbb{R}^M</math>,
<math>A \in \mathbb{R}^{m_1 \times n}</math>, <math>b_L,b_U \in \mathbb{R}^{m_1}</math>
and <math>c_L,c(x),c_U \in \mathbb{R}^{m_2}</math>.

Recommended solvers: '''TOMLAB /NLSSOL'''.

The TOMLAB Base Module nonlinear least squares solver ''clsSolve ''treats problems with bound constraints in a similar way as the routine ''ucSolve''. This strategy is combined with an active-set strategy to handle linear equality and inequality constraints.

''clsSolve ''includes seven optimization methods for nonlinear least squares problems, among them: the Gauss-Newton method, the Al-Baali-Fletcher and the Fletcher-Xu hybrid method, and the Huschens TSSM method. If rank problems occur, the solver uses subspace minimization. The line search algorithm used is the same as for unconstrained problems.

Another fast and robust solver is ''NLSSOL'', available in the TOMLAB /NPSOL or the TOMLAB /SOL extension toolbox.

One important utility routine is the TOMLAB Base Module line search algorithm ''LineSearch'', used by the solvers ''conSolve'', ''clsSolve ''and ''ucSolve''. It implements a modified version of an algorithm by Fletcher. The line search algorithm uses quadratic and cubic interpolation. Another TOMLAB Base Module routine, ''preSolve'', is running a presolve analysis on a system of linear qualities, linear inequalities and simple bounds. An algorithm by Gondzio, somewhat modified, is implemented in ''preSolve''.

===Linear Semi-definite Programming Problem===

The '''linear semi-definite programming problem with linear matrix inequalities '''('''sdp''') is defined as

<math>
\begin{array}{rccccl}
\min\limits_{x} & {f(x) = {c^T}x} \\
& \\s/t & x_{L} & \leq & x & \leq & x_{U}\\
& b_{L} & \leq & Ax & \leq & b_{U} \\
& {r}{Q^{i}_0 + Q^{i}_{k}x_{k} \sum{k=1}^{n} \preccurlyeq 0,\qquad i=1,\ldots,m.} \\
\end{array}
</math>

where <math>c, x, x_L, x_U \in \mathbb{R}^n</math>, <math>A \in \mathbb{R}^{m_l\times n}</math>, <math>b_L,b_U \in \mathbb{R}^{m_l}</math> and <math>Q^{i}_{k}</math> are symmetric matrices of similar dimensions in each constraint <math>i</math>. If there are several LMI constraints, each may have it's own dimension.

Recommended solvers: '''TOMLAB /PENSDP and TOMLAB /PENBMI'''.

The '''linear semi-definite programming problem with bilinear matrix inequalities '''('''bmi''') is defined similarly to but with the matrix inequality

<math>
Q^{i}_0 + \sum_{k=1}^{n} Q^{i}_{k} x_{k} + \sum_{k=1}^{n} \sum_{l=1}^{n} x_{k}x_{l} K^{i}_{kl} \preccurlyeq 0
</math>

The MEX solvers ''pensdp ''and ''penbmi ''treat '''sdp '''and '''bmi '''problems, respectively. These are available in the TOMLAB /PENSDP and TOMLAB /PENBMI toolboxes.

The MEX-file solver ''pensdp ''available in the TOMLAB /PENSDP toolbox implements a penalty method aimed at large-scale dense and sparse '''sdp '''problems. The interface to the solver allows for data input in the sparse SDPA input format as well as a TOMLAB specific format corresponding to.

The MEX-file solver ''penbmi ''available in the TOMLAB /PENBMI toolbox is similar to ''pensdp'', with added support for the bilinear matrix inequalities.

==Solver Routines in TOMLAB==

===TOMLAB Base Module===

TOMLAB includes a large set of optimization solvers. Most of them were originally developed by the Applied Optimization and Modeling group (TOM). Since then they have been improved e.g. to handle Matlab sparse arrays and been further developed. [[#Table: The optimization solvers in TOMLAB Base Module.]]. lists the main set of TOM optimization solvers in all versions of TOMLAB.

====Table: The optimization solvers in TOMLAB Base Module.====

{| class="wikitable"
!Function
!Description
|- valign="top"
|[[clsSolve]]||Constrained nonlinear least squares. Handles simple bounds and linear equality and inequality constraints using an active-set strategy. Implements Gauss-Newton, and hybrid quasi-Newton and Gauss-Newton methods.
|- valign="top"
|[[conSolve]]||Constrained nonlinear minimization solver using two different sequential quadratic programming methods.
|- valign="top"
|[[cutPlane]]||Mixed-integer programming using a cutting plane algorithm.
|- valign="top"
|[[DualSolve]]||Solves a linear program with a dual feasible starting point.
|- valign="top"
|[[glbSolve]]||Box-bounded global optimization, using only function values.
|- valign="top"
|[[glcCluster]]||Hybrid algorithm for constrained mixed-integer global optimization. Uses a combination of ''glcFast ''(DIRECT) and a clustering algorithm.
|- valign="top"
|[[glcSolve]]||Global mixed-integer nonlinear programming, using no derivatives.
|- valign="top"
|[[infSolve]]||Constrained minimax optimization. Reformulates problem and calls any suitable nonlinear solver.
|- valign="top"
|[[lpSimplex]]||Linear programming using a simplex algorithm.
|- valign="top"
|[[MilpSolve]]||Mixed-integer programming using branch and bound.
|- valign="top"
|[[L1Solve]]||Constrained L1 optimization. Reformulates problem and calls any suitable nonlinear solver.
|- valign="top"
|[[mipSolve]]||Mixed-integer programming using a branch-and-bound algorithm.
|- valign="top"
|[[nlpSolve]]||Constrained nonlinear minimization solver using a filter SQP algorithm.
|- valign="top"
|[[pdcoTL]]||Linearly constrained nonlinear minimization solver using a primal- dual barrier algorithm.
|- valign="top"
|[[pdscoTL]]||Linearly constrained nonlinear minimization solver using a primal- dual barrier algorithm, for separable functions.
|- valign="top"
|[[qpSolve]]||Non-convex quadratic programming.
|- valign="top"
|[[slsSolve]]||Sparse constrained nonlinear least squares. Reformulates problem and calls any suitable sparse nonlinear solver.
|- valign="top"
|[[sTrustr]]||Constrained convex optimization of partially separable functions, using a structural trust region algorithm.
|- valign="top"
|[[ucSolve]]||Unconstrained optimization with simple bounds on the parameters. Implements Newton, quasi-Newton and conjugate-gradient methods.
|}

Additional Fortran solvers in TOMLAB are listed in [[#Table: Additional solvers in TOMLAB.]]. They are called using a set of MEX-file interfaces developed in TOMLAB.

====Table: Additional solvers in TOMLAB.====

{| class="wikitable"
!Function
!Description
|-
|''goalSolve''||Solves sparse multi-objective goal attainment problems
|-
|''lsei''||Dense constrained linear least squares
|-
|''qld''||Convex quadratic programming
|-
|''Tfzero''||Finding a zero to f(x) in an interval, ''x '' is one-dimensional.
|-
|''Tlsqr''|| Sparse linear least squares.
|-
|''Tnnls''||Nonnegative constrained linear least squares
|}

===TOMLAB /BARNLP===

The add-on toolbox TOMLAB /BARNLP solves large-scale nonlinear programming problems using a sparse primal-dual interior point algorithm, in conjunction with a filter for globalization. The solver package was developed in co-operation with Boeing Phantom Works. The TOMLAB /BARNLP package is described in a separate manual available at [http://tomopt.com/ http://tomopt.com].

===TOMLAB /CGO===

The add-on toolbox TOMLAB /CGO solves costly global optimization problems. The solvers are listed in [[#Table: Additional solvers in TOMLAB /CGO.]]. They are written in a combination of Matlab and Fortran code, where the Fortran code is called using a set of
MEX-file interfaces developed in TOMLAB.

====Table: Additional solvers in TOMLAB /CGO.====

{| class="wikitable"
!Function
!Description
|-
|''rbfSolve||''Costly constrained box-bounded optimization using a RBF algorithm.
|-
|''ego''||Costly constrained box-bounded optimization using the Efficient Global Optimization (EGO) algorithm.
|}

===TOMLAB /CONOPT===

The add-on toolbox TOMLAB /CONOPT solves large-scale nonlinear programming problems with a feasible path GRG method . The solver package was developed in co-operation with Arki Consulting and Development A/S. The TOMLAB /CONOPT is described in a separate manual available at [http://tomopt.com/ http://tomopt.com]. There is also m-file help available.

===TOMLAB /CPLEX===

The add-on toolbox TOMLAB /CPLEX solves large-scale mixed-integer linear and quadratic programming prob- lems. The solver package was developed in co-operation with ILOG S.A. The TOMLAB /CPLEX solver package and interface are described in a manual available at [http://tomopt.com/ http://tomopt.com].

===TOMLAB /KNITRO===

The add-on toolbox TOMLAB /KNITRO solves large-scale nonlinear programming problems with interior (barrier) point trust-region methods. The solver package was developed in co-operation with Ziena Optimization Inc. The TOMLAB /KNITRO manual is available at [http://tomopt.com/ http://tomopt.com].

===TOMLAB /LGO===

The add-on toolbox TOMLAB /LGO solves global nonlinear programming problems. The LGO solver package is developed by Pint´er Consulting Services, Inc. The TOMLAB /LGO manual is available at [http://tomopt.com/ http://tomopt.com/].

===TOMLAB /MINLP===

The add-on toolbox TOMLAB /MINLP provides solvers for continuous and mixed-integer quadratic programming

('''qp''','''miqp''') and continuous and mixed-integer nonlinear constrained optimization ('''con''', '''minlp''').

All four solvers, written by Roger Fletcher and Sven Leyffer, University of Dundee, Scotland, are available in sparse and dense versions. The solvers are listed in [[#Table: Solver routines in TOMLAB /MINLP.]].

The TOMLAB /MINLP manual is available at [http://tomopt.com/ http://tomopt.com].

====Table: Solver routines in TOMLAB /MINLP.====

{| class="wikitable"
!Function
!Description
|-
|''bqpd''||Quadratic programming using a null-space method.
|-
|''miqpBB''||Mixed-integer quadratic programming using ''bqpd ''as subsolver.
|-
|''filterSQP''||Constrained nonlinear minimization using a Filtered Sequential QP method.
|-valign="top"
|''minlpBB''||Constrained, mixed-integer nonlinear minimization using a branch- and-bound search scheme. ''filterSQP ''is used as NLP solver.
|}

===TOMLAB /MINOS===

Another set of Fortran solvers were developed by the Stanford Optimization Laboratory (SOL). [[#Table: The SOL optimization solvers in TOMLAB /MINOS.]] lists the solvers included in TOMLAB /MINOS. The solvers are called using a set of MEX-file interfaces developed as part of TOMLAB. All functionality of the SOL solvers are available and changeable in the TOMLAB framework in Matlab.

====Table: The SOL optimization solvers in TOMLAB /MINOS.====

{| class="wikitable"
!Function
!Description
|-
|''MINOS 5.51||''Sparse linear and nonlinear programming with linear and nonlin- ear constraints.
|-
|''LP-MINOS||''A special version of the ''MINOS 5.5 ''MEX-file interface for sparse linear programming.
|-
|''QP-MINOS''||A special version of the ''MINOS 5.5 ''MEX-file interface for sparse quadratic programming.
|-
|''LPOPT 1.0-10''||Dense linear programming.
|-
|''QPOPT 1.0-10 ''||Non-convex quadratic programming with dense constraint matrix and sparse or dense quadratic matrix.
|}

===TOMLAB /OQNLP===

The add-on toolbox TOMLAB /OQNLP uses a multistart heuristic algorithm to find global optima of smooth constrained nonlinear programs (NLPs) and mixed-integer nonlinear programs (MINLPs). The solver package was developed in co-operation with Optimal Methods Inc. The TOMLAB /OQNLP manual is available at [http://tomopt.com/ http://tomopt.com/]

===TOMLAB /NLPQL===

The add-on toolbox TOMLAB /NLPQL solves dense nonlinear programming problems, multi criteria optimiza- tion problems and nonlinear fitting problems. The solver package was developed in co-operation with Klaus Schittkowski. The TOMLAB /NLPQL manual is available at [http://tomopt.com/ http://tomopt.com].

===TOMLAB /NPSOL===

The add-on toolbox TOMLAB /NPSOL is a sub package of TOMLAB /SOL. The package includes the MINOS solvers as well as NPSOL, LSSOL and NLSSOL. The TOMLAB /NPSOL manual is available at [http://tomopt.com/ http://tomopt].

===TOMLAB /PENBMI===

The add-on toolbox TOMLAB /PENBMI solves linear semi-definite programming problems with linear and bilinear matrix inequalities. The solvers are listed in [[#Additional solvers in TOMLAB /PENBMI.]]. They are written in a combination of Matlab and C code. The TOMLAB /PENBMI manual is available at [http://tomopt.com/ http://tomopt.com].

====Additional solvers in TOMLAB /PENBMI.====

{| class="wikitable"
!Function
!Description
|-
|''penbmi''||Sparse and dense linear semi-definite programming using a penalty algorithm.
|-
|''penfeas bmi''||Feasibility check of systems of linear matrix inequalities, using ''penbmi''.
|}

===TOMLAB /PENSDP===

The add-on toolbox TOMLAB /PENSDP solves linear semi-definite programming problems with linear matrix inequalities. The solvers are listed in [[#Table: Additional solvers in TOMLAB /PENSDP.]]. They are written in a combination of Matlab and C code. The TOMLAB /PENSDP manual is available at [http://tomopt.com/ http://tomopt.com].

====Table: Additional solvers in TOMLAB /PENSDP.====

{| class="wikitable"
!Function
!Description
|-
|''pensdp''||Sparse and dense linear semi-definite programming using a penalty algorithm.
|-
|''penfeas_sdp''||Feasibility check of systems of linear matrix inequalities, using ''pensdp''.
|}

===TOMLAB /SNOPT===

The add-on toolbox TOMLAB /SNOPT is a sub package of TOMLAB /SOL. The package includes the MINOS solvers as well as SNOPT and SQOPT. The TOMLAB /SNOPT manual is available at [http://tomopt.com/ http://tomopt.com].

===TOMLAB /SOL===

The extension toolbox TOMLAB /SOL gives access to the complete set of Fortran solvers developed by the Stanford Systems Optimization Laboratory (SOL). These solvers are listed in [[#Table: The SOL optimization solvers in TOMLAB /MINOS.]] and [[#Table: The optimization solvers in the TOMLAB /SOL toolbox.]].

====Table: The optimization solvers in the TOMLAB /SOL toolbox.====

{| class="wikitable"
!Function
!Description
|-
|''NPSOL 5.02''||Dense linear and nonlinear programming with linear and nonlinear constraints.
|-
|''SNOPT 6.2-2''||Large, sparse linear and nonlinear programming with linear and nonlinear constraints.
|-
|''SQOPT 6.2-2''||Sparse convex quadratic programming.
|-
|''NLSSOL 5.0-2''||Constrained nonlinear least squares. NLSSOL is based on NPSOL. No reference except for general NPSOL reference.
|-
|''LSSOL 1.05-4''||Dense linear and quadratic programs (convex), and constrained linear least squares problems.
|}

===TOMLAB /SPRNLP===

The add-on toolbox TOMLAB /SPRNLP solves large-scale nonlinear programming problems. SPRNLP is a state- of-the-art sequential quadratic programming (SQP) method, using an augmented Lagrangian merit function and safeguarded line search. The solver package was developed in co-operation with Boeing Phantom Works. The TOMLAB /SPRNLP package is described in a separate manual available at [http://tomopt.com/ http://tomopt.com].

===TOMLAB /XA===

The add-on toolbox TOMLAB /XA solves large-scale linear, binary, integer and semi-continuous linear program- ming problems, as well as quadratic programming problems. The solver package was developed in co-operation with Sunset Software Technology. The TOMLAB /XA package is described in a separate manual available at [http://tomopt.com/ http://tomopt.com].

===TOMLAB /Xpress===

The add-on toolbox TOMLAB /Xpress solves large-scale mixed-integer linear and quadratic programming prob- lems. The solver package was developed in co-operation with Dash Optimization Ltd. The TOMLAB /Xpress solver package and interface are described in the html manual that comes with the installation package. There is also a TOMLAB /Xpress manual available at [http://tomopt.com/ http://tomopt.com].

===Finding Available Solvers===

To get a list of all available solvers, including Fortran, C and Matlab Optimization Toolbox solvers, for a certain ''solvType'', call the routine ''SolverList ''with ''solvType ''as argument. ''solvType ''should either be a string ('uc', 'con' etc.) or the corresponding ''solvType ''number as given in following [[#Table: solvProbType]]. For example, if wanting a list of all available solvers of ''solvType '''''con''', then

<source lang="matlab">
SolverList('con')
</source>

gives the output

<pre>
>> SolverList('con');

Tomlab recommended choice for Constrained Nonlinear Programming (NLP)

npsol

Other solvers for NLP

Licensed:

nlpSolve
conSolve
sTrustr
constr
minos
PDCO
snopt
fmincon
filterSQP
PDSCO
knitro
conopt
nlpqlp

Non-licensed:

NONE

Solvers also handling NLP

Licensed:

glcSolve
glcFast
glcCluster
lgo
minlpBB
ego
rbfSolve
arbfmip

Non-licensed:

NONE
</pre>

''SolverList ''also returns two output arguments: all available solvers as a string matrix and a vector with the corresponding ''solvType ''for each solver.

Note that solvers for a more general problem type may be used to solve the problem. In [[#Table: solvProbType]] an attempt has been made to classify these relations.

====Table: solvProbType====

The problem classes (''probType'') possible to solve with each type of solver (''solvType'') is marked with an ''x''. When the solver is in theory possible to use, but from a practical point of view is probably not suitable, parenthesis are added (''x'').

{| class="wikitable"
!|| colspan="10" align="center" border="2" | solvType
|-
!probType||uc||qp||con||ls||lls||cls||mip||lp||glb||glc
|-
|'''uc'''||x||||x||||||||||||x||(x)
|-
|'''qp'''||||x||x||||||||||||||(x)
|-
|'''con'''||||||x||||||||||||||(x)
|-
|'''ls'''||||||x||x||||x||||||||(x)
|-
|'''lls'''||||x||x||x||x||x||||||||(x)
|-
|'''cls'''||||||x||||||x||||||||(x)
|-
|'''mip'''||||||||||||||x||||||(x)
|-
|'''lp'''||||x||x||||||||x||x||||(x)
|-
|'''glb'''||||||(x)||||||||||||x||x
|-
|'''glc'''||||||(x)||||||||||||||x
|-
|'''exp'''||x||||x||(x)||||x||||||||(x)
|-
|}

MIPNLP stoaMINLP

2014-07-14T10:41:10Z

Bjorn: Created page with "{{Part Of Manual|title=the MIPNLP Manual|link=MIPNLP Manual}} ==Purpose== stoaMINLP solves convex mixed-integer nonlinear programming problems (MINLP). ''stoaMINLP '..."

{{Part Of Manual|title=the MIPNLP Manual|link=[[MIPNLP|MIPNLP Manual]]}}
==Purpose==

stoaMINLP solves convex mixed-integer nonlinear programming problems (MINLP).

''stoaMINLP ''solves problems of the form

<math>
\begin{array}{cccccc}
\min\limits_{x} & f(x) \\s/t & x_{L} & \leq & x & \leq & x_{U} \\& b_{L} & \leq & Ax & \leq & b_{U} \\& c_{L} & \leq & c(x) & \leq & c_{U} \\& & & {x_{j} \in \mathbb{N} \ \ \forall j \in I} \\
\end{array}
</math>

where <math>x,x_{L},x_{U}\in \mathbb{R}^{n}</math> , <math>c(x),c_{L},c_{U}\in
\mathbb{R}^{m_{1}}</math> , <math>A\in \mathbb{R}^{m_{2}\times n}</math> and
<math>b_{L},b_{U}\in \mathbb{R}^{m_{2}}</math>. The variables <math>x \in I</math> , the
index subset of <math>1,...,n</math> are restricted to be integers.

==Calling Syntax==

Recommended is to first set IterPrint, to get information each iteration
<source lang="matlab">
Prob.optParam.IterPrint = 1;
</source>
Driver call, including printing with level 2:
<source lang="matlab">
Result = tomRun('stoaMINLP',Prob,2);
</source>
Direct solver call:
<source lang="matlab">
Result = stoaMINLP(Prob);
PrintResult(Result);
Result = tomRun('stoaMINLP',Prob,...)
</source>

=== Warm Start ===
To make a restart (warm start), just set the warm start flag, and call stoaMINLP once again:

<source lang="matlab">
Prob.WarmStart = 1;
Result = tomRun('stoaMINLP', Prob, 2);
</source>

stoaMINLP will read warm start information from the stoaMINLPSave.mat file. Another warm start (with same MaxFunc) is made by just calling tomRun again:

<source lang="matlab">
Result = tomRun('stoaMINLP', Prob, 2);
</source>

To make a restart from the warm start information in the Result structure, make a call to WarmDefGLOBAL before calling stoaMINLP. WarmDefGLOBAL moves information from the Result structure to the Prob structure and sets the warm start flag, <code>Prob.WarmStart = 1;</code>

<source lang="matlab">
Prob = WarmDefGLOBAL('stoaMINLP', Prob, Result);
</source>

where Result is the result structure returned by the previous run. A warm start (with same MaxIter) is done by just calling tomRun again:

<source lang="matlab">
Result = tomRun('stoaMINLP', Prob, 2);
</source>

To make another warm start with new MaxIter 100, say, redefine MaxIter as:

<source lang="matlab">
Prob.optParam.MaxIter = 100;
</source>

Then repeat the two lines:

<source lang="matlab">
Prob = WarmDefGLOBAL('stoaMINLP', Prob, Result);
Result = tomRun('stoaMINLP', Prob, 2);
</source>

==Inputs==

===Prob structure===
The '''TOMLAB''' problem structure

{| class="wikitable"
!colspan="2"|The following fields are used in ''Prob'':
|-
|'''Field'''||'''Description'''
|-
|''x_L''||Lower bounds on x.
|-
|''x_U''||Upper bounds on x.
|-
|''A''||The linear constraint matrix.
|-
|''b_L''||Lower bounds on linear constraints.
|-
|''b_U''||Upper bounds on linear constraints.
|-
|''c_L''||Lower bounds on nonlinear constraints.
|-
|''c_U''||Upper bounds on nonlinear constraints.
|-
|''x_0''||Starting point.
|-valign="top"
|''Convex''||If Convex==1, assume NLP problems are convex, and only one local NLP solver call is used at each node. If Convex==0 (Default), multiMin is used to do many calls to a local solver to determine the global minima at each node. The global minimum with most components integer valued is chosen.
|-valign="top"
|''MaxCPU''||Maximal CPU Time (in seconds) to be used by stoaMINLP, stops with best point found
|-valign="top"
|''PriLev''||Print level in stoaMINLP (default 1). Also see optParam.IterPrint
|-valign="top"
|''PriLevOpt''||Print level in sub-solvers (SNOPT and other NLP solvers): =0 No output; ''>''0 Convergence results. ''>''1 Output every iteration, ''>''2 Output each step in the NLP alg For other NLP solvers, see the documentation for the solver
|-valign="top"
|''WarmStart''||If true, ''>''0, stoaMINLP reads the output from the last run from Prob.stoaMINLP, if it exists. If it doesn't exist, stoaMINLP attempts to open and read warm start data from mat-file stoaMINLPSave.mat. stoaMINLP uses the warm start information to continue from the last run. The mat-file minlp- SolveSave.mat is saved every Prob.MIP.SaveFreq iteration.
|-valign="top"
|''SolverNLP''||Name of the solver used for NLP subproblems. If empty, the default solver is found calling GetSolver('con',1); If TOMLAB /SOL installed, SNOPT is the default solver. If SolverNLP is a SOL solver (SNOPT, MINOS or NPSOL), the SOL.optPar and SOL.PrintFile is used: See help minosTL.m, npsolTL.m or snoptTL.m for how to set these parameters
|-valign="top"
|''SolverLP''||Name of the solver used for LP subproblems. If empty, the default solver is found calling GetSolver('lp',1). If TOMLAB /SOL or /SNOPT or /NPSOL installed, MINOS is the default solver. If SolverLP is a SOL solver (MINOS, SNOPT or NPSOL), the SOL.optPar and SOL.PrintFile is used: See help minosTL.m, npsolTL.m or snoptTL.m for how to set these parameters.
|-
|''SolverNLP0''||Name of the solver used for the initial NLP-problem. If empty, SolverNLP is used.
|-valign="top"
|''SolverUC''||Solver used for the unconstrained feasibility problem, NLPF. NLPF is solved in case the NLP problem is infeasible. If empty, the default solver is found calling GetSolver('uc',LargeScale,0).
|-valign="top"
|''RandState''||If Convex == 0, RandState is sent to multiMin to initialize the random generator. RandState is used as follows: If ''> ''0, rand('state',RandState) is set to initialize the pseudo-random generator. If ''< ''0, rand('state',sum(100*clock)) is set to give a new set of random values each run. If RandState == 0, rand('state',) is not called. Default is RandState = -1
|-valign="top"
|''MIP''||Structure defining integer optimization parameters. See the table below for a description of each field used in ''Prob.MIP''.
|-valign="top"
|''STOAMINLP''||Structure with solver-specific options. See the table below with descriptions of the fields used in ''Prob.STOAMINLP''.
|-valign="top"
|''optParam''||Structure with general optimization parameters. See the table below with descriptions of the fields used in ''Prob.optParam''.
|}

===MIP structure===

Substructure in Prob with parameters related to mixed integer programming.

{|class="wikitable"
!colspan="2"|fields used in '''Prob.MIP'''
|-
|'''Field'''||'''Description'''
|-valign="top"
|''IntVars''||If empty, all variables are assumed non-integer. If islogical(IntVars) (=all elements are 0/1), then 1 = integer variable, 0 = continuous variable. If any element ''>''1, IntVars is the indices for integer variables.
|-valign="top"
|''VarWeight''||Weight for each variable in the variable selection phase. A lower value gives higher priority. Setting Prob.MIP.VarWeight might improve convergence.
|-valign="top"
|''DualGap''||''stoaMINLP ''stops if the duality gap is less than DualGap. DualGap = 1, stop at first integer solution e.g. DualGap = 0.01, stop if solution ''< ''1% from optimal solution.
|-valign="top"
|''fIP''||An upper bound on the IP value wanted. Makes it possible to cut branches and avoid node computations. Used even if xIP not given.
|-valign="top"
|''xIP''||The x-values giving the fIP value, if a solution (xIP,fIP) is known.
|-valign="top"
|''NodeSel''||Node selection method: = 1 Depth First. Priority on nodes with more integer components. Default = 2 Breadth First. Priority on nodes with more integer components. = 3 Pure LIFO (Last in, first out) Depth First. = 4 Pure FIFO (First in, first out) Breadth First. = 5 Maximize integer components. = 6 Best bound. = 7 Best estimate using pseudo-costs. = 8 Best projection.
|-valign="top"
|''Backtrack''||Node selection method to use after an integer solution has been found. Available choices are the same as for NodeSel. Default is 2, Breadth First.
|-valign="top"
|''VarSel''||Variable selection method in branch and bound. = 1 Use variable with most fractional value. = 2 Use gradient and distance to nearest integer value. = 3 Pseudo-cost-based branching.
|-valign="top"
|''KNAPSACK''||If = 1, use a knapsack heuristic. Default 0.
|-valign="top"
|''ROUNDH''||If = 1, use a rounding heuristic. Default 0.
|-valign="top"
|''SaveFreq''||Warm start info saved on stoaMINLPSave.mat every SaveFreq iteration (default -1, i.e. no warm start info is saved)
|}

===STOAMINLP structure===

Substructure in Prob with solver-specific options

{|class="wikitable"
!colspan="2"|fields used in Prob.STOAMINLP
|-
|'''Field'''||'''Description'''
|-valign="top"
|''USECUTS''||Flag to use cutting plane algorithm described in [[StoaMINLP#Algorithm]]. Using cuts is not recommended for nonconvex problems. Set nonzero to enable, zero to disable. By default, USECUTS = Prob.Convex.
|-valign="top"
|''B_ecp''||Parameter regulating likelihood of linearization using extended cutting plane. See [[StoaMINLP#Algorithm]] for more information. Default 10.
|-valign="top"
|''K_ecp''||Parameter regulating "tailing off" detection for extended cutting plane linearizations. See [[StoaMINLP#Algorithm]] for more information. Default 0.001.
|-valign="top"
|''M_ecp''||Parameter regulating the balance between branching the search tree and adding linearizations using extended cutting plane. See [[StoaMINLP#Algorithm]] for more information. Default 10.
|-valign="top"
|''B_ff''||Parameter regulating likelihood of linearization using fixed fractional integer decision variables. See [[StoaMINLP#Algorithm]] for more information. Default 10.
|-valign="top"
|''K_ff''||Parameter regulating "tailing off" detection for linearizations using fixed fractional integer decision variables. See [[StoaMINLP#Algorithm]] for more information. Default 0.001.
|-valign="top"
|''M_ff''||Parameter regulating the balance between branching the search tree and adding linearizations using fixed fractional integer decision variables. See [[StoaMINLP#Algorithm]] for more information. Default 10.
|-valign="top"
|''B_nlpr''||Parameter regulating likelihood of linearization using the solution of the relaxed NLP problem. See [[StoaMINLP#Algorithm]] for more information. Default 10.
|-valign="top"
|''K_nlpr''||Parameter regulating "tailing off" detection for linearizations using the solution of the relaxed NLP problem. See [[StoaMINLP#Algorithm]] for more information. Default 0.001.
|-valign="top"
|''M_nlpr''||Parameter regulating the balance between branching the search tree and adding linearizations using the solution of the relaxed NLP problem. See [[StoaMINLP#Algorithm]] for more information. Default 10.
|-valign="top"
|''rTYPE''||= 0 r is fixed to the value in rVALUE. = 1 r is a uniformly distributed random number in the interval [0,1]. Default.
|-valign="top"
|''rVALUE''||Defines the value of r when rTYPE is set to zero. Default is 0.5.
|-valign="top"
|''CUTPOOL''||= 0 All linearizations constraints are kept in the master problem. = 1 Manage a pool with inactive linearization constraints. If an inactive constraint gets violated, it is brought back from the pool. Default.
|-valign="top"
|''CUTDELBND''||The number of consecutive times a linearization can be inactive before it gets removed and put into the inactive pool. Default 15.
|-valign="top"
|''CUTLIMDEL''||= 0 No extra deletion of cuts. Default when Prob.Convex == 1. = 1 Delete any cuts limiting the true feasible region when detected. Such cuts will appear if the problem has nonlinear constraints. Default when Prob.Convex == 0.
|-valign="top"
|''PCITL''||Limit on time spent per node calculating initial pseudo costs when VarSel == 3. Default is 120 (s).
|-valign="top"
|''LINPRINT''||Set nonzero to print short information about the type of linearization added. Default 0. enabled when IterPrint > 3.
|-valign="top"
|''POOLPRINT''||Set nonzero to print information about the cutpool management. Default 0. Enabled when IterPrint > 4.
|}

===optParam structure===

Substructure in Prob with general optimization parameters.

{|class="wikitable"
!colspan="2"|fields used in Prob.optParam:
|-
|'''Field'''||'''Description'''
|-valign="top"
|''MaxIter''||Maximal number of iterations, default 10000
|-valign="top"
|''IterPrint''||Print short information each iteration. Setting PriLev > 1 also enables IterPrint, setting it to 1. 
The information printed for different levels is as follows: 

>0 A line at each evaluated node with the following: 
Iteration number: 
Depth in tree (symbol L[] - empty list, symbol Gap - Dual Gap convergence), fNLP (Optimal f(x) current node), fIPMin (Best integer feasible f(x) found), LowBnd (Lower bound on optimal integer feasible f(x)), Dual Gap in absolut value and percent, The length of the node list L, -L-, The Inform and ExitFlag the solver returned at the current node, FuEv (Number of function evaluations used by solver at current node), date/time stamp. Outer approximation linearizations, number of cuts in active/inactive pool (|C| #A #I). 

> 1 A line at each evaluated node with the information described above. 
Moreover, with IterPrint enabled a notice is printed whenever the algorithm switches node selection methods. 
Setting a higher value of IterPrint gives more detailed information. 

>2 Depth, number of integer components and lower bound on objective for each node in L. 
>3 Sets LINPRINT = 1, print info about linearizations added (if used). 
>4 Sets POOLPRINT = 1, print info about cut-pool management (if used).
|-valign="top"
|''bTol''||Linear constraint violation convergence tolerance.
|-valign="top"
|''cTol''||Constraint violation convergence tolerance.
|-valign="top"
|''fTol''||Optimality tolerance.
|}

==Outputs==

{| class="wikitable"
!''Result''||colspan="2"|Structure with result from optimization. The following fields are changed:
|-
|||''Iter ''||Number of iterations.
|-valign="top"
|||''ExitFlag ''||Exit flag. 0: Global optimal solution found, or integer solution with duality gap less than user tolerance. 1: Maximal number of iterations reached. 2: Empty feasible set, no integer solution found. 4: No feasible point found running NLP relaxation. 5: Illegal x_0 found in NLP relaxation. 99: Maximal CPU Time used (cputime ''> ''Prob.MaxCPU).
|-
|||''Inform''||Code telling type of convergence, returned from subsolver.
|-
|||''ExitText''||Text string giving ''ExitFlag'' and ''Inform'' information.
|-valign="top"
|||''DualGap''||Relative duality gap, max(0,fIPMin-fLB)/-fIPMin-, if fIPMin =0; max(0,fIPMin-fLB) if fIPMin == 0. If fIPMin =0: Scale with 100, 100*Dual- Gap, to get the percentage duality gap. For absolute value duality gap: scale with fIPMin, fIPMin * DualGap
|-
|||''x_k''||Solution.
|-valign="top"
|||''v_k''||Lagrange multipliers. Bounds, Linear and Nonlinear Constraints, size n + mLin + mNonLin.
|-
|||''f_k''||Function value at optimum.
|-
|||''g_k''||Gradient vector at optimum.
|-
|||''x_0''||Starting point x_0.
|-
|||''f_0''||Function value at start.
|-
|||''c_k''||Constraint values at optimum.
|-
|||''cJac''||Constraint derivative values at optimum.
|-
|||''xState''||State of each variable, described in [[TOMLAB_Appendix_B#Table:_The_state_variable_xState_for_the_variable.|TOMLAB Appendix B]].
|-
|||''bState''||State of each constraint, described in [[TOMLAB_Appendix_B#Table:_The_state_variable_bState_for_each_linear_constraint.|TOMLAB Appendix B]].
|-
|||''cState''||State of each general constraint, described in [[TOMLAB_Appendix_B#Table:_The_state_variable_cState_for_each_nonlinear_constraint.|TOMLAB Appendix B]].
|-
|||''Solver''||Solver used ('stoaMINLP').
|-
|||''SolverAlgorithm''||Description of method used.
|-
|||''Prob''||Problem structure used.
|-valign="top"
|||''stoaMINLP''||A structure with warm start information. Use with WarmDefGLOBAL, see example [[StoaMINLP#Warm_Start|here]].
|}

[[Category:MIPNLP]]

MIPNLP ecpMINLP

2014-07-14T10:02:47Z

Bjorn:

{{Part Of Manual|title=the MIPNLP Manual|link=[[MIPNLP|MIPNLP Manual]]}}
==Purpose==

ecpMINLP solves convex mixed-integer nonlinear programming problems (MINLP).

''ecpMINLP ''solves problems of the form

<math>
\begin{array}{cccccc}
\min\limits_{x} & f(x) \\s/t & x_{L} & \leq & x & \leq & x_{U} \\& b_{L} & \leq & Ax & \leq & b_{U} \\& c_{L} & \leq & c(x) & \leq & c_{U} \\& & & {x_{j} \in \mathbb{N} \ \ \forall j \in I} \\
\end{array}
</math>

where <math>x,x_{L},x_{U}\in \mathbb{R}^{n}</math> , <math>c(x),c_{L},c_{U}\in
\mathbb{R}^{m_{1}}</math> , <math>A\in \mathbb{R}^{m_{2}\times n}</math> and
<math>b_{L},b_{U}\in \mathbb{R}^{m_{2}}</math>. The variables <math>x \in I</math> , the
index subset of <math>1,...,n</math> are restricted to be integers.

==Calling Syntax==

Driver call, including printing with level 2:
<source lang="matlab">
Result = tomRun('ecpMINLP',Prob,2);
</source>
Direct solver call:
<source lang="matlab">
Result = ecpMINLP(Prob);
PrintResult(Result);
Result = tomRun('ecpMINLP',Prob,...)
</source>

=== Warm Start ===
Warm start is currently not supported, but might be included in a future release.

==Inputs==

===Prob structure===
The '''TOMLAB''' problem structure

{|class="wikitable"
!colspan="2"|The following fields are used in the problem description structure Prob
|-
|'''Field'''||'''Description'''
|-
|''x_L''||Lower bounds on x.
|-
|''x_U''||Upper bounds on x.
|-
|''A''||The linear constraint matrix.
|-
|''b_L''||Lower bounds on linear constraints.
|-
|''b_U''||Upper bounds on linear constraints.
|-
|''c_L''||Lower bounds on nonlinear constraints.
|-
|''c_U''||Upper bounds on nonlinear constraints.
|-
|''f_Low''||Lower bound on solution.
|-
|''x_0''||Starting point.
|-valign="top"
|''MaxCPU''||Maximal CPU Time (in seconds) to be used by ecpMINLP, stops with best point found
|-valign="top"
|''PriLev''||Print level in ecpMINLP (default 1). Also see optParam.IterPrint
{|class="wikitable"
!value||output
|-
|=0||Silent.
|-
|>0||Initial information and convergence results.
|-
|>1||Output a line whenever the solution has improved, containing:
nIterations, nCuts, nCuts with criteria fulfilled, nLinearizations, nSpecialCuts, best solution.
|-
|>2||Output a line every iteration with the following information:
{|class="wikitable"
!label||description
|-
|It ||Iterations
|-
|nECP ||Number of extended cutting planes (ECP)
|-
|nAlpha>=lim||Number of ECP with criteria fulfilled
|-
|nL ||Number of linearizations
|-
|nSECP ||Number of special case ECP (created from constraint on bound)
|-
|fIPMin ||Objective of best solution at current iteration
|}
|-
|>3||Output a description of each step in the MINLP algorithm
|-
|>4||Output additional numerical information in some algorithm steps
|-
|>5||Output information in substeps (preprocessing, line search)
|}
|-valign="top"
|''PriLevOpt''||Print level in sub-solvers, see the documentation for the solver
|-valign="top"
|''SolverMIP''||Name of the solver used for MIP subproblems. If empty, the default solver is found calling GetSolver('mip',1). If TOMLAB /CPLEX is installed, CPLEX is the default solver. Recommended TOMLAB solver to use as subsolvers are milpSolve, CPLEX and mipSolve. Which solver performs the best varies depending on the MINLP problem.
|-
|''SolverLP''||Name of the solver used for LP subproblems when SolverMIP == mipSolve
|-
|''MIP''||Structure with parameters specific to mixed integer optimization. See the table below describing the fields used in the MIP structure.
|-
|''ECPMINLP''||Structure with parameters specific to the ecpMINLP solver. See the table below describing the fields used in the ECPMINLP structure.
|-
|''optParam''||Structure with general optimization parameters. See the table below describing the fields used in the optParam structure.
|}

===MIP structure===
Substructure in Prob with parameters related to mixed integer programming.

{|class="wikitable"
!colspan="2"|'''fields used in Prob.MIP''':
|-
|'''Field'''||'''Description'''
|-valign="top"
|''IntVars''||If empty, all variables are assumed non-integer. If islogical(IntVars) (=all elements are 0/1), then 1 = integer variable, 0 = continuous variable. If any element ''>''1, IntVars is the indices for integer variables.
|-valign="top"
|''fIP''||An upper bound on the IP value wanted. Makes it possible to cut branches and avoid node computations. Used even if xIP not given.
|-valign="top"
|''xIP''||The x-values giving the fIP value, if a solution (xIP,fIP) is known.
|-valign="top"
|''DualGap''||ecpMINLP stops if the duality gap is less than DualGap
DualGap = 1, stop at first integer solution, e.g. DualGap = 0.01,stop if solution < 1% from optimal solution.
 The lower bound Prob.f_Low is used, (default -1.0e300), which can also be set by the user. If f_Low has not been changed from default the lower bound is obtained from the initial solution of a relaxed problem, but only when ECPMINLP.INIT_BND is 1 or 2 (default).
 Default DualGap is -1, not used.
|-valign="top"
|''PPP''||Pre-processing and probing, default is 0. 
0 Not used. Default. 
1 Apply initially on MINLP problem. 
2 Apply each iteration before solving MILP subproblem.
|-
|''ROUNDH''||If nonzero, a rounding heuristics will be used on the initial NLP solution in order to obtain an initial integer solution. Requires ECPMINLP.INIT_BND enabled. Default is 1, enabled.
|}

===ECPMINLP structure===
Substructure in ''Prob'' with solver-specific options.

{|class="wikitable"
!colspan="2"|fields used in Prob.ECPMINLP
|-
|'''Field'''||'''Description'''
|-valign="top"
|''beta''||Multiplier when increasing alpha after an infeasible MILP solution.
 Alpha is a parameter individually adjusting each cutting plane, starting at 1.0 and increasing until meeting a certain criterion. Default value for beta is 1.3.
|-valign="top"
|''gamma''||Multiplier when increasing alpha when MILP solution does not violate any nonlinear contraints, but still does not decrease the upper bound of the objective.
 Alpha is a parameter individually adjusting each cutting plane, starting at 1.0 and increasing until meeting a certain criterion. Default value for gamma is 2.0.
|-valign="top"
|''PREALLOC''||Flag enabling preallocation of memory for cutting planes and linearizations.
 0 No preallocation, dynamic growth of arrays. Current default.
 1 Preallocate arrays.
|-valign="top"
|''INIT_BND''||Selects method for setting lower bound when f_Low not changed from default.
{|class="wikitable"
!value||method
|-valign="top"
|0 ||No extra initial lower bound.
|-valign="top"
|1 ||Use default TOMLAB NLP solver on problem with relaxed integer constraints. Add a linearization if a feasible MINLP solution was found.
|-valign="top"
|2 ||Add an initial linearization as long as a feasdbile NLP solution was found. The linearization is a simple lower bound on the MILP objective. Default.
|-valign="top"
|3 ||Same as 2, but also use the gradient in the linearization. This might improve the solution process for some problems where no solution can be found otherwise. But for many problems, using this initial linearization cuts off a feasbiel region and slows down or even hinders the solver completely. Recommended to only use as a last resort.
|}
|-valign="top"
|''SETTOL''||Flag enabling changing tolerances, described below under optParam.eps_x, optParam.eps_x and optParam.eps_f.
 0 Default. Using the recommended solver default values, 1.0e-3.
 1 Tolerances can be changed, taken from Prob.optParam.
|-valign="top"
|''INTSOLLIM_INCR''||Integer option when using CPLEX as MIP subsolver.
 Define how much the CPLEX parameter INTSOLLIM increases when a feasible solution is not optimal and all alpha values have met their criteria.
 If set to zero, optimal strategy will be used immediately instead, without any gradual increase of INTSOLLIM.
 Default is 1.
|-valign="top"
|''USECUTPOOL''||Set nonzero to use a pool for the alpha-regulated extended cutting planes.
 Cuts not active in the MILP-solution for CUTDELBND iterations in a row will be inactivated (removed from the MILP-problem) until they are violated in a new solution.
 Default is 0, not used.
|-valign="top"
|''CUTDELBND''||The number of consecutive times an extended cutting plane can be inactive before it gets removed and put into the inactive pool, if the option USECUTPOOL is set nonzero.
 Default is 15 times.
|-valign="top"
|''MAXITNOIMP''||Limit on the number of successive iterations allowed without any improvements at all to neither objective nor solution point before the solver terminates
 Default is 2.
|-valign="top"
|''USENLP''||Set nonzero to use an NLP sub-solver on the original problem with the integer variables fixed at values from the latest MILP solution. Default is 1, enabled.
|-valign="top"
|''USERESELECT''||Set nonzero to enable cut reselection heuristics. Default is 1, enabled.
|-valign="top"
|''SCALECUTS''||Set nonzero to scale cuts before they are added to the MILP problem. Scaling is done by dividing the cut with its norm. Default is 1, enabled.
|}

===optParam Structure===
Substructure in ''Prob'' with general optimization parameters.

{|class="wikitable"
!colspan="2"|fields used in Prob.optParam
|-
|'''Field'''||'''Value'''
|-valign="top"
|''MaxIter''||Maximal number of iterations, default 10000
|-valign="top"
|''IterPrint''||Print short information each iteration. Setting PriLev > 1 also enables IterPrint, setting it to 1.
|-valign="top"
|''eps_x''||Linear constraint violation convergence tolerance. Default is 2.0e-6
|-valign="top"
|''eps_g''||Constraint violation convergence tolerance. Default is 1.0e-7
|-valign="top"
|''eps_f''||Optimality tolerance. Default is 1.0e-8
|}

''NOTE:'' For the solver to use these tolerances, the flag ''ECPMINLP.SETTOL'' must be set to nonzero.

==Outputs==

{| class="wikitable"
!''Result''||colspan="2"|Structure with result from optimization. The following fields are changed:
|-
|||''Iter ''||Number of iterations.
|-valign="top"
|||''ExitFlag ''||Exit flag.
 0: Solution found, or integer solution with duality gap less than user tolerance.
 1: Maximal number of iterations reached.
 2: Empty feasible set, no integer solution found.
 3: Problem in subsolver, see Inform value.
 99: Maximal CPU Time used (cputime > Prob.maxCPU
|-
|||''Inform''||Inform for ExitFlag != 3
 0: Global solution found.
 1: Local solution found.
 2: No solution found.
 >2: Inform value from subsolver.
|-
|||''ExitText''||Text string giving ''ExitFlag'' and ''Inform'' information.
|-valign="top"
|||''DualGap''||Relative duality gap, max(0,fIPMin-fLB)/-fIPMin-, if fIPMin =0; max(0,fIPMin-fLB) if fIPMin == 0. If fIPMin =0: Scale with 100, 100*Dual- Gap, to get the percentage duality gap. For absolute value duality gap: scale with fIPMin, fIPMin * DualGap
|-
|||''x_k''||Solution.
|-valign="top"
|||''f_k''||Function value at optimum.
|-
|||''g_k''||Gradient vector at optimum.
|-
|||''c_k''||Constraint values at optimum.
|-
|||''cJac''||Constraint derivative values at optimum.
|-
|||''xState''||State of each variable, described in [[TOMLAB_Appendix_B#Table:_The_state_variable_xState_for_the_variable.|TOMLAB Appendix B]].
|-
|||''bState''||State of each constraint, described in [[TOMLAB_Appendix_B#Table:_The_state_variable_bState_for_each_linear_constraint.|TOMLAB Appendix B]].
|-
|||''cState''||State of each general constraint, described in [[TOMLAB_Appendix_B#Table:_The_state_variable_cState_for_each_nonlinear_constraint.|TOMLAB Appendix B]].
|-
|||''x_0''||Starting point x_0.
|-
|||''Solver''||Solver used ('ecpMINLP').
|-
|||''SolverAlgorithm''||Description of method used.
|-
|||''Prob''||Problem structure used.
|}

== Algorithm==
ecpMINLP Solves convex or pseudo-convex mixed-integer nonlinear programming problems using an extended cutting plane algorithm with cuts regulated by a parameter-vector alpha. Cuts and linearizations are added to MIP subproblem which is then solved by a subsolver in each iteration.

The solver algorithm is mainly based on the paper 'Solving Pseudo-Convex Mixed Integer Optimization Problems by Cutting Plane Techniques' by Tapio Westerlund and Ray Pörn, published in Optimization and Engineering 3, 253-280, 2002, with some modifications.

Most prominent features in addition to the ones described in the main reference above are
* Solving the relaxed NLP problem initially to obtain a lower bound on the solution.
* A rounding heuristics performed on the initial NLP solution in order to obtain an initial upper bound on the initial solutions.
* Optional use of a cutpool for the alpha-regulated extended cutting planes.

[[Category:MIPNLP]]

MIPNLP ecpMINLP

2014-07-14T09:58:34Z

Bjorn: Created page with "==Purpose== ecpMINLP solves convex mixed-integer nonlinear programming problems (MINLP). ''ecpMINLP ''solves problems of the form <math> \begin{array}{cccccc} \min\limits_{x} ..."

==Purpose==

ecpMINLP solves convex mixed-integer nonlinear programming problems (MINLP).

''ecpMINLP ''solves problems of the form

<math>
\begin{array}{cccccc}
\min\limits_{x} & f(x) \\s/t & x_{L} & \leq & x & \leq & x_{U} \\& b_{L} & \leq & Ax & \leq & b_{U} \\& c_{L} & \leq & c(x) & \leq & c_{U} \\& & & {x_{j} \in \mathbb{N} \ \ \forall j \in I} \\
\end{array}
</math>

where <math>x,x_{L},x_{U}\in \mathbb{R}^{n}</math> , <math>c(x),c_{L},c_{U}\in
\mathbb{R}^{m_{1}}</math> , <math>A\in \mathbb{R}^{m_{2}\times n}</math> and
<math>b_{L},b_{U}\in \mathbb{R}^{m_{2}}</math>. The variables <math>x \in I</math> , the
index subset of <math>1,...,n</math> are restricted to be integers.

==Calling Syntax==

Driver call, including printing with level 2:
<source lang="matlab">
Result = tomRun('ecpMINLP',Prob,2);
</source>
Direct solver call:
<source lang="matlab">
Result = ecpMINLP(Prob);
PrintResult(Result);
Result = tomRun('ecpMINLP',Prob,...)
</source>

=== Warm Start ===
Warm start is currently not supported, but might be included in a future release.

==Inputs==

===Prob structure===
The '''TOMLAB''' problem structure

{|class="wikitable"
!colspan="2"|The following fields are used in the problem description structure Prob
|-
|'''Field'''||'''Description'''
|-
|''x_L''||Lower bounds on x.
|-
|''x_U''||Upper bounds on x.
|-
|''A''||The linear constraint matrix.
|-
|''b_L''||Lower bounds on linear constraints.
|-
|''b_U''||Upper bounds on linear constraints.
|-
|''c_L''||Lower bounds on nonlinear constraints.
|-
|''c_U''||Upper bounds on nonlinear constraints.
|-
|''f_Low''||Lower bound on solution.
|-
|''x_0''||Starting point.
|-valign="top"
|''MaxCPU''||Maximal CPU Time (in seconds) to be used by ecpMINLP, stops with best point found
|-valign="top"
|''PriLev''||Print level in ecpMINLP (default 1). Also see optParam.IterPrint
{|class="wikitable"
!value||output
|-
|=0||Silent.
|-
|>0||Initial information and convergence results.
|-
|>1||Output a line whenever the solution has improved, containing:
nIterations, nCuts, nCuts with criteria fulfilled, nLinearizations, nSpecialCuts, best solution.
|-
|>2||Output a line every iteration with the following information:
{|class="wikitable"
!label||description
|-
|It ||Iterations
|-
|nECP ||Number of extended cutting planes (ECP)
|-
|nAlpha>=lim||Number of ECP with criteria fulfilled
|-
|nL ||Number of linearizations
|-
|nSECP ||Number of special case ECP (created from constraint on bound)
|-
|fIPMin ||Objective of best solution at current iteration
|}
|-
|>3||Output a description of each step in the MINLP algorithm
|-
|>4||Output additional numerical information in some algorithm steps
|-
|>5||Output information in substeps (preprocessing, line search)
|}
|-valign="top"
|''PriLevOpt''||Print level in sub-solvers, see the documentation for the solver
|-valign="top"
|''SolverMIP''||Name of the solver used for MIP subproblems. If empty, the default solver is found calling GetSolver('mip',1). If TOMLAB /CPLEX is installed, CPLEX is the default solver. Recommended TOMLAB solver to use as subsolvers are milpSolve, CPLEX and mipSolve. Which solver performs the best varies depending on the MINLP problem.
|-
|''SolverLP''||Name of the solver used for LP subproblems when SolverMIP == mipSolve
|-
|''MIP''||Structure with parameters specific to mixed integer optimization. See the table below describing the fields used in the MIP structure.
|-
|''ECPMINLP''||Structure with parameters specific to the ecpMINLP solver. See the table below describing the fields used in the ECPMINLP structure.
|-
|''optParam''||Structure with general optimization parameters. See the table below describing the fields used in the optParam structure.
|}

===MIP structure===
Substructure in Prob with parameters related to mixed integer programming.

{|class="wikitable"
!colspan="2"|'''fields used in Prob.MIP''':
|-
|'''Field'''||'''Description'''
|-valign="top"
|''IntVars''||If empty, all variables are assumed non-integer. If islogical(IntVars) (=all elements are 0/1), then 1 = integer variable, 0 = continuous variable. If any element ''>''1, IntVars is the indices for integer variables.
|-valign="top"
|''fIP''||An upper bound on the IP value wanted. Makes it possible to cut branches and avoid node computations. Used even if xIP not given.
|-valign="top"
|''xIP''||The x-values giving the fIP value, if a solution (xIP,fIP) is known.
|-valign="top"
|''DualGap''||ecpMINLP stops if the duality gap is less than DualGap
DualGap = 1, stop at first integer solution, e.g. DualGap = 0.01,stop if solution < 1% from optimal solution.
 The lower bound Prob.f_Low is used, (default -1.0e300), which can also be set by the user. If f_Low has not been changed from default the lower bound is obtained from the initial solution of a relaxed problem, but only when ECPMINLP.INIT_BND is 1 or 2 (default).
 Default DualGap is -1, not used.
|-valign="top"
|''PPP''||Pre-processing and probing, default is 0. 
0 Not used. Default. 
1 Apply initially on MINLP problem. 
2 Apply each iteration before solving MILP subproblem.
|-
|''ROUNDH''||If nonzero, a rounding heuristics will be used on the initial NLP solution in order to obtain an initial integer solution. Requires ECPMINLP.INIT_BND enabled. Default is 1, enabled.
|}

===ECPMINLP structure===
Substructure in ''Prob'' with solver-specific options.

{|class="wikitable"
!colspan="2"|fields used in Prob.ECPMINLP
|-
|'''Field'''||'''Description'''
|-valign="top"
|''beta''||Multiplier when increasing alpha after an infeasible MILP solution.
 Alpha is a parameter individually adjusting each cutting plane, starting at 1.0 and increasing until meeting a certain criterion. Default value for beta is 1.3.
|-valign="top"
|''gamma''||Multiplier when increasing alpha when MILP solution does not violate any nonlinear contraints, but still does not decrease the upper bound of the objective.
 Alpha is a parameter individually adjusting each cutting plane, starting at 1.0 and increasing until meeting a certain criterion. Default value for gamma is 2.0.
|-valign="top"
|''PREALLOC''||Flag enabling preallocation of memory for cutting planes and linearizations.
 0 No preallocation, dynamic growth of arrays. Current default.
 1 Preallocate arrays.
|-valign="top"
|''INIT_BND''||Selects method for setting lower bound when f_Low not changed from default.
{|class="wikitable"
!value||method
|-valign="top"
|0 ||No extra initial lower bound.
|-valign="top"
|1 ||Use default TOMLAB NLP solver on problem with relaxed integer constraints. Add a linearization if a feasible MINLP solution was found.
|-valign="top"
|2 ||Add an initial linearization as long as a feasdbile NLP solution was found. The linearization is a simple lower bound on the MILP objective. Default.
|-valign="top"
|3 ||Same as 2, but also use the gradient in the linearization. This might improve the solution process for some problems where no solution can be found otherwise. But for many problems, using this initial linearization cuts off a feasbiel region and slows down or even hinders the solver completely. Recommended to only use as a last resort.
|}
|-valign="top"
|''SETTOL''||Flag enabling changing tolerances, described below under optParam.eps_x, optParam.eps_x and optParam.eps_f.
 0 Default. Using the recommended solver default values, 1.0e-3.
 1 Tolerances can be changed, taken from Prob.optParam.
|-valign="top"
|''INTSOLLIM_INCR''||Integer option when using CPLEX as MIP subsolver.
 Define how much the CPLEX parameter INTSOLLIM increases when a feasible solution is not optimal and all alpha values have met their criteria.
 If set to zero, optimal strategy will be used immediately instead, without any gradual increase of INTSOLLIM.
 Default is 1.
|-valign="top"
|''USECUTPOOL''||Set nonzero to use a pool for the alpha-regulated extended cutting planes.
 Cuts not active in the MILP-solution for CUTDELBND iterations in a row will be inactivated (removed from the MILP-problem) until they are violated in a new solution.
 Default is 0, not used.
|-valign="top"
|''CUTDELBND''||The number of consecutive times an extended cutting plane can be inactive before it gets removed and put into the inactive pool, if the option USECUTPOOL is set nonzero.
 Default is 15 times.
|-valign="top"
|''MAXITNOIMP''||Limit on the number of successive iterations allowed without any improvements at all to neither objective nor solution point before the solver terminates
 Default is 2.
|-valign="top"
|''USENLP''||Set nonzero to use an NLP sub-solver on the original problem with the integer variables fixed at values from the latest MILP solution. Default is 1, enabled.
|-valign="top"
|''USERESELECT''||Set nonzero to enable cut reselection heuristics. Default is 1, enabled.
|-valign="top"
|''SCALECUTS''||Set nonzero to scale cuts before they are added to the MILP problem. Scaling is done by dividing the cut with its norm. Default is 1, enabled.
|}

===optParam Structure===
Substructure in ''Prob'' with general optimization parameters.

{|class="wikitable"
!colspan="2"|fields used in Prob.optParam
|-
|'''Field'''||'''Value'''
|-valign="top"
|''MaxIter''||Maximal number of iterations, default 10000
|-valign="top"
|''IterPrint''||Print short information each iteration. Setting PriLev > 1 also enables IterPrint, setting it to 1.
|-valign="top"
|''eps_x''||Linear constraint violation convergence tolerance. Default is 2.0e-6
|-valign="top"
|''eps_g''||Constraint violation convergence tolerance. Default is 1.0e-7
|-valign="top"
|''eps_f''||Optimality tolerance. Default is 1.0e-8
|}

''NOTE:'' For the solver to use these tolerances, the flag ''ECPMINLP.SETTOL'' must be set to nonzero.

==Outputs==

{| class="wikitable"
!''Result''||colspan="2"|Structure with result from optimization. The following fields are changed:
|-
|||''Iter ''||Number of iterations.
|-valign="top"
|||''ExitFlag ''||Exit flag.
 0: Solution found, or integer solution with duality gap less than user tolerance.
 1: Maximal number of iterations reached.
 2: Empty feasible set, no integer solution found.
 3: Problem in subsolver, see Inform value.
 99: Maximal CPU Time used (cputime > Prob.maxCPU
|-
|||''Inform''||Inform for ExitFlag != 3
 0: Global solution found.
 1: Local solution found.
 2: No solution found.
 >2: Inform value from subsolver.
|-
|||''ExitText''||Text string giving ''ExitFlag'' and ''Inform'' information.
|-valign="top"
|||''DualGap''||Relative duality gap, max(0,fIPMin-fLB)/-fIPMin-, if fIPMin =0; max(0,fIPMin-fLB) if fIPMin == 0. If fIPMin =0: Scale with 100, 100*Dual- Gap, to get the percentage duality gap. For absolute value duality gap: scale with fIPMin, fIPMin * DualGap
|-
|||''x_k''||Solution.
|-valign="top"
|||''f_k''||Function value at optimum.
|-
|||''g_k''||Gradient vector at optimum.
|-
|||''c_k''||Constraint values at optimum.
|-
|||''cJac''||Constraint derivative values at optimum.
|-
|||''xState''||State of each variable, described in [[TOMLAB_Appendix_B#Table:_The_state_variable_xState_for_the_variable.|TOMLAB Appendix B]].
|-
|||''bState''||State of each constraint, described in [[TOMLAB_Appendix_B#Table:_The_state_variable_bState_for_each_linear_constraint.|TOMLAB Appendix B]].
|-
|||''cState''||State of each general constraint, described in [[TOMLAB_Appendix_B#Table:_The_state_variable_cState_for_each_nonlinear_constraint.|TOMLAB Appendix B]].
|-
|||''x_0''||Starting point x_0.
|-
|||''Solver''||Solver used ('ecpMINLP').
|-
|||''SolverAlgorithm''||Description of method used.
|-
|||''Prob''||Problem structure used.
|}

== Algorithm==
ecpMINLP Solves convex or pseudo-convex mixed-integer nonlinear programming problems using an extended cutting plane algorithm with cuts regulated by a parameter-vector alpha. Cuts and linearizations are added to MIP subproblem which is then solved by a subsolver in each iteration.

The solver algorithm is mainly based on the paper 'Solving Pseudo-Convex Mixed Integer Optimization Problems by Cutting Plane Techniques' by Tapio Westerlund and Ray Pörn, published in Optimization and Engineering 3, 253-280, 2002, with some modifications.

Most prominent features in addition to the ones described in the main reference above are
* Solving the relaxed NLP problem initially to obtain a lower bound on the solution.
* A rounding heuristics performed on the initial NLP solution in order to obtain an initial upper bound on the initial solutions.
* Optional use of a cutpool for the alpha-regulated extended cutting planes.