source: trunk/Docs/cbcmodelclass.xml @ 87

Last change on this file since 87 was 87, checked in by forrest, 15 years ago

start of documentation

  • Property svn:eol-style set to native
  • Property svn:keywords set to Author Date Id Revision
File size: 22.9 KB
Line 
1<?xml version="1.0" encoding="ISO-8859-1"?>
2  <chapter id="cbcmodelclass">
3  <title>
4  Basic Model Classes
5  </title>
6  <section id="hierarchy">
7  <title>
8  Hierarchy and list of classes
9  </title>
10  <para>
11  The class that controls Coin Branch and Cut is CbcModel.  This is where most
12  of the parameter setting is done.  CbcModel uses other classes some of
13  which are virtual and may have multiple instances.  More details on the more
14  useful classes will be given later.
15  The absolute minimum number of actions for CbcModel is:
16  <function>CbcModel(OsiSolverInterface &amp; linearSolver)</function> as constructor,
17  and <function>branchAndBound()</function> for solving the problem.
18  </para>
19    <table frame="none">
20  <title>Classes used by CbcModel - Most useful</title>
21    <tgroup cols="3">
22    <thead>
23    <row>
24    <entry>
25    Class name
26    </entry>
27    <entry>
28    Description
29    </entry>
30    <entry>
31    Notes
32    </entry>
33    </row>
34    </thead>
35    <tbody>
36    <row>
37      <entry align="left" valign="top">
38      CbcCompareBase
39      </entry>
40      <entry align="left" valign="top">
41      Controls choice of next node on tree
42      </entry>
43      <entry align="left" valign="top">
44      Default is CbcCompareDefault, others in CbcCompareActual.hpp include
45      CbcCompareDepth and CbcCompareObjective.  Very easy for user to
46      experiment.
47      </entry>
48    </row>
49    <row>
50      <entry align="left" valign="top">
51      CbcCutGenerator
52      </entry>
53      <entry align="left" valign="top">
54      Is a CglCutGenerator with data to decide when to use.
55      </entry>
56      <entry align="left" valign="top">
57      Need to know how to add generator to CbcModel.
58      Not much need to know about details of class.
59      </entry>
60    </row>
61    <row>
62      <entry align="left" valign="top">
63      CbcHeuristic
64      </entry>
65      <entry align="left" valign="top">
66      Heuristic to try and get valid solutions
67      </entry>
68      <entry align="left" valign="top">
69      User can get a lot of value out of coding this.  There can be
70      as many as you like.
71      </entry>
72    </row>
73    <row>
74      <entry align="left" valign="top">
75      CbcObject
76      </entry>
77      <entry align="left" valign="top">
78      Definition of what it means for a variable to be satisfied.
79      </entry>
80      <entry align="left" valign="top">
81      Virtual - instances include simple integer, simple integer with pseudocosts,
82      SOS (type 1 and 2) and lotsizing. (found in CbcBranch..hpp).  An object has to
83      have a method of generating a branching object which defines an up and down
84      branch.
85      </entry>
86    </row>
87    <row>
88      <entry align="left" valign="top">
89      OsiSolverInterface
90      </entry>
91      <entry align="left" valign="top">
92      Defines the solver being used and the LP model.  Is normally
93      passed across to CbcModel before branch and cut.
94      </entry>
95      <entry align="left" valign="top">
96      Virtual class - the user would instantiate a particular solver e.g.
97      OsiClpSolverInterface or OsiXprSolverInterface.
98      </entry>
99    </row>
100    </tbody>
101  </tgroup>
102  </table>
103    <table frame="none">
104  <title>Classes used by CbcModel - Least useful</title>
105    <tgroup cols="3">
106    <thead>
107    <row>
108    <entry>
109    Class name
110    </entry>
111    <entry>
112    Description
113    </entry>
114    <entry>
115    Notes
116    </entry>
117    </row>
118    </thead>
119    <tbody>
120    <row>
121      <entry align="left" valign="top">
122      CbcBranchDecision
123      </entry>
124      <entry align="left" valign="top">
125      Part of code for choosing which variable to branch on.  Most of
126      work is done by definitions in CbcObject
127      </entry>
128      <entry align="left" valign="top">
129      Defaults to CbcBranchDefaultDecision
130      Not much need to know about.
131      </entry>
132    </row>
133    <row>
134      <entry align="left" valign="top">
135      CbcCountRowCut
136      </entry>
137      <entry align="left" valign="top">
138      Interface to OsiRowCut but counts use so can gracefully vanish.
139      </entry>
140      <entry align="left" valign="top">
141      See OsiRowCut for extra information.
142      Not much need to know about.
143      </entry>
144    </row>
145    <row>
146      <entry align="left" valign="top">
147      CbcNode
148      </entry>
149      <entry align="left" valign="top">
150      Controls choice of variable/entity to branch on
151      </entry>
152      <entry align="left" valign="top">
153      Controlled via CbcModel parameters.
154      Not much need to know about.
155      </entry>
156    </row>
157    <row>
158      <entry align="left" valign="top">
159      CbcNodeInfo
160      </entry>
161      <entry align="left" valign="top">
162      Contains data for bounds, basis etc for one node of tree
163      </entry>
164      <entry align="left" valign="top">
165      Not much need to know about (header in CbcNode.hpp).
166      </entry>
167    </row>
168    <row>
169      <entry align="left" valign="top">
170      CbcTree
171      </entry>
172      <entry align="left" valign="top">
173      How tree is stored
174      </entry>
175      <entry align="left" valign="top">
176      Can be changed but unlikely.
177      Not much need to know about.
178      </entry>
179    </row>
180    <row>
181      <entry align="left" valign="top">
182      CoinMessageHandler
183      </entry>
184      <entry align="left" valign="top">
185      Deals with message handling
186      </entry>
187      <entry align="left" valign="top">
188      User can inherit from to specialize message handling. 
189      Not much need to know about.
190      </entry>
191    </row>
192    <row>
193      <entry align="left" valign="top">
194      CoinWarmStartBasis
195      </entry>
196      <entry align="left" valign="top">
197      Representation of a basis to be used by solver
198      </entry>
199      <entry align="left" valign="top">
200      Not much need to know about.
201      </entry>
202    </row>
203    </tbody>
204  </tgroup>
205  </table>
206  </section>
207  <section id="firstexample">
208  <title>
209  First Example
210  </title>
211  <para>
212  Below is our first CBC sample program.  It is short enough to present in full
213  (this code can be found in the CBC Samples directory, see
214  <xref linkend="moreexamples"/>).  Most of the remaining examples in this Guide
215  will take the form of small code fragments.
216  </para>
217  <example>
218  <title>minimum.cpp</title>
219  <programlisting>
220  <![CDATA[ 
221// Copyright (C) 2005, International Business Machines
222// Corporation and others.  All Rights Reserved.
223
224#include "CbcModel.hpp"
225
226// Using as solver
227#include "OsiClpSolverInterface.hpp"
228
229int main (int argc, const char *argv[])
230{
231  OsiClpSolverInterface solver1;
232  // Read in example model
233  // and assert that it is a clean model
234  int numMpsReadErrors = solver1.readMps("../../Mps/Sample/p0033.mps","");
235  assert(numMpsReadErrors==0);
236
237  // Pass data and solver to CbcModel
238  CbcModel model(solver1);
239
240  // Do complete search
241  model.branchAndBound();
242  /* Print solution.  CbcModel clones solver so we
243     need to get current copy */
244  int numberColumns = model.solver()->getNumCols();
245   
246  const double * solution = model.solver()->getColSolution();
247   
248  for (int iColumn=0;iColumn<numberColumns;iColumn++) {
249    double value=solution[iColumn];
250    if (fabs(value)>1.0e-7&&model.solver()->isInteger(iColumn))
251      printf("%d has value %g\n",iColumn,value);
252  }
253  return 0;
254}   
255  ]]>   
256  </programlisting>
257  </example>
258  <para>
259  This sample program creates a  <classname>OsiClpSolverInterface</classname> solver,
260  reads an MPS file, and if there are no errors, passes it to <classname>CbcModel</classname>
261  which solves it
262  using the Branch and Bound algorithm.  The part of the program which solves the program
263  is very small but before that the linear solver had to be created with data and
264  after that the results were printed out.  So the user can see that often knowledge
265  of the <classname>OsiSolverInterface</classname> methods will be necessary.
266  In this case CbcModel has the identical methods so we could have used those but not
267  always.  For instance the program produces a lot of output so one might add
268  <![CDATA[ 
269  model.solver()->setHintParam(OsiDoReducePrint,true,OsiHintTry);
270  ]]>   
271  to reduce the amount. That improves things a lot but we still get one message per node
272  so we could add
273  <![CDATA[ 
274    model.setLogLevel(1);
275  ]]>   
276  The following section gives many of the ways of getting information from the
277  model or underlying solver.
278  </para>
279  </section>
280  <section id="gettingsolution">
281  <title>
282  Getting at the Solution (CbcModel methods)
283  </title>
284  <para>
285  The OSI way to check for optimality is to call model.isProvenOptimal().  Also
286  available are <function>isProvenInfeasible()</function>,
287  <function>isSolutionLimitReached()</function>,
288  <function>isNodeLimitReached()</function> or the feared
289  <function>isAbandoned()</function>. You can also pick up
290  <function>int&nbsp;status()</function> which returns 0 if finished,
291   1 if stopped by user and 2 if difficulties. (status of 0 even if proved
292   infeasible)
293  </para>
294  <para>
295  Similarly, we can pick up the solution values.  The OSI methods pick up
296  the current solution.  This will match the best solution found so far if
297  called after branchAndBound and if a solution was found.
298  </para>
299  <table frame="none">
300  <title>
301  Methods for getting solution information from OSI solver
302  </title>
303  <tgroup cols="2">
304  <thead>
305    <row>
306      <entry>
307      Purpose
308      </entry>
309      <entry>
310      Name
311      </entry>
312      <entry>
313      Notes
314      </entry>
315    </row>
316  </thead>
317  <tbody>
318    <row>
319      <entry align="left" valign="top">
320      Primal column solution
321      </entry>
322      <entry align="left" valign="top">
323      <function>const double * getColSolution()</function>
324      </entry>
325      <entry align="left" valign="top">
326      Outside CBC will be best solution unless none found.  Safer to use
327      CbcModel::bestSolution()
328      </entry>
329    </row>
330    <row>
331      <entry align="left" valign="top">
332      Dual row solution
333      </entry>
334      <entry align="left" valign="top">
335      <function>const double * getRowPrice()</function>
336      </entry>
337      <entry align="left" valign="top">
338      CbcModel:: version available and identical
339      </entry>
340    </row>
341    <row>
342      <entry align="left" valign="top">
343      Primal row solution
344      </entry>
345      <entry align="left" valign="top">
346      <function>const double * getRowActivity()</function>
347      </entry>
348      <entry align="left" valign="top">
349      CbcModel:: version available and identical
350      </entry>
351    </row>
352    <row>
353      <entry align="left" valign="top">
354      Dual column solution
355      </entry>
356      <entry align="left" valign="top">
357      <function>const double * getReducedCost()</function>
358      </entry>
359      CbcModel:: version available and identical
360      <entry align="left" valign="top">
361      </entry>
362    </row>
363    <row>
364      <entry align="left" valign="top">
365      Number of rows in model
366      </entry>
367      <entry align="left" valign="top">
368      <function>int getNumRows()</function>
369      </entry>
370      <entry align="left" valign="top">
371      CbcModel:: version available and identical
372      (but note that number of rows may change due to cuts)
373      </entry>
374    </row>
375    <row>
376      <entry align="left" valign="top">
377      Number of columns in model
378      </entry>
379      <entry align="left" valign="top">
380      <function>int getNumCols()</function>
381      </entry>
382      <entry align="left" valign="top">
383      CbcModel:: version available and identical
384      </entry>
385    </row>
386  </tbody>
387  </tgroup>
388  </table>
389  <para>
390  The remainder of this chapter will show  more of the basic CBC tasks a user
391  might wish to perform.
392  </para>
393  </section>
394  <function>double&nbsp;getIntegerTolerance()</function> and
395  <function>setIntegerTolerance(double)</function>.  An integer variable
396  is deemed to be at an integral value if it is no further than this tolerance
397  away.
398  <section id="setsandgets">
399  <title>Some Useful Set and Get Methods</title>
400  <table frame="none">
401  <title>Some Useful Set and Get Methods</title>
402    <tgroup cols="2">
403    <thead>
404    <row>
405    <entry>
406    Method(s)
407    </entry>
408    <entry>
409    Description
410    </entry>
411    </row>
412    </thead>
413    <tbody>
414    <row>
415      <entry align="left" valign="top">
416      <function>setMaximumNodes(int value)</function><sbr/>
417      <function>int&nbsp;maximumNodes()</function><sbr/>
418      <function>setMaximumSeconds(double value)</function><sbr/>
419      <function>double&nbsp;maximumSeconds()</function>
420      <function>setMaximumSolutions(double value)</function><sbr/>
421      <function>double&nbsp;maximumSolutions()</function>
422      </entry>
423      <entry align="left" valign="top">
424      These methods tell CBC to stop after a given number of nodes or
425      seconds or solutions (and returns these values).
426      </entry>
427    </row>
428    <row>
429      <entry align="left" valign="top">
430      <function>setIntegerTolerance(double)</function><sbr/>
431      <function>double&nbsp;getIntegerTolerance()</function>
432      </entry>
433      <entry align="left" valign="top">
434      An integer variable
435      is deemed to be at an integral value if it is no further than this tolerance
436      away.
437      </entry>
438    </row>
439    <row>
440      <entry align="left" valign="top">
441      <function>setAllowableGap(double)</function><sbr/>
442      <function>double&nbsp;getAllowableGap()</function><sbr/>
443      <function>setAllowablePercentageGap(double)</function><sbr/>
444      <function>double&nbsp;getAllowablePercentageGap()</function><sbr/>
445      <function>setAllowableFractionGap(double)</function><sbr/>
446      <function>double&nbsp;getAllowableFractionGap()</function><sbr/>
447      </entry>
448      <entry align="left" valign="top">
449      CbcModel returns if the gap between the best known solution and the best
450      possible solution is less than this (or as a percentage or fraction).
451      </entry>
452    </row>
453    <row>
454      <entry align="left" valign="top">
455      <function>setNumberStrong(double) </function><sbr/>
456      <function>int&nbsp;numberStrong() </function>
457      </entry>
458      <entry align="left" valign="top">
459      Get or set the maximum number of candidates at a node to
460      be evaluated for strong branching.
461      </entry>
462    </row>
463    <row>
464      <entry align="left" valign="top">
465      <function>setPrintFrequency(int) </function><sbr/>
466      <function>int&nbsp;printFrequency()</function>
467      </entry>
468      <entry align="left" valign="top">
469      Controls the number of nodes evaluated between status prints.
470      Print frequency has very slight overhead if small.
471      </entry>
472    </row>
473    <row>
474      <entry align="left" valign="top">
475      <function>int&nbsp;getNodeCount() </function>
476      </entry>
477      <entry align="left" valign="top">
478      Returns number of nodes search took
479      </entry>
480    </row>
481    <row>
482      <entry align="left" valign="top">
483      <function>int&nbsp;numberRowsAtContinuous()</function>
484      </entry>
485      <entry align="left" valign="top">
486      Returns number of rows at continuous
487      </entry>
488    </row>
489    <row>
490      <entry align="left" valign="top">
491      <function>int &nbsp;numberIntegers()</function><sbr/>
492      <function>const int&nbsp;*&nbsp;integerVariable()</function>
493      </entry>
494      <entry align="left" valign="top">
495      Returns number of integers and an array giving which ones
496      </entry>
497    </row>
498    <row>
499      <entry align="left" valign="top">
500      <function>bool &nbsp;isBinary(int)</function><sbr/>
501      <function>bool &nbsp;isContinuous(int)</function><sbr/>
502      <function>const bool&nbsp;isInteger(int)</function>
503      </entry>
504      <entry align="left" valign="top">
505      Returns information on a variable.  You can use Osi methods
506      to set these attributes (before handing to CbcModel)
507      </entry>
508    </row>
509    <row>
510      <entry align="left" valign="top">
511      <function>double&nbsp;getObjValue()</function>
512      </entry>
513      <entry align="left" valign="top">
514      This method returns the best objective value.so far
515      </entry>
516    </row>
517    <row>
518      <entry align="left" valign="top">
519      <function>double&nbsp;getCurrentObjValue()</function>
520      </entry>
521      <entry align="left" valign="top">
522      This method returns the current objective value.
523      </entry>
524    </row>
525    <row>
526      <entry align="left" valign="top">
527      <function>const&nbsp;double&nbsp;*&nbsp;getObjCoefficients()</function><sbr/>
528      <function>double&nbsp;*&nbsp;objective()</function>
529      </entry>
530      <entry align="left" valign="top">
531      These methods return the objective coefficients.
532      </entry>
533    </row>
534    <row>
535      <entry align="left" valign="top">
536      <function>const&nbsp;double&nbsp;*&nbsp;getRowLower()</function><sbr/>
537      <function>double&nbsp;*&nbsp;rowLower()</function><sbr/>
538      <function>const&nbsp;double&nbsp;*&nbsp;getRowUpper()</function><sbr/>
539      <function>double&nbsp;*&nbsp;rowUpper()</function><sbr/>
540      <function>const&nbsp;double&nbsp;*&nbsp;getColLower()</function><sbr/>
541      <function>double&nbsp;*&nbsp;columnLower()</function><sbr/>
542      <function>const&nbsp;double&nbsp;*&nbsp;getColUpper()</function><sbr/>
543      <function>double&nbsp;*&nbsp;columnUpper()</function>
544      </entry>
545      <entry align="left" valign="top">
546      These methods give lower and upper bounds on row and column activities.
547      </entry>
548    </row>
549    <row>
550      <entry align="left" valign="top">
551      <function>const CoinPackMatrix * getMatrixByRow()</function>
552      </entry>
553      <entry align="left" valign="top">
554      This method returns a pointer to a row copy of matrix
555      <classname>CoinPackedMatrix</classname> which can be further examined.
556      </entry>
557    </row>
558    <row>
559      <entry align="left" valign="top">
560      <function>const CoinPackMatrix * getMatrixByCol()</function>
561      </entry>
562      <entry align="left" valign="top">
563      This method returns a pointer to a column copy of matrix
564      <classname>CoinPackedMatrix</classname> which can be further examined.
565      </entry>
566    </row>
567    <row>
568      <entry align="left" valign="top">
569      <function>CoinBigIndex&nbsp;getNumElements()</function>
570      <footnote>
571        <para>
572        <type>CoinBigIndex</type> is a <function>typedef</function> which in
573        most cases is the same as <type>int</type>.
574        </para>
575      </footnote>
576      </entry>
577      <entry align="left" valign="top">
578      Returns the number of elements in the problem matrix.
579      </entry>
580    </row>
581    <row>
582      <entry align="left" valign="top">
583      <function>void setObjSense(double&nbsp;value)</function><sbr/>
584      <function>double objSense()</function>
585      </entry>
586      <entry align="left" valign="top">
587      These methods set and get the objective sense.  The parameter
588      <parameter>value</parameter> should be +1 to minimize and -1 to maximize.
589      </entry>
590    </row>
591    </tbody>
592  </tgroup>
593  </table>
594  </section>
595  <section id="majormethods">
596  <title>
597  Methods which have a major impact on solution process
598  </title>
599  <para>
600  These are important methods which will impact search e.g. adding a cut
601  generator.  The description here may not give all parameters if they are exotic.
602  You will also find more on some of them under the description
603  of that class:
604  </para>
605  <table frame="none">
606  <title>Major methods</title>
607    <tgroup cols="2">
608    <thead>
609    <row>
610    <entry>
611    Method(s)
612    </entry>
613    <entry>
614    Description
615    </entry>
616    </row>
617    </thead>
618    <tbody>
619    <row>
620      <entry align="left" valign="top">
621      <function>passInPriorities(const int * priorities, bool ifNotSimpleIntegers,
622                        int defaultValue=1000)</function>
623      </entry>
624      <entry align="left" valign="top">
625      Normally this is a list of priorities (1 being highest) and the other
626      ifNotSimpleIntegers being false which set priorities for all integer
627      variables.  If two variables are unsatisfied and one has a higher priority
628      then it is always preferred whatever its value.  This can be very powerful
629      but also see PseudoCosts in CbcObject discussion.
630      </entry>
631    </row>
632    <row>
633      <entry align="left" valign="top">
634      <function>addCutGenerator(CglCutGenerator *,int howOften, const char * name)</function>
635      </entry>
636      <entry align="left" valign="top">
637      This is used to add a cut generator to CbcModel.  Any cut generator in Cgl
638      can be used.  If howOften >0 then the cut generator will be called at root
639      node and every howOften nodes (There is an option to override and do at
640      depth 0,k,2k..).  If -1 then the code sees how effective it was at root
641      node and sets howOften dynamically.  If -99 then just does at root node.
642      There is also a redundant -100 setting which switches off which can be useful
643      for testing.  For usage see sample2.cpp in the CBC Samples
644      directory<xref linkend="moreexamples"/> which uses the most common
645      cut generators.
646      </entry>
647    </row>
648    <row>
649      <entry align="left" valign="top">
650      <function>addHeuristic(CbcHeuristic *)</function>
651      </entry>
652      <entry align="left" valign="top">
653      This adds one heuristic to CbcModel.See the section on CbcHeuristic to obtain
654      a list of available heuristics and a guide as to building new ones.
655      </entry>
656    </row>
657    <row>
658      <entry align="left" valign="top">
659      <function>addObjects(int&nbsp;number,CbcObject&nbsp;**&nbsp;objects) </function>
660      </entry>
661      <entry align="left" valign="top">
662      This adds members of the base class CbcObject to CbcModel.  See the section
663      on CbcObject for detailed nformation.  The objects are cloned by code so
664      user should delete after <function>addObjects</function>.  There are two
665      main cases.  The first is when the originally created objects are left and
666      new ones added (maybe with a higher priority);  this might be used when
667      simple integer objects exist and Special Ordered Sets of type 1 are going
668      to be added, which while not necessary will give extra power in branching.
669      The second case is when the old ones are being deleted. 
670      For usage see sos.cpp in the CBC Samples
671      directory<xref linkend="moreexamples"/>.
672      </entry>
673    </row>
674    <row>
675      <entry align="left" valign="top">
676      <function>CglPreProcess::preProcess(OsiSolverInterface &amp;)</function>
677      </entry>
678      <entry align="left" valign="top">
679      This is not really part of Cbc and can be used by other mixed integer
680      solvers but it can be a useful tool.  It tries to fix variables and
681      strengthen coefficients and also do a normal presolve.  Owing to the
682      odd nature of integer programming it may not always reduce the time
683      taken but is definitely worth trying.  For an example of using
684      preProcess and postProcess see sample2.cpp in the CBC Samples
685      directory<xref linkend="moreexamples"/>.
686      </entry>
687    </row>
688    <row>
689      <entry align="left" valign="top">
690      <function>setNodeComparison(CbcCompareBase&nbsp;*)</function>
691      </entry>
692      <entry align="left" valign="top">
693       This is used to use a non-default node comparison function
694       to see which is the next node on tree to explore.  This
695       can make a large difference and specialized ones are easy to program.
696       See the section on CbcCompare.
697      </entry>
698    </row>
699    </tbody>
700  </tgroup>
701  </table>
702  </section>
703  </chapter>
Note: See TracBrowser for help on using the repository browser.