XA - Introduction: Difference between revisions

From TomWiki
Jump to navigationJump to search
mNo edit summary
(move "matlab interface" to its own page)
 
(5 intermediate revisions by the same user not shown)
Line 1: Line 1:
= Introduction =
Welcome to the <span class="roman">TOMLAB /XA</span> User's Guide. <span class="roman">TOMLAB /XA</span> includes the XA solver suite from Sunset Software Technology and an interface to The MathWorks' MATLAB.


== Overview ==
<span class="roman">TOMLAB /XA</span> is a solver package providing the user with functionality for solving linear, binary, integer and semi-continuous linear programming problems, as well as quadratic programming problems.


Welcome to the TOMLAB /XA User&rsquo;s Guide. TOMLAB /XA includes the XA solver suite from Sunset Software Technology and an interface to The MathWorks&rsquo; MATLAB.
===Contents of this Manual===


TOMLAB /XA is a solver package providing the user with functionality for solving linear, binary, integer and semi-continuous linear programming problems, as well as quadratic programming problems.
* Section [#intro 1] provides a basic overview of the <span class="roman">TOMLAB /XA</span> solver package.
* Section provides an overview of the Matlab interface to XA.
* Section describes how to set XA solver options from Matlab.
* Section gives detailed information about the interface routines ''xa'' and ''xaTL''. The solver control options, branch and bound settings, as well as solver and model status codes are also explained in this section.  


== Contents of this Manual ==
===More information===
 
* Section intro provides a basic overview of the TOMLAB /XA solver package.
* Section Using provides an overview of the Matlab interface to XA.
* Section options describes how to set XA solver options from Matlab.
* Section xaroutines gives detailed information about the interface routines {xa} and {xaTL}. The solver control options, branch and bound settings, as well as solver and model status codes are also explained in this section.
 
== More information ==


Please visit the following links for more information:
Please visit the following links for more information:


* http://tomopt.com/tomlab/products/xa/
* [http://tomopt.com/tomlab/products/xa/ <tt>http://tomopt.com/tomlab/products/xa/</tt>]
* http://www.sunsetsoft.com
* [http://www.sunsetsoft.com <tt>http://www.sunsetsoft.com</tt>]
 
== Prerequisites ==
 
In this manual we assume that the user is familiar with linear, mixed-integer and quadratic programming, setting up problems in TOMLAB (in particular mixed-integer ({mip}) problems) and the TOMLAB language in general.
 
= Using the Matlab Interface =
 
The XA solver is accessed via the {tomRun} driver routine, which calls the {xaTL} interface routine. The solver itself is located in the library file {Xav14}. It is also possible to make a direct call the {xaTL} using the TOMLAB format, as well as a direct call to the solver interface by calling {xa}.
 
It is recommended that the TOMLAB format is used for maximum flexibility.
 
The interface routines:
{| class="wikitable"
! Function
! Description
|-
| xa
| The interface routine calls the XA library.
|-
| xaTL
| The interface routine called by the TOMLAB driver routine tomRun or by a direct call. This routine then calls the interface routine xa, which calls the library file Xav14.
|}
 
= Setting XA Options =
 
All XA control parameters are possible to set from.
 
== Setting options using the xaControl structure ==
 
The parameters can be set as subfields in the {Prob.MIP.xaControl}structure. The following example shows how to set a limit on the maximum number of iterations.
 
<pre>Prob = mipAssign(...)    % Setup problem, see help mipAssign for more information
 
Prob.MIP.xaControl.ITERATION = 20000; % Setting maximum number of iterations</pre>
The maximum number of iterations can also be done through the  parameter {MaxIter}:
 
<pre>Prob.optParam.MaxIter = 20000;</pre>
In the cases where a solver specific parameter has a corresponding  general parameter, the latter is used only if the user has not given the solver specific parameter.
 
A complete description of the available XA parameters can be found in Section xaoptions.
 
== IIS ==
 
Irreducible Infeasible Sets (IIS) can be found with TOMLAB /XA. There are two options available to the user. The first one delivers the infeasible rows from the last simplex tableau. The second one will try to find a minimal number of constraints that need to be removed or corrected to make the model feasible. There may be more sets that the one delivered. The inputs and outputs are explained in Section xaTL.
 
= TOMLAB /XA Solver Reference =
 
A detailed description of the TOMLAB /XA solver interface is given below. Also see the M-file help for {xaTL}. It is strongly recommended that the user use the TOMLAB format when using XA. Please go to Section xaTL for information about using XA with TOMLAB.
 
== (xa){xa} ==
 
<blockquote>The XA linear, mixed-integer linear and quadratic programming (LP, MILP, QP) interface solves problems of the form <math>\begin{array}{cccccc}
\min\limits_{x} & \multicolumn{5}{l}{f(x) = \frac{1}{2}x^T F x + c^T x}  \\
s/t & x_{L} & \leq  & x    & \leq  & x_{U} \\
    & b_{L} & \leq  & Ax  & \leq  & b_{U} \\
    &      &      & x_i \mathrm{\ \ integer} &  & i \in I \\
\end{array}
</math> where <math>c, x, x_{L}, x_{U}\in \MATHSET{R}^{n}</math>, <math>F\in
\MATHSET{R}^{n\times n}</math>, <math>A\in \MATHSET{R}^{m\times n}</math> and <math>b_{L},b_{U}\in \MATHSET{R}^{m}</math>. The variables <math>x \in I</math>, the index subset of <math>1,...,n</math>, are restricted to be integers. All variables are considered continuous if <math>F</math> is given.
 
If <math>F</math> is empty, an LP or MILP problem is solved.
</blockquote>
<blockquote><br />
<math>[</math>x_k, f_k, Inform, modsts, solsts, act, dact, status<math>]</math> = xa(c, A, x_L, x_U, b_L, b_U, xaControl, callback, PriLev, LogFile, SaveFile, Prob, IntVars, VarWeight, SC, SC2, F) <br />
 
</blockquote>
{Description of Inputs}
 
<blockquote>{2}{l}{The following inputs are used:}<br />
<br />
 
 
 
{2}{l}{The following inputs are used:, continued}<br />
<br />
 
 
 
 
 
 
 
 
{c}&amp; Linear objective function cost coefficients, vector <math>n \times 1</math>. <br />
<br />
{A}&amp; Linear constraint matrix for linear constraints, dense or sparse matrix <math>m \times n</math>. <br />
<br />
{x\_L}&amp; Lower bounds on design parameters <math>x</math>. If empty assumed to be zero. <br />
{x\_U}&amp; Upper bounds on design parameters <math>x</math>. <br />
<br />
{b\_L}&amp; Lower bounds on the linear constraints. <br />
<br />
{2}{l}{{\bf The following parameters are optional:}}<br />
<br />
{b\_U}&amp; Upper bounds on the linear constraints. If empty, then {b\_U}={b\_L}is assumed, i.e. equality constraints. <br />
<br />
{xaControl}&amp; Structure, where the fields are set to the XA control parameters that the user wants to specify values for. The control parameters are listed in Section xaoptions <br />
<br />
{callback}&amp; 0/1 vector of length 10. Defines the active callbacks during the solving process.<br />
<br />
&amp; The callback routines and their corresponding indices in the callback vector are:<br />
<br />
&amp; 1 - xacb_begin.m - before solving<br />
&amp; 2 - xacb_infeas.m - infeasible iteration<br />
&amp; 3 - xacb_feas.m - feasible iteration<br />
&amp; 4 - xacb_node.m - integer node generated<br />
&amp; 5 - xacb_intsol.m - integer solution found<br />
&amp; 6 - xacb_branch.m - user selects b &amp; b variable<br />
&amp; 7 - xacb_barrier.m - barrier iteration<br />
&amp; 8 - xacb_resolve.m - problem solve <math>-></math> fast modify resolve<br />
&amp; 9 - currently not used<br />
&amp; 10 - xacb_end.m - after solving<br />
<br />
&amp; The user can either modify the existing xacb_*.m functions (use i.e. &quot;which xacb_feas&quot;) to find them, OR copies can be made and placed before the original files in the MATLAB path.<br />
<br />
&amp; The calling syntax for all XA callbacks is:<br />
<br />
&amp;     function xacb_(*)( xacbInfo, Prob )<br />
<br />
&amp; and is described in more detail in xacb.m (help xacb.m)<br />
<br />
{PriLev}&amp; Printing level in the {xa}<math>m</math>-file and the XA C-interface. <br />
&amp; = 0 Silent <br />
&amp; = 1 Warnings and Errors <br />
&amp; = 2 Summary information <br />
&amp; = 3 More detailed information <br />
&amp; <br />
&amp; <math>></math> 10 Pause statements, and maximal printing (debug mode)<br />
<br />
{LogFile}&amp; Name of file to write XA log to. If empty, no log is written. <br />
<br />
{SaveFile}&amp; Name of file to write MPS representation of the problem to. The name should be given without extension - .mps is added automatically. If empty, the problem is not saved. <br />
<br />
{Prob}&amp; A structure. If TOMLAB calls XA, then Prob is the standard TOMLAB problem structure, otherwise the user optionally may set: Prob.P = ProblemNumber, where ProblemNumber is some integer. <br />
<br />
&amp; If any callback is defined (see description of callback) then problem arrays are set as fields in Prob, and the Prob structure is always passed to the callback routines as the last parameter. The defined fields are Prob.QP.c, Prob.QP.F, Prob.x_L, Prob.x_U, Prob.A, Prob.b_L, Prob.b_U. (if input is [], then Prob.P=1 is set).<br />
<br />
{IntVars}&amp; Defines which variables are integers, of general type I or binary B Variable indices should be in the range [1,...,n]. IntVars is a logical vector <math>==></math> x(find(IntVars <math>></math> 0)) are integers. IntVars is a vector of indices <math>==></math> x(IntVars) are integers (if [], then no integers of type I or B are defined). XA checks which variables has x_L = 0 and x_U = 1, i.e. binary.<br />
<br />
{VarWeight}&amp; Vector of branching priorities for MILP problems. Should be a n-vector, ideally of integers <math>>=1</math>. A lower value means higher priority in the variable selection phase. <br />
<br />
{SC}&amp; A vector with indices for the Type 1 Semi-Continuous variables, i.e. that takes either the value 0 or a value in the range [ x_L(i) , x_U(i) ]. <br />
<br />
{SC2}&amp; A vector with indices for the Type 2 Semi-Continuous variables, i.e. that takes either the value of the corresponding upper bound, or a value in the range [ x_L(i) , 0 ]. <br />
<br />
{F}&amp; Square dense or sparse matrix. Empty if non-quadratic problem. <br />
<br />
{iisRequest}&amp; A flag telling whether to obtain an IIS when a problem is determined infeasible. The flag can be set to one of the following values: <br />
<br />
&amp; 0 - Do not search for an IIS (default).<br />
&amp; 1 - Implementation of irreducible inconsistent systems (IIS) of constraints. Algorithm: IIS.<br />
&amp; 2 - Method of locationing a minimal number of constraints such that if all are removed the model is feasible. Algorithm: Block.<br />
<br />
&amp; The IIS is returned through the output parameter: iis. Information about the IIS is automatically written to the LogFile if a LogFile is defined.<br />
<br />
 
 
</blockquote>
{Description of Outputs}
 
<blockquote>{2}{l}{The following fields are used:}<br />
<br />
 
 
 
{2}{l}{The following fields are used:, continued}<br />
<br />
 
 
 
 
 
 
 
{x\_k}&amp; Solution vector with decision variable values (n x 1 vector).<br />
<br />
{f\_k}&amp; Objective function value at optimum.<br />
<br />
{Inform}&amp; Result of XA run.<br />
<br />
&amp; 2 = Init Successful.<br />
&amp; 4 = Load Successful.<br />
&amp; 6 = Solve Successful.<br />
&amp; 8 = Undo Successful.<br />
&amp; 10 = Done Successful.<br />
&amp; 101 = Allocation amount must be greater than or equal to 0.<br />
&amp; 102 = Allocation amount must be greater than or equal to 0.<br />
&amp; 103 = Memory allocation error, no memory available.<br />
&amp; 104 = Memory allocation error, requested memory not available.<br />
&amp; 110-118 = XA called out of sequence.<br />
&amp; 122 = BXA.DLL not in path. <br />
&amp; 124 = Wrong version of BXA.DLL or your version has been damaged.<br />
&amp; 126 = Wrong routine called after XADONE.<br />
&amp; 128 = Restart OS.<br />
&amp; 132, 134, 136 = Size is incorrect.<br />
&amp; 204 = Incorrect No or Yes variable.<br />
&amp; 205 = Incorrect command line parameter.<br />
&amp; 207 = Unreasonable command line parameter value.<br />
&amp; 208 = Incorrect value set.<br />
&amp; 209 = Incorrect value set.<br />
&amp; 210 = Incorrect value set.<br />
&amp; 211 = Unable to process output.<br />
&amp; 214 = Incorrect value set.<br />
&amp; 300 = Column number out of range.<br />
&amp; 301 = Too many or zero rows in problem.<br />
&amp; 302 = Too many or zero columns in problem.<br />
&amp; 303 = Free memory error, XA could not release it&rsquo;s memory. Probably XA data storage area has been clobbered.<br />
&amp; 304 = Column lower bound <math>></math> upper bound.<br />
&amp; 305 = Row lower bound <math>></math> upper bound.<br />
&amp; 306 = Problem too large for available memory.<br />
&amp; 307 = Too many nonzeros.<br />
&amp; 308 = Row number out of range.<br />
&amp; 309 = Duplicate column and/or row.<br />
&amp; 310 = Arrays overlap.<br />
&amp; 312 = Bad colptr values.<br />
&amp; 314 = Unreasonable rownos values.<br />
&amp; 316 = Duplicate rownos value for the same column.<br />
&amp; 318 = Unreasonable technology coefficient in a array.<br />
&amp; 320 = Unreasonable value in status array.<br />
&amp; 322 = Unreasonable value in priority array.<br />
&amp; 324 = Unreasonable value in increment array.<br />
&amp; 326 = Semi-continuous type 1 or type 2 column missing lower bound.<br />
&amp; 328 = Column can not have both semi-continuous type 1 and type 2 at the same time.<br />
&amp; 330 = Unrecognized line in MPS file.<br />
&amp; 400 = MPS formatted file is missing NAME line. The NAME must start in column 1 and be the first line in the file.<br />
&amp; 402 = Incomplete MPS file. File probably truncated.<br />
&amp; 404 = Row relationship error.<br />
&amp; 406 = Expecting a number.<br />
&amp; 408 = Bound relationship error.<br />
&amp; 410 = Split Column declaration. All rows a column intersects must be grouped together. <br />
&amp; 412 = In Column section, a column has duplicate row entries. <br />
&amp; 420 = Column has a Power sequence with a negative lower bound.<br />
&amp; 600 = Misspelled or missing DBF table filename. <br />
&amp; 602 = Error reading DBF table.<br />
&amp; 604 = Special row and column name appear together.<br />
&amp; 606 = Row increment setting; increment settings only apply to integer columns.<br />
&amp; 608 = Row priority setting, priority settings only apply to integer columns.<br />
&amp; 610 = Row field name not found in DBF table.<br />
&amp; 612 = Column field name not found in DBF table.<br />
&amp; 614 = Coefficient field name not found in DBF table.<br />
&amp; 616 = No data available in DBF table.<br />
&amp; 700 = No data previously loaded for solving.<br />
&amp; 702 = Row name size not equal to previously loaded name size.<br />
&amp; 704 = Column name size not equal to previously loaded size.<br />
&amp; 706 = Specified name size does not match row or column name size.<br />
&amp; 900 = Unknown error.<br />
&amp; 901 = Incorrect call.<br />
&amp; 930 = XA is solving an integer programming problem. A node is generated splitting the feasible region of each integer variables. The default maximum number of nodes is sqrt( number of Integers variables ) + number of 0/1 and semi-continuous columns + 4000 This default settings is too small. Set MAXNODES # to increase.<br />
&amp; 998 = Internal system administration error.<br />
&amp; 999 = Code has XA&rsquo;s internal memory.<br />
&amp; 20001 = Ranging a free/null row with MPS file.<br />
&amp; 20030 = Row name referenced in COLUMNS section is undefined.<br />
&amp; 20040 = Column has no technological coefficients, XA is fixing with zero primal activity.<br />
&amp; 20045 = Column name referenced in BOUNDS section is undefined.<br />
&amp; 20050 = Unable to save &quot;advance basis&quot; solution. <br />
&amp; 20060 = A free column only appears in a FREE row. SET MPSXCOMPATIBLE YES to FIX this column to zero.<br />
&amp; 20080 = Duplicate row names in ROWS section.<br />
&amp; 20090 = Unrecognized line in MPS formatted file.<br />
&amp; 902-919 = Argument xx has a unreasonable value. This can also occur when you leave off an argument.<br />
<br />
{modsts}&amp; Model status. See Table tab:modelstat<br />
<br />
{solsts}&amp; Solver status. See Table tab:solverstat<br />
<br />
{act}&amp; Primal activities for all columns+rows.<br />
<br />
{dact}&amp; Dual activities for all columns+rows.<br />
<br />
{status}&amp; Status of all rows+cols at optimum.<br />
<br />
{iis}&amp; Structure containing IIS information. Fields:<br />
<br />
   {iisStatus}&amp; Status flag. Possible values:<br />
&amp; 1 - IIS was obtained.<br />
&amp; 0 - IIS was not requested.<br />
&amp; -1 - Problem is infeasible but no IIS found.<br />
&amp; -2 - Problem is not infeasible.<br />
<br />
   {iisMessage}&amp; Status message.<br />
<br />
   {rowind}&amp; The row indices of the IIS set.<br />
<br />
 


</blockquote>
===Prerequisites===
<blockquote>The interface routine {xa}calls XA to solve LP, QP, and MILP problems. The matrices <math>A</math> and <math>F</math> are transformed in {xa}to the XA sparse matrix format.


Error checking is made on the lengths of the vectors and matrices.
In this manual we assume that the user is familiar with linear, mixed-integer and quadratic programming, setting up problems in <span class="roman">TOMLAB</span> (in particular mixed-integer ('''mip''') problems) and the <span class="roman">Matlab</span> language in general.
</blockquote>

Latest revision as of 05:52, 16 December 2010

Welcome to the TOMLAB /XA User's Guide. TOMLAB /XA includes the XA solver suite from Sunset Software Technology and an interface to The MathWorks' MATLAB.

TOMLAB /XA is a solver package providing the user with functionality for solving linear, binary, integer and semi-continuous linear programming problems, as well as quadratic programming problems.

Contents of this Manual

  • Section [#intro 1] provides a basic overview of the TOMLAB /XA solver package.
  • Section provides an overview of the Matlab interface to XA.
  • Section describes how to set XA solver options from Matlab.
  • Section gives detailed information about the interface routines xa and xaTL. The solver control options, branch and bound settings, as well as solver and model status codes are also explained in this section.

More information

Please visit the following links for more information:

Prerequisites

In this manual we assume that the user is familiar with linear, mixed-integer and quadratic programming, setting up problems in TOMLAB (in particular mixed-integer (mip) problems) and the Matlab language in general.

Retrieved from "http://tomwiki.com/index.php?title=XA_-_Introduction&oldid=45"