<?xml version="1.0" encoding="ISO-8859-1"?>
  <chapter id="basicmodelclasses">
  <title>
  Basic Model Classes
  </title>
  <section id="hierarchy">
  <title>
  Hierarchy
  </title>
  <para>
  The basic CLP model class hierarchy is simple.  The top three levels of the 
  hierarchy are depicted in the figure below. The first two levels  (i.e.
  <classname>ClpModel</classname>, <classname>ClpSimplex</classname>,
  <classname>ClpInterior</classname>) contain all the problem data which define
  a model (that is, a problem instance). The third level contains most of the 
  algorithmic aspects of CLP.  There is a fourth level (for models with more general
  objectives than linear ones), but a description of it is beyond the current scope
  of this document.
  </para>
  <mediaobject>
    <!-- Caption doesn't line-up nicely in HTML, leave out for now
    <caption align="top">
      <para>
  	CLP Basic Classes
      </para>
    </caption>
    -->
    <imageobject>
      <imagedata fileref="figures/clpbasicmodelhier.gif" format="GIF"/>
    </imageobject>
  </mediaobject>
  <!-- Not appropriate here and not entirely correct as worded!
  <para>
  The class <classname>ClpModel</classname> contains most of the  problem data.
  There may be a few pieces of data which could be elsewhere but which are
  permanent and so they are here.  The main example of this is a status array:
  it makes the most sense for Simplex but has use for crossing over from any
  solution.
  </para>
  <para>
  <classname>ClpSimplex</classname> inherits from
  <classname>ClpModel</classname>, as does <classname>ClpInterior</classname>.
  Extra data is specific to the Simplex Algorithm and can be transient, e.g.
  scaling arrays.  Normally a user will just be dealing with the
  <classname>ClpSimplex</classname> class and not with the
  <classname>ClpModel</classname> class.
  </para>
  -->
  <para>
  Most Simplex users need only concern themselves with the classes
  <classname>ClpModel</classname> and <classname>ClpSimplex</classname>.  There
  are algorithm-specific classes which inherit from
  <classname>ClpSimplex</classname> (e.g. <classname>ClpSimplexDual</classname>
  and <classname>ClpSimplexPrimal</classname>), but they have no member data and
  rarely need be visible to the user.  These  classes are cast at algorithm
  time.  So, for example, after instantiating an object
  <userinput>model</userinput> of type <classname>ClpSimplex</classname>,
  a user only need call <userinput>model.dual()</userinput> to invoke the dual
  simplex method.
  </para>
  </section>
  <section id="firstexample">
  <title>
  First Example
  </title>
  <para>
  Below is our first CLP sample program.  It is short enough to present in full
  (this code can be found in the CLP Samples directory, see
  <xref linkend="moreexamples"/>).  Most of the remaining examples in this Guide
  will take the form of small code fragments.
  </para>
  <example>
  <title>minimum.cpp</title>
  <programlisting>
  <![CDATA[  
// Copyright (C) 2002, International Business Machines
// Corporation and others.  All Rights Reserved.

#include "ClpSimplex.hpp"
int main (int argc, const char *argv[])
{
  ClpSimplex  model;
  int status;
  if (argc<2)
    status=model.readMps("../../Mps/Sample/p0033.mps");
  else
    status=model.readMps(argv[1]);
  if (!status) {
    model.primal();
  }
  return 0;
} 
  ]]>   
  </programlisting>
  </example>
  <para>
  This sample program creates a  <classname>ClpSimplex</classname> model,
  reads an MPS file, and if there are no errors, solves it using the primal
  algorithm.  The program is easy to follow, but it is not terribly useful:
  it does not attempt to inspect the results of the solve.  There are two main
  kinds of results: a &quot;status&quot; describing what happened to the model
  during the solve, and arrays filled with solution values.  Both will be
  addressed in this chapter.
  </para>
  </section>
  <section id="gettingsolution">
  <title>
  Getting at the Solution
  </title>
  <para>
  It is often the case with CLP that there is more than one way to do something.
  This is a consequence of CLP's mixed heritage as a child of 
  <ulink url="http://www-306.ibm.com/software/data/bi/osl/">OSL</ulink>
  and a cousin of <ulink url="http://www.coin-or.org/faqs.html#OSI">OSI</ulink>.
  Finding the status of a model exemplifies this situation.
  </para>
  <para>
  The OSI way to check for optimality is to call model.isProvenOptimal().  Also
  available are <function>isProvenPrimalInfeasible()</function>,
  <function>isProvenDualInfeasible()</function>,
  <function>isPrimalObjectiveLimitReached()</function>,
  <function>isDualObjectiveLimitReached()</function>,
  <function>isIterationLimitReached()</function> or the feared
  <function>isAbandoned()</function>.  Should one prefer the OSL way of doing
  things, model.status() returns as it would in OSL, so 0 means optimal,
  1 means  primal infeasible etc.
  </para>
  <para>
  Similarly, to pick up the solution values, one could inhabit the virtuous
  world of OSI, or the not-quite-so-virtuous world of OSL and &quot;pure&quot;
  CLP.  By this it is meant that const and non-const forms of arrays are used,
  respectively.  It is easier to deal with the non-const versions, so most of
  the elaborate algorithms in CLP and its
  <link linkend="moresamples">Samples</link> use them.
  </para>
  <table frame="none">
  <title>
  Methods for getting solution information
  </title>
  <tgroup cols="3">
  <thead>
    <row>
      <entry>
      Purpose
      </entry>
      <entry>
      OSI-style (virtuous)
      </entry>
      <entry>
      CLP-style (less virtuous)
      </entry>
    </row>
  </thead>
  <tbody>
    <row>
      <entry align="left" valign="top">
      Primal column solution
      </entry>
      <entry align="left" valign="top">
      <function>const double * getColSolution()</function>
      </entry>
      <entry align="left" valign="top">
      <function>double * primalColumnSolution()</function>
      </entry>
    </row>
    <row>
      <entry align="left" valign="top">
      Dual row solution
      </entry>
      <entry align="left" valign="top">
      <function>const double * getRowPrice()</function>
      </entry>
      <entry align="left" valign="top">
      <function>double * dualColumnSolution()</function>
      </entry>
    </row>
    <row>
      <entry align="left" valign="top">
      Primal row solution
      </entry>
      <entry align="left" valign="top">
      <function>const double * getRowActivity()</function>
      </entry>
      <entry align="left" valign="top">
      <function>double * primalRowSolution()</function>
      </entry>
    </row>
    <row>
      <entry align="left" valign="top">
      Dual row solution
      </entry>
      <entry align="left" valign="top">
      <function>const double * getReducedCost()</function>
      </entry>
      <entry align="left" valign="top">
      <function>double * dualColumnSolution()</function>
      </entry>
    </row>
    <row>
      <entry align="left" valign="top">
      Number of rows in model
      </entry>
      <entry align="left" valign="top">
      <function>int getNumRows()</function>
      </entry>
      <entry align="left" valign="top">
      <function>int numberRows()</function>
      </entry>
    </row>
    <row>
      <entry align="left" valign="top">
      Number of columns in model
      </entry>
      <entry align="left" valign="top">
      <function>int getNumCols()</function>
      </entry>
      <entry align="left" valign="top">
      <function>int numberColumns()</function>
      </entry>
    </row>
  </tbody>
  </tgroup>
  </table>

  <para>
  The reader  may have noted a preference for &quot;number&quot; over
  &quot;num&quot; and &quot;column&quot; over &quot;col&quot;.  This may be a
  reaction to when one of the authors was young and 5 or 6 letters was the
  maximum in FORTRAN for any name or to early days with OSL when seven characters
  were allowed but the first three had to be &quot;ekk&quot;!  
  </para>
  <para>
  Using the above-listed functions, our
  <link linkend="firstexample">initial example</link> might be continued as follows:
  </para>
  <example>
  <title>
  Possible extension of minimum.cpp
  </title>
  <programlisting>
  <![CDATA[  
  int numberRows = model.numberRows();
  double * rowPrimal = model.primalRowSolution();
  double * rowDual = model.dualRowSolution();

  int iRow;

  for (iRow=0;iRow<numberRows;iRow++) 	
    printf("Row %d, primal %g, dual %g\n",iRow,
	rowPrimal[iRow],rowDual[iRow]);
	
  int numberColumns = model.numberColumns();
  double * columnPrimal = model.primalColumnSolution();
  double * columnDual = model.dualColumnSolution();

  int iColumn;

  for (iColumn=0;iColumn<numberColumns;iColumn++) 	
    printf("Column %d, primal %g, dual %g\n",iColumn,
	columnPrimal[iColumn],columnDual[iColumn]);
  ]]>
  </programlisting>
  </example>
  <para>
  This code sample would pretty-print information about the model's primal and
  dual solutions.  How to additionally print row and column names is
  illustrated in the <filename>defaults.cpp</filename> file in the
  &quot;Samples&quot; directory (the Samples are properly addressed
  in <xref linkend="moreexamples" />).  This sample is also useful as it
  explicitly performs default actions (e.g. it sets the primal feasiblility
  tolerance value to the default value).
  </para>
  <para>
  The remainder of this chapter will show  more of the basic CLP tasks a user
  might wish to perform.  Apart from presolve we will only be looking at actions
  which can be performed when including the single header file
  <filename>COIN/Clp/include/ClpSimplex.hpp</filename>.
  </para>
  </section>
  <section id="buildandmodify">
  <title>
  Building and Modifying a Model
  </title>
  <para>
  Rather than reading a model from an MPS file we can load a model from arrays
  in memory.  There are various <function>loadProblem</function> methods which
  are similar to those in OSI.  It is easy to add more such methods to CLP if the need arises.
  </para>
  <para>We can copy in integer information by 
  <function>copyInIntegerInformation(const&nbsp;char&nbsp;*&nbsp;array)</function> where array
  is 0 or 1 to say integer and we can drop existing information by
  <function>deleteIntegerInformation()</function>.  There are various ways of
  changing the size of a model.  The simplest is by the use of the method
  <function>resize(newNumberRows,newNumberColumns)</function> - this will either
  truncate the model or add &quot;default&quot; rows or columns - a default row
  has lower bound of -infinity and upper bound of +infinity, while a default
  column has zero cost, zero lower bound and an upper bound of +infinity.
  </para>
  <para>
  Normally we would use <function>deleteRows</function>,
  <function>addRows</function>, <function>deleteColumns</function> and
  <function>addColumns</function>, where the <function>add</function> methods
  will also add in the elements.  A potentially very useful way of modifying a model is strictly a
  constructor.  Given a large model and a list of rows and a list of columns it
  constructs the model as a subset of the large model.  It is possible to change
  the order of the columns/rows and to duplicate columns/rows.  So a list of
  columns 4,4,1,0 will create a new model where the first two columns are copies
  of column 4 in original model and the next two are the first two of original
  model in reverse order.  This can be useful to form a model with piecewise
  linear costs by duplicating columns and then modifying bounds and costs.
  </para>
  </section>
  <section id="tolerances">
  <title>Tolerances</title>
  <para>
  There are set and get methods for tolerances, for example,
  <function>double&nbsp;primalTolerance()</function> and
  <function>setPrimalTolerance(double)</function>.  Assuming that one has a
  minimization problem, an individual variable is deemed primal feasible if it
  is less than the tolerance referred to by these methods below its lower bound
  and less than it above its upper bound.  Similarly for dual tolerances, a
  variable is deemed to be dual feasible if its reduced cost is greater than
  minus the tolerance or its distance to the upper bound is less than primal
  tolerance and the reduced cost is less than plus the tolerance or the distance
  to lower bound is less than primal tolerance.  In short, this is complementarity
  conditions adadpted for tolerances and simple lower and upper bounds.(Note
  that the above was stated as for minimization; signs are reversed for
  maximization.)
  </para>
  </section>
  <section id="setsandgets">
  <title>Some Useful Set and Get Methods</title>
  <table frame="none">
  <title>Some Useful Set and Get Methods</title>
    <tgroup cols="2">
    <thead>
    <row>
    <entry>
    Method(s)
    </entry>
    <entry>
    Description
    </entry>
    </row>
    </thead>
    <tbody>
    <row>
      <entry align="left" valign="top">
      <function>setMaximumIterations(int value)</function><sbr/>
      <function>int maximumIterations()</function><sbr/>
      <function>setMaximumSeconds(double value)</function><sbr/>
      <function>double maximumIterations()</function>
      </entry>
      <entry align="left" valign="top">
      These methods tell CLP to stop after a given number of iterations or
      seconds (and returns these values).
      </entry>
    </row>
    <row>
      <entry align="left" valign="top">
      <function>double&nbsp;objectiveValue()</function>
      </entry>
      <entry align="left" valign="top">
      This method returns the objective value.
      </entry>
    </row>
    <row>
      <entry align="left" valign="top">
      <function>const&nbsp;double&nbsp;*&nbsp;getObjCoefficients()</function><sbr/>
      <function>double&nbsp;*&nbsp;objective()</function>
      </entry>
      <entry align="left" valign="top">
      These methods return the objective coefficients.
      </entry>
    </row>
    <row>
      <entry align="left" valign="top">
      <function>const&nbsp;double&nbsp;*&nbsp;getRowLower()</function><sbr/>
      <function>double&nbsp;*&nbsp;rowLower()</function><sbr/>
      <function>const&nbsp;double&nbsp;*&nbsp;getRowUpper()</function><sbr/>
      <function>double&nbsp;*&nbsp;rowUpper()</function><sbr/>
      <function>const&nbsp;double&nbsp;*&nbsp;getColLower()</function><sbr/>
      <function>double&nbsp;*&nbsp;columnLower()</function><sbr/>
      <function>const&nbsp;double&nbsp;*&nbsp;getColUpper()</function><sbr/>
      <function>double&nbsp;*&nbsp;columnUpper()</function>
      </entry>
      <entry align="left" valign="top">
      These methods give lower and upper bounds on row and column activities.
      </entry>
    </row>
    <row>
      <entry align="left" valign="top">
      <function>double * infeasibilityRay()</function><sbr/>
      <function>double * unboundedRay()</function>
      </entry>
      <entry align="left" valign="top">
      If the problem was primal or dual infeasible, these methods will give a
      pointer to a ray proving infeasibility.
      </entry>
    </row>
    <row>
      <entry align="left" valign="top">
      <function>CoinPackMatrix * matrix()</function>
      </entry>
      <entry align="left" valign="top">
      There are more options as the user has great flexibility in how the problem
      matrix is stored, but the default matrix class is
      <classname>CoinPackedMatrix</classname> (see 
      <xref linkend="matrixclasses"/>).
      So we have that this method returns a pointer to a
      <classname>CoinPackedMatrix</classname> which can be further manipulated.
      </entry>
    </row>
    <row>
      <entry align="left" valign="top">
      <function>CoinBigIndex&nbsp;getNumElements()</function>
      <footnote>
        <para>
	<type>CoinBigIndex</type> is a <function>typedef</function> which in
	most cases is the same as <type>int</type>.
	</para>
      </footnote>
      </entry>
      <entry align="left" valign="top">
      Returns the number of elements in the problem matrix.
      </entry>
    </row>
    <row>
      <entry align="left" valign="top">
      <function>void setOptimizationDirection(double&nbsp;value)</function><sbr/>
      <function>double optimizationDirection()</function>
      </entry>
      <entry align="left" valign="top">
      These methods set and get the objective sense.  The parameter
      <parameter>value</parameter> should be +1 to minimize, -1 to maximize,
      and 0 to ignore.
      </entry>
    </row>
    </tbody>
  </tgroup>
  </table>
  </section>
  <section id="simplexspecific">
  <title>
  Simplex-specific Methods
  </title>
  <para>
  Some of the most commonly-used methods when working with Simplex are listed in
  the table below.
  </para>
  <table frame="none">
  <title>Common Simplex-specific methods</title>
    <tgroup cols="2">
    <thead>
    <row>
    <entry>
    Method(s)
    </entry>
    <entry>
    Description
    </entry>
    </row>
    </thead>
    <tbody>
    <row>
      <entry align="left" valign="top">
      <function>primal(int&nbsp;mode=0)</function>
      </entry>
      <entry align="left" valign="top">
      This applies the primal algorithm. If <parameter>mode</parameter> is
      set to the default of 0, then the method uses the status variables to
      determine basis and solution. If <parameter>mode</parameter> is 1 then
      the method does a values pass so variables not in basis are given their
      current values and one pass of variables is done to clean up the basis
      with an equal or better objective value.
      </entry>
    </row>
    <row>
      <entry align="left" valign="top">
      <function>dual(int&nbsp;mode=0)</function>
      </entry>
      <entry align="left" valign="top">
      This applies the dual algorithm. if <parameter>mode</parameter> is set
      to the default of 0, then the method uses the status variables to
      determine basis and solution.  If <parameter>mode</parameter> is 1 then
      the method uses input duals and does a values pass so one pass of basic
      variables is done to clean up the duals with an equal or better objective
      value.
      </entry>
    </row>
    <row>
      <entry align="left" valign="top">
      <function>scaling(int&nbsp;mode=1)</function>
      </entry>
      <entry align="left" valign="top">
      This method toggles scaling on (<parameter>mode</parameter> set to 1)
      and off (<parameter>mode</parameter> set to 0).
      </entry>
    </row>
    <row>
      <entry align="left" valign="top">
      <function>int&nbsp;crash(double&nbsp;gap,int&nbsp;mode)</function>
      </entry>
      <entry align="left" valign="top">
      This method attemps to improve on an all slack basis.
      For dual this will move variables to the dual feasible bound
      if the gap between bounds is less than <parameter>gap</parameter>.  Setting
      <parameter>mode</parameter> to 0 guesses which algorithm is better, while
      a value of 1 or 2 will result in more work being done.  The return code is
      0 if the basis was not slacks in first case, it is negative if dual is
      preferred or positive if primal.  &plusmn;1 means an all slack basis seemed
      best, while &plusmn;2 means some work was done. 
      </entry>
    </row>
    <row>
      <entry align="left" valign="top">
      <function>perturb(int&nbsp;mode)</function>
      </entry>
      <entry align="left" valign="top">
      This method toggles perturbation on (<parameter>mode</parameter> set to 1)
      and off (<parameter>mode</parameter> set to 0).  It should be considered
      a work in progress, although on some problems it gives very good results.
      </entry>
    </row>
    <row>
      <entry align="left" valign="top">
      <function>factorizationFrequency()</function><sbr/>
      <function>setFactorizationFrequency(int&nbsp;value)</function>
      </entry>
      <entry align="left" valign="top">
      These are &quot;get&quot; and &quot;set&quot; methods for the basis matrix
      factorization frequency.  The default is to refactor every 200 iterations,
      but it may make more sense to use something such as 100 + the number of
      rows divided by 50.
      </entry>
    </row>
    <row>
      <entry align="left" valign="top">
      <function>dualBound()</function><sbr/>
      <function>setDualBound(double&nbsp;value)</function>
      </entry>
      <entry align="left" valign="top">
      These are &quot;get&quot; and &quot;set&quot; methods for the
      &quot;dual&nbsp;bound&quot;.  The CLP dual algorithm declares all problems
      to be dual feasible by putting non-basic variables to correct bounds for
      the reduced cost.  If the gap between the bounds is too big then it
      pretends the gap is only the value specified by this set method.
      In essence, this gives a composite dual rather than a pure
      Phase&nbsp;I- Phase&nbsp;II method.
      </entry>
    </row>
    <row>
      <entry align="left" valign="top">
      <function>infeasibilityCost()</function><sbr/>
      <function>setInfeasibilityCost(double&nbsp;value)</function>
      </entry>
      <entry align="left" valign="top">
      These are the primal analogs to the &quot;dual&nbsp;bound&quot; methods.
      </entry>
    </row>
    <row>
      <entry align="left" valign="top">
      <function>numberPrimalInfeasibilities()</function><sbr/>
      <function>sumPrimalInfeasibilities()</function>
      </entry>
      <entry align="left" valign="top">
      After a solve, there may be infeasibilities.  These methods serve to
      check for said infeasibilities.  One could check the solution explicitly
      as well.  For a code fragement illustrating this, see
      <xref linkend="presolveexample"/>.
      </entry>
    </row>
    </tbody>
  </tgroup>
  </table>
  </section>
  <section id="presolve">
  <title>
  Presolve
  </title>
  <para>
  The header file for the use of CLP's presolve functionality is
  <filename>COIN/Clp/include/Presolve.hpp</filename>.  The sample program below
  illustrates some of the possibilities offered by CLP's presolve:
  </para>
  <example id="presolveexample">
  <title>Presolve code fragment</title>
  <programlisting>
