source: trunk/Docs/basicmodelclasses.xml @ 405

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

Initial strawman version of user guide in DocBook? XML (v4.2) format

  • Property svn:eol-style set to native
  • Property svn:keywords set to Author Date Id Revision
File size: 3.8 KB
Line 
1<?xml version="1.0" encoding="ISO-8859-1"?>
2  <chapter>
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 beyond the current scope of this document. 
17  </para>
18  <mediaobject>
19    <imageobject>
20      <imagedata fileref="figures/clpbasicmodelhier.gif" format="GIF"/>
21    </imageobject>
22    <caption>
23      <para>
24        CLP Basic Classes
25      </para>
26    </caption>
27  </mediaobject>
28  <para>
29  ClpModel has all problem data.  There may be a few pieces of data which could
30  be elsewhere but which are permanent and so they are here.  The main example
31  of this is a status array which makes most sense for Simplex but has use for
32  crossing over from any solution.
33  </para>
34  <para>
35  ClpSimplex inherits from ClpModel, as does ClpInterior.  Extra data is specific
36  to the simplex algorithm and can be transient  e.g., scaling arrays.  Normally
37  a user will just be dealing with the ClpSimplex class and not with the ClpModel
38  class.
39  </para>
40  <para>
41  From the point of view of most Simplex users, the ClpModel and ClpSimplex
42  classes are all you need to know about.  There are algorithm-specific classes
43  which inherit from ClpSimplex (e.g., ClpSimplexDual and ClpSimplexPrimal), but
44  they have no member data and very rarely need be visible to user.  Normally,
45  after instantiating an object of type ClpSimplex, the user would type
46  model.dual() to invoke dual algorithm.
47  </para>
48  </section>
49  <section>
50  <title>
51  First example
52  </title>
53  <para>
54  Okay, first sample.  It is short enough to present in full (and to not be too
55  frightening!):
56  </para>
57  <programlisting>
58// Copyright (C) 2002, International Business Machines
59// Corporation and others.  All Rights Reserved.
60
61#include &quot;ClpSimplex.hpp&quot;
62int main (int argc, const char *argv[])
63{
64  ClpSimplex  model;
65  int status;
66  if (argc&lt;2)
67    status=model.readMps(&quot;../../Mps/Sample/p0033.mps&quot;);
68  else
69    status=model.readMps(argv[1]);
70  if (!status) {
71    model.primal();
72  }
73  return 0;
74}   
75  </programlisting>
76  <para>
77  This sample program creates a default ClpSimplex model, reads an mps file,
78  and if there are no errors, solves it using the primal algorithm.  Simple, but
79  not terribly useful: there is no way to see the result of the solve.  There are
80  two main results -- a status saying what happened, and then arrays filled with
81  the solution values.
82  </para>
83  </section>
84  <section>
85  <title>
86  Getting at the solution
87  </title>
88  <para>
89  It is often the case with CLP that there is more than one way to do something.
90  This is a consequence of CLP's mixed heritage as a child of OSL and a cousin of
91  OSI.  Finding the status exemplifies this situation.
92  </para>
93  <para>
94  The OSI way to check for optimality is to call model.isProvenOptimal().  Also
95  available are isProvenPrimalInfeasible(), isProvenDualInfeasible(),
96  isPrimalObjectiveLimitReached(), isDualObjectiveLimitReached(),
97  isIterationLimitReached() or the feared isAbandoned().  Should one prefer the
98  OSL way of doing things, model.status() returns as it would in OSL-land, so 0
99  means optimal, 1 means  primal infeasible etc.
100  </para>
101  <para>
102  Similarly, to pick up the solution values, we can inhabit the virtuous Osi-land or the
103  not-quite-so-virtuous Clp-land.  By this it is meant that there are const and
104  non-const forms of arrays.  It is easier to deal with the non-const versions,
105  so most of the later elaborate algorithms use them.
106  </para>
107  </section>
108  </chapter>
Note: See TracBrowser for help on using the repository browser.