Ignore:
Timestamp:
May 3, 2005 9:03:29 AM (16 years ago)
Author:
rlh
Message:

Rennovated Cbc user guide for INFORMS Tutorial book chapter

File:
1 edited

Legend:

Unmodified
Added
Removed
  • trunk/Docs/cbcmodelclass.xml

    r119 r120  
    99  </title>
    1010  <para>
    11   The class that controls CBC is <classname>CbcModel</classname>.  This class is where most
    12   of the parameter setting is done. The absolute minimum number of actions for <classname>CbcModel</classname> is two:
    13 
     11  The main class in CBC is <classname>CbcModel</classname>.  The <classname>CbcModel</classname> class is where most
     12  of the parameter setting is done. The absolute minimum number of actions taken with <classname>CbcModel</classname> is two,
    1413    <itemizedlist>
    1514    <listitem>
     
    2928  <section id="firstexample">
    3029  <title>
    31   First Example
     30  Simple Branch-and-Bound Example
    3231  </title>
    3332  <para>
    34   Below is our first CBC sample program.  This program is short enough to present in full.
    35   This code can be found in the CBC Samples directory, <filename>COIN/Cbc/Samples</filename>.
    36   Most of the remaining examples in this Guide will take the form of small code fragments.
     33  The first sample program shows how to perform simple branch-and-bound with CBC.  This program is short enough to present in full.  Most of the remaining examples will take the form of small code fragments.
     34  The complete code for all the examples in this Guide can be found in the CBC Samples directory, <filename>COIN/Cbc/Samples</filename>.
     35
    3736  </para>
    3837  <example id="minimum.cpp">
     
    5756  assert(numMpsReadErrors==0);
    5857
    59   // Pass the solver (with the problem data) to CbcModel
     58  // Pass the solver with the problem to be solved to CbcModel
    6059  CbcModel model(solver1);
    6160
     
    6362  model.branchAndBound();
    6463
    65   /* Print the solution.  CbcModel clones solver so we
     64  /* Print the solution.  CbcModel clones the solver so we
    6665     need to get current copy from the CbcModel */
    6766  int numberColumns = model.solver()->getNumCols();
     
    7978  </programlisting>
    8079  </example>
    81   <!-- Clone comment  needs more explaination. What info is safe? When do you need to do a refresh?? -->
     80  <!-- Clone comment  needs more explanation. What info is safe? When do you need to do a refresh?? -->
    8281  <!-- printf vs cout  -->
    8382
    8483  <para>
    85   The sample program <xref linkend="minimum.cpp"/> creates a <classname>OsiClpSolverInterface</classname> solver interface, and reads an MPS file. If there are no errors, the program passes the solver to <classname>CbcModel</classname>
    86   which solves it using the branch-and-bound algorithm.  The part of the program which solves the problem
    87   is very small (one line!) but before that one line, the LP solver had to be created and populated with data and
    88   after that one line the results were printed out.
     84  The program in <xref linkend="minimum.cpp"/> creates a <classname>OsiClpSolverInterface</classname> solver interface (i.e., <varname>solver1</varname>), and reads an MPS file. If there are no errors, the program passes the problem to <classname>CbcModel</classname> which solves the problem using the branch-and-bound algorithm. The part of the program which solves the problem is very small (one line!) but before that one line, the LP solver (i.e., <varname>solver1</varname>) had to be created and populated with the problem. After that one line, the results were printed out.
    8985 </para>
    9086</section>
     
    9591</title>
    9692<para>
    97  Example <xref linkend="minimum.cpp"/> illustrates the dependency of CBC on 
    98   the <classname>OsiSolverInterface</classname> class. The constructor of <classname>CbcModel</classname> takes a pointer to an <classname>OsiSolverInterface</classname> (i.e., a solver). The <classname>CbcModel</classname> clones the solver, and uses its own instance of the solver. The <classname>CbcModel</classname>'s solver and the original solver (e.g., <varname>sovler1</varname>) are not in sync unless the user synchronizes them. The user can always access the <classname>CbcModel</classname>'s solver through the <function>model()</function> method.  To synchronize the orignal solver, explicitly refreshing it, e.g., 
     93The program in <xref linkend="minimum.cpp"/> illustrates the dependency of CBC on 
     94  the <classname>OsiSolverInterface</classname> class. The constructor of <classname>CbcModel</classname> takes a pointer to an <classname>OsiSolverInterface</classname> (i.e., a solver). The <classname>CbcModel</classname> clones the solver, and uses its own instance of the solver. The <classname>CbcModel</classname>'s solver and the original solver (e.g., <varname>solver1</varname>) are not in sync unless the user synchronizes them. The user can always access the <classname>CbcModel</classname>'s solver through the <function>model()</function> method.  To synchronize the two solvers, explicitly refreshing the original, e.g., 
    9995 <programlisting>
    10096  solver1 = model.solver();
    10197</programlisting>
    102 
    103 For convenience, many of the OSI method's to access problem data have identical method names in  <classname>CbcModel</classname>. (It's just more convenient to type <function>model.getNumCols()</function> rather than <function>model.solver()->getNumCols()</function>). While the method names may be identical, sometimes the values they return are not, e.g., <function>getColSolution()</function>. <classname>CbcModel</classname> refreshes its solver at certain logical points. For instance, the OSI method<function>getColSolution()</function> will contain the best solution so far, while the <classname>CbcModel</classname> method may not. In this case, it is safer to use <function>CbcModel::bestSolution()</function>.
     98<classname>CbcModel</classname>'s method <function>solve()</function> returns a pointer to CBC's cloned solver.
     99</para>
     100
     101<para>
     102For convenience, many of the OSI methods to access problem data have identical method names in  <classname>CbcModel</classname>. (It's just more convenient to type <function>model.getNumCols()</function> rather than <function>model.solver()->getNumCols()</function>). The <classname>CbcModel</classname> refreshes its solver at certain logical points during the algorithm. At these points, the information from the <classname>CbcModel</classname> <varname>model</varname> will match the information from the <function>model.solver()</function>. Elsewhere, the information may vary. For instance, the OSI method <function>getColSolution()</function> will contain the best solution so far, while the <classname>CbcModel</classname> method may not. In this case, it is safer to use <function>CbcModel::bestSolution()</function>.
    104103</para>
    105104<para>
    106 All the OSI methods used in <filename>minimum.cpp</filename> have equivalent methods in <classname>CbcModel</classname>. But there are some OSI methods which are not present in CBC. For example, if  the program produced a lot of undesired output, one might add the line
     105While all the OSI methods used in <filename>minimum.cpp</filename> have equivalent methods in <classname>CbcModel</classname>, there are some OSI methods which do not. For example, if  the program produced a lot of undesired output, one might add the line
    107106</para>
    108107<programlisting>
     
    111110<para>
    112111  <!-- model.solver() returns an OSISolverInterface? -->
    113   to reduce the output. There is no <function>model.setHintParam(OsiDoReducePrint,true,OsiHintTry)</function>.
     112  to reduce the output. There is no <function>setHintParam()</function> method in <classname>CbcModel</classname>.
    114113  </para>
    115114  </section>
     
    117116  <section id="gettingsolution">
    118117  <title>
    119   Getting Solution Information Using <classname>CbcModel</classname> Methods
     118  Getting Solution Information
    120119  </title>
    121120  <para>
    122   The OSI way to check for optimality is to call <function>model.isProvenOptimal()</function>.  Also
     121  Optimality can be checked through a call to <function>model.isProvenOptimal()</function>.  Also
    123122  available are <function>isProvenInfeasible()</function>,
    124123  <function>isSolutionLimitReached()</function>,
    125124  <function>isNodeLimitReached()</function> or the feared
    126   <function>isAbandoned()</function>. You can also pick up
    127   <function>int&nbsp;status()</function> which returns 0 if finished,
    128    1 if stopped by user and 2 if difficulties. (Note: a status of 0 is returned, even if the model is proved
    129    infeasible.)
     125  <function>isAbandoned()</function>. There is also
     126  <function>int&nbsp;status()</function> which returns 0 if finished (which includes the case when the algorithm is finished because it has been proved infeasible), 1 if stopped by user, and 2 if difficulties arose.
    130127  </para>
    131128  <para>
    132   Similarly, solution values can be accessed via OSI methods.  The OSI methods pick up
    133   the current solution in the <classname>CBCModel</classname>.  The current solution will match the best solution found so far if called after <function>branchAndBound()</function> and if a solution was found.
     129  In addition to these <classname>CbcModel</classname> methods, solution values can be accessed via OSI methods.  The OSI methods pick up the current solution in the <classname>CBCModel</classname>.  The current solution will match the best solution found so far if called after <function>branchAndBound()</function> and a solution was found.
    134130  </para>
    135131  <table frame="none">
     
    160156      </entry>
    161157      <entry align="left" valign="top">
    162       The OSI version will return  best solution unless none has been found. It is safer to use <classname>CbcModel</classname> version, <function>CbcModel::bestSolution()</function>
     158      The OSI method will return the best solution found thus far, unless none has been found. It is safer to use <classname>CbcModel</classname> version, <function>CbcModel::bestSolution()</function>
    163159      </entry>
    164160    </row>
     
    204200      </entry>
    205201      <entry align="left" valign="top">
    206       Identical <classname>CbcModel</classname> version available, <function>CbcModel::getNumRows()</function>, but note that the number of rows may change due to cuts.
     202      Identical <classname>CbcModel</classname> version available, <function>CbcModel::getNumRows()</function>. Note: the number of rows can change due to cuts.
    207203      </entry>
    208204    </row>
     
    224220
    225221  <section id="setsandgets">
    226   <title>Useful Set and Get Methods in <classname>CbcModel</classname></title>
    227   <table frame="none">
     222  <title>
     223   Useful Set and Get Methods in <classname>CbcModel</classname>
     224  </title>
     225<para>
     226Most of the parameter setting in CBC is done through <classname>CbcModel</classname> methods. The most commonly used set and get methods are listed in <xref linkend="setGet"/>.
     227</para>
     228  <table frame="none" id="setGet">
    228229  <title>Useful Set and Get Methods in <classname>CbcModel</classname></title>
    229230    <tgroup cols="2">
     
    250251      </entry>
    251252      <entry align="left" valign="top">
    252       These methods tell CBC to stop after a given number of nodes or
    253       seconds or solutions (and returns these values).
     253      These set methods tell CBC to stop after a given number of nodes,
     254      seconds, or solutions is reached. The get methods return the corresponding values.
    254255      </entry>
    255256    </row>
     
    260261      </entry>
    261262      <entry align="left" valign="top">
    262       An integer variable
    263       is deemed to be at an integral value if it is no further than this tolerance
    264       away.
     263      An integer variable is deemed to be at an integral value if it is no further than this <parameter>value</parameter> (tolerance) away.
    265264      </entry>
    266265    </row>
     
    276275      <entry align="left" valign="top">
    277276      <classname>CbcModel</classname> returns if the gap between the best known solution and the best
    278       possible solution is less than this (or as a percentage or fraction).
     277      possible solution is less than this <parameter>value</parameter>, or as a percentage, or a fraction.
    279278      </entry>
    280279    </row>
     
    282281      <entry align="left" valign="top">
    283282      <function>void&nbsp;setNumberStrong(double value) </function><sbr/>
    284       <function>int&nbsp;numberStrong() const </function>
    285       </entry>
    286       <entry align="left" valign="top">
    287       Get or set the maximum number of candidates at a node to
     283      <function>int&nbsp;numberStrong() const </function> <!-- should be a "get" -->
     284      </entry>
     285      <entry align="left" valign="top">
     286      These methods set or get the maximum number of candidates at a node to
    288287      be evaluated for strong branching.
    289288      </entry>
     
    296295      <entry align="left" valign="top">
    297296      Controls the number of nodes evaluated between status prints.
    298       Print frequency has very slight overhead if small.
     297      Print frequency has a very slight overhead, if <parameter>value</parameter> is small.
    299298      </entry>
    300299    </row>
     
    304303      </entry>
    305304      <entry align="left" valign="top">
    306       Returns number of nodes search took
     305      Returns number of nodes evaluated in the search.
    307306      </entry>
    308307    </row>
     
    312311      </entry>
    313312      <entry align="left" valign="top">
    314       Returns number of rows at continuous
     313      Returns number of rows at continuous <!-- rlh: huh? -->
    315314      </entry>
    316315    </row>
     
    321320      </entry>
    322321      <entry align="left" valign="top">
    323       Returns number of integers and an array giving which ones
     322      Returns number of integer variables and an array specifying them.
    324323      </entry>
    325324    </row>
     
    331330      </entry>
    332331      <entry align="left" valign="top">
    333       Returns information on a variable.  You can use OSI methods
    334       to set these attributes (before handing to <classname>CbcModel</classname>)
     332      Returns information on variable <parameter>colIndex</parameter>. OSI methods
     333      can be used to set these attributes (before handing the model to <classname>CbcModel</classname>).
    335334      </entry>
    336335    </row>
     
    367366       </entry>
    368367      <entry align="left" valign="top">
    369       These methods give lower and upper bounds on row and column activities.
     368      These methods return the lower and upper bounds on row and column activities.
    370369      </entry>
    371370    </row>
     
    375374      </entry>
    376375      <entry align="left" valign="top">
    377       This method returns a pointer to a row copy of matrix
     376      This method returns a pointer to a row copy of matrix stored as a
    378377      <classname>CoinPackedMatrix</classname> which can be further examined.
    379378      </entry>
     
    384383      </entry>
    385384      <entry align="left" valign="top">
    386       This method returns a pointer to a column copy of matrix
     385      This method returns a pointer to a column copy of matrix stored as a
    387386      <classname>CoinPackedMatrix</classname> which can be further examined.
    388387      </entry>
     
    399398      </entry>
    400399      <entry align="left" valign="top">
    401       Returns the number of elements in the problem matrix.
     400      Returns the number of nonzero elements in the problem matrix.
    402401      </entry>
    403402    </row>
     
    420419  Impacting the Solution Process
    421420  </title>
    422   <para>
    423   The methods in <xref linkend="majorMethods"/> can have a major impact on CBC's search.. A brief description is given in the table, along with main parameters. ( The description here may not give all parameters if they are exotic.) The remainder of this documents describes some of the common usages of these methods.
    424   </para>
    425   <table frame="none" id="majorMethods">
    426   <title>Major Methods</title>
    427     <tgroup cols="2">
    428     <thead>
    429     <row>
    430     <entry>
    431     Method(s)
    432     </entry>
    433     <entry>
    434     Description
    435     </entry>
    436     </row>
    437     </thead>
    438     <tbody>
    439     <row>
    440       <entry align="left" valign="top">
    441       <function>passInPriorities(const int * priorities, bool ifNotSimpleIntegers,
    442                         int defaultValue=1000)</function>
    443       </entry>
    444       <entry align="left" valign="top">
    445       Normally this is a list of priorities (1 being highest) and the other
    446       <parameter>ifNotSimpleIntegers</parameter> being false which set priorities for all integer
    447       variables.  If two variables are unsatisfied and one has a higher priority
    448       then it is always preferred whatever its value.  This can be very powerful
    449       but also see PseudoCosts in <classname>CbcObject</classname> discussion.
    450       </entry>
    451     </row>
    452     <row>
    453       <entry align="left" valign="top">
    454       <function>addCutGenerator(CglCutGenerator *,int howOften, const char * name)</function>
    455       </entry>
    456       <entry align="left" valign="top">
    457       This is used to add a cut generator to <classname>CbcModel</classname>.  Any cut generator in CGL can be used. If <parameter>howOften</parameter> &gt; 0 then <parameter>name</parameter> will be called at root node and again every <parameter>howOften</parameter> nodes. There is an option to override and to call <parameter>name</parameter> depth 0,k,2k, etc.  If <parameter>howOften</parameter> = -1 then the code determines how effective <parameter>name</parameter>is at root node and dynamically sets <parameter>howOften</parameter>. If <parameter>howOften</parameter> = -99 then <parameter>name></parameter> is just used at root node.
    458       There is also a redundant <parameter>howOften</parameter> = -100 setting which switches <parameter>name</parameter> off. This parameter setting is useful for testing.  For usage see <filename>sample2.cpp</filename> in the <filename>COIN/Cbc/Samples</filename> directory <xref linkend="moreexamples"/> which uses the most common cut generators.
    459       </entry>
    460     </row>
    461     <row>
    462       <entry align="left" valign="top">
    463       <function>addHeuristic(CbcHeuristic *)</function>
    464       </entry>
    465       <entry align="left" valign="top">
    466       This adds one heuristic to <classname>CbcModel</classname>.See the section on <classname>CbcHeuristic</classname>  to obtain
    467       a list of available heuristics and a guide as to building new ones.
    468       </entry>
    469     </row>
    470     <row>
    471       <entry align="left" valign="top">
    472       <function>addObjects(int&nbsp;number,CbcObject&nbsp;**&nbsp;objects) </function>
    473       </entry>
    474       <entry align="left" valign="top">
    475       This adds members of the base class <classname>CbcObject</classname> to <classname>CbcModel</classname>.  See the section
    476       on <classname>CbcObject</classname> for detailed nformation.  The <parameter>objects</parameter> are cloned by the code so the
    477       user should delete them after the call to <function>addObjects</function>.  There are two
    478       main cases.  The first is when the originally created objects are left and
    479       new ones added (maybe with a higher priority);  this might be used when
    480       simple integer objects exist and Special Ordered Sets of type 1 are going
    481       to be added, which while not necessary will give extra power in branching.
    482       The second case is when the old ones are being deleted. 
    483       For usage see <filename>sos.cpp</filename> in the <filename>COIN/Cbc/Samples</filename> directory <xref linkend="moreexamples"/>.
    484       </entry>
    485     </row>
    486     <row>
    487       <entry align="left" valign="top">
    488       <function>CglPreProcess::preProcess(OsiSolverInterface &amp;)</function>
    489       </entry>
    490       <entry align="left" valign="top">
    491       This is not really part of CBC and can be used by other mixed integer
    492       solvers but it can be a useful tool.  It tries to fix variables and
    493       strengthen coefficients and also do a normal presolve.  Owing to the
    494       odd nature of integer programming it may not always reduce the time
    495       taken but is definitely worth trying.  For an example of using
    496       <function>CglPreProcess()</function> (and <function>CglPostProcess()</function>) see <filename>sample2.cpp</filename> in the CBC Samples
    497       directory <xref linkend="moreexamples"/>.
    498       </entry>
    499     </row>
    500     <row>
    501       <entry align="left" valign="top">
    502       <function>setNodeComparison(CbcCompareBase&nbsp;*)</function>
    503       </entry>
    504       <entry align="left" valign="top">
    505        This is used to invoke a non-default node comparisons
    506        in determining the next node on tree to explore. The order a tree is explored
    507        can make a large difference in runtime. Specialized comparisons are easy to implement.
    508        See the section on <classname>CbcCompare</classname>.
    509       </entry>
    510     </row>
    511     </tbody>
    512   </tgroup>
    513   </table>
    514   </section>
    515 
    516 <section id="mostAndLeastUsefulClasses">
    517  <title>
    518   Most (and Least) Useful Classes Used by CBC
    519 </title>
    520421<para>
    521 <classname>CbcModel</classname> uses other classes in CBC, some of which are virtual and may have multiple instances. Not all classes are created equal. The two tables below list the classes within <classname>CbcModel</classname> that are of most interest and of least interest.
     422<classname>CbcModel</classname> is extremely flexible and customizable. The class structure of CBC is designed to make the most commonly desired customizations of branch-and-cut possible. These include:
     423    <itemizedlist>
     424    <listitem>
     425    <simpara>
     426     selecting the next node to consider in the search tree,
     427    </simpara>
     428    </listitem>
     429    <listitem>
     430    <simpara>
     431    determining which variable to branch on,
     432    </simpara>
     433    </listitem>
     434   <listitem>
     435    <simpara>
     436    using heuristics to generate MIP-feasible solutions quickly,
     437    </simpara>
     438    </listitem>
     439   <listitem>
     440    <simpara>
     441    including cut generation when solving the LP-relaxations, and
     442    </simpara>
     443    </listitem>
     444  <listitem>
     445    <simpara>
     446    invoking customized subproblem solvers.
     447    </simpara>
     448    </listitem>
     449    </itemizedlist>
     450
     451
     452To enable this flexibility,  <classname>CbcModel</classname> uses other classes in CBC (some of which are virtual and may have multiple instances). Not all classes are created equal. The two tables below list in alphabetical order the classes used by <classname>CbcModel</classname> that are of most interest and of least interest.
    522453</para>
    523454    <table frame="none">
     
    543474      </entry>
    544475      <entry align="left" valign="top">
    545       Controls which node on tree is selected
    546       </entry>
    547       <entry align="left" valign="top">
    548       The default is <classname>CbcCompareDefault</classname>. Other comparison classes in <filename>CbcCompareActual.hpp</filename> include
    549       <classname>CbcCompareDepth</classname> and <classname>CbcCompareObjective</classname>. It is very easy for user to
    550       experiment with different comparisons.
     476      Controls which node on the tree is selected.
     477      </entry>
     478      <entry align="left" valign="top">
     479      The default is <classname>CbcCompareDefault</classname>. Other comparison classes in <filename>CbcCompareActual.hpp</filename> include <classname>CbcCompareDepth</classname> and <classname>CbcCompareObjective</classname>. Experimenting with these classes and creating new compare classes is easy.
    551480      </entry>
    552481    </row>
     
    556485      </entry>
    557486      <entry align="left" valign="top">
    558       A wrapper for <classname>CglCutGenerator</classname> with additional data to control when the cut generator is used.
    559       </entry>
    560       <entry align="left" valign="top">
    561       Other than knowing how to add a cut generator to <classname>CbcModel</classname>, there is not much the average user needs to know about this class. <!-- what's the default? -->
     487      A wrapper for <classname>CglCutGenerator</classname> with additional data to control when the cut generator is invoked during the tree search.
     488      </entry>
     489      <entry align="left" valign="top">
     490      Other than knowing how to add a cut generator to <classname>CbcModel</classname>, there is not much the average user needs to know about this class. However, sophisticated users can implement their own cut generators. <!-- what's the default? -->
    562491      </entry>
    563492    </row>
     
    567496      </entry>
    568497      <entry align="left" valign="top">
    569       Heuristic that attempts to generate valid solutions
    570       </entry>
    571       <entry align="left" valign="top">
    572       Users can get a lot of value out of coding specialized heuristics.  There can be
    573       as many different heuristics as you like. <!-- What's the default? -->
     498      Heuristic that attempts to generate valid MIP-solutions leading to good upper bounds.
     499      </entry>
     500      <entry align="left" valign="top">
     501      Specialized heuristics can dramatically improve branch-and-cut performance. As many different heuristics as desired can be used in CBC. Advanced users should consider implementing custom heuristics when tackling difficult problems. <!-- What's the default? -->
    574502      </entry>
    575503    </row>
     
    579507      </entry>
    580508      <entry align="left" valign="top">
    581       Defines what it means for a variable to be satisfied.
    582       </entry>
    583       <entry align="left" valign="top">
    584       Virtual class. The branching model used in CBC is based on the idea of an "object". An object has (i) feasible region, (ii) can be evaluated for infeaibility, (iii) can be branched on, e.g., a method of generating a branching object, which defines an up branch and a down branch and (iv) allows comparsion of the effect of branching. Instances include simple integer, simple integer with pseudocosts, SOS (type 1 and 2), and lotsizing (see CbcBranch....hpp).
     509      Defines what it means for a variable to be satisfied. Used in branching.
     510      </entry>
     511      <entry align="left" valign="top">
     512      Virtual class. CBC's concept of branching is based on the idea of an "object". An object has (i) a feasible region, (ii) can be evaluated for infeasibility, (iii) can be branched on, e.g., a method of generating a branching object, which defines an up branch and a down branch, and (iv) allows comparsion of the effect of branching. Instances of objects include <classname>CbcSimpleInteger</classname>, <classname>CbcSimpleIntegerPseudoCosts</classname>, <classname>CbcClique</classname>, <classname>CbcSOS</classname> (type 1 and 2), <classname>CbcFollowOn</classname>, and <classname>CbcLotsize</classname>.
    585513      </entry>
    586514    </row>
     
    601529  </tgroup>
    602530  </table>
    603 
     531<para>
    604532There is not much about the classes listed in <xref linkend="least"/> that the average user needs to know about.
     533</para>
    605534    <table frame="none" id="least">
    606535  <title>Classes Used by CbcModel - Least Useful</title>
     
    651580      </entry>
    652581      <entry align="left" valign="top">
    653       Controlled via <classname>CbcModel</classname> parameters. <!-- Default? -->
     582      Controlled via <classname>CbcModel</classname> parameters. Information from <classname>CbcNode</classname> can be useful in creating customized node selection rules. <!-- Default? -->
    654583      </entry>
    655584    </row>
Note: See TracChangeset for help on using the changeset viewer.