source: html/trunk/Clp/userguide/clpuserguide.html @ 956

Last change on this file since 956 was 956, checked in by ddelanu, 16 years ago

First revision of user guide

  • Property svn:eol-style set to native
  • Property svn:keywords set to Author Date Id Revision
File size: 72.8 KB
1<html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>CLP User Manual</title><meta name="generator" content="DocBook XSL Stylesheets V1.65.1"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="book" lang="en"><div class="titlepage"><div><div><h1 class="title"><a name="clpuserguide"></a>CLP User Manual</h1></div><div><div class="authorgroup"><div class="author"><h3 class="author"><span class="firstname">
2    John
3    </span> <span class="surname">
4    Forrest
5    </span></h3><div class="affiliation"><span class="orgname">
6      IBM Research
7      <br></span></div><tt class="email">&lt;<a href="mailto:jjforre%20at%20us%20dot%20ibm%20dot%20com">jjforre at us dot ibm dot com</a>&gt;</tt></div><div class="author"><h3 class="author"><span class="firstname">
8    David
9    </span> <span class="surname">
10    de la Nuez
11    </span></h3><div class="affiliation"><span class="orgname">
12      Columbia University &amp; IBM Research
13      <br></span></div><tt class="email">&lt;<a href="mailto:dmd57%20at%20columbia%20dot%20edu">dmd57 at columbia dot edu</a>&gt;</tt></div><div class="author"><h3 class="author"><span class="firstname">
14    Robin
15    </span> <span class="surname">
16    Lougee-Heimer
17    </span></h3><div class="affiliation"><span class="orgname">
18      IBM Research
19      <br></span></div><tt class="email">&lt;<a href="mailto:robinlh%20at%20us%20dot%20ibm%20dot%20com">robinlh at us dot ibm dot com</a>&gt;</tt></div></div></div><div><p class="copyright">Copyright © 2004 IBM Coportation</p></div><div><div class="legalnotice">
20CLP and this documentation are provided under the terms of the
21<a href="" target="_top">Common Public License
22</a>.  Any use, reproduction or distribution of the programs constitutes
23the recipient's acceptance of the license.  The
24<a href="" target="_top">CPL</a> is approved by
25the <a href="" target="_top">Open Source Initiative</a>.  IBM
26Corporation, the author of the
27<a href="" target="_top">CPL</a>, has a
28<a href="" target="_top">
29CPL FAQ</a> available which is based on IBM's understanding of the
30<a href="" target="_top">CPL</a>.
31</div></div></div><div></div><hr></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="chapter"><a href="#intro">1.
32    Introduction
33  </a></span></dt><dt><span class="chapter"><a href="#basicmodelclasses">2.
34  Basic Model Classes
35  </a></span></dt><dd><dl><dt><span class="section"><a href="#id4675266">
36  Hierarchy
37  </a></span></dt><dt><span class="section"><a href="#id4674791">
38  First Example
39  </a></span></dt><dt><span class="section"><a href="#id4674842">
40  Getting at the Solution
41  </a></span></dt><dt><span class="section"><a href="#id4738863">
42  Building and Modifying a Model
43  </a></span></dt><dt><span class="section"><a href="#id4738952">Tolerances</a></span></dt><dt><span class="section"><a href="#id4739000">Some Useful Set and Get Methods</a></span></dt><dt><span class="section"><a href="#id4739385">
44  Simplex-specific Methods
45  </a></span></dt><dt><span class="section"><a href="#presolve">
46  Presolve
47  </a></span></dt><dt><span class="section"><a href="#id4739858">Status Array</a></span></dt></dl></dd><dt><span class="chapter"><a href="#notsobasic">3.
48  Not-Quite-So-Basic Model Classes
49  </a></span></dt><dd><dl><dt><span class="section"><a href="#pivotchoices">Pivot Choices</a></span></dt><dt><span class="section"><a href="#matrixclasses">Matrix Classes</a></span></dt><dt><span class="section"><a href="#messagehandling">Message Handling</a></span></dt></dl></dd><dt><span class="chapter"><a href="#moreexamples">4.
50More Samples
51</a></span></dt><dt><span class="chapter"><a href="#clpexe">5.
52  The CLP Executable
53  </a></span></dt><dt><span class="chapter"><a href="#messages">6.
54  Messages
55  </a></span></dt><dt><span class="appendix"><a href="#id4749045">A. FAQ</a></span></dt><dt><span class="appendix"><a href="#id4749978">B. Doxygen</a></span></dt><dt><span class="appendix"><a href="#id4749947">C. Revision History</a></span></dt></dl></div><div class="list-of-tables"><p><b>List of Tables</b></p><dl><dt>2.1. <a href="#id4738404">
56  Methods for getting solution information
57  </a></dt><dt>2.2. <a href="#id4739006">Some Useful Set and Get Methods</a></dt><dt>2.3. <a href="#id4739396">Common Simplex-specific methods</a></dt><dt>2.4. <a href="#id4739872">Possible states of a variable</a></dt><dt>4.1. <a href="#id4742112">Contents of the Samples directory</a></dt><dt>5.1. <a href="#id4743714">Command examples for the clp executable</a></dt><dt>6.1. <a href="#id4741255">
58  COIN Messages passed at or above logging level 1
59  </a></dt><dt>6.2. <a href="#id4744902">
60  CLP Messages passed at or above logging level 1
61  </a></dt><dt>6.3. <a href="#id4745586">
62  COIN Messages passed at or above logging level 0
63  </a></dt><dt>6.4. <a href="#id4746365">
64  CLP Messages passed at or above logging level 0
65  </a></dt></dl></div><div class="list-of-examples"><p><b>List of Examples</b></p><dl><dt>2.1. <a href="#id4674803">minimum.cpp</a></dt><dt>2.2. <a href="#id4738689">
66  Possible extension of minimum.cpp
67  </a></dt><dt>2.3. <a href="#presolveexample">Presolve code fragment</a></dt><dt>3.1. <a href="#id4742539">Sophisticated message handling</a></dt></dl></div><div class="chapter" lang="en"><div class="titlepage"><div><div><h2 class="title"><a name="intro"></a>Chapter 1. 
68    Introduction
69  </h2></div></div><div></div></div><p>
70  The COIN  Linear Program code or CLP is an open-source simplex solver written
71  in C++.  It is primarily meant to be used as a callable library, but a
72  basic stand-alone executable version is also available.  This
73  is the first edition of the User Guide, and is to be considered a work in
74  progress.
75  </p><p>
76  This document is designed to be used in conjunction with the Samples
77  subdirectory of the Clp directory (i.e. <tt class="filename">COIN/Clp/Samples</tt>).
78  In the rare event that this document conflicts with the observed behavior of
79  the source code, the comments in the header files (found in
80  <tt class="filename">COIN/Clp/include</tt>) are the ultimate reference.
81  </p></div><div class="chapter" lang="en"><div class="titlepage"><div><div><h2 class="title"><a name="basicmodelclasses"></a>Chapter 2. 
82  Basic Model Classes
83  </h2></div></div><div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="section"><a href="#id4675266">
84  Hierarchy
85  </a></span></dt><dt><span class="section"><a href="#id4674791">
86  First Example
87  </a></span></dt><dt><span class="section"><a href="#id4674842">
88  Getting at the Solution
89  </a></span></dt><dt><span class="section"><a href="#id4738863">
90  Building and Modifying a Model
91  </a></span></dt><dt><span class="section"><a href="#id4738952">Tolerances</a></span></dt><dt><span class="section"><a href="#id4739000">Some Useful Set and Get Methods</a></span></dt><dt><span class="section"><a href="#id4739385">
92  Simplex-specific Methods
93  </a></span></dt><dt><span class="section"><a href="#presolve">
94  Presolve
95  </a></span></dt><dt><span class="section"><a href="#id4739858">Status Array</a></span></dt></dl></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="id4675266"></a>
96  Hierarchy
97  </h2></div></div><div></div></div><p>
98  The basic model class hierarchy is simple.  The top three levels of the
99  hierarchy are depicted in the figure below. The first two levels  (i.e.
100  <tt class="classname">ClpModel</tt>, <tt class="classname">ClpSimplex</tt>,
101  <tt class="classname">ClpInterior</tt>) contain all the problem data which defines
102  a model (aka, a problem instance). The third level is less model and more
103  algorithmic.  There is a fourth level (for models with more general
104  objectives than linear ones), but it is beyond the current scope of this
105  document. 
106  </p><div class="mediaobject"><img src="figures/clpbasicmodelhier.gif"></div><p>
107  The class <tt class="classname">ClpModel</tt> contains all problem data.
108  There may be a few pieces of data which could be elsewhere but which are
109  permanent and so they are here.  The main example of this is a status array:
110  it makes the most sense for Simplex but has use for crossing over from any
111  solution.
112  </p><p>
113  <tt class="classname">ClpSimplex</tt> inherits from
114  <tt class="classname">ClpModel</tt>, as does <tt class="classname">ClpInterior</tt>.
115  Extra data is specific to the Simplex Algorithm and can be transient, e.g.
116  scaling arrays.  Normally a user will just be dealing with the
117  <tt class="classname">ClpSimplex</tt> class and not with the
118  <tt class="classname">ClpModel</tt> class.
119  </p><p>
120  From the point of view of most Simplex users, the
121  <tt class="classname">ClpModel</tt> and <tt class="classname">ClpSimplex</tt>
122  classes are all one needs to know about.  There are algorithm-specific classes
123  which inherit from <tt class="classname">ClpSimplex</tt> (e.g.
124  <tt class="classname">ClpSimplexDual</tt> and
125  <tt class="classname">ClpSimplexPrimal</tt>), but they have no member data and
126  very rarely need be visible to user.  So, for example, after instantiating an
127  object <b class="userinput"><tt>model</tt></b> of type <tt class="classname">ClpSimplex</tt>,
128  the user would use <b class="userinput"><tt>model.dual()</tt></b> to invoke dual algorithm.
129  </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="id4674791"></a>
130  First Example
131  </h2></div></div><div></div></div><p>
132  Below is our first CLP example code.  It is short enough to present in full.
133  Most of the remaining examples in this Guide will take the form of small code
134  fragments.
135  </p><div class="example"><a name="id4674803"></a><p class="title"><b>Example 2.1. minimum.cpp</b></p><pre class="programlisting">
137// Copyright (C) 2002, International Business Machines
138// Corporation and others.  All Rights Reserved.
140#include "ClpSimplex.hpp"
141int main (int argc, const char *argv[])
143  ClpSimplex  model;
144  int status;
145  if (argc&lt;2)
146    status=model.readMps("../../Mps/Sample/p0033.mps");
147  else
148    status=model.readMps(argv[1]);
149  if (!status) {
150    model.primal();
151  }
152  return 0;
155  </pre></div><p>
156  This sample program creates a default <tt class="classname">ClpSimplex</tt> model,
157  reads an MPS file, and if there are no errors, solves it using the primal
158  algorithm.  Simple, but not terribly useful: there is no way to inspect the
159  results of the solve.  There are two main kinds of results: a status saying
160  what happened to the model, and arrays filled with the solution values.
161  </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="id4674842"></a>
162  Getting at the Solution
163  </h2></div></div><div></div></div><p>
164  It is often the case with CLP that there is more than one way to do something.
165  This is a consequence of CLP's mixed heritage as a child of
166  <a href="" target="_top">OSL</a>
167  and a cousin of <a href="" target="_top">OSI</a>.
168  Finding the status of a model exemplifies this situation.
169  </p><p>
170  The OSI way to check for optimality is to call model.isProvenOptimal().  Also
171  available are <tt class="function">isProvenPrimalInfeasible()</tt>,
172  <tt class="function">isProvenDualInfeasible()</tt>,
173  <tt class="function">isPrimalObjectiveLimitReached()</tt>,
174  <tt class="function">isDualObjectiveLimitReached()</tt>,
175  <tt class="function">isIterationLimitReached()</tt> or the feared
176  <tt class="function">isAbandoned()</tt>.  Should one prefer the OSL way of doing
177  things, model.status() returns as it would in OSL-land, so 0 means optimal,
178  1 means  primal infeasible etc.
179  </p><p>
180  Similarly, to pick up the solution values, we can inhabit the virtuous OSI-land
181  or the not-quite-so-virtuous CLP-land.  By this it is meant that there are
182  const and non-const forms of arrays.  It is easier to deal with the non-const
183  versions, so most of the later elaborate algorithms use them.
184  </p><div class="table"><a name="id4738404"></a><p class="title"><b>Table 2.1. 
185  Methods for getting solution information
186  </b></p><table summary="
187  Methods for getting solution information
188  " border="0"><colgroup><col><col><col></colgroup><thead><tr><th>
189      Purpose
190      </th><th>
191      OSI-style (virtuous)
192      </th><th>
193      CLP style (less virtuous)
194      </th></tr></thead><tbody><tr><td align="left" valign="top">
195      Primal column solution
196      </td><td align="left" valign="top"><tt class="function">const double * getColSolution()</tt></td><td align="left" valign="top"><tt class="function">double * primalColumnSolution()</tt></td></tr><tr><td align="left" valign="top">
197      Dual row solution
198      </td><td align="left" valign="top"><tt class="function">const double * getRowPrice()</tt></td><td align="left" valign="top"><tt class="function">double * dualColumnSolution()</tt></td></tr><tr><td align="left" valign="top">
199      Primal row solution
200      </td><td align="left" valign="top"><tt class="function">const double * getRowActivity()</tt></td><td align="left" valign="top"><tt class="function">double * primalRowSolution()</tt></td></tr><tr><td align="left" valign="top">
201      Dual row solution
202      </td><td align="left" valign="top"><tt class="function">const double * getReducedCost()</tt></td><td align="left" valign="top"><tt class="function">double * dualColumnSolution()</tt></td></tr><tr><td align="left" valign="top">
203      Number of rows in model
204      </td><td align="left" valign="top"><tt class="function">int getNumRows()</tt></td><td align="left" valign="top"><tt class="function">int numberRows()</tt></td></tr><tr><td align="left" valign="top">
205      Number of columns in model
206      </td><td align="left" valign="top"><tt class="function">int getNumCols()</tt></td><td align="left" valign="top"><tt class="function">int numberColumns()</tt></td></tr></tbody></table></div><p>
207  The reader  may have noted a preference for "number" over
208  "num" and "column" over "col".  This may be a
209  reaction to when one of the authors was young and 5 or 6 letters was the
210  maximum in FORTRAN for any name or to early days with Osl when seven characters
211  were allowed but the first three had to be "EKK"! 
212  </p><p>
213  Using the above-listed functions, our initial example might be continued as follows:
214  </p><div class="example"><a name="id4738689"></a><p class="title"><b>Example 2.2. 
215  Possible extension of minimum.cpp
216  </b></p><pre class="programlisting">
218  int numberRows = model.numberRows();
219  double * rowPrimal = model.primalRowSolution();
220  double * rowDual = model.dualRowSolution();
222  int iRow;
224  for (iRow=0;iRow&lt;numberRows;iRow++)       
225    printf("Row %d, primal %g, dual %g\n",iRow,
226        rowPrimal[iRow],rowDual[iRow]);
228  int numberColumns = model.numberColumns();
229  double * columnPrimal = model.primalColumnSolution();
230  double * columnDual = model.dualColumnSolution();
232  int iColumn;
234  for (iColumn=0;iColumn&lt;numberColumns;iColumn++)   
235    printf("Column %d, primal %g, dual %g\n",iColumn,
236        columnPrimal[iColumn],columnDual[iColumn]);
238  </pre></div><p>
239  This code sample would pretty-print information about the model's primal and
240  dual solutions.  How to additionally print row and column names is
241  illustrated in the <tt class="filename">defaults.cpp</tt> file in the
242  "Samples" directory (the "Samples" are properly addressed
243  in <a href="#moreexamples" title="Chapter 4. 
244More Samples
245">Chapter 4, <i>
246More Samples
247</i></a>).  This sample is also useful as it
248  explicitly performs default actions (e.g. it sets the primal feasiblility
249  tolerance value to the default value).
250  </p><p>
251  The remainder of this chapter will show some more of the basic tasks a user
252  might want to perform.  Apart from presolve we will only be looking at actions
253  which can be performed when including the single header file
254  <tt class="filename">COIN/Clp/include/ClpSimplex.hpp</tt>.
255  </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="id4738863"></a>
256  Building and Modifying a Model
257  </h2></div></div><div></div></div><p>
258  Rather than reading a model from an MPS file we can load a model from arrays
259  in memory.  There are various <tt class="function">loadProblem</tt> methods which
260  are similar to those in OSI.  It is easy to add more such methods to CLP if the need arises.
261  </p><p>We can copy in integer information by
262  <tt class="function">copyInIntegerInformation(const char * array)</tt> where array
263  is 0 or 1 to say integer and we can drop existing information by
264  <tt class="function">deleteIntegerInformation()</tt>.  There are various ways of
265  changing the size of a model.  The simplest is
266  <tt class="function">resize(newNumberRows,newNumberColumns)</tt> - this will either
267  truncate model or add default rows or columns - a default row has lower bound
268  of -infinity and upper bound of +infinity, while a default column has zero cost,
269  zero lower bound and an upper bound of +infinity.
270  </p><p>
271  Normally we would use <tt class="function">deleteRows</tt>,
272  <tt class="function">addRows</tt>, <tt class="function">deleteColumns</tt> and
273  <tt class="function">addColumns</tt>, where the add ones will also add in the
274  elements.  A potentially very useful way of modifying a model is strictly a
275  constructor.  Given a large model and a list of rows and a list of columns it
276  constructs the model as a subset of the large model.  It is possible to change
277  the order of the columns/rows and to duplicate columns/rows.  So a list of
278  columns 4,4,1,0 will create a new model where the first two columns are copies
279  of column 4 in original model and the next two are the first two of original
280  model in reverse order.  This can be useful to form a model with piecewise
281  linear costs by duplicating columns and then modifying bounds and costs.
282  </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="id4738952"></a>Tolerances</h2></div></div><div></div></div><p>
283  There are set and get methods for tolerances, for example,
284  <tt class="function">double primalTolerance()</tt> and
285  <tt class="function">setPrimalTolerance(double)</tt>.  Assuming that one has a
286  minimization problem, an individual variable is deemed primal feasible if it
287  is less than the tolerance referred to by these methods below its lower bound
288  and less than it above its upper bound.  Similarly for dual tolerances, a
289  variable is deemed to be dual feasible if its reduced cost is greater than
290  minus the tolerance or its distance to the upper bound is less than primal
291  tolerance and the reduced cost is less than plus the tolerance or the distance
292  to lower bound is less than primal tolerance.  In short, this is complementarity
293  conditions adadpted for tolerances and simple lower and upper bounds.(Note
294  that the above was stated as for minimization; signs are reversed for
295  maximization.)
296  </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="id4739000"></a>Some Useful Set and Get Methods</h2></div></div><div></div></div><div class="table"><a name="id4739006"></a><p class="title"><b>Table 2.2. Some Useful Set and Get Methods</b></p><table summary="Some Useful Set and Get Methods" border="0"><colgroup><col><col></colgroup><thead><tr><th>
297    Method(s)
298    </th><th>
299    Description
300    </th></tr></thead><tbody><tr><td align="left" valign="top"><tt class="function">setMaximumIterations(int value)</tt><br><tt class="function">int maximumIterations()</tt><br><tt class="function">setMaximumSeconds(double value)</tt><br><tt class="function">double maximumIterations()</tt></td><td align="left" valign="top">
301      These methods tell CLP to stop after a given number of iterations or
302      seconds (and returns these values).
303      </td></tr><tr><td align="left" valign="top"><tt class="function">double objectiveValue()</tt></td><td align="left" valign="top">
304      This method returns the objective value.
305      </td></tr><tr><td align="left" valign="top"><tt class="function">const double * getObjCoefficients()</tt><br><tt class="function">double * objective()</tt></td><td align="left" valign="top">
306      These methods return the objective coefficients.
307      </td></tr><tr><td align="left" valign="top"><tt class="function">const double * getRowLower()</tt><br><tt class="function">double * rowLower()</tt><br><tt class="function">const double * getRowUpper()</tt><br><tt class="function">double * rowUpper()</tt><br><tt class="function">const double * getColLower()</tt><br><tt class="function">double * columnLower()</tt><br><tt class="function">const double * getColUpper()</tt><br><tt class="function">double * columnUpper()</tt></td><td align="left" valign="top">
308      These methods give lower and upper bounds on row and column activities.
309      </td></tr><tr><td align="left" valign="top"><tt class="function">double * infeasibilityRay()</tt><br><tt class="function">double * unboundedRay()</tt></td><td align="left" valign="top">
310      If the problem was primal or dual infeasible, these methods will give a
311      pointer to a ray proving infeasibility.
312      </td></tr><tr><td align="left" valign="top"><tt class="function">CoinPackMatrix * matrix()</tt></td><td align="left" valign="top">
313      There are more options as the user has great flexibility in how the problem
314      matrix is stored, but the default matrix class is
315      <tt class="classname">CoinPackedMatrix</tt> (see
316      <a href="#matrixclasses" title="Matrix Classes">the section called &#8220;Matrix Classes&#8221;</a>).
317      So we have that this method returns a pointer to a
318      <tt class="classname">CoinPackedMatrix</tt> which can be further manipulated.
319      </td></tr><tr><td align="left" valign="top"><tt class="function">CoinBigIndex getNumElements()</tt><sup>[<a name="id4739309" href="#ftn.id4739309">a</a>]</sup></td><td align="left" valign="top">
320      Returns the number of elements in the problem matrix.
321      </td></tr><tr><td align="left" valign="top"><tt class="function">void setOptimizationDirection(double value)</tt><br><tt class="function">double optimizationDirection()</tt></td><td align="left" valign="top">
322      These methods set and get the objective sense.  The parameter
323      <i class="parameter"><tt>value</tt></i> should be +1 to minimize, -1 to maximize,
324      and 0 to ignore.
325      </td></tr></tbody><tbody class="footnotes"><tr><td colspan="2"><div class="footnote"><p><sup>[<a name="ftn.id4739309" href="#id4739309">a</a>] </sup>
326        <span class="type">CoinBigIndex</span> is a <tt class="function">typedef</tt> which in
327        most cases is the same as <span class="type">int</span>.
328        </p></div></td></tr></tbody></table></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="id4739385"></a>
329  Simplex-specific Methods
330  </h2></div></div><div></div></div><p>
331  Some of the most commonly-used methods when working with Simplex are listed in
332  the table below.
333  </p><div class="table"><a name="id4739396"></a><p class="title"><b>Table 2.3. Common Simplex-specific methods</b></p><table summary="Common Simplex-specific methods" border="0"><colgroup><col><col></colgroup><thead><tr><th>
334    Method(s)
335    </th><th>
336    Description
337    </th></tr></thead><tbody><tr><td align="left" valign="top"><tt class="function">primal(int mode=0)</tt></td><td align="left" valign="top">
338      This applies the primal algorithm. If <i class="parameter"><tt>mode</tt></i> is
339      set to the default of 0, then the method uses the status variables to
340      determine basis and solution. If <i class="parameter"><tt>mode</tt></i> is 1 then
341      the method does a values pass so variables not in basis are given their
342      current values and one pass of variables is done to clean up the basis
343      with an equal or better objective value.
344      </td></tr><tr><td align="left" valign="top"><tt class="function">dual(int mode=0)</tt></td><td align="left" valign="top">
345      This applies the dual algorithm. if <i class="parameter"><tt>mode</tt></i> is set
346      to the default of 0, then the method uses the status variables to
347      determine basis and solution.  If <i class="parameter"><tt>mode</tt></i> is 1 then
348      the method uses input duals and does a values pass so one pass of basic
349      variables is done to clean up the duals with an equal or better objective
350      value.
351      </td></tr><tr><td align="left" valign="top"><tt class="function">scaling(int mode=1)</tt></td><td align="left" valign="top">
352      This method toggles scaling on (<i class="parameter"><tt>mode</tt></i> set to 1)
353      and off (<i class="parameter"><tt>mode</tt></i> set to 0).
354      </td></tr><tr><td align="left" valign="top"><tt class="function">int crash(double gap,int mode)</tt></td><td align="left" valign="top">
355      This method attemps to improve on an all slack basis.
356      For dual this will move variables to the dual feasible bound
357      if the gap between bounds is less than <i class="parameter"><tt>gap</tt></i>.  Setting
358      <i class="parameter"><tt>mode</tt></i> to 0 guesses which algorithm is better, while
359      a value of 1 or 2 will result in more work being done.  The return code is
360      0 if the basis was not slacks in first case, it is negative if dual is
361      preferred or positive if primal.  ±1 means an all slack basis seemed
362      best, while ±2 means some work was done.
363      </td></tr><tr><td align="left" valign="top"><tt class="function">perturb(int mode)</tt></td><td align="left" valign="top">
364      This method toggles perturbation on (<i class="parameter"><tt>mode</tt></i> set to 1)
365      and off (<i class="parameter"><tt>mode</tt></i> set to 0).  It should be considered
366      a work in progress, although on some problems it gives very good results.
367      </td></tr><tr><td align="left" valign="top"><tt class="function">factorizationFrequency()</tt><br><tt class="function">setFactorizationFrequency(int value)</tt></td><td align="left" valign="top">
368      These are "get" and "set" methods for the basis matrix
369      factorization frequency.  The default is to refactor every 200 iterations,
370      but it may make more sense to use something such as 100 + the number of
371      rows divided by 50.
372      </td></tr><tr><td align="left" valign="top"><tt class="function">dualBound()</tt><br><tt class="function">setDualBound(double value)</tt></td><td align="left" valign="top">
373      These are "get" and "set" methods for the
374      "dual bound".  The CLP dual algorithm declares all problems
375      to be dual feasible by putting non-basic variables to correct bounds for
376      the reduced cost.  If the gap between the bounds is too big then it
377      pretends the gap is only the value specified by this set method.
378      In essence, this gives a composite dual rather than a pure
379      Phase I- Phase II method.
380      </td></tr><tr><td align="left" valign="top"><tt class="function">infeasibilityCost()</tt><br><tt class="function">setInfeasibilityCost(double value)</tt></td><td align="left" valign="top">
381      These are the primal analogs to the "dual bound" methods.
382      </td></tr><tr><td align="left" valign="top"><tt class="function">numberPrimalInfeasibilities()</tt><br><tt class="function">sumPrimalInfeasibilities()</tt></td><td align="left" valign="top">
383      After a solve, there may be infeasibilities.  These methods serve to
384      check for said infeasibilities.  One could check the solution explicitly
385      as well.  For a code fragement illustrating this, see
386      <a href="#presolveexample" title="Example 2.3. Presolve code fragment">Example 2.3, &#8220;Presolve code fragment&#8221;</a>.
387      </td></tr></tbody></table></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="presolve"></a>
388  Presolve
389  </h2></div></div><div></div></div><p>
390  The header file for the use of CLP's presolve functionality is
391  <tt class="filename">COIN/Clp/include/Presolve.hpp</tt>.  The sample program below
392  illustrates some of the possibilities offered by CLP's presolve:
393  </p><div class="example"><a name="presolveexample"></a><p class="title"><b>Example 2.3. Presolve code fragment</b></p><pre class="programlisting">
394#include "ClpSimplex.hpp"
395#include "ClpPresolve.hpp"
396int main (int argc, const char *argv[])
398  ClpSimplex model;
399  model.readMps("../../Mps/Sample/p0033.mps"); // initialized by readMps or whatever
400  ClpPresolve presolveInfo;
401  ClpSimplex * presolvedModel = presolveInfo.presolvedModel(model);
402  // at this point we have original model and a new model.  The  information
403  // on the operations done is in presolveInfo
404  if (presolvedModel) {
405    // was not found to be infeasible - so lets solve
406    // if presolvedModel was NULL then it was primal infeasible and ...
407    presolvedModel-&gt;dual(); // or whatever else we wish to do
408    presolveInfo.postsolve(true);  // the true updates status arrays in original       
409    /* If the presolved model was optimal then so should the
410       original be.           
411       We can use checkSolution and test feasibility */
412    model.checkSolution();         
413    if (model.numberDualInfeasibilities()||
414        model.numberPrimalInfeasibilities())
415      printf("%g dual %g(%d) Primal %g(%d)\n",
416             model.objectiveValue(),
417             model.sumDualInfeasibilities(),
418             model.numberDualInfeasibilities(),
419             model.sumPrimalInfeasibilities(),
420             model.numberPrimalInfeasibilities());
421    // Due to tolerances we can not guarantee that so you may wish to throw in
422    model.primal(1);
423  }
425  </pre></div><p>
426  Presolve has a few more options which can be found in the header file, for
427  example whether to treat as an integer problem or whether to keep row and
428  column names.
429  </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="id4739858"></a>Status Array</h2></div></div><div></div></div><p>
430  The astute reader may have noticed that the status array has been mentioned
431  once or twice.  The beginning user will not need to look at it   Nevertheless,
432  for completeness the status of a variable can be found and set as shown below.
433  The possible state of a variable are listed in the following table (each may
434  have to be preceded by ClpSimplex::):
435  </p><div class="table"><a name="id4739872"></a><p class="title"><b>Table 2.4. Possible states of a variable</b></p><table summary="Possible states of a variable" border="0"><colgroup><col><col></colgroup><thead><tr><th><span class="type">Status</span><sup>[<a name="id4739893" href="#ftn.id4739893">a</a>]</sup></th><th>
436          Description
437          </th></tr></thead><tbody><tr><td align="left" valign="top"><tt class="constant">basic</tt></td><td align="left" valign="top">
438          In basis
439          </td></tr><tr><td align="left" valign="top"><tt class="constant">isFree</tt></td><td align="left" valign="top">
440          Not in basis, has infinite bounds
441          </td></tr><tr><td align="left" valign="top"><tt class="constant">isFixed</tt></td><td align="left" valign="top">
442          Not in basis, bounds are equal
443          </td></tr><tr><td align="left" valign="top"><tt class="constant">atUpperBound</tt></td><td align="left" valign="top">
444          At upper bound, not in basis
445          </td></tr><tr><td align="left" valign="top"><tt class="constant">atLowerBound</tt></td><td align="left" valign="top">
446          At lower bound, not in basis
447          </td></tr><tr><td align="left" valign="top"><tt class="constant">superBasic</tt></td><td align="left" valign="top">
448          Between bounds, but not basic or free
449          </td></tr></tbody><tbody class="footnotes"><tr><td colspan="2"><div class="footnote"><p><sup>[<a name="ftn.id4739893" href="#id4739893">a</a>] </sup><span class="type">Status</span>
450            is an enumeration.</p></div></td></tr></tbody></table></div><p>
451  To get or set the status of a variable is a simple task:
452  </p><pre class="programlisting">
453  // Get row status...
454  Status status=model.getRowStatus(sequenceNumber)
455  // ... or get column status.
456  Status status=model.getColumnStatus(sequenceNumber)
457  // Set row status to basic (for example)...
458  model.setRowStatus(sequenceNumber,ClpSimplex::basic)
459  // ... or column status to basic.
460  model.setColumnStatus(sequenceNumber,ClpSimplex::basic)
461  </pre></div></div><div class="chapter" lang="en"><div class="titlepage"><div><div><h2 class="title"><a name="notsobasic"></a>Chapter 3. 
462  Not-Quite-So-Basic Model Classes
463  </h2></div></div><div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="section"><a href="#pivotchoices">Pivot Choices</a></span></dt><dt><span class="section"><a href="#matrixclasses">Matrix Classes</a></span></dt><dt><span class="section"><a href="#messagehandling">Message Handling</a></span></dt></dl></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="pivotchoices"></a>Pivot Choices</h2></div></div><div></div></div><p>
464  In the dual algorithm, any infeasible basic variable may be chosen to leave the
465  basis.  Similarly in the primal algorithm, any non-basic variable with a
466  "bad" reduced cost may be chosen to enter the basis.  This choice is
467  probably the most important factor in determining the number of iterations it
468  will take to solve a problem.  Clp provides a abstract base class for each case
469  and then instances of each.  It is relatively simple for an advanced user to
470  create new instances.
471  </p><p>
472  For the dual method the base class is <tt class="function">ClpDualRowPivot</tt>.
473  The two existing instances are <tt class="function">ClpDualRowDantzig</tt> and
474  <tt class="function">ClpDualRowSteepest</tt>.  The Dantzig version implements the
475  "standard" pivot rule: choose the  most violated basic variable.  It
476  is easily dominated by the Steepest instance which should normally be used.  The
477  default is to use un-initialized weights where the initial weight for each basic
478  variable is 1.0.  If an all-slack basis is being used then these are the correct
479  weights.  To use a version which calculates the weights, create an instance and
480  pass it to ClpSimplex model as in the following code fragment:
481  </p><pre class="programlisting">
482  ClpDualRowSteepest steep(1); // 0 uninitialized, 1 compute weights
483  model.setDualRowPivotAlgorithm(steep);
484  </pre><p>Similarly for the primal method the base class is
485  <tt class="function">ClpPrimalColumnPivot</tt>.  The two existing instances are
486  <tt class="function">ClpPrimalColumnDantzig</tt> and
487  <tt class="function">ClpPrimalColumnSteepest</tt>.  The Dantzig version implements
488  "standard" pivot rule: choose the most "violated" non-basic
489  variable.  It is dominated by the Steepest instance which should normally be
490  used.  The default is to use exact Devex where the initial weight for each
491  non-basic variable is 1.0.  Unlike for the dual, this is never the same as
492  normal steepest edge.  To use a version which does steepest edge create an
493  instance and pass it to ClpSimplex model as in the following code fragment:
494  </p><pre class="programlisting">
495  ClpPrimalColumnSteepest steep(1); // 0 devex, 1 steepest
496  model.setPrimalColumnPivotAlgorithm(steep);
497  </pre><p>
498  The partial pricing scheme (for long, thin problems) currently does not
499  exist.  This could be implemented by anyone who is interested.
500  </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="matrixclasses"></a>Matrix Classes</h2></div></div><div></div></div><p>
501  The next abstract class of interest is <tt class="function">ClpMatrixBase</tt>.
502  CLP encapsulates its knowledge of how a matrix is stored in this class.  The
503  default instance of this is the <tt class="function">ClpPackedMatrix</tt> class.
504  This is identical in format to <tt class="function">CoinPackedMatrix</tt>.  Below
505  is a diagram summarizing the hierarchy of the most important matrix classes:
506  </p><div class="mediaobject"><img src="figures/clpbasicmatrixhier.gif"></div><p>
507  The important new methods implemented are for filling a basis, checking validity
508  of elements and faster "times" and "transposeTimes" when
509  the input array is sparse and/or we have a row copy of the matrix.  Advanced
510  users should note that not all methods have to be implemented.  In particular,
511  <tt class="function">scaling</tt> need not be implemented and
512  <tt class="function">reverseOrderedCopy</tt> can return <i class="parameter"><tt>NULL</tt></i>
513  if a row copy does not make sense.
514  </p><p>
515  In addition to the default class, there are two others at present:
516  <tt class="function">ClpPlusMinusOneMatrix</tt> and
517  <tt class="function">ClpNetworkMatrix</tt>.  As the name implies, the first one is
518  useful when all elements are ±1.  In this case multiplies are not needed
519  and more importantly less memory is used and there are fewer cache misses.  A
520  class for a matrix where all elements are +1 would be trivial to create. If
521  there were fewer than 64000 rows one could even store row indices as shorts
522  etc.
523  </p><p>
524  The use of <tt class="function">ClpPlusMinusOneMatrix</tt> involves some work as one
525  cannot simply read-in an MPS file.  The key is to use
526  <tt class="function">loadProblem</tt> to pass in a matrix.  So if
527  <tt class="varname">matrix</tt> was a <tt class="function">CoinPackedMatrix</tt> one
528  could do the following:
529  </p><pre class="programlisting">
530  ClpPlusMinusOneMatrix plusMinus(matrix);
531  assert (plusMinus.getIndices()); // would be zero if not +- one
532  model.loadProblem(plusMinus,
533    lowerColumn,upperColumn,objective,
534    lower,upper);
535  </pre><p>
536  <tt class="function">ClpNetworkMatrix</tt> is similar, but represents a network,
537  thus may only have one element per column.  Fortunately, using is is very
538  easy.  Given <tt class="varname">head</tt> and <tt class="varname">tail</tt>, one could
539  do the following:
540  </p><pre class="programlisting">
541  ClpNetworkMatrix network(numberColumns,head,tail);
542  model.loadProblem(network,
543    lowerColumn,upperColumn,objective,
544    lower,upper);
545  </pre><p>
546  Actual code is in <tt class="filename">COIN/Clp/Test/unitTest.cpp</tt>.  A quick
547  glance at the output of this program shows that use of
548  <tt class="function">ClpNetworkMatrix</tt> gives much faster run times.  This is
549  not because of storage issues, but because CLP recognizes the network and uses
550  a network basis factorization which is much faster.  However, in this mode CLP
551  is not a genuine network code as it does not take full advantage of the
552  structure by combining operations but it does have the advantage of
553  flexibility.
554  </p><p>
555  Other instances are possible.  In particular, it should be possible to use the
556  abstract class for column generation or for dynamic matrices which change over
557  time.  Minor modifications may be needed but it should work quite smoothly
558  (there is already a dummy "refresh" method which would be used).
559  </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="messagehandling"></a>Message Handling</h2></div></div><div></div></div><p>
560  Strictly speaking, message handling is a general COIN topic, but it won't hurt
561  to repeat a few important things here.
562  </p><p>
563  A simple user you may wish to turn off some output.  This is done with
564  <tt class="function">model.setLogLevel(int value)</tt>
565  where 0 gives nothing and each increase in value switches on more
566  messages. See <tt class="filename">ClpMessage.cpp</tt>,
567  <tt class="filename">CoinMessage.cpp</tt> and <a href="#messages" title="Chapter 6. 
568  Messages
569  ">Chapter 6, <i>
570  Messages
571  </i></a> to see
572  which messages are at which level.  A more sophisticated user may wish to
573  handle messages in a different way.  This is done using
574  <tt class="function">passInMessageHandler</tt> with a pointer to a handler of the
575  user's own design.  The simplest case would be to use the default handler but
576  use a constructor which writes to file.  The code would be:
577  </p><pre class="programlisting">
578  FILE * fp; // assumed open
579  CoinMessageHandler handler(fp);
580  model.passInMessageHandler(&amp;handler);
581  </pre><p>
582  A still more sophisticated use would be to write a class derived from
583  <tt class="function">CoinMessageHandler</tt> and then override the
584  <tt class="function">print</tt> method.  Below follows an example which would
585  print only a message for optimality (or infeasibility):
586  </p><div class="example"><a name="id4742539"></a><p class="title"><b>Example 3.1. Sophisticated message handling</b></p><pre class="programlisting">
587  class DerivedHandler :
588   public CoinMessageHandler {
589   public:
590     virtual int print() ;
591   };
594   int DerivedHandler::print()
595   {
596     if (currentSource()=="Clp") {
597       if (currentMessage().externalNumber()&gt;=0
598       &amp;&amp; currentMessage().externalNumber()&lt;4) {
599         // finished
600         return CoinMessageHandler::print(); // print
601       }
602     }
603     return 0;
604   }
605  </pre></div></div></div><div class="chapter" lang="en"><div class="titlepage"><div><div><h2 class="title"><a name="moreexamples"></a>Chapter 4. 
606More Samples
608CLP includes a number of <tt class="filename">.cpp</tt> sample files.  They can be
609found in the <tt class="filename">COIN/Clp/Samples</tt> directory.  Below is a table
610listing some of the sample files with a short description for each.
611</p><div class="table"><a name="id4742112"></a><p class="title"><b>Table 4.1. Contents of the Samples directory</b></p><table summary="Contents of the Samples directory" border="0"><colgroup><col><col></colgroup><thead><tr><th align="left" valign="bottom">
612        Filename       
613        </th><th align="left" valign="bottom">
614        Description
615        </th></tr></thead><tbody><tr><td align="left" valign="top"><tt class="filename">minimum.cpp</tt></td><td align="left" valign="top">
616        This is a CLP &lt;Hello, world&gt; program.  It reads an MPS file, and
617        solves the problem.
618        </td></tr><tr><td align="left" valign="top"><tt class="filename">defaults.cpp</tt></td><td align="left" valign="top">
619        This is one of the simpler drivers.  It sets tolerances to defaults and
620        is a useful place to find simple use of "sets" and
621        "gets".  It also prints out a full MPS-like solutions.
622        </td></tr><tr><td align="left" valign="top"><tt class="filename">driver.cpp</tt></td><td align="left" valign="top">
623        This is designed to be the file that people modify to get a useful
624        driver.  It does presolve.
625        </td></tr><tr><td align="left" valign="top"><tt class="filename">piece.cpp</tt></td><td align="left" valign="top">
626        This simple example takes a matrix read in by
627        <tt class="classname">CoinMpsIo</tt> (can be used to read in MPS files
628        without a solver), deletes every second column and solves the
629        resulting problem.
630        </td></tr><tr><td align="left" valign="top"><tt class="filename">network.cpp</tt></td><td align="left" valign="top">
631        This shows the use of non-standard matrices and how to load a problem
632        without the use of MPS files.
633        </td></tr><tr><td align="left" valign="top"><tt class="filename">decompose.cpp</tt></td><td align="left" valign="top">
634        This does full Dantzig-Wolfe decomposition.  It illustrates
635        the use of many models, adding columns, et cetera.
636        </td></tr><tr><td align="left" valign="top"><tt class="filename">sprint.cpp</tt></td><td align="left" valign="top">
637        This solves a long, thin problem by solving smaller subsets.  It is a
638        simplified version of work done by one of the authors on aircrew
639        scheduling problems.  It shows the use of two models and their
640        synchronization.  A more general version can be found in
641        <tt class="filename">COIN/Clp/ClpSolve.cpp</tt></td></tr><tr><td align="left" valign="top"><tt class="filename">sprint2.cpp</tt></td><td align="left" valign="top">
642        This is similar to <tt class="filename">sprint.cpp</tt> but is designed for
643        solving large problems with little choice.  The idea is that if
644        relatively few variables are fixed, presolve can greatly reduce the
645        problem size so that a series of solves can get close to the optimal
646        solution much faster than would a naïve solve of the full problem.
647        </td></tr></tbody></table></div></div><div class="chapter" lang="en"><div class="titlepage"><div><div><h2 class="title"><a name="clpexe"></a>Chapter 5. 
648  The CLP Executable
649  </h2></div></div><div></div></div><p>
650  The result of <b class="userinput"><tt>make unitTest</tt></b> (executed in
651  <tt class="filename">COIN/Clp</tt>) is an executable
652  <tt class="filename">clp</tt> as well as the CLP and COIN libraries.
653  This can be used to do various unit tests, but can also be used as a standalone
654  solver.  As it only has a very simple solution file format the user may wish to
655  modify that part of <tt class="filename">COIN/Clp/Test/ClpMain.cpp</tt> and even
656  offer the modifications as contribution to CLP.
657  </p><p>
658  The <tt class="filename">clp</tt> executable operates in command line mode or
659  prompted mode.  Entering <b class="userinput"><tt>clp</tt></b> will bring being "prompt
660  mode", while <b class="userinput"><tt>clp &lt;filename&gt;</tt></b> will import an MPS file
661  from filename and solve it using the dual simplex method and exit.  Again
662  <b class="userinput"><tt>clp &lt;filename&gt; -primalsimplex</tt></b> will import a file
663  and solve using the primal simplex method.  A dash
664  ("<b class="userinput"><tt>-</tt></b>") by itself changes to prompt mode.  In
665  command line mode "<b class="userinput"><tt>-</tt></b>" is needed (apart from
666  first parameter which is taken as file name).  So the following are equivalent
667  and maximize a problem using dual and write a solution to file
668  <tt class="filename">solfile</tt>:
669  </p><div class="blockquote"><blockquote class="blockquote"><div class="literallayout"><p><br>
670    <tt class="prompt">$</tt> <b class="userinput"><tt>clp <i class="replaceable"><tt>filename</tt></i> -maximize -dualsimplex -solution solfile</tt></b><br>
671    </p></div></blockquote></div><p>
672  </p><div class="blockquote"><blockquote class="blockquote"><div class="literallayout"><p><br>
673    <tt class="prompt">$</tt> <b class="userinput"><tt>clp <i class="replaceable"><tt>filename</tt></i> -maximize -</tt></b><br>
674    <tt class="prompt">Clp:</tt><b class="userinput"><tt>duals</tt></b><br>
675    <tt class="prompt">Clp:</tt><b class="userinput"><tt>solution solfile</tt></b><br>
676    <tt class="prompt">Clp:</tt><b class="userinput"><tt>quit</tt></b><br>
677    </p></div></blockquote></div><p>
678  </p><p>
679  The executable has some command-completion functionality as well as some inline
680  help.  Below is a table with some examples which summarize these capabilities.
681  </p><div class="table"><a name="id4743714"></a><p class="title"><b>Table 5.1. Command examples for the clp executable</b></p><table summary="Command examples for the clp executable" border="0"><colgroup><col><col></colgroup><thead><tr><th align="left">
682        Command    
683        </th><th align="left">
684        Result
685        </th></tr></thead><tbody><tr><td><span><b class="command">?</b></span></td><td>
686        Gives a list of all  commands
687        </td></tr><tr><td><span><b class="command">p?</b></span></td><td>
688        Gives a list of all commands which begin with &lt;p&gt;.
689        </td></tr><tr><td><span><b class="command">p??</b></span></td><td>
690        Gives a list of all commands which begin with &lt;p&gt;., with a short
691        explanation for each.
692        </td></tr><tr><td><span><b class="command">primals??</b></span></td><td>
693        If is this is enough to uniquely determine a command (in this example,
694        <span><b class="command">primalS</b></span>, for primal simplex), a long explanation
695        is given.
696        </td></tr></tbody></table></div><p>
697  In addition, matching a name without a ? will either execute the command or give
698  the value of the corresponding parameter.  So,
699  <span><b class="command">primalweight</b></span> will give the current value of  the
700  primalWeight parameter while <span><b class="command">primalw 1.0e7</b></span> will change
701  it to 1.0e7.
702  </p><p>
703  The executable is at a very early stage and comments will graciously
704  welcomed.
705  </p></div><div class="chapter" lang="en"><div class="titlepage"><div><div><h2 class="title"><a name="messages"></a>Chapter 6. 
706  Messages
707  </h2></div></div><div></div></div><p>
708  Some of the more common messages and codes passed by CLP are listed in the
709  tables below.  This is list is not meant to exhaustive.  The notation is as
710  for printf from "C":
711  </p><div class="itemizedlist"><ul type="disc"><li>
712    <tt class="computeroutput">%s</tt> is a string
713    </li><li>
714    <tt class="computeroutput">%d</tt> is an integer
715    </li><li>
716    <tt class="computeroutput">%g</tt> or <tt class="computeroutput">%f</tt>
717    is a floating point value
718    </li></ul></div><div class="table"><a name="id4741255"></a><p class="title"><b>Table 6.1. 
719  COIN Messages passed at or above logging level 1
720  </b></p><table summary="
721  COIN Messages passed at or above logging level 1
722  " border="0"><colgroup><col><col><col><col></colgroup><thead><tr><th align="center">
723      Code
724      </th><th align="center">
725      Area
726      </th><th> </th><th align="left">
727      Text and notes
728      </th></tr></thead><tbody><tr><td align="left">
729      1
730      </td><td align="center">
731      MPSREAD
732      </td><td> </td><td align="left"><tt class="computeroutput">At line %d %s</tt></td></tr><tr><td colspan="3"> </td><td align="left"><p>
733      This just prints out NAME line, ROW line, etc
734      </p></td></tr><tr><td align="left">
735      2
736      </td><td align="center">
737      MPSREAD
738      </td><td> </td><td align="left"><tt class="computeroutput">Problem %s has %d rows, %d columns and %d elements
739      </tt></td></tr><tr><td colspan="3"> </td><td align="left"><p>
740      This gives statistics after reading an MPS file
741      </p></td></tr><tr><td align="left">
742      8
743      </td><td align="center">
744      MPSREAD
745      </td><td> </td><td align="left"><tt class="computeroutput">%s read with %d errors
746      </tt></td></tr><tr><td colspan="3"> </td><td align="left"><p>
747      This gives error statistics for file
748      </p></td></tr><tr><td align="left">
749      505
750      </td><td align="center">
751      PRESOLVE
752      </td><td> </td><td align="left"><tt class="computeroutput">
753      Presolved poblem not optimal, resolve after postsolve
754      </tt></td></tr><tr><td colspan="3"> </td><td align="left"><p>
755      This could be because it was not feasible or because of maximum
756      iterations.  If this message occurs then consider using primal clean up
757      </p></td></tr><tr><td align="left">
758      506
759      </td><td align="center">
760      PRESOLVE
761      </td><td> </td><td align="left"><tt class="computeroutput">
762      Presolve %d (%d) rows, %d (%d) columns and %d (%d) elements
763      </tt></td></tr><tr><td colspan="3"> </td><td align="left"><p>
764      The first number is the number after presolve and the number
765      in parentheses is amount of reduction
766      </p></td></tr><tr><td align="left">
767      510
768      </td><td align="center">
769      PRESOLVE
770      </td><td> </td><td align="left"><tt class="computeroutput">
771      Presolve is modifying %d integer bounds and re-presolving
772      </tt></td></tr><tr><td colspan="3"> </td><td align="left"><p>
773      If presolve determines at the end that an integer variable have its bounds
774      changed then it will repeat the entrire presolve
775      </p></td></tr><tr><td align="left">
776      511
777      </td><td align="center">
778      PRESOLVE
779      </td><td> </td><td align="left"><tt class="computeroutput">
780      After Postsolve, objective %g, infeasibilities - dual %g (%d),
781      primal %g (%d)
782      </tt></td></tr><tr><td colspan="3"> </td><td align="left"><p>
783      This gives the state after postsolve - this gives the objective value
784      and the sum of dual and primal infeasibilities with the number of
785      infeasibilities in parentheses.  Hopefully these should be zero
786      </p></td></tr><tr><td align="left">
787      512
788      </td><td align="center">
789      PRESOLVE
790      </td><td> </td><td align="left"><tt class="computeroutput">
791      Presolved model was optimal, full model needs cleaning up
792      </tt></td></tr><tr><td colspan="3"> </td><td align="left"><p>
793      If the numbers in previous message (511) were large then maybe we need to
794      know, if small then that's life
795      </p></td></tr></tbody></table></div><div class="table"><a name="id4744902"></a><p class="title"><b>Table 6.2. 
796  CLP Messages passed at or above logging level 1
797  </b></p><table summary="
798  CLP Messages passed at or above logging level 1
799  " border="0"><colgroup><col><col><col><col></colgroup><thead><tr><th align="center">
800      Code
801      </th><th align="center">
802      Area
803      </th><th> </th><th align="left">
804      Text and notes
805      </th></tr></thead><tbody><tr><td align="left">
806      1
807      </td><td align="center">
808      SIMPLEX
809      </td><td> </td><td align="left"><tt class="computeroutput">
810      Primal infeasible - objective value %g
811      </tt></td></tr><tr><td colspan="3"> </td><td align="left"><p>
812      You may need to look at previous messages or use methods.  Such as
813      sumPrimalInfeasibilities() to find cause
814      </p></td></tr><tr><td align="left">
815      2
816      </td><td align="center">
817      SIMPLEX
818      </td><td> </td><td align="left"><tt class="computeroutput">
819      Dual infeasible - objective value %g
820      </tt></td></tr><tr><td colspan="3"> </td><td align="left"><p>
821      You may need to look at previous messages or use methods.  Such as
822      sumDualInfeasibilities() to find cause
823      </p></td></tr><tr><td align="left">
824      3
825      </td><td align="center">
826      SIMPLEX
827      </td><td> </td><td align="left"><tt class="computeroutput">
828      Stopped - objective value %g
829      </tt></td></tr><tr><td colspan="3"> </td><td align="left"><p>
830      The algorithm stopped as requested by the user.
831      </p></td></tr><tr><td align="left">
832      4
833      </td><td align="center">
834      SIMPLEX
835      </td><td> </td><td align="left"><tt class="computeroutput">
836      Stopped due to errors - objective value %g
837      </tt></td></tr><tr><td colspan="3"> </td><td align="left"><p>
838      Switch on log level 2 to see information on size of elements etc.  If they
839      look reasonable then maybe we need to know.
840      </p></td></tr><tr><td align="left">
841      5
842      </td><td align="center">
843      SIMPLEX
844      </td><td> </td><td align="left"><tt class="computeroutput">
845      %d Obj %g Primal inf %g (%d) Dual inf %g (%d)
846      </tt></td></tr><tr><td colspan="3"> </td><td align="left"><p>
847      At each re-factorization this gives the number of iterations and the value
848      of the objective function.  If there are primal infeasibilities then the
849      sum and number are given and similarly for dual infeasibilities.
850      (This is a simplified form of message.)
851      </p></td></tr><tr><td align="left">
852      14
853      </td><td align="center">
854      SIMPLEX
855      </td><td> </td><td align="left"><tt class="computeroutput">
856      Perturbing problem by %g % of %g
857      </tt></td></tr><tr><td colspan="3"> </td><td align="left"><p>
858      There is more to this message but if the user sees this then s/he has
859      chosen to perturb the problem or the algorithm has decided to do so.
860      If the numbers look too large the user may wish to think again.
861      </p></td></tr><tr><td align="left">
862      19
863      </td><td align="center">
864      SIMPLEX
865      </td><td> </td><td align="left"><tt class="computeroutput">
866      %d variables/rows fixed as scaled bounds too close
867      </tt></td></tr><tr><td colspan="3"> </td><td align="left"><p>
868      If this occurs look carefully at your input data
869      </p></td></tr><tr><td align="left">
870      24
871      </td><td align="center">
872      SIMPLEX
873      </td><td> </td><td align="left"><tt class="computeroutput">
874      Matrix will be packed to eliminate small elements
875      </tt></td></tr><tr><td colspan="3"> </td><td align="left"><p>
876      If this occurs the user should look carefully at data.
877      </p></td></tr><tr><td align="left">
878      26
879      </td><td align="center">
880      SIMPLEX
881      </td><td> </td><td align="left"><tt class="computeroutput">
882      Matrix will be packed to eliminate %d duplicate elements
883      </tt></td></tr><tr><td colspan="3"> </td><td align="left"><p>
884      If this occurs the user should look carefully at data.
885      </p></td></tr><tr><td align="left">
886      28
887      </td><td align="center">
888      SIMPLEX
889      </td><td> </td><td align="left"><tt class="computeroutput">
890      Crash put %d variables in basis, %d dual infeasibilities
891      </tt></td></tr><tr><td colspan="3"> </td><td align="left"><p>
893      </p></td></tr><tr><td align="left">
894      29
895      </td><td align="center">
896      SIMPLEX
897      </td><td> </td><td align="left"><tt class="computeroutput">
898      End of values pass after %d iterations
899      </tt></td></tr><tr><td colspan="3"> </td><td align="left"><p>
900      ??? If primal(1) or dual(1) the a sweep through model is made and this
901      signals end of pass.
902      </p></td></tr></tbody></table></div><div class="table"><a name="id4745586"></a><p class="title"><b>Table 6.3. 
903  COIN Messages passed at or above logging level 0
904  </b></p><table summary="
905  COIN Messages passed at or above logging level 0
906  " border="0"><colgroup><col><col><col><col></colgroup><thead><tr><th align="center">
907      Code
908      </th><th align="center">
909      Area
910      </th><th> </th><th align="left">
911      Text and notes
912      </th></tr></thead><tbody><tr><td align="left">
913      3001
914      </td><td align="center">
915      MPSREAD
916      </td><td> </td><td align="left"><tt class="computeroutput">
917      Illegal value for %s of %g
918      </tt></td></tr><tr><td colspan="3"> </td><td align="left"><p>
919      String will be "infinity" if setInfinity passed bad value,
920      or "default integer bound" if setDefaultBound passed bad value.
921      </p></td></tr><tr><td align="left">
922      3002
923      </td><td align="center">
924      MPSREAD
925      </td><td> </td><td align="left"><tt class="computeroutput">
926      Bad image at line %d &lt; %s &gt;
927      </tt></td></tr><tr><td colspan="3"> </td><td align="left"><p>
928      This gives line number and the offending line
929      </p></td></tr><tr><td align="left">
930      3003
931      </td><td align="center">
932      MPSREAD
933      </td><td> </td><td align="left"><tt class="computeroutput">
934      Duplicate objective at line %d &lt; %s &gt;
935      </tt></td></tr><tr><td colspan="3"> </td><td align="left"><p>
936      An objective row appears twice in one column
937      </p></td></tr><tr><td align="left">
938      3004
939      </td><td align="center">
940      MPSREAD
941      </td><td> </td><td align="left"><tt class="computeroutput">
942      Duplicate row %s at line %d %s
943      </tt></td></tr><tr><td colspan="3"> </td><td align="left"><p>
944      The named row appears twice in one column.
945      </p></td></tr><tr><td align="left">
946      3005
947      </td><td align="center">
948      MPSREAD
949      </td><td> </td><td align="left"><tt class="computeroutput">
950      No match for row %s at line %d &lt; %s &gt;
951      </tt></td></tr><tr><td colspan="3"> </td><td align="left"><p>
952      The named row did not appear in ROWS section.
953      </p></td></tr><tr><td align="left">
954      3006
955      </td><td align="center">
956      MPSREAD
957      </td><td> </td><td align="left"><tt class="computeroutput">
958      No match for column at line %d &lt; %s &gt;
959      </tt></td></tr><tr><td colspan="3"> </td><td align="left"><p>
960      The named column (in BOUNDS section) did not appear in COLUMNS section.
961      </p></td></tr><tr><td align="left">
962      6001
963      </td><td align="center">
964      MPSREAD
965      </td><td> </td><td align="left"><tt class="computeroutput">
966      Unable to open mps input file %s
967      </tt></td></tr><tr><td colspan="3"> </td><td align="left"><p>
969      </p></td></tr><tr><td align="left">
970      6002
971      </td><td align="center">
972      MPSREAD
973      </td><td> </td><td align="left"><tt class="computeroutput">
974      Unknown image %s at line %d of file %s
975      </tt></td></tr><tr><td colspan="3"> </td><td align="left"><p>
976      The Mps reader could not make sense of the image file specified.
977      </p></td></tr><tr><td align="left">
978      6003
979      </td><td align="center">
980      MPSREAD
981      </td><td> </td><td align="left"><tt class="computeroutput">
982      Consider the possibility of a compressed file which zlib is unable to read.
983      </tt></td></tr><tr><td colspan="3"> </td><td align="left"><p>
984      Some .gz files can not be read by zlib.  Using gunzip and then gzip
985      normally cures problem.
986      </p></td></tr><tr><td align="left">
987      6004
988      </td><td align="center">
989      MPSREAD
990      </td><td> </td><td align="left"><tt class="computeroutput">
991      EOF on file %s
992      </tt></td></tr><tr><td colspan="3"> </td><td align="left"><p>
993      The Mps reader did not find expected section marker.     
994      </p></td></tr><tr><td align="left">
995      6005
996      </td><td align="center">
997      MPSREAD
998      </td><td> </td><td align="left"><tt class="computeroutput">
999      Returning as too many errors
1000      </tt></td></tr><tr><td colspan="3"> </td><td align="left"><p>
1001      The reader has put out 100 messages and is giving up.
1002      </p></td></tr><tr><td align="left">
1003      507
1004      </td><td align="center">
1005      PRESOLVE
1006      </td><td> </td><td align="left"><tt class="computeroutput">
1007      Presolve determined that the problem is infeasible with tolerance of %g
1008      </tt></td></tr><tr><td colspan="3"> </td><td align="left"><p>
1009      If you want you can try with a larger tolerance
1010      </p></td></tr><tr><td align="left">
1011      508
1012      </td><td align="center">
1013      PRESOLVE
1014      </td><td> </td><td align="left"><tt class="computeroutput">
1015      Presolve thinks problem is unbounded
1016      </tt></td></tr><tr><td colspan="3"> </td><td align="left"><p>
1017      Perhaps the user should maximize if initially minimizing or vice versa.
1018      </p></td></tr><tr><td align="left">
1019      509
1020      </td><td align="center">
1021      PRESOLVE
1022      </td><td> </td><td align="left"><tt class="computeroutput">
1023      Presolve thinks problem is infeasible AND unbounded???
1024      </tt></td></tr><tr><td colspan="3"> </td><td align="left"><p>
1025      If you get this message we want to know
1026      </p></td></tr></tbody></table></div><div class="table"><a name="id4746365"></a><p class="title"><b>Table 6.4. 
1027  CLP Messages passed at or above logging level 0
1028  </b></p><table summary="
1029  CLP Messages passed at or above logging level 0
1030  " border="0"><colgroup><col><col><col><col></colgroup><thead><tr><th align="center">
1031      Code
1032      </th><th align="center">
1033      Area
1034      </th><th> </th><th align="left">
1035      Text and notes
1036      </th></tr></thead><tbody><tr><td align="left">
1037      3002
1038      </td><td align="center">
1039      SIMPLEX
1040      </td><td> </td><td align="left"><tt class="computeroutput">
1041      Not solving empty problem - %d rows, %d columns and %d elements
1042      </tt></td></tr><tr><td colspan="3"> </td><td align="left"><p>
1043      Test problem size before solving.
1044      </p></td></tr><tr><td align="left">
1045      6002
1046      </td><td align="center">
1047      SIMPLEX
1048      </td><td> </td><td align="left"><tt class="computeroutput">
1049      %d bad bound pairs or bad objectives were found
1050      </tt></td></tr><tr><td colspan="3"> </td><td align="left"><p>
1051      Either the value in the objective was too large or a lower bound was
1052      greater than an upper bound.
1053      </p></td></tr><tr><td align="left">
1054      6003
1055      </td><td align="center">
1056      SIMPLEX
1057      </td><td> </td><td align="left"><tt class="computeroutput">
1058      Matrix has %d large values, first at column %d, row %d is %g
1059      </tt></td></tr><tr><td colspan="3"> </td><td align="left"><p>
1060      Some of the values in matrix are ridiculous.
1061      </p></td></tr><tr><td align="left">
1062      6004
1063      </td><td align="center">
1064      SIMPLEX
1065      </td><td> </td><td align="left"><tt class="computeroutput">
1066      Can't get out of loop ...
1067      </tt></td></tr><tr><td colspan="3"> </td><td align="left"><p>
1069      </p></td></tr></tbody></table></div><p>
1070  There are also messages available at log level 2 (the most likely useful relate
1071  to scaling), and will be addressed in a future version of this User Guide.
1072  </p></div><div class="appendix" lang="en"><div class="titlepage"><div><div><h2 class="title"><a name="id4749045"></a>Appendix A. FAQ</h2></div></div><div></div></div><div class="qandaset"><dl><dt>Q: <a href="#id4749124">
1073  What is CLP?
1074  </a></dt><dt>Q: <a href="#id4749083">
1075  What are some of the features of CLP?
1076  </a></dt><dt>Q: <a href="#id4749998">
1077  The barrier method sounds interesting, what are some of the details?
1078  </a></dt><dt>Q: <a href="#id4750024">
1079  How do I obtain and install CLP?
1080  </a></dt><dt>Q: <a href="#id4750060">
1081  Is CLP reliable?
1082  </a></dt><dt>Q: <a href="#id4750087">
1083  On which platforms does CLP run?   
1084  </a></dt><dt>Q: <a href="#id4750138">
1085  Is there any documentation for CLP? 
1086  </a></dt><dt>Q: <a href="#id4750171">
1087  Is CLP as fast as OSL?
1088  </a></dt><dt>Q: <a href="#id4750192">
1089  When will version 1.0 of CLP be available? 
1090  </a></dt><dt>Q: <a href="#id4750223">
1091  What can the community do to help?
1092  </a></dt></dl><table border="0" summary="Q and A Set"><col align="left" width="1%"><tbody><tr class="question"><td align="left" valign="top"><a name="id4749124"></a><a name="id4749126"></a><b>Q:</b></td><td align="left" valign="top"><p>
1093  What is <a href="" target="_top">CLP</a>?
1094  </p></td></tr><tr class="answer"><td align="left" valign="top"><b>A:</b></td><td align="left" valign="top"><p>
1095  (DN 08/27/04) The <a href="" target="_top">COIN-OR</a> LP code
1096  is designed to be a high quality Simplex code provided under the terms of the
1097  <a href="" target="_top">Common Public License</a>.
1098  CLP is written in C++, and is primarily intended to be used as a callable
1099  library (though a rudimentary stand-alone executable exists).
1100  The first release was version .90.  The current release is version .99.8.
1101  </p></td></tr><tr class="question"><td align="left" valign="top"><a name="id4749083"></a><a name="id4749085"></a><b>Q:</b></td><td align="left" valign="top"><p>
1102  What are some of the features of CLP?
1103  </p></td></tr><tr class="answer"><td align="left" valign="top"><b>A:</b></td><td align="left" valign="top"><p>
1104  (DN 08/27/04) CLP includes primal and dual Simplex solvers.  Both dual and primal algorithms
1105  can use matrix storage methods provided by the user (0-1 and network matrices
1106  already supported in addition the default sparse matrix). The dual algorithm
1107  has Dantzig and Steepest edge row pivot choices and new ones may be provided by
1108  the user. The same is true for the column pivot choice of the primal algorithm.
1109  The primal can also use a non linear cost which should work for piecewise
1110  linear convex functions.  CLP also includes a barrier method for solving LPs.
1111  </p></td></tr><tr class="question"><td align="left" valign="top"><a name="id4749998"></a><a name="id4750000"></a><b>Q:</b></td><td align="left" valign="top"><p>
1112  The barrier method sounds interesting, what are some of the details?
1113  </p></td></tr><tr class="answer"><td align="left" valign="top"><b>A:</b></td><td align="left" valign="top"><p>
1114  (DN 08/30/04) The CLP barrier method solves convex QPs as well as LPs. In
1115  general, a barrier method requires implementation of the algorithm, as
1116  well as a fast Cholesky factorization.  CLP provides the algorithm, and is
1117  expected to have a reasonable factorization implementation by the release of
1118  CLP version 1.0.  However, the sparse factorization requires a good ordering
1119  algorithm, which the user is expected to provide the ordering code, and
1120  perhaps a better factorization code as well.
1121  </p></td></tr><tr class="question"><td align="left" valign="top"><a name="id4750024"></a><a name="id4750026"></a><b>Q:</b></td><td align="left" valign="top"><p>
1122  How do I obtain and install CLP?
1123  </p></td></tr><tr class="answer"><td align="left" valign="top"><b>A:</b></td><td align="left" valign="top"><p>
1124  (DN 08/27/04) Please see the
1125  <a href="" target="_top">COIN-OR FAQ</a>
1126  for details on how to
1127  <a href="" target="_top">obtain</a>
1128  and
1129  <a href="" target="_top">install</a>
1130  COIN-OR modules.
1131  </p></td></tr><tr class="question"><td align="left" valign="top"><a name="id4750060"></a><a name="id4750062"></a><b>Q:</b></td><td align="left" valign="top"><p>
1132  Is CLP reliable?
1133  </p></td></tr><tr class="answer"><td align="left" valign="top"><b>A:</b></td><td align="left" valign="top"><p>
1134  (DN 08/27/04) CLP has been tested on many problems of up to 1.5 million constraints and has
1135  shown itself as reliable as OSL. It is also being tested in the context of
1136  <a href="" target="_top">SBB</a>, but more testing
1137  is needed before it can get to version 1.0.
1138  </p></td></tr><tr class="question"><td align="left" valign="top"><a name="id4750087"></a><a name="id4750089"></a><b>Q:</b></td><td align="left" valign="top"><p>
1139  On which platforms does CLP run?   
1140  </p></td></tr><tr class="answer"><td align="left" valign="top"><b>A:</b></td><td align="left" valign="top"><p>
1141  (DN 08/27/04) CLP compiles and has been tested (to varying degrees) on the following
1142  platforms:
1143  </p><div class="itemizedlist"><ul type="disc"><li><p>
1144  Linux using g++ version 3.1.1 (or later).
1145  </p></li><li><p>
1146  Windows using Microsoft Visual C++ 6
1147  </p></li><li><p>
1148  Windows using cygwin
1149  </p></li><li><p>
1150  AIX using xIC (not supported in the current Makefile)
1151  </p></li></ul></div></td></tr><tr class="question"><td align="left" valign="top"><a name="id4750138"></a><a name="id4750140"></a><b>Q:</b></td><td align="left" valign="top"><p>
1152  Is there any documentation for CLP? 
1153  </p></td></tr><tr class="answer"><td align="left" valign="top"><b>A:</b></td><td align="left" valign="top"><p>
1154  (DN 08/27/04) A User Guide should be available in time for the release of version 1.0 of CLP.
1155  Also available is a list of
1156  <a href="" target="_top">CLP class descriptions</a>.
1157  More on CLP documentation is available on the
1158  <a href="" target="_top">CLP documentation webpage</a>.
1159  </p></td></tr><tr class="question"><td align="left" valign="top"><a name="id4750171"></a><a name="id4750173"></a><b>Q:</b></td><td align="left" valign="top"><p>
1160  Is CLP as fast as OSL?
1161  </p></td></tr><tr class="answer"><td align="left" valign="top"><b>A:</b></td><td align="left" valign="top"><p>
1162   (DN 08/27/04) It uses sparse techniques designed for very large problems. The design
1163   criteria were for it not to be too slow. Some speed has been sacrificed
1164   to make the code less opaque than OSL (not difficult!).
1165  </p></td></tr><tr class="question"><td align="left" valign="top"><a name="id4750192"></a><a name="id4750194"></a><b>Q:</b></td><td align="left" valign="top"><p>
1166  When will version 1.0 of CLP be available? 
1167  </p></td></tr><tr class="answer"><td align="left" valign="top"><b>A:</b></td><td align="left" valign="top"><p>
1168  (DN 08/27/04) It is expected that version 1.0 will be released in time for the 2004
1169  <a href="" target="_top">INFORMS</a>
1170  <a href="" target="_top">Annual Meeting</a>
1171  (24-27 October, 2004).
1172  </p></td></tr><tr class="question"><td align="left" valign="top"><a name="id4750223"></a><a name="id4750226"></a><b>Q:</b></td><td align="left" valign="top"><p>
1173  What can the community do to help?
1174  </p></td></tr><tr class="answer"><td align="left" valign="top"><b>A:</b></td><td align="left" valign="top"><p>
1175  (DN 08/27/04) A lot!  A good first step would be to join the CLP
1176  <a href="" target="_top">mailing lists</a>.  Some
1177  other possibilities:
1178  </p><div class="itemizedlist"><ul type="disc"><li><p>
1179  Comment on the design
1180  </p></li><li><p>
1181  Break the code, or better yet, mend it.
1182  </p></li><li><p>
1183  Add non-English language support in your own favo(u)rite language.
1184  </p></li><li><p>
1185  Improve the Clp executable
1186  </p></li><li><p>
1187  Etc.
1188  </p></li></ul></div></td></tr></tbody></table></div></div><div class="appendix" lang="en"><div class="titlepage"><div><div><h2 class="title"><a name="id4749978"></a>Appendix B. Doxygen</h2></div></div><div></div></div><p>
1189There is Doxygen content for CLP available online at
1190<a href="" target="_top">
1192</p></div><div class="appendix" lang="en"><div class="titlepage"><div><div><h2 class="title"><a name="id4749947"></a>Appendix C. Revision History</h2></div></div><div></div></div><div class="revhistory"><table border="0" width="100%" summary="Revision history"><tr><th align="left" valign="top" colspan="3"><b>Revision History</b></th></tr><tr><td align="left">Revision 0.3</td><td align="left">19 Aug 2004</td><td align="left">DdlN</td></tr><tr><td align="left" colspan="3">Major overhaul, including transition from MS Word to DocBook
1193    XML.
1194  </td></tr><tr><td align="left">Revision 0.2</td><td align="left">23 Feb 2004</td><td align="left">RLH</td></tr><tr><td align="left" colspan="3">Revisions to make it clearer to the non-author reader.</td></tr><tr><td align="left">Revision 0.1</td><td align="left">Nov 2003</td><td align="left">JF</td></tr><tr><td align="left" colspan="3">First draft</td></tr></table></div></div></div></body></html>
Note: See TracBrowser for help on using the repository browser.