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-2015 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 Daniel Rehfeldt
19  * @author Gerald Gamrath
20  * @author Thorsten Koch
21  * @author Stephen Maher
22  * @author Yuji Shinano
23  * @author Michael Winkler
24  */
25 
26 /*--+----1----+----2----+----3----+----4----+----5----+----6----+----7----+----8----+----9----+----0----+----1----+----2*/
27 
28 /**@mainpage Overview
29  * @author Daniel Rehfeldt
30  * @author Gerald Gamrath
31  * @author Thorsten Koch
32  * @author Stephen Maher
33  * @author Yuji Shinano
34  * @author Michael Winkler
35  *
36  * This application contains the branch-and-cut based solver SCIP-Jack for Steiner tree problems, realized within the framework
37  * \SCIP, see: "A generic approach to solving the Steiner tree problem and variants" by D. Rehfeldt. The following plugins are implemented:
38  *
39  * - a problem reader, which parses the problem out of a .stp file
40  * (reader_stp.c)
41  * - a (global) problem data structure, containing all necessary information including the graph, which creates the model within \SCIP (probdata_stp.c)
42  * - a construction heuristic (heur_tm.c)
43  * - an improvment heuristic (heur_local.c)
44  * - a recombination heuristic (heur_rec.c)
45  * - a, by default deactivated, pricer, which generates new variables/columns during the search (pricer_stp.c)
46  * - a constraint handler, which checks solutions for feasibility and separates any violated model constraints (cons_stp.c)
47  * - a propagator, which attempts to fix (edge) variables to zero utilizing their reduced costs (prop_stp.c)
48  * - an event handler, which simply writes each incumbent solution to a file -- if activated (event_bestsol.c)
49  *
50  * In the following the problem is introduced and the solving process is delineated. Furthermore, the two main plugins are
51  * sketched.
52  *
53  * -# \ref PROBLEM "Problem description and solving approach"
54  * -# \ref PROBLEMDATA "Main problem data, creating the problem"
55  * -# \ref CONS "Separating violated constraints"
56  * -# \ref MAKEFILE "The Makefile"
57  *
58  */
59 
60 /**@page PROBLEM Problem description and solving approach
61  *
62  * The Steiner tree problem in graphs (SPG) can be described as follows: Given an undirected connected graph
63  * \f$ G=(V,E)\f$, costs \f[ c: E \rightarrow \mathcal{Q}^+ \f] and a set \f$ T \subset V \f$ of terminals,
64  * the problem is to find a minimum-weight tree \f$ S\subseteq G \f$ that spans \f$ T \f$. Each tree \f$ S \f$ that spans \f$ T \f$, called Steiner tree, is
65  * a feasible solution to the problem.
66  * The following picture shows an SPG instance with the terminals given as squares:
67  *
68  * <CENTER>
69  * \image html stp.png
70  * </CENTER>
71  *
72  *
73  * The solving approach of SCIP-Jack can be dissected into three major components:
74  *
75  * First, problem specific preprocessing is extremely important. Apart from some pathological instances
76  * specifically constructed to defy presolving techniques, preprocessing is often able to significantly
77  * reduce instances or even solve them.
78  *
79  * Second, heuristics are needed, especially for hard instances, to find good or even optimal solutions.
80  *
81  * Finally, the core of our approach is constituted by a branch-and-cut procedure used to compute lower bounds and prove optimality.
82  *
83  * The problem can be formulated using the directed equivalent of the SPG, the Steiner arborescence problem (SAP):
84  * Given a directed graph \f$ D=(V,A) \f$, a root \f$ r \in V \f$, costs \f$ c: A \rightarrow \mathcal{Q}^+ \f$
85  * and a set \f$ T \subset V \f$ of terminals, a subgraph \f$ S\subseteq D \f$ such that
86  * for all \f$ t \in T \f$, \f$ S \f$ contains exactly one directed path from \f$ r \f$ to \f$ t \f$ is called Steiner arborescence.
87  * Thereupon, a Steiner arborescence \f$ S = (V_S, A_S) \f$ is required that minimizes \f$ \sum_{a \in A_S} c_a \f$. An SPG can be
88  * transformed to an SAP by replacing each edge with two anti-parallel arcs of the same cost and distinguishing an arbitrary
89  * terminal as the root. This transformation results in a one-to-one correspondence between the respective solution sets.
90  * Introducing variables \f$y_a\f$ for \f$a\in A\f$ with the interpretation that \f$y_a:=1\f$ if and only if \f$a\f$ is in the
91  * Steiner arborecence, and \f$y_a:=0\f$ otherwise, we obtain the integer program:
92  *
93  * \f[
94  * \begin{array}[t]{rll}
95  * \min {c}^T y\\
96  * \\
97  * y(\delta^+(W))&\geq& 1, ~~~ \forall , W\subset V, r\in W, (V\setminus W)\cap T\neq \emptyset\\
98  * y(\delta^-(v))&
99  * \left\{{\begin{array}{l} = \\
100  * = \\
101  * \leq
102  * \end{array}}\right.
103  * &
104  * {\begin{array}{l}
105  * 0, \mbox{if } v=r;\\
106  * 1, \mbox{if } v\in T\setminus{r};\\
107  * 1, \mbox{if } v\in N; \end{array}} \hspace{2.9mm}\forall v \in V
108  * \\
109  * y(\delta^-(v))&\leq& y(\delta^+(v)), \hspace{10.5mm}\forall v\in N;\\
110  * y(\delta^-(v))&\geq& y_a, \hspace{20.2mm}\forall a\in\delta^+(v), v\in N;\\
111  * 0\leq y_a&\leq& 1, \hspace{22mm}\forall a\in A;\\
112  * y_a&\in& \{0,1\}, \hspace{15.1mm}\forall a\in A,
113  * \end{array}
114  * \f]
115  * where \f$N=V\setminus T\f$, \f$\delta^+(X):=\{(u,v)\in A| u\in X, v\in V\setminus X\}\f$, \f$\delta^-(X):= \delta^+(V \setminus X)\f$ for
116  * \f$X\subset V\f$ i.e., \f$\delta^+(X)\f$ is the set of all arcs going out of and \f$\delta^-(X)\f$ the set of all arcs going into \f$X\f$.
117  *
118  * Since the model potentially contains an exponential number of constraints, a separation approach is employed.
119  * Violated constraints are separated during the execution of the branch-and-cut algorithm.
120  *
121  * In addition to Steiner problems in graphs there exist several variations. The following Steiner problem variants can be solved by SCIP-JACK,
122  * by transforming them to a Steiner arborescence problem, and in some cases introducing additional constraints:
123  *
124  * -Steiner arborescence problems,
125  *
126  * -rectilinear Steiner minimum tree problems,
127  *
128  * -node-weighted Steiner tree problems,
129  *
130  * -prize-collecting Steiner tree problems,
131  *
132  * -rooted prize-collecting Steiner tree problems,
133  *
134  * -maximum-weight connected subgraph problems,
135  *
136  * -degree-constrained Steiner tree problems,
137  *
138  * -group Steiner tree problems, and
139  *
140  * -hop-honstrained directed Steiner tree problems.
141  *
142  * A far more intricate description of SCIP-Jack and its various components can be found in
143  * "A generic approach to solving the Steiner tree problem and variants" by D. Rehfeldt.
144  */
145 
146 
147 
148 /**@page MAKEFILE The Makefile
149  *
150  * The Makefile is based on the main \SCIP Makefile. This means that all compiling options which are
151  * available for \SCIP are also available for the stp project. Below, you find a list
152  * of the most important compiling flags, the values they can take, and a short description. The
153  * values in bold face are the default values.
154  *
155  * - <code>LPS={clp | cpx | none | <b>spx</b>}</code>
156  * <br>
157  * Defines the linear program solver to use:
158  * - <code>clp</code> use COIN-OR CLP
159  * - <code>cpx</code> use IBM CPLEX
160  * - <code>none</code> no LP solver
161  * - <code><b>spx</b></code> use SoPlex
162  *
163  * - <code>OPT={dbg | <b>opt</b>}</code>
164  * <br>
165  * Defines if the projects gets compiled in debug (<code>dbg</code>) mode or
166  * optimized (<code><b>opt</b></code>) mode. In the debug mode all assertions are checked.
167  *
168  * - <code>ZIMPL={false | <b>true</b>}</code>
169  * <br>
170  * Defines if the modeling language ZIMPL should be linked to binary or not.
171  *
172  * In the following we explain the all <b>Makefile targets</b>.
173  *
174  * - <b>lint</b>
175  * <br>
176  * Statically checks the code for uninitialized variables and many other possible problems,
177  * which even do not lead to compiler errors. For this, the
178  * the external tool flexelint is needed. The call produces the file <code>lint.out</code>
179  * which contains all the detected warnings. From the experience when developing \SCIP, we strongly
180  * recommend to use such a code checker. It is always a surprising the stuff such tools detect.
181  * <br>
182  *
183  * - <b>doc</b>
184  * <br>
185  * Generates a html documentation. For this call the external tool
186  * <a href="http://doxygen.org">doyxgen</a> is needed.
187  * After generating the documentation, you can use your favorite browser to open the main page
188  * <code>doc/html/index.shtml</code>.
189  * <br>
190  *
191  * - <b>clean</b>
192  * <br>
193  * Remove all objective files, libraries, and binaries.
194  * <br>
195  *
196  * - <b>test</b>
197  * <br>
198  * Starts an automated test run based on the SCIP test runs (see <a
199  * href="http://scip.zib.de/doc/html/TEST.php">How to run automated tests with SCIP</a>).
200  * <br>
201  *
202  * - <b>tags</b>
203  * <br>
204  * Generates tags which can be used in the editor <b>emacs</b> and <b>xemacs</b>.
205  * <br>
206  *
207  * - <b>depend</b>
208  * <br>
209  * Generates the dependencies for the compiling process.
210  */