source: stable/1.10/Clp/doc/moresamples.xml @ 1351

Last change on this file since 1351 was 754, checked in by andreasw, 15 years ago

first version
  • Property svn:eol-style set to native
  • Property svn:keywords set to Author Date Id Revision
File size: 15.4 KB
Line 
1<?xml version="1.0" encoding="ISO-8859-1"?>
2<chapter id="moreexamples">
3<title>
4More Samples
5</title>
6<section>
7<title>CLP's Samples Directory</title>
8<para>
9The CLP dsitribution includes a number of <filename>.cpp</filename> sample files.
10Users are encouraged to use them as starting points for their own CLP projects.
11The files can be found in the <filename>&clpsamplesdir;</filename> directory.
12For the latest information on compiling and running these samples, please see
13the file <filename>&clpsamplesdir;INSTALL</filename>.  Below is a list of
14some of the most useful sample files with a short description for each file.
15</para>
16<table frame="none">
17  <title>Basic Samples</title>
18  <tgroup cols="2">
19    <thead>
20      <row>
21        <entry align="left" valign="bottom">
22        Source file&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
23        </entry>
24        <entry align="left" valign="bottom">
25        Description
26        </entry>
27      </row>
28    </thead>
29    <tbody>
30      <row>
31        <entry align="left" valign="top">
32        &minimumcpp;
33        </entry>
34        <entry align="left" valign="top">
35        This is a CLP &quot;Hello, world&quot; program.  It reads a problem
36        from an MPS file, and solves the problem.
37        [<link linkend="minimumcppdesc">More...</link>]
38        </entry>
39      </row>
40      <row>
41        <entry align="left" valign="top">
42        &defaultscpp;
43        </entry>
44        <entry align="left" valign="top">
45        This is one of the simpler driver programs available.  It sets
46        tolerances to defaults and is a good place to find straightforward uses
47        of &quot;set&quot; and  &quot;get&quot; methods.  It also prints out full
48        MPS-like solutions.
49        [<link linkend="defaultscppdesc">More...</link>]
50        </entry>
51      </row>
52      <row>
53        <entry align="left" valign="top">
54        &drivercpp;
55        </entry>
56        <entry align="left" valign="top">
57        This is designed to be a file that a user could modify to get a useful
58        driver program for his or her project.  In particular, it demonstrates
59        the use of CLP's  presolve functionality.
60        [<link linkend="drivercppdesc">More...</link>]
61        </entry>
62      </row>
63      <row>
64        <entry align="left" valign="top">
65        &networkcpp;
66        </entry>
67        <entry align="left" valign="top">
68        This shows the use of non-standard matrices and how to load a problem
69        without the use of MPS files.
70        [<link linkend="networkcppdesc">More...</link>]
71        </entry>
72      </row>
73      <row>
74        <entry align="left" valign="top">
75        &testbarriercpp;
76        </entry>
77        <entry align="left" valign="top">
78        This is a basic driver file for the barrier method of CLP, similar to
79        &minimumcpp;.  The barrier method is not currently addressed in this
80        guide.
81        [<link linkend="testbarriercppdesc">More...</link>]
82        </entry>
83      </row>
84    </tbody>
85  </tgroup>
86</table>
87<table frame="none">
88  <title>Advanced Samples</title>
89  <tgroup cols="2">
90    <thead>
91      <row>
92        <entry align="left" valign="bottom">
93        Source file&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
94        </entry>
95        <entry align="left" valign="bottom">
96        Description
97        </entry>
98      </row>
99    </thead>
100    <tbody>
101      <row>
102        <entry align="left" valign="top">
103        &driver2cpp;
104        </entry>
105        <entry align="left" valign="top">
106        This sample, in addition to some tasks common to other samples, does
107        some advanced message handling and presolve.
108        </entry>
109      </row>
110      <row>
111        <entry align="left" valign="top">
112        &dualcutscpp;
113        </entry>
114        <entry align="left" valign="top">
115        This sample implements a method of treating a problem as a collection
116        of cuts.
117        </entry>
118      </row>
119      <row>
120        <entry align="left" valign="top">
121        &decomposecpp;
122        </entry>
123        <entry align="left" valign="top">
124        This does full Dantzig-Wolfe decomposition.  It illustrates
125        the use of many models, adding columns, et cetera.
126        </entry>
127      </row>
128      <row>
129        <entry align="left" valign="top">
130        &sprintcpp;
131        </entry>
132        <entry align="left" valign="top">
133        This solves a long, thin problem by solving smaller subsets.  It is a
134        simplified version of work done by one of the authors on aircrew
135        scheduling problems.  It shows the use of two models and their
136        synchronization.  A more general version can be found in
137        <filename>COIN/Clp/ClpSolve.cpp</filename>
138        </entry>
139      </row>
140      <row>
141        <entry align="left" valign="top">
142        &sprint2cpp;
143        </entry>
144        <entry align="left" valign="top">
145        This is similar to <filename>sprint.cpp</filename> but is designed for
146        solving large problems with little choice.  The idea is that if
147        relatively few variables are fixed, presolve can greatly reduce the
148        problem size so that a series of solves can get close to the optimal
149        solution much faster than would a na&iuml;ve solve of the full problem.
150        </entry>
151      </row>
152    </tbody>
153  </tgroup>
154</table>
155<para>
156The remaining Samples listed here are considered unsupported in that they are of
157a more esoteric nature and are sometimes contributed as a result of an
158individual's request.  The are to be found in
159<filename>&clpsamplesdir;Contributed</filename>.
160</para>
161<table frame="none">
162  <title>Unsupported Samples</title>
163  <tgroup cols="2">
164    <thead>
165      <row>
166        <entry align="left" valign="bottom">
167        Source file&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
168        </entry>
169        <entry align="left" valign="bottom">
170        Description
171        </entry>
172      </row>
173    </thead>
174    <tbody>
175      <row>
176        <entry align="left" valign="top">
177        &testbasiscpp;
178        </entry>
179        <entry align="left" valign="top">
180        This sample takes a problem, changes any inequality constraints to
181        equality constraints, solves the problem, and creates the optimal basis.
182        </entry>
183      </row>
184      <row>
185        <entry align="left" valign="top">
186        &testgubcpp;
187        </entry>
188        <entry align="left" valign="top">
189        This sample illustrates the use of the GUB (&quot;Generalized Upper
190        Bound&quot;) technique.
191        </entry>
192      </row>
193      <row>
194        <entry align="left" valign="top">
195        &ekkcpp;
196        </entry>
197        <entry align="left" valign="top">
198        This sample can be used to compare CLP and OSL.  It uses an additional
199        file in the Samples directory, <filename>ekk_interface.cpp</filename>.
200        These sample files are not likely to be interesting to new CLP users
201        who do not have experience with OSL.
202        </entry>
203      </row>
204      <row>
205        <entry align="left" valign="top">
206        &hellocpp;
207        </entry>
208        <entry align="left" valign="top">
209        This sample creates a text-based picture of a matrix on screen
210        (limited to an 80x80 matrix).  It's not terribly useful but it does
211        illustrate one way to step through the elements of a matrix.
212        </entry>
213      </row>
214      <row>
215        <entry align="left" valign="top">
216        &piececpp;
217        </entry>
218        <entry align="left" valign="top">
219        This sample takes a matrix read in by <classname>CoinMpsIo</classname>
220        (can be used to read in MPS files without a solver), deletes every
221        second column and solves the resulting problem.
222        </entry>
223      </row>
224      <row>
225        <entry align="left" valign="top">
226        &usevolumecpp;
227        </entry>
228        <entry align="left" valign="top">
229        The Volume Algorithm is another solver available as part of the COIN-OR
230        distribution.  This sample shows how to use the Volume Algorithm with
231        CLP.
232        </entry>
233      </row>
234    </tbody>
235  </tgroup>
236</table>
237<!-- subsection -->
238<section id="minimumcppdesc">
239<title>minimum.cpp</title>
240<para>
241This sample is examined in more detail in <xref linkend="firstexample"/>.
242</para>
243</section>
244<!-- end subsection -->
245<!-- subsection -->
246<section id="defaultscppdesc">
247<title>defaults.cpp</title>
248<para>
249This sample begins by reading an MPS file.  The default MPS file is
250<filename>COIN/Mps/Sample/p0033.mps</filename>; this can be over-riden by a
251command-line specification of a (path and) file name).  The sample then sets
252the pivot algorithm to be exact devex.  It &quot;gets&quot; the default
253infeasibility cost and &quot;sets&quot; it to that value (and prints it to
254standard out).  This sort of getting and setting of various parameters
255constitutes a common theme in this sample, with the purpose of illustrating
256usage of some of the more common get and set methods available in CLP.
257</para>
258<para>
259At this point the model is solved by the primal method.  A sequence of sets,
260gets and prints is then followed by a number of calls to methods which give
261specific information about the status of the problem (for example, the code
262checks that the current solution has been proven to be optimal by
263<code>assert(model.isProvenOptimal())</code>).
264</para>
265<para>
266Next, a copy of the original model is made.  More sets and gets are
267performed to demonstrate the use of additional options (including
268the setting of the default message handling as well as changing of the
269&quot;log level&quot; (amount of output)).  The model is solved again a
270number of times between changes of the optimization direction (i.e. changing
271from min to max or vice versa).  The remaining lines of this sample serve to
272display solution and problem information in much the same way as is done in
273driver.cpp.
274</para>
275</section>
276<!-- subsection -->
277<section id="drivercppdesc">
278<title>driver.cpp</title>
279<para>
280This sample begins by reading an MPS file.  The default MPS file is
281<filename>COIN/Mps/Sample/p0033.mps</filename>; this can be over-riden by a
282command-line specification of a (path and) file name).  A second command-line
283argument can specify that either the &quot;primal&quot; or &quot;dual&quot;
284method (or even the &quot;barrier&quot;, see below) should be used by CLP.
285</para>
286<para>
287Once the problem has been
288read, there are two options for how to solve it, one of which must be chosen at
289compile-time (<code>STYLE1</code> being defined or not determines this
290choice).  The second manner is more flexible and involves more specific
291directions being given to CLP, including the ability to specify that the barrier
292method should be used.
293</para>
294<para>
295At this point in the sample, the problem is solved by CLP, and some basic ouput
296is generated.  If more output is desired, at compile-time, an
297<code>exit(0)</code> statement must either be removed or commented.  There are
298two levels of additional output, the first of which is suppressed  by a
299<code>#if 0</code> directive which may be modified at compile-time if desired.
300This first level of output only involves non-zero columns, whereas the second
301provides additional information.
302</para>
303</section>
304<!-- end subsection -->
305<!-- subsection -->
306<section id="networkcppdesc">
307<title>network.cpp</title>
308<para>
309This handy sample reads a network problem generated by
310<ulink url="http://www.netlib.org/lp/generators/netgen">netgen</ulink>, converts
311it to an LP using CLP's network matrix type, and solves.  This entirely avoids
312the use of an MPS file, as the LP is built in memory from the network data file
313created by netgen.  Also, the factorization frequency is changed, and the
314problem is solved more than once (demonstrating the change of optimization sense
315as well as switching from dual to primal methods).
316</para>
317</section>
318<!-- end subsection -->
319<!-- subsection -->
320<section id="testbarriercppdesc">
321<title>testBarrier.cpp</title>
322<para>
323This straightfoward sample begins by reading a problem from an MPS file.  It
324then chooses a Cholesky factorization and solves the problem using the
325predictor corrector barrier method.  It then copies the problem and performs a
326crossover to a simplex solution in the new copy.
327</para>
328</section>
329<!-- end subsection -->
330<!-- subsection -->
331<section>
332<title>dualCuts.cpp</title>
333<para>
334This sample begins with only the equality constraints of a problem.  The
335inequalities are considered to be part of a pool of available cuts in much the
336same way as is done in integer programming.  However, in this case, the cuts are
337not &quot;generated&quot;, they are simply the inequalities of the problem.
338</para>
339</section>
340<!-- end subsection -->
341<!-- subsection -->
342<section>
343<title>decompose.cpp</title>
344<para>
345More on this sample coming soon!
346</para>
347</section>
348<!-- end subsection -->
349<!-- subsection -->
350<section>
351<title>driver2.cpp</title>
352<para>
353More on this sample coming soon!
354</para>
355</section>
356<!-- end subsection -->
357</section>
358<section>
359<title>Common CLP Tasks in the Samples</title>
360<para>
361Below is a listing of a number of common CLP tasks, such as loading a problem
362from an MPS file, matched with a list of each Sample file which illustrates the
363performance of a given task.
364</para>
365<table frame="none">
366  <title>Contents of the Samples directory</title>
367  <tgroup cols="3">
368    <thead>
369      <row>
370        <entry align="left" valign="bottom">
371        CLP Task(s)
372        </entry>
373        <entry>
374        Method(s)
375        </entry>
376        <entry align="left" valign="bottom">
377        Sample(s)
378        </entry>
379      </row>
380    </thead>
381    <tbody>
382      <row>
383        <entry>
384        Read problem from MPS file
385        </entry>
386        <entry>
387        <literallayout><function>int readMps(const char *filename)</function></literallayout>
388        </entry>
389        <entry>
390        &defaultscpp;, &drivercpp;, &minimumcpp;
391        </entry>
392      </row>
393      <row>
394        <entry>
395        Solve by primal method
396        </entry>
397        <entry>
398        <literallayout><function>int primal()</function></literallayout>
399        </entry>
400        <entry>
401        &drivercpp;
402        </entry>
403      </row>
404      <row>
405        <entry>
406        Choose pivot rule
407        </entry>
408        <entry>
409        <literallayout><function>void setPrimalColumnPivotAlgorithm(ClpPrimalColumnPivot &amp;choice)</function>
410        <function>void setDualRowPivotAlgorithm(ClpDualRowPivot &amp;choice)</function></literallayout>
411        </entry>
412        <entry>
413        &defaultscpp;
414        </entry>
415      </row>
416      <row>
417        <entry>
418        Get/set infeasibility cost
419        </entry>
420        <entry>
421        <literallayout><function>void setInfeasibilityCost(double value)</function>
422        <function>void setInfeasibilityCost(double value)</function></literallayout>
423        </entry>
424        <entry>
425        &defaultscpp;
426        </entry>
427      </row>
428      <row>
429        <entry>
430        Get string/&quot;double&quot;/integer information
431        </entry>
432        <entry>
433        <literallayout><function>bool getStrParam(ClpStrParam key, std::string &amp;value) const</function>
434        <function>bool getDblParam(ClpDblParam key, double &amp;value) const</function>
435        <function>bool  getIntParam (ClpIntParam key, int &amp;value) const </function></literallayout>
436        </entry>
437        <entry>
438        &defaultscpp;
439        </entry>
440      </row>
441      <row>
442        <entry>
443        Set maximum number of iterations
444        </entry>
445        <entry>
446        <literallayout><function>void setMaximumIterations(int value)</function></literallayout>
447        </entry>
448        <entry>
449        &defaultscpp;
450        </entry>
451      </row>
452      <row>
453        <entry>
454        Check solution status
455        </entry>
456        <entry>
457        <literallayout><function>int status() const</function>
458        <function>bool isAbandoned() const</function>
459        <function>bool isProvenOptimal() const</function>
460        <function>bool isProvenPrimalInfeasible() const</function>
461        <function>bool isProvenDualInfeasible() const</function>
462        <function>bool isPrimalObjectiveLimitReached() const</function>
463        <function>bool isDualObjectiveLimitReached() const</function>
464        <function>bool isIterationLimitReached() const</function>
465        <function></function>
466        <function></function></literallayout>
467        </entry>
468        <entry>
469       
470        </entry>
471      </row>
472      <row>
473        <entry>
474       
475        </entry>
476        <entry>
477       
478        </entry>
479        <entry>
480       
481        </entry>
482      </row>
483      <row>
484        <entry>
485       
486        </entry>
487        <entry>
488       
489        </entry>
490        <entry>
491       
492        </entry>
493      </row>
494      <row>
495        <entry>
496       
497        </entry>
498        <entry>
499       
500        </entry>
501        <entry>
502       
503        </entry>
504      </row>
505      <row>
506        <entry>
507       
508        </entry>
509        <entry>
510       
511        </entry>
512        <entry>
513       
514        </entry>
515      </row>
516      <row>
517        <entry>
518       
519        </entry>
520        <entry>
521       
522        </entry>
523        <entry>
524       
525        </entry>
526      </row>
527    </tbody>
528  </tgroup>
529</table>
530
531</section>
532</chapter>
Note: See TracBrowser for help on using the repository browser.