#include "ClpSimplex.hpp"
#include "ClpPresolve.hpp"
int main (int argc, const char *argv[])
{
  ClpSimplex model; 
  model.readMps("../../Mps/Sample/p0033.mps"); // initialized by readMps or whatever 
  ClpPresolve presolveInfo; 
  ClpSimplex * presolvedModel = presolveInfo.presolvedModel(model); 
  // at this point we have original model and a new model.  The  information
  // on the operations done is in presolveInfo 
  if (presolvedModel) { 
    // was not found to be infeasible - so lets solve 
    // if presolvedModel was NULL then it was primal infeasible and ... 
    presolvedModel->dual(); // or whatever else we wish to do 
    presolveInfo.postsolve(true);  // the true updates status arrays in original       
    /* If the presolved model was optimal then so should the 
       original be.           
       We can use checkSolution and test feasibility */ 
    model.checkSolution();         
    if (model.numberDualInfeasibilities()|| 
	model.numberPrimalInfeasibilities()) 
      printf("%g dual %g(%d) Primal %g(%d)\n", 
	     model.objectiveValue(), 
	     model.sumDualInfeasibilities(), 
	     model.numberDualInfeasibilities(), 
	     model.sumPrimalInfeasibilities(), 
	     model.numberPrimalInfeasibilities()); 
    // Due to tolerances we can not guarantee that so you may wish to throw in
    model.primal(1); 
  }
}   
  </programlisting>
  </example>
  <para>
  Presolve has a few more options which can be found in the header file, for
  example whether to treat as an integer problem or whether to keep row and
  column names.
  </para>
  </section>
  <section id="statusarray">
  <title>Status Array</title>
  <para>
  The astute reader may have noticed that the status array has been mentioned
  once or twice.  The beginning user will not need to look at it   Nevertheless,
  for completeness the status of a variable can be found and set as shown below.
  The possible state of a variable are listed in the following table (each may
  have to be preceded by ClpSimplex::):
  </para>
  <table frame="none">
  <title>Possible states of a variable</title>
    <tgroup cols="2">
      <thead>
        <row>
	  <entry>
	  <type>Status</type><footnote><para><type>Status</type>
	    is an enumeration.</para></footnote>
	  </entry>
	  <entry>
	  Description
	  </entry>
	</row>
      </thead>
      <tbody>
        <row>
	  <entry align="left" valign="top">
	  <constant>basic</constant>
	  </entry>
	  <entry align="left" valign="top">
	  In basis
	  </entry>
        </row>
        <row>
	  <entry align="left" valign="top">
	  <constant>isFree</constant>
	  </entry>
	  <entry align="left" valign="top">
	  Not in basis, has infinite bounds
	  </entry>
        </row>
        <row>
	  <entry align="left" valign="top">
	  <constant>isFixed</constant>
	  </entry>
	  <entry align="left" valign="top">
	  Not in basis, bounds are equal
	  </entry>
        </row>
        <row>
	  <entry align="left" valign="top">
	  <constant>atUpperBound</constant>
	  </entry>
	  <entry align="left" valign="top">
	  At upper bound, not in basis
	  </entry>
        </row>
        <row>
	  <entry align="left" valign="top">
	  <constant>atLowerBound</constant>
	  </entry>
	  <entry align="left" valign="top">
	  At lower bound, not in basis
	  </entry>
        </row>
        <row>
	  <entry align="left" valign="top">
	  <constant>superBasic</constant>
	  </entry>
	  <entry align="left" valign="top">
	  Between bounds, but not basic or free
	  </entry>
        </row>
      </tbody>
    </tgroup>
  </table>
  <para>
  To get or set the status of a variable is a simple task:
  </para>
  <programlisting>
  // Get row status...
  Status status=model.getRowStatus(sequenceNumber)
  // ... or get column status.
  Status status=model.getColumnStatus(sequenceNumber)
  // Set row status to basic (for example)...
  model.setRowStatus(sequenceNumber,ClpSimplex::basic)
  // ... or column status to basic.
  model.setColumnStatus(sequenceNumber,ClpSimplex::basic)
  </programlisting>
  </section>
  </chapter>