Scippy

SCIP

Solving Constraint Integer Programs

xternal.c
Go to the documentation of this file.
1 /* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */
2 /* */
3 /* This file is part of the program and library */
4 /* SCIP --- Solving Constraint Integer Programs */
5 /* */
6 /* Copyright (C) 2002-2016 Konrad-Zuse-Zentrum */
7 /* fuer Informationstechnik Berlin */
8 /* */
9 /* SCIP is distributed under the terms of the ZIB Academic License. */
10 /* */
11 /* You should have received a copy of the ZIB Academic License */
12 /* along with SCIP; see the file COPYING. If not email to scip@zib.de. */
13 /* */
14 /* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */
15 
16 /**@file xternal.c
17  * @brief main document page
18  * @author Timo Berthold
19  * @author Stefan Heinz
20  */
21 
22 /*--+----1----+----2----+----3----+----4----+----5----+----6----+----7----+----8----+----9----+----0----+----1----+----2*/
23 
24 /**@mainpage Overview
25  * @author Timo Berthold
26  * @author Stefan Heinz
27  *
28  * This example contains a branch-and-price approach for the binpacking problem which is realized with the framework
29  * \SCIP. Therefore, the following plugins are implemented:
30  *
31  * - a problem reader which parses the problem out of file and creates the corresponding problem within \SCIP
32  * (reader_bpa.c)
33  * - a (global) problem data structure which contains all necessary information (probdata_binpacking.c)
34  * - a pricer which generates new variables/columns during the search (pricer_binpacking.c)
35  * - the Ryan/Foster branching rule (branch_ryanfoster.c)
36  * - a constraint handler which handles the branching decisions of the Ryan/Foster branching (cons_samediff.c)
37  * - a variable data structure which stores information for each variable and is needed to perform the Ryan/Foster
38  * branching (vardata_binpacking.c)
39  *
40  * In the following we introduce the problem, explain the use of the reader plugin and pricer plugin. Finally, we
41  * introduce the Ryan/Foster branching rule and briefly discuss how that specific branching rule can be realized within
42  * the framework \SCIP.
43  *
44  * -# \ref PROBLEM "Problem description"
45  * -# \ref READER "Parsing the input format and creating the problem"
46  * -# \ref PROBLEMDATA "Main problem data"
47  * -# \ref PRICER "Pricing new variables"
48  * -# \ref BRANCHING "Ryan/Foster branching"
49  * -# \ref MAKEFILE "The Makefile"
50  *
51  */
52 
53 /**@page PROBLEM Problem description
54  *
55  * The binpacking problem consists of the task to distribute a given set of items \f$ [n] := \{1, \dots, n\}\f$ with
56  * nonnegative size \f$s_i\f$ to a minimal number of bins, all of the same capacity \f$\kappa\f$. As example consider 9
57  * items with sizes: 2, 1, 2, 1, 1, 2, 3, 2, and 1 and a bin capacity of \f$\kappa\f$ of 4. The following pictures show
58  * a feasible solution which needs 5 bins. The minimum number of bins needed for that example is 3.
59  *
60  * <CENTER>
61  * \image html binpacking.png
62  * </CENTER>
63  *
64  * This problem can be formulated as a set covering problem as discussed by Gilmore and Gomory in the following two classical papers:
65  * - Gilmore P. C., R. E. Gomory: A linear programming approach to the cutting-stock problem. Operations Research 9 (1961): 849-859.
66  * - Gilmore P. C., R. E. Gomory: A linear programming approach to the cutting-stock problem - Part II. Operations Research 11 (1963): 863-888
67  *
68  * We introduce a binary variable \f$x_{S}\f$ for each feasible packing \f$S\f$. A <b>packing</b> \f$S\f$ is an
69  * assignment vector \f$ \lambda_{S}\in\{0,1\}^n \f$ which states the items belonging to that packing. It is
70  * <b>feasible</b>, if and only if the total size of the items contained in this assignment is not greater than the
71  * given capacity \f$\kappa\f$. Let \f$\mathcal{S}\f$ be the set of all feasible packing, this measns:
72  *
73  * \f[
74  * \mathcal{S} := \{S\subseteq [n] \mid \sum_{i:i\in S} s_{i} \leq \kappa \}
75  * \f]
76  *
77  * An integer program can be formulated as follows:
78  *
79  * \f[
80  * \begin{array}[t]{rll}
81  * \min & \displaystyle \sum_{S \in \mathcal{S}} x_{S} \\
82  * & \\
83  * subject \ to & \displaystyle \sum_{S \in \mathcal{S}} (\lambda_{S})_{i}x_{S} \ge 1 & \quad \forall i \in \{1,\dots,n\} \\
84  * & \\
85  * & x_{S} \in \{0,1\} & \quad \forall S \in \mathcal{S} \\
86  * \end{array}
87  * \f]
88  *
89  * This means we are searching for a set of packings such that each item is contained in at least one of the selected
90  * packings. Since the objective is to minimize the number of used packings, each optimal solution to the above problem
91  * can be transformed into a solution where each item is packed exactly once with the same cost.
92  *
93  *
94  * Since \f$\mathcal{S}\f$ can be of exponential size, we are using a column generation approach to solve this
95  * problem. We initialize the (master) problem with a set of \f$ n \f$ variables representing packings of a single item
96  * per bin. Now, we have to iteratively search for variables representing "better" packings, i.e., a packing pattern
97  * which reduces the overall cost. For a given solution \f$y^\star\f$ of the (restricted) dual linear program, we have
98  * to find a variable/packing \f$ \lambda_{S} \f$ for which the reduced costs is negative. This means:
99  *
100  * \f[
101  * c_{S} - \sum_{i=0}^n (\lambda_S)_i y_i^\star < 0.
102  * \f]
103  *
104  * Since all variables \f$ \lambda_{S} \f$ have an objective coefficient \f$ c_{S} = 1 \f$ the above condition is
105  * equivalent to
106  *
107  * \f[
108  * \sum_{i=0}^n (\lambda_S)_i y_i^\star > 1.
109  * \f]
110  *
111  *
112  * To find such a variable/packing we solve the following integer program:
113  *
114  * \f[
115  * \begin{array}[t]{rll}
116  * \max & \displaystyle \sum_{i=1}^n (\lambda_S)_i y^\star_i\\
117  * & \\
118  * subject \ to & \displaystyle \sum_{i=0}^n (\lambda_S)_i s_i \leq \kappa \\
119  * & \\
120  * & (\lambda_S)_i \in \{0,1\} & \quad \forall i \in \{ 1, \dots , n \} \\
121  * \end{array}
122  * \f]
123  *
124  * where \f$ (\lambda_S)_i \f$ for \f$i\in\{1,\dots,n\}\f$ are binary variables and \f$y^\star_i\f$ given by the dual
125  * solution of the restricted master problem.
126  *
127  * The above problem is a knapsack problem which can be solved via dynamic programming or by solving the above integer
128  * program. In this example we implemented a pricer which solves the integer program.
129  *
130  */
131 
132 
133 
134 /**@page MAKEFILE The Makefile
135  *
136  * The Makefile is based on the main \SCIP Makefile. This means that all compiling options which are
137  * available for \SCIP are also available for the binpacking project. Below, you find a list
138  * of the most important compiling flags, the values they can take, and a short description. The
139  * values in bold face are the default values.
140  *
141  * - <code>LPS={clp | cpx | none | <b>spx</b>}</code>
142  * <br>
143  * Defines the linear program solver to use:
144  * - <code>clp</code> use COIN-OR CLP
145  * - <code>cpx</code> use IBM CPLEX
146  * - <code>none</code> no LP solver
147  * - <code><b>spx</b></code> use SoPlex
148  *
149  * - <code>OPT={dbg | <b>opt</b>}</code>
150  * <br>
151  * Defines if the projects gets compiled in debug (<code>dbg</code>) mode or
152  * optimized (<code><b>opt</b></code>) mode. In the debug mode all assertions are checked.
153  *
154  * - <code>ZIMPL={false | <b>true</b>}</code>
155  * <br>
156  * Defines if the modeling language ZIMPL should be linked to binary or not.
157  *
158  * In the following we explain the all <b>Makefile targets</b>.
159  *
160  * - <b>lint</b>
161  * <br>
162  * Statically checks the code for uninitialized variables and many other possible problems,
163  * which even do not lead to compiler errors. For this, the
164  * the external tool flexelint is needed. The call produces the file <code>lint.out</code>
165  * which contains all the detected warnings. From the experience when developing \SCIP, we strongly
166  * recommend to use such a code checker. It is always a surprising the stuff such tools detect.
167  * <br>
168  *
169  * - <b>doc</b>
170  * <br>
171  * Generates a html documentation. For this call the external tool
172  * <a href="http://doxygen.org">doyxgen</a> is needed.
173  * After generating the documentation, you can use your favorite browser to open the main page
174  * <code>doc/html/index.shtml</code>.
175  * <br>
176  *
177  * - <b>clean</b>
178  * <br>
179  * Remove all objective files, libraries, and binaries.
180  * <br>
181  *
182  * - <b>test</b>
183  * <br>
184  * Starts an automated test run based on the SCIP test runs (see <a
185  * href="http://scip.zib.de/doc/html/TEST.php">How to run automated tests with SCIP</a>).
186  * <br>
187  *
188  * - <b>tags</b>
189  * <br>
190  * Generates tags which can be used in the editor <b>emacs</b> and <b>xemacs</b>.
191  * <br>
192  *
193  * - <b>depend</b>
194  * <br>
195  * Generates the dependencies for the compiling process.
196  */
197