SCIP Doxygen Documentation
 
Loading...
Searching...
No Matches
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-2024 Zuse Institute Berlin (ZIB) */
7/* */
8/* Licensed under the Apache License, Version 2.0 (the "License"); */
9/* you may not use this file except in compliance with the License. */
10/* You may obtain a copy of the License at */
11/* */
12/* http://www.apache.org/licenses/LICENSE-2.0 */
13/* */
14/* Unless required by applicable law or agreed to in writing, software */
15/* distributed under the License is distributed on an "AS IS" BASIS, */
16/* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. */
17/* See the License for the specific language governing permissions and */
18/* limitations under the License. */
19/* */
20/* You should have received a copy of the Apache-2.0 license */
21/* along with SCIP; see the file LICENSE. If not visit scipopt.org. */
22/* */
23/* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */
24
25/**@file xternal.c
26 * @brief main document page
27 * @author Tobias Achterberg
28 * @author Timo Berthold
29 * @author Tristan Gally
30 * @author Gerald Gamrath
31 * @author Stefan Heinz
32 * @author Gregor Hendel
33 * @author Mathias Kinder
34 * @author Marc Pfetsch
35 * @author Stefan Vigerske
36 * @author Robert Waniek
37 * @author Kati Wolter
38 * @author Michael Winkler
39 */
40
41/*--+----1----+----2----+----3----+----4----+----5----+----6----+----7----+----8----+----9----+----0----+----1----+----2*/
42
43/** @mainpage Overview
44 *
45 * @section WHATISSCIP What is SCIP?
46 *
47 * \SCIP is a framework to solve constraint integer programs (CIPs) and mixed-integer nonlinear programs. In particular,
48 *
49 * - \SCIP incorporates a mixed-integer programming (MIP) solver as well as
50 * - an LP based mixed-integer nonlinear programming (MINLP) solver, and
51 * - is a framework for branch-and-cut-and-price.
52 *
53 * See the web site of <a href="http://scipopt.org">\SCIP</a> for more information about licensing and to download \SCIP.
54 *
55 * <b style="color: blue">If you are new to SCIP and don't know where to start you should have a look at the
56 * @ref GETTINGSTARTED "first steps walkthrough"
57 * .</b>
58 *
59 * @section TABLEOFCONTENTS Structure of this manual
60 *
61 * This manual gives an accessible introduction to the functionality of the SCIP code in the following chapters
62 *
63 * Setup and news
64 * - @subpage INSTALL
65 * - @subpage FAQ
66 * - @subpage CHG
67 *
68 * Tutorials and guides
69 * - @subpage GETTINGSTARTED
70 * - @subpage SHELL
71 * - @subpage PROGRAMMING "Important programming concepts for working with(in) SCIP"
72 * - @subpage START
73 * - @subpage DOC
74 * - @subpage HOWTOADD "Detailed guides for adding user plugins"
75 * - @subpage HOWTOUSESECTION "Detailed guides for advanced SCIP topics"
76 *
77 * Examples and applications
78 * - @subpage EXAMPLES "Coding examples in C and C++ in the source code distribution"
79 * - @subpage APPLICATIONS "Extensions of SCIP for specific applications"
80 *
81 * References
82 * - @subpage WHATPROBLEMS "Supported types of optimization problems"
83 * - @subpage FILEREADERS "Readable file formats"
84 * - @subpage INTERFACES
85 * - @subpage PARAMETERS
86 * - @subpage AUTHORS "SCIP Authors"
87 * - @subpage LICENSE
88 * - @subpage EXTERNALDOC "Links to external documentation"
89 *
90 *
91 * @section QUICKSTART Quickstart
92 *
93 * Let's consider the following minimal example in LP format. A 4-variable problem with a single, general integer
94 * variable and three linear constraints
95 *
96 * \verbinclude simple.lp
97 *
98 * Saving this file as "simple.lp" allows to read it into SCIP and solve it by calling the scip binary with the `-f` flag to solve the problem from the provided file and exit.
99 *
100 * ```
101 * scip -f simple.lp
102 * ```
103 * reads and optimizes this model in no time:
104 *
105 * \verbinclude output.log
106 *
107 * @version 9.1.0
108 *
109 * \image html scippy.png
110 */
111
112/*--+----1----+----2----+----3----+----4----+----5----+----6----+----7----+----8----+----9----+----0----+----1----+----2*/
113
114/** @page LPI Available implementations of the LP solver interface
115 *
116 * SCIP provides a range of different interfaces to LP solvers:
117 *
118 * LPI name | LP solver
119 * ---------|----------
120 * `spx` | SoPlex
121 * `cpx` | IBM ILOG CPLEX
122 * `xprs` | FICO XPress
123 * `grb` | Gurobi (version at least 7.0.2 required)
124 * `clp` | CoinOR CLP (interface currently sometimes produces wrong results)
125 * `glop` | Google Glop (contained in OR-tools)
126 * `msk` | Mosek (version at least 7.0.0 required)
127 * `qsopt` | QSopt (experimental)
128 * `none` | disables LP solving entirely (not recommended; only for technical reasons)
129 *
130 * There are two different interfaces for SoPlex. The default one (`spx`) uses an updated interface that is provided
131 * by SoPlex itself (since version 2.0), resulting in a slimmer LPI that is similiar to those for CPLEX or XPRESS.
132 * The other one - `spx1` - is the older LPI that directly interfaces the internal simplex solver of SoPlex and
133 * therefore needs to duplicate some features in the LPI that are already available in SoPlex itself. It lacks some
134 * features like persistent scaling which are only available in the modern interface. Upcoming features may not be
135 * supported. Old compilers might have difficulties with the new interface because some C++11 features are required
136 * that may not be supported.
137 *
138 */
139
140/*--+----1----+----2----+----3----+----4----+----5----+----6----+----7----+----8----+----9----+----0----+----1----+----2*/
141
142/** @page NLPISOLVERS Available implementations of the NLP solver interface
143 *
144 * SCIP implements the NLP solver interface for the solvers <a href="https://github.com/coin-or/Ipopt">IPOPT</a>, <a
145 * href="https://worhp.de/">WORHP</a>, and <a href="http://www.mcs.anl.gov/~leyffer/solvers.html">FilterSQP</a>. In
146 * contrast to the implementations of the LP solver interface, SCIP can be compiled with multiple NLP solvers and selects
147 * the solver with the highest priority at the beginning of the solving process.
148 * Currently, the priorities are, in descending order: Ipopt, WORHP/IP, FilterSQP, WORHP/SQP.
149 *
150 * If more than one solver is available, then it is possible to solve all NLPs during the solving process with all
151 * available NLP solvers by setting the parameter `nlpi/all/priority` to the highest value.
152 * In this case, SCIP uses the solution from a solver that provides the best objective value. Other possible use
153 * cases for the availability of multiple solvers have not been implemented yet.
154 *
155 * In the @ref MAKE "GNU make" based build system, building the implementations of the interface for FilterSQP, IPOPT, and
156 * WORHP can be enabled by specifying `FILTERSQP=true`, `IPOPT=true`, and `WORHP=true`, respectively, as argument to the
157 * `make` call.
158 * In the @ref CMAKE "CMAKE" based build system, building the implementation of the interface for IPOPT and WORHP can be
159 * enabled by specifying `IPOPT=on` and `WORHP=on`, respectively, as argument to the `cmake` call.
160 *
161 * @section NLPISOLVERS_IPOPT IPOPT
162 *
163 * <b>IPOPT</b> implements a primal-dual interior point method and uses line searches based on filter methods. It has
164 * been developed by Andreas W&auml;chter and Carl Laird and is available under the Eclipse Public License on <a
165 * href="https://www.coin-or.org/">COIN-OR</a>.
166 *
167 * @section NLPISOLVERS_WORHP WORHP
168 *
169 * <b>WORHP</b> implements a sequential quadratic programming method and a penalty-interior point algorithm. It is
170 * developed at the <a href="https://www.uni-bremen.de/en/">University of Bremen</a> and is free for academic
171 * purposes.
172 *
173 * @section NLPISOLVERS_FILTERSQP FilterSQP
174 *
175 * <b>FilterSQP</b> implements a sequential quadratic programming method. It has been developed by Roger Fletcher
176 * and Sven Leyffer. It is not publicly available, but may be obtained from Sven Leyffer on request.
177 */
178
179/*--+----1----+----2----+----3----+----4----+----5----+----6----+----7----+----8----+----9----+----0----+----1----+----2*/
180
181/**@page GETTINGSTARTED First Steps Walkthrough
182 *
183 * @section GETTINGSTARTED_BLACKBOX Use SCIP to solve a problem
184 *
185 * @subsection GETTINGSTARTED_BLACKBOX_WHY Why SCIP?
186 *
187 * Charlotte lectures at a university and she wants her students to get in touch with solving constraint integer programs (CIPs).
188 * She would like to use SCIP for this purpose because it allows the students to look at the full source code
189 * and SCIP comes with a permissive open source \ref LICENSE "license".
190 * Also, her advisor told her that there are various \ref INTERFACES "interfaces" to SCIP.
191 *
192 * @subsection GETTINGSTARTED_BLACKBOX_PROBLEMS What Kinds Of Problems?
193 *
194 * As a first step she checks \ref WHATPROBLEMS "what types of problems" \SCIP can solve and
195 * \ref FILEREADERS "what are readable formats", and is happy to find MIPs to be among them.
196 *
197 * @subsection GETTINGSTARTED_BLACKBOX_INSTALL Setup
198 *
199 * Charlotte now needs to \ref INSTALL "install SCIP".
200 * She works on a recent computer with a windows system and already has the <a href="https://support.microsoft.com/en-us/help/2977003/the-latest-supported-visual-c-downloads">Visual C++ Redistributable Packages</a> and <a href="https://github.com/oneapi-src/oneTBB">TBB</a> installed.
201 *
202 * Having these prerequisites in place, Charlotte downloads the 64-bit windows exectuable from the <a href="https://scipopt.org/index.php#download">download page</a> and installs it without a problem.
203 * They also read about the <a href="http://www.pokutta.com/blog/pages/scip/scip-teaching.html"> dockerized SCIP container</a> which she wants
204 * to recommend to her students, in case they are unable to install SCIP on their own machines.
205 *
206 * @subsection GETTINGSTARTED_BLACKBOX_SOLVE Solve A First Problem
207 *
208 * To test her installation and get a first feeling for SCIP, Charlotte follows the steps described in the \ref QUICKSTART "quickstart" section to solve a first simple lp problem.
209 *
210 * She has just solved a problem, using SCIP in the command-based mode, by passing a command to the scip call via the `-c` flag.
211 * These commands can also be typed into the interactive shell, that one uses by just calling the binary `scip`.
212 *
213 * After the first solution process worked like a charm, Charlotte downloads a more complicated problem file from the <a href="https://miplib.zib.de/instance_details_enlight_hard.html">MIPLIB 2017</a> page
214 * and follows the \ref SHELL_AFTERINSTALL "interactive shell tutorial".
215 * There, she already learns quite a lot about the solving process and how to work with the interactive shell.
216 *
217 * @subsection GETTINGSTARTED_BLACKBOX_HELP Getting Help
218 *
219 * Feeling happy about having already solved some instances and having worked in interactive mode, Charlotte is curious on what more options SCIP has.
220 * She types `scip -h` to find out.
221 *
222 * She feels confident to being able to understand and use some of the other options, like `-l` to write the output to a logfile, or `-b` to pass a file containing the commands to be executed by scip.
223 * There are some commands that do not yet make a lot of sense to her, but she doesn't worry about it for now.
224 * She will familiarize herself with it over time and with experience.
225 *
226 * @section GETTINGSTARTED_DEVELOP Develop A Custom Plugin
227 *
228 * Alex is a researcher in Charlotte's group and is working on problems that have a very special structure that he hopes to be able to exploit in the solving process.
229 *
230 * Alex heard Charlotte talk about SCIP.
231 * She explained that SCIP is plugin-based, that is, different components (plugins) are implemented using a generic interface and that it is very easy to write your own plugins, like constraint handlers, heuristics etc.
232 * So Alex decides to give it a go and dive into SCIP.
233 *
234 * @subsection GETTINGSTARTED_DEVELOP_PREREQUISITES Prerequisites And Setup
235 *
236 * After some time of using SCIP, he feels confident enough to dig into the source code and decides to write his own plugin.
237 * Alex likes to use his linux machine for developing code, because in his experience compilation is easiest there.
238 *
239 * He starts by downloading the latest <a href="http://scipopt.org/#download">source code tarball</a>,
240 * unpacking it and compiling via \ref CMAKE "cmake", typing `mkdir build; cd build; cmake ..; make`.
241 *
242 * @subsection GETTINGSTARTED_DEVELOP_HELP Getting help
243 *
244 * Before writing any code, he quickly scans over the contents of the \ref PROGRAMMING "Programming with SCIP" page,
245 * so that he knows about some of the pitfalls, best practices and mechanisms.
246 * If a problem comes up later or he gets stuck, he knows what to look out for and where to find help.
247 *
248 * Whenever Alex gets stuck inside the code, he makes use of the extensive documentation to \ref DOC "search for interface methods".
249 *
250 * @subsection GETTINGSTARTED_DEVELOP_EXAMPLE Writing An Example
251 *
252 * Alex is now ready to write his very first example, he creates a new folder `MinEx` under `examples` and puts two files in there:
253 * `CMakeLists.txt`:
254 * ```
255 * cmake_minimum_required(VERSION 3.3)
256 *
257 * project(minex)
258 * find_package(SCIP REQUIRED)
259 * include_directories(${SCIP_INCLUDE_DIRS})
260 *
261 * add_executable(minex
262 * src/cmain.c)
263 *
264 * target_link_libraries(minex ${SCIP_LIBRARIES})
265 *
266 * if( TARGET examples )
267 * add_dependencies( examples minex )
268 * endif()
269 * ```
270 *
271 * and `cmain.c` in a subfolder `src`:
272 * ```
273 * #include <string.h>
274 * #include <scip/scip.h>
275 *
276 * int main( int argc, char** argv )
277 * {
278 * SCIP* scip = NULL;
279 * SCIP_CALL( SCIPcreate(&scip) ); // initialize SCIP
280 * SCIPinfoMessage(scip, NULL, "Hello world.\n"); // output greeting
281 * SCIP_CALL( SCIPfree(&scip) ); // free SCIP
282 * BMScheckEmptyMemory();
283 * return 0;
284 * }
285 * ```
286 *
287 * This is a minimal example that just prints "Hello world." and exits.
288 * Alex compiles and runs it via cmake with the following command:
289 * ```
290 * mkdir build; cd build; cmake .. -DSCIP_DIR=../../build/; make; ./minex
291 * ```
292 *
293 * After having successfully written this minimal example, Alex follows the instructions to \ref START "start a new project" to start his actual project and extend this most basic code.
294 *
295 * @subsection GETTINGSTARTED_DEVELOP_CONSTRAINTHANDLER Writing A Plugin
296 *
297 * Alex now needs a custom constraint handler in his project, for that he will write a custom plugin.
298 * He looks up the instructions in the \ref HOWTOADD "How to add..." page and is
299 * very happy to find \ref CONS "a page with a detailed description" what he has to do.
300 *
301 * Furthermore he found exercises for implementing plugins for the example of the
302 * linear ordering problem. The corresponding code framework
303 * (<a href="https://scipopt.org/workshop2018/pyscipopt-exercises.tgz">Python</a> or
304 * <a href="https://scipopt.org/workshop2018/exercise.pdf">C/C++</a>)
305 * could form a good starting point for a new project as well.
306 *
307 * @subsection GETTINGSTARTED_DEVELOP_REOPTMIZATION Using Functionality In A Plugin
308 *
309 * After implementing his own constraint handler Alex realizes that he needs to use repotimization in his project.
310 * He looks up the \ref HOWTOUSESECTION "How to use..." section and finds some more information about \ref REOPT "how to use reoptimization".
311 *
312 */
313
314/**@page INSTALL Installing SCIP
315 *
316 * There are two options to get a running SCIP on your system.
317 * You can either use one of the installers or you can compile it yourself.
318 *
319 * Which one you choose depends on your use case and your level of expertise.
320 * If you just want to use SCIP as a black box solver you should use an installer with a precompiled binary from the <a href="http://scipopt.org/#download">download section</a>.
321 * This is highly recommended for new users.
322 * If you are just curious and want to try it out you can use the <a href="http://www.pokutta.com/blog/pages/scip/scip-teaching.html"> dockerized SCIP container</a>.
323 *
324 * However, if you want to develop your own plugin for SCIP, you have to compile SCIP or the SCIPOptSuite from source code, which are available as a tarball from the <a href="http://scipopt.org/#download">download page</a>.
325 * Note that you might need some level of experience to be able to do this, this is described in the following.
326 *
327 * SCIP lets you choose freely between its own, manually maintained Makefile system
328 * or the CMake cross platform build system generator. For new users, we strongly
329 * recommend to use CMake, if available on their targeted platform.
330 *
331 * Be aware that generated libraries and binaries of both systems might be different and incompatible.
332 *
333 * - @subpage md_INSTALL "Installation instructions"
334 * - @subpage LPI "Available implementations of the LP solver interface"
335 * - @subpage NLPISOLVERS "Available implementations of the NLP solver interface"
336 * - @subpage INSTALL_APPLICATIONS_EXAMPLES "Installation of applications and examples"
337 */
338
339/**@page PROGRAMMING Programming with SCIP
340 *
341 * - @subpage CODE "Coding style guidelines"
342 * - @subpage OBJ "Creating, capturing, releasing, and adding data objects"
343 * - @subpage MEMORY "Using the memory functions of SCIP"
344 * - @subpage DEBUG "Debugging"
345 * - @subpage STAGES "SCIP stages"
346 */
347/**@page HOWTOADD How to add ...
348 *
349 * Below you find for most plugin types a detailed description of how to implement and add them to \SCIP.
350 *
351 * - @subpage CONS "Constraint handlers"
352 * - @subpage PRICER "Variable pricers"
353 * - @subpage PRESOL "Presolvers"
354 * - @subpage SEPA "Separators"
355 * - @subpage PROP "Propagators"
356 * - @subpage BRANCH "Branching rules"
357 * - @subpage CUTSEL "Cut selectors"
358 * - @subpage NODESEL "Node selectors"
359 * - @subpage HEUR "Primal heuristics"
360 * - @subpage DIVINGHEUR "Diving heuristics"
361 * - @subpage RELAX "Relaxation handlers"
362 * - @subpage READER "File readers"
363 * - @subpage DIALOG "Dialogs"
364 * - @subpage DISP "Display columns"
365 * - @subpage EVENT "Event handler"
366 * - @subpage EXPRHDLR "Expression handlers"
367 * - @subpage NLHDLR "Nonlinear handlers"
368 * - @subpage NLPI "Interfaces to NLP solvers"
369 * - @subpage EXPRINT "Interfaces to expression interpreters"
370 * - @subpage PARAM "additional user parameters"
371 * - @subpage TABLE "Statistics tables"
372 * - @subpage BENDER "Benders' decomposition"
373 * + @subpage BENDERSCUT "Benders' decomposition cuts"
374 */
375/**@page HOWTOUSESECTION How to use ...
376 *
377 * - @subpage CONF "Conflict analysis"
378 * - @subpage TEST "How to run automated tests with SCIP"
379 * - @subpage COUNTER "How to use SCIP to count feasible solutions"
380 * - @subpage REOPT "How to use reoptimization in SCIP"
381 * - @subpage CONCSCIP "How to use the concurrent solving mode in SCIP"
382 * - @subpage DECOMP "How to provide a problem decomposition"
383 * - @subpage BENDDECF "How to use the Benders' decomposition framework"
384 * - @subpage TRAINESTIMATION "How to train custom tree size estimation for SCIP"
385 * - @subpage SYMMETRY "How to use symmetry handling in SCIP"
386 * - @subpage PROBINGDIVING "How to use probing and diving mode"
387 */
388
389/**@page AUTHORS SCIP Authors
390 *
391 * A list of all current and former developers as well as contributors can
392 * be found on the
393 * <a class="el" href="http://scipopt.org/#developers">Main Web Page</a>.
394 *
395 */
396
397/**@page EXTERNALDOC Links to external documentation
398 *
399 * <a class="el" href="https://www.cgudapati.com/integer-programming/2019/12/15/Getting-Started-With-SCIP-Optimization-Suite.html">Getting Started with SCIP optimization in C++: A toy example</a> by Chaitanya Gudapati.
400 *
401 */
402
403/**@page CHG Release notes and changes between different versions of SCIP
404 *
405 * New features, peformance improvements, and interface changes between different versions of SCIP are documented in the
406 * release notes:
407 *
408 * - \subpage RN9 "SCIP 9"
409 * - \subpage RN8 "SCIP 8"
410 * - \subpage RN70 "SCIP 7.0"
411 * - \subpage RN60 "SCIP 6.0"
412 * - \subpage RN50 "SCIP 5.0"
413 * - \subpage RN40 "SCIP 4.0"
414 * - \subpage RN32 "SCIP 3.2"
415 * - \subpage RN31 "SCIP 3.1"
416 * - \subpage RN30 "SCIP 3.0"
417 * - \subpage RN21 "SCIP 2.1"
418 * - \subpage RN20 "SCIP 2.0"
419 * - \subpage RN12 "SCIP 1.2"
420 * - \subpage RN11 "SCIP 1.1"
421 * - \subpage RN10 "SCIP 1.0"
422 * - \subpage RN09 "SCIP 0.9"
423 * - \subpage RN08 "SCIP 0.8"
424 * - \subpage RN07 "SCIP 0.7"
425 *
426 */
427
428/**@page WHATPROBLEMS What types of optimization problems does SCIP solve?
429 *
430 * As a stand-alone solver, \SCIP can solve mixed-integer nonlinear programs \b (MINLPs), to which it applies
431 * an LP based spatial branch-and-cut algorithm. This method is guaranteed to solve bounded MINLPs
432 * within a given numerical tolerance in a finite amount of time. In particular, \SCIP is a stand-alone
433 * solver for mixed-integer linear programs \b (MIPs).
434 *
435 * As a framework, \SCIP also provides the tools to solve constraint optimization problems defined over
436 * integer and continuous variables. Therefore, the design of \SCIP
437 * supports the easy integration of constraints of arbitrary type into the solver.
438 * More precisely, \SCIP can handle the class of constraint integer programs \b (CIPs), which are constraint optimization problems
439 * that become linear programs (LPs) after the integer variables are fixed.
440 *
441 * @section PROBLEMCLASSES Some important subclasses of CIP and MINLP
442 *
443 * The following table gives a non-exhaustive list of common types of mathematical optimization problems that can be solved
444 * through \SCIP itself or one of its extensions. Some recommendations are given on how to compile \SCIP for a
445 * certain problem class and how make best use of \SCIP. The file format column gives some common file
446 * formats for every class. Note that since some of the mentioned problem classes are more general than others (like
447 * every LP is a MIP is an MINLP), the formats for the superclass should always work just as fine, although they
448 * may be less common for the class at hand.
449 *
450 * Please see also the pages on \ref EXAMPLES "SCIP Examples" and \ref APPLICATIONS "SCIP Applications" to learn more on how
451 * to extend \SCIP for a particular MIP, MINLP, or CIP application.
452 * All examples and applications use the C or C++ APIs of \SCIP. Please have a look at \ref INTERFACES "SCIP interfaces"
453 * to see how to use \SCIP from within other programming languages.
454 *
455 * <table class="types">
456 * <caption align="top">Some problem classes that can be solved by \SCIP</caption>
457 * <tr style="border-bottom: medium solid black;">
458 * <th>Problem class</th>
459 * <th>Mathematical problem description</th>
460 * <th>Supported file formats</th>
461 * <th>Recommendations</th>
462 * </tr>
463 * <tr>
464 * <td>Mixed-integer linear program (MIP)</td>
465 * <td>\f{align*}{
466 * \text{min} \quad& c^T x \\
467 * \text{s.t.} \quad& Ax \geq b \\
468 * &l_{j} \leq x_{j} \leq u_{j} && \forall j \in \mathcal{N} \\
469 * &x_{j} \in \mathbb{Z} && \forall j \in \mathcal{I}
470 * \f}
471 * </td>
472 * <td>
473 * <ul>
474 * <li>\ref reader_cip.h "CIP"</li>
475 * <li>\ref reader_mps.h "MPS"</li>
476 * <li>\ref reader_lp.h "LP"</li>
477 * <li>\ref reader_zpl.h "ZPL"</li>
478 * </ul>
479 * </td>
480 * <td>
481 * <ul>
482 * <li>\SCIP requires an external LP solver to solve LP relaxations, which needs to be specified
483 * at compilation time. By default, it uses SoPlex (<code>LPS=spx</code>). See \ref MAKE for a
484 * list of available LP solver interfaces and how to use them inside \SCIP.</li>
485 * <li>Compile with Zimpl support (<code>ZIMPL=true</code>) to read in Zimpl models directly.</li>
486 * <li>\SCIP comes with many different parameters. Use the provided emphasis settings (see \ref SHELL "this tutorial")
487 * to change many parameters at once and boost the performance.</li>
488 * <li>Test instances are available at <code>check/instances/MIP/</code>.</li>
489 * </ul>
490 * </td>
491 * </tr>
492 * <tr>
493 * <td>Mixed-integer nonlinear program (MINLP)</td>
494 * <td>\f{align*}{
495 * \text{min} \quad& f(x) \\
496 * \text{s.t.} \quad& g_{i}(x) \leq 0 && \forall i \in \mathcal{M} \\
497 * &l_{j} \leq x_{j} \leq u_{j} && \forall j \in \mathcal{N} \\
498 * &x_{j} \in \mathbb{Z} && \forall j \in \mathcal{I}
499 * \f}
500 * </td>
501 * <td>
502 * <ul>
503 * <li>\ref reader_cip.h "CIP"</li>
504 * <li>\ref reader_gms.h "GMS"</li>
505 * <li>\ref reader_osil.h "OSiL"</li>
506 * <li>\ref reader_pip.h "PIP"</li>
507 * <li>\ref reader_zpl.h "ZPL"</li>
508 * <li>For MIQCPS:
509 * <ul>
510 * <li>\ref reader_lp.h "LP"</li>
511 * <li>\ref reader_mps.h "MPS"</li>
512 * </ul>
513 * </li>
514 * </ul>
515 * </td>
516 * <td>
517 * <ul>
518 * <li>Compile with <code>IPOPT=true</code> for better performance.</li>
519 * <li>Compile with <code>WORHP=true</code> for better performance.</li>
520 * <li>Compile with <code>FILTERSQP=true</code> for better performance.</li>
521 * <li>See <a href="FAQ\FILEEXT#minlptypes"> Which kind of MINLPs are supported by \SCIP? </a> in the FAQ.</li>
522 * <li>There is an interface for the modelling language AMPL, see \ref INTERFACES.</li>
523 * <li>Mixed-integer quadratically constrained programs (MIQCP) can also be formulated in the file formats
524 * <ul>
525 * <li>\ref reader_lp.h "LP", and</li>
526 * <li>\ref reader_mps.h "MPS".</li>
527 * </ul>
528 * </li>
529 * <li>Test instances are available at <code>check/instances/MINLP/</code>.</li>
530 * </ul>
531 * </td>
532 * </td>
533 * <tr>
534 * <td>Constraint Integer Program (CIP)</td>
535 * <td>\f{align*}{
536 * \text{min} \quad& c^T x + d^T y \\
537 * \text{s.t.} \quad& C_i(x,y) = \text{true} && \forall i \in \mathcal{M} \\
538 * & x \in \mathbb{Z}^{p}, y \in \mathbb{R}^{n - p}
539 * \f}
540 * where \f$\forall i \in\mathcal{M}, \forall x^* \in \mathbb{Z}^{p},\f$ \f$ \{ y : C_i(x^*, y) = \text{true} \} \f$ is a polyhedron.
541 * </td>
542 * <td>
543 * <ul>
544 * <li>\ref reader_cip.h "CIP"</li>
545 * <li>\ref reader_fzn.h "FlatZinc"</li>
546 * </ul>
547 * </td>
548 * <td>
549 * <ul>
550 * <li>\SCIP supports a limited number of general constraints; see \ref CONS "How to add constraint handlers"
551 * to learn how to extend the \SCIP framework to a given CIP.</li>
552 * <li>Use the emphasis setting <code>set emphasis cpsolver</code> to completely disable LP solves and
553 * use depth-first search with periodic restarts, see also
554 * <a href="FAQ\FILEEXT#scipascpsolver"> Can I use \SCIP as a pure CP solver? </a> in the FAQ.</li>
555 * <li>Test instances are available at <code>check/instances/CP</code>.</li>
556 * </ul>
557 * </td>
558 * <tr>
559 * <td>Convex MINLP</td>
560 * <td>Like MINLP, \f$f\f$ and all \f$g_i\f$ are \b convex.</td>
561 * <td>see MINLP formats</td>
562 * <td>
563 * <ul>
564 * <li>See the comments for MINLP.</li>
565 * <li>In addition, use <code>constraints/nonlinear/assumeconvex = TRUE</code> to inform \SCIP about a convex
566 * problem in cases where the automated detection is not strong enough.</li>
567 * <li>Test instances are available at <code>check/instances/MINLP/circle.lp</code>.</li>
568 * </ul>
569 * </td>
570 * </td>
571 * <tr>
572 * <td>Linear program (LP)</td>
573 * <td>\f{align*}{
574 * \text{min} \quad& c^T x \\
575 * \text{s.t.} \quad& Ax \geq b \\
576 * & x_{j} \geq 0 && \forall j \in \mathcal{N}
577 * \f}
578 * </td>
579 * <td>see MIP formats</td>
580 * <td>See <a href="FAQ\FILEEXT#scipaslpsolver">Can I use \SCIP as a pure LP solver</a> in the FAQ.</td>
581 * </td>
582 * <tr>
583 * <td>Pseudoboolean optimization</td>
584 * <td>\f{align*}{
585 * \text{min} \quad& c^T x \\
586 * \text{s.t.} \quad& \sum_{k=0}^p a_{ik} \cdot \prod_{j \in \mathcal{N}_{ik}} x_j \leq b_i && \forall i \in \mathcal{M} \\
587 * &x_{j} \in \{0,1\} && \forall j \in \mathcal{N}
588 * \f}
589 * </td>
590 * <td>
591 * <ul>
592 * <li>\ref reader_wbo.h "WBO"</li>
593 * <li>\ref reader_opb.h "OPB"</li>
594 * </ul>
595 * </td>
596 * <td>
597 * <ul>
598 * <li>Test instances are available at <code>check/instances/PseudoBoolean/</code>.</li>
599 * </ul>
600 * </td>
601 * </tr>
602 * <tr>
603 * <td>Satisfiability (SAT) and variants</td>
604 * <td>\f{align*}{
605 * \text{min} \quad& 0 \\
606 * \text{s.t.} \quad&\bigvee\limits_{j \in B_i} x_j \vee \bigvee\limits_{j \in \bar{B}_i} \neg x_j = \text{true} && \forall i \in \mathcal{M}\\
607 * &x_{j} \in \{\text{false},\text{true}\} && \forall j \in \mathcal{N}
608 * \f}
609 * </td>
610 * <td>
611 * <ul>
612 * <li>\ref reader_cnf.h "CNF"</li>
613 * </ul>
614 * </td>
615 * <td>
616 * <ul>
617 * <li>Use the emphasis setting <code>set emphasis cpsolver</code> to completely disable LP solves and
618 * use depth-first search with periodic restarts, see also
619 * <a href="FAQ\FILEEXT#scipascpsolver"> Can I use \SCIP as a pure CP/SAT solver? </a> in the FAQ.</li>
620 * <li>Test instances are available at <code>check/instances/SAT/</code>.</li>
621 * </ul>
622 * </td>
623 * </tr>
624 * <tr>
625 * <td>Multicriteria optimization</td>
626 * <td>\f{align*}{
627 * \text{min} \quad &(c_1^T x,\ldots,c_k^T x) \\
628 * \text{s.t. } \quad& Ax \geq b \\
629 * &x \in \mathbb{K}^n
630 * \f}
631 * where \f$\mathbb{K}\f$ is either \f$\mathbb{Z}\f$ or \f$\mathbb{R}\f$.
632 * </td>
633 * <td colspan="3"> see the <a href="http://polyscip.zib.de/">PolySCIP web page</a></td>
634 * </tr>
635 * <tr>
636 * <td>Mixed-integer semidefinite program (MISDP)</td>
637 * <td>\f{align*}{
638 * \text{inf} \quad \thinspace & b^T y \\
639 * \text{s.t.} \quad & \sum_{j=1}^m A_j\, y_j - A_0 \succeq 0 \\
640 * & y_j \in \mathbb{Z} && \forall\, j \in \mathcal{I}
641 * \f}
642 * </td>
643 * <td colspan="3"> see the <a href="http://www.opt.tu-darmstadt.de/scipsdp/">SCIP-SDP web page</a></td>
644 * </tr>
645 * </table>
646 *
647 *
648 */
649
650/*--+----1----+----2----+----3----+----4----+----5----+----6----+----7----+----8----+----9----+----0----+----1----+----2*/
651
652/**@page CODE Coding style guidelines
653 *
654 * We follow the following coding style guidelines and recommend them for all developers.
655 *
656 * @section CODESPACING Spacing:
657 *
658 * - Indentation is 3 spaces. No tabs anywhere in the code.
659 * - Every opening parenthesis requires an additional indentation of 3 spaces.
660 *
661 * @refsnippet{src/scip/branch_relpscost.c,SnippetCodeStyleParenIndent}
662 *
663 * - Spaces around all operators.
664 * - Spaces around the arguments inside an if/for/while-statement, as well as inside macros (e.g., SCIP_CALL).
665 * - No spaces between control structure keywords like "if", "for", "while", "switch" and the corresponding brackets.
666 * - No spaces between a function name and the parenthesis in both the definition and function calls.
667 * - Braces are on a new line and not indented.
668 * - Braces in if/for-statements should only be omitted if they enclose a single line.
669 *
670 * @refsnippet{src/scip/branch_relpscost.c,SnippetCodeStyleIfFor}
671 *
672 * - In function declarations, every parameter is on a new line. The name of the parameter starts at column 26,
673 * the comment starts at column 46 (if column-count starts with 1).
674 * - Maximal line length is 120 characters.
675 * - Always only one declaration in a line.
676 * - Variable names should be all lower case.
677 *
678 * @refsnippet{src/scip/branch_relpscost.c,SnippetCodeStyleDeclaration}
679 *
680 * - Blank lines are inserted where it improves readability.
681 * - Multiple blank lines are used to structure the code where single blank lines are insufficient,
682 * e.g., between differrent sections of the code.
683 *
684 * @refsnippet{src/scip/heur_xyz.c,SnippetCodeStyleBlanks}
685 *
686 * @section CODENAMING Naming:
687 *
688 * - Use assert() to show preconditions for the parameters, invariants, and postconditions.
689 * - Make all functions that are not used outside the module 'static'.
690 * - Naming should start with a lower case letter.
691 *
692 * @refsnippet{src/scip/branch_relpscost.c,SnippetCodeStyleStaticAsserts}
693 *
694 * - All global functions start with "SCIP". In the usual naming scheme this is followed by the object and a method name
695 * like in SCIPlpAddRow(). Functions return TRUE or FALSE should be named like SCIPisFeasEQ().
696 *
697 * @refsnippet{src/scip/scip_numerics.h,SnippetCodeStyleNaming}
698 *
699 * - For each structure there is a typedef with the name in all upper case.
700 * - Defines should be named all upper case.
701 *
702 * @refsnippet{src/scip/type_set.h,SnippetCodeStyleExample}
703 *
704 * @section CODEDOC Documentation:
705 *
706 * - Document functions, parameters, and variables in a doxygen conformed way.
707 * - Please do not leave code in comments that has been commented out, don't use `#if
708 * 0`. Instead put the code within defines `#ifdef SCIP_DISABLED_CODE` and add an explanation.
709 * - Todos need double stars to be registered by doxygen.
710 * - When documenting methods, the first brief description starts with lower case and is separated by semi-colons, if necessary
711 * The longer description starts capitalized and consists of complete sentences.
712 * If the documentation consists of multiple lines, the comment end must be on a new line.
713 *
714 * @refsnippet{src/scip/scip_datastructures.h,SnippetCodeStyleComment}
715 *
716 *
717 * @section XEMACS Customize (x)emacs
718 *
719 * If you are using (x)emacs, you can use the following customization for the c++-mode. These settings satisfy the
720 * coding guidelines of \SCIP.
721 *
722 * \include codestyle/emacs_scip_codestyle.el
723 *
724 *
725 * @section ECLIPSE Customize eclipse
726 *
727 * Eclipse user can use the profile below. This profile does not match the \SCIP coding guideline completely.
728 *
729 * \include codestyle/eclipse_scip_codestyle.xml
730 */
731
732/*--+----1----+----2----+----3----+----4----+----5----+----6----+----7----+----8----+----9----+----0----+----1----+----2*/
733
734/**@page START How to start a new project
735 *
736 * Once you succeeded installing \SCIP together with an LP-solver on your system,
737 * you have a powerful tool for solving MIPs, MIQCPs,
738 * MINLPs, etc... at hand. \SCIP can also be customized to the type of problems you
739 * are working on by additional plugins.
740 * Instructions on how to write a new plugin and include it in \SCIP can be found in the corresponding
741 * \ref HOWTOADD "How to add ... pages".
742 *
743 * \SCIP can also be used for writing your own branch-and-cut or branch-and-cut-and-price code. \SCIP already
744 * provides a number of existing code examples which we suggest as both reference and starting point
745 * for these kinds of projects.
746 * Below, you find some hints of how to start such a project.
747 *
748 * @section START_CHOICE Choose an example project
749 *
750 * The example should be chosen depending on the programming language (<b>C</b> or <b>C++</b>) and the purpose
751 * (<b>branch-and-cut</b> or <b>branch-and-cut-and-price</b>) of your project.
752 * <br>
753 * We suggest the use of one of the following examples:
754 * - The \ref VRP_MAIN "Vehicle Routing Problem Example" is a <b>branch-and-cut-and-price</b> (column generation)-code
755 * in <b>C++</b>.
756 * - The \ref BINPACKING_MAIN "Binpacking Example"
757 * and the \ref COLORING_MAIN "Coloring application" are
758 * <b>branch-and-cut-and-price</b> (column generation)-codes in <b>C</b>.
759 * - The \ref TSP_MAIN "TSP example"
760 * is a <b>branch-and-cut</b>-code in <b>C++</b>.
761 * - The \ref LOP_MAIN "LOP example"
762 * is a <b>branch-and-cut</b>-code in <b>C</b>.
763 *
764 * More examples can be found in the \ref EXAMPLES "list of Examples".
765 *
766 * - Copy one of the examples in the <code>examples</code> directory (in the \SCIP root
767 * directory). For instance, type
768 * \verbatim
769 cp -r examples/Binpacking/ ../SCIPProject/ ; cd ../SCIPProject
770 \endverbatim
771 * from the \SCIP root directory for copying the content of the <code>Binpacking</code>-example into a fresh
772 * directory named SCIPProject in the parent directory of the \SCIP root directory and jumping to
773 * the new SCIPProject directory rightafter.
774 *
775 * @section START_CMAKE Building with CMake
776 *
777 * It is recommended for all new users to use the CMake build system configuration, if available on their platform.
778 *
779 * - Open the <code>CMakeLists</code> (some examples projects have a subdirectory "check" for testing) via
780 * \verbatim
781 kate CMakeLists.txt & kate check/CMakeLists.txt # if check/CMakeLists.txt is available
782 \endverbatim
783 * and replace all instances of the copied project's name (e.g. <code>binpacking</code>) with your project name.
784 * - Create a new subdirectory, jump to the new directory and use cmake specifying your \SCIP directory. For instance, type
785 * \verbatim
786 mkdir Release ; cd Release ; cmake .. -DSCIP_DIR=../scip/Release
787 \endverbatim
788 * and compile using the <code>make</code> command. For the CMake equivalents of all the flags that can be used in \SCIP, see \ref CMAKE.
789 *
790 *
791 * @section START_MAKE Building with the Makefile system
792 *
793 * If CMake should be unavailable on your targeted platform, try the classic Makefile system of SCIP.
794 *
795 * - Open the <code>Makefile</code> via
796 * \verbatim
797 kate Makefile
798 \endverbatim
799 * and edit the following variables at the top to have a compilable code:
800 *
801 * - specify a correct path to the \SCIP root (<code>SCIPDIR</code>)
802 * - rename the targets name (<code>MAINNAME</code>)
803 * - adjust the source file names (<code>MAINOBJ</code>).
804 * .
805 * - Once you have edited the makefile, you can use all the flags that can be used in \SCIP to
806 * compile your code, see \ref MAKE.
807 *
808 */
809
810/**@page EXAMPLES Example projects
811 *
812 * \SCIP contains several examples that demonstrate its usage. They are contained in the &quot;examples&quot; directory
813 * in the source code distribution.
814 *
815 * <table>
816 * <tr>
817 * <td colspan="2">
818 * <b>
819 * Callable library
820 * </b>
821 * </td>
822 * </tr>
823 * <tr>
824 * <td>
825 * @subpage CALLABLELIBRARY_MAIN "Callable Library Example"
826 * </td>
827 * <td>
828 * An example showing how to setup constraints (esp. nonlinear ones) when using \SCIP as callable library.
829 * </td>
830 * </tr>
831 * <tr>
832 * <td>
833 * @subpage MIPSOLVER_MAIN "MIP solver"
834 * </td>
835 * <td>
836 * A minimal implementation for using \SCIP included into another source code
837 * </td>
838 * </tr>
839 * <tr>
840 * <td>
841 * @subpage QUEENS_MAIN "The n-Queens Problem"
842 * </td>
843 * <td>
844 * Using SCIP's callable library for solving the n-queens problem.
845 * </td>
846 * </tr>
847 * <tr>
848 * <td colspan="2">
849 * <b>
850 * Extending SCIP by custom plugins
851 * </b>
852 * </td>
853 * </tr>
854 * <tr>
855 * <td>
856 * @subpage EVENTHDLR_MAIN "Event handler"
857 * </td>
858 * <td>
859 * A small example illustrating the use of an event handler.
860 * </td>
861 * </tr>
862 * <tr>
863 * <td>
864 * @subpage GMI_MAIN "Gomory mixed integer cut example"
865 * </td>
866 * <td>
867 * An example about Gomory mixed-integer cuts.
868 * </td>
869 * </tr>
870 * <tr>
871 * <td>
872 * @subpage RELAXATOR_MAIN "Relaxator example"
873 * </td>
874 * <td>
875 * An example about using custom relaxators.
876 * </td>
877 * </tr>
878 * <tr>
879 * <td colspan="2">
880 * <b>
881 * Branch-and-cut
882 * </b>
883 * </td>
884 * </tr>
885 * <tr>
886 * <td>
887 * @subpage SUDOKU_MAIN "Sudoku example"
888 * </td>
889 * <td>
890 * An example solving sudokus.
891 * </td>
892 * </tr>
893 * <tr>
894 * <td>
895 * @subpage LOP_MAIN "Linear Ordering"
896 * </td>
897 * <td>
898 * An example for implementing a constraint handler.
899 * </td>
900 * </tr>
901 * <tr>
902 * <td>
903 * @subpage TSP_MAIN "The TSP example"
904 * </td>
905 * <td>
906 * A short implementations of a constraint handler, two easy combinatorial heuristics, a file reader, etc. which
907 * demonstrate the usage of \SCIP as a branch-and-cut-framework for solving traveling salesman problem instances.
908 * </td>
909 * </tr>
910 * <tr>
911 * <td colspan="2">
912 * <b>
913 * Branch-and-price
914 * </b>
915 * </td>
916 * </tr>
917 * <tr>
918 * <td>
919 * @subpage BINPACKING_MAIN "Binpacking"
920 * </td>
921 * <td>
922 * An implementation of the column generation approach for the binpacking problem. It includes a customized reader,
923 * Ryan/Foster branching rule, (global) problem data, variable data, and constraint handler.
924 * </td>
925 * </tr>
926 * <tr>
927 * <td>
928 * @subpage VRP_MAIN "Vehicle Routing"
929 * </td>
930 * <td>
931 * A solver for a simple capacity-constrained vehicle routing problem, which is based on pricing tours via a dynamic
932 * programming algorithm.
933 * </td>
934 * </tr>
935 * <tr>
936 * <td colspan="2">
937 * <b>
938 * Benders' decomposition
939 * </b>
940 * </td>
941 * </tr>
942 * <tr>
943 * <td>
944 * @subpage SCFLP_MAIN "Stochastic capacitated facility location problem"
945 * </td>
946 * <td>
947 * A stochastic programming problem that demonstrates the use of the Benders' decomposition framework within SCIP.
948 * </td>
949 * </tr>
950 * </table>
951 */
952
953/** @page APPLICATIONS Application projects
954 *
955 * There are several extensions of \SCIP for particular applications included in the release. They are contained in the &quot;applications&quot; directory
956 * in the source code distribution.
957 *
958 * <table>
959 * <tr>
960 * <td>
961 * @subpage COLORING_MAIN
962 * </td>
963 * <td>
964 * An implementation of the column generation approach for graph coloring of Mehrotra and Trick.
965 * </td>
966 * </tr>
967 * <tr>
968 * <td>
969 * @subpage CYCLECLUSTERING_MAIN
970 * </td>
971 * <td>
972 * Branch-and-cut implementation of a graph partitioning problem used for Markov state models.
973 * </td>
974 * </tr>
975 * <tr>
976 * <td>
977 * @subpage MINIISC_MAIN
978 * </td>
979 * <td>
980 * A solver that computes irreducible infeasible subsystems using Benders decomposition
981 * </td>
982 * </tr>
983 * <tr>
984 * <td>
985 * @subpage RINGPACKING_MAIN "Ringpacking"
986 * </td>
987 * <td>
988 * An implementation of the column generation approach for the Ringpacking Problem. It includes a customized reader,
989 * (global) problem data, variable data, and constraint handler.
990 * </td>
991 * </tr>
992 * <tr>
993 * <td>
994 * @subpage SCHEDULER_MAIN
995 * </td>
996 * <td>
997 * A solver for scheduling problems.
998 * </td>
999 * </tr>
1000 * </table>
1001 *
1002 */
1003
1004
1005/**@page SHELL Tutorial: the interactive shell
1006 *
1007 * If you are using \SCIP as a black box solver, here you will find some tips and tricks what you can do.
1008 *
1009 * @section TUTORIAL_OPTIMIZE Read and optimize a problem instance
1010 *
1011 * @subsection SHELL_PREREQUISITES "Prerequisites"
1012 *
1013 * First of all, we need a \SCIP binary and an example problem file to work with.
1014 * For installation we refer you to the \ref INSTALL section.
1015 *
1016 * Therefore, you can either download the \SCIP standard distribution (which includes problem files) and compile it on your own or you can download a
1017 * precompiled binary and an example problem separately. \SCIP can read files in LP, MPS, ZPL, WBO, FZN, PIP, OSiL, and
1018 * other formats (see \ref FILEREADERS).
1019 *
1020 * If you want to download the source code of the \SCIP standard distribution, we recommend to go to the <a
1021 * href="https://scipopt.org/#download">SCIP download section</a>, download the latest release,
1022 * inflate the tarball (e.g., with "tar xzf scipoptsuite-[version].tgz"), and follow the instructions
1023 * in the INSTALL file. The instance stein27, which will serve as an example in this tutorial, can be found under
1024 * scipoptsuite-[version]/scip-[version]/check/instances/MIP/stein27.fzn.
1025 * Alternatively you can download an instance file from the <a href="https://miplib.zib.de/tag_benchmark.html">MIPLIB 2017 page</a>.
1026 *
1027 * If you want to download a precompiled binary, go to the <a href="http://scipopt.org/#download">SCIP download
1028 * section</a> and download an appropriate binary for your operating system. The \SCIP source code distribution already comes with
1029 * the example instance used throughout this tutorial. To follow this tutorial with a precompiled binary, we recommend downloading the instance
1030 * <a href="http://miplib2010.zib.de/miplib3/miplib3/stein27.mps.gz">stein27</a> from
1031 * the <a href="http://miplib2010.zib.de/miplib3/miplib.html">MIPLIB 3.0</a> homepage.
1032 *
1033 * @subsection SHELL_AFTERINSTALL "After installation"
1034 *
1035 * Now start your binary, without any arguments. This opens the interactive shell, which should look somehow like this:
1036 *
1037 * @snippet shelltutorial/shelltutorialannotated.tmp SnippetVersion
1038 *
1039 * First of all "help" shows you a list of all available shell commands. Brackets indicate a submenu with further options.
1040 *
1041 * @snippet shelltutorial/shelltutorialannotated.tmp SnippetHelp
1042 *
1043 * Okay, let's solve the example instance... use "read check/instances/MIP/stein27.fzn" (or the problem file of your choice) to parse the instance file, "optimize" to solve it and "display
1044 * solution" to show the nonzero variables of the best found solution.
1045 *
1046 * @snippet shelltutorial/shelltutorialannotated.tmp SnippetOpt1
1047 *
1048 * What do we see here? After "optimize", SCIP first goes into presolving. Not much is happening for this instance, just
1049 * the linear constraints get upgraded to more specific types. Each round of presolving will be displayed in a single
1050 * line, with a short summary at the end. Then, we see the actual solving process. The table output of the branch-and-cut
1051 * solving process is very detailed during the root node. Afterwards, a new line is displayed every 100th node.
1052 * Furthermore, every new incumbent solution triggers a new table row, starting with a character to indicate the
1053 * heuristic that found the solution. Which letter represents which heuristic can be seen with the
1054 * "display heuristics" command, see \ref TUTORIAL_STATISTICS for an example.
1055 *
1056 * After some lines the root node processing is finished. From now on, we will see an output line every hundredth node or
1057 * whenever a new incumbent is found. After some more nodes, the "dualbound" starts
1058 * moving, too. At one point, both will be the same, and the solving process terminates, showing us some wrap-up
1059 * information.
1060 *
1061 * The exact performance may of course vary among different architectures and operating systems. Do not be worried if
1062 * your installation needs more or less time or nodes to solve. Also, this instance has more than 2000 different optimal
1063 * solutions. The optimal objective value always has to be 18, but the solution vector may differ. If you are interested
1064 * in this behavior, which is called "performance variability", you may have a look at the MIPLIB2010 paper.
1065 *
1066 * @section TUTORIAL_FILEIO Writing problems and solutions to a file
1067
1068 * \SCIP can also write information to files. E.g., we could store the incumbent solution to a file, or output the
1069 * problem instance in another file format (the LP format is much more human readable than the MPS format, for example).
1070 *
1071 * @snippet shelltutorial/shelltutorialannotated.tmp SnippetWriteSolutions
1072 *
1073 * Passing starting solutions can increase the solving performance so that \SCIP does not need to construct an initial feasible solution
1074 * by itself. After reading the problem instance, use the "read" command again, this time with a file containing solution information.
1075 * Solutions can be specified in a raw or xml-format and must have the file extension ".sol", see the documentation of the
1076 * \ref reader_sol.h "solution reader of SCIP" for further information.
1077 *
1078 * Customized settings are not written or read with the "write" and "read" commands, but with the three commands
1079 *
1080 * @snippet shelltutorial/shelltutorialannotated.tmp SnippetSaveSettingsOverview
1081 *
1082 * See the section on parameters \ref TUTORIAL_PARAMETERS for more information.
1083 *
1084 * @section TUTORIAL_STATISTICS Displaying detailed solving statistics
1085 *
1086 * We might want to have some more information now. Which of the heuristics found solutions? Which plugins
1087 * were called during the solutions process and how much time did they spend?
1088 * Information on certain plugin types (e.g., heuristics, branching rules, separators) is displayed via
1089 * "display <plugin-type>", information on the solution process via "display statistics", and "display problem"
1090 * shows the current instance.
1091 *
1092 * @snippet shelltutorial/shelltutorialannotated.tmp SnippetDisplayStatistics
1093 *
1094 * The statistics obtained via "display statistics" are quite comprehensive,
1095 * thus, we just explain a few lines here. Information is grouped by the plugin type. For the primal heuristics,
1096 * the execution time in seconds is shown as well as the number of calls to the heuristic, and its success regarding
1097 * the number of (best) solutions found by that heuristic. Appropriate statistics are also shown for presolvers, constraint handlers,
1098 * separators, propagators, the search tree, etc. User-written plugins will appear automatically in these statistics,
1099 * after they were included into \SCIP.
1100 *
1101 * @section TUTORIAL_PARAMETERS Changing parameters from the interactive shell
1102 *
1103 * Now, we can start playing around with parameters. The primal heuristics Rounding and shifting seem to be quite successful on this instance,
1104 * wondering what happens if we disable them? Or what happens, if we are even more rigorous and disable all heuristics?
1105 * Or if we do the opposite and use aggressive heuristics?
1106 *
1107 * @snippet shelltutorial/shelltutorialannotated.tmp SnippetSetSettings
1108 *
1109 * We can navigate through the menus step-by-step and get a list of available options and submenus. Therefore, we select
1110 * "set" to change settings, "heuristics" to change settings of primal heuristics, and "shifting" for that particular
1111 * heuristic. Then we see a list of parameters (and yet another submenu for advanced parameters), and disable this
1112 * heuristic by setting its calling frequency to -1. If we already know the path to a certain setting, we can directly
1113 * type it (as for the rounding heuristic in the above example). Note that we do not have to use the full names, but we
1114 * may use short versions, as long as they are unique.
1115 *
1116 * To solve a problem a second time, we have to read it in again before starting the optimization process.
1117 *
1118 * @snippet shelltutorial/shelltutorialannotated.tmp SnippetOpt2
1119 *
1120 * Okay, what happened here? First, we reset all parameters to their default values, using "set default". Next, we
1121 * loaded some meta-parameter settings (also see <a href="FAQ.php#howtochangebehaviour">the FAQ</a>), to apply primal heuristics
1122 * more aggressively. \SCIP shows us, which single parameters it changed therefore. Additionally, for pedagogical purposes,
1123 * we set the node limit to 200. Now, the optimal solution is already found at the root node, by a heuristic which is
1124 * deactivated by default. Then, after node 200, the user defined node limit is reached which interrupts the solving
1125 * process, We see that now in the short status report, primal and dual bound are different, thus, the problem is not solved
1126 * yet. Nevertheless, we could access statistics, see the current incumbent solution, change parameters and so on.
1127 * Entering "optimize" we continue the solving process from the point on at which it has been interrupted.
1128 *
1129 * Once you found a non-default parameter setting that you wish to save and use in the future, use either the command
1130 *
1131 * @snippet shelltutorial/shelltutorialannotated.tmp SnippetSaveSettingsFull
1132 *
1133 * to save <b>all</b> parameter values to the specified file, or
1134 *
1135 * @snippet shelltutorial/shelltutorialannotated.tmp SnippetSaveSettingsDiff
1136 *
1137 * in order to save only the nondefault parameters. The latter has several advantages, you can, e.g., combine parameter
1138 * settings from multiple settings files stored by the latter command, as long as they only affect mutually exclusive
1139 * parameter values.
1140 *
1141 * For loading a previously stored settings file, use the "load" command:
1142 *
1143 * @snippet shelltutorial/shelltutorialannotated.tmp SnippetLoadSettings
1144 *
1145 * Special attention should be drawn to the reserved settings file name "scip.set"; whenever the \SCIP interactive shell
1146 * is started from a working directory that contains a settings file with the name "scip.set", it will be automatically
1147 * replace the default settings.
1148 *
1149 * For using special settings for automated tests as described in \ref TEST, save your custom settings in a subdirectory
1150 * "SCIP_HOME/settings".
1151 *
1152 *
1153 * We hope this tutorial gave you an overview of what is possible using the \SCIP interactive shell. Please also read our
1154 * \ref FAQ, in particular the section "Using SCIP as a standalone MIP/MINLP-Solver".
1155 *
1156 */
1157
1158/*--+----1----+----2----+----3----+----4----+----5----+----6----+----7----+----8----+----9----+----0----+----1----+----2*/
1159
1160/**@page DOC How to search the documentation and source files structure for public interface methods
1161 *
1162 * If you are looking for a method in order to perform a specific task, the public \ref PUBLICAPI "SCIP C-API" is the place to look.
1163 * - It contains interface methods for all SCIP structs, both in the solver core or in one of the plugins.
1164 * - Plugins are mostly independent from each other, so to use them it is usually enough to browse the \ref PUBLICCOREAPI "Core API".
1165 * - If you want to add your own plugins, see the \ref HOWTOADD pages for exhaustive information for each plugin type.
1166 * - If you are learning SCIP with a concrete project in mind, looking at the available \ref EXAMPLES page may help you
1167 * getting started.
1168 * - See also \ref START "How to start a new project"
1169 *
1170 * Header file names of SCIP obey a consistent naming scheme: Type definitions and related objects such as enums are found in headers starting with "type_",
1171 * such as \ref type_var.h , which contains enums and type definitions related to \ref PublicVariableMethods "SCIP problem variables".
1172 * Definitions of the actual structs can be found in separate header files starting with "struct_".
1173 * All method definitions of the public SCIP API are split across header files starting with "pub_" such as \ref pub_cons.h
1174 * or headers starting with "scip_" such as \ref scip_cons.h .
1175 * The latter headers starting with "scip_" contain more complex methods, which always receive a scip pointer as first argument.
1176 * Those methods may affect several individual components controlled by SCIP. Such a method is SCIPbranchVar(), which
1177 * affects the search tree, which is controlled by SCIP itself and not meant to be accessed by user plugins.
1178 *
1179 * It should be sufficient to include scip/scip.h and scip/scipdefplugins.h for having all
1180 * needed functionality available in a project.
1181 *
1182 * If, for example, you are looking for information on how to create a problem instance, here are some steps you can take:
1183 *
1184 * 1. Browse the SCIP Core API and follow the path \ref PUBLICAPI > \ref PUBLICCOREAPI > \ref PublicProblemMethods > \ref GlobalProblemMethods > SCIPcreateProb()
1185 * 2. Here you can find information on the function's return value, preconditions, postconditions, parameters, as well as related functions.
1186 * 3. If you are unsure of how to use some of the parameters, it is worth looking for a basic version of the function.
1187 * This and other related functions may be found by either browsing neighboring functions and groups in the navigation tree to the left, or in the
1188 * 'References' and 'Referenced by' section of the function documentation. In this case, you can find `SCIPcreateProbBasic()`.
1189 *
1190 * The opposite case is that you already know the name of a function as, e.g., SCIPbranchVar().
1191 *
1192 * 1. Type the name of the function into the search bar to find the function documentation.
1193 * 2. In addition, you can find related methods by browsing the neighboring functions of the same group.
1194 * 3. In this example, you may now learn about SCIPgetNLPBranchCands() to query all integer
1195 * variables with fractional LP solution value, which are good candidates for classical branching on variables.
1196 *
1197 * Note that the \ref INTERNALAPI "private SCIP API" contains more complex functions and data structures that fill specialized roles and
1198 * is only for developers.
1199 * Those functions are **not** exported to the library and are therefore **not available in user projects** using the \ref PUBLICAPI "public SCIP API".
1200 */
1201
1202/*--+----1----+----2----+----3----+----4----+----5----+----6----+----7----+----8----+----9----+----0----+----1----+----2*/
1203
1204/**@page CONS How to add constraint handlers
1205 *
1206 * A constraint handler defines the semantics and the algorithms to process constraints of a certain class. A single
1207 * constraint handler is responsible for all constraints belonging to its constraint class. For example, there is
1208 * one \ref cons_knapsack.h "knapsack constraint handler" that ensures solutions are only accepted if they satisfy all
1209 * knapsack constraints in the model. \n A complete list of all constraint handlers contained in this release can be
1210 * found \ref CONSHDLRS "here".
1211 *
1212 * We now explain how users can add their own constraint handlers.
1213 * For an example, look into the subtour constraint handler (examples/TSP/src/ConshdlrSubtour.cpp) of the
1214 * \ref TSP_MAIN project.
1215 * The example is written in C++ and uses the C++ wrapper classes.
1216 * However, we will explain the implementation of a constraint handler using the C interface.
1217 * It is very easy to transfer the C explanation to C++; whenever a method should be implemented using the
1218 * SCIP_DECL_CONS... notion, reimplement the corresponding virtual member function of the abstract scip::ObjConshdlr
1219 * base class.
1220 *
1221 * Additional documentation for the callback methods of a constraint handler can be found in the file
1222 * type_cons.h.
1223 *
1224 * Here is what you have to do (assuming your constraint handler should be named "subtour"):
1225 * -# Copy the template files src/scip/cons_xyz.c and src/scip/cons_xyz.h into files "cons_subtour.c"
1226 * and "cons_subtour.h".
1227 * \n
1228 * Make sure to adjust your build system such that these files are compiled and linked to your project. \n
1229 * If you are adding a new default plugin, this means updating the `src/CMakeLists.txt` and `Makefile` files in the SCIP distribution.
1230 * -# Use `SCIPincludeConshdlrSubtour()` in order to include the constraint handler into your SCIP instance,
1231 * e.g., in the main file of your project (see, e.g., src/cppmain.cpp in the TSP example). \n
1232 * If you are adding a new default plugin, this include function must be added to `src/scipdefplugins.c`.
1233 * -# Open the new files with a text editor and replace all occurrences of "xyz" by "subtour".
1234 * -# Adjust the \ref CONS_PROPERTIES "properties of the constraint handler".
1235 * -# Define the \ref CONS_DATA "constraint data and the constraint handler data". This is optional.
1236 * -# Implement the \ref CONS_INTERFACE "interface methods".
1237 * -# Implement the \ref CONS_FUNDAMENTALCALLBACKS "fundamental callback methods".
1238 * -# Implement the \ref CONS_ADDITIONALCALLBACKS "additional callback methods". This is optional.
1239 *
1240 *
1241 * @section CONS_PROPERTIES Properties of a Constraint Handler
1242 *
1243 * At the top of the new file "cons_subtour.c" you can find the constraint handler properties.
1244 * These are given as compiler defines. Some of them are optional, as, e.g., separation-related properties,
1245 * which only have to be defined if the constraint handler supports the related callbacks.
1246 * In the C++ wrapper class, you have to provide the constraint handler properties by calling the constructor
1247 * of the abstract base class scip::ObjConshdlr from within your constructor (see the TSP example).
1248 * The properties you have to set have the following meaning:
1249 *
1250 * @subsection CONS_FUNDAMENTALPROPERTIES Fundamental Constraint Handler properties
1251 *
1252 * \par CONSHDLR_NAME: the name of the constraint handler.
1253 * This name is used in the interactive shell to address the constraint handler.
1254 * Additionally, if you are searching for a constraint handler with SCIPfindConshdlr(), this name is looked up.
1255 * Names have to be unique: no two constraint handlers may have the same name.
1256 *
1257 * \par CONSHDLR_DESC: the description of the constraint handler.
1258 * This string is printed as a description of the constraint handler in the interactive shell of SCIP.
1259 *
1260 * \par CONSHDLR_ENFOPRIORITY: the priority of the constraint handler for constraint enforcing.
1261 * Like the separation priority, the enforcement priorities define the order in which the different constraint handlers
1262 * are called in the constraint enforcement step of the subproblem processing.
1263 * The constraint enforcement is called after the price-and-cut loop is executed (in the case that the LP is solved
1264 * at the current subproblem).
1265 * \n
1266 * The integrality constraint handler has an enforcement priority of 0.
1267 * That means, if a constraint handler has negative enforcement priority, it only has to deal with integral solutions
1268 * in its enforcement methods, because for fractional solutions, the integrality constraint handler would have
1269 * created a branching, thereby aborting the enforcement step.
1270 * If you want to implement a constraint-depending branching rule (for example, SOS branching on special ordered
1271 * set constraints), you have to assign a positive enforcement priority to your constraint handler.
1272 * In this case, you have to be able to deal with fractional solutions.
1273 * \n
1274 * See \ref CONSENFOLP and \ref CONSENFOPS for further details of the separation callback.
1275 *
1276 * \par CONSHDLR_CHECKPRIORITY: the priority of the constraint handler for checking feasibility.
1277 * Like the separation priority, the checking priorities define the order in which the different constraint handlers
1278 * are called to check the feasibility of a given primal solution candidate.
1279 * The integrality constraint handler has a checking priority of 0.
1280 * That means, constraint handlers with negative checking priorities only have to deal with integral solutions.
1281 *
1282 * \par CONSHDLR_EAGERFREQ: the default frequency for using all instead of only the useful constraints in separation, propagation and enforcement.
1283 * If \em constraint \em aging is activated, some constraints that were not useful in the past for propagation or
1284 * separation are marked to be \em obsolete.
1285 * Usually, the obsolete constraints are not presented to the separation and propagation methods of the constraint
1286 * handlers, such that the constraint handlers only process the non-obsolete constraints.
1287 * However, every n'th call, with n being the EAGERFREQ of the constraint handler, all constraints are presented to the
1288 * separation and propagation methods of the constraint handler.
1289 * This gives obsolete constraints the chance of becoming non-obsolete again.
1290 * \n
1291 * If the eager evaluation frequency is set to -1, obsolete constraints are never presented to the separation and
1292 * propagation methods.
1293 * A frequency of 0 means, that obsolete constraints are only used in the first call of each method.
1294 *
1295 * \par CONSHDLR_NEEDSCONS: indicates whether the constraint handler should be skipped, if no constraints are available.
1296 * Usually, a constraint handler is only executed if there are constraints of its corresponding class in the model.
1297 * For those constraint handlers, the NEEDSCONS flag should be set to TRUE.
1298 * However, some constraint handlers must be called without having a constraint of the class in the model, because
1299 * the constraint is only implicitly available.
1300 * For example, the integrality constraint handler has the NEEDSCONS flag set to FALSE, because there is no explicit
1301 * integrality constraint in the model.
1302 * The integrality conditions are attached to the variables, and the integrality constraint handler has to check
1303 * all variables that are marked to be integer for integral values.
1304 *
1305 * @subsection CONS_ADDITIONALPROPERTIES Optional Constraint Handler properties
1306 *
1307 * The following properties are optional and only need to be defined if the constraint handlers support
1308 * separation, presolving, propagation, and/or upgrade functionality.
1309 *
1310 * \par LINCONSUPGD_PRIORITY: priority of the constraint handler for upgrading of linear constraints
1311 * This property is only needed if a certain linear constraint can be upgraded to a more specific one. In one of
1312 * the first presolving rounds SCIP tries to upgrade linear constraints to more specialized constraints, such as
1313 * knapsack constraints. The upgrading calls are processed in the order of decreasing priority.
1314 *
1315 * \par NONLINCONSUPGD_PRIORITY: priority of the constraint handler for upgrading of nonlinear constraints
1316 * This property has the same effect as the LINCONSUPGD_PRIORITY parameter, see above, and should be set whenever
1317 * an upgrade functionality from a general nonlinear constraint to the more specific one is defined.
1318 *
1319 * \par CONSHDLR_SEPAFREQ: the default frequency for separating cuts.
1320 * The separation frequency defines the depth levels at which the constraint handler's separation methods \ref CONSSEPALP
1321 * and \ref CONSSEPASOL are called.
1322 * For example, a separation frequency of 7 means, that the separation callback is executed for subproblems that are
1323 * in depth 0, 7, 14, ... of the branching tree.
1324 * A separation frequency of 0 means, that the separation method is only called at the root node.
1325 * A separation frequency of -1 disables the separation method of the constraint handler.
1326 * \n
1327 * The separation frequency can be adjusted by the user.
1328 * This property of the constraint handler only defines the default value of the frequency.
1329 * If you want to have a more flexible control of when to execute the separation algorithm, you have to assign
1330 * a separation frequency of 1 and implement a check at the beginning of your separation algorithm whether you really
1331 * want to execute the separator or not.
1332 * If you do not want to execute the method, set the result code to SCIP_DIDNOTRUN.
1333 *
1334 * \par CONSHDLR_SEPAPRIORITY: the priority of the constraint handler for separation. (optional: to be set only if the constraint handler supports separation)
1335 * In each separation round during the price-and-cut loop of the subproblem processing or during the separation loop
1336 * of the primal solution separation, the separators and separation methods of the constraint handlers are called in
1337 * a predefined order, which is given by the priorities of the separators and the separation priorities of the
1338 * constraint handlers.
1339 * First, the separators with non-negative priority are called in the order of decreasing priority.
1340 * Next, the separation methods of the different constraint handlers are called in the order of decreasing separation
1341 * priority.
1342 * Finally, the separators with negative priority are called in the order of decreasing priority.
1343 * \n
1344 * The separation priority of the constraint handler should be set according to the complexity of the cut separation
1345 * algorithm and the impact of the resulting cuts:
1346 * Constraint handlers that provide fast algorithms that usually have a high impact (i.e., cut off a large portion of
1347 * the LP relaxation) should have a high priority.
1348 * See \ref CONSSEPALP and \ref CONSSEPASOL for further details of the separation callbacks.
1349 *
1350 * \par CONSHDLR_DELAYSEPA: the default for whether the separation method should be delayed, if other separators found cuts.
1351 * If the constraint handler's separation method is marked to be delayed, it is only executed after no other separator
1352 * or constraint handler found a cut during the price-and-cut loop.
1353 * If the separation method of the constraint handler is very expensive, you may want to mark it to be delayed until all
1354 * cheap separation methods have been executed.
1355 *
1356 * \par CONSHDLR_PROPFREQ: the default frequency for propagating domains.
1357 * This default frequency has the same meaning as the CONSHDLR_SEPAFREQ with respect to the domain propagation
1358 * callback of the constraint handler.
1359 * A propagation frequency of 0 means that propagation is only applied in preprocessing and at the root node.
1360 * A propagation frequency of -1 disables the propagation method of the constraint handler.
1361 *
1362 * \par CONSHDLR_DELAYPROP: the default for whether the propagation method should be delayed, if other propagators found reductions.
1363 * This property is analogous to the DELAYSEPA flag, but deals with the propagation method of the constraint handler.
1364 *
1365 * \par CONSHDLR_PROP_TIMING: the propagation timing mask of the constraint handler.
1366 * SCIP calls the domain propagation routines at different places in the node processing loop.
1367 * This property indicates at which places the propagation routine of the constraint handler is called.
1368 * Possible values are defined in type_timing.h and can be concatenated, e.g., as in SCIP_PROPTIMING_ALWAYS.
1369 *
1370 * \par CONSHDLR_PRESOLTIMING: the timing of the constraint handler's presolving method (FAST, MEDIUM, or EXHAUSTIVE).
1371 * Every presolving round starts with the FAST presolving methods. MEDIUM presolvers are only called, if FAST presolvers did not find
1372 * enough reductions in this round so far, and EXHAUSTIVE presolving steps are only performed if all presolvers called before
1373 * in this round were unsuccessful.
1374 * Presolving methods should be assigned a timing based on how expensive they are, e.g., presolvers that provide fast algorithms that
1375 * usually have a high impact (i.e., remove lots of variables or tighten bounds of many variables) should have a timing FAST.
1376 * If a presolving method implements different algorithms of different complexity, it may also get multiple timings and check the timing
1377 * internally in the \ref CONSPRESOL callback to decide which algorithms to run.
1378 *
1379 * \par CONSHDLR_MAXPREROUNDS: the default maximal number of presolving rounds the constraint handler participates in.
1380 * The preprocessing is executed in rounds.
1381 * If enough changes have been applied to the model, an additional preprocessing round is performed.
1382 * The MAXPREROUNDS parameter of a constraint handler denotes the maximal number of preprocessing rounds the constraint
1383 * handler participates in.
1384 * A value of -1 means that there is no limit on the number of rounds.
1385 * A value of 0 means the preprocessing callback of the constraint handler is disabled.
1386 *
1387 *
1388 *
1389 * @section CONS_DATA Constraint Data and Constraint Handler Data
1390 *
1391 * Below the header "Data structures" you can find two structs called "struct SCIP_ConsData" and
1392 * "struct SCIP_ConshdlrData".
1393 * If you are using C++, you only need to define the "struct SCIP_ConsData".
1394 * The constraint handler data must be implemented as member variables of your constraint handler class.
1395 * \n
1396 * The constraint data are the information that is needed to define a single constraint of the constraint handler's
1397 * constraint class.
1398 * For example, the data of a knapsack constraint would consist of a list of variables, a list of weights, and
1399 * the capacity of the knapsack.
1400 * The data of a subtour constraint consists of the graph on which the problem is defined.
1401 * In the graph, each edge should be linked to the corresponding binary problem variable.
1402 * \n
1403 * The constraint handler data are additional variables, that belong to the constraint handler itself and which are
1404 * not specific to a single constraint.
1405 * For example, you can use these data to store parameters of the constraint handler or statistical information.
1406 * The constraint handler data are optional.
1407 * You can leave the struct empty.
1408 *
1409 *
1410 * @section CONS_INTERFACE Interface Methods
1411 *
1412 * At the bottom of "cons_subtour.c" you can find three interface methods, that also appear in "cons_subtour.h".
1413 * These are SCIPincludeConshdlrSubtour(), SCIPcreateConsSubtour(), and SCIPcreateConsSubtourBasic().
1414 * \n
1415 * The method SCIPincludeConshdlrSubtour() only has to be adjusted slightly.
1416 * It is responsible for notifying SCIP of the presence of the constraint handler by calling the method
1417 * SCIPincludeConshdlr().
1418 * It is called by the user, if (s)he wants to include the constraint handler, i.e., if (s)he wants to make
1419 * the constraint handler available to the model, and looks like this:
1420 * \dontinclude src/scip/cons_knapsack.c
1421 * -# If you are using constraint handler data, you have to <b>allocate the memory for the data</b> at this point.
1422 * You also have to initialize the fields in struct SCIP_ConshdlrData afterwards.
1423 *
1424 * \skip SCIP_RETCODE SCIPincludeConshdlrKnapsack(
1425 * \until SCIPallocBlockMemory
1426 *
1427 * -# Now, <b>SCIP gets notified</b> of the presence of the constraint handler together with its \ref CONS_FUNDAMENTALCALLBACKS "basic callbacks".
1428 *
1429 * \skip SCIPincludeConshdlrBasic
1430 * \until assert
1431 *
1432 * -# All \ref CONS_ADDITIONALCALLBACKS "additional callbacks" are added via their setter functions.
1433 *
1434 * \skip SCIPsetConshdlrCopy
1435 * \until SCIPsetConshdlrExit
1436 *
1437 * -# If the constraint handler is a specialization of a general linear or nonlinear constraint, we want to include an
1438 * <b>automatic upgrading mechanism</b> by calling the interface method
1439 *
1440 * \skip SCIPfindConshdlr
1441 * \until SCIPincludeLinconsUpgrade
1442 * or
1443 * \code
1444 * SCIP_CALL( SCIPincludeNonlinconsUpgrade(scip, nonlinconsUpgdSubtour, NULL, NONLINCONSUPGD_PRIORITY, TRUE, CONSHDLR_NAME) );
1445 * \endcode
1446 *
1447 * in the nonlinear case. See also cons_nonlinear.h for further information about the general upgrade procedure in the nonlinear case.
1448 * -# You may also add <b>user parameters</b> for your constraint handler.
1449 * Some parameters which are important to play with are added to every constraint automatically, as, e.g.,
1450 * propagation or separation frequency.
1451 * \skip SCIPaddIntParam
1452 * \until DEFAULT_SEPACARDFREQ
1453 * \skip SCIP_OKAY
1454 * \until }
1455 *
1456 *
1457 * The methods SCIPcreateConsSubtour() and SCIPcreateConsSubtourBasic() are called to create a single constraint of the constraint
1458 * handler's constraint class.
1459 * It should allocate and fill the constraint data, and call SCIPcreateCons().
1460 * Take a look at the following example from the \ref cons_knapsack.h "knapsack constraint handler":
1461 *
1462 * @refsnippet{src/scip/cons_knapsack.c,SnippetConsCreationKnapsack}
1463 *
1464 * In this example, consdataCreate() is a local method that allocates memory for the given consdata
1465 * and fills the data with the given <code>vars</code> array. For allocating memory for the constraint data, you
1466 * can use SCIP memory allocation:
1467 * \code
1468 * SCIP_CALL( SCIPallocBlockMemory(scip, consdata) );
1469 * \endcode
1470 *
1471 *
1472 * @section CONS_CALLBACKS Callback methods of Constraint handlers
1473 *
1474 * Besides the various functions which you will implement inside your constraint handler there exists a number
1475 * of <b> callback methods </b> associated with your constraint handler. Callback methods can be regarded as
1476 * tasks which your constraint handler is able to provide to the solver. They are grouped into two
1477 * categories:
1478 *
1479 * \ref CONS_FUNDAMENTALCALLBACKS "Fundamental Callback methods" are mandatory to implement
1480 * such that your code will work. For example, every constraint handler has to provide the
1481 * functionality to state whether all of its constraints are
1482 * fulfilled by a given variable assignment. Hence, the \ref CONSCHECK "CONSCHECK" callback is
1483 * one of the fundamental (or \a basic) callbacks of a constraint handler.
1484 *
1485 * Callbacks which are not necessarily implemented are grouped together as
1486 * \ref CONS_ADDITIONALCALLBACKS "additional callbacks". Such callbacks can be used to allocate and free memory
1487 * at different stages of the solving process. Although not mandatory, it might be useful to implement
1488 * some of these callbacks, e.g., to extend your constraint handler by a
1489 * \ref CONSSEPALP "separation" or \ref CONSPRESOL "presolving" functionality.
1490 *
1491 * All callbacks should be passed to SCIP during the SCIPinclude<PLUGINTYPE><PLUGINNAME> method
1492 * (e.g., SCIPincludeConshdlrKnapsack() for the \ref cons_knapsack.h "knapsack constraint handler").
1493 * Since SCIP version 3.0, two ways of setting callbacks can be used, either via SCIPincludeConshdlr()
1494 * (all at once, as it always was), or via SCIPincludeConshdlrBasic() and setter functions for additional callbacks.
1495 * Since the basic inclusion methods are very unlikely to change and will thus
1496 * make your code more stable towards future versions of SCIP with more callbacks,
1497 * we recommend the latter choice, as explained in the \ref CONS_INTERFACE "interface" section.
1498 *
1499 * @section CONS_FUNDAMENTALCALLBACKS Fundamental Callback Methods
1500 *
1501 * By implementing the fundamental callbacks, you define the semantics of the constraint class the constraint handler
1502 * deals with.
1503 * If these methods are implemented, the resulting code is already correct and finds the optimal solution to the
1504 * given problem instance.
1505 * However, it might be very slow because the additional features, like cut separation and domain propagation, are
1506 * missing.
1507 * In the C++ wrapper class scip::ObjConshdlr, the fundamental callback methods are virtual abstract member functions.
1508 * You have to implement them in order to be able to construct an object of your constraint handler class.
1509 *
1510 * There are three fundamental callback methods that are all dealing with the feasibility of a given solution.
1511 * They are called at different places in the algorithm and have slightly different meaning.
1512 * However, it is usually reasonable to implement a single local method that is called by all of the three callback
1513 * methods with slightly modified parameters.
1514 * The fourth method provides dual information that is used for example in preprocessing.
1515 *
1516 * Additional documentation for the callback methods can be found in type_cons.h.
1517 *
1518 * @subsection CONSCHECK
1519 *
1520 * The CONSCHECK callback gets a primal solution candidate in a SCIP_SOL* data structure
1521 * and has to check this solution for global feasibility.
1522 * It has to return a result SCIP_FEASIBLE, if the solution satisfies all the constraints of the constraint handler,
1523 * and a result SCIP_INFEASIBLE if there is at least one constraint that is violated.
1524 *
1525 * If the solution is not NULL, SCIP should also be informed about the constraint violation with a call to
1526 * SCIPupdateSolConsViolation() and additionally SCIPupdateSolLPRowViolation() for every row of the constraint's current
1527 * representation in the LP relaxation, if any such rows exist.
1528 * As a convenience method, SCIPupdateSolLPConsViolation() can be used if the constraint
1529 * is represented completely by a set of LP rows, meaning that the current constraint violation is equal to the maximum
1530 * of the contraint violations of the corresponding LP rows.
1531 *
1532 * The callback is used by primal heuristics to check a constructed solution for feasibility.
1533 * That means, the constraint handler has to deal with arbitrary solutions that do not necessarily satisfy the bounds
1534 * and constraints of the local subproblem.
1535 *
1536 * The value of a variable \em var in the given solution \em sol can be accessed by calling
1537 * \code
1538 * SCIPgetSolVal(scip, sol, var)
1539 * \endcode
1540 *
1541 * For example, the \ref cons_knapsack.h "knapsack constraint handler" loops over its constraints and
1542 * calculates the scalar product \f$w^T x\f$ of weights \f$w\f$ with the solution vector \f$x\f$.
1543 * This scalar product is compared with the capacity of the knapsack constraint.
1544 * If it exceeds the capacity, the CONSCHECK method is immediately aborted with the result SCIP_INFEASIBLE.
1545 * If all knapsack constraints are satisfied, a result SCIP_FEASIBLE is returned.
1546 *
1547 * @subsection CONSENFOLP
1548 *
1549 * The CONSENFOLP method is called after the price-and-cut loop was finished and an LP solution is available.
1550 * Like the CHECK call, the ENFOLP method should return a result SCIP_FEASIBLE, if the solution satisfies all the
1551 * constraints.
1552 * However, the behavior should be different, if the solution violates some of the associated constraints.
1553 * The constraint handler may return a result SCIP_INFEASIBLE in this situation, but this is not the best what
1554 * one can do.
1555 * The ENFOLP method has the possibility of \em resolving the infeasibility by
1556 * - stating that the current subproblem is infeasible (result SCIP_CUTOFF),
1557 * - adding an additional constraint that resolves the infeasibility (result SCIP_CONSADDED),
1558 * - reducing the domain of a variable (result SCIP_REDUCEDDOM),
1559 * - adding a cutting plane (result SCIP_SEPARATED),
1560 * - tightening the LP primal feasibility tolerance and requesting to solve the LP again (result SCIP_SOLVELP),
1561 * - performing a branching (result SCIP_BRANCHED).
1562 *
1563 * Note that in case SCIP_CONSADDED, the added constraints must be created with flag initial=TRUE.
1564 *
1565 * However, the solution is not given as a SCIP_SOL* data structure.
1566 *
1567 * The value of a variable <code>var</code> in the LP solution can be accessed by calling
1568 * \code
1569 * SCIPgetVarSol(scip, var)
1570 * \endcode
1571 * or by
1572 * \code
1573 * SCIPgetSolVal(scip, NULL, var)
1574 * \endcode
1575 * By using the latter method, you can have a single local method to check a solution for feasibility by passing
1576 * the given <code>sol</code> to the CONSCHECK call and by passing a NULL pointer as <code>sol</code> to
1577 * the CONSENFOLP and CONSENFOPS calls.
1578 *
1579 *
1580 * @subsection CONSENFOPS
1581 *
1582 * The CONSENFOPS callback is similar to the CONSENFOLP callback, but deals with \em pseudo \em solutions instead
1583 * of LP solutions.
1584 *
1585 * If the LP was not solved at the current subproblem (either because the user did not want to solve it, or because
1586 * numerical difficulties in the LP solving process were detected) no LP solution is available.
1587 * In this situation, the pseudo solution is used instead.
1588 * In this solution, the variables are set to the local bound which is best with respect to the objective function.
1589 * You can think of the pseudo solution as solution to the LP relaxation with all constraints except the bounds
1590 * being removed.
1591 *
1592 * Like the ENFOLP callback, the ENFOPS callback has to check whether the pseudo solution satisfies all the constraints
1593 * of the constraint handler.
1594 * The pseudo solution can be accessed by the same methods as the LP solution (SCIP knows, if the LP was solved at the
1595 * current subproblem, and returns either the LP solution or the pseudo solution).
1596 *
1597 * Unlike the ENFOLP callback, the ENFOPS callback must not add cuts and cannot return the result SCIP_SEPARATED.
1598 * It is, however, possible to force the solving of the LP by returning the result SCIP_SOLVELP.
1599 * For example, the infeasibility of a linear constraint that contains continuous variables cannot be resolved,
1600 * if all integer variables in the constraint are already fixed.
1601 * In this case, the LP has to be solved in order to get a solution that satisfies the linear constraint.
1602 *
1603 * @subsection CONSENFORELAX
1604 *
1605 * The CONSENFORELAX callback is similar to the CONSENFOLP and CONSENFOPS callbacks, but deals with relaxation solutions.
1606 *
1607 * If the best bound computed by a relaxator that includes the whole LP is strictly better than the bound of the LP itself,
1608 * the corresponding relaxation solution will get enforced. Therefore the CONSENFORELAX callback will only be called for
1609 * solutions that satisfy all active LP-constraints.
1610 *
1611 * Like the ENFOLP and ENFOPS callbacks, the ENFORELAX callback has to check whether the solution given in sol satisfies
1612 * all the constraints of the constraint handler. Since the callback is only called for relaxators including the whole LP,
1613 * cuts may be added with a result of SCIP_SEPARATED, like in the ENFOLP callback. It is also possible to return
1614 * SCIP_SOLVELP if the relaxation solution is invalid for some reason and the LP should be solved instead.
1615 *
1616 * Note that the CONSENFORELAX callback is only relevant if relaxators are used. Since the basic distribution of the
1617 * SCIP Optimization Suite does not contain any relaxators, this callback can be ignored unless any relaxators are added
1618 * via user-plugins.
1619 *
1620 * @subsection CONSLOCK
1621 *
1622 * The CONSLOCK callback provides dual information for a single constraint.
1623 * It has to tell SCIP, which variables are existing in the given constraint, and in which way modifications of these
1624 * variables may affect the feasibility of the constraint.
1625 *
1626 * For each variable that is affected by the constraint, the callback should call SCIPaddVarLocks():
1627 * - If the constraint may become violated by decreasing the value of a variable, it should call
1628 * SCIPaddVarLocks(scip, var, nlockspos, nlocksneg), saying that rounding down is potentially rendering the
1629 * (positive) constraint infeasible and rounding up is potentially rendering the negation of the constraint
1630 * infeasible.
1631 * - If the constraint may become violated by increasing the value of a variable, it should call
1632 * SCIPaddVarLocks(scip, var, nlocksneg, nlockspos), saying that rounding up is potentially rendering the
1633 * constraint's negation infeasible and rounding down is potentially rendering the constraint itself
1634 * infeasible.
1635 * - If the constraint may become violated by changing the variable in any direction, it should call
1636 * SCIPaddVarLocks(scip, var, nlockspos + nlocksneg, nlockspos + nlocksneg).
1637 *
1638 * <b>Note:</b> You do not have to worry about nlockspos and nlocksneg. These integer values are given as
1639 * parameter of the CONSLOCK callback (see type_cons.h). Just use these variables in the above described
1640 * fashion <b>without</b> adding or subtracting anything to them. In case of the knapsack constraints this
1641 * method looks like this.
1642 *
1643 * @refsnippet{src/scip/cons_knapsack.c,SnippetConsLockKnapsack}
1644 *
1645 * To give same more intuition, consider the linear constraint \f$3x -5y +2z \leq 7\f$ as an example.
1646 * The CONSLOCK callback method of the linear constraint handler should call
1647 * SCIPaddVarLocks(scip, x, nlocksneg, nlockspos), SCIPaddVarLocks(scip, y, nlockspos, nlocksneg),
1648 * and SCIPaddVarLocks(scip, z, nlocksneg, nlockspos) to tell SCIP, that rounding up of \f$x\f$
1649 * and \f$z\f$ and rounding down of \f$y\f$ can destroy the feasibility of the constraint, while rounding
1650 * down of \f$x\f$ and \f$z\f$ and rounding up of \f$y\f$ can destroy the feasibility of the
1651 * constraint's negation \f$3x -5y +2z > 7\f$.
1652 * \n
1653 * A linear constraint \f$2 \leq 3x -5y +2z \leq 7\f$ should call
1654 * SCIPaddVarLocks(scip, ..., nlockspos + nlocksneg, nlockspos + nlocksneg) on all variables,
1655 * since rounding in both directions of each variable can destroy both the feasibility of the
1656 * constraint and it's negation \f$3x -5y +2z < 2\f$ or \f$3x -5y +2z > 7\f$.
1657 *
1658 *
1659 * @section CONS_ADDITIONALCALLBACKS Additional Callback Methods
1660 *
1661 * The additional callback methods do not need to be implemented in every case, but provide useful functionality
1662 * for many applications. They can be added to your constraint handler via setter functions, see
1663 * \ref CONS_INTERFACE "here".
1664 *
1665 * @subsection CONSFREE
1666 *
1667 * If you are using constraint handler data, you have to implement this method in order to free the
1668 * constraint handler data. This can be done by the following procedure (which is taken from the
1669 * \ref cons_knapsack.h "knapsack constraint handler"):
1670 *
1671 * @refsnippet{src/scip/cons_knapsack.c,SnippetConsFreeKnapsack}
1672 *
1673 * If you have allocated memory for fields in your constraint handler data, remember to free this memory
1674 * before freeing the constraint handler data itself.
1675 * If you are using the C++ wrapper class, this method is not available.
1676 * Instead, just use the destructor of your class to free the member variables of your class.
1677 *
1678 * @subsection CONSHDLRCOPY
1679 *
1680 * The CONSHDLRCOPY callback is executed when the SCIP instance is copied, e.g. to solve a sub-SCIP. By defining this
1681 * callback as <code>NULL</code> the user disables the inclusion of the specified constraint handler into all copied SCIP
1682 * instances. This may deteriorate the performance of primal heuristics solving sub-SCIPs, since these constitute only
1683 * relaxations of the original problem if constraint handlers are missing.
1684 *
1685 * A usual implementation just
1686 * calls the interface method which includes the constraint handler to the model. For example, this callback is
1687 * implemented for the \ref cons_knapsack.c "knapsack constraint handler" as follows:
1688 *
1689 * @refsnippet{src/scip/cons_knapsack.c,SnippetConsCopyKnapsack}
1690 *
1691 * <b>Note:</b> If you implement this callback, take care when setting the valid pointer.
1692 *
1693 * A problem copy is called valid if it is valid in both the primal and the dual sense, i.e., if
1694 *
1695 * - it is a relaxation of the source problem
1696 * - it does not enlarge the feasible region.
1697 *
1698 * A constraint handler may choose to not copy a constraint and still declare the resulting copy as valid. It must ensure
1699 * the feasibility of any solution to the problem copy in the original (source) space.
1700 *
1701 * <b>Note:</b> If you implement this callback and the constraint handler needs constraints (see CONSHDLR_NEEDSCONS),
1702 * then you also need to implement the callback \ref CONSCOPY.
1703 *
1704 * @subsection CONSINIT
1705 *
1706 * The CONSINIT callback is executed after the problem is transformed.
1707 * The constraint handler may, e.g., use this call to replace the original variables in its constraints by transformed
1708 * variables, or to initialize its statistical constraint handler data.
1709 *
1710 * @subsection CONSEXIT
1711 *
1712 * The CONSEXIT callback is executed before the transformed problem is freed.
1713 * In this method, the constraint handler should free all resources that were allocated for the solving process.
1714 *
1715 * @subsection CONSINITPRE
1716 *
1717 * The CONSINITPRE callback is executed before the preprocessing is started, even if presolving is turned off.
1718 * The constraint handler may use this call to initialize its presolving data, or to modify its constraints
1719 * before the presolving process begins.
1720 * Necessary constraint modifications that have to be performed even if presolving is turned off should be done here
1721 * or in the presolving deinitialization call.
1722 *
1723 * @subsection CONSEXITPRE
1724 *
1725 * The CONSEXITPRE callback is executed after the preprocessing has been finished, even if presolving is turned off.
1726 * The constraint handler may use this call e.g. to clean up its presolving data, or to finally modify its constraints
1727 * before the branch-and-bound process begins.
1728 * Necessary constraint modifications that have to be performed even if presolving is turned off should be done here
1729 * or in the presolving initialization call.
1730 * Besides necessary modifications and clean up, no time consuming operations should be done.
1731 *
1732 * @subsection CONSINITSOL
1733 *
1734 * The CONSINITSOL callback is executed when the presolving is finished and the branch-and-bound process is about to
1735 * begin.
1736 * The constraint handler may use this call to initialize its branch-and-bound specific data.
1737 *
1738 * @subsection CONSEXITSOL
1739 *
1740 * The CONSEXITSOL callback is executed before the branch-and-bound process is freed.
1741 * The constraint handler should use this call to clean up its branch-and-bound data, in particular to release
1742 * all LP rows that it has created or captured.
1743 *
1744 * @subsection CONSDELETE
1745 *
1746 * The CONSDELETE callback is executed if a constraint should be freed.
1747 * You can think of it as the destructor of a single constraint.
1748 * In the callback, you have to free the given constraint data.
1749 * The CONSDELETE callback is therefore the counterpart of the SCIPcreateCons...() interface method and the CONSTRANS
1750 * method.
1751 *
1752 * @subsection CONSTRANS
1753 *
1754 * The CONSTRANS method is called for each constraint of the constraint handler, when the user starts the solving
1755 * process.
1756 * It has to copy the original constraint data of the constraint to the memory for the transformed problem.
1757 * You can think of it as a copy constructor for a single constraint.
1758 *
1759 * The original model is copied in order to protect it from transformations that are applied during the solving process,
1760 * in particular during preprocessing.
1761 * Preprocessing and solving always operates on the transformed problem.
1762 * If the solving process data are freed, the original data still exist and the user can, e.g., modify the problem and
1763 * restart the solving process.
1764 *
1765 * If you do not implement the CONSTRANS method, a transformed constraint is created with the same flags and the
1766 * same constraint data pointer.
1767 * That means, the transformed constraint points to the original constraint data.
1768 * This is okay, as long as the constraint data is not changed during the solving process.
1769 * If you want to implement preprocessing methods or other methods that modify the constraint data, you have to
1770 * implement the CONSTRANS method and create a copy of the constraint data.
1771 *
1772 * Here is an example, which is taken from the \ref cons_knapsack.h "knapsack constraint handler":
1773 *
1774 * @refsnippet{src/scip/cons_knapsack.c,SnippetConsTransKnapsack}
1775 *
1776 * @subsection CONSINITLP
1777 *
1778 * The CONSINITLP callback is executed before the first LP relaxation is solved.
1779 * It should add the LP relaxations of all "initial" constraints to the LP. The method should scan the constraints
1780 * array for constraints that are marked initial via calls to SCIPconsIsInitial() and put the LP relaxation
1781 * of all initial constraints to the LP with calls to SCIPaddCut().
1782 *
1783 * @subsection CONSSEPALP
1784 *
1785 * The CONSSEPALP callback is executed during the price-and-cut loop of the subproblem processing.
1786 * It should try to generate cutting planes for the constraints of the constraint handler in order to separate
1787 * the current LP solution.
1788 * The method is called in the LP solution loop, which means that a valid LP solution exists.
1789 *
1790 * Usually, a separation callback searches and produces cuts, that are added with a call to SCIPaddCut().
1791 * If the cut should be remembered in the global cut pool, it may also call SCIPaddPoolCut().
1792 * If the cut is constructed via multiple calls to SCIPaddVarToRow(), then performance can be improved by calling
1793 * SCIPcacheRowExtensions() before these additions and SCIPflushRowExtensions() after.
1794 * However, the callback may also produce domain reductions or add other constraints.
1795 *
1796 * The CONSSEPALP callback has the following options:
1797 * - detecting that the node is infeasible in the variables' bounds and can be cut off (result SCIP_CUTOFF)
1798 * - adding an additional constraint (result SCIP_CONSADDED)
1799 * - reducing a variable's domain (result SCIP_REDUCEDDOM)
1800 * - adding a cutting plane to the LP (result SCIP_SEPARATED)
1801 * - stating that the separator searched, but did not find domain reductions, cutting planes, or cut constraints
1802 * (result SCIP_DIDNOTFIND)
1803 * - stating that the separator was skipped (result SCIP_DIDNOTRUN)
1804 * - stating that the separator was skipped, but should be called again (result SCIP_DELAYED)
1805 * - stating that a new separation round should be started without calling the remaining separator methods (result SCIP_NEWROUND)
1806 *
1807 * Please see also the @ref CONS_ADDITIONALPROPERTIES section to learn about the properties
1808 * CONSHDLR_SEPAFREQ, CONSHDLR_SEPAPRIORITY, and CONSHDLR_DELAYSEPA, which influence the behaviour of SCIP
1809 * calling CONSSEPALP.
1810 *
1811 * @subsection CONSSEPASOL
1812 *
1813 * The CONSSEPASOL callback is executed during separation loop on arbitrary primal solutions.
1814 * It should try to generate cutting planes for the constraints of the constraint handler in order to separate
1815 * the given primal solution.
1816 * The method is not called in the LP solution loop, which means that there is no valid LP solution.
1817 *
1818 * Usually, a separation callback searches and produces cuts, that are added with a call to SCIPaddCut().
1819 * If the cut should be remembered in the global cut pool, it may also call SCIPaddPoolCut().
1820 * If the cut is constructed via multiple calls to SCIPaddVarToRow(), then performance can be improved by calling
1821 * SCIPcacheRowExtensions() before these additions and SCIPflushRowExtensions() after.
1822 * However, the callback may also produce domain reductions or add other constraints.
1823 *
1824 * The CONSSEPASOL callback has the following options:
1825 * - detecting that the node is infeasible in the variables' bounds and can be cut off (result SCIP_CUTOFF)
1826 * - adding an additional constraint (result SCIP_CONSADDED)
1827 * - reducing a variable's domain (result SCIP_REDUCEDDOM)
1828 * - adding a cutting plane to the LP (result SCIP_SEPARATED)
1829 * - stating that the separator searched, but did not find domain reductions, cutting planes, or cut constraints
1830 * (result SCIP_DIDNOTFIND)
1831 * - stating that the separator was skipped (result SCIP_DIDNOTRUN)
1832 * - stating that the separator was skipped, but should be called again (result SCIP_DELAYED)
1833 * - stating that a new separation round should be started without calling the remaining separator methods (result SCIP_NEWROUND)
1834 *
1835 * Please see also the @ref CONS_ADDITIONALPROPERTIES section to learn about the properties
1836 * CONSHDLR_SEPAFREQ, CONSHDLR_SEPAPRIORITY, and CONSHDLR_DELAYSEPA, which influence the behaviour of SCIP
1837 * calling CONSSEPASOL.
1838 *
1839 * @subsection CONSPROP
1840 *
1841 * The CONSPROP callback is called during the subproblem processing.
1842 * It should propagate the constraints, which means that it should infer reductions in the variables' local bounds
1843 * from the current local bounds.
1844 * This technique, which is the main workhorse of constraint programming, is called "node preprocessing" in the
1845 * Integer Programming community.
1846 *
1847 * The CONSPROP callback has the following options:
1848 * - detecting that the node is infeasible in the variables' bounds and can be cut off (result SCIP_CUTOFF)
1849 * - reducing a variable's domain (result SCIP_REDUCEDDOM)
1850 * - stating that the propagator searched, but did not find domain reductions, cutting planes, or cut constraints
1851 * (result SCIP_DIDNOTFIND)
1852 * - stating that the propagator was skipped (result SCIP_DIDNOTRUN)
1853 * - stating that the propagator was skipped, but should be called again (result SCIP_DELAYED)
1854 *
1855 * Please see also the @ref CONS_ADDITIONALPROPERTIES section to learn about the properties
1856 * CONSHDLR_PROPFREQ, CONSHDLR_DELAYPROP, and CONSHDLR_PROP_TIMING, which influence the behaviour of SCIP
1857 * calling CONSPROP.
1858 *
1859 * @subsection CONSRESPROP
1860 *
1861 * If the constraint handler should support \ref CONF "conflict analysis", it has to supply a CONSRESPROP method.
1862 * It also should call SCIPinferVarLbCons() or SCIPinferVarUbCons() in domain propagation instead of SCIPchgVarLb() or
1863 * SCIPchgVarUb() in order to deduce bound changes on variables.
1864 * In the SCIPinferVarLbCons() and SCIPinferVarUbCons() calls, the handler provides the constraint that deduced the
1865 * variable's bound change, and an integer value <code>inferinfo</code> that can be arbitrarily chosen.
1866 *
1867 * The propagation conflict resolving method CONSRESPROP must then be implemented to provide the "reasons" for the bound
1868 * changes, i.e., the bounds of variables at the time of the propagation, which forced the constraint to set the
1869 * conflict variable's bound to its current value. It can use the <code>inferinfo</code> tag to identify its own propagation rule
1870 * and thus identify the "reason" bounds. The bounds that form the reason of the assignment must then be provided by
1871 * calls to SCIPaddConflictLb() and SCIPaddConflictUb() in the propagation conflict resolving method.
1872 *
1873 * <b>Note:</b> The fact that <code>inferinfo</code> is an integer, as opposed to an arbitrary data object, is a compromise between space and speed. Sometimes a propagator would
1874 * need more information to efficiently infer the original propagation steps that lead to the conflict. This would,
1875 * however, require too much space. In the extreme, the original propagation steps have to be repeated.
1876 *
1877 * For example, the \ref cons_logicor.h "logicor constraint" \f$c = x \vee y \vee z\f$ fixes variable \f$z\f$ to TRUE (i.e., changes the lower
1878 * bound of \f$z\f$ to 1.0), if both, \f$x\f$ and \f$y\f$, are assigned to FALSE (i.e., if the upper bounds of these
1879 * variables are 0.0). It uses <code>SCIPinferVarLbCons(scip, z, 1.0, c, 0)</code> to apply this assignment (an
1880 * inference information tag is not needed by the constraint handler and is set to 0). In the conflict analysis, the
1881 * constraint handler may be asked to resolve the lower bound change on \f$z\f$ with constraint \f$c\f$, that was
1882 * applied at a time given by a bound change index "bdchgidx". With a call to <code>SCIPvarGetLbAtIndex(z,
1883 * bdchgidx)</code>, the handler can find out, that the lower bound of variable \f$z\f$ was set to 1.0 at the given
1884 * point of time, and should call <code>SCIPaddConflictUb(scip, x, bdchgidx)</code> and <code>SCIPaddConflictUb(scip, y,
1885 * bdchgidx)</code> to tell SCIP, that the upper bounds of \f$x\f$ and \f$y\f$ at this point of time were the reason for
1886 * the deduction of the lower bound of \f$z\f$.
1887 *
1888 * If conflict analysis should not be supported, the method has to set the result code to SCIP_DIDNOTFIND. Although
1889 * this is a viable approach to circumvent the implementation of the usually rather complex conflict resolving method, it
1890 * will make the conflict analysis less effective. We suggest to first omit the conflict resolving method and check how
1891 * effective the \ref CONSPROP "propagation method" is. If it produces a lot of propagations for your application, you definitely should
1892 * consider implementing the conflict resolving method.
1893 *
1894 * @subsection CONSPRESOL
1895 *
1896 * The CONSPRESOL callback is called during preprocessing.
1897 * It should try to tighten the domains of the variables, tighten the coefficients of the constraints of the constraint
1898 * handler, delete redundant constraints, aggregate and fix variables if possible, and upgrade constraints to more
1899 * specific types.
1900 *
1901 * If the CONSPRESOL callback applies changes to the constraint data, you also have to implement the \ref CONSTRANS callback
1902 * in order to copy the constraint data to the transformed problem space and protect the original problem from the
1903 * preprocessing changes.
1904 *
1905 * To inform SCIP that the presolving method found a reduction the result pointer has to be set in a proper way.
1906 * The following options are possible:
1907 *
1908 * - SCIP_UNBOUNDED : at least one variable is not bounded by any constraint in objective direction
1909 * - SCIP_CUTOFF : at least one constraint is infeasible in the variable's bounds
1910 * - SCIP_SUCCESS : the presolver found a reduction
1911 * - SCIP_DIDNOTFIND : the presolver searched, but did not find a presolving change
1912 * - SCIP_DIDNOTRUN : the presolver was skipped
1913 * - SCIP_DELAYED : the presolver was skipped, but should be called again
1914 *
1915 * Please see also the @ref CONS_ADDITIONALPROPERTIES section to learn about the properties
1916 * CONSHDLR_PRESOLTIMING and CONSHDLR_MAXPREROUNDS, which influence the behaviour of SCIP
1917 * calling CONSPRESOL.
1918 *
1919 * @subsection CONSACTIVE
1920 *
1921 * The CONSACTIVE callback method is called each time a constraint of the constraint handler is activated.
1922 * For example, if a constraint is added locally to a subproblem, the CONSACTIVE callback is called whenever the
1923 * search enters the subtree where the constraint exists.
1924 *
1925 * @subsection CONSDEACTIVE
1926 *
1927 * The CONSDEACTIVE callback method is called each time a constraint of the constraint handler is deactivated.
1928 * For example, if a constraint is added locally to a subproblem, the CONSDEACTIVE callback is called whenever the
1929 * search leaves the subtree where the constraint exists.
1930 *
1931 * @subsection CONSENABLE
1932 *
1933 * The CONSENABLE callback method is called each time a constraint of the constraint handler is enabled.
1934 * Constraints might be active without being enabled. In this case, only the feasibility checks are executed,
1935 * but domain propagation and separation is skipped.
1936 *
1937 * @subsection CONSDISABLE
1938 *
1939 * The CONSDISABLE callback method is called each time a constraint of the constraint handler is disabled.
1940 *
1941 * @subsection CONSPRINT
1942 *
1943 * The CONSPRINT callback method is called, when the user asks SCIP to display the problem to the screen
1944 * or save the problem into a file. This is, however, only the case if the user requested the CIP format.
1945 * For more details about reading and writing with SCIP we refer to the \ref READER "file readers". In this
1946 * callback method the constraint handler should display the data of the constraint in an appropriate form.
1947 * The output format that is defined by the CONSPRINT callbacks is called CIP format.
1948 * In later versions of SCIP, the constraint handlers should also be able to parse (i.e., read) constraints
1949 * which are given in CIP format.
1950 *
1951 * @subsection CONSCOPY
1952 *
1953 * The CONSCOPY callback method is used whenever constraints should be copied from one SCIP instance into another SCIP
1954 * instance. This method comes with the necessary parameters to do so, most importantly with a mapping of the variables of the
1955 * source SCIP instance to the corresponding variables of the target SCIP instance, and a mapping for the constraints
1956 * in the same way. For a complete list of all arguments of this callback method see type_cons.h.
1957 *
1958 * To get the corresponding target variable of a given source variable, you can use the variable map directly:
1959 *
1960 * \code
1961 * targetvar = (SCIP_VAR*) SCIPhashmapGetImage(varmap, sourcevar);
1962 * \endcode
1963 *
1964 * We recommend, however, to use the method SCIPgetVarCopy() which gets besides others the variable map and the constraint map as input
1965 * and returns the requested target variable. The advantage of using SCIPgetVarCopy() is that in the case
1966 * the required variable does not yet exist, it is created and added to the copy automatically:
1967 *
1968 * \code
1969 * SCIP_CALL( SCIPgetVarCopy(sourcescip, scip, sourcevar, &targetvar, varmap, consmap, global) );
1970 * \endcode
1971 *
1972 * Finally, the result pointer <code>valid</code> has to be set to TRUE if (and only if!) the copy process was successful.
1973 *
1974 * <b>Note:</b> Be careful when setting the valid pointer.
1975 * A problem copy is called valid if it is valid in both the primal and the dual sense, i.e., if
1976 *
1977 * - it is a relaxation of the source problem
1978 * - it does not enlarge the feasible region.
1979 *
1980 * A constraint handler may choose to not copy a constraint and still declare the resulting copy as valid. Therefore, it must ensure
1981 * the feasibility of any solution to the problem copy in the original (source) space.
1982 *
1983 * For an example implementation we refer to cons_linear.h. Additional documentation and the complete list of all
1984 * parameters can be found in the file in type_cons.h.
1985 *
1986 * @subsection CONSPARSE
1987 *
1988 * This method is the counter part to CONSPRINT. The ideal idea is that a constraint handler is able to parse the output
1989 * which it generated via the CONSPRINT method and creates the corresponding constraint. If the parsing was successfully
1990 * the result pointer success should be set to TRUE. An example implementation can be found in the \ref cons_linear.h
1991 * "linear constraint handler".
1992 *
1993 * @subsection CONSDELVARS
1994 *
1995 * This method should iterate over the given constraints and delete all variables that were marked for deletion by SCIPdelVar().
1996 * Variable deletion is especially interesting for branch-cut-and-price applications. If your constraint handler allows
1997 * the addition of variables during the solving process (see "modifiable" attribute of constraints), then you might also want to
1998 * implement this callback. This would allow you to not only create variables during solving, but also remove them dynamically
1999 * from the problem to reduce memory consumption in case they are no longer necessary.
2000 * During presolving, SCIP may also find that some variables are not needed anymore and then try
2001 * to delete them. Thus, if you do not implement this callback, the constraint handler should capture its variables via
2002 * SCIPcaptureVar() to prevent SCIP from erroneously deleting them.
2003 *
2004 * Additional documentation and the complete list of all parameters can be found in the file type_cons.h.
2005 *
2006 * @subsection CONSGETVARS
2007 *
2008 * The CONSGETVARS callback of a constraint handler can be implemented to give access to the constraint variables
2009 * as array, independently from the internal data structure of the constraint. The buffer array
2010 * is already passed, together with its length. Consider implementing @ref CONSGETNVARS, too, to have
2011 * information about the number of variables in this constraint.
2012 *
2013 * @subsection CONSGETNVARS
2014 *
2015 * This callback can be implemented to return the number of variables involved into a particular constraint.
2016 * In order to have access to the variable pointers, consider implementing @ref CONSGETVARS.
2017 *
2018 * @refsnippet{src/scip/cons_linear.c,Callback for the number of variables}
2019 *
2020 * @subsection CONSGETDIVEBDCHGS
2021 *
2022 * This callback is used inside the various diving heuristics of SCIP and does not affect the normal branching
2023 * of the actual search.
2024 * The constraint handler can provide this callback to render a current working solution (even more) infeasible by
2025 * suggesting one or several variable bound changes.
2026 *
2027 * @section CONS_FURTHERINFO Further documentation
2028 *
2029 * Further documentation can be found in @ref type_cons.h for callback descriptions and a complete
2030 * list of all callback parameters, or in @ref scip.h
2031 * for globally available functions.
2032 */
2033
2034/*--+----1----+----2----+----3----+----4----+----5----+----6----+----7----+----8----+----9----+----0----+----1----+----2*/
2035
2036/**@page PRICER How to add variable pricers
2037 *
2038 * A pricer performs the dynamic generation of new variables in a column generation algorithm.
2039 * It is an algorithmic representation of a (usually exponential) number of variables.
2040 * The \ref PRICERREDCOST and \ref PRICERFARKAS methods are called after each LP solve to generate additional
2041 * variables which may improve the objective value or decrease the LP infeasibility, respectively.
2042 * \n
2043 * A complete list of all pricers contained in this release can be found \ref PRICERS "here".
2044 *
2045 * If the pricer finds one or more variables with negative reduced costs or negative Farkas value, it should
2046 * call SCIPcreateVar() and SCIPaddPricedVar() to create and add the variable to the problem. Additionally,
2047 * the pricer has to add the variable to all constraints in which it appears. Therefore, a pricer needs to
2048 * know the constraints of the model and their meaning. Note that all constraints for which additional variables
2049 * are generated by a pricer have to be flagged as "modifiable" in the SCIPcreateCons() call.
2050 *
2051 * We now explain how users can add their own pricers.
2052 * For example, look into the variable pricer for the binpacking problem (examples/Binpacking/src/pricer_binpacking.c) of the
2053 * Binpacking example project.
2054 * The example is written in C. C++ users can easily adapt the code by using the scip::scip::ObjPricer wrapper base class and
2055 * implement the scip_...() virtual methods instead of the SCIP_DECL_PRICER... callback methods.
2056 *
2057 * Additional documentation for the callback methods of a pricer can be found in the file
2058 * type_pricer.h.
2059 *
2060 * Notice that if your pricer cannot cope with variable bounds other than 0 and infinity, you have to mark
2061 * all constraints containing priced variables as modifiable, and you may have to disable reduced cost
2062 * strengthening by setting propagating/rootredcost/freq to -1.
2063 *
2064 * Here is what you have to do to implement a pricer:
2065 * -# Copy the template files src/scip/pricer_xyz.c and src/scip/pricer_xyz.h into files "pricer_mypricer.c"
2066 * and "pricer_mypricer.h".
2067 * \n
2068 * Make sure to adjust your build system such that these files are compiled and linked to your project. \n
2069 * If you are adding a new default plugin, this means updating the `src/CMakeLists.txt` and `Makefile` files in the SCIP distribution.
2070 * -# Use `SCIPincludePricerMypricer()` in order to include the pricer into your SCIP instance,
2071 * e.g., in the main file of your project (see, e.g., src/cmain.c in the Binpacking example). \n
2072 * If you are adding a new default plugin, this include function must be added to `src/scipdefplugins.c`.
2073 * -# Open the new files with a text editor and replace all occurrences of "xyz" by "mypricer".
2074 * -# Adjust the properties of the pricer (see \ref PRICER_PROPERTIES).
2075 * -# Define the pricer data (see \ref PRICER_DATA). This is optional.
2076 * -# Implement the interface methods (see \ref PRICER_INTERFACE).
2077 * -# Implement the fundamental callback methods (see \ref PRICER_FUNDAMENTALCALLBACKS).
2078 * -# Implement the additional callback methods (see \ref PRICER_ADDITIONALCALLBACKS). This is optional.
2079 *
2080 *
2081 * @section PRICER_PROPERTIES Properties of a Pricer
2082 *
2083 * At the top of the new file "pricer_mypricer.c" you can find the pricer properties.
2084 * These are given as compiler defines.
2085 * In the C++ wrapper class, you have to provide the pricer properties by calling the constructor
2086 * of the abstract base class scip::ObjPricer from within your constructor.
2087 * The properties you have to set have the following meaning:
2088 *
2089 * \par PRICER_NAME: the name of the pricer.
2090 * This name is used in the interactive shell to address the pricer.
2091 * Additionally, if you are searching for a pricer with SCIPfindPricer(), this name is looked up.
2092 * Names have to be unique: no two pricers may have the same name.
2093 *
2094 * \par PRICER_DESC: the description of the pricer.
2095 * This string is printed as a description of the pricer in the interactive shell.
2096 *
2097 * \par PRICER_PRIORITY: the priority of the pricer.
2098 * In each pricing round during the price-and-cut loop of the subproblem processing, the included pricers are
2099 * called in a predefined order, which is given by the priorities of the pricers.
2100 * The higher the priority, the earlier the pricer is called.
2101 * Usually, you will have only one pricer in your application and the priority is therefore irrelevant.
2102 *
2103 * \par PRICER_DELAY: the default for whether the pricer should be delayed, if other variables with negative reduced
2104 * costs have already been found in the current pricing round.
2105 * Variables may be declared to be "removable" in the SCIPcreateVar() call. This means that SCIP may remove the variable
2106 * from the LP if it was inactive (i.e., sitting at zero) for a number of LP solves. Nevertheless, after the removal of the
2107 * column from the LP, the variable still exists, and SCIP can calculate reduced costs and add it to the LP again if
2108 * necessary.
2109 * \n
2110 * If the PRICER_DELAY flag is set to TRUE (which is the common setting), all those existing variables with negative reduced costs
2111 * are added to the LP, and the LP is resolved before the pricer is called. Thus, the pricer can assume that all existing variables
2112 * have non-negative reduced costs if the \ref PRICERREDCOST method is called or non-positive Farkas value if the \ref PRICERFARKAS
2113 * method is called.
2114 * \n
2115 * In some applications, this inner pricing loop on the already existing variables can significantly slow down the solving process,
2116 * since it may lead to the addition of only very few variables in each pricing round. If this is an issue in your application,
2117 * you should consider setting the PRICER_DELAY flag to FALSE. You must, however, be aware of the fact that there may be already
2118 * existing variables with negative reduced costs. For example, this may lead to the issue that your pricer generates the same
2119 * variable twice. In some models, this is not critical because an optimal solution would choose only one of the two identical
2120 * variables anyway, but for other models this can lead to wrong results because the duplication of a variable essentially doubles
2121 * the upper bound of the variable.
2122 *
2123 *
2124 * @section PRICER_DATA Pricer Data
2125 *
2126 * Below the header "Data structures" you can find a struct which is called "struct SCIP_PricerData".
2127 * In this data structure, you can store the data of your pricer. For example, it may be convenient to store pointers to the
2128 * constraints of the problem instance here, because the pricer has to add variables to those constraints.
2129 * If you are using C++, you can add pricer data, as usual, as object variables to your class.
2130 * \n
2131 * Defining pricer data is optional. You can leave the struct empty.
2132 *
2133 *
2134 * @section PRICER_INTERFACE Interface Methods
2135 *
2136 * At the bottom of "pricer_mypricer.c" you can find the interface method SCIPincludePricerMypricer(), which also appears in "pricer_mypricer.h".
2137 * It is called by the user, if (s)he wants to include the pricer, i.e., if (s)he wants to solve a model for which variables should
2138 * be generated by this pricer.
2139 *
2140 * This method only has to be adjusted slightly.
2141 * It is responsible for notifying SCIP of the presence of the pricer. For this, you can either call SCIPincludePricer(),
2142 * or SCIPincludePricerBasic() since SCIP version 3.0. In the latter variant, \ref PRICER_ADDITIONALCALLBACKS "additional callbacks"
2143 * must be added via setter functions as, e.g., SCIPsetPricerCopy(). We recommend this latter variant because
2144 * it is more stable towards future SCIP versions which might have more callbacks, whereas source code using the first
2145 * variant must be manually adjusted with every SCIP release containing new callbacks for pricers in order to compile.
2146 *
2147 *
2148 * In addition, the pricer has to be activated before the solution process starts, like it is done
2149 * in the pricer of the Coloring application (applications/Coloring/src/reader_col.c) by calling
2150 * \code
2151 * SCIP_CALL( SCIPactivatePricer(scip, SCIPfindPricer(scip, "coloring")) );
2152 * \endcode
2153 *
2154 * If you are using pricer data, you have to allocate the memory for the data at this point.
2155 * You can do this by calling:
2156 * \code
2157 * SCIP_CALL( SCIPallocBlockMemory(scip, &pricerdata) );
2158 * \endcode
2159 * You also have to initialize the fields in struct SCIP_PricerData afterwards.
2160 *
2161 * You may also add user parameters for your pricer, see the method SCIPincludePricerColoring() in the pricer of the Coloring application
2162 * for an example of how to add user parameters.
2163 *
2164 *
2165 * @section PRICER_FUNDAMENTALCALLBACKS Fundamental Callback Methods of a Pricer
2166 *
2167 * The fundamental callback methods have to be implemented in order to obtain an operational algorithm.
2168 * They are passed together with the pricer itself to SCIP using SCIPincludePricer() or SCIPincludePricerBasic(),
2169 * see @ref PRICER_INTERFACE.
2170 *
2171 * In the case of a pricer, there are two fundamental callback methods, namely the @ref PRICERREDCOST and the
2172 * @ref PRICERFARKAS callbacks, which both search for new variables and add them to the problem.
2173 * These methods have to be implemented for every pricer; the other callback methods are optional.
2174 * In the C++ wrapper class scip::ObjPricer, the scip_redcost() method (which corresponds to the PRICERREDCOST callback)
2175 * is a virtual abstract member function. You have to implement it in order to be able to construct an object of your
2176 * pricer class.
2177 *
2178 * Additional documentation for the callback methods can be found in type_pricer.h.
2179 *
2180 * @subsection PRICERREDCOST
2181 *
2182 * The PRICERREDCOST callback is called inside the price-and-cut loop of the subproblem solving process if the current LP relaxation
2183 * is feasible.
2184 * It should search for additional variables that can contribute to improve the current LP's solution value.
2185 * In standard branch-and-price, these are variables with negative dual feasibility, that is negative
2186 * reduced costs for non-negative variables, positive reduced costs for non-positive variables,
2187 * and non-zero reduced costs for variables that can be negative and positive.
2188 *
2189 * Whenever the pricer finds a variable with negative dual feasibility, it should call SCIPcreateVar()
2190 * and SCIPaddPricedVar() to add the variable to the problem. Furthermore, it should call the appropriate
2191 * methods of the constraint handlers to add the necessary variable entries to the constraints, see pub_cons.h.
2192 *
2193 * In the usual case that the pricer either adds a new variable or ensures that there are no further variables with negative dual feasibility,
2194 * the result pointer should be set to SCIP_SUCCESS. Only if the pricer aborts pricing without creating a new variable, but
2195 * there might exist additional variables with negative dual feasibility, the result pointer should be set to SCIP_DIDNOTRUN.
2196 * In this case, which sometimes is referred to as "early branching", the LP solution will not be used as a lower bound.
2197 * The pricer can, however, store a valid lower bound in the <code>lowerbound</code> pointer.
2198 *
2199 * Pricers usually need the dual LP solution as input for the pricing algorithm.
2200 * Since SCIP does not know the semantics of the individual constraints in the problem, the dual solution
2201 * has to be provided by the constraint handlers.
2202 * For example, the \ref cons_setppc.h "setppc constraint handler", which deals with set partitioning, packing, and covering constraints, provides
2203 * the method SCIPgetDualsolSetppc() to access the dual solution value for a single constraint.
2204 * Similarly, the dual solution of a linear constraint can be queried with the method SCIPgetDualsolLinear() of cons_linear.h.
2205 * The reduced costs of the existing variables can be accessed with the method SCIPgetVarRedcost().
2206 *
2207 * @subsection PRICERFARKAS
2208 *
2209 * If the current LP relaxation is infeasible, it is the task of the pricer to generate additional variables that can
2210 * potentially render the LP feasible again. In standard branch-and-price, these are variables with positive Farkas values,
2211 * and the PRICERFARKAS method should identify those variables.
2212 *
2213 * If the LP was proven to be infeasible, we have an infeasibility proof by the dual Farkas multipliers \f$y\f$.
2214 * With the values of \f$y\f$, an implicit inequality \f$y^T A x \ge y^T b\f$ is associated, with \f$b\f$ given
2215 * by the sides of the LP rows and the sign of \f$y\f$:
2216 * - if \f$y_i\f$ is positive, \f$b_i\f$ is the left hand side of the row,
2217 * - if \f$y_i\f$ is negative, \f$b_i\f$ is the right hand side of the row.
2218 *
2219 * \f$y\f$ is chosen in a way, such that the valid inequality \f$y^T A x \ge y^T b\f$ is violated by all \f$x\f$,
2220 * especially by the (for this inequality least infeasible solution) \f$x'\f$ defined by
2221 * - \f$x'_i := ub_i\f$, if \f$y^T A_i \ge 0\f$
2222 * - \f$x'_i := lb_i\f$, if \f$y^T A_i < 0\f$.
2223 * Pricing in this case means to add variables \f$i\f$ with positive Farkas value, i.e., \f$y^T A_i x'_i > 0\f$.
2224 *
2225 * To apply Farkas pricing, the pricer needs to know the Farkas values of the constraints. Like the dual solution values for
2226 * feasible LP solutions, the dual Farkas values for infeasible solutions can be obtained by constraint handler interface
2227 * methods such as the SCIPgetDualfarkasLinear() method of the linear constraint handler.
2228 * The Farkas values for the bounds of the variables can be accessed with SCIPgetVarFarkasCoef().
2229 *
2230 * It is useful to note that Farkas pricing is the same as the regular pricing with a zero objective function.
2231 * Therefore, a typical implementation of a pricer would consist of a generic pricing algorithm that gets a dual solution and an
2232 * objective function vector as input and generates variables by calling SCIPcreateVar() and SCIPaddPricedVar().
2233 * The PRICERREDCOST callback would call this function with the regular objective function and the regular dual solution vector,
2234 * while the PRICERFARKAS callback would call this function with a zero objective function and the Farkas vector.
2235 * From a practical point of view, it is usually the simplest approach to provide just one Boolean flag to the generic pricing
2236 * algorithm in order to identify whether it is reduced cost or Farkas pricing. Then, the algorithm would just call the appropriate
2237 * methods to access the dual solution or objective function, depending on the Boolean flag.
2238 *
2239 * @section PRICER_ADDITIONALCALLBACKS Additional Callback Methods of a Pricer
2240 *
2241 * The additional callback methods do not need to be implemented in every case.
2242 * However, some of them have to be implemented for most applications. They can either be passed directly with
2243 * SCIPincludePricer() to SCIP or via specific <b>setter functions</b> after a call of SCIPincludePricerBasic(),
2244 * see also @ref PRICER_INTERFACE.
2245 *
2246 * @subsection PRICERFREE
2247 *
2248 * If you are using pricer data, you have to implement this method in order to free the pricer data.
2249 * This can be done by the procedure described in stp/src/pricer_stp.c,
2250 * see https://scipjack.zib.de/.
2251 *
2252 * If you have allocated memory for fields in your pricer data, remember to free this memory
2253 * before freeing the pricer data itself.
2254 * If you are using the C++ wrapper class, this method is not available.
2255 * Instead, just use the destructor of your class to free the member variables of your class.
2256 *
2257 * @subsection PRICERCOPY
2258 *
2259 * The PRICERCOPY callback is executed when the SCIP instance is copied, e.g. to solve a sub-SCIP. By defining this
2260 * callback as <code>NULL</code> the user disables the inclusion of the pricer into all copied SCIP
2261 * instances. This means that primal heuristics will work on a sub-SCIP that contains only a part of the variables
2262 * and no variables are priced in during the solving process of the sub-SCIP. Therefore, primal solutions found in the
2263 * copied problem are typically still valid for the original problem and used for its solving process,
2264 * but dual reductions cannot be transferred to the original problem.
2265 *
2266 * <b>Note:</b> If you implement this callback, be careful when setting the valid pointer. The valid pointer should be
2267 * set to TRUE if (and only if!) you can make sure that all necessary data of the pricer are copied
2268 * correctly. If the complete problem is validly copied, i.e. if the copy methods of all problem defining plugins
2269 * (constraint handlers and pricers) return <code>*valid = TRUE</code>, then dual reductions found for the copied problem can be
2270 * transferred to the original SCIP instance. Thus, if the valid pointer is wrongly set to TRUE, it might happen that
2271 * optimal solutions are cut off.
2272 *
2273 * @subsection PRICERINIT
2274 *
2275 * The PRICERINIT callback is executed after the problem is transformed.
2276 * The pricer may, e.g., use this call to replace the original constraints stored in its pricer data by transformed
2277 * constraints, or to initialize other elements of its pricer data.
2278 *
2279 * @subsection PRICEREXIT
2280 *
2281 * The PRICEREXIT callback is executed before the transformed problem is freed.
2282 * In this method, the pricer should free all resources that have been allocated for the solving process in PRICERINIT.
2283 *
2284 * @subsection PRICERINITSOL
2285 *
2286 * The PRICERINITSOL callback is executed when the presolving is finished and the branch-and-bound process is about to begin.
2287 * The pricer may use this call to initialize its branch-and-bound specific data.
2288 *
2289 * @subsection PRICEREXITSOL
2290 *
2291 * The PRICEREXITSOL callback is executed before the branch-and-bound process is freed.
2292 * The pricer should use this call to clean up its branch-and-bound data, which was allocated in PRICERINITSOL.
2293 *
2294 * @section PRICER_REMARKS Further remarks
2295 *
2296 * If you use your own branching rule (e.g., to branch on constraints), make sure that it is able to branch on \a "pseudo solutions".
2297 * Otherwise, SCIP will use its default branching rules, if necessary (which all branch on variables). This
2298 * could disturb the pricing problem or branching might not even be possible, e.g., if all variables created thus far have already been fixed.
2299 *
2300 * Note that if the original problem is a maximization problem, SCIP will transform the problem into a minimization
2301 * problem by multiplying the objective function by -1. The pricer has to take care of this by multiplying
2302 * the original objective function value of all variables created during the solving process by -1.
2303 *
2304 * In some cases, bounds on variables are implicitly enforced by constraints of the problem and the objective function.
2305 * Therefore, these bounds do not need to be added to the LP explicitly, which has the advantage that the pricing routine does not need to
2306 * care about the corresponding dual values.
2307 * We call these bounds lazy bounds, they may be set by SCIPchgVarLbLazy() and SCIPchgVarUbLazy() for upper or lower bounds, respectively.
2308 * If the lazy bound equals the local bound, the corresponding bound is not put into the LP.
2309 * In diving mode, lazy bounds are explicitly put into the LP, because changing the objective (which is only possible in diving)
2310 * might reverse the implicitly given bounds. When diving is finished, the bounds are again removed from the LP.
2311 */
2312
2313/*--+----1----+----2----+----3----+----4----+----5----+----6----+----7----+----8----+----9----+----0----+----1----+----2*/
2314
2315/**@page PRESOL How to add presolvers
2316 *
2317 * Presolvers are used to reduce the size of the model by removing irrelevant information like redundant constraints,
2318 * to strengthen the LP relaxation by exploiting integrality information, and to extract useful information in the
2319 * presolving step.
2320 * Constraint based presolving is done in the CONSPRESOL callback methods of the constraint handlers, see \ref CONSPRESOL.
2321 * Some propagation steps can already be applied in presolving via the PROPRESOL callback methods of propagators, see \ref PROPPRESOL.
2322 * The presolver plugins complement these by additional, usually optimality based, presolving reductions.
2323 * \n
2324 * A complete list of all presolvers contained in this release can be found \ref PRESOLVERS "here".
2325 *
2326 * We now explain how users can add their own presolvers.
2327 * Take the trivial presolver (src/scip/presol_trivial.c) as an example.
2328 * As all other default plugins, it is written in C. C++ users can easily adapt the code by using the scip::ObjPresol wrapper
2329 * base class and implement the scip_...() virtual methods instead of the SCIP_DECL_PRESOL... callback methods.
2330 *
2331 * Additional documentation for the callback methods of a presolver, in particular for their input parameters,
2332 * can be found in the file type_presol.h.
2333 *
2334 * Here is what you have to do to implement a presolver:
2335 * -# Copy the template files src/scip/presol_xyz.c and src/scip/presol_xyz.h into files named "presol_mypresolver.c"
2336 * and "presol_mypresolver.h".
2337 * \n
2338 * Make sure to adjust your build system such that these files are compiled and linked to your project. \n
2339 * If you are adding a new default plugin, this means updating the `src/CMakeLists.txt` and `Makefile` files in the SCIP distribution.
2340 * -# Use `SCIPincludePresolMypresolver()` in order to include the presolver into your SCIP instance,
2341 * e.g., in the main file of your project (see, e.g., src/cmain.c in the Binpacking example). \n
2342 * If you are adding a new default plugin, this include function must be added to `src/scipdefplugins.c`.
2343 * -# Open the new files with a text editor and replace all occurrences of "xyz" by "mypresolver".
2344 * -# Adjust the properties of the presolver (see \ref PRESOL_PROPERTIES).
2345 * -# Define the presolver data (see \ref PRESOL_DATA). This is optional.
2346 * -# Implement the interface methods (see \ref PRESOL_INTERFACE).
2347 * -# Implement the fundamental callback methods (see \ref PRESOL_FUNDAMENTALCALLBACKS).
2348 * -# Implement the additional callback methods (see \ref PRESOL_ADDITIONALCALLBACKS). This is optional.
2349 *
2350 *
2351 * @section PRESOL_PROPERTIES Properties of a Presolver
2352 *
2353 * At the top of the new file "presol_mypresolver.c", you can find the presolver properties.
2354 * These are given as compiler defines.
2355 * In the C++ wrapper class, you have to provide the presolver properties by calling the constructor
2356 * of the abstract base class scip::ObjPresol from within your constructor.
2357 * The properties you have to set have the following meaning:
2358 *
2359 * \par PRESOL_NAME: the name of the presolver.
2360 * This name is used in the interactive shell to address the presolver.
2361 * Additionally, if you are searching for a presolver with SCIPfindPresol(), this name is looked up.
2362 * Names have to be <b>unique</b>: no two presolvers may have the same name.
2363 *
2364 * \par PRESOL_DESC: the description of the presolver.
2365 * This string is printed as a description of the presolver in the interactive shell.
2366 *
2367 * \par PRESOL_TIMING: the default timing of the presolver.
2368 * There are three presolving timings: FAST, MEDIUM, and EXHAUSTIVE.
2369 * Every presolving round starts with the FAST presolvers. MEDIUM presolvers are only called, if FAST presolvers did not find
2370 * enough reductions in this round so far, and EXHAUSTIVE presolving steps are only performed if all presolvers called before
2371 * in this round were unsuccessful.
2372 * Presolvers should be assigned a timing based on how expensive they are, e.g., presolvers that provide fast algorithms that
2373 * usually have a high impact (i.e., remove lots of variables or tighten bounds of many variables) should have a timing FAST.
2374 * If a presolver implements different algorithms of different complexity, it may also get multiple timings and check the timing
2375 * internally in the \ref PRESOLEXEC callback to decide which algorithms to run.
2376 *
2377 * \par PRESOL_PRIORITY: the priority of the presolver.
2378 * Within a presolving round, when calling all presolvers and presolving methods of propagators and constraint handlers
2379 * with a given timing, those are called in
2380 * a predefined order, which is given by the priorities of the presolvers and the check priorities of the
2381 * constraint handlers, see \ref CONS_PROPERTIES.
2382 * First, the presolvers with non-negative priority are called in the order of decreasing priority.
2383 * Next, the presolving methods of the different constraint handlers are called in the order of decreasing check
2384 * priority.
2385 * Finally, the presolvers with negative priority are called in the order of decreasing priority.
2386 * \n
2387 * Again, presolvers that provide fast algorithms that usually have a high impact (i.e., remove lots of variables or tighten
2388 * bounds of many variables) should have a high priority.
2389 * An easy way to list the timings and
2390 * priorities of all presolvers, propagators, and constraint handlers is to type "display presolvers", "display propagators",
2391 * and "display conshdlrs" in the interactive shell of SCIP.
2392 *
2393 * \par PRESOL_MAXROUNDS: the default maximal number of rounds the presolver participates in.
2394 * The presolving is conducted in rounds: the presolvers and presolving methods of the constraint handlers
2395 * are called iteratively until no more reductions have been found or some other abort criterion applies.
2396 * The "maxrounds" parameter of a presolver imposes a limit on the number of presolving rounds in which the
2397 * presolver is called. The PRESOL_MAXROUNDS property specifies the default value for this parameter.
2398 * A value of -1 represents an unlimited number of rounds.
2399 *
2400 *
2401 * @section PRESOL_DATA Presolver Data
2402 *
2403 * Below the header "Data structures" you can find a struct which is called "struct SCIP_PresolData".
2404 * In this data structure, you can store the data of your presolver. For example, you should store the adjustable parameters
2405 * of the presolver in this data structure.
2406 * If you are using C++, you can add presolver data as usual as object variables to your class.
2407 * \n
2408 * Defining presolver data is optional. You can leave this struct empty.
2409 *
2410 *
2411 * @section PRESOL_INTERFACE Interface Methods
2412 *
2413 * At the bottom of "presol_mypresolver.c", you can find the interface method SCIPincludePresolMypresolver(),
2414 * which also appears in "presol_mypresolver.h"
2415 * SCIPincludePresolMypresolver() is called by the user, if (s)he wants to include the presolver,
2416 * i.e., if (s)he wants to use the presolver in his/her application.
2417 *
2418 * This method only has to be adjusted slightly.
2419 * It is responsible for notifying SCIP of the presence of the presolver. For this, you can either call SCIPincludePresol(),
2420 * or SCIPincludePresolBasic() since SCIP version 3.0. In the latter variant, \ref PRESOL_ADDITIONALCALLBACKS "additional callbacks"
2421 * must be added via setter functions as, e.g., SCIPsetPresolCopy(). We recommend this latter variant because
2422 * it is more stable towards future SCIP versions which might have more callbacks, whereas source code using the first
2423 * variant must be manually adjusted with every SCIP release containing new callbacks for presolvers in order to compile.
2424 *
2425 * If you are using presolver data, you have to allocate the memory for the data at this point.
2426 * You can do this by calling:
2427 * \code
2428 * SCIP_CALL( SCIPallocBlockMemory(scip, &presoldata) );
2429 * \endcode
2430 * You also have to initialize the fields in struct SCIP_PresolData afterwards. For freeing the
2431 * presolver data, see \ref PRESOLFREE.
2432 *
2433 * You may also add user parameters for your presolver, see \ref PARAM for how to add user parameters and
2434 * the method SCIPincludePresolTrivial() in src/scip/presol_trivial.c for an example.
2435 *
2436 *
2437 * @section PRESOL_FUNDAMENTALCALLBACKS Fundamental Callback Methods of a Presolver
2438 *
2439 * The fundamental callback methods of the plugins are the ones that have to be implemented in order to obtain
2440 * an operational algorithm.
2441 * They are passed together with the presolver itself to SCIP using SCIPincludePresol() or SCIPincludePresolBasic(),
2442 * see @ref PRESOL_INTERFACE.
2443 *
2444 * Presolver plugins have only one fundamental callback method, namely the @ref PRESOLEXEC method.
2445 * This method has to be implemented for every presolver; the other callback methods are optional.
2446 * In the C++ wrapper class scip::ObjPresol, the scip_exec() method (which corresponds to the PRESOLEXEC callback) is a virtual
2447 * abstract member function.
2448 * You have to implement it in order to be able to construct an object of your presolver class.
2449 *
2450 * Additional documentation for the callback methods, in particular to their input parameters,
2451 * can be found in type_presol.h.
2452 *
2453 * @subsection PRESOLEXEC
2454 *
2455 * The PRESOLEXEC callback is called inside the presolving loop and should perform the actual presolving reductions.
2456 * It should inspect the problem instance at hand and simplify it by tightening bounds of variables, aggregating or fixing
2457 * variables, changing the type of variables, modifying the graph that represents the instance of your application, and
2458 * the like.
2459 *
2460 * Typical methods called by a presolver are, for example, SCIPchgVarType(), SCIPfixVar(), SCIPaggregateVars(), SCIPtightenVarLb(),
2461 * and SCIPtightenVarUb().
2462 *
2463 *
2464 * @section PRESOL_ADDITIONALCALLBACKS Additional Callback Methods of a Presolver
2465 *
2466 * The additional callback methods do not need to be implemented in every case. However, some of them have to be
2467 * implemented for most applications, they can be used, for example, to initialize and free private data.
2468 * Additional callbacks can either be passed directly with SCIPincludePresol() to SCIP or via specific
2469 * <b>setter functions</b> after a call of SCIPincludePresolBasic(), see also @ref PRESOL_INTERFACE.
2470 *
2471 * @subsection PRESOLFREE
2472 *
2473 * If you are using presolver data (see \ref PRESOL_DATA and \ref PRESOL_INTERFACE), you have to implement this method in order to free the presolver data.
2474 * This can be done by the following procedure:
2475 *
2476 * @refsnippet{src/scip/presol_boundshift.c,SnippetPresolFreeBoundshift}
2477 *
2478 * If you have allocated memory for fields in your presolver data, remember to free this memory
2479 * before freeing the presolver data itself.
2480 * If you are using the C++ wrapper class, this method is not available.
2481 * Instead, just use the destructor of your class to free the member variables of your class.
2482 *
2483 * @subsection PRESOLINIT
2484 *
2485 * The PRESOLINIT callback is executed after the problem is transformed.
2486 * The presolver may, e.g., use this call to initialize its presolver data.
2487 * The difference between the original and the transformed problem is explained in
2488 * "What is this thing with the original and the transformed problem about?" on \ref FAQ.
2489 *
2490 * @subsection PRESOLCOPY
2491 *
2492 * The PRESOLCOPY callback is executed when a SCIP instance is copied, e.g. to
2493 * solve a sub-SCIP. By
2494 * defining this callback as
2495 * <code>NULL</code> the user disables the execution of the specified
2496 * presolver for all copied SCIP instances. This may deteriorate the performance
2497 * of primal heuristics using sub-SCIPs.
2498 *
2499 * @subsection PRESOLEXIT
2500 *
2501 * The PRESOLEXIT callback is executed before the transformed problem is freed.
2502 * In this method, the presolver should free all resources that have been allocated for the solving process in PRESOLINIT.
2503 *
2504 * @subsection PRESOLINITPRE
2505 *
2506 * The PRESOLINITPRE callback is executed when the presolving is about to begin.
2507 * The presolver may use this call to initialize its presolving data which only need to exist during the presolving stage.
2508 *
2509 * @subsection PRESOLEXITPRE
2510 *
2511 * The PRESOLEXITPRE callback is executed after presolving finishes and before the branch-and-bound process begins.
2512 * The presolver should use this call to clean up its presolving data, which was allocated in PRESOLINITPRE.
2513 */
2514
2515/*--+----1----+----2----+----3----+----4----+----5----+----6----+----7----+----8----+----9----+----0----+----1----+----2*/
2516
2517/**@page SEPA How to add separators
2518 *
2519 * Separators are used to generate cutting planes that strengthen the LP relaxation of the problem formulation, but are
2520 * not required for a completeness and correctness of the model.
2521 * In contrast, constraint-based cutting planes, the second type of cutting planes in SCIP, are separated in the CONSSEPALP and
2522 * CONSSEPASOL callback methods of the constraint handlers, see \ref CONSSEPALP and \ref CONSSEPASOL. These cuts are
2523 * valid inequalities or even facets of the polyhedron described by a single constraint or a subset of the constraints of
2524 * a single constraint class. See also
2525 * "When should I implement a constraint handler, when should I implement a separator?" on \ref FAQ.
2526 * \n
2527 * A complete list of all separators contained in this release can be found \ref SEPARATORS "here".
2528 *
2529 * We now explain how users can add their own separators.
2530 * Take the separator for the class of Gomory mixed integer inequalities (src/scip/sepa_gomory.c) as an example.
2531 * As all other default plugins, it is written in C. C++ users can easily adapt the code by using the scip::ObjSepa wrapper
2532 * base class and implement the scip_...() virtual methods instead of the SCIP_DECL_SEPA... callback methods.
2533 *
2534 * Additional documentation for the callback methods of a separator, in particular for the input parameters,
2535 * can be found in the file type_sepa.h.
2536 *
2537 * Here is what you have to do to implement a separator:
2538 * -# Copy the template files src/scip/sepa_xyz.c and src/scip/sepa_xyz.h into files "sepa_myseparator.c"
2539 * and "sepa_myseparator.h".
2540 \n
2541 * Make sure to adjust your build system such that these files are compiled and linked to your project. \n
2542 * If you are adding a new default plugin, this means updating the `src/CMakeLists.txt` and `Makefile` files in the SCIP distribution.
2543 * -# Use `SCIPincludeSepaMyseparator()` in order to include the separator into your SCIP instance,
2544 * e.g., in the main file of your project (see, e.g., src/cmain.c in the Binpacking example). \n
2545 * If you are adding a new default plugin, this include function must be added to `src/scipdefplugins.c`.
2546 * -# Open the new files with a text editor and replace all occurrences of "xyz" by "myseparator".
2547 * -# Adjust the properties of the separator (see \ref SEPA_PROPERTIES).
2548 * -# Define the separator data (see \ref SEPA_DATA). This is optional.
2549 * -# Implement the interface methods (see \ref SEPA_INTERFACE).
2550 * -# Implement the fundamental callback methods (see \ref SEPA_FUNDAMENTALCALLBACKS).
2551 * -# Implement the additional callback methods (see \ref SEPA_ADDITIONALCALLBACKS). This is optional.
2552 *
2553 *
2554 * @section SEPA_PROPERTIES Properties of a Separator
2555 *
2556 * At the top of the new file "sepa_myseparator.c", you can find the separator properties.
2557 * These are given as compiler defines.
2558 * In the C++ wrapper class, you have to provide the separator properties by calling the constructor
2559 * of the abstract base class scip::ObjSepa from within your constructor.
2560 * The properties you have to set have the following meaning:
2561 *
2562 * \par SEPA_NAME: the name of the separator.
2563 * This name is used in the interactive shell to address the separator.
2564 * Additionally, if you are searching for a separator with SCIPfindSepa(), this name is looked up.
2565 * Names have to be unique: no two separators may have the same name.
2566 *
2567 * \par SEPA_DESC: the description of the separator.
2568 * This string is printed as a description of the separator in the interactive shell.
2569 *
2570 * \par SEPA_PRIORITY: the priority of the separator.
2571 * In each separation round during the price-and-cut loop of the subproblem processing or the separation loop
2572 * of the primal solution separation, the separators and separation methods of the constraint handlers are called in
2573 * a predefined order, which is given by the priorities of the separators and the separation priorities
2574 * of the constraint handlers (see \ref CONS_PROPERTIES).
2575 * First, the separators with non-negative priority are called in the order of decreasing priority.
2576 * Next, the separation methods of the constraint handlers are called in the order of decreasing separation
2577 * priority.
2578 * Finally, the separators with negative priority are called in the order of decreasing priority. An easy way to list the
2579 * priorities of all separators and constraint handlers is to type "display separators" and "display conshdlrs" in
2580 * the interactive shell.
2581 * \n
2582 * The priority of the separator should be set according to the complexity of the cut separation algorithm and the
2583 * impact of the resulting cuts: separators that provide fast algorithms that usually have a high impact (i.e., cut off
2584 * a large portion of the LP relaxation) should have a high priority.
2585 * See \ref SEPAEXECLP and \ref SEPAEXECSOL for further details of the separation callbacks.
2586 *
2587 * \par SEPA_FREQ: the default frequency for separating cuts.
2588 * The frequency defines the depth levels at which the separation methods \ref SEPAEXECLP and \ref SEPAEXECSOL are called.
2589 * For example, a frequency of 7 means, that the separation callback is executed for subproblems that are in depth
2590 * 0, 7, 14, ... of the branching tree. A frequency of 0 means, that the separation method is only called at the root node.
2591 * A frequency of -1 disables the separator.
2592 * \n
2593 * The frequency can be adjusted by the user. This property of the separator only defines the default value of the frequency.
2594 * If you want to have a more flexible control of when to execute the separation algorithm, you have to assign
2595 * a frequency of 1 and implement a check at the beginning of your separation methods whether you really want to execute
2596 * the separation or not. If you do not want to execute it, set the result code of
2597 * \ref SEPAEXECLP and \ref SEPAEXECSOL to SCIP_DIDNOTRUN.
2598 *
2599 * \par SEPA_MAXBOUNDDIST: the default maximal relative distance from the current node's dual bound to primal bound compared to best node's dual bound for applying separation.
2600 * At the current branch-and-bound node, the relative distance from its dual bound (local dual bound)
2601 * to the primal bound compared to the best node's dual bound (global dual bound) is considered. The separation method
2602 * of the separator will only be applied at the current node if this relative distance does not exceed SEPA_MAXBOUNDDIST.
2603 * \n
2604 * For example, if the global dual bound is 50 and the primal bound is 60, SEPA_MAXBOUNDDIST = 0.25 means that separation
2605 * is only applied if the current node's dual bound is in the first quarter of the interval [50,60], i.e., if it is less
2606 * than or equal to 52.5.
2607 * \n
2608 * In particular, the values 0.0 and 1.0 mean that separation is applied at the current best node only or at all
2609 * nodes, respectively. Since separation seems to be most important to apply at nodes that define to the global
2610 * dual bound, 0.0 is probably a good choice for SEPA_MAXBOUNDDIST.
2611 * Note that separators with a frequency of SEPA_FREQ = 0 are only applied at the root node.
2612 * Obviously, at the root node the local dual bound is equal to the global dual bound and thus, the separator is called
2613 * for any value of SEPA_MAXBOUNDDIST.
2614 *
2615 * \par SEPA_USESSUBSCIP: Does the separator use a secondary SCIP instance?
2616 * Some heuristics and separators solve MIPs or SAT problems and use a secondary SCIP instance. Examples are
2617 * Large Neighborhood Search heuristics such as RINS and Local Branching or the CGMIP separator. To avoid recursion,
2618 * these plugins usually deactivate all other plugins that solve MIPs. If a separator uses a secondary SCIP instance,
2619 * this parameter has to be TRUE and it is recommended to call SCIPsetSubscipsOff() for the secondary SCIP instance.
2620 *
2621 * \par SEPA_DELAY: the default for whether the separation method should be delayed, if other separators or constraint handlers found cuts.
2622 * If the separator's separation method is marked to be delayed, it is only executed after no other separator
2623 * or constraint handler found a cut during the price-and-cut loop.
2624 * If the separation method of the separator is very expensive, you may want to mark it to be delayed until all cheap
2625 * separation methods have been executed.
2626 *
2627 * @section SEPA_DATA Separator Data
2628 *
2629 * Below the header "Data structures" you can find a struct which is called "struct SCIP_SepaData".
2630 * In this data structure, you can store the data of your separator. For example, you should store the adjustable
2631 * parameters of the separator in this data structure. In a separator, user parameters for the maximal number of
2632 * separation rounds per node and for the maximal number of cuts separated per separation round might be useful.
2633 * If you are using C++, you can add separator data as usual as object variables to your class.
2634 * \n
2635 * Defining separator data is optional. You can leave the struct empty.
2636 *
2637 * @section SEPA_INTERFACE Interface Methods
2638 *
2639 * At the bottom of "sepa_myseparator.c", you can find the interface method SCIPincludeSepaMyseparator(),
2640 * which also appears in "sepa_myseparator.h"
2641 * SCIPincludeSepaMyseparator() is called by the user, if (s)he wants to include the separator,
2642 * i.e., if (s)he wants to use the separator in his/her application.
2643 *
2644 * This method only has to be adjusted slightly.
2645 * It is responsible for notifying SCIP of the presence of the separator. For this, you can either call SCIPincludeSepa(),
2646 * or SCIPincludeSepaBasic() since SCIP version 3.0. In the latter variant, \ref SEPA_ADDITIONALCALLBACKS "additional callbacks"
2647 * must be added via setter functions as, e.g., SCIPsetSepaCopy(). We recommend this latter variant because
2648 * it is more stable towards future SCIP versions which might have more callbacks, whereas source code using the first
2649 * variant must be manually adjusted with every SCIP release containing new callbacks for separators in order to compile.
2650 *
2651 * If you are using separator data, you have to allocate the memory
2652 * for the data at this point. You can do this by calling:
2653 * \code
2654 * SCIP_CALL( SCIPallocBlockMemory(scip, &sepadata) );
2655 * \endcode
2656 * You also have to initialize the fields in "struct SCIP_SepaData" afterwards. For freeing the
2657 * separator data, see \ref SEPAFREE.
2658 *
2659 * You may also add user parameters for your separator, see \ref PARAM for how to add user parameters and
2660 * the method SCIPincludeSepaGomory() in src/scip/sepa_gomory.c for an example.
2661 *
2662 *
2663 * @section SEPA_FUNDAMENTALCALLBACKS Fundamental Callback Methods of a Separator
2664 *
2665 * The fundamental callback methods of the plugins are the ones that have to be implemented in order to obtain
2666 * an operational algorithm.
2667 * They are passed together with the separator itself to SCIP using SCIPincludeSepa() or SCIPincludeSepaBasic(),
2668 * see @ref SEPA_INTERFACE.
2669 *
2670 * Separator plugins have two callbacks, @ref SEPAEXECLP and @ref SEPAEXECSOL, of which at least one must be implemented.
2671 *
2672 * Additional documentation for the callback methods, in particular to their input parameters,
2673 * can be found in type_sepa.h.
2674 *
2675 * @subsection SEPAEXECLP
2676 *
2677 * The SEPAEXECLP callback is executed during the price-and-cut loop of the subproblem processing.
2678 * It should try to generate general purpose cutting planes in order to separate the current LP solution.
2679 * The method is called in the LP solution loop, which means that a valid LP solution exists.
2680 *
2681 * Usually, the callback searches and produces cuts, that are added with a call to SCIPaddCut().
2682 * If the cut should be added to the global cut pool, it calls SCIPaddPoolCut().
2683 * If the cut is constructed via multiple calls to SCIPaddVarToRow(), then performance can be improved by calling
2684 * SCIPcacheRowExtensions() before these additions and SCIPflushRowExtensions() after.
2685 * In addition to LP rows, the callback may also produce domain reductions or add additional constraints.
2686 *
2687 * Overall, the SEPAEXECLP callback has the following options, which is indicated by the possible return values of
2688 * the 'result' variable (see type_sepa.h):
2689 * - detecting that the node is infeasible in the variable's bounds and can be cut off (result SCIP_CUTOFF)
2690 * - adding an additional constraint (result SCIP_CONSADDED)
2691 * - reducing a variable's domain (result SCIP_REDUCEDDOM)
2692 * - adding a cutting plane to the LP (result SCIP_SEPARATED)
2693 * - stating that the separator searched, but did not find domain reductions, cutting planes, or cut constraints
2694 * (result SCIP_DIDNOTFIND)
2695 * - stating that the separator was skipped (result SCIP_DIDNOTRUN)
2696 * - stating that the separator was skipped, but should be called again (result SCIP_DELAYED)
2697 * - stating that a new separation round should be started without calling the remaining separator methods (result SCIP_NEWROUND)
2698 *
2699 * @subsection SEPAEXECSOL
2700 *
2701 * The SEPAEXECSOL callback is executed during the separation loop on arbitrary primal solutions.
2702 * It should try to generate general purpose cutting planes in order to separate the given primal solution.
2703 * The method is not called in the LP solution loop, which means that there is no valid LP solution.
2704 *
2705 * In the standard SCIP environment, the SEPAEXECSOL callback is not used because only LP solutions are
2706 * separated. The SEPAEXECSOL callback provides means to support external relaxation handlers like semidefinite
2707 * relaxations that want to separate an intermediate primal solution vector. Thus, if you do not want to support
2708 * such external plugins, you do not need to implement this callback method.
2709 *
2710 * Usually, the callback searches and produces cuts, that are added with a call to SCIPaddCut().
2711 * If the cut should be added to the global cut pool, it calls SCIPaddPoolCut().
2712 * If the cut is constructed via multiple calls to SCIPaddVarToRow(), then performance can be improved by calling
2713 * SCIPcacheRowExtensions() before these additions and SCIPflushRowExtensions() after.
2714 * In addition to LP rows, the callback may also produce domain reductions or add other constraints.
2715 *
2716 * Overall, the SEPAEXECSOL callback has the following options, which is indicated by the possible return values of
2717 * the 'result' variable (see type_sepa.h):
2718 * - detecting that the node is infeasible in the variable's bounds and can be cut off (result SCIP_CUTOFF)
2719 * - adding an additional constraint (result SCIP_CONSADDED)
2720 * - reducing a variable's domain (result SCIP_REDUCEDDOM)
2721 * - adding a cutting plane to the LP (result SCIP_SEPARATED)
2722 * - stating that the separator searched, but did not find domain reductions, cutting planes, or cut constraints
2723 * (result SCIP_DIDNOTFIND)
2724 * - stating that the separator was skipped (result SCIP_DIDNOTRUN)
2725 * - stating that the separator was skipped, but should be called again (result SCIP_DELAYED)
2726 * - stating that a new separation round should be started without calling the remaining separator methods (result SCIP_NEWROUND)
2727 *
2728 *
2729 * @section SEPA_ADDITIONALCALLBACKS Additional Callback Methods of a Separator
2730 *
2731 * The additional callback methods do not need to be implemented in every case. However, some of them have to be
2732 * implemented for most applications, they can be used, for example, to initialize and free private data.
2733 * Additional callbacks can either be passed directly with SCIPincludeSepa() to SCIP or via specific
2734 * <b>setter functions</b> after a call of SCIPincludeSepaBasic(), see also @ref SEPA_INTERFACE.
2735 *
2736 * @subsection SEPAFREE
2737 *
2738 * If you are using separator data (see \ref SEPA_DATA and \ref SEPA_INTERFACE), you have to implement this method
2739 * in order to free the separator data. This can be done by the following procedure:
2740 *
2741 * @refsnippet{src/scip/sepa_gomory.c,SnippetSepaFreeGomory}
2742 *
2743 * If you have allocated memory for fields in your separator data, remember to free this memory
2744 * before freeing the separator data itself.
2745 * If you are using the C++ wrapper class, this method is not available.
2746 * Instead, just use the destructor of your class to free the member variables of your class.
2747 *
2748 * @subsection SEPACOPY
2749 *
2750 * The SEPACOPY callback is executed when a SCIP instance is copied, e.g. to
2751 * solve a sub-SCIP. By
2752 * defining this callback as
2753 * <code>NULL</code> the user disables the execution of the specified
2754 * separator for all copied SCIP instances. This may deteriorate the performance
2755 * of primal heuristics using sub-SCIPs.
2756 *
2757 * @subsection SEPAINIT
2758 *
2759 * The SEPAINIT callback is executed after the problem is transformed.
2760 * The separator may, e.g., use this call to initialize its separator data.
2761 * The difference between the original and the transformed problem is explained in
2762 * "What is this thing with the original and the transformed problem about?" on \ref FAQ.
2763 *
2764 * @subsection SEPAEXIT
2765 *
2766 * The SEPAEXIT callback is executed before the transformed problem is freed.
2767 * In this method, the separator should free all resources that have been allocated for the solving process in SEPAINIT.
2768 *
2769 * @subsection SEPAINITSOL
2770 *
2771 * The SEPAINITSOL callback is executed when the presolving is finished and the branch-and-bound process is about to
2772 * begin. The separator may use this call to initialize its branch-and-bound specific data.
2773 *
2774 * @subsection SEPAEXITSOL
2775 *
2776 * The SEPAEXITSOL callback is executed before the branch-and-bound process is freed. The separator should use this call
2777 * to clean up its branch-and-bound data, in particular to release all LP rows that it has created or captured.
2778 */
2779
2780/*--+----1----+----2----+----3----+----4----+----5----+----6----+----7----+----8----+----9----+----0----+----1----+----2*/
2781
2782/**@page PROP How to add propagators
2783 *
2784 * Propagators are used to tighten the domains of the variables. Like for cutting planes, there are two different types
2785 * of domain propagations. Constraint based (primal) domain propagation algorithms are part of the corresponding
2786 * constraint handlers, see \ref CONSPROP. In contrast, domain propagators usually provide dual propagations, i.e.,
2787 * propagations that can be applied using the objective function and the current best known primal solution. This
2788 * section deals with such propagators.
2789 *
2790 * A complete list of all propagators contained in this release can be found \ref PROPAGATORS "here".
2791 *
2792 * We now explain how users can add their own propagators. Take the pseudo objective function propagator
2793 * (src/scip/prop_pseudoobj.c) as an example. As all other default plugins, it is written in C. C++ users can easily
2794 * adapt the code by using the scip::ObjProp wrapper base class and implement the @c scip_...() virtual methods instead
2795 * of the @c SCIP_DECL_PROP... callback methods.
2796 *
2797 * Additional documentation for the callback methods of a propagator can be found in the file type_prop.h.
2798 *
2799 * Here is what you have to do to implement a propagator:
2800 * -# Copy the template files src/scip/prop_xyz.c and src/scip/prop_xyz.h into files named "prop_mypropagator.c"
2801 * and "prop_mypropagator.h".
2802 * \n
2803 * Make sure to adjust your build system such that these files are compiled and linked to your project. \n
2804 * If you are adding a new default plugin, this means updating the `src/CMakeLists.txt` and `Makefile` files in the SCIP distribution.
2805 * -# Use `SCIPincludePropMypropagator()` in order to include the propagator into your SCIP instance,
2806 * e.g., in the main file of your project (see, e.g., src/cmain.c in the Binpacking example). \n
2807 * If you are adding a new default plugin, this include function must be added to `src/scipdefplugins.c`.
2808 * -# Open the new files with a text editor and replace all occurrences of "xyz" by "mypropagator".
2809 * -# Adjust the properties of the propagator (see \ref PROP_PROPERTIES).
2810 * -# Define the propagator data (see \ref PROP_DATA). This is optional.
2811 * -# Implement the interface methods (see \ref PROP_INTERFACE).
2812 * -# Implement the fundamental callback methods (see \ref PROP_FUNDAMENTALCALLBACKS).
2813 * -# Implement the additional callback methods (see \ref PROP_ADDITIONALCALLBACKS). This is optional.
2814 *
2815 * @section PROP_PROPERTIES Properties of a Propagator
2816 *
2817 * At the top of the new file "prop_mypropagator.c" you can find the propagator properties. These are given as compiler
2818 * defines. The presolving-related properties are optional,
2819 * they only have to be defined if the propagator supports presolving routines.
2820 * In the C++ wrapper class, you have to provide the propagator properties by calling the constructor of the
2821 * abstract base class scip::ObjProp from within your constructor. The properties you have the following meaning:
2822 *
2823 * @subsection PROP_FUNDAMENTALPROPERTIES Fundamental properties of a propagator
2824 *
2825 * \par PROP_NAME: the name of the propagator.
2826 * This name is used in the interactive shell to address the propagator. Additionally, if you are searching for a
2827 * propagator with SCIPfindProp(), this name is searched for. Names have to be unique: no two propagators may have the
2828 * same name.
2829 *
2830 * \par PROP_DESC: the description of the propagator.
2831 * This string is printed as a description of the propagator in the interactive shell.
2832 *
2833 * \par PROP_PRIORITY: the priority of the propagator.
2834 * In each propagation round, the propagators and propagation methods of the constraint handlers are called in a
2835 * predefined order, which is given by the priorities of the propagators and the check priorities of the constraint
2836 * handlers. First, the propagators with non-negative priority are called in order of decreasing priority. Next, the
2837 * propagation methods of the different constraint handlers are called in order of decreasing check priority. Finally,
2838 * the propagators with negative priority are called in order of decreasing priority. \n The priority of the
2839 * propagators should be set according to the complexity of the propagation algorithm and the impact of the domain
2840 * propagations: propagators providing fast algorithms that usually have a high impact (i.e., tighten many bounds)
2841 * should have a high priority.
2842 *
2843 * \par PROP_FREQ: the default frequency for propagating domains.
2844 * The frequency defines the depth levels at which the propagation method \ref PROPEXEC is called. For example, a
2845 * frequency of 7 means, that the propagation callback is executed for subproblems that are in depth 0, 7, 14, ... of
2846 * the branching tree. A frequency of 0 means that propagation is only applied in preprocessing and at the root node. A
2847 * frequency of -1 disables the propagator.
2848 * \n
2849 * The frequency can be adjusted by the user. This property of the propagator only defines the default value of the
2850 * frequency.\n
2851 * <b>Note:</b> If you want to have a more flexible control of when to execute the propagation algorithm, you have to
2852 * assign a frequency of 1 and implement a check at the beginning of your propagation algorithm whether you really want
2853 * to execute the domain propagation or not. If you do not want to execute it, set the result code to SCIP_DIDNOTRUN.
2854 *
2855 * \par PROP_DELAY: the default for whether the propagation method should be delayed, if other propagators or constraint handlers found domain reductions.
2856 * If the propagator's propagation method is marked to be delayed, it is only executed after no other propagator or
2857 * constraint handler found a domain reduction in the current iteration of the domain propagation loop. If the
2858 * propagation method of the propagator is very expensive, you may want to mark it to be delayed until all cheap
2859 * propagation methods have been executed.
2860 *
2861 * \par PROP_TIMING: the timing mask of the propagator.
2862 * SCIP calls the domain propagation routines at different places in the node processing loop.
2863 * This property indicates at which places the propagator is called.
2864 * Possible values are defined in type_timing.h and can be concatenated, e.g., as in SCIP_PROPTIMING_ALWAYS.
2865 *
2866 * @subsection PROP_ADDITIONALPROPERTIES Optional propagator properties
2867 *
2868 * The following properties are optional and only need to be defined if the propagator supports
2869 * presolving, that is, if the \ref PROPPRESOL "presolving callback" is implemented.
2870
2871 * \par PROP_PRESOLTIMING: the timing of the presolving method (FAST, MEDIUM, or EXHAUSTIVE).
2872 * Every presolving round starts with the FAST presolving methods. MEDIUM presolvers are only called, if FAST presolvers did not find
2873 * enough reductions in this round so far, and EXHAUSTIVE presolving steps are only performed if all presolvers called before
2874 * in this round were unsuccessful.
2875 * Presolving methods should be assigned a timing based on how expensive they are, e.g., presolvers that provide fast algorithms that
2876 * usually have a high impact (i.e., remove lots of variables or tighten bounds of many variables) should have a timing FAST.
2877 * If a presolving method implements different algorithms of different complexity, it may also get multiple timings and check the timing
2878 * internally in the \ref PROPPRESOL callback to decide which algorithms to run.
2879 *
2880 * \par PROP_PRESOL_PRIORITY: the priority of the presolving method.
2881 * This attribute is analogous to the PROP_PRIORITY flag, but deals with the preprocessing method of the presolver.
2882 *
2883 * \par PROP_PRESOL_MAXROUNDS: the default maximal number of presolving rounds the propagator participates in.
2884 * The preprocessing is executed in rounds.
2885 * If enough changes have been applied to the model, an additional preprocessing round is performed.
2886 * The MAXROUNDS parameter of a propagator denotes the maximal number of preprocessing rounds, the propagator
2887 * participates in.
2888 * A value of -1 means, that there is no limit on the number of rounds.
2889 * A value of 0 means, the preprocessing callback of the propagator is disabled.
2890 *
2891 * @section PROP_DATA Propagator Data
2892 *
2893 * Below the title "Data structures" you can find a struct called <code>struct SCIP_PropData</code>. In this data
2894 * structure, you can store the data of your propagator. For example, you should store the adjustable parameters of the
2895 * propagator in this data structure. If you are using C++, you can add propagator data as object variables to your
2896 * class as usual .
2897 * \n
2898 * Defining propagator data is optional. You can leave the struct empty.
2899 *
2900 *
2901 * @section PROP_INTERFACE Interface Methods
2902 *
2903 * At the bottom of "prop_mypropagator.c", you can find the interface method SCIPincludeSepaMypropagator(),
2904 * which also appears in "prop_mypropagator.h"
2905 * SCIPincludePropMypropagator() is called by the user, if (s)he wants to include the propagator,
2906 * i.e., if (s)he wants to use the propagator in his/her application.
2907 *
2908 * This method only has to be adjusted slightly.
2909 * It is responsible for notifying SCIP of the presence of the propagator. For this, you can either call SCIPincludeProp(),
2910 * or SCIPincludePropBasic() since SCIP version 3.0. In the latter variant, \ref PROP_ADDITIONALCALLBACKS "additional callbacks"
2911 * must be added via setter functions as, e.g., SCIPsetPropCopy(). We recommend this latter variant because
2912 * it is more stable towards future SCIP versions which might have more callbacks, whereas source code using the first
2913 * variant must be manually adjusted with every SCIP release containing new callbacks for separators in order to compile.
2914 *
2915 *
2916 * If you are using propagator data, you have to allocate the memory for the data at this point. You can do this by
2917 * calling
2918 * \code
2919 * SCIP_CALL( SCIPallocBlockMemory(scip, &propdata) );
2920 * \endcode
2921 * You also have to initialize the fields in <code>struct SCIP_PropData</code> afterwards.
2922 *
2923 * You may also add user parameters for your propagator, see the method SCIPincludePropPseudoobj() in
2924 * src/scip/prop_pseudoobj.c for an example.
2925 *
2926 *
2927 * @section PROP_FUNDAMENTALCALLBACKS Fundamental Callback Methods of a Propagator
2928 *
2929 * The fundamental callback methods of the plugins are the ones that have to be implemented in order to obtain
2930 * an operational algorithm.
2931 * They are passed together with the propagator itself to SCIP using SCIPincludeProp() or SCIPincludePropBasic(),
2932 * see @ref PROP_INTERFACE.
2933 *
2934 * Propagator plugins have one fundamental callback method, namely the \ref PROPEXEC method
2935 * method. This method has to be implemented for every propagator; the other callback methods are optional. In the
2936 * C++ wrapper class scip::ObjProp, the scip_exec() method (which corresponds to the \ref PROPEXEC
2937 * callback) is a virtual abstract member function. You have to
2938 * implement it in order to be able to construct an object of your propagator class.
2939 *
2940 * Additional documentation for the callback methods can be found in type_prop.h.
2941 *
2942 * @subsection PROPEXEC
2943 *
2944 * The PROPEXEC callback is called during presolving and during the subproblem processing. It should perform the actual
2945 * domain propagation, which means that it should tighten the variables' bounds. The technique of domain propagation,
2946 * which is the main workhorse of constraint programming, is called "node preprocessing" in the Integer Programming
2947 * community.
2948 *
2949 * The PROPEXEC callback has the following options:
2950 * - detecting that the node is infeasible in the variables' bounds and can be cut off (result SCIP_CUTOFF)
2951 * - reducing (i.e, tightening) the domains of some variables (result SCIP_REDUCEDDOM)
2952 * - stating that the propagator searched, but did not find domain reductions, cutting planes, or cut constraints
2953 * (result SCIP_DIDNOTFIND)
2954 * - stating that the propagator was skipped (result SCIP_DIDNOTRUN)
2955 * - stating that the propagator was skipped, but should be called again (result SCIP_DELAYED)
2956 *
2957 *
2958 *
2959 * @section PROP_ADDITIONALCALLBACKS Additional Callback Methods of a Propagator
2960 *
2961 * The additional callback methods do not need to be implemented in every case. However, some of them have to be
2962 * implemented for most applications, they can be used, for example, to initialize and free private data.
2963 * Additional callbacks can either be passed directly with SCIPincludeProp() to SCIP or via specific
2964 * <b>setter functions</b> after a call of SCIPincludePropBasic(), see also @ref PROP_INTERFACE.
2965 *
2966 * @subsection PROPRESPROP
2967 *
2968 * If the propagator wants to support \ref CONF "conflict analysis", it has to supply the PROPRESPROP method. It also should call
2969 * SCIPinferVarLbProp() or SCIPinferVarUbProp() in the domain propagation instead of SCIPchgVarLb() or SCIPchgVarUb() in
2970 * order to deduce bound changes on variables. In the SCIPinferVarLbProp() and SCIPinferVarUbProp() calls, the
2971 * propagator provides a pointer to itself and an integer value "inferinfo" that can be arbitrarily chosen.
2972 *
2973 * The propagation conflict resolving method PROPRESPROP must then be implemented to provide the "reasons" for the bound
2974 * changes, i.e., the bounds of variables at the time of the propagation, which forced the propagator to set the
2975 * conflict variable's bound to its current value. It can use the "inferinfo" tag to identify its own propagation rule
2976 * and thus identify the "reason" bounds. The bounds that form the reason of the assignment must then be provided by
2977 * calls to SCIPaddConflictLb() and SCIPaddConflictUb() in the propagation conflict resolving method.
2978 *
2979 * See the description of the propagation conflict resolving method \ref CONSRESPROP of constraint handlers for
2980 * further details.
2981 *
2982 * Omitting the PROPRESPROP callback circumvents the implementation of the usually rather complex conflict resolving method.
2983 * Yet, it
2984 * will make the conflict analysis less effective. We suggest to first omit the conflict resolving method and check how
2985 * effective the propagation method is. If it produces a lot of propagations for your application, you definitely should
2986 * consider implementing the conflict resolving method.
2987 *
2988 *
2989 * @subsection PROPFREE
2990 *
2991 * If you are using propagator data, you have to implement this method in order to free the propagator data.
2992 * This can be done by the following procedure:
2993 *
2994 * @refsnippet{src/scip/prop_redcost.c,SnippetPropFreeRedcost}
2995 *
2996 * If you have allocated memory for fields in your propagator data, remember to free this memory
2997 * before freeing the propagator data itself.
2998 * If you are using the C++ wrapper class, this method is not available.
2999 * Instead, just use the destructor of your class to free the member variables of your class.
3000 *
3001 * @subsection PROPINIT
3002 *
3003 * The PROPINIT callback is executed after the problem is transformed. The propagator may, e.g., use this call to
3004 * initialize its propagator data.
3005 *
3006 * @subsection PROPCOPY
3007 *
3008 * The PROPCOPY callback is executed when a SCIP instance is copied, e.g. to
3009 * solve a sub-SCIP. By
3010 * defining this callback as
3011 * <code>NULL</code> the user disables the execution of the specified
3012 * propagator for all copied SCIP instances. This may deteriorate the performance
3013 * of primal heuristics using sub-SCIPs.
3014 *
3015 * @subsection PROPEXIT
3016 *
3017 * The PROPEXIT callback is executed before the transformed problem is freed.
3018 * In this method, the propagator should free all resources that have been allocated for the solving process in PROPINIT.
3019 *
3020 * @subsection PROPINITPRE
3021 *
3022 * The PROPINITPRE callback is executed before the preprocessing is started, even if presolving is turned off.
3023 * The propagator may use this call to initialize its presolving data before the presolving process begins.
3024 *
3025 * @subsection PROPEXITPRE
3026 *
3027 * The PROPEXITPRE callback is executed after the preprocessing has been finished, even if presolving is turned off.
3028 * The propagator may use this call, e.g., to clean up its presolving data.
3029 * Besides clean up, no time consuming operations should be done.
3030 *
3031 * @subsection PROPINITSOL
3032 *
3033 * The PROPINITSOL callback is executed when the presolving is finished and the branch-and-bound process is about to
3034 * begin.
3035 * The propagator may use this call to initialize its branch-and-bound specific data.
3036 *
3037 * @subsection PROPEXITSOL
3038 *
3039 * The PROPEXITSOL callback is executed before the branch-and-bound process is freed.
3040 * The propagator should use this call to clean up its branch-and-bound data.
3041 *
3042 * @subsection PROPPRESOL
3043 *
3044 * Seaches for domain propagations, analogous to the \ref PROPEXEC callback.
3045 * However, this callback is called during preprocessing.
3046 *
3047 * To inform SCIP that the presolving method found a reduction the result pointer has to be set in a proper way.
3048 * The following options are possible:
3049 *
3050 * - SCIP_UNBOUNDED : at least one variable is not bounded by any constraint in objective direction
3051 * - SCIP_CUTOFF : at least one domain reduction that renders the problem infeasible has been found
3052 * - SCIP_SUCCESS : the presolver found a domain reduction
3053 * - SCIP_DIDNOTFIND : the presolver searched, but did not find a presolving change
3054 * - SCIP_DIDNOTRUN : the presolver was skipped
3055 * - SCIP_DELAYED : the presolver was skipped, but should be called again
3056 *
3057 *
3058 * Please see also the @ref PROP_ADDITIONALPROPERTIES section to learn about the properties
3059 * PROP_PRESOLTIMING and PROP_PRESOL_MAXROUNDS, which influence the behaviour of SCIP
3060 * calling PROPPRESOL.
3061 *
3062 */
3063
3064/*--+----1----+----2----+----3----+----4----+----5----+----6----+----7----+----8----+----9----+----0----+----1----+----2*/
3065
3066/**@page BRANCH How to add branching rules
3067 *
3068 * Branching rules are used to split the problem at the current node into smaller subproblems. Branching rules can be called at three
3069 * different occasions, which is why they have three different execution methods (see \ref
3070 * BRANCHRULE_ADDITIONALCALLBACKS). Branching is performed if:
3071 * - the LP solution of the current problem is fractional. In this case, the integrality constraint handler calls the
3072 * \ref BRANCHEXECLP methods of the branching rules.
3073 * - the list of external branching candidates is not empty. This will only be the case if branching candidates were added
3074 * by a user's \ref RELAX "relaxation handler" or \ref CONS "constraint handler" plugin, calling SCIPaddExternBranchCand().
3075 * These branching candidates should be processed by the \ref BRANCHEXECEXT method.
3076 * - if an integral solution violates one or more constraints and this infeasibility could not be resolved in the callback methods
3077 * \ref CONSENFOLP and \ref CONSENFOPS of the corresponding constraint handlers. In this case, the \ref BRANCHEXECPS method will be called. This is the
3078 * standard case, if you use SCIP as a pure CP or SAT solver. If the LP or any other type of relaxation is used, then
3079 * branching on pseudo solutions works as a last resort.
3080 *
3081 * The idea of branching rules is to take a global view on the problem. In contrast, branching paradigms which are
3082 * specific to one type of constraint are best implemented within the enforcement callbacks of your constraint handler.
3083 * See, e.g., the constraint specific branching rules provided by the constraint handlers for special ordered sets
3084 * (src/scip/cons_sos{1,2}.c)).
3085 * \n
3086 * All branching rules that come with the default distribution of SCIP create two subproblems by splitting a single
3087 * variable's domain. It is, however, fully supported to implement much more general branching schemes, for example by
3088 * creating more than two subproblems, or by adding additional constraints to the subproblems instead of tightening the
3089 * domains of the variables.
3090 * \n
3091 * A complete list of all branching rules contained in this release can be found \ref BRANCHINGRULES "here".
3092 * However, note that constraint handlers can implement their own branching when enforcing constraints.
3093 * In particular the handler for nonlinear constraints currently does not use the branching plugins for spatial branching
3094 * by default. Its behavior can be adjusted with the parameters in category constraints/nonlinear/branching.
3095 *
3096 * We now explain how users can add their own branching rules. Take the most infeasible LP branching rule
3097 * (src/scip/branch_mostinf.c) as an example. As all other default plugins, it is written in C. C++ users can easily
3098 * adapt the code by using the scip::ObjBranchrule wrapper base class and implement the scip_...() virtual methods instead of
3099 * the SCIP_DECL_BRANCH... callback methods.
3100 *
3101 * Additional documentation for the callback methods of a branching rule can be found in the file type_branch.h.
3102 *
3103 * Here is what you have to do to implement a branching rule:
3104 * -# Copy the template files src/scip/branch_xyz.c and src/scip/branch_xyz.h into files named
3105 * "branch_mybranchingrule.c" and "branch_mybranchingrule.h".
3106 * \n
3107 * Make sure to adjust your build system such that these files are compiled and linked to your project. \n
3108 * If you are adding a new default plugin, this means updating the `src/CMakeLists.txt` and `Makefile` files in the SCIP distribution.
3109 * -# Use `SCIPincludeBranchruleMybranchingrule()` in order to include the branching rule into your SCIP instance,
3110 * e.g., in the main file of your project (see, e.g., src/cmain.c in the Binpacking example). \n
3111 * If you are adding a new default plugin, this include function must be added to `src/scipdefplugins.c`.
3112 * -# Open the new files with a text editor and replace all occurrences of "xyz" by "mybranchingrule".
3113 * -# Adjust the properties of the branching rule (see \ref BRANCHRULE_PROPERTIES).
3114 * -# Define the branching rule data (see \ref BRANCHRULE_DATA). This is optional.
3115 * -# Implement the interface methods (see \ref BRANCHRULE_INTERFACE).
3116 * -# Implement the fundamental callback methods (see \ref BRANCHRULE_FUNDAMENTALCALLBACKS).
3117 * -# Implement the additional callback methods (see \ref BRANCHRULE_ADDITIONALCALLBACKS). This is optional.
3118 *
3119 *
3120 * @section BRANCHRULE_PROPERTIES Properties of a Branching Rule
3121 *
3122 * At the top of the new file "branch_mybranchingrule.c" you can find the branching rule properties.
3123 * These are given as compiler defines.
3124 * In the C++ wrapper class, you have to provide the branching rule properties by calling the constructor
3125 * of the abstract base class scip::ObjBranchrule from within your constructor.
3126 * The properties you have to set have the following meaning:
3127 *
3128 * \par BRANCHRULE_NAME: the name of the branching rule.
3129 * This name is used in the interactive shell to address the branching rule.
3130 * Additionally, if you are searching for a branching rule with SCIPfindBranchrule(), this name is looked up.
3131 * Names have to be unique: no two branching rules may have the same name.
3132 *
3133 * \par BRANCHRULE_DESC: the description of the branching rule.
3134 * This string is printed as a description of the branching rule in the interactive shell.
3135 *
3136 * \par BRANCHRULE_PRIORITY: the default value for the priority of the branching rule.
3137 * In the subproblem processing, the branching rules are called in decreasing order of their priority until
3138 * one succeeded to branch. Since most branching rules are able to generate a branching in all situations,
3139 * only the rule of highest priority is used. In combination with the BRANCHRULE_MAXDEPTH and
3140 * BRANCHRULE_MAXBOUNDDIST settings, however, interesting strategies can be easily employed. For example,
3141 * the user can set the priority of the "full strong branching" strategy to the highest value and assign the
3142 * second highest value to the "reliable pseudo cost" rule. If (s)he also sets the maximal depth for the
3143 * "full strong branching" to 5, in the top 5 depth levels of the search tree the "full strong branching" is
3144 * applied, while in the deeper levels "reliable pseudo cost branching" is used.
3145 * \n
3146 * Note that the BRANCHRULE_PRIORITY property only specifies the default value of the priority. The user can
3147 * change this value arbitrarily.
3148 *
3149 * \par BRANCHRULE_MAXDEPTH: the default value for the maximal depth level of the branching rule.
3150 * This parameter denotes the maximal depth level in the branch-and-bound tree up to which the branching method of the
3151 * branching rule will be applied. Use -1 for no limit.
3152 * \n
3153 * Note that this property only specifies the default value. The user can change this value arbitrarily.
3154 *
3155 * \par BRANCHRULE_MAXBOUNDDIST: the default value for the maximal relative distance from current node's dual bound to primal bound compared to best node's dual bound for applying branching.
3156 * At the current branch-and-bound node, the relative distance from its dual bound (local dual bound)
3157 * to the primal bound compared to the best node's dual bound (global dual bound) is considered. The branching method of
3158 * the branching rule will only be applied at the node if this relative distance does not exceed BRANCHRULE_MAXBOUNDDIST.
3159 * \n
3160 * For example, if the global dual bound is 50 and the primal bound is 60, BRANCHRULE_MAXBOUNDDIST = 0.25 means that
3161 * branching is only applied if the current node's dual bound is in the first quarter of the interval [50,60], i.e., if it
3162 * is less than or equal to 52.5. In particular, the values 0.0 and 1.0 mean that the branching rule is applied at the
3163 * current best node only or at all nodes, respectively.
3164 * \n
3165 * Note that the BRANCHRULE_MAXBOUNDDIST property only specifies the default value of the maximal bound distance.
3166 * The user can change this value arbitrarily.
3167 *
3168 *
3169 * @section BRANCHRULE_DATA Branching Rule Data
3170 *
3171 * Below the header "Data structures" you can find a struct which is called "struct SCIP_BranchruleData".
3172 * In this data structure, you can store the data of your branching rule. For example, you should store the adjustable
3173 * parameters of the branching rule in this data structure.
3174 * If you are using C++, you can add branching rule data as usual as object variables to your class.
3175 * \n
3176 * Defining branching rule data is optional. You can leave the struct empty.
3177 *
3178 *
3179 * @section BRANCHRULE_INTERFACE Interface Methods
3180 *
3181 * At the bottom of "branch_mybranchingrule.c", you can find the interface method SCIPincludeBranchruleMybranchingrule(),
3182 * which also appears in "branch_mybranchingrule.h"
3183 * SCIPincludeBranchruleMybranchingrule() is called by the user, if (s)he wants to include the branching rule,
3184 * i.e., if (s)he wants to use the branching rule in his/her application.
3185 *
3186 * This method only has to be adjusted slightly.
3187 * It is responsible for notifying SCIP of the presence of the branching rule. For this, you can either call
3188 * SCIPincludeBranchrule(),
3189 * or SCIPincludeBranchruleBasic() since SCIP version 3.0. In the latter variant, \ref BRANCHRULE_ADDITIONALCALLBACKS "additional callbacks"
3190 * must be added via setter functions as, e.g., SCIPsetBranchruleCopy(). We recommend this latter variant because
3191 * it is more stable towards future SCIP versions which might have more callbacks, whereas source code using the first
3192 * variant must be manually adjusted with every SCIP release containing new callbacks for branchrule in order to compile.
3193 *
3194 *
3195 * If you are using branching rule data, you have to allocate the memory for the data at this point.
3196 * You can do this by calling:
3197 * \code
3198 * SCIP_CALL( SCIPallocBlockMemory(scip, &branchruledata) );
3199 * \endcode
3200 * You also have to initialize the fields in struct SCIP_BranchruleData afterwards.
3201 *
3202 * You may also add user parameters for your branching rule, see the method SCIPincludeBranchruleRelpscost() in
3203 * src/scip/branch_relpscost.c for an example.
3204 *
3205 *
3206 * @section BRANCHRULE_FUNDAMENTALCALLBACKS Fundamental Callback Methods of a Branching Rule
3207 *
3208 * Branching rules do not have any fundamental callback methods, i.e., all callback methods are optional.
3209 * In most cases, however, you want to implement the \ref BRANCHEXECLP method and sometimes the \ref BRANCHEXECPS method.
3210 *
3211 *
3212 * @section BRANCHRULE_ADDITIONALCALLBACKS Additional Callback Methods of a Branching Rule
3213 *
3214 * The additional callback methods do not need to be implemented in every case. However, some of them have to be
3215 * implemented for most applications, they can be used, for example, to initialize and free private data.
3216 * Additional callbacks can either be passed directly with SCIPincludeBranchrule() to SCIP or via specific
3217 * <b>setter functions</b> after a call of SCIPincludeBranchruleBasic(), see also @ref BRANCHRULE_INTERFACE.
3218 *
3219 * The most important callback methods are the \ref BRANCHEXECLP, \ref BRANCHEXECEXT,
3220 * and \ref BRANCHEXECPS methods, which perform the actual task of generating a branching.
3221 *
3222 * Additional documentation for the callback methods can be found in type_branch.h.
3223 *
3224 * @subsection BRANCHEXECLP
3225 *
3226 * The BRANCHEXECLP callback is executed during node processing if a fractional LP solution is available. It should
3227 * split the current problem into smaller subproblems. Usually, the branching is done in a way such that the current
3228 * fractional LP solution is no longer feasible in the relaxation of the subproblems. It is, however, possible to
3229 * create a child node for which the fractional LP solution is still feasible in the relaxation, for example, by
3230 * branching on a variable with integral LP value. In every case, you have to make sure that each subproblem is a
3231 * proper restriction of the current problem. Otherwise, you risk to produce an infinite path in the search tree.
3232 *
3233 * The user gains access to the branching candidates, i.e., to the fractional variables, and their LP solution values by
3234 * calling the method SCIPgetLPBranchCands(). Furthermore, SCIP provides two methods for performing the actual
3235 * branching, namely SCIPbranchVar() and SCIPcreateChild().
3236 *
3237 * Given an integral variable \f$x\f$ with fractional LP solution value \f$x^*\f$, the method SCIPbranchVar() creates
3238 * two child nodes; one contains the bound \f$x \le \lfloor x^* \rfloor\f$ and the other one contains the bound \f$x \ge
3239 * \lceil x^* \rceil\f$, see the BRANCHEXECLP callback in src/scip/branch_mostinf.c for an example. In addition, if a
3240 * proven lower objective bound of a created child node is known, like after strong branching has been applied, the user
3241 * may call the method SCIPupdateNodeLowerbound() in order to update the child node's lower bound.
3242 *
3243 * Please also see the \ref BRANCHEXEC "further information for the three execution methods".
3244 *
3245 * @subsection BRANCHEXECEXT
3246 *
3247 * The BRANCHEXECEXT callback is executed during node processing if no LP solution is available and the list of
3248 * external branching candidates is not empty. It should split the current problem into smaller subproblems. If you
3249 * do not use relaxation handlers or constraints handlers that provide external branching candidates, you do not need to
3250 * implement this callback.
3251 *
3252 * In contrast to the LP branching candidates and the pseudo branching candidates, the list of external branching
3253 * candidates will not be generated automatically. The user has to add all variables to the list by calling
3254 * SCIPaddExternBranchCand() for each of them. Usually, this will happen in the execution method of a relaxation handler or in the
3255 * enforcement methods of a constraint handler.
3256 *
3257 * The user gains access to these branching candidates by calling the method SCIPgetExternBranchCands(). Furthermore,
3258 * SCIP provides two methods for performing the actual branching with a given solution value, namely SCIPbranchVarVal()
3259 * and SCIPcreateChild(). SCIPbranchVarVal() allows users to specify the branching point for a variable in contrast to
3260 * SCIPbranchVar(), which will always use the current LP or pseudo solution.
3261 *
3262 * This paragraph contains additional information regarding how the method SCIPbranchVarVal() works. For external branching candidates,
3263 * there are three principle possibilities:
3264 * - Given a continuous variable \f$x\f$ with solution value \f$x^*\f$, the method SCIPbranchVarVal() creates
3265 * two child nodes; one contains the bound \f$x \le x^* \f$ and the other one contains the bound \f$x \ge x^* \f$.
3266 * - Given an integer variable \f$x\f$ with fractional solution value \f$x^*\f$, the method
3267 * SCIPbranchVarVal() creates two child nodes; one contains the bound \f$x \le \lfloor x^* \rfloor\f$ and the other
3268 * one contains the bound \f$x \ge \lceil x^* \rceil\f$.
3269 * - Given an integer variable \f$x\f$ with integral solution value \f$x^*\f$, the method SCIPbranchVarVal()
3270 * creates three child nodes; one contains the bound \f$x \le x^* -1\f$, one contains the bound \f$x \ge x^* +1\f$,
3271 * one contains the fixing \f$x = x^*\f$.
3272 *
3273 * See the BRANCHEXECEXT callback in src/scip/branch_random.c for an example. In addition, if a proven lower bound of a
3274 * created child node is known the user may call the method SCIPupdateNodeLowerbound() in order to update the child
3275 * node's lower bound.
3276 *
3277 * Please also see the \ref BRANCHEXEC "further information for the three execution methods".
3278 *
3279 * @subsection BRANCHEXECPS
3280 *
3281 * The BRANCHEXECPS callback is executed during node processing if no LP solution is available and at least one of the
3282 * integer variables is not yet fixed. It should split the current problem into smaller subproblems. PS stands for
3283 * pseudo solution which is the vector of all variables set to their locally best (w.r.t. the objective function)
3284 * bounds.
3285 *
3286 * The user gains access to the branching candidates, i.e., to the non-fixed integer variables, by calling the method
3287 * SCIPgetPseudoBranchCands(). Furthermore, SCIP provides two methods for performing the actual branching, namely
3288 * SCIPbranchVar() and SCIPcreateChild().
3289 *
3290 * Given an integer variable \f$x\f$ with bounds \f$[l,u]\f$ and not having solved the LP, the method SCIPbranchVar()
3291 * creates two child nodes:
3292 * - If both bounds are finite, then the two children will contain the domain reductions \f$x \le x^*\f$, and \f$x \ge
3293 * x^*+1\f$ with \f$x^* = \lfloor \frac{l + u}{2}\rfloor\f$. The current pseudo solution will remain feasible in one
3294 * of the branches, but the hope is that halving the domain's size leads to good propagations.
3295 * - If only one of the bounds is finite, the variable will be fixed to that bound in one of the child nodes. In the
3296 * other child node, the bound will be shifted by one.
3297 * - If both bounds are infinite, three children will be created: \f$x \le 1\f$, \f$x \ge 1\f$, and \f$x = 0\f$.
3298
3299 *
3300 * See the BRANCHEXECPS callback in src/scip/branch_random.c for an example. In addition, if a proven lower bound of a
3301 * created child node is known, the user may call the method SCIPupdateNodeLowerbound() in order to update the child
3302 * node's lower bound.
3303 *
3304 * Please also see the \ref BRANCHEXEC "further information for the three execution methods".
3305 *
3306 * @subsection BRANCHEXEC Further information for the three execution methods
3307 *
3308 * In order to apply more general branching schemes, one should use the method SCIPcreateChild().
3309 * After having created a child node, the additional restrictions of the child node have to be added with calls to
3310 * SCIPaddConsNode(), SCIPchgVarLbNode(), or SCIPchgVarUbNode().
3311 * \n
3312 * In the method SCIPcreateChild(), the branching rule has to assign two values to the new nodes: a node selection
3313 * priority for each node and an estimate for the objective value of the best feasible solution contained in the subtree
3314 * after applying the branching. If the method SCIPbranchVar() is used, these values are automatically assigned. For
3315 * variable based branching schemes, one might use the methods SCIPcalcNodeselPriority() and the method
3316 * SCIPcalcChildEstimate().
3317 *
3318 * In some cases, the branching rule can tighten the current subproblem instead of producing a branching. For example,
3319 * strong branching might have proven that rounding up a variable would lead to an infeasible LP relaxation and thus,
3320 * the variable must be rounded down. Therefore, the BRANCHEXECLP, BRANCHEXECPS and BRANCHEXECREL callbacks may also
3321 * produce domain reductions or add additional constraints to the current subproblem.
3322 *
3323 * The execution callbacks have the following options:
3324 * - detecting that the node is infeasible and can be cut off (result SCIP_CUTOFF)
3325 * - adding an additional constraint (e.g. a conflict constraint) (result SCIP_CONSADDED; note that this action
3326 * must not be performed if the input "allowaddcons" is FALSE)
3327 * - reducing the domain of a variable such that the current LP solution becomes infeasible (result SCIP_REDUCEDDOM)
3328 * - applying a branching (result SCIP_BRANCHED)
3329 * - stating that the branching rule was skipped (result SCIP_DIDNOTRUN).
3330 *
3331 * Only the BRANCHEXECLP callback has the possibility to add a cutting plane to the LP (result SCIP_SEPARATED).
3332 *
3333 * @subsection BRANCHFREE
3334 *
3335 * If you are using branching rule data, you have to implement this method in order to free the branching rule data.
3336 * This can be done by the following procedure:
3337 *
3338 * @refsnippet{src/scip/branch_random.c,SnippetBranchFreeRandom}
3339 *
3340 * If you have allocated memory for fields in your branching rule data, remember to free this memory
3341 * before freeing the branching rule data itself.
3342 * If you are using the C++ wrapper class, this method is not available.
3343 * Instead, just use the destructor of your class to free the member variables of your class.
3344 *
3345 * @subsection BRANCHINIT
3346 *
3347 * The BRANCHINIT callback is executed after the problem is transformed.
3348 * The branching rule may, e.g., use this call to initialize its branching rule data.
3349 *
3350 * @subsection BRANCHCOPY
3351 *
3352 * The BRANCHCOPY callback is executed when a SCIP instance is copied, e.g. to
3353 * solve a sub-SCIP. By
3354 * defining this callback as
3355 * <code>NULL</code> the user disables the execution of the specified
3356 * branching rule for all copied SCIP instances. This may deteriorate the performance
3357 * of primal heuristics using sub-SCIPs.
3358 *
3359 * @subsection BRANCHEXIT
3360 *
3361 * The BRANCHEXIT callback is executed before the transformed problem is freed.
3362 * In this method, the branching rule should free all resources that have been allocated for the solving process in
3363 * BRANCHINIT.
3364 *
3365 * @subsection BRANCHINITSOL
3366 *
3367 * The BRANCHINITSOL callback is executed when the presolving is finished and the branch-and-bound process is about to
3368 * begin.
3369 * The branching rule may use this call to initialize its branch-and-bound specific data.
3370 *
3371 * @subsection BRANCHEXITSOL
3372 *
3373 * The BRANCHEXITSOL callback is executed before the branch-and-bound process is freed.
3374 * The branching rule should use this call to clean up its branch-and-bound data.
3375 */
3376
3377
3378/*--+----1----+----2----+----3----+----4----+----5----+----6----+----7----+----8----+----9----+----0----+----1----+----2*/
3379
3380/**@page CUTSEL How to add cut selectors
3381 *
3382 * Cut selectors are used to select the cuts that are going to be added to the relaxation.
3383 * For more information on how SCIP manages cuts, see "What is the difference between a sepastore and the cutpool?" in the
3384 * \ref FAQ.
3385 * \n
3386 * A complete list of all cut selectors contained in this release can be found \ref CUTSELECTORS "here".
3387 *
3388 * We now explain how users can add their own cut selectors.
3389 * Take the hybrid cut selector (src/scip/cutsel_hybrid.c) as an example.
3390 * As all other default plugins, it is written in C. C++ users can easily adapt the code by using the scip::ObjCutsel wrapper
3391 * base class and implement the scip_...() virtual methods instead of the SCIP_DECL_CUTSEL... callback methods.
3392 *
3393 * Additional documentation for the callback methods of a cut selector can be found in the file type_cutsel.h.
3394 *
3395 * Here is what you have to do to implement a cut selector:
3396 * -# Copy the template files src/scip/cutsel_xyz.c and src/scip/cutsel_xyz.h into files named "cutsel_mycutselector.c"
3397 * and "cutsel_mycutselector.h".
3398 * \n
3399 * Make sure to adjust your build system such that these files are compiled and linked to your project. \n
3400 * If you are adding a new default plugin, this means updating the `src/CMakeLists.txt` and `Makefile` files in the SCIP distribution.
3401 * -# Use SCIPincludeCutselMycutselector() in order to include the cut selector into your SCIP instance,
3402 * e.g., in the main file of your project (see, e.g., src/cmain.c in the Binpacking example). \n
3403 * If you are adding a new default plugin, this include function must be added to `src/scipdefplugins.c`.
3404 * -# Open the new files with a text editor and replace all occurrences of "xyz" by "mycutselector".
3405 * -# Adjust the properties of the cut selector (see \ref CUTSEL_PROPERTIES).
3406 * -# Define the cut selector data (see \ref CUTSEL_DATA). This is optional.
3407 * -# Implement the interface methods (see \ref CUTSEL_INTERFACE).
3408 * -# Implement the fundamental callback methods (see \ref CUTSEL_FUNDAMENTALCALLBACKS).
3409 * -# Implement the additional callback methods (see \ref CUTSEL_ADDITIONALCALLBACKS). This is optional.
3410 *
3411 *
3412 * @section CUTSEL_PROPERTIES Properties of a Cut Selector
3413 *
3414 * At the top of the new file "cutsel_mycutselector.c" you can find the cut selector properties.
3415 * These are given as compiler defines.
3416 * In the C++ wrapper class, you have to provide the cut selector properties by calling the constructor
3417 * of the abstract base class scip::ObjCutsel from within your constructor.
3418 * The properties you have to set have the following meaning:
3419 *
3420 * \par CUTSEL_NAME: the name of the cut selector.
3421 * This name is used in the interactive shell to address the cut selector.
3422 * Additionally, if you are searching for a cut selector with SCIPfindCutsel(), this name is looked up.
3423 * Names have to be unique: no two cut selectors may have the same name.
3424 *
3425 * \par CUTSEL_DESC: the description of the cut selector.
3426 * This string is printed as a description of the cut selector in the interactive shell.
3427 *
3428 * \par CUTSEL_PRIORITY: the priority of the cut selector.
3429 * After all cuts have been collected in the sepastore, SCIP asks the cut selectors to select cuts.
3430 * The cut selectors are sorted by priority (highest goes first) and are called, in this order, until the first one
3431 * succeeds.
3432 * \n
3433 * Note that this property only defines the default value of the priority. The user may change this value arbitrarily by
3434 * adjusting the corresponding parameter setting. Whenever, even during solving, the priority of a cut selector is
3435 * changed, the cut selectors are resorted by the new priorities.
3436 *
3437 *
3438 * @section CUTSEL_DATA Cut Selector Data
3439 *
3440 * Below the header "Data structures" you can find a struct which is called "struct SCIP_CutselData".
3441 * In this data structure, you can store the data of your cut selector. For example, you should store the adjustable
3442 * parameters of the cut selector in this data structure.
3443 * If you are using C++, you can add cut selector data as usual as object variables to your class.
3444 * \n
3445 * Defining cut selector data is optional. You can leave the struct empty.
3446 *
3447 *
3448 * @section CUTSEL_INTERFACE Interface Methods
3449 *
3450 * At the bottom of "cutsel_mycutselector.c", you can find the interface method SCIPincludeCutselMycutselector(),
3451 * which also appears in "cutsel_mycutselector.h"
3452 * SCIPincludeCutselMycutselector() is called by the user, if they want to include the cut selector, i.e., if they want
3453 * to use the cut selector in their application.
3454 *
3455 * This method only has to be adjusted slightly.
3456 * It is responsible for notifying SCIP of the presence of the cut selector. For this, you can either call
3457 * SCIPincludeCutsel()
3458 * or SCIPincludeCutselBasic(). In the latter variant, \ref CUTSEL_ADDITIONALCALLBACKS "additional callbacks"
3459 * must be added via setter functions as, e.g., SCIPsetCutselCopy(). We recommend this latter variant because
3460 * it is more stable towards future SCIP versions which might have more callbacks, whereas source code using the first
3461 * variant must be manually adjusted with every SCIP release containing new callbacks for cut selectors in order to compile.
3462 *
3463 *
3464 * If you are using cut selector data, you have to allocate the memory for the data at this point.
3465 * You can do this by calling:
3466 * \code
3467 * SCIP_CALL( SCIPallocBlockMemory(scip, &cutseldata) );
3468 * \endcode
3469 * You also have to initialize the fields in struct SCIP_CutselData afterwards.
3470 *
3471 * You may also add user parameters for your cut selector, see the method SCIPincludeCutselHybrid() in
3472 * src/scip/cutsel_hybrid.c for an example.
3473 *
3474 *
3475 * @section CUTSEL_FUNDAMENTALCALLBACKS Fundamental Callback Methods of a Cut Selector
3476 *
3477 * The fundamental callback methods of the plugins are the ones that have to be implemented in order to obtain
3478 * an operational algorithm.
3479 * They are passed together with the cut selector itself to SCIP using SCIPincludeCutsel() or SCIPincludeCutselBasic(),
3480 * see @ref CUTSEL_INTERFACE.
3481 *
3482 * Cut selector plugins have a single fundamental callback method, namely the CUTSELSELECT method.
3483 * This method has to be implemented for every cut selector; the other callback methods are optional.
3484 * It implements the single contribution every selector has to provide: Selecting cuts to be added to the relaxation.
3485 * In the C++ wrapper class scip::ObjCutsel, the scip_select() method is a virtual abstract member function.
3486 * You have to implement it in order to be able to construct an object of your cut selector class.
3487 *
3488 * @subsection CUTSELSELECT
3489 *
3490 * The CUTSELSELECT callback should decide which cuts should be added to the relaxation.
3491 * The callback receives the arrays of cuts to select from. This array must be resorted and the first nselectedcuts from
3492 * the sorted array are going to be selected.
3493 * In addition to the aforementioned cuts, the list of forced cuts is also given as an argument. This array can be used
3494 * to help with the selection algorithm. Note, however, that this array should not be tampered with.
3495 *
3496 * Additional documentation for this callback can be found in type_cutsel.h.
3497 *
3498 * @section CUTSEL_ADDITIONALCALLBACKS Additional Callback Methods of a Cut Selector
3499 *
3500 * The additional callback methods do not need to be implemented in every case. However, some of them have to be
3501 * implemented for most applications. They can be used, for example, to initialize and free private data.
3502 * Additional callbacks can either be passed directly with SCIPincludeCutsel() to SCIP or via specific
3503 * <b>setter functions</b> after a call of SCIPincludeCutselBasic(), see also @ref CUTSEL_INTERFACE.
3504 *
3505 * @subsection CUTSELFREE
3506 *
3507 * If you are using cut selector data, you have to implement this method in order to free the cut selector data.
3508 * This can be done by the following procedure:
3509 *
3510 * @refsnippet{src/scip/cutsel_hybrid.c,SnippetCutselFreeHybrid}
3511 *
3512 * If you have allocated memory for fields in your cut selector data, remember to free this memory
3513 * before freeing the cut selector data itself.
3514 * If you are using the C++ wrapper class, this method is not available.
3515 * Instead, just use the destructor of your class to free the member variables of your class.
3516 *
3517 * @subsection CUTSELINIT
3518 *
3519 * The CUTSELINIT callback is executed after the problem is transformed.
3520 * The cut selector may, for example, use this call to initialize its cut selector data.
3521 *
3522 * @subsection CUTSELCOPY
3523 *
3524 * The CUTSELCOPY callback is executed when a SCIP instance is copied, e.g., to solve a sub-SCIP. By defining this
3525 * callback as <code>NULL</code> the user disables the execution of the specified cut selector for all copied SCIP
3526 * instances.
3527 *
3528 * @subsection CUTSELEXIT
3529 *
3530 * The CUTSELEXIT callback is executed before the transformed problem is freed.
3531 * In this method, the cut selector should free all resources that have been allocated for the solving process
3532 * in CUTSELINIT.
3533 *
3534 * @subsection CUTSELINITSOL
3535 *
3536 * The CUTSELINITSOL callback is executed when the presolving is finished and the branch-and-bound process is about to
3537 * begin.
3538 * The cut selector may use this call to initialize its branch-and-bound specific data.
3539 *
3540 * @subsection CUTSELEXITSOL
3541 *
3542 * The CUTSELEXITSOL callback is executed before the branch-and-bound process is freed.
3543 * The cut selector should use this call to clean up its branch-and-bound data.
3544 */
3545
3546/*--+----1----+----2----+----3----+----4----+----5----+----6----+----7----+----8----+----9----+----0----+----1----+----2*/
3547
3548/**@page NODESEL How to add node selectors
3549 *
3550 * Node selectors are used to decide which of the leaves in the current branching tree is selected as next subproblem
3551 * to be processed. The ordering relation of the tree's leaves for storing them in the leaf priority queue is also
3552 * defined by the node selectors.
3553 * \n
3554 * A complete list of all node selectors contained in this release can be found \ref NODESELECTORS "here".
3555 *
3556 * We now explain how users can add their own node selectors.
3557 * Take the node selector for depth first search (src/scip/nodesel_dfs.c) as an example.
3558 * As all other default plugins, it is written in C. C++ users can easily adapt the code by using the scip::ObjNodesel wrapper
3559 * base class and implement the scip_...() virtual methods instead of the SCIP_DECL_NODESEL... callback methods.
3560 *
3561 * Additional documentation for the callback methods of a node selector can be found in the file type_nodesel.h.
3562 *
3563 * Here is what you have to do to implement a node selector:
3564 * -# Copy the template files src/scip/nodesel_xyz.c and src/scip/nodesel_xyz.h into files named "nodesel_mynodeselector.c"
3565 * and "nodesel_mynodeselector.h".
3566 * \n
3567 * Make sure to adjust your build system such that these files are compiled and linked to your project. \n
3568 * If you are adding a new default plugin, this means updating the `src/CMakeLists.txt` and `Makefile` files in the SCIP distribution.
3569 * -# Use SCIPincludeNodeselMynodeselector() in order to include the node selector into your SCIP instance,
3570 * e.g., in the main file of your project (see, e.g., src/cmain.c in the Binpacking example). \n
3571 * If you are adding a new default plugin, this include function must be added to `src/scipdefplugins.c`.
3572 * -# Open the new files with a text editor and replace all occurrences of "xyz" by "mynodeselector".
3573 * -# Adjust the properties of the node selector (see \ref NODESEL_PROPERTIES).
3574 * -# Define the node selector data (see \ref NODESEL_DATA). This is optional.
3575 * -# Implement the interface methods (see \ref NODESEL_INTERFACE).
3576 * -# Implement the fundamental callback methods (see \ref NODESEL_FUNDAMENTALCALLBACKS).
3577 * -# Implement the additional callback methods (see \ref NODESEL_ADDITIONALCALLBACKS). This is optional.
3578 *
3579 *
3580 * @section NODESEL_PROPERTIES Properties of a Node Selector
3581 *
3582 * At the top of the new file "nodesel_mynodeselector.c" you can find the node selector properties.
3583 * These are given as compiler defines.
3584 * In the C++ wrapper class, you have to provide the node selector properties by calling the constructor
3585 * of the abstract base class scip::ObjNodesel from within your constructor.
3586 * The properties you have to set have the following meaning:
3587 *
3588 * \par NODESEL_NAME: the name of the node selector.
3589 * This name is used in the interactive shell to address the node selector.
3590 * Additionally, if you are searching for a node selector with SCIPfindNodesel(), this name is looked up.
3591 * Names have to be unique: no two node selectors may have the same name.
3592 *
3593 * \par NODESEL_DESC: the description of the node selector.
3594 * This string is printed as a description of the node selector in the interactive shell.
3595 *
3596 * \par NODESEL_STDPRIORITY: the default priority of the node selector in the standard mode.
3597 * The first step of each iteration of the main solving loop is the selection of the next subproblem to be processed.
3598 * The node selector of highest priority (the active node selector) is called to do this selection.
3599 * In particular, if you implemented your own node selector plugin which you want to be applied, you should choose a priority
3600 * which is greater then all priorities of the SCIP default node selectors.
3601 * Note that SCIP has two different operation modes: the standard mode and the memory saving mode. If the memory
3602 * limit - given as a parameter by the user - is almost reached, SCIP switches from the standard mode to the memory saving
3603 * mode in which different priorities for the node selectors are applied. NODESEL_STDPRIORITY is the priority of the
3604 * node selector used in the standard mode.
3605 * \n
3606 * Note that this property only defines the default value of the priority. The user may change this value arbitrarily by
3607 * adjusting the corresponding parameter setting.
3608 *
3609 * \par NODESEL_MEMSAVEPRIORITY: the default priority of the node selector in the memory saving mode.
3610 * The priority NODESEL_MEMSAVEPRIORITY of the node selector has the same meaning as the priority NODESEL_STDPRIORITY, but
3611 * is used in the memory saving mode.
3612 * Usually, you want the best performing node selector, for example best estimate search, to have maximal
3613 * standard priority, while you want a node selector which tends to keep the growth of the search tree limited, for example
3614 * depth first search, to have maximal memory saving priority.
3615 * \n
3616 * Note that this property only defines the default value of the priority. The user may change this value arbitrarily by
3617 * adjusting the corresponding parameter setting.
3618 *
3619 *
3620 * @section NODESEL_DATA Node Selector Data
3621 *
3622 * Below the header "Data structures" you can find a struct which is called "struct SCIP_NodeselData".
3623 * In this data structure, you can store the data of your node selector. For example, you should store the adjustable
3624 * parameters of the node selector in this data structure.
3625 * If you are using C++, you can add node selector data as usual as object variables to your class.
3626 * \n
3627 * Defining node selector data is optional. You can leave the struct empty.
3628 *
3629 *
3630 * @section NODESEL_INTERFACE Interface Methods
3631 *
3632 * At the bottom of "nodesel_mynodeselector.c", you can find the interface method SCIPincludeNodeselMynodeselector(),
3633 * which also appears in "nodesel_mynodeselector.h"
3634 * SCIPincludeNodeselMynodeselector() is called by the user, if (s)he wants to include the node selector,
3635 * i.e., if (s)he wants to use the node selector in his/her application.
3636 *
3637 * This method only has to be adjusted slightly.
3638 * It is responsible for notifying SCIP of the presence of the node selector. For this, you can either call
3639 * SCIPincludeNodesel(),
3640 * or SCIPincludeNodeselBasic() since SCIP version 3.0. In the latter variant, \ref NODESEL_ADDITIONALCALLBACKS "additional callbacks"
3641 * must be added via setter functions as, e.g., SCIPsetNodeselCopy(). We recommend this latter variant because
3642 * it is more stable towards future SCIP versions which might have more callbacks, whereas source code using the first
3643 * variant must be manually adjusted with every SCIP release containing new callbacks for node selectors in order to compile.
3644 *
3645 *
3646 * If you are using node selector data, you have to allocate the memory for the data at this point.
3647 * You can do this by calling:
3648 * \code
3649 * SCIP_CALL( SCIPallocBlockMemory(scip, &nodeseldata) );
3650 * \endcode
3651 * You also have to initialize the fields in struct SCIP_NodeselData afterwards.
3652 *
3653 * You may also add user parameters for your node selector, see the method SCIPincludeNodeselRestartdfs() in
3654 * src/scip/nodesel_restartdfs.c for an example.
3655 *
3656 *
3657 * @section NODESEL_FUNDAMENTALCALLBACKS Fundamental Callback Methods of a Node Selector
3658 *
3659 * The fundamental callback methods of the plugins are the ones that have to be implemented in order to obtain
3660 * an operational algorithm.
3661 * They are passed together with the node selector itself to SCIP using SCIPincludeNodesel() or SCIPincludeNodeselBasic(),
3662 * see @ref NODESEL_INTERFACE.
3663 *
3664 * Node selector plugins have two fundamental callback methods, namely the NODESELSELECT method and the NODESELCOMP method.
3665 * These methods have to be implemented for every node selector; the other callback methods are optional.
3666 * They implement the two requirements every node selector has to fulfill: Selecting a node from the queue to be processed
3667 * next and, given two nodes, deciding which of both is favored by the node selector's selection rule. The first
3668 * task is implemented in the NODESELSELECT callback, the second one in the NODESELCOMP callback.
3669 * In the C++ wrapper class scip::ObjNodesel, the scip_select() method and the scip_comp() method (which correspond to the
3670 * NODESELSELECT callback and the NODESELCOMP callback, respectively) are virtual abstract member functions.
3671 * You have to implement them in order to be able to construct an object of your node selector class.
3672 *
3673 * Additional documentation for the callback methods can be found in type_nodesel.h.
3674 *
3675 * @subsection NODESELSELECT
3676 *
3677 * The NODESELSELECT callback is the first method called in each iteration in the main solving loop. It should decide
3678 * which of the leaves in the current branching tree is selected as the next subproblem to be processed.
3679 * It can arbitrarily decide between all leaves stored in the tree, but for performance reasons,
3680 * the current node's children and siblings are often treated different from the remaining leaves.
3681 * This is mainly due to the warm start capabilities of the simplex algorithm and the expectation that the bases of
3682 * neighboring vertices in the branching tree very similar.
3683 * The node selector's choice of the next node to process can
3684 * have a large impact on the solver's performance, because it influences the finding of feasible solutions and the
3685 * development of the global dual bound.
3686 *
3687 * Besides the ranking of the node selector, every node gets assigned a node selection priority by the branching rule
3688 * that created the node. See the \ref BRANCHEXECLP and \ref BRANCHEXECPS callbacks of the branching rules for details.
3689 * For example, the node where the branching went in the same way as the deviation from the branching variable's
3690 * root solution could be assigned a higher priority than the node where the branching went in the opposite direction.
3691 *
3692 * The following methods provide access to the various types of leaf nodes:
3693 * - SCIPgetPrioChild() returns the child of the current node with the largest node selection priority, as assigned by the
3694 * branching rule.
3695 * If no child is available (for example, because the current node was pruned), a NULL pointer is returned.
3696 * - SCIPgetBestChild() returns the best child of the current node with respect to the node selector's ordering relation as
3697 * defined by the \ref NODESELCOMP callback. If no child is available, a NULL pointer is returned.
3698 * - SCIPgetPrioSibling() returns the sibling of the current node with the largest node selection priority.
3699 * If no sibling is available (for example, because all siblings of the current node have already been processed), a NULL
3700 * pointer is returned.
3701 * Note that in binary branching every node has at most one sibling, but since SCIP supports arbitrary branching rules,
3702 * this might not always be the case.
3703 * - SCIPgetBestSibling() returns the best sibling of the current node with respect to the node selector's ordering relation
3704 * as defined by the \ref NODESELCOMP callback. If no sibling is available, a NULL pointer is returned.
3705 * - SCIPgetBestNode() returns the best leaf from the tree (children, siblings, or other leaves) with respect to the node
3706 * selector's ordering relation as defined by the \ref NODESELCOMP callback. If no open leaf exists, a NULL pointer is
3707 * returned. In this case, the optimization is finished, and the node selector should return a NULL pointer as 'selnode'.
3708 * - SCIPgetBestboundNode() returns a leaf from the tree (children, siblings, or other leaves) with the smallest lower (dual)
3709 * objective bound. If the queue is empty, a NULL pointer is returned. In this case, the optimization is finished, and the
3710 * node selector should return a NULL pointer as 'selnode'.
3711 *
3712 *
3713 * @subsection NODESELCOMP
3714 *
3715 * The NODESELCOMP callback is called to compare two leaves of the current branching tree (say node 1 and node 2)
3716 * regarding their ordering relation.
3717 *
3718 * The NODESELCOMP should return the following values:
3719 * - value < 0, if node 1 comes before (is better than) node 2
3720 * - value = 0, if both nodes are equally good
3721 * - value > 0, if node 1 comes after (is worse than) node 2.
3722 *
3723 * @section NODESEL_ADDITIONALCALLBACKS Additional Callback Methods of a Node Selector
3724 *
3725 * The additional callback methods do not need to be implemented in every case. However, some of them have to be
3726 * implemented for most applications, they can be used, for example, to initialize and free private data.
3727 * Additional callbacks can either be passed directly with SCIPincludeNodesel() to SCIP or via specific
3728 * <b>setter functions</b> after a call of SCIPincludeNodeselBasic(), see also @ref NODESEL_INTERFACE.
3729 *
3730 * @subsection NODESELFREE
3731 *
3732 * If you are using node selector data, you have to implement this method in order to free the node selector data.
3733 * This can be done by the following procedure:
3734 *
3735 * @refsnippet{src/scip/nodesel_bfs.c,SnippetNodeselFreeBfs}
3736 *
3737 * If you have allocated memory for fields in your node selector data, remember to free this memory
3738 * before freeing the node selector data itself.
3739 * If you are using the C++ wrapper class, this method is not available.
3740 * Instead, just use the destructor of your class to free the member variables of your class.
3741 *
3742 * @subsection NODESELINIT
3743 *
3744 * The NODESELINIT callback is executed after the problem is transformed.
3745 * The node selector may, e.g., use this call to initialize its node selector data.
3746 *
3747 * @subsection NODESELCOPY
3748 *
3749 * The NODESELCOPY callback is executed when a SCIP instance is copied, e.g. to
3750 * solve a sub-SCIP. By
3751 * defining this callback as
3752 * <code>NULL</code> the user disables the execution of the specified
3753 * node selector for all copied SCIP instances. This may deteriorate the performance
3754 * of primal heuristics using sub-SCIPs.
3755 *
3756 * @subsection NODESELEXIT
3757 *
3758 * The NODESELEXIT callback is executed before the transformed problem is freed.
3759 * In this method, the node selector should free all resources that have been allocated for the solving process
3760 * in NODESELINIT.
3761 *
3762 * @subsection NODESELINITSOL
3763 *
3764 * The NODESELINITSOL callback is executed when the presolving is finished and the branch-and-bound process is about to
3765 * begin.
3766 * The node selector may use this call to initialize its branch-and-bound specific data.
3767 *
3768 * @subsection NODESELEXITSOL
3769 *
3770 * The NODESELEXITSOL callback is executed before the branch-and-bound process is freed.
3771 * The node selector should use this call to clean up its branch-and-bound data.
3772 */
3773
3774
3775/*--+----1----+----2----+----3----+----4----+----5----+----6----+----7----+----8----+----9----+----0----+----1----+----2*/
3776
3777/**@page HEUR How to add primal heuristics
3778 *
3779 * Feasible solutions can be found in two different ways during the traversal of the branch-and-bound tree. On one
3780 * hand, the solution of a node's relaxation may be feasible with respect to the constraints (including the integrality).
3781 * On the other hand, feasible solutions can be discovered by primal heuristics.
3782 * \n
3783 * A complete list of all primal heuristics contained in this release can be found \ref PRIMALHEURISTICS "here".
3784 * \n
3785 * Diving heuristics are primal heuristics that explore an auxiliary search tree in a depth-first manner. Since SCIP
3786 * version 3.2, it is easy to integrate further diving heuristics by using a special controller for the scoring,
3787 * see \ref DIVINGHEUR "here" for information on how to implement a diving heuristic.
3788 * \n
3789 * We now explain how users can add their own primal heuristics.
3790 * Take the simple and fast LP rounding heuristic (src/scip/heur_simplerounding.c) as an example.
3791 * The idea of simple rounding is to iterate over all fractional variables of an LP solution and round them down,
3792 * if the variables appears only with nonnegative coefficients in the system Ax <= b and round them up if
3793 * the variables appears only with nonpositive coefficients.
3794 * If one of both conditions applies for each of the fractional variables, this will give a feasible solution.
3795 * As all other default plugins, it is written in C. C++ users can easily adapt the code by using the scip::ObjHeur wrapper
3796 * base class and implement the scip_...() virtual methods instead of the SCIP_DECL_HEUR... callback methods.
3797 *
3798 * Additional documentation for the callback methods of a primal heuristic can be found in the file type_heur.h.
3799 *
3800 * Here is what you have to do to implement a primal heuristic:
3801 * -# Copy the template files src/scip/heur_xyz.c and src/scip/heur_xyz.h into files named "heur_myheuristic.c"
3802 * and "heur_myheuristic.h".
3803 * \n
3804 * Make sure to adjust your build system such that these files are compiled and linked to your project. \n
3805 * If you are adding a new default plugin, this means updating the `src/CMakeLists.txt` and `Makefile` files in the SCIP distribution.
3806 * -# Use `SCIPincludeHeurMyheuristic()` in order to include the heuristic into your SCIP instance,
3807 * e.g., in the main file of your project (see, e.g., src/cmain.c in the Binpacking example). \n
3808 * If you are adding a new default plugin, this include function must be added to `src/scipdefplugins.c`.
3809 * -# Open the new files with a text editor and replace all occurrences of "xyz" by "myheuristic".
3810 * -# Adjust the properties of the primal heuristic (see \ref HEUR_PROPERTIES).
3811 * -# Define the primal heuristic data (see \ref HEUR_DATA). This is optional.
3812 * -# Implement the interface methods (see \ref HEUR_INTERFACE).
3813 * -# Implement the fundamental callback methods (see \ref HEUR_FUNDAMENTALCALLBACKS).
3814 * -# Implement the additional callback methods (see \ref HEUR_ADDITIONALCALLBACKS). This is optional.
3815 *
3816 *
3817 * @section HEUR_PROPERTIES Properties of a Primal Heuristic
3818 *
3819 * At the top of the new file "heur_myheuristic.c" you can find the primal heuristic properties.
3820 * These are given as compiler defines.
3821 * In the C++ wrapper class, you have to provide the primal heuristic properties by calling the constructor
3822 * of the abstract base class scip::ObjHeur from within your constructor.
3823 * Of course, all of them are of relevant, but the most important ones for controlling the performance
3824 * are usually HEUR_FREQ and HEUR_TIMING.
3825 * The properties you have to set have the following meaning:
3826 *
3827 * \par HEUR_NAME: the name of the primal heuristic.
3828 * This name is used in the interactive shell to address the primal heuristic.
3829 * Additionally, if you are searching for a primal heuristic with SCIPfindHeur(), this name is looked up.
3830 * Names have to be unique: no two primal heuristics may have the same name.
3831 *
3832 * \par HEUR_DESC: the description of the primal heuristic.
3833 * This string is printed as a description of the primal heuristic in the interactive shell when you call "display heuristics".
3834 *
3835 * \par HEUR_DISPCHAR: the display character of the primal heuristic.
3836 * In the interactive shell, this character is printed in the first column of a status information row, if the primal
3837 * heuristic found the feasible solution belonging to the primal bound. Note that a star '*' stands for an integral
3838 * LP-relaxation.
3839 * It is recommended to select a lower or upper case letter as display character. The default primal heuristics of
3840 * SCIP use characters that describe the class to which the heuristic belongs. As an example all LP rounding heuristics
3841 * have an 'r' and all Large Neighborhood Search heuristics use the letter 'L'.
3842 * Users find commonly used display characters in type_heur.h.
3843 *
3844 *
3845 * \par HEUR_PRIORITY: the priority of the primal heuristic.
3846 * At each of the different entry points of the primal heuristics during the solving process (see HEUR_TIMING), they are
3847 * called in decreasing order of their priority.
3848 * \n
3849 * The priority of a primal heuristic should be set according to the complexity of the heuristic and the likelihood to find
3850 * feasible solutions: primal heuristics that provide fast algorithms that often succeed in finding a feasible solution should have
3851 * a high priority (like simple rounding). In addition, the interaction between different types of primal heuristics should be taken into account.
3852 * For example, improvement heuristics, which try to generate improved solutions by inspecting one or more of the feasible
3853 * solutions that have already been found, should have a low priority (like Crossover which by default needs at least 3 feasible solutions).
3854 *
3855 * \par HEUR_FREQ: the default frequency for executing the primal heuristic.
3856 * The frequency together with the frequency offset (see HEUR_FREQOFS) defines the depth levels at which the execution
3857 * method of the primal heuristic \ref HEUREXEC is called. For example, a frequency of 7 together with a frequency offset
3858 * of 5 means, that the \ref HEUREXEC callback is executed for subproblems that are in depth 5, 12, 19, ... of the branching tree. A
3859 * frequency of 0 together with a frequency offset of 3 means, that the execution method is only called at those nodes that are in
3860 * depth level 3 (i.e., at most for \f$2^3 = 8\f$ nodes if binary branching is applied).
3861 * Typical cases are: A frequency of 0 and an offset of 0 which means that
3862 * the heuristic is only called at the root node and a frequency of -1 which disables the heuristic.
3863 * \n
3864 * The frequency can be adjusted by the user. This property of the primal heuristic only defines the default value of the
3865 * frequency. If you want to have a more flexible control of when to execute the primal heuristic, you have to assign
3866 * a frequency of 1 and implement a check at the beginning of your execution method whether you really want to search for feasible
3867 * solutions or not. If you do not want to execute the method, set the result code to SCIP_DIDNOTRUN.
3868 *
3869 * \par HEUR_FREQOFS: the frequency offset for executing the primal heuristic.
3870 * The frequency offset defines the depth of the branching tree at which the primal heuristic is executed for the first
3871 * time. For example, a frequency of 7 (see HEUR_FREQ) together with a frequency offset of 10 means, that the
3872 * callback is executed for subproblems that are in depth 10, 17, 24, ... of the branching tree. In particular, assigning
3873 * different offset values to heuristics of the same type, like diving heuristics, can be useful for evenly spreading the
3874 * application of these heuristics across the branch-and-bound tree.
3875 * Note that if the frequency is equal to 1, the heuristic is applied for all nodes with depth level larger or equal to
3876 * the frequency offset.
3877 *
3878 * \par HEUR_MAXDEPTH: the maximal depth level for executing the primal heuristic.
3879 * This parameter denotes the maximal depth level in the branching tree up to which the execution method of the primal
3880 * heuristic is called. Use -1 for no limit (a usual case).
3881 *
3882 * \par HEUR_TIMING: the execution timing of the primal heuristic.
3883 * Primal heuristics have different entry points during the solving process and the execution timing parameter defines the
3884 * entry point at which the primal heuristic is executed first.
3885 * \n
3886 * The primal heuristic can be called first:
3887 * - before the processing of the node starts (SCIP_HEURTIMING_BEFORENODE)
3888 * - after each LP solve during the cut-and-price loop (SCIP_HEURTIMING_DURINGLPLOOP)
3889 * - after the cut-and-price loop was finished (SCIP_HEURTIMING_AFTERLPLOOP)
3890 * - after the processing of a node <em>with solved LP</em> was finished (SCIP_HEURTIMING_AFTERLPNODE)
3891 * - after the processing of a node <em>without solved LP</em> was finished (SCIP_HEURTIMING_AFTERPSEUDONODE)
3892 * - after the processing of the last node in the current plunge was finished, <em>and only if the LP was solved for
3893 * this node</em> (SCIP_HEURTIMING_AFTERLPPLUNGE)
3894 * - after the processing of the last node in the current plunge was finished, <em>and only if the LP was not solved
3895 * for this node</em> (SCIP_HEURTIMING_AFTERPSEUDOPLUNGE).
3896 * \par
3897 * A plunge is the successive solving of child and sibling nodes in the search tree.
3898 * The flags listed above can be combined to call the heuristic at multiple times by concatenating them with a bitwise OR.
3899 * Two useful combinations are already predefined:
3900 * - after the processing of a node was finished (SCIP_HEURTIMING_AFTERNODE; combines SCIP_HEURTIMING_AFTERLPNODE and
3901 * SCIP_HEURTIMING_AFTERPSEUDONODE)
3902 * - after the processing of the last node in the current plunge was finished (SCIP_HEURTIMING_AFTERPLUNGE; combines
3903 * SCIP_HEURTIMING_AFTERLPPLUNGE and SCIP_HEURTIMING_AFTERPSEUDOPLUNGE)
3904 * \par
3905 * Calling a primal heuristic "before the processing of the node starts" is particularly useful for heuristics
3906 * that do not need to access the LP solution of the current node. If such a heuristic finds a feasible solution, the
3907 * leaves of the branching tree exceeding the new primal bound are pruned. It may happen that even the current node can
3908 * be cut off without solving the LP relaxation. Combinatorial heuristics, like the farthest insert heuristic for the TSP
3909 * (see examples/TSP/src/HeurFarthestInsert.cpp), are often applicable at this point.
3910 * \n
3911 * Very fast primal heuristics that require an LP solution can also be called "after each LP solve during the
3912 * cut-and-price loop". Rounding heuristics, like the simple and fast LP rounding heuristic
3913 * (src/scip/heur_simplerounding.c), belong to this group of primal heuristics.
3914 * \n
3915 * Most heuristics, however, are called either after a node was completely processed
3916 * (e.g. expensive rounding heuristics like RENS), or even only after a full plunge was finished (e.g., diving heuristics).
3917 *
3918 * \par HEUR_USESSUBSCIP: Does the heuristic use a secondary SCIP instance?
3919 * Some heuristics and separators solve MIPs or SAT problems using a secondary SCIP instance. Examples are
3920 * Large Neighborhood Search heuristics such as RINS and Local Branching or the CGMIP separator. To avoid recursion,
3921 * these plugins usually deactivate all other plugins that solve MIPs. If a heuristic uses a secondary SCIP instance,
3922 * this parameter has to be TRUE and it is recommended to call SCIPsetSubscipsOff() for the secondary SCIP instance.
3923 *
3924 * Computational experiments indicate that for the overall performance of a MIP solver, it is important to evenly
3925 * spread the application of the heuristics across the branch-and-bound tree. Thus, the assignment of the parameters
3926 * HEUR_FREQ, HEUR_FREQOFS, and HEUR_TIMING should contribute to this aim.
3927 *
3928 * Note that all diving heuristics in the SCIP distribution (see, e.g., src/scip/heur_guideddiving.c) check whether other diving
3929 * heuristics have already been called at the current node. This can be done by comparing SCIPgetLastDivenode(scip) and
3930 * SCIPgetNNodes(scip). If the two are equal, and if the current node is not the root node (SCIPgetDepth(scip) > 0), diving
3931 * heuristics should be delayed by returning the result code 'SCIP_DELAYED'. This is an additional contribution to the goal of
3932 * not calling multiple similar heuristics at the same node.
3933 *
3934 *
3935 * @section HEUR_DATA Primal Heuristic Data
3936 *
3937 * Below the header "Data structures" you can find a struct which is called "struct SCIP_HeurData".
3938 * In this data structure, you can store the data of your primal heuristic. For example, you should store the adjustable
3939 * parameters of the primal heuristic or a working solution in this data structure.
3940 * If you are using C++, you can add primal heuristic data as usual as object variables to your class.
3941 * \n
3942 * Defining primal heuristic data is optional. You can leave the struct empty.
3943 *
3944 *
3945 * @section HEUR_INTERFACE Interface Methods
3946 *
3947 * At the bottom of "heur_myheuristic.c", you can find the interface method SCIPincludeHeurMyheuristic(),
3948 * which also appears in "heur_myheuristic.h"
3949 * SCIPincludeHeurMyheuristic() is called by the user, if (s)he wants to include the heuristic,
3950 * i.e., if (s)he wants to use the heuristic in his/her application.
3951 *
3952 * This method only has to be adjusted slightly.
3953 * It is responsible for notifying SCIP of the presence of the heuristic. For this, you can either call
3954 * SCIPincludeHeur(),
3955 * or SCIPincludeHeurBasic() since SCIP version 3.0. In the latter variant, \ref HEUR_ADDITIONALCALLBACKS "additional callbacks"
3956 * must be added via setter functions as, e.g., SCIPsetHeurCopy(). We recommend this latter variant because
3957 * it is more stable towards future SCIP versions which might have more callbacks, whereas source code using the first
3958 * variant must be manually adjusted with every SCIP release containing new callbacks for heuristics in order to compile.
3959 *
3960 * If you are using primal heuristic data, you have to allocate the memory for the data at this point.
3961 * You can do this by calling:
3962 * \code
3963 * SCIP_CALL( SCIPallocBlockMemory(scip, &heurdata) );
3964 * \endcode
3965 * You also have to initialize the fields in struct SCIP_HeurData afterwards.
3966 *
3967 * You may also add user parameters for your primal heuristic, see the method SCIPincludeHeurFeaspump() in
3968 * src/scip/heur_oneopt.c for an example where a single Boolean parameter is added.
3969 *
3970 *
3971 * @section HEUR_FUNDAMENTALCALLBACKS Fundamental Callback Methods of a Primal Heuristic
3972 *
3973 * The fundamental callback methods of the plugins are the ones that have to be implemented in order to obtain
3974 * an operational algorithm.
3975 * They are passed together with the primal heuristic itself to SCIP using SCIPincludeHeur() or SCIPincludeHeurBasic(),
3976 * see @ref HEUR_INTERFACE.
3977 *
3978 *
3979 * Primal heuristic plugins have only one fundamental callback method, namely the HEUREXEC method.
3980 * This method has to be implemented for every primal heuristic; the other callback methods are optional.
3981 * In the C++ wrapper class scip::ObjHeur, the scip_exec() method (which corresponds to the HEUREXEC callback) is a virtual
3982 * abstract member function. You have to implement it in order to be able to construct an object of your primal heuristic
3983 * class.
3984 *
3985 * Additional documentation for the callback methods can be found in type_heur.h.
3986 *
3987 * @subsection HEUREXEC
3988 *
3989 * The HEUREXEC callback is called at different positions during the node processing loop, see HEUR_TIMING. It should
3990 * search for feasible solutions and add them to the solution pool. For creating a new feasible solution, the
3991 * methods SCIPcreateSol() and SCIPsetSolVal() can be used. Afterwards, the solution can be added to the storage by
3992 * calling the method SCIPtrySolFree() (or SCIPtrySol() and SCIPfreeSol()).
3993 *
3994 * The HEUREXEC callback gets a SCIP pointer, a pointer to the heuristic itself, the current point in the
3995 * solve loop and a result pointer as input (see type_heur.h).
3996 *
3997 * The heuristic has to set the result pointer appropriately!
3998 * Therefore it has the following options:
3999 * - finding at least one feasible solution (result SCIP_FOUNDSOL)
4000 * - stating that the primal heuristic searched, but did not find a feasible solution (result SCIP_DIDNOTFIND)
4001 * - stating that the primal heuristic was skipped (result SCIP_DIDNOTRUN)
4002 * - stating that the primal heuristic was skipped, but should be called again (result SCIP_DELAYED).
4003 *
4004 *
4005 * @section HEUR_ADDITIONALCALLBACKS Additional Callback Methods of a Primal Heuristic
4006 *
4007 * The additional callback methods do not need to be implemented in every case. However, some of them have to be
4008 * implemented for most applications, they can be used, for example, to initialize and free private data.
4009 * Additional callbacks can either be passed directly with SCIPincludeHeur() to SCIP or via specific
4010 * <b>setter functions</b> after a call of SCIPincludeHeurBasic(), see also @ref HEUR_INTERFACE.
4011 *
4012 * @subsection HEURFREE
4013 *
4014 * If you are using primal heuristic data, you have to implement this method in order to free the primal heuristic data.
4015 * This can be done by the following procedure:
4016 *
4017 * @refsnippet{applications/Coloring/src/heur_init.c,SnippetHeurFreeInit}
4018 *
4019 * If you have allocated memory for fields in your primal heuristic data, remember to free this memory
4020 * before freeing the primal heuristic data itself.
4021 * If you are using the C++ wrapper class, this method is not available.
4022 * Instead, just use the destructor of your class to free the member variables of your class.
4023 *
4024 * @subsection HEURINIT
4025 *
4026 * The HEURINIT callback is executed after the problem is transformed.
4027 * The primal heuristic may, e.g., use this call to initialize its primal heuristic data.
4028 *
4029 * @subsection HEURCOPY
4030 *
4031 * The HEURCOPY callback is executed when a SCIP instance is copied, e.g. to
4032 * solve a sub-SCIP. By
4033 * defining this callback as
4034 * <code>NULL</code> the user disables the execution of the specified
4035 * heuristic for all copied SCIP instances. This may deteriorate the performance
4036 * of primal heuristics using sub-SCIPs.
4037 *
4038 * @subsection HEUREXIT
4039 *
4040 * The HEUREXIT callback is executed before the tDIVINGHEURransformed problem is freed.
4041 * In this method, the primal heuristic should free all resources that have been allocated for the solving process in
4042 * HEURINIT.
4043 *
4044 * @subsection HEURINITSOL
4045 *
4046 * The HEURINITSOL callback is executed when the presolving is finished and the branch-and-bound process is about to
4047 * begin. The primal heuristic may use this call to initialize its branch-and-bound specific data.
4048 *
4049 * @subsection HEUREXITSOL
4050 *
4051 * The HEUREXITSOL callback is executed before the branch-and-bound process is freed. The primal heuristic should use this
4052 * call to clean up its branch-and-bound data, which was allocated in HEURINITSOL.
4053 */
4054
4055/*--+----1----+----2----+----3----+----4----+----5----+----6----+----7----+----8----+----9----+----0----+----1----+----2*/
4056
4057/**@page EXPRHDLR How to add expression handlers
4058 *
4059 * Expression handlers define basic expression types and provide additional functionality to work with expressions,
4060 * e.g., differentiation, simplification, estimation, hashing, copying, printing, parsing.
4061 * A complete list of all expression handlers contained in this release can be found \ref EXPRHDLRS "here".
4062 * In addition to expression handlers, higher level nonlinear structures are handled by nonlinear handlers, see \ref NLHDLR.
4063 *
4064 * Here is what you have to do to implement an own expression handler:
4065 * -# Copy the template files `src/scip/expr_xyz.c` and `src/scip/expr_xyz.h` into files `expr_myfunc.c` and `expr_myfunc.h`, respectively. \n
4066 * Make sure to adjust your build system such that these files are compiled and linked to your project. \n
4067 * If you are adding a new default plugin, this means updating the `src/CMakeLists.txt` and `Makefile` files in the SCIP distribution.
4068 * -# Use `SCIPincludeExprhdlrMyfunc()` in order to include the expression handler into your SCIP instance,
4069 * e.g., in the main file of your project. \n
4070 * If you are adding a new default plugin, this include function must be added to `src/scipdefplugins.c`.
4071 * -# Open the new files with a text editor and replace all occurrences of "xyz" by "myfunc".
4072 * -# Adjust the properties of the expression handler (see \ref EXPRHDLR_PROPERTIES).
4073 * -# Define the expression handler data and expression data (see \ref EXPRHDLR_DATA). This is optional.
4074 * -# Implement the interface methods (see \ref EXPRHDLR_INTERFACE).
4075 * -# Implement the fundamental callback methods (see \ref EXPRHDLR_FUNDAMENTALCALLBACKS).
4076 * -# Implement the additional callback methods (see \ref EXPRHDLR_ADDITIONALCALLBACKS), where necessary.
4077 *
4078 * Additional documentation for the callback methods of an expression handler, in particular for the input parameters,
4079 * can be found in the file \ref type_expr.h.
4080 *
4081 * For a complete implementation of an expression handler, take the one for exponential expressions (src/scip/expr_exp.c) as an example.
4082 *
4083 * @section EXPRHDLR_PROPERTIES Properties of an Expression Handler
4084 *
4085 * At the top of the new file `expr_myfunc.c`, you can find the expression handler properties.
4086 * These are given as compiler defines.
4087 * The properties you have to set have the following meaning:
4088 *
4089 * \par EXPRHDLR_NAME: the name of the expression handler.
4090 * This name is used in the interactive shell to address the expression handler.
4091 * Additionally, if you or a parsing routine is searching for an expression handler with SCIPfindExprhdlr(), this name is looked up.
4092 * Names have to be unique: no two expression handlers may have the same name.
4093 *
4094 * \par EXPRHDLR_DESC: the description of the expression handler.
4095 * This string is printed as a description of the expression handler in the interactive shell.
4096 *
4097 * \par EXPRHDLR_PRECEDENCE: the precedence of the expression handler.
4098 * Precedence of the expression operation relative to other expressions when printing the expression.
4099 *
4100 * @section EXPRHDLR_DATA Expression Handler Data and Expression Data
4101 *
4102 * Below the header "Data structures" you can find structs called `struct SCIP_ExprhdlrData` and `struct SCIP_ExprData`.
4103 * In this first data structure, you can store the data of your expression handler.
4104 * For example, you should store the adjustable parameters of the expression handler in this data structure.
4105 * In the second data structure, you can store data that is unique to an expression.
4106 * For example, the pow expression handler stores the exponent in this data structure.
4107 * \n
4108 * Defining expression handler data and expression data is optional. You can leave these structs empty.
4109 *
4110 * @section EXPRHDLR_INTERFACE Interface Methods
4111 *
4112 * @subsection EXPRHDLR_INCLUDE SCIPincludeExprhdlrMyfunc()
4113 *
4114 * At the bottom of `expr_myfunc.c`, you can find the interface method `SCIPincludeExprhdlrMyfunc()`,
4115 * which also appears in `expr_myfunc.h`.
4116 * `SCIPincludeExprhdlrMyfunc()` is called by the user, if (s)he wants to include the expression handler,
4117 * i.e., if (s)he wants to use the expression handler in his/her application.
4118 *
4119 * This method is responsible for notifying SCIP of the presence of the expression handler.
4120 * For this, you must call SCIPincludeExprhdlr() from SCIPincludeExprhdlrMyfunc().
4121 * The function only expects the properties and fundamental callbacks of the expression handler as arguments.
4122 * \ref EXPRHDLR_ADDITIONALCALLBACKS "Additional callbacks" must be added via setter functions as, e.g., SCIPexprhdlrSetCopyFreeHdlr().
4123 *
4124 * If you are using expression handler data, you have to allocate the memory for the data at this point.
4125 * You can do this by calling:
4126 * \code
4127 * SCIP_CALL( SCIPallocBlockMemory(scip, &exprhdlrdata) );
4128 * \endcode
4129 * You also have to initialize the fields in `struct SCIP_ExprhdlrData` afterwards.
4130 * For freeing the expression handler data, see \ref EXPRFREEHDLR.
4131 *
4132 * You may also add user parameters for your expression handler, see \ref PARAM for how to add user parameters.
4133 *
4134 * For the logarithm expression handler, the include method is as follows:
4135 * @refsnippet{src/scip/expr_log.c,SnippetIncludeExprhdlrLog}
4136 *
4137 * @subsection EXPRHDLR_CREATEEXPR SCIPcreateExprMyfunc()
4138 *
4139 * Another interface method that can be found in `expr_myfunc.c` is `SCIPcreateExprMyfunc()`.
4140 * This method is called by the user, if (s)he wants to create an expression that is handled by this expression handler.
4141 * Typically, the creation function takes the operands of the expression (the children) as arguments.
4142 * `SCIPcreateExprMyfunc()` may further be extended to take parameters of an expression into account.
4143 * For example, SCIPcreateExprPow() receives the exponent as argument.
4144 *
4145 * In the implementation of `SCIPcreateExprMyfunc()`, the expression data shall be allocated and initialized, if the expression has data
4146 * (like the exponent of pow expressions).
4147 * Then the expression shall be created by a call to SCIPcreateExpr().
4148 * This function takes the expression handler, expression data, children, and ownercreate callback as arguments.
4149 * For freeing the expression data, see \ref EXPRFREEDATA.
4150 *
4151 * The `ownercreate` and `ownercreatedata` that are passed to `SCIPcreateExprMyfunc()` need to be passed on to SCIP.
4152 * The owner of the expression that is created uses these arguments to store additional data in an expression.
4153 * For most usecases, these arguments will be set to `NULL`.
4154 * However, if the \ref EXPRPARSE callback is implemented, then `SCIPcreateExprMyfunc()` may need to be called with a non-NULL value
4155 * for `ownercreate` and `ownercreatedata`.
4156 * This will be the case if, for example, the constraint handler for nonlinear constraint parses an expression.
4157 * The constraint handler will then own the expression and needs to store some data in the expression.
4158 *
4159 * For the product expression handler, the expression create function is as follows:
4160 * @refsnippet{src/scip/expr_product.c,SnippetCreateExprProduct}
4161 *
4162 *
4163 * @section EXPRHDLR_FUNDAMENTALCALLBACKS Fundamental Callback Methods of an Expression Handler
4164 *
4165 * The fundamental callback methods of the plugins are the ones that have to be implemented in order to obtain
4166 * an operational algorithm.
4167 * They are passed to SCIP when the expression handler is created and included in SCIP via SCIPincludeExprhdlr(),
4168 * see @ref EXPRHDLR_INTERFACE.
4169 *
4170 * Expression handlers have one fundamental callback, @ref EXPREVAL, that needs to be implemented.
4171 * However, expression handlers with stateful expressions (expressions that have data) need to implement also the
4172 * @ref EXPRCOPYDATA, @ref EXPRFREEDATA, and @ref EXPRCOMPARE callbacks.
4173 *
4174 * Additional documentation for the callback methods, in particular relating to their input parameters,
4175 * can be found in \ref type_expr.h.
4176 *
4177 * @subsection EXPREVAL
4178 *
4179 * The expression evaluation callback defines the mathematical operation that the expression handler represents.
4180 * Its purpose is to evaluate an expression by taking the values of its children (operands) into account.
4181 *
4182 * The children of the expression can be retrieved via SCIPexprGetChildren() and SCIPexprGetNChildren().
4183 * The value (a `SCIP_Real`) for each child can be retrieved via function SCIPexprGetEvalValue().
4184 * The value of the expression should be stored in the argument `val` that is passed to the callback.
4185 * For example, the evaluation in the expression handler for sum is doing the following:
4186 * @refsnippet{src/scip/expr_sum.c,SnippetExprEvalSum}
4187 *
4188 * When an expression cannot be evaluated w.r.t. the values of its children, such a domain error must be signaled
4189 * to SCIP by setting `*val` to `SCIP_INVALID`.
4190 * SCIP then aborts evaluation. It is thus not necessary to check in the evaluation callback whether any child
4191 * has value `SCIP_INVALID`.
4192 * For example, the evaluation in the expression handler for logarithm expressions is doing the following:
4193 * @refsnippet{src/scip/expr_log.c,SnippetExprEvalLog}
4194 *
4195 * The solution (`sol`) that is passed to EXPREVAL can usually be ignored.
4196 * It is used by the expression handler for variables to retrieve the value of a variable expression.
4197 *
4198 *
4199 * @section EXPRHDLR_ADDITIONALCALLBACKS Additional Callback Methods of an Expression Handler
4200 *
4201 * The additional callback methods do not need to be implemented in every case. However, some of them have to be
4202 * implemented for most applications; they can be used, for example, to initialize and free private data.
4203 * Additional callbacks can be passed via specific
4204 * <b>setter functions</b> after a call of SCIPincludeExprhdlr(), see also @ref EXPRHDLR_INCLUDE.
4205 *
4206 * @subsection EXPRCOPYHDLR
4207 *
4208 * This method should include the expression handler into a given SCIP instance.
4209 * It is usually called when a copy of SCIP is generated.
4210 *
4211 * By not implementing this callback, the expression handler will not be available in copied SCIP instances.
4212 * If a nonlinear constraint uses expressions of this type, it will not be possible to copy them.
4213 * This may deteriorate the performance of primal heuristics using sub-SCIPs.
4214 *
4215 * @subsection EXPRFREEHDLR
4216 *
4217 * If you are using expression handler data (see \ref EXPRHDLR_DATA and \ref EXPRHDLR_INCLUDE), you have to implement this method
4218 * in order to free the expression handler data.
4219 *
4220 * @subsection EXPRCOPYDATA
4221 *
4222 * This method is called when creating copies of an expression within
4223 * the same or between different SCIP instances. It is given the
4224 * source expression, whose data shall be copied, and expects that
4225 * the data for the target expression is returned. This data will then be used
4226 * to create a new expression.
4227 *
4228 * If expressions that are handled by this expression handler have no data,
4229 * then this callback can be omitted.
4230 *
4231 * @subsection EXPRFREEDATA
4232 *
4233 * This method is called when freeing an expression that has data.
4234 * It is given an expression and shall free its expression data.
4235 * It shall then call `SCIPexprSetData(expr, NULL)`.
4236 *
4237 * This callback must be implemented for expressions that have data.
4238 *
4239 * @subsection EXPRPRINT
4240 *
4241 * This callback is called when an expression is printed.
4242 * It is called while DFS-iterating over the expression at different stages, that is,
4243 * when the expression is visited the first time, before each child of the expression is visited,
4244 * after each child of the expression has been visited, and when the iterator leaves the expression
4245 * for its parent.
4246 * At the various stages, the expression may print a string.
4247 * The given precedence of the parent expression can be used to decide whether parenthesis need to be printed.
4248 *
4249 * For example, the pow expression prints `(f(x))^p` where `f(x)` is a print of the child of the pow expression and `p` is the exponent:
4250 * @refsnippet{src/scip/expr_pow.c,SnippetExprPrintPow}
4251 *
4252 * The pow expression handler does not yet take expression precedence into account to decide whether the parenthesis around `f(x)` can be omitted.
4253 * For the sum expression handler, this has been implemented:
4254 * @refsnippet{src/scip/expr_sum.c,SnippetExprPrintSum}
4255 *
4256 * If this callback is not implemented, the expression is printed as `<hdlrname>(<child1>, <child2>, ...)`.
4257 *
4258 * @subsection EXPRPARSE
4259 *
4260 * This callback is called when an expression is parsed from a string and an operator with the name of the expression handler is found.
4261 * The given string points to the beginning of the arguments of the expression, that is, the beginning of "..." in the string `myfunc(...)`.
4262 * The callback shall interpret "..." and create an expression, probably via `SCIPcreateExprMyfunc()`, and return this created expression
4263 * and the position of the last character in "..." to SCIP.
4264 * When creating an expression, the given `ownercreate` and `ownercreatedata` shall be passed on.
4265 *
4266 * The string "..." likely contains one or several other expressions that will be the children of the `myfunc` expression.
4267 * `SCIPparseExpr()` shall be used to parse these expressions.
4268 *
4269 * For an expression that takes only one argument and has no parameters, the parsing routine is straightforward.
4270 * For example:
4271 * @refsnippet{src/scip/expr_exp.c,SnippetExprParseExp}
4272 *
4273 * For an expression that has additional data, the parsing routine is slightly more complex.
4274 * For the signpower expression, this parses `signpower(<child>,<exponent>)`:
4275 * @refsnippet{src/scip/expr_pow.c,SnippetExprParseSignpower}
4276 *
4277 * If this callback is not implemented, the expression cannot be parsed.
4278 * For instance, `.cip` files with nonlinear constraints that use this expression cannot be read.
4279 *
4280 * @subsection EXPRCURVATURE
4281 *
4282 * This callback is called when an expression is checked for convexity or concavity.
4283 * It is important to note that the callback is given a desired curvature (convex, concave, or both (=linear))
4284 * and the callback is required to return whether the given expression has the desired curvature.
4285 * In addition, it can state conditions on the curvature of the children under which the desired curvature
4286 * can be achieved and it can take bounds on the children into account.
4287 * SCIPevalExprActivity() and SCIPexprGetActivity() shall be used to evaluate and get bounds on a child expression.
4288 *
4289 * The implementation in the absolute-value expression handler serves as an example:
4290 * @refsnippet{src/scip/expr_abs.c,SnippetExprCurvatureAbs}
4291 *
4292 * If this callback is not implemented, the expression is assumed to be indefinite.
4293 *
4294 * @subsection EXPRMONOTONICITY
4295 *
4296 * This callback is called when an expression is checked for its monotonicity with respect to a given child.
4297 * It is given the index of the child and shall return whether the expression is monotonically increasing or decreasing with respect to this child,
4298 * that is, when assuming that all other children are fixed.
4299 * Bounds on the children can be taken into account.
4300 * These can be evaluated and obtained via SCIPevalExprActivity() and SCIPexprGetActivity().
4301 *
4302 * The implementation in the absolute value expression handler serves as an example:
4303 * @refsnippet{src/scip/expr_abs.c,SnippetExprMonotonicityAbs}
4304 *
4305 * If this callback is not implemented, the expression is assumed to be not monotone in any child.
4306 *
4307 * @subsection EXPRINTEGRALITY
4308 *
4309 * This callback is called when an expression is checked for integrality, that is,
4310 * whether the expression evaluates always to an integral value in a feasible solution.
4311 * An implementation usually uses SCIPexprIsIntegral() to check whether children evaluate to an integral value.
4312 *
4313 * For example, a sum expression is returned to be integral if all coefficients and all children are integral:
4314 * @refsnippet{src/scip/expr_sum.c,SnippetExprIntegralitySum}
4315 *
4316 * If this callback is not implemented, the expression is assumed to be not integral.
4317 *
4318 * @subsection EXPRHASH
4319 *
4320 * This callback is called when a hash value is computed for an expression.
4321 * The hash is used to quickly identify expressions that may be equal (or better: to identify expressions that cannot be pairwise equal).
4322 *
4323 * The hash shall be unique to the expression as likely as positive.
4324 * To achieve this, the hashing algorithm shall use the expression type, expression data, and hash of children as input.
4325 * It must also be deterministic in this input.
4326 *
4327 * For example, for the sum expression, the coefficients and the hashes of all children are taken into account:
4328 * @refsnippet{src/scip/expr_sum.c,SnippetExprHashSum}
4329 *
4330 * `EXPRHDLR_HASHKEY` is a constant that is unique to the sum expression handler.
4331 *
4332 * If this callback is not implemented, a hash is computed from the expression handler name and the hashes of all children.
4333 *
4334 * @subsection EXPRCOMPARE
4335 *
4336 * This callback is called when two expressions (expr1 and expr2) that are handled by the expression handlers need to be compared.
4337 * The method shall impose an order on expressions and thus must return
4338 * - -1 if expr1 < expr2, or
4339 * - 0 if expr1 = expr2, or
4340 * - 1 if expr1 > expr2.
4341 *
4342 * The callback may use SCIPcompareExpr() to compare children of expr1 and expr2.
4343 *
4344 * For example, for pow expressions, the order is given by the order of the children.
4345 * If the children are equal, then the order of the exponents is used:
4346 * @refsnippet{src/scip/expr_pow.c,SnippetExprComparePow}
4347 *
4348 * If this callback is not implemented, a comparison is done based on the children of expr1 and expr2 only.
4349 * If the expression is stateful, it must implement this callback.
4350 *
4351 * @subsection EXPRBWDIFF
4352 *
4353 * This callback is called when the gradient or Hessian of a function that is represented by an expression is computed.
4354 *
4355 * The method shall compute the partial derivative of the expression w.r.t. a child with specified childidx.
4356 * That is, it should return
4357 * \f[
4358 * \frac{\partial \text{expr}}{\partial \text{child}_{\text{childidx}}}
4359 * \f]
4360 *
4361 * See also \ref SCIP_EXPR_DIFF "Differentiation methods in scip_expr.h" for more details on automatic differentiation of expressions.
4362 *
4363 * For the product expression, backward differentiation is implemented as follows:
4364 * @refsnippet{src/scip/expr_product.c,SnippetExprBwdiffProduct}
4365 *
4366 * If this callback is not implemented, gradients and Hessian of functions that involve this expression cannot be computed.
4367 * This can be hurtful for performance because linear relaxation routines that rely on gradient evaluation (e.g., nlhdlr_convex) cannot be used.
4368 *
4369 * @subsection EXPRFWDIFF
4370 *
4371 * This callback is called when the Hessian of a function that is represented by an expression is computed.
4372 * It may also be used to compute first derivatives.
4373 *
4374 * The method shall evaluate the directional derivative of the expression when interpreted as an operator
4375 * \f$ f(c_1, \ldots, c_n) \f$, where \f$ c_1, \ldots, c_n \f$ are the children.
4376 * The directional derivative is
4377 * \f[
4378 * \sum_{i = 1}^n \frac{\partial f}{\partial c_i} D_u c_i,
4379 * \f]
4380 * where \f$ u \f$ is the direction (given to the callback) and \f$ D_u c_i \f$ is the directional derivative of the i-th child,
4381 * which can be accessed via SCIPexprGetDot().
4382 * The point at which to compute the derivative is given by SCIPexprGetEvalValue().
4383 *
4384 * See also \ref SCIP_EXPR_DIFF "Differentiation methods in scip_expr.h" for more details on automatic differentiation of expressions.
4385 *
4386 * For a product, \f$f(x) = c\prod_i x_i\f$, the directional derivative is \f$c\sum_j \prod_{i\neq j} x_i x^{\text{dot}}_j\f$:
4387 * @refsnippet{src/scip/expr_product.c,SnippetExprFwdiffProduct}
4388 *
4389 * If this callback is not implemented, routines (in particular primal heuristics) that rely on solving NLPs cannot be used, as they currently rely on using forward differentiation for gradient computations.
4390 *
4391 * @subsection EXPRBWFWDIFF
4392 *
4393 * This callback is called when the Hessian of a function that is represented by an expression is computed.
4394 *
4395 * The method computes the total derivative, w.r.t. its children, of the partial derivative of expr w.r.t. childidx.
4396 * Equivalently, it computes the partial derivative w.r.t. childidx of the total derivative.
4397 *
4398 * The expression should be interpreted as an operator \f$ f(c_1, \ldots, c_n) \f$, where \f$ c_1, \ldots, c_n \f$ are the children,
4399 * and the method should return
4400 * \f[
4401 * \sum_{i = 1}^n \frac{\partial^2 f}{\partial c_i} \partial c_{\text{childidx}} D_u c_i,
4402 * \f]
4403 * where \f$ u \f$ is the direction (given to the callback) and \f$ D_u c_i \f$ is the directional derivative of the i-th child,
4404 * which can be accessed via SCIPexprGetDot().
4405 *
4406 * Thus, if \f$ n = 1 \f$ (i.e., the expression represents a univariate operator), the method should return
4407 * \f[
4408 * f^{\prime \prime}(\text{SCIPexprGetEvalValue}(c)) D_u c.
4409 * \f]
4410 *
4411 * See also \ref SCIP_EXPR_DIFF "Differentiation methods in scip_expr.h" for more details on automatic differentiation of expressions.
4412 *
4413 * For a product, \f$f(x) = c\prod_i x_i\f$, the directional derivative is
4414 * \f$c\partial_k \sum_j \prod_{i \neq j} x_i x^{\text{dot}}_j = c\sum_{j \neq k} \prod_{i \neq j, k} x_i x^{\text{dot}}_j\f$:
4415 * @refsnippet{src/scip/expr_product.c,SnippetExprBwfwdiffProduct}
4416 *
4417 * If this callback is not implemented, there is currently no particular performance impact.
4418 * In a future version, not implementing this callback would mean that Hessians are not available for NLP solvers, in which case they may have to work with approximations.
4419 *
4420 * @subsection EXPRINTEVAL
4421 *
4422 * This callback is called when bounds on an expression need to be computed.
4423 * It shall compute an (as tight as possible) overestimate on the range that the expression values take w.r.t. bounds (given as \ref SCIP_INTERVAL) for the children.
4424 * The latter can be accessed via SCIPexprGetActivity().
4425 *
4426 * Often, interval evaluation is implemented analogous to evaluation with numbers.
4427 * For example, for products:
4428 * @refsnippet{src/scip/expr_product.c,SnippetExprIntevalProduct}
4429 *
4430 * If this callback is not implemented, the performance of domain propagation for nonlinear constraints and other routines that rely on bounds of expressions will be impacted severely.
4431 *
4432 * @subsection EXPRESTIMATE
4433 *
4434 * While \ref EXPRINTEVAL computes constant under- and overestimators,
4435 * this callback is called when linear under- or overestimators need to be computed.
4436 * The estimator shall be as tight as possible at a given point and must be valid w.r.t. given (local) bounds.
4437 * If the value of the estimator in the reference point is smaller (larger) than a given targetvalue
4438 * when underestimating (overestimating), then no estimator needs to be computed.
4439 * Note, that targetvalue can be infinite if any estimator will be accepted.
4440 *
4441 * The callback shall also indicate whether the estimator is also valid w.r.t. given global bounds and for which
4442 * child a reduction in the local bounds (usually by branching) would improve the estimator.
4443 *
4444 * For the absolute-value expression, the under- and overestimators are computed as follows:
4445 * @refsnippet{src/scip/expr_abs.c,SnippetExprEstimateAbs}
4446 *
4447 * If this callback is not implemented, updating the linear relaxation for nonlinear constraints that use this expression will not be possible, which has a severe impact on performance.
4448 *
4449 * @subsection EXPRINITESTIMATES
4450 *
4451 * This callback is similar to \ref EXPRESTIMATE, but is not given a reference point.
4452 * It can also return several (up to \ref SCIP_EXPR_MAXINITESTIMATES many) estimators.
4453 * A usecase for this callback is the construction of an initial linear relaxation of nonlinear constraints.
4454 *
4455 * For the absolute-value expression, the following initial under- and overestimators are computed:
4456 * @refsnippet{src/scip/expr_abs.c,SnippetExprInitestimatesAbs}
4457 *
4458 * If this callback is not implemented, the initial linear relaxation for nonlinear constraints may be less tight.
4459 * This can have a minor effect on performance, as long as \ref EXPRESTIMATE has been implemented and the linear relaxation
4460 * is still bounded (e.g., when all nonlinear variables have finite bounds).
4461 *
4462 * @subsection EXPRSIMPLIFY
4463 *
4464 * This callback shall try to simplify an expression by applying algebraic transformations.
4465 * It shall return the simplified (and equivalent) expression.
4466 * It can assume that children have been simplified.
4467 * If no simplification is possible, then it can return the original expression, but needs to capture it.
4468 * When creating a new expression, it shall pass on the given ownerdata creation callback and its data.
4469 *
4470 * A simplification that should be implemented by every expression handler at the moment is constant-folding, i.e.,
4471 * returning a value-expression if every child is a value expression.
4472 * For an example, the simplification for the exponentiation expression is implemented as
4473 * @refsnippet{src/scip/expr_exp.c,SnippetExprSimplifyExp}
4474 *
4475 * See also SCIPsimplifyExpr() for more information on implemented simplification rules.
4476 *
4477 * If this callback is not implemented, reducing the problem size when variables are fixed may not be possible, which can have an impact on performance.
4478 * (Also bugs may show up as this situation is untested.)
4479 *
4480 * @subsection EXPRREVERSEPROP
4481 *
4482 * This callback is called when given bounds on an expression shall be propagated over the children of an expression.
4483 * Already existing bounds on the children (see \ref EXPRINTEVAL) shall be used.
4484 * That is, the method shall compute an interval overestimate on
4485 * \f[
4486 * \{ x_i : f(c_1,\ldots,c_{i-1},x_i,c_{i+1},\ldots,c_n) \in \text{bounds} \}
4487 * \f]
4488 * for each child \f$i\f$, given bounds on f and initial intervals \f$c_i, i=1,\ldots,n,\f$, for the children.
4489 *
4490 * For univariate expressions, the implementation can be rather straightforward, e.g., for absolute value:
4491 * @refsnippet{src/scip/expr_abs.c,SnippetExprReversepropAbs}
4492 *
4493 * For multivariate expressions, it can be more complicated, e.g., for products:
4494 * @refsnippet{src/scip/expr_product.c,SnippetExprReversepropProduct}
4495 *
4496 * If this callback is not implemented, the performance of domain propagation for nonlinear constraints will be impacted severely.
4497 */
4498
4499/*--+----1----+----2----+----3----+----4----+----5----+----6----+----7----+----8----+----9----+----0----+----1----+----2*/
4500
4501/**@page NLHDLR How to add nonlinear handlers
4502 *
4503 * Nonlinear handlers define the extended formulations of nonlinear constraints and provide domain propagation and separation routines on this extended formulation.
4504 * In difference to \ref EXPRHDLR "expression handlers", they do not define a function, but instead identify a
4505 * structure in an existing expression and provide bound tightening and separation on this structure similar to \ref EXPRINTEVAL, \ref EXPRREVERSEPROP, \ref EXPRINITESTIMATES, and \ref EXPRESTIMATE.
4506 * The structure typically consists of a composition of expressions.
4507 *
4508 * Nonlinear handlers are a new plugin type in SCIP and may still have some rough edges.
4509 * They resemble constraint handlers in some sense, but are specific to the handling of nonlinear constraints.
4510 * We suggest to read section "New Handler for Nonlinear Constraints" in the SCIP 8.0 release report (2021)
4511 * to understand the role and use of nonlinear handlers before attempting to implement one.
4512 *
4513 * A complete list of all nonlinear handlers contained in this release can be found \ref NLHDLRS "here".
4514 * In difference to many other plugins in SCIP, nonlinear handlers are not handled by the SCIP core but by the constraint handler for nonlinear constraints.
4515 *
4516 * Here is what you have to do to implement a nonlinear handler:
4517 * -# Copy the template files `src/scip/nlhdlr_xyz.c` and `src/scip/nlhdlr_xyz.h` into files `nlhdlr_mystruct.c` and `nlhdlr_mystruct.h`, respectively. \n
4518 * Make sure to adjust your build system such that these files are compiled and linked to your project. \n
4519 * If you are adding a new default plugin, this means updating the `src/CMakeLists.txt` and `Makefile` files in the SCIP distribution.
4520 * -# Use `SCIPincludeNlhdlrMystruct()` in order to include the nonlinear handler into your SCIP instance, e.g., in the main file of your project. \n
4521 If you are adding a new default plugin, this include function must be added to `src/scipdefplugins.c`.
4522 * -# Open the new files with a text editor and replace all occurrences of "xyz" by "mystruct".
4523 * -# Adjust the properties of the nonlinear handler (see \ref NLHDLR_PROPERTIES).
4524 * -# Define the nonlinear handler data and nonlinear handler expression data (see \ref NLHDLR_DATA). This is optional.
4525 * -# Implement the interface methods (see \ref NLHDLR_INTERFACE).
4526 * -# Implement the fundamental callback methods (see \ref NLHDLR_FUNDAMENTALCALLBACKS).
4527 * -# Implement the additional callback methods (see \ref NLHDLR_ADDITIONALCALLBACKS), where necessary.
4528 *
4529 * Additional documentation for the callback methods of a nonlinear handler, in particular for the input parameters,
4530 * can be found in the file \ref type_nlhdlr.h.
4531 *
4532 * @section NLHDLR_PROPERTIES Properties of a Nonlinear Handler
4533 *
4534 * At the top of the new file `nlhdlr_mystruct.c`, you can find the nonlinear handler properties.
4535 * These are given as compiler defines.
4536 * The properties you have to set have the following meaning:
4537 *
4538 * \par NLHDLR_NAME: the name of the nonlinear handler.
4539 * This name is used in the interactive shell to address the nonlinear handler.
4540 * Additionally, if you are searching for a nonlinear handler with SCIPfindNlhdlrNonlinear(), this name is looked up.
4541 * Names have to be unique: no two nonlinear handlers may have the same name.
4542 *
4543 * \par NLHDLR_DESC: the description of the nonlinear handler.
4544 * This string is printed as a description of the nonlinear handler in the interactive shell.
4545 *
4546 * \par NLHDLR_DETECTPRIORITY: the priority of the nonlinear handler when detecting structure.
4547 * This priority decides when the \ref NLHDLRDETECT callback of the nonlinear handler is called, relative to other nonlinear handlers, on an expression.
4548 * Typically, the priority should be strictly positive.
4549 * This is because the nonlinear handler "default" (having detection priority 0) will not become active on expressions that are already handled by other nonlinear handlers.
4550 *
4551 * \par NLHDLR_ENFOPRIORITY: the priority of the nonlinear handler when enforcing constraints in the extended formulations.
4552 * This priority decides when the callbacks that help on domain propagation and separation are called for an expression for which the nonlinear handler detected a structure.
4553 * A high priority means that the nonlinear handler will be called before others.
4554 * The nonlinear handler "default" has enforcement priority 0.
4555 *
4556 * @section NLHDLR_DATA Nonlinear Handler Data and Nonlinear Handler Expression Data
4557 *
4558 * Below the header "Data structures" you can find structs called `struct SCIP_NlhdlrData` and `struct SCIP_NlhdlrExprData`.
4559 * In this first data structure, you can store the data of your nonlinear handler.
4560 * For example, you should store the adjustable parameters of the nonlinear handler in this data structure.
4561 * In the second data structure, you can store data that is unique to an expression for which the nonlinear handler detected a structure.
4562 * For example, the nonlinear handler for quotients stores a representation of a detected quotient in this data structure.
4563 * \n
4564 * Defining nonlinear handler data and nonlinear handler expression data is optional. You can leave these structs empty.
4565 *
4566 * @section NLHDLR_INTERFACE Interface Methods
4567 *
4568 * At the bottom of `nlhdlr_mystruct.c`, you can find the interface method `SCIPincludeNlhdlrXyz()`,
4569 * which also appears in `nlhdlr_mystruct.h`.
4570 * `SCIPincludeNlhdlrXyz()` is called by the user, if (s)he wants to include the nonlinear handler,
4571 * i.e., if (s)he wants to use the nonlinear handler in his/her application.
4572 *
4573 * This method is responsible for notifying SCIP of the presence of the nonlinear handler.
4574 * For this, you must call SCIPincludeNlhdlrNonlinear() from SCIPincludeNlhdlrMystruct().
4575 * The function only expects the properties and fundamental callbacks of the nonlinear handler as arguments.
4576 * \ref NLHDLR_ADDITIONALCALLBACKS "Additional callbacks" must be added via setter functions as, e.g., SCIPnlhdlrSetCopyHdlr().
4577 *
4578 * If you are using nonlinear handler data, you have to allocate the memory for the data at this point and initialize it.
4579 * For freeing the nonlinear handler data, see \ref NLHDLRFREEHDLRDATA.
4580 * You may also add user parameters or statistic tables for your nonlinear handler, see \ref PARAM for how to add user parameters.
4581 *
4582 * For the bilinear nonlinear handler, the include method is as follows:
4583 * @refsnippet{src/scip/nlhdlr_bilinear.c,SnippetIncludeNlhdlrBilinear}
4584 *
4585 *
4586 * @section NLHDLR_FUNDAMENTALCALLBACKS Fundamental Callback Methods of a Nonlinear Handler
4587 *
4588 * The fundamental callback methods of the plugins are the ones that have to be implemented in order to obtain
4589 * an operational algorithm.
4590 * They are passed to SCIP when the nonlinear handler is created and included in SCIP via SCIPincludeNlhdlrNonlinear(),
4591 * see @ref NLHDLR_INTERFACE.
4592 *
4593 * Nonlinear handlers have two fundamental callbacks that need to be implemented.
4594 * Additional documentation for the callback methods, in particular to their input parameters,
4595 * can be found in \ref type_nlhdlr.h.
4596 *
4597 * @subsection NLHDLRDETECT
4598 *
4599 * This callback is called by the handler for nonlinear constraints when extended formulations are constructed.
4600 * The result of this callback determines the extended formulation.
4601 *
4602 * The nonlinear handler shall analyze the given expression (`expr`) and decide whether it wants to contribute
4603 * in enforcing the relation between bounds or an auxiliary variable (`auxvar`) associated with this expression and
4604 * its descendants (e.g., children) via linear under- or overestimation, cut generation, and/or activity computation and propagation.
4605 * For linear under- or overestimation and cut generation, an auxiliary variable can be assumed to
4606 * be associated with the expression and auxiliary variables may be requested for descendant expressions.
4607 *
4608 * We distinguish the following enforcement methods:
4609 * - \ref SCIP_NLHDLR_METHOD_SEPABELOW : linear underestimation of `expr` or cut generation for the relation `expr` &le; `auxvar` (denoted as "below")
4610 * - \ref SCIP_NLHDLR_METHOD_SEPAABOVE : linear overestimation of `expr` or cut generation for the relation `expr` &ge; `auxvar` (denoted as "above")
4611 * - \ref SCIP_NLHDLR_METHOD_ACTIVITY : domain propagation (i.e., constant under/overestimation) for `expr`.
4612 *
4613 * On input, parameter `enforcing` indicates for any of these methods, whether
4614 * - it is not necessary to have such a method, e.g., because no `auxvar` will exist for `expr`, or no one uses or sets activities of this expression,
4615 * or because analysis of the expression has shown that a relation like `expr` &ge; `auxvar` is not necessary to be satisfied,
4616 * - or there already exists a nonlinear handler that will provide this method in an "enforcement" sense, that is,
4617 * it believes that no one else could provide this method in a stronger sense. (This is mainly used by the nonlinear handler "default" to check whether
4618 * it should still reach out to the expression handler or whether it would be dominated by some nonlinear handler.)
4619 *
4620 * The DETECT callback shall augment the `enforcing` bitmask by setting the enforcement methods it wants to provide in an "enforcement" sense.
4621 *
4622 * Additionally, the `participating` bitmask shall be set if the nonlinear handler wants to be called on this expression at all.
4623 * Here, it shall set all methods that it wants to provide, which are those set in `enforcing`, but additionally those where it wants
4624 * to participate but leave enforcement to another nonlinear handler.
4625 * This can be useful for nonlinear handlers that do not implement a complete enforcement, e.g., a handler that only contributes
4626 * cutting planes in some situations only.
4627 *
4628 * A nonlinear handler will be called only for those callbacks that it mentioned in `participating`, which is
4629 * - \ref NLHDLRENFO and/or \ref NLHDLRESTIMATE will be called with `overestimate==FALSE` if \ref SCIP_NLHDLR_METHOD_SEPABELOW has been set
4630 * - \ref NLHDLRENFO and/or \ref NLHDLRESTIMATE will be called with `overestimate==TRUE` if \ref SCIP_NLHDLR_METHOD_SEPAABOVE has been set
4631 * - \ref NLHDLRINTEVAL and/or \ref NLHDLRREVERSEPROP will be called if \ref SCIP_NLHDLR_METHOD_ACTIVITY has been set
4632 *
4633 * If \ref SCIP_NLHDLR_METHOD_SEPABELOW or \ref SCIP_NLHDLR_METHOD_SEPAABOVE has been set, then at least one of the
4634 * callbacks \ref NLHDLRENFO and \ref NLHDLRESTIMATE needs to be implemented.
4635 * Also \ref NLHDLREVALAUX will be called in this case.
4636 * If \ref SCIP_NLHDLR_METHOD_ACTIVITY has been set, then at least one of \ref NLHDLRINTEVAL and \ref NLHDLRREVERSEPROP needs to be implemented.
4637 * If the nonlinear handler chooses not to participate, then it must not set `nlhdlrexprdata` and can leave `participating` at its
4638 * initial value (\ref SCIP_NLHDLR_METHOD_NONE).
4639 *
4640 * Additionally, a nonlinear handler that decides to participate in any of the enforcement methods must call
4641 * @ref SCIPregisterExprUsageNonlinear() for every subexpression that it will use and indicate whether
4642 * - it will use an auxiliary variable in \ref NLHDLRENFO or \ref NLHDLRESTIMATE,
4643 * - it will use activity for some subexpressions when computing estimators or cuts, and
4644 * - it will use activity for some subexpressions when in \ref NLHDLRINTEVAL or \ref NLHDLRREVERSEPROP.
4645 *
4646 * Note that auxiliary variables do not exist in subexpressions during DETECT and are not created by a call to @ref SCIPregisterExprUsageNonlinear().
4647 * They will be available when the \ref NLHDLRINITSEPA callback is called.
4648 *
4649 * For an example, see the implementation of the DETECT callback for the nonlinear handler for quotients (src/scip/nlhdlr_quotient.c).
4650 *
4651 * @subsection NLHDLREVALAUX
4652 *
4653 * This callback is called by the constraint handler for nonlinear constraints when the violation of constraints in the extended formulation
4654 * (`expr` &le;/&ge; `auxvar`) needs to be evaluated.
4655 * During constraint enforcement, this violation value is used to decide whether estimation and separation callbacks should be called.
4656 *
4657 * The method shall evaluate the expression w.r.t. the auxiliary variables that were introduced by the nonlinear handler (if any).
4658 * It can be assumed that the expression itself has been evaluated in the given sol.
4659 *
4660 * For an example, see the evaluation for the quotient nonlinear handler:
4661 * @refsnippet{src/scip/nlhdlr_quotient.c,SnippetNlhdlrEvalauxQuotient}
4662*
4663 * @section NLHDLR_ADDITIONALCALLBACKS Additional Callback Methods of a Nonlinear Handler
4664 *
4665 * The additional callback methods do not need to be implemented in every case. However, some of them have to be
4666 * implemented for most applications, they can be used, for example, to initialize and free private data.
4667 * Additional callbacks can be passed via specific
4668 * <b>setter functions</b> after a call of SCIPincludeNlhdlrNonlinear(), see also @ref NLHDLR_INTERFACE.
4669 *
4670 * @subsection NLHDLRCOPYHDLR
4671 *
4672 * This callback is called when doing a copy of the constraint handler for nonlinear constraints.
4673 * It shall include the nonlinear handler into the copy of the constraint handler.
4674 *
4675 * @subsection NLHDLRFREEHDLRDATA
4676 *
4677 * If you are using nonlinear handler data (see \ref NLHDLR_DATA and \ref NLHDLR_INTERFACE), you have to implement this method
4678 * in order to free the nonlinear handler data.
4679 *
4680 * @subsection NLHDLRFREEEXPRDATA
4681 *
4682 * If you are using nonlinear handler expression data (see \ref NLHDLR_DATA and \ref NLHDLRDETECT), you have to implement this method
4683 * in order to free the nonlinear handler expression data.
4684 * This method is called when an extended formulation is freed.
4685 *
4686 * @subsection NLHDLRINIT
4687 *
4688 * This callback is called when the constraint handler for nonlinear constraints is initialized, that is, after the problem was transformed.
4689 * The nonlinear handler can use this callback to initialize or reset some data for the upcoming solve.
4690 *
4691 * @subsection NLHDLREXIT
4692 *
4693 * This callback is called when the constraint handler for nonlinear constraints is deinitialized, that is, before the transformed problem is freed.
4694 * The nonlinear handler can use this callback to free some data that was used for the previous solve only.
4695 *
4696 * @subsection NLHDLRINTEVAL
4697 *
4698 * This callback is called when bounds on a given expression shall be computed.
4699 * It is called for expressions for which the nonlinear handler registered to participate in \ref SCIP_NLHDLR_METHOD_ACTIVITY in \ref NLHDLRDETECT.
4700 * The method is given the currently available bounds to the expression and can return possibly tighter bounds.
4701 *
4702 * For a univariate quotient ((ax+b)/(cx+d)), the interval evaluation is implemented as follows:
4703 * @refsnippet{src/scip/nlhdlr_quotient.c,SnippetNlhdlrIntevalQuotient}
4704 *
4705 * @subsection NLHDLRREVERSEPROP
4706 *
4707 * This callback is called when bounds on a given expression shall be propagated to its successors.
4708 * It is called for expressions for which the nonlinear handler registered to participate in \ref SCIP_NLHDLR_METHOD_ACTIVITY in \ref NLHDLRDETECT.
4709 * The tighter intervals should be passed to the corresponding expression via SCIPtightenExprIntervalNonlinear().
4710 *
4711 * For a univariate quotient ((ax+b)/(cx+d)), reverse propagation is implemented as follows:
4712 * @refsnippet{src/scip/nlhdlr_quotient.c,SnippetNlhdlrReversepropQuotient}
4713 *
4714 * @subsection NLHDLRINITSEPA
4715 *
4716 * This callback is called when the constraint handler for nonlinear constraints initializes the LP relaxation (@ref CONSINITLP).
4717 * It is called for expressions for which the nonlinear handler registered to participate in \ref SCIP_NLHDLR_METHOD_SEPABELOW or \ref SCIP_NLHDLR_METHOD_SEPAABOVE in \ref NLHDLRDETECT.
4718 * The method shall initialize the separation data of the nonlinear handler, if any, and add initial cuts to the LP relaxation.
4719 * It can assume that auxiliary variables are available for expressions for which auxiliary variables were requested via SCIPregisterExprUsageNonlinear() in \ref NLHDLRDETECT.
4720 *
4721 * @subsection NLHDLREXITSEPA
4722 *
4723 * This callback is called when the solving process is finished and the branch and bound process data is freed (@ref CONSEXITSOL).
4724 * It is called for expressions for which the nonlinear handler registered to participate in \ref SCIP_NLHDLR_METHOD_SEPABELOW or \ref SCIP_NLHDLR_METHOD_SEPAABOVE in \ref NLHDLRDETECT and \ref NLHDLRINITSEPA was called.
4725 * The method shall deinitialize the separation data of the nonlinear handler, if any.
4726 *
4727 * @subsection NLHDLRENFO
4728 *
4729 * This callback is called when the constraint handler requires that the relation between the given expression and its auxiliary variable
4730 * (`expr` &le; `auxvar` or `expr` &ge; `auxvar`) is violated by a given solution and this solution needs to be separated.
4731 * It is called for expressions for which the nonlinear handler registered to participate in \ref SCIP_NLHDLR_METHOD_SEPABELOW or \ref SCIP_NLHDLR_METHOD_SEPAABOVE in \ref NLHDLRDETECT.
4732 *
4733 * The nonlinear handler can enforce `expr` &le;/&ge; `auxvar` by
4734 * - separation, i.e., finding an affine hyperplane (a cut) that separates the given point, or
4735 * - bound tightening, i.e., changing bounds on a variable so that the given point is outside the updated domain, or
4736 * - adding branching scores to potentially split the current problem into two subproblems.
4737 *
4738 * If parameter `inenforcement` is FALSE, then only the first option (separation) is allowed.
4739 *
4740 * If the nonlinear handler always separates by computing a linear under- or overestimator of `expr`,
4741 * then it is usually easier to implement the \ref NLHDLRESTIMATE callback instead.
4742 *
4743 * Note, that the nonlinear handler may also choose to separate for a relaxation of the mentioned sets,
4744 * e.g., `expr` &le; upperbound(`auxvar`) or `expr` &ge; lowerbound(`auxvar`).
4745 * This is especially useful in situations where `expr` is the root expression of a constraint
4746 * and it is sufficient to satisfy `lhs` &le; `expr` &le; `rhs`.
4747 * The constraint handler ensures that `lhs` &le; lowerbound(`auxvar`) and upperbound(`auxvar`) &le; `rhs`.
4748 *
4749 * The constraint handler may call this callback first with `allowweakcuts` = FALSE and repeat later with
4750 * `allowweakcuts` = TRUE, if it didn't succeed to enforce a solution without using weak cuts.
4751 * If in enforcement and the nonlinear handler cannot enforce by separation or bound tightening, it should register
4752 * branching scores for those expressions where branching may help to compute tighter cuts in children.
4753 *
4754 * The nonlinear handler must set `result` to \ref SCIP_SEPARATED if it added a cut,
4755 * to \ref SCIP_REDUCEDDOM if it added a bound change, and
4756 * to \ref SCIP_BRANCHED if it added branching scores.
4757 * Otherwise, it may set result to \ref SCIP_DIDNOTRUN or \ref SCIP_DIDNOTFIND.
4758 *
4759 * @subsection NLHDLRESTIMATE
4760 *
4761 * This callback is called when the constraint handler requires that the relaxation between the given expression and its auxiliary variable
4762 * (`expr` &le; `auxvar` or `expr` &ge; `auxvar`) is violated by a given solution and this solution needs to be separated.
4763 * It is called for expressions for which the nonlinear handler registered to participate in \ref SCIP_NLHDLR_METHOD_SEPABELOW or \ref SCIP_NLHDLR_METHOD_SEPAABOVE in \ref NLHDLRDETECT.
4764 * This method is a simpler alternative to \ref NLHDLRENFO and is called if \ref NLHDLRENFO is not implemented or does not succeed.
4765 *
4766 * The method shall compute one or several linear under- or overestimator of `expr` that are as tight as possible at a given point.
4767 * If the value of the estimator in the solution is smaller (larger) than a given targetvalue
4768 * when underestimating (overestimating), then no estimator needs to be computed.
4769 * Note, that targetvalue can be infinite if any estimator will be accepted.
4770 * If successful, it shall store the estimators in the given `rowpreps` data structure and set the
4771 * `rowprep->local` flag accordingly (SCIProwprepSetLocal()).
4772 * The sidetype of a rowprep must be set to \ref SCIP_SIDETYPE_LEFT if overestimating and
4773 * \ref SCIP_SIDETYPE_RIGHT if underestimating.
4774 *
4775 * The callback may also be required to indicate for which expression a reduction in the local bounds (usually by branching) would improve the estimator.
4776 * This is done by a call to SCIPaddExprsViolScoreNonlinear().
4777 *
4778 * For the quotient nonlinear handler, the estimators are computed as follows:
4779 * @refsnippet{src/scip/nlhdlr_quotient.c,SnippetNlhdlrEstimateQuotient}
4780 *
4781 * @subsection NLHDLRSOLLINEARIZE
4782 *
4783 * This callback is called by the constraint handler when it has caught a solution event from SCIP and option constraints/nonlinear/linearizeheursol has been enabled.
4784 * The constraint handler then calls the nonlinear handlers for all expressions they currently handle.
4785 * The nonlinear handler may use this opportunity to add a cut that supports its nonlinear function in the given solution to the cutpool.
4786 * For convex functions, this may help to accellerate proving optimality for a solution found by a NLP solver.
4787 */
4788
4789/*--+----1----+----2----+----3----+----4----+----5----+----6----+----7----+----8----+----9----+----0----+----1----+----2*/
4790
4791/**@page DIVINGHEUR How to implement a diving heuristic
4792 *
4793 * Diving heuristics are an important addon to the branch-and-cut search. A diving heuristic explores a single probing
4794 * path down the search tree. In contrast to the regular search guided by branching rule(s) and the selected
4795 * node selector, the diving is performed in an auxiliary tree originating from the focus node of the main
4796 * search tree where the heuristic was called. The advantage of this approach is that many different scoring mechanisms
4797 * can be safely tried as diving heuristic and may probably lead to better solutions. SCIP has a lot of diving heuristics
4798 * included in its default plugin set.
4799 * \n
4800 *
4801 * Since SCIP version 3.2, the diving heuristics have been redesigned to contain mainly the scoring function used by the
4802 * heuristic. In order to implement a user-defined diving heuristic, it is possible to create one (or several)
4803 * divesets that control the scoring mechanism and add them to the primal heuristic. This has the advantage that
4804 * less code is necessary to create a working diving heuristic. The SCIP statistics now also display some interesting statistics
4805 * about every diveset together in the section 'Diving Statistics'.
4806 * \n
4807 *
4808 * This page contains the necessary steps to understand and include a diveset into ones primal diving heuristic plugin. As
4809 * a prerequisite, you should understand the basic implementation steps for a primal heuristic, see \ref HEUR.
4810 * In order to make use of divesets, they must be included _after_ the primal heuristic to which they should belong
4811 * has been included, by using SCIPincludeDiveset(). This will create the data structure for the diveset and
4812 * append it to the list of divesets belonging to the heuristic, which can be retrieved later together with their number
4813 * by using SCIPheurGetDivesets() and SCIPheurGetNDivesets(), respectively. No further memory allocation or deletion is needed;
4814 * As a member of the heuristic, SCIP automatically takes care of freeing the diveset when it is exiting.
4815 * \n
4816 *
4817 * Before the inclusion, one may think of adjusting the various properties that a diveset offers to control
4818 * the behavior of the algorithm. These are subject to the following section.
4819 * \n
4820 *
4821 * It is mandatory to implement the fundamental scoring callback of the diveset, which is explained in more detail
4822 * in Section \ref DIVING_FUNDAMENTALCALLBACKS.
4823 * \n
4824 *
4825 * Once the properties have been carefully adjusted and the scoring
4826 * has been defined, use the method SCIPperformGenericDivingAlgorithm() inside the execution callback (\ref HEUREXEC) of the primal
4827 * heuristic to which the diveset belongs, after checking possible preliminaries that may not be met at all times of the search.
4828 * \n
4829 *
4830 * For a code example, we refer to \ref heur_guideddiving.h, which guides the diving into the direction of the current incumbent solution.
4831 * Before it calls SCIPperformGenericDivingAlgorithm(), it checks whether an incumbent is available, and returns if there is none.
4832 *
4833 *
4834 * @section DIVING_PARAMETERS User parameters and properties for every diveset
4835 *
4836 * Every diveset controls the diving behavior through a set of user-defined parameters, which are explained in the following:
4837 *
4838 * \par MINRELDEPTH
4839 * the minimal relative depth (to the maximum depth explored during regular search) of the current focus node to start diving
4840 *
4841 * \par MAXRELDEPTH
4842 * the maximal relative depth (to the maximum depth explored during regular search) of the current focus node to start diving
4843 *
4844 * \par MAXLPITERQUOT
4845 * maximal fraction of diving LP iterations compared to node LP iterations that this dive controller may consume
4846 *
4847 * \par MAXLPITEROFS
4848 * an additional number of allowed LP iterations
4849 *
4850 * \par MAXDIVEUBQUOT
4851 * maximal quotient (curlowerbound - lowerbound)/(cutoffbound - lowerbound)
4852 * where diving is performed (0.0: no limit)
4853 *
4854 * \par MAXDIVEAVGQUOT
4855 * maximal quotient (curlowerbound - lowerbound)/(avglowerbound - lowerbound)
4856 * where diving is performed (0.0: no limit)
4857 *
4858 * \par MAXDIVEUBQUOTNOSOL
4859 * maximal UBQUOT when no solution was found yet (0.0: no limit)
4860 *
4861 * \par MAXDIVEAVGQUOTNOSOL
4862 * maximal AVGQUOT when no solution was found yet (0.0: no limit)
4863 *
4864 * \par BACKTRACK
4865 * use one level of backtracking if infeasibility is encountered?
4866 *
4867 * \par LPRESOLVEDOMCHGQUOT
4868 * parameter to control LP resolve dynamically based on this percentage of observed bound changes relative to all variables or
4869 * the LP branching candidates (integer variables with fractional solution values) from the last node where an LP has been solved.
4870 * This property has no effect when the LPSOLVEFREQ is set to 1.
4871 *
4872 * \par LPSOLVEFREQ
4873 * LP solve frequency for diveset, use a positive integer k to solve an LP at every k'th depth of the diving search (ie. 1 causes the
4874 * diveset to solve _all_ intermediate LPs) or 0 to only resolve the LP relaxation after propagation found at least a certain percentage
4875 * domain changes, see also the previous LPRESOLVEDOMCHGQUOT parameter.
4876 *
4877 * \par ONLYLPBRANCHCANDS
4878 * Set this property to TRUE if only LP branching candidates be considered for the execution of the diving algorithm instead of the slower but
4879 * more general constraint handler diving variable selection.
4880 *
4881 * \par DIVETYPES
4882 * bit mask that represents all supported dive types. Irrelevant if only LP branching candidates should be scored, otherwise, different
4883 * constraint handlers may ask the diveset if it supports their preferred divetype. See \ref type_heur.h for a list of
4884 * available dive types.
4885 *
4886 * @section DIVING_FUNDAMENTALCALLBACKS Fundamental callbacks of a diveset
4887 *
4888 * Only one callback is necessary to complete a diveset to guide the diving search performed:
4889 *
4890 * @subsection DIVESETGETSCORE
4891 *
4892 * The scoring callback expects a candidate variable and calculates a score value and a preferred direction. The selected
4893 * variable for diving will be one that _maximizes_ the score function provided by the diveset.
4894 * If the diveset should support more than one possible type of diving, it may use the divetype argument as a hint how
4895 * the caller of the score function (could be the diving algorithm itself or one of the constraint handlers that
4896 * implement diving variable selection) intends to perform the search.
4897 *
4898 * @section DIVING_FURTHERINFO Further information
4899 *
4900 * This is all there is to extend the SCIP set of diving heuristics by a new one. For further information, please see
4901 * diveset related methods in \ref type_heur.h, \ref pub_heur.h, \ref heuristics.h, and \ref heur_guideddiving.h or
4902 * other diving heuristics that implement diving through a diveset.
4903 */
4904
4905/*--+----1----+----2----+----3----+----4----+----5----+----6----+----7----+----8----+----9----+----0----+----1----+----2*/
4906
4907/**@page RELAX How to add relaxation handlers
4908 *
4909 * SCIP provides specific support for LP relaxations of constraint integer programs. In addition, relaxation handlers,
4910 * also called relaxators, can be used to include other relaxations, e.g. Lagrange relaxations or semidefinite
4911 * relaxations. The relaxation handler manages the necessary data structures and calls the relaxation solver to generate dual
4912 * bounds and primal solution candidates.
4913 * \n
4914 * However, the data to define a single relaxation must either be extracted by the relaxation handler itself (e.g., from
4915 * the user defined problem data, the LP information, or the integrality conditions), or it must be provided by the constraint
4916 * handlers. In the latter case, the constraint handlers have to be extended to support this specific relaxation.
4917 * \n
4918 *
4919 * We now explain how users can add their own relaxation handlers using the C interface. As an example, look into the NLP
4920 * relaxation handler of the \ref RELAXATOR_MAIN "Relaxator example" (examples/Relaxator/src/relax_nlp.c). It is very easy to
4921 * transfer the C explanation to C++: whenever a method should be implemented using the SCIP_DECL_RELAX... notion,
4922 * reimplement the corresponding virtual member function of the abstract scip::ObjRelax wrapper base class.
4923 *
4924 * Additional documentation for the callback methods of a relaxation handler can be found in the file type_relax.h.
4925 *
4926 * Here is what you have to do to implement a relaxation handler:
4927 * -# Copy the template files src/scip/relax_xyz.c and src/scip/relax_xyz.h into files named "relax_myrelaxator.c"
4928 * and "relax_myrelaxator.h".
4929 * \n
4930 * Make sure to adjust your build system such that these files are compiled and linked to your project. \n
4931 * If you are adding a new default plugin, this means updating the `src/CMakeLists.txt` and `Makefile` files in the SCIP distribution.
4932 * -# Use `SCIPincludeRelaxMyrelaxator()` in order to include the relaxation handler into your SCIP instance,
4933 * e.g., in the main file of your project (see, e.g., src/cmain.c in the Binpacking example). \n
4934 * If you are adding a new default plugin, this include function must be added to `src/scipdefplugins.c`.
4935 * -# Open the new files with a text editor and replace all occurrences of "xyz" by "myrelaxator".
4936 * -# Adjust the properties of the relaxation handler (see \ref RELAX_PROPERTIES).
4937 * -# Define the relaxation handler data (see \ref RELAX_DATA). This is optional.
4938 * -# Implement the interface methods (see \ref RELAX_INTERFACE).
4939 * -# Implement the fundamental callback methods (see \ref RELAX_FUNDAMENTALCALLBACKS).
4940 * -# Implement the additional callback methods (see \ref RELAX_ADDITIONALCALLBACKS). This is optional.
4941 *
4942 *
4943 * @section RELAX_PROPERTIES Properties of a Relaxation Handler
4944 *
4945 * At the top of the new file "relax_myrelaxator.c" you can find the relaxation handler properties,
4946 * which are given as compiler defines.
4947 * In the C++ wrapper class, you have to provide the relaxation handler properties by calling the constructor
4948 * of the abstract base class scip::ObjRelax from within your constructor.
4949 * The properties have the following meaning:
4950 *
4951 * \par RELAX_NAME: the name of the relaxation handler.
4952 * This name is used in the interactive shell to address the relaxation handler.
4953 * Additionally, if you are searching for a relaxation handler with SCIPfindRelax(), this name is looked up.
4954 * Names have to be unique: no two relaxation handlers may have the same name.
4955 *
4956 * \par RELAX_DESC: the description of the relaxation handler.
4957 * This string is printed as a description of the relaxation handler in the interactive shell.
4958 *
4959 * \par RELAX_PRIORITY: the priority of the relaxation handler.
4960 * During each relaxation solving round, the included relaxation handlers and the
4961 * price-and-cut loop for solving the LP relaxation are called in a predefined order, which is given by the priorities
4962 * of the relaxation handlers.
4963 * First, the relaxation handlers with non-negative priority are called in the order of decreasing priority.
4964 * Next, the price-and-cut loop for solving the LP relaxation is executed.
4965 * Finally, the relaxation handlers with negative priority are called in the order of decreasing priority.
4966 * \n
4967 * Usually, you will have only one relaxation handler in your application and thus only have to decide whether it should
4968 * be called before or after solving the LP relaxation. For this decision you should consider the complexity of
4969 * the relaxation solving algorithm and the impact of the resulting solution: if your relaxation handler provides a fast
4970 * algorithm that usually has a high impact (i.e. the relaxation is a good approximation of the
4971 * feasible region of the subproblem and the solution severely improves the dual bound), it should have a non-negative
4972 * priority.
4973 * \n
4974 * Note that for certain applications, it is useful to disable the LP relaxation and only use your custom relaxation.
4975 * This can easily be achieved by setting the "lp/solvefreq" parameter to -1.
4976 *
4977 * \par RELAX_FREQ: the default frequency for solving the relaxation.
4978 * The frequency defines the depth levels at which the relaxation solving method \ref RELAXEXEC is called.
4979 * For example, a frequency of 7 means, that the relaxation solving callback is executed for subproblems that are in depth
4980 * 0, 7, 14, ... of the branching tree. A frequency of 0 means that the callback is only executed at the root node, i.e.,
4981 * only the relaxation of the root problem is solved. A frequency of -1 disables the relaxation handler.
4982 *
4983 *
4984 *
4985 * @section RELAX_DATA Relaxation Handler Data
4986 *
4987 * Below the header "Data structures" you can find a struct which is called "struct SCIP_RelaxData".
4988 * In this data structure, you can store the data of your relaxation handler. For example, you should store the adjustable
4989 * parameters of the relaxation handler in this data structure.
4990 * If you are using C++, you can add relaxation handler data as usual as object variables to your class.
4991 * \n
4992 * Defining relaxation handler data is optional. You can leave the struct empty.
4993 *
4994 *
4995 * @section RELAX_INTERFACE Interface Methods
4996 *
4997 * At the bottom of "relax_myrelaxator.c", you can find the interface method SCIPincludeRelaxMyrelaxator(),
4998 * which also appears in "relax_myrelaxator.h".
4999 * SCIPincludeRelaxMyrelaxator() is called by the user, if (s)he wants to include the relaxation handler,
5000 * i.e., if (s)he wants to use the relaxation handler in his/her application.
5001 *
5002 * This method only has to be adjusted slightly.
5003 * It is responsible for notifying SCIP of the presence of the relaxation handler. For this, you can either call
5004 * SCIPincludeRelax(),
5005 * or SCIPincludeRelaxBasic() since SCIP version 3.0. In the latter variant, \ref RELAX_ADDITIONALCALLBACKS "additional callbacks"
5006 * must be added via setter functions as, e.g., SCIPsetRelaxCopy(). We recommend this latter variant because
5007 * it is more stable towards future SCIP versions which might have more callbacks, whereas source code using the first
5008 * variant must be manually adjusted with every SCIP release containing new callbacks for relaxation handlers in order to compile.
5009 *
5010 * If you are using relaxation handler data, you have to allocate the memory for the data at this point.
5011 * You can do this by calling:
5012 * \code
5013 * SCIP_CALL( SCIPallocBlockMemory(scip, &relaxdata) );
5014 * \endcode
5015 * You also have to initialize the fields in struct SCIP_RelaxData afterwards.
5016 *
5017 * You may also add user parameters for your relaxation handler, see the method SCIPincludeConshdlrKnapsack() in
5018 * the \ref cons_knapsack.h "knapsack constraint handler" for an example of how to add user parameters.
5019 *
5020 *
5021 * @section RELAX_FUNDAMENTALCALLBACKS Fundamental Callback Methods of a Relaxation Handler
5022 *
5023 * The fundamental callback methods of the plugins are the ones that have to be implemented in order to obtain
5024 * an operational algorithm.
5025 * They are passed together with the relaxation handler itself to SCIP using SCIPincludeRelax() or SCIPincludeRelaxBasic(),
5026 * see @ref RELAX_INTERFACE.
5027 *
5028 *
5029 * Relaxation handler plugins have only one fundamental callback method, namely the \ref RELAXEXEC method.
5030 * This method has to be implemented for every relaxation handler; the other callback methods are optional.
5031 * In the C++ wrapper class scip::ObjRelax, the scip_exec() method (which corresponds to the \ref RELAXEXEC callback) is a virtual
5032 * abstract member function.
5033 * You have to implement it in order to be able to construct an object of your relaxation handler class.
5034 *
5035 * Additional documentation for the callback methods can be found in type_relax.h.
5036 *
5037 * @subsection RELAXEXEC
5038 * The RELAXEXEC is called in each relaxation solving round. It should solve the current
5039 * subproblem's relaxation.
5040 *
5041 * Note that, like the LP relaxation, the relaxation handler should only operate on variables for which the corresponding
5042 * column exists in the transformed problem. Typical methods called by a relaxation handler are SCIPconstructLP() and SCIPflushLP() to
5043 * make sure that the LP of the current node is constructed and its data can be accessed via calls to SCIPgetLPRowsData()
5044 * and SCIPgetLPColsData(), and SCIPseparateSol() to call the cutting plane separators for a given primal solution.
5045 *
5046 * The lowerbound computed by the relaxation should be returned in the lowerbound pointer. If the relaxation improves on the best
5047 * relaxation already computed (either <code>SCIPisRelaxSolValid()</code> returns FALSE, meaning that no relaxation solution
5048 * is available so far, or the lowerbound is larger than the value returned by <code>SCIPgetRelaxSolObj()</code>), then the primal
5049 * solution of the relaxation should be stored inside the data structures of SCIP with <code>SCIPsetRelaxSolVal()</code>,
5050 * <code>SCIPsetRelaxSolVals()</code> or <code>SCIPsetRelaxSolValsSol()</code>. If you set the values one by one, you will need to call
5051 * <code>SCIPmarkRelaxSolValid()</code> to inform SCIP that the solution is complete and valid. With the "includeslp" argument of
5052 * <code>SCIPsetRelaxSolVals()</code>, <code>SCIPsetRelaxSolValsSol()</code> and <code>SCIPmarkRelaxSolValid()</code> you need to tell SCIP
5053 * whether the relaxation included all lp rows. In this case, the solution will be enforced and, if feasible, added to the solution storage if the
5054 * lowerbound of this relaxator is larger than the LP's. You may also call SCIPtrySolFree() directly from the
5055 * relaxation handler to make sure that a solution is added to the solution storage if it is feasible, even if the relaxator does not
5056 * include the LP or another relaxator produced a stronger bound. Also note that when setting the values of the relaxation solution one by one,
5057 * the objective value of the relaxation solution will be updated incrementally. If the whole solution should be updated, using SCIPsetRelaxSolVals()
5058 * instead or calling SCIPclearRelaxSolVals() before setting the first value to reset the solution and the objective value to 0 may help the numerics.
5059 * Furthermore, there is a list of external branching candidates, that can be filled by relaxation handlers and constraint handlers,
5060 * allowing branching rules to take these candidates as a guide on how to split the problem into subproblems. If the relaxation
5061 * solution is enforced, the integrality constraint handler will add external branching candidates for the relaxation solution
5062 * automatically, but the relaxation handler can also directly call <code>SCIPaddExternBranchCand()</code>.
5063 *
5064 * Usually, the RELAXEXEC callback only solves the relaxation and provides a lower (dual) bound through the corresponding pointer and
5065 * possibly a solution through <code>SCIPsetRelaxSolVal()</code> calls.
5066 * However, it may also produce domain reductions, add additional constraints or generate cutting planes. It has the
5067 * following options:
5068 * - detecting that the node is infeasible in the variable's bounds and can be cut off (result SCIP_CUTOFF)
5069 * - adding an additional constraint and stating that the relaxation handler should not be called again on the same
5070 * relaxation (result SCIP_CONSADDED)
5071 * - reducing a variable's domain and stating that the relaxation handler should not be called again on the same
5072 * relaxation (result SCIP_REDUCEDDOM)
5073 * - adding a cutting plane to the LP and stating that the relaxation handler should not be called again on the same
5074 * relaxation (result SCIP_SEPARATED)
5075 * - stating that the relaxation handler solved the relaxation and should not be called again on the same relaxation
5076 * (result SCIP_SUCCESS)
5077 * - interrupting the solving process to wait for additional input, e.g., cutting planes (result SCIP_SUSPENDED)
5078 * - stating that the separator was skipped (result SCIP_DIDNOTRUN).
5079 *
5080 * In the above criteria, "the same relaxation" means that the LP relaxation stayed unmodified. This means in particular
5081 * that no row has been added and no bounds have been modified. For example, changing the bounds of a variable will, as
5082 * long as it was a COLUMN variable, lead to a modification in the LP such that the relaxation handler is called again
5083 * after it returned with the result code SCIP_REDUCEDDOM. If the relaxation solution should be enforced, the relaxation
5084 * handler has to produce a new solution in this case which satisfies the updated LP. If a relaxation handler should only run
5085 * once per node to compute a lower bound, it should store the node of the last relaxation call itself and return
5086 * SCIP_DIDNOTRUN for subsequent calls in the same node.
5087 *
5088 *
5089 * @section RELAX_ADDITIONALCALLBACKS Additional Callback Methods of a Relaxation Handler
5090 *
5091 * The additional callback methods do not need to be implemented in every case. However, some of them have to be
5092 * implemented for most applications, they can be used, for example, to initialize and free private data.
5093 * Additional callbacks can either be passed directly with SCIPincludeRelax() to SCIP or via specific
5094 * <b>setter functions</b> after a call of SCIPincludeRelaxBasic(), see also @ref RELAX_INTERFACE.
5095 *
5096 * @subsection RELAXFREE
5097 *
5098 * If you are using relaxation handler data, you have to implement this method in order to free the relaxation handler
5099 * data. This can be done by the following procedure:
5100 *
5101 * @refsnippet{tests/src/relax/relax.c,SnippetRelaxFreeUnittest}
5102 *
5103 * If you have allocated memory for fields in your relaxation handler data, remember to free this memory
5104 * before freeing the relaxation handler data itself.
5105 * If you are using the C++ wrapper class, this method is not available.
5106 * Instead, just use the destructor of your class to free the member variables of your class.
5107 *
5108 * @subsection RELAXINIT
5109 *
5110 * The RELAXINIT callback is executed after the problem is transformed.
5111 * The relaxation handler may, e.g., use this call to initialize its relaxation handler data.
5112 *
5113 * @subsection RELAXCOPY
5114 *
5115 * The RELAXCOPY callback is executed when a SCIP instance is copied, e.g. to
5116 * solve a sub-SCIP. By
5117 * defining this callback as
5118 * <code>NULL</code> the user disables the execution of the specified
5119 * relaxation handler for all copied SCIP instances. This may deteriorate the performance
5120 * of primal heuristics using sub-SCIPs.
5121 *
5122 * @subsection RELAXEXIT
5123 *
5124 * The RELAXEXIT callback is executed before the transformed problem is freed.
5125 * In this method, the relaxation handler should free all resources that have been allocated for the solving process in
5126 * RELAXINIT.
5127 *
5128 * @subsection RELAXINITSOL
5129 *
5130 * The RELAXINITSOL callback is executed when the presolving is finished and the branch-and-bound process is about to
5131 * begin. The relaxation handler may use this call to initialize its branch-and-bound specific data.
5132 *
5133 * @subsection REALXEXITSOL
5134 *
5135 * The RELAXEXITSOL callback is executed before the branch-and-bound process is freed.
5136 * The relaxation handler should use this call to clean up its branch-and-bound data.
5137 */
5138
5139/*--+----1----+----2----+----3----+----4----+----5----+----6----+----7----+----8----+----9----+----0----+----1----+----2*/
5140
5141/**@page READER How to add file readers
5142 *
5143 * Mainly, file readers are called to parse an input file and generate a constraint integer programming model. They
5144 * create constraints and variables and activate variable pricers if necessary. However, they can also be called, for
5145 * example, to parse an input file containing information about a primal solution or fixing of variables. Besides that
5146 * it is possible to use some of them for writing (exporting) the problem in a specific format. \n A complete list of
5147 * all file readers contained in this release can be found \ref FILEREADERS "here".
5148 *
5149 * Since a file reader is also responsible for writing a file, the user may
5150 * ask why the readers have not the name "filehandler". This name would
5151 * represent this plugin much better than the used one.
5152 * \n
5153 * The used name "readers" is historically grown. In the beginning of SCIP
5154 * there was no need to write/export problems. Therefore, the the plugin
5155 * name "readers" was best fitting for this plugin since only reading was essential.
5156 * It turned out, however, that it is quite nice to write/export certain subproblem during
5157 * the solving process mainly for debugging. Therefore, a writing callback
5158 * was added to the "readers" plugin.
5159 *
5160 * We now explain how users can add their own file readers.
5161 * Take the file reader for MIPs in IBM's Mathematical Programming System format (src/scip/reader_mps.c) as an example.
5162 * As all other default plugins, it is written in C. C++ users can easily adapt the code by using the scip::ObjReader wrapper
5163 * base class and implement the scip_...() virtual methods instead of the SCIP_DECL_READER... callback methods.
5164 *
5165 * Additional documentation for the callback methods of a file reader can be found in the file type_reader.h.
5166 *
5167 * Here is what you have to do to implement a file reader named "myreader" in C:
5168 * -# Copy the template files src/scip/reader_xyz.c and src/scip/reader_xyz.h into files named
5169 * "reader_myreader.c" and "reader_myreader.h".
5170 * \n
5171 * Make sure to adjust your build system such that these files are compiled and linked to your project. \n
5172 * If you are adding a new default plugin, this means updating the `src/CMakeLists.txt` and `Makefile` files in the SCIP distribution.
5173 * -# Use `SCIPincludeReaderMyreader()` in order to include the reader into your SCIP instance,
5174 * e.g., in the main file of your project (see, e.g., src/cmain.c in the Binpacking example). \n
5175 * If you are adding a new default plugin, this include function must be added to `src/scipdefplugins.c`.
5176 * -# Open the new files with a text editor and replace all occurrences of "xyz" by "myreader".
5177 * -# Adjust the \ref READER_PROPERTIES "properties of the file reader".
5178 * -# Define the \ref READER_DATA "file reader data". This is optional.
5179 * -# Implement the \ref READER_INTERFACE "interface methods".
5180 * -# Implement the \ref READER_FUNDAMENTALCALLBACKS "fundamental callback methods".
5181 * -# Implement the \ref READER_ADDITIONALCALLBACKS "additional callback methods". This is optional.
5182 *
5183 *
5184 * @section READER_PROPERTIES Properties of a File Reader
5185 *
5186 * At the top of the new file "reader_myreader.c" you can find the file reader properties.
5187 * These are given as compiler defines.
5188 * In the C++ wrapper class, you have to provide the file reader properties by calling the constructor
5189 * of the abstract base class scip::ObjReader from within your constructor.
5190 * The properties you have to set have the following meaning:
5191 *
5192 * \par READER_NAME: the name of the file reader.
5193 * This name is used in the interactive shell to address the file reader.
5194 * Additionally, if you are searching for a file reader with SCIPfindReader(), this name is looked up.
5195 * Names have to be unique: no two file readers may have the same name.
5196 *
5197 * \par READER_DESC: the description of the file reader.
5198 * This string is printed as a description of the file reader in the interactive shell.
5199 *
5200 * \par READER_EXTENSION: the file name extension of the file reader.
5201 * Each file reader is hooked to a single file name extension. It is automatically called if the user wants to read in a
5202 * file of corresponding name. The extensions of the different file readers have to be unique.
5203 * Note that the additional extension '.gz', '.z', or '.Z' (indicating a gzip compressed file) are ignored for assigning
5204 * an input file to a reader.
5205 * \n
5206 * It is not possible to hook up a (single) file reader with more than one file extension.
5207 * It is, however, not necessary to implement the same (parsing/writing) methods more than once, if you want to
5208 * support several file extension with the same parser. To do so look at the files reader_lp.c
5209 * and reader_rlp.c. Both support the LP format.
5210 *
5211 *
5212 * @section READER_DATA File Reader Data
5213 *
5214 * Below the header "Data structures" you can find a struct which is called "struct SCIP_ReaderData".
5215 * In this data structure, you can store the data of your file reader. For example, you should store the adjustable
5216 * parameters of the file reader in this data structure.
5217 * If you are using C++, you can add file reader data as usual as object variables to your class.
5218 * \n
5219 * Defining file reader data is optional. You can leave the struct empty.
5220 *
5221 *
5222 * @section READER_INTERFACE Interface Methods
5223 *
5224 * At the bottom of "reader_myreader.c", you can find the interface method SCIPincludeReaderMyreader(),
5225 * which also appears in "reader_myreader.h".
5226 * SCIPincludeReaderMyreader() is called by the user, if (s)he wants to include the reader,
5227 * i.e., if (s)he wants to use the reader in his/her application.
5228 *
5229 * This method only has to be adjusted slightly.
5230 * It is responsible for notifying SCIP of the presence of the reader. For this, you can either call
5231 * SCIPincludeReader(),
5232 * or SCIPincludeReaderBasic() since SCIP version 3.0. In the latter variant, \ref READER_ADDITIONALCALLBACKS "additional callbacks"
5233 * must be added via setter functions as, e.g., SCIPsetReaderCopy(). We recommend this latter variant because
5234 * it is more stable towards future SCIP versions which might have more callbacks, whereas source code using the first
5235 * variant must be manually adjusted with every SCIP release containing new callbacks for readers in order to compile.
5236 *
5237 * If you are using file reader data, you have to allocate the memory for the data at this point.
5238 * You can do this by calling:
5239 * \code
5240 * SCIP_CALL( SCIPallocBlockMemory(scip, &readerdata) );
5241 * \endcode
5242 * You also have to initialize the fields in struct SCIP_ReaderData afterwards.
5243 *
5244 * You may also add user parameters for your file reader, see the method SCIPincludeReaderLp() in
5245 * src/scip/reader_lp.c for an example.
5246 *
5247 *
5248 * @section READER_FUNDAMENTALCALLBACKS Fundamental Callback Methods of a File Reader
5249 *
5250 * File reader plugins have no fundamental callback methods. This is due to
5251 * the fact that a file reader can be used for reading and/or writing a
5252 * file. A file reader is only useful if the reader method \ref READERREAD
5253 * and/or the writing method \ref READERWRITE is implemented. One of these
5254 * methods should be implemented for every file reader; the other callback
5255 * methods \ref READERCOPY and \ref READERFREE are optional. In the C++ wrapper class scip::ObjReader, the
5256 * scip_read() and scip_write() methods (which corresponds to the \ref
5257 * READERREAD and \ref READERWRITE callback) are virtual member
5258 * functions. At least one of them should be implemented.
5259 *
5260 * Additional documentation for the callback methods can be found in type_reader.h.
5261 *
5262 *
5263 * @section READER_ADDITIONALCALLBACKS Additional Callback Methods of a File Reader
5264 *
5265 * Additional callbacks can either be passed directly with SCIPincludeReader() to SCIP or via specific
5266 * <b>setter functions</b> after a call of SCIPincludeReaderBasic(), see also @ref READER_INTERFACE.
5267 *
5268 *
5269 * File reader plugins contain only additional callback methods, namely the methods \ref READERREAD,
5270 * \ref READERWRITE, \ref READERFREE, and \ref READERCOPY. Therefore, these are not needed to be implemented. However,
5271 * at least \ref READERREAD and/or \ref READERWRITE should be implemented (see notes
5272 * \ref READER_FUNDAMENTALCALLBACKS "above").
5273 *
5274 *
5275 * @subsection READERREAD
5276 *
5277 * The READERREAD callback is called when the user invokes SCIP to read in a file with file name extension
5278 * corresponding to the READER_EXTENSION property of the file reader. This is usually triggered by a call to the method
5279 * SCIPreadProb() or by an interactive shell command.
5280 * The READERREAD callback should parse the input file and perform the desired action, which usually means
5281 * generating a constraint integer programming model, adding a primal solution, fixing variables
5282 * in an existing model.
5283 * \n
5284 * Typical methods called by a file reader that is used to read/generate constraint
5285 * integer programming models are, for example,
5286 *
5287 * - creating an empty problem: SCIPcreateProb()
5288 * - creating the variables: SCIPcreateVar(), SCIPchgVarType(), SCIPchgVarLb(), SCIPchgVarUb(), SCIPaddVar(), and
5289 * SCIPreleaseVar()
5290 * - modifying the objective function: SCIPchgVarObj() and SCIPsetObjsense().
5291 * - creating the constraints: SCIPcreateConsLinear(), SCIPaddCoefLinear(), SCIPchgLhsLinear(), SCIPchgRhsLinear(),
5292 * SCIPaddCons(), and SCIPreleaseCons()
5293 *
5294 * Primal solutions can only be created for the transformed problem. Therefore, the user has to call SCIPtransformProb()
5295 * before (s)he reads in the file containing the solution and adds it to the solution pool via the method SCIPreadSol().
5296 *
5297 *
5298 * @subsection READERWRITE
5299 *
5300 * The READERWRITE callback is called when the user invokes SCIP to write a problem (original or transformed)
5301 * in the format the reader supports. This is only possible if this callback is implemented. To write the problem
5302 * all necessary information is given through the parameters of this callback method (see type_reader.h). This
5303 * information should be used to output the problem in the requested format. This callback method is usually
5304 * triggered by the call of the methods SCIPwriteOrigProblem(), SCIPwriteTransProblem(), SCIPprintOrigProblem(),
5305 * or SCIPprintTransProblem().
5306 * \n
5307 * A typical method called by a file reader which is used to write/export a constraint
5308 * integer programming model is SCIPinfoMessage(). This method outputs a given string into a file
5309 * or into stdout.
5310 * \n
5311 * For an example we refer to the writing method of the MPS reader (see reader_mps.c).
5312 *
5313 *
5314 * @subsection READERCOPY
5315 *
5316 * The READERCOPY callback is executed when a SCIP instance is copied, e.g. to solve a sub-SCIP. By defining this
5317 * callback as <code>NULL</code> the user disables the execution of the specified reader for all copied SCIP
5318 * instances. The question might arise why to copy that plugin. In case of debugging it is nice to be able to
5319 * write/display the copied instances. Since the reader is in charge of that, you might want to copy the plugin. Below
5320 * you see a standard implementation.
5321 *
5322 * @refsnippet{src/scip/reader_mps.c,SnippetReaderCopyMps}
5323 *
5324 * @subsection READERFREE
5325 *
5326 * If you are using file reader data, you have to implement this method in order to free the file reader data.
5327 * This can be done by the following procedure:
5328 *
5329 * @refsnippet{src/scip/reader_mps.c,SnippetReaderFreeMps}
5330 *
5331 * If you have allocated memory for fields in your file reader data, remember to free this memory
5332 * before freeing the file reader data itself.
5333 * If you are using the C++ wrapper class, this method is not available.
5334 * Instead, just use the destructor of your class to free the member variables of your class.
5335 *
5336 */
5337
5338/*--+----1----+----2----+----3----+----4----+----5----+----6----+----7----+----8----+----9----+----0----+----1----+----2*/
5339
5340/**@page DIALOG How to add dialogs
5341 *
5342 * SCIP comes with a command line shell which allows the user to read in problem instances, modify the solver's
5343 * parameters, initiate the optimization and display certain statistics and solution information. This shell consists
5344 * of dialogs, which are organized as a tree in SCIP. A node of this tree which is not a leaf represents a menu in
5345 * the shell and the children of this node correspond to the entries of this menu (which can again be menus). All
5346 * different dialogs are managed by a dialog handler, which, in particular, is responsible for executing the dialog
5347 * corresponding to the user's command in the shell. The concept of a dialog handler is different to that
5348 * of a constraint handler, which is used to manage objects of the same structure, see \ref CONS. In particular, SCIP
5349 * features only one dialog handler (dialog_default.h), whereas there may exist different constraint handlers.
5350 * \n
5351 * A complete list of all dialogs contained in this release can be found \ref DIALOGS "here".
5352 *
5353 * We now explain how users can extend the interactive shell by adding their own dialog.
5354 * We give the explanation for creating your own source file for each additional dialog. Of course, you can collect
5355 * different dialogs in one source file. Take src/scip/dialog_default.c, where all default dialog plugins are collected, as an
5356 * example.
5357 * As all other default plugins, the default dialog plugin and the template dialog are written in C. C++ users can easily
5358 * adapt the code by using the scip::ObjDialog wrapper base class and implement the scip_...() virtual methods instead of the
5359 * SCIP_DECL_DIALOG... callback methods.
5360 *
5361 * Additional documentation for the callback methods of a dialog can be found in the file type_dialog.h.
5362 *
5363 * Here is what you have to do to add a dialog (assuming your dialog is named "mydialog"):
5364 * -# Copy the template files src/scip/dialog_xyz.c and src/scip/dialog_xyz.h into files named "dialog_mydialog.c"
5365 * and "dialog_mydialog.h".
5366 * \n
5367 * Make sure to adjust your build system such that these files are compiled and linked to your project. \n
5368 * If you are adding a new default plugin, this means updating the `src/CMakeLists.txt` and `Makefile` files in the SCIP distribution.
5369 * -# Use `SCIPincludeDialogMydialog()` in order to include the dialog handler into your SCIP instance,
5370 * e.g., in the main file of your project (see, e.g., src/cmain.c in the Binpacking example). \n
5371 * If you are adding a new default plugin, this include function must be added to `src/scipdefplugins.c`.
5372 * -# Open the new files with a text editor and replace all occurrences of "xyz" by "mydialog".
5373 * -# Adjust the \ref DIALOG_PROPERTIES "properties of the dialog".
5374 * -# Define the \ref DIALOG_DATA "dialog data". This is optional.
5375 * -# Implement the \ref DIALOG_INTERFACE "interface methods".
5376 * -# Implement the \ref DIALOG_FUNDAMENTALCALLBACKS "fundamental callback methods".
5377 * -# Implement the \ref DIALOG_ADDITIONALCALLBACKS "additional callback methods". This is optional.
5378 *
5379 *
5380 * @section DIALOG_PROPERTIES Properties of a Dialog
5381 *
5382 * At the top of the new file "dialog_mydialog.c" you can find the dialog properties.
5383 * These are given as compiler defines.
5384 * In the C++ wrapper class, you have to provide the dialog properties by calling the constructor
5385 * of the abstract base class scip::ObjDialog from within your constructor.
5386 * The properties you have to set have the following meaning:
5387 *
5388 * \par DIALOG_NAME: the name of the dialog.
5389 * In the interactive shell, this name appears as the command name of the dialog in the parent dialog.
5390 * Additionally, if you are searching an entry in a menu with SCIPdialogFindEntry(), this name is looked up.
5391 * Names within one menu have to be unique: no two dialogs in the same menu may have the same name.
5392 *
5393 * \par DIALOG_DESC: the description of the dialog.
5394 * This string is printed as a description of the dialog in the interactive shell if the additional
5395 * callback method \ref DIALOGDESC is not implemented.
5396 *
5397 * \par DIALOG_ISSUBMENU: whether the dialog is a (sub)menu.
5398 * This parameter states whether the dialog is a menu in the interactive shell, i.e., is the parent of further
5399 * dialogs.
5400 *
5401 *
5402 * @section DIALOG_DATA Dialog Data
5403 *
5404 * Below the header "Data structures" you can find a struct which is called "struct SCIP_DialogData".
5405 * In this data structure, you can store the data of your dialog.
5406 * If you are using C++, you can add dialog data as usual as object variables to your class.
5407 * \n
5408 * Defining dialog data is optional. You can leave the struct empty.
5409 *
5410 *
5411 * @section DIALOG_INTERFACE Interface Methods
5412 *
5413 * At the bottom of "dialog_mydialog.c" you can find the interface method SCIPincludeDialogMydialog(), which also appears
5414 * in "dialog_mydialog.h".
5415 * \n
5416 * This method only has to be adjusted slightly.
5417 * It is responsible for notifying SCIP of the presence of the dialog, which can be done by the following lines of code:
5418 *
5419 * @refsnippet{src/scip/dialog_xyz.c,SnippetDialogAddXyz}
5420 *
5421 * Here "parentdialog" has to be an existing dialog which is defined to be a menu (see DIALOG_ISSUBMENU), e.g.,
5422 * the default root dialog. The method SCIPgetRootDialog() returns the root dialog.
5423 *
5424 * The interface method is called by the user, if (s)he wants to include the dialog, i.e., if (s)he wants to use the dialog in
5425 * his/her application.
5426 * Note that in order to be able to link the new dialog to an existing default dialog
5427 * (except the root dialog) it has to be included <b>after the
5428 * default dialogs plugin</b>, i.e., the SCIPincludeDialogMydialog() call has to occur after the
5429 * SCIPincludeDialogDefault() call. The SCIPincludeDialogDefault() method is called from within the SCIPincludeDefaultPlugins()
5430 * method. Therefore, it suffices to include your dialog plugins after you have called SCIPincludeDefaultPlugins().
5431 * In case you want to add a dialog to the <b>root dialog</b>, you just use the following
5432 * lines of code to get/create the root dialog.
5433 *
5434 * @refsnippet{tests/src/misc/snippets.c,SnippetDialogCreate}
5435 *
5436 * Therefore, in this case you do not have to worry about the calls of
5437 * SCIPincludeDialogDefault() and SCIPincludeDefaultPlugins() .
5438 *
5439 * If you are using dialog data, you have to allocate the memory for the data at this point.
5440 * You can do this by calling:
5441 * \code
5442 * SCIP_CALL( SCIPallocBlockMemory(scip, &dialogdata) );
5443 * \endcode
5444 * You also have to initialize the fields in struct SCIP_DialogData afterwards.
5445 *
5446 * Consider the following example. The user wants to add a "drawgraph" command to the root menu of SCIP.
5447 * (S)he copies the "dialog_xyz.c" and "dialog_xyz.h" files into files "dialog_drawgraph.c" and "dialog_drawgraph.h", respectively.
5448 * Then, (s)he puts the following code into the SCIPincludeDialogDrawgraph() method, compare SCIPincludeDialogDefault() in
5449 * src/scip/dialog_default.c:
5450 * @refsnippet{tests/src/misc/snippets.c,SnippetDialogInclude}
5451 *
5452 * Using this code, it is even possible to call SCIPincludeDialogDrawgraph() before including the default dialog plugins,
5453 * and you can also call it multiple times without causing inconsistencies in the dialog structure.
5454 *
5455 *
5456 * @section DIALOG_FUNDAMENTALCALLBACKS Fundamental Callback Methods of a Dialog
5457 *
5458 * Dialogs have only one fundamental callback method, namely the \ref DIALOGEXEC method.
5459 * This method has to be implemented for every dialog; the other callback methods are optional.
5460 * In the C++ wrapper class scip::ObjDialog, the scip_exec() method (which corresponds to the \ref DIALOGEXEC callback) is a virtual
5461 * abstract member function.
5462 * You have to implement it in order to be able to construct an object of your dialog class.
5463 *
5464 * Additional documentation for the callback methods can be found in type_dialog.h.
5465 *
5466 * @subsection DIALOGEXEC
5467 *
5468 * The DIALOGEXEC method is invoked, if the user selected the dialog's command name in the parent's menu. It should
5469 * execute what is stated in DIALOG_DESC, e.g., the display constraint handlers dialog should display information about
5470 * the constraint handlers included in SCIP, see src/scip/dialog_default.c.
5471 *
5472 * For typical methods called by the execution method, have a look at src/scip/dialog_default.c.
5473 *
5474 * The callback has to return which dialog should be processed next. This can be, for example, the root dialog
5475 * (SCIPdialoghdlrGetRoot()), the parent dialog (SCIPdialogGetParent()) or NULL, which stands for closing the interactive
5476 * shell.
5477 *
5478 *
5479 * @section DIALOG_ADDITIONALCALLBACKS Additional Callback Methods of a Dialog
5480 *
5481 * The additional callback methods do not need to be implemented in every case.
5482 * They can be used, for example, to free private data.
5483 *
5484 * @subsection DIALOGFREE
5485 *
5486 * If you are using dialog data, you have to implement this method in order to free the dialog data.
5487 * This can be done by the following procedure:
5488 * @refsnippet{tests/src/misc/snippets.c,SnippetDialogFree}
5489 *
5490 * If you have allocated memory for fields in your dialog data, remember to free this memory
5491 * before freeing the dialog data itself.
5492 * If you are using the C++ wrapper class, this method is not available.
5493 * Instead, just use the destructor of your class to free the member variables of your class.
5494 *
5495 * @subsection DIALOGDESC
5496 *
5497 * This method is called when the help menu of the parent is displayed. It should output (usually a single line of)
5498 * information describing the meaning of the dialog.
5499 * \n
5500 * If this callback is not implemented, the description string of the dialog (DIALOG_DESC) is displayed instead.
5501 *
5502 * @subsection DIALOGCOPY
5503 *
5504 * The DIALOGCOPY callback is executed when a SCIP instance is copied, e.g. to solve a sub-SCIP. By defining this
5505 * callback as <code>NULL</code> the user disables the execution of this dialog for all copied SCIP instances. In
5506 * general there is no need to copy any dialog since it is most unlikely to start the interactive shell of the copied
5507 * instances.
5508 *
5509 */
5510
5511/*--+----1----+----2----+----3----+----4----+----5----+----6----+----7----+----8----+----9----+----0----+----1----+----2*/
5512
5513/**@page DISP How to add display columns
5514 *
5515 * While solving a constraint integer program, SCIP displays status information in a column-like fashion. The current
5516 * number of processed branching tree nodes, the solving time, and the relative gap between primal and dual bound are
5517 * examples of such display columns. There already exists a wide variety of display columns which can be activated or
5518 * deactivated on demand, see src/scip/disp_default.c. Additionally, the user can implement his/her own display columns
5519 * in order to track problem or algorithm specific values.
5520 * \n
5521 * A complete list of all displays contained in this release can be found \ref DISPLAYS "here".
5522 *
5523 * We now explain how users can add their own display columns.
5524 * We give the explanation for creating your own source file for each additional display column. Of course, you can collect
5525 * different additional display columns in one source file.
5526 * Take src/scip/disp_default.c, where all default display columns are collected, as an example.
5527 * As all other default plugins, the default display column plugins and the display column template are written in C.
5528 * C++ users can easily adapt the code by using the scip::ObjDisp wrapper base class and implement the scip_...() virtual methods
5529 * instead of the SCIP_DECL_DISP... callback methods.
5530 *
5531 *
5532 * Additional documentation for the callback methods of a display column can be found in the file type_disp.h.
5533 *
5534 * Here is what you have to do to implement a display column (assuming your display column is named "mydisplaycolumn"):
5535 * -# Copy the template files src/scip/disp_xyz.c and src/scip/disp_xyz.h into files named "disp_mydisplaycolumn.c"
5536 * and "disp_mydisplaycolumn.h".
5537 \n
5538 * Make sure to adjust your build system such that these files are compiled and linked to your project. \n
5539 * If you are adding a new default plugin, this means updating the `src/CMakeLists.txt` and `Makefile` files in the SCIP distribution.
5540 * -# Use `SCIPincludeDispMydisplaycolumn()` in order to include the display column into your SCIP instance,
5541 * e.g., in the main file of your project (see, e.g., src/cmain.c in the Binpacking example). \n
5542 * If you are adding a new default plugin, this include function must be added to `src/scipdefplugins.c`.
5543 * -# Open the new files with a text editor and replace all occurrences of "xyz" by "mydisplaycolumn".
5544 * -# Adjust the \ref DISP_PROPERTIES "properties of the display column".
5545 * -# Define the \ref DISP_DATA "display column data". This is optional.
5546 * -# Implement the \ref DISP_INTERFACE "interface methods".
5547 * -# Implement the \ref DISP_FUNDAMENTALCALLBACKS "fundamental callback methods".
5548 * -# Implement the \ref DISP_ADDITIONALCALLBACKS "additional callback methods". This is optional.
5549 *
5550 *
5551 * @section DISP_PROPERTIES Properties of a Display Column
5552 *
5553 * At the top of the new file "disp_mydisplaycolumn.c" you can find the display column properties.
5554 * These are given as compiler defines.
5555 * In the C++ wrapper class, you have to provide the display column properties by calling the constructor
5556 * of the abstract base class scip::ObjDisp from within your constructor.
5557 * The properties you have to set have the following meaning:
5558 *
5559 * \par DISP_NAME: the name of the display column.
5560 * This name is used in the interactive shell to address the display column.
5561 * Additionally, if you are searching for a display column with SCIPfindDisp(), this name is looked up.
5562 * Names have to be unique: no two display columns may have the same name.
5563 *
5564 * \par DISP_DESC: the description of the display column.
5565 * This string is printed as a description of the display column in the interactive shell.
5566 *
5567 * \par DISP_HEADER: the header of the display column.
5568 * This string is printed as the header of the display column in the status information display.
5569 *
5570 * \par DISP_WIDTH: the width of the display column.
5571 * This parameter defines the width (number of characters) of the display column. The value of the parameter has to be
5572 * greater than or equal to the number of characters in the header string.
5573 *
5574 * \par DISP_PRIORITY: the priority of the display column.
5575 * The total width of status information lines is bounded by the parameter "display width". The display columns actually contained
5576 * in the status information display are selected in decreasing order of their priority. Furthermore, the user can force
5577 * columns to be displayed or not to be displayed in the status information display. For that, (s)he has to switch the value
5578 * of the display column's parameter "active" from "auto" (its default value) to "on" or "off", respectively.
5579 *
5580 * \par DISP_POSITION: the relative position of the display column.
5581 * In the status information display, the display columns are arranged from left to right in increasing order of their
5582 * relative position.
5583 *
5584 * \par DISP_STRIPLINE: the default for whether the display column should be separated with a line from its right neighbor.
5585 * This parameter states whether the display column should be separated with the string "|" from its right neighbor. In so
5586 * doing, the clearness of the status information display may improve.
5587 *
5588 * @section DISP_DATA Display Column Data
5589 *
5590 * Below the header "Data structures" you can find a struct which is called "struct SCIP_DispData".
5591 * In this data structure, you can store the data of your display column. For example, you should store the adjustable
5592 * parameters of the display column in this data structure.
5593 * If you are using C++, you can add display column data as usual as object variables to your class.
5594 * \n
5595 * Defining display column data is optional. You can leave the struct empty.
5596 *
5597 *
5598 * @section DISP_INTERFACE Interface Methods
5599 *
5600 * At the bottom of "disp_mydisplaycolumn.c" you can find the interface method SCIPincludeDispMydisplaycolumn(), which also
5601 * appears in "disp_mydisplaycolumn.h".
5602 * \n
5603 * This method only has to be adjusted slightly.
5604 * It is responsible for notifying SCIP of the presence of the display column by calling the method
5605 * SCIPincludeDisp().
5606 *
5607 * The interface method is called by the user, if (s)he wants to include the display column, i.e., if (s)he wants to use the display column in his
5608 * application.
5609 *
5610 * If you are using display column data, you have to allocate the memory for the data at this point.
5611 * You can do this by calling:
5612 * \code
5613 * SCIP_CALL( SCIPallocBlockMemory(scip, &dispdata) );
5614 * \endcode
5615 * You also have to initialize the fields in struct SCIP_DispData afterwards.
5616 *
5617 * Although this is very uncommon, you may also add user parameters for your display column, see the method
5618 * SCIPincludeConshdlrKnapsack() in the \ref cons_knapsack.h "knapsack constraint handler" for an example.
5619 *
5620 *
5621 * @section DISP_FUNDAMENTALCALLBACKS Fundamental Callback Methods of a Display Column
5622 *
5623 * Display column plugins have only one fundamental callback method, namely the \ref DISPOUTPUT method.
5624 * This method has to be implemented for every display column; the other callback methods are optional.
5625 * In the C++ wrapper class scip::ObjDisp, the scip_output() method (which corresponds to the \ref DISPOUTPUT callback) is a virtual
5626 * abstract member function.
5627 * You have to implement it in order to be able to construct an object of your display column class.
5628 *
5629 * Additional documentation for the callback methods can be found in type_disp.h.
5630 *
5631 * @subsection DISPOUTPUT
5632 *
5633 * The DISPOUTPUT callback is called after each pricing loop during node processing and after a node has been processed.
5634 * In addition, at the root node, the callback is executed after each iteration of the price-and-cut loop.
5635 * It should write the display column information for the current node to a given output file stream.
5636 *
5637 * Typical methods called by a display column are, for example, SCIPdispLongint(), SCIPdispInt(), SCIPdispTime(), and
5638 * SCIPinfoMessage().
5639 *
5640 *
5641 * @section DISP_ADDITIONALCALLBACKS Additional Callback Methods of a Display Column
5642 *
5643 * The additional callback methods do not need to be implemented in every case.
5644 * They can be used, for example, to initialize and free private data.
5645 *
5646 * @subsection DISPCOPY
5647 *
5648 * The DISPCOPY callback is executed when a SCIP instance is copied, e.g. to solve a sub-SCIP. By defining this callback
5649 * as <code>NULL</code> the user disables the execution of the specified column. In general it is probably not needed to
5650 * implement that callback since the output of the copied instance is usually suppressed. In the other case or for
5651 * debugging the callback should be implement.
5652 *
5653 *
5654 * @subsection DISPFREE
5655 *
5656 * If you are using display column data, you have to implement this method in order to free the display column data.
5657 * This can be done by the following procedure:
5658 * @refsnippet{tests/src/misc/snippets.c,SnippetDispFree}
5659 *
5660 * If you have allocated memory for fields in your display column data, remember to free this memory
5661 * before freeing the display column data itself.
5662 * If you are using the C++ wrapper class, this method is not available.
5663 * Instead, just use the destructor of your class to free the member variables of your class.
5664 *
5665 * @subsection DISPINIT
5666 *
5667 * The DISPINIT callback is executed after the problem is transformed.
5668 * The display column may, e.g., use this call to initialize its display column data.
5669 *
5670 * @subsection DISPEXIT
5671 *
5672 * The DISPEXIT callback is executed before the transformed problem is freed.
5673 * In this method, the display column should free all resources that have been allocated for the solving process in
5674 * \ref DISPINIT.
5675 *
5676 * @subsection DISPINITSOL
5677 *
5678 * The DISPINITSOL callback is executed when the presolving is finished and the branch-and-bound process is about to
5679 * begin. The display column may use this call to initialize its branch-and-bound specific data.
5680 *
5681 * @subsection DISPEXITSOL
5682 *
5683 * The DISPEXITSOL callback is executed before the branch-and-bound process is freed. The display column should use this
5684 * call to clean up its branch-and-bound specific data.
5685 */
5686
5687/*--+----1----+----2----+----3----+----4----+----5----+----6----+----7----+----8----+----9----+----0----+----1----+----2*/
5688
5689/**@page EVENT How to add event handler
5690 *
5691 * While solving a constraint integer program, SCIP drops thousands of events such as SCIP_EVENTTYPE_VARFIXED (a
5692 * complete list of all events is given in type_event.h). These events can be caught and used to do something after a
5693 * certain event happens. Events can be used to speed up the solution process. For example, the set partitioning
5694 * constraint is only worth propagating if one of the involved variables is fixed. This can be detected by
5695 * catching the event SCIP_EVENTTYPE_VARFIXED. To be able to catch an event it is necessary to write an event handler
5696 * which defines what to do after a certain event was caught.
5697 *
5698 * We now explain how users can add their own event handlers. We give the explanation for creating your own
5699 * source file for each additional event handler. Of course, you can collect different event handlers in one source file
5700 * or you can put the event handler directly into the constraint handler. In a \ref EVENTUSAGE "second step" we discuss
5701 * the usage of an event handler. This means how to catch and drop events. \ref EVENTTYPES "Finally", we give some notes on the existing
5702 * types of events.
5703 *
5704 * Take src/scip/cons_logior.c, where the event handler is directly included into the constraint handler. As all other
5705 * default plugins, the event handlers are written in C. C++ users can easily adapt the code by using the scip::ObjEventhdlr
5706 * wrapper base class and implement the scip_...() virtual methods instead of the SCIP_DECL_EVENT... callback methods.
5707 *
5708 * Additional documentation for the callback methods of an event handler can be found in the file type_event.h. There is
5709 * also an example written in C which deals with an event handler. You find this example in the directory
5710 * "examples/Eventhdlr/". An C++ example can be found within the TSP project (examples/TSP/src/EventhdlrNewSol.cpp).
5711 *
5712 * Here is what you have to do to implement an event handler (assuming your event handler is named "bestsol"):
5713 * -# Copy the template files src/scip/event_xyz.c and src/scip/event_xyz.h into files named "event_bestsol.c"
5714 * and "event_bestsol.h".
5715 \n
5716 * Make sure to adjust your build system such that these files are compiled and linked to your project. \n
5717 * If you are adding a new default plugin, this means updating the `src/CMakeLists.txt` and `Makefile` files in the SCIP distribution.
5718 * -# Use `SCIPincludeEventBestsol()` in order to include the event handler into your SCIP instance,
5719 * e.g., in the main file of your project (see, e.g., src/cmain.c in the Binpacking example). \n
5720 * If you are adding a new default plugin, this include function must be added to `src/scipdefplugins.c`.
5721 * -# Open the new files with a text editor and replace all occurrences of "xyz" by "bestsol".
5722 * -# Adjust the \ref EVENTHDLR_PROPERTIES "properties of the event handler".
5723 * -# Implement the \ref EVENT_INTERFACE "interface methods".
5724 * -# Implement the \ref EVENT_FUNDAMENTALCALLBACKS "fundamental callback methods".
5725 * -# Implement the \ref EVENT_ADDITIONALCALLBACKS "additional callback methods". This is optional.
5726 *
5727 *
5728 * @section EVENTHDLR_PROPERTIES Properties of a Event Handler
5729 *
5730 * At the top of the new file "event_bestsol.c" you can find the event handler properties.
5731 * These are given as compiler defines.
5732 * In the C++ wrapper class, you have to provide the event handler properties by calling the constructor
5733 * of the abstract base class scip::ObjEventhdlr from within your constructor.
5734 * The properties you have to set have the following meaning:
5735 *
5736 * \par EVENT_NAME: the name of the event handler.
5737 * This name has to be unique with respect to all other event handlers. If you are searching for an event handler with
5738 * SCIPfindEventhdlr(), this name is looked up.
5739 *
5740 * \par EVENT_DESC: the description of the event handler.
5741 * This string is printed as a description of the event handler.
5742 *
5743 * @section EVENTHDLR_DATA Event Handler Data
5744 *
5745 * Below the header "Data structures" you can find a struct which is called "struct SCIP_EventhdlrData".
5746 * In this data structure, you can store the data of your event handler. For example, you should store the adjustable
5747 * parameters of the event handler in this data structure.
5748 * If you are using C++, you can add event handler data as usual as object variables to your class.
5749 * \n
5750 * Defining event handler data is optional. You can leave the struct empty.
5751 *
5752 *
5753 * @section EVENT_INTERFACE Interface Methods
5754 *
5755 * At the bottom of "event_bestsol.c", you can find the interface method SCIPincludeEventBestsol(),
5756 * which also appears in "event_bestsol.h".
5757 * SCIPincludeEventBestsol() is called by the user, if (s)he wants to include the event handler,
5758 * i.e., if (s)he wants to use the event handler in his/her application.
5759 *
5760 * This method only has to be adjusted slightly.
5761 * It is responsible for notifying SCIP of the presence of the event handler. For this, you can either call
5762 * SCIPincludeEventhdlr(),
5763 * or SCIPincludeEventhdlrBasic() since SCIP version 3.0. In the latter variant, \ref EVENT_ADDITIONALCALLBACKS "additional callbacks"
5764 * must be added via setter functions as, e.g., SCIPsetReaderCopy(). We recommend this latter variant because
5765 * it is more stable towards future SCIP versions which might have more callbacks, whereas source code using the first
5766 * variant must be manually adjusted with every SCIP release containing new callbacks for event handlers in order to compile.
5767 *
5768 * If you are using event handler data, you have to allocate the memory for the data at this point.
5769 * You can do this by calling:
5770 * \code
5771 * SCIP_CALL( SCIPallocBlockMemory(scip, &eventhdlrdata) );
5772 * \endcode
5773 * You also have to initialize the fields in struct SCIP_EventhdlrData afterwards.
5774 *
5775 * Although this is very uncommon, you may also add user parameters for your event handler, see the method
5776 * SCIPincludeConshdlrKnapsack() in the \ref cons_knapsack.h "knapsack constraint handler" for an example.
5777 *
5778 *
5779 * @section EVENT_FUNDAMENTALCALLBACKS Fundamental Callback Methods of a Event Handler
5780 *
5781 * The fundamental callback methods of the plugins are the ones that have to be implemented in order to obtain
5782 * an operational algorithm.
5783 * They are passed together with the event handler itself to SCIP using SCIPincludeEventhdlr() or SCIPincludeEventhdlrBasic(),
5784 * see @ref EVENT_INTERFACE.
5785 *
5786 *
5787 * Event handler plugins have only one fundamental callback method, namely the \ref EVENTEXEC method. This method has
5788 * to be implemented for every event handler; the other callback methods are optional. In the C++ wrapper class
5789 * scip::ObjEventhdlr, the scip_exec() method (which corresponds to the \ref EVENTEXEC callback) is a virtual abstract member
5790 * function. You have to implement it in order to be able to construct an object of your event handler class.
5791 *
5792 * Additional documentation for the callback methods can be found in type_event.h.
5793 *
5794 * @subsection EVENTEXEC
5795 *
5796 * The EVENTEXEC callback is called after the requested event happened. Then the event handler can do some action in
5797 * reaction to the event.
5798 *
5799 * Typical the execution method sets a parameter to TRUE to indicate later in solving process that something happened
5800 * which should be analyzed further. In the \ref cons_knapsack.h "knapsack constraint handler" you find such a typical
5801 * example.
5802 *
5803 * @section EVENT_ADDITIONALCALLBACKS Additional Callback Methods of a Event Handler
5804 *
5805 * The additional callback methods do not need to be implemented in every case. However, some of them have to be
5806 * implemented for most applications, they can be used, for example, to initialize and free private data.
5807 * Additional callbacks can either be passed directly with SCIPincludeEventhdlr() to SCIP or via specific
5808 * <b>setter functions</b> after a call of SCIPincludeEventhdlrBasic(), see also @ref EVENT_INTERFACE.
5809 *
5810 * @subsection EVENTCOPY
5811 *
5812 * The EVENTCOPY callback is executed when a SCIP instance is copied, e.g. to solve a sub-SCIP. By defining this
5813 * callback as <code>NULL</code> the user disables the execution of the specified event handler for all copied SCIP
5814 * instances. Note that in most cases the event handler in the copied instance will be initialize by those objects (such
5815 * as constraint handlers or propagators) which need this event handler (see \ref cons_knapsack.h). In these cases the copy
5816 * callback can be ignored. In case of general events, such as a new best solution being found
5817 * (SCIP_EVENTTYPE_BESTSOLFOUND), you might want to implement that callback. The event handler example which you find
5818 * in the directory "examples/Eventhdlr/" uses that callback.
5819 *
5820 * @refsnippet{src/scip/event_softtimelimit.c,SnippetEventCopySofttimelimit}
5821 *
5822 * @subsection EVENTFREE
5823 *
5824 * If you are using event handler data, you have to implement this method in order to free the event handler data.
5825 * This can be done by the following procedure:
5826 *
5827 * @refsnippet{src/scip/event_softtimelimit.c,SnippetEventFreeSofttimelimit}
5828 *
5829 * If you have allocated memory for fields in your event handler data, remember to free this memory
5830 * before freeing the event handler data itself.
5831 * If you are using the C++ wrapper class, this method is not available.
5832 * Instead, just use the destructor of your class to free the member variables of your class.
5833 *
5834 *
5835 * @subsection EVENTINIT
5836 *
5837 * The EVENTINIT callback is executed after the problem is transformed.
5838 * The event handler may, e.g., use this call to initialize its event handler data.
5839 *
5840 * @subsection EVENTEXIT
5841 *
5842 * The EVENTEXIT callback is executed before the transformed problem is freed.
5843 * In this method, the event handler should free all resources that have been allocated for the solving process in
5844 * \ref EVENTINIT.
5845 *
5846 * @subsection EVENTINITSOL
5847 *
5848 * The EVENTINITSOL callback is executed when the presolving is finished and the branch-and-bound process is about to
5849 * begin. The event handler may use this call to initialize its branch-and-bound specific data.
5850 *
5851 * @subsection EVENTEXITSOL
5852 *
5853 * The EVENTEXITSOL callback is executed before the branch-and-bound process is freed. The event handler should use this
5854 * call to clean up its branch-and-bound specific data.
5855 *
5856 * @section EVENTUSAGE Catching and Dropping Events
5857 *
5858 * After you have implemented the event handler, you have to tell SCIP for which events this event handler should be
5859 * used. This can be a general events, such as <code>SCIP_EVENTTYPE_BESTSOLFOUND</code>, or a variable event which is the most common
5860 * way.
5861 *
5862 * In case of a general (not variable) event you use the function SCIPcatchEvent() to attach to an event and
5863 * SCIPdropEvent() to release this event later.
5864 *
5865 * \code
5866 * SCIP_CALL( SCIPcatchEvent( scip, SCIP_EVENTTYPE_BESTSOLFOUND, eventhdlr, NULL, NULL) );
5867 * \endcode
5868 *
5869 * \code
5870 * SCIP_CALL( SCIPdropEvent( scip, SCIP_EVENTTYPE_BESTSOLFOUND, eventhdlr, NULL, NULL) );
5871 * \endcode
5872 *
5873 * If you want trigger some variable event, you use the method SCIPcatchVarEvent() to attach the variable event and
5874 * SCIPdropVarEvent() to drop it later.
5875 *
5876 * \code
5877 * SCIP_CALL( SCIPcatchVarEvent( scip, var, SCIP_EVENTTYPE_VARFIXED, eventhdlr, NULL, NULL) );
5878 * \endcode
5879 *
5880 * \code
5881 * SCIP_CALL( SCIPdropVarEvent( scip, var, SCIP_EVENTTYPE_VARFIXED, eventhdlr, NULL, NULL) );
5882 * \endcode
5883 *
5884 * @section EVENTTYPES Event types
5885 *
5886 * All available events are listed in type_event.h. There are atomic events such as <code>SCIP_EVENTTYPE_VARFIXED</code>
5887 * and combined events such as <code>SCIP_EVENTTYPE_VARCHANGED</code>. The events are encoded via bit masks. Each atomic
5888 * event has a unique power of two. This enables combination of the atomic events.
5889 *
5890 * SCIP only throws atomic events. However, an event handler might be interested in bunch of events. Through the
5891 * underlying bit masks it is possible to combine the atomic events. For example, <code>SCIP_EVENTTYPE_VARCHANGED</code>
5892 * is an event which combines the events <code>SCIP_EVENTTYPE_VARFIXED</code>, <code>SCIP_EVENTTYPE_VARUNLOCKED</code>,
5893 * <code>SCIP_EVENTTYPE_OBJCHANGED</code>, <code>SCIP_EVENTTYPE_GBDCHANGED</code>,
5894 * <code>SCIP_EVENTTYPE_DOMCHANGED</code>, and <code>SCIP_EVENTTYPE_IMPLADDED</code>.
5895 *
5896 * \code
5897 * #define SCIP_EVENTTYPE_VARCHANGED (SCIP_EVENTTYPE_VARFIXED | SCIP_EVENTTYPE_VARUNLOCKED | SCIP_EVENTTYPE_OBJCHANGED
5898 * | SCIP_EVENTTYPE_GBDCHANGED | SCIP_EVENTTYPE_DOMCHANGED | SCIP_EVENTTYPE_IMPLADDED)
5899 * \endcode
5900 *
5901 * Depending on the event type, the event offers different information. The methods which can be used to gain
5902 * access to this information are given in pub_event.h.
5903 *
5904 */
5905
5906/*--+----1----+----2----+----3----+----4----+----5----+----6----+----7----+----8----+----9----+----0----+----1----+----2*/
5907
5908/**@page NLPI How to add interfaces to nonlinear programming solvers
5909 *
5910 * NLPIs are used to interface a solver for nonlinear programs (NLP).
5911 * It is used, e.g., to solve convex relaxations of the problem or to find locally optimal solutions of
5912 * nonlinear relaxations or subproblems.
5913 * The NLPI has been designed such that it can be used independently of a SCIP problem.
5914 *
5915 * While the NLPI itself corresponds to the solver interface, the NLPIPROBLEM corresponds to the
5916 * (solver specific) representation of a concrete nonlinear program.
5917 * An NLP is specified as a set of indexed variables with variable bounds, an objective function,
5918 * and a set of constraints, where each constraint is specified as a function which is restricted to lie
5919 * between given left and right hand sides (possibly infinite).
5920 * A function consists of a linear and a nonlinear part.
5921 * The linear part is specified via variable indices and coefficients, while the nonlinear part is specified via an expression.
5922 * That is, the user of the NLPI does not provide function evaluation callbacks but an algebraic representation of the NLP.
5923 * Interfaces for solvers that require function evaluations can make use of the \ref NLPIOracle "NLPIORACLE", which
5924 * provides functionality to store a NLP and compute functions values, gradients, Jacobians, and Hessians.
5925 * See the interface to Ipopt for an example on how to use the NLPIORACLE.
5926 *
5927 * A complete list of all NLPIs contained in this release can be found \ref NLPIS "here".
5928 *
5929 * We now explain how users can add their own NLP solver interface.
5930 * Take the interface to Ipopt (src/scip/nlpi_ipopt.cpp) as an example.
5931 * Unlike most other plugins, it is written in C++.
5932 * Additional documentation for the callback methods of an NLPI, in particular for their input parameters,
5933 * can be found in the file \ref type_nlpi.h.
5934 *
5935 * Here is what you have to do to implement an NLPI:
5936 * -# Copy the template files src/scip/nlpi_xyz.c and src/scip/nlpi_xyz.h into files named "nlpi_mysolver.c" and "nlpi_mysolver.h".
5937 * Make sure to adjust your build system such that these files are compiled and linked to your project. \n
5938 * If you are adding a new default plugin, this means updating the `src/CMakeLists.txt` and `Makefile` files in the SCIP distribution.
5939 * -# Use `SCIPincludeNlpSolverMysolver()` in order to include the NLPI into your SCIP instance,
5940 * e.g., in the main file of your project (see, e.g., src/cmain.c in the Binpacking example). \n
5941 * If you are adding a new default plugin, this include function must be added to `src/scipdefplugins.c`.
5942 * -# Open the new files with a text editor and replace all occurrences of "xyz" by "mysolver".
5943 * -# Adjust the properties of the nlpi (see \ref NLPI_PROPERTIES).
5944 * -# Define the NLPI and NLPIPROBLEM data (see \ref NLPI_DATA).
5945 * -# Implement the interface methods (see \ref NLPI_INTERFACE).
5946 * -# Implement the fundamental callback methods (see \ref NLPI_FUNDAMENTALCALLBACKS).
5947 * -# Implement the additional callback methods (see \ref NLPI_ADDITIONALCALLBACKS). This is optional.
5948 *
5949 *
5950 * @section NLPI_PROPERTIES Properties of an NLPI
5951 *
5952 * At the top of the new file "nlpi_mysolver.c", you can find the NLPI properties.
5953 * These are given as compiler defines.
5954 * The properties you have to set have the following meaning:
5955 *
5956 * \par NLPI_NAME: the name of the NLP solver interface.
5957 * This name is used in the interactive shell to address the NLPI.
5958 * Additionally, if you are searching for an NLPI with SCIPfindNlpi(), this name is looked up.
5959 * Names have to be unique: no two NLPIs may have the same name.
5960 *
5961 * \par NLPI_DESC: the description of the NLPI.
5962 * This string is printed as a description of the NLPI in the interactive shell.
5963 *
5964 * \par NLPI_PRIORITY: the priority of the NLPI.
5965 * If an NLP has to be solved, an NLP solver has to be selected.
5966 * By default, the solver with the NLPI with highest priority is selected.
5967 * The priority of an NLPI should be set according to performance of the solver:
5968 * solvers that provide fast algorithms that are usually successful on a wide range of problems should have a high priority.
5969 * An easy way to list the priorities of all NLPIs is to type "display nlpis" in the interactive shell of SCIP.
5970 *
5971 * @section NLPI_DATA NLPI Data
5972 *
5973 * Below the header "Data structures" you can find structs which are called `struct SCIP_NlpiData` and `struct SCIP_NlpiProblem`.
5974 * In these data structures, you can store the data of your solver interface and of a specific NLP problem.
5975 * For example, you could store a pointer to your NLP solver environment object in the `SCIP_NlpiData` data structure
5976 * and store a pointer to an NLPIORACLE in the `SCIP_NlpiProblem` data structure.
5977 *
5978 * @section NLPI_INTERFACE Interface Methods
5979 *
5980 * At the bottom of "nlpi_mysolver.c", you can find the interface method SCIPincludeNlpSolverXyz(),
5981 * which also appears in "nlpi_mysolver.h".
5982 *
5983 * This method only has to be adjusted slightly.
5984 * It is responsible for creating an NLPI that contains all properties and callback methods of your
5985 * solver interface and included it into SCIP by calling the method SCIPincludeNlpi().
5986 * SCIPincludeNlpSolverXyz() is called by the user (e.g., SCIP), if (s)he wants to use this solver interface in his/her application.
5987 *
5988 * If you are using NLPI data, you have to allocate the memory for the data at this point.
5989 * You can do this by calling:
5990 * \code
5991 * SCIP_CALL( SCIPallocBlockMemory(scip, &nlpidata) );
5992 * \endcode
5993 * You also have to initialize the fields in struct SCIP_NlpiData afterwards. For freeing the
5994 * NLPI data, see \ref NLPIFREE.
5995 *
5996 *
5997 * @section NLPI_FUNDAMENTALCALLBACKS Fundamental Callback Methods of an NLPI
5998 *
5999 * The fundamental callback methods of the plugins are the ones that have to be implemented in order to obtain
6000 * an operational algorithm. Most NLPI callbacks are fundamental.
6001 *
6002 * Additional documentation of the callback methods, in particular to their input parameters,
6003 * can be found in \ref type_nlpi.h.
6004 *
6005 * @subsection NLPIFREE
6006 *
6007 * The NLPIFREE callback is executed if the NLP solver interface data structure should be freed, e.g., when a SCIP instance is freed.
6008 *
6009 * @subsection NLPICREATEPROBLEM
6010 *
6011 * The NLPICREATEPROBLEM callback is executed if a particular NLP problem is to be created.
6012 * The callback method should initialize a SCIP_NlpiProblem struct here that corresponds to an empty NLP.
6013 *
6014 * @subsection NLPIFREEPROBLEM
6015 *
6016 * The NLPIFREEPROBLEMPOINTER callback is executed if a particular NLP problem is to be freed.
6017 * The callback method should free a SCIP_NlpiProblem struct here.
6018 *
6019 * @subsection NLPIADDVARS
6020 *
6021 * The NLPIADDVARS callback is executed if a set of variables with lower and upper bounds and names should be added to a particular NLP.
6022 * The callback method must add the new variables behind the previously added variables, if any.
6023 * If NULL is given for the lower bounds arguments, -infinity is assumed as lower bound for each new variable.
6024 * If NULL is given for the upper bounds arguments, +infinity is assumed as upper bound for each new variable.
6025 * It is also permitted to use NULL for the names argument.
6026 *
6027 * @subsection NLPIADDCONSTRAINTS
6028 *
6029 * The NLPIADDCONSTRAINTS callback is executed if a set of constraints should be added to a particular NLP.
6030 * Constraints are specified by providing left- and right-hand-sides, linear coefficients, expressions, and constraint names.
6031 * All of these arguments are optional, giving NULL for left-hand-sides corresponds to -infinity, giving NULL for right-hand-sides corresponds to +infinity.
6032 *
6033 * @subsection NLPISETOBJECTIVE
6034 *
6035 * The NLPISETOBJECTIVE callback is executed to set the objective function of a particular NLP.
6036 *
6037 * @subsection NLPICHGVARBOUNDS
6038 *
6039 * The NLPICHGVARBOUNDS callback is executed to change the bounds on a set of variables of an NLP.
6040 *
6041 * @subsection NLPICHGCONSSIDES
6042 *
6043 * The NLPICHGCONSSIDES callback is executed to change the sides on a set of constraints of an NLP.
6044 *
6045 * @subsection NLPIDELVARSET
6046 *
6047 * The NLPIDELVARSET callback is executed to delete a set of variables from an NLP.
6048 * The caller provides an array in which for each variable it is marked whether it should be deleted.
6049 * In the same array, the method should return the new position of each variable in the NLP, or -1 if it was deleted.
6050 *
6051 * @subsection NLPIDELCONSSET
6052 *
6053 * The NLPIDELCONSSET callback is executed to delete a set of constraints from an NLP.
6054 * The caller provides an array in which for each constraint it is marked whether it should be deleted.
6055 * In the same array, the method should return the new position of each constraint in the NLP, or -1 if it was deleted.
6056 *
6057 * @subsection NLPICHGLINEARCOEFS
6058 *
6059 * The NLPICHGLINEARCOEFS callback is executed to change the coefficients in the linear part of the objective function or a constraint of an NLP.
6060 *
6061 * @subsection NLPICHGEXPR
6062 *
6063 * The NLPICHGEXPR callback is executed to replace the expression of the objective function or a constraint of an NLP.
6064 *
6065 * @subsection NLPICHGOBJCONSTANT
6066 *
6067 * The NLPICHGOBJCONSTANT callback is executed to change the constant offset of the objective function of an NLP.
6068 *
6069 * @subsection NLPISOLVE
6070 *
6071 * The NLPISOLVE callback is executed when an NLP should be solved.
6072 * The solver may use the initial guess provided by \ref NLPISETINITIALGUESS as starting point.
6073 * The status of the solving process and solution can be requested by
6074 * \ref NLPIGETSOLSTAT, \ref NLPIGETTERMSTAT, \ref NLPIGETSOLUTION, and \ref NLPIGETSTATISTICS.
6075 *
6076 * @subsection NLPIGETSOLSTAT
6077 *
6078 * The NLPIGETSOLSTAT callback can be used to request the solution status (solved, infeasible, ...) after an NLP has been solved.
6079 *
6080 * @subsection NLPIGETTERMSTAT
6081 *
6082 * The NLPIGETTERMSTAT callback can be used to request the termination reason (normal, iteration limit, ...) after an NLP has been solved.
6083 *
6084 * @subsection NLPIGETSOLUTION
6085 *
6086 * The NLPIGETSOLUTION callback can be used to request the primal and dual solution values after an NLP solve.
6087 * The method should pass pointers to arrays of variable values to the caller.
6088 * It is possible to return only primal values for the variables, but no values for the dual variables, e.g., if a solver does not compute such values.
6089 *
6090 * @subsection NLPIGETSTATISTICS
6091 *
6092 * The NLPIGETSTATISTICS callback can be used to request the statistical values (number of iterations, time, ...) after an NLP solve.
6093 * The method should fill the provided NLPSTATISTICS data structure.
6094 *
6095 * @section NLPI_ADDITIONALCALLBACKS Additional Callback Methods of an NLPI
6096 *
6097 * The additional callback methods do not need to be implemented in every case.
6098 *
6099 * @subsection NLPICOPY
6100 *
6101 * The NLPICOPY callback is executed if the plugin should be copied, e.g., when a SCIP instance is copied.
6102 *
6103 * It is advisable to implement this callback to make the NLP solver available in sub-SCIPs.
6104 * Note that the sub-NLP heuristic solves NLPs in a sub-SCIP.
6105 *
6106 * @subsection NLPIGETSOLVERPOINTER
6107 *
6108 * The NLPIGETSOLVERPOINTER callback can be used to pass a pointer to a solver specific data structure to the user.
6109 * Return NULL if you do not have a pointer to return.
6110 *
6111 * @subsection NLPIGETPROBLEMPOINTER
6112 *
6113 * The NLPIGETPROBLEMPOINTER callback can be used to pass a pointer to a solver specific data structure of the NLP to the user.
6114 *
6115 * @subsection NLPISETINITIALGUESS
6116 *
6117 * The NLPISETINITIALGUESS callback is executed to provide primal and dual initial values for the variables and constraints of an NLP.
6118 * For a local solver, it is strongly advisable to implement this callback, as these values should be used as a starting point for the search.
6119 * It is possible to pass a NULL pointer for any of the arguments (primal values of variables, dual values of variable bounds, dual values of constraints).
6120 * In this case, the solver should clear previously set starting values and setup its own starting point.
6121 *
6122 */
6123
6124/*--+----1----+----2----+----3----+----4----+----5----+----6----+----7----+----8----+----9----+----0----+----1----+----2*/
6125
6126/**@page EXPRINT How to add interfaces to expression interpreters
6127 *
6128 * An expression interpreter is a tool to compute point-wise the function values, gradients, and
6129 * Hessians of algebraic expressions which are given in the form of an expression.
6130 * Typically, this is done via automatic differentiation.
6131 * It is used, e.g., by an NLP solver interface to compute Jacobians and Hessians for the solver.
6132 *
6133 * The expression interpreter interface in SCIP has been implemented similar to those of the LP solver interface (LPI).
6134 * For one binary, exactly one expression interpreter has to be linked.
6135 * The expression interpreter API has been designed such that it can be used independently from a SCIP problem.
6136 *
6137 * A complete list of all expression interpreters contained in this release can be found \ref EXPRINTS "here".
6138 *
6139 * We now explain how users can add their own expression interpreters.
6140 * Take the interface to CppAD (\ref exprinterpret_cppad.cpp) as an example.
6141 * Unlike most other plugins, it is written in C++.
6142 *
6143 * Additional documentation for the callback methods of an expression interpreter, in particular for their input parameters,
6144 * can be found in the file \ref exprinterpret.h.
6145 *
6146 * Here is what you have to do to implement an expression interpreter:
6147 * -# Copy the file \ref exprinterpret_none.c into a file named "exprinterpret_myad.c".
6148 * Make sure to adjust your build system such that this file is compiled and linked to your project instead of exprinterpret implementations. \n
6149 * If you are adding a new default plugin, this means updating the `src/CMakeLists.txt` and `Makefile` files in the SCIP distribution.
6150 * -# Open the new file with a text editor.
6151 * -# Define the expression interpreter data (see \ref EXPRINT_DATA).
6152 * -# Implement the interface methods (see \ref EXPRINT_INTERFACE).
6153 *
6154 *
6155 * @section EXPRINT_DATA Expression Interpreter Data
6156 *
6157 * In `struct SCIP_ExprInt`, you can store the general data of your expression interpreter.
6158 * For example, you could store the environment of your automatic differentiation code.
6159 *
6160 * @section EXPRINT_INTERFACE Interface Methods
6161 *
6162 * The expression interpreter has to implement a set of interface method.
6163 * In your "exprinterpret_myad.c", these methods are mostly dummy methods that return error codes.
6164 *
6165 * @subsection SCIPexprintGetName
6166 *
6167 * The SCIPexprintGetName() method should return the name of the expression interpreter.
6168 *
6169 * @subsection SCIPexprintGetDesc
6170 *
6171 * The SCIPexprintGetDesc() method should return a short description of the expression interpreter, e.g., the name of the developer of the code.
6172 *
6173 * @subsection SCIPexprintGetCapability
6174 *
6175 * The SCIPexprintGetCapability() method should return a bitmask that indicates the capabilities of the expression interpreter,
6176 * i.e., whether it can compute gradients and Hessians.
6177 *
6178 * @subsection SCIPexprintCreate
6179 *
6180 * The SCIPexprintCreate() method is called to create an expression interpreter data structure.
6181 * The method should initialize a `struct SCIP_ExprInt` here.
6182 *
6183 * @subsection SCIPexprintFree
6184 *
6185 * The SCIPexprintFree() method is called to free an expression interpreter data structure.
6186 * The method should free a `struct SCIP_ExprInt` here.
6187 *
6188 * @subsection SCIPexprintCompile
6189 *
6190 * The SCIPexprintCompile() method is called to initialize the data structures that are required to evaluate a particular expression.
6191 * The expression interpreter can create and return data that is particular to a given expression in the argument `exprintdata`.
6192 *
6193 * @subsection SCIPexprintFreeData
6194 *
6195 * The SCIPexprintFreeData() method is called to free the data that is particular to a given expression and was possibly created in SCIPexprintCompile().
6196 *
6197 * @subsection SCIPexprintGetExprCapability
6198 *
6199 * The SCIPexprintGetExprCapability() method is called to request the capability to evaluate a specific expression by the expression interpreter.
6200 *
6201 * In cases of user-given expressions, higher order derivatives may not be available for the user-expression,
6202 * even if the expression interpreter could handle these. This method allows to recognize that, e.g., the
6203 * Hessian for an expression is not available because it contains a user expression that does not provide
6204 * Hessians.
6205 *
6206 * @subsection SCIPexprintEval
6207 *
6208 * The SCIPexprintEval() method is called when the value of an expression should be computed for a point.
6209 *
6210 * @subsection SCIPexprintGrad
6211 *
6212 * The SCIPexprintGrad() method is called when the gradient of an expression represented by an expression should be computed for a point.
6213 *
6214 * @subsection SCIPexprintHessianSparsity
6215 *
6216 * The SCIPexprintHessianSparsity() method is called when the sparsity structure of the Hessian matrix should be computed and returned.
6217 * Only the position of nonzero entries in the lower-triangular part of Hessian should be reported.
6218 *
6219 * @subsection SCIPexprintHessian
6220 *
6221 * The SCIPexprintHessian() method is called when the Hessian of an expression should be computed for a point.
6222 */
6223
6224/*--+----1----+----2----+----3----+----4----+----5----+----6----+----7----+----8----+----9----+----0----+----1----+----2*/
6225
6226/**@page TABLE How to add statistics tables
6227 *
6228 * After solving a constraint integer program, SCIP can display statistics tables with information about, e.g., the solving time,
6229 * number of nodes, LP iterations or the number of calls and successes of different plugins via "display statistics" in the shell
6230 * or via SCIPprintStatistics() in the C-interface. There already exists a wide variety of statistics tables which can be activated
6231 * or deactivated on demand, see src/scip/table_default.c. Additionally, the user can implement his/her own statistics tables
6232 * in order to display problem or algorithm specific values.
6233 * \n
6234 * A complete list of all statistics tables contained in this release can be found \ref TABLES "here".
6235 *
6236 * We now explain how users can add their own statistics tables.
6237 * We give the explanation for creating your own source file for each additional statistics table. Of course, you can collect
6238 * different additional statistics tables in one source file.
6239 * Take src/scip/table_default.c, where all default statistics tables are collected, as an example.
6240 * As all other default plugins, the default statistics table plugins and the statistics table template are written in C.
6241 * C++ users can easily adapt the code by using the scip::ObjTable wrapper base class and implement the scip_...() virtual methods
6242 * instead of the SCIP_DECL_TABLE... callback methods.
6243 *
6244 *
6245 * Additional documentation for the callback methods of a statistics table can be found in the file type_table.h.
6246 *
6247 * Here is what you have to do to implement a statistics table (assuming your statistics table is named "mystatisticstable"):
6248 * -# Copy the template files src/scip/table_xyz.c and src/scip/table_xyz.h into files named "table_mystatisticstable.c"
6249 * and "table_mystatisticstable.h".
6250 * \n
6251 * Make sure to adjust your build system such that these files are compiled and linked to your project. \n
6252 * If you are adding a new default plugin, this means updating the `src/CMakeLists.txt` and `Makefile` files in the SCIP distribution.
6253 * -# Use SCIPincludeTableMystatisticstable() in order to include the statistics table into your SCIP instance,
6254 * e.g., in the main file of your project (see, e.g., src/cmain.c in the Binpacking example). \n
6255 * If you are adding a new default plugin, this include function must be added to `src/scipdefplugins.c`.
6256 * -# Open the new files with a text editor and replace all occurrences of "xyz" by "mystatisticstable".
6257 * -# Adjust the \ref TABLE_PROPERTIES "properties of the statistics table".
6258 * -# Define the \ref TABLE_DATA "statistics table data". This is optional.
6259 * -# Implement the \ref TABLE_INTERFACE "interface methods".
6260 * -# Implement the \ref TABLE_FUNDAMENTALCALLBACKS "fundamental callback methods".
6261 * -# Implement the \ref TABLE_ADDITIONALCALLBACKS "additional callback methods". This is optional.
6262 *
6263 *
6264 * @section TABLE_PROPERTIES Properties of a Statistics Table
6265 *
6266 * At the top of the new file "table_mystatisticstable.c" you can find the statistics table properties.
6267 * These are given as compiler defines.
6268 * In the C++ wrapper class, you have to provide the statistics table properties by calling the constructor
6269 * of the abstract base class scip::ObjTable from within your constructor.
6270 * The properties you have to set have the following meaning:
6271 *
6272 * \par TABLE_NAME: the name of the statistics table.
6273 * This name is used in the interactive shell to address the statistics table.
6274 * Additionally, if you are searching for a statistics table with SCIPfindTable(), this name is looked up.
6275 * Names have to be unique: no two statistic tables may have the same name.
6276 *
6277 * \par TABLE_DESC: the description of the statistics table.
6278 * This string is printed as a description of the statistics table in the interactive shell.
6279 *
6280 * \par TABLE_POSITION: the position of the statistics table.
6281 * In the statistics output, the statistics tables will be ordered by increasing position. Compare with the
6282 * default statistics tables in "table_default.c" to find a value which will give you the desired position
6283 * between the default statistics tables. If you give your table a negative position value, it will appear
6284 * before all SCIP statistcs, with a value larger than 20000 it will appear after all default statistics.
6285 *
6286 * \par TABLE_EARLIEST_STAGE: output of the statistics table is only printed from this stage onwards
6287 * The output routine of your statistics table will only be called if SCIP has reached this stage. For
6288 * example, the default table "tree" will only output information starting from SCIP_STAGE_SOLVING, because
6289 * there is no meaningful information available before, while the "presolver" table can already be called
6290 * in SCIP_STAGE_TRANSFORMED.
6291 *
6292 * @section TABLE_DATA Statistics Table Data
6293 *
6294 * Below the header "Data structures" you can find a struct which is called "struct SCIP_TableData".
6295 * In this data structure, you can store the data of your statistics table. For example, you should store the adjustable
6296 * parameters of the statistics table in this data structure.
6297 * If you are using C++, you can add statistics table data as usual as object variables to your class.
6298 * \n
6299 * Defining statistics table data is optional. You can leave the struct empty.
6300 *
6301 *
6302 * @section TABLE_INTERFACE Interface Methods
6303 *
6304 * At the bottom of "table_mystatisticstable.c" you can find the interface method SCIPincludeTableMystatisticstable(), which also
6305 * appears in "table_mystatisticstable.h".
6306 * \n
6307 * This method only has to be adjusted slightly.
6308 * It is responsible for notifying SCIP of the presence of the statistics table by calling the method
6309 * SCIPincludeTable().
6310 *
6311 * The interface method is called by the user, if (s)he wants to include the statistics table, i.e., if (s)he wants to use the statistics table in an
6312 * application.
6313 *
6314 * If you are using statistics table data, you have to allocate the memory for the data at this point.
6315 * You can do this by calling:
6316 * \code
6317 * SCIP_CALL( SCIPallocBlockMemory(scip, &tabledata) );
6318 * \endcode
6319 * You also have to initialize the fields in struct SCIP_TableData afterwards.
6320 *
6321 * Although this is very uncommon, you may also add user parameters for your statistics table, see the method
6322 * SCIPincludeConshdlrKnapsack() in the \ref cons_knapsack.h "knapsack constraint handler" for an example.
6323 *
6324 *
6325 * @section TABLE_FUNDAMENTALCALLBACKS Fundamental Callback Methods of a Statistics Table
6326 *
6327 * Statistics table plugins have only one fundamental callback method, namely the \ref TABLEOUTPUT method.
6328 * This method has to be implemented for every display column; the other callback methods are optional.
6329 * In the C++ wrapper class scip::ObjTable, the scip_output() method (which corresponds to the \ref TABLEOUTPUT callback) is a virtual
6330 * abstract member function.
6331 * You have to implement it in order to be able to construct an object of your statistics table class.
6332 *
6333 * Additional documentation for the callback methods can be found in type_table.h.
6334 *
6335 * @subsection TABLEOUTPUT
6336 *
6337 * The TABLEOUTPUT callback is called whenever SCIP is asked to print statistics (because the user typed "display statistics"
6338 * in the shell or called SCIPprintStatistics()). In this callback, the table should print all of its information to the given file
6339 * (which may be NULL if the output should be printed to the console).
6340 *
6341 * Typical methods called by a statistics table are, for example, SCIPdispLongint(), SCIPdispInt(), SCIPdispTime(), and
6342 * SCIPinfoMessage().
6343 *
6344 *
6345 * @section TABLE_ADDITIONALCALLBACKS Additional Callback Methods of a Statistics Table
6346 *
6347 * The additional callback methods do not need to be implemented in every case.
6348 * They can be used, for example, to initialize and free private data.
6349 *
6350 * @subsection TABLECOPY
6351 *
6352 * The TABLECOPY callback is executed when a SCIP instance is copied, e.g. to solve a sub-SCIP. By defining this callback
6353 * as <code>NULL</code> the user disables the execution of the specified column. In general it is probably not needed to
6354 * implement that callback since the output of the copied instance is usually suppressed. In the other case or for
6355 * debugging the callback should be implement.
6356 *
6357 *
6358 * @subsection TABLEFREE
6359 *
6360 * If you are using statistics table data, you have to implement this method in order to free the statistics table data.
6361 * This can be done by the following procedure:
6362 * @refsnippet{tests/src/misc/snippets.c,SnippetTableFree}
6363 *
6364 * If you have allocated memory for fields in your statistics table data, remember to free this memory
6365 * before freeing the statistics table data itself.
6366 * If you are using the C++ wrapper class, this method is not available.
6367 * Instead, just use the destructor of your class to free the member variables of your class.
6368 *
6369 * @subsection TABLEINIT
6370 *
6371 * The TABLEINIT callback is executed after the problem is transformed.
6372 * The statistics table may, e.g., use this call to initialize its statistics table data.
6373 *
6374 * @subsection TABLEEXIT
6375 *
6376 * The TABLEEXIT callback is executed before the transformed problem is freed.
6377 * In this method, the statistics table should free all resources that have been allocated for the solving process in
6378 * \ref TABLEINIT.
6379 *
6380 * @subsection TABLEINITSOL
6381 *
6382 * The TABLEINITSOL callback is executed when the presolving is finished and the branch-and-bound process is about to
6383 * begin. The statistics table may use this call to initialize its branch-and-bound specific data.
6384 *
6385 * @subsection TABLEEXITSOL
6386 *
6387 * The TABLEEXITSOL callback is executed before the branch-and-bound process is freed. The statistics table should use this
6388 * call to clean up its branch-and-bound specific data.
6389 */
6390
6391/*--+----1----+----2----+----3----+----4----+----5----+----6----+----7----+----8----+----9----+----0----+----1----+----2*/
6392
6393/**@page BENDER How to add custom Benders' decomposition implementations
6394 *
6395 * Benders' decomposition is a very popular mathematical programming technique that is applied to solve structured
6396 * problems. Problems that display a block diagonal structure are particularly amenable to the application of Benders'
6397 * decomposition. Such problems are given by
6398 *
6399 * \f[
6400 * \begin{array}[t]{rllclcl}
6401 * \min & \displaystyle & c^{T}x & + & d^{T}y \\
6402 * & \\
6403 * subject \ to & \displaystyle & Ax & & & = & b \\
6404 * & \\
6405 * & \displaystyle & Tx & + & Hy & = & h \\
6406 * & \\
6407 * & & x & & & \in & \mathbb{Z}^{p}\times\mathbb{R}^{n - p} \\
6408 * & & & & y & \in & \mathbb{R}^{m} \\
6409 * \end{array}
6410 * \f]
6411 *
6412 * The variables \f$x\f$ and \f$y\f$ are described as the first and second stage variables respectively. In the
6413 * classical use of Benders' decomposition, it is a requirement that the all second stage variables are continuous.
6414 * Extensions to the classical Benders' decomposition approach have permitted the use of more general second stage
6415 * problems.
6416 *
6417 * The application of Benders' decomposition to the above problem results in a subproblem, given by
6418 *
6419 * \f[
6420 * \begin{array}[t]{rll}
6421 * \min & \displaystyle & d^{T}y \\
6422 * & \\
6423 * subject \ to & \displaystyle & Hy = h - T\bar{x} \\
6424 * & \\
6425 * & & y \in \mathbb{R}^{m} \\
6426 * \end{array}
6427 * \f]
6428 *
6429 * where \f$\bar{x}\f$ is a solution vector of the first stage variables. As such, the subproblem is a problem only in
6430 * \f$y\f$. The dual solution to the subproblem, either an extreme point or extreme ray, is used to generate cuts that
6431 * are added to the master problem. Let \f$\lambda\f$ be the vector of dual variables associated with the set of
6432 * constraints from the subproblem. If, for a given \f$\bar{x}\f$, the subproblem is infeasible, then \f$\lambda\f$
6433 * corresponds to a dual ray and is used to produce the cut
6434 *
6435 * \f[
6436 * 0 \geq \lambda(h - Tx)
6437 * \f]
6438 *
6439 * which eliminates \f$\bar{x}\f$ from the master problem. If, for a given \f$\bar{x}\f$, the subproblem is feasible,
6440 * then \f$\lambda\f$ corresponds to a dual extreme point and is used to produce the cut
6441 *
6442 * \f[
6443 * \varphi \geq \lambda(h - Tx)
6444 * \f]
6445 *
6446 * where \f$\varphi\f$ is an auxiliary variable added to the master problem as an underestimator of the optimal
6447 * subproblem objective function value.
6448 *
6449 * Given \f$\Omega^{p}\f$ and \f$\Omega^{r}\f$ as the sets of dual extreme points and rays of the subproblem,
6450 * respectively, the Benders' decomposition master problem is given by
6451 *
6452 * \f[
6453 * \begin{array}[t]{rll}
6454 * \min & \displaystyle & c^{T}x + \varphi \\
6455 * & \\
6456 * subject \ to & \displaystyle & Ax = b \\
6457 * & \\
6458 * & \displaystyle & \varphi \geq \lambda(h - Tx) \quad \forall \lambda \in \Omega^{r}\\
6459 * & \\
6460 * & \displaystyle & 0 \geq \lambda(h - Tx) \quad \forall \lambda \in \Omega^{r} \\
6461 * & \\
6462 * & & x \in \mathbb{Z}^{p}\times\mathbb{R}^{n - p} \\
6463 * & & \varphi \in \mathbb{R} \\
6464 * \end{array}
6465 * \f]
6466 *
6467 * The Benders' decomposition framework of SCIP allows the user to provide a custom implementation of many aspects of
6468 * the Benders' decomposition algorithm. It is possible to implement multiple Benders' decompositions that work in
6469 * conjunction with each other. Such a situation is where you may have different formulations of the Benders'
6470 * decomposition subproblem.
6471 *
6472 * The current list of all Benders' decomposition implementations available in this release can be found \ref BENDERS
6473 * "here".
6474 *
6475 * We now explain how users can add their own Benders' decomposition implementations.
6476 * Take the default Benders' decomposition implementation (src/scip/benders_default.c) as an example. Same as all other
6477 * default plugins, it is written in C. C++ users can easily adapt the code by using the scip::ObjBenders wrapper base
6478 * class and implement the scip_...() virtual methods instead of the SCIP_DECL_BENDERS... callback methods.
6479 *
6480 * Additional documentation for the callback methods of a Benders' decomposition implementation, in particular for the
6481 * input parameters, can be found in the file type_benders.h.
6482 *
6483 * Here is what you have to do to implement a custom Benders' decomposition:
6484 * -# Copy the template files src/scip/benders_xyz.c and src/scip/benders_xyz.h into files "benders_mybenders.c" and
6485 * "benders_mybenders.h".
6486 \n
6487 * Make sure to adjust your build system such that these files are compiled and linked to your project. \n
6488 * If you are adding a new default plugin, this means updating the `src/CMakeLists.txt` and `Makefile` files in the SCIP distribution.
6489 * -# Use SCIPincludeBendersMybenders() in order to include the Benders' decomposition into your SCIP instance, e.g., in
6490 * the main file of your project (see, e.g., src/cmain.c in the Binpacking example). \n
6491 * If you are adding a new default plugin, this include function must be added to `src/scipdefplugins.c`.
6492 * -# Open the new files with a text editor and replace all occurrences of "xyz" by "mybenders".
6493 * -# Adjust the properties of the Benders' decomposition (see \ref BENDERS_PROPERTIES).
6494 * -# Define the Benders' decomposition data (see \ref BENDERS_DATA). This is optional.
6495 * -# Implement the interface methods (see \ref BENDERS_INTERFACE).
6496 * -# Implement the fundamental callback methods (see \ref BENDERS_FUNDAMENTALCALLBACKS).
6497 * -# Implement the additional callback methods (see \ref BENDERS_ADDITIONALCALLBACKS). This is optional.
6498 *
6499 *
6500 * @section BENDERS_PROPERTIES Properties of a Benders' decomposition
6501 *
6502 * At the top of the new file "benders_mybenders.c", you can find the Benders' decomposition properties.
6503 * These are given as compiler defines.
6504 * In the C++ wrapper class, you have to provide the Benders' decomposition properties by calling the constructor
6505 * of the abstract base class scip::ObjBenders from within your constructor.
6506 * The properties you have to set have the following meaning:
6507 *
6508 * \par BENDERS_NAME: the name of the Benders' decomposition.
6509 * This name is used in the interactive shell to address the Benders' decomposition.
6510 * Additionally, if you are searching for a Benders' decomposition with SCIPfindBenders(), this name is looked up.
6511 * Names have to be unique: no two Benders' decompositions may have the same name.
6512 *
6513 * \par BENDERS_DESC: the description of the Benders' decomposition.
6514 * This string is printed as a description of the Benders' decomposition in the interactive shell.
6515 *
6516 * \par BENDERS_PRIORITY: the priority of the Benders' decomposition.
6517 * During the enforcement and checking of solutions in src/scip/cons_benders.c and src/scip/cons_benderslp.c, every
6518 * active Benders' decompositions are called. The execution method of the Benders' decomposition calls each of the
6519 * subproblems and generates cuts from their solutions. So the active Benders' decompositions are called in order of
6520 * priority until a cut is generated or feasibility is proven.
6521 * \n
6522 * The priority of the Benders' decomposition should be set according to the difficulty of solving the subproblems and
6523 * the generation of cuts. However, it is possible to prioritise the Benders' decompositions with respect to the
6524 * strength of the subproblem formulation and the resulting cuts.
6525 *
6526 * \par BENDERS_CUTLP: should Benders' decomposition cuts be generated during the enforcement of LP solutions.
6527 * This is a flag that is used by src/scip/cons_benders.c and src/scip/cons_benderslp.c to idicate whether the
6528 * enforcement of LP solutions should involve solving the Benders' decomposition subproblems. This should be set to TRUE
6529 * to have an exact solution algorithm. In the presence of multiple Benders' decomposition, it may be desired to enforce
6530 * the LP solutions for only a subset of those implemented.
6531 *
6532 * \par BENDERS_CUTRELAX: should Benders' decomposition cuts be generated during the enforcement of relaxation solutions.
6533 * This is a flag that is used by src/scip/cons_benders.c and src/scip/cons_benderslp.c to idicate whether the
6534 * enforcement of relaxation solutions should involve solving the Benders' decomposition subproblems. This should be
6535 * set to TRUE to have an exact solution algorithm. In the presence of multiple Benders' decomposition, it may be desired
6536 * to enforce the relaxation solutions for only a subset of those implemented. This parameter will only take effect if
6537 * external relaxation have been implemented.
6538 *
6539 * \par BENDERS_CUTPSEUDO: should Benders' decomposition subproblems be solved during the enforcement of pseudo solutions.
6540 * This is a flag that is used by src/scip/cons_benders.c and src/scip/cons_benderslp.c to indicate whether the
6541 * enforcement of pseudo solutions should involve solving the Benders' decomposition subproblems. This should be set to
6542 * TRUE, since not enforcing pseudo solutions could result in an error or suboptimal result. During the enforcement of
6543 * pseudo solutions, no cuts are generated. Only a flag to indicate whether the solution is feasible or if the LP should
6544 * be solved again is returned.
6545 *
6546 * \par BENDERS_SHAREAUXVARS: should this Benders' decomposition use the auxiliary variables from the highest priority
6547 * Benders' decomposition.
6548 * This parameter only takes effect if multiple Benders' decompositions are implemented. Consider the case that two Benders'
6549 * decompositions are implemented with different formulations of the subproblem. Since the subproblems in each of the
6550 * decomposition will have the same optimal solution, then it is useful to only have a single auxiliary variable for the
6551 * two different subproblems. This means that when an optimality cut is generated in the lower priority Benders'
6552 * decomposition, the auxiliary variable from the highest priority Benders' decomposition will be added to the right
6553 * hand side.
6554 *
6555 * @section BENDERS_DATA Benders' decomposition Data
6556 *
6557 * Below the header "Data structures" you can find a struct which is called "struct SCIP_BendersData".
6558 * In this data structure, you can store the data of your Benders' decomposition. For example, you should store the adjustable
6559 * parameters of the Benders' decomposition in this data structure. In a Benders' decomposition, user parameters for the
6560 * number of subproblems and an array to store the subproblem SCIP instances could be useful.
6561 * \n
6562 * Defining Benders' decomposition data is optional. You can leave the struct empty.
6563 *
6564 * @section BENDERS_INTERFACE Interface Methods
6565 *
6566 * At the bottom of "benders_mybenders.c", you can find the interface method SCIPincludeBendersMybenders(),
6567 * which also appears in "benders_mybenders.h"
6568 * SCIPincludeBendersMybenders() is called by the user, if (s)he wants to include the Benders' decomposition,
6569 * i.e., if (s)he wants to use the Benders' decomposition in his/her application.
6570 *
6571 * This method only has to be adjusted slightly.
6572 * It is responsible for notifying SCIP of the presence of the Benders' decomposition. For this, you can either call SCIPincludeBenders(),
6573 * or SCIPincludeBendersBasic() since SCIP version 3.0. In the latter variant, \ref BENDERS_ADDITIONALCALLBACKS "additional callbacks"
6574 * must be added via setter functions as, e.g., SCIPsetBendersCopy(). We recommend this latter variant because
6575 * it is more stable towards future SCIP versions which might have more callbacks, whereas source code using the first
6576 * variant must be manually adjusted with every SCIP release containing new callbacks for Benders' decompositions in order to compile.
6577 *
6578 * If you are using Benders' decomposition data, you have to allocate the memory
6579 * for the data at this point. You can do this by calling:
6580 * \code
6581 * SCIP_CALL( SCIPallocBlockMemory(scip, &bendersdata) );
6582 * \endcode
6583 * You also have to initialize the fields in "struct SCIP_BendersData" afterwards. For freeing the
6584 * Benders' decomposition data, see \ref BENDERSFREE.
6585 *
6586 * You may also add user parameters for your Benders' decomposition, see \ref PARAM for how to add user parameters and
6587 * the method SCIPincludeBendersDefault() in src/scip/benders_default.c for an example.
6588 *
6589 * It is advised to disable presolving for the Benders' decomposition master problem by calling SCIPsetPresolving() with
6590 * the parameter SCIP_PARAMSETTING_OFF. Presolving should be disabled because reductions on the master problem could be
6591 * invalid since constraints have been transferred to the subproblems. It is not necessary to disable all presolving,
6592 * but care must be taken when it is used for the Benders' decomposition master problem.
6593 *
6594 * The Benders' decomposition constraint handler, see src/scip/cons_benders.c, includes a presolver for tightening the
6595 * bound on the auxiliary variables. This presolver can be enabled with by setting "presolving/maxround" to 1 and
6596 * "constraints/benders/maxprerounds" to 1. This presolver solves the Benders' decomposition subproblems without fixing
6597 * the master problem variables to find a lower bound for the auxiliary variable.
6598 *
6599 *
6600 * @section BENDERS_FUNDAMENTALCALLBACKS Fundamental Callback Methods of a Benders' decomposition
6601 *
6602 * The fundamental callback methods of the plugins are the ones that have to be implemented in order to obtain
6603 * an operational algorithm.
6604 * They are passed together with the Benders' decomposition itself to SCIP using SCIPincludeBenders() or SCIPincludeBendersBasic(),
6605 * see @ref BENDERS_INTERFACE.
6606 *
6607 * Benders' decomposition plugins have two callbacks, @ref BENDERSGETVAR and @ref BENDERSCREATESUB that must be implemented.
6608 *
6609 * Additional documentation for the callback methods, in particular to their input parameters,
6610 * can be found in type_benders.h.
6611 *
6612 * @subsection BENDERSGETVAR
6613 *
6614 * The BENDERSGETVAR callback provides a mapping between the master problem variables and their corresponding subproblem
6615 * variables, and vice versa. The parameters of this function include the variable for which the mapped variable is
6616 * desired and the problem number for the mapped variable. When requesting a subproblem variable for a given master
6617 * problem variable, the master variable is input with the appropriate subproblem index. If a master problem variable is
6618 * requested for a given subproblem variable, then the subproblem variable is input with the subproblem index given as
6619 * -1.
6620 *
6621 * An example of how to implement the mapping between the master and subproblem variables is shown by
6622 *
6623 * @refsnippet{src/scip/benders_default.c,SnippetBendersGetvarDefault}
6624 *
6625 * In the above code snippet, the hashmaps providing the mapping between the master and subproblem variables are
6626 * constructed in the <code>SCIP_STAGE_INIT</code> stage (see \ref BENDERSINIT).
6627 *
6628 * The requested variable is returned via the mappedvar parameter. There may not exist a corresponding master
6629 * (subproblem) variable for every input subproblem (master) variable. In such cases were no corresponding variable
6630 * exists, mappedvar must be returned as NULL.
6631 *
6632 * The mapped variables are retrieved by calling SCIPgetBendersMasterVar() and SCIPgetBendersSubproblemVar().
6633 *
6634 * The variable mapping must be created before <code>SCIP_STAGE_PRESOLVE</code> stage. This is because the variable
6635 * mapping is required for checking solutions found by heuristics during presolving.
6636 *
6637 * @subsection BENDERSCREATESUB
6638 *
6639 * The BENDERSCREATESUB callback is executed during the <code>SCIP_STAGE_INIT</code> stage. In this function, the
6640 * user must register the SCIP instances for each subproblem. The BENDERSCREATESUB callback is executed once for each
6641 * subproblem. The user registers a subproblem by calling SCIPbendersAddSubproblem().
6642 *
6643 * It is possible to build the SCIP instance for the subproblem during the execution of this callback. However, it may
6644 * be more convenient to build the subproblem instances during the problem creation stage of the master problem and
6645 * store the subproblem SCIP instances in SCIP_BendersData. This approach is used in src/scip/benders_default.c.
6646 *
6647 * @section BENDERS_ADDITIONALCALLBACKS Additional Callback Methods of a Benders' decomposition implementation
6648 *
6649 * The additional callback methods do not need to be implemented in every case. However, some of them have to be
6650 * implemented for most applications, they can be used, for example, to initialize and free private data.
6651 * Additional callbacks can either be passed directly with SCIPincludeBenders() to SCIP or via specific
6652 * <b>setter functions</b> after a call of SCIPincludeBendersBasic(), see also @ref BENDERS_INTERFACE.
6653 *
6654 * @subsection BENDERSFREE
6655 *
6656 * If you are using Benders' decomposition data (see \ref BENDERS_DATA and \ref BENDERS_INTERFACE), you have to
6657 * implement this method in order to free the Benders' decomposition data. This can be done by the following procedure:
6658 *
6659 * @refsnippet{src/scip/benders_default.c,SnippetBendersFreeDefault}
6660 *
6661 * If you have allocated memory for fields in your Benders' decomposition data, remember to free this memory
6662 * before freeing the Benders' decomposition data itself.
6663 * If you are using the C++ wrapper class, this method is not available.
6664 * Instead, just use the destructor of your class to free the member variables of your class.
6665 *
6666 * @subsection BENDERSCOPY
6667 *
6668 * The BENDERSCOPY callback is executed when a SCIP instance is copied, e.g. to
6669 * solve a sub-SCIP. By
6670 * defining this callback as
6671 * <code>NULL</code> the user disables the execution of the specified
6672 * separator for all copied SCIP instances. This may deteriorate the performance
6673 * of primal heuristics using sub-SCIPs.
6674 *
6675 * If a user wishes to employ the Large Neighbourhood Benders' Search, it is necessary for the BENDERSCOPY callback to
6676 * be implemented. This is required because the sub-SCIP instances of large neighbourhood search heuristics can only
6677 * access the implemented Benders' decomposition if it is copied via the BENDERSCOPY callback.
6678 *
6679 * @subsection BENDERSINIT
6680 *
6681 * The BENDERSINIT callback is executed after the problem is transformed.
6682 * The Benders' decomposition implementation may, e.g., use this call to initialize its Benders' decomposition data. In
6683 * src/scip/benders_default.c BENDERSINIT is used to create the mapping between the master and subproblem variables.
6684 * The difference between the original and the transformed problem is explained in
6685 * "What is this thing with the original and the transformed problem about?" on \ref FAQ.
6686 *
6687 * @subsection BENDERSEXIT
6688 *
6689 * The BENDERSEXIT callback is executed before the transformed problem is freed.
6690 * In this method, the Benders' decomposition implementation should free all resources that have been allocated for
6691 * the solving process in BENDERSINIT.
6692 *
6693 * @subsection BENDERSINITPRE
6694 *
6695 * The BENDERSINITPRE callback is executed before the preprocessing is started, even if presolving is turned off.
6696 * The Benders' decomposition may use this call to initialize its presolving data before the presolving process begins.
6697 *
6698 * @subsection BENDERSEXITPRE
6699 *
6700 * The BENDERSEXITPRE callback is executed after the preprocessing has been finished, even if presolving is turned off.
6701 * The Benders' decomposition implementation may use this call, e.g., to clean up its presolving data.
6702 * Besides clean up, no time consuming operations should be done.
6703 *
6704 * @subsection BENDERSINITSOL
6705 *
6706 * The BENDERSINITSOL callback is executed when the presolving is finished and the branch-and-bound process is about to
6707 * begin. The Benders' decomposition implementation may use this call to initialize its branch-and-bound specific data.
6708 *
6709 * @subsection BENDERSEXITSOL
6710 *
6711 * The BENDERSEXITSOL callback is executed before the branch-and-bound process is freed. The Benders' decomposition
6712 * implementation should use this call to clean up its branch-and-bound data.
6713 *
6714 * @subsection BENDERSPRESUBSOLVE
6715 *
6716 * The BENDERSPRESUBSOLVE callback is provided to give the user an opportunity in each iteration to perform any setup
6717 * operations prior to solving the subproblems. This callback also allows the user to skip the subproblem solve for the
6718 * current iteration. In this case, the user must set the result parameter appropriately
6719 * - the subproblem was not solved in this iteration. Other decompositions will be checked (SCIP_DIDNOTRUN).
6720 * - a constraint has been added to the master problem. No other decompositions will be checked (SCIP_CONSADDED).
6721 * - a cut has been added to the master problem. No other decompositions will be checked (SCIP_SEPARATED).
6722 * - feasibility of the solution is reported to SCIP. Other decompositions will be checked (SCIP_FEASIBLE).
6723 * - infeasibility of the solution is reported to SCIP. No other decompositions will be checked (SCIP_INFEASIBLE).
6724 *
6725 * @subsection BENDERSSOLVESUBCONVEX
6726 *
6727 * Two different subproblem solving functions are provide in the Benders' decomposition framework, BENDERSSOLVESUBCONVEX
6728 * and BENDERSSOLVESUB. These two solving functions are used in the two solving loops of the Benders' decomposition
6729 * framework. The first solving loop solves convex subproblems and convex relaxations of CIPs. The BENDERSSOLVESUBCONVEX
6730 * callback is executed only during the FIRST solving loop. Benders' cut generating methods suitable for convex
6731 * subproblems are executed during this solving loop. If a cut is found, then the second solve loop is not executed. If
6732 * your decomposition does not have any convex subproblems, then it is not necessary to implement the
6733 * BENDERSSOLVESUBCONVEX callback. However, it may be computationally beneficial to solve the convex relaxation of CIP
6734 * subproblems, such as the LP relaxation of a MIP subproblem.
6735 *
6736 * The second solve loop expects that the CIP subproblems are solved to optimality.
6737 *
6738 * If you implement the BENDERSSOLVESUBCONVEX callback, it is necessary to implement the BENDERSFREESUB callback.
6739 *
6740 * The objective function value after the subproblem solve and the result must be returned. The permissible results
6741 * are:
6742 * - the subproblem was not solved in this iteration (SCIP_DIDNOTRUN)
6743 * - the subproblem is solved and is feasible (SCIP_FEASIBLE)
6744 * - the subproblem is solved and is infeasible (SCIP_INFEASIBLE)
6745 * - the subproblem is solved and is unbounded (SCIP_UNBOUNDED)
6746 *
6747 * @subsection BENDERSSOLVESUB
6748 *
6749 * The BENDERSSOLVESUB is executed only during the SECOND solve loop. This callback function is used to solve CIP
6750 * subproblems. If your decomposition does not have any CIP subproblems, then it is not necessary to implement the
6751 * BENDERSSOLVESUB callback.
6752 *
6753 * If you implement the BENDERSSOLVESUB callback, it is necessary to implement the BENDERSFREESUB callback.
6754 *
6755 * The objective function value after the subproblem solve and the result must be returned. The permissible results
6756 * are:
6757 * - the subproblem was not solved in this iteration (SCIP_DIDNOTRUN)
6758 * - the subproblem is solved and is feasible (SCIP_FEASIBLE)
6759 * - the subproblem is solved and is infeasible (SCIP_INFEASIBLE)
6760 * - the subproblem is solved and is unbounded (SCIP_UNBOUNDED)
6761 *
6762 * @subsection BENDERSPOSTSOLVE
6763 *
6764 * The BENDERSPOSTSOLVE callback is executed after the subproblems have been solved and any required cuts have been
6765 * generated, but before the subproblems are freed. This callback provides the user an opportunity to interact the
6766 * subproblems at a global level. For example, the user is able to construct a solution to the original problem by
6767 * combining the solutions from the master problem and all subproblems.
6768 *
6769 * Additionally, the user is able to merge subproblems into the master problem during the execution of this callback.
6770 * The merging of subproblems into the master problem could be desired if it is too time consuming to satisfy the
6771 * feasibility of a subproblem or the appropriate cutting methods are not available for the provided subproblem. A list
6772 * of indicies of subproblems suitable for merging are given in the mergecands array. The first npriomergecands are the
6773 * merge candidates that must be merged into the master problem. If they are not, then the solution process will
6774 * terminate with an error. These merge candidates arise if a cut could not be generated due to numerical difficulties.
6775 * The remaining nmergecands - npriomergecands are subproblems that could be merged into the master problem if desired
6776 * by the user.
6777 *
6778 * @subsection BENDERSFREESUB
6779 *
6780 * The BENDERSFREESUB callback is executed to clean up the subproblems after the solving process and prepare them for
6781 * the next iteration. Typically, SCIPfreeTransform() is called for each subproblem to free the transformed problem.
6782 *
6783 */
6784
6785/*--+----1----+----2----+----3----+----4----+----5----+----6----+----7----+----8----+----9----+----0----+----1----+----2*/
6786
6787/**@page BENDERSCUT How to add custom Benders' decomposition cut generation methods
6788 *
6789 * The Benders' decomposition framework of SCIP allows the user to provide a custom implementation of cut generation
6790 * methods. The Benders' decomposition cut methods are linked to the Benders' decomposition implementations, not the
6791 * master problem SCIP instance. As such, you are able to have different Benders' decomposition cut methods for each
6792 * included Benders' decomposition.
6793 * The current list of all Benders' decomposition cut generation methods available in this release can be found
6794 * \ref BENDERSCUTS "here".
6795 *
6796 * We now explain how users can add their own Benders' decomposition cut methods. Take the default Benders'
6797 * decomposition cut method (src/scip/benderscut_opt.c) as an example. This Benders' decomposition cut method generates
6798 * a classical optimality cut from the optimal dual solution to the convex relaxation of the Benders' decomposition
6799 * subproblem. Same as all other default plugins, it is written in C. C++ users can easily adapt the code by using the
6800 * scip::ObjBenderscut wrapper base class and implement the scip_...() virtual methods instead of the
6801 * SCIP_DECL_BENDERSCUT... callback methods.
6802 *
6803 * Additional documentation for the callback methods of a Benders' decomposition cut methods, in particular for the
6804 * input parameters, can be found in the file type_benderscut.h.
6805 *
6806 * Here is what you have to do to implement a custom Benders' decomposition cut method:
6807 * -# Copy the template files src/scip/benderscut_xyz.c and src/scip/benderscut_xyz.h into files "benderscut_mybenderscut.c" and
6808 * "benderscut_mybenderscut.h".
6809 \n
6810 * Make sure to adjust your build system such that these files are compiled and linked to your project. \n
6811 * If you are adding a new default plugin, this means updating the `src/CMakeLists.txt` and `Makefile` files in the SCIP distribution.
6812 * -# Use SCIPincludeBenderscutMybenderscut() in order to include the Benders' decomposition cut method into your SCIP
6813 * instance, e.g., in the main file of your project (see, e.g., src/cmain.c in the Binpacking example). \n
6814 * If you are adding a new default plugin, this include function must be added to `src/scipdefplugins.c`.
6815 * -# Open the new files with a text editor and replace all occurrences of "xyz" by "mybenderscut".
6816 * -# Adjust the properties of the Benders' decomposition (see \ref BENDERSCUT_PROPERTIES).
6817 * -# Define the Benders' decomposition data (see \ref BENDERSCUT_DATA). This is optional.
6818 * -# Implement the interface methods (see \ref BENDERSCUT_INTERFACE).
6819 * -# Implement the fundamental callback methods (see \ref BENDERSCUT_FUNDAMENTALCALLBACKS).
6820 * -# Implement the additional callback methods (see \ref BENDERSCUT_ADDITIONALCALLBACKS). This is optional.
6821 *
6822 *
6823 * @section BENDERSCUT_PROPERTIES Properties of a Benders' decomposition
6824 *
6825 * At the top of the new file "benderscut_mybenderscut.c", you can find the Benders' decomposition cut methods
6826 * properties. These are given as compiler defines.
6827 * In the C++ wrapper class, you have to provide the Benders' decomposition properties by calling the constructor
6828 * of the abstract base class scip::ObjBenderscut from within your constructor.
6829 * The properties you have to set have the following meaning:
6830 *
6831 * \par BENDERSCUT_NAME: the name of the Benders' decomposition cut method.
6832 * This name is used in the interactive shell to address the Benders' decomposition cut method.
6833 * Additionally, if you are searching for a Benders' decomposition cut method with SCIPfindBenderscut(), this name is
6834 * looked up. Names have to be unique: no two Benders' decomposition cut methods linked to the same Benders'
6835 * decomposition may have the same name.
6836 *
6837 * \par BENDERSCUT_DESC: the description of the Benders' decomposition cut method.
6838 * This string is printed as a description of the Benders' decomposition cut method in the interactive shell.
6839 *
6840 * \par BENDERSCUT_PRIORITY: the priority of the Benders' decomposition cut method.
6841 * In each of the Benders' decomposition subproblem solving loops, the included Benders' decomposition cut methods are
6842 * called in order of priority. The priority is important because once a cut is generated for a subproblem, no other
6843 * cuts are generated for that subproblem for that solving loop.
6844 * \n
6845 * The priority of the Benders' decomposition should be set according to the order in which the cut should be generated.
6846 * For example, the priority of the included cuts attempt to generation feasibility cuts (src/scip/benderscut_feas.c
6847 * and src/scip/benderscut_nogood.c) prior to attempting to generate optimality cuts.
6848 *
6849 * \par BENDERSCUT_LPCUT: Can this cut be applied to convex subproblems and convex relaxations of CIP subproblems?
6850 * Since the Benders' decomposition framework executes two different solving loops, one for convex subproblems and the
6851 * other for CIP subproblems, the Benders' decomposition cut methods must be partitioned by their suitability for each
6852 * subproblem type. If BENDERSCUT_LPCUT is set to TRUE, then this cut is only applied to convex subproblems and convex
6853 * relaxations of CIP subproblems.
6854 *
6855 * @section BENDERSCUT_DATA Benders' decomposition Data
6856 *
6857 * Below the header "Data structures" you can find a struct which is called "struct SCIP_BenderscutData".
6858 * In this data structure, you can store the data of your Benders' decomposition. For example, you should store the adjustable
6859 * parameters of the Benders' decomposition in this data structure. In a Benders' decomposition, user parameters for the
6860 * number of subproblems and an array to store the subproblem SCIP instances could be useful.
6861 * \n
6862 * Defining Benders' decomposition data is optional. You can leave the struct empty.
6863 *
6864 * @section BENDERSCUT_INTERFACE Interface Methods
6865 *
6866 * At the bottom of "benderscut_mybenderscut.c", you can find the interface method SCIPincludeBenderscutMybenderscut(),
6867 * which also appears in "benderscut_mybenderscut.h"
6868 * SCIPincludeBenderscutMybenderscut() is called by the user, if (s)he wants to include the Benders' decomposition,
6869 * i.e., if (s)he wants to use the Benders' decomposition in his/her application.
6870 *
6871 * This method only has to be adjusted slightly.
6872 * It is responsible for notifying SCIP of the presence of the Benders' decomposition. For this, you can either call SCIPincludeBenderscut(),
6873 * or SCIPincludeBenderscutBasic() since SCIP version 3.0. In the latter variant, \ref BENDERSCUT_ADDITIONALCALLBACKS "additional callbacks"
6874 * must be added via setter functions as, e.g., SCIPsetBenderscutCopy(). We recommend this latter variant because
6875 * it is more stable towards future SCIP versions which might have more callbacks, whereas source code using the first
6876 * variant must be manually adjusted with every SCIP release containing new callbacks for Benders' decompositions in order to compile.
6877 *
6878 * If you are using Benders' decomposition cut data, you have to allocate the memory
6879 * for the data at this point. You can do this by calling:
6880 * \code
6881 * SCIP_CALL( SCIPallocBlockMemory(scip, &benderscutdata) );
6882 * \endcode
6883 * You also have to initialize the fields in "struct SCIP_BenderscutData" afterwards. For freeing the
6884 * Benders' decomposition cut data, see \ref BENDERSCUTFREE.
6885 *
6886 * You may also add user parameters for your Benders' decomposition, see \ref PARAM for how to add user parameters and
6887 * the method SCIPincludeBenderscutOpt() in src/scip/benderscut_opt.c for an example.
6888 *
6889 *
6890 * @section BENDERSCUT_FUNDAMENTALCALLBACKS Fundamental Callback Methods of a Benders' decomposition cut method
6891 *
6892 * The fundamental callback methods of the plugins are the ones that have to be implemented in order to obtain
6893 * an operational algorithm.
6894 * They are passed together with the Benders' decomposition itself to SCIP using SCIPincludeBenderscut() or SCIPincludeBenderscutBasic(),
6895 * see @ref BENDERSCUT_INTERFACE.
6896 *
6897 * Benders' decomposition cut methods only one callback, @ref BENDERSCUTEXEC, that must be implemented.
6898 *
6899 * Additional documentation for the callback methods, in particular to their input parameters,
6900 * can be found in type_benderscut.h.
6901 *
6902 * @subsection BENDERSCUTEXEC
6903 *
6904 * The BENDERSCUTEXEC callback is called during the cut generation process within the Benders' decomposition subproblem
6905 * solving loop. This method must generate a cut for the given subproblem if the associated subsystem is not optimal
6906 * with respect to the checked master problem solution.
6907 *
6908 * When generating cuts, it is possible to store these within the SCIP_BendersData of the associated Benders'
6909 * decomposition. This is achieved by calling SCIPstoreBenderscutCons() (SCIPstoreBenderscutCut() if the Benders'
6910 * decomposition cut is added as a cutting plane instead as a constraint). The storing of cuts can be useful when using
6911 * the large neighbourhood Benders' search, where the cut generated in the sub-SCIP solve are transferred to the main
6912 * SCIP instance.
6913 *
6914 * The BENDERSCUTEXEC callback must return the result of the cut generation. The permissable results are:
6915 * - if the Benders' cut was not run (SCIP_DIDNOTRUN).
6916 * - if the Benders' cut was run, but there was an error in generating the cut (SCIP_DIDNOTFIND).
6917 * - if the Benders' decomposition cut algorithm has not generated a constraint or cut (SCIP_FEASIBLE).
6918 * - an additional constraint for the Benders' decomposition cut was generated (SCIP_CONSADDED).
6919 * - a cutting plane representing the Benders' decomposition cut was generated (SCIP_SEPARATED).
6920 *
6921 * If the BENDERSCUTEXEC callback returns SCIP_DIDNOTFIND due to an error in the cut generation, if no other subproblems
6922 * generate a cut during the same iteration of the Benders' decomposition algorithm, then this could result in an
6923 * error. It is possible to avoid the error by merging the subproblem into the master problem (see \ref
6924 * BENDERSPOSTSOLVE).
6925 *
6926 * @section BENDERSCUT_ADDITIONALCALLBACKS Additional Callback Methods of a Separator
6927 *
6928 * The additional callback methods do not need to be implemented in every case. However, some of them have to be
6929 * implemented for most applications, they can be used, for example, to initialize and free private data.
6930 * Additional callbacks can either be passed directly with SCIPincludeBenderscut() to SCIP or via specific
6931 * <b>setter functions</b> after a call of SCIPincludeBenderscutBasic(), see also @ref BENDERSCUT_INTERFACE.
6932 *
6933 * @subsection BENDERSCUTFREE
6934 *
6935 * If you are using Benders' decomposition cut data (see \ref BENDERSCUT_DATA and \ref BENDERSCUT_INTERFACE), you have
6936 * to implement this method in order to free the Benders' decomposition cut data.
6937 *
6938 * If you have allocated memory for fields in your Benders' decomposition cut data, remember to free this memory
6939 * before freeing the Benders' decomposition data itself.
6940 * If you are using the C++ wrapper class, this method is not available.
6941 * Instead, just use the destructor of your class to free the member variables of your class.
6942 *
6943 * @subsection BENDERSCUTCOPY
6944 *
6945 * The BENDERSCUTCOPY callback is executed when a SCIP instance is copied, e.g. to
6946 * solve a sub-SCIP. By
6947 * defining this callback as
6948 * <code>NULL</code> the user disables the execution of the specified
6949 * separator for all copied SCIP instances. This may deteriorate the performance
6950 * of primal heuristics using sub-SCIPs.
6951 *
6952 * If the Benders' decomposition cuts are included by calling SCIPincludeBendersDefaultCuts() in the include method of
6953 * the Benders' decomposition implementation, such as SCIPincludeBendersDefault(), then it is not necessary to implement
6954 * BENDERSCUTCOPY. The copy method could be implemented to copy Benders' decomposition cut data from the original SCIP
6955 * instance to the sub-SCIP.
6956 *
6957 *
6958 * @subsection BENDERSCUTINIT
6959 *
6960 * The BENDERSCUTINIT callback is executed after the problem is transformed The Benders' decomposition cut method may,
6961 * e.g., use this call to initialize its Benders' decomposition cut data. The difference between the original and the
6962 * transformed problem is explained in "What is this thing with the original and the transformed problem about?" on \ref
6963 * FAQ.
6964 *
6965 * @subsection BENDERSCUTEXIT
6966 *
6967 * The BENDERSCUTEXIT callback is executed before the transformed problem is freed. In this method, the Benders'
6968 * decomposition cut method should free all resources that have been allocated for the solving process in
6969 * BENDERSCUTINIT.
6970 *
6971 * @subsection BENDERSCUTINITSOL
6972 *
6973 * The BENDERSCUTINITSOL callback is executed when the presolving is finished and the branch-and-bound process is about to
6974 * begin. The Benders' decomposition implementation may use this call to initialize its branch-and-bound specific data.
6975 *
6976 * @subsection BENDERSCUTEXITSOL
6977 *
6978 * The BENDERSCUTEXITSOL callback is executed before the branch-and-bound process is freed. The Benders' decomposition
6979 * implementation should use this call to clean up its branch-and-bound data.
6980 *
6981 */
6982/*--+----1----+----2----+----3----+----4----+----5----+----6----+----7----+----8----+----9----+----0----+----1----+----2*/
6983
6984/**@page CONF How to use conflict analysis
6985 *
6986 * Conflict analysis is a way to automatically use the information obtained from infeasible nodes
6987 * in the branch-and-bound tree.
6988 *
6989 * Once a node is declared infeasible, SCIP automatically tries to infer a constraint that explains the reason for the
6990 * infeasibility, in order to avoid similar situations later in the search. This explanation essentially consists of a
6991 * constraint stating that at least one of its variables should have a bound different from the current infeasible node,
6992 * because the current setting led to infeasibility. Clearly, all variables that are fixed in the current infeasible
6993 * node would yield such a constraint (since this leads to infeasibility). The key point rather is to infer a "small"
6994 * constraint that does the same job. SCIP handles this by several heuristics. For this, SCIP sets up a
6995 * so-called (directed) conflict graph. The nodes in this graph correspond to bound changes of variables and an arc (@a
6996 * u, @a v) means that the bound change corresponding to @a v is based on the bound change of @a u. In general, a node
6997 * will have several ingoing arcs which represent all bound changes that have been used to infer (propagate) the bound
6998 * change in question. The graph also contains source nodes for each bound that has been changed during branching and an
6999 * artificial target node representing the conflict, i.e., the infeasibility. Essentially, SCIP heuristically constructs
7000 * a cut in this graph that involves few "branching nodes". For details on the techniques that SCIP uses,
7001 * we refer to the paper @par
7002 * Tobias Achterberg, Conflict Analysis in Mixed Integer Programming@n
7003 * Discrete Optimization, 4, 4-20 (2007)
7004 *
7005 * For conflict analysis to work well, the author of a \ref CONS "Constraint Handler" or a
7006 * \ref PROP "Propagator" has to implement three kinds of functionality:
7007 *
7008 * -# If one detects infeasibility, one should initiate conflict analysis, see \ref INITCONFS "below".
7009 * -# During propagation, one should call the right functions to fix variables.
7010 * -# One should implement the <em>so-called reverse propagation</em>.
7011 *
7012 * If this functionality is not implemented, SCIP will still work correctly, but cannot use the information of the constraint
7013 * handler or the propagator for conflict analysis. In this case, each bound reduction performed by the constraint
7014 * handler/propagator will be treated as if it had been a branching decision.
7015 *
7016 * @section INITCONFS Initiating Conflict Analysis
7017 *
7018 * If one detects infeasibility within propagation, one should do the following:
7019 * -# Call SCIPinitConflictAnalysis().
7020 * -# Inform SCIP about the variable bounds that are the reason for the detection of infeasibility
7021 * via the functions SCIPaddConflictLb(), SCIPaddConflictUb(), SCIPaddConflictBd(), or
7022 * SCIPaddConflictBinvar(). If there is more than one valid explanation of infeasibility, either one can be used.
7023 * Typically, smaller explanations tend to be better.
7024 * -# Call SCIPanalyzeConflict() from a propagator or SCIPanalyzeConflictCons() from a constraint
7025 * handler.
7026 *
7027 * This functionality allows SCIP to set up the conflict graph and perform a conflict analysis.
7028 *
7029 * @section Propagation
7030 *
7031 * When propagating variable domains, SCIP needs to be informed that the deduced variable bounds should be
7032 * used in conflict analysis. This can be done by the functions SCIPinferVarLbCons(),
7033 * SCIPinferVarUbCons(), and SCIPinferBinvarCons() for constraint handlers and SCIPinferVarLbProp(),
7034 * SCIPinferVarUbProp(), and SCIPinferBinvarProp() for propagators. You can pass one integer of
7035 * information that should indicate the reason of the propagation and can be used in reverse
7036 * propagation, see the next section.
7037 *
7038 * @section RESPROP Reverse Propagation
7039 *
7040 * Reverse Propagation is used to build up the conflict graph. Essentially, it provides an algorithm to detect the arcs
7041 * leading to a node in the conflict graph, i.e., the bound changes responsible for the new bound change deduced during
7042 * propagation. Reverse Propagation needs to be implemented in the RESPROP callback functions of
7043 * \ref CONSRESPROP "constraint handlers" or \ref PROPRESPROP "propagators".
7044 * These callbacks receive the following information: the variable which is under investigation (@p
7045 * infervar), the corresponding bound change (@p bdchgidx, @p boundtype), and the integer (@p inferinfo) that has been
7046 * supplied during propagation.
7047 *
7048 * One can use SCIPvarGetUbAtIndex() or SCIPvarGetLbAtIndex() to detect the bounds before or after the propagation that
7049 * should be investigated. Then the bounds that were involved should be passed to SCIP via SCIPaddConflictLb() and
7050 * SCIPaddConflictUb(). If there is more than one valid explanation of infeasibility, either one can be used.
7051 * Typically, smaller explanations tend to be better.
7052 *
7053 * Details and (more) examples are given in Sections @ref CONSRESPROP and @ref PROPRESPROP.
7054 *
7055 *
7056 * @section Example
7057 *
7058 * Consider the constraint handler @p cons_linearordering.c in the
7059 * \ref LOP_MAIN "linear ordering example"
7060 * (see @p example/LOP directory). This constraint handler propagates the equations \f$x_{ij} + x_{ji} =
7061 * 1\f$ and triangle inequalities \f$x_{ij} + x_{jk} + x_{ki} \leq 2\f$.
7062 *
7063 * When propagating the equation and <code>vars[i][j]</code> is fixed to 1, the constraint handler uses
7064 * \code
7065 * SCIP_CALL( SCIPinferBinvarCons(scip, vars[j][i], FALSE, cons, i*n + j, &infeasible, &tightened) );
7066 * \endcode
7067 * Thus, variable <code>vars[j][i]</code> is fixed to 0 (@p FALSE), and it passes <code>i*n + j </code> as @p inferinfo.
7068 *
7069 * When it propagates the triangle inequality and both <code>vars[i][j]</code> and <code>vars[j][k]</code>
7070 * are fixed to 1, the constraint handler uses
7071 * \code
7072 * SCIP_CALL( SCIPinferBinvarCons(scip, vars[k][i], FALSE, cons, n*n + i*n*n + j*n + k, &infeasible, &tightened) );
7073 * \endcode
7074 * Thus, in this case, variable <code>vars[k][i]</code> is fixed to 0 and <code>n*n + i*n*n + j*n + k</code> is
7075 * passed as <code>inferinfo</code>.
7076 *
7077 * In reverse propagation, the two cases can be distinguished by @p inferinfo: if it is less than @p n*n,
7078 * we deal with an equation, otherwise with a triangle inequality. The constraint handler can then extract the
7079 * indices @p i, @p j (and @p k in the second case) from inferinfo.
7080 *
7081 * In the first case, it has to distinguish whether <code>vars[i][j]</code> is fixed to 0 or 1 &ndash;
7082 * by calling SCIPaddConflictLb()
7083 * or SCIPaddConflictUb(), respectively, with variable <code>vars[j][i]</code>. In the second case, it is clear that the only
7084 * possible propagation is to fix <code>vars[i][j]</code> to 0 when both <code>vars[k][i]</code> and <code>vars[j][k]</code>
7085 * are fixed to 1. It then calls
7086 * SCIPaddConflictLb() for both <code>vars[k][i]</code> and <code>vars[j][k]</code>.
7087 */
7088
7089/*--+----1----+----2----+----3----+----4----+----5----+----6----+----7----+----8----+----9----+----0----+----1----+----2*/
7090
7091/**@page REOPT How to use reoptimization
7092 *
7093 * The reoptimization feature of SCIP can be used to solve a sequence of optimization problems \f$(P_{i})_{i \in I}\f$ with
7094 * \f[
7095 * (P_i) \quad \min \{ c_i^T x \;|\; A^ix \geq b^i,\; x_{j} \in \mathbb{Z}\;\forall j \in \mathcal{I} \}
7096 * \f]
7097 * such that between two problems \f$P_i\f$ and \f$P_{i+1}\f$ the space of solutions gets restricted and/or the objective
7098 * function changes. To use reoptimization the user has to change the parameter <code>reoptimization/enable</code> to
7099 * <code>TRUE</code> before the solving process of the first problem of the sequence starts, i.e., in stage
7100 * <code>SCIP_STAGE_INIT</code> or <code>SCIP_STAGE_PROBLEM</code>. This can be done via the interactive shell or by
7101 * calling SCIPenableReoptimization(). In both cases SCIP changes some parameters and fixes them:
7102 * -# disable conflict analysis based on dual information
7103 * -# set the limit <code>maxorigsol</code> of stored solutions to zero because this is handled by a special solution tree provided
7104 * by the reoptimization feature itself
7105 * -# disable restarts (<code>presolving/maxrestarts = 0</code>)
7106 * -# disable multi-aggegations (<code>presolving/donotmultaggr = TRUE</code>)
7107 * -# disable dual reductions within presolvers and propagators (<code>misc/allowdualreds = FALSE</code>)
7108 * -# disable propagation with current cutoff bound (<code>misc/allowobjprop = FALSE</code>)
7109 *
7110 * In contrast to the presolving and propagating methods that are using dual information, performing strong branching is
7111 * allowed. The bound tightenings resulting from strong branching are handeled in a special way. After changing the objective
7112 * function and solving the modified problem the feasible region that was pruned by strong branching will be reconstructed
7113 * within the tree.
7114 *
7115 * If the reoptimization feature is enabled SCIP tries to reuse the search tree, especially the search frontier at the end
7116 * of the solving process, to speed up the solving process of the following problems. Therefore, the current release
7117 * provides the branching rule <code>branch_nodereopt</code> to reconstruct the tree. SCIP triggers a restart of the
7118 * reoptimization, i.e., solving the problem from scratch, if
7119 *
7120 * -# the stored search tree is too large,
7121 * -# the objective functions changed too much, or
7122 * -# the last \f$n\f$ optimal solution are updated solution of previous runs.
7123 *
7124 * The thresholds to trigger a restart can be set by the user:
7125 *
7126 * -# <code>reoptimization/maxsavednodes</code>
7127 * -# <code>reoptimization/delay</code>
7128 * -# <code>reoptimization/forceheurrestart</code>
7129 *
7130 * Before SCIP discards all the stored information and solves the problem from scratch it tries to compress the search
7131 * tree. Therefore, the current release provides compression heuristics that try to find a good and much smaller
7132 * representation of the current search tree.
7133 *
7134 * After a problem in the sequence of optimization problems was solved, the objective function can be changed in two ways:
7135 * -# Using the provided reader <code>reader_diff</code> the objective function can be changed via using the interactive
7136 * shell
7137 * \code
7138 * SCIP> read new_obj.diff
7139 * \endcode
7140 * or by calling SCIPreadDiff().
7141 * -# The objective function can be changed within the code. Therefore, the transformed problem needs to be freed by
7142 * calling SCIPfreeReoptSolve(). Afterwards, the new objective function can be installed by calling
7143 * SCIPchgReoptObjective().
7144 *
7145 * After changing the objective function the modified problem can be solved as usal.
7146 *
7147 * \note Currently, the compression heuristics used between two successive reoptimization runs only support pure binary
7148 * and mixed binary programs.
7149 *
7150 * For more information on reoptimization we refer to@par
7151 * Jakob Witzig@n
7152 * Reoptimization Techniques in MIP Solvers@n
7153 * Master's Thesis, Technical University of Berlin, 2014.
7154 */
7155
7156/*--+----1----+----2----+----3----+----4----+----5----+----6----+----7----+----8----+----9----+----0----+----1----+----2*/
7157
7158/**@page CONCSCIP How to use the concurrent solving mode
7159 *
7160 * @section Overview
7161 *
7162 * In \SCIP 4.0 a new feature has been added that allows to run multiple \SCIP instances with different settings
7163 * on one problem in parallel. To use this feature \SCIP has to be compiled with an additional make option to
7164 * enable the threading functionality (e.g. TPI=tny, see \ref MAKE).
7165 * Then, a concurrent solve can be started by using the <code>concurrentopt</code> command instead of the <code>optimize</code> command
7166 * in the \SCIP shell, or by calling the interface function SCIPsolveParallel().
7167 * To configure the behavior of the concurrent solving mode there are new parameters in the category <code>concurrent/</code>
7168 * and <code>parallel/</code> which will be explained here shortly.
7169 *
7170 * @section CONTROLNTHREADS Controlling the number of threads
7171 *
7172 * The parameters <code>parallel/maxnthreads</code> and <code>parallel/minnthreads</code> can be used to configure the number of threads
7173 * that sould be used for solving. \SCIP will try to use the configured maximum number of threads. If the
7174 * problem that is currently read is too large \SCIP will automatically use fewer threads, but never
7175 * go below the configured minimum number of threads.
7176 *
7177 * @section USEEMPHSETTINGS Using emphasis settings
7178 *
7179 * The parameters <code>concurrent/scip.../prefprio</code> configure which concurrent solvers should be used.
7180 * The concurrent solver <code>scip</code> will use the same settings as the \SCIP instance configured by the user.
7181 * The other concurrent solvers, e.g. <code>scip-feas</code>, will load the corresponding emphasis setting.
7182 * The behavior of the prefprio parameter is as follows: If it is set to 1.0 for <code>scip-feas</code> and
7183 * <code>scip-opti</code>, and to 0.0 for every other concurrent solver, then the threads will be evenly
7184 * distributed between the two types <code>scip-feas</code> and <code>scip-opti</code>. An example: if 4 threads are used each of these concurrent
7185 * solvers will use 2 threads. If the <code>prefprio</code> for one solver is set to 0.33 and the other is set to 1.0, then the former will use 1 thread
7186 * and the latter will use 3 threads of the 4 available threads.
7187 *
7188 * @section CUSTOMCONCSOLVERS Running custom solvers
7189 *
7190 * To use custom settings for the concurrent solvers there is the parameter <code>concurrent/paramsetprefix</code>. If custom parameters
7191 * should be loaded by the concurrent solvers, then it must point to the folder where they are located (including a path separator at the end).
7192 * The parameter settings must be named after the concurrent solvers, e.g. if only the concurrent solver <code>scip</code> is used
7193 * they should be named <code>scip-1</code>, <code>scip-2</code>, <code>scip-3</code>. When different types of concurrent solvers are used the counter
7194 * starts at one for each of them, e.g. <code>scip-1</code> and <code>scip-feas-1</code>.
7195 */
7196
7197/*--+----1----+----2----+----3----+----4----+----5----+----6----+----7----+----8----+----9----+----0----+----1----+----2*/
7198
7199/*--+----1----+----2----+----3----+----4----+----5----+----6----+----7----+----8----+----9----+----0----+----1----+----2*/
7200
7201/**@page DECOMP How to provide a problem decomposition
7202 *
7203 * Most mixed-integer programs have sparse constraint matrices in the sense that most columns and rows have only very few nonzero entries,
7204 * maybe except for a few outlier columns/rows with many nonzeros.
7205 * A decomposition identifies subproblems (subsets of rows and columns) that are only linked to each other via a set of linking rows and/or linking
7206 * columns, but are otherwise independent.
7207 * The special case of completely independent subproblems (with no linking rows and columns), for example, can be solved by solving
7208 * the much smaller subproblems and concatenating their optimal solutions.
7209 * This case has already been integrated into SCIP as a successful presolving technique (see @ref cons_components.c).
7210 * Another use of decomposition within SCIP is the @ref BENDDECF "Benders Decomposition framework".
7211 *
7212 * Since SCIP 7.0, it is easier to pass user decompositions to SCIP that can be used within Benders decomposition or by user algorithms.
7213 * This page introduces the struct SCIP_DECOMP and gives examples how to create and use it.
7214 *
7215 * @section DECOMP_OVERVIEW Overview
7216 *
7217 * In the following, we present decompositions of mixed-integer programs. However, the generalization to Constraint Integer Programs is straightforward.
7218 *
7219 * Concretely, for \f$k \geq 0\f$ we call a partition \f$\mathcal{D}=(D^{\text{row}},D^{\text{col}})\f$ of the rows and columns of the constraint matrix \f$A\f$ into \f$k + 1\f$ pieces each,
7220 *
7221 * \f[
7222 * D^{\text{row}} = (D^{\text{row}}_{1},\dots,D^{\text{row}}_{k},L^{\text{row}}), \quad D^{\text{col}} = (D^{\text{col}}_{1},\dots,D^{\text{col}}_{k},L^{\text{col}})
7223 * \f]
7224 * a decomposition of \f$A\f$ if \f$D^{\text{row}}_{q} \neq \emptyset\f$, \f$D^{\text{col}}_{q} \neq \emptyset\f$ for \f$q \in \{1,\dots,k\}\f$ and if it holds for all \f$i\in D^{\text{row}}_{q_{1}}, j\in D^{\text{col}}_{q_{2}}\f$ that \f$a_{i,j} \neq 0 \Rightarrow q_{1} = q_{2}\f$.
7225 * The special rows \f$L^{\text{row}}\f$ and columns \f$L^{\text{col}}\f$, which may be empty, are called linking rows and linking columns, respectively.
7226 * In other words, the inequality system \f$A x \geq b\f$ can be rewritten
7227 * with respect to a decomposition \f$\mathcal{D}\f$ by a suitable permutation of the rows
7228 * and columns of \f$A\f$ as equivalent system
7229 * \f[
7230 * \left(
7231 * \begin{matrix}
7232 * A_{[D^{\text{row}}_{1},D^{\text{col}}_{1}]} &
7233 * 0 &
7234 * \cdots &
7235 * 0 &
7236 * A_{[D^{\text{row}}_{1},L^{\text{col}}]}\\
7237 * 0 &
7238 * A_{[D^{\text{row}}_{2},D^{\text{col}}_{2}]} &
7239 * 0 &
7240 * 0 &
7241 * A_{[D^{\text{row}}_{2},L^{\text{col}}]}\\
7242 * \vdots &
7243 * 0 &
7244 * \ddots &
7245 * 0 &
7246 * \vdots\\
7247 * 0 &
7248 * \cdots &
7249 * 0 &
7250 * A_{[D^{\text{row}}_{k},D^{\text{col}}_{k}]} &
7251 * A_{[D^{\text{row}}_{k},L^{\text{col}}]}\\
7252 * A_{[L^{\text{row}},D^{\text{col}}_{1}]} &
7253 * A_{[L^{\text{row}},D^{\text{col}}_{2}]} &
7254 * \cdots &
7255 * A_{[L^{\text{row}},D^{\text{col}}_{k}]} &
7256 * A_{[L^{\text{row}},L^{\text{col}}]}
7257 * \end{matrix}
7258 * \right)
7259 * \left(
7260 * \begin{matrix}
7261 * x_{[D^{\text{col}}_{1}]}\\
7262 * x_{[D^{\text{col}}_{2}]}\\
7263 * \vdots\\
7264 * x_{[D^{\text{col}}_{k}]}\\
7265 * x_{[L^{\text{col}}]}
7266 * \end{matrix}
7267 * \right)
7268 * \geq
7269 * \left(
7270 * \begin{matrix}
7271 * b_{[D^{\text{row}}_{1}]}\\
7272 * b_{[D^{\text{row}}_{2}]}\\
7273 * \vdots\\
7274 * b_{[D^{\text{row}}_{k}]}\\
7275 * b_{[L^{\text{row}}]}
7276 * \end{matrix}
7277 * \right)
7278 * % A= \left(\begin{matrix}4&8&\frac{1}{2}\\\frac{3}{2}&4&1\\1&3&7\end{matrix}\right)
7279 * \f]
7280 * where we use the short hand syntax \f$A_{[I,J]}\f$ to denote
7281 * the \f$|I|\f$-by-\f$|J|\f$ submatrix that arises from the deletion of all entries
7282 * from \f$A\f$ except for rows \f$I\f$ and columns \f$J\f$,
7283 * for nonempty row
7284 * and column subsets \f$I\subseteq\{1,\dots,m\}\f$ and \f$J\subseteq\{1,\dots,n\}\f$.
7285 *
7286 *
7287 * @section DECOMP_USING Using a decomposition
7288 *
7289 * After passing one or more decompositions, see below, one can access all available decompositions with SCIPgetDecomps().
7290 * The labels can be obtained by calling SCIPdecompGetVarsLabels() and SCIPdecompGetConsLabels().
7291 * If some variables/constraints are not labeled, these methods will mark them as linking variables/constraints.
7292 * There are several methods to get more information about one decomposition, see @ref DecompMethods.
7293 *
7294 * A decomposition can be used to split the problem into several subproblems which, in general, are easier to solve.
7295 * For \f$q \in \{1,\dots,k\}\f$ the system
7296 * \f[
7297 * A_{[D^{\text{row}}_{q},D^{\text{col}}_{q}]}\; x_{[D^{\text{col}}_{q}]} \geq b_{[D^{\text{row}}_{q}]}
7298 * \f]
7299 * is part of subproblem \f$q\f$, the handling of the linking variables/constraints depends on the chosen application context.
7300 * For example, in the heuristic @ref heur_padm.c several smaller subproblems are solved multiple times to get a feasible solution.
7301 * Also the @ref BENDDECF "Benders' decomposition framework" was extended with release 7.0 to use user decompositions.
7302 *
7303 * @section DECOMP_CREATION Creation via SCIP-API
7304 *
7305 * There are two different ways to provide a decomposition in SCIP.
7306 * It can be created with the SCIP-API or it can be read from a file.
7307 *
7308 * To create it with the API, the user must first create a decomposition with SCIPcreateDecomp() specifying
7309 * whether the decomposition belongs to the original or transformed problem and the number of blocks.
7310 * Then the variables and constraints can be assigned to one block or to the linking rows/columns by calling
7311 * SCIPdecompSetVarsLabels() and SCIPdecompSetConsLabels(), respectively.
7312 * To complete the decomposition or to ensure that it is internally consistent, SCIPcomputeDecompVarsLabels() or
7313 * SCIPcomputeDecompConsLabels() can be called.
7314 * Note that SCIPcomputeDecompVarsLabels() will ignore the existing variable labels and computes again the labels based on the constraint labels only;
7315 * SCIPcomputeDecompConsLabels() works in the same way and ignores the existing constraint labels.
7316 *
7317 * After the decomposition has been successfully created, it can be saved for later use in the DecompStore using SCIPaddDecomp().
7318 * Access to all decompositions in the DecompStore is possible with SCIPgetDecomps().
7319 *
7320 * @section DECOMP_READDEC Reading a decomposition from a file
7321 *
7322 * Alternatively, after a problem has been read, a related decomposition can be read from a dec-file.
7323 * Please refer to the @ref reader_dec.h "DEC file reader" for further information about the required file format.
7324 * Upon reading a valid dec-file, a decomposition structure is created, where the corresponding variable labels are inferred from the constraint labels, giving precedence to block over linking constraints.
7325 *
7326 * @section DECOMP_BENDERS Use for Benders
7327 *
7328 * If the variables should be labeled for the application of @ref BENDDECF "Benders' decomposition", the decomposition must be explicitly flagged by setting the parameter decomposition/benderslabels to TRUE.
7329 * With this setting, the variable's labeling takes place giving precedence to its presence in linking constraints over its presence in named blocks.
7330 *
7331 * @section DECOMP_TRANS Decomposition after problem transformation
7332 *
7333 * As the problem's constraints are constantly changing, or possibly deleted, during presolving, the constraints' labeling must be triggered again.
7334 * Therefore, SCIP automatically transforms all user decompositions at the beginning of the root node based on the variables' labels.
7335 *
7336 * @section DECOMP_STATS Decomposition statistics
7337 *
7338 * Further useful measures and statistics about the decomposition are computed within SCIPcomputeDecompStats().
7339 * When the labeling process is concluded, the following measures are computed and printed:
7340 * - the number of blocks;
7341 * - the number of linking variables and linking constraints;
7342 * - the size of the largest as well as the smallest block;
7343 * - the area score:
7344 * This score is also used by GCG to rank decompositions during the automatic detection procedure.
7345 * For a decomposition
7346 * \f$\mathcal{D}=(D^{\text{row}},D^{\text{col}})\f$,
7347 * the area score is defined as
7348 * \f[
7349 * \text{areascore}(\mathcal{D}) = 1 - \frac{ \sum_{q=1}^k \lvert D^{\text{row}}_{q} \rvert
7350 * \lvert D^{\text{col}}_{q} \rvert + n\lvert L^{\text{row}} \rvert + m\lvert L^{\text{col}} \rvert -
7351 * \lvert L^{\text{row}} \rvert \lvert L^{\text{col}} \rvert }{mn}
7352 * \enspace.
7353 * \f]
7354 * In the case of a mixed-integer program, the area score intuitively measures the coverage of the rearranged matrix by 0's.
7355 * Decompositions with few linking variables and/or constraints and many small blocks \f$A_{[D^{\text{row}}_{q},D^{\text{col}}_{q}]}\f$
7356 * will have an area score close to \f$1\f$, whereas coarse decompositions of a matrix have smaller area scores.
7357 * The trivial decomposition with a single block has the worst possible area score of 0.
7358 * - the modularity:
7359 * This measure is used to assess the quality of the community structure within a decomposition.
7360 * The modularity of the decomposition is computed as follows:
7361 * \f[
7362 * \begin{aligned}
7363 * \sum_{q=1}^{k} \dfrac{e_{q}}{m} \left(1-\dfrac{e_{q}}{m}\right),
7364 * \end{aligned}
7365 * \f]
7366 * where \f$e_{q}\f$ is the number of inner edges within block \f$q\f$ and \f$m\f$ is the total number of edges.
7367 * The presence of an inner edge is identified through the presence of a variable in a constraint,
7368 * both—the variable and the constraint—belonging to the same block.
7369 * - the block graph statistics: A block graph is constructed with the aim of depicting the connection between the different blocks in a decomposition through the existing linking variables in the constraints.
7370 * Note that the linking constraints are intentionally skipped in this computation.
7371 * \f$ G = (V,E) \f$ denotes a block graph, with vertex set \f$V\f$ and edge set \f$E\f$.
7372 * Each vertex in the graph represents a block in the decomposition; \f$V = \{v_{1},\dots,v_{k}\}\f$.
7373 * An edge \f$e = \{ v_{s},v_{t} \}\f$ is added to \f$G\f$, if and only if there exists a column \f$\ell \in L^{\text{col}}\f$, a row \f$i \in D^{\text{row}}_{s}\f$
7374 * and a row \f$j \in D^{\text{row}}_{t}\f$, such that \f$a_{i,\ell} \neq 0\f$ and \f$a_{j,\ell} \neq 0\f$.
7375 * From the constructed graph, the number of edges, articulation points and connected components are computed, together with the maximum and minimum degree.
7376 * Note that building the block graph can become computationally expensive with large and dense decompositions.
7377 * Thus, it is possible through a user parameter <code>decomposition/maxgraphedge</code> to define a maximum edge limit.
7378 * The construction process will be interrupted once this limit is reached, in which case only approximate estimations of the block graph statistics will be displayed and accompanied with a warning message.
7379 *
7380 */
7381
7382/*--+----1----+----2----+----3----+----4----+----5----+----6----+----7----+----8----+----9----+----0----+----1----+----2*/
7383
7384
7385/**@page BENDDECF How to use the Benders' decomposition framework
7386 *
7387 * Benders' decomposition is a very popular mathematical programming technique that is applied to solve structured
7388 * problems. Problems that display a block diagonal structure are particularly amenable to the application of Benders'
7389 * decomposition. In a purely mixed-integer linear setting, such problems are given by
7390 *
7391 * \f[
7392 * \begin{array}[t]{rllclcl}
7393 * \min & \displaystyle & c^{T}x & + & d^{T}y \\
7394 * & \\
7395 * \text{subject to} & \displaystyle & Ax & & & = & b \\
7396 * & \\
7397 * & \displaystyle & Tx & + & Hy & = & h \\
7398 * & \\
7399 * & & x & & & \in & \mathbb{Z}^{p}\times\mathbb{R}^{n - p} \\
7400 * & & & & y & \in & \mathbb{R}^{m} \\
7401 * \end{array}
7402 * \f]
7403 *
7404 * The variables \f$x\f$ and \f$y\f$ are described as the first and second stage variables respectively. In the
7405 * classical use of Benders' decomposition, it is a requirement that the all second stage variables are continuous.
7406 * Extensions to the classical Benders' decomposition approach have permitted the use of more general second stage
7407 * problems.
7408 *
7409 * The application of Benders' decomposition to the above problem results in a subproblem, given by
7410 *
7411 * \f[
7412 * \begin{array}[t]{rll}
7413 * \min & \displaystyle & d^{T}y \\
7414 * & \\
7415 * \text{subject to} & \displaystyle & Hy = h - T\bar{x} \\
7416 * & \\
7417 * & & y \in \mathbb{R}^{m} \\
7418 * \end{array}
7419 * \f]
7420 *
7421 * where \f$\bar{x}\f$ is a solution vector of the first stage variables. As such, the subproblem is a problem only in
7422 * \f$y\f$. The dual solution to the subproblem, either an extreme point or extreme ray, is used to generate cuts that
7423 * are added to the master problem. Let \f$\lambda\f$ be the vector of dual variables associated with the set of
7424 * constraints from the subproblem. If, for a given \f$\bar{x}\f$, the subproblem is infeasible, then \f$\lambda\f$
7425 * corresponds to a dual ray and is used to produce the cut
7426 *
7427 * \f[
7428 * 0 \geq \lambda(h - Tx)
7429 * \f]
7430 *
7431 * which eliminates \f$\bar{x}\f$ from the master problem. If, for a given \f$\bar{x}\f$, the subproblem is feasible,
7432 * then \f$\lambda\f$ corresponds to a dual extreme point and is used to produce the cut
7433 *
7434 * \f[
7435 * \varphi \geq \lambda(h - Tx)
7436 * \f]
7437 *
7438 * where \f$\varphi\f$ is an auxiliary variable added to the master problem as an underestimator of the optimal
7439 * subproblem objective function value.
7440 *
7441 * Given \f$\Omega^{p}\f$ and \f$\Omega^{r}\f$ as the sets of dual extreme points and rays of the subproblem,
7442 * respectively, the Benders' decomposition master problem is given by
7443 *
7444 * \f[
7445 * \begin{array}[t]{rll}
7446 * \min & \displaystyle & c^{T}x + \varphi \\
7447 * & \\
7448 * \text{subject to} & \displaystyle & Ax = b \\
7449 * & \\
7450 * & \displaystyle & \varphi \geq \lambda(h - Tx) \quad \forall \lambda \in \Omega^{r}\\
7451 * & \\
7452 * & \displaystyle & 0 \geq \lambda(h - Tx) \quad \forall \lambda \in \Omega^{r} \\
7453 * & \\
7454 * & & x \in \mathbb{Z}^{p}\times\mathbb{R}^{n - p} \\
7455 * & & \varphi \in \mathbb{R} \\
7456 * \end{array}
7457 * \f]
7458 *
7459 * @section BENDERFRAMEWORK Overview
7460 *
7461 * In \SCIP 6.0 a Benders' decomposition framework has been implemented.
7462 *
7463 * The current framework can be used to handle a Benders Decomposition of CIPs of the form
7464 *
7465 * \f[
7466 * \begin{array}[t]{rllclcl}
7467 * \min & \displaystyle & c^{T}x & + & d^{T}y \\
7468 * \text{subject to} & \displaystyle & g(x & , & y) & \in & [\ell,u] \\
7469 * & & x & & & \in & X \\
7470 * & & & & y & \in & Y \\
7471 * \end{array}
7472 * \f]
7473 * when either
7474 * - the subproblem is convex: \f$g_i(x,y)\f$ convex on \f$X\times Y\f$ if \f$u_i<\infty\f$, \f$g_i(x,y)\f$ concave on \f$X\times Y\f$ if \f$\ell_i>-\infty\f$, and \f$Y=\mathbb{R}^m\f$, or
7475 * - the first stage variables are of binary type: \f$ X \subseteq \{0,1\}^n \f$.
7476 *
7477 * This framework can be used in four different
7478 * ways: inputting an instance in the SMPS file format, using the default Benders' decomposition implementation
7479 * (see src/scip/benders_default.c), implementing a custom Benders' decomposition plugin (see \ref BENDER), or by using
7480 * the Benders' decomposition mode of GCG.
7481 * An overview of how to use each of these methods will be provided in this section.
7482 *
7483 * @section BENDERSSMPS Inputting an instance in the SMPS file format.
7484 *
7485 * As part of the Benders' decomposition framework development, a reader for instances in the SMPS file format has been
7486 * implemented (see src/scip/reader_smps.c). The details regarding the SMPS file format can be found at:
7487 *
7488 * Birge, J. R.; Dempster, M. A.; Gassmann, H. I.; Gunn, E.; King, A. J. & Wallace, S. W.
7489 * A standard input format for multiperiod stochastic linear programs
7490 * IIASA, Laxenburg, Austria, WP-87-118, 1987
7491 *
7492 * In brief, the SMPS file format involves three different files:
7493 * - A core file (.cor): a problem instance in MPS format that is the core problem of a stochastic program.
7494 * - A time file (.tim): partitions the variables and constraints into the different stages of the stochastic program
7495 * - A stochastic file (.sto): describes the scenarios for each stage.
7496 *
7497 * The STO reader (see src/scip/reader_sto.c) constructs the stochastic program using the information from the core and
7498 * time files. By default, the STO reader will construct the deterministic equivalent of the stochastic program. A
7499 * parameter is provided "reading/sto/usebenders" that will inform the STO reader to apply Benders' decomposition to the
7500 * input stochastic program.
7501 *
7502 * @section BENDERSDEFAULT Using the default Benders' decomposition plugin.
7503 *
7504 * A default implementation of a Benders' decomposition plugin has been included in \SCIP 6.0 (see
7505 * src/scip/benders_default.c). In order to use the default plugin, the user must create SCIP instances of the master
7506 * problem and subproblems. The subproblems must also contain a copy of the master problem variables, since these are
7507 * fixed to the master problem solution values during the subproblem solving loop. These SCIP instances for the master
7508 * and subproblems are passed to the default plugin by calling SCIPcreateBendersDefault().
7509 *
7510 * The mapping between the master and subproblem variables is performed automatically. The default solving and cut
7511 * generation methods are applied to solve the input problem. It is important to note that the mapping between the
7512 * master and subproblem variables relies on the variable names. The variables of the subproblem corresponding to
7513 * master problem variables must have the same name in both problems.
7514 *
7515 * The CAP (stochastic capacitated facility location problem) example demonstrates the use of the default Benders'
7516 * decomposition implementation within a project.
7517 *
7518 * @section BENDERSCUSTOM Implementing a custom Benders' decomposition implementation.
7519 *
7520 * A custom Benders' decomposition requires the implementation of a Benders' decomposition plugin. The key aspects for
7521 * implementing a custom Benders' decomposition plugin are explained in \ref BENDER.
7522 *
7523 * @section BENDERSGCG Using the Benders' decomposition mode of GCG
7524 *
7525 * In GCG 3.0, a Benders' decomposition mode has been implemented. This mode takes the decomposition found by the
7526 * detection schemes of GCG and applies Benders' decomposition. Using GCG it is possible to apply Benders' decomposition
7527 * to general problem without having to manually construct the decompositions.
7528 *
7529 */
7530
7531/*--+----1----+----2----+----3----+----4----+----5----+----6----+----7----+----8----+----9----+----0----+----1----+----2*/
7532
7533/**@page PROBINGDIVING How to use probing and diving mode
7534 *
7535 * SCIP contains two methods to perform a temporary dive in the branch-and-bound tree: the diving mode and the probing mode.
7536 * Both methods enable the modification of variable bounds, addition of new constraints, or adjustments to the objective function.
7537 * Whereas the diving mode works directly on the LP structure, the probing mode creates temporary branch-and-bound nodes, which makes it possible to perform backtracks during a dive.
7538 * Probing allows to perform domain propagation at the temporary nodes and provides the ability to solve the LP by column generation if a pricer plugin is implemented; neither is possible in diving mode.
7539 *
7540 * After entering diving or probing mode by calling SCIPstartDive() and SCIPstartProbing(), respectively, there exist various functions that allow the user to temporarily change the LP.
7541 * An overview for diving can be found here[https://www.scipopt.org/doc/html/group__PublicLPDivingMethods.php] and for the probing mode here[https://scipopt.org/doc/html/group__PublicProbingMethods.php].
7542 * To reset all changes, the respective mode needs to be ended by calling SCIPendDive() and SCIPendProbing(), respectively.
7543 *
7544 * Note that, although the state of the LP and the problem is reset after ending probing and diving, both modes can have several effects on the subsequent solving process.
7545 * In some situations, when the LP is infeasible for example, conflict analysis will be run in both probing and diving modes, which can lead to globally valid conflict constraints that are then added to the main solving process.
7546 * Similarly, the function SCIPpropagateProbing() might find globally valid bound changes, which are added to the main SCIP and considered in the subsequent solving process.
7547 * Another way to leverage insights found during probing or diving is to update pseudo costs during both modes, helping make better branching decisions.
7548 * This is controlled by setting the parameter "divingpscosts" to TRUE, which is done in the default settings of SCIP.
7549 * Moreover, if the LP was not solved to optimality before entering diving mode (or the parameter "resolverestore" is set to TRUE), the LP is resolved to reset the solution.
7550 * In some cases, such as when dealing with a numerically difficult instance, this might lead to a different LP state.
7551 * Finally, during probing, global variable statistics can be collected by calling SCIPenableVarHistory() after starting probing.
7552 * Since these statistics can be used for decision-making in SCIP, enabling their collection can have an effect on the solving process after probing ends.
7553 *
7554 */
7555/*--+----1----+----2----+----3----+----4----+----5----+----6----+----7----+----8----+----9----+----0----+----1----+----2*/
7556
7557/**@page OBJ Creating, capturing, releasing, and adding data objects
7558 *
7559 * Data objects (variables, constraints, rows, ... ) are subject to reference counting
7560 * to avoid expensive copying operations. This concept is similar to smart pointers.
7561 * Creating such an object (e.g., by calling SCIPcreateVar()) will set the
7562 * reference counter to one. Capturing an object (e.g., by calling SCIPcaptureVar()) increases the reference counter,
7563 * releasing it (e.g., by calling SCIPreleaseVar()) decreases the counter. If the reference counter gets zero, the
7564 * object will be destroyed automatically.
7565 *
7566 * Remember that a created data object is automatically captured. If the user
7567 * doesn't need the object anymore, (s)he has to call the object's release method.
7568 *
7569 * When a data object is added to SCIP (e.g., by calling SCIPaddVar()) , it is captured again, such that a
7570 * release call does not destroy the object. If SCIP doesn't need the object
7571 * anymore, it is automatically released.
7572 *
7573 * E.g., if the user calls
7574 * \code
7575 * SCIPcreateVar(); // reference counter 1
7576 * SCIPaddVar(); // reference counter 2
7577 * SCIPreleaseVar(); // reference counter 1
7578 * \endcode
7579 * the reference counter will be 1 afterwards, and the variable will be destroyed, if SCIP frees the problem.
7580 * If the user wants to use this variable, e.g. for extracting statistics after SCIP was finished, the user must not call
7581 * SCIPreleaseVar() right after adding the variable, but before terminating the program.
7582 */
7583
7584/*--+----1----+----2----+----3----+----4----+----5----+----6----+----7----+----8----+----9----+----0----+----1----+----2*/
7585
7586/**@page PARAM How to add additional user parameters
7587 *
7588 * Users may add their own parameters to SCIP by calling SCIPaddXyzParam(). Using
7589 * this method, there are two possibilities for where to store the actual parameter value:
7590 * - If the given valueptr is NULL, SCIP stores the parameter value internally, and
7591 * the user can only access the value with the SCIPgetXyzParam() and
7592 * SCIPsetXyzParam() calls.
7593 * - If the given valueptr is not NULL, SCIP stores the parameter value at the given
7594 * address, and the user can directly manipulate the value at this address.
7595 * (S)he has to be careful with memory management in string parameters: when the
7596 * SCIPaddStringParam() method is called, the given address must hold a char*
7597 * pointer with value NULL. The default value is then copied into this pointer,
7598 * allocating memory with BMSallocMemoryArray(). If the parameter is changed, the
7599 * old string is freed with BMSfreeMemoryArray() and the new one is copied to a new
7600 * memory area allocated with BMSallocMemoryArray(). When the parameter is freed,
7601 * the memory is freed with BMSfreeMemoryArray().
7602 * The user should not interfere with this internal memory management. Accessing
7603 * the string parameter through the given valueptr is okay as long as it does not
7604 * involve reallocating memory for the string.
7605 *
7606 * In some cases, it is necessary to keep track of changes in a parameter.
7607 * If this is the case, the user can define a method by the PARAMCHGD callback and use this method as
7608 * the @c paramchgd parameter of the @c SCIPaddXyzParam() method, also giving a pointer to the data, which is
7609 * needed in this method, as @c paramdata. If this method is not NULL, it is called every time
7610 * the value of the parameter is changed.
7611 */
7612
7613/*--+----1----+----2----+----3----+----4----+----5----+----6----+----7----+----8----+----9----+----0----+----1----+----2*/
7614
7615/**@page MEMORY Using the memory functions of SCIP
7616 *
7617 * SCIP provides three ways for allocating memory:
7618 * -# <b>block memory:</b> efficient handling of memory blocks of similar small sizes
7619 * -# <b>buffer memory:</b> efficient handling of memory that needs to locally be allocated and freed
7620 * -# <b>standard memory:</b> access to standard malloc/free
7621 *
7622 * <em>Whenever possible, the first two should be used, because of reasons detailed below.</em>
7623 *
7624 * In the following, we provide a brief description of these methods. We refer the reader to the dissertation of Tobias
7625 * Achterberg for more details. We also present best practice models.
7626 *
7627 * @section MEMBACK Background
7628 *
7629 * The main goals for providing such particular methods are:
7630 * - <em>Accounting:</em> Using its own functions, SCIP knows the total size of memory allocated internally and can change its
7631 * behavior: for instance, it can change to "memory saving mode" (using depth first search (DFS) and possibly do a garbage
7632 * collection). It also allows for keeping a memory limit.
7633 * - <em>Speed:</em> SCIP often needs to allocate a very large number of small blocks of similar sizes (often powers of
7634 * two). Depending on the operating system and compiler, the methods implemented in SCIP can be faster, since blocks
7635 * of the same size are grouped together. Especially at the end of the 1990ies the standard malloc/free methods were
7636 * quite ineffective. The experiments of Tobias Achterberg in 2007 show a speed improvement of 11 % when using block
7637 * memory.
7638 * - <em>Efficiency:</em> Since blocks are groups in sizes, the blocks do not need to store their sizes within each
7639 * block. In comparison, standard malloc/free stores the size using one word for each memory chunk. The price to pay
7640 * is that one needs to pass the size to the methods that free a block. In any case, the methods in SCIP can save
7641 * memory. Moreover, buffer memory is stored in similar places and not spread out, which also might help cache.
7642 * - <em>Debugging:</em> All of the possibilities provide methods to detect memory leaks. Together with tools like
7643 * valgrind, this can be quite effective in avoiding such problems.
7644 *
7645 * @n
7646 * @section BLKMEM Block memory
7647 *
7648 * SCIP offers its own block memory handling, which allows efficient handling of smaller blocks of memory in cases in
7649 * which many blocks of the same (small) size appear. This is adequate for branch-and-cut codes in which small blocks
7650 * of the same size are allocated and freed very often (for data structures used to store rows or branch-and-bound
7651 * nodes). Actually, most blocks allocated within SCIP have small sizes like 8, 16, 30, 32, 64. The idea is simple:
7652 * There is a separate list of memory blocks for each interesting small size. When allocating memory, the list is
7653 * checked for a free spot in the list; if no such spot exists, the list is enlarged. Freeing just sets the block to be
7654 * available. Very large blocks are handled separately. See the dissertation of Tobias Achterberg for more details.
7655 *
7656 * One important comment is that freeing block memory requires the size of the block in order to find the right list.
7657 *
7658 * The most important functions are
7659 * - SCIPallocBlockMemory(), SCIPallocBlockMemoryArray() to allocate memory
7660 * - SCIPfreeBlockMemory(), SCIPfreeBlockMemoryArray() to free memory
7661 *
7662 * An example code is:
7663 * @refsnippet{tests/src/misc/snippets.c,SnippetArrayAllocAndFree}
7664 * @n
7665 *
7666 * @section BUFMEM Buffer memory
7667 *
7668 * @subsection BUFMEMSTD Standard Buffer Memory
7669 *
7670 * In addition to block memory, SCIP offers buffer memory. This should be used if memory is locally used within a
7671 * function and freed within the same function. For this purpose, SCIP has a list of memory buffers that are reused for
7672 * this purpose. In this way, a very efficient allocation/freeing is possible.
7673 *
7674 * Note that the buffers are organized in a stack, i.e., freeing buffers in reverse order of allocation is faster.
7675 *
7676 * The most important functions are
7677 * - SCIPallocBuffer(), SCIPallocBufferArray() to allocate memory,
7678 * - SCIPfreeBuffer(), SCIPfreeBufferArray() to free memory.
7679 *
7680 * @subsection BUFMEMCLEAN Clean Buffer Memory
7681 *
7682 * SCIP 3.2 introduced a new type of buffer memory, the <em>clean buffer</em>. It provides memory which is initialized to zero
7683 * and requires the user to reset the memory to zero before freeing it. This can be used at performance-critical
7684 * places where only few nonzeros are added to a dense array and removing these nonzeros individually is much faster
7685 * than clearing the whole array. Similar to the normal buffer array, the clean buffer should be used for temporary memory
7686 * allocated and freed within the same function.
7687 *
7688 * The most important functions are
7689 * - SCIPallocCleanBufferArray() to allocate memory,
7690 * - SCIPfreeCleanBufferArray() to free memory.
7691 *
7692 * @n
7693 * @section STDMEM Standard memory
7694 *
7695 * SCIP provides an access to the standard C functions @c malloc and @c free with the additional feature of tracking
7696 * memory in debug mode. In this way, memory leaks can be easily detected. This feature is automatically activated in
7697 * debug mode.
7698 *
7699 * The most important functions are
7700 * - SCIPallocMemory(), SCIPallocMemoryArray() to allocate memory,
7701 * - SCIPfreeMemory(), SCIPfreeMemoryArray() to free memory.
7702 *
7703 * @n
7704 * @section MEMBESTPRACTICE Best Practice of Using Memory Functions
7705 *
7706 * Since allocating and freeing memory is very crucial for the speed and memory consumption of a program, it is
7707 * important to keep the following notes and recommendations in mind.
7708 *
7709 * @subsection GEN General Notes
7710 *
7711 * The following holds for all three types of memory functions:
7712 * - In debug mode, the arguments are checked for overly large allocations (usually arising from a bug). Note that all
7713 * arguments are converted to unsigned values of type @c size_t, such that negative sizes are converted into very
7714 * large values.
7715 * - The functions always allocate at least one byte and return non-NULL pointers if memory is available. In particular,
7716 * freeing is always possible.
7717 * - The freeing methods set the pointer to the memory to NULL.
7718 * - Debugging can be supported by using the compiler flags @p NOBLKMEM=true, @p NOBUFMEM=true, @p NOBLKBUFMEM=true
7719 * that turn off the usage of block memory, buffer memory, as well as block and buffer memory, respectively. Since,
7720 * the internal block and buffer memory is freed at the end (leaving no memory leaks), turning them off allows tools
7721 * like valgrind to find memory leaks.
7722 * - Moreover, additional checks can be turned on by defining @p CHECKMEM in memory.c.
7723 *
7724 * @n
7725 * @subsection DOS Things to do ...
7726 *
7727 * - Use buffer memory if your memory chunk can be allocated and freed within the same function.
7728 * - Use buffer and block memory wherever possible, because of the reasons explained above.
7729 * - Free memory in the reverse order in which it was allocated! For block and buffer memory this @b significantly
7730 * speeds up the code.
7731 * - Use as few memory allocations/freeing operations as possible, since these functions take a significant amount of time.
7732 *
7733 * @n
7734 * @subsection DONTS Things to avoid ...
7735 *
7736 * - Avoid the usage of standard memory, since SCIP is unaware of the size used in such blocks.
7737 * - Avoid reallocation with only slightly increased size, rather use a geometrically growing
7738 * size allocation. SCIPcalcMemGrowSize() is one way to calculate new sizes.
7739 * - Be careful with buffer memory reallocation: For single buffers, the memory is reallocated (using malloc); since
7740 * the actual space might be larger than what was needed at allocation time, reallocation sometimes comes without
7741 * extra cost. Note that reallocating block memory in most cases implies moving memory arround.
7742 */
7743
7744/*--+----1----+----2----+----3----+----4----+----5----+----6----+----7----+----8----+----9----+----0----+----1----+----2*/
7745
7746/**@page DEBUG Debugging
7747 *
7748 * If you need to debug your own code that uses SCIP, here are some tips and tricks:
7749 *
7750 * - Use <b>asserts</b> in your code to show preconditions for the parameters, invariants and postconditions.
7751 * Assertions are boolean expressions which inevitably have to evaluate to <code>TRUE</code>. Consider the
7752 * following example:
7753 *
7754 * @refsnippet{src/scip/cons_linear.c,SnippetDebugAssertions}
7755 *
7756 * As you can see, both pointers and integers are checked for valid values at the beginning of the
7757 * function <code>consCatchEvent()</code>. This is particularly important for, e.g., array indices like
7758 * the variable <code>pos</code> in this example, where using the <code>consdata->vars[pos]</code>
7759 * pointer could result in unexspected behaviour
7760 * if the asserted precondition on <code>pos</code> were not matched and <code>pos</code> were an arbitrary index
7761 * outside the array range.
7762 *
7763 * - In order to activate assertions, use the <b>Debug mode</b> by compiling SCIP via
7764 * \code
7765 * cmake -DCMAKE_BUILD_TYPE=Debug
7766 * \endcode
7767 * or the Makefile equivalent
7768 * \code
7769 * make OPT=dbg
7770 * \endcode and run the code. See \ref CMAKE and \ref MAKE for further information about compiler options for SCIP.
7771 * As a rule of thumb, Spending only little extra time on
7772 * asserting preconditions saves most of the time spent on debugging!
7773 *
7774 * - Turn on <b>additional debug output</b> by adding the line
7775 * \code
7776 * #define SCIP_DEBUG
7777 * \endcode
7778 * at the top of SCIP files you want to analyze. This will output messages included in the code using
7779 * <code>SCIPdebugMsg(scip, ...)</code> (or <code>SCIPdebugMessage()</code>), see \ref EXAMPLE_1.
7780 * We recommend to also use <code>SCIPdebugMsg(scip, ...)</code> in your own code for being able to activate
7781 * debug output in the same way.
7782 * - If available on your system, we recommend to use a debugger like <code>gdb</code>
7783 * to trace all function calls on the stack,
7784 * display values of certain expressions, manually break the running code, and so forth.
7785 * - If available on your system, you can use software like <a href="http://valgrind.org">valgrind</a> to check for uninitialized
7786 * values or segmentation faults.
7787 * - For checking the usage of SCIP memory, you can use
7788 * <code>SCIPprintMemoryDiagnostic()</code>. This outputs memory that is currently in use,
7789 * which can be useful after a <code>SCIPfree()</code> call.
7790 * - If there are memory leaks for which you cannot detect the origin, you can recompile your code with the option <code>cmake -DNOBLKBUFMEM=on</code>
7791 * (or <code>make NOBLKBUFMEM=true</code> if you are using the Makefile system.
7792 * Also for the Makefile system, do not forget to clean your code before with <code>make OPT=... LPS=... clean</code>)
7793 * Only with that change, valgrind (or similar) reliably helps
7794 * to detect leaked memory.
7795 * - If your code cuts off a feasible solution, but you do not know which component is responsible,
7796 * you can use the debugging mechanism (see \ref EXAMPLE_2). Therefore, a given solution is read and it
7797 * is checked for every reduction, whether the solution will be pruned globally.
7798 *
7799 * @section EXAMPLE_1 How to activate debug messages
7800 * For example, if we include a <code>\#define SCIP_DEBUG</code> at the top of \ref heur_oneopt.c, recompile SCIP
7801 * in Debug mode, and run the SCIP interactive shell to solve p0033.mps from the
7802 * <a href="http://miplib2010.zib.de/miplib3/miplib.html">MIPLIB 3.0</a> , we get some output like:
7803 *
7804 * \include debugexamples/example1.txt
7805 *
7806 * @section EXAMPLE_2 How to add a debug solution
7807 *
7808 * Continuing the example above, we finish the solving process.
7809 * The optimal solution can now be written to a file:
7810 * \include debugexamples/example2_1.txt
7811 *
7812 * If we afterwards recompile SCIP with the additional compiler flag <code>cmake -DDEBUGSOL=on</code> (<code>make DEBUGSOL=true</code> in the Makefile system),
7813 * set the parameter <code>misc/debugsol = check/p0033.sol</code>, and run SCIP again it will output:
7814 * \include debugexamples/example2_2.txt
7815 * Further debug output would only appear, if the solution was cut off in the solving process.
7816 */
7817
7818/*--+----1----+----2----+----3----+----4----+----5----+----6----+----7----+----8----+----9----+----0----+----1----+----2*/
7819
7820/**@page STAGES SCIP stages
7821 *
7822 * The SCIP object goes through different stages during the solving process, the transitions from one to the next are presented in the following diagram.
7823 * \image html stages.png
7824 * More exhaustively, the stages are:
7825 * \code
7826 * SCIP_STAGE_INIT = 0, /**< SCIP data structures are initialized, no problem exists
7827 * SCIP_STAGE_PROBLEM = 1, /**< the problem is being created and modified
7828 * SCIP_STAGE_TRANSFORMING = 2, /**< the problem is being transformed into solving data space
7829 * SCIP_STAGE_TRANSFORMED = 3, /**< the problem was transformed into solving data space
7830 * SCIP_STAGE_INITPRESOLVE = 4, /**< presolving is initialized
7831 * SCIP_STAGE_PRESOLVING = 5, /**< the problem is being presolved
7832 * SCIP_STAGE_EXITPRESOLVE = 6, /**< presolving is exited
7833 * SCIP_STAGE_PRESOLVED = 7, /**< the problem was presolved
7834 * SCIP_STAGE_INITSOLVE = 8, /**< the solving process data is being initialized
7835 * SCIP_STAGE_SOLVING = 9, /**< the problem is being solved
7836 * SCIP_STAGE_SOLVED = 10, /**< the problem was solved
7837 * SCIP_STAGE_EXITSOLVE = 11, /**< the solving process data is being freed
7838 * SCIP_STAGE_FREETRANS = 12, /**< the transformed problem is being freed
7839 * SCIP_STAGE_FREE = 13 /**< SCIP data structures are being freed
7840 * \endcode
7841 * Most functions can be called in a subset of the stages, this is then documented, a runtime check is often added and will throw a \ref SCIP_INVALIDCALL if the stage is not allowed.
7842 */
7843
7844/*--+----1----+----2----+----3----+----4----+----5----+----6----+----7----+----8----+----9----+----0----+----1----+----2*/
7845
7846/**@page TEST How to run automated tests with SCIP
7847 *
7848 * SCIP comes along with a set of useful tools that allow to perform automated tests. The
7849 * following is a step-by-step guide from setting up the test environment for evaluation and
7850 * customization of test runs.
7851 *
7852 *
7853 * @section SETUP Setting up the test environment
7854 *
7855 * At first you should create a file listing all problem instances that should be part of the test.
7856 * This file has to be located in the the directory <code>scip/check/testset/</code>
7857 * and has to have the file extension <code>.test</code>, e.g., <code>testrun.test</code>,
7858 * in order to be found by the <code>scip/check/check.sh</code> script.
7859 * \n
7860 * All test problems can be listed in the <code>test</code>-file by a relative path,
7861 * e.g., <code>../../problems/instance1.lp</code> or absolute path, e.g., <code>/home/problems/instance2.mps</code>
7862 * in this file. Only one problem should be listed on every line (since the command <code>cat</code> is used to parse this file).
7863 * Note that these problems have to be readable for SCIP in order to solve them.
7864 * However, you can use different file formats.
7865 *
7866 * Optionally, you can provide a solution file in the <code>scip/check/testset/</code> directory containing
7867 * known information about the feasibility and the best known objective values for the test instances.
7868 * SCIP can use these values to verify the results. The file has to have the same basename as the
7869 * <code>.test</code>-file, i.e., in our case <code>testrun.solu</code>. One line can only contain
7870 * information about one test instance. A line has to start with the type of information given:
7871 *
7872 * - <code>=opt=</code> stating that a problem name with an optimal objective value follows
7873 * - <code>=best=</code> stating that a problem name with a best know objective value follows
7874 * - <code>=inf=</code> stating that a problem name follows which is infeasible
7875 *
7876 * With these information types you can encode for an instance named <code>instance1.lp</code> the following
7877 * information:
7878 * - The instance has a known optimal (objective) value of 10.
7879 * \code
7880 * =opt= instance1 10
7881 * \endcode
7882 * - The instance has a best known solution with objective value 15.
7883 * \code
7884 * =best= instance1 15
7885 * \endcode
7886 * - The instance is feasible (but has no objective function or we don't know a solution value)
7887 * \code
7888 * =feas= instance1
7889 * \endcode
7890 * - The instance is infeasible.
7891 * \code
7892 * =inf= instance1
7893 * \endcode
7894 *
7895 * If you don't know whether the instance is feasible or not (so the status is unknown),
7896 * you can omit the instance in the <code>solu</code>-file or write
7897 * \code
7898 * =unkn= instance1
7899 * \endcode
7900 *
7901 * <b>Note that in all lines the file extension of the file name is omitted.</b>
7902 * \n
7903 * See the files <code>scip/check/testset/short.test</code> and <code>scip/check/testset/short.solu</code>
7904 * for an example of a <code>test</code>-file and its corresponding <code>solu</code>-file.
7905 *
7906 *
7907 *
7908 * @section STARTING Starting a test run
7909 *
7910 *
7911 * \code
7912 * make TEST=testrun test
7913 * \endcode
7914 *
7915 * in the SCIP root directory. Note that <code>testrun</code> is exactly the basename of our
7916 * <code>test</code>-file (<code>testrun.test</code>). This will cause SCIP to solve our test instances
7917 * one after another and to create various output files (see \ref EVAL).
7918 *
7919 *
7920 * @section EVAL Evaluating a test run
7921 *
7922 * During computation, SCIP automatically creates the directory <code>scip/check/results/</code>
7923 * (if it does not already exist) and stores the following output files there.
7924 *
7925 * \arg <code>*.out</code> - output of <code>stdout</code>
7926 * \arg <code>*.err</code> - output of <code>stderr</code>
7927 * \arg <code>*.set</code> - copy of the used settings file
7928 *
7929 * \arg <code>*.res</code> - ASCII table containing a summary of the computational results
7930 * \arg <code>*.tex</code> - TeX table containing a summary of the computational results
7931 * \arg <code>*.pav</code> - <a href="http://www.gamsworld.org/performance/paver/">PAVER</a> output
7932 *
7933 * The last three files in the above list, i.e., the files containing a summary of the computational results,
7934 * can also be generated manually. Therefore the user has to call the <code>evalcheck.sh</code> script in the
7935 * @c check directory with the corresponding @c out file as argument. For example, this may be useful if the user stopped the
7936 * test before it was finished, in which case the last three files will not be automatically generated by SCIP.
7937 *
7938 * The last column of the ASCII summary table contains the solver status. We distinguish the following statuses: (in order of priority)
7939 *
7940 * \arg abort: solver broke before returning solution
7941 * \arg fail: solver cut off a known feasible solution (value of the <code>solu</code>-file is beyond the dual bound;
7942 * especially if problem is claimed to be solved but solution is not the optimal solution)
7943 * <b>or</b> if a final solution check revealed a violation of one of the original constraints.
7944 * \arg ok: solver solved problem with the value in solu-file
7945 * \arg solved: solver solved problem which has no (optimal) value in solu-file (since we here cannot detect the direction
7946 * of optimization, it is possible that a solver claims an optimal solution which contradicts a known feasible solution)
7947 * \arg better: solver found solution better than known best solution (or no solution was noted in the <code>solu</code>-file so far)
7948 * \arg gaplimit, sollimit: solver reached gaplimit or limit of number of solutions (at present: only in SCIP)
7949 * \arg timeout: solver reached any other limit (like time or nodes)
7950 * \arg unknown: otherwise
7951 *
7952 * Additionally the <code>evalcheck.sh</code> script can generate a <code>solu</code>-file by calling
7953 * \code
7954 * ./evalcheck.sh writesolufile=1 NEWSOLUFILE=<solu-file> <out-file>
7955 * \endcode
7956 * where <code><solu-file></code> denotes the filename of the new file where the solutions shall be
7957 * (and <code><out-file></code> denotes the output (<code>.out</code>) files to evaluate).
7958 *
7959 * Another feature can be enabled by calling:
7960 * \code
7961 * ./evalcheck.sh printsoltimes=1 ...
7962 * \endcode
7963 * The output has two additional columns containing the solving time until the first and the best solution was found.
7964 *
7965 *
7966 * @b Note: The @em basename of all these files is the same and has the following structure
7967 * which allows us to reconstruct the test run:
7968 *
7969 * \code
7970 * check.<test name>.<binary>.<machine name>.<setting name>
7971 * \endcode
7972 *
7973 * \arg <<code>test name</code>> indicates the name of the the test file, e.g., <code>testrun</code>
7974 * \arg <<code>binary</code>> defines the used binary, e.g., <code>scip-3.2.0.linux.x86_64.gnu.opt.spx</code>
7975 * \arg <<code>machine name</code>> tells the name of the machine, e.g., <code>mycomputer</code>
7976 * \arg <<code>setting name</code>> denotes the name of the used settings, e.g., <code>default</code>
7977 * means the (SCIP) default settings were used
7978 *
7979 * Using the examples out of the previous listing the six file names would have the name:
7980 *
7981 * \code
7982 * check.testrun.scip-1.1.0.linux.x86.gnu.opt.spx.mycomputer.default.<out,err,set,res,tex,pav>
7983 * \endcode
7984 *
7985 *
7986 * @section USING Using customized setting files
7987 *
7988 * It is possible to use customized settings files for the test run instead of testing SCIP with default settings.
7989 * These have to be placed in the directory <code>scip/settings/</code>.
7990 *
7991 * @b Note: Several common user parameters such as, e.g., the time limit and node limit parameters,
7992 * <b>cannot</b> be controlled by the settings file, whose specifications would be overwritten
7993 * by optional command line arguments to the <code>make test</code> command, see @ref ADVANCED
7994 * for a list of available advanced testing options that have to be specified from the command line.
7995 *
7996 * @b Note: Accessing settings files in subfolders of the @c settings directory is currently not supported.
7997 *
7998 * To run SCIP with a custom settings file, say for example <code>fast.set</code>, we call
7999 *
8000 * \code
8001 * make TEST=testrun SETTINGS=fast test
8002 * \endcode
8003 *
8004 * in the SCIP root directory. It is possible to enter a list of settings files as a double-quoted,
8005 * comma-separated list of settings names as <code>fast</code> above, i.e. <code>SETTINGS="fast,medium,slow"</code>
8006 * will invoke the solution process for every instance with the three settings <code>fast.set, medium.set, slow.set</code>
8007 * before continuing with the next instance from the <code>.test</code>-file. This may come in handy if the
8008 * whole test runs for a longer time and partial results are already available.
8009 *
8010 *
8011 * @section ADVANCED Advanced options
8012 *
8013 * We can further customize the test run by specifying the following options in the <code>make</code> call:
8014 *
8015 * \arg <code>CONTINUE</code> - continue the test run if it was previously aborted [default: "false"]
8016 * \arg <code>DISPFREQ</code> - display frequency of the output [default: 10000]
8017 * \arg <code>FEASTOL</code> - LP feasibility tolerance for constraints [default: "default"]
8018 * \arg <code>LOCK</code> - should the test run be locked to prevent other machines from performing the same test run [default: "false"]
8019 * \arg <code>MAXJOBS=n</code> - run tests on 'n' cores in parallel. Note that several instances are solved in parallel, but
8020 * only one thread is used per job (parallelization is not that easy) [default: 1]
8021 * \arg <code>MEM</code> - memory limit in MB [default: 6144]
8022 * \arg <code>NODES</code> - node limit [default: 2100000000]
8023 * \arg <code>TIME</code> - time limit for each test instance in seconds [default: 3600]
8024 * \arg <code>SETCUTOFF</code> - if set to '1', an optimal solution value (from the <code>.solu</code>-file) is used as objective limit [default: 0]
8025 * \arg <code>THREADS</code> - the number of threads used for solving LPs, if the linked LP solver supports multithreading [default: 1]
8026 * \arg <code>VALGRIND</code> - run valgrind on the SCIP binary; errors and memory leaks found by valgrind are reported as fails [default: "false"]
8027 *
8028 *
8029 * @section COMPARE Comparing test runs for different settings
8030 *
8031 * Often test runs are performed on the basis of different settings. In this case, it is useful to
8032 * have a performance comparison. For this purpose, we can use the <code>allcmpres.sh</code> script in
8033 * the @c check directory.
8034 *
8035 * Suppose, we performed our test run with two different settings, say <code>fast.set</code> and
8036 * <code>slow.set</code>. Assuming that all other parameters (including the SCIP binary), were the same,
8037 * we may have the following <code>res</code>-files in the directory <code>scip/check/results/</code>
8038 *
8039 * \code
8040 * check.testrun.scip-3.2.0.linux.x86_64.gnu.opt.spx.mycomputer.fast.res
8041 * check.testrun.scip-3.2.0.linux.x86_64.gnu.opt.spx.mycomputer.slow.res
8042 * \endcode
8043 *
8044 * For a comparison of both computations, we simply call
8045 *
8046 * \code
8047 * allcmpres.sh results/check.testrun.scip-3.2.0.linux.x86_64.gnu.opt.spx.mycomputer.fast.res \
8048 * results/check.testrun.scip-3.2.0.linux.x86_64.gnu.opt.spx.mycomputer.slow.res
8049 * \endcode
8050 *
8051 * in the @c check directory. This produces an ASCII table on the console that provide a detailed
8052 * performance comparison of both test runs. Note that the first <code>res</code>-file serves as reference
8053 * computation. The following list explains the output.
8054 * (The term "solver" can be considered as the combination of SCIP with a specific setting file.)
8055 *
8056 * \arg <code>Nodes</code> - Number of processed branch-and-bound nodes.
8057 * \arg <code>Time</code> - Computation time in seconds.
8058 * \arg <code>F</code> - If no feasible solution was found, then '#', empty otherwise.
8059 * \arg <code>NodQ</code> - Equals Nodes(i) / Nodes(0), where 'i' denotes the current solver and '0' stands for the reference solver.
8060 * \arg <code>TimQ</code> - Equals Time(i) / Time(0).
8061 * \arg <code>bounds check</code> - Status of the primal and dual bound check.
8062 *
8063 * \arg <code>proc</code> - Number of instances processed.
8064 * \arg <code>eval</code> - Number of instances evaluated (bounds check = "ok", i.e., solved to optimality
8065 * within the time and memory limit and result is correct). Only these instances are used in the calculation
8066 * of the mean values.
8067 * \arg <code>fail</code> - Number of instances with bounds check = "fail".
8068 * \arg <code>time</code> - Number of instances with timeout.
8069 * \arg <code>solv</code> - Number of instances correctly solved within the time limit.
8070 * \arg <code>wins</code> - Number of instances on which the solver won (i.e., the
8071 * solver was at most 10% slower than the fastest solver OR had the best
8072 * primal bound in case the instance was not solved by any solver within
8073 * the time limit).
8074 * \arg <code>bett</code> - Number of instances on which the solver was better than the
8075 * reference solver (i.e., more than 10% faster).
8076 * \arg <code>wors</code> - Number of instances on which the solver was worse than the
8077 * reference solver (i.e., more than 10% slower).
8078 * \arg <code>bobj</code> - Number of instances on which the solver had a better primal
8079 * bound than the reference solver (i.e., a difference larger than 10%).
8080 * \arg <code>wobj</code> - Number of instances on which the solver had a worse primal
8081 * bound than the reference solver (i.e., a difference larger than 10%).
8082 * \arg <code>feas</code> - Number of instances for which a feasible solution was found.
8083 * \arg <code>gnodes</code> - Geometric mean of the processed nodes over all evaluated instances.
8084 * \arg <code>shnodes</code> - Shifted geometric mean of the processed nodes over all evaluated instances.
8085 * \arg <code>gnodesQ</code> - Equals nodes(i) / nodes(0), where 'i' denotes the current
8086 * solver and '0' stands for the reference solver.
8087 * \arg <code>shnodesQ</code> - Equals shnodes(i) / shnodes(0).
8088 * \arg <code>gtime</code> - Geometric mean of the computation time over all evaluated instances.
8089 * \arg <code>shtime</code> - Shifted geometric mean of the computation time over all evaluated instances.
8090 * \arg <code>gtimeQ</code> - Equals time(i) / time(0).
8091 * \arg <code>shtimeQ</code> - Equals shtime(i) / shtime(0).
8092 * \arg <code>score</code> - N/A
8093 *
8094 * \arg <code>all</code> - All solvers.
8095 * \arg <code>optimal auto settings</code> - Theoretical result for a solver that performed 'best of all' for every instance.
8096 * \arg <code>diff</code> - Solvers with instances that differ from the reference solver in the number of
8097 * processed nodes or in the total number of simplex iterations.
8098 * \arg <code>equal</code> - Solvers with instances whose number of processed nodes and total number of
8099 * simplex iterations is equal to the reference solver (including a 10% tolerance) and where no timeout
8100 * occured.
8101 * \arg <code>all optimal</code> - Solvers with instances that could be solved to optimality by
8102 * <em>all</em> solvers; in particular, no timeout occurred.
8103 *
8104 * Since this large amount of information is not always needed, one can generate a narrower table by calling:
8105 * \code
8106 * allcmpres.sh short=1 ...
8107 * \endcode
8108 * where <code>NodQ</code>, <code>TimQ</code> and the additional comparison tables are omitted.
8109 *
8110 * If the <code>res</code>-files were generated with the parameter <code>printsoltimes=1</code>
8111 * we can enable the same feature here as well by calling:
8112 * \code
8113 * allcmpres.sh printsoltimes=1 ...
8114 * \endcode
8115 * As in the evaluation, the output contains the two additional columns of the solving time until the first and the best solution was found.
8116 *
8117 * @section STATISTICS Statistical tests
8118 *
8119 * The \c allcmpres script also performs two statistical tests for comparing different settings: For deciding whether
8120 * more feasible solutions have been found or more instances have been solved to optimality or not, we use a McNemar
8121 * test. For comparing the running time and number of nodes, we use a variant of the Wilcoxon signed rank test. A
8122 * detailed explanation can be found in the PhD thesis of Timo Berthold (Heuristic algorithms in global MINLP solvers).
8123 *
8124 * @subsection McNemar McNemar test
8125 *
8126 * Assume that we compare two settings \c S1 and \c S2 with respect to the number of instances solved to optimality
8127 * within the timelimit. The null hypothesis would be "Both settings lead to an equal number of instances being solved
8128 * to optimality", which we would like to disprove. Let \f$n_1\f$ be the number of instances solved by setting \c S1
8129 * but not by \c S2, and let \f$n_2\f$ be the number of instances solved by setting \c S2 but not by \c S1. The
8130 * McNemar test statistic is
8131 * \f[
8132 * \chi^2 = \frac{(n_1 - n_2)^2}{n_1 + n_2}.
8133 * \f]
8134 * Under the null hypothesis, \f$\chi^2\f$ is chi-squared distributed with one degree of freedom. This allows to compute
8135 * a \f$p\f$-value as the probability for obtaining a similar or even more extreme result under the null hypothesis.
8136 * More explicitly, \c allcmpres uses the following evaluation:
8137 * - \f$0.05 < p\f$: The null hypothesis is accepted (marked by "X").
8138 * - \f$0.005 < p \leq 0.05\f$: The null hypothesis might be false (marked by "!").
8139 * - \f$0.0005 < p \leq 0.005\f$: The null hypothesis can be false (marked by "!!").
8140 * - \f$p \leq 0.0005\f$: The null hypothesis is very likely false (marked by "!!!").
8141 *
8142 * As an example consider the following output:
8143 * \code
8144 * McNemar (feas) x2 0.0000, 0.05 < p X
8145 * McNemar (opt) x2 6.0000, p ~ (0.005, 0.05] !
8146 * \endcode
8147 * Here, \c x2 represents \f$\chi^2\f$.
8148 *
8149 * In this case, the test with respect to the number of found feasible solutions is irrelevant, since their number is
8150 * equal. In particular, the null hypothesis gets accepted (i.e., there is no difference in the settings - this is
8151 * marked by "X").
8152 *
8153 * With respect to the number of instances solved to optimality within the timelimit, we have that \f$0.005 < p <=
8154 * 0.05\f$ (marked by <tt>p ~ (0.005, 0.05)</tt>). Thus, there is some evidence that the null hypothesis is false, i.e., the
8155 * settings perform differently; this is marked by "!". In the concrete case, we have 230 instances, all of which are
8156 * solved by setting \c S2, but only 224 by setting \c S1.
8157 *
8158 * @subsection Wilcoxon Wilcoxon signed rank test
8159 *
8160 * Assume that we compare two settings \c S1 and \c S2 with respect to their solution times (within the time limit). We
8161 * generate a sorted list of the ratios of the run times, where ratios that are (absolutely or relatively) within 1\%
8162 * of 1.0 are discarded, and ratios between 0.0 and 0.99 are replaced with their negative inverse in order to
8163 * obtain a symmetric distribution for the ratios around the origin.
8164 * We then assign ranks 1 to \c N to the remaining \c N data points in nondecreasing
8165 * order of their absolute ratio. This yields two groups \c G1
8166 * and \c G2 depending on whether the ratios are smaller than -1.0 or larger than 1.0 (\c G1 contains the instances for which
8167 * setting \c S1 is faster). Then the sums of the ranks in groups \c G1 and \c G2 are computed, yielding values \c R1
8168 * and \c R2, respectively.
8169 *
8170 * The Wilcoxon test statistic is then
8171 * \f[
8172 * z = \frac{\min(R1, R2) - \frac{N(N+1)}{4}}{\sqrt{\frac{N(N+1)(2N+1)}{24}}},
8173 * \f]
8174 * which we assume to be (approximately) normally distributed (with zero mean) and allows to compute the probability
8175 * \f$p\f$ that one setting is faster than the other. (Note that for \f$N \leq 60\f$, we apply a correction by
8176 * subtracting 0.5 from the numerator).
8177 *
8178 * As an example consider the following output:
8179 * \code
8180 * Wilcoxon (time) z -0.1285, 0.05 <= p X
8181 * Wilcoxon (nodes) z -11.9154, p < 0.0005 !!!
8182 * \endcode
8183 * While the \f$z\f$-value is close to zero for the run time, it is extremely negative regarding the solving nodes. This latter
8184 * tendency for the number of nodes is significant on a 0.05 % level, i.e., the probability \f$p\f$ that setting \c S1 uses more
8185 * nodes than setting \c S2 is negligible (this null hypothesis is rejected - marked by "!!!").
8186 *
8187 * However, the null hypothesis is not rejected with respect to the run time. In the concrete case, setting \c S1 has a
8188 * shifted geometric mean of its run times (over 230 instances) of 248.5, for \c S2 it is 217.6. This makes a ratio of
8189 * 0.88. Still - the null hypothesis is not rejected.
8190 *
8191 * @section SOLVER Testing and Evaluating using GAMS
8192 *
8193 * Analogously to the target <code>test</code> there is another target to run automated tests with <a href="http://www.gams.com/">gams</a>
8194 * \code
8195 * make testgams GAMSSOLVER=xyz
8196 * \endcode
8197 * For this target, the option GAMSSOLVER has to be given to specify the name of a GAMS solver to run, e.g. GAMSSOLVER=SCIP.
8198 * Additional advanced options specific to this target are:
8199 * GAMS to specify the GAMS executable (default: gams),
8200 * GAP to specify a gap limit (default: 0.0),
8201 * CLIENTTMPDIR to specify a directory where GAMS should put its scratch files (default: /tmp),
8202 * CONVERTSCIP to specify a SCIP which can be used to convert non-gams files into gams format (default: bin/scip, if existing; set to "no" to disable conversion).
8203 * The following options are NOT supported (and ignored): DISPFREQ, FEASTOL, LOCK.
8204 * A memory limit (MEM option) is only passed as workspace option to GAMS, but not enforced via ulimit (it's up to the solver to regard and obey the limit).
8205 *
8206 * Note: This works only if the referred programs are installed globally on your machine.
8207 *
8208 * The above options like <code>TIME</code> are also available for gams.
8209 *
8210 * After the testrun there should be an <code>.out</code>, an <code>.err</code> and a <code>.res</code> file
8211 * with the same basename as described above.
8212 *
8213 * Furthermore you can also use the script <code>allcmpres.sh</code> for comparing results.
8214 *
8215 * @section PYTHON Testing using PySCIPOpt
8216 *
8217 * To run a python script that uses PySCIPOpt with <code>make test</code> or <code>make testcluster</code>, one has to
8218 * specify the python code to execute with the option <code>EXECUTABLE=/full/path/to/python-script.py</code>.
8219 * Note that <code>python-script.py</code> must be an executable file.
8220 * In addition, one <b>must</b> specify which python it should run with the option <code>PYTHON=my-python</code>.
8221 * The reason for this is that one usually installs PySCIPOpt in a virtual environment, thus only the python of the
8222 * virtual environment will work with the python script.
8223 *
8224 * The scripts work in such a way that they pass information to SCIP like the setting files, the instance name, and some other options.
8225 * It is the responsability of the python script <code>python-script.py</code> to parse this information.
8226 * Thus, you need to modify your python script to read the setting files and the other options provided by the testing scripts.
8227 * An example of how to do this is provided in <code>scip/check/scip-runner.py</code>.
8228 * One should either modify <code>scip/check/scip-runner.py</code> or include the <code>build_model()</code> function
8229 * into your script to correctly read the options passed by the scripts.
8230 *
8231 * An example of how to run the tests is
8232 * \code
8233 * make test EXECUTABLE=/full/path/to/scip/check/scip-runner.py PYTHON=python
8234 * \endcode
8235 */
8236
8237/*--+----1----+----2----+----3----+----4----+----5----+----6----+----7----+----8----+----9----+----0----+----1----+----2*/
8238
8239/**@page COUNTER How to use SCIP to count/enumerate feasible solutions
8240 *
8241 * SCIP is capable of computing (count or enumerate) the number of feasible solutions of a given constraint integer
8242 * program. In case continuous variables are present, the number of feasible solutions for the projection to the
8243 * integral variables is counted/enumerated. This means, an assignment to the integer variables is counted if the
8244 * remaining problem (this is the one after fixing the integer variables w.r.t. to this assignment) is feasible.
8245 *
8246 * As a first step you have to load or create your problem in the usual way. In case of using the
8247 * interactive shell, you use the <code>read</code> command:
8248 *
8249 * <code>SCIP&gt; read &lt;file name&gt;</code>
8250 *
8251 * Afterwards you can count the number of feasible solution with the command <code>count</code>.
8252 *
8253 * <code>SCIP&gt; count</code>
8254 *
8255 * @note After completing the counting process, SCIP will terminate with status <tt>infeasible</tt>. This is intended
8256 * behavior, because SCIP counts solutions by the following internal mechanism. Each feasible solution that is found is
8257 * reported as infeasible to the SCIP core. This avoids that SCIP performs reductions based on the primal bound that
8258 * could cut off suboptimal feasible solutions, which would then be missing in the count. However, as a result, the
8259 * SCIP core has not found any feasible solutions during the search and reports status <tt>infeasible</tt>.
8260 *
8261 * By default, SCIP only counts the number of solutions but does not store (enumerate) them. If you are interested in
8262 * that see \ref COLLECTALLFEASEBLES.
8263 *
8264 * @note Since SCIP version 2.0.0 you do not have to worry about the impact of dual reductions anymore. These are
8265 * automatically turned off. The only thing you should switch off are restarts. These restarts can lead to a wrong
8266 * counting process. We recommend using the counting settings which can be set in the interactive shell as follows:
8267 *
8268 * <code>SCIP&gt; set emphasis counter</code>
8269 *
8270 * The SCIP callable library provides an interface method SCIPcount() which allows users to count the number of feasible
8271 * solutions to their problem. The method SCIPsetParamsCountsols(), which is also located in cons_countsols.h, loads the
8272 * predefined counting settings to ensure a safe count. The complete list of all methods that can be used for counting
8273 * via the callable library can be found in cons_countsols.h.
8274 *
8275 *
8276 * @section COUNTLIMIT Limit the number of solutions which should be counted
8277 *
8278 * It is possible to give a (soft) upper bound on the number solutions that should be counted. If this upper bound is
8279 * exceeded, SCIP will be stopped. The name of this parameter is <code>constraints/countsols/sollimit</code>. In
8280 * the interactive shell this parameter can be set as follows:
8281 *
8282 * <code>SCIP&gt; set constraints countsols sollimit 1000</code>
8283 *
8284 * In case you are using the callable library, this upper bound can be assigned by calling SCIPsetLongintParam() as follows:
8285 *
8286 * \code
8287 * SCIP_CALL( SCIPsetLongintParam( scip, "constraints/countsols/sollimit", 1000) );
8288 * \endcode
8289 *
8290 *
8291 * The reason why this upper bound is soft comes from the fact that, by default, SCIP uses a technique called unrestricted
8292 * subtree detection. Using this technique it is possible to detect several solutions at once. Therefore, it can happen
8293 * that the solution limit is exceeded before SCIP is stopped.
8294 *
8295 * @section COLLECTALLFEASEBLES Collect all feasible solutions
8296 *
8297 * Per default SCIP only counts all feasible solutions. This means, these solutions are not stored. If you switch the
8298 * parameter <code>constraints/countsols/collect</code> to TRUE (the default value is FALSE) the detected solutions are
8299 * stored. Changing this parameter can be done in the interactive shell
8300 *
8301 * <code>SCIP&gt; set constraints countsols collect TRUE</code>
8302 *
8303 * as well as via the callable library
8304 *
8305 * \code
8306 * SCIP_CALL( SCIPsetBoolParam( scip, "constraints/countsols/collect", TRUE) );
8307 * \endcode
8308 *
8309 * @note The solution which are collected are stored w.r.t. the active variables. These are the variables which got not
8310 * removed during presolving.
8311 *
8312 * In case you are using the interactive shell you can write all collected solutions to a file as follows
8313 *
8314 * <code>SCIP&gt; write allsolutions &lt;file name&gt;</code>
8315 *
8316 * In that case the sparse solutions are unrolled and lifted back into the original variable space.
8317 *
8318 * The callable library provides a method which gives access to all collected sparse solutions. That is,
8319 * SCIPgetCountedSparseSolutions(). The sparse solutions you get are defined w.r.t. active variables. To get solutions
8320 * w.r.t. to the original variables. You have to do two things:
8321 *
8322 * -# unroll each sparse solution
8323 * -# lift each solution into original variable space by extending the solution by those variable which got removed
8324 * during presolving
8325 *
8326 * The get the variables which got removed during presolving, you can use the methods SCIPgetFixedVars() and
8327 * SCIPgetNFixedVars(). The method SCIPgetProbvarLinearSum() transforms given variables, scalars and constant to the
8328 * corresponding active variables, scalars and constant. Using this method for a single variable gives a representation
8329 * for that variable w.r.t. the active variables which can be used to compute the value for the considered solution (which
8330 * is defined w.r.t. active variables).
8331 *
8332 * For that complete procedure you can also check the source code of
8333 * \ref SCIP_DECL_DIALOGEXEC(SCIPdialogExecWriteAllsolutions) "SCIPdialogExecWriteAllsolutions()" cons_countsols.c which
8334 * does exactly that.
8335 *
8336 *
8337 * @section COUNTOPTIMAL Count number of optimal solutions
8338 *
8339 * If you are interested in counting the number of optimal solutions, this can be done with SCIP using the
8340 * <code>count</code> command by applying the following steps:
8341 *
8342 * -# Solve the original problem to optimality and let \f$c^*\f$ be the optimal value
8343 * -# Added the objective function as constraint with left and right hand side equal to \f$c^*\f$
8344 * -# load the adjusted problem into SCIP
8345 * -# use the predefined counting settings
8346 * -# start counting the number of feasible solutions
8347 *
8348 * If you do this, SCIP will collect all optimal solutions of the original problem.
8349 *
8350 */
8351
8352/*--+----1----+----2----+----3----+----4----+----5----+----6----+----7----+----8----+----9----+----0----+----1----+----2*/
8353
8354/** @page SYMMETRY How to use symmetry handling in SCIP
8355 *
8356 * Symmetry handling is an important feature of SCIP that allows to discard symmetric subproblems from the
8357 * branch-and-bound tree, and thus, can substantially reduce the running time. To handle symmetries, SCIP
8358 * automatically detects symmetries and then applies (combinations of) symmetry handling methods.
8359 *
8360 * @section SYMDETECT Symmetry detection
8361 *
8362 * SCIP can detect two types of symmetries: permutation symmetries and signed permutation symmetries.
8363 * In a purely integer linear setting
8364 * \f[
8365 * \max \{ c^{\top} x : Ax \leq b,\; x \in \mathbb{Z}^n \},
8366 * \f]
8367 * a permutation symmetry is a permutation \f$\gamma\f$ of \f$\{1,\dots,n\}\f$ that acts on vector \f$x\f$ by
8368 * permuting its coordinates via \f$\gamma(x) = (x_{\gamma^{-1}(1)}, \dots, x_{\gamma^{-1}(n)})\f$
8369 * such that
8370 *
8371 * -# \f$\gamma\f$ leaves the objective invariant, i.e., \f$c^{\top}x = c^{\top}\gamma(x)\f$, and
8372 * -# \f$\gamma\f$ maps feasible solutions onto feasible solutions, i.e., \f$Ax \leq b\f$ if and only
8373 * if \f$A\gamma(x) \leq b\f$.
8374 *
8375 * Signed permutation symmetries are defined similarly and allow to also handle symmetries arising from
8376 * reflections of the feasible region along standard hyperplanes, e.g., mapping \f$x_i\f$ to \f$-x_i\f$
8377 * and keeping the remaining entries of a solution vector \f$x\f$ invariant. Formally, a signed permutation \f$\gamma\f$
8378 * is a permutation of the set \f$\{\pm 1, \dots, \pm n\}\f$ such that \f$\gamma(-i) = - \gamma(i)\f$
8379 * for all \f$i \in \{1,\dots,n\}\f$. A signed permutation acts on a vector \f$x\f$ as
8380 * \f$\gamma(x) = (\mathrm{sgn}(\gamma^{-1}(1))x_{|\gamma^{-1}(1)|},\dots,
8381 * \mathrm{sgn}(\gamma^{-1}(n))x_{|\gamma^{-1}(n)|})\f$,
8382 * where \f$\mathrm{sgn}(\cdot)\f$ is the sign function. The remaining properties of a symmetry are the same.
8383 * It is possible to switch between these two types of symmetries via the
8384 * parameter <code>propagating/symmetry/symtype</code>.
8385 * Moreover, to detect more general signed permutations, one can shift variables with a
8386 * bounded domain to be centered at the origin. This way, also variables with, e.g., domains \f$[1,2]\f$
8387 * and \f$[0,1]\f$ can be symmetric. In SCIP, we implement this shift only within symmetry detection
8388 * to find generalized signed permutations; the variable bounds of the problem itself remain unchanged.
8389 *
8390 * Since both definitions depend on the feasible region of the integer program, which is unknown
8391 * in general, SCIP only computes symmetries that leave the formulation of the optimization problem
8392 * invariant. To detect such formulation symmetries, SCIP builds an auxiliary colored graph whose
8393 * color-preserving automorphisms correspond to symmetries of the integer program. The symmetries of
8394 * the graph, and thus of the integer program, are then computed by an external graph automorphism
8395 * library that needs to be linked to SCIP. Currently, SCIP ships with two such libraries: The graph
8396 * automorphism libraries bliss or nauty/traces are the basic workhorses to detect symmetries. Moreover, one can use
8397 * sassy, a graph symmetry preprocessor which passes the preprocessed graphs to bliss or nauty/traces.
8398 * The current default is to use bliss in combination with sassy for symmetry detection.
8399 *
8400 * @note To detect symmetries, SCIP needs to be built with sassy/bliss, which can be achieved
8401 * by using the options <code>SYM=sassy</code> and <code>-DSYM=sassy</code> in the Makefile and CMake
8402 * system, respectively.
8403 *
8404 * Besides purely integer linear problems, SCIP also supports symmetry detection for general
8405 * constraint mixed-integer programs containing most of the constraint types that can be handled
8406 * by SCIP. In particular, symmetries of mixed-integer nonlinear problems can be detected.
8407 * Moreover, symmetries can also be detected in code containing customized constraints.
8408 * To this end, a suitable callback needs to be implemented, see \ref SYMDETECTCUSTOM.
8409 *
8410 * @subsection SYMPROCESS Processing symmetry information
8411 *
8412 * After symmetries have been computed, SCIP has access to a list \f$\gamma_1,\dots,\gamma_m\f$ of
8413 * (signed) permutations that generate a group \f$\Gamma\f$ of symmetries of the optimization problem. That
8414 * is, SCIP has not access to all permutations in \f$\Gamma\f$, but only a set of generators. Based
8415 * on these generators, SCIP analyzes the group \f$\Gamma\f$ and checks whether it can be split into
8416 * independent factors. That is, whether there exist subgroups \f$\Gamma_1,\dots,\Gamma_k\f$ of
8417 * \f$\Gamma\f$ that act on pairwise independent sets of variables such that \f$\bigcup_{i=1}^k \Gamma_i = \Gamma\f$.
8418 * In this case, SCIP can handle the symmetries of the different subgroups independently. In particular,
8419 * different subgroups can be treated by different symmetry handling methods.
8420 *
8421 * @section SYMMETHODS Symmetry handling methods
8422 *
8423 * Most symmetry handling methods available in SCIP have only been implemented for ordinary permutation symmetries,
8424 * and not for signed permutation symmetries. In the following, we silently assume that the described methods
8425 * deal with ordinary permutation symmetries if not mentioned differently.
8426 * To handle symmetries, SCIP uses three different classes of methods, which we detail below.
8427 *
8428 * @subsection SYMCONSS Static symmetry handling constraints for binary variable domains
8429 *
8430 * SCIP contains three constraint handlers for handling symmetries of binary variables: the symresack,
8431 * orbisack, and orbitope constraint handler. Given a symmetry \f$\gamma\f$,
8432 * the symresack constraint handler enforces that a solution vector \f$x\f$ is not lexicographically
8433 * smaller than its image \f$\gamma(x)\f$. This constraint is enforced by a propagation algorithm
8434 * and separating inequalities. Moreover, given the disjoint cycle decomposition of \f$\gamma\f$,
8435 * SCIP checks, for each cycle of \f$\gamma\f$, whether all variables in the cycle are contained
8436 * in set packing or partitioning constraints. If this is the case, specialized inequalities can
8437 * be separated.
8438 *
8439 * In case the permutation \f$\gamma\f$ is an involution, i.e., \f$\gamma(\gamma(x)) = x\f$,
8440 * specialized separation and propagation algorithms can be used, which are implemented in the
8441 * orbisack constraint handler. For orbisack constraints, also facet-defining inequalities of the
8442 * convex hull of all binary points \f$x\f$ being not lexicographically smaller than \f$\gamma(x)\f$
8443 * can be separated. Since the coefficients in these inequalities grow exponentially large which might
8444 * cause numerical instabilities, the separation of these inequalities is disabled by default, but can be
8445 * enabled via the parameter <code>constraints/orbisack/orbiSeparation</code>. Furthermore, to avoid
8446 * numerical instabilities, the parameter <code>constraints/orbisack/coeffbound</code> controls the
8447 * maximum absolute value of a coefficient in separated facet-defining inequalities.
8448 *
8449 * Finally, the orbitope constraint handler is able to handle symmetries of special symmetric groups \f$\Gamma\f$.
8450 * For orbitopes to be applicable, the affected variables need to be arranged in a matrix \f$X\f$ such that
8451 * the symmetries in \f$\Gamma\f$ permute the columns of \f$X\f$. Symmetries are then handled by orbitope
8452 * constraints by enforcing to only compute solution matrices \f$X\f$ whose columns are sorted lexicographically
8453 * non-increasingly. To this end, a propagation algorithm is used and inequalities are separated. In case
8454 * the variables of each row of the matrix \f$X\f$ are contained in a set packing or partitioning constraint,
8455 * specialized propagation and separation routines are used.
8456 *
8457 * @subsection SYMPROP Dynamic symmetry handling by propagation
8458 *
8459 * Static symmetry handling enforces a lexicographic ordering on the variable solution vectors.
8460 * The pro of that approach, is that throughout the solving process, the same lexicographic ordering constraint
8461 * is used. This means that already during presolving certain symmetry reductions can be made.
8462 * The con of this approach is that an ordering of the variables for lexicographic comparisons have to be made
8463 * before solving. Consequently, if reductions of certain variable domains are found, but these variables are compared
8464 * late by the lexicographic comparison order, the effect for symmetry handling is very slim.
8465 *
8466 * Dynamic symmetry handling addresses this issue by propagating symmetry handling constraints, where the variable
8467 * comparison ordering are determined while solving, attempting to make strong symmetry handling reductions early on.
8468 * Dynamic symmetry handling removes feasible solutions of the problem, while it is guaranteed that at least one
8469 * symmetric solution remains feasible.
8470 *
8471 * Whether dynamic or static symmetry handling methods are used, is determined by the boolean parameter
8472 * <code>propagating/symmetry/usedynamicprop</code>.
8473 * SCIP features three dynamic symmetry handling methods.
8474 * SCIP only provides propagation methods for handling these symmetries,
8475 * and the methods work on variables with arbitrary (so also non-binary) variable domains.
8476 *
8477 * -# Orbitopal reduction is the dynamic counterpart of orbitopal fixing. This method can be used if the variables
8478 * can be arranged without duplicates in a matrix, and symmetries permute the columns of this matrix. This method
8479 * propagates the variable domains such that solutions in matrix-form have lexicographically decreasing columns,
8480 * with respect to the dynamically chosen row and column order.
8481 * Orbitopal reduction respects the parameter <code>propagating/symmetry/detectorbitopes</code>.
8482 * -# Lexicographic reduction is the dynamic counterpart of symresack and orbisack propagation.
8483 * Lexicographic reduction respects the parameter <code>propagating/symmetry/addsymresacks</code>.
8484 * At the moment, the implementation of this method is the only one that allows to also handle signed permutation
8485 * symmetries.
8486 * -# Orbital reduction is a generalization of orbital fixing that also works for non-binary variable domains.
8487 * Orbital reduction respects the 2-bit of the bitset <code>misc/usesymmetry</code>.
8488 * See \ref SYMMETHODSELECT "method selection". Since there is no static counterpart, this method ignores
8489 * <code>propagating/symmetry/usedynamicprop</code>.
8490 *
8491 * In all cases, the dynamic variable ordering is derived from the branching decisions.
8492 * In particular, at different branch-and-bound tree nodes, a different variable ordering can be active.
8493 * Since the symmetries are handled for independent factors of the symmetry group, a different variable ordering method
8494 * can be used for handling symmetries in different factors. In SCIP, the same method is used for orbital reduction and
8495 * for lexicographic reduction, which means that these two methods are compatible and can be used simultaneously in the
8496 * same factor. Orbitopal reduction uses a different method.
8497 *
8498 * As SCIP might restart the branch-and-bound process, which removes information regarding the branching decisions,
8499 * we need to make sure that correct reductions are found after a restart.
8500 * If a restart occurs, static symmetry handling methods are preserved. Since dynamic symmetry handling methods
8501 * depend on the branch-and-bound tree structure, and because the prior branch-and-bound tree is removed,
8502 * the dynamic symmetry handling methods are disabled after a restart.
8503 *
8504 * @subsection SYMSST SST cuts
8505 *
8506 * The Schreier-Sims table (SST) is a table that contains certain information about symmetry groups
8507 * and can be used, among others, to derive symmetry handling inequalities. The corresponding SST cuts
8508 * are symmetry handling inequalities that are defined iteratively in rounds \f$r = 1,\dots,R\f$.
8509 * In each round \f$r\f$, a leader variable \f$\ell_r\f$ is selected and the group
8510 * \f$\Gamma_r = \{ \gamma \in \Gamma : \gamma(\ell_i) = \ell_i \text{ for all } i = 1,\dots,r-1\}\f$
8511 * is considered. Then, the symmetry handling inequalities of round \f$r\f$ are defined as
8512 * \f$x_{\ell_r} \geq x_j\f$ for all \f$j \in \{\gamma(i) : i \in \{1,\dots,n\}\}\f$.
8513 * The latter set is called the orbit of leader \f$\ell_r\f$.
8514 *
8515 * SST cuts admit many degrees of freedom. In particular, they are not limited to binary variables
8516 * but can be used for arbitrary variable types. A user can gain control over the selection process of
8517 * SST cuts via several parameters. For instance,
8518 *
8519 * - <code>sstleadervartype</code> is a bitset encoding the variable types of leaders: the 1-bit models binary,
8520 * the 2-bit integer, the 4-bit implicit integer, and the 8-bit continuous variables. That is, a value
8521 * of 9 models that the leader can be a binary or continuous variable.
8522 * - <code>sstleaderrule</code> ranges from 0 to 2 and models whether a leader is the first variable in
8523 * its orbit, the last variable in its orbit, or a variable with most conflicts with other variables in
8524 * the orbit, respectively.
8525 * - <code>ssttiebreakrule</code> ranges from 0 to 2 and models whether an orbit of minimum size, maximum
8526 * size or with most variables being in conflict to the leader is selected, respectively.
8527 * - <code>sstmixedcomponents</code> whether SST cuts are also applied if a symmetries do not only affect
8528 * variables of a single type.
8529 * - <code>sstaddcuts</code> whether SST cuts are added to the problem. If no cuts are added, only
8530 * binary variables might be fixed to 0 if they are in conflict with the leader.
8531 *
8532 * @subsection SYMMETHODSELECT Selecting symmetry handling methods
8533 *
8534 * The symmetry handling methods explained above can be enabled and disabled via the parameter
8535 * <code>misc/usesymmetry</code>, which encodes the enabled methods via a bitset that ranges between 0
8536 * and 7: the 1-bit encodes symmetry handling constraints, the 2-bit encodes orbital reduction, and the
8537 * 4-bit encodes SST cuts. For example, <code>misc/usesymmetry = 3</code> enables symmetry handling
8538 * constraints and orbital reduction, whereas <code>misc/usesymmetry = 0</code> disables symmetry handling.
8539 * In the following, we explain how the combination of different symmetry handling methods works.
8540 *
8541 * The default strategy of SCIP is to handle symmetries via the bitset value 7, i.e., symmetry handling
8542 * constraints, orbital reduction, and SST cuts are enabled. To make sure that the different methods are
8543 * compatible, the following steps are carried out:
8544 *
8545 * -# SCIP determines independent subgroups \f$\Gamma_1,\dots,\Gamma_k\f$ as described in \ref SYMPROCESS.
8546 * Then, for each subgroup \f$\Gamma_i\f$, different symmetry handling methods can be applied.
8547 * -# For each subgroup \f$\Gamma_i\f$, a heuristic is called that checks whether orbitopes are applicable
8548 * to handle the entire subgroup. If yes, this subgroup is handled by orbitopes and no other
8549 * symmetry handling methods.
8550 * -# Otherwise, if parameter <code>propagating/symmetry/detectsubgroups</code> is <code>TRUE</code>
8551 * and <code>propagating/symmetry/usedynamicprop</code> is <code>FALSE</code>, a
8552 * heuristic is called to detect whether "hidden" orbitopes are present. That is, whether some but not
8553 * all symmetries of \f$\Gamma_i\f$ can be handled by orbitopes. If sufficiently many symmetries can
8554 * be handled by orbitopes, orbitopes are applied and, if parameter <code>propagating/symmetry/addweaksbcs</code>
8555 * is TRUE, some compatible SST cuts are added, too. Besides this, no further symmetry handling methods
8556 * are applied for \f$\Gamma_i\f$.
8557 * -# Otherwise, orbital reduction is used. If <code>propagating/symmetry/usedynamicprop</code> and
8558 * <code>propagating/symmetry/addsymresacks</code> are <code>TRUE</code>, then also the dynamic lexicographic
8559 * reduction method is used.
8560 * -# Otherwise, if the majority of variables affected by \f$\Gamma_i\f$ are non-binary, SST cuts are applied
8561 * to handle \f$\Gamma_i\f$. No further symmetry handling methods are applied for \f$\Gamma_i\f$.
8562 *
8563 * @note If orbital reduction is enabled, a factor \f$\Gamma_i\f$ can always be handled by this method.
8564 * As such, by default, no SST cuts will be added.
8565 *
8566 * @note Depending on the setting of <code>misc/usesymmetry</code>, it might be possible that a symmetry component is
8567 * not handled. For instance, if only orbitopal reduction is used
8568 * (i.e., <code>propagating/symmetry/detectorbitopes</code> is set to 1),
8569 * and if a symmetry component is no orbitope, no symmetry is handled for that component at all.
8570 *
8571 *
8572 * @subsection SYMTIMING Controlling the timing of symmetry computation
8573 *
8574 * Since presolving might both remove and introduce formulation symmetries, the timing of computing symmetries
8575 * can be changed via the parameter <code>propagating/symmetry/symtiming</code>.
8576 * The parameter takes value 0, 1, or 2, corresponding to computing symmetries before presolving,
8577 * during presolving, or at the end of presolving, respectively.
8578 * Based on the computed symmetries, SCIP enables some symmetry handling methods as explained above.
8579 *
8580 * @subsection SYMDETECTCUSTOM Symmetry detection for customized constraints
8581 *
8582 * To detect (signed) permutation symmetries, SCIP requests from each constraint present in the problem to be solved
8583 * a node and edge colored graph whose symmetries correspond to the symmetries of the corresponding constraint.
8584 * This information is provided by two callbacks, the SCIP_DECL_CONSGETPERMSYMGRAPH callback for permutation
8585 * symmetries and the SCIP_DECL_CONSGETSIGNEDPERMSYMGRAPH callback for signed permutation symmetries. If a
8586 * constraint handler does not implement one of these callbacks, SCIP will not detect symmetries of the corresponding
8587 * type.
8588 *
8589 * In the following, we briefly describe how such a symmetry detection graph looks like for linear constraints.
8590 * Afterwards, we mention the basic setup of the symmetry detection graphs and how the callbacks could be implemented
8591 * for customized constraints.
8592 *
8593 * @subsubsection SYMDETECTLINEAR Symmetry detection graphs for linear constraints
8594 *
8595 * Simple permutation symmetries of a linear constraint \f$\sum_{i = 1}^n a_ix_i \leq \beta\f$ are given
8596 * by permutations that exchange equivalent variables with the same coefficients. These symmetries can be encoded
8597 * by a graph with the following structure. For every variable \f$x_i\f$, the graph contains a node \f$v_i\f$
8598 * that receives a color that uniquely determines the type of the variable (lower/upper bound, objective coefficient,
8599 * integrality). Moreover, the graph contains a node \f$w\f$ that receives a color corresponding to the right-hand side
8600 * \f$\beta\f$. Node \f$w\f$ is then connected with all nodes corresponding to variables. Edge \f$\{w,v_i\}\f$ then
8601 * receives a color corresponding to the coefficient \f$a_i\f$. Then, every automorphism of this graph corresponds to a
8602 * permutation symmetry of the linear constraint.
8603 *
8604 * For signed permutation symmetries, almost the same construction can be used. The only difference is that also
8605 * nodes \f$v_{-i}\f$ need to be introduced that correspond to the negation of variable \f$x_i\f$. These negated
8606 * variable nodes are then also connected with node \f$\beta\f$ and the corresponding edge receives color \f$-a_i\f$.
8607 * Finally, to make sure that the corresponding symmetry corresponds to a signed permutation \f$\gamma\f$, i.e.,
8608 * \f$\gamma(-i) = - \gamma(i)\f$, one also needs to add the edges \f$\{v_i,v_{-i}\}\f$ that remain uncolored.
8609 * Note that the color of node \f$v_{-i}\f$ also needs to uniquely determine the negated variable bounds and
8610 * objective coefficient.
8611 *
8612 * @subsubsection SYMDETECTRULES Principles for building symmetry detection graphs
8613 *
8614 * A symmetry detection graph of a constraint needs to have the property that each of its automorphisms corresponds
8615 * to a (signed) permutation of the constraint. Moreover, the corresponding constraint handler of the constraints
8616 * needs to be encoded in the graph to make sure that only symmetries between equivalent constraints can be computed.
8617 * Among others, this can be achieved by assigning the nodes and edges appropriate colors. To make sure that the
8618 * colors are compatible between the different symmetry detection graphs, SCIP automatically determines the colors of
8619 * nodes and edges based on information that is provided by the user (or the creator of the graph).
8620 *
8621 * A pointer to a globally maintained symmetry detection graph is provided to the callbacks. The nodes and edges of the
8622 * graph of a constraint are added to this global graph.
8623 * The nodes of the graph need to be added via the functions <code>SCIPaddSymgraphValnode()</code>
8624 * and <code>SCIPaddSymgraphConsnode()</code>. The first function can be used to create nodes corresponding to
8625 * a numerical value like \f$\beta\f$ in the above example, the latter function creates a node corresponding to
8626 * a provided constraint. This ensures that only symmetry detection graphs from the same constraint handler
8627 * can be isomorphic. The colors of the nodes are then computed automatically by SCIP based on the information
8628 * that is provided the functions creating these nodes. This ensures that node colors are compatible.
8629 *
8630 * Edges are created via the function <code>SCIPaddSymgraphEdge()</code> which receives, among others, the
8631 * indices of created nodes. Note that there is no function for creating variable nodes as SCIP automatically
8632 * creates nodes for variables. Their indices can be accessed via <code>SCIPgetSymgraphVarnodeidx()</code> for
8633 * original variables and <code>SCIPgetSymgraphNegatedVarnodeidx()</code> for negated variables used for
8634 * signed permutations. The edges between variables \f$x_i\f$ and \f$-x_i\f$ are also automatically present
8635 * in the symmetry detection graph for signed permutation symmetries. The function <code>SCIPaddSymgraphEdge()</code>
8636 * also takes a numerical value as argument, which allows to assign an edge a weight (e.g., \f$a_i\f$
8637 * as in the above example).
8638 *
8639 * Moreover, special nodes, so-called operator nodes, can be added via <code>SCIPaddSymgraphOpnode()</code>.
8640 * Such nodes allow to model special structures of a constraint, which allow to have more degrees of freedom in
8641 * creating symmetry detection graphs. Different operators are distinguished by an integral value.
8642 * Their encoding is thus similar to the one of nodes created by <code>SCIPaddSymgraphValnode()</code>.
8643 * In computing colors, operator nodes are treated differently though, which allows to distinguish
8644 * operator 2 from the numerical value 2.
8645 *
8646 * @subsubsection SYMDETECTEXAMPLES Example for creating symmetry detection callbacks
8647 *
8648 * Let \f$G = (V,E)\f$ be an undirected graph with node weights \f$c_v\f$, \f$v \in C\f$. The maximum weight
8649 * stable set problem can be modeled via the integer program
8650 * \f\[ \max\Big\{ \sum_{v \in V} c_vx_v : x_u + x_v \leq 1 \text{ for all } \{u,v\} \in E,\; x \in \{0,1\}^V\Big\}.\f\]
8651 * Suppose a user wants to implement a constraint handler <code>cons_stableset</code> that enforces a solution to define
8652 * a stable set in \f$G\f$, e.g., by propagation methods and separating edge and clique inequalities.
8653 * Then, the symmetries of the constraint are the weight-preserving automorphisms of the underlying graph \f$G\f$.
8654 * The symmetry detection graph thus can be almost a copy of \f$G\f$.
8655 *
8656 * In our construction, we introduce for each node \f$v\f$ of the graph an operator node \f$v'\f$.
8657 * Moreover, for each edge \f$\{u,v\}\in E\f$, we add the edges \f$\{u',v'\}\f$ to the symmetry detection graph.
8658 * To identify the symmetry detection graph as derived from <code>cons_stableset</code>, we add a constraint node
8659 * that is connected with all operator nodes, which preserves the automorphisms of \f$G\f$. Finally, each
8660 * node \f$v'\f$ is connected with the corresponding variable node for \f$x_v\f$ by an edge.
8661 *
8662 * In the following, we present a code snippet showing how to implement the above mentioned symmetry detection graph.
8663 * We assume that the constraint data <code>consdata</code> contains the following fields
8664 *
8665 * - <code>nnodes</code> number of nodes in graph;
8666 * - <code>nedges</code> number of edges in graph;
8667 * - <code>first</code> array containing the first nodes of each edge;
8668 * - <code>second</code> array containing the second nodes of each edge;
8669 * - <code>weights</code> array containing for each node its corresponding weight;
8670 * - <code>vars</code> array containing a binary variable for each node modeling whether node is present in stable set.
8671 *
8672 * The code for creating the symmetry detection callback could then look like this.
8673 *
8674 * \code{.c}
8675 * #define NODEOP 1
8676 * static
8677 * SCIP_DECL_CONSGETPERMSYMGRAPH(consGetPermsymGraphStableSet)
8678 * {
8679 * SCIP_CONSDATA* consdata;
8680 * int* idx;
8681 * int vidx;
8682 * int nnodes;
8683 * int v;
8684 *
8685 * consdata = SCIPconsGetData(cons);
8686 * nnodes = consdata->nnodes;
8687 *
8688 * SCIP_CALL( SCIPallocBufferArray(scip, &idx, nnodes + 1) );
8689 *
8690 * // create operator nodes and constraint node
8691 * for( v = 0; v < nnodes; ++v )
8692 * {
8693 * SCIP_CALL( SCIPaddSymgraphOpnode(scip, graph, NODEOP, &idx[v]) );
8694 * }
8695 * SCIP_CALL( SCIPaddSymgraphConsnode(scip, graph, cons, 0.0, 0.0, &idx[nnodes]) );
8696 *
8697 * // add edges of underlying graph
8698 * for( v = 0; v < consdata->nedges; ++v )
8699 * {
8700 * SCIP_CALL( SCIPaddSymgraphEdge(scip, graph, idx[consdata->first[v]], idx[consdata->second[v]], FALSE, 0.0) );
8701 * }
8702 *
8703 * // connect nodes with constraint node
8704 * for( v = 0; v < nnodes; ++v )
8705 * {
8706 * SCIP_CALL( SCIPaddSymgraphEdge(scip, graph, idx[v], nodeidx[nnodes], FALSE, 0.0) );
8707 * }
8708 *
8709 * // connect operator nodes with variable nodes, assign edges weight of node
8710 * for( v = 0; v < nnodes; ++v )
8711 * {
8712 * vidx = SCIPgetSymgraphVarnodeidx(scip, graph, consdata->vars[v]);
8713 * SCIP_CALL( SCIPaddSymgraphEdge(scip, graph, idx[v], vidx, TRUE, consdata->weights[v]) );
8714 * }
8715 *
8716 * SCIPfreeBufferArray(scip, &idx);
8717 *
8718 * return SCIP_OKAY;
8719 * }
8720 * \endcode
8721 */
8722
8723/**@page LICENSE License
8724 *
8725 * \verbinclude LICENSE
8726 */
8727
8728/**@page FAQ Frequently Asked Questions (FAQ)
8729 * \htmlinclude faq/faq.inc
8730 */
8731
8732
8733/**@page PARAMETERS List of all SCIP parameters
8734 *
8735 * This page list all parameters of the current SCIP version. This list can
8736 * easily be generated by SCIP via the interactive shell using the following command:
8737 *
8738 * <code>SCIP&gt; set save &lt;file name&gt;</code>
8739 *
8740 * or via the function call:
8741 *
8742 * <code>SCIP_CALL( SCIPwriteParams(scip, &lt;file name&gt;, TRUE, FALSE) );</code>
8743 *
8744 * \verbinclude parameters.set
8745 */
8746
8747/**@page INTERFACES Interfaces
8748 *
8749 * There are several ways of accessing the \SCIP Optimization Suite from other software packages or programming
8750 * platforms.
8751 *
8752 *
8753 * @section FILEFORMATS File formats
8754 *
8755 * The easiest way to load a problem into SCIP is via an input file, given in a format that SCIP can parse directly,
8756 * see \ref SHELL "the tutorial on how to use the interactive shell".
8757 * \SCIP is capable of reading more than ten different file formats, including formats for nonlinear
8758 * problems and constraint programs. This gives researchers from different communities an easy access to the
8759 * \SCIP Optimization Suite. See also the \ref AVAILABLEFORMATS "list of readable file formats".
8760 *
8761 * @section C_API C API
8762 *
8763 * The main access point for \SCIP is its API to C. Please refer to the \ref PUBLICAPI documentation
8764 * for further details.
8765 *
8766 * @section CPLUSPLUS C++ wrapper classes
8767 *
8768 * Since \SCIP is written in C, its callable library can be directly accessed from C++. If a user wants to program own
8769 * plugins in C++, there are wrapper classes for all different types of plugins available in the <code>src/objscip</code>
8770 * directory of the \SCIP standard distribution. SCIP provides several examples that were written in C++, see
8771 * \ref EXAMPLES "Examples".
8772 *
8773 * @section SCIPINTERFACES Interfaces for other programming languages
8774 *
8775 * Interfaces for other programming languages are developed and maintained independently from the SCIP Optimization Suite
8776 * on <a href="https://github.com/scipopt">GitHub</a> in order to provide extensions and patches faster
8777 * and to collaborate on them more easily.
8778 *
8779 * - <a href="https://github.com/scipopt/PySCIPOpt">PySCIPOpt</a> provides an extensive open-source interface for Python.
8780 * PySCIPOpt can be installed via <a href="https://anaconda.org/conda-forge/pyscipopt">conda-forge</a>,
8781 * which automatically includes \SCIP.
8782 * PySCIPOpt uses wrappers to allow users to build
8783 * their own plugins without accessing the C code of \SCIP itself.
8784 * Since Python is one of the most commonly used programming languages, especially in the field of
8785 * machine learning, the API gives easy access to the solvers functionality to incorporate \SCIP
8786 * into any python project pipeline, extract data for further analysis and computation as well as allow
8787 * customizing the solving process.
8788 * - <a href="https://github.com/scipopt/SCIP.jl">SCIP.jl</a> is a
8789 * Julia interface that exposes an API identical to the SCIP-C_API and implements the
8790 * MathOptInterface used by most constrained solvers in Julia.
8791 * It can be accessed through the Julia package manager and will install a pre-built version of
8792 * \SCIP if none is provided by the user.
8793 * - There is a <a href="https://github.com/scipopt/MatlabSCIPInterface">Matlab interface</a>
8794 * to use SCIP and SCIP-SDP from Matlab and Octave.
8795 * - <a href="https://github.com/scipopt/JSCIPOpt">JSCIPOpt</a> is an interface for Java.
8796 *
8797 * Contributions to these projects are very welcome.
8798 *
8799 * There are also several third-party python interfaces to the \SCIP Optimization Suite:
8800 * - <a href="https://github.com/eomahony/Numberjack">NUMBERJACK</a> is a constraint programming platform implemented in python.
8801 * It supports a variety of different solvers, one of them being the \SCIP Optimization Suite .
8802 * - <a href="http://code.google.com/p/python-zibopt/">python-zibopt</a> was developed
8803 * by Ryan J. O'Neil and is a python extension of the \SCIP Optimization Suite (not maintained anymore).
8804 * - <a href="http://picos.zib.de/">PICOS</a> is a python interface for conic optimization,
8805 * provided by Guillaume Sagnol.
8806 *
8807 * @section MODELLING Modeling languages
8808 *
8809 * A natural way of formulating an optimization problem is to use a modeling language.
8810 * Besides ZIMPL, which is part of the \SCIP Optimization Suite,
8811 * there are several other modeling tools with a direct interface to \SCIP:
8812 *
8813 * - <a href="https://zimpl.zib.de">ZIMPL</a>, a modeling language for constraint programming,
8814 * - both <a href="http://www.ampl.com/">AMPL</a> and <a href="http://www.gams.com">GAMS</a>,
8815 * are well-suited for modeling mixed-integer linear and nonlinear optimization problems,
8816 * - and <a href="https://projects.coin-or.org/Cmpl">CMPL</a> for mixed-integer linear problems.
8817 * - <a href="https://jump.dev/JuMP.jl/stable/">JuMP</a> accesses SCIP through the Julia interface.
8818 * - <a href="http://users.isy.liu.se/johanl/yalmip/pmwiki.php?n=Main.HomePage">YALMIP</a> by Johan L&ouml;fberg provides a
8819 * free modeling language.
8820 *
8821 * The AMPL and ZIMPL interfaces are included in the \SCIP distribution,
8822 * the GAMS interface is available <a href="https://github.com/coin-or/GAMSlinks">here</a>.
8823 *
8824 */
8825
8826 /**@defgroup PUBLICAPI Public API of SCIP
8827 * @brief methods and headers of the public C-API of \SCIP. Please refer to \ref DOC "" for information how to use the reference manual.
8828 *
8829 * \PUBLICAPIDESCRIPTION
8830 *
8831 *
8832 */
8833
8834/**@defgroup PUBLICCOREAPI Core API
8835 * @ingroup PUBLICAPI
8836 * @brief methods and headers of the plugin-independent C-API provided by the \SCIP header file scip.h.
8837 *
8838 * This module comprises methods provided by the header file scip.h. Including this header into a user-written extension
8839 * suffices to have all plugin-independent functionality of \SCIP available. Plugin-independent
8840 * user functionality includes the
8841 *
8842 * - creation of problems that \SCIP should solve
8843 * - fine-grained access to initiate the solving process of \SCIP
8844 * - access to all sorts of solving process statistics
8845 * - commonly used data structures and algorithms
8846 * - the management of plugins
8847 * - ...
8848 *
8849 * In order facilitate the navigation through the core API of \SCIP, it is structured into different modules.
8850 */
8851
8852/**@defgroup TYPEDEFINITIONS Type Definitions
8853 * @ingroup PUBLICCOREAPI
8854 * @brief type definitions and callback declarations
8855 *
8856 * This page lists headers which contain type definitions of callback methods.
8857 *
8858 * All headers below include the descriptions of callback methods of
8859 * certain plugins. For more detail see the corresponding header.
8860 */
8861
8862/**@defgroup PublicProblemMethods Problem Creation
8863 * @ingroup PUBLICCOREAPI
8864 * @brief methods to create a problem that \SCIP should solve
8865 *
8866 * This module summarizes the main methods needed to create a problem for \SCIP, and access its most important members:
8867 * - Declaring, adding, accessing, and changing variables of the problem
8868 * - Declaring, adding, accessing, and changing constraints of the problem
8869 * - Creating, adding, accessing, changing, and checking of solutions to the problem
8870 *
8871 * @note These core methods are not sufficient to create constraints of a certain type that is provided by the default plugins of \SCIP.
8872 * An example would be the creation of a linear constraint for which the methods provided by the
8873 * \ref cons_linear.h "linear constraint handler" must be used. Such methods are provided by the default plugins of \SCIP
8874 * and can be found in the \ref PUBLICPLUGINAPI.
8875 */
8876
8877/**@defgroup GeneralSCIPMethods SCIP
8878 * @ingroup PublicProblemMethods
8879 * @brief methods to manipulate a SCIP object
8880 */
8881
8882/**@defgroup GlobalProblemMethods Global Problem
8883 * @ingroup PublicProblemMethods
8884 * @brief methods to create, read and modify a global problem together with its callbacks
8885 */
8886
8887/**@defgroup PublicVariableMethods Problem Variables
8888 * @ingroup PublicProblemMethods
8889 * @brief public methods for problem variables
8890 */
8891
8892/**@defgroup PublicConstraintMethods Problem Constraints
8893 * @ingroup PublicProblemMethods
8894 * @brief Public methods for constraints
8895 */
8896
8897/**@defgroup PublicSolutionMethods Primal Solution
8898 * @ingroup PublicProblemMethods
8899 * @brief methods to create and change primal solutions of \SCIP
8900 */
8901
8902/**@defgroup CopyMethods Problem Copies
8903 * @ingroup PublicProblemMethods
8904 * @brief methods to copy problems between a source and a target \SCIP
8905 */
8906
8907
8908 /**@defgroup PublicSolveMethods Solving Process
8909 * @ingroup PUBLICCOREAPI
8910 * @brief methods to control the solving process of \SCIP
8911 *
8912 * This large group of methods and modules comprises the solving process related API of \SCIP. This includes
8913 *
8914 * -# changing parameters to control the solver behavior
8915 * -# access search tree related information
8916 * -# access relaxation information
8917 * -# access various solving process statistics
8918 * -# solve auxiliary relaxations and subproblems using LP/NLP diving or probing mode
8919 */
8920
8921/**@defgroup PublicSolvingStatsMethods Solving Statistics
8922 * @ingroup PublicSolveMethods
8923 * @brief methods to query statistics about the solving process
8924 */
8925
8926/**@defgroup ParameterMethods Parameter
8927 * @ingroup PublicSolveMethods
8928 * @brief methods to create, query, and print user parameters
8929 */
8930
8931/**@defgroup PublicEventMethods Event Handling
8932 * @ingroup PublicSolveMethods
8933 * @brief methods to create, catch, process, and drop events during the solving process of \SCIP
8934 *
8935 * Events can only be caught during the operation on the transformed problem.
8936 * Events on variables can only be caught for transformed variables.
8937 * If you want to catch an event for an original variable, you have to get the corresponding transformed variable
8938 * with a call to SCIPgetTransformedVar() and catch the event on the transformed variable.
8939 */
8940
8941/**@defgroup PublicLPMethods LP Relaxation
8942 * @ingroup PublicSolveMethods
8943 * @brief methods to build and access LP relaxation information
8944 * @see methods to interact with \ref PublicColumnMethods "LP columns" and \ref PublicRowMethods "LP rows"
8945 */
8946
8947/**@defgroup PublicColumnMethods LP Column
8948 * @ingroup PublicLPMethods
8949 * @brief public methods for LP columns
8950 */
8951
8952/**@defgroup PublicRowMethods LP Row
8953 * @ingroup PublicLPMethods
8954 * @brief public methods for LP rows
8955 */
8956
8957/**@defgroup PublicCutMethods Cuts and Cutpools
8958 * @ingroup PublicLPMethods
8959 * @brief common methods used to manipulate, generate, and strengthen cuts and to organize the cutpool
8960 */
8961
8962/**@defgroup PublicLPDivingMethods LP Diving
8963 * @ingroup PublicLPMethods
8964 * @brief methods to initiate and conduct LP diving
8965 */
8966
8967/**@defgroup PublicNLPMethods NLP Relaxation
8968 * @ingroup PublicSolveMethods
8969 * @brief methods for the nonlinear relaxation
8970 */
8971
8972/**@defgroup PublicNLRowMethods Nonlinear Rows
8973 * @ingroup PublicNLPMethods
8974 * @brief methods for the creation and interaction with rows of the NLP relaxation
8975 */
8976
8977/**@defgroup PublicNLPDiveMethods NLP Diving
8978 * @ingroup PublicNLPMethods
8979 * @brief methods to initiate and conduct NLP Diving
8980 */
8981
8982/**@defgroup PublicConflictMethods Conflict Analysis
8983 * @ingroup PublicSolveMethods
8984 * @brief public methods for conflict analysis
8985 */
8986
8987/**@defgroup PublicBranchingMethods Branching
8988 * @ingroup PublicSolveMethods
8989 * @brief methods for branching on LP solutions, relaxation solutions, and pseudo solutions
8990 *
8991 * @see \ref PublicVariableMethods "Public Variable methods" contains some typical variable branching score functions
8992 */
8993
8994/**@defgroup LocalSubproblemMethods Local Subproblem
8995 * @ingroup PublicSolveMethods
8996 * @brief methods to query information about or strengthen the problem at the current local search node
8997 */
8998
8999/**@defgroup PublicTreeMethods Search Tree
9000 * @ingroup PublicSolveMethods
9001 * @brief methods to query search tree related information
9002 * @see \ref PublicNodeMethods "Public methods for nodes"
9003 */
9004
9005/**@defgroup PublicNodeMethods Nodes
9006 * @ingroup PublicTreeMethods
9007 * @brief methods for nodes of the search tree of \SCIP
9008 */
9009
9010/**@defgroup PublicProbingMethods Probing
9011 * @ingroup PublicSolveMethods
9012 * @brief methods to initiate and control the probing mode of \SCIP
9013 */
9014
9015/**@defgroup PublicReoptimizationMethods Reoptimization
9016 * @ingroup PublicSolveMethods
9017 * @brief methods for reoptimization related tasks
9018 */
9019
9020/** @defgroup DataStructures Data Structures
9021 * @ingroup PUBLICCOREAPI
9022 * @brief commonly used data structures
9023 *
9024 * Below you find a list of available data structures
9025 */
9026
9027/** @defgroup DisjointSet Disjoint Set (Union Find)
9028 * @ingroup DataStructures
9029 * @brief weighted disjoint set (union find) data structure with path compression
9030 *
9031 * Weighted Disjoint Set is a data structure to quickly update and query connectedness information
9032 * between nodes of a graph. Disjoint Set is also known as Union Find.
9033 */
9034
9035/**@defgroup PublicDynamicArrayMethods Dynamic Arrays
9036 * @ingroup DataStructures
9037 * @brief methods for the creation and access of dynamic arrays
9038 */
9039
9040/**@defgroup DirectedGraph Directed Graph
9041 * @ingroup DataStructures
9042 * @brief graph structure with common algorithms for directed and undirected graphs
9043 */
9044
9045/**@defgroup DecompMethods Decomposition data structure
9046 * @ingroup DataStructures
9047 * @brief methods for creating and accessing user decompositions
9048 */
9049
9050/**@defgroup MiscellaneousMethods Miscellaneous Methods
9051 * @ingroup PUBLICCOREAPI
9052 * @brief commonly used methods from different categories
9053 *
9054 * Below you find a list of miscellaneous methods grouped by different categories
9055 */
9056
9057/**@defgroup PublicValidationMethods Validation
9058 * @ingroup PUBLICCOREAPI
9059 * @brief methods for validating the correctness of a solving process
9060 */
9061
9062/**@defgroup PublicMemoryMethods Memory Management
9063 * @ingroup MiscellaneousMethods
9064 * @brief methods and macros to use the \SCIP memory management
9065 *
9066 * @see \ref MEMORY "Using the memory functions of SCIP" for more information
9067 */
9068
9069/**@defgroup PublicTimingMethods Timing
9070 * @ingroup MiscellaneousMethods
9071 * @brief methods for timing
9072 */
9073
9074/**@defgroup PublicBanditMethods Bandit Algorithms
9075 * @ingroup MiscellaneousMethods
9076 * @brief methods for bandit algorithms
9077 */
9078
9079
9080
9081/**@defgroup DebugSolutionMethods Debug Solution
9082 * @ingroup PUBLICCOREAPI
9083 * @brief methods to control the SCIP debug solution mechanism, see also \ref DEBUG
9084 */
9085
9086/**@defgroup MessageOutputMethods Messaging
9087 * @ingroup PUBLICCOREAPI
9088 * @brief message output methods
9089 */
9090
9091/**@defgroup PluginManagementMethods Methods for managing plugins
9092 * @ingroup PUBLICCOREAPI
9093 * @brief Methods for the inclusion and management of SCIP plugins and callback functions
9094 *
9095 */
9096
9097/**@defgroup PublicBendersMethods Benders' decomposition
9098 * @ingroup PluginManagementMethods
9099 * @brief methods for Benders' decomposition plugins
9100 */
9101
9102/**@defgroup PublicBenderscutsMethods Benders' decomposition cuts
9103 * @ingroup PluginManagementMethods
9104 * @brief methods for Benders' decomposition cuts plugins
9105 */
9106
9107/**@defgroup PublicBranchRuleMethods Branching Rules
9108 * @ingroup PluginManagementMethods
9109 * @brief methods for branching rule plugins
9110 */
9111
9112/**@defgroup PublicCompressionMethods Tree Compression
9113 * @ingroup PluginManagementMethods
9114 * @brief public methods for tree compressions
9115 */
9116
9117/**@defgroup PublicConflicthdlrMethods Conflict Analysis
9118 * @ingroup PluginManagementMethods
9119 * @brief public methods for conflict handlers
9120 */
9121
9122/**@defgroup PublicConshdlrMethods Constraint handlers
9123 * @ingroup PluginManagementMethods
9124 * @brief methods for constraint handlers
9125 */
9126
9127/**@defgroup PublicCutSelectorMethods Cut Selector
9128 * @ingroup PluginManagementMethods
9129 * @brief methods for cut selectors
9130 */
9131
9132/**@defgroup PublicDialogMethods Dialogs
9133 * @ingroup PluginManagementMethods
9134 * @brief public methods for user interface dialogs
9135 */
9136
9137/**@defgroup PublicDisplayMethods Displays
9138 * @ingroup PluginManagementMethods
9139 * @brief methods for the inclusion and access of display plugins
9140 */
9141
9142/**@defgroup PublicEventHandlerMethods Event Handler
9143 * @ingroup PluginManagementMethods
9144 * @brief methods for event handlers
9145 */
9146
9147/**@defgroup PublicExprHandlerMethods Expression Handler
9148 * @ingroup PluginManagementMethods
9149 * @brief methods for expression handlers
9150 */
9151
9152/**@defgroup PublicHeuristicMethods Primal Heuristics
9153 * @ingroup PluginManagementMethods
9154 * @brief methods for primal heuristic plugins
9155 */
9156
9157/**@defgroup PublicDivesetMethods Dive sets
9158 * @ingroup PublicSpecialHeuristicMethods
9159 * @brief methods for dive sets to control the generic diving algorithm
9160 */
9161
9162/**@defgroup PublicNodeSelectorMethods Node Selector
9163 * @ingroup PluginManagementMethods
9164 * @brief methods for node selector plugin management
9165 */
9166
9167/**@defgroup PublicNlhdlrInterfaceMethods Nonlinear Handlers
9168 * @ingroup PluginManagementMethods
9169 * @brief methods for the management of nonlinear handlers
9170 */
9171
9172/**@defgroup PublicPresolverMethods Presolver
9173 * @ingroup PluginManagementMethods
9174 * @brief methods for presolver plugins
9175 */
9176
9177/**@defgroup PublicPricerMethods Pricer
9178 * @ingroup PluginManagementMethods
9179 * @brief methods to include and access pricer plugins of \SCIP
9180 */
9181
9182/**@defgroup PublicPropagatorMethods Propagators
9183 * @ingroup PluginManagementMethods
9184 * @brief methods for propagator plugins
9185 */
9186
9187/**@defgroup PublicReaderMethods Reader
9188 * @ingroup PluginManagementMethods
9189 * @brief methods for the inclusion and access to reader plugins of \SCIP
9190 */
9191
9192/**@defgroup PublicRelaxatorMethods Relaxation Handlers
9193 * @ingroup PluginManagementMethods
9194 * @brief public methods for relaxation handlers
9195 */
9196
9197/**@defgroup PublicSeparatorMethods Separators
9198 * @ingroup PluginManagementMethods
9199 * @brief methods for separator plugins
9200 */
9201
9202/**@defgroup PublicTableMethods Tables
9203 * @ingroup PluginManagementMethods
9204 * @brief methods for the inclusion and access of statistics tables
9205 */
9206
9207/**@defgroup PublicConcsolverTypeMethods Concurrent Solver Types
9208 * @ingroup PluginManagementMethods
9209 * @brief methods for concurrent solver type plugins
9210 */
9211
9212/**@defgroup PublicNLPIInterfaceMethods NLP solver interfaces
9213 * @ingroup PluginManagementMethods
9214 * @brief methods for the management of NLP solver interfaces
9215 */
9216
9217/**@defgroup PublicExternalCodeMethods External Codes
9218 * @ingroup PluginManagementMethods
9219 * @brief methods to access information about external codes used by \SCIP
9220 */
9221
9222/**@defgroup PublicParallelMethods Parallel Interface
9223 * @ingroup PUBLICCOREAPI
9224 * @brief methods to construct the parallel interface of \SCIP
9225 */
9226
9227 /**@defgroup PUBLICPLUGINAPI Plugin API of SCIP
9228 * @ingroup PUBLICAPI
9229 * @brief core API extensions provided by the default plugins of \SCIP, includable via scipdefplugins.h.
9230 *
9231 * All default plugins of \SCIP, especially the default \ref CONSHDLRS "constraint handlers", provide
9232 * valuable extensions to the \ref PUBLICCOREAPI "core API" of \SCIP. These methods are made available
9233 * by including scipdefplugins.h to user-written extensions.
9234 *
9235 * For a better overview, this page lists all default plugin headers structured into modules based on their individual
9236 * topic.
9237 *
9238 * All of the modules listed below provide functions that are allowed to be used by user-written extensions of \SCIP.
9239 */
9240 /**@defgroup INTERNALAPI Internal API of SCIP
9241 * @brief internal API methods that should only be used by the core of \SCIP
9242 *
9243 * This page lists the header files of internal API methods. In contrast to the public API, these internal methods
9244 * should not be used by user plugins and extensions of SCIP. Please consult
9245 * \ref PUBLICCOREAPI "the Core API" and \ref PUBLICPLUGINAPI "Plugin API" for the complete API available to user plugins.
9246 *
9247 */
9248
9249/**@defgroup BENDERS Benders' decomposition implementations
9250 * @ingroup PUBLICPLUGINAPI
9251 * @brief methods and files provided by the default Benders' decomposition implementations of \SCIP
9252 *
9253 * A detailed description what a Benders' decomposition implementation does and how to add a Benders' decomposition
9254 * implementations to SCIP can be found
9255 * \ref BENDER "here".
9256 */
9257
9258/**@defgroup BendersIncludes Inclusion methods
9259 * @ingroup BENDERS
9260 * @brief methods to include specific Benders' decomposition implementations into \SCIP
9261 *
9262 * This module contains methods to include specific Benders' decomposition implementations into \SCIP.
9263 *
9264 * @note All default plugins can be included at once (including all Benders' decomposition implementations) using
9265 * SCIPincludeDefaultPlugins()
9266 *
9267 */
9268
9269/**@defgroup BENDERSCUTS Benders' decomposition cut method
9270 * @ingroup PUBLICPLUGINAPI
9271 * @brief methods and files provided by the default Benders' decomposition cut method of \SCIP
9272 *
9273 * A detailed description what a Benders' decomposition cut method does and how to add a Benders' decomposition
9274 * cut method to SCIP can be found
9275 * \ref BENDERSCUT "here".
9276 */
9277
9278/**@defgroup BenderscutIncludes Inclusion methods
9279 * @ingroup BENDERSCUTS
9280 * @brief methods to include specific Benders' decomposition cut methods into \SCIP
9281 *
9282 * This module contains methods to include specific Benders' decomposition cut methods into \SCIP.
9283 *
9284 * @note The Benders' decomposition cut methods are linked to each Benders' decomposition implementation. Thus, the
9285 * default Benders' decomposition implementations automatically include the necessary Benders' decomposition cut
9286 * methods. For custom Benders' decomposition implementations, you can call SCIPincludeDefaultBendersCuts() in the
9287 * SCIPincludeBendersMybenders() include function.
9288 *
9289 */
9290
9291/**@defgroup BRANCHINGRULES Branching Rules
9292 * @ingroup PUBLICPLUGINAPI
9293 * @brief methods and files provided by the default branching rules of \SCIP
9294 *
9295 * A detailed description what a branching rule does and how to add a branching rule to SCIP can be found
9296 * \ref BRANCH "here".
9297 */
9298
9299/**@defgroup BranchingRuleIncludes Inclusion methods
9300 * @ingroup BRANCHINGRULES
9301 * @brief methods to include specific branching rules into \SCIP
9302 *
9303 * This module contains methods to include specific branching rules into \SCIP.
9304 *
9305 * @note All default plugins can be included at once (including all branching rules) using SCIPincludeDefaultPlugins()
9306 *
9307 */
9308
9309/**@defgroup CONSHDLRS Constraint Handlers
9310 * @ingroup PUBLICPLUGINAPI
9311 * @brief methods and files provided by the default constraint handlers of \SCIP
9312 *
9313 * A detailed description what a constraint handler does and how to add a constraint handler to SCIP can be found
9314 * \ref CONS "here".
9315 */
9316
9317/**@defgroup ConshdlrIncludes Inclusion methods
9318 * @ingroup CONSHDLRS
9319 * @brief methods to include specific constraint handlers into \SCIP
9320 *
9321 * This module contains methods to include specific constraint handlers into \SCIP.
9322 *
9323 * @note All default plugins can be included at once (including all default constraint handlers) using SCIPincludeDefaultPlugins()
9324 *
9325 */
9326
9327/**@defgroup CUTSELECTORS Cut Selectors
9328 * @ingroup PUBLICPLUGINAPI
9329 * @brief methods and files provided by the default cut selectors of \SCIP
9330 *
9331 * A detailed description what a cut selector does and how to add a cut selector to SCIP can be found
9332 * \ref CUTSEL "here".
9333 */
9334
9335/**@defgroup CutSelectorIncludes Inclusion methods
9336 * @ingroup CUTSELECTORS
9337 * @brief methods to include specific cut selectors into \SCIP
9338 *
9339 * This module contains methods to include specific cut selectors into \SCIP.
9340 *
9341 * @note All default plugins can be included at once (including all default cut selectors) using SCIPincludeDefaultPlugins()
9342 *
9343 */
9344
9345/**@defgroup DIALOGS Dialogs
9346 * @ingroup PUBLICPLUGINAPI
9347 * @brief methods and files provided by the default dialogs of \SCIP
9348 *
9349 * A detailed description what a dialog does and how to add a dialog to SCIP can be found
9350 * \ref DIALOG "here".
9351 */
9352
9353/**@defgroup DialogIncludes Inclusion methods
9354 * @ingroup DIALOGS
9355 * @brief methods to include specific dialogs into \SCIP
9356 *
9357 * This module contains methods to include specific dialogs into \SCIP.
9358 *
9359 * @note All default plugins can be included at once (including all default dialogs) using SCIPincludeDefaultPlugins()
9360 *
9361 */
9362
9363/**@defgroup DISPLAYS Displays
9364 * @ingroup PUBLICPLUGINAPI
9365 * @brief methods and files provided by the default displays (output columns) of \SCIP
9366 *
9367 * A detailed description what a display does and how to add a display to SCIP can be found
9368 * \ref DISP "here".
9369 *
9370 */
9371
9372/**@defgroup DisplayIncludes Inclusion methods
9373 * @ingroup DISPLAYS
9374 * @brief methods to include specific displays into \SCIP
9375 *
9376 * This module contains methods to include specific displays into \SCIP.
9377 *
9378 * @note All default plugins can be included at once (including all default displays) using SCIPincludeDefaultPlugins()
9379 *
9380 */
9381
9382/**@defgroup EXPRHDLRS Expression Handlers
9383 * @ingroup PUBLICPLUGINAPI
9384 * @brief methods and files provided by the default expressions handlers of \SCIP
9385 */
9386
9387/**@defgroup ExprhdlrIncludes Inclusion methods
9388 * @ingroup EXPRHDLRS
9389 * @brief methods to include specific expression handlers into \SCIP
9390 *
9391 * This module contains methods to include specific expression handlers into \SCIP.
9392 *
9393 * @note All default plugins can be included at once (including all default expression handlers) using SCIPincludeDefaultPlugins()
9394 *
9395 */
9396
9397/**@defgroup EXPRINTS Expression Interpreter
9398 * @ingroup PUBLICPLUGINAPI
9399 * @brief methods and files provided by the default expression interpreters of \SCIP
9400 *
9401 * A detailed description what a expression interpreter does and how to add a expression interpreter to SCIP can be found
9402 * \ref EXPRINT "here".
9403 */
9404
9405/**@defgroup FILEREADERS File Readers
9406 * @ingroup PUBLICPLUGINAPI
9407 * @brief This page contains a list of all file readers which are currently available.
9408 *
9409 * @section AVAILABLEFORMATS List of readable file formats
9410 *
9411 * The \ref SHELL "interactive shell" and the callable library are capable of reading/parsing several different file
9412 * formats.
9413 *
9414 * <table>
9415 * <tr><td>\ref reader_bnd.h "BND format"</td> <td>for variable bounds</td></tr>
9416 * <tr><td>\ref reader_cip.h "CIP format"</td> <td>for SCIP's constraint integer programming format</td></tr>
9417 * <tr><td>\ref reader_cnf.h "CNF format"</td> <td>DIMACS CNF (conjunctive normal form) file format used for example for SAT problems</td></tr>
9418 * <tr><td>\ref reader_diff.h "DIFF format"</td> <td>for reading a new objective function for mixed-integer programs</td></tr>
9419 * <tr><td>\ref reader_fzn.h "FZN format"</td> <td>FlatZinc is a low-level solver input language that is the target language for MiniZinc</td></tr>
9420 * <tr><td>\ref reader_lp.h "LP format"</td> <td>for mixed-integer (quadratically constrained quadratic) programs (CPLEX)</td></tr>
9421 * <tr><td>\ref reader_mps.h "MPS format"</td> <td>for mixed-integer (quadratically constrained quadratic) programs</td></tr>
9422 * <tr><td>\ref reader_nl.h "NL format"</td> <td>for <a href="http://www.ampl.com">AMPL</a> .nl files, e.g., mixed-integer linear and nonlinear
9423 * <tr><td>\ref reader_opb.h "OPB format"</td> <td>for pseudo-Boolean optimization instances</td></tr>
9424 * <tr><td>\ref reader_osil.h "OSiL format"</td> <td>for mixed-integer nonlinear programs</td></tr>
9425 * <tr><td>\ref reader_pip.h "PIP format"</td> <td>for <a href="http://polip.zib.de/pipformat.php">mixed-integer polynomial programming problems</a></td></tr>
9426 * <tr><td>\ref reader_sol.h "SOL format"</td> <td>for solutions; XML-format (read-only) or raw SCIP format</td></tr>
9427 * <tr><td>\ref reader_wbo.h "WBO format"</td> <td>for weighted pseudo-Boolean optimization instances</td></tr>
9428 * <tr><td>\ref reader_zpl.h "ZPL format"</td> <td>for <a href="http://zimpl.zib.de">ZIMPL</a> models, i.e., mixed-integer linear and nonlinear
9429 * programming problems [read only]</td></tr>
9430 * </table>
9431 *
9432 * @section ADDREADER How to add a file reader
9433 *
9434 * A detailed description what a file reader does and how to add a file reader to SCIP can be found
9435 * \ref READER "here".
9436 *
9437 */
9438
9439/**@defgroup FileReaderIncludes Inclusion methods
9440 * @ingroup FILEREADERS
9441 * @brief methods to include specific file readers into \SCIP
9442 *
9443 * This module contains methods to include specific file readers into \SCIP.
9444 *
9445 * @note All default plugins can be included at once (including all default file readers) using SCIPincludeDefaultPlugins()
9446 *
9447 */
9448
9449/**@defgroup PARALLEL Parallel interface methods
9450 * @ingroup INTERNALAPI
9451 * @brief headers and methods for the parallel interface of \SCIP
9452 *
9453 */
9454
9455/**@defgroup PublicSymmetryMethods Symmetry
9456 * @ingroup INTERNALAPI
9457 * @brief methods for symmetry handling
9458 */
9459
9460/**@defgroup FileReaderIncludes Inclusion methods
9461 * @ingroup FILEREADERS
9462 * @brief methods to include specific file readers into \SCIP
9463 *
9464 * This module contains methods to include specific file readers into \SCIP.
9465 *
9466 * @note All default plugins can be included at once (including all default file readers) using SCIPincludeDefaultPlugins()
9467 *
9468 */
9469
9470/**@defgroup LPIS LP Solver Interface
9471 * @ingroup PUBLICPLUGINLPI
9472 * @brief methods and files provided by the LP solver interface of \SCIP
9473 *
9474 * \SCIP uses external tools to solve LP relaxations. The communication
9475 * is realized through an LP interface.
9476 *
9477 * This page lists public interface methods that every LP interface provides.
9478 * Find the concrete implementation for your LP solver
9479 * under "src/lpi/".
9480 *
9481 * @see \ref LPI for a list of available LP solver interfaces
9482 */
9483
9484/**@defgroup NODESELECTORS Node Selectors
9485 * @ingroup PUBLICPLUGINAPI
9486 * @brief methods and files provided by the default node selectors of \SCIP
9487 *
9488 * A detailed description what a node selector does and how to add a node selector to SCIP can be found
9489 * \ref NODESEL "here".
9490 */
9491
9492/**@defgroup NodeSelectorIncludes Inclusion methods
9493 * @ingroup NODESELECTORS
9494 * @brief methods to include specific node selectors into \SCIP
9495 *
9496 * This module contains methods to include specific node selectors into \SCIP.
9497 *
9498 * @note All default plugins can be included at once (including all default node selectors) using SCIPincludeDefaultPlugins()
9499 *
9500 */
9501
9502/**@defgroup NLHDLRS Nonlinear Handlers
9503 * @ingroup PUBLICPLUGINAPI
9504 * @brief methods and files provided by the default nonlinear handlers of \SCIP
9505 */
9506
9507/**@defgroup NlhdlrIncludes Inclusion methods
9508 * @ingroup NLHDLRS
9509 * @brief methods to include specific nonlinear handlers into \SCIP
9510 *
9511 * This module contains methods to include specific nonlinear handlers into \SCIP.
9512 *
9513 * @note All default plugins can be included at once (including all default nonlinear handlers) using SCIPincludeDefaultPlugins()
9514 *
9515 */
9516
9517/**@defgroup NLPIS NLP Solver Interfaces
9518 * @ingroup PUBLICPLUGINAPI
9519 * @brief methods and files provided by the default NLP solver interfaces of \SCIP
9520 *
9521 * A detailed description what a NLP solver interface does and how to add a NLP solver interface to SCIP can be found
9522 * \ref NLPI "here".
9523 */
9524
9525/**@defgroup NLPIIncludes Inclusion methods
9526 * @ingroup NLPIS
9527 * @brief methods to include specific NLP solver interfaces into \SCIP
9528 *
9529 * This module contains methods to include specific NLP solver interfaces into \SCIP.
9530 *
9531 * @note All default plugins can be included at once (including all default NLP solver interfaces) using SCIPincludeDefaultPlugins()
9532 *
9533 */
9534
9535/**@defgroup PRESOLVERS Presolvers
9536 * @ingroup PUBLICPLUGINAPI
9537 * @brief methods and files provided by the default presolvers of \SCIP
9538 *
9539 * A detailed description what a presolver does and how to add a presolver to SCIP can be found
9540 * \ref PRESOL "here".
9541 */
9542
9543/**@defgroup PresolverIncludes Inclusion methods
9544 * @ingroup PRESOLVERS
9545 * @brief methods to include specific presolvers into \SCIP
9546 *
9547 * This module contains methods to include specific presolvers into \SCIP.
9548 *
9549 * @note All default plugins can be included at once (including all default presolvers) using SCIPincludeDefaultPlugins()
9550 *
9551 */
9552
9553/**@defgroup PRICERS Pricers
9554 * @ingroup PUBLICPLUGINAPI
9555 * @brief methods and files provided by the default pricers of \SCIP
9556 *
9557 * Per default there exist no variable pricer. A detailed description what a variable pricer does and how to add a
9558 * variable pricer to SCIP can be found \ref PRICER "here".
9559 */
9560
9561/**@defgroup PricerIncludes Inclusion methods
9562* @ingroup PRICERS
9563* @brief methods to include specific pricers into \SCIP
9564*
9565* This module contains methods to include specific pricers into \SCIP.
9566*
9567* @note All default plugins can be included at once using SCIPincludeDefaultPlugins(). There exists no pricer per default.
9568* In order to see examples of variable pricers, please consult the \ref EXAMPLES "Coding Examples" of \SCIP.
9569*
9570*/
9571
9572/**@defgroup PRIMALHEURISTICS Primal Heuristics
9573 * @ingroup PUBLICPLUGINAPI
9574 * @brief methods and files provided by the default primal heuristics of \SCIP
9575 *
9576 * A detailed description what a primal heuristic does and how to add a primal heuristic to SCIP can be found
9577 * \ref HEUR "here".
9578 */
9579
9580/**@defgroup PrimalHeuristicIncludes Inclusion methods
9581 * @ingroup PRIMALHEURISTICS
9582 * @brief methods to include specific primal heuristics into \SCIP
9583 *
9584 * This module contains methods to include specific primal heuristics into \SCIP.
9585 *
9586 * @note All default plugins can be included at once (including all default primal heuristics) using SCIPincludeDefaultPlugins()
9587 *
9588 */
9589
9590/**@defgroup PROPAGATORS Propagators
9591 * @ingroup PUBLICPLUGINAPI
9592 * @brief methods and files provided by the default propagators of \SCIP
9593 *
9594 * A detailed description what a propagator does and how to add a propagator to SCIP can be found
9595 * \ref PROP "here".
9596 */
9597
9598/**@defgroup PropagatorIncludes Inclusion methods
9599 * @ingroup PROPAGATORS
9600 * @brief methods to include specific propagators into \SCIP
9601 *
9602 * This module contains methods to include specific propagators into \SCIP.
9603 *
9604 * @note All default plugins can be included at once (including all default propagators) using SCIPincludeDefaultPlugins()
9605 *
9606 */
9607
9608/**@defgroup RELAXATORS Relaxation Handlers
9609 * @ingroup PUBLICPLUGINAPI
9610 * @brief methods and files provided by the default relaxation handlers of \SCIP
9611 *
9612 * A detailed description what a relaxation handler does and how to add a relaxation handler to SCIP can be found
9613 * \ref RELAX "here". Note that the linear programming relaxation is not implemented via the relaxation handler plugin.
9614 * Per default no relaxation handler exists in SCIP. However, there are two relaxation handlers in the
9615 * \ref RELAXATOR_MAIN "Relaxator example".
9616 */
9617
9618/**@defgroup SEPARATORS Separators
9619 * @ingroup PUBLICPLUGINAPI
9620 * @brief methods and files provided by the default separators of \SCIP
9621 *
9622 * A detailed description what a separator does and how to add a separator to SCIP can be found
9623 * \ref SEPA "here".
9624 */
9625
9626/**@defgroup SeparatorIncludes Inclusion methods
9627 * @ingroup SEPARATORS
9628 * @brief methods to include specific separators into \SCIP
9629 *
9630 * This module contains methods to include specific separators into \SCIP.
9631 *
9632 * @note All default plugins can be included at once (including all default separators) using SCIPincludeDefaultPlugins()
9633 *
9634 */
9635
9636/**@defgroup TABLES Tables
9637 * @ingroup PUBLICPLUGINAPI
9638 * @brief methods and files provided by the default statistics tables of \SCIP
9639 *
9640 * A detailed description what a table does and how to add a table to SCIP can be found
9641 * \ref TABLE "here".
9642 *
9643 */
9644
9645/**@defgroup TableIncludes Inclusion methods
9646 * @ingroup TABLES
9647 * @brief methods to include specific tables into \SCIP
9648 *
9649 * This module contains methods to include specific statistics tables into \SCIP.
9650 *
9651 * @note All default plugins can be included at once (including all default statisticstables) using SCIPincludeDefaultPlugins()
9652 *
9653 */
9654
9655/**@defgroup PublicToleranceMethods Computations With Tolerances
9656 * @ingroup NumericalMethods
9657 * @brief methods used by the majority of operations involving floating-point computations in \SCIP
9658 *
9659 * - query the numerical tolerances of \SCIP, as well as special values such as infinity.
9660 * - change tolerances inside relaxations
9661 * - epsilon-comparison methods for floating point numbers
9662 */
9663
9664/** @defgroup CFILES Implementation files (.c files)
9665 * @brief implementation files (.c files) of the SCIP core and the default plugins
9666 *
9667 * The core provides the functionality for creating problems, variables, and general constraints.
9668 * The default plugins of SCIP provide a mix of public API function and private, static function and callback declarations.
9669 */
9670
9671/** @defgroup DEFPLUGINS SCIP Default Plugins
9672 * @ingroup CFILES
9673 * @brief implementation files (.c files) of the SCIP default plugins
9674 *
9675 * The SCIP default plugins provide a mix of public API function and private, static function and callback declarations.
9676 */
9677
9678/** @defgroup OTHER_CFILES Other implementation files of SCIP
9679 * @ingroup CFILES
9680 * @brief other implementation files of SCIP
9681 *
9682 * Relevant core and other functionality of SCIP.
9683 */