Changeset 2416


Ignore:
Timestamp:
Mar 6, 2019 7:53:25 PM (8 months ago)
Author:
stefan
Message:

more files into github flav markdown

Location:
branches/gh-pages
Files:
3 edited

Legend:

Unmodified
Added
Removed
  • branches/gh-pages/moresamples.md

    r2410 r2416  
    1 More Samples {#moreexamples}
    2 ============
     1# More Samples
    32
    4 CLP\'s Samples Directory
    5 ========================
     3# CLP’s Samples Directory
    64
    75The CLP dsitribution includes a number of `.cpp` sample files. Users are
    86encouraged to use them as starting points for their own CLP projects.
    9 The files can be found in the `` directory. For the latest information
    10 on compiling and running these samples, please see the file
    11 `CLPSAMPLESDIRINSTALL`. Below is a list of some of the most useful
    12 sample files with a short description for each file.
     7The files can be found in the \``directory. For the latest information
     8on compiling and running these samples, please see the
     9file`CLPSAMPLESDIRINSTALL\`. Below is a list of some of the most useful
     10sample files with a short description for each
     11file.
    1312
    14   Source file          Description
    15   -------------------- ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
    16   MINIMUMCPP           This is a CLP \"Hello, world\" program. It reads a problem from an MPS file, and solves the problem. \[[More\...](#minimumcppdesc)\]
    17   DEFAULTSCPP          This is one of the simpler driver programs available. It sets tolerances to defaults and is a good place to find straightforward uses of \"set\" and \"get\" methods. It also prints out full MPS-like solutions. \[[More\...](#defaultscppdesc)\]
    18   DRIVERCPP            This is designed to be a file that a user could modify to get a useful driver program for his or her project. In particular, it demonstrates the use of CLP\'s presolve functionality. \[[More\...](#drivercppdesc)\]
    19   NETWORKCPP           This shows the use of non-standard matrices and how to load a problem without the use of MPS files. \[[More\...](#networkcppdesc)\]
    20   TESTBARRIERCPP       This is a basic driver file for the barrier method of CLP, similar to MINIMUMCPP. The barrier method is not currently addressed in this guide. \[[More\...](#testbarriercppdesc)\]
     13| Source file    | Description                                                                                                                                                                                                                                   |
     14| :------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
     15| MINIMUMCPP     | This is a CLP “Hello, world” program. It reads a problem from an MPS file, and solves the problem. \[[More...](#minimumcppdesc)\]                                                                                                             |
     16| DEFAULTSCPP    | This is one of the simpler driver programs available. It sets tolerances to defaults and is a good place to find straightforward uses of “set” and “get” methods. It also prints out full MPS-like solutions. \[[More...](#defaultscppdesc)\] |
     17| DRIVERCPP      | This is designed to be a file that a user could modify to get a useful driver program for his or her project. In particular, it demonstrates the use of CLP’s presolve functionality. \[[More...](#drivercppdesc)\]                           |
     18| NETWORKCPP     | This shows the use of non-standard matrices and how to load a problem without the use of MPS files. \[[More...](#networkcppdesc)\]                                                                                                            |
     19| TESTBARRIERCPP | This is a basic driver file for the barrier method of CLP, similar to MINIMUMCPP. The barrier method is not currently addressed in this guide. \[[More...](#testbarriercppdesc)\]                                                             |
    2120
    22   : Basic Samples
     21Basic
     22Samples
    2323
    24   Source file          Description
    25   -------------------- --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
    26   DRIVER2CPP           This sample, in addition to some tasks common to other samples, does some advanced message handling and presolve.
    27   DUALCUTSCPP          This sample implements a method of treating a problem as a collection of cuts.
    28   DECOMPOSECPP         This does full Dantzig-Wolfe decomposition. It illustrates the use of many models, adding columns, et cetera.
    29   SPRINTCPP            This solves a long, thin problem by solving smaller subsets. It is a simplified version of work done by one of the authors on aircrew scheduling problems. It shows the use of two models and their synchronization. A more general version can be found in `COIN/Clp/ClpSolve.cpp`
    30   SPRINT2CPP           This is similar to `sprint.cpp` but is designed for solving large problems with little choice. The idea is that if relatively few variables are fixed, presolve can greatly reduce the problem size so that a series of solves can get close to the optimal solution much faster than would a naïve solve of the full problem.
     24| Source file  | Description                                                                                                                                                                                                                                                                                                                    |
     25| :----------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
     26| DRIVER2CPP   | This sample, in addition to some tasks common to other samples, does some advanced message handling and presolve.                                                                                                                                                                                                              |
     27| DUALCUTSCPP  | This sample implements a method of treating a problem as a collection of cuts.                                                                                                                                                                                                                                                 |
     28| DECOMPOSECPP | This does full Dantzig-Wolfe decomposition. It illustrates the use of many models, adding columns, et cetera.                                                                                                                                                                                                                  |
     29| SPRINTCPP    | This solves a long, thin problem by solving smaller subsets. It is a simplified version of work done by one of the authors on aircrew scheduling problems. It shows the use of two models and their synchronization. A more general version can be found in `COIN/Clp/ClpSolve.cpp`                                            |
     30| SPRINT2CPP   | This is similar to `sprint.cpp` but is designed for solving large problems with little choice. The idea is that if relatively few variables are fixed, presolve can greatly reduce the problem size so that a series of solves can get close to the optimal solution much faster than would a naïve solve of the full problem. |
    3131
    32   : Advanced Samples
     32Advanced Samples
    3333
    3434The remaining Samples listed here are considered unsupported in that
    3535they are of a more esoteric nature and are sometimes contributed as a
    36 result of an individual\'s request. The are to be found in
     36result of an individual’s request. The are to be found in
    3737`CLPSAMPLESDIRContributed`.
    3838
    39   Source file          Description
    40   -------------------- -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
    41   TESTBASISCPP         This sample takes a problem, changes any inequality constraints to equality constraints, solves the problem, and creates the optimal basis.
    42   TESTGUBCPP           This sample illustrates the use of the GUB (\"Generalized Upper Bound\") technique.
    43   EKKCPP               This sample can be used to compare CLP and OSL. It uses an additional file in the Samples directory, `ekk_interface.cpp`. These sample files are not likely to be interesting to new CLP users who do not have experience with OSL.
    44   HELLOCPP             This sample creates a text-based picture of a matrix on screen (limited to an 80x80 matrix). It\'s not terribly useful but it does illustrate one way to step through the elements of a matrix.
    45   PIECECPP             This sample takes a matrix read in by `CoinMpsIo` (can be used to read in MPS files without a solver), deletes every second column and solves the resulting problem.
    46   USEVOLUMECPP         The Volume Algorithm is another solver available as part of the COIN-OR distribution. This sample shows how to use the Volume Algorithm with CLP.
     39| Source file  | Description                                                                                                                                                                                                                         |
     40| :----------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
     41| TESTBASISCPP | This sample takes a problem, changes any inequality constraints to equality constraints, solves the problem, and creates the optimal basis.                                                                                         |
     42| TESTGUBCPP   | This sample illustrates the use of the GUB (“Generalized Upper Bound”) technique.                                                                                                                                                   |
     43| EKKCPP       | This sample can be used to compare CLP and OSL. It uses an additional file in the Samples directory, `ekk_interface.cpp`. These sample files are not likely to be interesting to new CLP users who do not have experience with OSL. |
     44| HELLOCPP     | This sample creates a text-based picture of a matrix on screen (limited to an 80x80 matrix). It’s not terribly useful but it does illustrate one way to step through the elements of a matrix.                                      |
     45| PIECECPP     | This sample takes a matrix read in by `CoinMpsIo` (can be used to read in MPS files without a solver), deletes every second column and solves the resulting problem.                                                                |
     46| USEVOLUMECPP | The Volume Algorithm is another solver available as part of the COIN-OR distribution. This sample shows how to use the Volume Algorithm with CLP.                                                                                   |
    4747
    48   : Unsupported Samples
     48Unsupported Samples
    4949
    50 minimum.cpp {#minimumcppdesc}
    51 -----------
     50## minimum.cpp
    5251
    5352This sample is examined in more detail in [???](#firstexample).
    5453
    55 defaults.cpp {#defaultscppdesc}
    56 ------------
     54## defaults.cpp
    5755
    5856This sample begins by reading an MPS file. The default MPS file is
    5957`COIN/Mps/Sample/p0033.mps`; this can be over-riden by a command-line
    6058specification of a (path and) file name). The sample then sets the pivot
    61 algorithm to be exact devex. It \"gets\" the default infeasibility cost
    62 and \"sets\" it to that value (and prints it to standard out). This sort
     59algorithm to be exact devex. It “gets” the default infeasibility cost
     60and “sets” it to that value (and prints it to standard out). This sort
    6361of getting and setting of various parameters constitutes a common theme
    6462in this sample, with the purpose of illustrating usage of some of the
     
    7371Next, a copy of the original model is made. More sets and gets are
    7472performed to demonstrate the use of additional options (including the
    75 setting of the default message handling as well as changing of the \"log
    76 level\" (amount of output)). The model is solved again a number of times
    77 between changes of the optimization direction (i.e. changing from min to
     73setting of the default message handling as well as changing of the “log
     74level” (amount of output)). The model is solved again a number of times
     75between changes of the optimization direction (i.e. changing from min to
    7876max or vice versa). The remaining lines of this sample serve to display
    7977solution and problem information in much the same way as is done in
    8078driver.cpp.
    8179
    82 driver.cpp {#drivercppdesc}
    83 ----------
     80## driver.cpp
    8481
    8582This sample begins by reading an MPS file. The default MPS file is
    8683`COIN/Mps/Sample/p0033.mps`; this can be over-riden by a command-line
    8784specification of a (path and) file name). A second command-line argument
    88 can specify that either the \"primal\" or \"dual\" method (or even the
    89 \"barrier\", see below) should be used by CLP.
     85can specify that either the “primal” or “dual” method (or even the
     86“barrier”, see below) should be used by CLP.
    9087
    9188Once the problem has been read, there are two options for how to solve
     
    103100provides additional information.
    104101
    105 network.cpp {#networkcppdesc}
    106 -----------
     102## network.cpp
    107103
    108104This handy sample reads a network problem generated by
    109105[netgen](http://www.netlib.org/lp/generators/netgen), converts it to an
    110 LP using CLP\'s network matrix type, and solves. This entirely avoids
    111 the use of an MPS file, as the LP is built in memory from the network
    112 data file created by netgen. Also, the factorization frequency is
    113 changed, and the problem is solved more than once (demonstrating the
    114 change of optimization sense as well as switching from dual to primal
    115 methods).
     106LP using CLP’s network matrix type, and solves. This entirely avoids the
     107use of an MPS file, as the LP is built in memory from the network data
     108file created by netgen. Also, the factorization frequency is changed,
     109and the problem is solved more than once (demonstrating the change of
     110optimization sense as well as switching from dual to primal methods).
    116111
    117 testBarrier.cpp {#testbarriercppdesc}
    118 ---------------
     112## testBarrier.cpp
    119113
    120114This straightfoward sample begins by reading a problem from an MPS file.
     
    123117performs a crossover to a simplex solution in the new copy.
    124118
    125 dualCuts.cpp
    126 ------------
     119## dualCuts.cpp
    127120
    128121This sample begins with only the equality constraints of a problem. The
    129122inequalities are considered to be part of a pool of available cuts in
    130123much the same way as is done in integer programming. However, in this
    131 case, the cuts are not \"generated\", they are simply the inequalities
    132 of the problem.
     124case, the cuts are not “generated”, they are simply the inequalities of
     125the problem.
    133126
    134 decompose.cpp
    135 -------------
     127## decompose.cpp
    136128
    137 More on this sample coming soon!
     129More on this sample coming soon\!
    138130
    139 driver2.cpp
    140 -----------
     131## driver2.cpp
    141132
    142 More on this sample coming soon!
     133More on this sample coming soon\!
    143134
    144 Common CLP Tasks in the Samples
    145 ===============================
     135# Common CLP Tasks in the Samples
    146136
    147137Below is a listing of a number of common CLP tasks, such as loading a
    148138problem from an MPS file, matched with a list of each Sample file which
    149 illustrates the performance of a given task.
     139illustrates the performance of a given
     140task.
    150141
    151   CLP Task(s)                                 Method(s)                                                                                                                                                                                                                                                                                           Sample(s)
    152   ------------------------------------------- --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- ------------------------------------
    153   Read problem from MPS file                  `int readMps(const char *filename)`                                                                                                                                                                                                                                                                 DEFAULTSCPP, DRIVERCPP, MINIMUMCPP
    154   Solve by primal method                      `int primal()`                                                                                                                                                                                                                                                                                      DRIVERCPP
    155   Choose pivot rule                           `void setPrimalColumnPivotAlgorithm(ClpPrimalColumnPivot &choice)` `void setDualRowPivotAlgorithm(ClpDualRowPivot &choice)`                                                                                                                                                                         DEFAULTSCPP
    156   Get/set infeasibility cost                  `void setInfeasibilityCost(double value)` `void setInfeasibilityCost(double value)`                                                                                                                                                                                                                 DEFAULTSCPP
    157   Get string/\"double\"/integer information   `bool getStrParam(ClpStrParam key, std::string &value) const` `bool getDblParam(ClpDblParam key, double &value) const` `bool  getIntParam (ClpIntParam key, int &value) const `                                                                                                                     DEFAULTSCPP
    158   Set maximum number of iterations            `void setMaximumIterations(int value)`                                                                                                                                                                                                                                                              DEFAULTSCPP
    159   Check solution status                       `int status() const` `bool isAbandoned() const` `bool isProvenOptimal() const` `bool isProvenPrimalInfeasible() const` `bool isProvenDualInfeasible() const` `bool isPrimalObjectiveLimitReached() const` `bool isDualObjectiveLimitReached() const` `bool isIterationLimitReached() const` `` ``   
    160                                                                                                                                                                                                                                                                                                                                                  
    161                                                                                                                                                                                                                                                                                                                                                  
    162                                                                                                                                                                                                                                                                                                                                                  
    163                                                                                                                                                                                                                                                                                                                                                  
    164                                                                                                                                                                                                                                                                                                                                                  
     142| CLP Task(s)                                 | Method(s)                                                                                                                                                                                                                                                                                        | Sample(s)                          |
     143| :------------------------------------------ | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :--------------------------------- |
     144| Read problem from MPS file                  | `int readMps(const char *filename)`                                                                                                                                                                                                                                                              | DEFAULTSCPP, DRIVERCPP, MINIMUMCPP |
     145| Solve by primal method                      | `int primal()`                                                                                                                                                                                                                                                                                   | DRIVERCPP                          |
     146| Choose pivot rule                           | `void setPrimalColumnPivotAlgorithm(ClpPrimalColumnPivot &choice)` `void setDualRowPivotAlgorithm(ClpDualRowPivot &choice)`                                                                                                                                                                      | DEFAULTSCPP                        |
     147| Get/set infeasibility cost                  | `void setInfeasibilityCost(double value)` `void setInfeasibilityCost(double value)`                                                                                                                                                                                                              | DEFAULTSCPP                        |
     148| Get string/“double”/integer information \`b | ool getStrParam(ClpStrParam key, std::string \&value) const`  `bool getDblParam(ClpDblParam key, double \&value) const`  `bool getIntParam (ClpIntParam key, int \&value) const \` DE                                                                                                            | FAULTSCPP                          |
     149| Set maximum number of iterations            | `void setMaximumIterations(int value)`                                                                                                                                                                                                                                                           | DEFAULTSCPP                        |
     150| Check solution status                       | `int status() const` `bool isAbandoned() const` `bool isProvenOptimal() const` `bool isProvenPrimalInfeasible() const` `bool isProvenDualInfeasible() const` `bool isPrimalObjectiveLimitReached() const` `bool isDualObjectiveLimitReached() const` `bool isIterationLimitReached() const` `  ` |                                    |
    165151
    166   : Contents of the Samples directory
     152Contents of the Samples directory
  • branches/gh-pages/notsobasic.md

    r2410 r2416  
    1 Not-Quite-So-Basic Model Classes {#notsobasic}
    2 ================================
     1# Not-Quite-So-Basic Model Classes
    32
    4 Pivot Choices {#pivotchoices}
    5 =============
     3# Pivot Choices
    64
    75In the dual algorithm, any infeasible basic variable may be chosen to
    86leave the basis. Similarly in the primal algorithm, any non-basic
    9 variable with a \"bad\" reduced cost may be chosen to enter the basis.
     7variable with a "bad" reduced cost may be chosen to enter the basis.
    108This choice is probably the most important factor in determining the
    119number of iterations it will take to solve a problem. Clp provides a
     
    1513For the dual method the base class is `ClpDualRowPivot`. The two
    1614existing instances are `ClpDualRowDantzig` and `ClpDualRowSteepest`. The
    17 Dantzig version implements the \"standard\" pivot rule: choose the most
     15Dantzig version implements the "standard" pivot rule: choose the most
    1816violated basic variable. It is easily dominated by the Steepest instance
    1917which should normally be used. The default is to use un-initialized
     
    2321to ClpSimplex model as in the following code fragment:
    2422
    25       ClpDualRowSteepest steep(1); // 0 uninitialized, 1 compute weights
    26       model.setDualRowPivotAlgorithm(steep);
    27      
     23```
     24  ClpDualRowSteepest steep(1); // 0 uninitialized, 1 compute weights
     25  model.setDualRowPivotAlgorithm(steep);
     26 
     27```
    2828
    2929Similarly for the primal method the base class is
    3030`ClpPrimalColumnPivot`. The two existing instances are
    3131`ClpPrimalColumnDantzig` and `ClpPrimalColumnSteepest`. The Dantzig
    32 version implements \"standard\" pivot rule: choose the most \"violated\"
     32version implements "standard" pivot rule: choose the most "violated"
    3333non-basic variable. It is dominated by the Steepest instance which
    3434should normally be used. The default is to use exact Devex where the
     
    3838in the following code fragment:
    3939
    40       ClpPrimalColumnSteepest steep(1); // 0 devex, 1 steepest
    41       model.setPrimalColumnPivotAlgorithm(steep);
    42      
     40```
     41  ClpPrimalColumnSteepest steep(1); // 0 devex, 1 steepest
     42  model.setPrimalColumnPivotAlgorithm(steep);
     43 
     44```
    4345
    4446The partial pricing scheme (for long, thin problems) currently does not
    4547exist. This could be implemented by anyone who is interested.
    4648
    47 Matrix Classes {#matrixclasses}
    48 ==============
     49# Matrix Classes
    4950
    5051The next abstract class of interest is `ClpMatrixBase`. CLP encapsulates
     
    5758
    5859The important new methods implemented are for filling a basis, checking
    59 validity of elements and faster \"times\" and \"transposeTimes\" when
    60 the input array is sparse and/or we have a row copy of the matrix.
    61 Advanced users should note that not all methods have to be implemented.
    62 In particular, `scaling` need not be implemented and
    63 `reverseOrderedCopy` can return `NULL` if a row copy does not make
    64 sense.
     60validity of elements and faster "times" and "transposeTimes" when the
     61input array is sparse and/or we have a row copy of the matrix. Advanced
     62users should note that not all methods have to be implemented. In
     63particular, `scaling` need not be implemented and `reverseOrderedCopy`
     64can return `NULL` if a row copy does not make sense.
    6565
    6666In addition to the default class, there are two others at present:
     
    7777following:
    7878
    79       ClpPlusMinusOneMatrix plusMinus(matrix);
    80       assert (plusMinus.getIndices()); // would be zero if not +- one
    81       model.loadProblem(plusMinus,
    82         lowerColumn,upperColumn,objective,
    83         lower,upper);
    84      
     79```
     80  ClpPlusMinusOneMatrix plusMinus(matrix);
     81  assert (plusMinus.getIndices()); // would be zero if not +- one
     82  model.loadProblem(plusMinus,
     83    lowerColumn,upperColumn,objective,
     84    lower,upper);
     85 
     86```
    8587
    8688`ClpNetworkMatrix` is similar, but represents a network, thus may only
     
    8890`head` and `tail`, one could do the following:
    8991
    90       ClpNetworkMatrix network(numberColumns,head,tail);
    91       model.loadProblem(network,
    92         lowerColumn,upperColumn,objective,
    93         lower,upper);
    94      
     92```
     93  ClpNetworkMatrix network(numberColumns,head,tail);
     94  model.loadProblem(network,
     95    lowerColumn,upperColumn,objective,
     96    lower,upper);
     97 
     98```
    9599
    96100Actual code is in `COIN/Clp/Test/unitTest.cpp`. A quick glance at the
     
    105109use the abstract class for column generation or for dynamic matrices
    106110which change over time. Minor modifications may be needed but it should
    107 work quite smoothly (there is already a dummy \"refresh\" method which
     111work quite smoothly (there is already a dummy "refresh" method which
    108112would be used).
    109113
    110 Message Handling {#messagehandling}
    111 ================
     114# Message Handling
    112115
    113116Strictly speaking, message handling is a general COIN topic, but it
    114 won\'t hurt to repeat a few important things here.
     117won't hurt to repeat a few important things here.
    115118
    116119A simple user you may wish to turn off some output. This is done with
     
    120123which level. A more sophisticated user may wish to handle messages in a
    121124different way. This is done using `passInMessageHandler` with a pointer
    122 to a handler of the user\'s own design. The simplest case would be to
    123 use the default handler but use a constructor which writes to file. The
    124 code would be:
     125to a handler of the user's own design. The simplest case would be to use
     126the default handler but use a constructor which writes to file. The code
     127would be:
    125128
    126       FILE * fp; // assumed open
    127       CoinMessageHandler handler(fp);
    128       model.passInMessageHandler(&handler);
    129      
     129```
     130  FILE * fp; // assumed open
     131  CoinMessageHandler handler(fp);
     132  model.passInMessageHandler(&handler);
     133 
     134```
    130135
    131136A still more sophisticated use would be to write a class derived from
     
    134139infeasibility):
    135140
    136       class DerivedHandler :
    137        public CoinMessageHandler {
    138        public:
    139          virtual int print() ;
    140        };
     141```
     142  class DerivedHandler :
     143   public CoinMessageHandler {
     144   public:
     145     virtual int print() ;
     146   };
    141147
    142148
    143        int DerivedHandler::print()
    144        {
    145          if (currentSource()=="Clp") {
    146            if (currentMessage().externalNumber()>=0
    147            && currentMessage().externalNumber()<4) {
    148              // finished
    149              return CoinMessageHandler::print(); // print
    150            }
    151          }
    152          return 0;
     149   int DerivedHandler::print()
     150   {
     151     if (currentSource()=="Clp") {
     152       if (currentMessage().externalNumber()>=0
     153       && currentMessage().externalNumber()<4) {
     154         // finished
     155         return CoinMessageHandler::print(); // print
    153156       }
    154      
     157     }
     158     return 0;
     159   }
     160 
     161```
  • branches/gh-pages/revhist.md

    r2410 r2416  
    1 Revision History
    2 ================
     1# Revision History
    32
    430.4
Note: See TracChangeset for help on using the changeset viewer.