source: trunk/Docs/basicmodelclasses.xml @ 411

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

Candidate for User Guide revision 0.3, which is to be the first world-wide release

  • Property svn:eol-style set to native
  • Property svn:keywords set to Author Date Id Revision
File size: 23.9 KB
Line 
1<?xml version="1.0" encoding="ISO-8859-1"?>
2  <chapter id="basicmodelclasses">
3  <title>
4  Basic Model Classes
5  </title>
6  <section>
7  <title>
8  Hierarchy
9  </title>
10  <para>
11  The basic model class hierarchy is simple.  The top three levels of the
12  hierarchy are depicted in the figure below. The first two levels  (i.e., Clp
13  Model, Clp Simplex, ClpInterior) contain all the problem data which defines a
14  model (aka, a problem instance). The third level is less model and more
15  algorithmic.  There is a fourth level (for models with more general
16  objectives than linear ones), but it is beyond the current scope of this
17  document. 
18  </para>
19  <mediaobject>
20    <!-- Caption doesn't line-up nicely in HTML, leave out for now
21    <caption align="top">
22      <para>
23        CLP Basic Classes
24      </para>
25    </caption>
26    -->
27    <imageobject>
28      <imagedata fileref="figures/clpbasicmodelhier.gif" format="GIF"/>
29    </imageobject>
30  </mediaobject>
31  <para>
32  The class ClpModel contains all problem data.  There may be a few pieces of
33  data which could be elsewhere but which are permanent and so they are here.
34  The main example of this is a status array: it makes the most sense for
35  Simplex but has use for crossing over from any solution.
36  </para>
37  <para>
38  ClpSimplex inherits from ClpModel, as does ClpInterior.  Extra data is specific
39  to the Simplex Algorithm and can be transient  e.g., scaling arrays.  Normally
40  a user will just be dealing with the ClpSimplex class and not with the ClpModel
41  class.
42  </para>
43  <para>
44  From the point of view of most Simplex users, the ClpModel and ClpSimplex
45  classes are all one needs to know about.  There are algorithm-specific classes
46  which inherit from ClpSimplex (e.g., ClpSimplexDual and ClpSimplexPrimal), but
47  they have no member data and very rarely need be visible to user.  So, for
48  example, after instantiating an object <userinput>model</userinput> of type ClpSimplex,
49  the user would type <userinput>model.dual()</userinput> to invoke dual algorithm.
50  </para>
51  </section>
52  <section>
53  <title>
54  First Example
55  </title>
56  <para>
57  Below is our first CLP example code.  It is short enough to present in full.
58  Most of the remaining examples in this Guide will take the form of small code
59  fragments.
60  </para>
61  <example>
62  <title>minimum.cpp</title>
63  <programlisting>
64  <![CDATA[ 
65// Copyright (C) 2002, International Business Machines
66// Corporation and others.  All Rights Reserved.
67
68#include "ClpSimplex.hpp"
69int main (int argc, const char *argv[])
70{
71  ClpSimplex  model;
72  int status;
73  if (argc<2)
74    status=model.readMps("../../Mps/Sample/p0033.mps");
75  else
76    status=model.readMps(argv[1]);
77  if (!status) {
78    model.primal();
79  }
80  return 0;
81}
82  ]]>   
83  </programlisting>
84  </example>
85  <para>
86  This sample program creates a default <classname>ClpSimplex</classname> model,
87  reads an mps file, and if there are no errors, solves it using the primal
88  algorithm.  Simple, but not terribly useful: there is no way to see the results
89  of the solve.  There are two main kinds of results -- a status saying what
90  happened to the model, and arrays filled with the solution values.
91  </para>
92  </section>
93  <section>
94  <title>
95  Getting at the Solution
96  </title>
97  <para>
98  It is often the case with CLP that there is more than one way to do something.
99  This is a consequence of CLP's mixed heritage as a child of OSL and a cousin of
100  OSI.  Finding the status of a model exemplifies this situation.
101  </para>
102  <para>
103  The OSI way to check for optimality is to call model.isProvenOptimal().  Also
104  available are <function>isProvenPrimalInfeasible()</function>,
105  <function>isProvenDualInfeasible()</function>,
106  <function>isPrimalObjectiveLimitReached()</function>,
107  <function>isDualObjectiveLimitReached()</function>,
108  <function>isIterationLimitReached()</function> or the feared
109  <function>isAbandoned()</function>.  Should one prefer the OSL way of doing
110  things, model.status() returns as it would in OSL-land, so 0 means optimal,
111  1 means  primal infeasible etc.
112  </para>
113  <para>
114  Similarly, to pick up the solution values, we can inhabit the virtuous OSI-land
115  or the not-quite-so-virtuous CLP-land.  By this it is meant that there are
116  const and non-const forms of arrays.  It is easier to deal with the non-const
117  versions, so most of the later elaborate algorithms use them.
118  </para>
119
120  <table frame="none">
121  <title>
122  Methods for getting solution information
123  </title>
124  <tgroup cols="3">
125  <thead>
126    <row>
127      <entry>
128      Purpose
129      </entry>
130      <entry>
131      OSI-style (virtuous)
132      </entry>
133      <entry>
134      CLP style (less virtuous)
135      </entry>
136    </row>
137  </thead>
138  <tbody>
139    <row>
140      <entry align="left" valign="top">
141      Primal column solution
142      </entry>
143      <entry align="left" valign="top">
144      <function>const double * getColSolution()</function>
145      </entry>
146      <entry align="left" valign="top">
147      <function>double * primalColumnSolution()</function>
148      </entry>
149    </row>
150    <row>
151      <entry align="left" valign="top">
152      Dual row solution
153      </entry>
154      <entry align="left" valign="top">
155      <function>const double * getRowPrice()</function>
156      </entry>
157      <entry align="left" valign="top">
158      <function>double * dualColumnSolution()</function>
159      </entry>
160    </row>
161    <row>
162      <entry align="left" valign="top">
163      Primal row solution
164      </entry>
165      <entry align="left" valign="top">
166      <function>const double * getRowActivity()</function>
167      </entry>
168      <entry align="left" valign="top">
169      <function>double * primalRowSolution()</function>
170      </entry>
171    </row>
172    <row>
173      <entry align="left" valign="top">
174      Dual row solution
175      </entry>
176      <entry align="left" valign="top">
177      <function>const double * getReducedCost()</function>
178      </entry>
179      <entry align="left" valign="top">
180      <function>double * dualColumnSolution()</function>
181      </entry>
182    </row>
183    <row>
184      <entry align="left" valign="top">
185      Number of rows in model
186      </entry>
187      <entry align="left" valign="top">
188      <function>int getNumRows()</function>
189      </entry>
190      <entry align="left" valign="top">
191      <function>int numberRows()</function>
192      </entry>
193    </row>
194    <row>
195      <entry align="left" valign="top">
196      Number of columns in model
197      </entry>
198      <entry align="left" valign="top">
199      <function>int getNumCols()</function>
200      </entry>
201      <entry align="left" valign="top">
202      <function>int numberColumns()</function>
203      </entry>
204    </row>
205  </tbody>
206  </tgroup>
207  </table>
208
209  <para>
210  The reader  may have noted a preference for &quot;number&quot; over
211  &quot;num&quot; and &quot;column&quot; over &quot;col&quot;.  This may be a
212  reaction to when one of the authors was young and 5 or 6 letters was the
213  maximum in FORTRAN for any name or to early days with Osl when seven characters
214  were allowed but the first three had to be &quot;EKK&quot;
215  </para>
216  <para>
217  Using the above-listed functions, our initial example might be continued as follows:
218  </para>
219  <example>
220  <title>
221  Possible extension of minimum.cpp
222  </title>
223  <programlisting>
224  <![CDATA[ 
225  int numberRows = model.numberRows();
226  double * rowPrimal = model.primalRowSolution();
227  double * rowDual = model.dualRowSolution();
228
229  int iRow;
230
231  for (iRow=0;iRow<numberRows;iRow++)   
232    printf("Row %d, primal %g, dual %g\n",iRow,
233        rowPrimal[iRow],rowDual[iRow]);
234       
235  int numberColumns = model.numberColumns();
236  double * columnPrimal = model.primalColumnSolution();
237  double * columnDual = model.dualColumnSolution();
238
239  int iColumn;
240
241  for (iColumn=0;iColumn<numberColumns;iColumn++)       
242    printf("Column %d, primal %g, dual %g\n",iColumn,
243        columnPrimal[iColumn],columnDual[iColumn]);
244  ]]>
245  </programlisting>
246  </example>
247  <para>
248  This code sample would pretty-print information about the model's primal and
249  dual solutions.  How to additionally print row and column names is
250  illustrated in the <filename>defaults.cpp</filename> file in the
251  &quot;Samples&quot; directory (the &quot;Samples&quot; are properly addressed
252  in <xref linkend="moreexamples" />).  This sample is also useful as it
253  explicitly performs default actions (e.g. it sets the primal feasiblility
254  tolerance value to the default value).
255  </para>
256  <para>
257  The remainder of this chapter will show some more of the basic tasks a user
258  might want to perform.  Apart from presolve we will only be looking at actions
259  which can be performed when including the single header file
260  <filename>COIN/Clp/include/ClpSimplex.hpp</filename>.
261  </para>
262  </section>
263  <section>
264  <title>
265  Building and Modifying a Model
266  </title>
267  <para>
268  Rather than reading a model from an MPS file we can load a model from arrays
269  in memory.  There are various <function>loadProblem</function> methods which
270  are similar to those in OSI.  It is easy to add more such methods to CLP if the need arises.
271  </para>
272  <para>We can copy in integer information by
273  <function>copyInIntegerInformation(const&nbsp;char&nbsp;*&nbsp;array)</function> where array
274  is 0 or 1 to say integer and we can drop existing information by
275  <function>deleteIntegerInformation()</function>.  There are various ways of
276  changing the size of a model.  The simplest is
277  <function>resize(newNumberRows,newNumberColumns)</function> - this will either
278  truncate model or add default rows or columns - a default row has lower bound
279  of -infinity and upper bound of +infinity, while a default column has zero cost,
280  zero lower bound and an upper bound of +infinity.
281  </para>
282  <para>
283  Normally we would use <function>deleteRows</function>,
284  <function>addRows</function>, <function>deleteColumns</function> and
285  <function>addColumns</function>, where the add ones will also add in the
286  elements.  A potentially very useful way of modifying a model is strictly a
287  constructor.  Given a large model and a list of rows and a list of columns it
288  constructs the model as a subset of the large model.  It is possible to change
289  the order of the columns/rows and to duplicate columns/rows.  So a list of
290  columns 4,4,1,0 will create a new model where the first two columns are copies
291  of column 4 in original model and the next two are the first two of original
292  model in reverse order.  This can be useful to form a model with piecewise
293  linear costs by duplicating columns and then modifying bounds and costs.
294  </para>
295  </section>
296  <section>
297  <title>Tolerances</title>
298  <para>
299  There are set and get methods for tolerances, for example,
300  <function>double&nbsp;primalTolerance()</function> and
301  <function>setPrimalTolerance(double)</function>.  An individual variable is
302  deemed primal feasible if it is less than the tolerance referred to by these
303  methods below its lower bound and less than it above its upper bound.
304  Similarly for dual tolerances, a variable is deemed to be dual feasible if its
305  reduced cost is greater than minus the tolerance or its distance to the upper
306  bound is less than primal tolerance and the reduced cost is less than plus the
307  tolerance or the distance to lower bound is less than primal tolerance.  This
308  is just complementarity conditions adadpted for tolerances and simple lower and
309  upper bounds.(Note that the above was stated as for minimization - signs are
310  reversed for maximization.)
311  </para>
312  </section>
313  <section>
314  <title>Some Useful Sets and Gets</title>
315  <table frame="none">
316  <title>Some Useful Sets and Gets</title>
317    <tgroup cols="2">
318    <thead>
319    <row>
320    <entry>
321    Method(s)
322    </entry>
323    <entry>
324    Description
325    </entry>
326    </row>
327    </thead>
328    <tbody>
329    <row>
330      <entry align="left" valign="top">
331      <function>setMaximumIterations(int value)</function><sbr/>
332      <function>setMaximumSeconds(double value)</function>
333      </entry>
334      <entry align="left" valign="top">
335      These methods tell CLP to stop after a given number of iterations or
336      seconds.
337      </entry>
338    </row>
339    <row>
340      <entry align="left" valign="top">
341      <function>double&nbsp;objectiveValue()</function>
342      </entry>
343      <entry align="left" valign="top">
344      This method returns the objective value.
345      </entry>
346    </row>
347    <row>
348      <entry align="left" valign="top">
349      <function>const&nbsp;double&nbsp;*&nbsp;getObjCoefficients()</function><sbr/>
350      <function>double&nbsp;*&nbsp;objective()</function>
351      </entry>
352      <entry align="left" valign="top">
353      These methods return the objective coefficients.
354      </entry>
355    </row>
356    <row>
357      <entry align="left" valign="top">
358      <function>const&nbsp;double&nbsp;*&nbsp;getRowLower()</function><sbr/>
359      <function>double&nbsp;*&nbsp;rowLower()</function><sbr/>
360      <function>const&nbsp;double&nbsp;*&nbsp;getRowUpper()</function><sbr/>
361      <function>double&nbsp;*&nbsp;rowUpper()</function><sbr/>
362      <function>const&nbsp;double&nbsp;*&nbsp;getColLower()</function><sbr/>
363      <function>double&nbsp;*&nbsp;columnLower()</function><sbr/>
364      <function>const&nbsp;double&nbsp;*&nbsp;getColUpper()</function><sbr/>
365      <function>double&nbsp;*&nbsp;columnUpper()</function>
366      </entry>
367      <entry align="left" valign="top">
368      These methods give lower and upper bounds on row and column activities.
369      </entry>
370    </row>
371    <row>
372      <entry align="left" valign="top">
373      <function>infeasibilityRay()</function><sbr/>
374      <function>unboundedRay()</function>
375      </entry>
376      <entry align="left" valign="top">
377      If the problem was primal or dual infeasible, these methods will give a
378      pointer to a ray proving infeasibility.
379      </entry>
380    </row>
381    <row>
382      <entry align="left" valign="top">
383      <function>matrix()</function>
384      </entry>
385      <entry align="left" valign="top">
386      There are more options as the user has great flexibility in how the problem
387      matrix is stored, but the default is as a
388      <classname>CoinPackedMatrix</classname> and so we have that this method
389      returns a pointer to a <classname>CoinPackedMatrix</classname> which can
390      be further manipulated.
391      </entry>
392    </row>
393    <row>
394      <entry align="left" valign="top">
395      <function>getNumElements()</function>
396      </entry>
397      <entry align="left" valign="top">
398      Returns the number of elements in the problem matrix.
399      </entry>
400    </row>
401    <row>
402      <entry align="left" valign="top">
403      <function>setOptimizationDirection(int&nbsp;direction)</function><sbr/>
404      <function>optimizationDirection()</function>
405      </entry>
406      <entry align="left" valign="top">
407      These methods set and get the objective sense.  The parameter
408      <parameter>direction</parameter> should be +1 to minimize, -1 to maximize,
409      and 0 to ignore.
410      </entry>
411    </row>
412    </tbody>
413  </tgroup>
414  </table>
415  </section>
416  <section>
417  <title>
418  Simplex-specific Methods
419  </title>
420  <para>
421  Some of the most commonly-used methods when working with Simplex are listed in
422  the table below.
423  </para>
424  <table frame="none">
425  <title>Common Simplex-specific methods</title>
426    <tgroup cols="2">
427    <thead>
428    <row>
429    <entry>
430    Method(s)
431    </entry>
432    <entry>
433    Description
434    </entry>
435    </row>
436    </thead>
437    <tbody>
438    <row>
439      <entry align="left" valign="top">
440      <function>primal(int&nbsp;mode=0)</function>
441      </entry>
442      <entry align="left" valign="top">
443      This applies the primal algorithm. If <parameter>mode</parameter> is
444      set to the default of 0, then the method uses the status variables to
445      determine basis and solution. If <parameter>mode</parameter> is 1 then
446      the method does a values pass so variables not in basis are given their
447      current values and one pass of variables is done to clean up the basis
448      with an equal or better objective value.
449      </entry>
450    </row>
451    <row>
452      <entry align="left" valign="top">
453      <function>dual(int&nbsp;mode=0)</function>
454      </entry>
455      <entry align="left" valign="top">
456      This applies the dual algorithm. if <parameter>mode</parameter> is set
457      to the default of 0, then the method uses the status variables to
458      determine basis and solution.  If <parameter>mode</parameter> is 1 then
459      the method uses input duals and does a values pass so one pass of basic
460      variables is done to clean up the duals with an equal or better objective
461      value.
462      </entry>
463    </row>
464    <row>
465      <entry align="left" valign="top">
466      <function>scaling(int&nbsp;mode=1)</function>
467      </entry>
468      <entry align="left" valign="top">
469      This method toggles scaling on (<parameter>mode</parameter> set to 1)
470      and off (<parameter>mode</parameter> set to 0).
471      </entry>
472    </row>
473    <row>
474      <entry align="left" valign="top">
475      <function>int&nbsp;crash(double&nbsp;gap,int&nbsp;mode)</function>
476      </entry>
477      <entry align="left" valign="top">
478      This method attemps to improve on an all slack basis and remains a work
479      in progress.  For dual this will move variables to the dual feasible bound
480      if the gap between bounds is less than <parameter>gap</parameter>.  Setting
481      <parameter>mode</parameter> to 0 guesses which algorithm is better, while
482      a value of 1 or 2 will result in more work being done.  The return code is
483      0 if the basis was not slacks in first case, it is negative if dual is
484      preferred or positive if primal.  &plusmn;1 means an all slack basis seemed
485      best, while &plusmn;2 means some work was done.
486      </entry>
487    </row>
488    <row>
489      <entry align="left" valign="top">
490      <function>perturb(int&nbsp;mode)</function>
491      </entry>
492      <entry align="left" valign="top">
493      This method toggles perturbation on (<parameter>mode</parameter> set to 1)
494      and off (<parameter>mode</parameter> set to 0).  It should be considered
495      a work in progress, although on some problems it gives very good results.
496      </entry>
497    </row>
498    <row>
499      <entry align="left" valign="top">
500      <function>factorizationFrequency()</function><sbr/>
501      <function>setFactorizationFrequency(int&nbsp;value)</function>
502      </entry>
503      <entry align="left" valign="top">
504      These are &quot;get&quot; and &quot;set&quot; methods for the basis matrix
505      factorization frequency.  The default is to refactor every 200 iterations,
506      but it may make more sense to use something such as 100 + the number of
507      rows divided by 50.
508      </entry>
509    </row>
510    <row>
511      <entry align="left" valign="top">
512      <function>dualBound()</function><sbr/>
513      <function>setDualBound(double&nbsp;value)</function>
514      </entry>
515      <entry align="left" valign="top">
516      These are &quot;get&quot; and &quot;set&quot; methods for the
517      &quot;dual&nbsp;bound&quot;.  The CLP dual algorithm declares all problems
518      to be dual feasible by putting non-basic variables to correct bounds for
519      the reduced cost.  If the gap between the bounds is too big then it
520      pretends the gap is only the value specified by this set method.
521      In essence, this gives a composite dual rather than a pure
522      Phase&nbsp;I- Phase&nbsp;II method.
523      </entry>
524    </row>
525    <row>
526      <entry align="left" valign="top">
527      <function>infeasibilityCost()</function><sbr/>
528      <function>setInfeasibilityCost(double&nbsp;value)</function>
529      </entry>
530      <entry align="left" valign="top">
531      These are the primal analogs to the &quot;dual&nbsp;bound&quot; methods.
532      </entry>
533    </row>
534    <row>
535      <entry align="left" valign="top">
536      <function>numberPrimalInfeasibilities()</function><sbr/>
537      <function>sumPrimalInfeasibilities()</function>
538      </entry>
539      <entry align="left" valign="top">
540      After a solve, there may be infeasibilities.  These methods serve to
541      check for said infeasibilities.  One could check the solution explicitly
542      as well.  For a code fragement illustrating this, see
543      <xref linkend="presolveexample"/>.
544      </entry>
545    </row>
546    </tbody>
547  </tgroup>
548  </table>
549  </section>
550  <section>
551  <title>
552  Presolve
553  </title>
554  <para>
555  The header file for the use of CLP's presolve functionality is
556  <filename>COIN/Clp/include/Presolve.hpp</filename>.  The code fragment below
557  illustrates some of the possibilities offered by CLP's presolve:
558  </para>
559  <example id="presolveexample">
560  <title>Presolve code fragment</title>
561  <programlisting>
562    #include "Presolve.hpp"
563   
564    ...
565
566    ClpSimplex model; // initialized by readMps or some other method
567   
568    ...
569
570    Presolve presolveInfo;
571    ClpSimplex * presolvedModel = presolveInfo(model);
572    // at this point we have original model and a new model.  The information
573    // on the operations done is in presolveInfo
574    if (presolvedModel) {
575      // was not found to be infeasible - so lets solve
576      // if presolvedModel was NULL then it was primal infeasible and ...
577      presolvedModel->dual(); // or whatever else we wish to do
578      presolveInfo.postsolve(true);  // the true updates status arrays in original
579      /* If the presolved model was optimal then so should the original be.
580         We can use checkSolution and test feasibility */
581    model.checkSolution();     
582    if (model.numberDualInfeasibilities()||
583      model.numberPrimalInfeasibilities()) {
584      printf("%g dual %g(%d) Primal %g(%d)\n",
585         model.objectiveValue(),
586          model.sumDualInfeasibilities(),
587          model.numberDualInfeasibilities(),
588          model.sumPrimalInfeasibilities(),
589          model.numberPrimalInfeasibilities());
590      // Due to tolerances we can not guarantee that so you may wish to throw in
591      model.primal(1);
592    }
593  </programlisting>
594  </example>
595  <para>
596  Presolve has a few more options which can be found in the header file, for
597  example whether to treat as an integer problem or whether to keep row and
598  column names.
599  </para>
600  </section>
601  <section>
602  <title>Status Array</title>
603  <para>
604  The astute reader may have noticed that the status array has been mentioned
605  once or twice.  The beginning user will not need to look at it   Nevertheless,
606  for completeness the status of a variable can be found and set as shown below.
607  The possible state of a variable are listed in the following table (each may
608  have to be preceded by ClpSimplex::):
609  </para>
610  <table frame="none">
611  <title>Possible states of a variable</title>
612    <tgroup cols="2">
613      <thead>
614        <row>
615          <entry>
616          State
617          </entry>
618          <entry>
619          Description
620          </entry>
621        </row>
622      </thead>
623      <tbody>
624        <row>
625          <entry align="left" valign="top">
626          <constant>isFree</constant>
627          </entry>
628          <entry align="left" valign="top">
629          Not in basis, has infinite bounds
630          </entry>
631        </row>
632        <row>
633          <entry align="left" valign="top">
634          <constant>basic</constant>
635          </entry>
636          <entry align="left" valign="top">
637          In basis
638          </entry>
639        </row>
640        <row>
641          <entry align="left" valign="top">
642          <constant>atUpperBound</constant>
643          </entry>
644          <entry align="left" valign="top">
645          At upper bound
646          </entry>
647        </row>
648        <row>
649          <entry align="left" valign="top">
650          <constant>atLowerBound</constant>
651          </entry>
652          <entry align="left" valign="top">
653          At lower bound
654          </entry>
655        </row>
656        <row>
657          <entry align="left" valign="top">
658          <constant>superBasic</constant>
659          </entry>
660          <entry align="left" valign="top">
661          Between bounds, but not basic or free
662          </entry>
663        </row>
664        <row>
665          <entry align="left" valign="top">
666          <constant>isFixed</constant>
667          </entry>
668          <entry align="left" valign="top">
669          Not in basis, bounds are equal
670          </entry>
671        </row>
672      </tbody>
673    </tgroup>
674  </table>
675  <para>
676  To get or set the status of a variable is a simple task:
677  </para>
678  <programlisting>
679  // Get row status...
680  Status status=model.getRowStatus(sequenceNumber)
681  // ... or get column status.
682  Status status=model.getColumnStatus(sequenceNumber)
683  // Set row status to basic (for example)...
684  model.setRowStatus(sequenceNumber,ClpSimplex::basic)
685  // ... or column status to basic.
686  model.setColumnStatus(sequenceNumber,ClpSimplex::basic)
687  </programlisting>
688  </section>
689  </chapter>
Note: See TracBrowser for help on using the repository browser.